@exagone313/dsh-podman 0.2.0-rc.2

package/dist/mounts.test.js

@@ -0,0 +1,408 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { MOUNT_EXEC, MOUNT_TOOLS, guestExecRecorder, mountRequestRecorder, testReadSession, WORKSPACE_ID, } from "./test-support.js";
+import { TOOLS, approvalDecision, preExecutePolicy, summarizeArgs, toolHandlers } from "./index.js";
+import { forcedMountMode } from "./mount-enums.js";
+test("container_start approval depends on mounts being passed", () => {
+    const tool = TOOLS.find((entry) => entry.name === "container_start");
+    assert.ok(tool, "container_start registered");
+    assert.notEqual(tool.approval, true, "container_start must not always ask");
+    assert.ok(typeof tool.approvalWhen === "function", "container_start approvalWhen");
+    assert.equal(approvalDecision("container_start", { container: "web" }), undefined, "no mounts: must not ask");
+    assert.equal(approvalDecision("container_start", { container: "web", mounts: [] }), undefined, "empty mounts: must not ask");
+    const decision = approvalDecision("container_start", {
+        container: "web",
+        image: "localhost/dsh-podman/nginx:latest",
+        mounts: [
+            { project: "team/src", mode: "read_only" },
+            { project: "team", destination: "/workspace/team", mode: "read_write" },
+        ],
+    });
+    assert.ok(decision, "mounts passed: must ask");
+    assert.equal(decision.kind, "ask");
+    assert.equal(decision.reason, 'Start container "web" from image "localhost/dsh-podman/nginx:latest" with mounts: project "team/src" (read-only), project "team" at "/workspace/team" (read-write).');
+});
+test("summarizeArgs infers the mount target when kind is omitted", () => {
+    assert.equal(summarizeArgs("container_mount_remove", {
+        container: "valkey-ctr",
+        secret: "valkey-tls",
+    }), 'Remove mount from container "valkey-ctr": secret "valkey-tls".');
+    assert.equal(summarizeArgs("container_mount_add", {
+        container: "valkey-ctr",
+        volume: "valkey-data",
+    }), 'Add mount to container "valkey-ctr": volume "valkey-data" (read-only).');
+});
+test("preExecutePolicy denies project mounts that carry a destination", async () => {
+    const deny = (await preExecutePolicy({
+        name: "container_mount_add",
+        arguments: { kind: "project", project: "team/src", destination: "/custom" },
+    }, () => Promise.resolve({ kind: "allow" }), () => "/projects"));
+    assert.equal(deny.kind, "deny", "must deny instead of asking");
+    assert.equal(deny.reason, 'Project mounts cannot set a destination; "team/src" always mounts at "/projects/team/src".');
+    const startDeny = (await preExecutePolicy({
+        name: "container_start",
+        arguments: {
+            container: "web",
+            mounts: [
+                { project: "team", mode: "read_only" },
+                { kind: "project", project: "team", destination: "/x" },
+            ],
+        },
+    }, () => Promise.resolve({ kind: "allow" }), () => "/projects"));
+    assert.equal(startDeny.kind, "deny", "a mounts array with a project destination must deny");
+    const volumeAllowed = (await preExecutePolicy({
+        name: "container_mount_add",
+        arguments: { kind: "volume", volume: "data", destination: "/data" },
+    }, () => Promise.resolve({ kind: "ask", reason: "x" })));
+    assert.equal(volumeAllowed.kind, "ask", "non-project mounts with a destination must still ask");
+    const underNever = (await preExecutePolicy({
+        name: "container_mount_add",
+        arguments: { kind: "project", project: "team", destination: "/x" },
+        agent: { session: { facts: { policy: "never" } } },
+    }, () => Promise.resolve({ kind: "allow" }), () => "/projects", undefined, testReadSession));
+    assert.equal(underNever.kind, "deny", "full access must not accept an invalid project mount");
+});
+test("mount tools are registered with the expected schemas", () => {
+    const listTool = TOOLS.find((entry) => entry.name === "container_mount_list");
+    assert.ok(listTool, "container_mount_list registered");
+    assert.notEqual(listTool.approval, true, "container_mount_list must not require approval");
+    assert.deepEqual(listTool.parameters.required, ["container"]);
+    const addTool = TOOLS.find((entry) => entry.name === "container_mount_add");
+    assert.ok(addTool, "container_mount_add registered");
+    assert.equal(addTool.approval, true, "container_mount_add must require approval");
+    assert.deepEqual(addTool.parameters.required, ["container"]);
+    assert.deepEqual(addTool.parameters.properties.mode.enum, [
+        "read_only",
+        "read_write",
+    ]);
+    assert.deepEqual(addTool.parameters.properties.kind.enum, [
+        "project",
+        "tmpfs",
+        "volume",
+        "secret",
+    ]);
+    assert.equal(typeof addTool.parameters.properties.volume, "object", "container_mount_add accepts a volume");
+    assert.equal(typeof addTool.parameters.properties.secret, "object", "container_mount_add accepts a secret");
+    const removeTool = TOOLS.find((entry) => entry.name === "container_mount_remove");
+    assert.ok(removeTool, "container_mount_remove registered");
+    assert.equal(removeTool.approval, true, "container_mount_remove must require approval");
+    assert.deepEqual(removeTool.parameters.required, ["container"]);
+    assert.deepEqual(removeTool.parameters.properties.kind.enum, [
+        "project",
+        "tmpfs",
+        "volume",
+        "secret",
+    ]);
+    assert.equal(typeof removeTool.parameters.properties.volume, "object", "container_mount_remove accepts a volume");
+    assert.equal(typeof removeTool.parameters.properties.secret, "object", "container_mount_remove accepts a secret");
+    assert.equal(typeof removeTool.parameters.properties.destination, "object", "container_mount_remove accepts a destination");
+    const updateTool = TOOLS.find((entry) => entry.name === "container_mount_update");
+    assert.ok(updateTool, "container_mount_update registered");
+    assert.equal(updateTool.approval, true, "container_mount_update must require approval");
+    assert.deepEqual(updateTool.parameters.required, ["container", "mode"]);
+    assert.deepEqual(updateTool.parameters.properties.kind.enum, [
+        "project",
+        "volume",
+    ]);
+    assert.deepEqual(updateTool.parameters.properties.mode.enum, [
+        "read_only",
+        "read_write",
+    ]);
+    assert.equal(typeof updateTool.parameters.properties.destination, "object", "container_mount_update accepts a destination");
+});
+test("an omitted mount kind is inferred from the source field", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await toolHandlers.container_mount_remove(resolver, { container: "valkey-ctr", secret: "valkey-tls" }, MOUNT_EXEC);
+    await toolHandlers.container_mount_add(resolver, { container: "valkey-ctr", volume: "valkey-data", destination: "/data" }, MOUNT_EXEC);
+    assert.deepEqual(requests[0], [
+        "removeContainerMount",
+        {
+            workspaceSlug: WORKSPACE_ID,
+            container: "valkey-ctr",
+            kind: "MOUNT_KIND_SECRET",
+            secret: "valkey-tls",
+        },
+    ]);
+    assert.deepEqual(requests[1], [
+        "addContainerMount",
+        {
+            workspaceSlug: WORKSPACE_ID,
+            container: "valkey-ctr",
+            kind: "MOUNT_KIND_VOLUME",
+            volume: "valkey-data",
+            destination: "/data",
+            mode: "MOUNT_MODE_READ_ONLY",
+        },
+    ]);
+});
+test("container_mount_update maps the selector and mode", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await toolHandlers.container_mount_update(resolver, { container: "valkey-ctr", kind: "project", project: "team/src", mode: "read_only" }, MOUNT_EXEC);
+    await toolHandlers.container_mount_update(resolver, { container: "valkey-ctr", volume: "valkey-data", destination: "/data", mode: "read_write" }, MOUNT_EXEC);
+    assert.deepEqual(requests[0], [
+        "updateContainerMount",
+        {
+            workspaceSlug: WORKSPACE_ID,
+            container: "valkey-ctr",
+            kind: "MOUNT_KIND_PROJECT",
+            project: "team/src",
+            mode: "MOUNT_MODE_READ_ONLY",
+        },
+    ]);
+    assert.deepEqual(requests[1], [
+        "updateContainerMount",
+        {
+            workspaceSlug: WORKSPACE_ID,
+            container: "valkey-ctr",
+            kind: "MOUNT_KIND_VOLUME",
+            volume: "valkey-data",
+            destination: "/data",
+            mode: "MOUNT_MODE_READ_WRITE",
+        },
+    ]);
+});
+test("container_mount_update rejects kinds without a mode", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_mount_update(resolver, { container: "web", kind: "tmpfs", destination: "/mnt", mode: "read_only" }, MOUNT_EXEC), /only project and volume mounts carry a mode; tmpfs mounts cannot be remounted/);
+    await assert.rejects(() => toolHandlers.container_mount_update(resolver, { container: "web", project: "team", mode: "rw" }, MOUNT_EXEC), /unknown mount mode: rw/);
+    assert.deepEqual(requests, [], "a rejected update must not reach the orchestrator");
+});
+test("summarizeArgs renders the remount reason", () => {
+    assert.equal(summarizeArgs("container_mount_update", {
+        container: "valkey-ctr",
+        kind: "project",
+        project: "team",
+        mode: "read_only",
+    }), 'Update mount in container "valkey-ctr": remount project "team" to read-only.');
+    assert.equal(summarizeArgs("container_mount_update", {
+        container: "valkey-ctr",
+        volume: "data",
+        destination: "/data",
+        mode: "read_write",
+    }), 'Update mount in container "valkey-ctr": remount volume "data" at "/data" to read-write.');
+});
+test("container_mount_add rejects unknown mount kinds and modes", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_mount_add(resolver, { container: "web", kind: "bind", project: "team" }, MOUNT_EXEC), /unknown mount kind: bind/);
+    await assert.rejects(() => toolHandlers.container_mount_add(resolver, { container: "web", project: "team", mode: "rw" }, MOUNT_EXEC), /unknown mount mode: rw/);
+    assert.deepEqual(requests, [], "a rejected mount must not reach the orchestrator");
+});
+test("container_mount_add rejects a destination on a project mount", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_mount_add(resolver, { container: "web", kind: "project", project: "team/src", destination: "/custom" }, MOUNT_EXEC), /Project mounts cannot set a destination; "team\/src" always mounts at "\/projects\/team\/src"/);
+    await assert.rejects(() => toolHandlers.container_mount_add(resolver, { container: "web", project: "team", destination: "/custom" }, MOUNT_EXEC), /Project mounts cannot set a destination/);
+    assert.deepEqual(requests, [], "a rejected mount must not reach the orchestrator");
+    await toolHandlers.container_mount_add(resolver, { container: "web", kind: "volume", volume: "data", destination: "/data" }, MOUNT_EXEC);
+    assert.equal(requests.length, 1, "a volume mount with a destination is still accepted");
+});
+test("container_start rejects a destination on a project mount", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_start(resolver, {
+        container: "web",
+        image: "img1",
+        mounts: [{ project: "team", destination: "/custom" }],
+    }, MOUNT_EXEC), /Project mounts cannot set a destination/);
+    assert.deepEqual(requests, [], "a rejected mount must not reach the orchestrator");
+});
+test("container_mount_remove rejects unknown mount kinds", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_mount_remove(resolver, { container: "web", kind: "bind", project: "team" }, MOUNT_EXEC), /unknown mount kind: bind/);
+    assert.deepEqual(requests, [], "a rejected mount must not reach the orchestrator");
+});
+test("adding a tmpfs mount without a mode stays read_write", async () => {
+    // The orchestrator rejects a read-only tmpfs, so the read-only default must
+    // not apply to it.
+    const { requests, resolver } = mountRequestRecorder();
+    await toolHandlers.container_mount_add(resolver, { container: "web", kind: "tmpfs", destination: "/scratch" }, MOUNT_EXEC);
+    assert.deepEqual(requests, [
+        ["addContainerMount", {
+                workspaceSlug: WORKSPACE_ID,
+                container: "web",
+                kind: "MOUNT_KIND_TMPFS",
+                destination: "/scratch",
+                mode: "MOUNT_MODE_READ_WRITE",
+            }],
+    ]);
+});
+test("mount tools default a missing kind to project and a missing mode to read_only", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await toolHandlers.container_mount_add(resolver, { container: "web", project: "team" }, MOUNT_EXEC);
+    await toolHandlers.container_mount_add(resolver, {
+        container: "web",
+        kind: "volume",
+        volume: "valkey-data",
+        destination: "/data",
+        mode: "read_only",
+    }, MOUNT_EXEC);
+    await toolHandlers.container_mount_remove(resolver, { container: "web", project: "team" }, MOUNT_EXEC);
+    assert.deepEqual(requests, [
+        ["addContainerMount", {
+                workspaceSlug: WORKSPACE_ID,
+                container: "web",
+                kind: "MOUNT_KIND_PROJECT",
+                project: "team",
+                mode: "MOUNT_MODE_READ_ONLY",
+            }],
+        ["addContainerMount", {
+                workspaceSlug: WORKSPACE_ID,
+                container: "web",
+                kind: "MOUNT_KIND_VOLUME",
+                volume: "valkey-data",
+                destination: "/data",
+                mode: "MOUNT_MODE_READ_ONLY",
+            }],
+        ["removeContainerMount", {
+                workspaceSlug: WORKSPACE_ID,
+                container: "web",
+                kind: "MOUNT_KIND_PROJECT",
+                project: "team",
+            }],
+    ]);
+});
+test("container start and recreate reject unknown mount kinds and modes", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await assert.rejects(() => toolHandlers.container_start(resolver, { container: "web", mounts: [{ project: "team", kind: "bind" }] }, MOUNT_EXEC), /unknown mount kind: bind/);
+    await assert.rejects(() => toolHandlers.container_recreate(resolver, { container: "web", mounts: [{ project: "team", mode: "rw" }] }, MOUNT_EXEC), /unknown mount mode: rw/);
+    assert.deepEqual(requests, [], "a rejected mount must not reach the orchestrator");
+});
+test("container start maps valid mounts and defaults the mode to read_only", async () => {
+    const { requests, resolver } = mountRequestRecorder();
+    await toolHandlers.container_start(resolver, {
+        container: "web",
+        image: "img1",
+        mounts: [
+            { project: "team/src", mode: "read_only" },
+            { project: "team", mode: "read_write" },
+            { kind: "volume", volume: "valkey-data", destination: "/data" },
+            { kind: "secret", secret: "valkey-tls", destination: "/run/secrets/tls" },
+            { kind: "tmpfs", destination: "/scratch" },
+        ],
+    }, MOUNT_EXEC);
+    assert.deepEqual(requests, [
+        ["startContainer", {
+                workspaceSlug: WORKSPACE_ID,
+                container: "web",
+                imageId: "img1",
+                mounts: [
+                    {
+                        projectName: "team/src",
+                        kind: "MOUNT_KIND_PROJECT",
+                        mode: "MOUNT_MODE_READ_ONLY",
+                    },
+                    {
+                        projectName: "team",
+                        kind: "MOUNT_KIND_PROJECT",
+                        mode: "MOUNT_MODE_READ_WRITE",
+                    },
+                    {
+                        projectName: "",
+                        kind: "MOUNT_KIND_VOLUME",
+                        mode: "MOUNT_MODE_READ_ONLY",
+                        destination: "/data",
+                        volume: "valkey-data",
+                    },
+                    {
+                        projectName: "",
+                        kind: "MOUNT_KIND_SECRET",
+                        mode: "MOUNT_MODE_READ_ONLY",
+                        destination: "/run/secrets/tls",
+                        secret: "valkey-tls",
+                    },
+                    {
+                        projectName: "",
+                        kind: "MOUNT_KIND_TMPFS",
+                        mode: "MOUNT_MODE_READ_WRITE",
+                        destination: "/scratch",
+                    },
+                ],
+            }],
+    ]);
+});
+test("mount schemas are object-rooted without per-property required", () => {
+    for (const name of MOUNT_TOOLS) {
+        const tool = TOOLS.find((entry) => entry.name === name);
+        assert.ok(tool, `${name} registered`);
+        assert.equal(tool.parameters.type, "object", `${name} type`);
+        assert.equal(typeof tool.parameters.properties, "object");
+        assert.ok(Array.isArray(tool.parameters.required));
+        for (const key of Object.keys(tool.parameters.properties)) {
+            const property = tool.parameters.properties[key];
+            assert.ok(!Object.prototype.hasOwnProperty.call(property, "required"), `${name}.${key} must not carry per-property required`);
+        }
+    }
+    for (const name of ["container_start", "container_recreate"]) {
+        const tool = TOOLS.find((entry) => entry.name === name);
+        assert.ok(tool, `${name} registered`);
+        const mounts = tool.parameters.properties.mounts;
+        assert.equal(mounts.type, "array", `${name}.mounts type`);
+        assert.equal(mounts.items.type, "object", `${name}.mounts items type`);
+        assert.equal(mounts.items.additionalProperties, false);
+        assert.deepEqual(mounts.items.required, []);
+        for (const key of Object.keys(mounts.items.properties)) {
+            const property = mounts.items.properties[key];
+            assert.ok(!Object.prototype.hasOwnProperty.call(property, "required"), `${name}.mounts.items.${key} must not carry per-property required`);
+        }
+    }
+});
+test("container_mount_list returns mount objects", async () => {
+    const resolver = {
+        registry: {
+            resolveByPath: async () => ({ id: WORKSPACE_ID }),
+        },
+        control: async () => ({
+            containers: [
+                {
+                    workspaceSlug: WORKSPACE_ID,
+                    containerName: "default",
+                    mounts: [
+                        { projectName: "team", mode: "MOUNT_MODE_READ_WRITE", kind: "MOUNT_KIND_PROJECT" },
+                        { volume: "myvol", destination: "/data", mode: "MOUNT_MODE_READ_ONLY", kind: "MOUNT_KIND_VOLUME" },
+                    ],
+                },
+            ],
+        }),
+    };
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const out = await toolHandlers.container_mount_list(resolver, { container: "default" }, exec);
+    assert.deepEqual(out, [
+        { projectName: "team", mode: "read_write", kind: "project" },
+        { volume: "myvol", destination: "/data", mode: "read_only", kind: "volume" },
+    ]);
+});
+test("command tools default to the session directory when mounted", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const bash = guestExecRecorder("/projects/team");
+    await toolHandlers.container_bash(bash.resolver, { container: "default", command: "ls" }, exec);
+    assert.equal(bash.starts[0].cwd, "/projects/team");
+    const run = guestExecRecorder("/projects/team");
+    await toolHandlers.container_exec(run.resolver, { container: "default", argv: ["ls"] }, exec);
+    assert.equal(run.starts[0].cwd, "/projects/team");
+    const glob = guestExecRecorder("/projects/team");
+    await toolHandlers.container_glob(glob.resolver, { container: "default", pattern: "*.ts" }, exec);
+    assert.equal(glob.starts[0].cwd, "/projects/team");
+    const grep = guestExecRecorder("/projects/team");
+    await toolHandlers.container_grep(grep.resolver, { container: "default", pattern: "TODO" }, exec);
+    assert.equal(grep.starts[0].cwd, "/projects/team");
+});
+test("command tools fall back to the guest cwd when the session directory is not mounted", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const bare = guestExecRecorder();
+    await toolHandlers.container_exec(bare.resolver, { container: "db", argv: ["ls"] }, exec);
+    assert.equal(bare.starts[0].cwd, undefined);
+    // An explicit working directory still resolves without a mounted default.
+    const explicit = guestExecRecorder();
+    await toolHandlers.container_exec(explicit.resolver, { container: "db", argv: ["ls"], workdir: "/data" }, exec);
+    assert.equal(explicit.starts[0].cwd, "/data");
+});
+test("forcedMountMode fixes tmpfs and secret and leaves project and volume editable", () => {
+    // The orchestrator rejects a read-only tmpfs and exposes secrets read-only,
+    // so the card shows those two as a fixed mode.
+    assert.equal(forcedMountMode("tmpfs"), "read_write");
+    assert.equal(forcedMountMode("secret"), "read_only");
+    assert.equal(forcedMountMode("project"), undefined);
+    assert.equal(forcedMountMode("volume"), undefined);
+    assert.equal(forcedMountMode(undefined), undefined);
+});

