@armadra/agent 0.0.0-stage → 0.3.0

package/dist/agent/session.js

@@ -0,0 +1,485 @@
+/**
+ * AgentSessionImpl（设计 §4.2–§4.3、§9、§11.1 第 16 步、§13.1）。[B2]
+ *
+ * 会话 = SessionManager（JSONL 树，事实来源）+ Agent（上下文消息、队列、run）+ 压缩 / 重试 / Hook 调度。
+ * - 每条 message_end 落盘为条目；Agent 的上下文 = 活动分支的投影（压缩 / context_edit 后重建）。
+ * - 首次模型请求前把系统提示 + 工具表作为首条 `system` 消息落盘并 `flush()`（此时才创建文件）；
+ *   之后节或工具表变化落 system 补丁。
+ * - `prompt()`：运行中且无 streamingBehavior → `AmaError{code:"busy"}`；否则展开（expandPrompt）→
+ *   UserPromptSubmit Hook → 阈值压缩检查 → 会话周期（session-run.ts）；周期结束后 resolve。
+ * - `steer()` / `followUp()`：运行中入队（返回 "queued"）；空闲时直接以该消息开始一个周期（"handled"）。
+ * - `abort()`：中断供应商流、工具、重试等待与压缩；回到 idle 后 resolve；不清队列。
+ */
+import { modelRefOf } from "../ai/providers/channels.js";
+import { join } from "node:path";
+import { AmaError } from "../errors.js";
+import { buildProjection } from "../session/projection.js";
+import { Agent } from "./agent.js";
+import { queuedText } from "./queue.js";
+import { resolveRetrySettings } from "./retry.js";
+import { SessionCacheController, resolveCacheSettings } from "./session-cache.js";
+import { CompactionController } from "./session-compaction.js";
+import { makeUserMessage, runPrompt } from "./session-run.js";
+import { buildSessionState, computeStats, lastAssistantText } from "./session-state.js";
+import { DEFAULT_SUBAGENT_CONCURRENCY, SubagentPool, runSubagent } from "./session-subagent.js";
+import { persistMessage, runHookWithEvents, syncSystemMessage } from "./session-sync.js";
+import { createToolRunnerOptions } from "./session-tools.js";
+import { convertToLlm } from "./transform.js";
+/** `"user"` = 普通用户输入，不写 origin。 */
+function normalizeOrigin(origin) {
+    return origin === undefined || origin === "user" ? undefined : origin;
+}
+export class AgentSessionImpl {
+    options;
+    manager;
+    agent;
+    cwd;
+    depth;
+    readFiles = new Set();
+    stream;
+    cache;
+    currentModel;
+    currentThinking;
+    allTools = new Map();
+    activeNames;
+    listeners = new Set();
+    compaction;
+    retrySettings;
+    cycle;
+    retrying = false;
+    stopReason;
+    stopFlag = false;
+    turns = 0;
+    systemInput;
+    subagentPool;
+    disposed = false;
+    /** 已入队、尚未投递的消息（投递时发 queue_update）。 */
+    queuedMessages = new WeakSet();
+    constructor(options) {
+        this.options = options;
+        this.manager = options.sessionManager;
+        this.cwd = this.manager.cwd;
+        this.depth = options.depth ?? 0;
+        this.currentModel = options.model;
+        this.currentThinking = options.thinkingLevel ?? "off";
+        for (const tool of options.tools ?? [])
+            this.allTools.set(tool.name, tool);
+        this.activeNames = [...(options.activeTools ?? this.allTools.keys())].filter((name) => this.allTools.has(name));
+        this.systemInput = { ...(options.system ?? {}) };
+        this.retrySettings = resolveRetrySettings(options.retry);
+        this.cache = new SessionCacheController(this, resolveCacheSettings(options.cache), {
+            decider: () => options.warmingDecider?.(),
+        });
+        this.stream = this.cache.wrapStream((model, context, streamOptions) => {
+            const api = options.providers.getApi(model.api);
+            if (api === undefined) {
+                throw new AmaError("provider_not_found", `no implementation registered for api ${model.api}`);
+            }
+            return api.stream(model, context, streamOptions);
+        });
+        const runner = createToolRunnerOptions(this);
+        const agentOptions = {
+            hooks: {
+                convertToLlm: (messages) => convertToLlm(messages, {
+                    provider: this.currentModel.provider,
+                    model: this.currentModel.id,
+                }),
+                beforeToolCall: runner.beforeToolCall,
+                prepareNextTurn: async () => {
+                    const signal = this.agent.signal ?? this.cycle?.controller.signal;
+                    if (signal !== undefined)
+                        await this.compaction.checkThreshold(signal);
+                },
+                finishTurn: async () => {
+                    this.turns++;
+                    if (this.stopFlag)
+                        return "end";
+                    const maxTurns = options.maxTurns;
+                    return maxTurns !== undefined && this.turns >= maxTurns ? "end" : "continue";
+                },
+            },
+            stream: this.stream,
+            getModel: () => this.currentModel,
+            getThinkingLevel: () => this.currentThinking,
+            streamOptions: async () => {
+                const apiKey = await this.resolveApiKey();
+                return apiKey === undefined
+                    ? { sessionId: this.manager.id }
+                    : { apiKey, sessionId: this.manager.id };
+            },
+            beforeRequest: async () => {
+                this.syncSystem();
+                this.manager.flush();
+            },
+            tools: runner,
+            messages: buildProjection(this.manager.branch()).messages,
+            onListenerError: (error, event) => this.log("warn", `listener failed on ${event.type}: ${String(error)}`),
+        };
+        if (options.steeringMode !== undefined)
+            agentOptions.steeringMode = options.steeringMode;
+        if (options.followUpMode !== undefined)
+            agentOptions.followUpMode = options.followUpMode;
+        this.agent = new Agent(agentOptions);
+        this.agent.subscribe((event) => this.onAgentEvent(event));
+        this.compaction = new CompactionController(this, options.compaction);
+        const subagents = options.subagents === false ? undefined : options.subagents;
+        this.subagentPool = new SubagentPool(subagents?.maxConcurrent ?? DEFAULT_SUBAGENT_CONCURRENCY);
+    }
+    // -------------------------------------------------------------------------
+    // SessionCore
+    // -------------------------------------------------------------------------
+    model() {
+        return this.currentModel;
+    }
+    thinkingLevel() {
+        return this.currentThinking;
+    }
+    outputDir() {
+        if (this.options.outputDir !== undefined)
+            return this.options.outputDir;
+        const dir = this.manager.directory();
+        return dir === undefined ? undefined : join(dir, "outputs");
+    }
+    async resolveApiKey() {
+        try {
+            const { provider, channel } = this.currentModel;
+            return (await this.options.providers.resolveApiKey(provider, channel)).apiKey;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    emit(event) {
+        this.cache.onEvent(event);
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.log("warn", `session listener failed on ${event.type}: ${String(error)}`);
+            }
+        }
+    }
+    appendEntry(input) {
+        const entry = this.manager.append(input);
+        this.emit({ type: "entry_appended", entry });
+        return entry;
+    }
+    reloadMessages() {
+        this.agent.messages = buildProjection(this.manager.branch()).messages;
+    }
+    activeTool(name) {
+        return this.activeNames.includes(name) ? this.allTools.get(name) : undefined;
+    }
+    tool(name) {
+        return this.allTools.get(name);
+    }
+    activeToolNames() {
+        return [...this.activeNames];
+    }
+    runHook(event, payload, signal) {
+        return runHookWithEvents(this, event, payload, signal);
+    }
+    requestStop(reason) {
+        this.stopFlag = true;
+        this.stopReason = reason;
+    }
+    log(level, message) {
+        this.options.log?.(level, message);
+    }
+    // -------------------------------------------------------------------------
+    // 事件与落盘
+    // -------------------------------------------------------------------------
+    onAgentEvent(event) {
+        if (event.type === "message_end")
+            persistMessage(this, event.message);
+        else if (event.type === "agent_start")
+            this.compaction.breaker.startRun();
+        this.emit(event);
+        if (event.type === "message_start" &&
+            event.message.role === "user" &&
+            this.queuedMessages.delete(event.message)) {
+            this.emitQueue();
+        }
+    }
+    emitQueue() {
+        this.emit({
+            type: "queue_update",
+            steering: this.agent.steeringQueue.snapshot().map(queuedText),
+            followUp: this.agent.followUpQueue.snapshot().map(queuedText),
+        });
+    }
+    syncSystem() {
+        syncSystemMessage(this, this.systemInput, this.getTools());
+    }
+    // -------------------------------------------------------------------------
+    // 周期
+    // -------------------------------------------------------------------------
+    assertUsable() {
+        if (this.disposed)
+            throw new AmaError("session_closed", "session is disposed");
+    }
+    startCycle(work) {
+        const controller = new AbortController();
+        let done = () => { };
+        const promise = new Promise((resolve) => {
+            done = resolve;
+        });
+        this.cycle = { controller, promise };
+        this.turns = 0;
+        this.stopFlag = false;
+        this.stopReason = undefined;
+        return (async () => {
+            try {
+                return await work(controller.signal);
+            }
+            finally {
+                this.cycle = undefined;
+                this.retrying = false;
+                done();
+            }
+        })();
+    }
+    runDeps() {
+        return {
+            core: this,
+            compaction: this.compaction,
+            retry: () => this.retrySettings,
+            syncSystem: () => this.syncSystem(),
+            stopRequested: () => this.stopFlag,
+            setRetrying: (value) => {
+                this.retrying = value;
+            },
+            lastAssistantText: () => this.getLastAssistantText(),
+        };
+    }
+    // -------------------------------------------------------------------------
+    // AgentSession
+    // -------------------------------------------------------------------------
+    async prompt(text, options = {}) {
+        this.assertUsable();
+        if (this.cycle !== undefined) {
+            const behavior = options.streamingBehavior;
+            if (behavior === undefined) {
+                throw new AmaError("busy", "a run is in progress; pass streamingBehavior or use steer()/followUp()");
+            }
+            this.enqueue(makeUserMessage(text, options.images, normalizeOrigin(options.origin ?? behavior)), behavior);
+            return "queued";
+        }
+        const origin = normalizeOrigin(options.origin);
+        return this.startCycle((signal) => runPrompt(this.runDeps(), text, options.images, origin, signal));
+    }
+    enqueue(message, queue) {
+        this.queuedMessages.add(message);
+        if (queue === "steer")
+            this.agent.steer(message);
+        else
+            this.agent.followUp(message);
+        this.emitQueue();
+    }
+    async enqueueOrRun(text, queue, options) {
+        this.assertUsable();
+        const origin = normalizeOrigin(options.origin ?? queue);
+        if (this.cycle === undefined) {
+            await this.startCycle((signal) => runPrompt(this.runDeps(), text, undefined, origin, signal));
+            return "handled";
+        }
+        this.enqueue(makeUserMessage(text, undefined, origin), queue);
+        return "queued";
+    }
+    steer(text, options = {}) {
+        return this.enqueueOrRun(text, "steer", options);
+    }
+    followUp(text, options = {}) {
+        return this.enqueueOrRun(text, "followUp", options);
+    }
+    async abort() {
+        const cycle = this.cycle;
+        if (cycle === undefined)
+            return;
+        cycle.controller.abort();
+        this.agent.abort();
+        await cycle.promise;
+    }
+    waitForIdle() {
+        return this.cycle?.promise ?? Promise.resolve();
+    }
+    clearQueue() {
+        const cleared = {
+            steering: this.agent.steeringQueue.clear().map(queuedText),
+            followUp: this.agent.followUpQueue.clear().map(queuedText),
+        };
+        this.emitQueue();
+        return cleared;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** 手动压缩；运行中 → busy。 */
+    compact(instructions) {
+        this.assertUsable();
+        if (this.cycle !== undefined)
+            return Promise.reject(new AmaError("busy", "cannot compact while running"));
+        return this.startCycle((signal) => this.compaction.compactManual(instructions, signal));
+    }
+    async fork(entryId) {
+        this.assertUsable();
+        if (this.cycle !== undefined)
+            throw new AmaError("busy", "cannot fork while running");
+        return new AgentSessionImpl({
+            ...this.options,
+            ...this.childBase(),
+            sessionManager: this.manager.fork(entryId),
+        });
+    }
+    /**
+     * `/tree`：同文件换叶子；`summarize` 时为离开的分支写 branch_summary（挂在新叶子下）。
+     */
+    async navigate(targetId, options = {}) {
+        this.assertUsable();
+        if (this.cycle !== undefined)
+            throw new AmaError("busy", "cannot navigate while running");
+        let entry;
+        if (options.summarize === true) {
+            entry = await this.startCycle((signal) => this.compaction.leaveBranch(targetId, options.instructions, signal));
+        }
+        else
+            this.manager.setLeaf(targetId);
+        this.reloadMessages();
+        this.cache.onContextChanged();
+        return entry;
+    }
+    async setModel(ref) {
+        this.assertUsable();
+        const lookup = this.options.providers.findModel(ref);
+        if (!lookup.ok) {
+            throw new AmaError("model_not_found", `model ${ref} not found`, {
+                detail: lookup.candidates,
+            });
+        }
+        this.currentModel = lookup.model;
+        this.compaction.refresh();
+        const next = modelRefOf(lookup.model);
+        this.appendEntry({
+            type: "model_change",
+            provider: next.provider,
+            modelId: next.id,
+            ...(next.channel !== undefined ? { channel: next.channel } : {}),
+        });
+        this.emit({ type: "model_changed", model: next });
+    }
+    setThinkingLevel(level) {
+        this.currentThinking = level;
+        this.appendEntry({ type: "thinking_level_change", thinkingLevel: level });
+        this.emit({ type: "thinking_level_changed", level });
+    }
+    setPermissionMode(mode) {
+        this.options.permission?.setMode(mode);
+        this.emit({ type: "permission_mode_changed", mode });
+    }
+    setActiveTools(names) {
+        const unknown = names.filter((name) => !this.allTools.has(name));
+        if (unknown.length > 0)
+            throw new AmaError("tool_not_found", `unknown tools: ${unknown.join(", ")}`);
+        this.activeNames = [...new Set(names)];
+    }
+    /** 宿主 / SDK 在会话创建后追加工具（下次请求前以 system 补丁声明）。 */
+    addTool(tool, active = true) {
+        if (this.allTools.has(tool.name))
+            throw new AmaError("tool_exists", `tool ${tool.name} already exists`);
+        this.allTools.set(tool.name, tool);
+        if (active)
+            this.activeNames.push(tool.name);
+    }
+    /** 更新系统提示的静态部分（SessionStart Hook 的 hookContext、宿主 instructions 等）。 */
+    updateSystem(patch) {
+        this.systemInput = { ...this.systemInput, ...patch };
+    }
+    setAutoCompaction(enabled) {
+        this.compaction.setAuto(enabled);
+    }
+    setAutoRetry(enabled) {
+        this.retrySettings = { ...this.retrySettings, enabled };
+    }
+    getTools() {
+        return this.activeNames
+            .map((name) => this.allTools.get(name))
+            .filter((tool) => tool !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /** 发 session_start（bootstrap / SDK 在会话就绪后调用一次）。 */
+    announceStart(reason) {
+        const event = {
+            type: "session_start",
+            sessionId: this.manager.id,
+            cwd: this.cwd,
+            reason,
+        };
+        const file = this.manager.file();
+        if (file !== undefined)
+            event.sessionFile = file;
+        this.emit(event);
+    }
+    get state() {
+        return buildSessionState({
+            agent: this.agent,
+            manager: this.manager,
+            model: this.currentModel,
+            thinkingLevel: this.currentThinking,
+            permissionMode: this.options.permission?.mode ?? "default",
+            isCompacting: this.compaction.isCompacting,
+            isRetrying: this.retrying,
+            autoCompaction: this.compaction.settings.enabled,
+            autoRetry: this.retrySettings.enabled,
+        });
+    }
+    get messages() {
+        return this.agent.messages;
+    }
+    get entries() {
+        return this.manager.entries();
+    }
+    /** run 被 Hook 的 continue:false 结束时的说明。 */
+    get stopHookReason() {
+        return this.stopReason;
+    }
+    getLastAssistantText() {
+        return lastAssistantText(this.manager.branch());
+    }
+    getStats() {
+        const contextTokens = this.compaction.estimate().tokens;
+        const contextWindow = this.currentModel.contextWindow;
+        return computeStats({
+            sessionId: this.manager.id,
+            sessionFile: this.manager.file(),
+            branch: this.manager.branch(),
+            contextTokens,
+            contextWindow,
+            cache: this.cache.stats({ tokens: contextTokens, window: contextWindow }),
+        });
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        await this.abort();
+        this.cache.dispose();
+        this.disposed = true;
+        this.manager.close();
+        this.listeners.clear();
+    }
+    // -------------------------------------------------------------------------
+    // 子 Agent（ToolContext.spawnSubagent，供 B3 的 task 工具）
+    // -------------------------------------------------------------------------
+    childBase() {
+        return {
+            model: this.currentModel,
+            thinkingLevel: this.currentThinking,
+            activeTools: this.activeNames,
+            system: this.systemInput,
+        };
+    }
+    spawnSubagent(request) {
+        return runSubagent(this, request, this.subagentPool, (options) => new AgentSessionImpl(options));
+    }
+}

package/dist/agent/system-prompt.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 系统提示的命名节装配与补丁 diff（设计 §1.2 system-prompt.ts、§9「缓存」）。[B2]
+ *
+ * 节顺序固定：preamble → tools → rules → project_context → skills → hooks → cwd → host
+ * （`hooks` = SessionStart Hook 的 additionalContext；`host` = 宿主 instructions.add，最后）。
+ * 不含时间戳等易变内容，保证前缀缓存稳定。
+ *
+ * 首次请求前，整份节 + 工具表作为首条 `system` 消息落盘；之后节或工具表变化时只落补丁
+ * （节名级替换、`null` 删除；`toolsAdded` / `toolsRemoved`），请求时由协议层重装全量。
+ */
+import type { SystemMessage, ToolDecl } from "../ai/types.js";
+import { type SystemState } from "../session/projection.js";
+import type { AgentMessage } from "../session/types.js";
+import type { ToolDefinition } from "../tools/types.js";
+export declare const SECTION_ORDER: readonly ["preamble", "tools", "rules", "project_context", "skills", "hooks", "cwd", "host"];
+export type SectionName = (typeof SECTION_ORDER)[number];
+export declare const DEFAULT_PREAMBLE: string;
+export interface SystemPromptInput {
+    preamble?: string;
+    tools: readonly ToolDefinition[];
+    extraRules?: readonly string[];
+    contextFiles?: readonly {
+        path: string;
+        content: string;
+    }[];
+    /** 预渲染的 `<available_skills>` 索引（B3 的 index-prompt.ts）；缺省时由 skills 列表生成最小索引。 */
+    skillsIndex?: string;
+    skills?: readonly {
+        name: string;
+        description: string;
+        location: string;
+    }[];
+    /** SessionStart Hook 的 additionalContext。 */
+    hookContext?: string;
+    cwd: string;
+    /** 宿主 instructions（已读入的文本），按添加顺序。 */
+    hostInstructions?: readonly string[];
+}
+export declare function toolDecl(tool: ToolDefinition): ToolDecl;
+/** 按名排序的工具声明（与 ToolRegistry.active() 的顺序一致）。 */
+export declare function toolDecls(tools: readonly ToolDefinition[]): ToolDecl[];
+export declare function assembleSections(input: SystemPromptInput): Record<SectionName, string | undefined>;
+/** 去掉 undefined 的有序节表。 */
+export declare function definedSections(sections: Record<SectionName, string | undefined>): Record<string, string>;
+export declare function currentSystemState(messages: Iterable<AgentMessage>): SystemState | undefined;
+/**
+ * 当前状态 → 目标状态的 system 消息：无当前状态 → 全量；有差异 → 补丁；无差异 → undefined。
+ */
+export declare function diffSystem(current: SystemState | undefined, sections: Record<string, string>, tools: readonly ToolDecl[], timestamp?: number): SystemMessage | undefined;

package/dist/agent/system-prompt.js

@@ -0,0 +1,121 @@
+/**
+ * 系统提示的命名节装配与补丁 diff（设计 §1.2 system-prompt.ts、§9「缓存」）。[B2]
+ *
+ * 节顺序固定：preamble → tools → rules → project_context → skills → hooks → cwd → host
+ * （`hooks` = SessionStart Hook 的 additionalContext；`host` = 宿主 instructions.add，最后）。
+ * 不含时间戳等易变内容，保证前缀缓存稳定。
+ *
+ * 首次请求前，整份节 + 工具表作为首条 `system` 消息落盘；之后节或工具表变化时只落补丁
+ * （节名级替换、`null` 删除；`toolsAdded` / `toolsRemoved`），请求时由协议层重装全量。
+ */
+import { replaySystem } from "../session/projection.js";
+import { escapeXml } from "../skills/index-prompt.js";
+export const SECTION_ORDER = [
+    "preamble",
+    "tools",
+    "rules",
+    "project_context",
+    "skills",
+    "hooks",
+    "cwd",
+    "host",
+];
+export const DEFAULT_PREAMBLE = "You are ama, a coding agent working in the user's project through tools. Read files before " +
+    "changing them, make focused changes, and verify your work. Be concise.";
+function firstLine(text) {
+    return text.split("\n", 1)[0]?.trim() ?? "";
+}
+export function toolDecl(tool) {
+    return { name: tool.name, description: tool.description, parameters: tool.parameters };
+}
+/** 按名排序的工具声明（与 ToolRegistry.active() 的顺序一致）。 */
+export function toolDecls(tools) {
+    return [...tools].sort((a, b) => a.name.localeCompare(b.name)).map(toolDecl);
+}
+export function assembleSections(input) {
+    const tools = [...input.tools].sort((a, b) => a.name.localeCompare(b.name));
+    const toolLines = tools.map((tool) => {
+        const snippet = tool.promptSnippet ?? firstLine(tool.description);
+        // 内置工具的 promptSnippet 已以「name: 」开头（B3 约定），不再重复工具名。
+        return snippet.startsWith(`${tool.name}:`) ? `- ${snippet}` : `- ${tool.name}: ${snippet}`;
+    });
+    const rules = [
+        ...tools.flatMap((tool) => tool.promptGuidelines ?? []),
+        ...(input.extraRules ?? []),
+    ];
+    const projectContext = (input.contextFiles ?? [])
+        .map((file) => `<file path="${escapeXml(file.path)}">\n${file.content.trim()}\n</file>`)
+        .join("\n\n");
+    let skills = input.skillsIndex;
+    if (skills === undefined && input.skills !== undefined && input.skills.length > 0) {
+        skills = [
+            "<available_skills>",
+            ...input.skills.map((skill) => `<skill name="${escapeXml(skill.name)}" location="${escapeXml(skill.location)}">${escapeXml(skill.description)}</skill>`),
+            "</available_skills>",
+        ].join("\n");
+    }
+    const host = (input.hostInstructions ?? []).map((text) => text.trim()).filter(Boolean);
+    const nonEmpty = (text) => text === undefined || text.trim() === "" ? undefined : text;
+    return {
+        preamble: input.preamble ?? DEFAULT_PREAMBLE,
+        tools: toolLines.length > 0 ? `Available tools:\n${toolLines.join("\n")}` : undefined,
+        rules: rules.length > 0 ? `Rules:\n${rules.map((rule) => `- ${rule}`).join("\n")}` : undefined,
+        project_context: nonEmpty(projectContext),
+        skills: nonEmpty(skills),
+        hooks: nonEmpty(input.hookContext),
+        cwd: `Current working directory: ${input.cwd}`,
+        host: host.length > 0 ? host.join("\n\n") : undefined,
+    };
+}
+/** 去掉 undefined 的有序节表。 */
+export function definedSections(sections) {
+    const out = {};
+    for (const name of SECTION_ORDER) {
+        const text = sections[name];
+        if (text !== undefined)
+            out[name] = text;
+    }
+    return out;
+}
+export function currentSystemState(messages) {
+    return replaySystem(messages);
+}
+function sameTool(a, b) {
+    return (a.description === b.description && JSON.stringify(a.parameters) === JSON.stringify(b.parameters));
+}
+/**
+ * 当前状态 → 目标状态的 system 消息：无当前状态 → 全量；有差异 → 补丁；无差异 → undefined。
+ */
+export function diffSystem(current, sections, tools, timestamp = Date.now()) {
+    if (current === undefined) {
+        const full = { role: "system", sections: { ...sections }, timestamp };
+        if (tools.length > 0)
+            full.toolsAdded = tools.map((tool) => ({ ...tool }));
+        return full;
+    }
+    const patch = {};
+    for (const [name, text] of Object.entries(sections)) {
+        if (current.sections[name] !== text)
+            patch[name] = text;
+    }
+    for (const name of Object.keys(current.sections)) {
+        if (!(name in sections))
+            patch[name] = null;
+    }
+    const before = new Map(current.tools.map((tool) => [tool.name, tool]));
+    const after = new Map(tools.map((tool) => [tool.name, tool]));
+    const toolsAdded = tools.filter((tool) => {
+        const old = before.get(tool.name);
+        return old === undefined || !sameTool(old, tool);
+    });
+    const toolsRemoved = [...before.keys()].filter((name) => !after.has(name));
+    if (Object.keys(patch).length === 0 && toolsAdded.length === 0 && toolsRemoved.length === 0) {
+        return undefined;
+    }
+    const message = { role: "system", sections: patch, timestamp };
+    if (toolsAdded.length > 0)
+        message.toolsAdded = toolsAdded.map((tool) => ({ ...tool }));
+    if (toolsRemoved.length > 0)
+        message.toolsRemoved = toolsRemoved;
+    return message;
+}