repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

fix(ultra): share workflow reports with agents

a2fd6a70c6bc4e67904af872deb2e7ee3c1033ca

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (11)

extensions/ultra/README.md

Modified
89 89 Agent-facing structured payloads remain JSON.
91 91 For both tool and command results, the full aggregate is always stored once and every bounded model-facing envelope includes `fullOutputPath`.
92 -The envelope contains the selected final value when it fits, phase counts, bounded failure diagnostics, and usage, not duplicated `phaseResults`.
93 -When `report` is configured, it is persisted in the full aggregate and rendered only on human-facing surfaces; it is omitted from the bounded model-facing envelope.
92 +The envelope contains the selected `return` and configured `report` values when they fit, phase counts, bounded failure diagnostics, and usage, not duplicated `phaseResults`.
93 +When `report` is configured, it is persisted in the full aggregate, included in the bounded model-facing envelope, and rendered on human-facing surfaces.
94 94 `executionStatus` is `finished`, `incomplete` for dropped steps, or `aborted`; `finished` describes execution only, not artifact quality or semantic success.
95 95 Oversized values use a retrieval notice within the 50KB or 2000 lines limit; read the saved aggregate selectively.
96 96 Complete contents, including intermediate results and failure inputs/transcript tails, remain in UI details.

extensions/ultra/__tests__/harness.test.ts

Modified
453 453 const body = JSON.parse(message.content);
455 455 expect(body.result).toEqual(result.result);
456 - expect(body.report).toBeUndefined();
456 + expect(body.report).toEqual(result.report);
457 457 expect(body.executionStatus).toBe("finished");
458 458 expect(body.phaseResults).toBeUndefined();
459 459 expect(message.content).not.toContain("INTERMEDIATE");

extensions/ultra/__tests__/spec.test.ts

