@exagone313/dsh-podman 0.2.0-rc.2

package/dist/grpc/proto/dshguest/v1/guest.proto

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+
+syntax = "proto3";
+package dshguest.v1;
+option go_package = "github.com/Exagone313/dsh-podman/internal/genproto/dshguest/v1;dshguestv1";
+
+import "google/protobuf/wrappers.proto";
+
+service WorkspaceGuestAgent {
+  rpc Exec(stream ExecInput) returns (stream ExecOutput);
+  rpc Signal(SignalRequest) returns (SignalResponse);
+  rpc ReadFile(ReadFileRequest) returns (stream ReadFileChunk);
+  rpc WriteFile(stream WriteFileChunk) returns (WriteFileResponse);
+  rpc Stat(StatRequest) returns (StatResponse);
+  rpc ReadDir(ReadDirRequest) returns (ReadDirResponse);
+  rpc Mkdir(MkdirRequest) returns (MkdirResponse);
+  rpc Delete(DeleteRequest) returns (DeleteResponse);
+  rpc SetPaths(SetPathsRequest) returns (PathsResponse);
+  rpc GetPaths(GetPathsRequest) returns (PathsResponse);
+  rpc StartDaemon(StartDaemonRequest) returns (DaemonInfo);
+  rpc ListDaemons(ListDaemonsRequest) returns (ListDaemonsResponse);
+  rpc StopDaemon(StopDaemonRequest) returns (StopDaemonResponse);
+  rpc StopAllDaemons(StopAllDaemonsRequest) returns (StopAllDaemonsResponse);
+  rpc RestartDaemon(RestartDaemonRequest) returns (DaemonInfo);
+  rpc DaemonLogs(DaemonLogsRequest) returns (DaemonLogsResponse);
+  rpc Terminal(stream TerminalInput) returns (stream TerminalOutput);
+}
+message ExecInput { oneof payload { ExecStart start = 1; bytes stdin_chunk = 2; } }
+message ExecStart { repeated string argv = 1; string cwd = 2; map<string, string> env = 3; repeated string unset_env = 4; SpillTarget spill_stdout = 5; SpillTarget spill_stderr = 6; google.protobuf.Int32Value uid = 7; google.protobuf.Int32Value gid = 8; repeated uint32 groups = 9; bool stdin_pipe = 10; }
+message ExecOutput { oneof payload { bytes stdout_chunk = 1; bytes stderr_chunk = 2; ExecExit exit = 3; } string process_id = 4; }
+message ExecExit { int32 exit_code = 1; bool signaled = 2; string signal = 3; bool stdout_spill_valid = 4; bool stderr_spill_valid = 5; }
+// SpillTarget is a bounded full-stream copy of one output stream, written in
+// the guest's execution world so the caller can read the complete output after
+// an in-memory truncation.
+message SpillTarget { int64 max_bytes = 1; string path = 2; }
+message SignalRequest { string process_id = 1; string signal = 2; }
+message SignalResponse {}
+message ReadFileRequest { string path = 1; int64 offset = 2; int64 length = 3; }
+message ReadFileChunk { bytes data = 1; }
+message WriteFileChunk { oneof payload { WriteFileStart start = 1; bytes data_chunk = 2; } }
+message WriteFileStart { string path = 1; bool create = 2; bool truncate = 3; }
+message WriteFileResponse { int64 bytes_written = 1; }
+message StatRequest { string path = 1; bool no_follow = 2; }
+message StatResponse { bool exists = 1; bool is_dir = 2; int64 size = 3; string mode = 4; string modified_at = 5; bool is_symlink = 6; }
+message ReadDirRequest { string path = 1; }
+message ReadDirResponse { repeated DirEntry entries = 1; }
+message DirEntry { string name = 1; bool is_dir = 2; int64 size = 3; string type = 4; }
+message MkdirRequest { string path = 1; bool parents = 2; }
+message MkdirResponse {}
+message DeleteRequest { string path = 1; bool recursive = 2; }
+message DeleteResponse {}
+// Path additions the agent prepends to every child's PATH, highest priority
+// first. default_path is the agent's own PATH (the container image's), which
+// the additions are prepended to.
+message SetPathsRequest { repeated string paths = 1; }
+message GetPathsRequest {}
+message PathsResponse { repeated string paths = 1; string default_path = 2; }
+message StartDaemonRequest { string name = 1; repeated string argv = 2; string cwd = 3; map<string, string> env = 4; google.protobuf.Int32Value uid = 5; google.protobuf.Int32Value gid = 6; repeated uint32 groups = 7; google.protobuf.BoolValue inherit_env = 8; }
+message DaemonInfo { string name = 1; repeated string argv = 2; bool running = 3; int32 exit_code = 4; string started_at = 5; string stopped_at = 6; uint32 uid = 7; uint32 gid = 8; repeated uint32 groups = 9; }
+message ListDaemonsRequest {}
+message ListDaemonsResponse { repeated DaemonInfo daemons = 1; }
+message StopDaemonRequest { string name = 1; string signal = 2; }
+message StopDaemonResponse {}
+message StopAllDaemonsRequest {}
+message StopAllDaemonsResponse { repeated string daemons = 1; }
+message RestartDaemonRequest { string name = 1; }
+message DaemonLogsRequest { string name = 1; int32 tail_bytes = 2; }
+message DaemonLogsResponse { bytes stdout = 1; bytes stderr = 2; }
+message TerminalInput { oneof payload { TerminalStart start = 1; bytes stdin_chunk = 2; TerminalResize resize = 3; TerminalSignal signal = 4; string inspect_request_id = 5; bool close = 6; } }
+message TerminalStart { repeated string argv = 1; string cwd = 2; map<string, string> env = 3; uint32 rows = 4; uint32 cols = 5; }
+message TerminalResize { uint32 rows = 1; uint32 cols = 2; }
+message TerminalSignal { string signal = 1; string request_id = 2; }
+message TerminalOutput { oneof payload { TerminalStarted started = 1; bytes stdout_chunk = 2; TerminalExit exit = 3; TerminalForeground foreground = 4; TerminalSignalled signalled = 5; } }
+message TerminalStarted { int32 pid = 1; }
+message TerminalExit { int32 exit_code = 1; bool signaled = 2; string signal = 3; }
+message TerminalForeground { string request_id = 1; bool found = 2; int32 process_group_id = 3; bool input_waiting = 4; }
+message TerminalSignalled { string request_id = 1; bool found = 2; int32 process_group_id = 3; }

package/dist/grpc/runtime-client.d.ts

@@ -0,0 +1,5 @@
+import grpc from "@grpc/grpc-js";
+export declare function controlClient(socket: string): grpc.Client;
+export declare function guestClient(socket: string): grpc.Client;
+export declare function unary<T>(client: grpc.Client, method: string, request: unknown, metadata?: grpc.Metadata): Promise<T>;
+export { grpc };

package/dist/grpc/runtime-client.js

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import grpc from "@grpc/grpc-js";
+import loader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "proto");
+const definitions = new Map();
+function unixTarget(socket) {
+    return socket.startsWith("unix:") ? socket : `unix:${socket}`;
+}
+function client(service, proto, socket) {
+    const key = `${service}:${socket}`;
+    let Constructor = definitions.get(key);
+    if (Constructor === undefined) {
+        const packageDefinition = loader.loadSync(resolve(root, proto), {
+            longs: String,
+            enums: String,
+            defaults: true,
+        });
+        const loaded = grpc.loadPackageDefinition(packageDefinition);
+        const namespace = service.startsWith("dshctl")
+            ? loaded.dshctl
+            : loaded.dshguest;
+        const version = namespace.v1;
+        Constructor = version[service.split(".").at(-1)];
+        definitions.set(key, Constructor);
+    }
+    return new Constructor(unixTarget(socket), grpc.credentials.createInsecure());
+}
+export function controlClient(socket) {
+    return client("dshctl.v1.OrchestratorControl", "dshctl/v1/control.proto", socket);
+}
+export function guestClient(socket) {
+    return client("dshguest.v1.WorkspaceGuestAgent", "dshguest/v1/guest.proto", socket);
+}
+export function unary(client, method, request, metadata) {
+    return new Promise((resolvePromise, reject) => {
+        client[method](request, metadata ?? new grpc.Metadata(), (error, value) => error ? reject(error) : resolvePromise(value));
+    });
+}
+export { grpc };

