agent-lattice 0.15.0 → 0.17.0

package/README.md

@@ -55,6 +55,11 @@ const agent = createBareAgent({
 });
 ```
 
+`Agent` is a type-only export — instances come from these factories (or
+`AgentSpec.spawn()`), never from `new Agent()`, because the factories also
+generate the session id and install the workspace. (Breaking in 0.17.0: the
+`Agent` class constructor is no longer exported.)
+
 `agent.query()` yields `stream_event` messages while the model is still
 responding, so a host can render output incrementally:
 
@@ -73,6 +78,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
@@ -208,9 +226,9 @@ for await (const event of team.query("Ask engineering to investigate.", {
 
 ## LangSmith Context Tracing
 
-Pass LangSmith's `RunTree` constructor to the SDK tracer. The SDK depends on
-`langsmith` directly and uses its official `RunTree` / `RunTreeConfig` types for
-this adapter.
+The SDK depends on `langsmith` directly and uses its official `RunTree` /
+`RunTreeConfig` types for this adapter, so the tracer works out of the box —
+no constructor wiring needed.
 
 Configure LangSmith with its standard environment variables:
 
@@ -224,7 +242,6 @@ LANGSMITH_WORKSPACE_ID=<your-langsmith-workspace-id>
 ```
 
 ```ts
-import { RunTree } from "langsmith/run_trees";
 import {
   createAgent,
   createCompositeContextTracer,
@@ -235,7 +252,6 @@ import {
 const tracer = createCompositeContextTracer([
   createJsonlContextTracer({ path: ".agent-runs/session.jsonl" }),
   createLangSmithContextTracer({
-    RunTree,
     projectName: process.env.LANGSMITH_PROJECT,
     workspaceId: process.env.LANGSMITH_WORKSPACE_ID,
     tags: ["local-debug"],
@@ -264,11 +280,9 @@ tracer. `workspaceId` is optional and only selects a LangSmith workspace; it is
 not the tracing project name.
 
 ```ts
