@tt-a1i/openpi 0.1.0 → 0.1.1

package/extensions/workflows/invocation-ledger.ts

@@ -0,0 +1,362 @@
+export interface InvocationIdentity {
+  readonly runId: string;
+  readonly callIndex: number;
+}
+
+export type InvocationIntentState = "requested";
+export type InvocationAdmissionState =
+  "pending" | "claimed" | "replayed" | "rejected";
+export type InvocationExecutionState =
+  "pending" | "running" | "settled" | "uncertain";
+export type InvocationOutcome = "success" | "error" | "uncertain";
+
+/**
+ * Three-plane durable lifecycle for one workflow call.
+ *
+ * Intent says what the script requested, admission says whether the host
+ * accepted or replayed it, and execution says what the child runtime actually
+ * proved. Keeping them separate prevents a persisted `running` label from
+ * pretending that an interrupted side effect is known to have failed.
+ */
+export interface InvocationRecord {
+  readonly identity: InvocationIdentity;
+  readonly intentState: InvocationIntentState;
+  readonly admissionState: InvocationAdmissionState;
+  readonly executionState: InvocationExecutionState;
+  readonly outcome?: InvocationOutcome;
+  readonly requestedAt: number;
+  readonly claimedAt?: number;
+  readonly runningAt?: number;
+  readonly terminalAt?: number;
+}
+
+export type InvocationTransition =
+  | { readonly status: "claimed"; readonly at: number }
+  | { readonly status: "running"; readonly at: number }
+  | {
+      readonly status: "settled";
+      readonly outcome: "success" | "error";
+      readonly at: number;
+    }
+  | { readonly status: "replayed"; readonly at: number }
+  | { readonly status: "rejected"; readonly at: number };
+
+const ADMISSION_STATES: readonly InvocationAdmissionState[] = [
+  "pending",
+  "claimed",
+  "replayed",
+  "rejected",
+];
+const EXECUTION_STATES: readonly InvocationExecutionState[] = [
+  "pending",
+  "running",
+  "settled",
+  "uncertain",
+];
+
+function assertIdentity(identity: InvocationIdentity) {
+  if (typeof identity.runId !== "string" || identity.runId.trim() === "") {
+    throw new Error("runId must be a nonblank string");
+  }
+  if (!Number.isSafeInteger(identity.callIndex) || identity.callIndex <= 0) {
+    throw new Error("callIndex must be a positive safe integer");
+  }
+}
+
+function assertFinite(value: number | undefined, name: string) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${name} must be finite`);
+  }
+  return value;
+}
+
+function immutableSnapshot(record: InvocationRecord) {
+  return Object.freeze({
+    ...record,
+    identity: Object.freeze({ ...record.identity }),
+  });
+}
+
+function lifecycleLabel(record: InvocationRecord) {
+  if (record.admissionState === "replayed") return "replayed";
+  if (record.admissionState === "rejected") return "rejected";
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    return "settled";
+  }
+  if (record.executionState === "running") return "running";
+  if (record.admissionState === "claimed") return "claimed";
+  return "requested";
+}
+
+function assertRecord(record: InvocationRecord) {
+  assertIdentity(record.identity);
+  assertFinite(record.requestedAt, "requestedAt");
+  if (record.intentState !== "requested") {
+    throw new Error("Invalid invocation intent state");
+  }
+  if (!ADMISSION_STATES.includes(record.admissionState)) {
+    throw new Error("Invalid invocation admission state");
+  }
+  if (!EXECUTION_STATES.includes(record.executionState)) {
+    throw new Error("Invalid invocation execution state");
+  }
+  if (record.admissionState === "claimed") {
+    assertFinite(record.claimedAt, "claimedAt");
+  }
+  if (record.executionState === "running") {
+    assertFinite(record.runningAt, "runningAt");
+  }
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    assertFinite(record.terminalAt, "terminalAt");
+  }
+  if (
+    record.admissionState === "replayed" &&
+    (record.executionState !== "settled" || record.outcome !== "success")
+  ) {
+    throw new Error("Invalid replayed invocation state");
+  }
+  if (
+    record.admissionState === "rejected" &&
+    (record.executionState !== "settled" || record.outcome !== "error")
+  ) {
+    throw new Error("Invalid rejected invocation state");
+  }
+  if (
+    record.admissionState === "pending" &&
+    record.executionState !== "pending" &&
+    record.executionState !== "uncertain"
+  ) {
+    throw new Error("Invalid pending invocation state");
+  }
+  if (
+    record.executionState === "settled" &&
+    record.outcome !== "success" &&
+    record.outcome !== "error"
+  ) {
+    throw new Error("Settled invocation requires a success or error outcome");
+  }
+  if (record.executionState === "uncertain" && record.outcome !== "uncertain") {
+    throw new Error("Uncertain invocation requires an uncertain outcome");
+  }
+  if (
+    (record.executionState === "pending" ||
+      record.executionState === "running") &&
+    record.outcome !== undefined
+  ) {
+    throw new Error("Nonterminal invocation cannot have an outcome");
+  }
+  if (
+    record.executionState !== "settled" &&
+    record.executionState !== "uncertain" &&
+    record.terminalAt !== undefined
+  ) {
+    throw new Error("Nonterminal invocation cannot have terminalAt");
+  }
+  if (record.admissionState !== "claimed" && record.claimedAt !== undefined) {
+    throw new Error("Only a claimed invocation can have claimedAt");
+  }
+  if (
+    record.runningAt !== undefined &&
+    (record.admissionState !== "claimed" ||
+      (record.executionState !== "running" &&
+        record.executionState !== "settled" &&
+        record.executionState !== "uncertain"))
+  ) {
+    throw new Error("Invalid runningAt for invocation state");
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "settled" &&
+    record.runningAt === undefined
+  ) {
+    throw new Error("A normally settled invocation requires runningAt");
+  }
+
+  const timestamps = [
+    ["requestedAt", record.requestedAt],
+    ["claimedAt", record.claimedAt],
+    ["runningAt", record.runningAt],
+    ["terminalAt", record.terminalAt],
+  ] as const;
+  let previous = record.requestedAt;
+  for (const [name, timestamp] of timestamps.slice(1)) {
+    if (timestamp === undefined) continue;
+    assertFinite(timestamp, name);
+    if (timestamp < previous) {
+      throw new Error(`${name} cannot precede an earlier lifecycle timestamp`);
+    }
+    previous = timestamp;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Decode untrusted persisted data without inventing missing lifecycle facts. */
+export function decodeInvocationRecord(value: unknown) {
+  if (!isRecord(value) || !isRecord(value.identity)) return undefined;
+  const candidate = value as unknown as InvocationRecord;
+  try {
+    assertRecord(candidate);
+    return immutableSnapshot(candidate);
+  } catch {
+    return undefined;
+  }
+}
+
+function currentTransitionTime(record: InvocationRecord) {
+  if (record.terminalAt !== undefined) {
+    return {
+      name: "terminalAt",
+      at: assertFinite(record.terminalAt, "terminalAt"),
+    };
+  }
+  if (record.runningAt !== undefined) {
+    return {
+      name: "runningAt",
+      at: assertFinite(record.runningAt, "runningAt"),
+    };
+  }
+  if (record.claimedAt !== undefined) {
+    return {
+      name: "claimedAt",
+      at: assertFinite(record.claimedAt, "claimedAt"),
+    };
+  }
+  return { name: "requestedAt", at: record.requestedAt };
+}
+
+function assertChronology(record: InvocationRecord, at: number) {
+  assertFinite(at, "at");
+  const current = currentTransitionTime(record);
+  if (at < current.at) {
+    throw new Error(`Transition time cannot precede ${current.name}`);
+  }
+}
+
+function isLegalTransition(
+  record: InvocationRecord,
+  next: InvocationTransition["status"],
+) {
+  if (
+    record.admissionState === "pending" &&
+    record.executionState === "pending"
+  ) {
+    return next === "claimed" || next === "replayed" || next === "rejected";
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "pending"
+  ) {
+    return next === "running";
+  }
+  if (
+    record.admissionState === "claimed" &&
+    record.executionState === "running"
+  ) {
+    return next === "settled";
+  }
+  return false;
+}
+
+/** Structured identity avoids ambiguous string concatenation of run and call. */
+export function createInvocationIdentity(runId: string, callIndex: number) {
+  const identity = { runId, callIndex };
+  assertIdentity(identity);
+  return Object.freeze(identity);
+}
+
+/** Start a call record without consulting a clock inside the ledger. */
+export function requestInvocation(identity: InvocationIdentity, at: number) {
+  assertIdentity(identity);
+  assertFinite(at, "at");
+  return immutableSnapshot({
+    identity,
+    intentState: "requested",
+    admissionState: "pending",
+    executionState: "pending",
+    requestedAt: at,
+  });
+}
+
+/** Apply one normal lifecycle or replay/rejection transition. */
+export function transitionInvocation(
+  record: InvocationRecord,
+  transition: InvocationTransition,
+) {
+  assertRecord(record);
+  if (!isLegalTransition(record, transition.status)) {
+    throw new Error(
+      `Illegal invocation transition: ${lifecycleLabel(record)} -> ${transition.status}`,
+    );
+  }
+  assertChronology(record, transition.at);
+
+  switch (transition.status) {
+    case "claimed":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "claimed",
+        claimedAt: transition.at,
+      });
+    case "running":
+      return immutableSnapshot({
+        ...record,
+        executionState: "running",
+        runningAt: transition.at,
+      });
+    case "settled":
+      return immutableSnapshot({
+        ...record,
+        executionState: "settled",
+        outcome: transition.outcome,
+        terminalAt: transition.at,
+      });
+    case "replayed":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "replayed",
+        executionState: "settled",
+        outcome: "success",
+        terminalAt: transition.at,
+      });
+    case "rejected":
+      return immutableSnapshot({
+        ...record,
+        admissionState: "rejected",
+        executionState: "settled",
+        outcome: "error",
+        terminalAt: transition.at,
+      });
+  }
+}
+
+/** Interrupt recovery is conservative: execution may have happened. */
+export function classifyInterruptedInvocation(
+  record: InvocationRecord,
+  at: number,
+) {
+  assertRecord(record);
+  if (
+    record.executionState === "settled" ||
+    record.executionState === "uncertain"
+  ) {
+    throw new Error(
+      `Cannot classify terminal invocation ${lifecycleLabel(record)} as uncertain`,
+    );
+  }
+  assertChronology(record, at);
+  return immutableSnapshot({
+    ...record,
+    executionState: "uncertain",
+    outcome: "uncertain",
+    terminalAt: at,
+  });
+}

package/extensions/workflows/model.ts

@@ -12,6 +12,12 @@ import { formatContextUtilization } from "../shared/context-utilization.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import type { WorktreeCleanup } from "../shared/worktree.ts";
 import type { AcceptanceLedger } from "./acceptance.ts";
+import {
+  projectWorkflowGraph,
+  type WorkflowGraphProjection,
+  type WorkflowGraphRecord,
+} from "./graph-projection.ts";
+import type { InvocationRecord } from "./invocation-ledger.ts";
 import { safeStringify } from "./serialization.ts";
 
 export type Theme = ExtensionContext["ui"]["theme"];
@@ -65,6 +71,15 @@ export interface TranscriptEntry {
 
 export interface AgentRecord {
   index: number;
+  /** Stable identity and independent intent/admission/execution status planes. */
+  callId?: string;
+  invocation?: InvocationRecord;
+  /** Ephemeral same-run child Session reused for this logical operator. */
+  operatorKey?: string;
+  /** Explicit result-reference dependencies used by the derived graph. */
+  inputCallIds?: string[];
+  /** Opaque same-run reference returned to the workflow script. */
+  resultRef?: string;
   label: string;
   phase?: string;
   state: AgentState;
@@ -122,9 +137,46 @@ export interface WorkflowDetails {
   resumedFrom?: string;
   /** Why a requested resume produced no cache, for an honest result message. */
   resumeNote?: string;
+  /** Read-only lineage projection; never execution or admission authority. */
+  graph?: WorkflowGraphProjection;
   error?: string;
 }
 
+export function workflowGraphRecords(
+  agents: readonly AgentRecord[],
+): WorkflowGraphRecord[] {
+  return agents.flatMap((agent) =>
+    agent.callId
+      ? [
+          {
+            callId: agent.callId,
+            index: agent.index,
+            label: agent.label,
+            state: agent.state,
+            ...(agent.invocation
+              ? {
+                  admissionState: agent.invocation.admissionState,
+                  executionState: agent.invocation.executionState,
+                }
+              : {}),
+            ...(agent.operatorKey ? { operatorKey: agent.operatorKey } : {}),
+            ...(agent.inputCallIds
+              ? { inputCallIds: [...agent.inputCallIds] }
+              : {}),
+            ...(agent.resultRef ? { resultRef: agent.resultRef } : {}),
+          },
+        ]
+      : [],
+  );
+}
+
+/** Refresh the descriptive graph without granting it scheduling authority. */
+export function refreshWorkflowGraph(details: WorkflowDetails) {
+  const records = workflowGraphRecords(details.agents);
+  details.graph = projectWorkflowGraph(records);
+  return details.graph;
+}
+
 export const MAX_LOG_ENTRIES = 100;
 export const MAX_LOG_TEXT = 300;
 

package/extensions/workflows/operator.ts

@@ -0,0 +1,131 @@
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+
+export interface WorkflowOperatorActivation {
+  key: string;
+  fingerprint: string;
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+type OperatorEntry = {
+  fingerprint: string;
+  cwd: string;
+  sessionManager: SessionManager;
+  tail: Promise<void>;
+};
+
+export function normalizeWorkflowOperatorKey(key: string) {
+  if (typeof key !== "string" || !/^[A-Za-z0-9._:-]{1,80}$/.test(key)) {
+    throw new Error(
+      "Workflow operator key must be 1-80 ASCII letters, digits, or ._:- characters",
+    );
+  }
+  return key;
+}
+
+function abortError(signal: AbortSignal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error("Workflow operator activation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function invokeAfter<T>(
+  turn: Promise<void>,
+  signal: AbortSignal | undefined,
+  invoke: () => T | PromiseLike<T>,
+) {
+  if (!signal) return turn.then(invoke);
+  if (signal.aborted) return Promise.reject(abortError(signal));
+
+  return new Promise<T>((resolve, reject) => {
+    let waiting = true;
+    const onAbort = () => {
+      if (!waiting) return;
+      waiting = false;
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    void turn.then(
+      () => {
+        if (!waiting) return;
+        if (signal.aborted) {
+          onAbort();
+          return;
+        }
+        waiting = false;
+        signal.removeEventListener("abort", onAbort);
+        try {
+          Promise.resolve(invoke()).then(resolve, reject);
+        } catch (error) {
+          reject(error);
+        }
+      },
+      (error) => {
+        if (!waiting) return;
+        waiting = false;
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Per-run, in-process operator sessions. Nothing in this registry is persisted
+ * or shared with another process.
+ */
+export class WorkflowOperatorRegistry {
+  private readonly operators = new Map<string, OperatorEntry>();
+  private closed = false;
+  private closePromise?: Promise<void>;
+
+  activate<T>(
+    activation: WorkflowOperatorActivation,
+    invoke: (sessionManager: SessionManager) => T | PromiseLike<T>,
+  ) {
+    if (this.closed) {
+      return Promise.reject(new Error("Workflow operator registry is closed"));
+    }
+
+    const key = normalizeWorkflowOperatorKey(activation.key);
+    let operator = this.operators.get(key);
+    if (!operator) {
+      operator = {
+        fingerprint: activation.fingerprint,
+        cwd: activation.cwd,
+        sessionManager: SessionManager.inMemory(activation.cwd),
+        tail: Promise.resolve(),
+      };
+      this.operators.set(key, operator);
+    } else if (
+      operator.fingerprint !== activation.fingerprint ||
+      operator.cwd !== activation.cwd
+    ) {
+      return Promise.reject(
+        new Error(`Workflow operator identity mismatch for "${key}"`),
+      );
+    }
+    const previous = operator.tail;
+    const result = invokeAfter(previous, activation.signal, () =>
+      invoke(operator.sessionManager),
+    );
+    operator.tail = Promise.allSettled([previous, result]).then(
+      () => undefined,
+    );
+    return result;
+  }
+
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closed = true;
+    const queues = [...this.operators.values()].map(
+      (operator) => operator.tail,
+    );
+    this.closePromise = Promise.allSettled(queues).then(() => {
+      this.operators.clear();
+    });
+    return this.closePromise;
+  }
+}

package/extensions/workflows/prompt.ts

@@ -50,27 +50,29 @@ export const WORKFLOW_TOOL_DESCRIPTION = [
   "• phase(title) — mark the current phase at runtime (use titles from meta.phases).",
   "• log(message) — emit one progress line to the user and to your own final report. This is the run's narrator: use it for anything the reader needs while the run is still going, or that the return value would not capture — round counts, how many agents were dropped, why a branch was skipped. Unlike phase(), it does not touch the phase list. Lines are one row each (newlines are flattened); the most recent 100 are kept and any earlier ones are reported as dropped.",
   "• usage() — read this run's cumulative token spend so far: { input, output, cacheRead, cacheWrite, total, cost, agents }. The reading refreshes as each agent settles, so evaluating it right after an `await` reflects that agent. `total` never decreases, but it is a LOWER BOUND rather than an exact figure: a child session that compacts drops the tokens of the messages it discarded. Use it to report or adapt cost — e.g. log a running total, or stop a discovery loop once the spend stops paying for itself — and expect a long run to have spent somewhat more than it says. It is a reading, not a limit: nothing is enforced for you.",
-  "• await agent(prompt, { agent_type?, label?, phase?, schema?, acceptance?, model?, provider?, effort?, isolation? }) — run ONE subagent in an isolated context and wait for it. `agent_type` applies the same named preset and enforced capabilities as subagent_spawn: specialized system prompt, tool allowlist, model assignment, and default effort. Prefer a matching type when one exists. Model precedence is explicit model/provider > type-file model > configured built-in role model > parent model; effort precedence is explicit effort > type default > parent effort. Omit `agent_type` for a general-purpose child. Always resolves to { ok, output, structured?, acceptance?, error? }. Check `ok` before using the result. When you pass a JSON `schema`, `structured` holds the validated object on success. Optional `acceptance: { criteria: [{ id, description, requiredEvidence? }] }` is explicit and adds no extra agent: the same structured result must include an evidence ledger; missing, malformed, or rejected criteria make `ok:false` while preserving output and ledger. Children receive normal built-ins and trust-appropriate extensions, settings, skills, and AGENTS.md context, but cannot recursively orchestrate or ask the user.",
+  "• await agent(prompt, { agent_type?, label?, phase?, schema?, acceptance?, model?, provider?, effort?, isolation?, operator?, inputs? }) — run ONE subagent and wait for it. `agent_type` applies the same named preset and enforced capabilities as subagent_spawn: specialized system prompt, tool allowlist, model assignment, and default effort. Prefer a matching type when one exists. Model precedence is explicit model/provider > type-file model > configured built-in role model > parent model; effort precedence is explicit effort > type default > parent effort. Omit `agent_type` for a general-purpose child. Always resolves to { ok, output, structured?, ref?, acceptance?, error? }. Check `ok` before using the result. A successful call's opaque result ref can be passed through `inputs: [previous.ref]` to hydrate bounded same-run handoffs as untrusted data and record explicit lineage. When you pass a JSON `schema`, `structured` holds the validated object on success. Optional `acceptance: { criteria: [{ id, description, requiredEvidence? }] }` is explicit and adds no extra agent: the same structured result must include an evidence ledger; missing, malformed, or rejected criteria make `ok:false` while preserving output and ledger. Children receive normal built-ins and trust-appropriate extensions, settings, skills, and AGENTS.md context, but cannot recursively orchestrate or ask the user.",
+  "• operator: 'name' reuses one in-memory child Session for serialized follow-up activations inside the same workflow run. Its model, role/tool surface, effort, structured mode, and cwd are frozen by the first activation. Operator calls cannot use per-call worktrees or result replay, and operator continuity is not a cross-restart guarantee.",
+  "• inputs: [resultRef, ...] accepts only opaque refs issued by successful calls in this same workflow run. The host injects at most 16 KiB per conclusion and 48 KiB total, marks it as data rather than instructions, and derives a read-only graph from those explicit refs. The graph is observability, never scheduling authority.",
   "• isolation: 'worktree' runs that one agent in its own git worktree on its own branch, instead of the shared working directory. Use it for any fan-out where agents WRITE — without it, concurrent agents share one checkout and one git index, so their edits and `git add`s silently overwrite each other. Tell such an agent to COMMIT its work: on completion the worktree directory is reclaimed and its branch is kept for you to merge (an empty branch is deleted; uncommitted changes keep the directory instead). The branch name comes back in the run artifacts. Costs a fresh checkout, needs a git repo, and starts without gitignored files, so leave it off for read-only agents.",
-  "• await parallel([() => agent(...), () => agent(...)], { concurrency? }) — run zero-argument agent thunks concurrently and return results in order. This is a BARRIER: nothing after it starts until every thunk settles. A thunk that throws settles to null (filter it out) rather than failing the whole batch, so one bad item never discards the others' results. The package default is 8 concurrent agents per workflow and can be changed with /my-pi-setup (hard maximum 64).",
+  "• await parallel([() => agent(...), () => agent(...)], { concurrency? }) — run zero-argument agent thunks concurrently and return results in order. This is a BARRIER: nothing after it starts until every thunk settles. A thunk that throws settles to null (filter it out) rather than failing the whole batch, so one bad item never discards the others' results. The package default is 8 concurrent agents per workflow and can be changed with /openpi-setup (hard maximum 64).",
   "• await pipeline(items, stage1, stage2, ...) — run each item through every stage independently, with NO barrier between stages: item A can be in stage 3 while item B is still in stage 1. Results come back in input order. Each stage receives (previousResult, originalItem, index), so a later stage can label its work without threading context through the earlier stage's return value. A stage that throws drops that item to null and skips its remaining stages, leaving siblings untouched.",
   "PREFER pipeline() for multi-stage work. parallel() forces every item to wait for the slowest one in each stage, so wall-clock becomes the sum of per-stage worst cases (max stage1 + max stage2) instead of the slowest single chain. The gap is widest when different items are slow in different stages; when one item is slowest everywhere it is the critical path either way. Reach for a barrier only when a stage genuinely needs cross-item context from ALL of the previous one: deduping or merging the full result set, exiting early when the total count is zero, or a prompt that compares one finding against the others. Needing to flatten/map/filter in between is NOT a reason — do that inside a pipeline stage.",
 
   "• args — the parsed value of the `args` tool parameter (or undefined).",
-  "Workflow JavaScript runs in a restricted, killable child with no imports, eval, timers, filesystem, network, or process APIs. The package default permits 128 agent calls per run and can be changed with /my-pi-setup (hard maximum 1024); there is no overall deadline. Each agent must receive its first assistant response event within 45 seconds so silent provider requests fail clearly; after that, agent() has no wall-clock deadline. Each individual child tool call times out independently after 3 minutes, becomes an error tool result, and leaves the agent loop free to recover. Use map/filter/if/await/template strings to orchestrate, and `return` a JSON-serializable aggregate.",
-  "Pass a `schema` to agent() whenever a later step branches on the result, so you get typed fields instead of prose. Artifacts are saved under ~/.pi/agent/workflows/<runId>/ for inspection. To re-run an edited workflow cheaply, pass `resume_from_run_id` with the previous run id: only provably read-only calls whose content and project/resource context are unchanged can replay; writable, unrestricted, unknown-tool, and worktree calls always run for real.",
+  "Workflow JavaScript runs in a restricted, killable child with no imports, eval, timers, filesystem, network, or process APIs. The package default permits 128 agent calls per run and can be changed with /openpi-setup (hard maximum 1024); there is no overall deadline. Each agent must receive its first assistant response event within 45 seconds so silent provider requests fail clearly; after that, agent() has no wall-clock deadline. Each individual child tool call times out independently after 3 minutes, becomes an error tool result, and leaves the agent loop free to recover. Use map/filter/if/await/template strings to orchestrate, and `return` a JSON-serializable aggregate.",
+  "Pass a `schema` to agent() whenever a later step branches on the result, so you get typed fields instead of prose. Each call persists independent intent, admission, and execution state; interrupted nonterminal calls are reported as uncertain rather than guessed failed. Artifacts include a bounded graph projection for explicit result-ref dependencies. To re-run an edited workflow cheaply, pass `resume_from_run_id` with the previous run id: only provably read-only non-operator calls whose content and project/resource context are unchanged can replay; writable, unrestricted, unknown-tool, operator, and worktree calls always run for real.",
   "Example — each file is verified as soon as ITS OWN scan lands, instead of waiting for every scan:",
   "export const meta = { name: 'reliability-review', description: 'Review modules for reliability risks, then report', phases: [{ title: 'Scan' }, { title: 'Verify' }, { title: 'Report' }] }",
   "const FINDINGS = { type: 'object', properties: { issues: { type: 'array', items: { type: 'string' } }, ok: { type: 'boolean' } }, required: ['issues', 'ok'] }",
   "phase('Scan')",
   "const checked = await pipeline(args.files,",
   "  (f) => agent(`Trace ${f} for candidate reliability risks with file:line evidence.`, { agent_type: 'explorer', label: `scan:${f}`, phase: 'Scan', schema: FINDINGS }),",
-  "  (scan, f) => scan.ok ? agent(`Review whether these candidate issues in ${f} are real: ${JSON.stringify(scan.structured.issues)}`, { agent_type: 'reviewer', label: `verify:${f}`, phase: 'Verify' }) : null)",
+  "  (scan, f) => scan.ok ? agent(`Review the candidate issues in ${f}.`, { agent_type: 'reviewer', label: `verify:${f}`, phase: 'Verify', inputs: [scan.ref] }) : null)",
   "const verified = checked.filter((r) => r && r.ok)",
   "const dropped = checked.length - verified.length // agents that failed/dropped: surface, never silently swallow",
   "if (dropped) log(`${dropped}/${checked.length} file(s) dropped before verification`)",
   "phase('Report')",
-  "const report = await agent(`Synthesize tradeoffs and recommendations from these verified findings: ${JSON.stringify(verified.map((r) => r.output))}`, { agent_type: 'advisor', label: 'report', phase: 'Report' })",
+  "const report = await agent('Synthesize tradeoffs and recommendations from the verified findings.', { agent_type: 'advisor', label: 'report', phase: 'Report', inputs: verified.map((r) => r.ref) })",
   "log(`done — ${verified.length} verified, ${usage().total} tokens`)",
   "return { verified: verified.length, dropped, report: report.ok ? report.output : report.error }",
 ].join("\n");

package/extensions/workflows/runner.ts

@@ -97,6 +97,8 @@ export interface RunAgentOptions {
   cwd: string;
   loader: DefaultResourceLoader;
   settingsManager: SettingsManager;
+  /** Optional per-run manager reused by one logical workflow operator. */
+  sessionManager?: SessionManager;
   modelRegistry: ExtensionContext["modelRegistry"];
   /** Agent Type allowlist; childToolPolicy can only narrow capabilities. */
   tools?: readonly string[];
@@ -465,6 +467,8 @@ export function createFirstResponseWatchdog(
   const timeoutMs = options.timeoutMs ?? FIRST_RESPONSE_TIMEOUT_MS;
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timeout = new Promise<never>((_resolve, reject) => {
+    // This timer owns the awaited watchdog outcome. Keep it referenced so a
+    // short-lived Node 22 process cannot exit with the promise still pending.
     timer = setTimeout(() => {
       timer = undefined;
       const model = options.model ? ` for ${options.model}` : "";
@@ -475,7 +479,6 @@ export function createFirstResponseWatchdog(
       );
       void onTimeout().catch(() => {});
     }, timeoutMs);
-    timer.unref?.();
   });
 
   const cancel = () => {
@@ -485,6 +488,7 @@ export function createFirstResponseWatchdog(
 
   return {
     markResponse: cancel,
+    cancel,
     async waitFor<T>(operation: Promise<T>) {
       try {
         return await Promise.race([operation, timeout]);
@@ -533,7 +537,8 @@ export async function runAgent(
         : {}),
       resourceLoader: options.loader,
       settingsManager: options.settingsManager,
-      sessionManager: SessionManager.inMemory(options.cwd),
+      sessionManager:
+        options.sessionManager ?? SessionManager.inMemory(options.cwd),
       ...(customTools ? { customTools } : {}),
       ...childToolPolicy(childTools),
     }));
@@ -619,6 +624,7 @@ export async function runAgent(
   };
 
   let markFirstResponse = () => {};
+  let cancelFirstResponseWatchdog = () => {};
   const unsubscribe = childSession.subscribe((event) => {
     if (settled) return;
     if (isAssistantResponseEvent(event)) markFirstResponse();
@@ -693,6 +699,7 @@ export async function runAgent(
         },
       );
       markFirstResponse = watchdog.markResponse;
+      cancelFirstResponseWatchdog = watchdog.cancel;
       await Promise.race([
         watchdog.waitFor(
           childSession.prompt(buildWorkflowAgentPrompt(options.prompt)),
@@ -703,6 +710,7 @@ export async function runAgent(
   } catch (error) {
     promptErrorMessage = errorText(error);
   } finally {
+    cancelFirstResponseWatchdog();
     options.signal?.removeEventListener("abort", onAbort);
     settled = true;
     unsubscribe();