@namzu/sandbox 13.0.0 → 14.0.0

package/dist/backends/kubernetes/privilege-probe.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Acquire-time privilege probe: prove the guest process really was
+ * deprivileged, rather than assume the entrypoint did its job.
+ *
+ * The image's entrypoint mounts the workspace as root and then
+ * `exec setpriv --reuid --regid --clear-groups --inh-caps=-all
+ * --bounding-set=-all --no-new-privs -- tini -- node agent.cjs` (`tini` is
+ * the container's pid 1 so it can reap an orphan `agent.cjs` itself never
+ * spawned — see `k8s/entrypoint.sh` and the Dockerfile). Nothing in
+ * `agent.cjs` knows about any of that, and nothing on the host can see it
+ * either — an image built from an older entrypoint, a `RuntimeClass` change,
+ * a hand-edited `SandboxTemplate` all produce a sandbox that works perfectly
+ * and is not deprivileged. So the backend asks the guest, once, before it
+ * hands a caller a handle.
+ *
+ * ## Why `execute`, and why not `read-file`
+ *
+ * The guest's `read-file` resolves every path against `READ_ROOTS`
+ * (`WORKSPACE_ROOT` only), so it cannot reach `/proc` at all, and widening
+ * `READ_ROOTS` to make the probe work would hand every caller of `readFile`
+ * a window into the guest's process tree for the sake of one diagnostic.
+ * `handleExecute` jails only `cwd`, so a command whose ARGUMENT is an
+ * absolute path outside the workspace runs fine. The probe therefore spends
+ * one `exec` and touches no jail.
+ *
+ * ## Why all four masks
+ *
+ * Checking `CapEff` alone is a true-looking answer: an ordinary unprivileged
+ * process shows `CapEff: 0000000000000000` whether or not its bounding set
+ * was ever dropped, so a container running as uid 0 with the full bounding
+ * set still passes. `CapBnd` is the one that says a capability can never be
+ * regained; `CapInh` and `CapPrm` close the two ways one could be carried
+ * across an exec. `NoNewPrivs: 1` is what makes a setuid binary inside the
+ * guest unable to raise any of it back.
+ *
+ * ## Why every failure is a refusal
+ *
+ * A probe that could not run, one that never answered at all, output that
+ * could not be parsed and a process that is genuinely privileged are all
+ * reasons NOT to hand back a handle, and they are separated only in the error
+ * TEXT — a distroless image with no `cat` on `PATH` must be diagnosable as
+ * exactly that rather than read as a hardening failure. There is no
+ * configuration that turns this off.
+ *
+ * ## The clock is the caller's, and it lives in `index.ts`
+ *
+ * Nothing here has a timeout: the probe is one `exec`, and the budget it may
+ * spend belongs to the `create()` that ordered it. `admitProbedSandbox` runs
+ * it under an `OperationDeadline` and turns an expiry into
+ * {@link privilegeProbeTimedOut}, so a guest that accepts the connection and
+ * then goes quiet is refused on the caller's clock rather than on the
+ * execution controller's five-minute generic default.
+ */
+import type { SandboxExecResult } from '@namzu/sdk';
+/**
+ * The probe command. `cat` rather than an absolute `/bin/cat` so a guest
+ * that keeps its coreutils somewhere else still answers, and rather than a
+ * shell so there is no quoting to get wrong. A guest without it fails with
+ * a spawn error the refusal repeats verbatim.
+ */
+export declare const PRIVILEGE_PROBE_COMMAND = "cat";
+/** `/proc/self/status` — of the process the guest agent spawns, which
+ * inherits exactly the agent's own credentials and capability masks. */
+export declare const PRIVILEGE_PROBE_ARGS: readonly string[];
+/** Why a probe refused. The text says the same thing in words. */
+export type PrivilegeProbeFailure = 
+/** The `exec` failed, exited non-zero, or never answered at all. */
+'probe-failed'
+/** It ran, but its output is not a readable `/proc/<pid>/status`. */
+ | 'unreadable-output'
+/** It ran, it parsed, and the process has capabilities it should not. */
+ | 'privileged';
+/**
+ * Raised by {@link runPrivilegeProbe} and {@link parseProcStatus}. The
+ * `reason` is the machine-readable form of the distinction the message
+ * draws in prose: `'privileged'` means the guest is under-hardened, and the
+ * other two mean the backend could not tell.
+ */
+export declare class KubernetesPrivilegeProbeError extends Error {
+    readonly reason: PrivilegeProbeFailure;
+    readonly name = "KubernetesPrivilegeProbeError";
+    constructor(reason: PrivilegeProbeFailure, message: string, options?: ErrorOptions);
+}
+/**
+ * The five fields the probe reads, parsed. The four capability masks are
+ * `bigint` because a capability mask is 64 bits wide and `Number` stops
+ * being exact at 53 — `000001ffffffffff` is only 41 bits today, but a mask
+ * that silently rounds is precisely the bug this whole module exists to
+ * catch.
+ */
+export interface ProcStatusPrivileges {
+    readonly capInh: bigint;
+    readonly capPrm: bigint;
+    readonly capEff: bigint;
+    readonly capBnd: bigint;
+    /** `prctl(PR_GET_NO_NEW_PRIVS)`, 0 or 1 as the kernel prints it. */
+    readonly noNewPrivs: number;
+}
+/**
+ * Parse `/proc/<pid>/status` into the five fields that decide admission.
+ *
+ * Pure: no transport, no clock, no I/O. Everything it cannot read is a
+ * throw, never a default — a zero substituted for a missing mask is the one
+ * mistake that would make this function report hardening that is not there.
+ */
+export declare function parseProcStatus(text: string): ProcStatusPrivileges;
+/**
+ * Admit only an all-zero capability set with `no_new_privs` set. Every
+ * non-zero mask is named in the refusal, because "one of them is set" sends
+ * the reader back to the guest to find out which.
+ */
+export declare function assertDeprivileged(privileges: ProcStatusPrivileges, sandboxName: string): void;
+/**
+ * Run the probe over an already-built sandbox's `exec` and admit or refuse.
+ *
+ * `run` is the sandbox's own `exec`, not the raw transport, so the probe
+ * traverses exactly the path every later call will: reserve, admit, stream,
+ * confirm. A probe that cannot get through this is a sandbox a caller
+ * cannot use either.
+ */
+export declare function runPrivilegeProbe(run: (command: string, args: string[]) => Promise<SandboxExecResult>, sandboxName: string): Promise<ProcStatusPrivileges>;
+/**
+ * The refusal for a probe that never answered.
+ *
+ * A guest that accepts the TCP connection and then goes quiet — an agent
+ * process out of memory, an event loop blocked by the workload, a container
+ * alive with a listener that has stopped reading — cannot be told apart from
+ * a healthy one by the wire alone, so the caller's acquire budget is the only
+ * thing that ends the wait. That expiry is a `'probe-failed'` like any other
+ * way the probe could not run, but it gets its own words: "the deadline
+ * expired" on its own says nothing about WHICH half of the acquire stopped
+ * answering, and a reader who sees `cat` blamed for a hang goes looking for a
+ * missing binary that is not missing.
+ */
+export declare function privilegeProbeTimedOut(sandboxName: string, timeoutMs: number, cause: unknown): KubernetesPrivilegeProbeError;
+//# sourceMappingURL=privilege-probe.d.ts.map

