@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/roles/worker-role.js

@@ -0,0 +1,144 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { ChannelsProcessor } from "../channels/channels.module.js";
+import { ChannelOutbound } from "../channels/outbound.js";
+import { TitleQueue } from "../conversations/titles.js";
+import { EvalsProcessor } from "../evals/evals.module.js";
+import { EvalWorker } from "../evals/worker.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockedIntervalScheduler } from "../infra/schedule/locked-interval.js";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MaintenanceProcessor } from "../runtime/maintenance.js";
+import { RunsProcessor, SubagentRunsProcessor, TitleProcessor, UsageReportProcessor, } from "../runtime/run-processors.js";
+import { RunWorker } from "../runtime/run-worker.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+/**
+ * The worker role's parts, driven by `KernelLifecycle` at fixed points of its start order and stop
+ * phases (so they stay ordered after the extension load and before the extension host closes): the
+ * queue consumers (runs, sub-agent runs, evals, maintenance, channel deliveries, `usage.report`,
+ * titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
+ * `WorkerModule`, so a process without the worker role has none of them.
+ */
+let WorkerRole = class WorkerRole {
+    log;
+    intervals;
+    scheduledRuns;
+    runWorker;
+    evalWorker;
+    usageReport;
+    titles;
+    channelOutbound;
+    runsProcessor;
+    subagentRunsProcessor;
+    usageProcessor;
+    titleProcessor;
+    channelsProcessor;
+    evalsProcessor;
+    maintenanceProcessor;
+    /** The startup config (the roles). */
+    config;
+    /** The run worker was started: the runs phase drains it. */
+    runsStarted = false;
+    /** The eval worker was started: the runs phase drains it. */
+    evalsStarted = false;
+    constructor(config, log, intervals, scheduledRuns, runWorker, evalWorker, usageReport, titles, channelOutbound, runsProcessor, subagentRunsProcessor, usageProcessor, titleProcessor, channelsProcessor, evalsProcessor, maintenanceProcessor) {
+        this.log = log;
+        this.intervals = intervals;
+        this.scheduledRuns = scheduledRuns;
+        this.runWorker = runWorker;
+        this.evalWorker = evalWorker;
+        this.usageReport = usageReport;
+        this.titles = titles;
+        this.channelOutbound = channelOutbound;
+        this.runsProcessor = runsProcessor;
+        this.subagentRunsProcessor = subagentRunsProcessor;
+        this.usageProcessor = usageProcessor;
+        this.titleProcessor = titleProcessor;
+        this.channelsProcessor = channelsProcessor;
+        this.evalsProcessor = evalsProcessor;
+        this.maintenanceProcessor = maintenanceProcessor;
+        this.config = config.get();
+    }
+    /**
+     * Starts the queue consumers (after the extension load), then opens the schedules' start gate:
+     * the cron and interval timers were armed at application bootstrap, but every tick before this
+     * point skipped (decision R21 of the Nest kernel spec); the `@LockedInterval({ runOnStart })`
+     * jobs run now, in the background (once across replicas starting together). `checkpoint` throws
+     * when a stop began meanwhile.
+     */
+    async start(checkpoint) {
+        // both run queues' @Processor workers (built with the run config, never autorun)
+        this.runWorker.start([this.runsProcessor.worker, this.subagentRunsProcessor.worker]);
+        this.runsStarted = true;
+        this.evalWorker.start(this.evalsProcessor.worker);
+        this.evalsStarted = true;
+        // The maintenance queue: remove the retired job schedulers (idempotent, harmless when several
+        // replicas do it), then start its one consumer. A failure is only logged and does not stop the
+        // start (like the workers' connection errors): any worker replica removes them on its next start.
+        try {
+            await this.maintenanceProcessor.removeRetiredSchedulers();
+        }
+        catch (err) {
+            this.log.error("cannot register maintenance job schedulers", { err });
+        }
+        checkpoint();
+        this.maintenanceProcessor.start();
+        this.channelOutbound.startWorker(this.channelsProcessor.worker);
+        this.usageReport.startWorker(this.usageProcessor.worker);
+        this.titles.startWorker(this.titleProcessor.worker);
+        if (!this.config.roles.includes("gateway")) {
+            this.log.info("this process runs the worker role without gateway; channel long connections are held only by processes with the gateway role", { roles: this.config.roles });
+        }
+        // The gate opens: from here on ticks run; the runOnStart jobs run once now, in the background
+        this.scheduledRuns.open();
+        this.intervals.runStartJobs();
+    }
+    /**
+     * Closes the start gate and stops the schedulers (no new tick; the runs in progress get the stop
+     * signal) and returns the wait for those runs, at most `budgetMs`.
+     */
+    stopSchedules(budgetMs) {
+        return this.scheduledRuns.stop(budgetMs);
+    }
+    /** The runs phase: this process's runs stop at their next step boundary (undefined: never started). */
+    drainRuns(budgetMs) {
+        return this.runsStarted ? this.runWorker.close(budgetMs) : undefined;
+    }
+    /** The eval cases in progress stop (undefined: never started). */
+    drainEvals(budgetMs) {
+        return this.evalsStarted ? this.evalWorker.close(budgetMs) : undefined;
+    }
+    /** Closes the maintenance queue's worker. */
+    closeMaintenance() {
+        return this.maintenanceProcessor.worker.close();
+    }
+};
+WorkerRole = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelConfigService)),
+    __param(1, Inject(KERNEL_LOGGER)),
+    __param(2, Inject(LockedIntervalScheduler)),
+    __param(3, Inject(ScheduledRuns)),
+    __param(4, Inject(RunWorker)),
+    __param(5, Inject(EvalWorker)),
+    __param(6, Inject(UsageReporter)),
+    __param(7, Inject(TitleQueue)),
+    __param(8, Inject(ChannelOutbound)),
+    __param(9, Inject(RunsProcessor)),
+    __param(10, Inject(SubagentRunsProcessor)),
+    __param(11, Inject(UsageReportProcessor)),
+    __param(12, Inject(TitleProcessor)),
+    __param(13, Inject(ChannelsProcessor)),
+    __param(14, Inject(EvalsProcessor)),
+    __param(15, Inject(MaintenanceProcessor))
+], WorkerRole);
+export { WorkerRole };

