@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/runtime/context/claude-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Claude Code tool-name map (phase B, spec §9.4): skills written for Claude Code name its tools
+ * (`Bash`, `Read`, `Skill`, …). When a conversation's skills include one from a Claude Code plugin,
+ * the run start writes this text into the `skills_catalog` snapshot (`toolMap`), and request
+ * building renders it from the log, so a replay never depends on this constant. Model-visible:
+ * English, fixed (Decision 15: not tailored to the agent's tools; it says "when it is in your
+ * tools" instead). Changing it only affects snapshots written afterwards: a conversation's next
+ * run writes a new snapshot announcing the new map, and old snapshots keep their text (phase C
+ * changed the Task / Agent line, sub-agents spec §16.5).
+ */
+export declare const CLAUDE_CODE_TOOL_MAP: string;

package/dist/runtime/context/claude-tools.js

@@ -0,0 +1,24 @@
+/**
+ * The Claude Code tool-name map (phase B, spec §9.4): skills written for Claude Code name its tools
+ * (`Bash`, `Read`, `Skill`, …). When a conversation's skills include one from a Claude Code plugin,
+ * the run start writes this text into the `skills_catalog` snapshot (`toolMap`), and request
+ * building renders it from the log, so a replay never depends on this constant. Model-visible:
+ * English, fixed (Decision 15: not tailored to the agent's tools; it says "when it is in your
+ * tools" instead). Changing it only affects snapshots written afterwards: a conversation's next
+ * run writes a new snapshot announcing the new map, and old snapshots keep their text (phase C
+ * changed the Task / Agent line, sub-agents spec §16.5).
+ */
+export const CLAUDE_CODE_TOOL_MAP = [
+    "Some skills in this conversation were written for Claude Code and name its tools. Use these tools instead:",
+    "- Bash -> sandbox_bash",
+    "- Read -> sandbox_read; Write -> sandbox_write; Edit and MultiEdit -> sandbox_edit; Glob -> sandbox_glob; Grep -> sandbox_grep",
+    '- Skill -> skill_load (a name such as "superpowers:brainstorming" also works)',
+    "- TodoWrite -> todo__write when it is in your tools; otherwise keep the task list in your replies",
+    "- AskUserQuestion -> ask_user",
+    "- ToolSearch -> tool_search when it is in your tools",
+    "- Task and Agent (sub-agents) -> agent when it is in your tools (subagent_type names one of the types its description lists; model names haiku / sonnet / opus -> fast / standard / capable; SendMessage to a sub-agent -> agent with resume); otherwise not available: do the steps yourself, in order",
+    "- TaskOutput, TaskStop -> not available",
+    "- Any other tool a skill names (for example WebFetch, WebSearch, NotebookEdit, EnterWorktree) -> not available unless one of your tools does the same job",
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: the literal Claude Code variable the model reads
+    "The sandbox tools exist only when this agent has a sandbox; without them a skill's scripts cannot run. A path such as ${CLAUDE_PLUGIN_ROOT}/skills/<name>/... means /skills/<name>/... after skill_load has copied that skill into the sandbox.",
+].join("\n");

package/dist/runtime/context/compaction.d.ts

@@ -0,0 +1,26 @@
+import type { ModelInfo, ModelRequest } from "@capybara-hq/plugin-sdk";
+import type { ConversationEvent } from "../../conversations/events.js";
+/** 压缩请求的标记：放在 system 中，便于识别（model-fake 据此返回摘要）。 */
+export declare const COMPACTION_MARKER = "CAPYBARA_COMPACTION";
+/** 压缩请求的输出上限。 */
+export declare const COMPACTION_MAX_OUTPUT_TOKENS = 4096;
+/** 估算 token 数达到上下文窗口的 `threshold`（如 0.8）时压缩。 */
+export declare function shouldCompact(estimatedTokens: number, model: ModelInfo, threshold: number): boolean;
+/**
+ * 压缩计划：保留最近 `keepRecentTurns` 个「以 user_message 开头的轮次」原文，把更早、且尚未被
+ * 上一条摘要覆盖的内容转成纯文本对话记录（上一条摘要放在记录开头，由新摘要合并）。
+ * `coversUpToSeq` 为第一条保留的 user_message 之前的最大 seq。可压缩的内容为空时返回 null。
+ */
+export declare function compactionPlan(events: ConversationEvent[], keepRecentTurns: number): {
+    coversUpToSeq: number;
+    transcript: string;
+} | null;
+/** 摘要请求：system 为带标记的英文摘要指令，对话记录作为唯一一条 user 消息。 */
+export declare function buildCompactionRequest(transcript: string, model: string): ModelRequest;
+/** 摘要（去掉首尾空白）至少 min(200, 原文 5%) 个字符才接受；过短视为失败（可靠性清单 A）。 */
+export declare function acceptSummary(text: string, transcript: string): boolean;
+/**
+ * 压缩失败后的退避：最近一次 `compaction_failed`（attempt = n）之后新增的 user 轮次少于 2^n 时
+ * 返回 true（本轮跳过压缩）。之后已有成功摘要、或从未失败，返回 false。
+ */
+export declare function compactionBackoff(events: ConversationEvent[]): boolean;

package/dist/runtime/context/compaction.js

@@ -0,0 +1,195 @@
+import { latestSummary } from "./build.js";
+/** 压缩请求的标记：放在 system 中，便于识别（model-fake 据此返回摘要）。 */
+export const COMPACTION_MARKER = "CAPYBARA_COMPACTION";
+/** 压缩请求的输出上限。 */
+export const COMPACTION_MAX_OUTPUT_TOKENS = 4096;
+/** 摘要的最短长度：200 字符或原文的 5%，取较小者。 */
+const MIN_SUMMARY_CHARS = 200;
+const MIN_SUMMARY_RATIO = 0.05;
+/** 摘要指令（模型可见，英文）。 */
+const COMPACTION_INSTRUCTION = [
+    COMPACTION_MARKER,
+    "You are summarizing the earlier part of a conversation between people and an AI agent, so the agent can continue without the full history.",
+    "Write a concise but complete summary that preserves: the users' goals and requests, decisions made, facts and data established (names, numbers, identifiers, file names, links), work completed and its results, and open questions or pending tasks.",
+    "If the transcript starts with an earlier summary, merge it into your summary.",
+    "Write in the same language as the conversation. Output only the summary text.",
+].join("\n");
+/** 估算 token 数达到上下文窗口的 `threshold`（如 0.8）时压缩。 */
+export function shouldCompact(estimatedTokens, model, threshold) {
+    return estimatedTokens >= model.contextWindow * threshold;
+}
+/**
+ * 压缩计划：保留最近 `keepRecentTurns` 个「以 user_message 开头的轮次」原文，把更早、且尚未被
+ * 上一条摘要覆盖的内容转成纯文本对话记录（上一条摘要放在记录开头，由新摘要合并）。
+ * `coversUpToSeq` 为第一条保留的 user_message 之前的最大 seq。可压缩的内容为空时返回 null。
+ */
+export function compactionPlan(events, keepRecentTurns) {
+    const sorted = [...events].sort((a, b) => a.seq - b.seq);
+    const prev = latestSummary(sorted);
+    const floor = prev ? prev.payload.coversUpToSeq : Number.NEGATIVE_INFINITY;
+    const candidate = sorted.filter((e) => e.seq > floor && e.type !== "compaction_summary");
+    const userIdx = [];
+    candidate.forEach((e, i) => {
+        if (e.type === "user_message")
+            userIdx.push(i);
+    });
+    let boundary;
+    if (keepRecentTurns <= 0)
+        boundary = candidate.length;
+    else if (userIdx.length < keepRecentTurns)
+        boundary = 0;
+    else
+        boundary = userIdx[userIdx.length - keepRecentTurns];
+    boundary = keepToolPairs(candidate, userIdx, boundary);
+    const lines = [];
+    for (const e of candidate.slice(0, boundary)) {
+        const line = transcriptLine(e);
+        if (line)
+            lines.push(line);
+    }
+    if (lines.length === 0)
+        return null;
+    const boundarySeq = candidate[boundary]?.seq ?? Number.POSITIVE_INFINITY;
+    let coversUpToSeq = floor;
+    for (const e of sorted)
+        if (e.seq < boundarySeq && e.seq > coversUpToSeq)
+            coversUpToSeq = e.seq;
+    const parts = prev ? [`[Earlier summary]\n${prev.payload.text}`, ...lines] : lines;
+    return { coversUpToSeq, transcript: parts.join("\n\n") };
+}
+/**
+ * 边界不得切开工具调用与其结果：工具运行期间到达的插话（user_message）记在 assistant 的 tool_call 与
+ * tool_result 之间，若它成了边界，assistant 进摘要而结果留在原文，构建请求时结果因找不到调用被丢弃。
+ * 做法：边界之前仍「未结束」（结果在边界之后）的调用存在时，把边界退到最早那条未结束 assistant 之前的
+ * 最近一个 user_message（没有则 0，即不压缩这段），重复直到没有被切开的调用。结果从未写入的调用不算
+ * （它们由配对守卫补 unknown，与边界无关）。
+ */
+function keepToolPairs(candidate, userIdx, boundary) {
+    const key = (runId, callId) => `${runId ?? ""}\u0000${callId}`;
+    const resultAt = new Map();
+    candidate.forEach((e, i) => {
+        if (e.type !== "tool_result")
+            return;
+        const k = key(e.runId, e.payload.callId);
+        if (!resultAt.has(k))
+            resultAt.set(k, i);
+    });
+    for (;;) {
+        let earliestOpen = -1;
+        for (let i = 0; i < boundary && earliestOpen < 0; i++) {
+            const e = candidate[i];
+            if (e.type !== "assistant_message")
+                continue;
+            for (const b of e.payload.content) {
+                if (b.type !== "tool_call")
+                    continue;
+                const at = resultAt.get(key(e.runId, b.id));
+                if (at !== undefined && at >= boundary) {
+                    earliestOpen = i;
+                    break;
+                }
+            }
+        }
+        if (earliestOpen < 0)
+            return boundary;
+        let next = 0;
+        for (const u of userIdx)
+            if (u < earliestOpen)
+                next = u;
+        boundary = next;
+    }
+}
+function transcriptLine(e) {
+    switch (e.type) {
+        case "user_message": {
+            const text = renderBlocks(e.payload.content);
+            return text ? `User: ${text}` : null;
+        }
+        case "assistant_message": {
+            const text = renderBlocks(e.payload.content);
+            return text ? `Assistant: ${text}` : null;
+        }
+        case "reminder":
+            return `System reminder: ${e.payload.text}`;
+        // phase D: a forked skill's report is user content of the request (build.ts)
+        case "skill_fork_result":
+            return `User: ${e.payload.text}`;
+        case "tool_result":
+            return `Tool result ${e.payload.toolKey}${e.payload.isError ? " (error)" : ""}: ${e.payload.content}`;
+        default:
+            return null;
+    }
+}
+/**
+ * 内容块转纯文本；思考块不进记录，媒体块记为 `[image: "<name>"]` / `[document: "<name>"]`
+ * （名字按 JSON.stringify 加引号，与请求里的占位一致）。
+ */
+function renderBlocks(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        switch (b.type) {
+            case "text":
+                if (b.text)
+                    out.push(b.text);
+                break;
+            case "tool_call":
+                out.push(`[Tool call ${b.name}: ${JSON.stringify(b.input) ?? ""}]`);
+                break;
+            case "tool_result":
+                out.push(`[Tool result${b.isError ? " (error)" : ""}: ${b.content}]`);
+                break;
+            case "thinking":
+                break;
+            case "image":
+            case "document":
+                out.push(`[${b.type}: ${JSON.stringify(b.name ?? "attachment")}]`);
+                break;
+        }
+    }
+    return out.join("\n");
+}
+/** 摘要请求：system 为带标记的英文摘要指令，对话记录作为唯一一条 user 消息。 */
+export function buildCompactionRequest(transcript, model) {
+    return {
+        model,
+        system: [{ text: COMPACTION_INSTRUCTION, cache: false }],
+        messages: [
+            {
+                role: "user",
+                content: [{ type: "text", text: `<transcript>\n${transcript}\n</transcript>` }],
+            },
+        ],
+        tools: [],
+        maxOutputTokens: COMPACTION_MAX_OUTPUT_TOKENS,
+        params: {},
+    };
+}
+/** 摘要（去掉首尾空白）至少 min(200, 原文 5%) 个字符才接受；过短视为失败（可靠性清单 A）。 */
+export function acceptSummary(text, transcript) {
+    const min = Math.min(MIN_SUMMARY_CHARS, transcript.length * MIN_SUMMARY_RATIO);
+    return text.trim().length >= min;
+}
+/**
+ * 压缩失败后的退避：最近一次 `compaction_failed`（attempt = n）之后新增的 user 轮次少于 2^n 时
+ * 返回 true（本轮跳过压缩）。之后已有成功摘要、或从未失败，返回 false。
+ */
+export function compactionBackoff(events) {
+    let failure = null;
+    for (const e of events) {
+        if (e.type === "compaction_failed" && (!failure || e.seq > failure.seq)) {
+            failure = { seq: e.seq, attempt: e.payload.attempt };
+        }
+    }
+    if (!failure)
+        return false;
+    let turns = 0;
+    for (const e of events) {
+        if (e.seq <= failure.seq)
+            continue;
+        if (e.type === "compaction_summary")
+            return false;
+        if (e.type === "user_message")
+            turns++;
+    }
+    return turns < 2 ** failure.attempt;
+}

