@tranhoangnguyen0310/pi-flow-external 3.1.0-external.0 → 3.2.0-external.0

package/AGENTS.md

@@ -43,7 +43,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Receipt and evidence invariants
 
-- Agent public contract v1 uses a discriminated `ok` envelope with `isError === !ok`; renderer details remain independent. Expected errors are coded at their source, not parsed from prose. Canonical output is inline only within 16 KiB UTF-8 JSON after redaction, with `output_redacted` disclosed when changed. Refs must be resolvable, liveness must be observed after evidence I/O, and unavailable evidence must not discard a settled result. Native codemode tests must assert script output and hook-captured flags outside hooks (the SDK catches hook exceptions).
+- Public contract v1 (`Agent`, `workflow`, every `external_runs` action; `src/contract/`) uses one discriminated `ok` envelope with `isError === !ok`; `ok` describes the operation, so inspecting or waiting on a failed run is `ok`. Renderer details remain independent. Expected errors are coded at their source and returned, not thrown or parsed from prose; `/external runs` reads the same structured contract a script reads. A workflow root that handled child failures stays `ok` with `children.failed` counted at the single non-fatal delivery site (never from snapshot rows) and a `handled_child_failures` warning. Supervision text is redacted at its source before it is measured or sliced; never redact an already-cut page. Canonical output is inline only within 16 KiB UTF-8 JSON after redaction, with `output_redacted` disclosed when changed. Refs must be resolvable, liveness must be observed after evidence I/O, and unavailable evidence must not discard a settled result. Native codemode tests must assert script output and hook-captured flags outside hooks (the SDK catches hook exceptions).
 
 - Success requires a recognized backend terminal-success event, a zero process exit, and a non-empty result.
 - A backend failure with a complete local record is different from an incomplete or damaged record; preserve that distinction in reports.
@@ -51,7 +51,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 - Settings retention automatically prunes eligible completed records beyond `maxRunRecords`; active, interrupted, incomplete, and damaged records are not eligible.
 - Structured nested-agent activity may extend the wall-clock deadline once, by one fresh base timeout, capped at twice the original deadline.
 - Do not automatically retry failed or aborted external runs. Preserve the receipt and retry only when the user asks. Exception: the agy backend retries once on infrastructure-classified failures (auth, eligibility, network); the retry is disclosed in the receipt details (`retries`, `retryOf`) and never applies to agent-level failures, aborts, or timeouts.
