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

package/dist/runtime/checkpointer.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from "@langchain/core/runnables";
 import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from "@langchain/langgraph-checkpoint";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 /**
  * LangGraph checkpoint saver，存在内核 schema 的 `lg_checkpoints` / `lg_checkpoint_writes` 里（0007_checkpoints.sql）。
  *
@@ -10,12 +11,16 @@ import type { KernelDb } from "../db/kernel-schema.js";
  * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
  */
 export declare class KyselyCheckpointSaver extends BaseCheckpointSaver {
-    private readonly db;
-    constructor(db: KernelDb);
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, txHost: TransactionHost);
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    private get db();
     getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
     list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
     put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: ChannelVersions): Promise<RunnableConfig>;
     putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;
+    private insertWrites;
     deleteThread(threadId: string): Promise<void>;
     /**
      * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，

package/dist/runtime/checkpointer.js

@@ -1,5 +1,18 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { BaseCheckpointSaver, compareWritesSortKeys, copyCheckpoint, getCheckpointId, maxChannelVersion, TASKS, WRITES_IDX_MAP, writesSortKey, } from "@langchain/langgraph-checkpoint";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 const CHECKPOINT_COLUMNS = [
     "thread_id",
     "checkpoint_ns",
@@ -20,11 +33,17 @@ const idC = sql `checkpoint_id collate "C"`;
  * - thread_id 约定为 runId。
  * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
  */