package/dist/runtime/context/pairing.d.ts

@@ -0,0 +1,11 @@
+import type { ModelMessage } from "@capybara-hq/plugin-sdk";
+/** 补给缺失结果的 tool_call 的结果文案（模型可见，英文）。 */
+export declare const UNKNOWN_RESULT_TEXT = "Result unknown: the call was interrupted before a result was recorded. Verify the outcome before retrying.";
+/**
+ * tool_call / tool_result 配对守卫（spec 6.2 的独立管线阶段）：
+ * - assistant 消息里的 tool_call，若在下一条 assistant 消息之前没有对应的 tool_result，
+ *   紧跟该 assistant 消息补一条 user 消息，内含 `isError: true` 的 unknown 结果；
+ * - 找不到对应 call（或出现在下一条 assistant 之后）的孤立 tool_result 删除，删空的消息一并去掉。
+ * 不修改入参。
+ */
+export declare function guardToolPairs(messages: ModelMessage[]): ModelMessage[];

package/dist/runtime/context/pairing.js

@@ -0,0 +1,82 @@
+/** 补给缺失结果的 tool_call 的结果文案（模型可见，英文）。 */
+export const UNKNOWN_RESULT_TEXT = "Result unknown: the call was interrupted before a result was recorded. Verify the outcome before retrying.";
+/**
+ * tool_call / tool_result 配对守卫（spec 6.2 的独立管线阶段）：
+ * - assistant 消息里的 tool_call，若在下一条 assistant 消息之前没有对应的 tool_result，
+ *   紧跟该 assistant 消息补一条 user 消息，内含 `isError: true` 的 unknown 结果；
+ * - 找不到对应 call（或出现在下一条 assistant 之后）的孤立 tool_result 删除，删空的消息一并去掉。
+ * 不修改入参。
+ */
+export function guardToolPairs(messages) {
+    const out = [];
+    let i = 0;
+    while (i < messages.length) {
+        const m = messages[i];
+        i++;
+        if (m.role !== "assistant") {
+            // 不在任何 assistant 之后窗口内的结果都是孤立的。
+            pushFiltered(out, m, new Set());
+            continue;
+        }
+        out.push(m);
+        const callIds = m.content.flatMap((b) => (b.type === "tool_call" ? [b.id] : []));
+        if (callIds.length === 0)
+            continue;
+        // 收集到下一条 assistant 之前的消息，并统计其中已有的结果。
+        const window = [];
+        while (i < messages.length && messages[i].role !== "assistant") {
+            window.push(messages[i]);
+            i++;
+        }
+        const answered = new Set();
+        for (const w of window) {
+            if (w.role === "system")
+                continue;
+            for (const b of w.content)
+                if (b.type === "tool_result")
+                    answered.add(b.callId);
+        }
+        const missing = callIds.filter((id) => !answered.has(id));
+        if (missing.length > 0) {
+            out.push({
+                role: "user",
+                content: missing.map((callId) => ({
+                    type: "tool_result",
+                    callId,
+                    content: UNKNOWN_RESULT_TEXT,
+                    isError: true,
+                })),
+            });
+        }
+        const valid = new Set(callIds);
+        // 同一 call 只保留第一个结果。
+        for (const w of window)
+            pushFiltered(out, w, valid);
+    }
+    return out;
+}
+/** 只保留 callId 在 `valid` 中（且尚未用过）的 tool_result；消息删空则丢弃。 */
+function pushFiltered(out, m, valid) {
+    if (m.role === "system") {
+        out.push(m);
+        return;
+    }
+    if (!m.content.some((b) => b.type === "tool_result")) {
+        out.push(m);
+        return;
+    }
+    const content = m.content.filter((b) => {
+        if (b.type !== "tool_result")
+            return true;
+        if (!valid.has(b.callId))
+            return false;
+        valid.delete(b.callId);
+        return true;
+    });
+    if (content.length === m.content.length) {
+        out.push(m);
+    }
+    else if (content.length > 0) {
+        out.push({ ...m, content });
+    }
+}

