agent-lattice 0.9.24 → 0.12.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:
@@ -230,9 +277,13 @@ const tracer = createLangSmithContextTracer({
 });
 ```
 
-LangSmith receives one root `chain` run per SDK query, child `llm` runs for
-model turns, child `tool` runs for SDK tool calls, and run events for auxiliary
-trace events.
+LangSmith receives one root `chain` run per SDK query. For an `Agent` query,
+model turns and SDK tool calls appear as child `llm` and `tool` runs. For a
+`Team` query, the root represents the complete Team invocation; the initial
+Lead run, delegated Member runs, and later Lead runs all appear beneath that
+root and share one trace session. Each Agent keeps its own SDK session identity,
+recorded as `agent_session_id` metadata, so tracing does not change Agent state
+or returned SDK messages.
 
 Custom sinks can implement the same interface for SQLite, OpenTelemetry, object
 storage, or host-specific observability. The functions below are application
@@ -283,6 +334,47 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## Concurrent Tool Calls
+
+The model requests concurrency by returning multiple `tool_use` blocks in one
+assistant message. The SDK makes the final safety decision. By default, only
+tools whose parsed input passes `isConcurrencySafe(input)` run together:
+
+```ts
+const search = tool(
+  "search",
+  "Search documents",
+  z.object({ query: z.string() }),
+  async ({ query }) => {
+    // App code: replace with your database or search client.
+    return { content: await documentIndex.search(query) };
+  },
+  { isConcurrencySafe: () => true },
+);
+
+const agent = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [search],
+  toolConcurrency: { mode: "safe", maxConcurrency: 8 },
+});
+```
+
+`safe` is the default mode, `maxConcurrency` defaults to `10`, and tools without
+an `isConcurrencySafe` declaration stay sequential. Use `mode: "all"` only when
+every tool in the Agent is safe to overlap. Use `mode: "sequential"` to disable
+tool concurrency even for tools marked safe.
+
+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.
+
+The SDK waits for the complete batch before requesting the model again. Tools
+may finish in any order, while the `tool_result` blocks sent to the model remain
+in the original `tool_use` order. One tool failure does not discard the other
+results. On abort, running handlers receive the shared `AbortSignal`, queued
+handlers do not start, and the SDK waits for handlers that already started to
+settle.
+
 ## Tool Batch Policy
 
 Use `toolBatchPolicy` when some tools must not run in the same model response.
@@ -324,6 +416,44 @@ 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.
 
+## 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
@@ -852,3 +982,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

@@ -150,9 +150,23 @@ 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" | "max_tokens" | "stop_sequence" | "tool_use" | "pause_turn" | "refusal" | (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 +182,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,7 +227,58 @@ 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;
+};
+/**
+ * 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;
+};
 export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
     description: string;
@@ -219,6 +287,12 @@ export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     jsonSchema: Record<string, unknown>;
     parse(input: unknown): TInput;
     handler: ToolHandler<TInput, TContext>;
+    isConcurrencySafe?: (input: TInput) => boolean;
+};
+export type ToolConcurrencyMode = "safe" | "all" | "sequential";
+export type ToolConcurrencyOptions = {
+    mode?: ToolConcurrencyMode;
+    maxConcurrency?: number;
 };
 export type SkillDefinition = {
     name: string;
@@ -412,8 +486,14 @@ 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>;
+    toolConcurrency?: ToolConcurrencyOptions;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
@@ -430,6 +510,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;
@@ -445,6 +528,7 @@ export type ThinkingConfig = {
 } | {
     type: "disabled";
 };
+export type ReasoningEffort = "low" | "high" | "max";
 export type SDKSystemInitMessage = {
     type: "system";
     subtype: "init";
@@ -471,12 +555,19 @@ 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;
+    /** 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 | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
 export type TeamRunnerSource = AgentRuntimeSource;
@@ -518,6 +609,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);
@@ -526,8 +623,8 @@ export declare class ToolPermissionDeniedError extends AgentSDKError {
     readonly denial: PermissionDenial;
     constructor(denial: PermissionDenial);
 }
-export declare function tool<TContext = unknown>(): <TSchema>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>) => ToolDefinition<InferInput<TSchema>, TContext>;
-export declare function tool<TSchema, TContext = unknown>(name: string, description: string, inputSchema: TSchema, handler: ToolHandler<InferInput<TSchema>, TContext>): ToolDefinition<InferInput<TSchema>, TContext>;
+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>;
 export type DelegateToolOptions = {
     wait?: DelegateWaitMode;
     targetMailboxId?: string;
@@ -565,6 +662,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;
@@ -583,6 +686,7 @@ export declare function query<TContext = unknown>(params: AgentOptions<TContext>
     stream?: boolean;
     outputFormat?: OutputFormat;
     thinkingConfig?: ThinkingConfig;
+    reasoningEffort?: ReasoningEffort;
     signal?: AbortSignal;
     context?: TContext;
 }): AsyncGenerator<SDKMessage>;
@@ -591,8 +695,16 @@ export declare class Agent<TContext = unknown> {
     private readonly modelClient;
     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;
@@ -601,6 +713,8 @@ export declare class Agent<TContext = unknown> {
     private messagesForModel;
     private selectSkills;
     private runTool;
+    private executeToolBatch;
+    private isToolCallConcurrencySafe;
 }
 type InferInput<TSchema> = TSchema extends {
     parse(input: unknown): infer TInput;