-export class KyselyCheckpointSaver extends BaseCheckpointSaver {
-    db;
-    constructor(db) {
+let KyselyCheckpointSaver = class KyselyCheckpointSaver extends BaseCheckpointSaver {
+    kdb;
+    txHost;
+    constructor(kdb, txHost) {
         super();
-        this.db = db;
+        this.kdb = kdb;
+        this.txHost = txHost;
+    }
+    /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
+    get db() {
+        return this.kdb.db;
     }
     async getTuple(config) {
         const threadId = config.configurable?.thread_id;
@@ -130,34 +149,33 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
         // 特殊 channel（错误、中断等，idx < 0）以最后一次为准；普通 write 已存在则保留先写入的。
         const special = rows.filter((r) => r.idx < 0);
         const regular = rows.filter((r) => r.idx >= 0);
+        await this.insertWrites(regular, special);
+    }
+    async insertWrites(regular, special) {
         const key = ["thread_id", "checkpoint_ns", "checkpoint_id", "task_id", "idx"];
-        await this.db.transaction().execute(async (trx) => {
-            if (regular.length > 0) {
-                await trx
-                    .insertInto("lg_checkpoint_writes")
-                    .values(regular)
-                    .onConflict((oc) => oc.columns(key).doNothing())
-                    .execute();
-            }
-            if (special.length > 0) {
-                await trx
-                    .insertInto("lg_checkpoint_writes")
-                    .values(special)
-                    .onConflict((oc) => oc.columns(key).doUpdateSet((eb) => ({
-                    channel: eb.ref("excluded.channel"),
-                    value_type: eb.ref("excluded.value_type"),
-                    value: eb.ref("excluded.value"),
-                    task_path: eb.ref("excluded.task_path"),
-                })))
-                    .execute();
-            }
-        });
+        if (regular.length > 0) {
+            await this.db
+                .insertInto("lg_checkpoint_writes")
+                .values(regular)
+                .onConflict((oc) => oc.columns(key).doNothing())
+                .execute();
+        }
+        if (special.length > 0) {
+            await this.db
+                .insertInto("lg_checkpoint_writes")
+                .values(special)
+                .onConflict((oc) => oc.columns(key).doUpdateSet((eb) => ({
+                channel: eb.ref("excluded.channel"),
+                value_type: eb.ref("excluded.value_type"),
+                value: eb.ref("excluded.value"),
+                task_path: eb.ref("excluded.task_path"),
+            })))
+                .execute();
+        }
     }
     async deleteThread(threadId) {
-        await this.db.transaction().execute(async (trx) => {
-            await trx.deleteFrom("lg_checkpoint_writes").where("thread_id", "=", threadId).execute();
-            await trx.deleteFrom("lg_checkpoints").where("thread_id", "=", threadId).execute();
-        });
+        await this.db.deleteFrom("lg_checkpoint_writes").where("thread_id", "=", threadId).execute();
+        await this.db.deleteFrom("lg_checkpoints").where("thread_id", "=", threadId).execute();
     }
     /**
      * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，
@@ -166,31 +184,30 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
      * 保留下来的 checkpoint 的 parent_checkpoint_id 原样保留（父 checkpoint 已不存在）。
      */
     async pruneToLatest(threadId) {
-        return this.db.transaction().execute(async (trx) => {
-            const latest = await trx
-                .selectFrom("lg_checkpoints")
-                .select("checkpoint_id")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .orderBy(sql `${idC} desc`)
-                .limit(1)
-                .executeTakeFirst();
-            if (!latest)
-                return 0;
-            await trx
-                .deleteFrom("lg_checkpoint_writes")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .where(idC, "<", latest.checkpoint_id)
-                .execute();
-            const res = await trx
-                .deleteFrom("lg_checkpoints")
-                .where("thread_id", "=", threadId)
-                .where("checkpoint_ns", "=", "")
-                .where(idC, "<", latest.checkpoint_id)
-                .executeTakeFirst();
-            return Number(res.numDeletedRows);
-        });
+        const db = this.db;
+        const latest = await db
+            .selectFrom("lg_checkpoints")
+            .select("checkpoint_id")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .orderBy(sql `${idC} desc`)
+            .limit(1)
+            .executeTakeFirst();
+        if (!latest)
+            return 0;
+        await db
+            .deleteFrom("lg_checkpoint_writes")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .where(idC, "<", latest.checkpoint_id)
+            .execute();
+        const res = await db
+            .deleteFrom("lg_checkpoints")
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", "")
+            .where(idC, "<", latest.checkpoint_id)
+            .executeTakeFirst();
+        return Number(res.numDeletedRows);
     }
     async toTuple(row, metadata) {
         const { thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id } = row;
@@ -240,4 +257,19 @@ export class KyselyCheckpointSaver extends BaseCheckpointSaver {
         checkpoint.channel_versions[TASKS] =
             versions.length > 0 ? maxChannelVersion(...versions) : this.getNextVersion(undefined);
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "insertWrites", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "deleteThread", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], KyselyCheckpointSaver.prototype, "pruneToLatest", null);
+KyselyCheckpointSaver = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], KyselyCheckpointSaver);
+export { KyselyCheckpointSaver };

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

@@ -1,6 +1,6 @@
 import { type ContentBlock, type ModelInfo, type ModelRequest, type ParamValue } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../../agents/definition.js";
-import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+import { type ConversationEvent, type EventPayload } from "../../conversations/events.js";
 import type { ResolvedTool } from "../../tools/registry.js";
 /**
  * 平台行为规范（模型可见，英文）。短而通用（spec 6 原则 5）；不放时间戳、会话 ID 等会变化的内容，
@@ -25,13 +25,13 @@ export interface ModelCallMeta {
     params: Record<string, ParamValue>;
     /**
      * 请求带的工具（按发送顺序）及定义指纹；定义本身按指纹存在 `capybara.tool_specs`。
-     * 未启用 tool_search 时按 key 排序；启用时见 {@link BuildModelRequestInput.toolSearch}。
+     * 未启用 ToolSearch 时按 key 排序；启用时见 {@link BuildModelRequestInput.toolSearch}。
      */
     tools: {
         key: string;
         specHash: string;
     }[];
-    /** 启用 tool_search 时 system 第二块目录里的工具（按 key 排序）及定义指纹；未启用没有该字段。 */
+    /** 启用 ToolSearch 时 system 第二块目录里的工具（按 key 排序）及定义指纹；未启用没有该字段。 */
     catalog?: {
         key: string;
         specHash: string;
@@ -54,13 +54,14 @@ export interface BuildModelRequestInput {
     model: ModelInfo;
     step: number;
     /**
-     * loop 已吸收到的 user_message seq（R31）。提供时：
-     * - seq 大于它的 user_message 不进请求（运行中途到达、尚未被吸收的插话，由后续步骤吸收或触发下一轮）；
-     * - 每条 user_message 放在**吸收它的那次模型调用**的位置：日志里第一个 `request.absorbedUpToSeq`
+     * loop 已吸收到的位置（R31）：the largest seq of the absorbable events (`user_message`,
+     * `background_task_finished` and `subagent_delivery`, {@link isAbsorbable}) the loop took. 提供时：
+     * - seq 大于它的可吸收事件不进请求（运行中途到达、尚未被吸收的插话或后台任务结束，由后续步骤吸收或触发下一轮）；
+     * - 每个可吸收事件放在**吸收它的那次模型调用**的位置：日志里第一个 `request.absorbedUpToSeq`
      *   不小于它的 `model_call` 之前（没有该字段的旧 model_call 视为吸收了它之前的全部消息），
      *   本次请求吸收的放在末尾。于是模型看到的历史只追加（插话不会插到已发送的回复之前），
      *   且请求可由日志 + `model_call` 精确还原。
-     * 不提供时按 seq 原样回放全部 user_message。
+     * 不提供时按 seq 原样回放全部可吸收事件。
      */
     absorbedUpToSeq?: number;
     /**
@@ -75,8 +76,8 @@ export interface BuildModelRequestInput {
      */
     tools?: RequestTool[];
     /**
-     * 启用 tool_search（spec 5.5，由 `ToolRegistry.forAgent` 判定）。启用且有工具时：
-     * - `tools` 只放内置工具（含 `tool_search`，按 key 排序）与**已加载**工具的完整定义；
+     * 启用 ToolSearch（spec 5.5，由 `ToolRegistry.forAgent` 判定）。启用且有工具时：
+     * - `tools` 只放内置工具（含 `ToolSearch`，按 key 排序）与**已加载**工具的完整定义；
      *   已加载 = 日志中全部 `tool_result.loadedTools` 的并集（含摘要之前的；不在本步可用工具中的忽略），
      *   按首次加载顺序追加在内置工具之后——新加载只在末尾追加，已发送的工具顺序不变；
      * - 其余工具（不论是否已加载）以目录形式放进 system 第二个块（按 key 排序，打缓存断点），
@@ -224,17 +225,24 @@ export declare function summaryText(summary: string): string;
  * 由会话事件日志 + agent 定义构建模型请求（纯函数，不做 I/O）。
  * - system：`BEHAVIOR_RULES + "\n\n" + agent.instructions` 一个块，打缓存断点（a sub-agent's log:
  *   `BEHAVIOR_RULES`, its preamble and its instructions, all from its `subagent_started`）；日志里第一份 `skills_catalog`
- *   快照在任何 `model_call` 之前时，技能目录接在这个块末尾（Ruling M17，见 ./skills.ts）；启用 tool_search 时
+ *   快照在任何 `model_call` 之前时，技能目录接在这个块末尾（Ruling M17，见 ./skills.ts）；启用 ToolSearch 时
  *   第二个块是工具目录（见 {@link BuildModelRequestInput.toolSearch}）；
  * - 之后的 `skills_catalog` 在所在位置渲染为 system 变更提醒；被压缩摘要覆盖的，若摘要时生效的目录与 system 里的
  *   不同，紧随摘要补一条完整的当前目录；
  * - messages：最近一条摘要（若有）作为首条 user 消息，其后按 seq 回放 `coversUpToSeq` 之后的
  *   `user_message` / `assistant_message`（content 原样，含 opaque；aborted 的也回放；媒体引用按
  *   {@link resolveMedia} 换成 base64 或文字占位）/ `reminder`
- *   （`role: "system"`，放在它所在的位置）；`tool_result` 事件还原为紧随其 assistant 消息之后的一条 user 消息
+ *   （`role: "system"`，放在它所在的位置）/ `tools_changed` (`role: "system"`, the text of {@link toolsChangedText}, at its position) /
+ *   `environment_paths` (`role: "system"` at its position, `environmentPathsText`; covered by the
+ *   summary: the latest one follows the summary) /
+ *   `run_context` (`role: "system"` at its position, `runContextText`; covered by the summary: the
+ *   current context follows the summary whole; a user message's sender line by `senderLines`) /
+ *   `background_task_finished`（`role: "system"`, the text of
+ *   {@link renderBackgroundFinished}, placed like a user_message）/ `subagent_delivery` (likewise,
+ *   the text of {@link renderSubagentDelivery})；`tool_result` 事件还原为紧随其 assistant 消息之后的一条 user 消息
  *   （同一步的多个结果合并，按该 assistant 消息里 tool_call 的顺序；找不到对应调用的结果不进请求）。
  *   其他事件不进请求。提供 `absorbedUpToSeq` 时，
- *   尚未被吸收的 user_message 不进请求，运行中途到达的插话放在吸收它的调用处（见 BuildModelRequestInput）。
+ *   尚未被吸收的可吸收事件不进请求，运行中途到达的放在吸收它的调用处（见 BuildModelRequestInput）。
  * 只追加：新事件只会在 messages 末尾追加；唯一的前缀变化来自新的压缩摘要。
  * `step` 与 `agentVersion` 不进请求内容（保证缓存前缀稳定），由调用方写入 `model_call` 事件。
  */
@@ -245,7 +253,7 @@ export declare function buildModelRequest(input: BuildModelRequestInput): {
     mediaTokens: number;
 };
 /**
- * 日志里 `tool_search` 加载过的工具 key（全部 `tool_result.loadedTools` 的并集，按首次出现顺序）。
+ * 日志里 `ToolSearch` 加载过的工具 key（全部 `tool_result.loadedTools` 的并集，按首次出现顺序）。
  * 不看压缩摘要的边界：加载过的工具在摘要之后仍保持加载（模型可能凭摘要继续使用它们，且已发送的工具列表只追加）。
  */
 export declare function loadedToolKeys(events: readonly ConversationEvent[]): string[];

package/dist/runtime/context/build.js

@@ -1,7 +1,14 @@
 import { createHash } from "node:crypto";
 import { MEDIA_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { renderBackgroundFinished } from "../../background/render.js";
+import { isAbsorbable, } from "../../conversations/events.js";
 import { catalogText, isAlwaysLoaded } from "../../tools/builtins/tool-search.js";
-import { invokedSkillNames, invokedSkillsText, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
+import { renderSubagentDelivery } from "../subagents/render.js";
+import { environmentPathsAt, environmentPathsText } from "./environment-paths.js";
+import { LEGACY_CATALOG_HEADER, LEGACY_SKILL_TEXTS, usesLegacyToolNames } from "./legacy-text.js";
+import { currentRunContext, runContextEvents, runContextFullText, runContextText, senderLines, } from "./run-context.js";
+import { invokedSkillNames, invokedSkillsText, SKILL_TEXTS, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
+import { toolsChangedText } from "./tool-changes.js";
 /**
  * 平台行为规范（模型可见，英文）。短而通用（spec 6 原则 5）；不放时间戳、会话 ID 等会变化的内容，
  * 保证同一 agent 版本在所有会话中 system 前缀一致、可命中提示词缓存。改动它会让所有缓存失效。
@@ -322,17 +329,24 @@ export function summaryText(summary) {
  * 由会话事件日志 + agent 定义构建模型请求（纯函数，不做 I/O）。
  * - system：`BEHAVIOR_RULES + "\n\n" + agent.instructions` 一个块，打缓存断点（a sub-agent's log:
  *   `BEHAVIOR_RULES`, its preamble and its instructions, all from its `subagent_started`）；日志里第一份 `skills_catalog`
- *   快照在任何 `model_call` 之前时，技能目录接在这个块末尾（Ruling M17，见 ./skills.ts）；启用 tool_search 时
+ *   快照在任何 `model_call` 之前时，技能目录接在这个块末尾（Ruling M17，见 ./skills.ts）；启用 ToolSearch 时
  *   第二个块是工具目录（见 {@link BuildModelRequestInput.toolSearch}）；
  * - 之后的 `skills_catalog` 在所在位置渲染为 system 变更提醒；被压缩摘要覆盖的，若摘要时生效的目录与 system 里的
  *   不同，紧随摘要补一条完整的当前目录；
  * - messages：最近一条摘要（若有）作为首条 user 消息，其后按 seq 回放 `coversUpToSeq` 之后的
  *   `user_message` / `assistant_message`（content 原样，含 opaque；aborted 的也回放；媒体引用按
  *   {@link resolveMedia} 换成 base64 或文字占位）/ `reminder`
- *   （`role: "system"`，放在它所在的位置）；`tool_result` 事件还原为紧随其 assistant 消息之后的一条 user 消息
+ *   （`role: "system"`，放在它所在的位置）/ `tools_changed` (`role: "system"`, the text of {@link toolsChangedText}, at its position) /
+ *   `environment_paths` (`role: "system"` at its position, `environmentPathsText`; covered by the
+ *   summary: the latest one follows the summary) /
+ *   `run_context` (`role: "system"` at its position, `runContextText`; covered by the summary: the
+ *   current context follows the summary whole; a user message's sender line by `senderLines`) /
+ *   `background_task_finished`（`role: "system"`, the text of
+ *   {@link renderBackgroundFinished}, placed like a user_message）/ `subagent_delivery` (likewise,
+ *   the text of {@link renderSubagentDelivery})；`tool_result` 事件还原为紧随其 assistant 消息之后的一条 user 消息
  *   （同一步的多个结果合并，按该 assistant 消息里 tool_call 的顺序；找不到对应调用的结果不进请求）。
  *   其他事件不进请求。提供 `absorbedUpToSeq` 时，
- *   尚未被吸收的 user_message 不进请求，运行中途到达的插话放在吸收它的调用处（见 BuildModelRequestInput）。
+ *   尚未被吸收的可吸收事件不进请求，运行中途到达的放在吸收它的调用处（见 BuildModelRequestInput）。
  * 只追加：新事件只会在 messages 末尾追加；唯一的前缀变化来自新的压缩摘要。
  * `step` 与 `agentVersion` 不进请求内容（保证缓存前缀稳定），由调用方写入 `model_call` 事件。
  */
@@ -377,7 +391,7 @@ export function buildModelRequest(input) {
             lastCall = absorbedBy(e);
     }
     /**
-     * 第 i 个事件（user_message）的放置方式：
+     * 第 i 个事件（可吸收事件：user_message / background_task_finished / subagent_delivery）的放置方式：
      * - `inline`：在吸收它的调用（之后第一个 `absorbedBy ≥ seq` 的 model_call，或本次请求）之前，
      *   没有「由未吸收它的调用生成的回复」→ 按 seq 原位回放（常规情况，与不提供 absorbedUpToSeq 时一致）；
      * - `deferred`：它之后有非空 assistant_message 是由一次没有吸收它的 model_call 生成的（它在那一步
@@ -455,14 +469,38 @@ export function buildModelRequest(input) {
         }
         racedPending = racedPending.filter((x) => x.seq > toSeq);
     };
-    /** A user message's blocks, with its fork report when it has one. */
+    /** Run context spec §4: the sender lines, by the messages after the summary boundary. */
+    const senders = senderLines(events, after);
+    /**
+     * A user message's blocks: its sender line first when the sender changed (a separate block, so
+     * `content[0]` stays the typed text), then its own blocks, then its fork report when it has one.
+     */
     const userBlocks = (u) => {
         const report = forkReports.get(u.seq);
+        const line = senders.get(u.seq);
         const blocks = blocksOf(u.payload.content);
-        return report === undefined ? blocks : [...blocks, { type: "text", text: report }];
+        return [
+            ...(line === undefined ? [] : [{ type: "text", text: line }]),
+            ...blocks,
+            ...(report === undefined ? [] : [{ type: "text", text: report }]),
+        ];
     };
-    /** 被某次模型调用跳过（运行中途到达）、尚未被吸收的 user_message，按 seq 升序。 */
+    /** 被某次模型调用跳过（运行中途到达）、尚未被吸收的可吸收事件，按 seq 升序。 */
     let deferred = [];
+    /**
+     * An absorbable event as a request message: a user turn, or the system text of a finished task
+     * or a sub-agent's delivery.
+     */
+    const absorbableMessage = (e) => {
+        switch (e.type) {
+            case "user_message":
+                return { role: "user", content: userBlocks(e) };
+            case "background_task_finished":
+                return { role: "system", content: renderBackgroundFinished(e.payload) };
+            case "subagent_delivery":
+                return { role: "system", content: renderSubagentDelivery(e.payload) };
+        }
+    };
     /**
      * 把已被吸收（seq ≤ upTo）的延后消息按 seq 顺序放进 messages，插在末尾连续的 system 提醒之前
      * （若有）。这样某一步自己写在 model_call 之前的提醒（含收尾提醒）仍排在它所跟随的用户消息之后，
@@ -476,7 +514,7 @@ export function buildModelRequest(input) {
         let at = messages.length;
         while (at > 0 && messages[at - 1]?.role === "system")
             at--;
-        messages.splice(at, 0, ...ready.map((u) => ({ role: "user", content: userBlocks(u) })));
+        messages.splice(at, 0, ...ready.map(absorbableMessage));
     };
     /** (runId, callId) → 该调用的 tool_result 事件（同一调用只取第一个）。 */
     const results = new Map();
@@ -488,6 +526,10 @@ export function buildModelRequest(input) {
         if (!results.has(k))
             results.set(k, e.payload);
     }
+    // System texts naming a builtin: a request whose tools were recorded before the tool rename
+    // renders the frozen pre-rename wording, so it rebuilds exactly (tool naming spec §10)
+    const legacyNames = usesLegacyToolNames(input.tools ?? []);
+    const skillTexts = legacyNames ? LEGACY_SKILL_TEXTS : SKILL_TEXTS;
     // 技能目录（Ruling M17）：第一份快照进 system；之后的每份在所在位置追加变更提醒（相对上一份快照）。
     const skillSnaps = skillsCatalogEvents(events);
     const systemSkills = systemSkillsCatalog(events);
@@ -500,37 +542,52 @@ export function buildModelRequest(input) {
             role: "user",
             content: [{ type: "text", text: summaryText(summary.payload.text) }],
         });
+        // run context spec §5: snapshots covered by the summary are not rendered; the context in
+        // effect at the summary's boundary follows it whole
+        if (runContextEvents(events).some((e) => e.seq <= after)) {
+            messages.push({
+                role: "system",
+                content: runContextFullText(currentRunContext(events, after)),
+            });
+        }
+        // environments spec §13.1: the instance's directories told before the boundary follow the
+        // summary again (the model keeps using the real paths)
+        const paths = environmentPathsAt(events, after);
+        if (paths) {
+            messages.push({ role: "system", content: environmentPathsText(paths.payload.roots) });
+        }
         // 被摘要覆盖的变更提醒不再发送：摘要时生效的目录与 system 里的不同 → 紧随摘要补上完整的当前目录
         const covered = skillSnaps.filter((e) => e.seq <= after).at(-1);
         // (phase B: plus the current pinned skills and tool-name map when they differ from system's)
         if (covered && covered !== systemSkills) {
-            const text = snapshotCurrentText(systemSkills?.payload, covered.payload);
+            const text = snapshotCurrentText(systemSkills?.payload, covered.payload, skillTexts);
             if (text !== "")
                 messages.push({ role: "system", content: text });
         }
         // phase D: the skills a person invoked in the summarised range, by name (from the log only)
-        const invoked = invokedSkillsText(invokedSkillNames(events, after));
+        const invoked = invokedSkillsText(invokedSkillNames(events, after), skillTexts);
         if (invoked !== "")
             messages.push({ role: "system", content: invoked });
     }
     for (const [i, e] of events.entries()) {
         if (e.seq <= after)
             continue;
+        if (isAbsorbable(e)) {
+            switch (absorbed === undefined ? "inline" : placement(i, e.seq)) {
+                case "inline":
+                    // seq 更小的延后事件被同一次或更早的调用吸收：先放它们，保持发送顺序。
+                    flush(e.seq - 1);
+                    messages.push(absorbableMessage(e));
+                    break;
+                case "deferred":
+                    deferred.push(e);
+                    break;
+                default:
+                    break;
+            }
+            continue;
+        }
         switch (e.type) {
-            case "user_message":
-                switch (absorbed === undefined ? "inline" : placement(i, e.seq)) {
-                    case "inline":
-                        // seq 更小的延后消息被同一次或更早的调用吸收：先放它们，保持用户消息的发送顺序。
-                        flush(e.seq - 1);
-                        messages.push({ role: "user", content: userBlocks(e) });
-                        break;
-                    case "deferred":
-                        deferred.push(e);
-                        break;
-                    default:
-                        break;
-                }
-                break;
             case "model_call":
                 emitRaced(e.payload.request.toSeq);
                 if (absorbed !== undefined)
@@ -562,6 +619,21 @@ export function buildModelRequest(input) {
                 messages.push({ role: "system", content: e.payload.text });
                 reminderSeqs.push(e.seq);
                 break;
+            // the tool set changed since the previous request (tool naming spec §9.1); one covered by
+            // the summary is dropped: the request's tool list is current anyway
+            case "tools_changed":
+                messages.push({ role: "system", content: toolsChangedText(e.payload) });
+                break;
+            // who the agent is and the facts of the day (run context spec §4): the first snapshot whole,
+            // a later one as the changes against the fold before it
+            case "run_context":
+                messages.push({ role: "system", content: runContextText(events, e) });
+                break;
+            // the instance's directories (environments spec §13.1): logged during a step's tool call,
+            // so rendered after that step's tool results
+            case "environment_paths":
+                messages.push({ role: "system", content: environmentPathsText(e.payload.roots) });
+                break;
             // hook_denied is not model-visible: the model sees only the denied tool call's tool_result
             // (and nothing for a denied model request), so request building skips it
             case "hook_denied":
@@ -588,7 +660,7 @@ export function buildModelRequest(input) {
                 break;
             case "skills_catalog":
                 if (e !== systemSkills) {
-                    const text = snapshotChangeText(prevSnapshot.get(e.seq), e.payload);
+                    const text = snapshotChangeText(prevSnapshot.get(e.seq), e.payload, skillTexts);
                     if (text !== "")
                         messages.push({ role: "system", content: text });
                 }
@@ -608,7 +680,9 @@ export function buildModelRequest(input) {
         : `${BEHAVIOR_RULES}\n\n${agent.instructions}`;
     const system = [
         {
-            text: systemSkills ? `${base}\n\n${snapshotSystemText(systemSkills.payload)}` : base,
+            text: systemSkills
+                ? `${base}\n\n${snapshotSystemText(systemSkills.payload, skillTexts)}`
+                : base,
             cache: true,
         },
     ];
@@ -622,7 +696,10 @@ export function buildModelRequest(input) {
         tools = [...sorted.filter((t) => isAlwaysLoaded(t.key)), ...loaded];
         if (deferred.length > 0) {
             catalog = deferred;
-            system.push({ text: catalogText(deferred), cache: true });
+            system.push({
+                text: catalogText(deferred, legacyNames ? LEGACY_CATALOG_HEADER : undefined),
+                cache: true,
+            });
         }
     }
     const request = {
@@ -664,7 +741,7 @@ export function buildModelRequest(input) {
     return { request, meta, mediaTokens };
 }
 /**
- * 日志里 `tool_search` 加载过的工具 key（全部 `tool_result.loadedTools` 的并集，按首次出现顺序）。
+ * 日志里 `ToolSearch` 加载过的工具 key（全部 `tool_result.loadedTools` 的并集，按首次出现顺序）。
  * 不看压缩摘要的边界：加载过的工具在摘要之后仍保持加载（模型可能凭摘要继续使用它们，且已发送的工具列表只追加）。
  */
 export function loadedToolKeys(events) {

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

@@ -6,6 +6,9 @@
  * 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).
+ * changed the Task / Agent line, sub-agents spec §16.5; the tool-naming change shortened it to the
+ * Claude Code names, spec 2026-10-29 §6; background Bash made TaskOutput and TaskStop available,
+ * spec 2026-11-05 §4.4; WebFetch and WebSearch joined the same-name list with the web tools;
+ * SendMessage joined it when it replaced `Agent` with `resume`, agent map spec §4.2).
  */
 export declare const CLAUDE_CODE_TOOL_MAP: string;

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

@@ -6,19 +6,20 @@
  * 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).
+ * changed the Task / Agent line, sub-agents spec §16.5; the tool-naming change shortened it to the
+ * Claude Code names, spec 2026-10-29 §6; background Bash made TaskOutput and TaskStop available,
+ * spec 2026-11-05 §4.4; WebFetch and WebSearch joined the same-name list with the web tools;
+ * SendMessage joined it when it replaced `Agent` with `resume`, agent map spec §4.2).
  */
 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",
+    "Some skills in this conversation were written for Claude Code. Its tools Bash, Read, Write, Edit,",
+    "Glob, Grep, Skill, AskUserQuestion, ToolSearch, Agent, SendMessage, WebFetch and WebSearch have the same names here, when they are",
+    "in your tools. For the others:",
+    "- MultiEdit -> several Edit calls",
+    "- TodoWrite -> plugin__todo__write when it is in your tools; otherwise keep the task list in your replies",
+    "- Task -> Agent; model names haiku / sonnet / opus -> fast / standard / capable",
+    "- TaskOutput -> TaskOutput, TaskStop -> TaskStop",
+    "- Any other tool a skill names (for example 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.",
+    "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>@<version-id>/... after Skill has copied that skill into the sandbox.",
 ].join("\n");

package/dist/runtime/context/compaction.js

@@ -1,4 +1,8 @@
+import { renderBackgroundFinished } from "../../background/render.js";
+import { renderSubagentDelivery } from "../subagents/render.js";
 import { latestSummary } from "./build.js";
+import { senderTranscriptLabel } from "./run-context.js";
+import { toolsChangedText } from "./tool-changes.js";
 /** 压缩请求的标记：放在 system 中，便于识别（model-fake 据此返回摘要）。 */
 export const COMPACTION_MARKER = "CAPYBARA_COMPACTION";
 /** 压缩请求的输出上限。 */
@@ -103,7 +107,13 @@ function transcriptLine(e) {
     switch (e.type) {
         case "user_message": {
             const text = renderBlocks(e.payload.content);
-            return text ? `User: ${text}` : null;
+            if (!text)
+                return null;
+            // run context spec §5: the sender as logged (older logs have none: unchanged)
+            const sender = e.payload.sender;
+            return sender !== undefined
+                ? `User (${senderTranscriptLabel(sender)}): ${text}`
+                : `User: ${text}`;
         }
         case "assistant_message": {
             const text = renderBlocks(e.payload.content);
@@ -111,9 +121,22 @@ function transcriptLine(e) {
         }
         case "reminder":
             return `System reminder: ${e.payload.text}`;
+        // a tool set change is a system message of the request (build.ts); kept in the transcript so
+        // the summary does not carry an earlier "I have no such tool" forward as current
+        case "tools_changed":
+            return `System reminder: ${toolsChangedText(e.payload)}`;
+        // a finished background task is a system message of the request (build.ts)
+        case "background_task_finished":
+            return `System reminder: ${renderBackgroundFinished(e.payload)}`;
+        // a sub-agent's delivery is a system message of the request (build.ts)
+        case "subagent_delivery":
+            return `System reminder: ${renderSubagentDelivery(e.payload)}`;
         // phase D: a forked skill's report is user content of the request (build.ts)
         case "skill_fork_result":
             return `User: ${e.payload.text}`;
+        // environment_paths is left out too: the latest one follows the summary (build.ts)
+        // run_context is left out: its current values follow the summary anyway (build.ts), and
+        // stale names should not be summarised as current
         case "tool_result":
             return `Tool result ${e.payload.toolKey}${e.payload.isError ? " (error)" : ""}: ${e.payload.content}`;
         default: