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

package/dist/sandbox/leases.js

@@ -14,21 +14,23 @@ import { LockService, } from "../infra/lock/lock.service.js";
 import { redisClockScript, sharedLeaseReadScript, } from "../infra/lock/shared-lease.js";
 import { KERNEL_LOGGER, REDIS } from "../infra/tokens.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`,
@@ -37,23 +39,10 @@ import { KERNEL_LOGGER, REDIS } from "../infra/tokens.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 const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
 /** TTL of a lease (ms): renewed every TTL / 3 while held. */
 export const SANDBOX_LOCK_TTL_MS = 60_000;
-/**
- * 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 const SANDBOX_BUSY_PREFIX = "capk:sandbox-busy:";
-/** Value of the busy marker written by holders of this kernel (ignored by it). */
-export const BUSY_V2 = "v2";
 const USERS_PREFIX = "capk:sandbox-users:";
 const INTENT_PREFIX = "capk:sandbox-intent:";
 const HOLDERS_PREFIX = "capk:sandbox-holders:";
@@ -62,16 +51,16 @@ const PATH_PREFIX = "capk:sandbox-path:";
 const PATH_LEASE_TTL_MS = 30_000;
 /** Shortest life of an exclusive waiter's intent (ms): outlasts event-loop lag between polls. */
 const INTENT_TTL_FLOOR_MS = 2000;
-/** The sandbox of this conversation is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
-export const sandboxBusy = () => new ApiError("sandbox.busy", "The sandbox for this conversation is busy with another command; wait for it to finish and try again");
+/** The environment's sandbox is busy: waited longer than `sandbox.lockWaitSeconds` (409). */
+export const sandboxBusy = () => new ApiError("sandbox.busy", "The sandbox of this environment is busy with other commands; wait for them to finish and try again");
 /** A lease was lost while held, or the record changed under it (generation mismatch). */
 export class SandboxLockLostError extends Error {
     /** `lock`: the lease was lost (renewal failed or none succeeded in time); `generation`: the record's fence changed. */
     reason;
-    constructor(conversationId, reason = "lock") {
+    constructor(environmentId, reason = "lock") {
         super(reason === "lock"
-            ? `sandbox lock lost for conversation ${conversationId}`
-            : `sandbox state of conversation ${conversationId} changed concurrently (generation mismatch)`);
+            ? `sandbox lock lost for environment ${environmentId}`
+            : `sandbox state of environment ${environmentId} changed concurrently (generation mismatch)`);
         this.name = "SandboxLockLostError";
         this.reason = reason;
     }
@@ -83,37 +72,18 @@ export class SandboxPathBusyError extends Error {
         this.name = "SandboxPathBusyError";
     }
 }
-/**
- * KEYS holders, busy; ARGV token, ttl. Also writes the busy marker as v2 (kept for at least `ttl`)
- * unless an older kernel's holder owns it.
- */
+/** KEYS holders; ARGV token, ttl. The hash is kept for at least `ttl`. */
 const REGISTER = redisClockScript(`local ttl = tonumber(ARGV[2])
 redis.call('HSET', KEYS[1], ARGV[1], now + ttl)
 if redis.call('PTTL', KEYS[1]) < ttl then redis.call('PEXPIRE', KEYS[1], ttl) end
-local b = redis.call('GET', KEYS[2])
-if (not b) or (b == '${BUSY_V2}' and redis.call('PTTL', KEYS[2]) < ttl) then
-  redis.call('SET', KEYS[2], '${BUSY_V2}', 'PX', ttl)
-end
 return 1`);
-/** Deletes the v2 busy marker (key `busy`) once no holder record (hash `holders`) is left. */
-const dropV2 = (holders, busy) => `
-if redis.call('HLEN', ${holders}) == 0 and redis.call('GET', ${busy}) == '${BUSY_V2}' then
-  redis.call('DEL', ${busy})
-end`;
-/** KEYS holders, busy; ARGV token. */
-const UNREGISTER = `
-redis.call('HDEL', KEYS[1], ARGV[1])
-${dropV2("KEYS[1]", "KEYS[2]")}
-return 1`;
 /**
- * KEYS lock, users, holders, busy; ARGV the caller's exclusive token (or ''). Removes and returns
- * the holder fields without a live lease (expired fields are dropped without being returned: the
- * in-sandbox time limit ended their commands); claims an older kernel's busy marker only for the
- * caller holding the exclusive lease (`cur == token`, so no shared lease is live and killing
- * everything cannot hit a live sibling). The v2 marker is never claimed; it goes with the last
- * record. Returns { legacy, tag… }.
+ * KEYS lock, users, holders. Removes and returns the holder fields without a live lease (expired
+ * fields are dropped without being returned: the in-sandbox time limit ended their commands). The
+ * caller's own token is live (a shared lease, or the exclusive token in the lock key), so it is
+ * never returned. Returns the tags.
  */
