agent-lattice 0.12.0 → 0.15.0

package/README.md

@@ -416,6 +416,62 @@ 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
@@ -644,6 +700,44 @@ type AgentLike<TContext = unknown> = {
 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

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;
@@ -160,7 +160,11 @@ export type TokenUsage = {
  * 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 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[];
@@ -254,6 +258,22 @@ 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.
@@ -493,6 +513,11 @@ export type AgentOptions<TContext = unknown> = {
     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;
@@ -536,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;
@@ -569,7 +607,7 @@ export type SDKResultMessage = {
      */
     stop_reason?: StopReason;
 };
-export type SDKMessage = SDKSystemInitMessage | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
+export type SDKMessage = SDKSystemInitMessage | SDKSystemCompactionMessage | SDKStreamEventMessage | SDKAssistantMessage | SDKUserMessage | SDKResultMessage;
 export type TeamRunnerSource = AgentRuntimeSource;
 export type TeamRunnerTeamMessage = {
     type: "team_message";
@@ -654,12 +692,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;
 /**
@@ -710,6 +769,20 @@ export declare class Agent<TContext = unknown> {
     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;