package/dist/output-reader.d.ts

@@ -0,0 +1,34 @@
+export declare const SPILL_ROOT = "/tmp/dsh-podman";
+interface SpillSpec {
+    path: string;
+    maxBytes: number;
+}
+export interface OutputReader {
+    append(data: Buffer): void;
+    readFrom(offset: number): {
+        text: string;
+        nextOffset: number;
+        lossy: boolean;
+        spillPath?: string;
+    };
+    setSpillValid(valid: boolean): void;
+    readonly spillPath: string | undefined;
+    readonly spillNeeded: boolean;
+}
+export declare function outputReader(mode: unknown, spill?: SpillSpec): OutputReader | undefined;
+export declare function spillTargetFor(mode: unknown, label: string): {
+    target?: {
+        path: string;
+        maxBytes: number;
+    };
+    spec?: SpillSpec;
+};
+export declare function splitEnv(env: unknown): {
+    env: Record<string, string>;
+    unsetEnv: string[];
+};
+export declare function discardUnneededSpill(binding: {
+    guest: any;
+    token: string;
+}, reader: OutputReader | undefined): void;
+export {};

package/dist/output-reader.js

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { unaryGuest } from "./guest-rpc.js";
+import { randomUUID } from "node:crypto";
+// The container-local directory the orchestrator mounts read-write for
+// command-output spill files. Must match the orchestrator's `spillRoot`.
+export const SPILL_ROOT = "/tmp/dsh-podman";
+export function outputReader(mode, spill) {
+    if (typeof mode !== "object" || mode === null)
+        return undefined;
+    const maxBytes = Number(mode.maxBytes);
+    if (!Number.isFinite(maxBytes) || maxBytes < 0)
+        return undefined;
+    let total = 0;
+    let retained = Buffer.alloc(0);
+    let spillValid = spill !== undefined;
+    return {
+        append(data) {
+            total += data.length;
+            retained = Buffer.concat([retained, data]).subarray(-maxBytes);
+        },
+        readFrom(offset) {
+            const start = Math.max(0, total - retained.length);
+            const requested = Math.max(0, Number.isFinite(offset) ? offset : 0);
+            const local = Math.max(0, requested - start);
+            const lossy = requested < start;
+            return {
+                text: retained.subarray(local).toString("utf8"),
+                nextOffset: total,
+                lossy,
+                // Advertise the full-stream file only while it can still hold the
+                // complete stream, matching the local backend's reader.
+                ...(lossy &&
+                    spill !== undefined &&
+                    spillValid &&
+                    total <= spill.maxBytes
+                    ? { spillPath: spill.path }
+                    : {}),
+            };
+        },
+        setSpillValid(valid) {
+            spillValid = valid;
+        },
+        get spillPath() {
+            return spill?.path;
+        },
+        get spillNeeded() {
+            return total > maxBytes;
+        },
+    };
+}
+// spillTargetFor builds the guest spill request for one collect-mode stream, or
+// an empty object when the mode requests no spill.
+export function spillTargetFor(mode, label) {
+    const spill = mode?.spill;
+    const maxBytes = Number(spill?.maxBytes);
+    if (!Number.isFinite(maxBytes) || maxBytes <= 0)
+        return {};
+    const path = `${SPILL_ROOT}/${randomUUID()}.${label}`;
+    return { target: { path, maxBytes }, spec: { path, maxBytes } };
+}
+// splitEnv separates the harness's explicit environment entries from its
+// `undefined` tombstones, which a proto string map cannot carry.
+export function splitEnv(env) {
+    const set = {};
+    const unsetEnv = [];
+    if (typeof env === "object" && env !== null) {
+        for (const [key, value] of Object.entries(env)) {
+            if (value === undefined)
+                unsetEnv.push(key);
+            else
+                set[key] = String(value);
+        }
+    }
+    return { env: set, unsetEnv };
+}
+// discardUnneededSpill removes a spill the in-memory tail already covered. A
+// valid spill that holds output the tail dropped stays for the caller to read,
+// and an incomplete one was already removed by the guest.
+export function discardUnneededSpill(binding, reader) {
+    if (reader === undefined || reader.spillPath === undefined)
+        return;
+    if (reader.spillNeeded)
+        return;
+    void unaryGuest({ binding }, "delete", { path: reader.spillPath, recursive: false }).catch(() => { });
+}

