@dynamicagents/plugins 0.14.0 → 0.15.0

package/dist/sandbox/egress.d.ts

@@ -0,0 +1,81 @@
+import type { EgressRoute } from "agents/harness/container";
+/**
+ * The container's way out, on the Worker side.
+ *
+ * A plugin that needs a host from inside the container declares it as a
+ * {@link SandboxEgressRule}: the hosts to intercept, the placeholders its
+ * processes see, and the handler that swaps a placeholder for the real
+ * credential. A consumer lists the rules a sandbox class carries once, and
+ * hands that list both to the class's config and to the entrypoint that calls
+ * {@link sandboxEgress}. This module names no host and holds no credential.
+ *
+ * An intercepted request reaches the entrypoint, a stateless Worker invocation
+ * outside the container. The sandbox object is on the path only when a handler
+ * calls it ({@link EgressCall.sandbox}).
+ */
+export interface SandboxEgressRule {
+    /** Names the rule where a clash or a refusal is reported. */
+    readonly name: string;
+    /**
+     * Hosts intercepted over plain HTTP, each to its real `https:` upstream: a
+     * placeholder host the container is pointed at, so nothing in it terminates
+     * TLS.
+     */
+    readonly http?: Readonly<Record<string, string>>;
+    /**
+     * Real hosts intercepted over HTTPS, each to its `https:` upstream, for a
+     * client that cannot be pointed at a placeholder, or whose URLs other tools
+     * read back, as git's remotes are. The sandbox trusts the runtime's
+     * interception CA in every container that has one.
+     */
+    readonly https?: Readonly<Record<string, string>>;
+    /**
+     * What a process needs to reach those hosts — a placeholder credential, a
+     * base URL. Every command `exec` runs and every CLI turn gets it, over its
+     * own environment. Never a secret: the container can read it.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Serve one intercepted request: swap the placeholder for the real credential, then {@link forward}. */
+    handle(call: EgressCall): Promise<Response>;
+}
+/** One request the container made, for the rule serving its host. */
+export interface EgressCall {
+    readonly request: Request;
+    /** The rule's upstream for the request's host, with the request's path and query. */
+    readonly target: URL;
+    /** The Worker's `env`, where a credential is read at the moment it is used. */
+    readonly env: Readonly<Record<string, unknown>>;
+    /**
+     * The sandbox whose container made the request, by the name it was reached
+     * by — waking it if it is not in memory. Throws for a sandbox reached without
+     * a name.
+     */
+    sandbox(): DurableObjectStub;
+}
+/** What one sandbox registers for its rules. */
+export interface EgressPlan {
+    /** Intercepted over HTTP by the harness, at every start. */
+    readonly http: readonly EgressRoute[];
+    /** Intercepted over HTTPS by the sandbox, once per container. */
+    readonly https: readonly EgressRoute[];
+    /** Every rule's `env`, merged. */
+    readonly env: Readonly<Record<string, string>>;
+}
+/** Headers that carry a credential, which a handler removes from what the container sent. */
+export declare const CREDENTIAL_HEADERS: readonly string[];
+/**
+ * `rules` as the sandbox `sandbox` (`<binding>/<name>`) registers them.
+ *
+ * Throws for a host two rules declare, an environment key two rules set, or an
+ * upstream that is not https: each would otherwise surface as a request that
+ * reaches the wrong handler, or none.
+ */
+export declare function egressPlan(rules: readonly SandboxEgressRule[], sandbox?: string): EgressPlan;
+/**
+ * Serve one request the container made: `routes` are what the sandbox
+ * registered for this container, which the harness hands the entrypoint as its
+ * props, and `rules` the same list the sandbox's config holds.
+ */
+export declare function sandboxEgress(request: Request, routes: readonly EgressRoute[], env: Readonly<Record<string, unknown>>, rules: readonly SandboxEgressRule[]): Promise<Response>;
+/** `call.request` at its target, with `rewrite` applied to its headers; never following a redirect. */
+export declare function forward(call: EgressCall, rewrite: (headers: Headers) => void, body?: BodyInit): Promise<Response>;

