agent-lattice 0.25.1 → 0.29.0

package/README.md

@@ -182,6 +182,24 @@ The Kimi Open Platform endpoint at `https://api.moonshot.cn/v1` uses the OpenAI
 Chat Completions protocol and is not a valid `baseURL` for the SDK's built-in
 Anthropic client.
 
+## Default output budget
+
+*Requires 0.29.0 or later.*
+
+When `baseURL` points to the official `api.deepseek.com` host and `maxTokens` is
+omitted, the SDK uses **393216 tokens (384K)**, the maximum output advertised by
+DeepSeek's [model metadata](https://api-docs.deepseek.com/api/list-models/) and
+[API reference](https://api-docs.deepseek.com/api/create-chat-completion/).
+Other endpoints keep the existing 16384-token default. An explicit `maxTokens`
+always takes precedence. Set `baseURL` explicitly to use this provider default;
+the SDK does not inspect environment variables to choose the output budget.
+
+This is a maximum allowance per model request, including thinking output, not a
+request to generate that many tokens. The provider can end the response sooner;
+usage and billing depend on tokens actually generated. Smaller explicit limits
+remain useful when an application deliberately limits output or cost. The
+separate `autoCompact.maxTokens` summary budget is unchanged.
+
 ## Multimodal Input
 
 Pass Anthropic-compatible content blocks for image or document prompts:
@@ -535,7 +553,7 @@ The structure is enforced by the harness, not by prompt discipline:
   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
+- If recovery is disabled or unsuccessful, ending without `submit_output` 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
@@ -553,6 +571,69 @@ ending after a submission succeeds with the last submission as
 `structuredResult`; ending without any submission still fails with
 `error_missing_output`. *Requires 0.25.0 or later.*
 
+### Retry a missing submission once
+
+*Requires 0.27.0 or later.*
+
+For agents with `outputSchema` or a registered `submit_output` tool, missing-output
+recovery is enabled by default since 0.28.0. *Requires 0.28.0 or later for this default.*
+It allows one additional model request per query when the model ends normally
+without submitting structured output. Set `retryMissingOutput: false` to disable
+it, restoring the immediate failure behavior. This default change is breaking
+for submission agents; ordinary chat agents keep their existing behavior.
+Version 0.27.0 required an explicit `retryMissingOutput: true`.
+
+```ts
+import { createBareAgent } from "agent-lattice";
+import { z } from "zod/v4";
+
+const agent = createBareAgent({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash-vision-exp",
+  outputSchema: z.object({ result: z.string() }),
+  thinkingConfig: { type: "enabled", budgetTokens: 4096 },
+  maxTurns: 5,
+  // Recovery is enabled by default for outputSchema (since 0.28.0).
+});
+const result = await agent.prompt("Explain why the supplied evidence supports the conclusion.");
+if (result.subtype === "success") console.log(result.structuredResult);
+```
+
+The recovery request keeps the conversation, including thinking blocks and
+completed tool results, and appends a submission reminder. Only `submit_output`
+is offered; thinking is explicitly disabled, reasoning effort is omitted, and
+`tool_choice` is set to `{ type: "tool", name: "submit_output" }`. The SDK also
+rejects any recovery batch other than a single complete `submit_output` call
+before executing handlers. Previous tools are not replayed.
+
+The option requires `outputSchema` or a registered custom `submit_output` tool.
+A custom tool keeps its own argument validation and result transformation and
+must return `ToolResult.structuredResult`; handler success alone is not delivery.
+Enabling the option makes submission required for that query. Custom tools
+remain responsible for validating their result. With `submitOutputEndTurn: false`,
+a successful recovery can still be followed by the usual summary turn; that turn
+restores normal thinking and tools and is not another recovery attempt.
+
+Recovery consumes a `maxTurns` turn and uses the existing cancellation and
+per-request timeout. It does not run after refusal, truncation, or another
+explicit abnormal stop. Custom model clients that omit stop reasons are treated
+as normally ended. A second missing submission, invalid arguments, rejected
+batch, or missing custom structured result ends with `error_missing_output`;
+there is no further corrective model call in recovery. Provider errors, timeout,
+interrupt, and abort retain their existing failure semantics. Recovery skips
+compaction and overflow retries to preserve the conversation and the one-request
+limit. `requestTimeoutMs` is per request; use `QueryOptions.signal` for an overall
+deadline.
+
+The extra request adds latency and token cost. Use it only with a provider
+that supports forced tool choice with thinking disabled; otherwise set
+`retryMissingOutput: false`. A custom `ModelClient`
+must honour `ModelRequest.toolChoice` and the thinking override. The SDK does
+not infer or parse tool calls from plain text. The reminder is persisted through
+`HistoryStore` and tracing; the recovery `model_request` trace has
+`missingOutputRetry: true`, the effective `thinkingConfig`, and `toolChoice`.
+
 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/)),
