@dynamicagents/plugins 0.14.0 → 0.16.0

package/dist/{workspace → sandbox}/advisory.d.ts

@@ -1,6 +1,6 @@
-import type { InstallState } from "./install.js";
+import type { InstallState } from "./install-plan.js";
 /**
- * What a caller must not assume about a workspace, and how to say it.
+ * What a caller must not assume about a sandbox's checkout, and how to say it.
  *
  * ## Why this is not `InstallState`
  *
@@ -12,13 +12,6 @@ import type { InstallState } from "./install.js";
  * workspace right now?** The two diverge, and expressing the second through the
  * first goes wrong in ways that are each easy to reintroduce:
  *
- * - A workspace at its storage ceiling is not `skipped`. That variant means
- *   "this checkout has nothing to install" — routine, and about the repository.
- *   A ceiling is a hard wall about the Durable Object, and the two are then told
- *   apart only by reading prose.
- * - Capacity must not travel through a channel gated by
- *   {@link file://../computer/gate.ts needsDependencies}, or a full workspace says nothing
- *   at all to `echo hi > file.txt` — the command whose write is being lost.
  * - "The tree is fine now", after an agent installed by hand, has no honest
  *   spelling as a job record: fabricating a `done` rests on the presence of a
  *   `node_modules` directory, which the wreckage of the very install being
@@ -30,7 +23,7 @@ import type { InstallState } from "./install.js";
  *
  * ## One home for what each kind means
  *
- * {@link shapeOf} is the only exhaustive `switch` over {@link WorkspaceAdvisory}
+ * {@link shapeOf} is the only exhaustive `switch` over {@link SandboxAdvisory}
  * that decides *policy*, and {@link renderAdvisory} the only one that decides
  * *wording*. Everything else reads {@link AdvisoryShape}. A new kind is a
  * compile error in exactly those two places, and whoever adds it has to say what
@@ -39,7 +32,7 @@ import type { InstallState } from "./install.js";
  * discipline.
  */
 /** Something a caller must not assume away. An empty array is the good case. */
