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

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

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the sandbox sweeps 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 sandbox providers.
+ */
+/** The idle suspension sweep's old scheduler (every minute). */
+export declare const SANDBOX_SUSPEND_SCHEDULER_ID = "sandbox-suspend-idle-every-minute";
+/** The inactivity destruction sweep's old scheduler (hourly). */
+export declare const SANDBOX_DESTROY_SCHEDULER_ID = "sandbox-destroy-inactive-hourly";

package/dist/sandbox/job-ids.js

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the sandbox sweeps 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 sandbox providers.
+ */
+/** The idle suspension sweep's old scheduler (every minute). */
+export const SANDBOX_SUSPEND_SCHEDULER_ID = "sandbox-suspend-idle-every-minute";
+/** The inactivity destruction sweep's old scheduler (hourly). */
+export const SANDBOX_DESTROY_SCHEDULER_ID = "sandbox-destroy-inactive-hourly";

package/dist/sandbox/jobs.d.ts

@@ -0,0 +1,41 @@
+import type { Job, Queue } from "bullmq";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxService } from "./sandbox.service.js";
+/** 空闲休眠扫描（每分钟，跨副本每个 tick 一次）。 */
+export declare const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
+/** 不活跃销毁扫描（每小时，跨副本每个 tick 一次）。 */
+export declare const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
+/** 一次性任务：立即销毁一批对话的沙箱（成员离职、删除 agent 后投递，数据 `{ conversationIds }`）。 */
+export declare const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * The producer of {@link SANDBOX_DESTROY_FOR_JOB} on the maintenance queue (BullMQ's own job ids, as
+ * before: every enqueue is a new job, also after a batch failed all its attempts); `MaintenanceProcessor`
+ * consumes it.
+ */
+export declare class SandboxJobs {
+    private readonly queue;
+    constructor(queue: Pick<Queue, "add">);
+    /** Enqueues the destruction of these conversations' sandboxes: a failed batch is retried whole (destroying one already destroyed does nothing). */
+    destroy(conversationIds: string[]): Promise<void>;
+}
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyFor` one by one; a failure is warned
+ * and fails the job (the whole batch is retried) after the others were destroyed.
+ */
+export declare function runSandboxDestroyFor(sandbox: Pick<SandboxService, "destroyFor">, log: Pick<KernelLogger, "warn">, job: Pick<Job, "data">): Promise<void>;
+/**
+ * The sandbox sweeps (exactly once per tick across replicas): every minute the idle and overdue
+ * running sandboxes are suspended, every hour the inactive ones and those of deleted orgs or
+ * conversations are destroyed. Both do nothing without a sandbox provider. They replace the
+ * maintenance schedulers `sandbox-suspend-idle-every-minute` and `sandbox-destroy-inactive-hourly`
+ * (retired at worker start).
+ */
+export declare class SandboxSweepJobs {
+    private readonly sandbox;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(sandbox: Pick<SandboxService, "suspendIdle" | "destroyInactive">, lockService: LockService, log: KernelLogger);
+    suspendIdle(): Promise<void>;
+    destroyInactive(): Promise<void>;
+}

package/dist/sandbox/jobs.js

@@ -0,0 +1,113 @@
+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 { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { SandboxService } from "./sandbox.service.js";
+/** 空闲休眠扫描（每分钟，跨副本每个 tick 一次）。 */
+export const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
+/** 不活跃销毁扫描（每小时，跨副本每个 tick 一次）。 */
+export const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
+/** 一次性任务：立即销毁一批对话的沙箱（成员离职、删除 agent 后投递，数据 `{ conversationIds }`）。 */
+export const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * The producer of {@link SANDBOX_DESTROY_FOR_JOB} on the maintenance queue (BullMQ's own job ids, as
+ * before: every enqueue is a new job, also after a batch failed all its attempts); `MaintenanceProcessor`
+ * consumes it.
+ */
+let SandboxJobs = class SandboxJobs {
+    queue;
+    constructor(queue) {
+        this.queue = queue;
+    }
+    /** Enqueues the destruction of these conversations' sandboxes: a failed batch is retried whole (destroying one already destroyed does nothing). */
+    async destroy(conversationIds) {
+        await this.queue.add(SANDBOX_DESTROY_FOR_JOB, { conversationIds }, {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 30_000 },
+            removeOnComplete: true,
+            removeOnFail: 100,
+        });
+    }
+};
+SandboxJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+], SandboxJobs);
+export { SandboxJobs };
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyFor` one by one; a failure is warned
+ * and fails the job (the whole batch is retried) after the others were destroyed.
+ */
+export async function runSandboxDestroyFor(sandbox, log, job) {
+    const ids = job.data.conversationIds;
+    if (!Array.isArray(ids))
+        return;
+    let failed = 0;
+    for (const id of ids) {
+        if (typeof id !== "string")
+            continue;
+        try {
+            await sandbox.destroyFor(id);
+        }
+        catch (err) {
+            failed++;
+            log.warn("cannot destroy sandbox of an offboarded member; will retry", {
+                conversationId: id,
+                err,
+            });
+        }
+    }
+    if (failed > 0)
+        throw new Error(`${failed} of ${ids.length} sandboxes could not be destroyed`);
+}
+/**
+ * The sandbox sweeps (exactly once per tick across replicas): every minute the idle and overdue
+ * running sandboxes are suspended, every hour the inactive ones and those of deleted orgs or
+ * conversations are destroyed. Both do nothing without a sandbox provider. They replace the
+ * maintenance schedulers `sandbox-suspend-idle-every-minute` and `sandbox-destroy-inactive-hourly`
+ * (retired at worker start).
+ */
+let SandboxSweepJobs = class SandboxSweepJobs {
+    sandbox;
+    lockService;
+    log;
+    constructor(sandbox, lockService, log) {
+        this.sandbox = sandbox;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async suspendIdle() {
+        const n = await this.sandbox.suspendIdle(new Date());
+        if (n > 0)
+            this.log.info("idle sandboxes suspended", { count: n });
+    }
+    async destroyInactive() {
+        const n = await this.sandbox.destroyInactive(new Date());
+        if (n > 0)
+            this.log.info("inactive sandboxes destroyed", { count: n });
+    }
+};
+__decorate([
+    LockedCron("* * * * *", { name: SANDBOX_SUSPEND_JOB })
+], SandboxSweepJobs.prototype, "suspendIdle", null);
+__decorate([
+    LockedCron("0 * * * *", { name: SANDBOX_DESTROY_JOB })
+], SandboxSweepJobs.prototype, "destroyInactive", null);
+SandboxSweepJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(SandboxService)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], SandboxSweepJobs);
+export { SandboxSweepJobs };

