@tt-a1i/openpi 0.4.0 → 0.6.0

package/extensions/workflows/prompt.ts

@@ -1,8 +1,8 @@
-import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import {
   allocateResultBudgets,
   type ParentContextUsage,
 } from "../shared/result-budget.ts";
+import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import { projectText } from "../shared/text-projection.ts";
 import {
   countStates,
@@ -18,15 +18,15 @@ export const WORKFLOW_PARAMETER_DESCRIPTIONS = {
     "JavaScript workflow script. May start with `export const meta = {...}`, then use phase(), agent(), parallel(), args, and a final `return`.",
   args: "Optional JSON string exposed to the script as `args` (parsed when valid JSON, otherwise passed through as the raw string).",
   background:
-    "Deprecated compatibility alias: true means wait=false; false means wait=true. Do not provide both background and wait.",
+    "Deprecated compatibility alias for published callers only; new calls must use wait. Replace true with wait=false and false with wait=true. Do not provide both fields. The alias will be removed in the next announced breaking release.",
   wait: "Wait for the final result in this tool call. Interactive sessions default to false and deliver completion later; print/automation defaults to true. Interrupting the wait does not cancel the workflow.",
   resumeFromRunId:
     "Optional prior run id or unique suffix for safe read-only replay. See the workflows Skill for matching rules.",
 };
 
-/** Describes stopping a running background workflow, mirroring subagent_cancel/bg_kill. */
+/** Describes stopping a running workflow, mirroring subagent_cancel/bg_kill. */
 export const WORKFLOW_STOP_TOOL_DESCRIPTION =
-  "Cancel a running background workflow by its run id (from the workflow launch result). This aborts its remaining agents and settles the run; partial results and artifacts are preserved. Only background runs need this — a blocking workflow is already cancelled by interrupting the turn.";
+  "Cancel a running workflow by its run id (from the workflow launch result). This aborts its remaining agents and settles the run; partial results and artifacts are preserved.";
 
 /** Model-facing schema description for the workflow run id to stop. */
 export const WORKFLOW_STOP_PARAMETER_DESCRIPTIONS = {
@@ -56,7 +56,7 @@ export const WORKFLOW_TOOL_DESCRIPTION = [
   "Interactive sessions launch in the background by default and deliver completion later. Set wait: true only when this tool call must return the final result inline.",
   "Derive fan-out from independent verifiable work items and task difficulty. Concurrency is a runtime ceiling, not a target or the total-call limit; user cost, count, model, and effort constraints take precedence.",
   "For concurrent writers use isolation: 'worktree' and tell each agent to commit. Read-only work should normally stay in the shared checkout.",
-  "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, acceptance, result refs, replay, background lifecycle, limits, and examples.",
+  "Read the workflows Skill before a nontrivial script; it covers the restricted sandbox, full DSL, result refs, replay, background lifecycle, limits, and examples.",
 ].join("\n");
 
 /** Adds workflow orchestration primitives and background execution to the model's tool prompt. */
@@ -75,14 +75,6 @@ export function buildWorkflowAgentPrompt(prompt: string) {
   return prompt;
 }
 
-/** Instructs structured workflow children to terminate with exactly one structured_output call. */
-export const STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION =
-  "When your task is complete, call the `structured_output` tool exactly once as your final action, with fields matching the required schema. Do not write any other text after it.";
-
-/** Describes the terminating structured_output tool and its final-action contract. */
-export const STRUCTURED_OUTPUT_TOOL_DESCRIPTION =
-  "Return your final result as structured data matching the required schema. Call this exactly once, as your last action; do not write any other text after it.";
-
 /** Builds the workflow completion report returned to the parent model. */
 export function buildWorkflowResultMessage(
   details: WorkflowDetails,
@@ -157,7 +149,9 @@ export function buildWorkflowResultMessage(
               : "running";
       lines.push(
         `- [${agent.label}]${agent.phase ? ` (${agent.phase})` : ""} ${status}` +
-          (agent.acceptance ? ` · acceptance ${agent.acceptance.status}` : "") +
+          (agent.acceptance
+            ? ` · deprecated model self-attestation ${agent.acceptance.status}`
+            : "") +
           (agent.error ? ` — ${agent.error}` : ""),
       );
     }
@@ -214,6 +208,16 @@ export function buildProjectedWorkflowCompletionBatch(
   }[],
   usage?: ParentContextUsage | null,
 ) {
+  const deliveryFacts = JSON.stringify(
+    entries.map(({ deliveryId, details, runDir }) => ({
+      deliveryId,
+      runId: details.runId,
+      evidence: shortenHome(runDir),
+    })),
+  );
+  const manifest =
+    "Workflow completion delivery facts (stable across retries; deduplicate by deliveryId):\n" +
+    deliveryFacts;
   const full = entries.map(({ deliveryId, details, runDir }) =>
     buildBackgroundWorkflowFollowUp({
       runId: details.runId,
@@ -223,18 +227,30 @@ export function buildProjectedWorkflowCompletionBatch(
     }),
   );
   const separatorBytes = Math.max(0, entries.length - 1) * 2;
+  const manifestSeparatorBytes = entries.length > 0 ? 2 : 0;
+  const fixedBytes =
+    Buffer.byteLength(manifest, "utf8") +
+    separatorBytes +
+    manifestSeparatorBytes;
+  const bodyBudget = 48 * 1024 - fixedBytes;
+  if (bodyBudget < 0) {
+    throw new Error(
+      "Workflow completion delivery facts exceed the transport payload limit",
+    );
+  }
   const allocation = allocateResultBudgets(
     full.map((message) => Buffer.byteLength(message, "utf8")),
     usage,
     {
-      maxBatchBytes: 48 * 1024 - separatorBytes,
+      maxBatchBytes: bodyBudget,
       maxResultBytes: 48 * 1024,
       minResultBytes: 1024,
       headroomShare: 0.25,
       estimatedBytesPerToken: 4,
+      fixedBytes,
     },
   );
-  return full
+  const projected = full
     .map((message, index) =>
       projectText(message, {
         maxBytes: allocation.budgets[index] ?? 1024,
@@ -243,6 +259,44 @@ export function buildProjectedWorkflowCompletionBatch(
       }),
     )
     .join("\n\n");
+  return projected ? `${manifest}\n\n${projected}` : manifest;
+}
+
+/** Split transport batches so every manifest and projected body fit together. */
+export function buildProjectedWorkflowCompletionBatches(
+  entries: readonly {
+    deliveryId: string;
+    details: WorkflowDetails;
+    runDir: string;
+  }[],
+  usage?: ParentContextUsage | null,
+) {
+  const batches: Array<{
+    entries: (typeof entries)[number][];
+    content: string;
+  }> = [];
+  let current: (typeof entries)[number][] = [];
+  for (const entry of entries) {
+    const candidate = [...current, entry];
+    try {
+      buildProjectedWorkflowCompletionBatch(candidate, usage);
+      current = candidate;
+    } catch (error) {
+      if (current.length === 0) throw error;
+      batches.push({
+        entries: current,
+        content: buildProjectedWorkflowCompletionBatch(current, usage),
+      });
+      current = [entry];
+    }
+  }
+  if (current.length > 0) {
+    batches.push({
+      entries: current,
+      content: buildProjectedWorkflowCompletionBatch(current, usage),
+    });
+  }
+  return batches;
 }
 
 /** Builds the background-launch result and tells the parent model how to inspect or stop the run. */

package/extensions/workflows/replay-safety.ts

@@ -423,13 +423,44 @@ function canonicalPath(value: string) {
   return fs.realpathSync.native(value);
 }
 
-function repositoryFingerprint(cwd: string) {
+function deadlineBoundGitRunner() {
+  // One budget per fingerprint call: every git invocation shares a single
+  // deadline.
   const deadline = Date.now() + REPLAY_IDENTITY_TIMEOUT_MS;
-  const git = (gitCwd: string, args: readonly string[]) =>
+  return (gitCwd: string, args: readonly string[]) =>
     boundedGit(gitCwd, args, deadline);
-  const root = canonicalPath(git(cwd, ["rev-parse", "--show-toplevel"]).trim());
-  const head = git(root, ["rev-parse", "--verify", "HEAD"]).trim();
-  const diff = git(root, [
+}
+
+export function repositoryFingerprint(
+  cwd: string,
+  runGit: (
+    gitCwd: string,
+    args: readonly string[],
+  ) => string = deadlineBoundGitRunner(),
+) {
+  const root = canonicalPath(
+    runGit(cwd, ["rev-parse", "--show-toplevel"]).trim(),
+  );
+  const assertNoIgnoredFiles = () => {
+    // Ignored files are observable to a read-capable child but are commonly
+    // too large or secret-bearing to hash (node_modules, .env, build output).
+    // A complete identity cannot pretend they do not exist, so disable replay.
+    const ignoredOutput = runGit(root, [
+      "ls-files",
+      "--others",
+      "--ignored",
+      "--exclude-standard",
+      "--directory",
+      "-z",
+    ]);
+    if (ignoredOutput.length > 0) {
+      throw new Error("ignored files make the replay identity incomplete");
+    }
+  };
+  // The common disqualifying case exits before the expensive binary diff.
+  assertNoIgnoredFiles();
+  const head = runGit(root, ["rev-parse", "--verify", "HEAD"]).trim();
+  const diff = runGit(root, [
     "diff",
     "--no-ext-diff",
     "--no-textconv",
@@ -437,7 +468,7 @@ function repositoryFingerprint(cwd: string) {
     "HEAD",
     "--",
   ]);
-  const trackedModes = git(root, ["ls-files", "-s", "-z"]);
+  const trackedModes = runGit(root, ["ls-files", "-s", "-z"]);
   // Tracked symlinks can expose changing content outside Git, while gitlinks
   // can expose submodule state absent from the parent diff. Neither has a
   // complete bounded identity here, so execute instead of replaying.
@@ -450,21 +481,11 @@ function repositoryFingerprint(cwd: string) {
   ) {
     throw new Error("symlinks and gitlinks make replay identity incomplete");
   }
-  // Ignored files are observable to a read-capable child but are commonly too
-  // large or secret-bearing to hash (node_modules, .env, build output). A
-  // complete identity cannot pretend they do not exist, so disable replay.
-  const ignoredOutput = git(root, [
-    "ls-files",
-    "--others",
-    "--ignored",
-    "--exclude-standard",
-    "--directory",
-    "-z",
-  ]);
-  if (ignoredOutput.length > 0) {
-    throw new Error("ignored files make the replay identity incomplete");
-  }
-  const untrackedOutput = git(root, [
+  // Preserve the original post-diff safety observation: an ignored file can
+  // appear while the synchronous diff is running, including from another
+  // process. The early check is only an optimization, never the final gate.
+  assertNoIgnoredFiles();
+  const untrackedOutput = runGit(root, [
     "ls-files",
     "--others",
     "--exclude-standard",

package/extensions/workflows/result-delivery.ts

@@ -1,3 +1,12 @@
+import {
+  type CompletionEnvelope,
+  type CompletionOwner,
+  createCompletionInbox,
+} from "../shared/completion-inbox.ts";
+import type {
+  DurableResultDeliveryQueue,
+  DurableResultDeliveryReceipt,
+} from "../shared/result-delivery.ts";
 import type { WorkflowDetails } from "./model.ts";
 
 export interface WorkflowCompletionEnvelope {
@@ -6,19 +15,14 @@ export interface WorkflowCompletionEnvelope {
   details: WorkflowDetails;
 }
 
-export interface WorkflowDeliveryReceipt {
-  deliveryId: string;
-  delivered: boolean;
-  error?: string;
-}
-
 export interface WorkflowResultDeliveryOptions {
   isIdle: () => boolean;
+  owner?: () => CompletionOwner | undefined;
   persist: (details: WorkflowDetails) => void;
   deliver: (
     envelopes: readonly WorkflowCompletionEnvelope[],
     wake: boolean,
-  ) => Promise<readonly WorkflowDeliveryReceipt[]>;
+  ) => Promise<readonly DurableResultDeliveryReceipt[]>;
 }
 
 function errorText(error: unknown) {
@@ -36,8 +40,12 @@ function errorText(error: unknown) {
 export function createWorkflowResultDelivery(
   options: WorkflowResultDeliveryOptions,
 ) {
-  const pending = new Map<string, WorkflowCompletionEnvelope>();
+  const inbox = createCompletionInbox<WorkflowCompletionEnvelope>();
+  const currentOwner =
+    options.owner ?? (() => ({ sessionId: "test", epoch: 0 }));
   let flushing: Promise<void> | undefined;
+  let flushRequested = false;
+  let wakeRequested = false;
 
   const persistState = (
     details: WorkflowDetails,
@@ -57,67 +65,154 @@ export function createWorkflowResultDelivery(
     options.persist(details);
   };
 
-  const enqueue = (envelope: WorkflowCompletionEnvelope) => {
-    pending.set(envelope.deliveryId, envelope);
+  const inboxEnvelope = (
+    envelope: WorkflowCompletionEnvelope,
+  ): CompletionEnvelope<WorkflowCompletionEnvelope> => {
+    const delivery = envelope.details.delivery;
+    const deliverySessionId = delivery?.ownerSessionId;
+    const detailsSessionId = envelope.details.sessionId;
+
+    // Conflicting owner fields invalidate delivery ownership fail-closed.
+    const hasConflict =
+      deliverySessionId !== undefined &&
+      detailsSessionId !== undefined &&
+      deliverySessionId !== detailsSessionId;
+
+    const ownerSessionId = hasConflict ? undefined : deliverySessionId;
+    return {
+      deliveryId: envelope.deliveryId,
+      owner: {
+        sessionId:
+          ownerSessionId && ownerSessionId !== "unowned"
+            ? ownerSessionId
+            : "unowned",
+        epoch: delivery?.ownerEpoch ?? 0,
+      },
+      producer: "workflow",
+      producerId: envelope.runId,
+      terminalRef: {
+        kind: "workflow-terminal",
+        runId: envelope.runId,
+        status: envelope.details.status,
+      },
+      wake: "producer-policy",
+      payload: envelope,
+    };
+  };
+
+  const enqueue = (envelope: WorkflowCompletionEnvelope) =>
+    inbox.defer(inboxEnvelope(envelope), currentOwner());
+
+  const retainPending = (
+    envelope: WorkflowCompletionEnvelope,
+    patch: Partial<NonNullable<WorkflowDetails["delivery"]>>,
+    persistenceFailure: string,
+  ) => {
+    // Memory owns the retry before persistence is attempted. A broken disk
+    // must not make this envelope, or any sibling after it, disappear from the
+    // current process.
+    const admitted = enqueue(envelope);
+    try {
+      persistState(envelope.details, "pending", patch);
+    } catch (error) {
+      const delivery = envelope.details.delivery;
+      if (delivery) {
+        envelope.details.delivery = {
+          ...delivery,
+          state: "pending",
+          updatedAt: Date.now(),
+          lastError: `${persistenceFailure}: ${errorText(error)}`,
+        };
+      }
+    }
+    return admitted;
   };
 
   const flush = async (wake: boolean) => {
-    if (flushing) return flushing;
-    if (pending.size === 0) return;
-    const envelopes = [...pending.values()];
-    for (const envelope of envelopes) pending.delete(envelope.deliveryId);
+    if (flushing) {
+      flushRequested = true;
+      wakeRequested ||= wake;
+      return flushing;
+    }
+    if (inbox.size() === 0) return;
 
     flushing = (async () => {
-      let receipts: readonly WorkflowDeliveryReceipt[];
-      try {
-        receipts = await options.deliver(envelopes, wake);
-      } catch (error) {
-        const message = errorText(error);
-        for (const envelope of envelopes) {
-          enqueue(envelope);
-          persistState(envelope.details, "pending", {
-            attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
-            lastError: message,
-          });
+      let passWake = wake;
+      while (inbox.size() > 0) {
+        flushRequested = false;
+        wakeRequested = false;
+        const claimed = inbox.claim(currentOwner());
+        const envelopes = claimed.map((envelope) => envelope.payload);
+        if (envelopes.length === 0) break;
+
+        let receipts: readonly DurableResultDeliveryReceipt[] | undefined;
+        try {
+          receipts = await options.deliver(envelopes, passWake);
+        } catch (error) {
+          const message = errorText(error);
+          for (const envelope of envelopes) {
+            inbox.acknowledge([envelope.deliveryId]);
+            retainPending(
+              envelope,
+              {
+                attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
+                lastError: message,
+              },
+              "Pending delivery persistence failed",
+            );
+          }
         }
-        return;
-      }
 
-      const byId = new Map(
-        receipts.map((receipt) => [receipt.deliveryId, receipt] as const),
-      );
-      for (const envelope of envelopes) {
-        const receipt = byId.get(envelope.deliveryId);
-        if (receipt?.delivered) {
-          try {
-            persistState(envelope.details, "delivered", {
-              attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
-              deliveredAt: Date.now(),
-              lastError: undefined,
-            });
-          } catch (error) {
-            // The transport already accepted the message, but the durable
-            // receipt did not commit. Retain it for at-least-once recovery;
-            // the visible stable id lets the parent recognize a rare replay.
-            enqueue(envelope);
-            const delivery = envelope.details.delivery;
-            if (delivery) {
-              envelope.details.delivery = {
-                ...delivery,
-                state: "pending",
-                updatedAt: Date.now(),
-                lastError: `Delivery receipt persistence failed: ${errorText(error)}`,
-              };
+        if (receipts !== undefined) {
+          const byId = new Map(
+            receipts.map((receipt) => [receipt.deliveryId, receipt] as const),
+          );
+          for (const envelope of envelopes) {
+            const receipt = byId.get(envelope.deliveryId);
+            if (receipt?.delivered) {
+              inbox.acknowledge([envelope.deliveryId]);
+              try {
+                persistState(envelope.details, "delivered", {
+                  attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
+                  deliveredAt: Date.now(),
+                  lastError: undefined,
+                });
+              } catch (error) {
+                // The transport already accepted the message, but the durable
+                // receipt did not commit. Retain it for at-least-once recovery;
+                // the visible stable id lets the parent recognize a rare replay.
+                enqueue(envelope);
+                const delivery = envelope.details.delivery;
+                if (delivery) {
+                  envelope.details.delivery = {
+                    ...delivery,
+                    state: "pending",
+                    updatedAt: Date.now(),
+                    lastError: `Delivery receipt persistence failed: ${errorText(error)}`,
+                  };
+                }
+              }
+              continue;
             }
+            inbox.acknowledge([envelope.deliveryId]);
+            retainPending(
+              envelope,
+              {
+                attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
+                lastError:
+                  receipt?.error ?? "Completion delivery was not acknowledged",
+              },
+              "Pending delivery persistence failed",
+            );
           }
-          continue;
         }
-        enqueue(envelope);
-        persistState(envelope.details, "pending", {
-          attempts: (envelope.details.delivery?.attempts ?? 0) + 1,
-          lastError:
-            receipt?.error ?? "Completion delivery was not acknowledged",
-        });
+
+        // A completion or lifecycle edge joined this pass while transport was
+        // in flight. Drain once more so that request is not lost. Failures
+        // retained above do not request their own immediate retry, preventing
+        // an unavailable transport from creating a busy loop.
+        if (!flushRequested) break;
+        passWake ||= wakeRequested;
       }
     })().finally(() => {
       flushing = undefined;
@@ -125,7 +220,7 @@ export function createWorkflowResultDelivery(
     return flushing;
   };
 
-  return {
+  const queue = {
     /** Register inline interest before the run starts. */
     holdInline(details: WorkflowDetails) {
       persistState(details, "held-for-inline");
@@ -133,7 +228,7 @@ export function createWorkflowResultDelivery(
 
     /** Terminal won the wait/abort arbitration and will be returned inline. */
     consumeInline(details: WorkflowDetails) {
-      if (details.delivery) pending.delete(details.delivery.id);
+      if (details.delivery) inbox.consumeDeliveryIds([details.delivery.id]);
       persistState(details, "consumed-inline", {
         deliveredAt: Date.now(),
         lastError: undefined,
@@ -142,15 +237,21 @@ export function createWorkflowResultDelivery(
 
     /** Abort won the wait/terminal arbitration; deliver the result later. */
     releaseInline(envelope: WorkflowCompletionEnvelope) {
-      persistState(envelope.details, "pending", { lastError: undefined });
-      enqueue(envelope);
+      retainPending(
+        envelope,
+        { lastError: undefined },
+        "Initial delivery persistence failed",
+      );
       if (options.isIdle()) void flush(true);
     },
 
-    /** Queue a detached run after terminal status and pending are persisted. */
+    /** Queue a detached run with in-memory retry ownership before persistence. */
     defer(envelope: WorkflowCompletionEnvelope) {
-      persistState(envelope.details, "pending", { lastError: undefined });
-      enqueue(envelope);
+      retainPending(
+        envelope,
+        { lastError: undefined },
+        "Initial delivery persistence failed",
+      );
       if (options.isIdle()) void flush(true);
     },
 
@@ -158,15 +259,50 @@ export function createWorkflowResultDelivery(
     restore(envelope: WorkflowCompletionEnvelope) {
       const state = envelope.details.delivery?.state;
       if (state !== "pending" && state !== "held-for-inline") return false;
-      // A process restart cannot still own the inline waiter. Deterministically
-      // reconstruct pending delivery from the terminal artifact.
-      if (state === "held-for-inline") {
-        persistState(envelope.details, "pending", {
-          lastError: "Inline waiter was not active after session restart",
-        });
+      const owner = currentOwner();
+      const deliverySessionId = envelope.details.delivery?.ownerSessionId;
+      const detailsSessionId = envelope.details.sessionId;
+      const hasConflict =
+        deliverySessionId !== undefined &&
+        detailsSessionId !== undefined &&
+        deliverySessionId !== detailsSessionId;
+      const storedSessionId = hasConflict
+        ? undefined
+        : (deliverySessionId ?? detailsSessionId);
+
+      // Restoring canonical producer state is the explicit owner-revival
+      // boundary. Rebind only the same transcript to this process-local
+      // SessionManager generation; a different Session still dead-letters.
+      if (
+        owner &&
+        storedSessionId !== undefined &&
+        storedSessionId === owner.sessionId
+      ) {
+        envelope.details.delivery = {
+          ...envelope.details.delivery!,
+          ownerSessionId: owner.sessionId,
+          ownerEpoch: owner.epoch,
+        };
+        return retainPending(
+          envelope,
+          {
+            ownerSessionId: owner.sessionId,
+            ownerEpoch: owner.epoch,
+            lastError:
+              state === "held-for-inline"
+                ? "Inline waiter was not active after session restart"
+                : undefined,
+          },
+          "Restored delivery state persistence failed",
+        );
       }
-      enqueue(envelope);
-      return true;
+      // Keep the canonical terminal artifact pending, but record that this
+      // process is not its transcript owner instead of redirecting it.
+      return enqueue(envelope);
+    },
+
+    retryPending() {
+      return flush(true) ?? Promise.resolve();
     },
 
     parentSettled() {
@@ -179,11 +315,13 @@ export function createWorkflowResultDelivery(
     },
 
     size() {
-      return pending.size;
+      return inbox.size();
     },
 
     clear() {
-      pending.clear();
+      inbox.clear();
     },
+    inspectDeadLetters: inbox.inspectDeadLetters,
   };
+  return queue satisfies DurableResultDeliveryQueue<WorkflowCompletionEnvelope>;
 }