agent-lattice 0.19.0 → 0.21.0

package/README.md

@@ -86,7 +86,7 @@ them, so keep expensive handling off the loop itself.
 | `stream_event` | While the model is responding | Raw provider stream event for incremental rendering. |
 | `assistant` | After each model turn is assembled | The `AssistantModelMessage` with text / `tool_use` blocks and provider metadata. |
 | `user` | After a whole tool batch finishes | Tool results as `ToolResultBlock[]`; the prompt is never echoed. |
-| `result` | Once, at the end of the query | Final text, `subtype` (`"success"`, `"interrupted"`, or an error variant), and token usage. |
+| `result` | Once, at the end of the query | Final text, `subtype` (`"success"`, `"interrupted"`, or an error variant), optional `structuredResult`, and token usage. |
 
 For the exact per-event guarantees see
 [Streaming Events](https://docs.claude-code-sdk.com/concepts/streaming-events/).
@@ -150,6 +150,14 @@ Anthropic-compatible providers (for example DeepSeek's
 `https://api.deepseek.com/anthropic` endpoint) default thinking to on —
 omitting the field would leave it enabled.
 
+On DeepSeek, the on/off switch is the only thinking control that works:
+DeepSeek accepts `budget_tokens` but ignores the value, treats `adaptive` as
+plain enabled thinking, and does not support `reasoning_effort` at all. Its own
+thinking-strength knob is `output_config.effort`, which the SDK does not expose
+yet. See
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/)
+for the full matrix.
+
 For Kimi K3 through an Anthropic-compatible endpoint or gateway, use
 `reasoningEffort` to send the provider's top-level `reasoning_effort` parameter:
 
@@ -415,6 +423,12 @@ const agent = createAgent({
 });
 ```
 
+Pass an explicit `deepseek-*` model name — unknown names are silently mapped to
+`deepseek-v4-flash`. For which SDK options DeepSeek actually honors (thinking
+budgets are ignored; `reasoningEffort` does not apply; structured output is not
+supported), see
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/).
+
 ## Custom Tool
 
 ```ts
@@ -462,6 +476,148 @@ started concurrently, their `tool_result` blocks still enter the history, and
 model call is skipped. When several tools in a batch set `endTurn`, the first
 one's content becomes the result text.
 
