@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/runtime/context/environment-paths.d.ts

@@ -0,0 +1,40 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
+import type { ConversationEvent } from "../../conversations/events.js";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export declare function environmentPathsText(r: SandboxRoots): string;
+/** Whether two sets of roots are the same paths. */
+export declare const sameRoots: (a: SandboxRoots, b: SandboxRoots) => boolean;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export declare const environmentPathsIdemKey: (r: SandboxRoots, prevSeq: number) => string;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export declare function environmentPathsChange(latest: {
+    seq: number;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | undefined, roots: SandboxRoots, runId: string | undefined): {
+    type: "environment_paths";
+    runId?: string;
+    idemKey: string;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | null;
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export declare function environmentPathsAt(events: readonly ConversationEvent[], seq: number): Extract<ConversationEvent, {
+    type: "environment_paths";
+}> | undefined;

package/dist/runtime/context/environment-paths.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export function environmentPathsText(r) {
+    return `This environment's directories: workspace ${r.workspace}, skills ${r.skills} (read only), temporary files ${r.tmp}. Use these paths in commands and tool calls.`;
+}
+/** Whether two sets of roots are the same paths. */
+export const sameRoots = (a, b) => a.workspace === b.workspace && a.skills === b.skills && a.tmp === b.tmp;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export const environmentPathsIdemKey = (r, prevSeq) => `environment_paths:${createHash("sha256")
+    .update(JSON.stringify([r.workspace, r.skills, r.tmp]))
+    .digest("hex")
+    .slice(0, 16)}:${prevSeq}`;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export function environmentPathsChange(latest, roots, runId) {
+    if (latest && sameRoots(latest.payload.roots, roots))
+        return null;
+    return {
+        type: "environment_paths",
+        ...(runId !== undefined && { runId }),
+        idemKey: environmentPathsIdemKey(roots, latest?.seq ?? 0),
+        payload: { roots: { workspace: roots.workspace, skills: roots.skills, tmp: roots.tmp } },
+    };
+}
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export function environmentPathsAt(events, seq) {
+    let found;
+    for (const e of events) {
+        if (e.seq > seq)
+            break;
+        if (e.type === "environment_paths")
+            found = e;
+    }
+    return found;
+}

package/dist/runtime/context/legacy-text.d.ts

@@ -0,0 +1,22 @@
+import type { SkillTexts } from "./skills.js";
+/**
+ * The system texts of a request as the release candidates rendered them, naming the old builtins
+ * (`skill_load`, `tool_search`). FROZEN: verbatim copies from `main` at 02b9634b
+ * (`runtime/context/skills.ts`, `tools/builtins/tool-search.ts`); never edit them. A request whose
+ * tools hold an old builtin key (a recording made before the rename) is rebuilt with these, so it
+ * reconstructs with no `system_hash` drift (tool naming spec §10). `check:terms` exempts this file.
+ *
+ * The skills texts (`skills.ts`) naming `skill_load`.
+ */
+export declare const LEGACY_SKILL_TEXTS: SkillTexts;
+/** The tool catalog header (`tools/builtins/tool-search.ts` `CATALOG_HEADER`) naming `tool_search`. */
+export declare const LEGACY_CATALOG_HEADER: string;
+/**
+ * Was this request's tool list recorded before the rename? True when one of its tool keys is a
+ * release-candidate builtin name (the run's tools, as the request carries them). Every request
+ * that renders one of these texts offers the tool it names (`skill_load` whenever the log has a
+ * skills catalog or an invocation, `tool_search` with a tool catalog), so the tools decide it.
+ */
+export declare function usesLegacyToolNames(tools: readonly {
+    key: string;
+}[]): boolean;

package/dist/runtime/context/legacy-text.js

@@ -0,0 +1,37 @@
+import { isLegacyBuiltinKey } from "../../tools/legacy-keys.js";
+/**
+ * The system texts of a request as the release candidates rendered them, naming the old builtins
+ * (`skill_load`, `tool_search`). FROZEN: verbatim copies from `main` at 02b9634b
+ * (`runtime/context/skills.ts`, `tools/builtins/tool-search.ts`); never edit them. A request whose
+ * tools hold an old builtin key (a recording made before the rename) is rebuilt with these, so it
+ * reconstructs with no `system_hash` drift (tool naming spec §10). `check:terms` exempts this file.
+ *
+ * The skills texts (`skills.ts`) naming `skill_load`.
+ */
+export const LEGACY_SKILL_TEXTS = Object.freeze({
+    skillsCatalogHeader: "Skills are available in this conversation. A skill is a set of instructions, sometimes with " +
+        "scripts or other files, for a specific kind of task. When a task matches a skill's description, " +
+        "call skill_load with the skill's name to read its instructions before you start; do not guess " +
+        "what a skill says. Available skills:",
+    newSkills: "New skills (call skill_load with the name to use one):",
+    updatedSkills: "Updated skills (call skill_load again before relying on earlier instructions):",
+    currentSkills: "Skills available in this conversation now (this replaces any earlier list of skills; call " +
+        "skill_load with a name to read a skill's instructions):",
+    invokedSkills: (names) => `Skills the user invoked earlier in this conversation: ${names.join(", ")}. Call skill_load with a name to read its instructions again.`,
+    pinnedSkillsHeader: "Pinned skills: the owner of this agent pinned these skills, so their instructions apply " +
+        "throughout this conversation. Follow them without calling skill_load; call skill_load " +
+        "only to copy a pinned skill's files into the sandbox.",
+});
+/** The tool catalog header (`tools/builtins/tool-search.ts` `CATALOG_HEADER`) naming `tool_search`. */
+export const LEGACY_CATALOG_HEADER = "More tools are available but not loaded. To use one, first call tool_search with keywords; " +
+    "it returns the full definitions and loads the matching tools for your next step. " +
+    "Calling a tool that is not loaded returns an error. Tool catalog:";
+/**
+ * Was this request's tool list recorded before the rename? True when one of its tool keys is a
+ * release-candidate builtin name (the run's tools, as the request carries them). Every request
+ * that renders one of these texts offers the tool it names (`skill_load` whenever the log has a
+ * skills catalog or an invocation, `tool_search` with a tool catalog), so the tools decide it.
+ */
+export function usesLegacyToolNames(tools) {
+    return tools.some((t) => isLegacyBuiltinKey(t.key));
+}

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

@@ -3,3 +3,5 @@
  * 调用方先把它写成 `reminder` 事件，再由 `buildModelRequest` 按事件重建进请求。
  */
 export declare function turnLimitReminder(step: number, maxSteps: number): string | null;
+/** 所用模型不支持工具（`capabilities.tools` 为 false）时的提醒（模型可见，英文）。 */
+export declare const TOOLS_UNSUPPORTED_REMINDER = "Tools are unavailable for this model. Answer without calling tools.";

package/dist/runtime/context/reminders.js

@@ -9,3 +9,5 @@ export function turnLimitReminder(step, maxSteps) {
         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.`;
 }
+/** 所用模型不支持工具（`capabilities.tools` 为 false）时的提醒（模型可见，英文）。 */
+export const TOOLS_UNSUPPORTED_REMINDER = "Tools are unavailable for this model. Answer without calling tools.";

package/dist/runtime/context/run-context.d.ts

@@ -0,0 +1,65 @@
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+/**
+ * Run context (spec 2026-11-08-run-context-design): who the agent is, the org, the date, the time
+ * zone and language of the person it works for, and who wrote each user message. Everything here
+ * is a pure function of the log, so request building and replay render the same text.
+ */
+export type RunContext = EventPayload<"run_context">;
+export type MessageSender = NonNullable<EventPayload<"user_message">["sender"]>;
+type RunContextEvent = ConversationEvent & {
+    type: "run_context";
+    payload: RunContext;
+};
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export declare const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export declare const SENDER_NAME_MAX = 80;
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export declare const sanitizeSenderName: (name: string) => string;
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export declare function snapshotDescription(description: string | undefined): string | undefined;
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export declare function dateIn(now: Date, timeZone: string): string;
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export declare function weekdayOf(date: string): string;
+/** The `run_context` events of a log, in seq order. */
+export declare function runContextEvents(events: readonly ConversationEvent[]): RunContextEvent[];
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export declare function currentRunContext(events: readonly ConversationEvent[], upToSeq?: number): RunContext;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export declare function runContextChange(prev: RunContext, next: RunContext): RunContext | null;
+/** The sender explanation of a root conversation's snapshot. */
+export declare const SENDER_NOTE = "- A user message may start with a line \"From <name> (<role>)\" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.";
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export declare function runContextFullText(ctx: RunContext): string;
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export declare function runContextUpdateText(prev: RunContext, change: RunContext): string;
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export declare function runContextText(events: readonly ConversationEvent[], e: RunContextEvent): string;
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export declare function senderLine(s: MessageSender): string;
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export declare function senderTranscriptLabel(s: MessageSender): string;
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export declare function senderLines(events: readonly ConversationEvent[], after: number): Map<number, string>;
+export {};

package/dist/runtime/context/run-context.js

@@ -0,0 +1,215 @@
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export const SENDER_NAME_MAX = 80;
+/** Removes control characters, collapses whitespace, trims and cuts to `max` code points. */
+function oneLine(text, max, ellipsis) {
+    const flat = text
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const points = [...flat];
+    if (points.length <= max)
+        return flat;
+    return ellipsis ? `${points.slice(0, max - 1).join("")}…` : points.slice(0, max).join("");
+}
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export const sanitizeSenderName = (name) => oneLine(name, SENDER_NAME_MAX, false);
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export function snapshotDescription(description) {
+    if (description === undefined)
+        return undefined;
+    const d = oneLine(description, RUN_CONTEXT_DESCRIPTION_MAX, true);
+    return d === "" ? undefined : d;
+}
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export function dateIn(now, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    return `${part("year")}-${part("month")}-${part("day")}`;
+}
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export function weekdayOf(date) {
+    const [y, m, d] = date.split("-").map(Number);
+    return WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+const LANGUAGE = {
+    zh: "Chinese (zh)",
+    en: "English (en)",
+};
+/** The `run_context` events of a log, in seq order. */
+export function runContextEvents(events) {
+    return events
+        .filter((e) => e.type === "run_context")
+        .sort((a, b) => a.seq - b.seq);
+}
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export function currentRunContext(events, upToSeq = Number.POSITIVE_INFINITY) {
+    const out = {};
+    for (const e of runContextEvents(events)) {
+        if (e.seq > upToSeq)
+            break;
+        Object.assign(out, e.payload);
+    }
+    return out;
+}
+const sameAgent = (a, b) => a?.name === b?.name && a?.description === b?.description;
+const sameDispatcher = (a, b) => a?.agent === b?.agent && a?.person === b?.person;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export function runContextChange(prev, next) {
+    const out = {};
+    if (next.agent !== undefined && !sameAgent(prev.agent, next.agent))
+        out.agent = next.agent;
+    if (next.org !== undefined && next.org.name !== prev.org?.name)
+        out.org = next.org;
+    const zoneChanged = next.timeZone !== undefined && next.timeZone !== prev.timeZone;
+    if (zoneChanged)
+        out.timeZone = next.timeZone;
+    if (next.date !== undefined &&
+        next.date !== prev.date &&
+        (prev.date === undefined || next.date > prev.date || zoneChanged)) {
+        out.date = next.date;
+    }
+    if (next.locale !== undefined && next.locale !== prev.locale)
+        out.locale = next.locale;
+    if (next.dispatchedBy !== undefined && !sameDispatcher(prev.dispatchedBy, next.dispatchedBy)) {
+        out.dispatchedBy = next.dispatchedBy;
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+const q = (s) => JSON.stringify(s);
+/** The sender explanation of a root conversation's snapshot. */
+export const SENDER_NOTE = '- A user message may start with a line "From <name> (<role>)" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.';
+function dayLine(date, timeZone, prevZone) {
+    const was = prevZone !== undefined && prevZone !== timeZone ? ` (it was ${prevZone})` : "";
+    if (date !== undefined) {
+        const zone = timeZone !== undefined ? `, time zone ${timeZone}${was}` : "";
+        return `Today is ${date} (${weekdayOf(date)})${zone}.`;
+    }
+    return timeZone !== undefined ? `Your time zone is ${timeZone}${was}.` : null;
+}
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export function runContextFullText(ctx) {
+    const lines = [];
+    const name = ctx.agent?.name;
+    if (ctx.dispatchedBy !== undefined) {
+        const who = name !== undefined ? `You are ${q(name)}, dispatched` : "You were dispatched";
+        lines.push(`- ${who} by the agent ${q(ctx.dispatchedBy.agent)} working for ${ctx.dispatchedBy.person}.`);
+    }
+    else if (name !== undefined) {
+        const org = ctx.org !== undefined ? `, an agent in the org ${q(ctx.org.name)}` : "";
+        const description = ctx.agent?.description !== undefined ? ` Your description: ${ctx.agent.description}` : "";
+        lines.push(`- You are ${q(name)}${org}.${description}`);
+    }
+    else if (ctx.org !== undefined) {
+        lines.push(`- You work in the org ${q(ctx.org.name)}.`);
+    }
+    const day = dayLine(ctx.date, ctx.timeZone);
+    if (day !== null)
+        lines.push(`- ${day}`);
+    if (ctx.locale !== undefined) {
+        lines.push(`- The person's language is ${LANGUAGE[ctx.locale]}. Reply in the language the person writes in.`);
+    }
+    if (ctx.dispatchedBy === undefined)
+        lines.push(SENDER_NOTE);
+    return [
+        "Context from the platform:",
+        ...lines,
+        "A later context update replaces these facts.",
+    ].join("\n");
+}
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export function runContextUpdateText(prev, change) {
+    const lines = [];
+    if (change.agent !== undefined) {
+        const before = prev.agent;
+        if (change.agent.name !== before?.name) {
+            const was = before !== undefined ? ` (it was ${q(before.name)})` : "";
+            lines.push(`- Your name is now ${q(change.agent.name)}${was}.`);
+        }
+        if (change.agent.description !== before?.description) {
+            lines.push(change.agent.description !== undefined
+                ? `- Your description is now: ${change.agent.description}`
+                : "- You no longer have a description.");
+        }
+    }
+    if (change.org !== undefined) {
+        const was = prev.org !== undefined ? ` (it was ${q(prev.org.name)})` : "";
+        lines.push(`- The org is now named ${q(change.org.name)}${was}.`);
+    }
+    if (change.date !== undefined || change.timeZone !== undefined) {
+        const day = dayLine(change.date ?? prev.date, change.timeZone ?? prev.timeZone, change.timeZone !== undefined ? prev.timeZone : undefined);
+        if (day !== null)
+            lines.push(`- ${day}`);
+    }
+    if (change.locale !== undefined) {
+        const was = prev.locale !== undefined ? ` (it was ${LANGUAGE[prev.locale]})` : "";
+        lines.push(`- The person's language is now ${LANGUAGE[change.locale]}${was}.`);
+    }
+    if (change.dispatchedBy !== undefined) {
+        lines.push(`- You now work for ${change.dispatchedBy.person}, dispatched by the agent ${q(change.dispatchedBy.agent)}.`);
+    }
+    return ["Context update (replaces the earlier values):", ...lines].join("\n");
+}
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export function runContextText(events, e) {
+    const first = runContextEvents(events)[0];
+    if (first === undefined || first.seq === e.seq)
+        return runContextFullText(e.payload);
+    return runContextUpdateText(currentRunContext(events, e.seq - 1), e.payload);
+}
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export function senderLine(s) {
+    if (s.anonymous === true)
+        return `From ${s.name} (guest, not signed in)`;
+    return s.role !== undefined ? `From ${s.name} (${s.role})` : `From ${s.name}`;
+}
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export function senderTranscriptLabel(s) {
+    if (s.anonymous === true)
+        return `From ${s.name}, guest, not signed in`;
+    return s.role !== undefined ? `From ${s.name}, ${s.role}` : `From ${s.name}`;
+}
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export function senderLines(events, after) {
+    const out = new Map();
+    let first = true;
+    let prev = null;
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.seq <= after || e.type !== "user_message")
+            continue;
+        const line = e.payload.sender !== undefined ? senderLine(e.payload.sender) : null;
+        if (line !== null && (first || line !== prev))
+            out.set(e.seq, line);
+        prev = line;
+        first = false;
+    }
+    return out;
+}

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