package/dist/sandbox/egress.js

@@ -0,0 +1,109 @@
+/**
+ * On each route, `<binding>/<name>` of the sandbox it was registered by. A
+ * route is the only thing the harness hands the entrypoint, so it is the only
+ * way the entrypoint can know which sandbox's container is calling.
+ */
+const ROUTE_SANDBOX = "x-da-sandbox";
+/** Headers that carry a credential, which a handler removes from what the container sent. */
+export const CREDENTIAL_HEADERS = [
+    "authorization",
+    "x-api-key",
+    "proxy-authorization"
+];
+/**
+ * `rules` as the sandbox `sandbox` (`<binding>/<name>`) registers them.
+ *
+ * Throws for a host two rules declare, an environment key two rules set, or an
+ * upstream that is not https: each would otherwise surface as a request that
+ * reaches the wrong handler, or none.
+ */
+export function egressPlan(rules, sandbox) {
+    const hosts = new Map();
+    const keys = new Map();
+    const http = [];
+    const https = [];
+    const env = {};
+    const route = (rule, host, upstream) => {
+        const owner = hosts.get(host);
+        if (owner !== undefined)
+            throw new Error(`egress: ${host} is declared by both ${owner} and ${rule.name}`);
+        hosts.set(host, rule.name);
+        if (!upstream.startsWith("https://"))
+            throw new Error(`egress: ${rule.name} sends ${host} to ${upstream}, which is not https`);
+        return {
+            host,
+            upstream,
+            headers: sandbox === undefined ? {} : { [ROUTE_SANDBOX]: sandbox },
+            strip: []
+        };
+    };
+    for (const rule of rules) {
+        for (const [host, upstream] of Object.entries(rule.http ?? {}))
+            http.push(route(rule, host, upstream));
+        for (const [host, upstream] of Object.entries(rule.https ?? {}))
+            https.push(route(rule, host, upstream));
+        for (const [key, value] of Object.entries(rule.env ?? {})) {
+            const owner = keys.get(key);
+            if (owner !== undefined)
+                throw new Error(`egress: ${key} is set by both ${owner} and ${rule.name}`);
+            keys.set(key, rule.name);
+            env[key] = value;
+        }
+    }
+    return { http, https, env };
+}
+/**
+ * Serve one request the container made: `routes` are what the sandbox
+ * registered for this container, which the harness hands the entrypoint as its
+ * props, and `rules` the same list the sandbox's config holds.
+ */
+export async function sandboxEgress(request, routes, env, rules) {
+    const url = new URL(request.url);
+    const route = routes.find((each) => each.host === url.hostname);
+    if (!route) {
+        return new Response(`No egress route for ${url.hostname}`, { status: 403 });
+    }
+    for (const rule of rules) {
+        const upstream = upstreamOf(rule.http, url.hostname) ??
+            upstreamOf(rule.https, url.hostname);
+        if (upstream === undefined)
+            continue;
+        const named = route.headers[ROUTE_SANDBOX];
+        return rule.handle({
+            request,
+            target: new URL(`${upstream.replace(/\/+$/, "")}${url.pathname}${url.search}`),
+            env,
+            sandbox: () => sandboxStub(env, named)
+        });
+    }
+    return new Response(`No egress rule serves ${url.hostname}`, {
+        status: 403
+    });
+}
+/** `call.request` at its target, with `rewrite` applied to its headers; never following a redirect. */
+export async function forward(call, rewrite, body) {
+    const headers = new Headers(call.request.headers);
+    headers.delete("host");
+    rewrite(headers);
+    const hasBody = call.request.method !== "GET" && call.request.method !== "HEAD";
+    return fetch(call.target, {
+        method: call.request.method,
+        headers,
+        ...(hasBody ? { body: body ?? call.request.body } : {}),
+        redirect: "manual"
+    });
+}
+function upstreamOf(hosts, host) {
+    return hosts && Object.hasOwn(hosts, host) ? hosts[host] : undefined;
+}
+function sandboxStub(env, named) {
+    const slash = named?.indexOf("/") ?? -1;
+    const namespace = named !== undefined && slash > 0 ? env[named.slice(0, slash)] : undefined;
+    if (named === undefined ||
+        !namespace ||
+        typeof namespace.getByName !== "function") {
+        throw new Error(`egress: this route names no sandbox the Worker can reach (${JSON.stringify(named ?? null)}); ` +
+            "a sandbox is reached by name, and its config's `egress.self` is its binding");
+    }
+    return namespace.getByName(named.slice(slash + 1));
+}

