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

package/dist/runtime/conversation-lock.js

@@ -1,97 +1,87 @@
+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 { LockService } from "../infra/lock/lock.service.js";
 /** 会话运行锁的默认 TTL（毫秒）：持有方每 `ttlMs / 3` 续租一次。 */
 export const CONVERSATION_LOCK_TTL_MS = 30_000;
 /** 会话运行锁的键前缀。 */
 const RUN_LOCK_PREFIX = "capk:conv-run:";
-const RENEW = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
-end
-return 0
-`;
-const RELEASE = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('DEL', KEYS[1])
-end
-return 0
-`;
 /**
- * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
- * 带 TTL；持有期间由本进程的定时器每 `ttlMs / 3` 续租（本进程持有的锁的续租，允许的进程内定时器）。
- * 持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ * A per-conversation lease on {@link LockService.hold}: key `<prefix><conversationId>`, value the
+ * holder's run id (other replicas read it with {@link holder}), renewed every TTL/3 by the lock
+ * service while held; a crashed holder's key expires within the TTL and another replica can take
+ * it. Built by {@link ConversationLock} (the run lock) and its {@link ConversationLock.scoped}
+ * views (the same lock for another purpose, e.g. the channel delivery `capk:channel-deliver:`).
+ * A loss is logged once, by the lock service (`lock lost`, with the key).
  */
