@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/sandbox/jobs.d.ts

@@ -2,32 +2,59 @@ 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 一次）。 */
+/** The idle suspension sweep (every minute, once per tick across replicas). */
 export declare const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
-/** 不活跃销毁扫描（每小时，跨副本每个 tick 一次）。 */
+/** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export declare const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
-/** 一次性任务：立即销毁一批对话的沙箱（成员离职、删除 agent 后投递，数据 `{ conversationIds }`）。 */
+/**
+ * One-off job: destroy a batch of environments now, instance and file system (environment
+ * deletion, offboarding; data `{ environmentIds }`).
+ */
 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.
+ * One-off job: start an environment over with empty files (`resetFileSystem`; data
+ * `{ environmentId }`, job id {@link resetFilesJobId}).
+ */
+export declare const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
+/**
+ * The deterministic id of an environment's reset job: a second request while one is waiting or
+ * running joins it (that reset still empties the files); once it ended, a new request is a new job.
+ */
+export declare const resetFilesJobId: (environmentId: string) => string;
+/**
+ * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
+ * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
+ * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
  */
 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>;
+    /**
+     * Enqueues the destruction of these environments: a failed batch is retried whole (destroying
+     * one already destroyed does nothing).
+     */
+    destroy(environmentIds: string[]): Promise<void>;
+    /**
+     * Enqueues the reset of an environment's files (see {@link resetFilesJobId}): retried on failure
+     * (the exclusive lease not obtained in time, the provider failing); a job that failed all its
+     * attempts is removed, so the id never blocks a later request.
+     */
+    resetFiles(environmentId: 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.
+ * The worker side of {@link SANDBOX_RESET_FILES_JOB}: `resetFileSystem` under the exclusive lease;
+ * a failure fails the job (retried).
+ */
+export declare function runSandboxResetFiles(sandbox: Pick<SandboxService, "resetFileSystem">, job: Pick<Job, "data">): Promise<void>;
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyEnvironment` 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>;
+export declare function runSandboxDestroyFor(sandbox: Pick<SandboxService, "destroyEnvironment">, 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
+ * running instances are suspended, every hour the inactive instances are destroyed (files kept)
+ * and deleted environments, or those of deleted orgs, are destroyed with their files. 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).
  */

package/dist/sandbox/jobs.js

@@ -14,31 +14,61 @@ 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 一次）。 */
+/** The idle suspension sweep (every minute, once per tick across replicas). */
 export const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
-/** 不活跃销毁扫描（每小时，跨副本每个 tick 一次）。 */
+/** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
-/** 一次性任务：立即销毁一批对话的沙箱（成员离职、删除 agent 后投递，数据 `{ conversationIds }`）。 */
+/**
+ * One-off job: destroy a batch of environments now, instance and file system (environment
+ * deletion, offboarding; data `{ environmentIds }`).
+ */
 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.
+ * One-off job: start an environment over with empty files (`resetFileSystem`; data
+ * `{ environmentId }`, job id {@link resetFilesJobId}).
+ */
+export const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
+/**
+ * The deterministic id of an environment's reset job: a second request while one is waiting or
+ * running joins it (that reset still empties the files); once it ended, a new request is a new job.
+ */
+export const resetFilesJobId = (environmentId) => `${SANDBOX_RESET_FILES_JOB}-${environmentId}`;
+/**
+ * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
+ * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
+ * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
  */
 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 }, {
+    /**
+     * Enqueues the destruction of these environments: a failed batch is retried whole (destroying
+     * one already destroyed does nothing).
+     */
+    async destroy(environmentIds) {
+        await this.queue.add(SANDBOX_DESTROY_FOR_JOB, { environmentIds }, {
             attempts: 5,
             backoff: { type: "exponential", delay: 30_000 },
             removeOnComplete: true,
             removeOnFail: 100,
         });
     }
+    /**
+     * Enqueues the reset of an environment's files (see {@link resetFilesJobId}): retried on failure
+     * (the exclusive lease not obtained in time, the provider failing); a job that failed all its
+     * attempts is removed, so the id never blocks a later request.
+     */
+    async resetFiles(environmentId) {
+        await this.queue.add(SANDBOX_RESET_FILES_JOB, { environmentId }, {
+            jobId: resetFilesJobId(environmentId),
+            attempts: 5,
+            backoff: { type: "exponential", delay: 30_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        });
+    }
 };
 SandboxJobs = __decorate([
     Injectable(),
@@ -46,11 +76,21 @@ SandboxJobs = __decorate([
 ], 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.
+ * The worker side of {@link SANDBOX_RESET_FILES_JOB}: `resetFileSystem` under the exclusive lease;
+ * a failure fails the job (retried).
+ */
+export async function runSandboxResetFiles(sandbox, job) {
+    const id = job.data.environmentId;
+    if (typeof id !== "string")
+        return;
+    await sandbox.resetFileSystem(id);
+}
+/**
+ * The worker side of {@link SANDBOX_DESTROY_FOR_JOB}: `destroyEnvironment` 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;
+    const ids = job.data.environmentIds;
     if (!Array.isArray(ids))
         return;
     let failed = 0;
@@ -58,23 +98,20 @@ export async function runSandboxDestroyFor(sandbox, log, job) {
         if (typeof id !== "string")
             continue;
         try {
-            await sandbox.destroyFor(id);
+            await sandbox.destroyEnvironment(id);
         }
         catch (err) {
             failed++;
-            log.warn("cannot destroy sandbox of an offboarded member; will retry", {
-                conversationId: id,
-                err,
-            });
+            log.warn("cannot destroy environment; will retry", { environmentId: id, err });
         }
     }
     if (failed > 0)
-        throw new Error(`${failed} of ${ids.length} sandboxes could not be destroyed`);
+        throw new Error(`${failed} of ${ids.length} environments 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
+ * running instances are suspended, every hour the inactive instances are destroyed (files kept)
+ * and deleted environments, or those of deleted orgs, are destroyed with their files. 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).
  */

