@nredd/pi-subagents 0.22.0-nredd.8 → 0.22.0-nredd.9

package/src/ui/workflow-dialog.ts

@@ -61,12 +61,11 @@ import {
   type WorkflowDisplayState,
   type WorkflowEntry,
 } from "../workflow/progress.js";
-import { SPINNER, type Theme } from "./agent-widget.js";
-import { fallbackFlagText, hasFallback } from "./fallback-flag.js";
+import { formatCompactTokens, SPINNER, type Theme } from "./agent-widget.js";
+import { boundedWrappedRows, fallbackFlagText, hasFallback, withLeadingFlag } from "./fallback-flag.js";
 import {
   ASCII_GLYPHS,
   clampLine,
-  formatCompactTokens,
   formatModel,
   formatThinking,
   REPLAYED_ANNOTATION,
@@ -105,6 +104,8 @@ export const MIN_PANE_BODY_ROWS = 6;
 export const PROMPT_COLLAPSED_LINES = 4;
 /** Spinner cadence. Unlike the card's 1s header tick, this row really animates. */
 export const WORKFLOW_DIALOG_SPINNER_MS = 80;
+/** Maximum physical detail rows a fallback note may occupy. */
+const MODEL_NOTE_ROWS = 4;
 
 /* ------------------------------------------------------------------------- *
  * Glyphs
@@ -459,12 +460,6 @@ export function leftPaneWidth(width: number): number {
   return Math.max(1, Math.min(LEFT_PANE_WIDTH, Math.floor(available / 3), available - 1));
 }
 
-/** Fill a title out to the cell width with rule, so the corners stay put. */
-function padTitle(line: WorkflowCardLine, width: number, horizontal: string): WorkflowCardLine {
-  const gap = Math.max(0, width - lineWidth(line));
-  return gap > 0 ? [...line, { text: horizontal.repeat(gap), color: "dim" }] : line;
-}
-
 /** One pane row, padded to exactly `width` so the frame stays vertical. */
 function padCell(line: WorkflowCardLine, width: number): WorkflowCardLine {
   const clamped = clampLine(line, width);
@@ -519,9 +514,9 @@ function paneFrame(options: {
   const lines: WorkflowCardLine[] = [];
   lines.push([
     { text: box.topLeft, color: "dim" },
-    ...padTitle(frameTitle(options.leftTitle, left, glyphs), left, box.horizontal),
+    ...frameTitle(options.leftTitle, left, glyphs),
     { text: box.topTee, color: "dim" },
-    ...padTitle(frameTitle(options.rightTitle, right, glyphs), right, box.horizontal),
+    ...frameTitle(options.rightTitle, right, glyphs),
     { text: box.topRight, color: "dim" },
   ]);
 
@@ -638,18 +633,33 @@ function agentRow(options: {
 }): WorkflowCardLine {
   const { entry, selected, glyphs, width } = options;
   const display = displayState(entry, options.workflowActive);
-  const head: WorkflowCardLine = [
+  const prefix: WorkflowCardLine = [
     { text: " " },
     { text: selected ? glyphs.pointer : " ", color: "accent" },
     { text: " " },
     dialogRowGlyph(display, glyphs, options.spinnerFrame),
     { text: " " },
-    // Leading, ahead of the label, in both pane modes: the row clamps from the right.
-    ...(entry.modelTier || hasFallback(entry) ? [{ text: `${fallbackFlagText(1, entry)} `, color: hasFallback(entry) ? "warning" as const : "dim" as const }] : []),
+  ];
+  const flag = entry.modelTier || hasFallback(entry) ? fallbackFlagText(1, entry) : "";
+  const flagColor = hasFallback(entry) ? "warning" as const : "dim" as const;
+  // The narrow pane holds the label and nothing else; reserve its status prefix,
+  // then let the shared flag degrade rather than clipping it to `[fal…`.
+  if (options.compact && flag) {
+    const flagWidth = Math.max(0, width - lineWidth(prefix));
+    const compactFlag = withLeadingFlag("", flag, "", flagWidth);
+    const labelWidth = Math.max(0, flagWidth - visibleWidth(compactFlag) - 1);
+    const label = truncateToWidth(entry.label, labelWidth, "");
+    return [
+      ...prefix,
+      { text: compactFlag, color: flagColor },
+      ...(label ? [{ text: ` ${label}`, color: selected ? "accent" as const : undefined }] : []),
+    ];
+  }
+  const head: WorkflowCardLine = [
+    ...prefix,
+    ...(flag ? [{ text: `${flag} `, color: flagColor }] : []),
     { text: entry.label, color: selected ? "accent" : undefined },
   ];
-  // The narrow pane holds the label and nothing else; there is no room for a
-  // stat tail, and clamping one would just spend columns on a truncated word.
   if (options.compact) return clampLine(head, width);
 
   const model = formatModel(entry);
@@ -800,9 +810,12 @@ export function layoutWorkflowDialog(input: WorkflowDialogInput): WorkflowCardLi
       detailRows.push(clampLine([{ text: ` ${stats.join(" · ")}`, color: "dim" }], rightWidth));
     }
     // A substituted model is never cosmetic: name the failed input and what ran.
-    // Wrapped, not clamped: this is the one place the full note is readable.
+    // Bound physical rows, not text width: a configured value can contain
+    // newlines, each of which otherwise displaces the final diagnosis below the
+    // pane's fixed row budget.
     if (entry.modelNote) {
-      for (const line of wrapTextWithAnsi(entry.modelNote, Math.max(1, rightWidth - 1))) {
+      const noteWidth = Math.max(1, rightWidth - 1);
+      for (const line of boundedWrappedRows(entry.modelNote, noteWidth, MODEL_NOTE_ROWS, glyphs.ellipsis)) {
         detailRows.push(clampLine([{ text: ` ${line}`, color: "warning" }], rightWidth));
       }
     }

package/src/workflow/host.ts

@@ -167,10 +167,6 @@ function toSpawnResult(record: AgentRecord, opts: { resumed?: boolean } = {}): W
   return { ...common, ...modelNote, ok: false, error: `${lead}${record.error ?? `Agent ${record.status}.`}` };
 }
 
-/** Shell used to run a `gate` command, mirroring how a user would type it. */
-const GATE_SHELL: readonly [string, string] =
-  process.platform === "win32" ? ["cmd", "/c"] : ["sh", "-c"];
-
 export function createWorkflowHost(deps: WorkflowHostOptions): WorkflowHost {
   const { pi, ctx, manager } = deps;
   /** Runtime agent id → the manager record it spawned. Never pruned mid-run. */
@@ -189,7 +185,10 @@ export function createWorkflowHost(deps: WorkflowHostOptions): WorkflowHost {
    * decided from one behaviour, whichever route the command took.
    */
   async function executeGate(command: string, cwd: string): Promise<WorkflowGateResult> {
-    const result = await pi.exec(GATE_SHELL[0], [GATE_SHELL[1], command], {
+    // The shell a user would type the command into. Read per call rather than
+    // at import, so the choice follows the platform the gate actually runs on.
+    const [shell, flag] = process.platform === "win32" ? ["cmd", "/c"] : ["sh", "-c"];
+    const result = await pi.exec(shell, [flag, command], {
       cwd,
       timeout: deps.gateTimeoutMs ?? DEFAULT_GATE_TIMEOUT_MS,
       ...(deps.signal !== undefined ? { signal: deps.signal } : {}),

package/src/workflow/meta.ts

@@ -38,6 +38,8 @@ export interface WorkflowMeta {
 
 export interface MetaExtraction {
   meta: WorkflowMeta;
+  /** Byte offset immediately after the validated meta object literal. */
+  metaEnd: number;
   /**
    * The script with the leading `export ` stripped, so `const meta = {...}`
    * compiles inside the vm. Byte offsets after the keyword are untouched, which
@@ -175,8 +177,9 @@ function scanObjectLiteral(source: string, open: number): ScanResult {
  */
 function isRegexPosition(source: string, i: number): boolean {
   let j = i - 1;
-  while (j >= 0 && /\s/.test(source[j])) j--;
-  if (j < 0) return true;
+  // Never runs off the front: the scan starts at the literal's `{`, so the
+  // walk back always stops on it or something after it.
+  while (/\s/.test(source[j])) j--;
   const prev = source[j];
   // Identifier/number/closer before `/` means division.
   return !/[\w$)\]]/.test(prev);
@@ -289,7 +292,7 @@ export function extractMeta(source: string): MetaExtraction {
   const exportAt = source.indexOf("export", declaration.index);
   const body = `${source.slice(0, exportAt)}${" ".repeat(6)}${source.slice(exportAt + 6)}`;
 
-  return { meta, body };
+  return { meta, metaEnd: close, body };
 }
 
 /**
@@ -309,7 +312,7 @@ export function workflowCallName(args: { script?: string; scriptPath?: string; n
   if (source === undefined || source === "") {
     // A path-only call would need a synchronous file read per rebuild to do
     // better than this, and the file name is what the author will recognize.
-    if (args.scriptPath !== undefined) return args.scriptPath.split(/[/\\]/).pop() ?? "workflow";
+    if (args.scriptPath !== undefined) return args.scriptPath.replace(/^[\s\S]*[/\\]/, "");
     // A saved workflow is already named by the caller; no read needed at all.
     return args.name !== undefined && args.name !== "" ? args.name : "workflow";
   }

package/src/workflow/progress.ts

@@ -514,11 +514,12 @@ export function gerund(word: string): string {
 
   // Short consonant-vowel-consonant words double the final consonant: run →
   // running. `w`, `x` and `y` never double.
-  const last = lower.at(-1) ?? "";
+  // GERUND_CANDIDATE guarantees at least three letters, so every index exists.
+  const last = lower[lower.length - 1];
   if (
     lower.length <= 4 &&
-    !VOWELS.includes(lower.at(-3) ?? "") &&
-    VOWELS.includes(lower.at(-2) ?? "") &&
+    !VOWELS.includes(lower[lower.length - 3]) &&
+    VOWELS.includes(lower[lower.length - 2]) &&
     !VOWELS.includes(last) &&
     !"wxy".includes(last)
   ) {

package/src/workflow/runtime.ts

@@ -153,8 +153,8 @@ export interface WorkflowSpawnResult {
    * verifies the wrong working copy. Left unset, a gate runs wherever the host
    * runs commands by default.
    *
-   * Usually unset for a worktree child even so: the copy is removed during the
-   * child's own settle, so it no longer exists by the time this is read. That
+   * Usually unset for a worktree child even so: the copy is normally removed during
+   * the child's own settle, so it no longer exists by the time this is read. That
    * is what {@link gate} is for.
    */
   cwd?: string;
@@ -282,6 +282,19 @@ export interface RunWorkflowOptions {
   signal?: AbortSignal;
   /** Fired per batch, not per entry — see the worker's progress batching. */
   onProgress?(entries: readonly WorkflowEntry[]): void;
+  /**
+   * Receives optional Istanbul counters authored inside a workflow VM.
+   *
+   * The runtime itself never instruments scripts. Test producers may pass
+   * instrumented source and merge these counters into their own collector,
+   * retaining worker/VM execution rather than measuring a substitute runner.
+   */
+  onScriptCoverage?(coverage: unknown): void;
+  /**
+   * Trusted caller-side transform applied after the workflow's metadata has
+   * passed validation and before its body enters the worker VM.
+   */
+  transformScriptBody?(input: { script: string; body: string }): string;
   concurrency?: number;
   agentCap?: number;
   itemCap?: number;
@@ -357,7 +370,8 @@ function walk(value: unknown, path: string, seen: Set<object>): void {
   if (kind === "bigint") throw boundaryError("a BigInt", path);
   if (kind === "symbol") throw boundaryError("a symbol", path);
   if (kind === "function") throw boundaryError("a function", path);
-  if (kind !== "object") throw boundaryError(`a ${kind}`, path);
+  // Every other `typeof` result is handled above; a new one fails `tsc` here.
+  kind satisfies "object";
 
   const object = value as object;
   if (seen.has(object)) throw boundaryError("a circular structure", path);
@@ -457,7 +471,7 @@ interface AgentCallPayload {
 type WorkerMessage =
   | { type: "call"; callId: number; method: string; payload: AgentCallPayload }
   | { type: "progress"; entries: WorkflowEntry[] }
-  | { type: "complete"; resultJson?: string }
+  | { type: "complete"; resultJson?: string; coverage?: unknown }
   | { type: "error"; message: string; stack?: string };
 
 /** Everything below 0x20 except tab, newline and carriage return, plus DEL. */
@@ -595,7 +609,8 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
 
   assertBoundarySafe(options.args, "args");
 
-  const { meta, body } = validateScript(script);
+  const { meta, body: validatedBody } = validateScript(script);
+  const body = options.transformScriptBody?.({ script, body: validatedBody }) ?? validatedBody;
   const agentCap = options.agentCap ?? WORKFLOW_AGENT_CAP;
   const itemCap = options.itemCap ?? WORKFLOW_ITEM_CAP;
   const semaphore = new Semaphore(options.concurrency ?? workflowConcurrency());
@@ -732,12 +747,12 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
       argsJson: options.args === undefined ? undefined : JSON.stringify(options.args),
       itemCap,
       nestedCap: options.nestedCap ?? WORKFLOW_NESTED_CAP,
+      collectCoverage: options.onScriptCoverage !== undefined,
     },
   });
 
   return await new Promise<WorkflowRunResult>(resolve => {
     const emit = (entries: WorkflowEntry[]) => {
-      if (entries.length === 0) return;
       progress.push(...entries);
       options.onProgress?.(entries);
     };
@@ -1174,7 +1189,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
         respond(callId, true, {
           name: child.meta.name,
           metaJson: JSON.stringify(child.meta),
-          body: child.body,
+          body: options.transformScriptBody?.({ script: source.script, body: child.body }) ?? child.body,
         });
       } catch (error) {
         respond(callId, false, undefined, error instanceof Error ? error.message : String(error));
@@ -1199,6 +1214,7 @@ export async function runWorkflow(options: RunWorkflowOptions): Promise<Workflow
           void handleAgent(message.callId, message.payload as AgentCallPayload);
           break;
         case "complete": {
+          if (message.coverage !== undefined) options.onScriptCoverage?.(message.coverage);
           // The script is done, so every launch it made should have been
           // answered by now — a response is sent before the worker can post
           // this, so anything still open was never awaited. finish() aborts

package/src/workflow/saved.ts

@@ -162,10 +162,8 @@ export function resolveWorkflowSource(
     try {
       return { ok: true, script: readFileSync(resolved, "utf-8"), path: resolved };
     } catch (err) {
-      return {
-        ok: false,
-        message: `Could not read workflow script "${resolved}": ${err instanceof Error ? err.message : String(err)}`,
-      };
+      // `readFileSync` only ever throws Node's own `Error`s.
+      return { ok: false, message: `Could not read workflow script "${resolved}": ${(err as Error).message}` };
     }
   }
   const name = ref.name?.trim();

package/src/workflow/task.ts

@@ -78,6 +78,8 @@ export interface WorkflowTask {
   logs: string[];
 
   abortController: AbortController;
+  /** Set when the parent stopped the run with `stop_subagent`; unset for a human stop. */
+  stoppedBy?: "parent";
   startTime: number;
   endTime?: number;
   /** Excluded from the elapsed clock the header shows. */
@@ -184,19 +186,22 @@ export function resumeWorkflowTask(task: WorkflowTask, now = Date.now()): boolea
   if (task.status !== "paused" || task.control === undefined) return false;
   task.control.resume();
   task.status = "running";
-  task.totalPausedMs = (task.totalPausedMs ?? 0) + Math.max(0, now - (task.pausedAt ?? now));
-  task.pausedAt = undefined;
+  bankPause(task, now);
   return true;
 }
 
+/** Close out an open pause into `totalPausedMs`; a no-op when the run is not held. */
+function bankPause(task: WorkflowTask, now: number): void {
+  if (task.pausedAt === undefined) return;
+  task.totalPausedMs += Math.max(0, now - task.pausedAt);
+  task.pausedAt = undefined;
+}
+
 /** Settle a task from the run's own result. */
 export function completeWorkflowTask(task: WorkflowTask, result: WorkflowRunResult): void {
   // Banked before the status moves off "paused": a run that finished while held
   // still spent that time held, and the elapsed figure has to say so.
-  if (task.pausedAt !== undefined) {
-    task.totalPausedMs = (task.totalPausedMs ?? 0) + Math.max(0, Date.now() - task.pausedAt);
-    task.pausedAt = undefined;
-  }
+  bankPause(task, Date.now());
   // Nothing left to control, and holding the handle would let the dialog offer
   // pause on a run that has already stopped.
   task.control = undefined;
@@ -293,7 +298,7 @@ export function formatWorkflowNotification(task: WorkflowTask, now = Date.now())
   const totals = stats(task.workflowProgress, task.agentCount);
   const status =
     task.status === "completed" ? "Done"
-    : task.status === "killed" ? "Stopped"
+    : task.status === "killed" ? (task.stoppedBy === "parent" ? "Stopped by the parent with stop_subagent" : "Stopped")
     : `Error: ${task.error ?? "unknown"}`;
   const result = workflowResultText(task);
   return [

package/src/workflow/tool-description.ts

@@ -19,7 +19,7 @@
  *   - `budget.total` is always null; pi has no token-target directive.
  *   - `parallel` propagates a fatal run error instead of folding it to null.
  *   - `effort` inherits the agent definition's level, then the parent's.
- *   - `isolation` removes the worktree on settle, changes kept on a branch.
+ *   - `isolation` removes the worktree on settle (kept if cleanup fails), changes kept on a branch.
  * Additions with no upstream counterpart: `gate`, `resume`, `effort: "minimal"`,
  * the saved-workflow directories, and the reject-unknown-options guarantee.
  *
@@ -77,7 +77,7 @@ Every script must begin with \`export const meta = {...}\`:
 The \`meta\` object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation. Required fields: \`name\`, \`description\`. Optional: \`whenToUse\` (shown in the workflow list), \`phases\`. Use the SAME phase titles in meta.phases as in phase() calls — titles are matched exactly; a phase() call with no matching meta entry just gets its own progress group. Add \`model\` to a phase entry when that phase uses a specific model override.
 
 Script body hooks:
-- agent(prompt: string, opts?: {label?: string, phase?: string, schema?: object, model?: string, effort?: string, isolation?: 'worktree', agentType?: string, gate?: string, resume?: string}): Promise<any> — spawn a subagent. Without schema, returns its final text as a string. With schema (a JSON Schema), the subagent is given a StructuredOutput tool built from it and agent() returns the validated object — no parsing needed. A payload that does not match is rejected back to the child, which corrects it; a child that never answers through the tool gets one more prompt and then fails, so the call returns null — filter after every schema stage. Returns null if the user skips the agent mid-run or the subagent dies on a terminal API error after retries (filter with .filter(Boolean)). opts.label overrides the display label. opts.phase explicitly assigns this agent to a progress group (use this inside pipeline()/parallel() stages to avoid races on the global phase() state — same phase string → same group box). opts.model overrides the model for this agent call. Default to omitting it — the agent inherits the main-loop model (the resolved session model), which is almost always correct. Only set it when you're highly confident a different tier fits the task; when unsure, omit. opts.effort overrides the reasoning effort for this agent call ('minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max') — omit to inherit the agent definition's own level, then the parent's; use 'low' for cheap mechanical stages and higher tiers only for the hardest verify/judge stages. opts.isolation: 'worktree' runs the agent in a fresh git worktree — EXPENSIVE (setup time + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is removed when the agent settles, its changes preserved on a branch. opts.gate: '<command>' runs a shell command after the agent finishes and requires it to pass — a non-zero exit marks the agent failed and the command's output becomes the error; prefer gate: 'npm test' over asking another agent whether the code looks right. opts.resume: '<label>' continues the child that ran under that label instead of starting fresh, so an iterative loop keeps its context — it cannot be combined with agentType, model, effort, isolation, gate or schema. opts.agentType uses a custom subagent type instead of the default workflow subagent — resolved from the same registry as the Agent tool; composes with schema. Available types:
+- agent(prompt: string, opts?: {label?: string, phase?: string, schema?: object, model?: string, effort?: string, isolation?: 'worktree', agentType?: string, gate?: string, resume?: string}): Promise<any> — spawn a subagent. Without schema, returns its final text as a string. With schema (a JSON Schema), the subagent is given a StructuredOutput tool built from it and agent() returns the validated object — no parsing needed. A payload that does not match is rejected back to the child, which corrects it; a child that never answers through the tool gets one more prompt and then fails, so the call returns null — filter after every schema stage. Returns null if the user skips the agent mid-run or the subagent dies on a terminal API error after retries (filter with .filter(Boolean)). opts.label overrides the display label. opts.phase explicitly assigns this agent to a progress group (use this inside pipeline()/parallel() stages to avoid races on the global phase() state — same phase string → same group box). opts.model overrides the model for this agent call. Default to omitting it so the configured selection policy applies: agentModels for the type, then agentModels["*"], then the agent definition, then the parent model. Only set it when you're highly confident a different tier fits the task; when unsure, omit. opts.effort overrides the reasoning effort for this agent call ('minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max') — omit to inherit the agent definition's own level, then the parent's; use 'low' for cheap mechanical stages and higher tiers only for the hardest verify/judge stages. opts.isolation: 'worktree' runs the agent in a fresh git worktree — EXPENSIVE (setup time + disk per agent), use ONLY when agents mutate files in parallel and would otherwise conflict; the worktree is removed when the agent settles, its changes preserved on a branch; if cleanup fails the worktree is kept and the agent errors. opts.gate: '<command>' runs a shell command after the agent finishes and requires it to pass — a non-zero exit marks the agent failed, returns null to the script, and records the command output on the workflow agent error; prefer gate: 'npm test' over asking another agent whether the code looks right. opts.resume: '<label>' continues the child that ran under that label instead of starting fresh, so an iterative loop keeps its context — it cannot be combined with agentType, model, effort, isolation, gate or schema. opts.agentType uses a custom subagent type instead of the default workflow subagent — resolved from the same registry as the Agent tool; composes with schema. Available types:
 {{typeList}}
 - pipeline(items, stage1, stage2, ...): Promise<any[]> — run each item through all stages independently, NO barrier between stages. Item A can be in stage 3 while item B is still in stage 1. This is the DEFAULT for multi-stage work. Wall-clock = slowest single-item chain, not sum-of-slowest-per-stage. Every stage callback receives (prevResult, originalItem, index) — use originalItem/index in later stages to label work without threading context through stage 1's return value. A stage that throws drops that item to \`null\` and skips its remaining stages.
 - parallel(thunks: Array<() => Promise<any>>): Promise<any[]> — run tasks concurrently. This is a BARRIER: awaits all thunks before returning. A thunk that throws (or whose agent errors) resolves to \`null\` in the result array, so \`.filter(Boolean)\` before using the results; only a fatal run error — a cap breach, or a nested workflow that could not load — propagates instead of being folded into a null. Use ONLY when you genuinely need all results together.

package/src/workflow/worker-source.ts

@@ -863,10 +863,14 @@ async function main() {
   const value = await run(rootScope.agent, rootScope.phase, rootScope.log, rootScope.workflow, rootScope.console, sandbox.args);
   checkBoundary(value, "the workflow result");
   flushProgress();
-  port.postMessage({
+  const result = {
     type: "complete",
     resultJson: value === undefined ? undefined : JSON.stringify(value),
-  });
+  };
+  if (workerData.collectCoverage) {
+    result.coverage = vm.runInContext("globalThis.__coverage__", context);
+  }
+  port.postMessage(result);
 }
 
 /** Serialize diagnostics only: keep realm errors untouched and bound cause traversal/output. */