agent-lattice 0.14.0 → 0.16.0

package/README.md

@@ -73,6 +73,19 @@ 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.
 
+`query()` yields these SDK messages:
+
+| Type | When | What it carries |
+| --- | --- | --- |
+| `system` | Query start | Session init metadata (model, tools, `session_id`). |
+| `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. |
+
+For the exact per-event guarantees see
+[Streaming Events](https://docs.claude-code-sdk.com/concepts/streaming-events/).
+
 Pass `{ stream: false }` to disable model streaming for a query:
 
 ```ts
@@ -334,6 +347,29 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## End The Run From A Tool
+
+*Requires 0.16.0 or later.*
+
+A tool that has the final answer can end the run itself by returning
+`endTurn: true`. The SDK finishes with `subtype: "success"` and uses that
+tool's text content as the result, without calling the model again:
+
+```ts
+const finish = tool(
+  "finish",
+  "Submit the final answer and end the run",
+  z.object({ answer: z.string() }),
+  async ({ answer }) => ({ content: answer, endTurn: true }),
+);
+```
+
+`endTurn` does not cancel the other tools of the same batch — they already
+started concurrently, their `tool_result` blocks still enter the history, and
+`onToolResult` hooks and trace events run for them as usual. Only the next
+model call is skipped. When several tools in a batch set `endTurn`, the first
+one's content becomes the result text.
+
 ## Concurrent Tool Calls
 
 The model requests concurrency by returning multiple `tool_use` blocks in one