Modified
83 83 describe("parseWorkflow", () => {
84 - it("accepts an independent human report selector", () => {
84 + it("accepts an independent report selector", () => {
85 85 const spec = { ...validSpec(), report: "{verify.results}" };
86 86 expect(parseWorkflow(spec).report).toBe("{verify.results}");

extensions/ultra/__tests__/wire.test.ts

Modified
108 108 const output = await formatWorkflowToolResult(result);
109 109 const body = JSON.parse(output.text);
110 110 expect(body.result).toEqual(result.result);
111 - expect(body.report).toBeUndefined();
111 + expect(body.report).toEqual(result.report);
112 112 expect(output.text.match(/FINAL ANSWER/g)).toHaveLength(1);
113 - expect(output.text).not.toContain("HUMAN REPORT");
113 + expect(output.text.match(/HUMAN REPORT/g)).toHaveLength(1);
114 114 expect(body.phases).toEqual(result.phases);
115 115 expect(body.tokenUsage).toEqual(result.tokenUsage);
116 116 expect(body.steered).toBe(false);
213 213 .map(stripVTControlCharacters);
216 - it("renders only the configured report in collapsed and expanded views", () => {
216 + it("renders text reports as native Markdown documents", () => {
217 + const report = "# HUMAN REPORT\n\n- **Finding:** native rendering";
218 + expect(
219 + formatUltraResultMarkdown({
220 + workflow: "custom",
221 + phases: [{ id: "work", ran: 1, ok: 1, dropped: 0 }],
222 + phaseResults: {},
223 + phaseFailures: {},
224 + result: [{ secret: "AGENT ONLY" }],
225 + report,
226 + steered: false,
227 + tokenUsage: {
228 + input: 10,
229 + output: 20,
230 + total: 30,
231 + cacheRead: 0,
232 + cacheWrite: 0,
233 + cost: 0.4,
234 + },
235 + }),
236 + ).toBe(report);
237 + });
239 + it("renders only the configured structured report in collapsed and expanded views", () => {
217 240 const markdown = formatUltraResultMarkdown({
218 241 workflow: "custom",
219 242 phases: [{ id: "work", ran: 1, ok: 1, dropped: 0 }],

extensions/ultra/prompts/references/examples/dynamic-extensions.md

Modified
95 95 "kind": "single",
96 96 "step": {
97 97 "summary": "Report capability status",
98 - "prompt": "Prepare a concise human report from builder results {build.results} and consumer results {use.results}. Mark blocked or incomplete explicitly; do not infer successful use from an empty result.",
98 + "prompt": "Prepare a concise report for the human and agent from builder results {build.results} and consumer results {use.results}. Mark blocked or incomplete explicitly; do not infer successful use from an empty result.",
99 99 "model": "large",
100 100 "schema": "HumanReport"

extensions/ultra/prompts/references/examples/safety-and-results.md

Modified
48 -### independent human report
48 +### independent report
50 50 ```json
60 60 "id": "human",
61 61 "kind": "single",
62 - "step": { "summary": "Prepare the report", "prompt": "Prepare a concise human report from {work.results}." }
62 + "step": { "summary": "Prepare the report", "prompt": "Prepare a concise report for the human and agent from {work.results}." }
65 65 "return": "{work.results}",

extensions/ultra/prompts/references/spec-format.md

Modified
22 22 - `return` selects the final value; without it, the last phase's results are used.
23 23 - `report` optionally selects the human-facing value; without it, human rendering uses the existing `return`-based formatting.
24 24 - tool and command results store the full aggregate once; every bounded model-facing envelope includes `fullOutputPath`.
25 -- the selected `return` value appears once in the bounded model-facing envelope when it fits, with phase counts, bounded failure diagnostics, and usage; `phaseResults` is not duplicated.
26 -- the selected `report` value is persisted in the full aggregate and rendered only on human-facing surfaces; it is omitted from the bounded model-facing envelope.
25 +- the selected `return` value and configured `report` value appear in the bounded model-facing envelope when they fit, with phase counts, bounded failure diagnostics, and usage; `phaseResults` is not duplicated.
26 +- the selected `report` value is also rendered on human-facing surfaces through Pi's native Markdown/structured renderer, so the agent and maintainer receive the same selected report data.
27 27 - `executionStatus` is `finished`, `incomplete` for dropped steps, or `aborted`.
28 28 - `finished` describes execution only, not artifact quality or semantic success.
29 29 - oversized values use a retrieval notice within the 50KB or 2000 lines limit.

extensions/ultra/prompts/ultra-authoring/SKILL.md

Modified
28 28 - phase IDs are unique identifiers; `args` is reserved.
29 29 - `when` skips a phase when its selector resolves to a false, null, undefined, empty string, or empty array value.
30 30 - `return` selects the final value; without it, the last phase's results are returned.
31 -- `report` optionally selects the human-facing value independently from `return`.
31 +- `report` optionally selects a human-facing value independently from `return`; it is also returned to the agent.
32 32 - use `args` for declared run inputs and `schemas` for output shapes reused by later phases.
34 34 ## give children context
79 79 ## inspect results
81 81 `return` selects the value shown to the orchestrator.
82 -`report` selects the value shown to the human; unselected data remains agent-facing.
82 +`report` selects the value rendered to the human and included alongside `return` in the tool result.
83 +Unselected data remains available through the full aggregate path.
83 84 the result includes failures, usage, and `fullOutputPath` for complete evidence.
84 85 read that path selectively when the bounded result is insufficient.
85 86 a dropped step appears in its phase's failures and can feed one later recovery phase;

extensions/ultra/result.ts

Modified
241 241 return `${plural(finalCount, "final result")}.${incomplete}`;
244 +function reportMarkdown(value: unknown): string {
245 + if (typeof value === "string") return value;
246 + if (
247 + Array.isArray(value) &&
248 + value.length > 0 &&
249 + value.every((item) => typeof item === "string")
251 + return value.join("\n\n");
252 + return formatValueMarkdown(value);
244 255 function recommendationLines(
245 256 result: WorkflowResult,
246 257 finalCount: number,
268 279 result: WorkflowResult,
269 280 expanded = false,
270 281 ): string {
271 - if (Object.hasOwn(result, "report"))
272 - return formatValueMarkdown(result.report);
282 + if (Object.hasOwn(result, "report")) return reportMarkdown(result.report);
273 283 const report = reviewReport(result);
274 284 const research = researchReport(result);
275 285 const selected = resultItems(result.result);

extensions/ultra/spec.ts

Modified
235 235 report: Type.Optional(
236 236 Type.String({
237 - description: `${SELECTOR_GUIDANCE} Selects the human-facing report; the selected value may have any type.`,
237 + description: `${SELECTOR_GUIDANCE} Selects the report rendered for humans and included in the model-facing result; the selected value may have any type.`,

extensions/ultra/wire.ts

Modified
45 45 : dropped > 0
46 46 ? "incomplete"
47 47 : "finished";
48 - const {
49 - phaseResults: _phaseResults,
50 - phaseFailures,
51 - report: _report,
52 - ...output
53 - } = result;
48 + const { phaseResults: _phaseResults, phaseFailures, ...output } = result;
54 49 const text = JSON.stringify(
56 51 ...output,