@tt-a1i/openpi 0.4.0 → 0.6.0

package/extensions/subagents/src/domain.ts

@@ -31,6 +31,7 @@ export const REASONING_EFFORTS = [
 export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
 
 export type SubagentStatus = "running" | "done" | "error";
+export type SubagentOutcome = "completed" | "failed" | "interrupted";
 
 /** Parent-session context resolved by the tool layer and passed opaquely. */
 export interface ParentContext {
@@ -68,6 +69,8 @@ export interface SpawnTask {
   readonly tools?: readonly string[];
   /** Agent type that supplied the above, for the session label. */
   readonly agentTypeName?: string;
+  /** Optional JSON Schema for one terminating, validated child result. */
+  readonly outputSchema?: unknown;
   /**
    * Isolated git worktree this child runs in, created by the tool layer. The
    * backend only reclaims it when the session scope closes; it does not know
@@ -141,7 +144,11 @@ export interface QueuedMessage {
 // --- Events ------------------------------------------------------------------
 
 export type RunOutcome =
-  | { readonly _tag: "Completed"; readonly finalText: string }
+  | {
+      readonly _tag: "Completed";
+      readonly finalText: string;
+      readonly structuredResult?: StructuredSubagentResult;
+    }
   | {
       readonly _tag: "Failed";
       readonly errorText: string;
@@ -215,22 +222,35 @@ export interface SubagentSnapshot {
   readonly prompt: string;
   readonly cwd: string;
   readonly status: SubagentStatus;
+  readonly outcome?: SubagentOutcome;
+  readonly worktreeBranch?: string;
   readonly createdAt: number;
   readonly settledAt?: number;
   readonly errorText?: string;
   readonly meta: SubagentMeta;
   readonly usage: { readonly tokens?: number; readonly contextWindow?: number };
   readonly transcript: ReadonlyArray<TranscriptItem>;
+  /** Monotonic version bumped on every transcript mutation (see manager). */
+  readonly transcriptVersion: number;
   /** Streaming assistant buffers, cleared when the finalized message lands. */
   readonly liveAssistant?: { readonly text: string; readonly thinking: string };
   readonly liveTools: ReadonlyArray<LiveToolState>;
   readonly queued: ReadonlyArray<QueuedMessage>;
   /** Final text of the most recent completed run (v1 `finalOutput`). */
   readonly finalText: string;
+  /** Present only when this run supplied and satisfied output_schema. */
+  readonly structuredResult?: StructuredSubagentResult;
   /** Count of finalized assistant messages (for subagent_check). */
   readonly turns: number;
 }
 
+export interface StructuredSubagentResult {
+  readonly value: unknown;
+  readonly json: string;
+  readonly byteLength: number;
+  readonly artifactPath: string;
+}
+
 /** Final text, or the live streaming buffer while a run is active (v1 `latestOutput`). */
 export function latestText(snap: SubagentSnapshot) {
   const live = snap.liveAssistant?.text.trim();

package/extensions/subagents/src/manager.ts

@@ -27,6 +27,7 @@ import {
   Stream,
 } from "effect";
 import type { SubagentBackend, SubagentSession } from "./backend.ts";
+import type { AgentToolRenderer } from "../../shared/agent-tool-renderer.ts";
 import { BackendRegistry } from "./backend.ts";
 import type {
   BackendName,
@@ -63,7 +64,7 @@ const ENTRY_CLOSE_TIMEOUT_MS = 10_000;
  * First-response watchdog: a run whose provider accepts the request but
  * never emits an assistant event is settled as a failure so it cannot
  * occupy a concurrency slot forever. Matches the workflow runner's
- * FIRST_RESPONSE_TIMEOUT_MS (extensions/workflows/runner.ts).
+ * MODEL_PROGRESS_TIMEOUT_MS (extensions/workflows/runner.ts).
  */
 export const FIRST_RESPONSE_TIMEOUT_MS = 45_000;
 const ERROR_TEXT_MAX_LENGTH = 4_096;
@@ -92,6 +93,9 @@ function appendTranscript(snapshot: MutableSnapshot, item: TranscriptItem) {
       snapshot.transcript.length - MAX_TRANSCRIPT_ITEMS,
     );
   }
+  // Monotonic version so UI projections can detect transcript changes by
+  // O(1) comparison instead of scanning the mutable array.
+  snapshot.transcriptVersion++;
 }
 
 // --- Internal state -----------------------------------------------------------
@@ -105,16 +109,21 @@ interface MutableSnapshot {
   prompt: string;
   cwd: string;
   status: SubagentStatus;
+  outcome?: SubagentSnapshot["outcome"];
+  worktreeBranch?: string;
   createdAt: number;
   settledAt?: number;
   errorText?: string;
   meta: SubagentMeta;
   usage: { tokens?: number; contextWindow?: number };
   transcript: TranscriptItem[];
+  /** Bumped on every transcript mutation; UI caches key on this. */
+  transcriptVersion: number;
   liveAssistant?: { text: string; thinking: string };
   liveTools: LiveToolState[];
   queued: SubagentSnapshot["queued"];
   finalText: string;
+  structuredResult?: SubagentSnapshot["structuredResult"];
   turns: number;
 }
 
@@ -137,6 +146,8 @@ interface Entry {
 export interface SubagentReadModel {
   list(): ReadonlyArray<SubagentSnapshot>;
   get(id: string): SubagentSnapshot | undefined;
+  /** Native tool projection retained by the live child session, when present. */
+  getToolRenderer?(id: string): AgentToolRenderer | undefined;
   size(): number;
   /** Any-change notification (footer status, dashboard). */
   subscribe(listener: () => void): () => void;
@@ -299,7 +310,20 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     };
 
     const closeEntryScope = (entry: Entry) =>
-      Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
+      Scope.close(entry.scope, Exit.void).pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            const receipt = entry.session.cleanupReceipt?.();
+            if (!receipt?.uncertain) return;
+            const current = entry.snapshot.errorText;
+            entry.snapshot.errorText = current
+              ? `${current}; ${receipt.message}`
+              : receipt.message;
+            notify(entry.snapshot.id);
+          }),
+        ),
+        Effect.ignore,
+      );
 
     const pruneSettled = () => {
       if (entries.size <= MAX_TRACKED) return;
@@ -337,25 +361,31 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
       switch (outcome._tag) {
         case "Completed":
           s.status = "done";
+          s.outcome = "completed";
           s.errorText = undefined;
           s.finalText = outcome.finalText.slice(0, FINAL_TEXT_MAX_LENGTH);
+          s.structuredResult = outcome.structuredResult;
           break;
         case "Failed":
           s.status = "error";
+          s.outcome = "failed";
           s.errorText = bounded(outcome.errorText);
           // Never let a failed run report the previous run's successful output.
           s.finalText = (outcome.partialText ?? "").slice(
             0,
             FINAL_TEXT_MAX_LENGTH,
           );
+          s.structuredResult = undefined;
           break;
         case "Interrupted":
           s.status = "error";
+          s.outcome = "interrupted";
           s.errorText = "Run was aborted";
           s.finalText = (outcome.partialText ?? "").slice(
             0,
             FINAL_TEXT_MAX_LENGTH,
           );
+          s.structuredResult = undefined;
           break;
       }
       s.liveAssistant = undefined;
@@ -417,8 +447,10 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
         case "RunStarted":
           entry.restarting = false;
           s.status = "running";
+          s.outcome = undefined;
           s.settledAt = undefined;
           s.errorText = undefined;
+          s.structuredResult = undefined;
           armWatchdog(entry);
           break;
         case "RunSettled":
@@ -578,10 +610,14 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
               prompt: task.prompt,
               cwd: task.cwd,
               status: "running",
+              ...(task.worktree
+                ? { worktreeBranch: task.worktree.branch }
+                : {}),
               createdAt: Date.now(),
               meta,
               usage: { contextWindow: meta.contextWindow },
               transcript: [],
+              transcriptVersion: 0,
               liveTools: [],
               queued: [],
               finalText: "",
@@ -792,6 +828,7 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     const view: SubagentReadModel = {
       list: () => [...entries.values()].map((entry) => entry.snapshot),
       get: (id) => entries.get(id)?.snapshot,
+      getToolRenderer: (id) => entries.get(id)?.session.toolRenderer,
       size: () => entries.size,
       subscribe: (listener) => {
         listeners.add(listener);

package/extensions/subagents/src/prompt.ts

@@ -17,8 +17,8 @@ export const SUBAGENT_SCHEMA_BUDGETS = Object.freeze({
 
 /** Describes subagent_spawn, including the fixed concurrency cap. */
 export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background in-process Pi subagent with its own context, child-safe tools, and normal host permissions. Returns immediately; its final result is delivered automatically. The child cannot see this conversation, ask the user, or orchestrate agents/workflows. Use only trusted working directories. " +
-  `Max ${MAX_RUNNING} subagents can be running at once.`;
+  "Spawn a background Pi subagent with isolated context and child-safe tools. Returns immediately; its result arrives automatically. It cannot see this chat, ask the user, or orchestrate. Use trusted directories. " +
+  `Max ${MAX_RUNNING} subagents can run at once.`;
 
 /** UTF-8 bounded, whitespace-normalized text for the parent-facing roster. */
 function boundedPurpose(description: string) {
@@ -152,6 +152,7 @@ export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
     'Optional "provider/model-id" or current-provider model override. Omit to use the preset, configured role, or parent default. Never guess a model name.',
   reasoningEffort:
     "Optional child thinking level. Honor the user's requested level. Otherwise choose a level supported by the resolved child model based on the selected role and task difficulty. An explicit value overrides a role default.",
+  outputSchema: "Optional result JSON Schema.",
 };
 
 /** The exact name/description/wire-schema source used by registration/tests. */
@@ -193,6 +194,15 @@ export function createSubagentSpawnToolSurface(
           description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.reasoningEffort,
         }),
       ),
+      output_schema: Type.Optional(
+        Type.Object(
+          {},
+          {
+            additionalProperties: true,
+            description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.outputSchema,
+          },
+        ),
+      ),
     }),
   };
 }