package/dist/roles/worker.module.d.ts

@@ -0,0 +1,14 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { KernelConfig } from "../config/schema.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+export declare class WorkerModule {
+    static forRoot(config: KernelConfig): DynamicModule;
+}

package/dist/roles/worker.module.js

@@ -0,0 +1,90 @@
+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 WorkerModule_1;
+import { Module } from "@nestjs/common";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { CatalogJobs } from "../catalog/jobs.js";
+import { ChannelsModule, ChannelWorkersModule } from "../channels/channels.module.js";
+import { GatewayCheckJob } from "../channels/supervisor.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { AttachmentCleanupJob } from "../conversations/attachments.service.js";
+import { TitlesModule } from "../conversations/titles.js";
+import { EvalWorkersModule } from "../evals/evals.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { PluginsReconcileJob } from "../extensions/lifecycle.js";
+import { KernelScheduleModule } from "../infra/schedule/schedule.module.js";
+import { DirectoryScanJob } from "../orgs/directory-sync.js";
+import { OffboardSweepJob } from "../orgs/offboarding.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { MaintenanceModule } from "../runtime/maintenance.js";
+import { RuntimeWorkersModule } from "../runtime/run-processors.js";
+import { RuntimeModule } from "../runtime/runtime.module.js";
+import { UsageReportModule, UsageSweepJob } from "../runtime/usage-report.js";
+import { WaitSweepJob } from "../runtime/waits.js";
+import { SandboxSweepJobs } from "../sandbox/jobs.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { StoragePurgeJob } from "../storage/purge.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ToolJobs } from "../tools/jobs.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { WorkerRole } from "./worker-role.js";
+/**
+ * The worker role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
+ * `worker`: the cron scheduler and the `@LockedInterval` scheduler (`KernelScheduleModule`, the one
+ * place `ScheduleModule.forRoot` is imported), every fixed-period job (`@LockedCron` /
+ * `@LockedInterval`, each once per tick across replicas), every queue consumer (`@Processor`: runs,
+ * sub-agent runs, `usage.report`, titles, evals, maintenance, channel deliveries) and
+ * {@link WorkerRole}, which `KernelLifecycle` drives. A process without the worker role runs no cron
+ * and no BullMQ worker (the queues' producers exist on every role).
+ */
+let WorkerModule = WorkerModule_1 = class WorkerModule {
+    static forRoot(config) {
+        return {
+            module: WorkerModule_1,
+            imports: [
+                KernelScheduleModule,
+                // the queue consumers (their worker options come from the startup config)
+                RuntimeWorkersModule.forRoot(config),
+                EvalWorkersModule.forRoot(config),
+                ChannelWorkersModule.forRoot(config),
+                MaintenanceModule,
+                // the domains the fixed-period jobs call
+                RuntimeModule,
+                UsageReportModule,
+                TitlesModule,
+                AttachmentsModule,
+                StorageModule,
+                SandboxModule,
+                ToolsModule,
+                CatalogModule,
+                OrgsModule,
+                ExtensionsModule,
+                ChannelsModule,
+            ],
+            providers: [
+                WaitSweepJob,
+                UsageSweepJob,
+                AttachmentCleanupJob,
+                StoragePurgeJob,
+                SandboxSweepJobs,
+                ToolJobs,
+                CatalogJobs,
+                DirectoryScanJob,
+                OffboardSweepJob,
+                PluginsReconcileJob,
+                GatewayCheckJob,
+                WorkerRole,
+            ],
+            exports: [WorkerRole],
+        };
+    }
+};
+WorkerModule = WorkerModule_1 = __decorate([
+    Module({})
+    // biome-ignore lint/complexity/noStaticOnlyClass: a Nest dynamic module
+], WorkerModule);
+export { WorkerModule };

