agent-lattice 0.9.25 → 0.14.0

package/README.md

@@ -7,6 +7,11 @@ Install it from npm as `agent-lattice`. It works with Anthropic and
 Anthropic-compatible providers such as DeepSeek, without installing the Claude
 Code CLI runtime.
 
+> **Integrating this SDK from an AI agent?** Start at
+> <https://docs.claude-code-sdk.com/llms.txt> for an index of the documentation,
+> where every page is served as clean Markdown. Read
+> <https://docs.claude-code-sdk.com/llms-full.txt> to take it all in one request.
+
 ## Install
 
 ```bash
@@ -50,6 +55,24 @@ const agent = createBareAgent({
 });
 ```
 
+`agent.query()` yields `stream_event` messages while the model is still
+responding, so a host can render output incrementally:
+
+```ts
+for await (const message of agent.query("Say hello")) {
+  if (message.type === "stream_event") {
+    const event = message.event as { type: string; delta?: { text?: string } };
+    if (event.type === "content_block_delta" && event.delta?.text) {
+      process.stdout.write(event.delta.text);
+    }
+  }
+}
+```
+
+The SDK produces the next event only after the loop takes the current one.
+Slow work in the loop body delays later events without dropping or reordering
+them, so keep expensive handling off the loop itself.
+
 Pass `{ stream: false }` to disable model streaming for a query:
 
 ```ts
@@ -103,6 +126,30 @@ Use `{ type: "adaptive" }` for models that support adaptive thinking. Use
 budget is capped at `maxTokens - 1` to satisfy the Anthropic API constraint.
 When omitted, the SDK does not send a thinking configuration.
 
+For Kimi K3 through an Anthropic-compatible endpoint or gateway, use
+`reasoningEffort` to send the provider's top-level `reasoning_effort` parameter:
+
+```ts
+const agent = createAgent({
+  apiKey: process.env.MOONSHOT_API_KEY,
+  baseURL: process.env.KIMI_ANTHROPIC_BASE_URL,
+  model: "kimi-k3",
+  reasoningEffort: "high",
+});
+
+const result = await agent.prompt("Solve this carefully.", {
+  reasoningEffort: "low",
+});
+```
+
+The supported values are `"low"`, `"high"`, and `"max"`. A query-level value
+overrides the agent default. When omitted, the SDK does not send
+`reasoning_effort`, so the provider applies its own default (`"max"` for Kimi
+K3). Kimi K3 does not accept `thinkingConfig`; use `reasoningEffort` instead.
+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.
+
 ## Multimodal Input
 
 Pass Anthropic-compatible content blocks for image or document prompts:
@@ -369,6 +416,100 @@ policy, tool execution is unchanged. A policy prevents known bad combinations
 inside one model response, but it does not replace database transactions or
 revision checks against concurrent external updates.
 
+## Automatic Context Compaction
+
+History only grows, so a long-running agent eventually exceeds the model's
+context window. Enable `autoCompact` to replace the older part of the
+conversation with a model-written summary:
+
+```ts
+const agent = createAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: "claude-sonnet-4-6",
+  autoCompact: true, // or { thresholdTokens: 150_000, keepRecentMessages: 8 }
+});
+```
+
+Compaction runs between turns, once a response reports more input tokens than
+`thresholdTokens` (default `100000`). Everything except the last
+`keepRecentMessages` messages (default `6`) is summarized, and the history is
+rebuilt as that summary followed by the retained messages. The summary is
+wrapped in an instruction telling the model that compaction just happened and to
+continue from it, so the next turn resumes the task instead of restarting it.
+
+Unlike the `onModelRequest` hook, which shapes a single request, this **rewrites
+the stored conversation** — that is what makes the saving persist, but the
+replaced turns are gone.
+
+The cut point never separates a `tool_result` from the `tool_use` that produced
+it, because the model API rejects that. If no safe cut leaves anything to
+summarize, compaction is skipped.
+
+Compaction costs a model call. Its tokens are folded into `result.usage`, and a
+`system` message with `subtype: "compaction"` reports what happened:
+
+```ts
+for await (const message of agent.query("Refactor this module.")) {
+  if (message.type === "system" && message.subtype === "compaction") {
+    console.log(`compacted ${message.compacted_messages} messages`, message.usage);
+  }
+}
+```
+
+The trigger depends on reported usage, so a custom `ModelClient` that omits
+`usage` never compacts. Override the instruction with `prompt`, or read the
+built-in one from `DEFAULT_COMPACTION_PROMPT`.
+
+The threshold is a forecast, so a single large tool result can still carry a
+request past the window. Compaction then runs as a recovery — summarize, then
+retry the same turn — on either `stop_reason: "model_context_window_exceeded"`
+or an API error naming a too-long prompt. It is attempted once per query; if
+summarizing fails or there is nothing left to summarize, the original failure
+surfaces unchanged.
+
+`stop_reason: "max_tokens"` deliberately does **not** trigger compaction. It
+means the *output* hit `maxTokens`, not that the input was too large — the model
+had room to read and ran out of room to write, so compacting the history would
+not make the answer complete. Raise `maxTokens` instead.
+
+## Hooks
+
+`permission` and `toolBatchPolicy` decide whether something runs. Hooks decide
+what it looks like — redacting tool output, trimming context before a request,
+or injecting retrieved documents:
+
+```ts
+const agent = createAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: "claude-sonnet-4-6",
+  tools: [queryDatabase],
+  hooks: {
+    async onToolResult({ toolName, result, error }) {
+      if (toolName !== "queryDatabase") return; // undefined: leave unchanged
+      return { ...result, content: await redact(result.content) };
+    },
+    onModelRequest({ messages, turn }) {
+      if (messages.length < 40) return;
+      return { messages: compact(messages) };
+    },
+  },
+});
+```
+
+`onToolResult` sees every result on its way to the model, including handler
+failures, aborted calls, and calls blocked by `toolBatchPolicy`. `onModelRequest`
+shapes a single request; the stored conversation is untouched, so trimming
+context does not destroy history.
+
+A hook returns a replacement or nothing, and must not mutate what it receives. A
+hook that throws propagates out of `query()` rather than becoming an error
+`result` — a redaction hook that failed quietly would leak the data it exists to
+protect. Hooks run before the matching trace event, so traces record what was
+actually sent.
+
+Compose independent concerns with `createCompositeAgentHooks([a, b, c])`, which
+chains them in order, each receiving the previous one's output.
+
 ## Business Context For Tools
 
 Pass host application data through `context`. The SDK gives that context to
@@ -897,3 +1038,62 @@ console.log(result.result);
 The SDK stores conversation state in memory for the lifetime of the `Agent`
 instance. Persistent transcripts and resume support are intentionally out of
 scope for the first release.
+
+An `Agent` is a conversation, not a reusable client. Because the history is
+instance state, starting a query while another is still running would interleave
+both conversations; the SDK rejects the second one with `ConcurrentQueryError`.
+Create one Agent per concurrent conversation — in a server, per request or per
+user session rather than a shared module-level instance. Sequential reuse, as
+above, is the intended pattern.
+
+## Deadlines
+
+`QueryOptions.signal` bounds a whole query — every model request, tool call, and
+turn together. `requestTimeoutMs` bounds each single model request, so an agent
+that legitimately runs many tool-using turns does not have to fit them all into
+one budget:
+
+```ts
+const agent = createAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: "claude-sonnet-4-6",
+  requestTimeoutMs: 120_000,
+});
+
+const result = await agent.prompt("Audit this repository.", {
+  signal: AbortSignal.timeout(600_000),
+  requestTimeoutMs: 60_000, // overrides the agent default for this query
+});
+```
+
+A request deadline produces `subtype: "error_timeout"` with a `TimeoutError`,
+distinct from the `"error_abort"` of a caller-initiated cancellation, so hosts
+can retry timeouts without retrying deliberate cancellations.
+
+Both limits are enforced by the SDK rather than delegated. `ModelRequest` carries
+`signal` and `timeoutMs` so a client can cancel its own work, but the agent loop
+also races the call, so a `ModelClient` that honours neither cannot stall the
+loop indefinitely. Losing that race abandons the call rather than cancelling it.
+
+## Token Usage And Truncation
+
+Every `result` message reports `usage`, summed over the model requests in that
+query, plus the `stop_reason` of the last response:
+
+```ts
+const result = await agent.prompt("Summarize this file.");
+console.log(result.usage);
+// { input_tokens: 1200, output_tokens: 512, cache_read_input_tokens: 800 }
+
+if (result.stop_reason === "max_tokens") {
+  // subtype is still "success", but result is a fragment, not an answer.
+}
+```
+
+`stop_reason: "max_tokens"` means the model hit its output budget mid-response.
+The SDK does not treat that as an error, so checking this field is the only way
+to distinguish a complete answer from a truncated one.
+
+Usage comes from the model client. The built-in Anthropic client fills it in from
+the response, including the streaming path; a custom `ModelClient` that omits
+`usage` produces zeroed counts rather than an error.

package/dist/index.d.ts

@@ -102,7 +102,7 @@ export type AgentRuntimeContext = {
     emit(message: TeamRunnerMessage): void;
     shouldPauseAfterToolBatch?(): boolean;
 };
-export type ContextTraceEventType = "run_start" | "user_message" | "model_request" | "assistant_message" | "tool_use" | "tool_result" | "team_message" | "result" | "error";
+export type ContextTraceEventType = "run_start" | "user_message" | "model_request" | "assistant_message" | "tool_use" | "tool_result" | "team_message" | "result" | "compaction" | "error";
 export type ContextTraceEvent = {
     version: 1;
     timestamp: string;
@@ -150,9 +150,27 @@ export type ModelMessage = {
     role: "user" | "assistant";
     content: string | ContentBlock[];
 };
+export type TokenUsage = {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+};
+/**
+ * Why the model stopped. `"max_tokens"` means the response was cut off mid-way:
+ * the text is a fragment, not an answer. Left open because providers add values.
+ */
+export type StopReason = "end_turn"
+/** Output hit `maxTokens`. The text is a fragment; compaction does not help. */
+ | "max_tokens" | "stop_sequence" | "tool_use" | "pause_turn" | "refusal"
+/** The context window ran out mid-request. This is what compaction is for. */
+ | "model_context_window_exceeded" | (string & {});
 export type AssistantModelMessage = {
     role: "assistant";
     content: ContentBlock[];
+    /** Absent when a custom ModelClient does not report it. */
+    usage?: TokenUsage;
+    stopReason?: StopReason;
 };
 export type ModelToolDefinition = {
     name: string;
@@ -168,6 +186,9 @@ export type ModelRequest = {
     stream: boolean;
     outputFormat?: OutputFormat;
     thinkingConfig?: ThinkingConfig;
+    reasoningEffort?: ReasoningEffort;
+    /** Deadline for this single request. Clients should honour it; the SDK also enforces it. */
+    timeoutMs?: number;
     onStreamEvent?: (event: Record<string, unknown>) => void;
     signal?: AbortSignal;
 };
@@ -210,6 +231,70 @@ export type ToolExecutionContext<TContext = unknown> = {
     agentRuntime?: AgentRuntimeContext;
     permissions?: RuntimePermissions;
 };
+export type ToolResultHookContext<TContext = unknown> = {
+    toolName: string;
+    toolUseId: string;
+    /** Raw input as the model sent it, before the tool schema parsed it. */
+    input: unknown;
+    /** What the SDK would send back to the model. */
+    result: ToolResultBlock;
+    /** Present when the handler failed, was denied, or was cancelled. */
+    error?: Error;
+    context?: TContext;
+    source?: AgentRuntimeSource;
+    signal?: AbortSignal;
+};
+export type ModelRequestHookContext<TContext = unknown> = {
+    /** What the SDK would send. Not the stored history; see AgentHooks. */
+    messages: ModelMessage[];
+    systemPrompt?: string;
+    /** 1 for the first model request of the query. */
+    turn: number;
+    context?: TContext;
+    source?: AgentRuntimeSource;
+    signal?: AbortSignal;
+};
+export type ModelRequestHookResult = {
+    messages?: ModelMessage[];
+    systemPrompt?: string;
+};
+export declare const DEFAULT_COMPACTION_PROMPT = "Your task is to create a detailed summary of the conversation so far,\npaying close attention to the user's explicit requests and your previous actions.\n\nThis summary should be thorough in capturing:\n- technical details\n- code patterns\n- architectural decisions\n- files that were modified\n- commands that were run\n- errors encountered\n- solutions attempted\n- important context needed to continue the work\n\nPreserve:\n- user's intent\n- important constraints\n- decisions already made\n- reasoning behind decisions\n- unresolved issues\n- next steps\n\nThe summary will replace the conversation history, so include everything\nnecessary for another Claude instance to continue the task successfully.\n\nOutput only the summary.";
+export type AutoCompactOptions = {
+    /**
+     * Compact once a model response reports more input tokens than this.
+     * Defaults to 100000, chosen to leave headroom on a 200k-token model.
+     */
+    thresholdTokens?: number;
+    /** Trailing messages left verbatim after the summary. Defaults to 6. */
+    keepRecentMessages?: number;
+    /** Replaces DEFAULT_COMPACTION_PROMPT. */
+    prompt?: string;
+    /** Model used for the summary. Defaults to the agent's model. */
+    model?: string;
+    /** Output cap for the summary. Defaults to 8192. */
+    maxTokens?: number;
+};
+/**
+ * Lifecycle callbacks that can rewrite what crosses the agent loop's boundaries,
+ * as opposed to `permission` and `toolBatchPolicy`, which can only allow or deny.
+ *
+ * A hook returns a replacement, or nothing to leave the value unchanged; it must
+ * not mutate what it receives.
+ *
+ * A hook that throws propagates out of `query()` rather than being swallowed the
+ * way a tracer error is, or being reported as an error `result`. A hook failure
+ * is host code failing, like `ConcurrentQueryError`, not an upstream failure the
+ * loop can describe to the model — and a redaction hook that failed quietly
+ * would leak the data it exists to protect.
+ *
+ * Hooks run before the matching trace event, so traces record what was actually
+ * sent. `onModelRequest` shapes one request only and never edits the stored
+ * conversation, so trimming context for a long turn does not destroy history.
+ */
+export type AgentHooks<TContext = unknown> = {
+    onToolResult?(context: ToolResultHookContext<TContext>): ToolResultBlock | void | Promise<ToolResultBlock | void>;
+    onModelRequest?(context: ModelRequestHookContext<TContext>): ModelRequestHookResult | void | Promise<ModelRequestHookResult | void>;
+};
 export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput, context: ToolExecutionContext<TContext>) => Promise<ToolResult> | ToolResult;
 export type ToolOptions<TInput = unknown> = {
     isConcurrencySafe?: (input: TInput) => boolean;
@@ -421,8 +506,18 @@ export type AgentOptions<TContext = unknown> = {
     maxTokens?: number;
     maxTurns?: number;
     thinkingConfig?: ThinkingConfig;
+    reasoningEffort?: ReasoningEffort;
+    /** Deadline for each single model request, in milliseconds. Unset means no SDK-side limit. */
+    requestTimeoutMs?: number;
     tools?: Array<ToolDefinition<any, TContext>>;
     toolBatchPolicy?: ToolBatchPolicy<TContext>;
+    /** Lifecycle callbacks that rewrite tool results and outgoing model requests. */
+    hooks?: AgentHooks<TContext>;
+    /**
+     * Replaces older conversation history with a model-written summary once it
+     * grows past a threshold. Off unless set; `true` uses the defaults.
+     */
+    autoCompact?: boolean | AutoCompactOptions;
     toolConcurrency?: ToolConcurrencyOptions;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
@@ -440,6 +535,9 @@ export type QueryOptions<TContext = unknown> = {
     stream?: boolean;
     outputFormat?: OutputFormat;
     thinkingConfig?: ThinkingConfig;
+    reasoningEffort?: ReasoningEffort;
+    /** Overrides the agent's per-request deadline for this query. */
+    requestTimeoutMs?: number;
     signal?: AbortSignal;
     context?: TContext;
     agentRuntime?: AgentRuntimeContext;
@@ -455,6 +553,7 @@ export type ThinkingConfig = {
 } | {
     type: "disabled";
 };
+export type ReasoningEffort = "low" | "high" | "max";
 export type SDKSystemInitMessage = {
     type: "system";
     subtype: "init";
@@ -462,6 +561,19 @@ export type SDKSystemInitMessage = {
     tools: string[];
     session_id: string;
 };
+export type SDKSystemCompactionMessage = {
+    type: "system";
+    subtype: "compaction";
+    session_id: string;
+    /** Messages replaced by the summary. */
+    compacted_messages: number;
+    /** Messages kept verbatim after it. */
+    retained_messages: number;
+    /** Input tokens of the turn that triggered compaction. */
+    trigger_input_tokens: number;
+    /** Cost of producing the summary, already folded into the result usage. */
+    usage: TokenUsage;
+};
 export type SDKAssistantMessage = {
     type: "assistant";
     message: AssistantModelMessage;
@@ -481,14 +593,21 @@ export type SDKStreamEventMessage = {
 };
 export type SDKResultMessage = {
     type: "result";
-    subtype: "success" | "error" | "error_max_turns" | "error_abort";
+    subtype: "success" | "error" | "error_max_turns" | "error_abort" | "error_timeout";
     is_error: boolean;
     result: string;
     session_id: string;
     num_turns: number;
     error?: Error;
-};
-export type SDKMessage = SDKSystemInitMessage | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
+    /** Summed over every model request in the query. Zeroed when unreported. */
+    usage: TokenUsage;
+    /**
+     * From the last model response. Check for `"max_tokens"`: `subtype` is still
+     * `"success"` there, but `result` is a truncated fragment.
+     */
+    stop_reason?: StopReason;
+};
+export type SDKMessage = SDKSystemInitMessage | SDKSystemCompactionMessage | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
 export type TeamRunnerSource = AgentRuntimeSource;
 export type TeamRunnerTeamMessage = {
     type: "team_message";
@@ -528,6 +647,12 @@ export declare class MaxTurnsError extends AgentSDKError {
 }
 export declare class AbortError extends AgentSDKError {
 }
+/** A second query was started on an Agent that was still running one. */
+export declare class ConcurrentQueryError extends AgentSDKError {
+}
+/** A model request exceeded `requestTimeoutMs`. */
+export declare class TimeoutError extends AgentSDKError {
+}
 export declare class ToolBatchRejectedError extends AgentSDKError {
     readonly rejection: ToolBatchPolicyRejection;
     constructor(rejection: ToolBatchPolicyRejection);
@@ -575,6 +700,12 @@ export declare function createAgent<TContext = unknown>(options: AgentOptions<TC
 export declare function createBareAgent<TContext = unknown>(options: BareAgentOptions<TContext>): Agent<TContext>;
 export declare function createBuiltinTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any, any>>;
 export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
+/**
+ * Chains hooks in array order: each one sees the previous one's output, so
+ * redaction, truncation, and auditing can be written separately and combined.
+ * Unlike the composite tracer, a failure is not swallowed — see `AgentHooks`.
+ */
+export declare function createCompositeAgentHooks<TContext = unknown>(hooks: Array<AgentHooks<TContext> | undefined | null>): AgentHooks<TContext>;
 export declare function createCompositeContextTracer(tracers: Array<ContextTracer | undefined | null>): ContextTracer;
 export declare function createLangSmithContextTracer(options: LangSmithContextTracerOptions): ContextTracer;
 export declare function skill(input: SkillInput): SkillDefinition;
@@ -593,6 +724,7 @@ export declare function query<TContext = unknown>(params: AgentOptions<TContext>
     stream?: boolean;
     outputFormat?: OutputFormat;
     thinkingConfig?: ThinkingConfig;
+    reasoningEffort?: ReasoningEffort;
     signal?: AbortSignal;
     context?: TContext;
 }): AsyncGenerator<SDKMessage>;
@@ -602,13 +734,34 @@ export declare class Agent<TContext = unknown> {
     private readonly messages;
     private readonly sessionId;
     private readonly toolConcurrency;
+    private running;
     constructor(options: AgentOptions<TContext>);
+    /**
+     * One Agent owns one conversation. Overlapping queries would interleave writes
+     * into the shared history, so the second caller is rejected rather than served
+     * a conversation containing someone else's turns.
+     */
     query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<SDKMessage>;
+    private runQuery;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
     addTools(tools: Array<ToolDefinition<any, TContext>>): void;
     private initMessage;
     private resultMessage;
     private modelTools;
+    /**
+     * Replaces the summarizable head of the conversation with a model-written
+     * summary. Returns undefined when there is nothing safe to compact, and lets a
+     * failed summarization surface so the caller can decide: compaction is best
+     * effort, and continuing with a full history is better than losing it.
+     */
+    private compactHistory;
+    /**
+     * Last-resort compaction after a turn already ran out of context, as opposed
+     * to the threshold check that runs between turns. Returns the message to emit
+     * so the caller can retry, or undefined when compaction cannot help and the
+     * original failure should surface instead.
+     */
+    private recoverFromOverflow;
     private messagesForModel;
     private selectSkills;
     private runTool;