package/dist/runtime/context/reminders.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 轮次收尾的尾部提醒：`step >= maxSteps - 2` 时返回英文软提醒，否则 null。
+ * 调用方先把它写成 `reminder` 事件，再由 `buildModelRequest` 按事件重建进请求。
+ */
+export declare function turnLimitReminder(step: number, maxSteps: number): string | null;

package/dist/runtime/context/reminders.js

@@ -0,0 +1,11 @@
+/** 距本轮步数上限还剩几步时开始提醒。 */
+const TURN_LIMIT_LEAD = 2;
+/**
+ * 轮次收尾的尾部提醒：`step >= maxSteps - 2` 时返回英文软提醒，否则 null。
+ * 调用方先把它写成 `reminder` 事件，再由 `buildModelRequest` 按事件重建进请求。
+ */
+export function turnLimitReminder(step, maxSteps) {
+    if (step < maxSteps - TURN_LIMIT_LEAD)
+        return null;
+    return `You are close to the step limit for this turn (step ${step} of ${maxSteps}). Wrap up and give the user your best answer now.`;
+}

package/dist/runtime/context/skills.d.ts

@@ -0,0 +1,105 @@
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+/**
+ * 技能目录在模型请求里的渲染（M5 T14，Ruling M17）。纯函数：只取决于日志里的 `skills_catalog` 快照，
+ * 请求可由日志还原。模型可见文案一律英文。
+ */
+/** 快照里的一项技能。 */
+export type CatalogSkill = EventPayload<"skills_catalog">["skills"][number];
+/** The whole `skills_catalog` payload. */
+export type SkillsSnapshot = EventPayload<"skills_catalog">;
+/** A pinned skill in a snapshot (phase B, spec §9.1). */
+export type PinnedSkill = NonNullable<SkillsSnapshot["pinned"]>[number];
+/** 日志里的 `skills_catalog` 事件。 */
+export type SkillsCatalogEvent = Extract<ConversationEvent, {
+    type: "skills_catalog";
+}>;
+/** 加载技能的内置工具名。 */
+export declare const SKILL_LOAD = "skill_load";
+/** 目录开头的说明（system 缓存段里的第一份目录）。 */
+export declare const SKILLS_CATALOG_HEADER: string;
+/** 目录里每个技能描述最多的码点数（超出确定地截断；`skill_load` 仍返回完整正文）。 */
+export declare const CATALOG_DESCRIPTION_MAX_CHARS = 300;
+/** 第一份目录（进 system 缓存段），按名字排序。 */
+export declare function skillsCatalogText(skills: readonly CatalogSkill[]): string;
+/** 两份快照是否相同（按 id、版本、名字、描述与来源）。顺序无关。 */
+export declare function sameSkills(a: readonly CatalogSkill[], b: readonly CatalogSkill[]): boolean;
+/**
+ * Two pinned lists are the same: id, version and source in order (absent = []). Bodies follow the
+ * source. The order counts, so a reordered `skills.pinned` writes a new snapshot; that snapshot
+ * renders no message ({@link pinnedChangeText} is "" and the catalog part is skipped), and only the
+ * system segment of a new conversation or a compaction restore shows the new order. This is
+ * deliberate and consistent from the log: do not "fix" the missing message.
+ */
+export declare function samePinned(a: readonly PinnedSkill[] | undefined, b: readonly PinnedSkill[] | undefined): boolean;
+/**
+ * Two snapshots are the same: {@link sameSkills} (`plugin` is not compared, so a snapshot written
+ * before phase B stays current), {@link samePinned} and the same `toolMap` (absent = undefined).
+ */
+export declare function sameSnapshot(a: SkillsSnapshot, b: SkillsSnapshot): boolean;
+/**
+ * 目录变更提醒（之后的快照在所在位置以 system 消息追加）：新增、移除、更新（同一 id 的版本、描述或来源变了：
+ * 试用草稿被拒绝 / 批准了别人的同号版本时，内容变了而版本号可能不变）。
+ * `prev` 为上一份快照（没有为空）。
+ */
+export declare function skillsChangeText(prev: readonly CatalogSkill[], next: readonly CatalogSkill[], pinnedIds?: ReadonlySet<string>): string;
+/** 压缩摘要之后补上的「当前目录」（与 system 里的第一份不同时）：完整列出，替代之前的目录与提醒。 */
+export declare function skillsCurrentText(skills: readonly CatalogSkill[]): string;
+/**
+ * The line restored after a compaction summary whose range holds inline skill invocations
+ * (`names`: distinct, code point order); empty for none. Bodies are not re-injected.
+ */
+export declare function invokedSkillsText(names: readonly string[]): string;
+/** The distinct names (code point order) of the inline invocations in `events` up to `upToSeq`. */
+export declare function invokedSkillNames(events: readonly ConversationEvent[], upToSeq: number): string[];
+/** A skill a person invoked: the version recorded in their message. */
+export interface InvokedSkill {
+    id: string;
+    version: number;
+    source: string;
+    name: string;
+    plugin?: string;
+}
+/**
+ * The latest invocation in `events` of the skill `name` (its bare name, or `<plugin>:<name>`),
+ * from the `skill` field of the `user_message`s; undefined when none.
+ */
+export declare function latestInvocation(events: readonly ConversationEvent[], name: string): InvokedSkill | undefined;
+/** 日志里的全部 `skills_catalog` 事件，按 seq 升序。 */
+export declare function skillsCatalogEvents(events: readonly ConversationEvent[]): SkillsCatalogEvent[];
+/** 最新一份快照；没有为 null。 */
+export declare function latestSkillsCatalog(events: readonly ConversationEvent[]): SkillsCatalogEvent | null;
+/**
+ * 进 system 缓存段的快照：第一份快照，且它之前没有任何 `model_call`（对话已经发过请求之后才有技能时，
+ * 改为在所在位置追加提醒，已发送的前缀不变）。没有为 null。
+ */
+export declare function systemSkillsCatalog(events: readonly ConversationEvent[]): SkillsCatalogEvent | null;
+/** The header of the pinned skills in the system cache segment. */
+export declare const PINNED_SKILLS_HEADER: string;
+/** One pinned skill with its body. */
+export declare function pinnedBlock(p: PinnedSkill): string;
+/** The pinned skills of the system snapshot (non-empty), after the catalog. */
+export declare function pinnedSystemText(pinned: readonly PinnedSkill[]): string;
+/**
+ * The pinned change notice between two snapshots ({@link samePinned} false): each entry that is new
+ * or has another version or source, with its whole body; then the names of the removed ones.
+ * Empty when nothing changed.
+ */
+export declare function pinnedChangeText(prev: readonly PinnedSkill[] | undefined, next: readonly PinnedSkill[] | undefined): string;
+/** The pinned skills after a compaction summary, when they differ from the system snapshot's. */
+export declare function pinnedCurrentText(pinned: readonly PinnedSkill[] | undefined): string;
+/** The tool-name map change notice (the map differs from the previous one). */
+export declare function toolMapChangeText(next: string | undefined): string;
+/**
+ * The one system message of a later snapshot: the catalog change (when the skills differ, or when
+ * nothing else differs: logs before phase B render exactly as before), the pinned change, the
+ * tool-name map change; joined by blank lines.
+ */
+export declare function snapshotChangeText(prev: SkillsSnapshot | undefined, next: SkillsSnapshot): string;
+/**
+ * What follows a compaction summary when the covered snapshot is not the system one: today's
+ * current catalog (when the skills differ from the system snapshot's), the current pinned skills
+ * (when they differ), the tool-name map (when it differs); joined by blank lines, "" for nothing.
+ */
+export declare function snapshotCurrentText(system: SkillsSnapshot | undefined, covered: SkillsSnapshot): string;
+/** The system snapshot's text after the agent's instructions: catalog, pinned skills, tool map. */
+export declare function snapshotSystemText(s: SkillsSnapshot): string;