agent-lattice 0.26.0 → 0.29.1

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/)),
@@ -1672,4 +1753,6 @@ them.
 
 When a completed Anthropic-compatible stream contains malformed tool argument JSON, the SDK does not execute the tool. It returns a matching `tool_result` with `is_error: true`, identifies the JSON syntax problem (including a character position when available), lists required top-level fields, and asks the model to regenerate complete arguments from the tool schema. Raw argument excerpts are not echoed in the error.
 
+From 0.29.1 the error also carries the runtime parser's own message, sanitized so no argument text is included (for example, `Parser error: Bad control character in string literal in JSON.`). *Requires 0.29.1 or later.*
+
 Incomplete intermediate chunks are not errors if the final JSON is valid. Valid JSON objects, including `{}`, still go through normal schema validation. Valid JSON values that are not objects are rejected before execution. Existing turn limits still apply; this feedback does not guarantee that a model will correct its response.

package/dist/index.d.ts

@@ -248,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;
@@ -604,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).
      */
@@ -622,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>;
     /**
@@ -788,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 {
 }