@bastani/atomic 0.8.29-alpha.3 → 0.8.29

package/CHANGELOG.md

@@ -2,12 +2,14 @@
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Added
 
 - Added support for local `-e <dir>` extension sources to borrow project-local Atomic resources from `<dir>/.atomic`, legacy `<dir>/.pi`, and `<dir>/.agents/skills` after resolving trust for that extension source, preserving package-manager provenance and explicit-path workflow forwarding while avoiding untrusted borrowed resources ([#1354](https://github.com/bastani-inc/atomic/issues/1354)).
 - Added a prototype Rust/N-API Cursor HTTP/2 native transport binding through the generated `@bastani/atomic-natives` NAPI-RS package, so Atomic can use an in-process native HTTP/2 client without requiring Node.js on `PATH`.
 - Added the experimental bundled `@bastani/cursor` provider scaffold so `/login` can offer Cursor OAuth, estimated fallback exposes `cursor/composer-2`, and Cursor model mapping/streaming hooks are available behind an isolated HTTP/2 Connect transport boundary with production-default protobuf decoding, buffered Connect frames, write-before-headers Run streaming, stable Cursor conversation ids, schema-correct Cursor MCP tool advertisement, Cursor MCP tool-call decoding with protobuf `Value` or raw UTF-8/JSON arguments and exec-id metadata, same-stream MCP tool-result resume, abort/idle cleanup for paused tool streams, Connect end-stream error classification, exact live model id fidelity without static default injection, fast/thinking catalog grouping, and usage-delta accumulation.
-- Added the opt-in `createStructuredOutputTool({ schema, capture, output, name })` factory for terminating machine-readable final answers with schema-as-parameters validation, flat `details`, in-process capture, flat private `output.json` capture plus `output.meta.json` sidecar metadata, and prompt guidance for exact-once use without registering `structured_output` in normal agent sessions by default ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Added the opt-in `createStructuredOutputTool({ schema, capture, output, name })` factory for terminating machine-readable final answers with direct schema-as-parameters capture, flat `details`, in-process capture, configurable private file capture via `output.outputPath`, and the concise two-line `structured_output` prompt guidance from `pi-dynamic-workflows` without registering `structured_output` in normal agent sessions by default ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 
 ### Changed
 
@@ -15,17 +17,18 @@
 - Changed bundled `goal`, `ralph`, and `open-claude-design` decision gates to use schema-backed workflow `structured_output` stages instead of registering bespoke terminating custom tools.
 - Changed bundled `goal` worker/reviewer prompts and `ralph` orchestrator/reviewer prompts to request end-to-end verification when practical, using browser-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios.
 - Bumped the bundled upstream pi runtime libraries `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` from `^0.79.1` to `^0.79.3`, bringing the latest upstream provider, model, agent-core, and TUI compatibility fixes into `@bastani/atomic`.
-- Updated the structured-output extension example and SDK/workflow/extension docs to use the canonical factory instead of hand-rolled `terminate: true` wrappers, and documented that schema-specific calls pass fields directly rather than through `{ value: ... }` ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Enforced top-level object schemas for `structured_output` factory registration, with guidance to wrap array or primitive final values in object fields, made custom-named factory tools advertise the configured name in prompt metadata, and documented that text print mode recognizes factory-created custom structured-output tools without treating every terminating tool as printable ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Updated the structured-output extension example and SDK/workflow/extension docs to use the canonical factory instead of hand-rolled `terminate: true` wrappers, and documented that Atomic passes the supplied schema directly to the tool without additional structured-output parsing, object-root restrictions, or sidecar validation ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Made custom-named factory tools advertise the configured name in concise prompt metadata, and documented that text print mode recognizes factory-created custom structured-output tools without treating every terminating tool as printable ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Changed factory-created structured-output tool descriptions and prompt guidance to use context-neutral final-result wording for SDK, extension, workflow, and subagent registrations ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Clarified SDK, extension, and workflow guidance that structured-output tools are opt-in custom tools, with workflow stages/tasks/chains/parallel items receiving `structured_output` only when they declare a `schema` and subagent children receiving it only when `outputSchema` is enabled ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 
 ### Fixed
 
 - Fixed the root `@bastani/atomic` package export to include a `default` condition alongside the ESM import target, improving compatibility with loaders that select default export conditions.
 - Fixed extension custom UI focus deferral so full-screen overlays can keep keyboard focus while a parent/main-chat inline custom UI is pending, then focus that pending UI when the overlay is hidden; already-aborted custom UI calls no longer invoke factories or emit host custom-UI state changes ([#1353](https://github.com/bastani-inc/atomic/issues/1353)).
-- Fixed text print mode to emit trailing terminating JSON from factory-created structured-output tools, including custom tool names such as `final_decision`, instead of only recognizing the canonical `structured_output` name ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Fixed terminating `structured_output` results to opt out of oversized-result persistence so large final JSON stays inline instead of being replaced by a `<persisted-output>` pointer ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Fixed cross-process structured-output file capture to preserve flat schema-valid params in `output.json` and write call metadata to an `output.meta.json` sidecar so parent readback can reject stale or non-final captures instead of accepting any schema-valid `output.json` payload by existence alone ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed text print mode to emit trailing terminating JSON from factory-created structured-output tools, including custom tool names such as `final_decision`, instead of only recognizing the canonical `structured_output` name; the same structured value remains available through `details`, capture sinks, and workflow/subagent structured result fields ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed terminating `structured_output` results to opt out of oversized-result persistence ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed cross-process structured-output file capture to preserve flat tool arguments in `output.json` without sidecar metadata or transcript-finality parsing ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed bundled subagent handling so explicit empty `tools: []` plus `outputSchema` grants only the schema-backed `structured_output` runtime tool instead of restoring default tools ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed prerelease publishing for native Atomic artifacts by allowing the `@bastani/atomic-natives` package metadata in release-preparation verification, running native artifact builds on architecture-matched Blacksmith and macOS runners, and documenting the two-package publish flow while keeping npm provenance publishing on GitHub-hosted Ubuntu.
 - Fixed the bundled experimental Cursor provider to honor per-request stream deadlines across open/read/resume writes, reset timed-out or aborted streams, clean up replaced paused turns safely, catch cleanup cancellation failures, tolerate non-MCP Cursor exec protocol messages without ending assistant turns, and align Run requests with Cursor's private CLI protocol by using blob/KV conversation state plus request-context tool-definition responses without the unsupported custom system-prompt field ([#1286](https://github.com/bastani-inc/atomic/issues/1286)).

package/dist/builtin/cursor/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Added
 
 - Added a prototype Rust/N-API HTTP/2 native binding and loader so the Cursor transport uses the generated `@bastani/atomic-natives` NAPI-RS package without requiring Node.js on `PATH`.

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.8.29-alpha.3",
+    "@bastani/atomic-natives": "0.8.29",
     "@bufbuild/protobuf": "^2.0.0"
   }
 }

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,9 +4,11 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Changed
 
-- Published a synchronized Atomic 0.8.29-alpha.1 prerelease with the upstream pi TUI dependency aligned to `^0.79.3`; no functional changes were made in the intercom extension.
+- Published a synchronized Atomic 0.8.29 stable release with the upstream pi TUI dependency aligned to `^0.79.3`; no functional changes were made in the intercom extension.
 
 ## [0.8.28] - 2026-06-11
 

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,9 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Changed
 
-- Published a synchronized Atomic 0.8.29-alpha.1 prerelease with upstream pi AI/TUI dependencies aligned to `^0.79.3`; no functional changes were made in the MCP extension.
+- Published a synchronized Atomic 0.8.29 stable release with upstream pi AI/TUI dependencies aligned to `^0.79.3`; no functional changes were made in the MCP extension.
 
 ## [0.8.28] - 2026-06-11
 

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,16 +2,17 @@
 
 ## [Unreleased]
 
+## [0.8.29] - 2026-06-15
+
 ### Changed
 
 - Aligned the subagents extension with upstream pi `^0.79.3` runtime packages (`@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui`) so child sessions inherit the latest shared agent, provider, and TUI compatibility fixes.
-- Changed `outputSchema` child runs to use Atomic's shared `structured_output` factory with flat schema parameters, preserving parent-side `structuredOutput` capture while removing the old child-facing `{ value: ... }` envelope, auto-allowing the required tool for explicit child tool allowlists, and documenting that the prompt-runtime extension is loaded before user/tool extensions so the allowlist sees the runtime-registered tool ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Enforced parent-side fail-fast validation that subagent child `outputSchema` roots are top-level object tool-argument schemas; array or primitive handoff values must now be wrapped in object fields such as `{ items: [...] }` or `{ value: ... }` ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
-- Kept dynamic fanout `collect.outputSchema` as a general JSON Schema validator so saved chains and direct runs can validate aggregate arrays with array-root schemas while child `outputSchema` tool contracts remain object-rooted ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Changed `outputSchema` child runs to use Atomic's shared `structured_output` factory with direct schema parameters, concise two-line prompt guidance, parent-side `structuredOutput` capture from `output.json`, and auto-allowing the required tool for explicit child tool allowlists ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Removed parent-side top-level-object restrictions from child `outputSchema`; any plain JSON Schema object can be passed directly to the `structured_output` tool ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 
 ### Fixed
 
-- Fixed subagent `outputSchema` readback to accept cross-process captures only when flat `output.json` params validate against the schema and `output.meta.json` sidecar metadata matches the final successful terminating `structured_output` transcript action, rejecting missing metadata, stale captures with later assistant/tool-result messages, sibling tool calls, duplicate structured-output calls, mismatched call IDs/names, and error tool results while ignoring benign `custom` host annotations around the final tool result ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed subagent `outputSchema` readback to use the captured `output.json` directly without sidecar metadata, transcript-finality parsing, duplicate-call checks, or parent-side schema revalidation ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed explicit empty child `tools: []` allowlists with `outputSchema` to pass only `--tools structured_output`, keeping the restricted child from regaining default tools while still enabling the required final-answer channel ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
 - Fixed workflow-stage subagent depth handling so bundled workflow stages inherit the main-chat two-hop subagent nesting budget while preserving stricter configured limits, and updated the nested-depth rejection message to describe the maximum-depth condition ([#1372](https://github.com/bastani-inc/atomic/pull/1372)).
 

package/dist/builtin/subagents/README.md

@@ -531,15 +531,15 @@ Create an implementation plan based on {outputs.context}
 
 Each `.chain.md` `## agent-name` section is a step. Config lines such as `phase`, `label`, `as`, `outputSchema`, `output`, `outputMode`, `reads`, `model`, `skills`, and `progress` go immediately after the header. A blank line separates config from task text. In saved `.chain.md` files, `outputSchema` is a path to a JSON Schema file; direct tool calls and `.chain.json` files can pass the schema object inline.
 
-When `outputSchema` is present, the child receives a schema-specific `structured_output` tool backed by Atomic's shared factory. The schema must be a top-level object tool-argument schema; wrap array or primitive handoff values in explicit object fields such as `{ items: [...] }` or `{ value: ... }`. The child must call `structured_output` exactly once with the schema fields directly, for example `structured_output({ files: [...], risks: [...] })`; do not use the old `structured_output({ value: ... })` wrapper unless your schema explicitly defines a top-level `value` property. The child writes flat params to `output.json` and call metadata (`toolName`, `toolCallId`, `success`, `terminate`) to the `output.meta.json` sidecar. Missing calls, missing sidecar metadata, invalid values, duplicate calls, stale output-file captures, sibling tool calls in the same assistant batch, and later assistant/custom/tool-result messages after the successful tool result fail the step. The parent accepts the cross-process capture only when the flat `output.json` validates and sidecar metadata plus transcript finality prove the same `structured_output` call was the final successful terminating action, then exposes the validated flat value as `structuredOutput`.
+When `outputSchema` is present, the child receives a schema-specific `structured_output` tool backed by Atomic's shared factory. The schema is passed directly to the tool. The child writes the tool arguments to `output.json`, and the parent reads that JSON back as `structuredOutput`; Atomic no longer adds object-root restrictions, sidecar metadata, transcript-finality checks, or duplicate-call guards.
 
-Children without `outputSchema` do not receive `structured_output` from Atomic's default tool registry. They can still use a custom extension-provided terminating tool if you explicitly add one, but validated `result.structuredOutput` remains reserved for schema-backed captures.
+Children without `outputSchema` do not receive `structured_output` from Atomic's default tool registry. They can still use a custom extension-provided terminating tool if you explicitly add one.
 
 For `output`, `reads`, `skills`, and `progress`, chain behavior is three-state: omitted inherits from the agent, a value overrides, and `false` disables.
 
 Use `phase` to group related work in status output, `label` for a readable step name, and `as` to store a successful step or parallel task result for later `{outputs.name}` references. Duplicate `as` names, invalid identifiers, and unknown output references fail before child execution.
 
-Dynamic fanout is available only through direct `subagent({ chain: [...] })` JSON or saved `.chain.json` files. It expands an array from a prior structured named output, runs one child template per item, and stores the ordered collection under `collect.as`. The source must be structured output; prose is never parsed. `expand.maxItems` is required, over-limit arrays fail, nested fanout and arbitrary expressions are not supported, and `.chain.md` has no dynamic syntax in this release. `collect.outputSchema` validates the collected array after child execution and remains a general JSON Schema, so array-root schemas such as `{ "type": "array", "minItems": 1 }` are allowed there even though child `outputSchema` tool schemas must be top-level objects.
+Dynamic fanout is available only through direct `subagent({ chain: [...] })` JSON or saved `.chain.json` files. It expands an array from a prior structured named output, runs one child template per item, and stores the ordered collection under `collect.as`. The source must be structured output; prose is never parsed. `expand.maxItems` is required, over-limit arrays fail, nested fanout and arbitrary expressions are not supported, and `.chain.md` has no dynamic syntax in this release. `collect.outputSchema` validates the collected array after child execution.
 
 ```json
 {
@@ -820,7 +820,7 @@ Agent definitions are not loaded into context by default. Management actions let
 
 Use `outputMode: "file-only"` when a saved output may be large and the parent only needs a pointer. The returned text is a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Failed runs and save errors still return normal inline output for debugging. In chains, later `{previous}` steps receive the same compact reference when the prior step used file-only mode.
 
-Sequential and parallel chain tasks accept `agent`, `task`, `phase`, `label`, `as`, `outputSchema`, `cwd`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`. If child `outputSchema` is present, it must be a top-level object schema and the child must call `structured_output` with schema-valid flat JSON arguments; prose-only completion, missing `output.meta.json` sidecar metadata, invalid JSON, top-level arrays/primitives, or an obsolete `{ value: ... }` envelope fails unless the schema itself allows that shape. Validated structured values are preserved on the step result, and `as` also exposes a compact text representation through `{outputs.name}`. Without `outputSchema`, Atomic does not inject `structured_output` into the child. Dynamic fanout `collect.outputSchema` is looser because it validates the aggregate collection rather than a tool call; array-root collection schemas remain valid.
+Sequential and parallel chain tasks accept `agent`, `task`, `phase`, `label`, `as`, `outputSchema`, `cwd`, `output`, `outputMode`, `reads`, `progress`, `skill`, and `model`. Parallel tasks also accept `count`. Parallel step groups accept `parallel`, `concurrency`, `failFast`, and `worktree`. If child `outputSchema` is present, Atomic injects `structured_output`, writes the child tool arguments to `output.json`, and preserves the parsed value on the step result; `as` also exposes a compact text representation through `{outputs.name}`. Without `outputSchema`, Atomic does not inject `structured_output` into the child.
 
 Status and control actions:
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.8.29-alpha.3",
+  "version": "0.8.29",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/subagents/src/extension/index.ts

@@ -213,6 +213,19 @@ class SubagentControlNoticeComponent implements Component {
 	}
 }
 
+export const DEFAULT_PROMPT_GUIDANCE: string[] = [
+	`**Subagent Orchestration**:
+  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.
+  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \`aws\` CLI, using the \`gh\` CLI, digging through logs to \`bash\` subagents.
+  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.
+  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.
+  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.
+    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.
+    - Explain the debugger's insights to the user clearly and concisely.
+    - Once the user confirms, implement the necessary code changes based on those insights.
+    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`,
+];
+
 export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	if (getEnvValue(SUBAGENT_CHILD_ENV) === "1") {
 		if (getEnvValue(SUBAGENT_FANOUT_CHILD_ENV) === "1") registerFanoutChildSubagentExtension(pi);
@@ -431,6 +444,7 @@ CONTROL:
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,
 		parameters: SubagentParams,
+		promptGuidelines: DEFAULT_PROMPT_GUIDANCE,
 
 		execute(id, params, signal, onUpdate, ctx) {
 			return executeSubagentCollapsed(id, params, signal, onUpdate, ctx);

package/dist/builtin/subagents/src/extension/schemas.ts

@@ -38,7 +38,7 @@ const ReadsOverride = Type.Unsafe({
 const JsonSchemaObject = Type.Unsafe({
 	type: "object",
 	additionalProperties: true,
-	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
+	description: "Plain JSON Schema object for structured output.",
 });
 
 const AcceptanceEvidenceKind = Type.String({

package/dist/builtin/subagents/src/runs/background/subagent-runner.ts

@@ -748,12 +748,7 @@ async function runSingleStep(
 		let structuredOutput: unknown;
 		let structuredError: string | undefined;
 		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !hiddenError?.hasError) {
-			const structured = readStructuredOutput({
-				schema: effectiveStructuredOutput.schema,
-				schemaPath: effectiveStructuredOutput.schemaPath,
-				outputPath: effectiveStructuredOutput.outputPath,
-				metadataPath: effectiveStructuredOutput.metadataPath,
-			}, { messages: run.messages });
+			const structured = readStructuredOutput(effectiveStructuredOutput);
 			if (structured.error) structuredError = structured.error;
 			else structuredOutput = structured.value;
 		}

package/dist/builtin/subagents/src/runs/foreground/execution.ts

@@ -748,12 +748,7 @@ async function runSingleAttempt(
 		}
 	}
 	if (options.structuredOutput && result.exitCode === 0 && !result.error) {
-		const structured = readStructuredOutput({
-			schema: options.structuredOutput.schema,
-			schemaPath: options.structuredOutput.schemaPath,
-			outputPath: options.structuredOutput.outputPath,
-			metadataPath: options.structuredOutput.metadataPath,
-		}, { messages: result.messages ?? [] });
+		const structured = readStructuredOutput(options.structuredOutput);
 		result.structuredOutputSchemaPath = options.structuredOutput.schemaPath;
 		result.structuredOutputPath = options.structuredOutput.outputPath;
 		if (structured.error) {

package/dist/builtin/subagents/src/runs/shared/parallel-utils.ts

@@ -33,7 +33,6 @@ export interface RunnerSubagentStep {
 		schema: import("../../shared/types.ts").JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
-		metadataPath: string;
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;

package/dist/builtin/subagents/src/runs/shared/pi-args.ts

@@ -75,7 +75,6 @@ interface BuildPiArgsInput {
 		schema: JsonSchemaObject;
 		schemaPath: string;
 		outputPath: string;
-		metadataPath: string;
 	};
 }
 

package/dist/builtin/subagents/src/runs/shared/structured-output.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { APP_NAME, STRUCTURED_OUTPUT_TOOL_NAME, getStructuredOutputMetadataPath } from "@bastani/atomic";
+import { APP_NAME } from "@bastani/atomic";
 import { Compile } from "typebox/compile";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 
@@ -9,239 +9,10 @@ const ENV_PREFIX = APP_NAME.toUpperCase();
 export const STRUCTURED_OUTPUT_SCHEMA_ENV = `${ENV_PREFIX}_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA`;
 export const STRUCTURED_OUTPUT_CAPTURE_ENV = `${ENV_PREFIX}_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE`;
 
-type JsonPrimitive = string | number | boolean | null;
-type JsonArray = readonly JsonValue[];
-type JsonRecord = { readonly [key: string]: JsonValue };
-type JsonValue = JsonPrimitive | JsonArray | JsonRecord;
-
 export interface StructuredOutputRuntime {
 	schema: JsonSchemaObject;
 	schemaPath: string;
 	outputPath: string;
-	metadataPath: string;
-}
-
-export interface StructuredOutputCaptureMetadata {
-	toolName: string;
-	toolCallId: string;
-	success: true;
-	terminate: true;
-	capturedAt?: string;
-}
-
-export interface StructuredOutputTranscriptContent {
-	readonly type?: string;
-	readonly id?: string;
-	readonly name?: string;
-}
-
-export interface StructuredOutputTranscriptMessage {
-	readonly role: string;
-	readonly content?: string | readonly StructuredOutputTranscriptContent[];
-	readonly toolCallId?: string;
-	readonly toolName?: string;
-	readonly isError?: boolean;
-}
-
-export interface ReadStructuredOutputOptions {
-	messages?: readonly StructuredOutputTranscriptMessage[];
-	toolName?: string;
-}
-
-interface CompiledJsonSchema {
-	Check(value: unknown): boolean;
-	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
-}
-
-type JsonSchemaRootDescriptor = {
-	readonly type?: string | readonly string[];
-	readonly anyOf?: readonly JsonSchemaObject[];
-	readonly oneOf?: readonly JsonSchemaObject[];
-	readonly allOf?: readonly JsonSchemaObject[];
-};
-
-type ToolCallBlock = {
-	readonly type: "toolCall";
-	readonly id?: string;
-	readonly name?: string;
-};
-
-function schemaTypeIsObjectOnly(type: JsonSchemaRootDescriptor["type"]): boolean {
-	if (type === "object") return true;
-	return Array.isArray(type) && type.length === 1 && type[0] === "object";
-}
-
-function isTopLevelObjectOutputSchema(schema: JsonSchemaObject): boolean {
-	const descriptor = schema as JsonSchemaRootDescriptor;
-	if (schemaTypeIsObjectOnly(descriptor.type)) return true;
-	if (descriptor.type !== undefined) return false;
-	if (Array.isArray(descriptor.anyOf) || Array.isArray(descriptor.oneOf)) return false;
-	if (Array.isArray(descriptor.allOf)) {
-		return descriptor.allOf.length > 0 && descriptor.allOf.every((member) => isTopLevelObjectOutputSchema(member));
-	}
-	return false;
-}
-
-function isJsonRecord(value: JsonValue): value is JsonRecord {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function stringField(record: JsonRecord, key: string): string | undefined {
-	const value = record[key];
-	return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
-function booleanField(record: JsonRecord, key: string): boolean | undefined {
-	const value = record[key];
-	return typeof value === "boolean" ? value : undefined;
-}
-
-function roleOf(message: StructuredOutputTranscriptMessage): string {
-	return message.role;
-}
-
-function toolCallBlocks(message: StructuredOutputTranscriptMessage): ToolCallBlock[] {
-	if (roleOf(message) !== "assistant" || !Array.isArray(message.content)) return [];
-	return message.content
-		.filter((block): block is ToolCallBlock => block.type === "toolCall")
-		.map((block) => ({ type: "toolCall", id: block.id, name: block.name }));
-}
-
-function isFinalityRelevantMessage(message: StructuredOutputTranscriptMessage): boolean {
-	const role = roleOf(message);
-	// `custom` entries are host/runtime annotations (for example display/status
-	// messages) rather than additional child model output, so they should not make
-	// an otherwise-final structured_output capture look stale.
-	return role === "assistant" || role === "toolResult";
-}
-
-function finalityInvalid(message: string): { status: "invalid"; message: string } {
-	return { status: "invalid", message };
-}
-
-function parseCaptureMetadata(value: JsonValue): { metadata?: StructuredOutputCaptureMetadata; error?: string } {
-	if (!isJsonRecord(value)) {
-		return { error: "Structured output metadata sidecar must contain an object with call metadata." };
-	}
-	const toolName = stringField(value, "toolName");
-	const toolCallId = stringField(value, "toolCallId");
-	if (!toolName || !toolCallId) {
-		return { error: "Structured output metadata sidecar is missing toolName or toolCallId metadata." };
-	}
-	if (booleanField(value, "success") !== true) {
-		return { error: "Structured output capture was not marked successful." };
-	}
-	if (booleanField(value, "terminate") !== true) {
-		return { error: "Structured output capture was not marked as a terminating action." };
-	}
-	return {
-		metadata: {
-			toolName,
-			toolCallId,
-			success: true,
-			terminate: true,
-			...(typeof value.capturedAt === "string" ? { capturedAt: value.capturedAt } : {}),
-		},
-	};
-}
-
-function verifyStructuredOutputFinality(
-	messages: readonly StructuredOutputTranscriptMessage[],
-	metadata: StructuredOutputCaptureMetadata,
-	expectedToolName: string,
-): { status: "valid" } | { status: "invalid"; message: string } {
-	if (metadata.toolName !== expectedToolName) {
-		return finalityInvalid(
-			`Captured structured output tool name ${JSON.stringify(metadata.toolName)} did not match expected ${JSON.stringify(expectedToolName)}.`,
-		);
-	}
-	if (messages.length === 0) {
-		return finalityInvalid("Structured output finality could not be verified because the child transcript is empty.");
-	}
-
-	let structuredOutputCallCount = 0;
-	let assistantIndex = -1;
-	let matchingAssistantToolCalls: ToolCallBlock[] = [];
-	for (let index = 0; index < messages.length; index++) {
-		const calls = toolCallBlocks(messages[index]);
-		if (calls.length === 0) continue;
-		for (const call of calls) {
-			if (call.name === metadata.toolName) {
-				structuredOutputCallCount += 1;
-			}
-		}
-		const idMatch = calls.find((call) => call.id === metadata.toolCallId);
-		if (!idMatch) continue;
-		if (idMatch.name !== metadata.toolName) {
-			return finalityInvalid(
-				`Captured structured output tool call ${JSON.stringify(metadata.toolCallId)} used tool name ${JSON.stringify(idMatch.name)} instead of ${JSON.stringify(metadata.toolName)}.`,
-			);
-		}
-		assistantIndex = index;
-		matchingAssistantToolCalls = calls;
-	}
-
-	if (structuredOutputCallCount > 1) {
-		return finalityInvalid(
-			`Captured structured output call ${JSON.stringify(metadata.toolCallId)} was not exactly once; another ${metadata.toolName} tool call appeared in the child transcript.`,
-		);
-	}
-	if (assistantIndex === -1) {
-		return finalityInvalid(
-			`No assistant tool call matched captured structured output toolCallId ${JSON.stringify(metadata.toolCallId)}.`,
-		);
-	}
-	if (matchingAssistantToolCalls.length !== 1) {
-		return finalityInvalid(
-			`Captured structured output call ${JSON.stringify(metadata.toolCallId)} was accompanied by sibling tool calls in the same assistant message.`,
-		);
-	}
-
-	let resultIndex = -1;
-	let resultMessage: StructuredOutputTranscriptMessage | undefined;
-	for (let index = assistantIndex + 1; index < messages.length; index++) {
-		const message = messages[index];
-		if (roleOf(message) !== "toolResult") continue;
-		if (message.toolCallId !== metadata.toolCallId) continue;
-		resultIndex = index;
-		resultMessage = message;
-		break;
-	}
-
-	if (!resultMessage) {
-		return finalityInvalid(
-			`No tool result matched captured structured output toolCallId ${JSON.stringify(metadata.toolCallId)}.`,
-		);
-	}
-	if (resultMessage.toolName !== metadata.toolName) {
-		return finalityInvalid(
-			`Structured output tool result for ${JSON.stringify(metadata.toolCallId)} used tool name ${JSON.stringify(resultMessage.toolName)} instead of ${JSON.stringify(metadata.toolName)}.`,
-		);
-	}
-	if (resultMessage.isError !== false) {
-		return finalityInvalid(
-			`Structured output tool result for ${JSON.stringify(metadata.toolCallId)} was an error or did not prove success.`,
-		);
-	}
-
-	for (let index = assistantIndex + 1; index < resultIndex; index++) {
-		const message = messages[index];
-		if (isFinalityRelevantMessage(message)) {
-			return finalityInvalid(
-				`Structured output call ${JSON.stringify(metadata.toolCallId)} was not final; another ${roleOf(message)} message appeared before its matching tool result.`,
-			);
-		}
-	}
-	for (let index = resultIndex + 1; index < messages.length; index++) {
-		const message = messages[index];
-		if (isFinalityRelevantMessage(message)) {
-			return finalityInvalid(
-				`Structured output call ${JSON.stringify(metadata.toolCallId)} was not final; a later ${roleOf(message)} message followed the successful tool result.`,
-			);
-		}
-	}
-
-	return { status: "valid" };
 }
 
 export function assertJsonSchemaDescriptor(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
@@ -250,84 +21,44 @@ export function assertJsonSchemaDescriptor(schema: unknown, label = "outputSchem
 	}
 }
 
-export function assertStructuredOutputParameterSchema(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
-	assertJsonSchemaDescriptor(schema, label);
-	if (!isTopLevelObjectOutputSchema(schema)) {
-		throw new Error(
-			`${label} must be a top-level object tool-argument schema. `
-			+ "Wrap array or primitive outputs in an object field, for example `{ items: [...] }` or `{ value: ... }`.",
-		);
-	}
-}
-
 export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string): StructuredOutputRuntime {
-	assertStructuredOutputParameterSchema(schema);
 	const rootDir = baseDir ?? os.tmpdir();
 	fs.mkdirSync(rootDir, { recursive: true });
 	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
 	const schemaPath = path.join(dir, "schema.json");
 	const outputPath = path.join(dir, "output.json");
-	const metadataPath = path.join(dir, "output.meta.json");
 	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
-	return { schema, schemaPath, outputPath, metadataPath };
+	return { schema, schemaPath, outputPath };
 }
 
 export function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): { status: "valid" } | { status: "invalid"; message: string } {
-	let validator: CompiledJsonSchema;
 	try {
-		validator = (Compile as (schema: unknown) => CompiledJsonSchema)(schema);
+		const validator = (Compile as (schema: unknown) => {
+			Check(value: unknown): boolean;
+			Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+		})(schema);
+		if (validator.Check(value)) return { status: "valid" };
+		const errors = [...validator.Errors(value)]
+			.slice(0, 8)
+			.map((error) => {
+				const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+				return `${pathText}: ${error.message}`;
+			});
+		return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
 	} catch (error) {
 		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
 	}
-	if (validator.Check(value)) return { status: "valid" };
-	const errors = [...validator.Errors(value)]
-		.slice(0, 8)
-		.map((error) => {
-			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
-			return `${pathText}: ${error.message}`;
-		});
-	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
 }
 
-export function readStructuredOutput(
-	runtime: StructuredOutputRuntime,
-	options: ReadStructuredOutputOptions = {},
-): { value?: unknown; error?: string } {
+export function readStructuredOutput(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
 	if (!fs.existsSync(runtime.outputPath)) {
 		return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
 	}
-	const metadataPath = runtime.metadataPath ?? getStructuredOutputMetadataPath(runtime.outputPath);
-	if (!fs.existsSync(metadataPath)) {
-		return { error: "Missing structured_output metadata sidecar; this step must finish with a verified structured_output call." };
-	}
-	let payload: JsonValue;
 	try {
-		payload = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8")) as JsonValue;
+		return { value: JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8")) as unknown };
 	} catch (error) {
 		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
 	}
-	let rawMetadata: JsonValue;
-	try {
-		rawMetadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8")) as JsonValue;
-	} catch (error) {
-		return { error: `Failed to read structured output metadata: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	const parsed = parseCaptureMetadata(rawMetadata);
-	if (parsed.error || !parsed.metadata) {
-		return { error: parsed.error ?? "Structured output metadata sidecar is invalid." };
-	}
-	const validation = validateStructuredOutputValue(runtime.schema, payload);
-	if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
-	const expectedToolName = options.toolName ?? STRUCTURED_OUTPUT_TOOL_NAME;
-	if (options.messages) {
-		const finality = verifyStructuredOutputFinality(options.messages, parsed.metadata, expectedToolName);
-		if (finality.status === "invalid") return { error: finality.message };
-	} else if (parsed.metadata.toolName !== expectedToolName) {
-		return {
-			error: `Captured structured output tool name ${JSON.stringify(parsed.metadata.toolName)} did not match expected ${JSON.stringify(expectedToolName)}.`,
-		};
-	}
-	return { value: payload };
 }
 
 export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {