@exagone313/dsh-podman 0.2.0-rc.2

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export declare const name = "podman";
+export declare const inject: string[];
+export interface PluginConfig {
+    socketsRoot?: string;
+    defaultImage?: string;
+    projectsRoot?: string;
+    controlToken?: string;
+    imagePrefix?: string;
+}
+export declare function apply(ctx: any, config?: PluginConfig): void;
+export { PODMAN_OPS_APPROVAL_TOOLS, PODMAN_OPS_PRESET, READ_ONLY_TOOLS, SANDBOX_ESCALATION_REASON_PREFIX, approvalDecision, isSandboxEscalation, mountDestinationsReason, preExecutePolicy, summarizeArgs, } from "./approval.js";
+export type { SessionFacts } from "./approval.js";
+export { READ_ONLY_GATED_TOOLS, REMOUNT_TOOL_NAME, createReadOnlyShellGate, } from "./read-only-shell.js";
+export { FilesystemProvider, createFilesystemProvider } from "./fs-provider.js";
+export { resolveGuestCwd, resolveGuestPath, remoteArgv, globCwd } from "./guest-rpc.js";
+export { inferMountKind, projectMountDestinationReason, projectMountMirror, } from "./mount-input.js";
+export { HARNESS_SOURCE_SECTION, PODMAN_OPS_AGENT_CORDIS_YML, PODMAN_OPS_PRESET_YML, ensurePodmanOpsPreset, homePresetsRoot, podmanRuntimeSection, withoutHarnessSourceSection, } from "./prompts.js";
+export { publicContainer, publicDaemon, publicImage, publicMount } from "./public.js";
+export { OutputReader, SubprocessProvider, createSubprocessProvider, outputReader, } from "./subprocess.js";
+export { toolHandlers } from "./tool-handlers.js";
+export { TOOLS, ToolDefinition, containerBashParameters, containerEditParameters, containerExecParameters, containerGlobParameters, containerGrepParameters, containerListParameters, containerMountAddParameters, containerMountListParameters, containerMountRemoveParameters, containerReadParameters, containerRecreateParameters, containerRemoveParameters, containerSecretAddParameters, containerSecretRemoveParameters, containerStartParameters, containerWriteParameters, daemonListParameters, daemonLogsParameters, daemonRestartParameters, daemonStartParameters, daemonStopParameters, defineTool, envParam, imageBuildParameters, imageGetParameters, imageListParameters, imageRebuildAllParameters, imageRebuildParameters, imageRemoveParameters, secretCreateParameters, secretListParameters, secretRemoveParameters, toolOutput, volumeCreateParameters, volumeListParameters, volumeRemoveParameters, } from "./tool-schemas.js";
+export { toolCallView, toolResultView } from "./tool-views.js";

package/dist/index.js

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { isSandboxEscalation, preExecutePolicy } from "./approval.js";
+import { resolveReasonLocale } from "./approval-reasons.js";
+import { createFilesystemProvider } from "./fs-provider.js";
+import { createSpillStore } from "./spill-store.js";
+import { ensurePodmanOpsPreset, podmanRuntimeSection, withoutHarnessSourceSection, } from "./prompts.js";
+import { createSubprocessProvider } from "./subprocess.js";
+import { createReadOnlyShellGate, REMOUNT_TOOL_NAME } from "./read-only-shell.js";
+import { toolHandlers } from "./tool-handlers.js";
+import { TOOLS, TOOL_DESCRIPTIONS, defineTool, toolOutput } from "./tool-schemas.js";
+import { toolCallView, toolResultView } from "./tool-views.js";
+import { installContainerPreferences } from "./preferences.js";
+import { registerCardRoute } from "./card-route.js";
+import { WorkspaceResolver, normalizeToolError } from "./workspace-binding.js";
+function withTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+export const name = "podman";
+export const inject = ["tools", "workspaceRegistry"];
+export function apply(ctx, config = {}) {
+    // Approval text follows the session language: the browser client records its
+    // active locale in the plugin namespace, with the durable user preference as
+    // the fallback. Without a settings provider everything renders in English.
+    let readLocale = () => "en";
+    ctx.inject(["settings"], (settingsCtx) => {
+        readLocale = () => resolveReasonLocale(settingsCtx.settings);
+    });
+    // The session's permission knobs live in the harness's own services: the
+    // sandbox policy resolves the effective mode (approved override, last logged
+    // mode, then the deployment default), the approval service reports the logged
+    // policy override, and the agent-preset projection reports the preset the
+    // session currently runs (its header only names the creation-time one).
+    const readSession = (session) => ({
+        mode: ctx.get("sandboxPolicy")?.resolve({ session })?.mode,
+        // The deployment default is private, so an unset override conservatively
+        // keeps asking.
+        policy: ctx.get("approval")?.overrideOf(session) ?? "ask",
+        preset: ctx.get("sessionProjections")?.stateOf(session, "agentPreset") ??
+            session?.header?.agentPreset,
+    });
+    // The read-only shell gate needs the resolver, which is created below, so it
+    // is built on first use. Under read-only permission it re-checks the target
+    // container's mounts and, when a read-write mount would block the tool, asks
+    // the user (through the approval service) to remount them read-only.
+    let readOnlyShell;
+    const readOnlyShellGate = () => (readOnlyShell ??= createReadOnlyShellGate({
+        resolver,
+        approve: async (exec, reason) => {
+            const approval = ctx.get("approval");
+            if (approval === undefined || exec?.agent === undefined)
+                return false;
+            try {
+                const outcome = await approval.request({
+                    agent: exec.agent,
+                    toolName: REMOUNT_TOOL_NAME,
+                    ...(exec.callId !== undefined ? { callId: exec.callId } : {}),
+                    ...(exec.signal !== undefined ? { signal: exec.signal } : {}),
+                    reason,
+                });
+                return outcome === "allowed-once";
+            }
+            catch {
+                // A request that cannot be raised (no open turn, no channel) fails
+                // closed, exactly like a rejection.
+                return false;
+            }
+        },
+    }));
+    ctx.on("tools/pre-execute", (exec, next) => preExecutePolicy(exec, next, () => resolver.getConfig().projectsRoot, () => readLocale(), readSession, readOnlyShellGate()));
+    // The harness asks the user to widen the sandbox before a confined call (for
+    // example `bash` with `sandbox_permissions`). This deployment bypasses the
+    // sandbox inside the container, so the grant changes nothing: claim the
+    // request so a stray `sandbox_permissions` argument raises no prompt. The
+    // listener is prepended so it runs before the bridge that forwards approvals
+    // to the browser, and it delegates everything else.
+    ctx.on("approval/request", (request, next) => isSandboxEscalation(request) ? Promise.resolve("allowed-once") : next(), { prepend: true });
+    ensurePodmanOpsPreset(ctx);
+    const imagePrefix = withTrailingSlash(config.imagePrefix ?? process.env.DSH_PODMAN_IMAGE_PREFIX ?? "localhost/dsh-podman/");
+    const resolver = new WorkspaceResolver({
+        socketsRoot: config.socketsRoot ??
+            process.env.DSH_PODMAN_SOCKETS_ROOT ??
+            "/run/dsh-podman",
+        defaultImage: config.defaultImage ?? "archlinux",
+        projectsRoot: config.projectsRoot ??
+            process.env.DSH_PODMAN_PROJECTS_ROOT ??
+            "/projects",
+        controlToken: config.controlToken ?? process.env.DSH_PODMAN_ORCHESTRATOR_TOKEN ?? "",
+    }, ctx.workspaceRegistry);
+    ctx.provide("workspaceResolver", resolver);
+    const subprocess = createSubprocessProvider(resolver);
+    ctx.provide("subprocess", subprocess);
+    ctx.effect(() => () => subprocess.dispose(), "podman: subprocess cleanup");
+    ctx.provide("fs", createFilesystemProvider(resolver));
+    // Oversized tool results spill inside the session's container, so the agent
+    // can read them back with the container file tools; the harness's local
+    // (host-filesystem) spill backend is disabled by the bundle patch.
+    ctx.provide("spillStore", createSpillStore(ctx, resolver));
+    ctx.inject(["systemPrompt"], (promptCtx) => {
+        promptCtx.systemPrompt.section(podmanRuntimeSection(promptCtx));
+        promptCtx.on("system-prompt/assemble", async (_assembly, _context, next) => withoutHarnessSourceSection(await next()), { global: true, prepend: true });
+    });
+    registerTools(ctx, resolver);
+    installContainerPreferences(ctx, resolver);
+    registerCardRoute(ctx, resolver, ctx.workspaceRegistry);
+}
+function registerTools(ctx, resolver) {
+    for (const tool of TOOLS) {
+        const handler = toolHandlers[tool.name];
+        ctx.tools.register(defineTool({
+            name: tool.name,
+            description: TOOL_DESCRIPTIONS[tool.name],
+            parameters: tool.parameters,
+            ...(tool.approval ? { approval: true } : {}),
+            presentCall: (args) => toolCallView(tool.name, args),
+            presentResult: (args, result) => toolResultView(tool.name, args, result),
+            output: toolOutput,
+            execute: async (input, exec) => {
+                try {
+                    return JSON.stringify(await handler(resolver, input, exec, ctx));
+                }
+                catch (error) {
+                    throw normalizeToolError(error);
+                }
+            },
+        }));
+    }
+}
+export { PODMAN_OPS_APPROVAL_TOOLS, PODMAN_OPS_PRESET, READ_ONLY_TOOLS, SANDBOX_ESCALATION_REASON_PREFIX, approvalDecision, isSandboxEscalation, mountDestinationsReason, preExecutePolicy, summarizeArgs, } from "./approval.js";
+export { READ_ONLY_GATED_TOOLS, REMOUNT_TOOL_NAME, createReadOnlyShellGate, } from "./read-only-shell.js";
+export { createFilesystemProvider } from "./fs-provider.js";
+export { resolveGuestCwd, resolveGuestPath, remoteArgv, globCwd } from "./guest-rpc.js";
+export { inferMountKind, projectMountDestinationReason, projectMountMirror, } from "./mount-input.js";
+export { HARNESS_SOURCE_SECTION, PODMAN_OPS_AGENT_CORDIS_YML, PODMAN_OPS_PRESET_YML, ensurePodmanOpsPreset, homePresetsRoot, podmanRuntimeSection, withoutHarnessSourceSection, } from "./prompts.js";
+export { publicContainer, publicDaemon, publicImage, publicMount } from "./public.js";
+export { createSubprocessProvider, outputReader, } from "./subprocess.js";
+export { toolHandlers } from "./tool-handlers.js";
+export { TOOLS, containerBashParameters, containerEditParameters, containerExecParameters, containerGlobParameters, containerGrepParameters, containerListParameters, containerMountAddParameters, containerMountListParameters, containerMountRemoveParameters, containerReadParameters, containerRecreateParameters, containerRemoveParameters, containerSecretAddParameters, containerSecretRemoveParameters, containerStartParameters, containerWriteParameters, daemonListParameters, daemonLogsParameters, daemonRestartParameters, daemonStartParameters, daemonStopParameters, defineTool, envParam, imageBuildParameters, imageGetParameters, imageListParameters, imageRebuildAllParameters, imageRebuildParameters, imageRemoveParameters, secretCreateParameters, secretListParameters, secretRemoveParameters, toolOutput, volumeCreateParameters, volumeListParameters, volumeRemoveParameters, } from "./tool-schemas.js";
+export { toolCallView, toolResultView } from "./tool-views.js";

package/dist/misc.test.d.ts

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

package/dist/misc.test.js

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { fakeToolContext, guestExecRecorder, guestFileRecorder } from "./test-support.js";
+import { HARNESS_SOURCE_SECTION, TOOLS, toolCallView, toolHandlers, toolResultView, withoutHarnessSourceSection, } from "./index.js";
+test("every tool parameters is a valid JSON-Schema object", () => {
+    for (const tool of TOOLS) {
+        assert.equal(tool.parameters.type, "object", `${tool.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"), `${tool.name}.${key} must not carry per-property required`);
+            assert.ok(!Array.isArray(property.required), `${tool.name}.${key} must not carry a required array`);
+        }
+    }
+});
+test("file tools resolve relative paths against the session cwd", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const read = guestFileRecorder();
+    await toolHandlers.container_read(read.resolver, { container: "default", file_path: "README.md" }, exec, fakeToolContext(read.resolver));
+    assert.deepEqual(read.reads, ["/projects/team/README.md"]);
+    const absolute = guestFileRecorder();
+    await toolHandlers.container_read(absolute.resolver, { container: "default", file_path: "/etc/hosts" }, exec, fakeToolContext(absolute.resolver));
+    assert.deepEqual(absolute.reads, ["/etc/hosts"], "absolute paths pass through");
+    const write = guestFileRecorder();
+    await toolHandlers.container_write(write.resolver, { container: "default", file_path: "out.txt", content: "x" }, exec, fakeToolContext(write.resolver));
+    assert.deepEqual(write.writes.map((entry) => entry.path), ["/projects/team/out.txt"]);
+    const edit = guestFileRecorder("hello");
+    await toolHandlers.container_edit(edit.resolver, { container: "default", file_path: "a.txt", old_string: "hello", new_string: "bye" }, exec, fakeToolContext(edit.resolver));
+    assert.deepEqual(edit.reads, ["/projects/team/a.txt"]);
+    assert.deepEqual(edit.writes.map((entry) => entry.path), ["/projects/team/a.txt"]);
+});
+test("file tools refuse traversal before reaching the guest", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const { reads, writes, resolver } = guestFileRecorder();
+    for (const path of ["../escape", "a/../../b"]) {
+        await assert.rejects(() => toolHandlers.container_read(resolver, { container: "default", file_path: path }, exec, fakeToolContext(resolver)), /must not escape/);
+    }
+    await assert.rejects(() => toolHandlers.container_write(resolver, { container: "default", file_path: "../escape", content: "x" }, exec, fakeToolContext(resolver)), /must not escape/);
+    assert.deepEqual(reads, [], "a refused path must not reach the guest");
+    assert.deepEqual(writes, []);
+});
+test("tool presenters label every tool and render terminal commands", () => {
+    for (const tool of TOOLS) {
+        assert.notEqual(toolCallView(tool.name, {}), undefined, `${tool.name} has a call view`);
+    }
+    assert.deepEqual(toolCallView("container_bash", { command: "ls", description: "List files" }), { card: "terminal", title: "ls", description: "List files" });
+    assert.deepEqual(toolCallView("container_exec", { argv: ["ls", "-la"], description: "List all" }), { card: "terminal", title: "ls -la", description: "List all" });
+    assert.deepEqual(toolCallView("image_list", {}), { card: "generic", title: "List images", kind: "search" });
+    assert.deepEqual(toolCallView("container_read", {}), { card: "generic", title: "Container read", kind: "read" });
+    assert.deepEqual(toolCallView("container_write", {}), { card: "generic", title: "Container write", kind: "edit" });
+    assert.deepEqual(toolCallView("container_edit", {}), { card: "generic", title: "Container edit", kind: "edit" });
+    assert.deepEqual(toolCallView("container_glob", {}), { card: "generic", title: "Container glob", kind: "search" });
+    assert.deepEqual(toolCallView("container_grep", {}), { card: "generic", title: "Container grep", kind: "search" });
+});
+test("tool presenters render command results as terminal output", () => {
+    const result = (value) => ({
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        isError: false,
+    });
+    assert.deepEqual(toolResultView("container_bash", {}, result({ exitCode: 0, signal: null, stdout: "hi\n", stderr: "" })), { card: "terminal", output: "hi\n", exitCode: 0 });
+    assert.deepEqual(toolResultView("container_bash", {}, result({ exitCode: 0, signal: "SIGTERM", stdout: "", stderr: "" })), { card: "terminal", output: "", signal: "SIGTERM" });
+    assert.equal(toolResultView("container_bash", {}, { content: [{ type: "text", text: "boom" }], isError: true }), undefined);
+    assert.equal(toolResultView("image_list", {}, result({})), undefined);
+});
+test("command tools resolve a relative working directory", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const bash = guestExecRecorder("/projects/team");
+    await toolHandlers.container_bash(bash.resolver, { container: "default", command: "ls", workdir: "sub" }, exec);
+    assert.equal(bash.starts[0].cwd, "/projects/team/sub");
+    const run = guestExecRecorder("/projects/team");
+    await toolHandlers.container_exec(run.resolver, { container: "default", argv: ["ls"], workdir: "/abs" }, exec);
+    assert.equal(run.starts[0].cwd, "/abs", "absolute working directories pass through");
+    // An unset working directory defaults to the session's (when mounted).
+    const bare = guestExecRecorder("/projects/team");
+    await toolHandlers.container_exec(bare.resolver, { container: "default", argv: ["ls"] }, exec);
+    assert.equal(bare.starts[0].cwd, "/projects/team");
+    // Commands are not confined to the projects root, so ".." is allowed.
+    const up = guestExecRecorder("/projects/team");
+    await toolHandlers.container_bash(up.resolver, { container: "default", command: "ls", workdir: "../sibling" }, exec);
+    assert.equal(up.starts[0].cwd, "/projects/sibling");
+});
+test("command tools pass an optional uid, gid, and groups", async () => {
+    const exec = { agent: { session: { header: { cwd: "/projects/team" } } } };
+    const bash = guestExecRecorder("/projects/team");
+    await toolHandlers.container_bash(bash.resolver, { container: "default", command: "id", uid: 1000 }, exec);
+    // The managed environment is asserted separately; this pins the identity.
+    const { env: _bashEnv, ...bashStart } = bash.starts[0];
+    assert.deepEqual(bashStart, { argv: ["bash", "-c", "id"], cwd: "/projects/team", uid: 1000 });
+    const run = guestExecRecorder("/projects/team");
+    await toolHandlers.container_exec(run.resolver, { container: "default", argv: ["id"], uid: 1000, gid: 2000, groups: [3000, 4000] }, exec);
+    const { env: _runEnv, ...runStart } = run.starts[0];
+    assert.deepEqual(runStart, {
+        argv: ["id"],
+        cwd: "/projects/team",
+        uid: 1000,
+        gid: 2000,
+        groups: [3000, 4000],
+    });
+    // No identity leaves the command as the container's default user.
+    const none = guestExecRecorder("/projects/team");
+    await toolHandlers.container_exec(none.resolver, { container: "default", argv: ["id"] }, exec);
+    assert.equal("uid" in none.starts[0], false);
+    assert.equal("groups" in none.starts[0], false);
+    for (const bad of [
+        { uid: -1 },
+        { gid: -1 },
+        { groups: [1, -2] },
+        { groups: "1" },
+        { uid: 1.5 },
+    ]) {
+        await assert.rejects(toolHandlers.container_exec(guestExecRecorder("/projects/team").resolver, { container: "default", argv: ["id"], ...bad }, exec));
+    }
+});
+test("withoutHarnessSourceSection drops only the harness checkout section", () => {
+    const assembly = {
+        sections: [
+            { name: "harness:identity", text: "identity" },
+            { name: HARNESS_SOURCE_SECTION, text: "checkout at /src" },
+            { name: "deployment:persona", text: "persona" },
+        ],
+        contexts: [{ name: "c", text: "t" }],
+        tools: [{ name: "t" }],
+        variables: { model: "m" },
+    };
+    const result = withoutHarnessSourceSection(assembly);
+    assert.deepEqual(result.sections.map((section) => section.name), ["harness:identity", "deployment:persona"]);
+    assert.deepEqual(result.contexts, assembly.contexts);
+    assert.deepEqual(result.tools, assembly.tools);
+    assert.deepEqual(result.variables, assembly.variables);
+    // The input assembly is not mutated.
+    assert.equal(assembly.sections.length, 3);
+});
+test("withoutHarnessSourceSection leaves an assembly without the section intact", () => {
+    const assembly = { sections: [{ name: "harness:identity", text: "i" }] };
+    const result = withoutHarnessSourceSection(assembly);
+    assert.deepEqual(result, assembly);
+});

package/dist/mount-enums.d.ts

@@ -0,0 +1,22 @@
+export declare function mountKindToProto(kind: string | undefined): string;
+/**
+ * The mount mode to use when a caller does not name one.
+ *
+ * Adding a mount should not grant write access nobody asked for, so every kind
+ * defaults to read-only. tmpfs is the exception: its contents are per-container
+ * scratch space and the orchestrator rejects a read-only one outright.
+ */
+export declare function defaultMountMode(kind: string | undefined): string;
+/**
+ * The mode a mount kind is fixed to, or undefined when the caller chooses.
+ *
+ * A tmpfs is scratch space and the orchestrator rejects a read-only one; a
+ * secret is exposed read-only and carries no mode at all. Project and volume
+ * mounts are the ones a caller may switch.
+ */
+export declare function forcedMountMode(kind: string | undefined): string | undefined;
+export declare function mountModeToProto(mode: string | undefined): string;
+/** The logical mount kind for a proto enum value, or undefined when unspecified. */
+export declare function mountKindFromProto(proto: string | undefined): string | undefined;
+/** The logical mount mode for a proto enum value, or undefined when unspecified. */
+export declare function mountModeFromProto(proto: string | undefined): string | undefined;

package/dist/mount-enums.js

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+const MOUNT_KINDS = {
+    project: "MOUNT_KIND_PROJECT",
+    tmpfs: "MOUNT_KIND_TMPFS",
+    volume: "MOUNT_KIND_VOLUME",
+    secret: "MOUNT_KIND_SECRET",
+};
+const MOUNT_MODES = {
+    read_only: "MOUNT_MODE_READ_ONLY",
+    read_write: "MOUNT_MODE_READ_WRITE",
+};
+const KIND_FROM_PROTO = {
+    MOUNT_KIND_PROJECT: "project",
+    MOUNT_KIND_TMPFS: "tmpfs",
+    MOUNT_KIND_VOLUME: "volume",
+    MOUNT_KIND_SECRET: "secret",
+};
+const MODE_FROM_PROTO = {
+    MOUNT_MODE_READ_ONLY: "read_only",
+    MOUNT_MODE_READ_WRITE: "read_write",
+};
+export function mountKindToProto(kind) {
+    if (kind === undefined)
+        return "MOUNT_KIND_PROJECT";
+    const proto = Object.prototype.hasOwnProperty.call(MOUNT_KINDS, kind)
+        ? MOUNT_KINDS[kind]
+        : undefined;
+    if (proto === undefined)
+        throw new Error(`unknown mount kind: ${kind}`);
+    return proto;
+}
+/**
+ * The mount mode to use when a caller does not name one.
+ *
+ * Adding a mount should not grant write access nobody asked for, so every kind
+ * defaults to read-only. tmpfs is the exception: its contents are per-container
+ * scratch space and the orchestrator rejects a read-only one outright.
+ */
+export function defaultMountMode(kind) {
+    return kind === "tmpfs" ? "read_write" : "read_only";
+}
+/**
+ * The mode a mount kind is fixed to, or undefined when the caller chooses.
+ *
+ * A tmpfs is scratch space and the orchestrator rejects a read-only one; a
+ * secret is exposed read-only and carries no mode at all. Project and volume
+ * mounts are the ones a caller may switch.
+ */
+export function forcedMountMode(kind) {
+    if (kind === "tmpfs")
+        return "read_write";
+    if (kind === "secret")
+        return "read_only";
+    return undefined;
+}
+export function mountModeToProto(mode) {
+    const proto = mode !== undefined && Object.prototype.hasOwnProperty.call(MOUNT_MODES, mode)
+        ? MOUNT_MODES[mode]
+        : undefined;
+    if (proto === undefined)
+        throw new Error(`unknown mount mode: ${mode}`);
+    return proto;
+}
+/** The logical mount kind for a proto enum value, or undefined when unspecified. */
+export function mountKindFromProto(proto) {
+    if (proto === undefined)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(KIND_FROM_PROTO, proto)
+        ? KIND_FROM_PROTO[proto]
+        : undefined;
+}
+/** The logical mount mode for a proto enum value, or undefined when unspecified. */
+export function mountModeFromProto(proto) {
+    if (proto === undefined)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(MODE_FROM_PROTO, proto)
+        ? MODE_FROM_PROTO[proto]
+        : undefined;
+}

package/dist/mount-input.d.ts

@@ -0,0 +1,14 @@
+import { type ReasonLocale } from "./approval-reasons.js";
+export declare function inferMountKind(args: {
+    kind?: unknown;
+    project?: unknown;
+    volume?: unknown;
+    secret?: unknown;
+}): string;
+export declare function projectMountMirror(projectsRoot: string, project: string): string;
+export declare function projectMountDestinationReason(projectsRoot: string | undefined, args: {
+    kind?: unknown;
+    project?: unknown;
+    destination?: unknown;
+}, locale?: ReasonLocale): string | undefined;
+export declare function mountsFromInput(mounts: unknown, projectsRoot: string | undefined): Record<string, unknown>[] | undefined;

package/dist/mount-input.js

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { defaultMountMode, mountKindToProto, mountModeToProto } from "./mount-enums.js";
+import { renderDenial } from "./approval-reasons.js";
+// The mount kind for a call: an explicit non-empty `kind` wins, otherwise it is
+// inferred from the source field the caller supplied (`secret`/`volume`), since
+// `kind` is optional in the mount schemas. Falls back to a project mount.
+export function inferMountKind(args) {
+    if (typeof args.kind === "string" && args.kind !== "")
+        return args.kind;
+    if (typeof args.secret === "string" && args.secret !== "")
+        return "secret";
+    if (typeof args.volume === "string" && args.volume !== "")
+        return "volume";
+    return "project";
+}
+// The container-side destination a project mount always lands at: the project
+// path under projectsRoot.
+export function projectMountMirror(projectsRoot, project) {
+    return [projectsRoot, project].filter((part) => part !== "").join("/");
+}
+// The reason to deny a mount item that carries a destination on a project (or
+// unnamed) mount, or undefined when the item is allowed. Project mounts never
+// take a destination; without one the directory lands at its project root.
+export function projectMountDestinationReason(projectsRoot, args, locale = "en") {
+    if (inferMountKind(args) !== "project")
+        return undefined;
+    if (args.destination === undefined || args.destination === "")
+        return undefined;
+    const project = typeof args.project === "string" ? args.project : "";
+    const mirror = projectsRoot === undefined
+        ? ""
+        : projectMountMirror(projectsRoot, project);
+    return renderDenial(locale, {
+        kind: "project_destination",
+        ...(project === "" ? {} : { source: project }),
+        ...(mirror === "" ? {} : { mirror }),
+    });
+}
+export function mountsFromInput(mounts, projectsRoot) {
+    if (!Array.isArray(mounts) || mounts.length === 0)
+        return undefined;
+    return mounts.map((mount) => {
+        const inferredKind = inferMountKind(mount);
+        const destinationReason = projectMountDestinationReason(projectsRoot, mount);
+        if (destinationReason !== undefined)
+            throw new Error(destinationReason);
+        if (inferredKind === "secret" && mount.mode === "read_write") {
+            throw new Error("secret mounts are read-only; omit mode or use read_only");
+        }
+        const kind = mountKindToProto(inferredKind);
+        const mode = mountModeToProto(mount.mode ?? defaultMountMode(inferredKind));
+        const result = { projectName: mount.project ?? "", kind, mode };
+        if (inferredKind !== "project" && mount.destination) {
+            result.destination = mount.destination;
+        }
+        if (mount.volume)
+            result.volume = mount.volume;
+        if (mount.secret)
+            result.secret = mount.secret;
+        return result;
+    });
+}

package/dist/mounts.test.d.ts

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