@tickernelz/paperclip-pro-plugin-kubernetes 2026.925.0

package/dist/pod-spec-builder.js

@@ -0,0 +1,82 @@
+export function buildJobManifest(input) {
+    const podLabels = {
+        ...input.labels,
+        "paperclip.io/role": "agent",
+    };
+    return {
+        apiVersion: "batch/v1",
+        kind: "Job",
+        metadata: {
+            name: input.jobName,
+            namespace: input.namespace,
+            labels: { ...input.labels },
+        },
+        spec: {
+            backoffLimit: 0,
+            ttlSecondsAfterFinished: input.ttlSecondsAfterFinished,
+            activeDeadlineSeconds: input.activeDeadlineSec,
+            template: {
+                metadata: { labels: podLabels },
+                spec: {
+                    serviceAccountName: input.serviceAccountName,
+                    // Agent containers call back to paperclip-server via HTTPS egress;
+                    // they never call the Kubernetes API, so mounting an SA token is
+                    // unnecessary attack surface.
+                    automountServiceAccountToken: false,
+                    restartPolicy: "Never",
+                    ...(input.runtimeClassName ? { runtimeClassName: input.runtimeClassName } : {}),
+                    ...(input.imagePullSecrets && input.imagePullSecrets.length > 0
+                        ? { imagePullSecrets: input.imagePullSecrets.map((name) => ({ name })) }
+                        : {}),
+                    securityContext: {
+                        runAsNonRoot: true,
+                        runAsUser: 1000,
+                        runAsGroup: 1000,
+                        fsGroup: 1000,
+                        fsGroupChangePolicy: "OnRootMismatch",
+                        seccompProfile: { type: "RuntimeDefault" },
+                    },
+                    containers: [
+                        {
+                            name: "agent",
+                            image: input.image,
+                            imagePullPolicy: "IfNotPresent",
+                            command: ["/usr/bin/tini", "--", "/usr/local/bin/paperclip-agent-shim"],
+                            // HOME must point at a writable mount; the image's default
+                            // HOME is inside the readOnly root filesystem. Agent runtimes
+                            // can silently exit with code 0 and no output when HOME is
+                            // unwritable, so set this explicitly.
+                            env: [{ name: "HOME", value: "/home/paperclip" }],
+                            envFrom: [{ secretRef: { name: input.envSecretName } }],
+                            securityContext: {
+                                runAsNonRoot: true,
+                                runAsUser: 1000,
+                                runAsGroup: 1000,
+                                readOnlyRootFilesystem: true,
+                                allowPrivilegeEscalation: false,
+                                capabilities: { drop: ["ALL"] },
+                            },
+                            resources: {
+                                requests: input.resources.requests ?? { cpu: "250m", memory: "512Mi" },
+                                limits: input.resources.limits ?? { cpu: "2", memory: "4Gi" },
+                            },
+                            volumeMounts: [
+                                { name: "workspace", mountPath: "/workspace" },
+                                { name: "home", mountPath: "/home/paperclip" },
+                                { name: "cache", mountPath: "/home/paperclip/.cache" },
+                                { name: "tmp", mountPath: "/tmp" },
+                            ],
+                        },
+                    ],
+                    volumes: [
+                        { name: "workspace", emptyDir: { sizeLimit: "8Gi" } },
+                        { name: "home", emptyDir: { sizeLimit: "1Gi" } },
+                        { name: "cache", emptyDir: { sizeLimit: "1Gi" } },
+                        { name: "tmp", emptyDir: { sizeLimit: "2Gi" } },
+                    ],
+                },
+            },
+        },
+    };
+}
+//# sourceMappingURL=pod-spec-builder.js.map

package/dist/pod-spec-builder.js.map

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

