agent-lattice 0.16.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:
 
@@ -221,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:
 
@@ -237,7 +242,6 @@ LANGSMITH_WORKSPACE_ID=<your-langsmith-workspace-id>
 ```
 
 ```ts
-import { RunTree } from "langsmith/run_trees";
 import {
   createAgent,
   createCompositeContextTracer,
@@ -248,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"],
@@ -277,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,
@@ -290,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
@@ -299,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
@@ -730,13 +740,15 @@ 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(): 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. *Requires 0.16.0 or later.*
+`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.
@@ -1170,8 +1182,42 @@ The store contract is three methods — `load()`, `append(message)`, and
 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.
+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
 
@@ -1204,7 +1250,7 @@ loop indefinitely. Losing that race abandons the call rather than cancelling it.
 
 ## Interrupting A Query
 
-*Requires 0.16.0 or later.*
+*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"`,
@@ -1225,8 +1271,10 @@ 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.
+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
 

package/dist/index.d.ts

@@ -34,8 +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(). No-op when idle. */
-    interrupt(): void;
+    /**
+     * 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 = {
@@ -117,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>;
@@ -135,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;
@@ -159,11 +164,18 @@ export type ModelMessage = {
  * 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.
+ * 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 = {
-    failOnError?: boolean;
     load(): ModelMessage[] | Promise<ModelMessage[]>;
     append(message: ModelMessage): void | Promise<void>;
     replace(messages: ModelMessage[]): void | Promise<void>;
@@ -489,8 +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. */
-    interrupt(): void;
+    /** 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;
@@ -513,8 +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. */
-    interrupt(): void;
+    /** 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;
@@ -774,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
@@ -782,7 +803,7 @@ 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>>>>;
@@ -796,6 +817,16 @@ export declare function connectMCPStreamableHTTPServer(url: string | URL, option
  * 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;
@@ -812,7 +843,13 @@ 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;
@@ -833,14 +870,17 @@ export declare class Agent<TContext = unknown> {
      * "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.
+     * 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(): void;
+    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` is set, in
-     * which case the error propagates and the Agent starts empty.
+     * 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;
@@ -854,6 +894,16 @@ export declare class Agent<TContext = unknown> {
      * 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;
@@ -878,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 {};