@archmax-ai/harness 0.3.1 → 0.4.0

package/dist/core/binary-read.js

@@ -0,0 +1,129 @@
+import { posix } from "node:path";
+/**
+ * Reads are text only. Deep Agents' `read_file` hands a non-text file to the
+ * model as a base64 multimodal block (`image`, `audio`, `video`, `file`), which
+ * an OpenAI-compatible tool message cannot carry and which would otherwise
+ * ride in every checkpoint, script result and event preview; and it decodes a
+ * binary file whose extension it does not know as UTF-8 garbage. The workspace
+ * router refuses both with the notice built here, and the `read_file`
+ * description the model is handed says so.
+ *
+ * The classification is `read_file`'s own — the route's `mimeType`, else the
+ * extension's, through `isTextMimeType` — plus two content checks: bytes, and a
+ * NUL character (git's and ripgrep's rule), which survives the backend's UTF-8
+ * decoding of an unknown extension.
+ */
+/**
+ * The non-text entries of Deep Agents' extension table (`backends/utils.ts`,
+ * identical in 1.13.4 and 1.14.2), which it does not export. Every other
+ * extension maps to a text type, or to `text/plain` by default, so only these
+ * decide anything. Pinned against `FilesystemBackend` by `binary-read.test.ts`.
+ */
+export const BINARY_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".aiff": "audio/aiff",
+    ".aac": "audio/aac",
+    ".ogg": "audio/ogg",
+    ".flac": "audio/flac",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mpeg": "video/mpeg",
+    ".mov": "video/quicktime",
+    ".avi": "video/x-msvideo",
+    ".flv": "video/x-flv",
+    ".mpg": "video/mpeg",
+    ".wmv": "video/x-ms-wmv",
+    ".3gpp": "video/3gpp",
+    ".pdf": "application/pdf",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+/** The MIME type for a path's binary extension, or `undefined` when Deep Agents would read it as text. */
+export function binaryMimeTypeOf(path) {
+    return BINARY_MIME_TYPES[posix.extname(path).toLocaleLowerCase()];
+}
+/**
+ * The image types the model may be shown (`images` assembly option): the ones
+ * chat-completions vision accepts. HEIC/HEIF are binary but not among them, so
+ * they stay refused like every other binary file.
+ */
+export const SHOWN_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+/** The MIME type of a path the model may be shown as an image, or `undefined`. */
+export function shownImageMimeTypeOf(path) {
+    const mime = binaryMimeTypeOf(path);
+    return mime !== undefined && SHOWN_IMAGE_MIME_TYPES.has(mime) ? mime : undefined;
+}
+/** Deep Agents' `isTextMimeType`: the types `read_file` renders as text. */
+export function isTextMimeType(mimeType) {
+    return (mimeType.startsWith("text/") ||
+        mimeType === "application/json" ||
+        mimeType === "application/javascript" ||
+        mimeType === "image/svg+xml");
+}
+/** Byte length of non-string content: bytes, or the numeric-key object they become once serialized. */
+function byteLength(content) {
+    if (ArrayBuffer.isView(content))
+        return content.byteLength;
+    if (content !== null && typeof content === "object")
+        return Object.keys(content).length;
+    return undefined;
+}
+/** A byte count as a person reads it: `512 B`, `24.1 KB`, `3.2 MB`. */
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * The binary notice for a successful read of `path`, or `null` when the result
+ * is text. A result carrying an `error` is the route's own answer and is never
+ * classified.
+ */
+export function binaryReadError(path, result) {
+    if (result.error)
+        return null;
+    const { content } = result;
+    const declared = result.mimeType ?? binaryMimeTypeOf(path) ?? "text/plain";
+    const typed = !isTextMimeType(declared);
+    const bytes = content !== undefined && typeof content !== "string";
+    const nul = typeof content === "string" && content.includes("\u0000");
+    if (!typed && !bytes && !nul)
+        return null;
+    const mime = typed ? declared : "application/octet-stream";
+    const size = bytes ? byteLength(content) : undefined;
+    const detail = size === undefined ? mime : `${mime}, ${formatSize(size)}`;
+    const shown = path.replace(/^\/+/, "");
+    return `'${shown}' is a binary file (${detail}) and was not read; read_file returns text files only.`;
+}
+/** The line the `read_file` description carries in place of Deep Agents' multimodal promise. */
+export const READ_FILE_TEXT_ONLY_LINE = "- Text files only: a binary file (an image, audio, video, a PDF, an archive, …) is not returned; " +
+    "the result says the file is binary and was not read.";
+/** The same line for an agent whose model is shown the images it reads (`images` option). */
+export const READ_FILE_IMAGES_LINE = "- Text files, and images (PNG, JPEG, GIF, WebP): an image is shown to you right after the tool " +
+    "result. Any other binary file (audio, video, a PDF, an archive, …) is not returned; the result " +
+    "says the file is binary and was not read.";
+const MULTIMODAL_LINE = /^- Images \(.*multimodal content blocks.*$/m;
+const BINARY_PAGINATION_LINE = /^- For images and PDFs, pagination.*(?:\n|$)/m;
+/**
+ * Deep Agents' `read_file` description with its binary-file lines replaced by
+ * `line` ({@link READ_FILE_TEXT_ONLY_LINE} by default), or `null` when the multimodal line is not
+ * there (reworded upstream) — the caller then keeps the description and warns.
+ */
+export function textOnlyReadFileDescription(description, line = READ_FILE_TEXT_ONLY_LINE) {
+    if (description.includes(line))
+        return description;
+    if (!MULTIMODAL_LINE.test(description))
+        return null;
+    return description.replace(MULTIMODAL_LINE, line).replace(BINARY_PAGINATION_LINE, "");
+}
+//# sourceMappingURL=binary-read.js.map

package/dist/core/binary-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-read.js","sourceRoot":"","sources":["../../src/core/binary-read.ts"],"names":[],"mappings":"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"}

package/dist/core/file-operations.d.ts

@@ -0,0 +1,43 @@
+import type { StructuredTool } from "@langchain/core/tools";
+import type { BackendProtocolV2 } from "deepagents";
+import type { MountPrefixes } from "./mounts.js";
+/** A successful operation, in workspace form. */
+export interface FileOperationDone {
+    source: string;
+    destination?: string;
+    bytes?: number;
+}
+export type FileOperationResult = FileOperationDone | {
+    error: string;
+};
+/** Copy one workspace file. Paths in any spelling; the result names them in canonical form. */
+export declare function copyWorkspaceFile(backend: BackendProtocolV2, source: string, destination: string, options?: {
+    overwrite?: boolean;
+}): Promise<FileOperationResult>;
+/**
+ * Move one workspace file: the destination is written (and verified) before the
+ * source is removed, so a failure leaves a duplicate rather than a loss. A
+ * source the workspace serves read-only is refused before anything is written —
+ * the kernel refuses it too, but an ungoverned agent has only this.
+ */
+export declare function moveWorkspaceFile(backend: BackendProtocolV2, source: string, destination: string, options?: {
+    overwrite?: boolean;
+    mountPrefixes?: MountPrefixes;
+}): Promise<FileOperationResult>;
+/** Remove one workspace file — a file, never a folder. */
+export declare function removeWorkspaceFile(backend: BackendProtocolV2, path: string): Promise<FileOperationResult>;
+/** The descriptions the model is handed. */
+export declare const FILE_OPERATION_DESCRIPTIONS: {
+    readonly copy_file: string;
+    readonly move_file: string;
+    readonly remove_file: string;
+};
+/**
+ * The runtime's file operations over `ctx.backend` — the assembly's workspace
+ * backend, which resolves agent paths against the session bound for the turn,
+ * as Deep Agents' own file tools do.
+ */
+export declare function createFileOperationTools(ctx: {
+    backend: BackendProtocolV2;
+    mountPrefixes: MountPrefixes;
+}): StructuredTool[];

package/dist/core/file-operations.js

@@ -0,0 +1,368 @@
+import { tool } from "langchain";
+import { z } from "zod";
+import { COPY_FILE_TOOL, MOVE_FILE_TOOL, REMOVE_FILE_TOOL } from "../machine/tool-names.js";
+import { binaryMimeTypeOf, formatSize } from "./binary-read.js";
+import { canonicalizeRelPath } from "./workspace.js";
+import { classifyWorkspacePath } from "./zones.js";
+/** Why the store refused a path, from whatever it said or threw. */
+function classify(detail) {
+    if (/read-only mount/.test(detail))
+        return "it is served by a read-only mount";
+    if (/symlink|symbolic link|ELOOP/i.test(detail))
+        return "it is a symbolic link, which the workspace does not follow";
+    if (/EISDIR|is_directory|is a directory/i.test(detail))
+        return "it is a directory; this tool works on one file";
+    if (/ENOENT|not found|file_not_found/i.test(detail))
+        return "it does not exist";
+    if (/EACCES|EPERM|permission/i.test(detail))
+        return "permission was denied";
+    if (/cannot delete|not support|not available/i.test(detail))
+        return "the store serving it cannot do that";
+    return "the store refused it";
+}
+const message = (err) => (err instanceof Error ? err.message : String(err));
+/** A workspace-form path as every backend accepts it. */
+const keyOf = (path) => `/${path}`;
+/** `TextDecoder` that refuses invalid UTF-8 and keeps a byte-order mark. */
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function asText(bytes) {
+    try {
+        return strictUtf8.decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+function sameBytes(a, b) {
+    if (a.byteLength !== b.byteLength)
+        return false;
+    for (let i = 0; i < a.byteLength; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** One path's raw bytes, or `null` when the backend has no raw transfer or it failed. */
+async function download(backend, path) {
+    if (!backend.downloadFiles)
+        return null;
+    try {
+        const [res] = await backend.downloadFiles([keyOf(path)]);
+        return res?.content ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `readRaw` as a gate: the file's content, or the refusal any read of it meets.
+ * A filesystem `readRaw` reports a directory as not found; the raw channel names
+ * it, and is consulted for the reason only.
+ */
+async function gate(backend, path, verb) {
+    let refusal;
+    try {
+        const res = await backend.readRaw(keyOf(path));
+        if (!res.error && res.data)
+            return { content: res.data.content };
+        refusal = res.error ?? "not found";
+    }
+    catch (err) {
+        refusal = message(err);
+    }
+    let reason = classify(refusal);
+    if (reason === "it does not exist" && backend.downloadFiles) {
+        try {
+            const [res] = await backend.downloadFiles([keyOf(path)]);
+            if (res?.error === "is_directory")
+                reason = classify(res.error);
+        }
+        catch {
+            // No raw transfer: the first reason stands.
+        }
+    }
+    return { error: `Cannot ${verb} '${path}': ${reason}.` };
+}
+/** Whether a file is already at `path` (a refusal to read it says nothing either way). */
+async function fileExists(backend, path) {
+    try {
+        const res = await backend.readRaw(keyOf(path));
+        return !res.error && res.data !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** The source's exact bytes, gated by `readRaw`'s refusals. */
+async function readSource(backend, path, verb) {
+    const read = await gate(backend, path, verb);
+    if ("error" in read)
+        return read;
+    const { content } = read;
+    if (ArrayBuffer.isView(content)) {
+        return { bytes: new Uint8Array(content.buffer, content.byteOffset, content.byteLength) };
+    }
+    // Text: the backend decoded it, which loses whatever was not UTF-8. The path
+    // has passed `readRaw`'s refusals, so its raw bytes may now be taken.
+    const exact = await download(backend, path);
+    if (exact)
+        return { bytes: exact };
+    const text = Array.isArray(content) ? content.join("\n") : String(content ?? "");
+    // Without the raw channel, a replacement character is where decoding may have
+    // lost bytes: refuse rather than write something the source never held.
+    if (text.includes("�")) {
+        return {
+            error: `Cannot ${verb} '${path}': it is not UTF-8 text, and the store serving it cannot hand over ` +
+                `its bytes unchanged.`,
+        };
+    }
+    return { bytes: new TextEncoder().encode(text) };
+}
+/** A `write`/`uploadFiles` outcome as the refusal, or `null` when it succeeded. */
+async function attempt(path, verb, op) {
+    try {
+        const res = await op();
+        return res?.error ? `Cannot ${verb} to '${path}': ${classify(res.error)}.` : null;
+    }
+    catch (err) {
+        return `Cannot ${verb} to '${path}': ${classify(message(err))}.`;
+    }
+}
+/**
+ * What the store now holds at `path`, read back to confirm a write: the raw
+ * bytes when it can download them, else what `readRaw` returns (bytes, or text
+ * encoded as UTF-8). `null` when it cannot be read back at all.
+ */
+async function readBack(backend, path) {
+    const raw = await download(backend, path);
+    if (raw)
+        return raw;
+    try {
+        const res = await backend.readRaw(keyOf(path));
+        if (res.error || !res.data)
+            return null;
+        const { content } = res.data;
+        if (ArrayBuffer.isView(content))
+            return new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
+        return new TextEncoder().encode(Array.isArray(content) ? content.join("\n") : String(content));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write `bytes` at `path` and confirm the store kept them, or say why not.
+ *
+ * The text channel goes first whenever it can carry the bytes: base64 for a
+ * binary-typed path (Deep Agents' convention — the store decodes it), the text
+ * itself when the bytes are valid UTF-8. A store that kept something else — the
+ * base64 string as given, a decoded variant — gets the raw channel next, when it
+ * has one. Bytes no text channel carries claim the path with an empty `write`
+ * first, because the upload follows a symlink and a write does not. Every write
+ * is read back; a destination the operation created and could not fill is
+ * removed again, so a refusal leaves nothing behind.
+ */
+async function writeDestination(backend, path, bytes, verb, fresh) {
+    const binaryType = binaryMimeTypeOf(path) !== undefined;
+    const text = binaryType ? null : asText(bytes);
+    const kept = async () => {
+        const back = await readBack(backend, path);
+        return back !== null && sameBytes(back, bytes);
+    };
+    if (binaryType || text !== null) {
+        const content = binaryType ? Buffer.from(bytes).toString("base64") : text;
+        const refused = await attempt(path, verb, async () => backend.write(keyOf(path), content));
+        if (refused)
+            return refused;
+        if (await kept())
+            return null;
+    }
+    else {
+        const claimed = await attempt(path, verb, async () => backend.write(keyOf(path), ""));
+        if (claimed)
+            return claimed;
+    }
+    if (backend.uploadFiles) {
+        const uploadFiles = backend.uploadFiles.bind(backend);
+        const refused = await attempt(path, verb, async () => (await uploadFiles([[keyOf(path), bytes]]))[0]);
+        if (refused)
+            return refused + (await leftBehind(backend, path, fresh));
+        if (await kept())
+            return null;
+    }
+    const why = binaryType
+        ? "a write to a binary-typed path carries base64, which the store must decode, and it did not"
+        : text === null
+            ? "it holds files of this type as text, and this file is not text"
+            : "what it holds differs from what was written";
+    return (`Cannot ${verb} to '${path}': the store serving it did not keep the file's bytes — ${why}.` +
+        (await leftBehind(backend, path, fresh)));
+}
+/** Undo a failed write the operation created; the sentence saying what is left. */
+async function leftBehind(backend, path, fresh) {
+    if (fresh && (await removeAt(backend, path)) === null)
+        return " Nothing was kept.";
+    return ` '${path}' was left as the store wrote it.`;
+}
+/** Canonical workspace form of each path, or the refusal of the first that has none. */
+function canonicalPaths(verb, ...given) {
+    const paths = [];
+    for (const path of given) {
+        const resolved = canonicalizeRelPath(path);
+        if (resolved.escapes)
+            return { error: `Cannot ${verb} '${path}': it resolves outside the workspace root.` };
+        if (resolved.path === "")
+            return { error: `Cannot ${verb} '${path}': it names the workspace root, not a file.` };
+        paths.push(resolved.path);
+    }
+    return { paths };
+}
+/** The checks a copy and a move share before any byte moves. */
+async function precheckTransfer(backend, verb, source, destination, overwrite) {
+    const canonical = canonicalPaths(verb, source, destination);
+    if ("error" in canonical)
+        return canonical;
+    const [from, to] = canonical.paths;
+    if (from === to) {
+        return { error: `Cannot ${verb} '${from}' onto itself: the source and the destination are the same file.` };
+    }
+    const existed = await fileExists(backend, to);
+    if (existed && !overwrite) {
+        return {
+            error: `Cannot ${verb} to '${to}': a file is already there. Pass overwrite: true to replace it, or ` +
+                `choose another destination.`,
+        };
+    }
+    return { from, to, fresh: !existed };
+}
+/** Copy one workspace file. Paths in any spelling; the result names them in canonical form. */
+export async function copyWorkspaceFile(backend, source, destination, options = {}) {
+    const checked = await precheckTransfer(backend, "copy", source, destination, options.overwrite === true);
+    if ("error" in checked)
+        return checked;
+    const read = await readSource(backend, checked.from, "copy");
+    if ("error" in read)
+        return read;
+    const refused = await writeDestination(backend, checked.to, read.bytes, "copy", checked.fresh);
+    if (refused)
+        return { error: refused };
+    return { source: checked.from, destination: checked.to, bytes: read.bytes.byteLength };
+}
+/**
+ * Move one workspace file: the destination is written (and verified) before the
+ * source is removed, so a failure leaves a duplicate rather than a loss. A
+ * source the workspace serves read-only is refused before anything is written —
+ * the kernel refuses it too, but an ungoverned agent has only this.
+ */
+export async function moveWorkspaceFile(backend, source, destination, options = {}) {
+    const checked = await precheckTransfer(backend, "move", source, destination, options.overwrite === true);
+    if ("error" in checked)
+        return checked;
+    const { from, to, fresh } = checked;
+    if (classifyWorkspacePath(from, options.mountPrefixes) === "authored") {
+        return {
+            error: `Cannot move '${from}': it is served by a read-only mount, so it cannot be removed. Use ` +
+                `copy_file to copy it instead.`,
+        };
+    }
+    const read = await readSource(backend, from, "move");
+    if ("error" in read)
+        return read;
+    const refused = await writeDestination(backend, to, read.bytes, "move", fresh);
+    if (refused)
+        return { error: refused };
+    const removed = await removeAt(backend, from);
+    if (removed) {
+        return {
+            error: `Copied '${from}' to '${to}', but could not remove '${from}': ${removed}. Both files now ` +
+                `exist.`,
+        };
+    }
+    return { source: from, destination: to, bytes: read.bytes.byteLength };
+}
+/** Delete the file at `path`; the reason it was refused, or `null`. */
+async function removeAt(backend, path) {
+    if (!backend.delete)
+        return "the store serving it cannot delete";
+    try {
+        const res = await backend.delete(keyOf(path));
+        return res.error ? classify(res.error) : null;
+    }
+    catch (err) {
+        return classify(message(err));
+    }
+}
+/** Remove one workspace file — a file, never a folder. */
+export async function removeWorkspaceFile(backend, path) {
+    const canonical = canonicalPaths("remove", path);
+    if ("error" in canonical)
+        return canonical;
+    const [target] = canonical.paths;
+    // The same refusals a read meets: a folder, a missing file, a symlink.
+    const read = await gate(backend, target, "remove");
+    if ("error" in read)
+        return read;
+    const refused = await removeAt(backend, target);
+    if (refused)
+        return { error: `Cannot remove '${target}': ${refused}.` };
+    return { source: target };
+}
+/** The descriptions the model is handed. */
+export const FILE_OPERATION_DESCRIPTIONS = {
+    [COPY_FILE_TOOL]: [
+        "Copies one file to another path, byte for byte — text or binary (an image, a PDF, a .docx) — " +
+            "without reading it into the conversation. Creates the destination's folders and leaves the " +
+            "source untouched.",
+        "",
+        "Usage:",
+        "- Use it to start from a template or asset (e.g. one in a skill's assets/) instead of " +
+            "read_file followed by write_file.",
+        "- A file already at destination is refused unless overwrite is true.",
+        "- It copies a single file, not a folder.",
+    ].join("\n"),
+    [MOVE_FILE_TOOL]: [
+        "Moves one file to another path, byte for byte, without reading it into the conversation. The " +
+            "destination is written before the source is removed, so a failure leaves a copy, never a loss.",
+        "",
+        "Usage:",
+        "- A file already at destination is refused unless overwrite is true.",
+        "- A file in a read-only folder cannot be moved; use copy_file for it.",
+        "- It moves a single file, not a folder.",
+    ].join("\n"),
+    [REMOVE_FILE_TOOL]: [
+        "Deletes one file.",
+        "",
+        "Usage:",
+        "- It deletes a single file, not a folder.",
+        "- A file in a read-only folder cannot be removed.",
+    ].join("\n"),
+};
+const transferSchema = (verb) => z.object({
+    source: z.string().describe(`Path of the file to ${verb}`),
+    destination: z.string().describe(`Path to ${verb} it to`),
+    overwrite: z
+        .boolean()
+        .optional()
+        .describe("Replace a file already at destination (default false: such a destination is refused)"),
+});
+/** One line for the model: the success sentence, or `Error: …`. */
+function render(res, done) {
+    return "error" in res ? `Error: ${res.error}` : done(res);
+}
+/**
+ * The runtime's file operations over `ctx.backend` — the assembly's workspace
+ * backend, which resolves agent paths against the session bound for the turn,
+ * as Deep Agents' own file tools do.
+ */
+export function createFileOperationTools(ctx) {
+    const { backend, mountPrefixes } = ctx;
+    return [
+        tool(async ({ source, destination, overwrite }) => render(await copyWorkspaceFile(backend, source, destination, { overwrite: overwrite === true }), (ok) => `Copied '${ok.source}' to '${ok.destination}' (${formatSize(ok.bytes ?? 0)}).`), { name: COPY_FILE_TOOL, description: FILE_OPERATION_DESCRIPTIONS[COPY_FILE_TOOL], schema: transferSchema("copy") }),
+        tool(async ({ source, destination, overwrite }) => render(await moveWorkspaceFile(backend, source, destination, { overwrite: overwrite === true, mountPrefixes }), (ok) => `Moved '${ok.source}' to '${ok.destination}' (${formatSize(ok.bytes ?? 0)}).`), { name: MOVE_FILE_TOOL, description: FILE_OPERATION_DESCRIPTIONS[MOVE_FILE_TOOL], schema: transferSchema("move") }),
+        tool(async ({ file_path }) => render(await removeWorkspaceFile(backend, file_path), (ok) => `Removed '${ok.source}'.`), {
+            name: REMOVE_FILE_TOOL,
+            description: FILE_OPERATION_DESCRIPTIONS[REMOVE_FILE_TOOL],
+            schema: z.object({ file_path: z.string().describe("Path of the file to delete") }),
+        }),
+    ];
+}
+//# sourceMappingURL=file-operations.js.map

package/dist/core/file-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-operations.js","sourceRoot":"","sources":["../../src/core/file-operations.ts"],"names":[],"mappings":"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"}

package/dist/core/path-mapping.d.ts

@@ -15,12 +15,19 @@ import type { BackendProtocolV2 } from "deepagents";
  *    agent-visible listings, so it is stripped on the way out.
  *
  * Inbound: `/x` → `/<prefix>/x`. Outbound: every `path` a result carries
- * (`ls`/`glob` entries, `grep` matches, `write`/`edit` results) is mapped back.
+ * (`ls`/`glob` entries, `grep` matches, `write`/`edit`/`delete` results,
+ * download and upload responses) is mapped back.
  * A result path that does not start with the prefix is left untouched — the
  * inner backend is free to report paths we did not ask about.
  */
 /** The prefix in effect for a call: a fixed string, or resolved per call. */
 export type PrefixResolver = () => string | undefined;
+/**
+ * A mapped backend: raw-byte transfer and deletion are always present. Transfer
+ * throws when the wrapped backend lacks it, as `CompositeBackend` does; deletion
+ * answers an error, as `CompositeBackend` does.
+ */
+export type MappedBackend = BackendProtocolV2 & Required<Pick<BackendProtocolV2, "downloadFiles" | "uploadFiles" | "delete">>;
 /**
  * Wrap `backend` so it is addressed under `prefix` from the outside, mapping
  * paths in both directions. `prefix` may be a resolver, returning `undefined`
@@ -35,7 +42,7 @@ export type PrefixResolver = () => string | undefined;
 export declare function mountSubtree(backend: BackendProtocolV2, prefix: string | PrefixResolver, options?: {
     passthrough?: (relPath: string, prefix: string) => boolean;
     /**
-     * Refuse `write`/`edit` at the mount instead of delegating. Read-only is a
+     * Refuse `write`/`edit`/`uploadFiles`/`delete` at the mount instead of delegating. Read-only is a
      * property of the mount, so an authored mount cannot be written through even
      * by a caller that bypasses governance — the kernel's `zone.read-only` rule
      * remains the agent-facing diagnostic, not the only enforcement.
@@ -49,4 +56,4 @@ export declare function mountSubtree(backend: BackendProtocolV2, prefix: string
      * which is exactly the confusion that makes it retry with invented paths.
      */
     displayPrefix?: string;
-}): BackendProtocolV2;
+}): MappedBackend;

package/dist/core/path-mapping.js

@@ -102,6 +102,33 @@ export function mountSubtree(backend, prefix, options = {}) {
             const res = await backend.edit(mapIn(filePath, active), oldString, newString, replaceAll);
             return res.path === undefined ? res : { ...res, path: mapOut(res.path, active) };
         },
+        // Raw-byte transfer. A backend without it throws, as `CompositeBackend` does
+        // for a route without it, so a caller has one "unsupported" signal to handle.
+        async downloadFiles(paths) {
+            if (!backend.downloadFiles)
+                throw new Error("Backend does not support downloadFiles");
+            const actives = paths.map(prefixFor);
+            const res = await backend.downloadFiles(paths.map((path, i) => mapIn(path, actives[i])));
+            return res.map((entry, i) => ({ ...entry, path: mapOut(entry.path, actives[i]) }));
+        },
+        async delete(filePath) {
+            if (options.readOnly)
+                return readOnlyError("delete", filePath);
+            if (!backend.delete)
+                return { error: `Cannot delete '${displayPath(filePath)}': the store serving it cannot delete.` };
+            const active = prefixFor(filePath);
+            const res = await backend.delete(mapIn(filePath, active));
+            return res.path === undefined ? res : { ...res, path: mapOut(res.path, active) };
+        },
+        async uploadFiles(files) {
+            if (options.readOnly)
+                return files.map(([path]) => ({ path, error: "permission_denied" }));
+            if (!backend.uploadFiles)
+                throw new Error("Backend does not support uploadFiles");
+            const actives = files.map(([path]) => prefixFor(path));
+            const res = await backend.uploadFiles(files.map(([path, content], i) => [mapIn(path, actives[i]), content]));
+            return res.map((entry, i) => ({ ...entry, path: mapOut(entry.path, actives[i]) }));
+        },
     };
 }
 function optionalRel(prefix) {