package/dist/sandbox-cr-builder.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Builds a kubernetes-sigs/agent-sandbox Sandbox CR manifest.
+ *
+ * The Sandbox CR creates a long-lived pod (sleep infinity entrypoint) into
+ * which paperclip-server can exec arbitrary commands. This solves the
+ * architectural mismatch with the batch/v1 Job backend, which only supports
+ * a single one-shot entrypoint — not the multi-command adapter-install pattern
+ * used by paperclip-server.
+ *
+ * Security baseline is identical to buildJobManifest (pod-spec-builder.ts):
+ * non-root, drop ALL caps, read-only rootFS, Tini PID 1, seccomp
+ * RuntimeDefault, fsGroupChangePolicy OnRootMismatch, automountSAToken=false.
+ *
+ * NOTE: paperclip-server runs OUTSIDE the cluster, so we cannot set ownerReferences
+ * on the Sandbox CR (the owner would need to be an in-cluster resource). The
+ * release path is explicit delete via sandboxCrOrchestrator.release().
+ */
+export interface BuildSandboxCrManifestInput {
+    namespace: string;
+    sandboxName: string;
+    adapterType: string;
+    image: string;
+    envSecretName: string;
+    serviceAccountName: string;
+    labels: Record<string, string>;
+    resources: {
+        requests?: {
+            cpu?: string;
+            memory?: string;
+        };
+        limits?: {
+            cpu?: string;
+            memory?: string;
+        };
+    };
+    runtimeClassName?: string;
+    imagePullSecrets?: string[];
+}
+export declare function buildSandboxCrManifest(input: BuildSandboxCrManifestInput): Record<string, unknown>;
+//# sourceMappingURL=sandbox-cr-builder.d.ts.map

package/dist/sandbox-cr-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-cr-builder.d.ts","sourceRoot":"","sources":["../src/sandbox-cr-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE;QACT,QAAQ,CAAC,EAAE;YAAE,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7C,MAAM,CAAC,EAAE;YAAE,GAAG,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5C,CAAC;IACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwGzB"}

package/dist/sandbox-cr-builder.js