package/dist/sandbox/leases.d.ts

@@ -1,6 +1,7 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { ApiError } from "../errors.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
 /**
  * Shared and exclusive sandbox leases (sub-agents spec §10.3): the Redis protocol that lets several
  * holders use one conversation's running sandbox concurrently (shared leases: commands, file reads
@@ -19,9 +20,11 @@ import { ApiError } from "../errors.js";
  * - `capk:sandbox-path:<conv>:<sha256hex(path)>`: a short per-path lease around the kernel's own
  *   read-modify-write of one file.
  *
- * Every script purges expired shared leases first, and every key carries a TTL. A holder renews
- * every TTL / 3 (a timer for a lease this process holds) and treats "no successful renewal for
- * 2/3 TTL" as lost: its `signal` aborts with {@link SandboxLockLostError}.
+ * The first three keys are a {@link LockService} shared lease (`tryShared` / `tryExclusive`,
+ * infra/lock/shared-lease.ts); the holder records and the path leases are this file's. Every key
+ * carries a TTL. A holder renews every TTL / 3 (LockService's watchdog) and loses the lease at
+ * the renewal deadline (send time of the last successful renewal + 2/3 TTL): its `signal` aborts
+ * with {@link SandboxLockLostError}.
  */
 /** Prefix of the lock key `capk:sandbox:<conversationId>`. */
 export declare const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
@@ -67,30 +70,41 @@ export interface SandboxLease {
     /** exclusive → shared in one Lua step (same token, same signal); throws if not exclusive. */
     downgrade(): Promise<SandboxLease>;
 }