-export class ConversationLock {
-    redis;
-    log;
+export class ConversationLeases {
+    locks;
     keyPrefix;
-    /** `keyPrefix`：同样语义、按会话互斥的其他用途用别的前缀（如渠道出站投递 `capk:channel-deliver:`）。 */
-    constructor(redis, log, keyPrefix = RUN_LOCK_PREFIX) {
-        this.redis = redis;
-        this.log = log;
+    constructor(locks, keyPrefix) {
+        this.locks = locks;
         this.keyPrefix = keyPrefix;
     }
     lockKey(conversationId) {
         return `${this.keyPrefix}${conversationId}`;
     }
     async acquire(conversationId, runId, ttlMs = CONVERSATION_LOCK_TTL_MS) {
-        const key = this.lockKey(conversationId);
-        const ok = await this.redis.set(key, runId, "PX", ttlMs, "NX");
-        if (ok !== "OK")
+        const held = await this.locks.hold(this.lockKey(conversationId), runId, ttlMs);
+        if (!held)
             return null;
-        const redis = this.redis;
-        const log = this.log;
-        let lost = false;
-        let timer;
-        const lostCallbacks = [];
-        const stop = () => {
-            clearInterval(timer);
-            timer = undefined;
-        };
-        const lease = {
-            conversationId,
-            runId,
-            get lost() {
-                return lost;
-            },
-            async renew() {
-                if (lost)
-                    return false;
-                const r = Number(await redis.eval(RENEW, 1, key, runId, ttlMs));
-                if (r !== 1) {
-                    lost = true;
-                    stop();
-                    log?.warn("conversation run lock lost", { conversationId, runId });
-                    for (const cb of lostCallbacks.splice(0))
-                        cb();
-                }
-                return r === 1;
-            },
-            async release() {
-                stop();
-                await redis.eval(RELEASE, 1, key, runId);
-            },
-            abandon: stop,
-            onLost(cb) {
-                if (lost)
-                    cb();
-                else
-                    lostCallbacks.push(cb);
-            },
-        };
-        timer = setInterval(() => {
-            lease.renew().catch((err) => log?.warn("conversation run lock renew failed", { err }));
-        }, Math.max(1, Math.floor(ttlMs / 3)));
-        timer.unref();
-        return lease;
+        return toLease(held, conversationId, runId);
     }
     /**
      * 释放某个运行持有的锁（只在仍由该 runId 持有时删除），不需要 Lease：用于 BullMQ 已判定任务失败
      * （例如持有者崩溃、stalled 次数超限）后清理死去持有者留下的锁，不必等 TTL 过期。
      */
     async releaseFor(conversationId, runId) {
-        await this.redis.eval(RELEASE, 1, this.lockKey(conversationId), runId);
+        await this.locks.releaseIf(this.lockKey(conversationId), runId);
     }
     /** 当前持有者的 runId；无人持有 → null。 */
     holder(conversationId) {
-        return this.redis.get(this.lockKey(conversationId));
+        return this.locks.holderOf(this.lockKey(conversationId));
     }
 }
+function toLease(held, conversationId, runId) {
+    return {
+        conversationId,
+        runId,
+        get lost() {
+            return held.lost.aborted;
+        },
+        renew: () => held.renew(),
+        release: () => held.release(),
+        abandon: () => held.abandon(),
+        onLost(cb) {
+            if (held.lost.aborted)
+                cb();
+            else
+                held.lost.addEventListener("abort", () => cb(), { once: true });
+        },
+    };
+}
+/**
+ * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
+ * 带 TTL，由 {@link LockService} 每 TTL/3 续租。持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ */
+let ConversationLock = class ConversationLock extends ConversationLeases {
+    constructor(locks) {
+        super(locks, RUN_LOCK_PREFIX);
+    }
+    /** The same per-conversation lease under another key prefix (another purpose). */
+    scoped(keyPrefix) {
+        return new ConversationLeases(this.locks, keyPrefix);
+    }
+};
+ConversationLock = __decorate([
+    Injectable(),
+    __param(0, Inject(LockService))
+], ConversationLock);
+export { ConversationLock };

package/dist/runtime/hook-calls.d.ts

@@ -1,9 +1,9 @@
 import type { AvailableHook, HookModelRequest, HookParentScope, HookPayloads, HookScope, Logger, ModelRequest } from "@capybara-hq/plugin-sdk";
 import type { AppendEvent, EventLog } from "../conversations/event-log.js";
 import type { EventPayload } from "../conversations/events.js";
-import type { KernelDb } from "../db/kernel-schema.js";
 import type { HookOutcome, HookRegistry } from "../extensions/hooks.js";
-import { audit } from "../identity/audit.js";
+import type { audit } from "../identity/audit.js";
+import type { StepLog } from "./step-log.js";
 /** What the runtime needs from the host's hook registry (absent in eval replays). */
 export type HookRunner = Pick<HookRegistry, "run" | "has">;
 /**
@@ -75,8 +75,8 @@ export type AuditEntry = Parameters<typeof audit>[1];
  * denial rethrows it before running the hooks again, so no second audit entry is written.
  */
 export declare function recordHookDenial(d: {
-    db: KernelDb;
     eventLog: EventLog;
+    stepLog: Pick<StepLog, "appendAudited">;
 }, at: DenialSite, mount: Extract<AvailableHook, "model.request" | "tool.preExecute">, denial: HookDenial, where: {
     step: number;
     attempt?: number;

package/dist/runtime/hook-calls.js

@@ -1,4 +1,3 @@
-import { audit } from "../identity/audit.js";
 /**
  * The scope for hook payloads, or null when hooks must not fire: no registry (eval replays omit it),
  * a conversation that is neither `chat` nor `subagent`, or missing identity fields. A sub-agent's
@@ -125,11 +124,7 @@ export async function recordHookDenial(d, at, mount, denial, where) {
     if (await d.eventLog.findByIdem(at.conversationId, at.idemKey))
         return;
     const event = hookDeniedEvent(at, mount, denial, where);
-    const written = await d.db.transaction().execute(async (t) => {
-        const out = await d.eventLog.append(at.conversationId, [event], t);
-        await audit(t, hookDeniedAudit(at, event.payload, denial));
-        return out;
-    });
+    const written = await d.stepLog.appendAudited(at.conversationId, [event], hookDeniedAudit(at, event.payload, denial));
     if (written.length > 0) {
         await d.eventLog.notify(at.conversationId, Math.max(...written.map((e) => e.seq)));
     }

package/dist/runtime/job-ids.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the runtime's fixed-period jobs had before they became
+ * `@LockedCron` jobs: an upgraded deployment still has them in Redis, so the
+ * worker removes them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker
+ * imports it without the runtime's providers.
+ */
+/** The wait sweep's old scheduler (every 10 minutes). */
+export declare const WAIT_SWEEP_SCHEDULER_ID = "wait-sweep-every-10m";
+/** The usage sweeper's old scheduler (every minute). */
+export declare const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";

package/dist/runtime/job-ids.js

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the runtime's fixed-period jobs had before they became
+ * `@LockedCron` jobs: an upgraded deployment still has them in Redis, so the
+ * worker removes them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker
+ * imports it without the runtime's providers.
+ */
+/** The wait sweep's old scheduler (every 10 minutes). */
+export const WAIT_SWEEP_SCHEDULER_ID = "wait-sweep-every-10m";
+/** The usage sweeper's old scheduler (every minute). */
+export const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";

package/dist/runtime/langgraph-loop.js

@@ -112,7 +112,7 @@ export class LangGraphLoop {
     build(ctx) {
         const timedOut = () => Date.now() >= ctx.limits.deadline;
         // 本次运行的附件字节缓存：各步共用，运行结束即丢弃（只是优化，见 MediaCache）
-        const mediaCache = new MediaCache(this.stepDeps.config().attachments.requestMediaBytes);
+        const mediaCache = new MediaCache(this.stepDeps.config.get().attachments.requestMediaBytes);
         const input = (step, absorbedUpToSeq) => ({
             orgId: ctx.orgId,
             conversationId: ctx.conversationId,

package/dist/runtime/loop.d.ts

@@ -1,4 +1,5 @@
 import type { AgentDefinition } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
 import type { ConversationEvent } from "../conversations/events.js";
 import type { StreamSink } from "./model-call.js";
 /** 一次运行交给 loop 的上下文（spec 4.4）。 */
@@ -91,3 +92,9 @@ export type LoopOutcome =
 export interface AgentLoop {
     run(ctx: LoopContext): Promise<LoopOutcome>;
 }
+/**
+ * The wait of a step whose sub-agents still run (spec §7.2): id `sa-<runId>-<step>`, expiring after
+ * the approval timeout plus one run's duration plus 10 minutes (a child may itself wait for an
+ * approval); the timeout is a safety net.
+ */
+export declare function subagentsWait(runId: string, step: number, config: Pick<KernelConfig, "tools" | "runtime">, now?: number): WaitingFor;

package/dist/runtime/loop.js

@@ -5,3 +5,17 @@
 export const subagentWaitingIdemKey = (childRunId, waitId) => `subagent_waiting:${childRunId}:${waitId}`;
 /** The id of a run's `subagents` wait in `step` (part of BullMQ job ids, so no `:`). */
 export const subagentsWaitId = (runId, step) => `sa-${runId}-${step}`;
+/**
+ * The wait of a step whose sub-agents still run (spec §7.2): id `sa-<runId>-<step>`, expiring after
+ * the approval timeout plus one run's duration plus 10 minutes (a child may itself wait for an
+ * approval); the timeout is a safety net.
+ */
+export function subagentsWait(runId, step, config, now = Date.now()) {
+    const ms = config.tools.approvalTimeoutHours * 3_600_000 + config.runtime.maxRunSeconds * 1000 + 600_000;
+    return {
+        kind: "subagents",
+        id: subagentsWaitId(runId, step),
+        expiresAt: new Date(now + ms).toISOString(),
+        step,
+    };
+}

package/dist/runtime/maintenance-queue.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The kernel maintenance queue (no `:`): wait timeouts (`wait-timeout`, see waits.ts), one-off
+ * maintenance (sandbox destruction, connector drift, directory sync); no periodic jobs any more
+ * (they are `@LockedCron` / `@LockedInterval` jobs). The queue has one Worker (started on the `worker` role only) that
+ * dispatches by job name to the registered handlers. Separate from the run queues: their handler,
+ * stalled and failure handling assume "one job = one run"; maintenance jobs are short, with no
+ * conversation lock or quota. A leaf module, so providers that add jobs (orgs/directory-sync.ts)
+ * import the name without importing the worker (which imports their scheduler ids back).
+ */
+export declare const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";

package/dist/runtime/maintenance-queue.js

@@ -0,0 +1,10 @@
+/**
+ * The kernel maintenance queue (no `:`): wait timeouts (`wait-timeout`, see waits.ts), one-off
+ * maintenance (sandbox destruction, connector drift, directory sync); no periodic jobs any more
+ * (they are `@LockedCron` / `@LockedInterval` jobs). The queue has one Worker (started on the `worker` role only) that
+ * dispatches by job name to the registered handlers. Separate from the run queues: their handler,
+ * stalled and failure handling assume "one job = one run"; maintenance jobs are short, with no
+ * conversation lock or quota. A leaf module, so providers that add jobs (orgs/directory-sync.ts)
+ * import the name without importing the worker (which imports their scheduler ids back).
+ */
+export const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";

package/dist/runtime/maintenance.d.ts

@@ -1,80 +1,51 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Job, type JobsOptions } from "bullmq";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { WorkerHost } from "@nestjs/bullmq";
+import type { Job, Queue, Worker } from "bullmq";
+import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
+import type { KernelLogger } from "../log.js";
+import { DirectorySync } from "../orgs/directory-sync.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { ToolDrift } from "../tools/drift.js";
+import { Waits } from "./waits.js";
+export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+/** The maintenance worker's concurrency (as the hand-made worker had). */
+export declare const MAINTENANCE_CONCURRENCY = 5;
 /**
- * 内核维护队列（不含 `:`）：等待超时任务（`wait-timeout`，见 waits.ts）与周期性维护（输出存档清理、
- * 工具漂移检测（见 tools/drift.ts）、等待兜底扫描（`wait-sweep`，见 waits.ts）、沙箱的空闲休眠与不活跃销毁
- * （见 sandbox/lifecycle.ts）等）。整个队列只有一个 Worker（只在 `worker` 角色上启动），
- * 按任务名分派给登记的处理函数。
- * 与运行队列分开：运行 worker 的处理函数、stalled / 失败处理都按「一个任务 = 一次运行」设计；
- * 维护任务短、无会话锁与配额。
+ * The one consumer of `cap-kernel-maintenance` (decision R11 of the Nest kernel spec): dispatches
+ * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` →
+ * {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
+ * {@link DirectorySync}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
+ * such as `sandbox-suspend-idle`) runs that job's body once ({@link ScheduledRuns.runNow}), as the
+ * maintenance handlers did when those jobs were schedulers on this queue: an operator's or a
+ * test's one-off run, not a second schedule (decision R23 of the Nest kernel spec). Any other
+ * name is warned and completes. The producers are the domains' own (same names, ids and options).
  */
-export declare const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";
-/** 输出存档清理：任务名、job scheduler id（不含 `:`）、周期与每批删除行数。 */
-export declare const OUTPUT_CLEANUP_JOB = "output-cleanup";
-export declare const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";
-export declare const OUTPUT_CLEANUP_EVERY_MS = 3600000;
-export declare const OUTPUT_CLEANUP_BATCH = 1000;
-/**
- * Periodic marketplace refresh (C26): job name and job scheduler id (no `:`), every
- * `marketplaces.refreshIntervalMinutes`. One scheduler for all replicas; the handler refreshes each
- * enabled marketplace in turn (see catalog/marketplaces.service.ts). The values keep their old
- * names: the scheduler id is stored in Redis, and renaming it would leave the old scheduler behind.
- */
-export declare const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
-export declare const MARKETPLACES_REFRESH_SCHEDULER_ID = "catalogs-refresh-every";
-/**
- * Cleanup of plugin (app bundle) import staging (T25, F-AE): job name and job scheduler id (no
- * `:`), hourly; deletes expired (24-hour) staging rows and their object storage prefixes (see
- * catalog/plugin-import.ts `PluginImport.cleanupExpired`). The values keep their old names: the
- * scheduler id is stored in Redis, so renaming it would leave the old scheduler behind.
- */
-export declare const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
-export declare const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
-export declare const PLUGIN_STAGING_CLEANUP_EVERY_MS = 3600000;
-/** 维护任务的处理函数（`token` 供 `moveToDelayed` 等使用）。 */
-export type MaintenanceHandler = (job: Job, token: string | undefined) => Promise<void>;
-/** 由其他模块登记的周期任务（如漂移检测）：scheduler id 与任务名不含 `:`，周期在登记时读取。 */
-export interface MaintenanceSchedule {
-    id: string;
-    name: string;
-    everyMs: () => number;
-}
-/**
- * 删除已过期（`expires_at < now()`）的输出存档，每批 `batch` 行，直到删完；返回删除的总行数。
- * 每批一条独立语句（不开长事务）；多个 worker 同时清理时 `SKIP LOCKED` 互不等待。
- */
-export declare function deleteExpiredOutputs(db: KernelDb, batch?: number): Promise<number>;
-export interface MaintenanceDeps {
-    db: KernelDb;
-    redisUrl: string;
-    log: Pick<Logger, "error" | "warn" | "info">;
+export declare class MaintenanceProcessor extends WorkerHost<Worker> {
+    private readonly waits;
+    private readonly sandbox;
+    private readonly drift;
+    private readonly directory;
+    private readonly scheduled;
+    private readonly log;
+    private readonly queue;
+    constructor(waits: Pick<Waits, "processTimeout">, sandbox: Pick<SandboxService, "destroyFor">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
+    /**
+     * Removes the retired job schedulers (`RETIRED_SCHEDULER_IDS`, runtime/retired-schedulers.ts): every fixed-period
+     * maintenance job is a `@LockedCron` / `@LockedInterval` now. Idempotent; called once when a
+     * worker role starts.
+     */
+    removeRetiredSchedulers(): Promise<void>;
+    process(job: Job, token?: string): Promise<void>;
+    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
+    start(): void;
+    private dispatch;
+    failed(job: Job | undefined, err: Error): void;
+    error(err: Error): void;
 }
 /**
- * 维护队列的生产方与（worker 角色上的）唯一 Worker。状态都在 Redis / PG，没有进程内定时器：
- * 周期任务用 BullMQ job scheduler（`upsertJobScheduler` 幂等，多副本重复调用只有一个 scheduler）。
+ * The maintenance queue's consumer: {@link MaintenanceProcessor}. Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by
+ * itself: the worker role (`WorkerRole`) removes the retired job schedulers and starts it after the
+ * extensions loaded.
  */
-export declare class Maintenance {
-    private readonly d;
-    private queue;
-    private queueConn;
-    private worker;
-    private workerConn;
-    private closed;
-    private readonly handlers;
-    private readonly schedules;
-    constructor(d: MaintenanceDeps);
-    /** 登记某个任务名的处理函数（构造期调用；Worker 启动前后都可）。 */
-    handle(name: string, fn: MaintenanceHandler): void;
-    /** 登记一个周期任务（构造期调用；`ensureSchedules` 时一并 upsert）。 */
-    schedule(s: MaintenanceSchedule): void;
-    /** 投递一个维护任务。 */
-    add(name: string, data: unknown, opts: JobsOptions): Promise<void>;
-    /** 登记周期任务的 job scheduler（幂等；worker 角色启动时调用）。 */
-    ensureSchedules(): Promise<void>;
-    /** 启动维护队列的 Worker（只在含 `worker` 角色的进程）。 */
-    startWorker(): void;
-    close(): Promise<void>;
-    private getQueue;
-    private process;
+export declare class MaintenanceModule {
 }