+A tool can also return `structuredResult` next to `endTurn: true` to carry a
+structured payload to `SDKResultMessage.structuredResult`
+(*requires 0.20.0 or later*). Without `endTurn`, `structuredResult` is
+ignored.
+
+## Structured Output Via submit_output
+
+*Requires 0.20.0 or later.*
+
+Set `AgentOptions.outputSchema` when a run must deliver a typed result rather
+than free text. The SDK injects a built-in `submit_output` tool (exported as
+`SUBMIT_OUTPUT_TOOL_NAME`) whose input schema is your schema converted to JSON
+Schema — a zod schema works directly, since `OutputSchema<T>` is just
+`{ parse(input: unknown): T }`:
+
+```ts
+import { createAgent } from "agent-lattice";
+import { z } from "zod/v4";
+
+const reviewSchema = z.object({
+  approved: z.boolean(),
+  issues: z.array(z.string()),
+});
+
+const reviewer = createAgent({
+  model: "claude-sonnet-4-6",
+  systemPrompt: "Review the change and submit your verdict.",
+  outputSchema: reviewSchema,
+});
+
+const result = await reviewer.prompt("Review the patch in this workspace.");
+if (result.subtype === "success") {
+  console.log(result.structuredResult); // { approved: false, issues: [...] }
+}
+```
+
+The structure is enforced by the harness, not by prompt discipline:
+
+- The model submits its answer by calling `submit_output`. The payload is
+  validated against the schema first; a validation failure goes back into the
+  loop as an error `tool_result`, so the model can fix it and retry. A valid
+  submission ends the run with `subtype: "success"` and the payload on
+  `SDKResultMessage.structuredResult`.
+- If the model ends its turn without calling `submit_output`, the run fails
+  with `subtype: "error_missing_output"` and a `MissingOutputError`. There is
+  no fallback that parses the final text as JSON.
+- `submit_output` must be the only tool call in its batch. A batch that mixes
+  it with other calls — or contains two submissions — is rejected with code
+  `submit_output_exclusive_batch` and the loop continues.
+- The name is reserved: registering your own `submit_output` tool while
+  `outputSchema` is set throws from `createAgent`/`addTools`.
+
+Unlike `outputFormat` (which relies on the provider's
+`response_format`/`json_schema` support — DeepSeek ignores it, see
+[Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/)),
+`submit_output` only requires a model that can call tools, so it ports to any
+tool-capable provider.
+
+The same schema composes with `agentTool()` for parent/child delegation: give
+it to the child agent, and an `ask` call returns the child's validated output
+as a JSON string. Since 0.21.0 the parent side inherits the child's declared
+schema, so the `agentTool()` copy can be omitted. Passing
+`AgentToolOptions.outputSchema` explicitly is still allowed, but it must match
+the target's declaration (compared by reference, then by derived JSON Schema
+structure) — a mismatch throws at assembly time, so drift fails fast instead
+of at call time. The error message suggests sharing one schema instance or
+omitting the `agentTool()` copy:
+
+```ts
+import { agentTool, createAgent } from "agent-lattice";
+
+const child = createAgent({
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You review code and submit a structured verdict.",
+  outputSchema: reviewSchema, // child submits via submit_output
+});
+
+const parent = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [
+    agentTool("review", child, {
+      description: "Ask the reviewer to audit a change.",
+      // outputSchema is inherited from the child (0.21.0+); an explicit copy
+      // must match the child's declaration or agentTool() throws.
+    }),
+  ],
+});
+```
+
+If the child ends without submitting or submits a payload that fails the
+schema, the tool returns an `is_error` `tool_result` starting with
+`child_output_invalid:`, so the parent model sees the failure and can retry.
+
+*Behavior change in 0.21.0:* where the child declares an `outputSchema` and
+the parent does not, the `ask` tool result changed from the fixed text
+`"Structured output submitted."` to the validated JSON. That is the intended
+fix and ships in a minor under 0.x. Host-defined `AgentLike` adapters carry no
+readable declaration, so nothing is inherited or cross-checked for them; an
+explicit `outputSchema` still applies. Whenever a schema is in effect, the
+generated tool description states that the tool returns the target's
+validated structured output as JSON.
+
+### Typed delegation
+
+*Requires 0.21.0 or later.*
+
+`AgentToolOptions.inputSchema` replaces the default `{mode, task,
+expectedOutput, acceptanceCriteria, workspaceGrants}` input shape with your
+own schema (a zod schema works directly), and `mapInput` projects the
+validated input into the child prompt:
+
+```ts
+const judge = createAgent({
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You judge a case and submit a structured verdict.",
+  outputSchema: verdictSchema,
+});
+
+const judgeTool = agentTool("judge", judge, {
+  description: "Judge a case from its summary and documents.",
+  inputSchema: z.object({
+    caseSummary: z.string(),
+    documents: z.array(z.object({ title: z.string(), content: z.string() })),
+  }),
+  mapInput: input => renderJudgeTask(input.caseSummary, input.documents),
+});
+```
+
+- The parent's arguments are parsed against `inputSchema` before anything
+  runs; invalid input is rejected as an error `tool_result` in the parent's
+  loop — the same semantics as a plain `tool()` call — and the child is never
+  invoked.
+- `inputSchema` and `mapInput` must come as a pair: `agentTool()` throws at
+  assembly time when one is missing.
+- Typed delegation is ask-only: there is no `mode` field and no
+  `workspaceGrants`.
+- `mapInput` may return a string or `ContentBlock[]`; `ContentBlock[]` is only
+  supported for direct `ask` calls — inside a team runtime the projected
+  prompt must be a string, or the call fails at runtime.
+- Because typed input no longer matches `AgentToolInput`, `agentTool()` now
+  returns `ToolDefinition<any>`.
+
 ## Concurrent Tool Calls
 
 The model requests concurrency by returning multiple `tool_use` blocks in one

package/dist/index.d.ts

@@ -70,7 +70,7 @@ export type AgentRuntimeDelegateResult = {
     workspaceGrants?: WorkspaceGrant[];
 };
 export type AgentRuntimeFailure = {
-    code: "max_turns_exceeded" | "api_error" | "tool_execution_error" | "permission_denied" | "agent_error";
+    code: "max_turns_exceeded" | "api_error" | "tool_execution_error" | "permission_denied" | "missing_output" | "agent_error";
     message: string;
     name: string;
 };