@@ -207,6 +217,7 @@ export function buildSubagentSpawnResult(options: {
   agentTypeName?: string;
   tools?: readonly string[];
   worktreeBranch?: string;
+  structured?: boolean;
 }) {
   const typeNote = options.agentTypeName
     ? ` Agent type "${options.agentTypeName}" applied.`
@@ -226,8 +237,11 @@ export function buildSubagentSpawnResult(options: {
   const worktreeNote = options.worktreeBranch
     ? ` Isolated in its own worktree on branch "${options.worktreeBranch}" — its edits are invisible here until you merge that branch. The checkout stays available for later send/review and is reclaimed on Session retirement only when bounded inspection proves it empty.`
     : "";
+  const structuredNote = options.structured
+    ? " This run must finish with the requested validated structured result."
+    : "";
   return (
-    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}\n` +
+    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}${structuredNote}\n` +
     `It runs in the background — keep working on independent work. If none remains in an interactive session, briefly tell the user it is still running and end your turn; its result is delivered automatically and you are automatically re-invoked when it finishes. Do not poll or call subagent_wait merely because a later step depends on it. ` +
     `Use subagent_wait(ids: ["${options.id}"]) only if the user explicitly asked you to keep the current response open for this result, or a non-interactive automation must return it in the same invocation; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
   );
@@ -285,8 +299,11 @@ export const SUBAGENT_CHECK_PARAMETER_DESCRIPTIONS = {
 export const SUBAGENT_LIST_TOOL_DESCRIPTION =
   "List all subagents (running and finished) with their status.";
 
-/** Builds the child completion/failure wrapper injected into the parent model's context. */
-export function buildSubagentResultMessage(options: {
+const SUBAGENT_RESULT_TRANSPORT_INSTRUCTION =
+  "(This result is already shown to the user. Act on it and relay only the decisions or next steps — do not repeat it verbatim.)";
+
+/** Builds the user-visible child completion/failure projection. */
+export function buildSubagentResultDisplayMessage(options: {
   id: string;
   title: string;
   status: "running" | "done" | "error";
@@ -297,9 +314,34 @@ export function buildSubagentResultMessage(options: {
   let text = `Subagent ${options.id} "${options.title}" ${verb}.`;
   if (options.errorText) text += `\nError: ${options.errorText}`;
   text += `\n\n${options.output}`;
+  return text;
+}
+
+/** Builds the child completion/failure wrapper injected into the parent model's context. */
+export function buildSubagentResultMessage(options: {
+  id: string;
+  title: string;
+  status: "running" | "done" | "error";
+  errorText?: string;
+  output: string;
+}) {
+  let text = buildSubagentResultDisplayMessage(options);
   // This message is already displayed to the user, so tell the parent to act on
   // it rather than reprint it verbatim.
-  text +=
-    "\n\n(This result is already shown to the user. Act on it and relay only the decisions or next steps — do not repeat it verbatim.)";
+  text += `\n\n${SUBAGENT_RESULT_TRANSPORT_INSTRUCTION}`;
   return text;
 }
+
+/** Remove the transport-only suffix from results persisted before the split. */
+export function stripSubagentResultTransportInstruction(content: string) {
+  const separator = `\n\n${SUBAGENT_RESULT_TRANSPORT_INSTRUCTION}`;
+  const withoutBatchedSeparators = content.replaceAll(
+    `${separator}\n\nSubagent `,
+    "\n\nSubagent ",
+  );
+  return (
+    withoutBatchedSeparators.endsWith(separator)
+      ? withoutBatchedSeparators.slice(0, -separator.length)
+      : withoutBatchedSeparators
+  ).trimEnd();
+}

package/extensions/subagents/src/result-artifact.ts

@@ -20,6 +20,7 @@ export interface ResultProjection {
   readonly text: string;
   readonly truncated: boolean;
   readonly artifactPath?: string;
+  readonly artifactSaveFailed?: boolean;
 }
 
 function sliceStartToUtf8Bytes(content: string, maxBytes: number) {
@@ -76,6 +77,38 @@ export function persistResultArtifact(agentDir: string, content: string) {
   return artifactPath;
 }
 
+/** Persist one complete validated structured value under a JSON identity. */
+export function persistStructuredResultArtifact(
+  agentDir: string,
+  content: string,
+) {
+  let directory = path.resolve(agentDir);
+  for (const segment of RESULT_ARTIFACT_DIR) {
+    directory = ensureDirectory(directory, segment);
+  }
+
+  const digest = createHash("sha256").update(content).digest("hex");
+  const artifactPath = path.join(directory, `${digest}.json`);
+  try {
+    writeFileSync(artifactPath, content, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const stat = lstatSync(artifactPath);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      readFileSync(artifactPath, "utf8") !== content
+    ) {
+      throw new Error(`Structured result artifact collision: ${artifactPath}`);
+    }
+  }
+  return artifactPath;
+}
+
 /**
  * Build the single model-visible projection used by automatic delivery and
  * explicit waits. Short answers pass through byte-for-byte. Long answers keep
@@ -96,11 +129,13 @@ export function projectResult(
   const tailLines = Math.max(1, options.maxLines - headLines);
 
   let artifactPath: string | undefined;
+  let artifactSaveFailed = false;
   try {
     artifactPath = options.writeArtifact(content);
   } catch {
     // Delivery is more important than the optional recovery cache. The footer
     // below stays explicit so a failed write never advertises a false path.
+    artifactSaveFailed = true;
   }
 
   let bodyBudget = options.maxBytes;
@@ -138,5 +173,6 @@ export function projectResult(
     text,
     truncated: true,
     ...(artifactPath ? { artifactPath } : {}),
+    ...(artifactSaveFailed ? { artifactSaveFailed: true } : {}),
   };
 }

package/extensions/subagents/src/result-delivery.ts

@@ -1,8 +1,16 @@
+import type { ConsumableResultDeliveryQueue } from "../../shared/result-delivery.ts";
+import {
+  type CompletionOwner,
+  createCompletionInbox,
+} from "../../shared/completion-inbox.ts";
+
 export interface SubagentResultDeliveryOptions<T> {
   /** True only when the parent has no run or queued continuation in flight. */
   readonly isIdle: () => boolean;
   /** Deliver one drained batch and wake the parent. */
   readonly deliver: (results: readonly T[]) => void;
+  /** Current Pi Session transcript owner. */
+  readonly owner?: () => CompletionOwner | undefined;
 }
 
 /**
@@ -20,46 +28,63 @@ export interface SubagentResultDeliveryOptions<T> {
  * The parent boundary wakes even if an earlier extension handler has already
  * started another turn: Pi queues the follow-up into that active run.
  *
- * The Map is the one-shot gate: `subagent_wait` may consume a result before it
- * is delivered, and whichever path drains first prevents duplicate delivery.
+ * The shared inbox is the one-shot gate: `subagent_wait` may consume a result
+ * before it is delivered, and whichever path claims first prevents duplicate
+ * delivery.
  */
 export function createSubagentResultDelivery<T extends { id: string }>(
   options: SubagentResultDeliveryOptions<T>,
 ) {
-  const pending = new Map<string, T>();
+  const inbox = createCompletionInbox<T>();
+  const owner = options.owner ?? (() => ({ sessionId: "test", epoch: 0 }));
 
   const flush = () => {
-    if (pending.size === 0) return;
-    const results = [...pending.values()];
-    pending.clear();
+    const envelopes = inbox.claim(owner());
+    if (envelopes.length === 0) return;
+    const results = envelopes.map((envelope) => envelope.payload);
     try {
       options.deliver(results);
+      inbox.acknowledge(envelopes.map((envelope) => envelope.deliveryId));
     } catch (error) {
       // A synchronous session teardown may reject append/send. Preserve the
       // original batch ahead of anything deferred re-entrantly while delivery
       // ran, so a later boundary can retry without loss or reordering.
-      const current = [...pending.values()];
-      pending.clear();
-      for (const result of results) pending.set(result.id, result);
-      for (const result of current) pending.set(result.id, result);
+      inbox.retry(envelopes, owner());
       throw error;
     }
   };
 
-  return {
+  const queue = {
     defer(result: T) {
-      pending.set(result.id, result);
+      const currentOwner = owner();
+      inbox.defer(
+        {
+          deliveryId: `subagent:${result.id}`,
+          owner: currentOwner ?? { sessionId: "unowned", epoch: 0 },
+          producer: "subagent",
+          producerId: result.id,
+          terminalRef: { kind: "subagent-snapshot", id: result.id },
+          wake: "follow-up",
+          payload: result,
+        },
+        currentOwner,
+      );
       if (options.isIdle()) flush();
     },
     consume(ids: Iterable<string>) {
-      for (const id of ids) pending.delete(id);
+      inbox.consume("subagent", ids);
     },
     /** Flush at the authoritative parent boundary. */
     parentSettled() {
       flush();
     },
     clear() {
-      pending.clear();
+      inbox.clear();
+    },
+    size() {
+      return inbox.size();
     },
+    inspectDeadLetters: inbox.inspectDeadLetters,
   };
+  return queue satisfies ConsumableResultDeliveryQueue<T>;
 }

package/extensions/subagents/src/runtime.ts

@@ -11,8 +11,22 @@ import { BackendRegistry, type SubagentBackend } from "./backend.ts";
 import { piBackend } from "./backends/pi.ts";
 import type { BackendName } from "./domain.ts";
 
+/**
+ * Test-only injection seam for extension-level tests that drive real spawns
+ * without a child pi session: production never sets it. The underscore-prefixed
+ * setter name makes any accidental production use self-evidently wrong.
+ */
+let testBackends: readonly SubagentBackend[] | undefined;
+
+/** Test-only: replace the backends the manager can spawn against. */
+export function __setSubagentTestBackends(
+  backends: readonly SubagentBackend[] | undefined,
+) {
+  testBackends = backends;
+}
+
 const BackendRegistryLive = Layer.sync(BackendRegistry, () => {
-  const backends: SubagentBackend[] = [piBackend];
+  const backends: readonly SubagentBackend[] = testBackends ?? [piBackend];
   return new Map<BackendName, SubagentBackend>(
     backends.map((backend) => [backend.name, backend]),
   );