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

package/dist/sandbox/leases.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 { createHash, randomUUID } from "node:crypto";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+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
@@ -18,9 +31,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 const SANDBOX_LOCK_PREFIX = "capk:sandbox:";
@@ -68,104 +83,18 @@ export class SandboxPathBusyError extends Error {
         this.name = "SandboxPathBusyError";
     }
 }
-const NOW = `local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)`;
-/** Drops expired shared leases; drops a `shared` lock value no live shared lease backs. */
-const PURGE = `
-redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
-local cur = redis.call('GET', KEYS[1])
-if cur == 'shared' and redis.call('ZCARD', KEYS[2]) == 0 then
-  redis.call('DEL', KEYS[1])
-  cur = false
-end`;
-/**
- * Keeps the users set and the `shared` lock value alive for at least `ttl` without shortening a
- * longer TTL another holder set (holders may use different TTLs).
- */
-const KEEP_SHARED = `
-if redis.call('PTTL', KEYS[2]) < ttl then redis.call('PEXPIRE', KEYS[2], ttl) end
-local lt = redis.call('PTTL', KEYS[1])
-if redis.call('GET', KEYS[1]) ~= 'shared' or lt < ttl then
-  redis.call('SET', KEYS[1], 'shared', 'PX', math.max(ttl, lt))
-end`;
-/** KEYS lock, users, intent; ARGV token, cap, ttl. */
-const ACQUIRE_SHARED = `${NOW}
-${PURGE}
-if cur and cur ~= 'shared' then return 0 end
-local it = redis.call('GET', KEYS[3])
-if it and it ~= ARGV[1] then return 0 end
-if redis.call('ZCARD', KEYS[2]) >= tonumber(ARGV[2]) then return 0 end
-local ttl = tonumber(ARGV[3])
-redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users, intent; ARGV token, ttl, setIntent (0/1), intentTtl. */
-const ACQUIRE_EXCLUSIVE = `${NOW}
-${PURGE}
-if cur or redis.call('ZCARD', KEYS[2]) > 0 then
-  if ARGV[3] == '1' then
-    local it = redis.call('GET', KEYS[3])
-    if (not it) or it == ARGV[1] then
-      redis.call('SET', KEYS[3], ARGV[1], 'PX', tonumber(ARGV[4]))
-    end
-  end
-  return 0
-end
-redis.call('SET', KEYS[1], ARGV[1], 'PX', tonumber(ARGV[2]))
-if redis.call('GET', KEYS[3]) == ARGV[1] then redis.call('DEL', KEYS[3]) end
-return 1`;
-/** KEYS lock, users; ARGV token, ttl, kind. Shared: lost when the member is gone or the lock holds a token. */
-const RENEW = `${NOW}
-local ttl = tonumber(ARGV[2])
-if ARGV[3] == 'exclusive' then
-  if redis.call('GET', KEYS[1]) == ARGV[1] then
-    redis.call('PEXPIRE', KEYS[1], ttl)
-    return 1
-  end
-  return 0
-end
-redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
-if not redis.call('ZSCORE', KEYS[2], ARGV[1]) then return 0 end
-local cur = redis.call('GET', KEYS[1])
-if cur and cur ~= 'shared' then
-  redis.call('ZREM', KEYS[2], ARGV[1])
-  return 0
-end
-redis.call('ZADD', KEYS[2], 'XX', now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users; ARGV token, kind. */
-const RELEASE = `${NOW}
-if ARGV[2] == 'exclusive' then
-  if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]) end
-  return 1
-end
-redis.call('ZREM', KEYS[2], ARGV[1])
-${PURGE}
-return 1`;
-/** KEYS lock, users; ARGV token, ttl. */
-const DOWNGRADE = `${NOW}
-if redis.call('GET', KEYS[1]) ~= ARGV[1] then return 0 end
-local ttl = tonumber(ARGV[2])
-redis.call('ZADD', KEYS[2], now + ttl, ARGV[1])
-${KEEP_SHARED}
-return 1`;
-/** KEYS lock, users; returns the live shared count. */
-const COUNT = `${NOW}
-${PURGE}
-return redis.call('ZCARD', KEYS[2])`;
 /**
  * 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.
  */
-const REGISTER = `${NOW}
-local ttl = tonumber(ARGV[2])
+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`;
+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
@@ -184,9 +113,7 @@ return 1`;
  * everything cannot hit a live sibling). The v2 marker is never claimed; it goes with the last
  * record. Returns { legacy, tag… }.
  */
-const CLAIM = `${NOW}
-${PURGE}
-local out = {0}
+const CLAIM = sharedLeaseReadScript(`local out = {0}
 local f = redis.call('HGETALL', KEYS[3])
 for i = 1, #f, 2 do
   local tok = f[i]
@@ -203,10 +130,7 @@ 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`;
-/** Compare-and-delete / compare-and-expire of a single-valued key. */
-const DEL_IF = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
-const EXPIRE_IF = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+return out`);
 const abortReason = (signal) => signal.reason ?? new DOMException("This operation was aborted", "AbortError");
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -225,19 +149,41 @@ function sleep(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-/** The lease protocol; no state in process beyond the leases this process holds. */
-export class SandboxLeases {
+/** A signal that aborts with {@link SandboxLockLostError} when `lost` aborts. */
+function lostSignal(lost, conv) {
+    const ctl = new AbortController();
+    const abort = () => ctl.abort(new SandboxLockLostError(conv));
+    if (lost.aborted)
+        abort();
+    else
+        lost.addEventListener("abort", abort, { once: true });
+    return ctl.signal;
+}
+/** Optional provider: {@link SandboxLeaseTimings} that replace some defaults (tests make them shorter). */
+export const SANDBOX_LEASE_TIMINGS = Symbol("SANDBOX_LEASE_TIMINGS");
+/**
+ * The lease protocol over {@link LockService}'s shared leases; no state in process beyond the
+ * leases this process holds.
+ */
+let SandboxLeases = class SandboxLeases {
+    locks;
     redis;
     log;
+    /** Lease TTL (ms). */
     ttlMs;
+    /** Poll interval while waiting (ms, jittered up to 2×). */
     pollMs;
+    /** Path lease TTL (ms). */
     pathTtlMs;
-    constructor(d) {
-        this.redis = d.redis;
-        this.log = d.log;
-        this.ttlMs = d.ttlMs ?? SANDBOX_LOCK_TTL_MS;
-        this.pollMs = d.pollMs ?? 100;
-        this.pathTtlMs = d.pathTtlMs ?? PATH_LEASE_TTL_MS;
+    constructor(locks, 
+    /** The holder records and the legacy busy marker (scripts of this file). */
+    redis, log, timings = {}) {
+        this.locks = locks;
+        this.redis = redis;
+        this.log = log;
+        this.ttlMs = timings.ttlMs ?? SANDBOX_LOCK_TTL_MS;
+        this.pollMs = timings.pollMs ?? 100;
+        this.pathTtlMs = timings.pathTtlMs ?? PATH_LEASE_TTL_MS;
     }
     /**
      * TTL of an intent (ms): 4 × the poll interval (a jittered wait is up to 2 × the interval plus
@@ -247,7 +193,11 @@ export class SandboxLeases {
         return Math.max(this.pollMs * 4, INTENT_TTL_FLOOR_MS);
     }
     keys(conv) {
-        return [`${SANDBOX_LOCK_PREFIX}${conv}`, `${USERS_PREFIX}${conv}`, `${INTENT_PREFIX}${conv}`];
+        return {
+            lock: `${SANDBOX_LOCK_PREFIX}${conv}`,
+            users: `${USERS_PREFIX}${conv}`,
+            intent: `${INTENT_PREFIX}${conv}`,
+        };
     }
     wait(signal) {
         return sleep(this.pollMs + Math.floor(Math.random() * this.pollMs), signal);
@@ -263,9 +213,9 @@ export class SandboxLeases {
         for (;;) {
             if (signal.aborted)
                 throw abortReason(signal);
-            const ok = await this.redis.eval(ACQUIRE_SHARED, 3, ...this.keys(conv), token, cap, this.ttlMs);
-            if (Number(ok) === 1)
-                return this.hold(conv, token, "shared");
+            const lease = await this.tryShared(conv, cap, token);
+            if (lease)
+                return lease;
             if (Date.now() + this.pollMs > deadline)
                 throw sandboxBusy();
             await this.wait(signal);
@@ -280,14 +230,13 @@ export class SandboxLeases {
     async acquireExclusive(conv, signal, capMs, o = {}) {
         const token = randomUUID();
         const deadline = capMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + capMs;
-        const keys = this.keys(conv);
         try {
             for (;;) {
                 if (signal.aborted)
                     throw abortReason(signal);
-                const ok = await this.redis.eval(ACQUIRE_EXCLUSIVE, 3, ...keys, token, this.ttlMs, o.intent ? 1 : 0, this.intentTtlMs);
-                if (Number(ok) === 1)
-                    return this.hold(conv, token, "exclusive");
+                const lease = await this.tryExclusive(conv, { token, intent: o.intent === true });
+                if (lease)
+                    return lease;
                 if (Date.now() + this.pollMs > deadline)
                     throw sandboxBusy();
                 await this.wait(signal);
@@ -295,9 +244,7 @@ export class SandboxLeases {
         }
         catch (e) {
             if (o.intent) {
-                await this.redis
-                    .eval(DEL_IF, 1, keys[2], token)
-                    .catch((err) => this.log.warn("cannot clear sandbox intent", { conversationId: conv, err }));
+                await this.clearIntent(conv, token).catch((err) => this.log.warn("cannot clear sandbox intent", { conversationId: conv, err }));
             }
             throw e;
         }
@@ -308,9 +255,8 @@ export class SandboxLeases {
      * token, so one waiter can alternate between this and {@link tryShared} with the same token.
      */
     async tryExclusive(conv, o = {}) {
-        const token = o.token ?? randomUUID();
-        const ok = await this.redis.eval(ACQUIRE_EXCLUSIVE, 3, ...this.keys(conv), token, this.ttlMs, o.intent ? 1 : 0, this.intentTtlMs);
-        return Number(ok) === 1 ? this.hold(conv, token, "exclusive") : null;
+        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;
     }
     /**
      * One try at a shared lease (`cap` holders at most); null when it is not granted. `token` is the
@@ -318,12 +264,12 @@ export class SandboxLeases {
      * (it should then {@link clearIntent}).
      */
     async tryShared(conv, cap, token = randomUUID()) {
-        const ok = await this.redis.eval(ACQUIRE_SHARED, 3, ...this.keys(conv), token, cap, this.ttlMs);
-        return Number(ok) === 1 ? this.hold(conv, token, "shared") : null;
+        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.redis.eval(DEL_IF, 1, this.keys(conv)[2], token);
+        await this.locks.releaseIf(this.keys(conv).intent, token);
     }
     /** Whether the single busy marker of a kernel before phase C is present (v2 does not count). */
     async legacyMarker(conv) {
@@ -331,9 +277,8 @@ export class SandboxLeases {
         return v !== null && v !== BUSY_V2;
     }
     /** Live shared leases of the conversation. */
-    async sharedCount(conv) {
-        const [lock, users] = this.keys(conv);
-        return Number(await this.redis.eval(COUNT, 2, lock, users));
+    sharedCount(conv) {
+        return this.locks.sharedCount(this.keys(conv));
     }
     /**
      * Records (or refreshes) a holder that may run commands (before its provider calls); `ttlMs`
@@ -352,164 +297,79 @@ export class SandboxLeases {
      * claimed only when `exclusiveToken` is the caller's exclusive lease (no shared lease live).
      */
     async claimDeadHolders(conv, exclusiveToken) {
-        const [lock, users] = this.keys(conv);
+        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 };
     }
     /**
      * 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.
      */
     async pathLease(conv, path, signal, capMs) {
         const key = `${PATH_PREFIX}${conv}:${createHash("sha256").update(path).digest("hex")}`;
         const token = randomUUID();
-        const ttl = this.pathTtlMs;
         const deadline = Date.now() + capMs;
+        let h;
         for (;;) {
             if (signal.aborted)
                 throw abortReason(signal);
-            if ((await this.redis.set(key, token, "PX", ttl, "NX")) === "OK")
+            h = await this.locks.hold(key, token, this.pathTtlMs);
+            if (h)
                 break;
             if (Date.now() + this.pollMs > deadline)
                 throw new SandboxPathBusyError();
             await this.wait(signal);
         }
-        const ctl = new AbortController();
-        const timer = setInterval(() => {
-            this.redis
-                .eval(EXPIRE_IF, 1, key, token, ttl)
-                .then((ok) => {
-                if (Number(ok) === 1 || ctl.signal.aborted)
-                    return;
-                this.log.warn("sandbox path lease lost", { conversationId: conv });
-                ctl.abort(new SandboxLockLostError(conv));
-                clearInterval(timer);
-            })
-                .catch((err) => this.log.warn("sandbox path lease renew failed", { conversationId: conv, err }));
-        }, Math.max(1, Math.floor(ttl / 3)));
-        timer.unref();
-        return {
-            signal: ctl.signal,
-            release: async () => {
-                clearInterval(timer);
-                await this.redis.eval(DEL_IF, 1, key, token);
-            },
-        };
-    }
-    /**
-     * 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).
-     */
-    hold(conv, token, kind) {
-        const ctl = new AbortController();
-        const staleMs = Math.floor((this.ttlMs * 2) / 3);
-        let inFlight = false;
-        const s = {
-            kind,
-            token,
-            conv,
-            ctl,
-            lastOk: Date.now(),
-            released: false,
-            stop: () => {
-                clearInterval(timer);
-                clearInterval(watchdog);
-            },
-        };
-        const stale = () => Date.now() - s.lastOk > staleMs;
-        const tick = () => {
-            if (stale())
-                this.lose(s);
-            if (ctl.signal.aborted) {
-                s.stop();
-                return;
-            }
-            if (inFlight)
-                return;
-            inFlight = true;
-            void this.renew(s).finally(() => {
-                inFlight = false;
-            });
-        };
-        const timer = setInterval(tick, Math.max(1, Math.floor(this.ttlMs / 3)));
-        timer.unref();
-        // a finer check (at most every 5 s): notices a renewal that hangs
-        const watchdog = setInterval(() => {
-            if (stale())
-                this.lose(s);
-            if (ctl.signal.aborted)
-                s.stop();
-        }, Math.min(5000, Math.max(1, Math.floor(this.ttlMs / 6))));
-        watchdog.unref();
-        return this.view(s, kind);
+        const held = h;
+        return { signal: lostSignal(held.lost, conv), release: () => held.release() };
     }
-    lose(s) {
-        if (s.ctl.signal.aborted)
-            return;
-        this.log.warn("sandbox lease lost", { conversationId: s.conv, kind: s.kind });
-        s.ctl.abort(new SandboxLockLostError(s.conv));
-        s.stop();
+    /** 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);
     }
-    async renew(s) {
-        if (s.ctl.signal.aborted)
-            return false;
-        const [lock, users] = this.keys(s.conv);
-        // Redis computes the new expiry when it runs the script: freshness counts from the send
-        const sent = Date.now();
-        try {
-            const ok = Number(await this.redis.eval(RENEW, 2, lock, users, s.token, this.ttlMs, s.kind));
-            if (ok === 1)
-                s.lastOk = Math.max(s.lastOk, sent);
-            else
-                this.lose(s);
-        }
-        catch (err) {
-            this.log.warn("sandbox lease renew failed", { conversationId: s.conv, err });
-        }
-        if (Date.now() - s.lastOk > Math.floor((this.ttlMs * 2) / 3))
-            this.lose(s);
-        return !s.ctl.signal.aborted;
-    }
-    /** A lease view of `s` as `kind`; a view stops working once the lease changes kind. */
-    view(s, kind) {
-        const [lock, users] = this.keys(s.conv);
-        const current = () => s.kind === kind;
+    /** A lease view of `h` as `kind`; a view stops working once the lease changes kind. */
+    view(conv, h, signal, kind) {
+        const current = () => h.kind === kind;
         return {
             kind,
-            token: s.token,
-            conversationId: s.conv,
-            signal: s.ctl.signal,
-            renew: () => (current() ? this.renew(s) : Promise.resolve(false)),
+            token: h.token,
+            conversationId: conv,
+            signal,
+            // a Redis error is warned, not thrown: the deadline decides whether the lease is lost
+            renew: async () => {
+                if (!current())
+                    return false;
+                try {
+                    return await h.renew();
+                }
+                catch (err) {
+                    this.log.warn("sandbox lease renew failed", { conversationId: conv, err });
+                    return !signal.aborted;
+                }
+            },
             // Any view releases the lease in its current kind (a caller that kept only the exclusive
             // view after a downgrade must not leak the shared lease, which would renew forever)
-            release: async () => {
-                if (s.released)
-                    return;
-                s.released = true;
-                s.stop();
-                await this.redis
-                    .eval(RELEASE, 2, lock, users, s.token, s.kind)
-                    .catch((err) => this.log.warn("cannot release sandbox lease", { conversationId: s.conv, err }));
-            },
+            release: () => h.release(),
             downgrade: async () => {
-                if (!current() || s.kind !== "exclusive" || s.released) {
+                if (!current() || h.kind !== "exclusive")
                     throw new Error("sandbox lease is not exclusive");
-                }
-                if (s.ctl.signal.aborted)
-                    throw abortReason(s.ctl.signal);
-                const sent = Date.now();
-                const ok = Number(await this.redis.eval(DOWNGRADE, 2, lock, users, s.token, this.ttlMs));
-                if (ok !== 1) {
-                    this.lose(s);
-                    throw new SandboxLockLostError(s.conv);
-                }
-                s.kind = "shared";
-                s.lastOk = Math.max(s.lastOk, sent);
-                return this.view(s, "shared");
+                if (signal.aborted)
+                    throw abortReason(signal);
+                if (!(await h.downgrade()))
+                    throw new SandboxLockLostError(conv);
+                return this.view(conv, h, signal, "shared");
             },
         };
     }
-}
+};
+SandboxLeases = __decorate([
+    Injectable(),
+    __param(0, Inject(LockService)),
+    __param(1, Inject(REDIS)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Optional()),
+    __param(3, Inject(SANDBOX_LEASE_TIMINGS))
+], SandboxLeases);
+export { SandboxLeases };

package/dist/sandbox/providers.d.ts

@@ -0,0 +1,19 @@
+import { type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { ExtensionRegistry } from "../extensions/registry.js";
+/** 当前的 `sandbox@1` 提供方：插件名与实现。 */
+export interface SandboxProviderEntry {
+    plugin: string;
+    impl: SandboxProvider;
+}
+/**
+ * The `sandbox@1` 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 {
+    private readonly registry;
+    constructor(registry: Pick<ExtensionRegistry, "list">);
+    /** The current provider; undefined without one. */
+    current(): SandboxProviderEntry | undefined;
+    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
+    lookup(plugin: string): SandboxProvider | undefined;
+}

package/dist/sandbox/providers.js

@@ -0,0 +1,38 @@
+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 { 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
+ * call: providers are ready only after the extension load, and change with installs.
+ */
+let SandboxProviders = class SandboxProviders {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    /** The current provider; undefined without one. */
+    current() {
+        const e = this.registry.list("sandbox").find((x) => x.capability === SANDBOX_EXTENSION_POINT);
+        return e ? { plugin: e.plugin, impl: e.impl } : undefined;
+    }
+    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
+    lookup(plugin) {
+        return this.registry
+            .list("sandbox")
+            .find((x) => x.capability === SANDBOX_EXTENSION_POINT && x.plugin === plugin)?.impl;
+    }
+};
+SandboxProviders = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry))
+], SandboxProviders);
+export { SandboxProviders };

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

@@ -0,0 +1,8 @@
+/**
+ * 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
+ * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps
+ * (`SandboxSweepJobs`) are the worker role's (`WorkerModule`).
+ */
+export declare class SandboxModule {
+}

package/dist/sandbox/sandbox.module.js

@@ -0,0 +1,30 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { ExtensionRegistryModule } from "../extensions/registry.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { SandboxJobs } from "./jobs.js";
+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
+ * one-off `sandbox-destroy-for` jobs (`MaintenanceProcessor` consumes them). The sweeps
+ * (`SandboxSweepJobs`) are the worker role's (`WorkerModule`).
+ */
+let SandboxModule = class SandboxModule {
+};
+SandboxModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule, QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME)],
+        providers: [SandboxProviders, SandboxLeases, SandboxService, SandboxJobs],
+        exports: [SandboxService, SandboxJobs],
+    })
+], SandboxModule);
+export { SandboxModule };