@@ -0,0 +1,123 @@
+/**
+ * Builds a kubernetes-sigs/agent-sandbox Sandbox CR manifest.
+ *
+ * The Sandbox CR creates a long-lived pod (sleep infinity entrypoint) into
+ * which paperclip-server can exec arbitrary commands. This solves the
+ * architectural mismatch with the batch/v1 Job backend, which only supports
+ * a single one-shot entrypoint — not the multi-command adapter-install pattern
+ * used by paperclip-server.
+ *
+ * Security baseline is identical to buildJobManifest (pod-spec-builder.ts):
+ * non-root, drop ALL caps, read-only rootFS, Tini PID 1, seccomp
+ * RuntimeDefault, fsGroupChangePolicy OnRootMismatch, automountSAToken=false.
+ *
+ * NOTE: paperclip-server runs OUTSIDE the cluster, so we cannot set ownerReferences
+ * on the Sandbox CR (the owner would need to be an in-cluster resource). The
+ * release path is explicit delete via sandboxCrOrchestrator.release().
+ */
+export function buildSandboxCrManifest(input) {
+    const podLabels = {
+        ...input.labels,
+        "paperclip.io/role": "agent",
+    };
+    return {
+        apiVersion: "agents.x-k8s.io/v1alpha1",
+        kind: "Sandbox",
+        metadata: {
+            name: input.sandboxName,
+            namespace: input.namespace,
+            labels: { ...input.labels },
+            // No ownerReferences: paperclip-server is out-of-cluster. Release is
+            // explicit delete.
+        },
+        spec: {
+            podTemplate: {
+                metadata: {
+                    labels: podLabels,
+                },
+                spec: {
+                    serviceAccountName: input.serviceAccountName,
+                    // Agent containers call back to paperclip-server via HTTPS egress;
+                    // they never call the Kubernetes API, so mounting an SA token is
+                    // unnecessary attack surface.
+                    automountServiceAccountToken: false,
+                    // Sandbox controller requires restartPolicy: Always so the pod
+                    // stays running between exec calls.
+                    restartPolicy: "Always",
+                    ...(input.runtimeClassName
+                        ? { runtimeClassName: input.runtimeClassName }
+                        : {}),
+                    ...(input.imagePullSecrets && input.imagePullSecrets.length > 0
+                        ? {
+                            imagePullSecrets: input.imagePullSecrets.map((name) => ({
+                                name,
+                            })),
+                        }
+                        : {}),
+                    securityContext: {
+                        runAsNonRoot: true,
+                        runAsUser: 1000,
+                        runAsGroup: 1000,
+                        fsGroup: 1000,
+                        fsGroupChangePolicy: "OnRootMismatch",
+                        seccompProfile: { type: "RuntimeDefault" },
+                    },
+                    containers: [
+                        {
+                            name: "agent",
+                            image: input.image,
+                            imagePullPolicy: "IfNotPresent",
+                            // sleep infinity keeps the pod running; paperclip-server execs
+                            // commands into it via Kubernetes exec API. Tini as PID 1 for
+                            // proper signal forwarding and zombie reaping.
+                            command: [
+                                "/usr/bin/tini",
+                                "--",
+                                "/bin/sh",
+                                "-c",
+                                "sleep infinity",
+                            ],
+                            // HOME must point at a writable mount; the image's default
+                            // HOME=/home/node is inside the readOnly root filesystem.
+                            // Claude (and most agent runtimes) silently exit with code 0
+                            // and no output when HOME is unwritable, so set this explicitly.
+                            env: [{ name: "HOME", value: "/home/paperclip" }],
+                            envFrom: [{ secretRef: { name: input.envSecretName } }],
+                            securityContext: {
+                                runAsNonRoot: true,
+                                runAsUser: 1000,
+                                runAsGroup: 1000,
+                                readOnlyRootFilesystem: true,
+                                allowPrivilegeEscalation: false,
+                                capabilities: { drop: ["ALL"] },
+                            },
+                            resources: {
+                                requests: input.resources.requests ?? {
+                                    cpu: "250m",
+                                    memory: "512Mi",
+                                },
+                                limits: input.resources.limits ?? {
+                                    cpu: "2",
+                                    memory: "4Gi",
+                                },
+                            },
+                            volumeMounts: [
+                                { name: "workspace", mountPath: "/workspace" },
+                                { name: "home", mountPath: "/home/paperclip" },
+                                { name: "cache", mountPath: "/home/paperclip/.cache" },
+                                { name: "tmp", mountPath: "/tmp" },
+                            ],
+                        },
+                    ],
+                    volumes: [
+                        { name: "workspace", emptyDir: { sizeLimit: "8Gi" } },
+                        { name: "home", emptyDir: { sizeLimit: "1Gi" } },
+                        { name: "cache", emptyDir: { sizeLimit: "1Gi" } },
+                        { name: "tmp", emptyDir: { sizeLimit: "2Gi" } },
+                    ],
+                },
+            },
+        },
+    };
+}
+//# sourceMappingURL=sandbox-cr-builder.js.map

package/dist/sandbox-cr-builder.js.map

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