@@ -263,6 +263,11 @@ export type ToolResult = {
     content: string | ContentBlock[];
     /** End the run after this tool batch: finish with subtype "success" instead of calling the model again. */
     endTurn?: boolean;
+    /**
+     * Structured payload carried to `SDKResultMessage.structuredResult` when this
+     * tool also ends the run with `endTurn`. Ignored otherwise.
+     */
+    structuredResult?: unknown;
 };
 export type ToolKind = "tool" | "agent_tool";
 export type ToolBatchCall = {
@@ -581,6 +586,16 @@ export type AgentOptions<TContext = unknown> = {
     requestTimeoutMs?: number;
     tools?: Array<ToolDefinition<any, TContext>>;
     toolBatchPolicy?: ToolBatchPolicy<TContext>;
+    /**
+     * Declares the run's structured output contract. When set, the SDK injects a
+     * `submit_output` tool with this schema: the run only ends successfully once
+     * the model submits a payload through it, and the validated payload lands on
+     * `SDKResultMessage.structuredResult`. Ending the turn without submitting
+     * fails the run with subtype `error_missing_output`. The tool must be the
+     * only call in its batch, and its name is reserved (registering a user tool
+     * with the same name throws).
+     */
+    outputSchema?: OutputSchema;
     /** Lifecycle callbacks that rewrite tool results and outgoing model requests. */
     hooks?: AgentHooks<TContext>;
     /**
@@ -682,12 +697,18 @@ export type SDKResultMessage = {
      * way, keeping completed turns in history so a follow-up query can continue
      * the conversation. `is_error` stays `false` for it.
      */
-    subtype: "success" | "interrupted" | "error" | "error_max_turns" | "error_abort" | "error_timeout";
+    subtype: "success" | "interrupted" | "error" | "error_max_turns" | "error_abort" | "error_timeout" | "error_missing_output";
     is_error: boolean;
     result: string;
     session_id: string;
     num_turns: number;
     error?: Error;
+    /**
+     * Validated structured payload submitted via the `submit_output` tool (see
+     * `AgentOptions.outputSchema`), or by any tool that ended the run with both
+     * `endTurn` and `ToolResult.structuredResult`. Absent otherwise.
+     */
+    structuredResult?: unknown;
     /** Summed over every model request in the query. Zeroed when unreported. */
     usage: TokenUsage;
     /**
@@ -734,6 +755,12 @@ export declare class ToolExecutionError extends AgentSDKError {
 }
 export declare class MaxTurnsError extends AgentSDKError {
 }
+/**
+ * A run with `AgentOptions.outputSchema` ended without the model calling the
+ * `submit_output` tool, so no structured output was produced.
+ */
+export declare class MissingOutputError extends AgentSDKError {
+}
 export declare class AbortError extends AgentSDKError {
 }
 /** A second query was started on an Agent that was still running one. */
@@ -752,6 +779,20 @@ export declare class ToolPermissionDeniedError extends AgentSDKError {
 }
 export declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>) => ToolDefinition<InferInput<TSchema>, TContext>;
 export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>, options?: ToolOptions<InferInput<TSchema>>): ToolDefinition<InferInput<TSchema>, TContext>;
+/**
+ * A schema describing structured output: a zod schema, or any object with a
+ * compatible `parse` method. The SDK validates submitted payloads with it and
+ * converts it to the JSON schema shown to the model.
+ */
+export type OutputSchema<TOutput = unknown> = {
+    parse(input: unknown): TOutput;
+};
+/**
+ * Name of the tool the SDK injects when `AgentOptions.outputSchema` is set.
+ * Reserved in that configuration: registering a user tool with the same name
+ * throws at `createAgent`/`addTools` time.
+ */
+export declare const SUBMIT_OUTPUT_TOOL_NAME = "submit_output";
 export type DelegateToolOptions = {
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -780,6 +821,35 @@ export type AgentToolInput = z.infer<typeof agentToolInputSchema>;
 export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
+    /**
+     * Expected structured output of the target. When omitted, the declaration is
+     * inherited from the target itself (an Agent's or AgentSpec's
+     * `AgentOptions.outputSchema`); when passed explicitly it must match the
+     * target's declaration or `agentTool()` throws at assembly time. Host-defined
+     * AgentLike adapters carry no readable declaration, so nothing is inherited
+     * or cross-checked for them.
+     *
+     * With the schema in effect, the tool result is the target's validated
+     * structured output as JSON; a target that ends without submitting — or
+     * submits a payload that fails the schema — produces a `child_output_invalid`
+     * tool error the parent can retry.
+     */
+    outputSchema?: OutputSchema;
+    /**
+     * Typed delegation: replaces the default `{mode, task, ...}` input shape
+     * with this schema (same structural shape as OutputSchema; a zod schema
+     * works directly). The parent's arguments are validated before the child is
+     * invoked, and `mapInput` projects the validated input into the child
+     * prompt. Typed delegation is ask-only: there is no `mode` field and no
+     * `workspaceGrants`. Requires `mapInput`.
+     */
+    inputSchema?: OutputSchema;
+    /**
+     * Projects validated `inputSchema` input into the child prompt. Returning
+     * `ContentBlock[]` is only supported for direct ask calls; inside a team
+     * runtime the projected prompt must be a string.
+     */
+    mapInput?: (input: any) => string | ContentBlock[];
 };
 /**
  * An AgentLike is a live session: it keeps its conversation history across
@@ -788,7 +858,7 @@ export type AgentToolOptions = {
  * continuity.
  */
 export type AgentToolTarget = AgentLike<any> | AgentSpec<any>;
-export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<any>;
 export declare function delegateTool(name: string, description: string, agent: AgentToolTarget, options?: DelegateToolOptions): ToolDefinition<{
     task: string;
 }>;
@@ -938,6 +1008,8 @@ declare class Agent<TContext = unknown> {
      */
     replaceHistory(messages: ModelMessage[]): Promise<void>;
     addTools(tools: Array<ToolDefinition<any, TContext>>): void;
+    /** The structured output contract declared via `AgentOptions.outputSchema`, if any. */
+    get outputSchema(): OutputSchema | undefined;
     private initMessage;
     private resultMessage;
     private modelTools;