-const CLAIM = sharedLeaseReadScript(`local out = {0}
+const CLAIM = sharedLeaseReadScript(`local out = {}
 local f = redis.call('HGETALL', KEYS[3])
 for i = 1, #f, 2 do
   local tok = f[i]
@@ -124,12 +94,6 @@ for i = 1, #f, 2 do
     table.insert(out, tok)
   end
 end
-${dropV2("KEYS[3]", "KEYS[4]")}
-local b = redis.call('GET', KEYS[4])
-if ARGV[1] ~= '' and cur == ARGV[1] and b and b ~= '${BUSY_V2}' then
-  redis.call('DEL', KEYS[4])
-  out[1] = 1
-end
 return out`);
 const abortReason = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
 function sleep(ms, signal) {
@@ -150,9 +114,9 @@ function sleep(ms, signal) {
     });
 }
 /** A signal that aborts with {@link SandboxLockLostError} when `lost` aborts. */
-function lostSignal(lost, conv) {
+function lostSignal(lost, env) {
     const ctl = new AbortController();
-    const abort = () => ctl.abort(new SandboxLockLostError(conv));
+    const abort = () => ctl.abort(new SandboxLockLostError(env));
     if (lost.aborted)
         abort();
     else
@@ -176,7 +140,7 @@ let SandboxLeases = class SandboxLeases {
     /** Path lease TTL (ms). */
     pathTtlMs;
     constructor(locks, 
-    /** The holder records and the legacy busy marker (scripts of this file). */
+    /** The holder records (scripts of this file). */
     redis, log, timings = {}) {
         this.locks = locks;
         this.redis = redis;
@@ -192,11 +156,11 @@ let SandboxLeases = class SandboxLeases {
     get intentTtlMs() {
         return Math.max(this.pollMs * 4, INTENT_TTL_FLOOR_MS);
     }
-    keys(conv) {
+    keys(env) {
         return {
-            lock: `${SANDBOX_LOCK_PREFIX}${conv}`,
-            users: `${USERS_PREFIX}${conv}`,
-            intent: `${INTENT_PREFIX}${conv}`,
+            lock: `${SANDBOX_LOCK_PREFIX}${env}`,
+            users: `${USERS_PREFIX}${env}`,
+            intent: `${INTENT_PREFIX}${env}`,
         };
     }
     wait(signal) {
@@ -207,13 +171,13 @@ let SandboxLeases = 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.
      */
-    async acquireShared(conv, cap, signal, capMs) {
+    async acquireShared(env, cap, signal, capMs) {
         const token = randomUUID();
         const deadline = Date.now() + capMs;
         for (;;) {
             if (signal.aborted)
                 throw abortReason(signal);
-            const lease = await this.tryShared(conv, cap, token);
+            const lease = await this.tryShared(env, cap, token);
             if (lease)
                 return lease;
             if (Date.now() + this.pollMs > deadline)
@@ -227,14 +191,14 @@ let SandboxLeases = class SandboxLeases {
      * (refreshed while it waits) so new shared leases stop being granted; it is cleared on success
      * and when the wait ends otherwise.
      */
-    async acquireExclusive(conv, signal, capMs, o = {}) {
+    async acquireExclusive(env, signal, capMs, o = {}) {
         const token = randomUUID();
         const deadline = capMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + capMs;
         try {
             for (;;) {
                 if (signal.aborted)
                     throw abortReason(signal);
-                const lease = await this.tryExclusive(conv, { token, intent: o.intent === true });
+                const lease = await this.tryExclusive(env, { token, intent: o.intent === true });
                 if (lease)
                     return lease;
                 if (Date.now() + this.pollMs > deadline)
@@ -244,7 +208,7 @@ let SandboxLeases = class SandboxLeases {
         }
         catch (e) {
             if (o.intent) {
-                await this.clearIntent(conv, token).catch((err) => this.log.warn("cannot clear sandbox intent", { conversationId: conv, err }));
+                await this.clearIntent(env, token).catch((err) => this.log.warn("cannot clear sandbox intent", { environmentId: env, err }));
             }
             throw e;
         }
@@ -254,61 +218,53 @@ let SandboxLeases = 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.
      */
-    async tryExclusive(conv, o = {}) {
-        const h = await this.locks.tryExclusive(this.keys(conv), o.token ?? randomUUID(), this.ttlMs, o.intent ? this.intentTtlMs : undefined);
-        return h ? this.held(conv, h) : null;
+    async tryExclusive(env, o = {}) {
+        const h = await this.locks.tryExclusive(this.keys(env), o.token ?? randomUUID(), this.ttlMs, o.intent ? this.intentTtlMs : undefined);
+        return h ? this.held(env, h) : null;
     }
     /**
      * One try at a shared lease (`cap` holders at most); null when it is not granted. `token` is the
      * lease token; a waiter that set an intent with the same token is let through its own intent
      * (it should then {@link clearIntent}).
      */
-    async tryShared(conv, cap, token = randomUUID()) {
-        const h = await this.locks.tryShared(this.keys(conv), token, cap, this.ttlMs);
-        return h ? this.held(conv, h) : null;
-    }
-    /** Deletes the conversation's intent when it is `token`'s. */
-    async clearIntent(conv, token) {
-        await this.locks.releaseIf(this.keys(conv).intent, token);
+    async tryShared(env, cap, token = randomUUID()) {
+        const h = await this.locks.tryShared(this.keys(env), token, cap, this.ttlMs);
+        return h ? this.held(env, h) : null;
     }
-    /** Whether the single busy marker of a kernel before phase C is present (v2 does not count). */
-    async legacyMarker(conv) {
-        const v = await this.redis.get(`${SANDBOX_BUSY_PREFIX}${conv}`);
-        return v !== null && v !== BUSY_V2;
+    /** Deletes the environment's intent when it is `token`'s. */
+    async clearIntent(env, token) {
+        await this.locks.releaseIf(this.keys(env).intent, token);
     }
-    /** Live shared leases of the conversation. */
-    sharedCount(conv) {
-        return this.locks.sharedCount(this.keys(conv));
+    /** Live shared leases of the environment. */
+    sharedCount(env) {
+        return this.locks.sharedCount(this.keys(env));
     }
     /**
      * 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.
      */
-    async registerHolder(conv, token, ttlMs) {
-        await this.redis.eval(REGISTER, 2, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, token, ttlMs);
+    async registerHolder(env, token, ttlMs) {
+        await this.redis.eval(REGISTER, 1, `${HOLDERS_PREFIX}${env}`, token, ttlMs);
     }
-    /** Deletes a holder record (after its provider calls); the v2 marker goes with the last one. */
-    async unregisterHolder(conv, token) {
-        await this.redis.eval(UNREGISTER, 2, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, token);
+    /** Deletes a holder record (after its provider calls). */
+    async unregisterHolder(env, token) {
+        await this.redis.hdel(`${HOLDERS_PREFIX}${env}`, token);
     }
     /**
-     * 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.
      */
-    async claimDeadHolders(conv, exclusiveToken) {
-        const { lock, users } = this.keys(conv);
-        const r = (await this.redis.eval(CLAIM, 4, lock, users, `${HOLDERS_PREFIX}${conv}`, `${SANDBOX_BUSY_PREFIX}${conv}`, exclusiveToken ?? ""));
-        const [legacy, ...tags] = r;
-        return { tags, legacyMarker: Number(legacy) === 1 };
+    async claimDeadHolders(env) {
+        const { lock, users } = this.keys(env);
+        return (await this.redis.eval(CLAIM, 3, lock, users, `${HOLDERS_PREFIX}${env}`));
     }
     /**
      * 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.
      */
-    async pathLease(conv, path, signal, capMs) {
-        const key = `${PATH_PREFIX}${conv}:${createHash("sha256").update(path).digest("hex")}`;
+    async pathLease(env, path, signal, capMs) {
+        const key = `${PATH_PREFIX}${env}:${createHash("sha256").update(path).digest("hex")}`;
         const token = randomUUID();
         const deadline = Date.now() + capMs;
         let h;
@@ -323,19 +279,19 @@ let SandboxLeases = class SandboxLeases {
             await this.wait(signal);
         }
         const held = h;
-        return { signal: lostSignal(held.lost, conv), release: () => held.release() };
+        return { signal: lostSignal(held.lost, env), release: () => held.release() };
     }
     /** A sandbox lease over a held {@link SharedLeaseHandle}, as its current kind. */
-    held(conv, h) {
-        return this.view(conv, h, lostSignal(h.lost, conv), h.kind);
+    held(env, h) {
+        return this.view(env, h, lostSignal(h.lost, env), h.kind);
     }
     /** A lease view of `h` as `kind`; a view stops working once the lease changes kind. */
-    view(conv, h, signal, kind) {
+    view(env, h, signal, kind) {
         const current = () => h.kind === kind;
         return {
             kind,
             token: h.token,
-            conversationId: conv,
+            environmentId: env,
             signal,
             // a Redis error is warned, not thrown: the deadline decides whether the lease is lost
             renew: async () => {
@@ -345,7 +301,7 @@ let SandboxLeases = class SandboxLeases {
                     return await h.renew();
                 }
                 catch (err) {
-                    this.log.warn("sandbox lease renew failed", { conversationId: conv, err });
+                    this.log.warn("sandbox lease renew failed", { environmentId: env, err });
                     return !signal.aborted;
                 }
             },
@@ -358,8 +314,8 @@ let SandboxLeases = class SandboxLeases {
                 if (signal.aborted)
                     throw abortReason(signal);
                 if (!(await h.downgrade()))
-                    throw new SandboxLockLostError(conv);
-                return this.view(conv, h, signal, "shared");
+                    throw new SandboxLockLostError(env);
+                return this.view(env, h, signal, "shared");
             },
         };
     }

package/dist/sandbox/providers.d.ts

@@ -1,12 +1,12 @@
 import { type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import { ExtensionRegistry } from "../extensions/registry.js";
-/** 当前的 `sandbox@1` 提供方：插件名与实现。 */
+/** 当前的 `sandbox@2` 提供方：插件名与实现。 */
 export interface SandboxProviderEntry {
     plugin: string;
     impl: SandboxProvider;
 }
 /**
- * The `sandbox@1` providers of this process, read from the {@link ExtensionRegistry} at every
+ * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
  * call: providers are ready only after the extension load, and change with installs.
  */
 export declare class SandboxProviders {

package/dist/sandbox/providers.js

@@ -11,7 +11,7 @@ import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ExtensionRegistry } from "../extensions/registry.js";
 /**
- * The `sandbox@1` providers of this process, read from the {@link ExtensionRegistry} at every
+ * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
  * call: providers are ready only after the extension load, and change with installs.
  */
 let SandboxProviders = class SandboxProviders {

package/dist/sandbox/sandbox.module.d.ts

@@ -1,6 +1,7 @@
 /**
- * Sandboxes: the one {@link SandboxService} (a conversation's sandbox over the `sandbox@1`
- * provider, with the shared / exclusive leases of {@link SandboxLeases}) and the producer of the
+ * Sandboxes: the one {@link SandboxService} (an environment's file system and instance over the
+ * `sandbox@2` provider, with the shared / exclusive leases of {@link SandboxLeases}) and the
+ * producer of the
  * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps
  * (`SandboxSweepJobs`) are the worker role's (`WorkerModule`).
  */

package/dist/sandbox/sandbox.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { BackgroundStoreModule } from "../background/store.module.js";
 import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
@@ -13,8 +14,9 @@ import { SandboxLeases } from "./leases.js";
 import { SandboxProviders } from "./providers.js";
 import { SandboxService } from "./sandbox.service.js";
 /**
- * Sandboxes: the one {@link SandboxService} (a conversation's sandbox over the `sandbox@1`
- * provider, with the shared / exclusive leases of {@link SandboxLeases}) and the producer of the
+ * Sandboxes: the one {@link SandboxService} (an environment's file system and instance over the
+ * `sandbox@2` provider, with the shared / exclusive leases of {@link SandboxLeases}) and the
+ * producer of the
  * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps
  * (`SandboxSweepJobs`) are the worker role's (`WorkerModule`).
  */
@@ -22,9 +24,13 @@ let SandboxModule = class SandboxModule {
 };
 SandboxModule = __decorate([
     Module({
-        imports: [ExtensionRegistryModule, QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME)],
+        imports: [
+            ExtensionRegistryModule,
+            BackgroundStoreModule,
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
         providers: [SandboxProviders, SandboxLeases, SandboxService, SandboxJobs],
-        exports: [SandboxService, SandboxJobs],
+        exports: [SandboxService, SandboxJobs, SandboxProviders],
     })
 ], SandboxModule);
 export { SandboxModule };