package/dist/guest-rpc.d.ts

@@ -0,0 +1,62 @@
+import { WorkspaceResolver } from "./workspace-binding.js";
+export declare function resolveGuestPath(path: string, sessionCwd: unknown): string;
+export declare function resolveGuestCwd(cwd: unknown, sessionCwd: unknown): string | undefined;
+export declare function guestCwd(requested: unknown, sessionCwd: unknown, binding: {
+    defaultCwd?: string;
+}): string | undefined;
+export declare function approvalPath(path: string, sessionCwd: unknown): string;
+export declare const DIFF_BASIS_MAX_BYTES: number;
+export declare function normalizeLineEndings(content: string): string;
+export declare function detectLineEndings(raw: string): "CRLF" | "LF";
+export declare function restoreLineEndings(content: string, endings: "CRLF" | "LF"): string;
+export declare function fsError(code: string, message: string): Error;
+export declare function throwIfAborted(signal: AbortSignal | undefined, verb: string): void;
+export declare function guestChunks(target: any, range: {
+    offset?: number;
+    length?: number;
+} | undefined, signal: AbortSignal | undefined): AsyncIterable<Buffer>;
+export declare function guestTextChunks(target: any, signal: AbortSignal | undefined): AsyncIterable<string>;
+export declare function readGuestText(target: any, signal: AbortSignal | undefined): Promise<string>;
+export declare function readDiffBasis(target: any, signal: AbortSignal | undefined): Promise<string | null>;
+export declare function guestVersion(result: any): string;
+export declare function writeGuestFile(binding: {
+    guest: any;
+    token: string;
+}, path: string, content: string, opts: {
+    create: boolean;
+    truncate: boolean;
+}, signal?: AbortSignal): Promise<number>;
+export declare function readGuestFile(binding: {
+    guest: any;
+    token: string;
+}, path: string): Promise<string>;
+export interface ExecIdentity {
+    uid?: number;
+    gid?: number;
+    groups?: number[];
+}
+export declare function runExec(binding: {
+    guest: any;
+    token: string;
+}, argv: readonly string[], cwd?: string, env?: Record<string, string>, timeoutMs?: number, identity?: ExecIdentity): Promise<{
+    exitCode: number;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function sliceLines(content: string, offset: unknown, limit: unknown): string;
+export declare function outputLines(text: string): string[];
+export declare function bytesText(value: unknown): string;
+export declare function currentCwd(exec: any): unknown;
+export declare function sessionWorkspaceSlug(resolver: WorkspaceResolver, cwd: unknown): Promise<string>;
+export declare function resolveToolBinding(resolver: WorkspaceResolver, cwd: unknown, container: string): Promise<{
+    guest: any;
+    token: string;
+    socket: string;
+    defaultCwd?: string;
+}>;
+export declare function guestStat(target: any, signal?: AbortSignal): Promise<any>;
+export declare function guestStatResponse(target: any, signal?: AbortSignal): Promise<any>;
+export declare function unaryGuest(target: any, method: string, request: unknown, signal?: AbortSignal): Promise<unknown>;
+export declare function globCwd(argv: readonly string[], cwd: unknown): string | undefined;
+export declare function remoteArgv(argv: readonly string[]): readonly string[];

package/dist/guest-rpc.js

@@ -0,0 +1,391 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { metadata, workspaceSlug } from "./workspace-binding.js";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+// Resolve a container-side path against the session working directory.
+// Absolute paths pass through unchanged. The session cwd and the container's
+// view of the project coincide because the orchestrator mounts each project at
+// its mirrored path under DSH_PODMAN_PROJECTS_ROOT.
+function resolveAgainstSession(path, sessionCwd) {
+    if (isAbsolute(path))
+        return path;
+    const base = typeof sessionCwd === "string" && sessionCwd !== "" ? sessionCwd : undefined;
+    if (base === undefined) {
+        throw new Error("relative paths need a session working directory; pass an absolute path");
+    }
+    return resolvePath(base, path);
+}
+// Resolve a guest filesystem path against the session working directory.
+//
+// A ".." segment is refused before resolution: afterwards it would have been
+// normalised away, and the guest agent would reject the result with a less
+// helpful error. The guest agent confines these paths to the projects root, so
+// this is a clearer error rather than the boundary itself.
+export function resolveGuestPath(path, sessionCwd) {
+    if (path.split("/").includes("..")) {
+        throw new Error("path must not escape the workspace");
+    }
+    return resolveAgainstSession(path, sessionCwd);
+}
+// Resolve a working directory, or a path handed to a command, against the
+// session working directory. An unset value stays unset, leaving the guest
+// agent's own working directory in place.
+//
+// Unlike resolveGuestPath this does not refuse "..": commands are not confined
+// to the projects root, so rejecting it would be theatre while breaking a
+// legitimate "../sibling" working directory.
+export function resolveGuestCwd(cwd, sessionCwd) {
+    if (typeof cwd !== "string" || cwd === "")
+        return undefined;
+    return resolveAgainstSession(cwd, sessionCwd);
+}
+// guestCwd resolves a command's working directory: an explicit value is
+// resolved against the session, otherwise the container's default (the session
+// directory when it is mounted) is used. Undefined leaves the guest agent's own
+// working directory in place.
+export function guestCwd(requested, sessionCwd, binding) {
+    return resolveGuestCwd(requested, sessionCwd) ?? binding.defaultCwd;
+}
+// The path to show in an approval prompt: the resolved target when it can be
+// worked out, else the value as given. Never throws — a bad path is reported
+// by the handler, and the prompt must still render.
+export function approvalPath(path, sessionCwd) {
+    try {
+        return resolveGuestPath(path, sessionCwd);
+    }
+    catch {
+        return path;
+    }
+}
+// Binary detection samples only the head of a file, matching the harness's
+// local backend (`fs-local`).
+const BINARY_SAMPLE_BYTES = 8192;
+// Cap on the contextual-diff basis read before a write; a larger existing file
+// yields `before: null`, matching `fs-local`'s default (10 MiB).
+export const DIFF_BASIS_MAX_BYTES = 10 * 1024 * 1024;
+// Line-ending handling for edits, mirroring `fs-local`: match on LF-normalized
+// text, then restore the file's original style on write-back.
+export function normalizeLineEndings(content) {
+    return content.replaceAll("\r\n", "\n");
+}
+export function detectLineEndings(raw) {
+    const sample = raw.slice(0, 4096);
+    const crlfCount = sample.split("\r\n").length - 1;
+    const lfCount = sample.split("\n").length - 1 - crlfCount;
+    return crlfCount > lfCount ? "CRLF" : "LF";
+}
+export function restoreLineEndings(content, endings) {
+    return endings === "LF"
+        ? content
+        : normalizeLineEndings(content).split("\n").join("\r\n");
+}
+export function fsError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+// The harness's FS_ABORTED: a caller that already cancelled must fail before
+// any I/O.
+export function throwIfAborted(signal, verb) {
+    if (signal?.aborted)
+        throw fsError("FS_ABORTED", `${verb} aborted`);
+}
+// Cancel a gRPC call when the caller aborts; returns a detach function.
+function onAbortCancel(call, signal) {
+    if (signal === undefined)
+        return () => { };
+    const cancel = () => {
+        try {
+            call.cancel?.();
+        }
+        catch {
+            // A finished call cannot be cancelled; nothing to do.
+        }
+    };
+    if (signal.aborted) {
+        cancel();
+        return () => { };
+    }
+    signal.addEventListener("abort", cancel, { once: true });
+    return () => signal.removeEventListener("abort", cancel);
+}
+// Stream raw bytes from the guest's ReadFile. A zero/absent length reads to
+// EOF. Cancelling the signal cancels the call and reports FS_ABORTED.
+export async function* guestChunks(target, range, signal) {
+    throwIfAborted(signal, "read");
+    const request = { path: target.targetKey };
+    if (range?.offset !== undefined && range.offset > 0) {
+        request.offset = range.offset;
+    }
+    if (range?.length !== undefined && range.length > 0) {
+        request.length = range.length;
+    }
+    const call = target.binding.guest.readFile(request, metadata(target.binding.token));
+    const detach = onAbortCancel(call, signal);
+    try {
+        for await (const chunk of call) {
+            yield Buffer.from(chunk.data);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw fsError("FS_ABORTED", "read aborted");
+        throw error;
+    }
+    finally {
+        detach();
+    }
+}
+// Stream the guest file as decoded UTF-8 text, rejecting binary content (a NUL
+// byte in the head, or invalid UTF-8) with the harness's FS_NOT_TEXT code.
+export async function* guestTextChunks(target, signal) {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let sampled = 0;
+    try {
+        for await (const buffer of guestChunks(target, undefined, signal)) {
+            if (sampled < BINARY_SAMPLE_BYTES) {
+                const sample = buffer.subarray(0, Math.min(buffer.length, BINARY_SAMPLE_BYTES - sampled));
+                if (sample.includes(0)) {
+                    throw fsError("FS_NOT_TEXT", `cannot read "${target.displayPath}": binary file`);
+                }
+                sampled += sample.length;
+            }
+            const text = decoder.decode(buffer, { stream: true });
+            if (text !== "")
+                yield text;
+        }
+        const tail = decoder.decode();
+        if (tail !== "")
+            yield tail;
+    }
+    catch (error) {
+        // A fatal TextDecoder failure is a TypeError; anything else (our own
+        // FS_NOT_TEXT/FS_ABORTED, or a transport error) keeps its identity.
+        if (error instanceof TypeError) {
+            throw fsError("FS_NOT_TEXT", `cannot read "${target.displayPath}": invalid UTF-8 text`);
+        }
+        throw error;
+    }
+}
+export async function readGuestText(target, signal) {
+    let text = "";
+    for await (const chunk of guestTextChunks(target, signal))
+        text += chunk;
+    return text;
+}
+// The contextual-diff basis before a write: absent for a create, binary, or
+// unreadable prior file (presentation only, never a correctness input).
+export async function readDiffBasis(target, signal) {
+    try {
+        return await readGuestText(target, signal);
+    }
+    catch (error) {
+        if (error.code === "FS_NOT_TEXT")
+            return null;
+        throw error;
+    }
+}
+export function guestVersion(result) {
+    return `agent:${result.modifiedAt ?? ""}:${result.size ?? 0}:${result.mode ?? ""}`;
+}
+export async function writeGuestFile(binding, path, content, opts, signal) {
+    throwIfAborted(signal, "write");
+    return new Promise((resolveDone, reject) => {
+        let detach = () => { };
+        const call = binding.guest.writeFile(metadata(binding.token), {}, (error, result) => {
+            detach();
+            error
+                ? reject(signal?.aborted ? fsError("FS_ABORTED", "write aborted") : error)
+                : resolveDone(Number(result?.bytesWritten ?? 0));
+        });
+        detach = onAbortCancel(call, signal);
+        call.write({
+            start: { path, create: opts.create, truncate: opts.truncate },
+        });
+        call.write({ dataChunk: Buffer.from(content) });
+        call.end();
+    });
+}
+export async function readGuestFile(binding, path) {
+    const chunks = [];
+    await new Promise((resolveDone, reject) => {
+        const call = binding.guest.readFile({ path }, metadata(binding.token));
+        call.on("data", (chunk) => chunks.push(Buffer.from(chunk.data)));
+        call.on("error", reject);
+        call.on("end", resolveDone);
+    });
+    return Buffer.concat(chunks).toString("utf8");
+}
+const READ_LIMIT = 2000;
+export async function runExec(binding, argv, cwd, env, timeoutMs, identity) {
+    const stdout = [];
+    const stderr = [];
+    return new Promise((resolveDone, reject) => {
+        const stream = binding.guest.exec(metadata(binding.token));
+        let processId;
+        let timer;
+        const stopTimer = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        };
+        if (typeof timeoutMs === "number" && timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timer = undefined;
+                if (processId !== undefined) {
+                    // Best effort: ask the guest to terminate the running process.
+                    unaryGuest({ binding }, "signal", {
+                        processId,
+                        signal: "SIGTERM",
+                    }).catch(() => { });
+                }
+                reject(new Error(`command timed out after ${timeoutMs} ms`));
+            }, timeoutMs);
+        }
+        stream.on("data", (output) => {
+            if (output.processId)
+                processId = String(output.processId);
+            if (output.stdoutChunk)
+                stdout.push(Buffer.from(output.stdoutChunk));
+            if (output.stderrChunk)
+                stderr.push(Buffer.from(output.stderrChunk));
+            if (output.exit) {
+                stopTimer();
+                resolveDone({
+                    exitCode: output.exit.exitCode,
+                    signal: output.exit.signaled ? output.exit.signal : null,
+                    stdout: Buffer.concat(stdout).toString("utf8"),
+                    stderr: Buffer.concat(stderr).toString("utf8"),
+                });
+            }
+        });
+        stream.on("error", (error) => {
+            stopTimer();
+            reject(error);
+        });
+        stream.write({
+            start: {
+                argv: remoteArgv(argv),
+                cwd,
+                env: env ?? {},
+                ...(identity?.uid !== undefined ? { uid: { value: identity.uid } } : {}),
+                ...(identity?.gid !== undefined ? { gid: { value: identity.gid } } : {}),
+                ...(identity?.groups !== undefined ? { groups: identity.groups } : {}),
+            },
+        });
+        stream.end();
+    });
+}
+// sliceLines returns the requested 1-based line range of a file's content,
+// defaulting to the first READ_LIMIT lines like the harness's read tool.
+export function sliceLines(content, offset, limit) {
+    const start = typeof offset === "number" && Number.isInteger(offset) && offset > 0
+        ? offset
+        : 1;
+    const max = typeof limit === "number" && Number.isInteger(limit) && limit > 0
+        ? limit
+        : READ_LIMIT;
+    return content.split("\n").slice(start - 1, start - 1 + max).join("\n");
+}
+export function outputLines(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line !== "");
+}
+export function bytesText(value) {
+    if (value === undefined)
+        return "";
+    return Buffer.isBuffer(value) ? value.toString("utf8") : String(value);
+}
+export function currentCwd(exec) {
+    return exec?.agent?.session?.header?.cwd;
+}
+export async function sessionWorkspaceSlug(resolver, cwd) {
+    const workspace = await resolver.registry?.resolveByPath?.(String(cwd));
+    if (workspace === undefined)
+        return "default";
+    return workspaceSlug(workspace.id);
+}
+export async function resolveToolBinding(resolver, cwd, container) {
+    if (container === "default")
+        return resolver.resolve(cwd);
+    return resolver.containerBinding(cwd, container);
+}
+export async function guestStat(target, signal) {
+    const result = await guestStatResponse(target, signal);
+    if (!result.exists)
+        return undefined;
+    return {
+        version: guestVersion(result),
+        type: result.isDir ? "directory" : "file",
+        ...(result.isDir ? {} : { size: Number(result.size ?? 0) }),
+    };
+}
+export function guestStatResponse(target, signal) {
+    throwIfAborted(signal, "stat");
+    return new Promise((resolveDone, reject) => {
+        let detach = () => { };
+        const call = target.binding.guest.stat({ path: target.targetKey }, metadata(target.binding.token), (error, value) => {
+            detach();
+            error
+                ? reject(signal?.aborted ? fsError("FS_ABORTED", "stat aborted") : error)
+                : resolveDone(value);
+        });
+        detach = onAbortCancel(call, signal);
+    });
+}
+export async function unaryGuest(target, method, request, signal) {
+    throwIfAborted(signal, method);
+    return new Promise((resolveDone, reject) => {
+        let detach = () => { };
+        const call = target.binding.guest[method](request, metadata(target.binding.token), (error, result) => {
+            detach();
+            error
+                ? reject(signal?.aborted ? fsError("FS_ABORTED", `${method} aborted`) : error)
+                : resolveDone(result);
+        });
+        detach = onAbortCancel(call, signal);
+    });
+}
+// globCwd returns the working directory a ripgrep discovery listing must run
+// in, or undefined to keep the caller's. The harness's glob tool passes its
+// search path as an absolute positional root, but ripgrep anchors a `--glob`
+// pattern containing "/" to the process cwd, so a pattern like "sub/b.txt"
+// could never match an absolute root. Running the listing from the root anchors
+// the pattern to `path` while keeping the printed paths absolute, which is what
+// the harness renders against the session working directory.
+export function globCwd(argv, cwd) {
+    const runner = argv[0];
+    if (runner === undefined || !/(?:^|\/)rg(?:\.exe)?$/.test(runner))
+        return undefined;
+    if (!argv.includes("--files"))
+        return undefined;
+    const separator = argv.indexOf("--");
+    if (separator < 0)
+        return undefined;
+    const roots = argv.slice(separator + 1);
+    if (roots.length !== 1)
+        return undefined;
+    const root = roots[0];
+    if (typeof cwd !== "string" || cwd === "" || !isAbsolute(root))
+        return undefined;
+    return root;
+}
+// remoteArgv rewrites an argv for the guest's execution world: the harness's
+// bundled ripgrep becomes the guest's /usr/bin/rg, and a landlock-run sandbox
+// wrapper is unwrapped to the command it guards.
+export function remoteArgv(argv) {
+    const runner = argv[0];
+    if (runner !== undefined && /(?:^|\/)rg(?:\.exe)?$/.test(runner)) {
+        return ["/usr/bin/rg", ...argv.slice(1)];
+    }
+    if (runner !== undefined && /(?:^|\/)landlock-run(?:$|\/)/.test(runner)) {
+        const separator = argv.indexOf("--");
+        if (separator >= 0)
+            return remoteArgv(argv.slice(separator + 1));
+    }
+    return argv;
+}

package/dist/images.test.d.ts

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

package/dist/images.test.js

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EXPECTED_TOOLS } from "./test-support.js";
+import { TOOLS, imageRemoveParameters, toolHandlers } from "./index.js";
+test("tool set covers the image and container surface", () => {
+    assert.deepEqual(TOOLS.map((tool) => tool.name).sort(), [...EXPECTED_TOOLS].sort());
+});
+test("image_build requires imageId, parent and packages", () => {
+    const tool = TOOLS.find((entry) => entry.name === "image_build");
+    assert.ok(tool, "image_build registered");
+    assert.equal(tool.approval, true, "image_build must require approval");
+    assert.deepEqual(tool.parameters.required, ["imageId", "parent", "packages"]);
+    assert.equal(tool.parameters.properties.imageId.description, "Image short name.");
+    assert.ok(tool.parameters.properties.parent.description.includes("Short name of the parent image"), "parent must be documented as a short name");
+});
+test("image_remove is registered, requires approval and requires imageId", () => {
+    const tool = TOOLS.find((entry) => entry.name === "image_remove");
+    assert.ok(tool, "image_remove registered");
+    assert.equal(tool.approval, true, "image_remove must require approval");
+    assert.equal(tool.parameters.type, "object", "image_remove type");
+    assert.equal(typeof tool.parameters.properties, "object");
+    assert.deepEqual(tool.parameters.required, ["imageId"]);
+    assert.equal(tool.parameters.properties.imageId.type, "string");
+    assert.deepEqual(imageRemoveParameters, tool.parameters);
+});
+test("image_list returns image objects", async () => {
+    const resolver = {
+        control: async () => ({
+            images: [
+                {
+                    imageId: "archlinux",
+                    isBase: true,
+                    status: "built",
+                    primitive: "docker.io/library/archlinux:latest",
+                    packageManager: "pacman",
+                    basePublic: false,
+                },
+                {
+                    imageId: "dev",
+                    parent: "ubuntu",
+                    status: "built",
+                    packages: ["git"],
+                    packageManager: "apt",
+                },
+            ],
+        }),
+    };
+    const out = await toolHandlers.image_list(resolver, {}, {});
+    assert.deepEqual(out, [
+        {
+            imageId: "archlinux",
+            isBase: true,
+            status: "built",
+            primitive: "docker.io/library/archlinux:latest",
+            packageManager: "pacman",
+            basePublic: false,
+            packages: [],
+        },
+        {
+            imageId: "dev",
+            parent: "ubuntu",
+            isBase: false,
+            status: "built",
+            packageManager: "apt",
+            basePublic: false,
+            packages: ["git"],
+        },
+    ]);
+});
+test("image_rebuild_all returns rebuilt and skipped arrays", async () => {
+    const resolver = {
+        control: async () => ({ rebuilt: ["archlinux", "dev"], skipped: ["broken"] }),
+    };
+    const out = await toolHandlers.image_rebuild_all(resolver, {}, {});
+    assert.deepEqual(out, { rebuilt: ["archlinux", "dev"], skipped: ["broken"] });
+});