@bastani/atomic 0.8.28-alpha.4 → 0.8.29-alpha.2

package/dist/builtin/web-access/github-extract.ts

@@ -78,7 +78,7 @@ function loadGitHubConfig(): GitHubCloneConfig {
 		enabled: true,
 		maxRepoSizeMB: 350,
 		cloneTimeoutSeconds: 30,
-		clonePath: "/tmp/pi-github-repos",
+		clonePath: "/tmp/atomic-github-repos",
 	};
 
 	if (!existsSync(CONFIG_PATH)) {

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.8.28-alpha.4",
+  "version": "0.8.29-alpha.2",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [
@@ -30,7 +30,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.78.1"
+    "@earendil-works/pi-tui": "^0.79.3"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {
@@ -43,7 +43,7 @@
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.12",
-    "p-limit": "^6.1.0",
+    "p-limit": "^7.3.0",
     "turndown": "^7.2.0",
     "unpdf": "^1.6.2"
   }

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,50 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Added opt-in schema-backed workflow item results: `ctx.stage(..., { schema })`, `ctx.task(..., { schema })`, `ctx.chain` items, and `ctx.parallel` items now receive a schema-specific `structured_output` tool only for that item, require the final tool call, return the parsed value from `ctx.stage().prompt(...)`, and expose parsed task values as `result.structured` while preserving formatted JSON handoff text ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+
+### Changed
+
+- Aligned the workflows extension with upstream pi TUI `^0.79.3` so workflow graph, custom UI, and prompt-broker integrations inherit the latest shared TUI compatibility fixes.
+- Documented the opt-in `structured_output` workflow path and clarified that ordinary workflow stages do not receive `structured_output` from the default tool registry; schema-enabled items auto-add the runtime tool to explicit `tools` allowlists ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Clarified that workflow `structured_output` gate schemas must be top-level object tool-argument schemas, with arrays and primitives wrapped in object fields before being returned through the terminating tool, and documented the one-`prompt()` limit for schema-backed `StageContext` result contracts ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Documented that terminating workflow-stage `structured_output` JSON stays inline even when large, while artifact-sized handoffs should still be saved to files when downstream stages do not need the full payload in context ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+
+### Fixed
+
+- Fixed direct workflow tool validation so schema-enabled `task`, `tasks`, `chain`, and `parallel` items reject array or primitive structured-output schemas at argument-validation time while accepting the same object-root contracts as runtime validation, including object-only `allOf` schemas ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed schema-backed workflow stages to fail with a clear stage-level error when `prompt()` is called more than once on the same `StageContext`, rather than surfacing the lower-level structured-output single-use guard ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed schema-backed workflow model fallback so an attempt that already captured a valid terminating `structured_output` result is treated as successful instead of retrying against fallback models and tripping the single-use result guard ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed the workflow graph overlay remaining interactive when the parent/main-chat agent opens `ask_user_question`: the graph keeps focus, the parent question stays pending behind it with a clear “Main chat needs input — exit graph to answer.” status hint, hiding/exiting the graph focuses the pending question, and host custom-UI state changes no longer hide, restore, remount, or repaint the overlay ([#1353](https://github.com/bastani-inc/atomic/issues/1353)).
+
+## [0.8.28] - 2026-06-11
+
+### Added
+
+- Added workflow `ctx.ui.custom<T>(factory, options?)` for graph-visible custom TUI human-in-the-loop prompts. Custom prompts create `awaiting_input` prompt nodes, reuse the stage UI broker/attached stage chat component path, expose the same real TUI/theme/keybinding/component types as Atomic extension custom UI, participate in live-memory prompt replay through hashed custom identities, honor prompt/run abort signals, and reject clearly in headless/unavailable UI modes ([#1309](https://github.com/bastani-inc/atomic/issues/1309)).
+- Added workflow authoring `ctx.exit(options?)` for intentional early terminal runs from any call depth, supporting `completed`, `skipped`, `cancelled`, and `blocked` terminal statuses, optional persisted/displayed reasons, and partial declared outputs with strict validation for provided output keys. Public run/detail/child status unions widen with `skipped`, `cancelled`, and `blocked`, and child workflow results are discriminated by `exited`.
+- Added workflow stage/task `bashPolicy` wiring so individual workflow stages can constrain the built-in `bash` tool with command-level allow/deny rules, command-string glob matching, fail-closed invalid-policy validation, and default-allow no-rule compatibility.
+
+### Changed
+
+- Changed the builtin `deep-research-codebase`, `goal`, `ralph`, and `open-claude-design` workflows to use `anthropic/claude-fable-5:xhigh` as the primary planner/reviewer/design model, demoting each previous primary to the head of the fallback chain ([#1345](https://github.com/bastani-inc/atomic/pull/1345)).
+- Changed workflow transcript introspection to return `sessionFile`/`transcriptPath` metadata with a lazy-read prompt by default when a transcript path exists, keeping bounded inline previews behind explicit `tail`/`limit` requests ([#1314](https://github.com/bastani-inc/atomic/issues/1314)).
+
+### Fixed
+
+- Fixed a workflow kill/abort race that could crash the entire CLI with a process-level uncaught exception when a workflow was killed mid-prompt; `raceAbort` now always observes the in-flight promise in the already-aborted branch so a killed run can no longer orphan a rejecting prompt.
+- Fixed `ctx.exit(...)` cleanup races across the executor: the selected exit is a level-triggered gate so delayed `ctx.stage`/`ctx.task`/`ctx.chain`/`ctx.parallel`/`ctx.workflow`/graph-backed `ctx.ui.*` calls and retained `StageContext` session-control methods no longer create artifacts after exit, queued `ctx.parallel` work stops after exit, parent exits cancel linked hidden child workflows with typed parent-exit abort reasons and exactly-once stage-end ordering, and prompt-node abort handling preserves `workflow-exit` skipped reasons.
+- Fixed terminal run-end reconciliation after `ctx.exit(...)` so when an external kill or another terminal writer wins `Store.recordRunEnd(...)`, the returned `RunResult` and `onRunEnd` callback report the canonical store status and only the winning run-end write is persisted.
+- Fixed workflow-boundary child-edge metadata cleanup for `ctx.exit(...)` and continuation replay: skipped/failed boundaries clear `workflowChild`/`workflowChildRun`, stage-end persistence only emits child replay metadata for completed boundary stages, and expanded graph views no longer flatten stale child stages.
+- Fixed `ctx.exit({ outputs })` payload capture to snapshot outputs by value at the first selected exit call, and deep-froze the thrown exit signal so author code cannot rewrite the terminal status, reason, or outputs after the fact.
+- Fixed continuation replay races where replayed stage `prompt`/`complete` or prompt-node finalizers could complete after a concurrent `ctx.exit(...)`; pending replay finalizers now re-check the exit gate so resumed runs skip those stages instead of writing misleading completed stage-end entries.
+- Fixed control-signal probing for arbitrary workflow-thrown values and abort reasons to use non-throwing reads, so throwing or inaccessible author accessors no longer leak from the executor catch path.
+- Fixed interactive `ctx.ui.*` handling so workflow runs degrade gracefully: every primitive is guarded against method-less UI adapters with a clear per-method error, and headless (non-interactive) runs without a UI adapter reject with an explicit actionable message ([#1339](https://github.com/bastani-inc/atomic/issues/1339)).
+- Fixed the builtin `open-claude-design` workflow not installing the browser skill's `browse` CLI before it is needed: a deterministic best-effort setup step probes `PATH` and installs the CLI when missing, per-run bootstrap guidance is injected into every browser-using stage, the install outcome is exposed via a new `browse_cli_status` output, and read-only `read`/`grep`/`ls` tools are granted to the refinement and pre-export decision gates ([#1327](https://github.com/bastani-inc/atomic/issues/1327)).
+- Fixed paused workflow runs being counted as running in `/workflow status` (now shown separately as `❚❚ paused`) and run detail cards to surface the natural `workflow resume` action hint ([#1283](https://github.com/bastani-inc/atomic/issues/1283)).
+
 ## [0.8.28-alpha.4] - 2026-06-11
 
 ### Changed

package/dist/builtin/workflows/README.md

@@ -264,6 +264,24 @@ Worktree semantics:
 
 For advanced integrations, the SDK also exports `setupGitWorktree(options)`, which returns `{ worktreeRoot, cwd, repositoryRoot, created }` and uses the same validation/path behavior as the executor.
 
+### Structured stage results
+
+`structured_output` is opt-in for workflow items. Add `schema` to `ctx.stage`, `ctx.task`, `ctx.chain` items, or `ctx.parallel` items when the stage must finish with machine-readable JSON:
+
+```typescript
+const Decision = Type.Object({
+  approved: Type.Boolean(),
+  findings: Type.Array(Type.String()),
+}, { additionalProperties: false });
+
+const decision = await ctx.stage("review-gate", { schema: Decision }).prompt(
+  "Review the artifact and return the decision.",
+);
+// decision.approved is typed from the schema.
+```
+
+Atomic registers the canonical `structured_output` tool only for schema-enabled items, automatically adds it to explicit `tools` allowlists, and fails the item if the model completes without the final tool call. The schema is used directly as the tool argument contract, so wrap arrays or primitives in an object field such as `{ items: [...] }` or `{ value: ... }`. A schema-backed `StageContext` supports one `prompt()` call because the final-answer tool is an exact-once result contract; create another `ctx.stage(..., { schema })` for another structured prompt. `ctx.task`/`ctx.chain`/`ctx.parallel` results expose the parsed value as `result.structured` and keep `result.text` as formatted JSON for handoffs.
+
 ### Model fallbacks
 
 Stages and high-level task helpers can retry transient provider/model failures with an ordered `fallbackModels` list. The primary `model` is tried first, then each fallback, and finally the current Atomic-selected model when available. Fallbacks are only used for retryable model/provider failures such as rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — ordinary tool, shell, validation, cancellation, and workflow-code failures are not retried.
@@ -501,7 +519,7 @@ Prompt answer replay is live-memory only. `StageSnapshot.promptAnswerState` repo
     "async": "optional boolean to dispatch a run in the background",
     "intercom": "optional intercom coordination options",
     "chainDir": "optional directory for direct chain artifacts",
-    "session/task options": "per-stage overrides also accepted at the top level and on direct task items — model, thinkingLevel, fallbackModels, tools, noTools, customTools, mcp, context, cwd, output, outputMode, reads, worktree, gitWorktreeDir, baseBranch, maxOutput, artifacts, and more"
+    "session/task options": "per-stage overrides also accepted at the top level and on direct task items — schema, model, thinkingLevel, fallbackModels, tools, noTools, customTools, mcp, context, cwd, output, outputMode, reads, worktree, gitWorktreeDir, baseBranch, maxOutput, artifacts, and more"
   }
 }
 ```

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.28-alpha.4",
+  "version": "0.8.29-alpha.2",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -83,7 +83,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.78.1"
+    "@earendil-works/pi-tui": "^0.79.3"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/workflows/skills/research-codebase/SKILL.md

@@ -65,10 +65,24 @@ The user's research question/request is: **$ARGUMENTS**
         - The agent fetches live web content using the **browser** skill's `browse` CLI (or `npx browse` / `curl`). Instruct it to apply the token-efficient fetch order: (1) try `curl https://<site>/llms.txt` for an AI-friendly index (see [llmstxt.org](https://llmstxt.org/llms.txt)), (2) try `curl <url> -H "Accept: text/markdown"` to get pre-converted Markdown (supported on Cloudflare-hosted docs via [Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)), (3) fall back to HTML parsing via `browse`
         - Instruct the agent to return LINKS with their findings and INCLUDE those links in the research document
         - The agent should persist reusable source documents under `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` (with frontmatter noting `source_url`, `fetched_at`, and `fetch_method`) so future research can reuse them without re-fetching
-        - Output directory for the synthesized research artifact: `research/docs/`
+        - Output directory for the synthesized web research artifacts: `research/web/`:
+
+          When you fetch a document that is worth keeping for future sessions (reference docs, API schemas, SDK guides, release notes, troubleshooting writeups, architecture articles), `write` it to `research/web/<YYYY-MM-DD>-<kebab-case-topic>.md` with frontmatter capturing:
+          
+          ```markdown
+          ---
+          source_url: <original URL>
+          fetched_at: <YYYY-MM-DD>
+          fetch_method: read | llms.txt | markdown-accept-header | browser | browse
+          topic: <short description>
+          ---
+          ```
+
+        - Followed by the extracted content (trimmed of nav chrome, ads, and irrelevant boilerplate). This lets future work reuse the lookup without re-fetching. Before fetching anything, quickly `find research/web/` for an existing, recent copy.
+
         - Examples:
-            - If researching `Redis` locks usage, the agent might find relevant usage and create a document `research/docs/2024-01-15-redis-locks-usage.md` with internal links to Redis docs and code references (and cache the fetched Redis docs under `research/web/`)
-            - If researching `OAuth` flows, the agent might find relevant external articles and create a document `research/docs/2024-01-16-oauth-flows.md` with links to those articles
+            - If researching `Redis` locks usage, the agent might find relevant usage and create a document `research/web/2024-01-15-redis-locks-usage.md` with internal links to Redis docs and code references (and cache the fetched Redis docs under `research/web/`)
+            - If researching `OAuth` flows, the agent might find relevant external articles and create a document `research/web/2024-01-16-oauth-flows.md` with links to those articles
 
     The key is to use these agents intelligently:
     - Start with locator agents to find what exists

package/dist/builtin/workflows/src/extension/wiring.ts

@@ -253,7 +253,7 @@ async function createTestAgentSession(_options?: CreateAgentSessionOptions): Pro
 function stripWorkflowOnlyOptions(options: (StageOptions | CreateAgentSessionOptions) | undefined): CreateAgentSessionOptions | undefined {
   if (!options) return options;
   const maybeWorkflowOptions = options as StageOptions;
-  const { mcp: _mcp, fallbackModels: _fallbackModels, ...sessionOptions } = maybeWorkflowOptions;
+  const { schema: _schema, mcp: _mcp, fallbackModels: _fallbackModels, ...sessionOptions } = maybeWorkflowOptions;
   return sessionOptions as CreateAgentSessionOptions;
 }
 
@@ -499,6 +499,14 @@ export interface PiOverlayHandle {
  * (`overlay-adapter.ts`); inline pickers leave it unset and dismiss
  * via the factory `done()` callback.
  */
+export interface PiHostCustomUiState {
+  blockingInlineCustomUiDepth: number;
+  blockingInlineCustomUiActive: boolean;
+  blockingInlineCustomUiFocusDeferred?: boolean;
+}
+
+export type PiHostCustomUiStateListener = (state: PiHostCustomUiState) => void;
+
 export interface PiCustomOverlayOptions {
   /**
    * `true` mounts a floating popup; `false` mounts a focused
@@ -506,6 +514,8 @@ export interface PiCustomOverlayOptions {
    * place of the editor until the factory's `done()` callback fires.
    */
   overlay: boolean;
+  /** Keep host inline custom UI pending in the background while this overlay is visible. */
+  deferInlineCustomUiFocus?: boolean;
   /**
    * Geometry / anchoring intended for pi-tui's `resolveOverlayLayout`.
    * NOT forwarded by current pi interactive `custom()` — see
@@ -636,6 +646,12 @@ export interface PiUISurface {
   setTitle?: (title: string) => void;
   /** Show a custom component or overlay. */
   custom?: PiCustomOverlayFunction;
+  /** Get host-owned inline custom UI focus state, if exposed by the host. */
+  getHostCustomUiState?: () => PiHostCustomUiState;
+  /** Observe host-owned inline custom UI focus state changes, if exposed by the host. */
+  onHostCustomUiStateChange?: (listener: PiHostCustomUiStateListener) => () => void;
+  /** Move focus to a mounted host-owned inline custom UI, if one is pending. */
+  focusHostInlineCustomUi?: () => boolean;
   pasteToEditor?: (text: string) => void;
   setEditorText?: (text: string) => void;
   getEditorText?: () => string;

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -37,6 +37,39 @@ const McpOptionsSchema = Type.Object({
   deny: Type.Optional(Type.Array(Type.String())),
 });
 
+const JsonSchemaObjectTypeValue = {
+  anyOf: [
+    { const: "object" },
+    { type: "array", minItems: 1, maxItems: 1, items: { const: "object" } },
+  ],
+};
+
+const JsonSchemaExplicitObjectDescriptor = {
+  type: "object",
+  required: ["type"],
+  properties: { type: JsonSchemaObjectTypeValue },
+  additionalProperties: true,
+};
+
+const JsonSchemaObject = Type.Unsafe<Record<string, unknown>>({
+  description: "Top-level object JSON Schema used as structured_output tool arguments for this workflow item.",
+  anyOf: [
+    JsonSchemaExplicitObjectDescriptor,
+    {
+      type: "object",
+      required: ["allOf"],
+      properties: {
+        allOf: {
+          type: "array",
+          minItems: 1,
+          items: JsonSchemaExplicitObjectDescriptor,
+        },
+      },
+      additionalProperties: true,
+    },
+  ],
+});
+
 const BashCommandRuleSchema = Type.Union([
   Type.String(),
   Type.Object({ prefix: Type.String() }, { additionalProperties: false }),
@@ -55,6 +88,7 @@ const BashCommandPolicySchema = Type.Object({
 }, { additionalProperties: false });
 
 const StageSessionOptionProperties = {
+  schema: Type.Optional(JsonSchemaObject),
   cwd: Type.Optional(Type.String()),
   agentDir: Type.Optional(Type.String()),
   authStorage: Type.Optional(SdkSessionOptionSchema("authStorage")),

package/dist/builtin/workflows/src/runs/foreground/executor.ts

@@ -1267,6 +1267,15 @@ function truncateByBytes(text: string, maxBytes: number): { text: string; trunca
   return { text: text.slice(0, low), truncated: true };
 }
 
+function structuredTaskOutputText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    throw new Error(`atomic-workflows: structured task output is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 function truncateTaskOutput(text: string, maxOutput: WorkflowMaxOutput | undefined): string {
   const limits = normalizeMaxOutput(maxOutput);
   const byLines = truncateByLines(text, limits.lines);
@@ -4827,11 +4836,12 @@ export async function run<TInputs extends WorkflowInputValues>(
           taskStageOptions(resolvedTaskOptions),
           stageFailFastScope,
         );
-        const rawText = await stage.prompt(
+        const rawOutput = await stage.prompt(
           applyTaskContext(`${taskReadInstruction(resolvedTaskOptions)}${taskPrompt(resolvedTaskOptions)}`, taskPrevious(resolvedTaskOptions)),
           taskPromptOptions(resolvedTaskOptions),
         );
-        const text = truncateTaskOutput(rawText, resolvedTaskOptions.maxOutput);
+        const structured = typeof rawOutput === "string" ? undefined : rawOutput;
+        const text = truncateTaskOutput(structuredTaskOutputText(rawOutput), resolvedTaskOptions.maxOutput);
         const sessionId = (() => {
           try {
             return stage.sessionId;
@@ -4844,6 +4854,7 @@ export async function run<TInputs extends WorkflowInputValues>(
           name,
           stageName: name,
           text,
+          ...(structured !== undefined ? { structured: structured as WorkflowSerializableValue } : {}),
           ...(sessionId !== undefined ? { sessionId } : {}),
           ...(stage.sessionFile !== undefined ? { sessionFile: stage.sessionFile } : {}),
           ...(stageMeta.model !== undefined ? { model: stageMeta.model } : {}),

package/dist/builtin/workflows/src/runs/foreground/stage-runner.ts

@@ -10,11 +10,14 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import {
+  createStructuredOutputCapture,
+  createStructuredOutputTool,
   shouldApplyCodexFastModeForScope,
   SessionManager,
   type AgentSession,
   type CreateAgentSessionOptions,
   type PromptOptions,
+  type StructuredOutputCapture,
 } from "@bastani/atomic";
 import type {
   CompleteStageOpts,
@@ -28,6 +31,7 @@ import type {
   WorkflowExecutionMode,
   WorkflowModelCatalogPort,
 } from "../../shared/types.js";
+import type { Static, TSchema } from "typebox";
 import {
   buildModelCandidatesFromCatalog,
   errorMessage,
@@ -167,6 +171,7 @@ export interface InternalStageContext extends StageContext {
 function stripWorkflowOnlyOptions(options: StageOptions | undefined): CreateAgentSessionOptions {
   if (!options) return {};
   const {
+    schema: _schema,
     mcp: _mcp,
     fallbackModels: _fallbackModels,
     fallbackThinkingLevels: _fallbackThinkingLevels,
@@ -530,6 +535,43 @@ function splitPromptOptions(options: StagePromptOptions | undefined): {
   };
 }
 
+const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
+
+function structuredOutputPrompt(text: string): string {
+  return `${text}\n\nFinal output contract:\n- Your final action MUST be a structured_output tool call.\n- Pass the schema fields directly as tool arguments; do not wrap them in { value: ... } unless the schema explicitly defines a top-level value field.\n- Do not emit a prose final answer instead of structured_output.\n- If you need to inspect files or run commands first, do so, then call structured_output exactly once.`;
+}
+
+function stringifyStructuredOutputValue(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    throw new Error(`atomic-workflows: structured_output returned a non-serializable value: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function stageOptionsWithStructuredOutput(
+  options: StageOptions | undefined,
+  capture: StructuredOutputCapture<unknown> | undefined,
+): StageOptions | undefined {
+  if (!options?.schema || !capture) return options;
+  const tools = options.tools === undefined
+    ? undefined
+    : Array.from(new Set([...options.tools, STRUCTURED_OUTPUT_TOOL_NAME]));
+  const excludedTools = options.excludedTools?.filter((toolName) => toolName !== STRUCTURED_OUTPUT_TOOL_NAME);
+  return {
+    ...options,
+    ...(tools !== undefined ? { tools } : {}),
+    ...(excludedTools !== undefined ? { excludedTools } : {}),
+    customTools: [
+      ...(options.customTools ?? []),
+      createStructuredOutputTool({
+        schema: options.schema as TSchema,
+        capture: capture as StructuredOutputCapture<Static<TSchema>>,
+      }),
+    ],
+  };
+}
+
 function validatePromptOutputOptions(outputOptions: StageOutputOptions): void {
   if (outputOptions.outputMode === "file-only" && (typeof outputOptions.output !== "string" || outputOptions.output.length === 0)) {
     throw new Error(
@@ -564,7 +606,9 @@ async function finalizePromptOutput(
 
 export function createStageContext(opts: StageRunnerOpts): InternalStageContext {
   const { stageId, stageName, adapters, runId, signal, stageOptions, executionMode } = opts;
-  const meta: StageExecutionMeta = { runId, stageId, stageName, signal, stageOptions, executionMode };
+  const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<unknown>() : undefined;
+  const effectiveStageOptions = stageOptionsWithStructuredOutput(stageOptions, structuredOutputCapture);
+  const meta: StageExecutionMeta = { runId, stageId, stageName, signal, stageOptions: effectiveStageOptions, executionMode };
   let session: StageSessionRuntime | undefined;
   let sessionPromise: Promise<StageSessionRuntime> | undefined;
   let lastAssistantText: string | undefined;
@@ -633,7 +677,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   }
 
   const hasExplicitModelFallbackConfig =
-    stageOptions?.model !== undefined || (stageOptions?.fallbackModels?.length ?? 0) > 0;
+    effectiveStageOptions?.model !== undefined || (effectiveStageOptions?.fallbackModels?.length ?? 0) > 0;
   let candidatesPromise: Promise<WorkflowResolvedModelCandidate[]> | undefined;
   let activeCandidateIndex: number | undefined;
   let selectedModel: string | undefined;
@@ -653,9 +697,9 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   function modelCandidates(): Promise<WorkflowResolvedModelCandidate[]> {
     if (!candidatesPromise) {
       candidatesPromise = buildModelCandidatesFromCatalog({
-        primaryModel: stageOptions?.model,
-        fallbackModels: stageOptions?.fallbackModels,
-        fallbackThinkingLevels: stageOptions?.fallbackThinkingLevels,
+        primaryModel: effectiveStageOptions?.model,
+        fallbackModels: effectiveStageOptions?.fallbackModels,
+        fallbackThinkingLevels: effectiveStageOptions?.fallbackThinkingLevels,
         catalog: modelCatalog,
       });
     }
@@ -663,9 +707,9 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   }
 
   function stageOptionsForCandidate(candidate: WorkflowResolvedModelCandidate | undefined): StageOptions | undefined {
-    if (candidate === undefined) return stageOptions;
+    if (candidate === undefined) return effectiveStageOptions;
     return {
-      ...(stageOptions ?? {}),
+      ...(effectiveStageOptions ?? {}),
       model: candidate.value,
       ...(candidate.reasoningLevel !== undefined ? { thinkingLevel: candidate.reasoningLevel } : {}),
       fallbackModels: undefined,
@@ -677,7 +721,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
   function isWorkflowFastModeEnabled(): boolean | undefined {
     const model = session?.model;
-    const settingsManager = sessionSettingsManager ?? stageOptions?.settingsManager;
+    const settingsManager = sessionSettingsManager ?? effectiveStageOptions?.settingsManager;
     if (model === undefined || settingsManager === undefined) return undefined;
     return shouldApplyCodexFastModeForScope(model, settingsManager.getCodexFastModeSettings(), "workflow");
   }
@@ -705,7 +749,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
   }
 
   function effectiveCandidateReasoning(candidate: WorkflowResolvedModelCandidate): StageOptions["thinkingLevel"] | undefined {
-    return candidate.reasoningLevel ?? stageOptions?.thinkingLevel;
+    return candidate.reasoningLevel ?? effectiveStageOptions?.thinkingLevel;
   }
 
   function modelAttemptReasoning(candidate: WorkflowResolvedModelCandidate): Pick<WorkflowModelAttempt, "reasoningLevel"> {
@@ -715,7 +759,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
   function applyCandidateThinking(candidate: WorkflowResolvedModelCandidate | undefined): void {
     pendingThinkingLevel = candidate === undefined
-      ? stageOptions?.thinkingLevel
+      ? effectiveStageOptions?.thinkingLevel
       : effectiveCandidateReasoning(candidate);
   }
 
@@ -843,6 +887,13 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     }
 
     let index = activeCandidateIndex ?? 0;
+    const capturedStructuredOutputForAttempt = (): boolean =>
+      structuredOutputCapture?.called === true && signal?.aborted !== true;
+    const recordSuccessfulAttempt = (candidate: WorkflowResolvedModelCandidate): void => {
+      modelAttempts.push({ model: candidate.id, success: true, ...modelAttemptReasoning(candidate) });
+      pendingFallbackWarnings.length = 0;
+    };
+
     while (index < candidates.length) {
       const candidate = candidates[index]!;
       const activeSession = session && activeCandidateIndex === index
@@ -855,13 +906,20 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
         const { terminalScanStartIndex } = await promptWithPauseResume(activeSession, text, sdkOptions);
         const terminalFailure = latestTerminalAssistantFailureSince(activeSession.messages, terminalScanStartIndex);
         if (terminalFailure !== undefined) {
+          if (capturedStructuredOutputForAttempt()) {
+            recordSuccessfulAttempt(candidate);
+            return;
+          }
           throw new WorkflowPromptModelFailure(terminalFailure);
         }
-        modelAttempts.push({ model: candidate.id, success: true, ...modelAttemptReasoning(candidate) });
-        pendingFallbackWarnings.length = 0;
+        recordSuccessfulAttempt(candidate);
         return;
       } catch (err) {
         const message = errorMessage(err);
+        if (capturedStructuredOutputForAttempt() && isRetryableModelFailure(err)) {
+          recordSuccessfulAttempt(candidate);
+          return;
+        }
         modelAttempts.push({ model: candidate.id, success: false, ...modelAttemptReasoning(candidate), error: message });
         if (signal?.aborted || !isRetryableModelFailure(err) || index === candidates.length - 1) {
           modelWarnings.push(...pendingFallbackWarnings);
@@ -887,15 +945,29 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
     async prompt(text, options) {
       const { sdkOptions, outputOptions } = splitPromptOptions(options);
-      const runtimeCwd = typeof stageOptions?.cwd === "string" ? stageOptions.cwd : process.cwd();
+      const runtimeCwd = typeof effectiveStageOptions?.cwd === "string" ? effectiveStageOptions.cwd : process.cwd();
       validatePromptOutputOptions(outputOptions);
+      if (structuredOutputCapture?.called) {
+        throw new Error("atomic-workflows: stage schema supports one prompt() call per stage context because structured_output may be called exactly once. Create a new ctx.stage(...) for each additional schema-backed prompt.");
+      }
       if (adapters.prompt) {
+        if (structuredOutputCapture) {
+          throw new Error("atomic-workflows: stage schema requires an AgentSessionAdapter so the structured_output tool can be registered.");
+        }
         const rawText = await adapters.prompt.prompt(text, meta);
         lastAssistantText = await finalizePromptOutput(rawText, outputOptions, runtimeCwd);
         adapterMessages = assistantMessage(lastAssistantText);
         return lastAssistantText;
       }
-      await promptWithFallback(text, sdkOptions);
+      await promptWithFallback(structuredOutputCapture ? structuredOutputPrompt(text) : text, sdkOptions);
+      if (structuredOutputCapture) {
+        if (!structuredOutputCapture.called) {
+          throw new Error("atomic-workflows: stage configured with schema must finish by calling structured_output.");
+        }
+        const rawStructuredText = stringifyStructuredOutputValue(structuredOutputCapture.value);
+        lastAssistantText = await finalizePromptOutput(rawStructuredText, outputOptions, runtimeCwd);
+        return structuredOutputCapture.value as never;
+      }
       const rawText = lastAssistantTextFromSession(session, lastAssistantText, terminatingToolCallIds) ?? "";
       lastAssistantText = await finalizePromptOutput(rawText, outputOptions, runtimeCwd);
       return lastAssistantText;

package/dist/builtin/workflows/src/shared/authoring-contract.d.ts

@@ -48,6 +48,7 @@ export interface WorkflowModelFallbackFields {
     readonly fallbackThinkingLevels?: readonly string[];
 }
 export type WorkflowModelValue = string | object;
+export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> = [TSchemaDef] extends [TSchema] ? Static<TSchemaDef> : string;
 export interface WorkflowModelUsage extends WorkflowSerializableObject {
     readonly input?: number;
     readonly output?: number;
@@ -111,7 +112,9 @@ export interface WorkflowFastModeSettings extends WorkflowSerializableObject {
 export interface WorkflowFastModeSettingsManager {
     getCodexFastModeSettings(): WorkflowFastModeSettings;
 }
-export interface StageOptions extends WorkflowModelFallbackFields {
+export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> extends WorkflowModelFallbackFields {
+    /** Optional structured final-answer schema. When set, the stage receives a schema-specific `structured_output` tool and must finish by calling it. */
+    readonly schema?: TSchemaDef;
     readonly model?: WorkflowModelValue;
     readonly mcp?: StageMcpOptions;
     readonly tools?: readonly string[];
@@ -231,9 +234,9 @@ export interface StageAdapters {
     readonly prompt?: PromptAdapter;
     readonly complete?: CompleteAdapter;
 }
-export interface StageContext {
+export interface StageContext<TSchemaDef extends TSchema | undefined = undefined> {
     readonly name: string;
-    prompt(text: string, options?: StagePromptOptions): Promise<string>;
+    prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
     complete(text: string, options?: CompleteStageOpts): Promise<string>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
@@ -279,6 +282,8 @@ export interface WorkflowTaskContext extends WorkflowSerializableObject {
 export type WorkflowTaskContextInput = string | WorkflowTaskContext | WorkflowTaskResult;
 export interface WorkflowTaskResult extends WorkflowTaskContext {
     readonly stageName: string;
+    /** Parsed structured value when the task/stage was configured with `schema`. */
+    readonly structured?: WorkflowSerializableValue;
     readonly sessionId?: string;
     readonly sessionFile?: string;
     readonly artifacts?: readonly WorkflowArtifact[];
@@ -400,6 +405,9 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
     readonly inputs: Readonly<TInputs>;
     readonly cwd?: string;
     exit(options?: WorkflowExitOptions<TOutputs>): never;
+    stage<TSchemaDef extends TSchema>(name: string, options: StageOptions<TSchemaDef> & {
+        readonly schema: TSchemaDef;
+    }): StageContext<TSchemaDef>;
     stage(name: string, options?: StageOptions): StageContext;
     task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
     chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;

package/dist/builtin/workflows/src/shared/types.ts

@@ -153,9 +153,11 @@ export interface StageMcpOptions extends AuthoringContract.StageMcpOptions {
  * All pi SDK createAgentSession options are forwarded to the stage session;
  * workflow-owned options such as `mcp` and `gitWorktreeDir` are stripped before SDK session creation.
  */
-export interface StageOptions
+export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined>
   extends Omit<CreateAgentSessionOptions, "model" | keyof AuthoringContract.StageOptions>,
-    Omit<Mutable<AuthoringContract.StageOptions>, "sessionManager" | "settingsManager"> {
+    Omit<Mutable<AuthoringContract.StageOptions<TSchemaDef>>, "sessionManager" | "settingsManager"> {
+  /** Optional structured final-answer schema. When set, the stage receives a schema-specific `structured_output` tool and must finish by calling it. */
+  schema?: TSchemaDef;
   /** Model id or pi SDK model object used as the primary stage model. */
   model?: WorkflowModelValue;
   /** Per-stage MCP server gating. No-op when no WorkflowMcpPort is configured. */
@@ -231,6 +233,7 @@ export interface WorkflowPersistencePort {
 export type WorkflowTaskContext = AuthoringContract.WorkflowTaskContext;
 export type WorkflowTaskContextInput = AuthoringContract.WorkflowTaskContextInput;
 export type WorkflowTaskResult = AuthoringContract.WorkflowTaskResult;
+export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> = AuthoringContract.WorkflowStageResult<TSchemaDef>;
 
 /**
  * Higher-level task API: create a tracked stage, optionally inject prior task
@@ -276,12 +279,12 @@ export interface WorkflowDirectOptions extends StageOptions, Omit<Mutable<Author
  * This exposes the supported subset of pi's SDK AgentSession. The workflow
  * executor owns disposal and wraps prompt() with stage lifecycle tracking.
  */
-export interface StageContext {
+export interface StageContext<TSchemaDef extends TSchema | undefined = undefined> {
   /** Human-readable name for this stage (used in TUI + persistence). */
   readonly name: string;
 
   /** Send a prompt and wait for completion. */
-  prompt(text: string, options?: StagePromptOptions): Promise<string>;
+  prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
   complete(text: string, options?: CompleteStageOpts): Promise<string>;
 
   /** Queue messages during streaming. */
@@ -344,6 +347,7 @@ export interface WorkflowRunContext<
    * @param name   Human-readable stage name (used in TUI + persistence).
    * @param options Optional per-stage configuration (mcp allow/deny, etc.).
    */
+  stage<TSchemaDef extends TSchema>(name: string, options: StageOptions<TSchemaDef> & { schema: TSchemaDef }): StageContext<TSchemaDef>;
   stage(name: string, options?: StageOptions): StageContext;
   /**
    * Safe high-level task primitive. Equivalent to creating a named stage and