package/dist/runtime/abort.js

@@ -1,3 +1,14 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { KERNEL_BUS, REDIS } from "../infra/tokens.js";
 /** 中止广播的内核 bus 主题。 */
 export const RUN_ABORT_TOPIC = "run.abort";
 /** 中止标记的保留时长（秒）。 */
@@ -15,7 +26,7 @@ const parseStored = (stored) => {
  * 跨副本中止（spec 4.3「中止信号经 Redis 广播」）：`request` 先写标记键再广播；
  * `watch` 先订阅、再检查一次标记键，订阅之前发出的中止也不会丢。
  */
-export class RunAbort {
+let RunAbort = class RunAbort {
     redis;
     bus;
     constructor(redis, bus) {
@@ -68,4 +79,10 @@ export class RunAbort {
         }
         return unsubscribe;
     }
-}
+};
+RunAbort = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KERNEL_BUS))
+], RunAbort);
+export { RunAbort };

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

@@ -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;
@@ -75,8 +75,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,7 +224,7 @@ 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 里的
  *   不同，紧随摘要补一条完整的当前目录；
@@ -245,7 +245,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,8 @@
 import { createHash } from "node:crypto";
 import { MEDIA_LIMITS, } from "@capybara-hq/plugin-sdk";
 import { catalogText, isAlwaysLoaded } from "../../tools/builtins/tool-search.js";
-import { invokedSkillNames, invokedSkillsText, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
+import { LEGACY_CATALOG_HEADER, LEGACY_SKILL_TEXTS, usesLegacyToolNames } from "./legacy-text.js";
+import { invokedSkillNames, invokedSkillsText, SKILL_TEXTS, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
 /**
  * 平台行为规范（模型可见，英文）。短而通用（spec 6 原则 5）；不放时间戳、会话 ID 等会变化的内容，
  * 保证同一 agent 版本在所有会话中 system 前缀一致、可命中提示词缓存。改动它会让所有缓存失效。
@@ -322,7 +323,7 @@ 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 里的
  *   不同，紧随摘要补一条完整的当前目录；
@@ -488,6 +489,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);
@@ -504,12 +509,12 @@ export function buildModelRequest(input) {
         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 });
     }
@@ -588,7 +593,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 +613,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 +629,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 +674,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,7 @@
  * 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).
  */
 export declare const CLAUDE_CODE_TOOL_MAP: string;