-export type WorkspaceAdvisory = {
+export type SandboxAdvisory = {
     kind: "deps-building";
     command: string;
     startedAt: number;
@@ -65,19 +58,15 @@ export type WorkspaceAdvisory = {
 } | {
     kind: "deps-absent";
     reason: string;
-} | {
-    kind: "storage-exhausted";
-    bytes: number;
-    capBytes: number;
 };
 /**
  * The three axes every reader decides on, so none of them re-derives severity
  * from a prose string.
  *
- * They are separate because they vary independently, and the combination that
- * proves it is `storage-exhausted`: permanent, reaches every command, and the
- * only one under which writes are lost. Collapsing any pair would have hidden
- * exactly that case.
+ * They are separate because they vary independently. Every kind a sandbox can
+ * report today is `universal: false, writesPersist: true` — its checkout is the
+ * container's own disk, with no ceiling of its own — and the axes stay because
+ * the readers decide on them rather than on a kind.
  */
 export interface AdvisoryShape {
     /**
@@ -95,15 +84,14 @@ export interface AdvisoryShape {
      * Reaches commands that never read `node_modules`.
      *
      * A dependency problem does not; `cat README.md` is unaffected and must not
-     * queue behind an install. A full workspace does, because the write that is
-     * being lost is usually not a dependency's.
+     * queue behind an install.
      */
     universal: boolean;
     /** Whether a write made under this survives. `false` is the loudest thing here. */
     writesPersist: boolean;
 }
 /** What each advisory *means*. The one exhaustive home for policy. */
-export declare function shapeOf(advisory: WorkspaceAdvisory): AdvisoryShape;
+export declare function shapeOf(advisory: SandboxAdvisory): AdvisoryShape;
 /**
  * Who is being told, which decides the **verbs** rather than the facts.
  *
@@ -125,16 +113,11 @@ export type AdvisoryAudience = "tool-call" | "session";
  * this file exists to remove — one repository further out, where it is harder to
  * see.
  */
-export declare function renderAdvisory(advisory: WorkspaceAdvisory, to: AdvisoryAudience): string;
+export declare function renderAdvisory(advisory: SandboxAdvisory, to: AdvisoryAudience): string;
 /** What the host knows, in the shape {@link deriveAdvisories} reads. */
 export interface AdvisoryInput {
     /** The durable install record, exactly as the job wrote it. */
     install: InstallState;
-    /** Set only when the workspace is over its ceiling. */
-    storage?: {
-        bytes: number;
-        capBytes: number;
-    };
     /**
      * Whether a `node_modules` directory exists — **existence only, not health**.
      *
@@ -145,7 +128,7 @@ export interface AdvisoryInput {
      * with the install having failed for real.
      *
      * So it never suppresses a proven failure. It travels onto the advisory as
-     * {@link WorkspaceAdvisory} `treePresent` and the reader is told which way the
+     * {@link SandboxAdvisory} `treePresent` and the reader is told which way the
      * ambiguity runs. The alternative — treating it as proof of success — is what
      * made a durable record of a failed install disappear on exactly the failure
      * mode it was recording.
@@ -169,15 +152,13 @@ export interface AdvisoryInput {
 /**
  * Everything currently true about a workspace, from what the host can see.
  *
- * An array, and that is not future-proofing. A full workspace and a failed
- * install are both true at once, and a single-slot record could only keep the
- * one written last — so the ceiling silently erased whatever the install had
- * said, or the reverse.
+ * An array, so a reader handles any number the same way and a new kind that can
+ * be true beside another needs no new shape.
  *
  * Order is severity-descending, so a renderer that shows only the first shows
  * the one that matters.
  */
-export declare function deriveAdvisories(input: AdvisoryInput): readonly WorkspaceAdvisory[];
+export declare function deriveAdvisories(input: AdvisoryInput): readonly SandboxAdvisory[];
 /**
  * Everything a session should know before it starts, or `undefined` for silence.
  *
@@ -186,4 +167,4 @@ export declare function deriveAdvisories(input: AdvisoryInput): readonly Workspa
  * be: it can install dependencies itself, and the only thing it must not do is
  * work silently against a workspace that is not what it assumes.
  */
-export declare function sessionAdvisory(advisories: readonly WorkspaceAdvisory[]): string | undefined;
+export declare function sessionAdvisory(advisories: readonly SandboxAdvisory[]): string | undefined;

package/dist/{workspace → sandbox}/advisory.js

@@ -8,8 +8,6 @@ export function shapeOf(advisory) {
             return { transient: false, universal: false, writesPersist: true };
         case "deps-absent":
             return { transient: false, universal: false, writesPersist: true };
-        case "storage-exhausted":
-            return { transient: false, universal: true, writesPersist: false };
         default: {
             // A new kind lands here as a type error, which is the point: it cannot be
             // added without someone stating whether it is transient, whether it
@@ -19,10 +17,6 @@ export function shapeOf(advisory) {
         }
     }
 }
-/** Gigabytes, because this is the one place the numbers are that large. */
-function gb(bytes) {
-    return `${(bytes / 1e9).toFixed(1)} GB`;
-}
 /** A failed install's own last words, fenced so a model reads them as output. */
 function quoted(tail) {
     const trimmed = tail?.trim();
@@ -80,17 +74,6 @@ export function renderAdvisory(advisory, to) {
                     "yourself first."
                 : `${fact}\n\nIf you need \`node_modules\`, install them yourself first.`;
         }
-        case "storage-exhausted": {
-            const fact = `This workspace holds ${gb(advisory.bytes)} against a ` +
-                `${gb(advisory.capBytes)} ceiling, so nothing further can be written ` +
-                "to it.";
-            return to === "tool-call"
-                ? `${fact}\n\nNothing written to this workspace survives. Stop and ` +
-                    "report this rather than retrying."
-                : `${fact}\n\n**Nothing you write here will survive**, including every ` +
-                    "edit you are about to make. Report this and stop; an operator has " +
-                    "to reclaim the space or point this caller at a smaller repository.";
-        }
         default: {
             const unhandled = advisory;
             return unhandled;
@@ -100,24 +83,14 @@ export function renderAdvisory(advisory, to) {
 /**
  * Everything currently true about a workspace, from what the host can see.
  *
- * An array, and that is not future-proofing. A full workspace and a failed
- * install are both true at once, and a single-slot record could only keep the
- * one written last — so the ceiling silently erased whatever the install had
- * said, or the reverse.
+ * An array, so a reader handles any number the same way and a new kind that can
+ * be true beside another needs no new shape.
  *
  * Order is severity-descending, so a renderer that shows only the first shows
  * the one that matters.
  */
 export function deriveAdvisories(input) {
     const advisories = [];
-    // First, because it is the only one under which nothing a caller does sticks.
-    if (input.storage) {
-        advisories.push({
-            kind: "storage-exhausted",
-            bytes: input.storage.bytes,
-            capBytes: input.storage.capBytes
-        });
-    }
     const install = input.install;
     switch (install.state) {
         case "running":

package/dist/sandbox/agent-exec.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Running a command in the container as the agent, and only as the agent.
+ *
+ * `ctx.container.exec(argv, { user })` changes the uid and keeps root's
+ * capability set: a process started that way as `10001:10001` was measured with
+ * `CapEff 0xabac35fb`, `CAP_DAC_OVERRIDE` and `CAP_SYS_PTRACE` among it. So
+ * every host command goes through `setpriv`, which drops the inheritable and
+ * bounding sets and changes identity in one step, and the image provides it
+ * (util-linux).
+ *
+ * `setpriv` starts as root, so it is named by its absolute path and given no
+ * environment of the caller's: a `PATH` or `LD_PRELOAD` would otherwise be
+ * honoured as root before the drop. The command's environment is applied after
+ * it, by `env -i`, which also clears whatever the container's own carries.
+ *
+ * So is its directory, by `env -C`, and never as the platform's `cwd`: a `cwd`
+ * that does not exist fails the spawn, and the platform reports that as the
+ * command not being found in the container (observed). A missing directory is
+ * an answer — `/repo` probes a clone target before cloning into it — so it has
+ * to arrive as one: `env` exits 125 and says which directory.
+ */
+/** The image's unprivileged user, which owns `/workspace` and runs the CLI. */
+export declare const AGENT_UID = 10001;
+export declare const AGENT_GID = 10001;
+export declare const AGENT_HOME = "/home/agent";
+/** `argv`, run as the agent with no capabilities, in exactly {@link agentEnv}`(env)`, from `cwd` when given. */
+export declare function asAgent(argv: readonly string[], env?: Readonly<Record<string, string>>, cwd?: string): string[];
+/** The environment a command run {@link asAgent} expects of its user. */
+export declare function agentEnv(extra?: Readonly<Record<string, string>>): Record<string, string>;
+/** A shell string for `sh -c`, single-quoted so nothing in it is expanded. */
+export declare function shellQuote(value: string): string;

package/dist/sandbox/agent-exec.js

@@ -0,0 +1,62 @@
+/**
+ * Running a command in the container as the agent, and only as the agent.
+ *
+ * `ctx.container.exec(argv, { user })` changes the uid and keeps root's
+ * capability set: a process started that way as `10001:10001` was measured with
+ * `CapEff 0xabac35fb`, `CAP_DAC_OVERRIDE` and `CAP_SYS_PTRACE` among it. So
+ * every host command goes through `setpriv`, which drops the inheritable and
+ * bounding sets and changes identity in one step, and the image provides it
+ * (util-linux).
+ *
+ * `setpriv` starts as root, so it is named by its absolute path and given no
+ * environment of the caller's: a `PATH` or `LD_PRELOAD` would otherwise be
+ * honoured as root before the drop. The command's environment is applied after
+ * it, by `env -i`, which also clears whatever the container's own carries.
+ *
+ * So is its directory, by `env -C`, and never as the platform's `cwd`: a `cwd`
+ * that does not exist fails the spawn, and the platform reports that as the
+ * command not being found in the container (observed). A missing directory is
+ * an answer — `/repo` probes a clone target before cloning into it — so it has
+ * to arrive as one: `env` exits 125 and says which directory.
+ */
+/** The image's unprivileged user, which owns `/workspace` and runs the CLI. */
+export const AGENT_UID = 10001;
+export const AGENT_GID = 10001;
+export const AGENT_HOME = "/home/agent";
+const SETPRIV = "/usr/bin/setpriv";
+const ENV = "/usr/bin/env";
+/** Where the image's tools are. A command's own `env` may replace it. */
+const AGENT_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+/** `argv`, run as the agent with no capabilities, in exactly {@link agentEnv}`(env)`, from `cwd` when given. */
+export function asAgent(argv, env = {}, cwd) {
+    if (argv.length === 0)
+        throw new Error("asAgent: an empty command");
+    return [
+        SETPRIV,
+        `--reuid=${AGENT_UID}`,
+        `--regid=${AGENT_GID}`,
+        "--init-groups",
+        "--inh-caps=-all",
+        "--bounding-set=-all",
+        "--",
+        ENV,
+        "-i",
+        ...(cwd ? ["-C", cwd] : []),
+        ...Object.entries(agentEnv(env)).map(([name, value]) => `${name}=${value}`),
+        ...argv
+    ];
+}
+/** The environment a command run {@link asAgent} expects of its user. */
+export function agentEnv(extra = {}) {
+    return {
+        HOME: AGENT_HOME,
+        USER: "agent",
+        LOGNAME: "agent",
+        PATH: AGENT_PATH,
+        ...extra
+    };
+}
+/** A shell string for `sh -c`, single-quoted so nothing in it is expanded. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/sandbox/ca-trust.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Trusting the runtime's interception CA, which only exists once intercepted.
+ *
+ * Intercepting HTTPS means the runtime terminates TLS with its own certificate,
+ * and it mounts that CA only after `start()` and the intercept call — so the
+ * image's entrypoint runs before there is anything to trust, and this runs from
+ * the object instead, once per container. HTTP intercepts need none of it.
+ */
+export declare const TRUST_CA_COMMAND: string;

package/dist/sandbox/ca-trust.js

@@ -0,0 +1,21 @@
+/**
+ * Trusting the runtime's interception CA, which only exists once intercepted.
+ *
+ * Intercepting HTTPS means the runtime terminates TLS with its own certificate,
+ * and it mounts that CA only after `start()` and the intercept call — so the
+ * image's entrypoint runs before there is anything to trust, and this runs from
+ * the object instead, once per container. HTTP intercepts need none of it.
+ */
+export const TRUST_CA_COMMAND = [
+    'ls -A /etc/cloudflare/certs 2>&1 || echo "(no /etc/cloudflare/certs)"',
+    "CA=/etc/cloudflare/certs/cloudflare-containers-ca.crt",
+    'if [ -r "$CA" ]; then',
+    // Trailing operators: a newline ends a command in sh, so a leading `&&` on
+    // the next line is a syntax error rather than a continuation.
+    '  install -m 644 "$CA" /usr/local/share/ca-certificates/cloudflare-containers-ca.crt &&',
+    "  update-ca-certificates > /dev/null 2>&1 &&",
+    '  echo TRUSTED || echo "TRUST FAILED"',
+    "else",
+    '  echo "NO CA AT $CA"',
+    "fi"
+].join("\n");

package/dist/sandbox/constants.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What the object and the daemon in its container must spell identically.
+ *
+ * A module of its own, with no imports, because the daemon runs in Node and
+ * cannot load anything that reaches `cloudflare:workers`.
+ */
+/** Bumped when an RPC of the object changes shape, so a caller can tell a busy object still on older code. */
+export declare const SANDBOX_CONTRACT = 2;
+/**
+ * The harness's own root session, which a sandbox keeps for control prompts:
+ * the daemon answers it without starting a CLI. The contract spec pins it to
+ * the harness's `ROOT_SESSION`.
+ */
+export declare const CONTROL_SESSION = "root";
+/** A control prompt that only starts the container. */
+export declare const CONTROL_WAKE = "control:wake";
+/** Markers and job output in the container: made by the object, owned by the agent. */
+export declare const RUN_DIR = "/run/da";
+/** The marker a CLI turn waits for, holding the runtime id its egress was prepared for. */
+export declare const EGRESS_READY = "/run/da/egress-ready";
+/** How long a CLI turn waits for {@link EGRESS_READY} before it refuses to start. */
+export declare const EGRESS_WAIT_MS = 60000;

package/dist/sandbox/constants.js

@@ -0,0 +1,22 @@
+/**
+ * What the object and the daemon in its container must spell identically.
+ *
+ * A module of its own, with no imports, because the daemon runs in Node and
+ * cannot load anything that reaches `cloudflare:workers`.
+ */
+/** Bumped when an RPC of the object changes shape, so a caller can tell a busy object still on older code. */
+export const SANDBOX_CONTRACT = 2;
+/**
+ * The harness's own root session, which a sandbox keeps for control prompts:
+ * the daemon answers it without starting a CLI. The contract spec pins it to
+ * the harness's `ROOT_SESSION`.
+ */
+export const CONTROL_SESSION = "root";
+/** A control prompt that only starts the container. */
+export const CONTROL_WAKE = "control:wake";
+/** Markers and job output in the container: made by the object, owned by the agent. */
+export const RUN_DIR = "/run/da";
+/** The marker a CLI turn waits for, holding the runtime id its egress was prepared for. */
+export const EGRESS_READY = `${RUN_DIR}/egress-ready`;
+/** How long a CLI turn waits for {@link EGRESS_READY} before it refuses to start. */
+export const EGRESS_WAIT_MS = 60_000;

package/dist/sandbox/daemon/composite.d.ts

@@ -0,0 +1,9 @@
+import type { ContainerAdapter } from "agents/harness/container/daemon";
+/**
+ * `adapter` for every session but the root one, which is the object's control
+ * channel: it answers a `control:` prompt at once and starts nothing.
+ *
+ * Runtime-agnostic, so the specs serve it from a Worker the way an image serves
+ * it from Node.
+ */
+export declare function withControlSession(adapter: ContainerAdapter): ContainerAdapter;

package/dist/sandbox/daemon/composite.js

@@ -0,0 +1,35 @@
+import { CONTROL_SESSION, SANDBOX_CONTRACT } from "../constants.js";
+/**
+ * `adapter` for every session but the root one, which is the object's control
+ * channel: it answers a `control:` prompt at once and starts nothing.
+ *
+ * Runtime-agnostic, so the specs serve it from a Worker the way an image serves
+ * it from Node.
+ */
+export function withControlSession(adapter) {
+    return {
+        id: adapter.id,
+        version: `${adapter.version}+sandbox.${SANDBOX_CONTRACT}`,
+        ...(adapter.capabilities ? { capabilities: adapter.capabilities } : {}),
+        open(context) {
+            return context.session === CONTROL_SESSION
+                ? controlSession()
+                : adapter.open(context);
+        }
+    };
+}
+function controlSession() {
+    return {
+        async run(turn) {
+            return textOf(turn.input).startsWith("control:")
+                ? { status: "done", text: "ok" }
+                : { status: "unanswered", reason: "the control session runs no CLI" };
+        },
+        async close() { }
+    };
+}
+function textOf(input) {
+    return typeof input === "string"
+        ? input
+        : input.map((part) => (part.type === "text" ? part.text : "")).join("");
+}

package/dist/sandbox/daemon/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `@dynamicagents/plugins/sandbox/daemon` — the entrypoint of a sandbox image.
+ *
+ * Node, not a Worker: this is what the container runs. A consumer bundles it
+ * with its own CLI options from its own `node_modules`, so the daemon and the
+ * object speak one `agents` version.
+ *
+ * It is the harness daemon with one adapter that wears two faces. The root
+ * session is the object's control channel: it answers at once and starts no
+ * CLI, which is how the object starts a container without spending a turn.
+ * Every other session runs the CLI, each turn launched the way its run header
+ * says and only once the object has prepared this container's egress.
+ */
+import { type ContainerAdapter } from "agents/harness/container/daemon";
+import { type CliAdapterOptions, type CliCommand, type CliTurn, type DaemonServer } from "agents/harness/container/runtime";
+import { type RunHeader } from "../header.js";
+export { withControlSession } from "./composite.js";
+/** One CLI turn, with its run header already taken off the prompt. */
+export type SandboxCliTurn = CliTurn & {
+    readonly header: RunHeader | undefined;
+};
+export interface SandboxDaemonOptions {
+    /**
+     * The CLI the sessions run. Everything a sandbox decides about how it runs —
+     * its user, its homes, its working directory, the wait for egress — is set
+     * here and may not be passed.
+     */
+    readonly cli: Omit<CliAdapterOptions, "command" | "user" | "homes" | "skeleton" | "cwd"> & {
+        readonly command: (turn: SandboxCliTurn) => CliCommand;
+    };
+    /** The environment the daemon was started with. Default `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * What a session's home starts as: root-owned in the image, so a session starts
+ * from what the image says rather than from what an earlier one left.
+ */
+export declare const SESSION_SKELETON = "/etc/da/skel";
+/** The adapter a sandbox image serves. Exported for specs; an image calls {@link serveSandboxDaemon}. */
+export declare function sandboxAdapter(options: SandboxDaemonOptions, runtimeId: string): ContainerAdapter;
+/**
+ * Serve the daemon with the identity, secret and port the object started the
+ * container with — as the agent, never root, holding {@link DAEMON_CAPABILITY}:
+ * the image starts it through `setpriv` (see the README), and this refuses to
+ * start otherwise.
+ */
+export declare function serveSandboxDaemon(options: SandboxDaemonOptions): Promise<DaemonServer>;

package/dist/sandbox/daemon/index.js

@@ -0,0 +1,116 @@
+/**
+ * `@dynamicagents/plugins/sandbox/daemon` — the entrypoint of a sandbox image.
+ *
+ * Node, not a Worker: this is what the container runs. A consumer bundles it
+ * with its own CLI options from its own `node_modules`, so the daemon and the
+ * object speak one `agents` version.
+ *
+ * It is the harness daemon with one adapter that wears two faces. The root
+ * session is the object's control channel: it answers at once and starts no
+ * CLI, which is how the object starts a container without spending a turn.
+ * Every other session runs the CLI, each turn launched the way its run header
+ * says and only once the object has prepared this container's egress.
+ */
+import { CONTAINER_ENV } from "agents/harness/container/daemon";
+import { cliAdapter, serveFromEnv } from "agents/harness/container/runtime";
+import { readFileSync } from "node:fs";
+import { AGENT_HOME, AGENT_UID } from "../agent-exec.js";
+import { EGRESS_READY, EGRESS_WAIT_MS } from "../constants.js";
+import { readRunHeader, SANDBOX_ROOT } from "../header.js";
+import { withControlSession } from "./composite.js";
+export { withControlSession } from "./composite.js";
+/**
+ * The one capability the daemon holds, `CAP_NET_BIND_SERVICE`, which grants
+ * nothing here. It is held so the daemon's capabilities are not a subset of
+ * an agent process's: Linux then refuses same-uid processes its
+ * `/proc/<pid>/environ` and `mem`, where the harness token is. Measured: a CLI
+ * launched this way reads neither, and one that kept the capability reads the
+ * token. A same-uid process can still signal the daemon, which ends the
+ * container, as a crash would.
+ */
+const DAEMON_CAPABILITY = 10;
+/** How the daemon launches the CLI: without the capability it holds. */
+const DROP_DAEMON_CAPABILITY = [
+    "/usr/bin/setpriv",
+    "--ambient-caps=-all",
+    "--inh-caps=-all",
+    "--"
+];
+/**
+ * Wait for this container's egress, then run the CLI in the run's directory.
+ *
+ * `$1` is the runtime id the object writes into {@link EGRESS_READY} once it
+ * has registered what the harness does not; a marker naming another runtime is
+ * a snapshot's, and does not count.
+ */
+const LAUNCH = [
+    'rt="$1"; cwd="$2"; shift 2',
+    `n=0; while [ "$(cat ${EGRESS_READY} 2>/dev/null)" != "$rt" ]; do`,
+    `  n=$((n+1)); if [ "$n" -gt ${Math.ceil(EGRESS_WAIT_MS / 100)} ]; then`,
+    '    echo "the sandbox never prepared this container\'s egress" >&2; exit 97',
+    "  fi; sleep 0.1",
+    "done",
+    'cd "$cwd" || exit 98',
+    'exec "$@"'
+].join("\n");
+/**
+ * What a session's home starts as: root-owned in the image, so a session starts
+ * from what the image says rather than from what an earlier one left.
+ */
+export const SESSION_SKELETON = "/etc/da/skel";
+/** The adapter a sandbox image serves. Exported for specs; an image calls {@link serveSandboxDaemon}. */
+export function sandboxAdapter(options, runtimeId) {
+    const cli = cliAdapter({
+        ...options.cli,
+        // No `user`: the daemon is already the agent (see `serveSandboxDaemon`), so
+        // the adapter chowns nothing. Given one, it chowns each home as root, and
+        // chown follows a symlink the agent left there to whatever file it names.
+        homes: `${AGENT_HOME}/.harness/sessions`,
+        skeleton: SESSION_SKELETON,
+        command(turn) {
+            const { header, prompt } = readRunHeader(turn.prompt);
+            const inner = options.cli.command({ ...turn, prompt, header });
+            return {
+                ...inner,
+                argv: [
+                    ...DROP_DAEMON_CAPABILITY,
+                    "sh",
+                    "-c",
+                    LAUNCH,
+                    "sandbox-cli",
+                    runtimeId,
+                    header?.cwd ?? SANDBOX_ROOT,
+                    ...inner.argv
+                ]
+            };
+        }
+    });
+    return withControlSession(cli);
+}
+/**
+ * Serve the daemon with the identity, secret and port the object started the
+ * container with — as the agent, never root, holding {@link DAEMON_CAPABILITY}:
+ * the image starts it through `setpriv` (see the README), and this refuses to
+ * start otherwise.
+ */
+export function serveSandboxDaemon(options) {
+    const uid = process.getuid?.();
+    if (uid !== AGENT_UID || !holdsCapability(DAEMON_CAPABILITY))
+        throw new Error(`the sandbox daemon runs as the agent (uid ${AGENT_UID}) holding net_bind_service, ` +
+            `and this is uid ${uid}: start it through setpriv, as the README's ENTRYPOINT does`);
+    const env = options.env ?? process.env;
+    // `serveFromEnv` deletes it from the env it is given, and the CLI inherits
+    // `process.env`: whatever env was given, the CLI gets no way to the daemon.
+    if (env !== process.env)
+        delete process.env[CONTAINER_ENV.token];
+    const runtimeId = env[CONTAINER_ENV.runtimeId];
+    if (!runtimeId)
+        throw new Error(`${CONTAINER_ENV.runtimeId} is not set: the sandbox object starts this image`);
+    return serveFromEnv(sandboxAdapter(options, runtimeId), env);
+}
+/** Whether this process's permitted set holds capability `bit`. */
+function holdsCapability(bit) {
+    const permitted = /^CapPrm:\s*([0-9a-f]+)$/m.exec(readFileSync("/proc/self/status", "utf8"))?.[1];
+    return (permitted !== undefined &&
+        ((BigInt(`0x${permitted}`) >> BigInt(bit)) & 1n) === 1n);
+}