-import { RunTree } from "langsmith/run_trees";
 import { createLangSmithContextTracer } from "agent-lattice";
 
 const tracer = createLangSmithContextTracer({
-  RunTree,
   apiKey: process.env.LANGSMITH_API_KEY,
   apiUrl: process.env.LANGSMITH_ENDPOINT,
   projectName: process.env.LANGSMITH_PROJECT,
@@ -277,6 +291,9 @@ const tracer = createLangSmithContextTracer({
 });
 ```
 
+`RunTree` defaults to the bundled langsmith constructor since 0.17.0; pass
+`RunTree` or `runTree` only to inject a custom runtime or a test fake.
+
 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
@@ -286,15 +303,21 @@ 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
-code you provide, not SDK exports:
+storage, or host-specific observability. A `ContextTracer` port object exposes
+methods only — `failOnError` is bound when the factory creates the tracer, not
+set as a field afterwards. Implement a custom sink with `defineContextTracer()`.
+*Requires 0.17.0 or later.* (Breaking in 0.17.0: the public `failOnError` field
+was removed from `ContextTracer`; custom tracers created before 0.17.0 must go
+through `defineContextTracer()`.)
 
 ```ts
-const tracer = {
+import { defineContextTracer } from "agent-lattice";
+
+const tracer = defineContextTracer({
   async onEvent(event) {
     // TODO: Replace with your own storage/logging code.
   },
-};
+});
 ```
 
 ## DeepSeek Anthropic-compatible API
@@ -334,6 +357,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,9 +740,16 @@ 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(): boolean;
 };
 ```
 
+`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. It returns `true` when a
+query was interrupted and `false` when idle. *Requires 0.16.0 or later; the
+`boolean` return requires 0.17.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.
 
@@ -1074,8 +1127,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
@@ -1084,6 +1137,88 @@ 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; bind `failOnError: true` when the
+store is created (via `createJsonlHistoryStore()` options or
+`defineHistoryStore()`) to propagate store errors out of `query()` instead.
+
+Implement a custom store with `defineHistoryStore()`, which validates the
+three methods and binds `failOnError`; the returned port object exposes
+methods only. *Requires 0.17.0 or later.* (Breaking in 0.17.0: the public
+`failOnError` field was removed from `HistoryStore`; custom stores created
+before 0.17.0 must go through `defineHistoryStore()`.)
+
+```ts
+import { defineHistoryStore } from "agent-lattice";
+
+const historyStore = defineHistoryStore({
+  load: () => loadMessagesFromYourDatabase(),
+  append: message => appendMessageToYourDatabase(message),
+  replace: messages => replaceMessagesInYourDatabase(messages),
+});
+```
+
+To rewrite the history from the host instead of from compaction, use
+`agent.replaceHistory(messages)`. *Requires 0.17.0 or later.* It is idle-only:
+calling it while a query is running throws `ConcurrentQueryError`, the same
+guard as a concurrent `query()`. When a `historyStore` is configured the store
+is replaced too, so persistence stays in sync, and the replacement also
+suppresses the lazy `load()` — seeding never overwrites what the host just
+installed. The SDK does not validate the content: the host owns it, and the
+history must be well-formed (e.g. no dangling `tool_use` without its matching
+`tool_result`).
+
+```ts
+await agent.replaceHistory([
+  { role: "user", content: "My name is Ada." },
+  { role: "assistant", content: [{ type: "text", text: "Nice to meet you, Ada." }] },
+]);
+```
+
 ## Deadlines
 
 `QueryOptions.signal` bounds a whole query — every model request, tool call, and
@@ -1113,6 +1248,34 @@ 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; `interrupt()` returns `boolean` from 0.17.0.*
+
+`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()` returns `true`
+when a query was running and is now interrupted, and `false` when idle — a
+`false` tells the host there is nothing to wait for, so it can send its next
+query directly.
+
 ## Token Usage And Truncation
 
 Every `result` message reports `usage`, summed over the model requests in that
@@ -1135,3 +1298,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,12 @@ 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(). Returns `true` when a query was interrupted, `false`
+     * when idle — a `false` means the host can send its next query directly.
+     */
+    interrupt(): boolean;
 };
 export type DelegateWaitMode = "result" | "accepted";
 export type AgentRuntimeSource = {
@@ -115,7 +121,6 @@ export type ContextTraceEvent = {
     data: Record<string, unknown>;
 };
 export type ContextTracer = {
-    failOnError?: boolean;
     onEvent(event: ContextTraceEvent): Promise<void> | void;
     flush?(): Promise<void>;
     close?(): Promise<void>;
@@ -133,7 +138,9 @@ export type LangSmithRunTreeLike = RunTree;
 export type LangSmithRunTreeConstructor = new (config: LangSmithRunTreeConfig) => LangSmithRunTreeLike;
 export type LangSmithWriteReplicaConfig = NonNullable<LangSmithRunTreeConfig["replicas"]>[number];
 export type LangSmithContextTracerOptions = {
+    /** Defaults to the bundled langsmith RunTree; inject a constructor for custom runtimes. */
     RunTree?: LangSmithRunTreeConstructor;
+    /** Factory form of RunTree, mainly for tests. Takes precedence over RunTree. */
     runTree?: (config: LangSmithRunTreeConfig) => LangSmithRunTreeLike;
     projectName?: string;
     name?: string;
@@ -150,6 +157,33 @@ 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; pass `failOnError` to the factory
+ * that creates the store (`createJsonlHistoryStore`, `defineHistoryStore`)
+ * to propagate store errors out of `query()` instead.
+ *
+ * The objects passed to `append()` and `replace()` are guaranteed to carry at
+ * least `role` and `content`. Runtime objects may carry extra fields (`usage`,
+ * `stopReason`, `providerResponseId`, `model`) that are not part of the
+ * contract and must not be relied on; hosts that need response metadata for
+ * reconciliation or analytics should use the ContextTracer's
+ * `assistant_message` events instead.
+ */
+export type HistoryStore = {
+    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 +205,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 +238,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 +501,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; returns `true` when a query was interrupted, `false` when idle. */
+    interrupt(): boolean;
 };
 export type TeamDrainOptions = {
     maxRounds?: number;
@@ -480,6 +525,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; returns `true` when a query was interrupted, `false` when idle. */
+    interrupt(): boolean;
 };
 export type PermissionRequest = {
     toolName: string;
@@ -524,6 +571,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 +632,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 +654,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;
@@ -720,6 +786,15 @@ export type AgentSpec<TContext = unknown> = {
 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>>;
+/**
+ * Entry point for implementing a custom trace sink. Validates that the
+ * required `onEvent` method exists and binds `failOnError` at creation time —
+ * a `ContextTracer` exposes methods only; the flag travels with the returned
+ * object as internal metadata the runtime reads when a call throws.
+ */
+export declare function defineContextTracer(impl: ContextTracer & {
+    failOnError?: boolean;
+}): ContextTracer;
 export declare function createJsonlContextTracer(options: JsonlContextTracerOptions): ContextTracer;
 /**
  * Chains hooks in array order: each one sees the previous one's output, so
@@ -728,12 +803,31 @@ export declare function createJsonlContextTracer(options: JsonlContextTracerOpti
  */
 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 createLangSmithContextTracer(options?: LangSmithContextTracerOptions): ContextTracer;
 export declare function skill(input: SkillInput): SkillDefinition;
 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.
+ */
+/**
+ * Entry point for implementing a custom history store. Validates that the
+ * required `load`/`append`/`replace` methods exist and binds `failOnError` at
+ * creation time — a `HistoryStore` exposes methods only; the flag travels
+ * with the returned object as internal metadata the runtime reads when a call
+ * throws.
+ */
+export declare function defineHistoryStore(impl: HistoryStore & {
+    failOnError?: boolean;
+}): HistoryStore;
+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;
@@ -749,13 +843,21 @@ export declare function query<TContext = unknown>(params: AgentOptions<TContext>
     signal?: AbortSignal;
     context?: TContext;
 }): AsyncGenerator<SDKMessage>;
-export declare class Agent<TContext = unknown> {
+/**
+ * An Agent owns one conversation: history, workspace, and session identity.
+ * Create instances with `createAgent()` or `createBareAgent()` (or spawn from
+ * an `AgentSpec`) — the constructor is intentionally not exported, because the
+ * factories also generate the session id and install workspace tools.
+ */
+declare class Agent<TContext = unknown> {
     private readonly options;
     private readonly modelClient;
     private readonly messages;
     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
@@ -763,8 +865,45 @@ 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.
+     * Returns `true` when a query was running and is now interrupted, `false`
+     * when idle — a `false` tells the host it can send its next query directly
+     * instead of waiting for an "interrupted" result.
+     */
+    interrupt(): boolean;
+    /**
+     * 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` was bound
+     * by the store's factory, 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[]>;
+    /**
+     * Replace the conversation history. Idle only: throws ConcurrentQueryError
+     * while a query is running. When a historyStore is configured the store is
+     * replaced too, so persistence stays in sync.
+     *
+     * The host owns the content: the SDK does not validate the messages, so the
+     * replacement must be a well-formed history — e.g. no dangling `tool_use`
+     * without its matching `tool_result`.
+     */
+    replaceHistory(messages: ModelMessage[]): Promise<void>;
     addTools(tools: Array<ToolDefinition<any, TContext>>): void;
     private initMessage;
     private resultMessage;
@@ -789,7 +928,7 @@ export declare class Agent<TContext = unknown> {
     private executeToolBatch;
     private isToolCallConcurrencySafe;
 }
+export type { Agent };
 type InferInput<TSchema> = TSchema extends {
     parse(input: unknown): infer TInput;
 } ? TInput : Record<string, unknown>;
-export {};