@@ -13,14 +13,32 @@ export type PinnedSkill = NonNullable<SkillsSnapshot["pinned"]>[number];
 export type SkillsCatalogEvent = Extract<ConversationEvent, {
     type: "skills_catalog";
 }>;
-/** 加载技能的内置工具名。 */
-export declare const SKILL_LOAD = "skill_load";
+/**
+ * The model-visible skills texts that name the skill-loading builtin. A request recorded before the
+ * tool rename renders {@link LEGACY_SKILL_TEXTS} instead (`./legacy-text.ts`, chosen from the
+ * request's tools by `usesLegacyToolNames`), so its system text stays as it was sent.
+ */
+export interface SkillTexts {
+    /** The header of the first catalog (in the system cache segment). */
+    skillsCatalogHeader: string;
+    /** The heading of the added skills in a change notice. */
+    newSkills: string;
+    /** The heading of the updated skills in a change notice. */
+    updatedSkills: string;
+    /** The heading of the current catalog after a compaction summary. */
+    currentSkills: string;
+    /** The line restored after a compaction summary for the invoked skills (`names` non-empty). */
+    invokedSkills: (names: readonly string[]) => string;
+    /** The header of the pinned skills in the system cache segment. */
+    pinnedSkillsHeader: string;
+}
+export declare const SKILL_TEXTS: SkillTexts;
 /** 目录开头的说明（system 缓存段里的第一份目录）。 */
 export declare const SKILLS_CATALOG_HEADER: string;