package/dist/sandbox/leases.d.ts

@@ -3,21 +3,23 @@ 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
- * and writes) while lifecycle changes (create, resume, rebuild, suspend, destroy) stay alone
- * (exclusive leases). Keys, conversation = the sandbox conversation:
+ * Shared and exclusive sandbox leases (sub-agents spec §10.3; environments spec §4.2): the Redis
+ * protocol that lets several holders (every conversation bound to the environment, and their
+ * sub-agents) use one environment's running instance concurrently (shared leases: commands, file
+ * reads and writes) while lifecycle changes (create, resume, rebuild, suspend, destroy, reset) stay
+ * alone (exclusive leases). Every `sandbox@2` provider runs commands concurrently and kills by tag,
+ * so there is no single-holder mode. Keys, env = the environment id:
  *
- * - `capk:sandbox:<conv>`: the lock key kept from before (rollout, §10.8): an exclusive holder's
- *   token, or `shared` while shared leases exist. An older replica's `SET NX` therefore never gets
- *   in while shared leases live, and its token blocks new shared leases.
- * - `capk:sandbox-users:<conv>`: sorted set of shared lease tokens scored by their expiry (ms, Redis
+ * - `capk:sandbox:<env>`: the lock key: an exclusive holder's token, or `shared` while shared
+ *   leases exist.
+ * - `capk:sandbox-users:<env>`: sorted set of shared lease tokens scored by their expiry (ms, Redis
  *   server clock).
- * - `capk:sandbox-intent:<conv>`: an exclusive waiter's token (writer preference); while it exists
+ * - `capk:sandbox-intent:<env>`: an exclusive waiter's token (writer preference); while it exists
  *   no new shared lease is granted.
- * - `capk:sandbox-holders:<conv>`: hash token → expiry of holders that may have commands running
- *   (the per-holder replacement of the single busy marker `capk:sandbox-busy:<conv>`, still read).
- * - `capk:sandbox-path:<conv>:<sha256hex(path)>`: a short per-path lease around the kernel's own
+ * - `capk:sandbox-holders:<env>`: hash token → expiry of holders that may have commands running;
+ *   a record without a live lease is a crashed holder whose commands (tagged with its token) are
+ *   killed by the next acquirer.
+ * - `capk:sandbox-path:<env>:<sha256hex(path)>`: a short per-path lease around the kernel's own
  *   read-modify-write of one file.
  *
  * The first three keys are a {@link LockService} shared lease (`tryShared` / `tryExclusive`,
@@ -26,30 +28,17 @@ import type { KernelLogger } from "../log.js";
  * 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>`. */
+/** Prefix of the lock key `capk:sandbox:<environmentId>`. */
 export declare const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
 /** TTL of a lease (ms): renewed every TTL / 3 while held. */
 export declare const SANDBOX_LOCK_TTL_MS = 60000;
-/**
- * Prefix of the single "sandbox in use" marker of kernels before phase C,
- * `capk:sandbox-busy:<conversationId>`: present while such a holder ran commands. Found by an
- * exclusive acquirer, it means that holder crashed and its commands may still run.
- *
- * Holders of this kernel write it too, with the value {@link BUSY_V2}, while any holder record
- * exists (spec §10.8): this kernel ignores that value, and a replica from before phase C that
- * takes the lock after a new holder crashed sees a marker and kills everything, which is safe
- * because it only gets the lock when no shared lease is live.
- */
-export declare const SANDBOX_BUSY_PREFIX = "capk:sandbox-busy:";
-/** Value of the busy marker written by holders of this kernel (ignored by it). */
-export declare const BUSY_V2 = "v2";
-/** The sandbox of this conversation is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
+/** The environment's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
 export declare const sandboxBusy: () => ApiError;
 /** A lease was lost while held, or the record changed under it (generation mismatch). */
 export declare class SandboxLockLostError extends Error {
     /** `lock`: the lease was lost (renewal failed or none succeeded in time); `generation`: the record's fence changed. */
     readonly reason: "lock" | "generation";
-    constructor(conversationId: string, reason?: "lock" | "generation");
+    constructor(environmentId: string, reason?: "lock" | "generation");
 }
 /** Another holder kept writing the same file longer than the path lease wait (model-visible text). */
 export declare class SandboxPathBusyError extends Error {
@@ -60,7 +49,7 @@ export type LeaseKind = "shared" | "exclusive";
 export interface SandboxLease {
     readonly kind: LeaseKind;
     readonly token: string;
-    readonly conversationId: string;
+    readonly environmentId: string;
     /** Aborts with {@link SandboxLockLostError} when the lease is lost. */
     readonly signal: AbortSignal;
     /** Renews once now; false when the lease is lost (the signal then aborts). */
@@ -93,7 +82,7 @@ export declare const SANDBOX_LEASE_TIMINGS: unique symbol;
  */
 export declare class SandboxLeases {
     private readonly locks;
-    /** The holder records and the legacy busy marker (scripts of this file). */
+    /** The holder records (scripts of this file). */
     private readonly redis;
     private readonly log;
     /** Lease TTL (ms). */
@@ -103,8 +92,8 @@ export declare class SandboxLeases {
     /** 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>);
+    /** The holder records (scripts of this file). */
+    redis: Pick<Redis, "eval" | "hdel">, 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.
@@ -117,14 +106,14 @@ export declare class SandboxLeases {
      * `capMs`, the signal's reason when it aborts. Not granted while an exclusive lease, an older
      * replica's lock token or another caller's intent exists.
      */
-    acquireShared(conv: string, cap: number, signal: AbortSignal, capMs: number): Promise<SandboxLease>;
+    acquireShared(env: string, cap: number, signal: AbortSignal, capMs: number): Promise<SandboxLease>;
     /**
      * An exclusive lease, polling until no other lease exists; `sandbox.busy` after `capMs` (no cap
      * when omitted), the signal's reason when it aborts. With `intent` the waiter sets the intent
      * (refreshed while it waits) so new shared leases stop being granted; it is cleared on success
      * and when the wait ends otherwise.
      */
-    acquireExclusive(conv: string, signal: AbortSignal, capMs?: number, o?: {
+    acquireExclusive(env: string, signal: AbortSignal, capMs?: number, o?: {
         intent?: boolean;
     }): Promise<SandboxLease>;
     /**
@@ -132,7 +121,7 @@ export declare class SandboxLeases {
      * intent. With `o.token` the lease (and, when `o.intent`, the intent set on failure) carries that
      * token, so one waiter can alternate between this and {@link tryShared} with the same token.
      */
-    tryExclusive(conv: string, o?: {
+    tryExclusive(env: string, o?: {
         token?: string;
         intent?: boolean;
     }): Promise<SandboxLease | null>;
@@ -141,35 +130,29 @@ export declare class SandboxLeases {
      * lease token; a waiter that set an intent with the same token is let through its own intent
      * (it should then {@link clearIntent}).
      */
-    tryShared(conv: string, cap: number, token?: string): Promise<SandboxLease | null>;
-    /** Deletes the conversation's intent when it is `token`'s. */
-    clearIntent(conv: string, token: string): Promise<void>;
-    /** Whether the single busy marker of a kernel before phase C is present (v2 does not count). */
-    legacyMarker(conv: string): Promise<boolean>;
-    /** Live shared leases of the conversation. */
-    sharedCount(conv: string): Promise<number>;
+    tryShared(env: string, cap: number, token?: string): Promise<SandboxLease | null>;
+    /** Deletes the environment's intent when it is `token`'s. */
+    clearIntent(env: string, token: string): Promise<void>;
+    /** Live shared leases of the environment. */
+    sharedCount(env: string): Promise<number>;
     /**
      * Records (or refreshes) a holder that may run commands (before its provider calls); `ttlMs`
-     * bounds the record. Also keeps the v2 busy marker for older replicas ({@link BUSY_V2}).
+     * bounds the record.
      */
-    registerHolder(conv: string, token: string, ttlMs: number): Promise<void>;
-    /** Deletes a holder record (after its provider calls); the v2 marker goes with the last one. */
-    unregisterHolder(conv: string, token: string): Promise<void>;
+    registerHolder(env: string, token: string, ttlMs: number): Promise<void>;
+    /** Deletes a holder record (after its provider calls). */
+    unregisterHolder(env: string, token: string): Promise<void>;
     /**
-     * Tags of holders without a live lease, plus whether an older kernel's single busy marker was
-     * present. Atomically claims them (removes the fields) so only one caller kills. That marker is
-     * claimed only when `exclusiveToken` is the caller's exclusive lease (no shared lease live).
+     * Tags of holders without a live lease, atomically claimed (their fields removed) so only one
+     * caller kills them.
      */
-    claimDeadHolders(conv: string, exclusiveToken?: string): Promise<{
-        tags: string[];
-        legacyMarker: boolean;
-    }>;
+    claimDeadHolders(env: string): Promise<string[]>;
     /**
      * 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}. 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>;
+    pathLease(env: string, path: string, signal: AbortSignal, capMs: number): Promise<SandboxPathLease>;
     /** 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. */