-- `external_runs` is session/project scoped. `list` pages runs and workflow roots, each carrying a shared timing projection (`queuedAt`/`executionStartedAt`/`processStartedAt`/activity timestamps plus derived `queueDelayMs`/`elapsedMs`/`activityAgeMs`/`processDurationMs`); `activityAgeMs` and a running `elapsedMs` are computed only for a target independently confirmed live by the registry, never inferred from a durable record's status field alone (an unowned "running"-looking record may be an orphaned/crashed run, not a live one). `inspect` pages `summary`/`output`/`diagnostics`/`final` for one `runId`; `final` returns only the same canonical terminal result every other view already reads (no separate backend parser, no narration promoted to final) and is empty with `finalAvailable: false` until a verified successful terminal boundary exists — including for workflows, where an intentional JSON `null` result still counts as available. `inspect` also accepts a bounded batch `runIds` (up to 20, deduplicated, order preserved, summary-only, mutually exclusive with `runId`): every requested ID's ownership is validated before any page returns, entries share one consistent nested shape regardless of live/durable/agent/workflow origin (a workflow entry omits its unbounded children array in favor of `outputRef`/`diagnosticsRef`), reuses the existing per-inspect `limitBytes` cap with no second budget, and fails with an actionable error naming the run rather than ever silently dropping a target or serving a page over the caller's own byte budget. `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; while waiting it reports bounded live progress (watched targets, completed/pending counts, recent activity) through the tool's own update channel on a fixed heartbeat, stopped on settlement/error/interruption, that never mutates run state or affects cancellation; each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response in the caller's requested order, never settlement race order — complete when it fits, `resultTruncated: true` plus the existing `outputRef`/`diagnosticsRef` when it does not, never a fixed-length teaser regardless of size; a target's evidence is never read from disk once that shared budget is already exhausted. `cancel` targets one stable ID and preserves its reason. An unresolvable `wf_...` ID fails as unknown/unavailable across `inspect`/`cancel`/`wait`/batch `inspect`, never falling through to the agent-only durable reader. No routine run event sends a parent message or notification.
+- `external_runs` is session/project scoped. `list` pages runs and workflow roots, each carrying a shared timing projection (`queuedAt`/`executionStartedAt`/`processStartedAt`/activity timestamps plus derived `queueDelayMs`/`elapsedMs`/`activityAgeMs`/`processDurationMs`); `activityAgeMs` and a running `elapsedMs` are computed only for a target independently confirmed live by the registry, never inferred from a durable record's status field alone (an unowned "running"-looking record may be an orphaned/crashed run, not a live one). `inspect` pages `summary`/`output`/`diagnostics`/`final` for one `runId`; `final` returns only the same canonical terminal result every other view already reads (no separate backend parser, no narration promoted to final) and is empty with `finalAvailable: false` until a verified successful terminal boundary exists — including for workflows, where an intentional JSON `null` result still counts as available. `inspect` also accepts a bounded batch `runIds` (up to 20, deduplicated, order preserved, summary-only, mutually exclusive with `runId`): every requested ID's ownership is validated before any page returns, entries share one consistent nested shape regardless of live/durable/agent/workflow origin (a workflow entry omits its unbounded children array in favor of `outputRef`/`diagnosticsRef`), reuses the existing per-inspect `limitBytes` cap with no second budget (an entry is served only when both the legacy text and the full structured envelope fit), and returns `page_too_small` naming the run rather than ever silently dropping a target or serving a page over the caller's own byte budget. `wait` returns outcomes only for the selected one/any/all target set and never cancels pending work; while waiting it reports bounded live progress (watched targets, completed/pending counts, recent activity) through the tool's own update channel on a fixed heartbeat, stopped on settlement/error/interruption, that never mutates run state or affects cancellation; each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response in the caller's requested order, never settlement race order — complete when it fits, `resultTruncated: true` plus the existing `outputRef`/`diagnosticsRef` when it does not, never a fixed-length teaser regardless of size; a target's evidence is never read from disk once that shared budget is already exhausted. The structured `completed[i].output.value` is inline only from memory when the legacy text was delivered whole and its encoded JSON fits both 16 KiB and what remains of the structured channel's own copy of `limitBytes` (spent in the same request order); otherwise it is delivered by reference (always for durable targets), with no extra read. An agent `final` view serves a settled successful registry result from memory, so a promised `refs.final` resolves even without persisted evidence. Output/diagnostics pages concatenate losslessly (a `\n` separates each new message); inspection cursors from the previous page format fail as `cursor_stale`. `cancel` targets one stable ID and preserves its reason. An unresolvable `wf_...` ID fails as unknown/unavailable across `inspect`/`cancel`/`wait`/batch `inspect`, never falling through to the agent-only durable reader. No routine run event sends a parent message or notification.
 - `list`, `inspect`, and `wait` share one run projection (`src/core/run-projection.ts`: `projectLiveAgent`/`projectDurableAgent` for agents, `projectWorkflowRun` for workflows) instead of independent per-surface field extraction. Task identity includes the resolved profile and an explicit `harness` (registered pi-* config, or equal to backend for agy/claude/codex/grok/muse/opencode), persisted at the source (run-record metadata, live progress nodes, workflow child snapshots) by every backend — never reparsed or guessed from a profile/subagentType name.
 
 ## Workflow contract

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [3.2.0-external.0] - 2026-10-02
+
+### Added
+- Versioned public contracts for `workflow` and every `external_runs` action (issue #77), sharing the `Agent` envelope from 3.1.0: `outputSchema`, matching `structuredContent`, and `isError === !ok`. `ok` describes the operation, so inspecting or waiting on a failed run is `ok: true`. See [docs/public-contract.md](docs/public-contract.md), which replaces `docs/agent-public-contract.md`.
+- `external_runs` payloads:
+
+  | Action | `data` |
+  |---|---|
+  | `list` | `{runs, workflows, nextCursor?, nextWorkflowCursor?}` |
+  | batch `inspect` | `{mode: "batch", entries, nextCursor?}` |
+  | single `inspect` | `{mode: "single", runId, view, page: {text, encoding, complete, nextCursor?}, finalAvailable?, outputStatus?}` |
+  | `wait` | `{mode, completed, pending}` |
+  | `cancel` | `{runId, status}` |
+
+  Every row is one `PublicRun` shape, with evidence integrity and callable `refs`. In `wait`, a structured value is inline only when it is in memory, its text result was delivered whole, and its encoded JSON fits both 16 KiB and what remains of the structured channel's own copy of `limitBytes`, spent in request order. Otherwise it is delivered by reference.
+- An agent's `final` view now serves a settled successful result still held in the registry, so a `refs.final` reference resolves even when the run's evidence was never saved.
+- Workflow receipts. A foreground root that failed, was cancelled or timed out is `ok: false` and keeps its run. A background launch is `ok: true` once accepted. A root that succeeded after catching child failures stays `ok: true`, reports `run.children.failed`, and adds the warning `handled_child_failures` and a sentence in its text result. Failures are counted where the script receives them, including calls that fail before a child is indexed; always-fatal failures are excluded. Journals record the count (`childFailures`) and report integrity: a torn last line is `incomplete`, a bad line mid-file is `damaged`.
+- New error codes: `request_invalid`, `run_unavailable`, `run_not_live`, `cursor_invalid`, `cursor_stale`, `page_too_small`, `session_unavailable`, `script_invalid`, `storage_unavailable`.
+
+### Changed (compatibility)
+- **Expected `external_runs` and `workflow` failures are returned, not thrown.** Messages are unchanged except where noted. Direct callers and scripts that relied on a rejection must check `ok` or `isError`. Interrupted waits, unexpected exceptions, schema validation and `tool_call` blocks still throw.
+
+  | Previously thrown message | Now returned with code |
+  |---|---|
+  | "Invalid run ID"; "Invalid workflow run ID"; "inspect accepts either runId or runIds, not both"; "cancel accepts either runId or runIds, not both"; "cancel targets one run at a time"; "inspect runIds requires 1-20 run IDs"; "wait requires 1-100 run IDs"; 'Batch inspect (runIds) only supports view: "summary"'; "limitBytes must be finite" | `request_invalid` |
+  | "Run is unknown or unavailable in this session" | `run_unavailable` |
+  | "Run is no longer live in this session; cancellation cannot be confirmed"; "Run … is unavailable for live waiting" | `run_not_live` |
+  | "Invalid cursor"; "Cursor belongs to a different run/view/list scope"; "Batch cursor does not match the requested run IDs…"; a batch cursor from another session (message is now "Cursor belongs to a different session or project") | `cursor_invalid` |
+  | "Run changed while paging; restart inspection without a cursor"; "Cursor points past available evidence"/"outside available workflow content" (message is now the "Run changed while paging" text) | `cursor_stale` |
+  | "Batch summary for … does not fit within limitBytes…" | `page_too_small` |
+  | "external_runs requires a persisted originating session" | `session_unavailable` |
+
+- Failed workflow rows now set `isError`, so they render red like failed `Agent` calls.
+- **Output and diagnostics pages concatenate losslessly.** Each new message after the first carries a leading `\n` separator inside the page text and items; agy/muse streaming deltas still join into one message. Previously, two messages split across a page boundary ran together. Byte offsets shift, so inspection cursors issued by earlier versions fail with `cursor_stale`; restart without a cursor.
+- Batch `inspect` serves an entry only when it fits `limitBytes` in both the text and the structured result, so text pages may hold fewer entries than before.
+- Live output pages, in-memory wait results and workflow views (from memory or the journal) are now redacted in full before they are measured or sliced. Previously they were served unredacted.
+- `/external runs` reads the structured contract. Stale cursors restart from page 1 by code, now including paged summaries. Other failures show a notice and keep the navigator open instead of closing it.
+- An unreadable workflow journal in this project is reported as `run_unavailable` with its read error; another project's journal is reported like an unknown run.
+
+## [3.1.1-external.0] - 2026-10-02
+
+### Fixed
+- `external_runs list` no longer reports live work as `interrupted_or_uncertain` on later pages, or lists a live run twice. Live state now replaces a run's persisted row on whichever page that row falls. Live runs with no persisted row yet (for example, while evidence writes fail) are paged first and count against `limit`, so every page stays within `limit`. The cursor bookmarks the last such run in registry order, so persisting one between pages never skips another; it can only appear twice (once live, once persisted). If the bookmarked run has left the registry, the next page fails with "Run list changed while paging" instead of guessing. A run started after the listing reached its persisted rows appears in the next fresh listing.
+- One unreadable workflow journal (an incompatible version, a corrupt start line, or a read error) no longer fails the whole `list`. It is listed as one `interrupted_or_uncertain` row with the read error; `inspect` of that ID still reports the error.
+- A workflow launched after its session closed no longer throws with its journal left open. The journal is settled as failed, and the call returns an error result naming the closed session.
+- Workflow resume no longer reveals that another project's run exists: it reports the same "run journal not found" message as an unknown run ID.
+
 ## [3.1.0-external.0] - 2026-10-02
 
 ### Added

package/README.md

@@ -14,11 +14,13 @@ Six built-in roles are available in memory on every one of those harnesses. A fr
 
 The ordinary driver has four tools (`workflow` can be disabled):
 
-- `Agent` resolves and runs one external role. Its [versioned public receipt](docs/agent-public-contract.md) is available to native Pi codemode; scripts must check `ok`.
+- `Agent` resolves and runs one external role.
 - `workflow` orchestrates multiple external roles with trusted JavaScript.
 - `external_help` returns the usage playbook, role details, permission behavior, or workflow guidance on demand.
 - `external_runs` lists, inspects, waits for, and cancels session-owned runs.
 
+`Agent`, `workflow` and `external_runs` return a [versioned public contract](docs/public-contract.md) to native Pi codemode. Expected failures are returned with a typed `error.code` rather than thrown, so scripts must check `ok`.
+
 `Agent` and `workflow` accept a role with an optional harness — `agy`, `claude`, `codex`, `grok`, `muse`, `opencode`, or a registered `pi-*` name. A registered Pi harness uses that same selection. Legacy exact `subagent_type` remains available and cannot be combined with `role` or `harness`. `pi_flow_role_create` is active only during `/external config role assist`. `pi_flow_harness_create` is active only during `/external config harness assist`. Worked calls are `external_help` topic `usage`.
 
 ## Install
@@ -535,9 +537,9 @@ Agent({
 
 Use `external_runs` with these actions:
 
-- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`.
-- `inspect`: single-entry `runIds` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
-- `inspect` with `runIds` (summary view) (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. The legacy `runId` selector remains accepted by programmatic callers but is no longer advertised to models. A singleton list supports other views; multiple targets require `summary`.
+- `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`. A live run shows live state on the page where its record falls; live runs with no record yet come first and count against `limit`. `nextCursor` means the scan stopped early, not that more rows exist, so a next page can be empty.
+- `inspect`: single-entry `runIds` with `view: "summary" | "output" | "diagnostics" | "final" | "launch"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. Output and diagnostics pages concatenate losslessly. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result). `launch` shows the recorded prompt, shared context and execution configuration; it is sensitive and only for explicit inspection.
+- `inspect` with `runIds` (summary view) (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. A single-entry `runIds` with the summary view (or no view) also returns this batch form; use `view` to read one run's pages instead. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection, which must fit both the text and the structured result; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, the call fails with `page_too_small`, asking you to increase `limitBytes` or inspect that run individually; no target is silently dropped. The legacy `runId` selector remains accepted by programmatic callers but is no longer advertised to models. Multiple targets require `summary`.
 - `wait`: selected `runIds` (one or more), with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work. While waiting, a bounded heartbeat (independent of any single target settling) reports live progress — watched targets, completed/pending counts, and recent activity — through the tool's update channel; it stops automatically on settlement, error, or interruption. Each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response, in the requested `runId`/`runIds` order — never settlement race order, so the same targets and final states spend the budget identically regardless of which one happened to settle first: a result that fits is returned complete, one that does not is truncated with `resultTruncated: true` and the existing `outputRef`/`diagnosticsRef` to continue reading it — not a fixed-length teaser regardless of size. A target's evidence is never read from disk once the shared budget is already exhausted.
 - `cancel`: single-entry `runIds` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
 
@@ -594,7 +596,7 @@ Example request:
 Use the workflow tool to ask role "explorer" on harness "claude" for an architecture map and role "reviewer" on harness "codex" for a risk review, then synthesize their findings.
 ```
 
-Direct `Agent` calls and workflow children share one concurrency limiter (`maxConcurrentSubagents`, default 12) and the same timeout controls. There is no per-harness cap: three `agy` children run together when started together — `parallel([() => agent(..., { harness: "agy" }), ...])` in a workflow, or three `background: true` `Agent` calls in one turn followed by `external_runs wait`. Sequentially `await`ed children stay serial by construction. Direct calls default `executionMode: "parallel"` so top-level `Agent` calls issued together run together. Workflow `agent(prompt, { role, context: { mode: "recent", turns: 5 } })` accepts the same context modes. Every current-version `agent()` returns its value or throws a catchable `ChildRunError` with `runId`, `outcome` (`failed`, `cancelled`, or `timed_out`), `message`, and output/diagnostic references. Catch an optional failure explicitly; an uncaught child error fails the workflow and drains active siblings. `parallel` and `pipeline` preserve this contract and never convert failure to `null`.
+Direct `Agent` calls and workflow children share one concurrency limiter (`maxConcurrentSubagents`, default 12) and the same timeout controls. There is no per-harness cap: three `agy` children run together when started together — `parallel([() => agent(..., { harness: "agy" }), ...])` in a workflow, or three `background: true` `Agent` calls in one turn followed by `external_runs wait`. Sequentially `await`ed children stay serial by construction. Direct calls default `executionMode: "parallel"` so top-level `Agent` calls issued together run together. Workflow `agent(prompt, { role, context: { mode: "recent", turns: 5 } })` accepts the same context modes. Every current-version `agent()` returns its value or throws a catchable `ChildRunError` with `runId`, `outcome` (`failed`, `cancelled`, or `timed_out`), `message`, and output/diagnostic references. Catch an optional failure explicitly; an uncaught child error fails the workflow and drains active siblings. A workflow that succeeded after catching failures stays successful: its receipt counts them in `run.children.failed`, adds the warning `handled_child_failures`, and says so in the text result. `parallel` and `pipeline` preserve this contract and never convert failure to `null`.
 
 Every child selects from one parent snapshot and effective settings frozen at workflow invocation; earlier child results must still be passed explicitly. `resumeFromRunId` is explicit replay for a persisted `scriptPath`: it reuses only the longest unchanged prefix of successful child calls. The API version, transferred context, prompt, selection, and relevant options participate in fingerprints. The first changed, failed, cancelled, or timed-out call and everything after it executes again. Recomposition is cheap, but rerun children may cost money or repeat side effects; the runtime never retries or replays a repaired script automatically.
 

package/docs/public-contract.md

@@ -0,0 +1,110 @@
+# Public contract v1: Agent, workflow and external_runs
+
+`Agent`, `workflow` and `external_runs` declare `outputSchema` and return matching `structuredContent`. Human `content` and renderer `details` stay separate. Native Pi codemode receives the structured result, including failures. **Check `ok`**, not just whether the call threw.
+
+```js
+const receipt = await tools.Agent({ role: "worker", description: "Check build", prompt: "Run the build and report." });
+if (!receipt.ok) return receipt.error;
+return receipt.data.run;
+```
+
+## Envelope
+
+Every result carries:
+- `contractVersion: 1`;
+- `tool` and `action`;
+- an ISO `observedAt` timestamp;
+- `ok`;
+- `data`;
+- `warnings` (strings).
+
+`error: {code, message}` exists only when `ok` is false, and `isError === !ok`. A red tool row therefore means the *operation* failed, not that some target run failed. V1 consumers must ignore unknown fields. Removing fields or changing their meaning requires a new contract version. The host uses the schema for declarations, not to validate output at run time; tests validate actual results.
+
+| Tool | `action` | Success `data` | Failure `data` |
+|---|---|---|---|
+| `Agent` | `delegate` | `{run}` | `{run}`, or `{run: null}` before registration |
+| `workflow` | `run` | `{run}` | `{run}`, or `{run: null}` before registration |
+| `external_runs` | the requested action | the action's payload (below) | `null` |
+
+A failure that has a run keeps that run's evidence. Read-only supervision never returns partial data on failure.
+
+## Runs
+
+A run reports:
+- task identity;
+- registry-confirmed liveness;
+- lifecycle state and outcome;
+- timing;
+- evidence integrity;
+- output availability and delivery;
+- inspect references, where they resolve.
+
+`kind` is `agent` or `workflow`. Supervision adds the status `interrupted_or_uncertain` for unfinished evidence with no live owner. Private evidence paths and launch/configuration details are not included.
+
+**Integrity** is one of:
+- `complete`;
+- `incomplete`: live, or not yet finalized;
+- `damaged`;
+- `unknown`: evidence was not read, or could not be read.
+
+Missing or unreadable evidence never discards a settled result. For a workflow journal:
+- **`complete`:** a start line and a terminal line, with no bad line.
+- **`incomplete`:** there is no terminal line, or only the last line is torn (an unfinished write).
+- **`damaged`:** there is a bad line with records after it, or the run ID does not match.
+- **`unknown`:** the journal version is unsupported or the file is unreadable.
+
+**Delivery.** A complete canonical result is inline (`output.delivery: "inline"`, `output.value`) only within **16 KiB of UTF-8 JSON after secret redaction**. Otherwise it is delivered by reference: `refs.final` points to a pageable `external_runs` inspection. A value is never truncated. False, null, zero and empty strings are valid results. Partial narration is never the canonical value. `warnings` includes `output_redacted` when redaction changed an inlined value. This is best-effort pattern redaction, not a guarantee that arbitrary sensitive prose is caught.
+
+`refs` are ready-to-call `external_runs` arguments:
+- `refs.summary` is a batch inspection with one ID, and returns `{mode: "batch", entries}`.
+- `refs.final` and `refs.diagnostics` are single-run page inspections.
+
+## Workflow receipts
+
+`ok` describes the workflow root:
+- A foreground root that succeeded is `ok: true`.
+- A foreground root that failed, was cancelled or timed out is `ok: false`, with that outcome as `error.code` and its run evidence kept.
+- A background launch is `ok: true` once it is **accepted**. That does not mean it has finished; use `external_runs wait`.
+
+`run.children.count` is the number of indexed `agent()` children. `run.children.failed` counts every failed `agent()` call delivered to the script, including calls that failed before a child was indexed. Failures that are always fatal (an unknown role, the call limit) are excluded, because they fail the root. A root that succeeded after catching child failures stays `ok: true` with the warning `handled_child_failures`, and its `content` says so too. `failed` is absent, meaning unknown, for journals written before it was recorded.
+
+## external_runs payloads
+
+| Action | `data` |
+|---|---|
+| `list` | `{runs, workflows, nextCursor?, nextWorkflowCursor?}`. The two cursor streams are independent. `nextCursor` means the scan stopped early, not that more rows exist; a next page may be empty. A live run with a record appears on the page where that record falls, with live state. Live runs with no record yet (for example, while evidence writes fail) come first and count against `limit`. Their stage of the cursor bookmarks the last one served, so a run saved between pages is never skipped; it can appear twice (once live, once from its record). If the bookmarked run has left the registry, the next page fails with `cursor_stale`; restart without a cursor. A run started after the listing reached its saved rows appears in the next fresh listing. |
+| `inspect` (`runIds`, summary) | `{mode: "batch", entries, nextCursor?}`. An entry is served only if it fits `limitBytes` in **both** the legacy text and the full structured envelope, so both channels carry the same entries and one cursor. If even one entry cannot fit, the error is `page_too_small`; targets are never silently dropped. A one-element `runIds` with the summary view also returns batch entries. |
+| `inspect` (one run) | `{mode: "single", runId, view, page: {text, encoding, complete, nextCursor?}, finalAvailable?, outputStatus?}`. `page.text` is bounded by `limitBytes` in UTF-8 bytes; the envelope adds a small fixed overhead. `encoding` is `json` for agent `summary`/`launch` and for every workflow view, and `text` for agent `output`/`diagnostics`/`final`. JSON pages may be fragments: concatenate one cursor sequence before parsing. Output and diagnostics pages concatenate losslessly, because each new message carries a leading `\n` separator. Unavailable output leaves `page.text` empty, with the human fallback only in `content`. An unavailable `final` is empty with `finalAvailable: false`, never partial narration. A settled successful agent result still held in memory is served as `final` even if its evidence was never saved, so `refs.final` always resolves. A schema-constrained child stores JSON text as its agent final value. |
+| `wait` | `{mode, completed, pending}`, in request order. Pending work is never cancelled, and an unsuccessful workflow returns early. The legacy `content` spends one shared byte budget (`limitBytes`). The structured channel spends its own copy of `limitBytes`, in the same order. A completed run's value is inline only when it is held in memory, its legacy text was delivered whole, and its encoded JSON fits both 16 KiB and what remains of that structured budget. Everything else, including every durable target, is delivered by reference. No evidence is read once the budget is spent. |
+| `cancel` | `{runId, status: "requested" \| "terminal"}`. `requested` does not mean the run has stopped. |
+
+Supervision text is redacted at its source before it is measured or sliced. Durable run records are redacted when written. Memory-sourced text (live output, in-memory wait results, workflow views and journal values) is redacted in full before paging, so `limitBytes` holds and a secret split across a page boundary is still caught.
+
+## Error codes
+
+| Code | Meaning |
+|---|---|
+| `configuration_invalid`, `harness_unavailable`, `selection_invalid`, `model_unavailable`, `context_invalid` | Configuration or selection problems found before launch. `selection_invalid` also covers an unknown saved workflow. |
+| `session_closed` | The owning session closed before the run registered. |
+| `failed`, `cancelled`, `timed_out` | Terminal outcome of the run this receipt is about. |
+| `request_invalid` | Malformed or contradictory parameters (bad ID, both selectors, target count, view, source count). |
+| `run_unavailable` | Unknown, belonging to another session or project, or pruned by retention. These cases are deliberately indistinguishable. Also covers an unreadable journal in this project. |
+| `run_not_live` | The run is in this session but has no live owner and its evidence is not terminal, so a wait cannot complete and a cancel cannot be confirmed. |
+| `cursor_invalid` | A malformed cursor, or one from a different run, view, scope or target set. |
+| `cursor_stale` | The evidence changed while paging, or the cursor predates the current page format. Restart without a cursor. |
+| `page_too_small` | One whole batch entry does not fit `limitBytes`. |
+| `session_unavailable` | Supervision needs a persisted originating session. |
+| `script_invalid` | Workflow parse, `meta` or `apiVersion` failure. Nothing was launched. |
+| `storage_unavailable` | Workflow script or journal persistence failed before registration. |
+
+Still thrown, not returned:
+- an interrupted wait ("Run wait aborted");
+- unexpected exceptions;
+- predispatch schema or permission failures;
+- `tool_call` blocks.
+
+A host redaction hook that replaces content drops structured content unless it explicitly supplies a replacement.
+
+## Discovery
+
+Pi 0.99.2 generates discriminated return types from these schemas through native `describeTool`. The `Agent` input declaration currently loses its input properties, because Pi renders the root `anyOf` constraints before the properties; input validation itself remains intact. This is a known input-discovery limitation, not a runtime validation bypass.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "3.1.0-external.0",
+  "version": "3.2.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",
@@ -9,7 +9,7 @@
     "index.ts",
     "src",
     "scripts/field-report.mjs",
-    "docs/agent-public-contract.md",
+    "docs/public-contract.md",
     "docs/ARCHITECTURE_SNAPSHOT.md",
     "docs/field-testing.md",
     "docs/releasing.md",

package/src/contract/agent.ts

@@ -0,0 +1,29 @@
+import { type JsonObject } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import type { RegisteredRunEntry } from "../core/run-registry.ts";
+import { contractEnvelope, envelope, INLINE_RESULT_BYTES, type PublicError } from "./envelope.ts";
+import { agentRunSchema, liveAgentRun, type EvidenceIntegrity } from "./run.ts";
+
+const agentData = Type.Object({ run: Type.Union([Type.Null(), agentRunSchema]) });
+export const agentOutputSchema = contractEnvelope("Agent", Type.Literal("delegate"), agentData, agentData);
+export type AgentReceipt = Static<typeof agentOutputSchema>;
+
+/** Only registry-confirmed entries may supply a public handle. Never infer liveness from disk. */
+export function agentReceipt({ entry, integrity = "unknown", error, inspectable = true }: {
+  entry?: RegisteredRunEntry;
+  integrity?: EvidenceIntegrity;
+  error?: PublicError;
+  inspectable?: boolean;
+}): AgentReceipt & JsonObject {
+  const warnings: string[] = [];
+  let run = null;
+  if (entry) {
+    const built = liveAgentRun(entry, { integrity, inlineBudget: INLINE_RESULT_BYTES, inspectable });
+    run = built.run;
+    if (built.redacted) warnings.push("output_redacted");
+    if (!error && entry.outcome && entry.outcome.status !== "done") {
+      error = { code: entry.outcome.outcome === "succeeded" ? "failed" : entry.outcome.outcome, message: entry.outcome.error ?? "Child execution failed" };
+    }
+  }
+  return envelope({ tool: "Agent", action: "delegate", data: { run }, warnings, error, redact: true }) as AgentReceipt & JsonObject;
+}

package/src/contract/envelope.ts

@@ -0,0 +1,97 @@
+import { StringEnum, type JsonObject } from "@earendil-works/pi-ai";
+import { Type, type Static, type TSchema } from "typebox";
+import { ExpectedFlowError, FLOW_ERROR_CODES } from "../core/errors.ts";
+import { redactSecrets } from "../core/run-record.ts";
+
+/** Inline cap for a canonical value, in UTF-8 bytes of its redacted JSON. */
+export const INLINE_RESULT_BYTES = 16 * 1024;
+
+export const strings = <T extends string[]>(...values: T) => StringEnum(values);
+export const errorSchema = Type.Object({ code: StringEnum(FLOW_ERROR_CODES), message: Type.String() });
+export type PublicError = Static<typeof errorSchema>;
+
+const envelopeFields = (tool: string, action: TSchema) => ({ contractVersion: Type.Literal(1), tool: Type.Literal(tool), action, observedAt: Type.String(), warnings: Type.Array(Type.String()) });
+
+export function successVariant<S extends TSchema>(tool: string, action: TSchema, data: S) {
+  return Type.Object({ ...envelopeFields(tool, action), ok: Type.Literal(true), data, error: Type.Optional(Type.Never()) });
+}
+
+export function failureVariant<F extends TSchema>(tool: string, action: TSchema, data: F) {
+  return Type.Object({ ...envelopeFields(tool, action), ok: Type.Literal(false), data, error: errorSchema });
+}
+
+/** The versioned envelope shared by every public tool: `ok` discriminates `data` and `error`. */
+export function contractEnvelope<S extends TSchema, F extends TSchema>(tool: string, action: TSchema, success: S, failure: F) {
+  return Type.Union([successVariant(tool, action, success), failureVariant(tool, action, failure)]);
+}
+
+/** Builds one envelope as plain JSON. `redact` re-redacts the whole envelope (Agent and workflow receipts). */
+export function envelope({ tool, action, data, warnings = [], error, redact = false }: {
+  tool: string;
+  action: string;
+  data: unknown;
+  warnings?: string[];
+  error?: PublicError;
+  redact?: boolean;
+}): JsonObject {
+  const base = { contractVersion: 1, tool, action, observedAt: new Date().toISOString(), data, warnings };
+  const value = error ? { ...base, ok: false, error: { code: error.code, message: error.message } } : { ...base, ok: true };
+  return JSON.parse(JSON.stringify(redact ? redactSecrets(value) : value)) as JsonObject;
+}
+
+/** Redacts memory-sourced text in full, before anything measures or slices it. */
+export function redactedText(text: string): string {
+  return redactSecrets(text) as string;
+}
+
+/**
+ * The single canonical-value delivery rule: redact, measure, then inline the
+ * whole value or deliver it by reference. A value is never truncated.
+ */
+export function deliverValue(value: unknown, { finalAvailable, inlineBudget, inspectable }: { finalAvailable: boolean; inlineBudget: number; inspectable: boolean }): {
+  output: { delivery: "inline" | "reference" | "none"; value?: unknown };
+  redacted: boolean;
+} {
+  let encoded: string | undefined;
+  try { encoded = finalAvailable ? JSON.stringify(value) : undefined; } catch { /* Non-JSON values are never presented as complete. */ }
+  const redactedValue = encoded === undefined ? undefined : redactSecrets(JSON.parse(encoded));
+  const redactedEncoded = encoded === undefined ? undefined : JSON.stringify(redactedValue);
+  const inline = redactedEncoded !== undefined && Buffer.byteLength(redactedEncoded, "utf8") <= inlineBudget;
+  return {
+    output: { delivery: inline ? "inline" : finalAvailable && inspectable ? "reference" : "none", ...(inline ? { value: redactedValue } : {}) },
+    redacted: redactedEncoded !== encoded,
+  };
+}
+
+export type TextContent = { type: "text"; text: string };
+
+export interface ContractResult<D = unknown> {
+  content: TextContent[];
+  details: D;
+  data: unknown;
+  warnings?: string[];
+  /** A returned failure keeps the caller's own content, details and data. */
+  error?: PublicError;
+}
+
+/**
+ * Runs one tool body and returns `content`/`details` plus the public
+ * `structuredContent`, with `isError === !ok`. A thrown ExpectedFlowError
+ * becomes a returned failure with `failureData` and `{error, code}` details
+ * (so `D` must accept that shape); anything else is rethrown.
+ */
+export async function withContract<D>(
+  { tool, action, failureData, redact = false }: { tool: string; action: string; failureData: unknown; redact?: boolean },
+  body: () => Promise<ContractResult<D>>,
+): Promise<{ content: TextContent[]; details: D; structuredContent: JsonObject; isError: boolean }> {
+  let settled: ContractResult<D>;
+  try {
+    settled = await body();
+  } catch (error) {
+    if (!(error instanceof ExpectedFlowError)) throw error;
+    settled = { content: [{ type: "text", text: error.message }], details: { error: error.message, code: error.code } as D, data: failureData, error };
+  }
+  const structuredContent = envelope({ tool, action, data: settled.data, warnings: settled.warnings, error: settled.error, redact });
+  const content = redact ? redactSecrets(settled.content) as TextContent[] : settled.content;
+  return { content, details: settled.details, structuredContent, isError: structuredContent.ok !== true };
+}

package/src/contract/run.ts

@@ -0,0 +1,157 @@
+import { Type, type Static, type TProperties } from "typebox";
+import { projectDurableAgent, projectLiveAgent } from "../core/run-projection.ts";
+import type { RunRecordListItem } from "../core/run-inspection.ts";
+import type { RegisteredRunEntry } from "../core/run-registry.ts";
+import type { WorkflowToolDetails } from "../types.ts";
+import type { LoadedWorkflowJournal, UnreadableWorkflowJournal } from "../workflow/journal.ts";
+import { deliverValue, strings } from "./envelope.ts";
+
+export type EvidenceIntegrity = "complete" | "incomplete" | "damaged" | "unknown";
+
+const inspectRef = Type.Object({ tool: Type.Literal("external_runs"), action: Type.Literal("inspect"), runIds: Type.Array(Type.String()), view: strings("summary", "final", "diagnostics") });
+const timing = Type.Object({
+  queuedAt: Type.Optional(Type.String()), executionStartedAt: Type.Optional(Type.String()),
+  processStartedAt: Type.Optional(Type.String()), firstActivityAt: Type.Optional(Type.String()),
+  lastActivityAt: Type.Optional(Type.String()), finishedAt: Type.Optional(Type.String()),
+  queueDelayMs: Type.Optional(Type.Number()), elapsedMs: Type.Optional(Type.Number()),
+  activityAgeMs: Type.Optional(Type.Number()), processDurationMs: Type.Optional(Type.Number()),
+});
+const outcome = strings("succeeded", "failed", "cancelled", "timed_out");
+const optionalStrings = (...names: string[]): TProperties => Object.fromEntries(names.map((name) => [name, Type.Optional(Type.String())]));
+
+/** One PublicRun builder; each tool declares only the kinds, statuses and fields it can return. */
+function publicRunSchema(kind: ReturnType<typeof Type.Literal> | ReturnType<typeof strings>, statuses: ReturnType<typeof strings>, task: TProperties, children: boolean) {
+  return Type.Object({
+    runId: Type.String(), kind, live: Type.Boolean(),
+    task: Type.Object(task),
+    state: Type.Object({ status: statuses, outcome: Type.Optional(outcome) }),
+    timing,
+    output: Type.Object({ available: Type.Boolean(), finalAvailable: Type.Boolean(), delivery: strings("inline", "reference", "none"), value: Type.Optional(Type.Unknown()) }),
+    evidence: Type.Object({ integrity: strings("complete", "incomplete", "damaged", "unknown") }),
+    ...(children ? { children: Type.Optional(Type.Object({ count: Type.Optional(Type.Integer()), failed: Type.Optional(Type.Integer()) })) } : {}),
+    refs: Type.Optional(Type.Object({ summary: inspectRef, final: inspectRef, diagnostics: inspectRef })),
+  });
+}
+
+export const agentRunSchema = publicRunSchema(Type.Literal("agent"), strings("queued", "running", "done", "error", "aborted"), optionalStrings("description", "profile", "backend", "harness"), false);
+export const workflowRunSchema = publicRunSchema(Type.Literal("workflow"), strings("running", "done", "error", "aborted"), optionalStrings("name", "source"), true);
+export const supervisedRunSchema = publicRunSchema(
+  strings("agent", "workflow"),
+  strings("queued", "running", "done", "error", "aborted", "interrupted_or_uncertain"),
+  optionalStrings("description", "profile", "backend", "harness", "workflowRunId", "name", "source"),
+  true,
+);
+type InspectRef = Static<typeof inspectRef>;
+export interface PublicRun {
+  runId: string;
+  kind: "agent" | "workflow";
+  live: boolean;
+  task: Record<string, string>;
+  state: { status: "queued" | "running" | "done" | "error" | "aborted" | "interrupted_or_uncertain"; outcome?: Static<typeof outcome> };
+  timing: Static<typeof timing>;
+  output: { available: boolean; finalAvailable: boolean; delivery: "inline" | "reference" | "none"; value?: unknown };
+  evidence: { integrity: EvidenceIntegrity };
+  children?: { count?: number; failed?: number };
+  refs?: { summary: InspectRef; final: InspectRef; diagnostics: InspectRef };
+}
+
+export function runRefs(runId: string): NonNullable<PublicRun["refs"]> {
+  const ref = (view: "summary" | "final" | "diagnostics") => ({ tool: "external_runs" as const, action: "inspect" as const, runIds: [runId], view });
+  return { summary: ref("summary"), final: ref("final"), diagnostics: ref("diagnostics") };
+}
+
+export interface RunDelivery {
+  /** Evidence integrity; defaults to incomplete while live, unknown once settled without an evidence read. */
+  integrity?: EvidenceIntegrity;
+  /** 0 never inlines (list and batch rows). */
+  inlineBudget?: number;
+  inspectable?: boolean;
+}
+
+interface Built { run: PublicRun; redacted: boolean }
+
+function defaultIntegrity(entry: RegisteredRunEntry): EvidenceIntegrity {
+  return entry.state === "running" ? "incomplete" : "unknown";
+}
+
+function pick(task: Record<string, unknown>, keys: string[]): Record<string, string> {
+  return Object.fromEntries(keys.flatMap((key) => typeof task[key] === "string" ? [[key, task[key] as string]] : []));
+}
+
+/** Only registry-confirmed entries are live; liveness is never inferred from disk. */
+export function liveAgentRun(entry: RegisteredRunEntry, { integrity, inlineBudget = 0, inspectable = true }: RunDelivery = {}): Built {
+  const projected = projectLiveAgent(entry);
+  const finalAvailable = projected.output.finalAvailable;
+  const delivered = deliverValue(entry.outcome?.result, { finalAvailable, inlineBudget, inspectable });
+  return {
+    run: {
+      runId: entry.runId, kind: "agent", live: projected.live,
+      task: pick(projected.task as Record<string, unknown>, ["description", "profile", "backend", "harness", "workflowRunId"]),
+      state: { status: projected.state.status as PublicRun["state"]["status"], ...(entry.outcome ? { outcome: entry.outcome.outcome } : {}) },
+      timing: projected.timing,
+      output: { available: projected.output.available, finalAvailable, ...delivered.output },
+      evidence: { integrity: integrity ?? defaultIntegrity(entry) },
+      ...(inspectable ? { refs: runRefs(entry.runId) } : {}),
+    },
+    redacted: delivered.redacted,
+  };
+}
+
+export function durableAgentRun(item: RunRecordListItem): PublicRun {
+  const projected = projectDurableAgent(item);
+  return {
+    runId: item.runId, kind: "agent", live: false,
+    task: pick(projected.task as Record<string, unknown>, ["description", "profile", "backend", "harness", "workflowRunId"]),
+    state: { status: projected.state.status as PublicRun["state"]["status"], ...(item.outcome ? { outcome: item.outcome } : {}) },
+    timing: item.timing,
+    output: { available: item.outputAvailable, finalAvailable: item.finalAvailable, delivery: item.finalAvailable ? "reference" : "none" },
+    evidence: { integrity: item.integrity },
+    refs: runRefs(item.runId),
+  };
+}
+
+export function liveWorkflowRun(entry: RegisteredRunEntry, { integrity, inlineBudget = 0, inspectable = true }: RunDelivery = {}): Built {
+  const observation = entry.observation as WorkflowToolDetails | undefined;
+  const status = entry.state === "running" ? "running" : entry.outcome?.status ?? "error";
+  const finalAvailable = entry.outcome?.status === "done" && entry.outcome.result !== undefined;
+  const delivered = deliverValue(entry.outcome?.result, { finalAvailable, inlineBudget, inspectable });
+  const count = observation?.agentCount ?? observation?.agents?.length;
+  return {
+    run: {
+      runId: entry.runId, kind: "workflow", live: entry.state === "running",
+      task: pick({ name: observation?.name, source: observation?.source }, ["name", "source"]),
+      state: { status, ...(entry.outcome ? { outcome: entry.outcome.outcome } : {}) },
+      timing: {},
+      output: { available: entry.outcome?.result !== undefined, finalAvailable, ...delivered.output },
+      evidence: { integrity: integrity ?? defaultIntegrity(entry) },
+      children: { ...(count !== undefined ? { count } : {}), ...(observation?.childFailures !== undefined ? { failed: observation.childFailures } : {}) },
+      ...(inspectable ? { refs: runRefs(entry.runId) } : {}),
+    },
+    redacted: delivered.redacted,
+  };
+}
+
+export function journalWorkflowRun(journal: LoadedWorkflowJournal): PublicRun {
+  const finalAvailable = journal.status === "done" && journal.result !== undefined;
+  return {
+    runId: journal.runId, kind: "workflow", live: false,
+    task: pick({ name: journal.name, source: journal.source }, ["name", "source"]),
+    state: { status: journal.status === "running" ? "interrupted_or_uncertain" : journal.status, ...(journal.outcome ? { outcome: journal.outcome } : {}) },
+    timing: {},
+    output: { available: journal.result !== undefined, finalAvailable, delivery: finalAvailable ? "reference" : "none" },
+    evidence: { integrity: journal.integrity },
+    children: { count: journal.children.length, ...(journal.childFailures !== undefined ? { failed: journal.childFailures } : {}) },
+    refs: runRefs(journal.runId),
+  };
+}
+
+/** No refs: inspecting an unreadable journal reports its read error rather than a page. */
+export function unreadableWorkflowRun(journal: UnreadableWorkflowJournal): PublicRun {
+  return {
+    runId: journal.runId, kind: "workflow", live: false, task: {},
+    state: { status: "interrupted_or_uncertain" },
+    timing: {},
+    output: { available: false, finalAvailable: false, delivery: "none" },
+    evidence: { integrity: journal.integrity },
+  };
+}

package/src/contract/runs.ts

@@ -0,0 +1,34 @@
+import { Type } from "typebox";
+import { failureVariant, strings, successVariant } from "./envelope.ts";
+import { supervisedRunSchema } from "./run.ts";
+
+const TOOL = "external_runs";
+const runs = Type.Array(supervisedRunSchema);
+const cursor = Type.Optional(Type.String());
+
+export const SINGLE_INSPECT_VIEWS = ["summary", "output", "diagnostics", "final", "launch"] as const;
+
+/** One success variant per action (inspect has batch and single shapes); every expected failure has `data: null`. */
+export const externalRunsOutputSchema = Type.Union([
+  successVariant(TOOL, Type.Literal("list"), Type.Object({ runs, workflows: runs, nextCursor: cursor, nextWorkflowCursor: cursor })),
+  successVariant(TOOL, Type.Literal("inspect"), Type.Union([
+    Type.Object({ mode: Type.Literal("batch"), entries: runs, nextCursor: cursor }),
+    Type.Object({
+      mode: Type.Literal("single"),
+      runId: Type.String(),
+      view: strings(...SINGLE_INSPECT_VIEWS),
+      page: Type.Object({
+        /** UTF-8 bytes bounded by limitBytes. JSON pages may be fragments: concatenate one cursor sequence before parsing. */
+        text: Type.String(),
+        encoding: strings("json", "text"),
+        complete: Type.Boolean(),
+        nextCursor: cursor,
+      }),
+      finalAvailable: Type.Optional(Type.Boolean()),
+      outputStatus: Type.Optional(strings("preliminary", "final", "interrupted")),
+    }),
+  ])),
+  successVariant(TOOL, Type.Literal("wait"), Type.Object({ mode: strings("any", "all"), completed: runs, pending: Type.Array(Type.String()) })),
+  successVariant(TOOL, Type.Literal("cancel"), Type.Object({ runId: Type.String(), status: strings("requested", "terminal") })),
+  failureVariant(TOOL, strings("list", "inspect", "wait", "cancel"), Type.Null()),
+]);

package/src/contract/workflow.ts

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+import type { RegisteredRunEntry } from "../core/run-registry.ts";
+import { contractEnvelope, INLINE_RESULT_BYTES, type PublicError } from "./envelope.ts";
+import { liveWorkflowRun, workflowRunSchema, type EvidenceIntegrity, type PublicRun } from "./run.ts";
+
+const workflowData = Type.Object({ run: Type.Union([Type.Null(), workflowRunSchema]) });
+/** `ok` describes the workflow operation: a background launch is accepted, a foreground one settled successfully. */
+export const workflowOutputSchema = contractEnvelope("workflow", Type.Literal("run"), workflowData, workflowData);
+
+export const HANDLED_CHILD_FAILURES = "handled_child_failures";
+
+/**
+ * The public receipt for one registered workflow. A foreground root that
+ * succeeded after handling child failures stays ok, with a warning; an
+ * unsuccessful root is a failed operation that keeps its run evidence.
+ */
+export function workflowReceipt(entry: RegisteredRunEntry, { integrity, inspectable }: { integrity?: EvidenceIntegrity; inspectable: boolean }): {
+  data: { run: PublicRun };
+  warnings: string[];
+  error?: PublicError;
+} {
+  const built = liveWorkflowRun(entry, { integrity, inlineBudget: INLINE_RESULT_BYTES, inspectable });
+  const warnings: string[] = [];
+  if (built.redacted) warnings.push("output_redacted");
+  const outcome = entry.outcome;
+  if (outcome && outcome.status !== "done") {
+    return { data: { run: built.run }, warnings, error: { code: outcome.outcome === "succeeded" ? "failed" : outcome.outcome, message: outcome.error ?? "Workflow failed" } };
+  }
+  if (outcome && (built.run.children?.failed ?? 0) > 0) warnings.push(HANDLED_CHILD_FAILURES);
+  return { data: { run: built.run }, warnings };
+}