package/dist/backends/kubernetes/privilege-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privilege-probe.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/privilege-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAQ,CAAA;AAE5C;wEACwE;AACxE,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAA0B,CAAA;AAE5E,kEAAkE;AAClE,MAAM,MAAM,qBAAqB;AAChC,oEAAoE;AAClE,cAAc;AAChB,qEAAqE;GACnE,mBAAmB;AACrB,yEAAyE;GACvE,YAAY,CAAA;AAEf;;;;;GAKG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IAItD,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAHvC,SAAkB,IAAI,mCAAkC;gBAG9C,MAAM,EAAE,qBAAqB,EACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAuBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CA8BlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAe9F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,EACpE,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA6B/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACZ,6BAA6B,CAQ/B"}

package/dist/backends/kubernetes/privilege-probe.js

@@ -0,0 +1,185 @@
+/**
+ * Acquire-time privilege probe: prove the guest process really was
+ * deprivileged, rather than assume the entrypoint did its job.
+ *
+ * The image's entrypoint mounts the workspace as root and then
+ * `exec setpriv --reuid --regid --clear-groups --inh-caps=-all
+ * --bounding-set=-all --no-new-privs -- tini -- node agent.cjs` (`tini` is
+ * the container's pid 1 so it can reap an orphan `agent.cjs` itself never
+ * spawned — see `k8s/entrypoint.sh` and the Dockerfile). Nothing in
+ * `agent.cjs` knows about any of that, and nothing on the host can see it
+ * either — an image built from an older entrypoint, a `RuntimeClass` change,
+ * a hand-edited `SandboxTemplate` all produce a sandbox that works perfectly
+ * and is not deprivileged. So the backend asks the guest, once, before it
+ * hands a caller a handle.
+ *
+ * ## Why `execute`, and why not `read-file`
+ *
+ * The guest's `read-file` resolves every path against `READ_ROOTS`
+ * (`WORKSPACE_ROOT` only), so it cannot reach `/proc` at all, and widening
+ * `READ_ROOTS` to make the probe work would hand every caller of `readFile`
+ * a window into the guest's process tree for the sake of one diagnostic.
+ * `handleExecute` jails only `cwd`, so a command whose ARGUMENT is an
+ * absolute path outside the workspace runs fine. The probe therefore spends
+ * one `exec` and touches no jail.
+ *
+ * ## Why all four masks
+ *
+ * Checking `CapEff` alone is a true-looking answer: an ordinary unprivileged
+ * process shows `CapEff: 0000000000000000` whether or not its bounding set
+ * was ever dropped, so a container running as uid 0 with the full bounding
+ * set still passes. `CapBnd` is the one that says a capability can never be
+ * regained; `CapInh` and `CapPrm` close the two ways one could be carried
+ * across an exec. `NoNewPrivs: 1` is what makes a setuid binary inside the
+ * guest unable to raise any of it back.
+ *
+ * ## Why every failure is a refusal
+ *
+ * A probe that could not run, one that never answered at all, output that
+ * could not be parsed and a process that is genuinely privileged are all
+ * reasons NOT to hand back a handle, and they are separated only in the error
+ * TEXT — a distroless image with no `cat` on `PATH` must be diagnosable as
+ * exactly that rather than read as a hardening failure. There is no
+ * configuration that turns this off.
+ *
+ * ## The clock is the caller's, and it lives in `index.ts`
+ *
+ * Nothing here has a timeout: the probe is one `exec`, and the budget it may
+ * spend belongs to the `create()` that ordered it. `admitProbedSandbox` runs
+ * it under an `OperationDeadline` and turns an expiry into
+ * {@link privilegeProbeTimedOut}, so a guest that accepts the connection and
+ * then goes quiet is refused on the caller's clock rather than on the
+ * execution controller's five-minute generic default.
+ */
+/**
+ * The probe command. `cat` rather than an absolute `/bin/cat` so a guest
+ * that keeps its coreutils somewhere else still answers, and rather than a
+ * shell so there is no quoting to get wrong. A guest without it fails with
+ * a spawn error the refusal repeats verbatim.
+ */
+export const PRIVILEGE_PROBE_COMMAND = 'cat';
+/** `/proc/self/status` — of the process the guest agent spawns, which
+ * inherits exactly the agent's own credentials and capability masks. */
+export const PRIVILEGE_PROBE_ARGS = ['/proc/self/status'];
+/**
+ * Raised by {@link runPrivilegeProbe} and {@link parseProcStatus}. The
+ * `reason` is the machine-readable form of the distinction the message
+ * draws in prose: `'privileged'` means the guest is under-hardened, and the
+ * other two mean the backend could not tell.
+ */
+export class KubernetesPrivilegeProbeError extends Error {
+    reason;
+    name = 'KubernetesPrivilegeProbeError';
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+const CAPABILITY_FIELDS = ['CapInh', 'CapPrm', 'CapEff', 'CapBnd'];
+const NO_NEW_PRIVS_FIELD = 'NoNewPrivs';
+/** Clip a value before it goes into an error message. */
+function clip(value) {
+    return value.length > 40 ? `${value.slice(0, 40)}…` : value;
+}
+function readField(text, field) {
+    for (const rawLine of text.split(/\r?\n/)) {
+        const colon = rawLine.indexOf(':');
+        if (colon < 0)
+            continue;
+        if (rawLine.slice(0, colon).trim() !== field)
+            continue;
+        return rawLine.slice(colon + 1).trim();
+    }
+    throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but its output carries no ${field} line, so this sandbox's privileges could not be read. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` — a guest whose /proc is not mounted, or whose kernel does not publish ${field}, cannot be admitted, because an unreadable answer is not a safe one.`);
+}
+/**
+ * Parse `/proc/<pid>/status` into the five fields that decide admission.
+ *
+ * Pure: no transport, no clock, no I/O. Everything it cannot read is a
+ * throw, never a default — a zero substituted for a missing mask is the one
+ * mistake that would make this function report hardening that is not there.
+ */
+export function parseProcStatus(text) {
+    const masks = CAPABILITY_FIELDS.map((field) => {
+        const raw = readField(text, field);
+        // The kernel prints a bare, fixed-width hex mask with no `0x`. A
+        // `0x` prefix, a sign, whitespace inside, or anything non-hex means
+        // this is not the file this parser thinks it is.
+        if (!/^[0-9a-fA-F]+$/.test(raw)) {
+            throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but ${field} is ${JSON.stringify(clip(raw))}, which is not the bare hexadecimal capability mask /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`);
+        }
+        return BigInt(`0x${raw}`);
+    });
+    const noNewPrivsRaw = readField(text, NO_NEW_PRIVS_FIELD);
+    if (!/^\d+$/.test(noNewPrivsRaw)) {
+        throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but ${NO_NEW_PRIVS_FIELD} is ${JSON.stringify(clip(noNewPrivsRaw))}, which is not the integer /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`);
+    }
+    return {
+        capInh: masks[0],
+        capPrm: masks[1],
+        capEff: masks[2],
+        capBnd: masks[3],
+        noNewPrivs: Number(noNewPrivsRaw),
+    };
+}
+/**
+ * Admit only an all-zero capability set with `no_new_privs` set. Every
+ * non-zero mask is named in the refusal, because "one of them is set" sends
+ * the reader back to the guest to find out which.
+ */
+export function assertDeprivileged(privileges, sandboxName) {
+    const offenders = [];
+    if (privileges.capInh !== 0n)
+        offenders.push(`CapInh=${privileges.capInh.toString(16)}`);
+    if (privileges.capPrm !== 0n)
+        offenders.push(`CapPrm=${privileges.capPrm.toString(16)}`);
+    if (privileges.capEff !== 0n)
+        offenders.push(`CapEff=${privileges.capEff.toString(16)}`);
+    if (privileges.capBnd !== 0n)
+        offenders.push(`CapBnd=${privileges.capBnd.toString(16)}`);
+    if (privileges.noNewPrivs !== 1)
+        offenders.push(`NoNewPrivs=${privileges.noNewPrivs}`);
+    if (offenders.length === 0)
+        return;
+    throw new KubernetesPrivilegeProbeError('privileged', `kubernetes sandbox ${sandboxName} is PRIVILEGED and was refused: ${offenders.join(', ')} (every capability mask must be 0 and NoNewPrivs must be 1). The probe ran and was read successfully — this is the guest's real state, not a diagnostic failure. The image's entrypoint is expected to end with \`exec setpriv --reuid --regid --clear-groups --inh-caps=-all --bounding-set=-all --no-new-privs -- tini -- node agent.cjs\`; a sandbox that reaches this message is running with capabilities the workload could use.`);
+}
+/**
+ * Run the probe over an already-built sandbox's `exec` and admit or refuse.
+ *
+ * `run` is the sandbox's own `exec`, not the raw transport, so the probe
+ * traverses exactly the path every later call will: reserve, admit, stream,
+ * confirm. A probe that cannot get through this is a sandbox a caller
+ * cannot use either.
+ */
+export async function runPrivilegeProbe(run, sandboxName) {
+    let result;
+    try {
+        result = await run(PRIVILEGE_PROBE_COMMAND, [...PRIVILEGE_PROBE_ARGS]);
+    }
+    catch (error) {
+        throw new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: ${error instanceof Error ? error.message : String(error)}. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\`; an image without it on PATH cannot be admitted, because a sandbox whose privileges cannot be checked is refused rather than trusted.`, { cause: error });
+    }
+    if (result.exitCode !== 0) {
+        throw new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` exited ${result.exitCode}${result.stderr.trim() ? ` (${clip(result.stderr.trim())})` : ''}. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown.`);
+    }
+    const privileges = parseProcStatus(result.stdout);
+    assertDeprivileged(privileges, sandboxName);
+    return privileges;
+}
+/**
+ * The refusal for a probe that never answered.
+ *
+ * A guest that accepts the TCP connection and then goes quiet — an agent
+ * process out of memory, an event loop blocked by the workload, a container
+ * alive with a listener that has stopped reading — cannot be told apart from
+ * a healthy one by the wire alone, so the caller's acquire budget is the only
+ * thing that ends the wait. That expiry is a `'probe-failed'` like any other
+ * way the probe could not run, but it gets its own words: "the deadline
+ * expired" on its own says nothing about WHICH half of the acquire stopped
+ * answering, and a reader who sees `cat` blamed for a hang goes looking for a
+ * missing binary that is not missing.
+ */
+export function privilegeProbeTimedOut(sandboxName, timeoutMs, cause) {
+    return new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: the guest accepted the connection and did not answer \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` within ${timeoutMs} ms, so the probe was abandoned. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown. A wedged agent (out of memory, an event loop blocked by the workload) looks exactly like this from the host; check the pod's logs before raising the acquire budget.`, { cause });
+}
+//# sourceMappingURL=privilege-probe.js.map