-/** 目录里每个技能描述最多的码点数（超出确定地截断；`skill_load` 仍返回完整正文）。 */
+/** 目录里每个技能描述最多的码点数（超出确定地截断；`Skill` 仍返回完整正文）。 */
 export declare const CATALOG_DESCRIPTION_MAX_CHARS = 300;
 /** 第一份目录（进 system 缓存段），按名字排序。 */
-export declare function skillsCatalogText(skills: readonly CatalogSkill[]): string;
+export declare function skillsCatalogText(skills: readonly CatalogSkill[], texts?: SkillTexts): string;
 /** 两份快照是否相同（按 id、版本、名字、描述与来源）。顺序无关。 */
 export declare function sameSkills(a: readonly CatalogSkill[], b: readonly CatalogSkill[]): boolean;
 /**
@@ -41,14 +59,14 @@ export declare function sameSnapshot(a: SkillsSnapshot, b: SkillsSnapshot): bool
  * 试用草稿被拒绝 / 批准了别人的同号版本时，内容变了而版本号可能不变）。
  * `prev` 为上一份快照（没有为空）。
  */
-export declare function skillsChangeText(prev: readonly CatalogSkill[], next: readonly CatalogSkill[], pinnedIds?: ReadonlySet<string>): string;
+export declare function skillsChangeText(prev: readonly CatalogSkill[], next: readonly CatalogSkill[], pinnedIds?: ReadonlySet<string>, texts?: SkillTexts): string;
 /** 压缩摘要之后补上的「当前目录」（与 system 里的第一份不同时）：完整列出，替代之前的目录与提醒。 */
-export declare function skillsCurrentText(skills: readonly CatalogSkill[]): string;
+export declare function skillsCurrentText(skills: readonly CatalogSkill[], texts?: SkillTexts): 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;
+export declare function invokedSkillsText(names: readonly string[], texts?: SkillTexts): 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. */
@@ -78,7 +96,7 @@ 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;
+export declare function pinnedSystemText(pinned: readonly PinnedSkill[], texts?: SkillTexts): 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.
@@ -94,12 +112,12 @@ export declare function toolMapChangeText(next: string | undefined): string;
  * 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;
+export declare function snapshotChangeText(prev: SkillsSnapshot | undefined, next: SkillsSnapshot, texts?: SkillTexts): 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;
+export declare function snapshotCurrentText(system: SkillsSnapshot | undefined, covered: SkillsSnapshot, texts?: SkillTexts): string;
 /** The system snapshot's text after the agent's instructions: catalog, pinned skills, tool map. */
-export declare function snapshotSystemText(s: SkillsSnapshot): string;
+export declare function snapshotSystemText(s: SkillsSnapshot, texts?: SkillTexts): string;