@@ -694,12 +730,55 @@ const mcp = await connectMCPStreamableHTTPServer("https://mcp.example.com/mcp",
 type AgentLike<TContext = unknown> = {
   query(prompt, options?): AsyncGenerator<SDKMessage | TeamRunnerMessage>;
   prompt(prompt, options?): Promise<SDKResultMessage>;
+  interrupt(): void;
 };
 ```
 
+`interrupt()` ends the in-flight model request with an `"interrupted"` result
+(see [Interrupting A Query](#interrupting-a-query)); on a `Team` or
+`TeamRunner` it delegates to the lead/root agent. *Requires 0.16.0 or later.*
+
 That means a team can be used anywhere a callable agent is expected. From the
 outside, a team is an agent; inside, it can contain a whole organization.
 
+## Agent Specs (Templates) And Sessions
+
+*Requires 0.15.0 or later.*
+
+`createAgent()` returns a live session: one conversation, one history, one
+workspace. `defineAgent()` returns an `AgentSpec` — a template carrying the
+same options but no state. `spawn()` creates an independent session from it:
+
+```ts
+import { agentTool, defineAgent } from "agent-lattice";
+
+const reviewerSpec = defineAgent({
+  name: "reviewer",
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You are a senior code reviewer...",
+});
+
+// Register the spec: every tool call spawns a fresh session with no memory
+// of previous calls. This is the safe default for reuse.
+const lead = createAgent({
+  model: "claude-sonnet-4-5",
+  tools: [
+    agentTool("review", reviewerSpec, {
+      description: "Ask the reviewer to audit a change.",
+    }),
+  ],
+});
+
+// Register a spawned session instead when the target should remember earlier
+// tasks across calls — continuity is an explicit opt-in.
+const reviewSession = reviewerSpec.spawn();
+```
+
+The same union applies to `delegateTool()`. The generated tool description
+states which semantics a target has, so the calling agent knows whether each
+task must be self-contained. Existing code that passes an `AgentLike` keeps
+its current behavior: a long-lived session with history.
+
 ## Team Mailbox Collaboration
 
 Use `createTeam()` when you want to talk to one `AgentLike` while it coordinates
@@ -1036,8 +1115,8 @@ 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.
+instance. To persist it or resume a conversation in another process, attach a
+`HistoryStore` — see [Persistent History And Resume](#persistent-history-and-resume).
 
 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
@@ -1046,6 +1125,54 @@ 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.
 
+## Persistent History And Resume
+
+*Requires 0.16.0 or later.*
+
+Pass a `HistoryStore` to seed an Agent's history from durable storage and have
+every later write mirrored back. `createJsonlHistoryStore()` persists one JSON
+message per line:
+
+```ts
+import { createAgent, createJsonlHistoryStore } from "agent-lattice";
+
+const historyStore = createJsonlHistoryStore({
+  path: ".agent-sessions/ada.jsonl",
+});
+
+const agent = createAgent({
+  apiKey: process.env.DEEPSEEK_API_KEY,
+  baseURL: "https://api.deepseek.com/anthropic",
+  model: "deepseek-v4-flash",
+  historyStore,
+});
+
+// The first query lazily loads any history the store already holds, then the
+// new prompt continues from it. Every user, assistant, and tool_result message
+// is appended to the file as it lands.
+const result = await agent.prompt("What is my name?");
+
+// A copy of the live history, safe to inspect or mutate.
+const transcript = await agent.getHistory();
+```
+
+The store contract is three methods — `load()`, `append(message)`, and
+`replace(messages)` — each synchronous or returning a promise:
+
+- `load()` runs once per Agent lifetime, lazily before the first query (the
+  constructor cannot be async). Resuming across processes is simply a new
+  Agent over the same store; the "one Agent, one conversation" rule is
+  unchanged.
+- `append(message)` follows every message added to the history.
+- `replace(messages)` follows compaction, which rewrites the whole history —
+  a store must support full replacement, not just appends.
+
+The JSONL store's `load()` skips malformed lines rather than failing, so a
+torn final write does not lose the rest of the transcript. By default a
+failing store is swallowed and the conversation continues in memory only,
+mirroring the tracer's failure semantics; set `failOnError: true` on the store
+to propagate store errors out of `query()` instead.
+
 ## Deadlines
 
 `QueryOptions.signal` bounds a whole query — every model request, tool call, and
@@ -1075,6 +1202,32 @@ Both limits are enforced by the SDK rather than delegated. `ModelRequest` carrie
 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.
 
+## Interrupting A Query
+
+*Requires 0.16.0 or later.*
+
+`agent.interrupt()` ends the current query without tearing the conversation
+down. Where `QueryOptions.signal` terminates the query with `"error_abort"`,
+`interrupt()` aborts only the in-flight model request and finishes with
+`subtype: "interrupted"` — normal control flow, so `is_error` stays `false`.
+As on abort, the partial assistant message is dropped, but every completed
+turn stays in the history, so the host can continue the same Agent with a new
+`query()` that injects its own message:
+
+```ts
+const pending = agent.prompt("Draft the release notes.");
+agent.interrupt(); // e.g. the user typed a correction
+const result = await pending;
+// result.subtype === "interrupted"
+
+await agent.prompt("Actually, skip 0.15.x and cover 0.16.0 only.");
+```
+
+An interrupt that lands while a tool batch is executing takes effect once the
+batch completes: its tool results are written to history first, and the query
+ends `"interrupted"` before the next model call. `interrupt()` is a no-op when
+no query is running.
+
 ## Token Usage And Truncation
 
 Every `result` message reports `usage`, summed over the model requests in that
@@ -1097,3 +1250,13 @@ 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.
+
+Assistant messages also carry provider response metadata: `providerResponseId`
+is the provider-assigned response id and `model` is the model that actually
+served the response, which may differ from the requested `AgentOptions.model`.
+The built-in Anthropic client fills both in on streaming and non-streaming
+requests; a custom `ModelClient` may set them on the `AssistantModelMessage` it
+returns. Both fields are optional and absent when the client does not report
+them.
+
+*Requires 0.16.0 or later.*

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export type AgentLikeEvent = SDKMessage | TeamRunnerMessage;
 export type AgentLike<TContext = unknown> = {
     query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<AgentLikeEvent>;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
+    /** End the in-flight model request with an "interrupted" result; follow up with a new query(). No-op when idle. */
+    interrupt(): void;
 };
 export type DelegateWaitMode = "result" | "accepted";
 export type AgentRuntimeSource = {
@@ -150,6 +152,26 @@ export type ModelMessage = {
     role: "user" | "assistant";
     content: string | ContentBlock[];
 };
+/**
+ * Persistence adapter for an Agent's conversation history. `load()` runs once
+ * per Agent lifetime, before the first query; `append()` follows every message
+ * added to the history; `replace()` follows compaction, which rewrites the
+ * whole history — a store must support full replacement. Methods may be
+ * synchronous or return a promise; the Agent awaits them to preserve order.
+ * Like `ContextTracer`, a failing store is swallowed by default and the
+ * conversation continues in memory only; set `failOnError` to propagate store
+ * errors out of `query()` instead.
+ */
+export type HistoryStore = {
+    failOnError?: boolean;
+    load(): ModelMessage[] | Promise<ModelMessage[]>;
+    append(message: ModelMessage): void | Promise<void>;
+    replace(messages: ModelMessage[]): void | Promise<void>;
+};
+export type JsonlHistoryStoreOptions = {
+    path: string;
+    failOnError?: boolean;
+};
 export type TokenUsage = {
     input_tokens: number;
     output_tokens: number;
@@ -171,6 +193,13 @@ export type AssistantModelMessage = {
     /** Absent when a custom ModelClient does not report it. */
     usage?: TokenUsage;
     stopReason?: StopReason;
+    /** The provider-assigned response id. Absent when a custom ModelClient does not report it. */
+    providerResponseId?: string;
+    /**
+     * The model that actually served this response, which may differ from
+     * `ModelRequest.model`. Absent when a custom ModelClient does not report it.
+     */
+    model?: string;
 };
 export type ModelToolDefinition = {
     name: string;
@@ -197,6 +226,8 @@ export interface ModelClient {
 }
 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;
 };
 export type ToolKind = "tool" | "agent_tool";
 export type ToolBatchCall = {
@@ -458,6 +489,8 @@ export type Team = {
     drain(options?: TeamDrainOptions): Promise<TeamDrainResult>;
     query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+    /** Interrupts the lead agent's in-flight model request. */
+    interrupt(): void;
 };
 export type TeamDrainOptions = {
     maxRounds?: number;
@@ -480,6 +513,8 @@ export type TeamRunner = {
     mailbox: TeamMailbox;
     query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions): Promise<SDKResultMessage>;
+    /** Interrupts the root agent's in-flight model request. */
+    interrupt(): void;
 };
 export type PermissionRequest = {
     toolName: string;
@@ -524,6 +559,12 @@ export type AgentOptions<TContext = unknown> = {
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
     modelClient?: ModelClient;
     tracer?: ContextTracer;
+    /**
+     * Persistence adapter for the conversation history. Seeded via `load()` once
+     * before the first query, then notified on every history write. Compaction
+     * calls `replace()`, so the store must support full replacement.
+     */
+    historyStore?: HistoryStore;
 };
 export type BareAgentOptions<TContext = unknown> = Omit<AgentOptions<TContext>, "workspace">;
 export type AgentWorkspaceToolsOptions = {
@@ -579,6 +620,14 @@ export type SDKAssistantMessage = {
     message: AssistantModelMessage;
     session_id: string;
 };
+/**
+ * Emitted only after a whole tool batch finishes — one event per batch, never
+ * one per tool, and never for the prompt (the prompt is not echoed; subscribe
+ * a `ContextTracer` for a full transcript). `message.content` is always
+ * `ToolResultBlock[]`; the declared `ModelMessage` type is wider than this
+ * guarantee. `tool_use_result` is a convenience view: a single tool's result
+ * `content`, or the array of result blocks when the batch had several tools.
+ */
 export type SDKUserMessage = {
     type: "user";
     message: ModelMessage;
@@ -593,7 +642,12 @@ export type SDKStreamEventMessage = {
 };
 export type SDKResultMessage = {
     type: "result";
-    subtype: "success" | "error" | "error_max_turns" | "error_abort" | "error_timeout";
+    /**
+     * `"interrupted"` is not an error: `Agent.interrupt()` ends the query this
+     * 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";
     is_error: boolean;
     result: string;
     session_id: string;
@@ -692,12 +746,33 @@ export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
 };
-export declare function agentTool(name: string, agent: AgentLike<any>, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
-export declare function delegateTool(name: string, description: string, agent: AgentLike<any>, options?: DelegateToolOptions): ToolDefinition<{
+/**
+ * An AgentLike is a live session: it keeps its conversation history across
+ * calls. An AgentSpec is a template: each call spawns a fresh session with no
+ * memory of previous calls. Prefer a spec unless the parent explicitly wants
+ * continuity.
+ */
+export type AgentToolTarget = AgentLike<any> | AgentSpec<any>;
+export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function delegateTool(name: string, description: string, agent: AgentToolTarget, options?: DelegateToolOptions): ToolDefinition<{
     task: string;
 }>;
 export declare function createAgent<TContext = unknown>(options: AgentOptions<TContext>): Agent<TContext>;
 export declare function createBareAgent<TContext = unknown>(options: BareAgentOptions<TContext>): Agent<TContext>;
+/**
+ * A template describing an agent's identity: model, prompt, tools, skills,
+ * and workspace policy. A spec carries no conversation state; `spawn()`
+ * creates an independent session (an Agent) that owns its own history and
+ * workspace. Register a spec wherever a capability should be reused without
+ * leaking memory between tasks; spawn a session when continuity is wanted.
+ */
+export type AgentSpec<TContext = unknown> = {
+    readonly name?: string;
+    readonly options: AgentOptions<TContext>;
+    spawn(overrides?: Partial<AgentOptions<TContext>>): Agent<TContext>;
+};
+export declare function defineAgent<TContext = unknown>(options: AgentOptions<TContext>): AgentSpec<TContext>;
+export declare function isAgentSpec(target: AgentLike<any> | AgentSpec<any>): target is AgentSpec<any>;
 export declare function createBuiltinTools(options?: AgentWorkspaceToolsOptions): Array<ToolDefinition<any, any>>;
 export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
 /**
@@ -713,6 +788,15 @@ export declare function loadSkill(path: string): Promise<SkillDefinition>;
 export declare function createMCPTools(client: MCPClient, options?: MCPToolsOptions): Promise<Array<ToolDefinition<Record<string, unknown>>>>;
 export declare function connectMCPStdioServer(server: StdioServerParameters, options?: MCPStdioServerOptions): Promise<MCPStdioConnection>;
 export declare function connectMCPStreamableHTTPServer(url: string | URL, options?: MCPStreamableHTTPServerOptions): Promise<MCPStreamableHTTPConnection>;
+/**
+ * Persists an Agent's history as one JSON message per line. `append()` adds a
+ * line; `replace()` rewrites the whole file, which is how compaction is
+ * persisted. `load()` reads every line and skips malformed ones — a truncated
+ * final line from a torn write must not lose the rest of the transcript.
+ * Writes are serialized through an internal queue, so callers may fire them
+ * without waiting for ordering.
+ */
+export declare function createJsonlHistoryStore(options: JsonlHistoryStoreOptions): HistoryStore;
 export declare function teamMember(input: TeamMemberInput): TeamMemberDefinition;
 export declare function createMemoryMailbox(): TeamMailbox;
 export declare function createSQLiteMailbox(options: SQLiteMailboxOptions): TeamMailbox;
@@ -735,6 +819,8 @@ export declare class Agent<TContext = unknown> {
     private readonly sessionId;
     private readonly toolConcurrency;
     private running;
+    private interruptController;
+    private historyLoaded;
     constructor(options: AgentOptions<TContext>);
     /**
      * One Agent owns one conversation. Overlapping queries would interleave writes
@@ -742,8 +828,32 @@ export declare class Agent<TContext = unknown> {
      * a conversation containing someone else's turns.
      */
     query(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): AsyncGenerator<SDKMessage>;
+    /**
+     * Abort the in-flight model request and end the current query with subtype
+     * "interrupted". Completed turns stay in history; follow up with a new
+     * query() to continue the conversation. Unlike `QueryOptions.signal`, which
+     * terminates the query as an error, an interrupt is normal control flow.
+     * A no-op when no query is running.
+     */
+    interrupt(): void;
+    /**
+     * The store is read once per Agent lifetime, lazily on the first query or
+     * getHistory() call — the constructor cannot be async. A failed load follows
+     * the same rule as a failed write: swallowed unless `failOnError` is set, in
+     * which case the error propagates and the Agent starts empty.
+     */
+    private ensureHistoryLoaded;
+    private loadHistory;
+    private appendStoredHistory;
+    private replaceStoredHistory;
     private runQuery;
     prompt(prompt: string | ContentBlock[], options?: QueryOptions<TContext>): Promise<SDKResultMessage>;
+    /**
+     * The conversation history as currently held by this Agent, including any
+     * messages seeded from `AgentOptions.historyStore`. Returns a deep copy, so
+     * mutating the result cannot corrupt the live conversation.
+     */
+    getHistory(): Promise<ModelMessage[]>;
     addTools(tools: Array<ToolDefinition<any, TContext>>): void;
     private initMessage;
     private resultMessage;