package/dist/backends/kubernetes/privilege-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"privilege-probe.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/privilege-probe.ts"],"names":[],"mappings":"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"}

package/dist/backends/kubernetes/sandbox.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The {@link Sandbox} a kubernetes acquire hands back: the SDK contract,
+ * served over the guest agent's TCP transport, with the lease that keeps the
+ * cluster from deleting the pod out from under a long run.
+ *
+ * Split out of `index.ts` because that file is about the CONTROL plane —
+ * claim, poll, address, release — and this one is about the DATA plane, and
+ * the two are read for different reasons.
+ *
+ * ## What it implements, and what it deliberately does not
+ *
+ * Implemented: `exec` (through the shared {@link RemoteExecutionController},
+ * so an `AbortSignal` terminates the guest process rather than abandoning
+ * the wait), `writeFile`, `readFile`, `listFiles`, `openTerminal`,
+ * `openTcpConnection`, `destroy`.
+ *
+ * Absent on purpose, because the SDK's contract says a backend that cannot
+ * honour an optional method must omit it rather than accept and ignore:
+ *
+ *  - `setNetworkPolicy` — egress here is a `NetworkPolicy` attached to the
+ *    pool's `SandboxTemplate`. There is no per-running-pod knob to turn, and
+ *    a policy accepted and not applied is worse than one never offered: the
+ *    caller stops looking.
+ *  - `spawnDetached` — the guest agent has no op that starts a process and
+ *    returns it running. A host asking for background jobs must be told no.
+ *  - `walkFiles` — not in this batch. A host that requires bounded search
+ *    refuses an absent method, which is the honest answer today.
+ *
+ * ## Terminals are owned
+ *
+ * `openTerminal` is only a compliant implementation if `destroy()` kills and
+ * awaits every terminal it returned, so open terminals are tracked and
+ * reaped before the object is released — the same thing the Firecracker
+ * backend does, for the same contract.
+ *
+ * ## Two terminal states, one `SandboxStatus`
+ *
+ * `SandboxStatus` has exactly four members and this change does not widen
+ * the SDK's union, so both ways a sandbox ends report `'destroyed'`. They
+ * are told apart by the error a later call throws:
+ * {@link KubernetesSandboxDestroyedError} (this host released it) and
+ * {@link KubernetesSandboxGoneError} (the cluster deleted it — the lease
+ * renewal found the object already gone).
+ */
+import type { Sandbox } from '@namzu/sdk';
+import type { KubernetesAgentTransport } from './transport.js';
+/** Thrown by any operation on a sandbox this host already destroyed. */
+export declare class KubernetesSandboxDestroyedError extends Error {
+    readonly operation: string;
+    readonly sandboxName: string;
+    readonly name = "KubernetesSandboxDestroyedError";
+    constructor(operation: string, sandboxName: string);
+}
+/**
+ * Thrown by any operation on a sandbox the CLUSTER removed while this
+ * handle still held it — the lease renewal PATCH came back 404/410. Distinct
+ * from {@link KubernetesSandboxDestroyedError} because nothing this host did
+ * caused it: the object expired, an operator deleted it, or the controller
+ * reaped it, and the actionable advice is different.
+ */
+export declare class KubernetesSandboxGoneError extends Error {
+    readonly operation: string;
+    readonly sandboxName: string;
+    readonly name = "KubernetesSandboxGoneError";
+    constructor(operation: string, sandboxName: string);
+}
+interface KubernetesSandboxBaseOptions {
+    /** The cluster's own name for the bound sandbox — also the sandbox id. */
+    readonly name: string;
+    readonly rootDir: string;
+    readonly transport: KubernetesAgentTransport;
+    /** DELETE the object this backend created. Already-gone counts as done. */
+    readonly release: (signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * The lease half of the options: a way to move the expiry, and the expiry it
+ * is moving. Required TOGETHER, because `renew` without `ttlSeconds` is a
+ * renewal loop with nothing to stamp — it would re-stamp `now + 0`, an
+ * expiry already in the past, and hand the object straight to the
+ * controller's reaper while reporting every tick a success. A pair is the
+ * only shape that cannot be half-configured.
+ */
+interface KubernetesSandboxLeaseOptions {
+    /** PATCH the object's `shutdownTime` forward. See `lease.ts`. */
+    readonly renew: (shutdownTime: string, signal?: AbortSignal) => Promise<void>;
+    /** The TTL acquire stamped; each renewal re-stamps exactly this much. */
+    readonly ttlSeconds: number;
+    readonly onRenewalError?: (error: unknown) => void;
+    /** Test seam: the renewal loop's base interval. Default: half the TTL. */
+    readonly leaseIntervalMs?: number;
+}
+/**
+ * The other arm: an object that carries no expiry, so this handle runs no
+ * renewal loop at all — the persistent workspace (`workspace.ts`), which is
+ * explicitly managed and must outlive a host that stopped renewing. A no-op
+ * `renew` would be the wrong way to say that: it would leave a timer ticking
+ * forever to do nothing. The lease fields are typed `undefined` rather than
+ * omitted so that passing one of them here is a type error and not an
+ * excess-property check a spread would slip past.
+ */
+interface KubernetesSandboxUnleasedOptions {
+    readonly renew?: undefined;
+    readonly ttlSeconds?: undefined;
+    readonly onRenewalError?: undefined;
+    readonly leaseIntervalMs?: undefined;
+}
+export type KubernetesSandboxOptions = KubernetesSandboxBaseOptions & (KubernetesSandboxLeaseOptions | KubernetesSandboxUnleasedOptions);
+/**
+ * What this backend hands back: the SDK contract, with the two optional
+ * members it DOES implement narrowed to present, so a caller that composes
+ * one — `workspace.ts` wraps this handle — does not have to re-check for a
+ * method this file always defines.
+ */
+export type KubernetesSandboxHandle = Sandbox & Required<Pick<Sandbox, 'openTerminal' | 'openTcpConnection'>>;
+/**
+ * Build the handle. It does NOT run the acquire-time privilege probe — that
+ * is `create()`'s job in `index.ts`, so that a refusal can destroy this
+ * object before any caller has a reference to it, and so this function stays
+ * usable by the workspace path that runs its own probe.
+ */
+export declare function buildKubernetesSandbox(options: KubernetesSandboxOptions): KubernetesSandboxHandle;
+export {};
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/backends/kubernetes/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAEX,OAAO,EAWP,MAAM,YAAY,CAAA;AAQnB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAW9D,wEAAwE;AACxE,qBAAa,+BAAgC,SAAQ,KAAK;IAIxD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,qCAAoC;gBAGhD,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAInD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAJ7B,SAAkB,IAAI,gCAA+B;gBAG3C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAM7B;AAED,UAAU,4BAA4B;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzD;AAED;;;;;;;GAOG;AACH,UAAU,6BAA6B;IACtC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7E,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,UAAU,gCAAgC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAA;CACpC;AAED,MAAM,MAAM,wBAAwB,GAAG,4BAA4B,GAClE,CAAC,6BAA6B,GAAG,gCAAgC,CAAC,CAAA;AASnE;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAC5C,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,CAAC,CAAC,CAAA;AAE9D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CAuNjG"}