package/dist/sandbox-cr-orchestrator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SandboxOrchestrator implementation backed by the kubernetes-sigs/agent-sandbox
+ * Sandbox CRD (agents.x-k8s.io/v1alpha1).
+ *
+ * The Sandbox CR creates a long-lived pod that paperclip-server can exec into
+ * for multi-command adapter-install workflows — the key architectural win over
+ * the batch/v1 Job backend.
+ *
+ * Key semantic differences from jobOrchestrator:
+ * - claim() creates a Sandbox CR via CustomObjectsApi instead of a batch Job
+ * - getStatus() maps Sandbox phase (Pending|Ready|Terminating|Failed) to SandboxStatus
+ * - findPod() reads status.podName from the Sandbox CR (falls back to label query)
+ * - waitForCompletion() means "wait until pod is Ready to exec" NOT "wait until
+ *   workload finishes". The Sandbox pod runs sleep infinity; execution completion
+ *   is tracked by the individual execInPod() calls.
+ * - release() deletes the Sandbox CR with Foreground propagation (controller
+ *   tears down the underlying pod).
+ *
+ * NOTE: streamLogs() is provided for interface conformance but is limited —
+ * the sleep-infinity pod has no meaningful stdout. Callers in execute mode
+ * should use execInPod() and capture its stdout/stderr directly.
+ */
+import type { KubeClients } from "./kube-client.js";
+import type { SandboxOrchestrator, SandboxStatus } from "./sandbox-orchestrator.js";
+export declare class SandboxCrTimeoutError extends Error {
+    constructor(namespace: string, name: string, timeoutMs: number);
+}
+export declare function createSandboxCr(clients: KubeClients, namespace: string, manifest: Record<string, unknown>): Promise<{
+    uid: string;
+}>;
+export declare function getSandboxCrStatus(clients: KubeClients, namespace: string, name: string): Promise<SandboxStatus>;
+/**
+ * Returns the pod name backing a Sandbox CR.
+ * Primary: read status.podName from the CR (set by the controller once ready).
+ * Fallback: list pods in the namespace filtered by the paperclip.io/managed-by
+ * label and the sandbox name label set on the pod template.
+ */
+export declare function findPodForSandbox(clients: KubeClients, namespace: string, name: string): Promise<string | null>;
+export declare function streamSandboxLogs(clients: KubeClients, namespace: string, podName: string, onChunk: (stream: "stdout" | "stderr", text: string) => Promise<void>): Promise<void>;
+export declare function deleteSandboxCr(clients: KubeClients, namespace: string, name: string): Promise<void>;
+/**
+ * Wait until the Sandbox CR's pod reaches Ready phase (i.e., the pod is up and
+ * exec-able). This is NOT waiting for a workload to finish — the Sandbox pod
+ * runs sleep infinity indefinitely. Execution completion is tracked by the
+ * individual execInPod() calls.
+ *
+ * Throws SandboxCrTimeoutError if Ready is not reached within timeoutMs.
+ * Throws if the Sandbox transitions to Failed.
+ */
+export declare function waitForSandboxReady(clients: KubeClients, namespace: string, name: string, opts?: {
+    timeoutMs: number;
+    pollMs?: number;
+}): Promise<SandboxStatus>;
+/**
+ * Sandbox CR-backed conformance to SandboxOrchestrator.
+ *
+ * waitForCompletion semantics change: for this backend, "completion" means
+ * "pod is up and Ready to exec into" — NOT "workload finished". The actual
+ * command execution and its completion is handled by execInPod().
+ */
+export declare const sandboxCrOrchestrator: SandboxOrchestrator;
+//# sourceMappingURL=sandbox-cr-orchestrator.d.ts.map

package/dist/sandbox-cr-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-cr-orchestrator.d.ts","sourceRoot":"","sources":["../src/sandbox-cr-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAMpF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM/D;AA2DD,wBAAsB,eAAe,CACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAW1B;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CASxB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiExB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACpE,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAGzC,GACA,OAAO,CAAC,aAAa,CAAC,CA6CxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAOnC,CAAC"}

package/dist/sandbox-cr-orchestrator.js