-export interface SandboxLeasesDeps {
-    redis: Redis;
-    log: Pick<Logger, "warn">;
-    /** Lease TTL (ms), default {@link SANDBOX_LOCK_TTL_MS}. */
-    ttlMs?: number;
-    /** Poll interval while waiting (ms, jittered up to 2×), default 100. */
-    pollMs?: number;
-    /** Path lease TTL (ms), default 30 s; tests make it shorter. */
-    pathTtlMs?: number;
-}
 /** A path lease this process holds. */
 export interface SandboxPathLease {
-    /** Aborts with {@link SandboxLockLostError} when a renewal finds the lease gone. */
+    /** Aborts with {@link SandboxLockLostError} when the lease is lost. */
     readonly signal: AbortSignal;
     release(): Promise<void>;
 }
-/** The lease protocol; no state in process beyond the leases this process holds. */
+/** The timings of {@link SandboxLeases} (each defaults as documented). */
+export interface SandboxLeaseTimings {
+    /** Lease TTL (ms), default {@link SANDBOX_LOCK_TTL_MS}. */
+    ttlMs: number;
+    /** Poll interval while waiting (ms, jittered up to 2×), default 100. */
+    pollMs: number;
+    /** Path lease TTL (ms), default {@link PATH_LEASE_TTL_MS}. */
+    pathTtlMs: number;
+}
+/** Optional provider: {@link SandboxLeaseTimings} that replace some defaults (tests make them shorter). */
+export declare const SANDBOX_LEASE_TIMINGS: unique symbol;
+/**
+ * The lease protocol over {@link LockService}'s shared leases; no state in process beyond the
+ * leases this process holds.
+ */
 export declare class SandboxLeases {
+    private readonly locks;
+    /** The holder records and the legacy busy marker (scripts of this file). */
     private readonly redis;
     private readonly log;
-    private readonly ttlMs;
-    private readonly pollMs;
-    private readonly pathTtlMs;
-    constructor(d: SandboxLeasesDeps);
+    /** Lease TTL (ms). */
+    readonly ttlMs: number;
+    /** Poll interval while waiting (ms, jittered up to 2×). */
+    readonly pollMs: number;
+    /** Path lease TTL (ms). */
+    readonly pathTtlMs: number;
+    constructor(locks: LockService, 
+    /** The holder records and the legacy busy marker (scripts of this file). */
+    redis: Pick<Redis, "eval" | "get">, log: Pick<KernelLogger, "warn">, timings?: Partial<SandboxLeaseTimings>);
     /**
      * TTL of an intent (ms): 4 × the poll interval (a jittered wait is up to 2 × the interval plus
      * round trips), at least {@link INTENT_TTL_FLOOR_MS} so event-loop lag cannot let it lapse.
@@ -152,18 +166,12 @@ export declare class SandboxLeases {
     }>;
     /**
      * A short lease on one path of the sandbox (the kernel's own read-modify-write of a file); waits
-     * up to `capMs`, then throws {@link SandboxPathBusyError}. Renewed while held; a renewal that
-     * finds it gone warns and aborts its `signal`.
+     * up to `capMs`, then throws {@link SandboxPathBusyError}. A {@link LockService.hold} lease
+     * (renewed every TTL / 3): when it is lost its `signal` aborts.
      */
     pathLease(conv: string, path: string, signal: AbortSignal, capMs: number): Promise<SandboxPathLease>;
-    /**
-     * Wraps a just-acquired lease: renews every TTL / 3 and remembers the last successful renewal;
-     * the lease is lost when a renewal reports it gone or none succeeded for 2/3 TTL (leaving margin
-     * so the abort takes effect before the key expires).
-     */
-    private hold;
-    private lose;
-    private renew;
-    /** A lease view of `s` as `kind`; a view stops working once the lease changes kind. */
+    /** A sandbox lease over a held {@link SharedLeaseHandle}, as its current kind. */
+    private held;
+    /** A lease view of `h` as `kind`; a view stops working once the lease changes kind. */
     private view;
 }