agent-lattice 0.19.0 → 0.20.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,92 @@ 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: pass
+it to the child agent and to `AgentToolOptions.outputSchema` on the parent
+side, and an `ask` call returns the child's validated output as a JSON string:
+
+```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: reviewSchema, // validates the child's submission
+    }),
+  ],
+});
+```
+
+If the child ends without submitting or submits a payload that fails the
+parent's schema, the tool returns an `is_error` `tool_result` starting with
+`child_output_invalid:`, so the parent model sees the failure and can retry.
+
 ## 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,14 @@ export type AgentToolInput = z.infer<typeof agentToolInputSchema>;
 export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
+    /**
+     * Expected structured output of the target, declared with the same schema
+     * the target uses for its own `AgentOptions.outputSchema`. With mode "ask"
+     * the tool result is the target's validated structured output as JSON; a
+     * target that ends without submitting — or submits a payload that fails this
+     * schema — produces a `child_output_invalid` tool error the parent can retry.
+     */
+    outputSchema?: OutputSchema;
 };
 /**
  * An AgentLike is a live session: it keeps its conversation history across