repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

update Ultra workflows and tooling

b70279699b644d25ef480bdd21ed266f33addcab

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (20)

CHANGELOG.md

Modified
2 2 # Changelog
4 4 ## Unreleased
6 -- Update extensions for Pi 0.86, including context APIs, model handling, and compatibility fixes
7 -- Add the missing `@earendil-works/pi-ai` peer dependency to masks
8 -- Improve PFUI compatibility with Pi 0.86 prompt-option validation and preserve tool descriptions and guidelines in its fallback prompt
9 -- Make PFUI provide structured custom identity, tools, general-guideline, and tool-guideline sections while omitting empty sections
10 -- Move The System, Ultra, Mockup, and Tune prompt contributions into named sections and prohibit flat prompt overrides
11 -- Register Mockup and Ultra authoring guidance as skills instead of tool rules
12 -- Correct tool metadata with self-identifying guidelines, UV and IntelliJ routing guidance, Tune VCS semantics, and richer provider descriptions
13 -- Update Prompt Autopsy to group Pi 0.86 prompt sections, handle nested sections, and write captured prompts to private temporary files
14 -- Improve Decay’s compaction display with stationary retained context, left-growing summaries, chunk-position progress, live memory selection, and recency markers
15 -- Make Decay retry classification and summarization with the current session model when an explicit model is unavailable or fails, including quota and rate-limit errors
16 -- Remove working-label updates from the Web fetch and search tools
17 -- Remove the working-label update from git-safe cloning
18 -- Add custom `󰰀` provider icon for Hetzner in model-info extension; enforce that Nerd Fonts skill updates occur strictly via official `--refresh`, reverting manual DB edits and removing the uncompressed `.txt` database artifact to maintain the compressed-only design
20 -- Declutter the status bar: show context usage as the bar alone, drop unreadable cache-read and cache-write totals in favour of the cache hit rate, scale token counts and costs through `k` and `M`, drop the provider name from the active quota segment that the model icon already identifies, and replace glyph labels with spelled-out status text outside TUI mode
22 -- Recover Decay from partial classification with up to two gap-fill rounds over only the missing chunks, tolerate exact duplicate chunk records, and salvage a deterministic summary from ranked atoms when the summarizer fails instead of discarding the whole run to default compaction
23 -- Keep Klaus models in sync with Pi's Anthropic catalog: inherit the human's model overrides, never inherit transport-owned fields, clamp an inherited context window or output maximum to the builtin catalog value the Agent SDK path can actually deliver, re-project the catalog at each turn boundary, and re-register the provider only when the projection changed
24 -- Expose Klaus tools to Claude under their Pi names instead of the `mcp__klaus__` prefix, while still accepting prefixed names from resumed sessions and older runtimes
25 -- Stop Klaus from replacing large Pi tool results with a `<persisted-output>` pointer into a deleted temp directory, and isolate the Klaus child from ambient Claude Code context, deferred tool loading, tool backgrounding, and non-streaming retries
26 -- Capture Klaus tool identities from Claude's `PreToolUse` hook so tool calls keep working when a permission rule answers them without asking Klaus, and truncate tool results at Claude's result-size ceiling instead of losing them to a persisted file
27 -- Name the Klaus tool behind an Anthropic input-schema rejection instead of leaving the API's positional `tools.N` reference unexplained
28 -- Reuse the running Claude child for the next turn in a Klaus session instead of spawning one per turn, swap its tool list in place when Pi changes tools, and drop it after a two-minute idle lease or any lineage change, saving about 1.7 seconds per follow-up turn
29 -- Run every Klaus query in streaming input mode, interrupt the child instead of killing it so an abandoned turn no longer spends an extra request, flush mirrored transcripts eagerly, and surface child API retries, self-decided permission denials, warnings, and worker shutdowns to the human
30 -- Add Bak for asynchronous S3-compatible session backup and conflict-safe restore, with host initialization, manual backup, refresh, and status commands, durable retries, safe partial-failure handling, and no filesystem or network work during Pi startup
31 -- Make Ultra workflow `report` values available to agents as well as human-facing output, while preserving full-output references for oversized reports
32 -- Refine Ultra model-tier selection around residual judgement: default to `small`, use `tiny` only for deterministic work, decompose when context or risk benefits exceed handoff cost, and block rather than compensate for missing facts or authority
33 -- Add `ctrl+enter` to park editor text as a note, clear the editor on success, and show a confirmation notification; update `addFromEditor` command to clear the editor and notify on success; `ctrl+alt+enter` opens a notes picker and sends the selected note
34 -- Add Witness definition discovery, validation, trusted project overrides, `/witness list`, `/witness show`, `/witness validate`, and isolated manual text observers through `/witness run <id>`; cancel stale runs and preserve child usage
35 -- Load no extensions into Angel children by default, add `angel.subagentExtensions` for `"all"`, `"none"`, or a static sibling-extension whitelist, and keep unavailable parent-local or on-demand tools from blocking consultation
36 -- Make Angel's advisor read-only: remove `bash`, `edit`, and `write` and its temporary experiment directory, leaving only `read`, `ls`, `find`, and `grep` built-ins plus `parent_session`
37 -- Keep footer segment order stable when multiple segments share the same priority
38 -- Speed up shared footer rendering by avoiding redundant truncation of lines that already fit
39 -- Load the shared footer before producers and synchronously acknowledge accepted segments so initial TUI telemetry bypasses fallback statuses without sacrificing standalone producers; stop footer mount polling, isolate nested runtimes, and ignore malformed producer segments instead of blanking the entire footer
40 -- Add cumulative session token and cache totals, latest cache-hit rate, provider identity, and subscription marking to the shared footer while preserving its compact visual style
41 -- Let IQ counter judging fall back to the next pool member when the assigned counter rejects a request (rate limits), rotating deterministically, since a lost agreement pair never returns once the session is scored; report exhausted pools separately as "counter pairs lost" instead of counting already-scored sessions as failed, and keep primary-judge failures failing so unscored sessions retry on the next scan
42 -- Replace `/iq export` and its `iq.exportDir`/`iq.exportName` settings with `iq.stateDir`: one shared, synced directory for records, telemetry, and checks; the first use with an empty shared directory copies local state in once, records carry a `host` field for provenance, the leaderboard merges all hosts, and the scan lock moves to the OS temp directory so synced folders never carry lock files; unreadable IQ settings fall back to the local state directory with a warning instead of blocking commands
43 -- Add `telemetry` and `checks` tabs to the IQ dashboard, bringing it to five tabs: telemetry shows measured per-model behavior (turns, tool calls, edit share, output volume, cache share, latency, speed) and checks shows each model's latest check result with task states, acceptance, estimate, and check-versus-history deltas
44 -- Add PFUI benchmark and CPU-profile tasks, with benchstat managed by Mise
45 -- Add `/iq check <provider/model>` for check-suite scoring: three frozen fixture tasks (fix-and-document, refactor-with-correction, feature-with-trap) with content hashes are materialized as git workspaces and solved by child Pi sessions; step and final-state judging reuse the IQ judge machinery with repair and retries, acceptance results are executed for real, and runs are stored separately under `checks/`; until a reference check exists on a rated model, results show raw 1-5 ratings only, then add leave-one-out calibration against real scores
46 -- Let IQ check acceptance use tamper-proof Node verifier scripts (`checks/*.mjs`) stored in the fixture directory outside the workspace, running with the candidate workspace as cwd, so candidates cannot tamper with their own grading; the fixture hash covers the whole fixture directory including verifier scripts, and fixtures referencing missing scripts are rejected at load
47 -- Fix IQ check failure handling: a failed final evaluation now persists an incomplete record with all judged evidence, unreadable sessions are reported as unreadable instead of blaming the candidate for no work, cancellation before delivery stops without recording undelivered instructions as work, and nonzero-exit details keep the head of stderr so error headers are not truncated
48 -- Fix IQ check step resume: pass the session file path to `--session` instead of the filename stem, since Pi matches by id or path and session files are named `<timestamp>_<uuid>.jsonl`
49 -- Add an IQ dashboard `c` shortcut and tab completion for `check` model refs from the live registry
50 -- Exclude IQ check fixtures from Biome via folder ignores that work from both repo and extension working directories
51 -- Add PFUI with a fallback system identity, installed Pi context variables, and an on-demand skill for consulting Pi documentation; report each distinct warning once and retain valid skills with warning-only diagnostics
52 -- Serve `/system board` pages from a live snapshot that re-renders whenever `.system` changes, so refreshes show persisted state and open boards follow disk edits; board changes patch the page in place while document changes reload it and restore open disclosures
53 -- Toggle plan `status` between `draft` and `approved` and spec board state directly from the rendered metadata box
54 -- Fix `/system board` controls failing when clicked during page load by making the board and ledger scripts self-contained instead of depending on load order
55 -- Let `iq.counterJudgeModel` take a list of judges that rotate per session, assigned deterministically from session content, so cost stays flat while calibration broadens; the confirm dialog lists the rotating counters and the IQ method view reports agreement and per-model bias for each counter separately
56 -- Add `iq.counterSampleRate` (0-1) to counter-judge that share of every normal IQ scan, sampled deterministically from session content so the same sessions are picked on every host and rerun; the confirm dialog shows the counter judge, sampled session count, and combined cost estimate, progress marks counter passes, and the summary reports counter-judged sessions
57 -- Show per-model judge bias in the IQ method view, making a judge's favouritism toward its own model family visible
58 -- Add the `ask` extension with an `ask_user_question` tool for 1-4 structured multiple-choice questions: option lists with a recommended option, multi-select support, optional stable answer IDs, free-form `Other…` input, TUI overlays with Tab notes and Esc cancel-all, Pi dialogs in RPC mode, and immediate `unavailable` results in print/JSON modes
59 -- Wrap Ask questions, options, answers, and notes to the available width; fullscreen TUI mode also supports mouse selection, toggling, wheel navigation, and text cursor positioning
60 -- Fix concurrent web tool calls crashing on first use by sharing one lazy import promise per implementation module, so parallel calls never receive a partially loaded module
61 -- Memoize per-call dynamic implementation imports in Angel consultations, git-safe clones, and Strata command/GitHub review paths so concurrent calls share one module evaluation instead of racing Pi's module-cache-free jiti loader
62 -- Extend the shared lazy-import memo to The System (centralized loaders for system, renderer, board server, startup notice, bundle slot, and command modules), IQ, and usage command paths so all concurrent entry points share one module evaluation
63 -- Let `/system exec` apply verified board states directly through `system_board_update` with `source: agent` and an evidence note, keeping `/system assess` proposal-only; invalid batches are rejected whole and humans can override any entry
64 -- Show board entry notes in `/system board` and inject a board state block with counts and unfinished items into every `/system` lifecycle prompt
65 -- Add a `/klaus-setup-token` command that mints a long-lived Claude OAuth token natively inside Pi through the Claude Code PKCE sign-in flow, without spawning the Claude binary: it opens the sign-in page in the browser, rejects state mismatches, accepts `code#state`, a redirect URL, a query string, or a bare code, copies the token to the clipboard with platform fallbacks, and shows the token when no clipboard tool exists; RPC mode uses a plain input dialog without opening a browser, and there is no `--klaus-setup-token` CLI flag
66 -- Run the whole `/klaus-setup-token` TUI flow in one animated Bureau of Tokens counter: a block-art snail clerk and clerical form type themselves in above a sign-in link (`c` copies it) and code field that are live from the first frame, a status row spins through sign-in and exchange, and the outcome stamps `APPROVED` with the token's validity date or `DENIED` with the failure reason in place; `r` retries a denial with a fresh sign-in, the first key skips a running stamp, the next closes, Esc cancels at any point, and the counter sizes itself to the terminal in full, compact, and tiny width tiers with wrapping instead of truncation
67 -- Repair sloppy IQ judge output instead of discarding whole chunks: keep only cited in-chunk evidence, clamp ratings, default missing fields, count repairs alongside retries, and report why sessions failed to score
68 -- Treat System plans as the required outcome rather than an implementation order: re-sequence layered plans into vertical slices, implement them fully, and stop treating slice boundaries as human approval points
69 -- Make visual models the System Markdown default, require at least one diagram, mockup, or state model in specs, require structure or sequence diagrams and visual dependencies in plans, and use sequence diagrams for cross-component issue reproduction
70 -- Decompose System plans by observable behavior instead of architectural layer, naming touched modules without a layer-by-layer build order
71 -- Show Anthropic subscription quota while a klaus model is active by mapping klaus to Pi's Anthropic OAuth token
72 -- Display klaus usage as `anthropic (klaus)` in the usage dashboard
73 -- Honor Pi `maxTokens` in Klaus through the child runtime's `CLAUDE_CODE_MAX_OUTPUT_TOKENS` environment variable: validate it as a positive safe integer, set it only when Pi supplies it, never inherit it from the host environment, and treat a cap change across a tool-boundary continuation as an incompatibility that replays canonically
74 -- Keep Klaus adaptive-thinking models (Fable, Opus, Sonnet) always adaptive with an effort level, never pinning them into fixed-budget thinking from a Pi thinking budget; apply budgets only to budget-based models such as Haiku
75 -- Align Klaus Haiku fallback thinking budgets with Pi's defaults (1024/2024/8192/16384) so unset Pi budgets behave like native Pi usage
76 -- Redesign Angel with persistent investigative child sessions, inherited tools, bounded on-demand access to pinned parent context, automatic failure analysis, cancellable live progress, and stale-session delivery protection
77 -- Shorten model labels consistently in model status displays, including family-specific speed and release qualifiers
78 -- Remove the cmprss, Leaks, and Verboten extensions and the dedicated Leaks fuzz task
79 -- Remove the always-on Terse extension; configure personal response style through Pi's `APPEND_SYSTEM.md` instead
80 -- Redesign Decay progress as a borderless five-row widget with aligned CTX, FACTS, and NEW maps, theme-safe semantic blocks, live durable/context classification, selected-memory highlighting, and summary growth on a shared retained-token scale
81 -- Fix Decay retained-token estimates to measure the actual preserved suffix instead of the configured target, and show unknown counts when unavailable
82 -- Show Ultra workflow phases and live prompt tails while arguments stream, hand off to the execution board when agents start, and retain full received prompts on Ctrl+O
83 -- Fix Ultra failed tool calls to show an error summary instead of an empty progress board, with full diagnostics on Ctrl+O
84 -- Add Parallel and Google WML search fallbacks; use Codex, MiniMax, Parallel, Google WML, DuckDuckGo, then Z.AI, preserving full excerpts and stopping fallback on cancellation
85 -- Add `mise run //extensions/web:evaluate-search` to compare configured search providers live on five fixed queries, recording target rank, latency, and full results
86 -- Reduce mockup tool context with shorter metadata while retaining on-demand HTML guidance and option limits; give interactive scripts an explicit reference to their fragment root and preserve fragment-local data scripts
87 -- Show terminal-pixel-matched animated mockup option previews directly in Pi with shared content-aware heights up to 720 pixels, visible crop warnings, transparent terminal-composited backgrounds, replay up to ten times after a one-second pause, and a persistent final frame
88 -- Show mockup HTML generation size, queue and browser-opening states, feedback readiness, and expanded server and opener timings in Pi
89 -- Replace Web's separate tools with one compact `web` tool using `action: fetch | map | search`, validating action-specific arguments before I/O; remove legacy aliases and MiniMax image analysis, and require tool allowlists to use `web`
90 -- Reduce Ultra's context footprint with a compact workflow tool schema while retaining strict runtime validation
91 -- Add `mise run //:context-extensions` to discover extensions automatically and measure removal savings one at a time, including uncertain registrations; report provider input and heuristic deltas, and withhold savings when repeated controls differ
92 -- Add `mise run //:context-startup-skill-descriptions` to rank visible agent-directory skills by description size and show the five largest descriptions for review
93 -- Add `mise run //:context-startup-sources` to estimate `APPEND_SYSTEM.md`, agent-directory and extension/package skill entries, and shared catalog instructions separately at startup, excluding direct project-local skills, skill bodies, and prompt templates without sending a measurement prompt
94 -- Add `mise run //:context-startup` to compare stock, configured, and agent-text-free headless startup context with three live requests, retaining extensions, settings, and project context while reporting cache-inclusive provider input tokens and labeled Pi heuristic estimates
95 -- Fix Strata cancellation and session shutdown so pending requests and subprocesses settle before cleanup finishes
96 -- Keep Ultra's intermediate results out of orchestrator context, return final output once, and replace output above 50KB or 2000 lines with a full-output file reference while preserving complete results in UI details
97 -- Let Ultra configure named model tiers with default thinking levels and orchestrator selection guidance, merge global and project overrides, use the session model by default across providers, and start fresh checkpoints when effective model or thinking routes change
98 -- Remove Strata Ask's fixed tool-call, round, batch, and cumulative-output caps while retaining per-tool resource limits and cancellation
99 -- Add optional Strata GitHub PR reviews with confirmed checkout switching, attributed read-only discussions, and PR-aware feedback; keep saved plans and drafts separate across PRs and forge hosts
100 -- Add Strata Vim-style line, hunk, layer, and pane navigation, literal diff search, keyboard review actions, whole-layer review toggles, and contextual shortcut guides
101 -- Keep Strata draft saves from overwriting newer edits, preserve focus when toggling review status, confirm submission and close, and keep unavailable workspaces read-only
102 -- Add Strata for browser-based Git review with model-organized layers, layer questions, resumable drafts, stale-snapshot-checks, and feedback sent back to Pi
103 -- Add independently collapsible Strata side panels and keyboard-accessible Details, Ask, and Feedback tabs; keep selected tabs readable on hover
104 -- Keep Strata's layer and All changes conversations and drafts separate, preserve hunk focus, and restore question input focus after answers when appropriate
105 -- Let Strata Ask inspect installed packages and external docs with bounded read, literal grep, and ls tools, enforce protected-path checks, and label live evidence separately from the review snapshot
106 -- Keep Strata on the model selected when the workspace opens and fix current-file tracking near the end of long diffs
107 -- Let larger Strata reviews and layer questions fit within the existing prompt limit without dropping diff text or line anchors
108 -- Track secret encryption rules in `.gitattributes`, migrate obsolete local rules, and block commits when `.secrets` or generated attributes are not fully staged
109 -- Add on-demand IntelliJ MCP connections with project-scoped tools, saved loopback endpoints, connection health status, readable tool results, connection management commands, and faster large tool-catalog loading
110 -- Improve IntelliJ footer status readability and report saved-settings read failures in `/intellij status`
111 -- Fix IQ scoring and storage across platforms, including stable session-settling checks
112 -- Make Nu diagnostics tests compatible with supported version differences
113 -- Fix Web so its extension tools activate when a session starts
114 -- Prevent extension diagnostics from corrupting Pi's terminal UI and machine-readable output
115 -- Add IQ for confirmed longitudinal model scoring with cited evidence, safe concurrent scans, and a responsive `/iq` leaderboard
116 -- Add Masks for quickly switching between named model and thinking combinations with `/masks`, `Alt+M`, configurable direct shortcuts, and fuzzy matching
117 -- Let prompt templates select a Mask through their tool loop and automatic recovery with an optional `mask` frontmatter field; restore before ordinary follow-ups and block prompts when switching or restoration fails
118 -- Queue masked follow-ups after Pi's native queue with attached images, a footer count, and `/masks-cancel`; discard deferred prompts on abort, error, tree navigation, or shutdown, and reject masked steering and competing input during preparation
119 -- Change Tune's fullscreen shortcut to `Ctrl+Alt+T`
120 -- Generate git-safe's fixed-executable wrapper on first Bash use and reuse it across reloads
121 -- Defer unused extension implementations, PATH checks, settings reads, prompt loading, and RTK probes beyond startup and reload
122 -- Lazy-load Ultra execution, workflow discovery, validation, and workflow tool registration until first use unless `ultra.auto_enable` is enabled
123 -- Let `ultra.auto_enable` activate Ultra's workflow tool when each session starts
124 -- Retain Ultra sub-agent sessions as named parent-linked children, resume matching interrupted steps, and provide an explicit stateless opt-out
125 -- Let Ultra load one static extension-name allowlist into every sub-agent while preserving `"all"` as the default
126 -- Let loaded extensions activate their own Ultra sub-agent tools without extension-specific workflow tool names
127 -- Let Ultra create, check out, validate, publish, reuse, and load dynamic extensions from a canonical catalog under Pi's agent directory; keep one accepted version per name, isolate editable drafts in the platform cache, reject stale updates, retry deliberate rebases once, and publish atomically
128 -- Treat manually edited canonical dynamic extensions as unvalidated until they are validated in place, and require revalidation when the validator contract changes
129 -- Validate dynamic extension drafts with real Pi loading, `node:test` capability coverage, structural checks, deterministic network-free tests, and hot-path benchmarks; report load and benchmark overruns as advisory warnings, report actionable diagnostics for every independent correctness failure, and retain unpublished drafts when validation is cancelled
130 -- Give dynamic-extension builders every available tool except recursive Ultra workflow execution while keeping consumer agents unaware of the build system
131 -- Load one or more dynamic extensions after configured extensions, resolve stable names to recorded source hashes for each run, preserve declared order, require explicit qualified override metadata for collisions, and block consumer phases when extension building fails
132 -- Let Ultra repair dynamic extensions after consumer failures and rerun the original workflow, reusing unaffected checkpoints without a fixed repair-cycle limit
133 -- Give dynamic extensions bounded, redacted NDJSON debug logs in the platform cache that Ultra can inspect on demand and retain for seven days
134 -- Let Ultra search only canonical dynamic extensions with bounded deterministic matching over manifest metadata and selected README sections
135 -- Make Ultra progress rows task-first and put metadata below summaries, live activity, and failure details across tool rows, command overlays, and result reports
136 -- Count every Ultra sub-agent response and failed result-submission attempt in token and cost totals
137 -- Remove synchronous Pulse Git processes, use the current Node process version, and fold vcs-status stash detection into its existing Git status process
138 -- Remove the Overkill and Q extensions
139 -- Remove the Goal, Diff Review, and Devil extensions
140 -- Remove the Cwd, Split Fork, LLM Iterate, and Goldfish extensions
141 -- Remove the unneeded `builtin-tools` extension and `/builtin-tools` command
142 -- Update npm dependency lockfile to latest resolved package versions
143 -- Replace dprint and markdownlint-cli2 with rumdl for Markdown, Taplo for TOML, and yq frontmatter validation; add structural Markdown checks for links, footnotes, fences, TOCs, anchors, encoding, and comments
144 -- Pin all Pi packages to 0.84.3 and modernize extensions for API changes around agent sessions, provider headers, auth, and RPC messages
145 -- Store Klaus sessions separately under Pi's configured session directory, never in normal Claude session storage; non-persisted Pi sessions and sessionless model calls remain isolated in memory
146 -- Make Klaus SDK upgrades exact-version cutovers with once-only asynchronous startup migrations; Pi remains responsive while Klaus waits, and failed migrations preserve existing data
147 -- Preserve exact Pi branch context in Klaus through turn checkpoints and Claude SDK session fork and resume APIs, without runtime fallbacks or private transcript manipulation
148 -- Follow Pi's canonical context replacement during compaction by starting a new Claude lineage from Pi's summary; disable Claude SDK auto-compaction
149 -- Make Klaus use Pi's system prompt and tools while disabling optional Claude tools, settings, memory, compaction, and external MCP integrations
150 -- Keep Pi authoritative for Klaus tool execution, including permissions, UI, events, and transcripts; forward only model-facing text, images, and error status from tool results, and support tools added or removed by extensions during active turns
151 -- Preserve Pi tool schema validation in Klaus; reject required JSON-schema constrained sampling and fall back for preferred or unsupported grammar constraints
152 -- Preserve Pi provider hooks in Klaus through transformable logical requests and virtual `x-klaus-*` response metadata that never reaches Anthropic
153 -- Treat Klaus request timeouts as sliding Claude-activity timeouts, paused while Pi tools run
154 -- Make Klaus discover available Claude models with Pi's OAuth and never auto-probe undiscovered models that could consume usage credits
155 -- Advertise one current Klaus model per Claude family and map each explicit Pi model ID to Fable, Opus, Sonnet, or Haiku without silently upgrading it
156 -- Target Fable 5.1 with verified routing and API-equivalent pricing; let it proceed when absent from authenticated discovery, with a usage-credit warning shown once per Pi session
157 -- Support Pi thinking in Klaus, mapping `minimal` to `low`, preserving supported levels, silently clamping unsupported levels down, and disabling it for `off`
158 -- Prevent Klaus from replaying full context after generic resume failures; retry only when the SDK explicitly rejects the resume point
159 -- Fix Klaus cached resumes with branch-bounded history validation, safe corrupt-cache recovery, reapplied payload transformations on cold replay, and reliable checkpoint publication
160 -- Fix Klaus lifecycle cleanup so concurrent completion and session teardown await one Agent SDK shutdown
161 -- Fix Klaus prompt translation so subscription-triggering phrases no longer cause third-party-app usage errors while the available skills section, `.pi`, paths, and compound names such as `pi-ext` remain unchanged; keep Pi identifiable to the model and warn once per session only when recognizable Pi prompts change upstream and prevent expected translations
162 -- Add automatic Klaus setup on Android through an isolated `grun` launcher
163 -- Support concurrent Klaus calls from extensions that create Pi agent sessions or make direct model calls
164 -- Make Angel, Pulse, session renaming, TLDR, and Ultra action summaries work with custom extension providers such as Klaus
165 -- Make session renaming use medium reasoning when the active model supports it
166 -- Reap idle secondary Klaus queries after 15 minutes, refreshing the timeout on provider or tool activity and replaying canonical Pi context if a later result arrives
167 -- Report Klaus API-equivalent spend using Pi's current Anthropic rates and recognized fallback model rates while keeping token usage and warning that actual subscription or Fable credit usage may differ
168 -- Document that Klaus uses Anthropic's proprietary Claude Agent SDK under its commercial terms without vendoring the SDK
169 -- Add Decay to classify and compact session history into ranked durable memory, with a passive progress widget that keeps Pi's editor available for queued steering and Escape cancellation, plus automatic fallback to Pi's default compaction on failure
170 -- Let Decay use a separately configured model for summarization
171 -- Fix Decay compaction reliability by assigning source provenance locally instead of relying on model output
172 -- Fix Decay summarization failures on large compactions by using the provider's standard streaming path
173 -- Fix repeated Decay compactions so paraphrased memories reuse the same identity without being counted as new occurrences
174 -- Add Continuity to automatically resume the current task after context compaction while yielding to queued messages and active Goal or Tune runs
175 -- Fix Continuity so it resumes user intent only when actionable work remains and stops instead of rerunning completed checks, retrying known blockers, or inventing follow-up work
176 -- Fix The System README bundle path docs to show plural directories
177 -- Make `/system init` deterministic with confirmation; it creates schema 0 config, board state, plural bundle directories, and core files directly
178 -- Add an optional project title to The System config; `/system init` writes it from the project directory name and rendered books make it
179 -- Require one-shot human approval before mutating existing System core documents or spec and phase files, and reject oversized core documents before approval
180 -- Seed `/system init` core files with concise SYSTEM, MISSION, and RULES role guidance while preserving existing core content on rerun
181 -- Fix `/system init` so rerunning in an initialized project reuses the existing prefix instead of asking again
182 -- Fix exact `/system` subcommands such as `doctor` and `book` so autocomplete does not consume Enter
183 -- Add `/system edit <path|id|slug>` to open System documents in VISUAL, EDITOR, or a platform editor
184 -- Fix `/system edit` on Windows so quoted editor paths and file paths preserve backslashes and launch correctly
185 -- Fix `/system edit` fallback selection so `termux-open` is used only on Termux/Android and other platforms keep their native editor fallback
186 -- Fix The System document prompt and governance to require plural bundle directories and block unknown `.system` paths such as `.system/spec`
187 -- Fix `/system view` and `/system book` HTML output so rendered pages include document bodies and open in the browser
188 -- Fix `/system view` and `/system book` on Windows to use the native URL handler without flashing a command window
189 -- Fix rich System doc rendering so heading anchors are document-scoped and iframe embeds use browser-loadable file URLs
190 -- Fix `/system book` Mermaid diagrams so they load from local file output in browsers
191 -- Fix `/system book` layout so the On this page sidebar and referenced-by panels no longer overlap content, referenced-by panels are collapsible at the end of pages, the dossier uses full width, header elements align, empty diagnostics are hidden, law navigation avoids duplicate labels, project metadata is used for titles and favicons, and graph labels no longer overflow boxes
192 -- Fix `/system book` mobile layout so navigation drawers start collapsed, headings and topbar scale responsively, and the reference graph uses a constrained initial viewport
193 -- Fix `/system book` at limited desktop widths so the right utilities rail is hidden instead of covering graph controls
194 -- Fix `/system book` document links so they navigate within the book instead of jumping to separate file pages
195 -- Fix `/system book` layout so clicking document links no longer causes horizontal scroll or layout corruption
196 -- Improve `/system book` with a responsive dossier reader, fixed header and left navigation with utilities merged in instead of a separate right box, collapsible navigation, attached search results with highlights, diagnostic links, reference graph, Nugu colors, and print CSS
197 -- Improve The System book reference graph with all linked docs, pan/zoom controls, touch gestures, clickable node links, text fallback, and Dagre primary-edge layered layout to reduce crossing and clutter
198 -- Fix The System book reference graph so pan/zoom handling no longer breaks node links
199 -- Remove redundant helper text from The System book reference graph header
200 -- Update The System lifecycle design around one `/system` command with subcommands for init, doctor, view, book, research, spec, spec-verify, phase, plan, issue, and exec
201 -- Update The System lifecycle stages: the small path is `spec -> exec`; the larger path is `research -> spec -> spec-verify -> phase -> plan -> exec`; optional stages never auto-chain
202 -- Update The System lifecycle IDs to schema v3 token IDs and rename roadmap terminology to phase terminology
203 -- Update The System lifecycle design so phase and plan status is `draft` or `approved`; `approved` means human-approved, immutable, and exec-eligible, while supersession happens by creating a new plan bundle with prose references
204 -- Require interactive approval before changing a phase or plan from `draft` to `approved`
205 -- Add turn-scoped `system_bundle_slot` allocation so semantic titles produce slugs and one command can reserve multiple unique bundle IDs
206 -- Update The System lifecycle metadata: specs have `id`, `type`, `title`, and optional `research`; phases have `spec`, `status: draft|approved`, and optional `depends_on`; plans have `spec`, optional `phase`, `status: draft|approved`, and optional `depends_on`; issues have `specs` without status; `spec-verify` creates no canonical document
207 -- Add The System dependency validation and rendering for phase and plan `depends_on`, including same-spec checks, dangling-reference and cycle diagnostics, reference graph edges, and dependency-aware book ordering
208 -- Update The System rich-Markdown design to use phases instead of roadmaps in the lifecycle model
209 -- Remove The System top-level prompt templates; `/system` subcommands use internal prompt includes for document and Markdown knowledge
210 -- Add initialized-project-only GFM, TeX, and Mermaid format skills that activate only after the format is selected; `/system init` requests a reload when needed
211 -- Keep generated `/system` lifecycle turns alive in print and JSON modes
212 -- Remove unused The System renderer dependencies
213 -- Add terse document detail budgets for System docs; plans stay at module/interface/package/class level, and all System docs avoid real code snippets in favor of essential pseudocode
214 -- Fix The System runtime warning so it stays quiet until a project opts into `.system`
215 -- Improve The System startup performance in projects without `.system` by skipping governance loading
216 -- Redefine The System phases as selectable project-wide operating epochs, inject the current phase, show it in Pi status, foreground it in the book, and reset the unreleased schema to version 0
217 -- Make `/system init` update config and board schema markers mechanically, then offer agent-led bundle migration after config schema changes
218 -- Fix rejected System config edits so errors no longer mislabel them as phase changes
219 -- Add `/system board` for persistent spec, plan, and issue status tracking, plus reviewable proposals from `/system assess` and completed `/system exec` runs
220 -- Fix System board proposals so expanded details are not repeated in the result
221 -- Fix `/system assess` so board proposals remain available across clarification turns and compaction
222 -- Add a generally invocable vertical-slicing skill and require `/system exec` to use it for thin, complete, verified slices
223 -- Prevent The System E2E tests from opening a browser
224 -- Extract Mockup into a standalone extension while retaining System visual-asset integration
225 -- Keep one mockup page open across connected browser iterations, automatically continue in the browser after Iterate, retain clickable live URLs, report browser-open failures, reopen disconnected pages, support authenticated agent cancellation and abandoned-transport cleanup, prompt explicitly for continuation, and close best-effort on acceptance
226 -- Fix mockups on Windows so the browser opens in the foreground through the native URL handler
227 -- Fix mockup edge annotations so they stay contained without horizontal scrolling
228 -- Preserve mockup iteration HTML, feedback, summaries, selection metadata, and result context in the OS cache and across compaction, while keeping only essential accepted visual assets in project bundles
229 -- Let System specs use mockups and diagrams for visual, interaction, and relationship choices; preserve accepted visual assets and local dependencies in bundles, capture feedback as constraints, and preview standalone HTML, images, and videos in System views while keeping inline and companion Markdown links intact
230 -- Auto-prune closed mockup cache entries when their sessions are missing, after 30 days of inactivity, or by oldest use above 256 MiB
231 -- Use `/ultra exec <instructions>` to design or execute a workflow and `/ultra run <name> [args]` to run a saved workflow; bare `/ultra` enables the hidden `run_workflow` tool and confirms activation
232 -- Use Ultra only when independent parallel work, staged agent handoffs, or isolated specialist contexts materially improve the result
233 -- Make `/ultra exec` send a short visible instruction and the user's request without injecting authoring guides; choose between a one-off and saved workflow from reuse intent, and ask one focused question when uncertain
234 -- Add `/ultra` autocomplete for `exec` and `run`, with saved workflows completed under `run`
235 -- Remove Ultra background runs and `/ultra history`; workflows now run interactively without persisted run history
236 -- Improve Ultra progress with phase-first expandable views, transcript navigation, native Pi tool rows and `Ctrl+O` output expansion, checkpoint, token, and cost details, and final outcomes
237 -- Add optional `ultra.actionSummarizerModel` summaries that replace raw Ultra tool arguments with concise action phrases; rapid actions coalesce per agent, only one summary request runs at a time, final pending actions are flushed when an agent finishes, collapsed transcripts hide redundant tool previews, summaries are bounded, and `Ctrl+O` still shows native tool details and results
238 -- Hide Ultra's internal `structured_output` completion tool from progress summaries
239 -- Make every Ultra workflow step submit structured output through one validated contract, with strict schema sampling where supported and same-session reminders for missing results
240 -- Fix Ultra workflow thinking-level schemas for providers that require string enums
241 -- Improve Ultra's review workflow with readable analysis, verified findings, and concrete next steps instead of raw JSON output
242 -- Add Ultra's shipped `research` workflow with parallel web evidence gathering, gap auditing, adversarial verification, and a cited human-readable report
243 -- Load skills in Ultra's tool-using sub-agents by default with `ultra.subagentSkills: "none"` as the opt-out, and refuse workflows requiring unavailable tools
244 -- Let Ultra run mutating fanout when a phase declares a write-isolation rationale, trusting the orchestrator to assign disjoint ownership while loading normal extensions unchanged
245 -- Fix Ultra progress so phase transitions and completion preserve terminal scrollback
246 -- Fix Ultra tool-step cleanup so teardown errors do not hide a completed workflow step
247 -- Make Ultra's authoring skill available on demand through the active workflow tool, without a global skill entry or inactive-tool guidance
248 -- Fix Ultra native tool transcripts so partial results stay hidden until expanded
249 -- Fix Pulse TAB completion
250 -- Fix `/modernize` on Windows by resolving Pi behind platform launchers, and speed up audits by reading the installed package version without launching Pi
251 -- Fix Notes so `/tree` restores notes from the selected branch and `/new` asks whether to carry pending notes into the new session
252 -- Add `ctrl+enter` shortcut to park editor text as a note, clear the editor on success, and show a confirmation notification; `ctrl+alt+enter` opens a picker and sends the selected note
253 -- Disable all mise-managed tools on Android to avoid platform-specific tool failures
254 -- Speed up Mise workflows with direct task references and parallel CI check and lint stages
255 -- Fix the uv extension on Windows by skipping incompatible shell shims while retaining command blocking
256 -- Fix RTK rewriting so `find` commands keep exact path semantics unless RTK passes a path capability probe, and notify users when rewrites are disabled or the compatibility guard can be removed
257 -- Replace the tmux-only terminal skill with a terminal harness for observable TUI testing through tmux or WezTerm
258 -- Harden git-safe against hook-skipping Git options through aliases, shell indirection, nested Bash, `xargs`, and child-process PATH lookup, including Git Bash on Windows
259 -- Fix git-safe startup on Windows when commands clear or replace `PATH`, or disable MSYS argument conversion; give actionable errors without exposing launcher internals when Git cannot start
260 -- Fix git-safe cloning on Windows so valid deep destination paths are accepted
6 +- Harden dynamic-extension validator protocol handling and share workflow preparation across command and tool runs
7 +- Identify Ultra child assignments by workflow, phase, and agent; attribute interpolated prior-agent output to its immediate producers, preserve provenance through fanout transformations, and invalidate checkpoints when attribution changes
262 9 ## 0.0.3
277 24 - Add goal loop: autocomplete, progress UI, standing prompts, judge-gated updates
278 25 - Add tldr live summaries; model footer; quota parsers; jj-aware workspace status
279 26 - Fix session startup races, stale telemetry, aux LLM calls, provider secret leaks
280 -- Ship initial pi-ext set:
281 - goal, tldr, leaks, tps, quota, vcs-status
282 -- Add goal loop:
283 - autocomplete, progress UI, standing prompts, judge-gated updates
284 -- Add tldr live summaries; model footer; quota parsers; jj-aware workspace
285 - status
286 -- Fix session startup races, stale telemetry, aux LLM calls, provider secret
287 - leaks