package/dist/sandbox/exec.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A shell in a sandbox, for a plugin that needs one but does not own the
+ * container: `/repo-github`'s git, `/scratch`, a host's own scripts. It answers
+ * the contract those plugins take — `success`, `stdout`, `stderr` and
+ * `exitCode`.
+ *
+ * Every command runs as the agent, with every egress rule's `env`, and under
+ * `timeout` at its limit: the sandbox's own `exec` can only stop waiting, and a
+ * command it stopped waiting for would go on running.
+ *
+ * It merges no host environment of its own: this is a raw shell for another
+ * plugin's commands, and a host environment underneath would let through what
+ * git honours — `GIT_PROXY_COMMAND`, `GIT_CONFIG_GLOBAL`, `http_proxy`. What a
+ * host merges into a plugin's commands it composes where the merge is visible.
+ */
+/** The sandbox RPC this uses. */
+export interface SandboxExecHost {
+    exec(argv: string[], options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export interface SandboxExecConfig {
+    /** Addressed by name only: the sandbox's lifecycle needs it. */
+    binding: DurableObjectNamespace<SandboxExecHost & Rpc.DurableObjectBranded>;
+    /** The sandbox a parent's own commands run in. A sub-agent's comes from its `runtime()`. */
+    sandboxName: () => string;
+    /** Default `/workspace`. */
+    cwd?: string;
+    /**
+     * The shell a command string runs in. Default `bash`: a model writing shell
+     * writes bash, and `/bin/sh` is dash on Debian, which fails `${PIPESTATUS[0]}`
+     * and the rest of that family after the command they wrapped has run.
+     */
+    shell?: string;
+    /** Per command. Default {@link DEFAULT_EXEC_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/** A command that has not finished in this long is a hung command. */
+export declare const DEFAULT_EXEC_TIMEOUT_MS: number;
+export declare function sandboxExec(config: SandboxExecConfig): (command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    timeout?: number;
+    /** A sub-agent's `runtime()`, forwarded opaquely by the plugin calling this. */
+    runtime?: unknown;
+}) => Promise<{
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;

package/dist/sandbox/exec.js

@@ -0,0 +1,52 @@
+import { humanMs } from "./format.js";
+import { SANDBOX_ROOT } from "./header.js";
+import { sandboxNameFromRuntime } from "./name.js";
+/** A command that has not finished in this long is a hung command. */
+export const DEFAULT_EXEC_TIMEOUT_MS = 10 * 60 * 1000;
+/** After `timeout`'s TERM, how long before its KILL. */
+const KILL_AFTER_S = 5;
+/**
+ * `timeout`'s exits for a command it ended. Read as the limit only once the
+ * limit has passed: any SIGKILL is a 137, an out-of-memory kill included.
+ */
+const TIMED_OUT = new Set([124, 137]);
+export function sandboxExec(config) {
+    return async (command, options) => {
+        const name = sandboxNameFromRuntime(options?.runtime) ?? config.sandboxName();
+        const limitMs = options?.timeout ?? config.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS;
+        const env = options?.env
+            ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== undefined))
+            : undefined;
+        const startedAt = Date.now();
+        const run = await config.binding
+            .getByName(name)
+            .exec([
+            "timeout",
+            `--kill-after=${KILL_AFTER_S}`,
+            String(Math.ceil(limitMs / 1000)),
+            config.shell ?? "bash",
+            "-c",
+            command
+        ], {
+            cwd: options?.cwd ?? config.cwd ?? SANDBOX_ROOT,
+            ...(env ? { env } : {}),
+            timeoutMs: limitMs + (KILL_AFTER_S + 5) * 1000
+        });
+        const killed = TIMED_OUT.has(run.exitCode) && Date.now() - startedAt >= limitMs;
+        return {
+            success: run.exitCode === 0,
+            stdout: run.stdout,
+            // Appended rather than substituted: a command killed at its limit may
+            // have written plenty first, and `stdout` is a channel callers parse.
+            stderr: killed
+                ? [
+                    run.stderr,
+                    `the command was killed at its time limit of ${humanMs(limitMs)}, so anything it had not yet written is gone`
+                ]
+                    .filter(Boolean)
+                    .join("\n")
+                : run.stderr,
+            exitCode: run.exitCode
+        };
+    };
+}

package/dist/sandbox/format.d.ts

@@ -0,0 +1,2 @@
+/** Elapsed time in the shape a sentence wants. */
+export declare function humanMs(ms: number): string;

package/dist/sandbox/format.js

@@ -0,0 +1,7 @@
+/** Elapsed time in the shape a sentence wants. */
+export function humanMs(ms) {
+    const s = Math.round(ms / 1000);
+    return s < 60
+        ? `${s}s`
+        : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}

package/dist/sandbox/header.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The run header: how a host tells the daemon how to launch one run.
+ *
+ * `ContainerHarness` takes its adapter options once, for every session it holds,
+ * and its adapters run every turn in one fixed working directory. A sandbox runs
+ * a planner, a writer and a reviser in the same object, each in its own
+ * checkout and under its own permission mode, so neither is enough. The
+ * harness passes a prompt through untouched, so the run's own settings travel
+ * as the prompt's first line, and the daemon takes that line off before the CLI
+ * reads its stdin.
+ *
+ * Parsed on both sides from this one module, so the spelling cannot drift.
+ */
+/** The first characters of a prompt that carries a header. */
+export declare const RUN_HEADER_PREFIX = "@@da ";
+/** Where every run's working directory must sit. */
+export declare const SANDBOX_ROOT = "/workspace";
+export interface RunHeader {
+    /** The checkout the run works in. Fixed for a session's life: the CLI files a transcript by directory. */
+    cwd: string;
+    /** `plan` runs read-only and answers to {@link schema}. */
+    mode?: "plan" | "build";
+    /** A schema the daemon was built with, by name. Not the schema itself: a prompt is stored. */
+    schema?: string;
+    /** The CLI's effort level, passed through. */
+    effort?: string;
+    /** Continue the session's conversation as a new branch of it. */
+    fork?: boolean;
+    /** The CLI's model, when the run needs one other than the session's. */
+    model?: string;
+}
+/** A header the daemon cannot honour, refused rather than run with defaults. */
+export declare class RunHeaderError extends Error {
+    readonly name = "RunHeaderError";
+}
+/** `prompt` with `header` as its first line. */
+export declare function withRunHeader(header: RunHeader, prompt: string): string;
+/**
+ * The header and the prompt beneath it. A prompt with no header line is
+ * returned whole with `header: undefined`: control prompts and a session's own
+ * follow-ups carry none.
+ *
+ * @throws {RunHeaderError} the first line claims to be a header and is not one.
+ */
+export declare function readRunHeader(text: string): {
+    header: RunHeader | undefined;
+    prompt: string;
+};
+/** Whether `path` is `root` or inside it, with no `..` escaping it. */
+export declare function isUnder(path: string, root: string): boolean;

package/dist/sandbox/header.js

@@ -0,0 +1,94 @@
+/**
+ * The run header: how a host tells the daemon how to launch one run.
+ *
+ * `ContainerHarness` takes its adapter options once, for every session it holds,
+ * and its adapters run every turn in one fixed working directory. A sandbox runs
+ * a planner, a writer and a reviser in the same object, each in its own
+ * checkout and under its own permission mode, so neither is enough. The
+ * harness passes a prompt through untouched, so the run's own settings travel
+ * as the prompt's first line, and the daemon takes that line off before the CLI
+ * reads its stdin.
+ *
+ * Parsed on both sides from this one module, so the spelling cannot drift.
+ */
+/** The first characters of a prompt that carries a header. */
+export const RUN_HEADER_PREFIX = "@@da ";
+/** Where every run's working directory must sit. */
+export const SANDBOX_ROOT = "/workspace";
+/** A header the daemon cannot honour, refused rather than run with defaults. */
+export class RunHeaderError extends Error {
+    name = "RunHeaderError";
+}
+/** `prompt` with `header` as its first line. */
+export function withRunHeader(header, prompt) {
+    assertRunHeader(header);
+    return `${RUN_HEADER_PREFIX}${JSON.stringify(header)}\n${prompt}`;
+}
+/**
+ * The header and the prompt beneath it. A prompt with no header line is
+ * returned whole with `header: undefined`: control prompts and a session's own
+ * follow-ups carry none.
+ *
+ * @throws {RunHeaderError} the first line claims to be a header and is not one.
+ */
+export function readRunHeader(text) {
+    if (!text.startsWith(RUN_HEADER_PREFIX))
+        return { header: undefined, prompt: text };
+    const end = text.indexOf("\n");
+    const line = end === -1 ? text : text.slice(0, end);
+    const prompt = end === -1 ? "" : text.slice(end + 1);
+    let value;
+    try {
+        value = JSON.parse(line.slice(RUN_HEADER_PREFIX.length));
+    }
+    catch {
+        throw new RunHeaderError(`the run header is not JSON: ${line.slice(0, 120)}`);
+    }
+    assertRunHeader(value);
+    return { header: value, prompt };
+}
+function assertRunHeader(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new RunHeaderError("the run header must be an object");
+    }
+    const header = value;
+    const cwd = header.cwd;
+    if (typeof cwd !== "string" || !isUnder(cwd, SANDBOX_ROOT)) {
+        throw new RunHeaderError(`the run header's cwd must be an absolute path under ${SANDBOX_ROOT}, got ${JSON.stringify(cwd)}`);
+    }
+    if (header.mode !== undefined &&
+        header.mode !== "plan" &&
+        header.mode !== "build") {
+        throw new RunHeaderError(`unknown run mode ${JSON.stringify(header.mode)}`);
+    }
+    for (const key of ["schema", "effort", "model"]) {
+        if (header[key] !== undefined && typeof header[key] !== "string") {
+            throw new RunHeaderError(`the run header's ${key} must be a string`);
+        }
+    }
+    if (header.fork !== undefined && typeof header.fork !== "boolean") {
+        throw new RunHeaderError("the run header's fork must be a boolean");
+    }
+    if (header.mode === "plan" && header.schema === undefined) {
+        throw new RunHeaderError("a plan run names the schema its answer follows");
+    }
+}
+/** Whether `path` is `root` or inside it, with no `..` escaping it. */
+export function isUnder(path, root) {
+    if (!path.startsWith("/"))
+        return false;
+    const parts = [];
+    for (const part of path.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (parts.length === 0)
+                return false;
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    const normal = `/${parts.join("/")}`;
+    return normal === root || normal.startsWith(`${root}/`);
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@dynamicagents/plugins/sandbox` — a container whose disk is the checkout,
+ * driven from a Durable Object through `agents`' `ContainerHarness`.
+ *
+ * The README has the model. The daemon an image runs is the separate,
+ * Node-only `@dynamicagents/plugins/sandbox/daemon`.
+ */
+export { SandboxObjectBase, type CheckoutRecord, type ExecResult, type PolledMessage, type PollResult, type SandboxObjectConfig, type SnapshotSeed } from "./object.js";
+export { CONTROL_SESSION, CONTROL_WAKE, EGRESS_READY, RUN_DIR, SANDBOX_CONTRACT } from "./constants.js";
+export { readRunHeader, RUN_HEADER_PREFIX, RunHeaderError, SANDBOX_ROOT, withRunHeader, type RunHeader } from "./header.js";
+export { AGENT_GID, AGENT_HOME, AGENT_UID, agentEnv, asAgent } from "./agent-exec.js";
+export { sandboxName, sandboxNameFromRuntime, SANDBOX_RUNTIME_KEY } from "./name.js";
+export { DEFAULT_EXEC_TIMEOUT_MS, sandboxExec, type SandboxExecConfig, type SandboxExecHost } from "./exec.js";
+export { CREDENTIAL_HEADERS, egressPlan, forward, sandboxEgress, type EgressCall, type EgressPlan, type SandboxEgressRule } from "./egress.js";
+export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf, type AdvisoryAudience, type AdvisoryShape, type SandboxAdvisory } from "./advisory.js";
+export { DEFAULT_INSTALL_PLAN, resolveInstallCommand, type InstallPlan, type InstallRule, type InstallState } from "./install-plan.js";
+export { DirectoryBackupGateway } from "@cloudflare/sandbox";

package/dist/sandbox/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@dynamicagents/plugins/sandbox` — a container whose disk is the checkout,
+ * driven from a Durable Object through `agents`' `ContainerHarness`.
+ *
+ * The README has the model. The daemon an image runs is the separate,
+ * Node-only `@dynamicagents/plugins/sandbox/daemon`.
+ */
+export { SandboxObjectBase } from "./object.js";
+export { CONTROL_SESSION, CONTROL_WAKE, EGRESS_READY, RUN_DIR, SANDBOX_CONTRACT } from "./constants.js";
+export { readRunHeader, RUN_HEADER_PREFIX, RunHeaderError, SANDBOX_ROOT, withRunHeader } from "./header.js";
+export { AGENT_GID, AGENT_HOME, AGENT_UID, agentEnv, asAgent } from "./agent-exec.js";
+export { sandboxName, sandboxNameFromRuntime, SANDBOX_RUNTIME_KEY } from "./name.js";
+export { DEFAULT_EXEC_TIMEOUT_MS, sandboxExec } from "./exec.js";
+export { CREDENTIAL_HEADERS, egressPlan, forward, sandboxEgress } from "./egress.js";
+export { deriveAdvisories, renderAdvisory, sessionAdvisory, shapeOf } from "./advisory.js";
+export { DEFAULT_INSTALL_PLAN, resolveInstallCommand } from "./install-plan.js";
+export { DirectoryBackupGateway } from "@cloudflare/sandbox";

package/dist/{workspace/install.d.ts → sandbox/install-plan.d.ts}

@@ -184,7 +184,7 @@ export declare function resolveInstallCommand(fs: InstallProbe, dir: string, pla
  * A matching fingerprint means "the same install would produce the same tree".
  * It does **not** mean the tree is there: it is on the container's disk, and
  * goes with the container. The caller also needs a record that this container
- * finished it — see `./install-job.ts`.
+ * finished it — see `startInstall` in `./object.ts`.
  */
 export declare function installFingerprint(fs: InstallProbe, dir: string, resolution: InstallResolution): Promise<string | null>;
 /**
@@ -192,7 +192,7 @@ export declare function installFingerprint(fs: InstallProbe, dir: string, resolu
  * at it — a submodule a bootstrap installs, say — where there is no command to
  * fold in, and every lockfile the plan knows stands in for the one it would pick.
  *
- * For `./deps-snapshot.ts`, which restores every root's tree at once and so has
+ * For a caller restoring every root's tree at once from one snapshot, which has
  * to know none of them moved.
  */
 export declare function rootFingerprint(fs: InstallProbe, dir: string, plan: InstallPlan): Promise<string | null>;

package/dist/{workspace/install.js → sandbox/install-plan.js}

@@ -262,7 +262,7 @@ async function firstPresent(fs, dir, names) {
  * A matching fingerprint means "the same install would produce the same tree".
  * It does **not** mean the tree is there: it is on the container's disk, and
  * goes with the container. The caller also needs a record that this container
- * finished it — see `./install-job.ts`.
+ * finished it — see `startInstall` in `./object.ts`.
  */
 export async function installFingerprint(fs, dir, resolution) {
     if (resolution.kind !== "run")
@@ -283,7 +283,7 @@ export async function installFingerprint(fs, dir, resolution) {
  * at it — a submodule a bootstrap installs, say — where there is no command to
  * fold in, and every lockfile the plan knows stands in for the one it would pick.
  *
- * For `./deps-snapshot.ts`, which restores every root's tree at once and so has
+ * For a caller restoring every root's tree at once from one snapshot, which has
  * to know none of them moved.
  */
 export async function rootFingerprint(fs, dir, plan) {

package/dist/sandbox/name.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which sandbox a caller reaches: its name, and how a parent hands it to a
+ * sub-agent.
+ *
+ * One sandbox is one container is one repository, so a caller's sandboxes are
+ * keyed on the repository it works in. A module of its own, with no imports,
+ * because every path into a sandbox — a plugin's tools, a host's shell, a
+ * sub-agent's `prepare` — must spell it the same way.
+ */
+/**
+ * The Durable Object name for one caller's sandbox for one repository.
+ *
+ * A pipe rather than a slash, so the caller half cannot forge a repository
+ * boundary by containing one. `repo` may be a sentinel rather than a
+ * repository — a scratchpad, a worktree — as long as no caller could clone
+ * something that collides with it. Undefined is the window before a task has
+ * chosen one, which resolves to a caller-level sandbox nothing works in.
+ */
+export declare function sandboxName(callerKey: string, repo?: string): string;
+/** The key a parent's `prepare` puts a sub-agent's sandbox name under, in its `runtime()`. */
+export declare const SANDBOX_RUNTIME_KEY = "sandboxName";
+/**
+ * A parent-resolved sandbox name, read off a sub-agent's `runtime()`.
+ * `undefined` for anything else: a parent has no runtime, and falls back to its
+ * own name.
+ */
+export declare function sandboxNameFromRuntime(runtime: unknown): string | undefined;

package/dist/sandbox/name.js

@@ -0,0 +1,32 @@
+/**
+ * Which sandbox a caller reaches: its name, and how a parent hands it to a
+ * sub-agent.
+ *
+ * One sandbox is one container is one repository, so a caller's sandboxes are
+ * keyed on the repository it works in. A module of its own, with no imports,
+ * because every path into a sandbox — a plugin's tools, a host's shell, a
+ * sub-agent's `prepare` — must spell it the same way.
+ */
+/**
+ * The Durable Object name for one caller's sandbox for one repository.
+ *
+ * A pipe rather than a slash, so the caller half cannot forge a repository
+ * boundary by containing one. `repo` may be a sentinel rather than a
+ * repository — a scratchpad, a worktree — as long as no caller could clone
+ * something that collides with it. Undefined is the window before a task has
+ * chosen one, which resolves to a caller-level sandbox nothing works in.
+ */
+export function sandboxName(callerKey, repo) {
+    return repo ? `${callerKey}|${repo}` : `${callerKey}|<unassigned>`;
+}
+/** The key a parent's `prepare` puts a sub-agent's sandbox name under, in its `runtime()`. */
+export const SANDBOX_RUNTIME_KEY = "sandboxName";
+/**
+ * A parent-resolved sandbox name, read off a sub-agent's `runtime()`.
+ * `undefined` for anything else: a parent has no runtime, and falls back to its
+ * own name.
+ */
+export function sandboxNameFromRuntime(runtime) {
+    const value = runtime?.[SANDBOX_RUNTIME_KEY];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}