package/dist/paths.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/paths.test.js

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { pathRequestRecorder, WORKSPACE_ID } from "./test-support.js";
+import { TOOLS, summarizeArgs, toolHandlers } from "./index.js";
+const EXEC = { agent: { session: { header: { cwd: "/proj" } } } };
+test("the path tools are registered and approval-gated", () => {
+    for (const name of [
+        "container_path_set",
+        "container_path_add",
+        "container_path_remove",
+    ]) {
+        const tool = TOOLS.find((entry) => entry.name === name);
+        assert.ok(tool, `${name} registered`);
+        assert.equal(tool.approval, true, `${name} must require approval`);
+        assert.ok(tool.parameters.required.includes("container"), `${name} requires container`);
+    }
+    assert.deepEqual(TOOLS.find((entry) => entry.name === "container_path_set").parameters
+        .required, ["container", "paths"]);
+    assert.deepEqual(TOOLS.find((entry) => entry.name === "container_path_add").parameters
+        .required, ["container", "path"]);
+});
+test("container_path_set persists and applies the whole list", async () => {
+    const { controlCalls, setCalls, resolver } = pathRequestRecorder();
+    const out = await toolHandlers.container_path_set(resolver, { container: "default", paths: ["/opt/bin", "/usr/local/bin"] }, EXEC);
+    assert.deepEqual(controlCalls, [
+        [
+            "setContainerPaths",
+            {
+                workspaceSlug: WORKSPACE_ID,
+                container: "default",
+                paths: ["/opt/bin", "/usr/local/bin"],
+            },
+        ],
+    ]);
+    assert.deepEqual(setCalls, [["/opt/bin", "/usr/local/bin"]]);
+    assert.deepEqual(out, { paths: ["/opt/bin", "/usr/local/bin"] });
+});
+test("container_path_add prepends and moves an existing entry to the front", async () => {
+    const { controlCalls, resolver } = pathRequestRecorder({ paths: ["/a", "/b"] });
+    const added = await toolHandlers.container_path_add(resolver, { container: "default", path: "/c" }, EXEC);
+    assert.deepEqual(added, { paths: ["/c", "/a", "/b"] });
+    const moved = await toolHandlers.container_path_add(resolver, { container: "default", path: "/b" }, EXEC);
+    assert.deepEqual(moved, { paths: ["/b", "/c", "/a"] });
+    assert.equal(controlCalls.length, 2);
+});
+test("container_path_remove removes an added path", async () => {
+    const { resolver } = pathRequestRecorder({ paths: ["/a", "/b"] });
+    const out = await toolHandlers.container_path_remove(resolver, { container: "default", path: "/a" }, EXEC);
+    assert.deepEqual(out, { paths: ["/b"] });
+});
+test("container_path_remove distinguishes a default path from an unknown one", async () => {
+    const { controlCalls, resolver } = pathRequestRecorder({
+        paths: ["/a"],
+        defaultPath: "/usr/bin:/bin",
+    });
+    await assert.rejects(() => toolHandlers.container_path_remove(resolver, { container: "default", path: "/usr/bin" }, EXEC), /is part of the container's default PATH and cannot be removed/);
+    await assert.rejects(() => toolHandlers.container_path_remove(resolver, { container: "default", path: "/nope" }, EXEC), /is not an added path/);
+    assert.deepEqual(controlCalls, [], "a rejected removal must not reach the orchestrator");
+});
+test("summarizeArgs renders the PATH reasons", () => {
+    assert.equal(summarizeArgs("container_path_set", {
+        container: "web",
+        paths: ["/opt/bin", "/usr/local/bin"],
+    }), 'Set the PATH additions of container "web": "/opt/bin", "/usr/local/bin".');
+    assert.equal(summarizeArgs("container_path_set", { container: "web", paths: [] }), 'Set the PATH additions of container "web": (none).');
+    assert.equal(summarizeArgs("container_path_add", { container: "web", path: "/opt/bin" }), 'Add "/opt/bin" to the PATH of container "web".');
+    assert.equal(summarizeArgs("container_path_remove", {
+        container: "web",
+        path: "/opt/bin",
+    }), 'Remove "/opt/bin" from the PATH of container "web".');
+});

package/dist/preferences.d.ts

@@ -0,0 +1,6 @@
+import { type WorkspaceResolver } from "./workspace-binding.js";
+/**
+ * Register the plugin's preferences namespace and keep the resolver's config in
+ * step with the user's choices.
+ */
+export declare function installContainerPreferences(ctx: any, resolver: WorkspaceResolver): void;

package/dist/preferences.js

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// The plugin's real preferences (default image, sockets root, and the browser
+// locale) live in the settings namespace; everything derived from the
+// orchestrator travels over the card route (see card-route.ts).
+import { CONTAINER_NS, settingsSchema, } from "./settings-schema.js";
+/**
+ * Register the plugin's preferences namespace and keep the resolver's config in
+ * step with the user's choices.
+ */
+export function installContainerPreferences(ctx, resolver) {
+    ctx.inject(["settings"], (sctx) => {
+        const scope = sctx.settings.register(CONTAINER_NS, settingsSchema, {
+            base: {
+                defaultImage: resolver.getConfig().defaultImage,
+                socketsRoot: resolver.getConfig().socketsRoot,
+            },
+        });
+        scope.watch((next) => {
+            resolver.setConfig({
+                defaultImage: next.defaultImage,
+                socketsRoot: next.socketsRoot,
+            });
+        });
+    });
+}

package/dist/project-path.d.ts

@@ -0,0 +1,6 @@
+export declare function projectNameFromHostPath(projectsRoot: string, path: string): string | undefined;
+export declare function hostPathForProjectName(projectsRoot: string, project: string): string;
+export declare function confineToRoot(root: string, path: string): string;
+export declare function parentDirectory(root: string, path: string): string;
+export declare function rootCrumbs(root: string, path: string): string[];
+export declare function crumbLabel(path: string): string;