extensions/ultra/README.md

Modified
98 98 Workflow runs append incomplete-run checkpoints to the current Pi session as custom entries that never enter LLM context.
99 99 Each launched step also gets a named persistent child session in the parent's session directory, linked to the parent session and resumable after interruption.
100 100 The parent journal stores child identity before prompting; the next matching run continues unchanged incomplete steps and reruns changed work in clean children.
101 -Checkpoint identity includes the resolved output schema; changing a named schema invalidates stale child work.
101 +Checkpoint identity includes the delivered agent envelope, immediate producer attribution, and resolved output schema.
102 +Changing assignment content, attribution, or a named schema invalidates stale child work.
102 103 Reused outputs must satisfy the current schema, and a schema-valid submission alone never proves task completion.
103 104 Completed runs start fresh but retain their named child sessions for `/resume` inspection.
104 105 No-session parents and `ultra.subagentSessionRetention = "none"` keep children entirely in memory.
106 107 Both progress surfaces use the same phase-first hierarchy, authored step summaries, status language, icons, elapsed time, counts, checkpoint state, token usage, and cost.
107 108 All agent rows keep task and activity summaries above indented metadata.
108 109 Summary interpolation uses short object labels and array counts, while prompts retain their complete JSON inputs.
109 -The overlay also shows each exact resolved sub-agent prompt as the first user message in its transcript.
110 +Ultra wraps every fresh child assignment in an agent envelope containing workflow, phase, and `phase#index` identity.
111 +Interpolated prior-agent outputs are quoted with their immediate producer IDs and resolved task summaries, while workflow arguments and literal items remain unquoted.
112 +The overlay shows this exact delivered sub-agent prompt as the first user message in its transcript.
110 113 Sub-agent tool calls keep one native Pi tool row from invocation through result and follow Pi's global expand state.
111 114 Collapsed workflow tool output shows counts, reported cost, and output tokens with Pi's standard expand hint.
112 115 Interactive completion also notifies the user with the status, phase count, and usage; headless runs stay silent.
213 216 Normal child context-file loading is enabled, including Pi's global and cwd/ancestor context files.
214 217 Builder guidance appends to discovered user system instructions rather than replacing `APPEND_SYSTEM.md`.
215 218 Children do not inherit the parent conversation or parent chat history.
219 +Ultra identifies each child and marks prior-agent output inserted through interpolation, but this metadata does not replace task context.
216 220 Authored prompts still supply task-specific parent constraints and applicable nested instruction paths, and require children to read those instructions before acting.
217 221 Skill and reference contents remain on demand; normal context loading is not wholesale parent history inheritance.
218 222 Available tools and extensions provide host capability, not permission to exceed the assignment's authorized scope.