@@ -0,0 +1,248 @@
+/**
+ * SandboxOrchestrator implementation backed by the kubernetes-sigs/agent-sandbox
+ * Sandbox CRD (agents.x-k8s.io/v1alpha1).
+ *
+ * The Sandbox CR creates a long-lived pod that paperclip-server can exec into
+ * for multi-command adapter-install workflows — the key architectural win over
+ * the batch/v1 Job backend.
+ *
+ * Key semantic differences from jobOrchestrator:
+ * - claim() creates a Sandbox CR via CustomObjectsApi instead of a batch Job
+ * - getStatus() maps Sandbox phase (Pending|Ready|Terminating|Failed) to SandboxStatus
+ * - findPod() reads status.podName from the Sandbox CR (falls back to label query)
+ * - waitForCompletion() means "wait until pod is Ready to exec" NOT "wait until
+ *   workload finishes". The Sandbox pod runs sleep infinity; execution completion
+ *   is tracked by the individual execInPod() calls.
+ * - release() deletes the Sandbox CR with Foreground propagation (controller
+ *   tears down the underlying pod).
+ *
+ * NOTE: streamLogs() is provided for interface conformance but is limited —
+ * the sleep-infinity pod has no meaningful stdout. Callers in execute mode
+ * should use execInPod() and capture its stdout/stderr directly.
+ */
+const SANDBOX_GROUP = "agents.x-k8s.io";
+const SANDBOX_VERSION = "v1alpha1";
+const SANDBOX_PLURAL = "sandboxes";
+export class SandboxCrTimeoutError extends Error {
+    constructor(namespace, name, timeoutMs) {
+        super(`Sandbox ${namespace}/${name} did not reach Ready phase within ${timeoutMs}ms`);
+        this.name = "SandboxCrTimeoutError";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Map a Sandbox CR status.phase value to our SandboxStatus shape.
+ * Sandbox phases: Pending | Ready | Terminating | Failed
+ */
+function mapSandboxPhase(cr) {
+    const status = cr.status ?? {};
+    const phase = status.phase ?? "Pending";
+    switch (phase) {
+        case "Ready":
+            return {
+                phase: "Running", // SandboxStatus.phase uses Job semantics; "Running" = active pod
+                complete: false,
+                active: 1,
+                succeeded: 0,
+                failed: 0,
+            };
+        case "Terminating":
+            return {
+                phase: "Running",
+                complete: false,
+                active: 0,
+                succeeded: 0,
+                failed: 0,
+                reason: "Terminating",
+            };
+        case "Failed": {
+            const conditions = status.conditions ?? [];
+            const failedCond = conditions.find((c) => c.type === "Failed");
+            return {
+                phase: "Failed",
+                complete: false,
+                active: 0,
+                succeeded: 0,
+                failed: 1,
+                reason: failedCond?.reason,
+                message: failedCond?.message,
+            };
+        }
+        default:
+            // "Pending" or unknown
+            return {
+                phase: "Pending",
+                complete: false,
+                active: 0,
+                succeeded: 0,
+                failed: 0,
+            };
+    }
+}
+export async function createSandboxCr(clients, namespace, manifest) {
+    const result = await clients.custom.createNamespacedCustomObject({
+        group: SANDBOX_GROUP,
+        version: SANDBOX_VERSION,
+        namespace,
+        plural: SANDBOX_PLURAL,
+        body: manifest,
+    });
+    const uid = result.metadata?.uid;
+    if (!uid)
+        throw new Error("Sandbox CR created without a UID");
+    return { uid };
+}
+export async function getSandboxCrStatus(clients, namespace, name) {
+    const result = await clients.custom.getNamespacedCustomObject({
+        group: SANDBOX_GROUP,
+        version: SANDBOX_VERSION,
+        namespace,
+        plural: SANDBOX_PLURAL,
+        name,
+    });
+    return mapSandboxPhase(result);
+}
+/**
+ * Returns the pod name backing a Sandbox CR.
+ * Primary: read status.podName from the CR (set by the controller once ready).
+ * Fallback: list pods in the namespace filtered by the paperclip.io/managed-by
+ * label and the sandbox name label set on the pod template.
+ */
+export async function findPodForSandbox(clients, namespace, name) {
+    // Primary: read status.podName from the Sandbox CR
+    const cr = await clients.custom.getNamespacedCustomObject({
+        group: SANDBOX_GROUP,
+        version: SANDBOX_VERSION,
+        namespace,
+        plural: SANDBOX_PLURAL,
+        name,
+    });
+    const status = cr.status ?? {};
+    const podName = status.podName;
+    if (podName && podName.trim().length > 0) {
+        return podName;
+    }
+    // Secondary: the agent-sandbox controller (v0.4.x) names the backing pod
+    // EXACTLY after the Sandbox CR and labels it only with
+    // agents.x-k8s.io/sandbox-name-hash (a hash, not the full name), so the
+    // full-name label selector below matches nothing on that controller. An
+    // exact-name GET is collision-free (unlike name-prefix matching, which
+    // could hit a concurrent sandbox sharing a prefix) and resolves the pod on
+    // every controller version that keeps pod name == sandbox name.
+    try {
+        const pod = (await clients.core.readNamespacedPod({ namespace, name }));
+        if (pod?.metadata?.name) {
+            return pod.metadata.name;
+        }
+    }
+    catch (err) {
+        const code = err.code ??
+            err.statusCode;
+        if (code !== 404)
+            throw err;
+    }
+    // Fallback: list pods by a full-name sandbox label, for controller versions
+    // that label pods with the sandbox name. A broader managed-by selector plus
+    // name-prefix narrowing could match a concurrent sandbox whose generated
+    // name shares a prefix, and exec would target the wrong lease's pod.
+    const result = await clients.core.listNamespacedPod({
+        namespace,
+        labelSelector: `agents.x-k8s.io/sandbox-name=${name}`,
+    });
+    const items = (result.items) ?? [];
+    // The label selector already scopes to exactly this sandbox's pod(s); keep a
+    // defensive re-check on the label value only (no name-prefix matching).
+    const matching = items.filter((p) => (p.metadata?.labels ?? {})["agents.x-k8s.io/sandbox-name"] === name);
+    const running = matching.find((p) => p.status?.phase === "Running");
+    return (running ?? matching[0])?.metadata?.name ?? null;
+}
+export async function streamSandboxLogs(clients, namespace, podName, onChunk) {
+    // V1 limitation: readNamespacedPodLog returns combined stdout. The
+    // sleep-infinity pod will have minimal output; this is provided for interface
+    // conformance. For actual command output, use execInPod() directly.
+    const result = await clients.core.readNamespacedPodLog({
+        namespace,
+        name: podName,
+    });
+    const text = result ?? "";
+    if (text.length > 0)
+        await onChunk("stdout", text);
+}
+export async function deleteSandboxCr(clients, namespace, name) {
+    await clients.custom.deleteNamespacedCustomObject({
+        group: SANDBOX_GROUP,
+        version: SANDBOX_VERSION,
+        namespace,
+        plural: SANDBOX_PLURAL,
+        name,
+        propagationPolicy: "Foreground",
+    });
+}
+/**
+ * Wait until the Sandbox CR's pod reaches Ready phase (i.e., the pod is up and
+ * exec-able). This is NOT waiting for a workload to finish — the Sandbox pod
+ * runs sleep infinity indefinitely. Execution completion is tracked by the
+ * individual execInPod() calls.
+ *
+ * Throws SandboxCrTimeoutError if Ready is not reached within timeoutMs.
+ * Throws if the Sandbox transitions to Failed.
+ */
+export async function waitForSandboxReady(clients, namespace, name, opts = {
+    timeoutMs: 120_000,
+    pollMs: 2000,
+}) {
+    const deadline = Date.now() + opts.timeoutMs;
+    const pollMs = opts.pollMs ?? 2000;
+    while (Date.now() < deadline) {
+        const cr = await clients.custom.getNamespacedCustomObject({
+            group: SANDBOX_GROUP,
+            version: SANDBOX_VERSION,
+            namespace,
+            plural: SANDBOX_PLURAL,
+            name,
+        });
+        const status = cr.status ?? {};
+        // agent-sandbox v1alpha1 uses status.conditions[type=Ready,status=True],
+        // not status.phase. Fall back to phase for forward-compat.
+        const conditions = Array.isArray(status.conditions) ? status.conditions : [];
+        const readyCondition = conditions.find((c) => c.type === "Ready");
+        const failedCondition = conditions.find((c) => c.type === "Failed" || (c.type === "Ready" && c.status === "False" && typeof c.reason === "string" && /failed/i.test(c.reason)));
+        const phase = status.phase ?? "";
+        if (readyCondition?.status === "True" || phase === "Ready") {
+            return mapSandboxPhase(cr);
+        }
+        if (failedCondition?.status === "True" || phase === "Failed") {
+            const mapped = mapSandboxPhase(cr);
+            throw new Error(`Sandbox ${namespace}/${name} failed: ${mapped.reason ?? failedCondition?.reason ?? "unknown reason"} — ${mapped.message ?? failedCondition?.message ?? ""}`);
+        }
+        if (phase === "Terminating") {
+            // A Sandbox being torn down will never transition to Ready. Polling
+            // until the deadline would burn the full timeoutMs (potentially
+            // 30+ minutes) before throwing a generic timeout. Fail fast instead
+            // so the caller can surface a clear "the lease is being released"
+            // error and decide whether to retry against a fresh Sandbox.
+            throw new Error(`Sandbox ${namespace}/${name} is Terminating — cannot wait for Ready`);
+        }
+        // Pending — keep polling
+        await sleep(pollMs);
+    }
+    throw new SandboxCrTimeoutError(namespace, name, opts.timeoutMs);
+}
+/**
+ * Sandbox CR-backed conformance to SandboxOrchestrator.
+ *
+ * waitForCompletion semantics change: for this backend, "completion" means
+ * "pod is up and Ready to exec into" — NOT "workload finished". The actual
+ * command execution and its completion is handled by execInPod().
+ */
+export const sandboxCrOrchestrator = {
+    claim: createSandboxCr,
+    getStatus: getSandboxCrStatus,
+    findPod: findPodForSandbox,
+    streamLogs: streamSandboxLogs,
+    release: deleteSandboxCr,
+    waitForCompletion: waitForSandboxReady,
+};
+//# sourceMappingURL=sandbox-cr-orchestrator.js.map

package/dist/sandbox-cr-orchestrator.js.map

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

package/dist/sandbox-orchestrator.d.ts

@@ -0,0 +1,39 @@
+import type { KubeClients } from "./kube-client.js";
+export interface SandboxStatus {
+    phase: "Pending" | "Running" | "Succeeded" | "Failed";
+    complete: boolean;
+    active: number;
+    succeeded: number;
+    failed: number;
+    reason?: string;
+    message?: string;
+}
+/**
+ * Abstract interface over a sandbox runtime backend. The current implementation
+ * is Job-backed (job-orchestrator.ts). Future backends slot in by exporting an
+ * object conforming to this shape — e.g. a Kata-FC warm-pool backend that
+ * additionally implements the optional pause/resume slots, or a CRD-backed
+ * backend on kubernetes-sigs/agent-sandbox once it reaches Beta.
+ */
+export interface SandboxOrchestrator {
+    /** Provision the sandbox. Returns the runtime's stable UID. */
+    claim(clients: KubeClients, namespace: string, manifest: Record<string, unknown>): Promise<{
+        uid: string;
+    }>;
+    /** Read current lifecycle phase. */
+    getStatus(clients: KubeClients, namespace: string, name: string): Promise<SandboxStatus>;
+    /** Locate the pod backing this sandbox (or null if none exists yet). */
+    findPod(clients: KubeClients, namespace: string, name: string): Promise<string | null>;
+    /** Read logs from the sandbox's pod. V1: post-completion read. */
+    streamLogs(clients: KubeClients, namespace: string, podName: string, onChunk: (stream: "stdout" | "stderr", text: string) => Promise<void>): Promise<void>;
+    /** Tear down the sandbox. Implementations MUST cascade-delete child resources. */
+    release(clients: KubeClients, namespace: string, name: string): Promise<void>;
+    /** Block until phase is Succeeded or Failed, or throw on timeout. */
+    waitForCompletion(clients: KubeClients, namespace: string, name: string, opts: {
+        timeoutMs: number;
+        pollMs?: number;
+    }): Promise<SandboxStatus>;
+    pause?(clients: KubeClients, namespace: string, name: string): Promise<void>;
+    resume?(clients: KubeClients, namespace: string, name: string): Promise<void>;
+}
+//# sourceMappingURL=sandbox-orchestrator.d.ts.map

package/dist/sandbox-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-orchestrator.d.ts","sourceRoot":"","sources":["../src/sandbox-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtD,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,KAAK,CACH,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE5B,oCAAoC;IACpC,SAAS,CACP,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B,wEAAwE;IACxE,OAAO,CACL,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE1B,kEAAkE;IAClE,UAAU,CACR,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACpE,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,kFAAkF;IAClF,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E,qEAAqE;IACrE,iBAAiB,CACf,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3C,OAAO,CAAC,aAAa,CAAC,CAAC;IAO1B,KAAK,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E"}

package/dist/sandbox-orchestrator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandbox-orchestrator.js.map

package/dist/sandbox-orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-orchestrator.js","sourceRoot":"","sources":["../src/sandbox-orchestrator.ts"],"names":[],"mappings":""}