@@ -701,6 +782,17 @@ the target's lifecycle: an `AgentSpec` spawns a fresh session per call, while an
 `AgentLike` target keeps history across calls and is usually not safe to call
 concurrently. *Requires 0.24.0 or later.*
 
+For durable child sessions, `AgentToolOptions.prepareTarget` runs after the
+child's input has been validated and mapped to a task, before the child starts.
+It receives the target, task, tool-use ID, parent run ID, trace session ID, and
+abort signal; return the `AgentLike` to call. A host can spawn the supplied
+`AgentSpec` with a per-call `HistoryStore` and return an adapter that records
+its event stream. Without the hook, a spec still spawns a fresh session as
+before. Direct `ask` child trace events share the parent's trace session and
+carry both `parent_run_id` and `parent_tool_use_id`, so concurrent calls to the
+same child can be distinguished. The host owns cleanup if preparing a child
+fails. *Requires 0.26.0 or later.*
+
 When concurrency is available, the SDK tells the model to batch independent
 calls and to use separate assistant responses when a later call needs an earlier
 result. Runtime safety checks and `toolBatchPolicy` remain authoritative.

package/dist/index.d.ts

@@ -117,6 +117,7 @@ export type ContextTraceEvent = {
     session_id: string;
     run_id: string;
     parent_run_id?: string;
+    parent_tool_use_id?: string;
     seq: number;
     source: AgentRuntimeSource;
     type: ContextTraceEventType;
@@ -247,6 +248,11 @@ export type ModelRequest = {
     maxTokens: number;
     messages: ModelMessage[];
     tools: ModelToolDefinition[];
+    /** Forced submission during missing-output recovery. Custom clients must honour it. */
+    toolChoice?: {
+        type: "tool";
+        name: string;
+    };
     stream: boolean;
     outputFormat?: OutputFormat;
     thinkingConfig?: ThinkingConfig;
@@ -298,6 +304,11 @@ export type ToolBatchPolicy<TContext = unknown> = {
 export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
+    /** Current agent query, when the tool is called from an agent loop. */
+    trace?: {
+        sessionId: string;
+        runId: string;
+    };
     context?: TContext;
     agentRuntime?: AgentRuntimeContext;
     permissions?: RuntimePermissions;
@@ -598,7 +609,8 @@ export type AgentOptions<TContext = unknown> = {
      * `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
+     * fails with `error_missing_output` if recovery is disabled or unsuccessful.
+     * Missing-output recovery is enabled by default (see retryMissingOutput). The tool must be the
      * only call in its batch, and its name is reserved (registering a user tool
      * with the same name throws).
      */
@@ -616,6 +628,16 @@ export type AgentOptions<TContext = unknown> = {
      * ending without any submission still fails with `error_missing_output`.
      */
     submitOutputEndTurn?: boolean;
+    /**
+     * Allow one extra model request when a normal text ending has not
+     * submitted output. Defaults to true for agents with submit_output, false
+     * for ordinary chat agents. Requires outputSchema or a custom
+     * submit_output tool returning structuredResult. Recovery disables thinking
+     * and forces submit_output; no other tool may execute in that request.
+     * The extra request counts toward maxTurns and respects cancellation and
+     * requestTimeoutMs. An unsuccessful recovery fails with error_missing_output.
+     */
+    retryMissingOutput?: boolean;
     /** Lifecycle callbacks that rewrite tool results and outgoing model requests. */
     hooks?: AgentHooks<TContext>;
     /**
@@ -782,8 +804,8 @@ 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.
+ * A run requiring submission (`outputSchema` or `retryMissingOutput`) ended
+ * without structured output from the `submit_output` tool.
  */
 export declare class MissingOutputError extends AgentSDKError {
 }
@@ -853,6 +875,21 @@ export type AgentToolOptions = {
      * never shown to the model.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * Resolve the child session for this invocation after input validation and
+     * task mapping, before the child runs. A host can spawn an AgentSpec with a
+     * per-call HistoryStore and return an AgentLike that records its event stream.
+     * The default is to spawn a spec or reuse a live AgentLike target.
+     */
+    prepareTarget?: (invocation: {
+        target: AgentToolTarget;
+        toolName: string;
+        toolUseId: string;
+        task: string | ContentBlock[];
+        parentRunId?: string;
+        traceSessionId?: string;
+        signal?: AbortSignal;
+    }) => AgentLike<any> | Promise<AgentLike<any>>;
     /**
      * Expected structured output of the target. When omitted, the declaration is
      * inherited from the target itself (an Agent's or AgentSpec's