extensions/ultra/__bench__/progress.bench.ts

Added
new file mode 100644
1 +import type { ReducerState, UltraProgressEvent } from "../progress.ts";
2 +import { initialReducerState, reduceProgress } from "../progress.ts";
4 +const ROUNDS = 12;
5 +const MINIMUM_ROUND_NS = 200_000_000;
6 +const EVENTS_PER_AGENT = 32;
7 +let sink = 0;
9 +function progressEvents(agentCount: number): UltraProgressEvent[] {
10 + const agentIds = Array.from(
11 + { length: agentCount },
12 + (_, index) => `agent#${index}`,
13 + );
14 + return [
15 + {
16 + kind: "plan",
17 + startedAt: 1,
18 + phases: [{ phase: "fanout", status: "resolved" as const, agentIds }],
19 + },
20 + ...agentIds.flatMap((agentId) => [
21 + {
22 + kind: "start" as const,
23 + agentId,
24 + phase: "fanout",
25 + },
26 + ...Array.from({ length: EVENTS_PER_AGENT }, () => ({
27 + kind: "delta" as const,
28 + agentId,
29 + phase: "fanout",
30 + text: "0123456789abcdef",
31 + })),
32 + {
33 + kind: "end" as const,
34 + agentId,
35 + phase: "fanout",
36 + status: "done",
37 + },
38 + ]),
39 + ];
42 +function fold(events: readonly UltraProgressEvent[]): void {
43 + let state: ReducerState = initialReducerState();
44 + for (const event of events) state = reduceProgress(state, event);
45 + sink ^= state.done + (state.transcripts["agent#0"]?.length ?? 0);
48 +function benchmark(name: string, operation: () => void): void {
49 + for (let index = 0; index < 3; index++) operation();
50 + let iterations = 1;
51 + while (true) {
52 + const started = process.hrtime.bigint();
53 + for (let index = 0; index < iterations; index++) operation();
54 + if (Number(process.hrtime.bigint() - started) >= MINIMUM_ROUND_NS) break;
55 + iterations *= 2;
56 + }
57 + for (let round = 0; round < ROUNDS; round++) {
58 + const started = process.hrtime.bigint();
59 + for (let index = 0; index < iterations; index++) operation();
60 + const elapsed = Number(process.hrtime.bigint() - started);
61 + console.log(
62 + `Benchmark${name}\t${iterations}\t${(elapsed / iterations).toFixed(0)} ns/op`,
63 + );
64 + }
67 +console.log(`goos: ${process.platform}`);
68 +console.log(`goarch: ${process.arch}`);
69 +console.log("pkg: pi-ext/ultra");
70 +for (const agentCount of [8, 64, 256]) {
71 + const events = progressEvents(agentCount);
72 + benchmark(`Progress${agentCount}`, () => fold(events));
74 +if (sink === 42) console.error(sink);

extensions/ultra/__tests__/agent-prompt.test.ts

Added
new file mode 100644
1 +import { describe, expect, it } from "vitest";
2 +import {
3 + assignmentPrompt,
4 + quoteAgentOutput,
5 + resumePrompt,
6 +} from "../agent-prompt.ts";
8 +describe("agent prompt envelopes", () => {
9 + it("identifies fresh assignments", () => {
10 + expect(
11 + assignmentPrompt(
12 + { workflow: "research", phase: "synthesis", index: 2 },
13 + "Synthesize evidence.",
14 + ),
15 + ).toBe(`<agent id="synthesis#2" workflow="research" phase="synthesis" index="2">
16 + <message from="orchestrator" kind="assignment">
17 +Synthesize evidence.
18 + </message>
19 +</agent>`);
20 + });
22 + it("quotes producer identity and task without exposing interpolation syntax", () => {
23 + const quoted = quoteAgentOutput('{"finding":"a < b"}', [
24 + { agentId: "gather#0", task: 'Inspect "parser" & docs' },
25 + ]);
26 + expect(quoted).toContain(
27 + '<source agent="gather#0" task="Inspect &quot;parser&quot; &amp; docs"/>',
28 + );
29 + expect(quoted).toContain(
30 + '<content><![CDATA[{"finding":"a < b"}]]></content>',
31 + );
32 + expect(quoted).not.toContain("results[]");
33 + });
35 + it("marks continuation without exposing checkpoint internals", () => {
36 + const prompt = resumePrompt("synthesis#2", "synthesis", "Continue.");
37 + expect(prompt).toContain('from="ultra" kind="resume"');
38 + expect(prompt).not.toContain("checkpoint");
39 + });
40 +});

extensions/ultra/__tests__/dynamic-extensions.test.ts

Modified
532 532 expect(await stat(created.draftPath)).toBeDefined();
533 533 }, 10_000);
535 + it("rejects a malformed validator result without crashing publication", async () => {
536 + const root = await mkdtemp(join(tmpdir(), "ultra-protocol-test-"));
537 + roots.push(root);
538 + const workerPath = join(root, "malformed-validator.mjs");
539 + await writeFile(
540 + workerPath,
541 + 'console.log("ULTRA_VALIDATION_RESULT=null");\n',
542 + "utf8",
543 + );
544 + const paths = fakePaths(root);
545 + const coordinator = createDynamicExtensionCoordinator({
546 + agentDir: join(root, "agent"),
547 + parentSessionId: "parent",
548 + workflowRunId: "protocol-run",
549 + availableTools: ["read"],
550 + paths,
551 + workerPath,
552 + });
553 + const builder = await coordinator.builder("build#0");
554 + const tools = new Map(builder.tools.map((tool) => [tool.name, tool]));
555 + await invoke(requiredTool(tools, "search_dynamic_extensions"), {
556 + query: "protocol probe",
557 + });
558 + const created = (await invoke(
559 + requiredTool(tools, "create_dynamic_extension"),
561 + name: "protocol-probe-capability",
562 + description: "Handles malformed validator protocol probes.",
563 + topic: "malformed validator protocol handling",
564 + scope: "Reject malformed validator protocol results safely.",
565 + nonGoals: ["Network access."],
566 + tags: ["protocol", "probe"],
567 + consideredCandidates: [],
568 + noMatchRationale: "The catalog has no protocol probe capability.",
569 + },
570 + )) as { draftPath: string };
572 + const validation = (await invoke(
573 + requiredTool(tools, "validate_dynamic_extension"),
574 + { path: created.draftPath },
575 + )) as { status: string; diagnostics: Array<{ code: string }> };
576 + expect(validation.status).toBe("failed");
577 + expect(validation.diagnostics).toEqual(
578 + expect.arrayContaining([
579 + expect.objectContaining({ code: "validator_protocol" }),
580 + ]),
581 + );
582 + });
535 584 it("searches, scaffolds, validates, publishes, and resolves an exact snapshot", async () => {
536 585 const root = await mkdtemp(join(tmpdir(), "ultra-dynamic-test-"));
537 586 roots.push(root);

extensions/ultra/__tests__/engine.test.ts

Modified
1 1 import { describe, expect, it, vi } from "vitest";
2 +import { assignmentPrompt } from "../agent-prompt.ts";
2 3 import { type EngineDeps, runWorkflow } from "../engine.ts";
3 4 import {
4 5 initialReducerState,
139 140 expect(fr.calls[0].item).toBeUndefined();
140 141 expect(fr.calls[0].phase).toBe("judge");
141 142 expect(fr.calls[0].agentId).toBe("judge#0");
143 + const prompt = assignmentPrompt(
144 + { workflow: "wf", phase: "judge", index: 0 },
145 + "hello",
146 + );
142 147 expect(JSON.parse(fr.calls[0].sessionKey)).toMatchObject({
143 148 phase: "judge",
144 149 index: 0,
145 - step: { prompt: "hello" },
150 + step: { prompt },
147 152 expect(res.phases).toEqual([{ id: "judge", ran: 1, ok: 1, dropped: 0 }]);
148 153 expect(res.workflow).toBe("wf");
149 154 expect(res.steered).toBe(false);
150 155 // No `return` ⇒ result defaults to the last phase's values.
151 - expect(res.result).toEqual([{ said: "hello" }]);
156 + expect(res.result).toEqual([{ said: prompt }]);
154 159 it("renders object summaries for humans without changing prompts or results", async () => {
185 190 expect(fr.calls[0].step.summary).toBe("Validate Niri handoff: integration");
186 - expect(fr.calls[0].step.prompt).toBe(`Validate ${JSON.stringify(item)}`);
191 + expect(fr.calls[0].step.prompt).toBe(
192 + assignmentPrompt(
193 + { workflow: "wf", phase: "validate", index: 0 },
194 + `Validate ${JSON.stringify(item)}`,
195 + ),
196 + );
187 197 expect(events).toContainEqual(
188 198 expect.objectContaining({
189 199 kind: "prompt",
395 405 expect(res.phaseResults.conditional).toEqual([]);
396 406 expect(res.phaseFailures.conditional).toEqual([]);
397 - expect(res.result).toEqual(["saw []"]);
407 + expect(res.result).toEqual([
408 + assignmentPrompt({ workflow: "wf", phase: "after", index: 0 }, "saw []"),
409 + ]);
400 412 it("runs one explicit recovery phase over prior failures", async () => {
525 537 const prompts = fr.calls.map((c) => c.step.prompt).sort();
526 - expect(prompts).toEqual(["do a for alice", "do b for alice"]);
538 + expect(prompts).toEqual([
539 + assignmentPrompt(
540 + { workflow: "wf", phase: "p", index: 0 },
541 + "do a for alice",
542 + ),
543 + assignmentPrompt(
544 + { workflow: "wf", phase: "p", index: 1 },
545 + "do b for alice",
546 + ),
547 + ]);
527 548 expect(events).toContainEqual(
528 549 expect.objectContaining({
529 550 agentId: "p#0",
530 551 kind: "prompt",
531 552 summary: "do a for alice",
532 - prompt: "do a for alice",
553 + prompt: assignmentPrompt(
554 + { workflow: "wf", phase: "p", index: 0 },
555 + "do a for alice",
556 + ),
581 605 expect(res.phases[0].id).toBe("review");
582 606 expect(res.phases[1].id).toBe("verify");
583 607 expect(res.phases[1].ran).toBe(2); // verify fanned out over both findings
608 + const verifyCalls = fr.calls
609 + .filter((call) => call.phase === "verify")
610 + .sort((left, right) => left.agentId.localeCompare(right.agentId));
611 + expect(verifyCalls[0].step.prompt).toContain(
612 + '<source agent="review#0" task="review correctness"/>',
613 + );
614 + expect(verifyCalls[0].step.prompt).toContain(
615 + '<content><![CDATA[{"title":"correctness-1","file":"correctness.ts"}]]></content>',
616 + );
617 + expect(verifyCalls[1].step.prompt).toContain(
618 + '<source agent="review#1" task="review security"/>',
619 + );
620 + expect(verifyCalls[0].step.prompt).not.toContain("results[].findings[]");
584 621 // Only the correctness verdict is `real`; it retains its join key.
585 622 expect(res.result).toEqual([
586 623 { title: "correctness-1", file: "correctness.ts", real: true },
707 744 // ---------------------------------------------------------------------------
709 746 describe("runWorkflow — resume journal", () => {
747 + it("includes producer attribution in downstream checkpoint identity", async () => {
748 + const downstreamKeys: string[] = [];
749 + const run = async (producer: "source_a" | "source_b") => {
750 + const fr = fakeRunner((args) => {
751 + if (args.phase === "consume") downstreamKeys.push(args.sessionKey);
752 + return args.phase === "consume"
753 + ? { ok: true, value: "done" }
754 + : { ok: true, value: { evidence: "same" } };
755 + });
756 + await runWorkflow(
757 + spec({
758 + name: "provenance-checkpoint",
759 + phases: [
761 + id: producer,
762 + kind: "single",
763 + step: { summary: `Gather ${producer}`, prompt: "Gather" },
764 + },
766 + id: "consume",
767 + kind: "single",
768 + step: {
769 + summary: "Consume evidence",
770 + prompt: `Consume {${producer}.results}`,
771 + },
772 + },
773 + ],
774 + }),
775 + undefined,
776 + baseDeps({ stepRunner: fr.runner }),
777 + );
778 + };
780 + await run("source_a");
781 + await run("source_b");
783 + expect(downstreamKeys).toHaveLength(2);
784 + expect(downstreamKeys[0]).not.toBe(downstreamKeys[1]);
785 + expect(downstreamKeys[0]).toContain('source agent=\\"source_a#0\\"');
786 + expect(downstreamKeys[1]).toContain('source agent=\\"source_b#0\\"');
787 + });
710 789 it("writes successful step results and reuses matching cached steps", async () => {
711 790 const firstJournal = memoryJournal();
712 791 const s = spec({
788 867 phase: "review",
789 868 index: 0,
791 - step,
870 + step: {
871 + ...step,
872 + prompt: assignmentPrompt(
873 + { workflow: "wf", phase: "review", index: 0 },
874 + step.prompt,
875 + ),
876 + },
792 877 resolvedSchema: definition,
793 878 dynamicExtensions: [],

extensions/ultra/__tests__/harness.test.ts

Modified
598 + it("prepares dynamic extension runs on both command and tool surfaces", async () => {
599 + const message =
600 + 'ultra: dynamic extension "missing-live-capability" has no canonical revision. Run a builder with all four dynamic-extension tools.';
601 + t = await createTestSession({ extensions: [ultraPath()] });
602 + saveWorkflow(t, "runtime-error-command", "missing-live-capability");
603 + saveWorkflow(t, "runtime-error-tool", "missing-live-capability");
604 + const [extension] = t.session.extensionRunner.extensions;
605 + const ctx = t.session.extensionRunner.createCommandContext();
606 + driveOverlay(ctx);
607 + await extension.commands
608 + .get("ultra")
609 + .handler("run runtime-error-command", ctx);
610 + expect(t.events.uiCallsFor("notify").at(-1)?.args).toEqual([
611 + message,
612 + "error",
613 + ]);
615 + await extension.commands.get("ultra").handler("", ctx);
616 + await expect(
617 + extension.tools
618 + .get("run_workflow")
619 + .definition.execute(
620 + "call",
621 + { name: "runtime-error-tool" },
622 + undefined,
623 + undefined,
624 + ctx,
625 + ),
626 + ).rejects.toThrow(message);
627 + });
598 629 it("reports confirmed whole-run cancellation as aborted while retaining its aggregate", async () => {
599 630 t = await createTestSession({ extensions: [ultraPath()] });
600 631 saveWorkflow(t, "cancelled-run");

extensions/ultra/__tests__/interp.test.ts

Modified
2 2 import { describe, expect, it } from "vitest";
3 3 import {
4 4 type InterpContext,
5 5 resolveOver,
6 + resolveOverWithSources,
6 7 resolveSelector,
7 8 resolveTemplate,
9 + resolveTemplateWithSources,
8 10 SpecValidationError,
9 11 } from "../interp.ts";
80 +describe("source attribution", () => {
81 + it("preserves producer positions through flattening and filtering", () => {
82 + const flattened = resolveOverWithSources(
83 + "{r.results[].findings[]}",
84 + fixture(),
85 + );
86 + expect(flattened).toEqual([
87 + { value: "a1", sources: [{ phase: "r", index: 0 }] },
88 + { value: "a2", sources: [{ phase: "r", index: 0 }] },
89 + { value: "b1", sources: [{ phase: "r", index: 2 }] },
90 + { value: "c1", sources: [{ phase: "r", index: 4 }] },
91 + ]);
93 + const filtered = resolveOverWithSources(
94 + "{r.results | where real}",
95 + fixture(),
96 + );
97 + expect(filtered.map((item) => item.sources)).toEqual([
98 + [{ phase: "r", index: 0 }],
99 + [{ phase: "r", index: 3 }],
100 + ]);
101 + });
103 + it("unions member producers for grouped fanout items", () => {
104 + const grouped = resolveOverWithSources("{r.results | groupBy source}", {
105 + results: {
106 + r: [
107 + { source: "sessions", id: 1 },
108 + { source: "repository", id: 2 },
109 + { source: "sessions", id: 3 },
110 + ],
111 + },
112 + });
113 + expect(grouped[0].sources).toEqual([
114 + { phase: "r", index: 0 },
115 + { phase: "r", index: 2 },
116 + ]);
117 + expect(grouped[1].sources).toEqual([{ phase: "r", index: 1 }]);
118 + });
120 + it("reports sources to prompt rendering without changing ordinary values", () => {
121 + const rendered = resolveTemplateWithSources(
122 + "topic={args.topic}; prior={r.results}; item={item}",
124 + ...fixture(),
125 + itemSources: [{ phase: "r", index: 4 }],
126 + },
127 + (content, sources) =>
128 + `${content}<${sources.map(({ phase, index }) => `${phase}#${index}`).join(",")}>`,
129 + );
130 + expect(rendered).toContain("topic=security<>");
131 + expect(rendered).toContain("<r#0,r#2,r#3,r#4>");
132 + expect(rendered).toContain("item=performance<r#4>");
133 + });
134 +});
78 136 describe("resolveSelector", () => {
79 137 it("retains nulls positionally for plain {PHASE.results}", () => {
80 138 const out = resolveSelector("{r.results}", fixture());

extensions/ultra/__tests__/prompt.test.ts

Modified
93 93 "fanout",
94 94 "children run in separate sessions",
95 95 "do not inherit the parent conversation",
96 + "automatically wraps fresh assignments",
97 + "immediate producer identity",
96 98 "writeIsolation",
97 99 "structured_output",
98 100 "fullOutputPath",

extensions/ultra/__tests__/runner.test.ts

Modified
6 6 // the structured result on `tool_execution_end.result.details`).
8 8 import { describe, expect, it, vi } from "vitest";
9 +import { resumePrompt } from "../agent-prompt.ts";
9 10 import type { UltraProgressEvent } from "../progress.ts";
10 11 import {
11 12 makeStepRunner,
636 637 baseOpts(),
639 - expect(prompts).toEqual([RESUME_STEP_PROMPT]);
640 + expect(prompts).toEqual([
641 + resumePrompt("review#0", "review", RESUME_STEP_PROMPT),
642 + ]);
640 643 expect(prompts).not.toContain(toolStep.prompt);
641 644 expect(result).toEqual({ ok: true, value: { verdict: "resumed" } });

extensions/ultra/agent-prompt.ts

Added
new file mode 100644
1 +export interface AgentPromptIdentity {
2 + workflow: string;
3 + phase: string;
4 + index: number;
5 +}
7 +export interface AgentPromptSource {
8 + agentId: string;
9 + task: string;
12 +function escapeAttribute(value: string): string {
13 + return value
14 + .replaceAll("&", "&amp;")
15 + .replaceAll('"', "&quot;")
16 + .replaceAll("<", "&lt;")
17 + .replaceAll(">", "&gt;");
20 +function cdata(value: string): string {
21 + return `<![CDATA[${value.replaceAll("]]>", "]]]]><![CDATA[>")}]]>`;
24 +export function quoteAgentOutput(
25 + content: string,
26 + sources: AgentPromptSource[],
27 +): string {
28 + if (sources.length === 0) return content;
29 + const sourceLines = sources.map(
30 + (source) =>
31 + ` <source agent="${escapeAttribute(source.agentId)}" task="${escapeAttribute(source.task)}"/>`,
32 + );
33 + return [
34 + "<quote>",
35 + ...sourceLines,
36 + ` <content>${cdata(content)}</content>`,
37 + "</quote>",
38 + ].join("\n");
41 +export function assignmentPrompt(
42 + identity: AgentPromptIdentity,
43 + assignment: string,
44 +): string {
45 + const agentId = `${identity.phase}#${identity.index}`;
46 + return [
47 + `<agent id="${escapeAttribute(agentId)}" workflow="${escapeAttribute(identity.workflow)}" phase="${escapeAttribute(identity.phase)}" index="${identity.index}">`,
48 + ' <message from="orchestrator" kind="assignment">',
49 + assignment,
50 + " </message>",
51 + "</agent>",
52 + ].join("\n");
55 +export function resumePrompt(
56 + agentId: string,
57 + phase: string,
58 + message: string,
59 +): string {
60 + return [
61 + `<agent id="${escapeAttribute(agentId)}" phase="${escapeAttribute(phase)}">`,
62 + ' <message from="ultra" kind="resume">',
63 + message,
64 + " </message>",
65 + "</agent>",
66 + ].join("\n");

extensions/ultra/dynamic-catalog.ts

Modified
973 +type ValidatorResult = WorkerValidationResult & { aborted?: boolean };
975 +function parseValidatorResult(text: string): ValidatorResult {
976 + const value: unknown = JSON.parse(text);
977 + if (
978 + !value ||
979 + typeof value !== "object" ||
980 + Array.isArray(value) ||
981 + typeof (value as { ok?: unknown }).ok !== "boolean" ||
982 + !Array.isArray((value as { diagnostics?: unknown }).diagnostics)
984 + throw new Error("validator result has an invalid shape");
985 + return value as ValidatorResult;
988 +async function readValidatorResult(
989 + path: string,
990 +): Promise<ValidatorResult | undefined> {
991 + try {
992 + return parseValidatorResult(await readFile(path, "utf8"));
993 + } catch {
994 + return undefined;
998 +function validatorProtocolFailure(
999 + draftPath: string,
1000 + output: string,
1001 + actual?: string,
1002 +): ValidatorResult {
1003 + return failedValidation(draftPath, {
1004 + gate: "validator",
1005 + code: "validator_protocol",
1006 + status: "error",
1007 + ...(actual ? { actual } : {}),
1008 + output: bounded(output),
1009 + remediation:
1010 + "Inspect validator output and repair the worker protocol failure.",
1011 + draftPath,
1012 + });
973 1015 async function runValidator(args: {
974 1016 workerPath: string;
975 1017 draftPath: string;
976 1018 signal?: AbortSignal;
977 -}): Promise<WorkerValidationResult & { aborted?: boolean }> {
1019 +}): Promise<ValidatorResult> {
978 1020 if (args.signal?.aborted)
979 1021 return abortedValidation(
980 1022 args.draftPath,
1004 1046 child.stderr.on("data", append);
1005 1047 let finished = false;
1006 1048 let stopping = false;
1007 - const finish = (value: WorkerValidationResult & { aborted?: boolean }) => {
1049 + const finish = (value: ValidatorResult): void => {
1008 1050 if (finished) return;
1009 1051 finished = true;
1010 1052 clearTimeout(timer);
1011 1053 args.signal?.removeEventListener("abort", onAbort);
1012 - void rm(resultPath, { force: true });
1054 + void rm(resultPath, { force: true }).catch(() => {});
1013 1055 resolveResult(value);
1015 - const stop = async (reason: "aborted" | "timeout") => {
1057 + const stop = async (reason: "aborted" | "timeout"): Promise<void> => {
1016 1058 if (finished || stopping) return;
1017 1059 stopping = true;
1018 1060 await killProcessTree(child.pid);
1050 - child.on("close", async () => {
1092 + child.on("close", () => {
1051 1093 if (stopping) return;
1052 - try {
1053 - finish(JSON.parse(await readFile(resultPath, "utf8")));
1054 - return;
1055 - } catch {}
1056 - const marker = "ULTRA_VALIDATION_RESULT=";
1057 - const index = output.lastIndexOf(marker);
1058 - if (index < 0) {
1059 - finish(
1060 - failedValidation(args.draftPath, {
1061 - gate: "validator",
1062 - code: "validator_protocol",
1063 - status: "error",
1064 - output: bounded(output),
1065 - remediation:
1066 - "Inspect validator output and repair the worker protocol failure.",
1067 - draftPath: args.draftPath,
1068 - }),
1069 - );
1070 - return;
1072 - try {
1073 - const line = output.slice(index + marker.length).split(/\r?\n/u)[0];
1074 - finish(JSON.parse(line));
1075 - } catch (error) {
1076 - finish(
1077 - failedValidation(args.draftPath, {
1078 - gate: "validator",
1079 - code: "validator_protocol",
1080 - status: "error",
1081 - actual: error instanceof Error ? error.message : String(error),
1082 - output: bounded(output),
1083 - remediation: "Repair malformed validator result output.",
1084 - draftPath: args.draftPath,
1085 - }),
1086 - );
1094 + void (async () => {
1095 + const fileResult = await readValidatorResult(resultPath);
1096 + if (fileResult) {
1097 + finish(fileResult);
1098 + return;
1100 + const marker = "ULTRA_VALIDATION_RESULT=";
1101 + const index = output.lastIndexOf(marker);
1102 + if (index < 0) {
1103 + finish(validatorProtocolFailure(args.draftPath, output));
1104 + return;
1106 + try {
1107 + const line = output.slice(index + marker.length).split(/\r?\n/u)[0];
1108 + finish(parseValidatorResult(line));
1109 + } catch (error) {
1110 + finish(
1111 + validatorProtocolFailure(
1112 + args.draftPath,
1113 + output,
1114 + error instanceof Error ? error.message : String(error),
1115 + ),
1116 + );
1118 + })();

extensions/ultra/engine.ts

Modified
19 19 // results (`isAborted` ∥ `!ok`), independent of the progress stream — the
20 20 // synthetic `end` is board-only.
22 +import {
23 + type AgentPromptSource,
24 + assignmentPrompt,
25 + quoteAgentOutput,
26 +} from "./agent-prompt.ts";
22 27 import { summarizeValue } from "./display.ts";
23 28 import type {
24 29 DynamicExtensionResolver,
27 32 } from "./dynamic-types.ts";
28 33 import {
29 34 type InterpContext,
30 - resolveOver,
35 + type InterpSource,
36 + resolveOverWithSources,
31 37 resolveSelector,
32 38 resolveTemplate,
39 + resolveTemplateWithSources,
40 + type SourcedValue,
33 41 } from "./interp.ts";
34 42 import { isAborted, mapWithConcurrency } from "./pool.ts";
35 43 import type {
164 172 const phases: PhaseResult[] = [];
165 173 const tokenUsage = zeroUsage();
166 174 const steeredBox = { value: false };
175 + const agentTasks = new Map<string, string>();
167 176 const forward = makeForwarder(deps, steeredBox);
168 177 forward({ kind: "plan", phases: planPhases(spec), startedAt: Date.now() });
191 200 // launches — it is deliberately not a runtime drop.
192 201 const context = { args, results, failures: phaseFailures };
193 202 const items = phaseItems(phase, context);
194 - const resolved = items.map((item) => ({
195 - item,
196 - step: resolveStep(phase.step, { ...context, item }),
197 - }));
203 + const resolved = items.map(
204 + ({ value: item, sources: itemSources }, index) => ({
205 + item,
206 + step: resolveStep(
207 + phase.step,
208 + { ...context, item, itemSources },
210 + workflow: spec.name,
211 + phase: phase.id,
212 + index,
213 + },
214 + agentTasks,
215 + ),
216 + }),
217 + );
198 218 const agentIds = resolved.map((_, index) => `${phase.id}#${index}`);
219 + resolved.forEach(({ step }, index) =>
220 + agentTasks.set(`${phase.id}#${index}`, step.summary),
221 + );
199 222 forward({
200 223 kind: "phase",
201 224 phase: phase.id,
587 610 /** The fanout/single item list. `single` runs its step exactly once (any `over`
588 611 * is ignored in v1); `fanout` resolves `over` to its element array. */
589 -function phaseItems(phase: Phase, ctx: InterpContext): unknown[] {
590 - if (phase.kind === "fanout") return resolveOver(phase.over, ctx);
591 - return [undefined];
612 +function phaseItems(phase: Phase, ctx: InterpContext): SourcedValue[] {
613 + if (phase.kind === "fanout") return resolveOverWithSources(phase.over, ctx);
614 + return [{ value: undefined, sources: [] }];
617 +function promptSources(
618 + sources: readonly InterpSource[],
619 + agentTasks: ReadonlyMap<string, string>,
620 +): AgentPromptSource[] {
621 + return sources.map(({ phase, index }) => {
622 + const agentId = `${phase}#${index}`;
623 + return { agentId, task: agentTasks.get(agentId) ?? phase };
624 + });
594 627 /** Resolve a step's UI summary and prompt; the runner receives both verbatim. */
595 -function resolveStep(step: Step, ctx: InterpContext): Step {
628 +function resolveStep(
629 + step: Step,
630 + ctx: InterpContext,
631 + identity: { workflow: string; phase: string; index: number },
632 + agentTasks: ReadonlyMap<string, string>,
633 +): Step {
596 634 let dynamicExtensions = step.dynamicExtensions;
597 635 if (typeof dynamicExtensions === "string") {
598 636 const selected = resolveSelector(dynamicExtensions, ctx);
607 645 dynamicExtensions = selected as string[];
647 + const prompt = resolveTemplateWithSources(
648 + step.prompt,
649 + ctx,
650 + (content, sources) =>
651 + quoteAgentOutput(content, promptSources(sources, agentTasks)),
652 + );
609 653 return {
610 654 ...step,
611 655 summary: resolveTemplate(step.summary, ctx, summarizeValue),
612 - prompt: resolveTemplate(step.prompt, ctx),
656 + prompt: assignmentPrompt(identity, prompt),
613 657 ...(dynamicExtensions === undefined ? {} : { dynamicExtensions }),

extensions/ultra/implementation.ts

Modified
282 + const prepareRun = async (
283 + ctx: ExtensionContext,
284 + spec: WorkflowSpec,
285 + cfg: UltraSettings,
286 + args: Record<string, unknown> | undefined,
287 + extensions: SubagentExtensionSelection,
288 + ): Promise<{
289 + journal: SessionWorkflowJournal;
290 + dynamicExtensions?: DynamicExtensionResolver;
291 + stepRunner: StepRunner;
292 + }> => {
293 + const journal = createJournal(ctx, spec, cfg, args);
294 + const dynamicExtensions = await dynamicResolver(
295 + ctx,
296 + spec,
297 + journal,
298 + extensions,
299 + );
300 + return {
301 + journal,
302 + dynamicExtensions,
303 + stepRunner: buildStepRunner(
304 + ctx,
305 + spec,
306 + cfg,
307 + journal,
308 + extensions,
309 + dynamicExtensions,
310 + ),
311 + };
312 + };
282 314 // ── `run_workflow` tool (model-callable, mid-turn, read-only onUpdate surface) ──
283 315 pi.registerTool({
284 316 name: "run_workflow",
322 354 const extensions = resolveSubagentExtensions(cfg.subagentExtensions);
323 355 const error = workflowError(spec, extensions, cfg);
324 356 if (error) throw new Error(error);
325 - const journal = createJournal(ctx, spec, cfg, args);
326 - const dynamicExtensions = await dynamicResolver(
327 - ctx,
328 - spec,
329 - journal,
330 - extensions,
331 - );
332 - const stepRunner = buildStepRunner(
333 - ctx,
334 - spec,
335 - cfg,
336 - journal,
337 - extensions,
338 - dynamicExtensions,
339 - );
357 + const prepared = await prepareRun(ctx, spec, cfg, args, extensions);
340 358 // onProgress folds into the reducer + pushes through `onUpdate`; headless
341 359 // (no `onUpdate`) degrades to a no-op sink that still tracks final state.
342 360 const progress = makeToolProgressSink(onUpdate ?? (() => {}), {
344 362 workflowDescription: spec.description,
346 364 const result = await runWorkflow(spec, args, {
347 - stepRunner,
365 + stepRunner: prepared.stepRunner,
348 366 concurrency: cfg.concurrency,
349 - journal,
350 - dynamicExtensions,
367 + journal: prepared.journal,
368 + dynamicExtensions: prepared.dynamicExtensions,
351 369 signal, // the SDK execute() signal: stops the pool + fans session.abort()
352 370 onProgress: progress.sink,
444 462 ctx.ui.notify(error, "error");
445 463 return;
447 - const journal = createJournal(ctx, spec, cfg, runArgs);
448 - const dynamicExtensions = await dynamicResolver(
449 - ctx,
450 - spec,
451 - journal,
452 - extensions,
453 - );
454 - const stepRunner = buildStepRunner(
455 - ctx,
456 - spec,
457 - cfg,
458 - journal,
459 - extensions,
460 - dynamicExtensions,
461 - );
465 + const prepared = await prepareRun(ctx, spec, cfg, runArgs, extensions);
463 467 // The command owns its AbortController (idle ⇒ ctx.signal is undefined).
464 468 // Global Esc / per-agent abort fire it; the engine fans session.abort().
490 494 void (async () => {
492 496 const r = await runWorkflow(spec, runArgs, {
493 - stepRunner,
497 + stepRunner: prepared.stepRunner,
494 498 concurrency: cfg.concurrency,
495 - journal,
496 - dynamicExtensions,
499 + journal: prepared.journal,
500 + dynamicExtensions: prepared.dynamicExtensions,
497 501 signal: controller.signal,
498 502 onProgress: (e) => overlay.handleProgress(e),

extensions/ultra/interp.ts

Modified
32 32 * The three namespaces are segregated so a phase named `args` or `item`
33 33 * cannot collide with the reserved roots.
35 +export interface InterpSource {
36 + phase: string;
37 + index: number;
35 40 export interface InterpContext {
36 41 args?: Record<string, unknown>;
37 42 item?: unknown;
43 + itemSources?: readonly InterpSource[];
38 44 results?: Record<string, unknown[]>;
39 45 failures?: Record<string, unknown[]>;
48 +export interface SourcedValue {
49 + value: unknown;
50 + sources: InterpSource[];
53 +interface ResolvedNode extends SourcedValue {
54 + elements?: ResolvedNode[];
42 57 const IDENT = "[A-Za-z_][A-Za-z0-9_]*";
43 58 const RE_ARGS = new RegExp(`^args\\.(${IDENT})$`);
44 59 const RE_RESULTS = new RegExp(`^(${IDENT})\\.results$`);
187 202 return failures;
190 -function resolveBase(base: Base, ctx: InterpContext): unknown {
205 +function uniqueSources(sources: readonly InterpSource[]): InterpSource[] {
206 + const seen = new Set<string>();
207 + const out: InterpSource[] = [];
208 + for (const source of sources) {
209 + const key = `${source.phase}#${source.index}`;
210 + if (seen.has(key)) continue;
211 + seen.add(key);
212 + out.push(source);
214 + return out;
217 +function node(
218 + value: unknown,
219 + sources: readonly InterpSource[] = [],
220 +): ResolvedNode {
221 + const ownSources = uniqueSources(sources);
222 + return {
223 + value,
224 + sources: ownSources,
225 + ...(Array.isArray(value)
226 + ? { elements: value.map((element) => node(element, ownSources)) }
227 + : {}),
228 + };
231 +function arrayNode(elements: ResolvedNode[]): ResolvedNode {
232 + return {
233 + value: elements.map((element) => element.value),
234 + sources: uniqueSources(elements.flatMap((element) => element.sources)),
235 + elements,
236 + };
239 +function resultNode(ctx: InterpContext, phase: string): ResolvedNode {
240 + return arrayNode(
241 + getResults(ctx, phase).map((value, index) =>
242 + node(
243 + value,
244 + value === null || value === undefined ? [] : [{ phase, index }],
245 + ),
246 + ),
247 + );
250 +function resolveBaseNode(base: Base, ctx: InterpContext): ResolvedNode {
191 251 switch (base.kind) {
192 252 case "item":
193 - return ctx.item;
253 + return node(ctx.item, ctx.itemSources);
194 254 case "args":
195 - return ctx.args?.[base.name];
255 + return node(ctx.args?.[base.name]);
196 256 case "results":
197 257 // Retain nulls positionally — callers depend on length.
198 - return getResults(ctx, base.phase);
258 + return resultNode(ctx, base.phase);
199 259 case "failures":
200 - return getFailures(ctx, base.phase);
260 + // Failure records are emitted by Ultra, not authored by the failed agent.
261 + return node(getFailures(ctx, base.phase));
201 262 case "flatten": {
202 - const out: unknown[] = [];
203 - for (const el of getResults(ctx, base.phase)) {
204 - if (el === null || el === undefined) continue; // skip null elements
205 - if (!isRecord(el)) continue;
206 - const field = el[base.field];
263 + const out: ResolvedNode[] = [];
264 + for (const element of resultNode(ctx, base.phase).elements ?? []) {
265 + if (element.value === null || element.value === undefined) continue;
266 + if (!isRecord(element.value)) continue;
267 + const field = element.value[base.field];
207 268 // Only arrays contribute; missing / null / non-array FIELDs skipped.
208 - if (Array.isArray(field)) out.push(...field);
269 + if (!Array.isArray(field)) continue;
270 + out.push(...field.map((value) => node(value, element.sources)));
210 - return out;
272 + return arrayNode(out);
212 274 case "project": {
213 - const out: unknown[] = [];
214 - for (const el of getResults(ctx, base.phase)) {
215 - if (el === null || el === undefined) continue;
216 - if (!isRecord(el)) continue;
217 - const field = el[base.field];
275 + const out: ResolvedNode[] = [];
276 + for (const element of resultNode(ctx, base.phase).elements ?? []) {
277 + if (element.value === null || element.value === undefined) continue;
278 + if (!isRecord(element.value)) continue;
279 + const field = element.value[base.field];
218 280 // Missing / null FIELDs contribute no projected value.
219 - if (field !== undefined && field !== null) out.push(field);
281 + if (field !== undefined && field !== null)
282 + out.push(node(field, element.sources));
221 - return out;
284 + return arrayNode(out);
226 -function resolveExpr(expr: Expr, ctx: InterpContext): unknown {
289 +function resolveExprNode(expr: Expr, ctx: InterpContext): ResolvedNode {
227 290 if (expr.kind === "where") {
228 - const source = resolveBase(expr.base, ctx);
229 - if (!Array.isArray(source)) {
291 + const source = resolveBaseNode(expr.base, ctx);
292 + if (!Array.isArray(source.value)) {
230 293 throw new SpecValidationError(
231 294 `"| where ${expr.field}" requires an array on its left-hand side`,
234 - const out: unknown[] = [];
235 - for (const el of source) {
236 - if (el === null || el === undefined) continue; // skip null elements
237 - if (!isRecord(el)) continue; // missing FIELD (not dereferenceable)
238 - const value = el[expr.field];
297 + const out: ResolvedNode[] = [];
298 + for (const element of source.elements ?? []) {
299 + if (element.value === null || element.value === undefined) continue;
300 + if (!isRecord(element.value)) continue;
301 + const value = element.value[expr.field];
240 303 expr.equals !== undefined
241 304 ? typeof value === "string" && value === expr.equals
242 305 : Boolean(value)
244 - out.push(el);
307 + out.push(element);
246 - return out;
309 + return arrayNode(out);
248 311 if (expr.kind === "groupBy") {
249 - const source = resolveBase(expr.base, ctx);
250 - if (!Array.isArray(source)) {
312 + const source = resolveBaseNode(expr.base, ctx);
313 + if (!Array.isArray(source.value)) {
251 314 throw new SpecValidationError(
252 315 `"| groupBy ${expr.field}" requires an array on its left-hand side`,
255 - const groups: Array<{ key: string; items: unknown[] }> = [];
256 - const byKey = new Map<string, { key: string; items: unknown[] }>();
257 - for (const el of source) {
258 - if (!isRecord(el)) continue;
259 - const value = el[expr.field];
318 + const groups: Array<{
319 + key: string;
320 + items: unknown[];
321 + sources: InterpSource[];
322 + }> = [];
323 + const byKey = new Map<string, (typeof groups)[number]>();
324 + for (const element of source.elements ?? []) {
325 + if (!isRecord(element.value)) continue;
326 + const value = element.value[expr.field];
260 327 if (typeof value !== "string") continue;
261 328 const group = byKey.get(value);
262 329 if (group) {
263 - group.items.push(el);
330 + group.items.push(element.value);
331 + group.sources = uniqueSources([...group.sources, ...element.sources]);
264 332 continue;
266 - const created = { key: value, items: [el] };
334 + const created = {
335 + key: value,
336 + items: [element.value],
337 + sources: [...element.sources],
338 + };
267 339 byKey.set(value, created);
268 340 groups.push(created);
270 - return groups;
342 + return arrayNode(
343 + groups.map((group) =>
344 + node({ key: group.key, items: group.items }, group.sources),
345 + ),
346 + );
272 - return resolveBase(expr, ctx);
348 + return resolveBaseNode(expr, ctx);
351 +function resolveExpr(expr: Expr, ctx: InterpContext): unknown {
352 + return resolveExprNode(expr, ctx).value;
275 355 /** Render a resolved value into template text: strings verbatim, else compact JSON. */
377 +/** Resolve prompt substitutions with immediate producer metadata while leaving
378 + * ordinary workflow arguments and literal fanout items unattributed. */
379 +export function resolveTemplateWithSources(
380 + template: string,
381 + ctx: InterpContext,
382 + render: (content: string, sources: readonly InterpSource[]) => string,
383 +): string {
384 + return template.replace(RE_TOKEN, (_match, inner: string) => {
385 + const resolved = resolveExprNode(parseExpr(inner), ctx);
386 + return render(renderValue(resolved.value), resolved.sources);
387 + });
298 391 * Resolve a single braced selector expression (`over` / `when` / `return` /
299 392 * `report`) to its raw
314 407 * interpolation expression that must resolve to an array.
316 409 export function resolveOver(over: unknown, ctx: InterpContext): unknown[] {
317 - if (Array.isArray(over)) return over;
410 + return resolveOverWithSources(over, ctx).map((item) => item.value);
413 +/** Resolve fanout items together with immediate producer metadata. */
414 +export function resolveOverWithSources(
415 + over: unknown,
416 + ctx: InterpContext,
417 +): SourcedValue[] {
418 + if (Array.isArray(over)) return over.map((value) => ({ value, sources: [] }));
318 419 if (typeof over === "string") {
319 - const resolved = resolveSelector(over, ctx);
320 - if (!Array.isArray(resolved)) {
420 + const match = over.trim().match(RE_SINGLE_TOKEN);
421 + if (!match) {
422 + throw new SpecValidationError(
423 + `selector must be a single brace-wrapped token, got "${over}"`,
424 + );
426 + const resolved = resolveExprNode(parseExpr(match[1]), ctx);
427 + if (!Array.isArray(resolved.value)) {
321 428 throw new SpecValidationError(
322 429 `"over" interpolation "${over}" did not resolve to an array`,
325 - return resolved;
432 + return (resolved.elements ?? []).map(({ value, sources }) => ({
433 + value,
434 + sources,
435 + }));
327 437 throw new SpecValidationError(
328 438 `"over" must be an array literal or an interpolation string, got ${typeof over}`,

extensions/ultra/mise.toml

Modified
1 +[tasks.bench]
2 +description = "Benchmark Ultra progress reduction"
3 +depends = ["//:install"]
4 +run = "node --no-warnings --experimental-strip-types __bench__/progress.bench.ts"
6 +[tasks.profile]
7 +description = "Profile Ultra progress reduction"
8 +depends = ["//:install"]
9 +run = [
10 + '''node -e "require('node:fs').mkdirSync('../../.research/ultra', { recursive: true })"''',
11 + "node --no-warnings --experimental-strip-types --cpu-prof --cpu-prof-dir ../../.research/ultra --cpu-prof-name ultra.cpuprofile __bench__/progress.bench.ts",
14 +[tasks.benchstat]
15 +description = "Compare Ultra benchmark results"
16 +depends = ["//:install"]
17 +usage = '''
18 +arg "<baseline>"
19 +arg "<candidate>"
20 +'''
21 +run = 'benchstat "{{ usage.baseline }}" "{{ usage.candidate }}"'
1 23 [tasks.fmt]
2 24 description = "Format ultra extension"
3 25 depends = ["//:install"]

extensions/ultra/progress.ts

Modified
602 602 const idx = state.rows.findIndex((row) => row.agentId === event.agentId);
603 603 const prev = idx >= 0 ? state.rows[idx] : undefined;
604 604 const row = nextRow(prev, event);
605 - const rows =
606 - idx >= 0
607 - ? state.rows.map((entry, i) => (i === idx ? row : entry))
608 - : [...state.rows, row];
605 + const rows = idx < 0 ? [...state.rows, row] : state.rows.slice();
606 + if (idx >= 0) rows[idx] = row;
610 608 const added = transcriptText(event);
611 609 const transcripts = added
650 - const phases = state.phases.some((phase) => phase.phase === event.phase)
651 - ? state.phases
652 - : [
653 - ...state.phases,
654 - {
655 - phase: event.phase,
656 - status: "resolved" as const,
657 - agentIds: [event.agentId],
658 - },
659 - ];
648 + const phases =
649 + state.phase === event.phase ||
650 + state.phases.some((phase) => phase.phase === event.phase)
651 + ? state.phases
652 + : [
653 + ...state.phases,
655 + phase: event.phase,
656 + status: "resolved" as const,
657 + agentIds: [event.agentId],
658 + },
659 + ];
661 - return withCounts({
661 + // Agent events can change only one row status. Updating its counters directly
662 + // avoids rescanning every fanout row for every streamed token while preserving
663 + // immutable snapshots required by tool-result structured cloning.
664 + let { total, queued, running, done, dropped } = state;
665 + if (!prev || prev.status !== row.status) {
666 + const adjust = (status: AgentStatus, amount: number): void => {
667 + if (status === "queued") queued += amount;
668 + else if (status === "running") running += amount;
669 + else if (status === "done") done += amount;
670 + else dropped += amount;
671 + };
672 + if (!prev) total++;
673 + else adjust(prev.status, -1);
674 + adjust(row.status, 1);
677 + return {
662 678 workflowName: state.workflowName,
663 679 workflowDescription: state.workflowDescription,
668 684 phase: event.phase,
669 685 startedAt: state.startedAt,
670 686 endedAt: state.endedAt,
687 + total,
688 + queued,
689 + running,
690 + done,
691 + dropped,
692 + later: state.later,
671 693 workflowResult: state.workflowResult,
672 - });
694 + };

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

Modified
63 63 - schema-declared step fields and types are available through the active tool contract.
64 64 - `summary` is rendered on tool and overlay agent rows.
65 -- `prompt` is the exact resolved child instruction.
65 +- `prompt` is the child assignment body before Ultra adds runtime identity and provenance markup.
66 66 - model, tools, thinking-level, dynamic-extension, and output-schema behavior below describes runtime semantics not captured by field shape alone.
67 67 - use the same interpolation grammar as `prompt` so fan-out rows can identify their item.
68 68 - summary interpolation renders objects as short labels and arrays as counts; prompts retain compact JSON.
69 -- the overlay shows the exact resolved `prompt` as the first user message in that agent's transcript.
69 +- Ultra wraps every fresh assignment with workflow, phase, and `phase#index` identity.
70 +- prior-agent outputs inserted through interpolation are quoted with immediate producer identity and the producer's resolved task summary.
71 +- workflow arguments, literal items, failure records, and operator steering are not attributed to sub-agents.
72 +- workflow authors must not add manual identity or provenance wrappers.
73 +- the overlay shows the exact delivered envelope as the first user message in that agent's transcript.
70 74 - normal child context-file loading is enabled; children do not inherit the parent conversation.
71 75 - prompts must supply the task context, constraints, instruction paths, evidence, and authority boundaries each child needs.
72 76 - see [child context mechanics](../ultra-authoring/SKILL.md#give-children-context).

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

Modified
38 38 and authority boundaries it needs.
39 39 normal child context-file loading remains enabled, but it does not replace that
40 40 prompt-specific context.
41 +Ultra automatically wraps fresh assignments with workflow, phase, and agent identity.
42 +prior-agent outputs inserted through interpolation are automatically quoted with
43 +immediate producer identity and task summary.
44 +do not add manual agent identity or provenance wrappers to workflow prompts.
42 46 ## connect phases

extensions/ultra/runner.ts

Modified
30 30 ToolDefinition,
31 31 } from "@earendil-works/pi-coding-agent";
32 32 import type { ActionSummarizer } from "./action-summarizer.ts";
33 +import { resumePrompt } from "./agent-prompt.ts";
33 34 import type {
34 35 DynamicExtensionResolver,
35 36 ResolvedDynamicExtension,
553 554 unsubscribe = observeToolSession(session, opts, meta, state, step.summary);
554 555 return await promptAgentSession(
555 556 session,
556 - child.resumed ? RESUME_STEP_PROMPT : step.prompt,
557 + child.resumed
558 + ? resumePrompt(opts.agentId, opts.phase, RESUME_STEP_PROMPT)
559 + : step.prompt,
557 560 opts.maxRetries,
558 561 opts.signal,