@bevel-software/platform-core-backend 0.23.0 → 0.24.0

package/dist/modules/workspace/workspace.tools.js

@@ -1,16 +1,17 @@
 import { spawn } from 'node:child_process';
 import nodeFs from 'node:fs/promises';
 import { join } from 'node:path';
+import AdmZip from 'adm-zip';
 import { ToolError } from '../tool-helpers/tool.contract.js';
 import { BRANCH_INPUT, toolDef } from '../tool-helpers/tool-def.js';
 import { notifyAgentRead, assertAgentWriteAllowed, SESSION_ID_INPUT, } from './agent-access.gate.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import { assertBranchProvided } from '../../shared/domain-errors.js';
+import { assertBranchProvided, GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
-import { assertInsideRepo, assertRepoRootNameFreeArgs, normalizePathArgs } from '../kb-fs/repo-path.js';
+import { assertInsideRepo, assertRepoRootNameFree, assertRepoRootNameFreeArgs, isInsideRepo, normalizePathArgs, } from '../kb-fs/repo-path.js';
 import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
 import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isRolesYamlPath } from '../access-model/roles-yaml-guard.js';
@@ -23,14 +24,16 @@ import { fileTypeOf, needsContent } from './file-readers/content-mode.js';
 import { createFileReaderRegistry } from './file-readers/file-reader.registry.js';
 import { DocumentReader } from './file-readers/document-reader.js';
 import { mcpImageResult } from '@bevel-software/platform-mcp-core';
-import { LEGACY_AGENTS_FILE, folderPlaceholderPath, isFolderPlaceholder, isPlatformFile, isPlatformFolder, platformFileCreationRefusal, platformFileNames, platformFileRefusal, platformFolderRefusal, entryExistsMessage, } from '@bevel-software/platform-shared';
+import { folderPlaceholderPath, isFolderPlaceholder, isPlatformFile, isPlatformFolder, platformFileCreationRefusal, platformFileRefusal, platformFileUploadRefusal, platformFolderRefusal, entryExistsMessage, } from '@bevel-software/platform-shared';
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import { removeEmptyDirs } from './empty-dirs.js';
-import { PROPOSAL_ROUTE_NOTE, rethrowAsWriteDenial } from './write-denial.js';
+import { rethrowAsWriteDenial } from './write-denial.js';
+import { sharedRulesPointer } from '../agent-instructions/shared-file-rules.js';
 import { notFound, orDeclaredNotFound, orNotFound } from './not-found.js';
 import { logger } from '../../shared/logging.js';
 import { printable } from '../../shared/printable.js';
 import { DestinationTakenError, inspectDestination } from '../../shared/rename-no-replace.js';
+import { isSymlinkZipEntry, isZipNoiseEntry, readZipEntry, zipEntryName, zipEntryNameRefusal, zipEntrySegments, } from './zip-entry-rules.js';
 const log = logger('workspace-tools');
 /** How many files `file_stat` counts under a folder before it stops and says so. */
 const DESCENDANTS_CAP = 10_000;
@@ -122,53 +125,23 @@ async function keepFolderOf(fs, ctx, branch, removedPath, kbDirName) {
         throw err;
     }
 }
-/**
- * Appended (centrally, in `mount`) to EVERY workspace tool description. The
- * platform's managed agent guide sits at the workspace root and documents the
- * conventions of that knowledge base; agents (ours and external) should consult
- * it before touching files. It rides on every entrypoint — reads (grep/
- * list_files/file_stat) included — because any of them can be a session's first
- * touch.
- *
- * `CLAUDE.md` is named as a fallback because knowledge bases seeded before the
- * rename still carry one, and the seeder never deletes a file it did not
- * expect. Naming both means an agent finds the conventions either way, instead
- * of reading none because it looked for the newer name and stopped.
- *
- * WHEN THE GUIDE HAS BEEN RENAMED the sentence names two files, ours first. The
- * second is the organisation's OWN `AGENTS.md`, which on such a deployment is
- * ordinary content the platform never touches — and which no harness reads for a
- * remote agent, because a remote agent has no checkout. Telling it to read both
- * is the only way the conventions the customer actually wrote reach the agent
- * working in their knowledge base. Under the default name the wording collapses
- * to the one file it has always named.
- *
- * A FUNCTION of the layout, called when a description is built: the name is a
- * deployment setting, and a module-scope string would snapshot the default.
- */
-function kbConventionsNote(layout) {
-    const agentsFile = layout.agentsFile ?? LEGACY_AGENTS_FILE;
-    if (agentsFile === LEGACY_AGENTS_FILE) {
-        return ' Before your first read or change in a workspace, read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed — if either exists: it holds the author\'s conventions for this knowledge base, and you should follow them.';
-    }
-    return (` Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
-        '`AGENTS.md` if it also exists (the organisation\'s own conventions) — or `CLAUDE.md` on a knowledge base seeded before it was renamed: together they hold the conventions for this knowledge base, and you should follow them.');
-}
-/** The platform files as a tool description lists them — the guide under its own name. */
-function platformFileList(layout) {
-    return platformFileNames(layout)
-        .map((name) => `\`${name}\``)
-        .join(', ');
-}
 const int = (description) => ({ type: 'integer', description });
 const str = (description) => ({ type: 'string', description });
 /**
- * Where pictures go, on the two tools that write pages. An agent in core cannot
- * upload bytes yet (TODOS.md), but it can write the page with the link a person
- * will satisfy, and this sentence is what keeps every page it writes on the
- * README's convention: images beside the page, linked relatively.
+ * The upload route, named on every tool that takes content as a JSON string.
+ *
+ * ONE sentence, and the tools' own: it is what stops the three failures the
+ * route was built for. An agent landing 27 files read each one and typed it
+ * out again as a tool argument: a 37 KB write was truncated mid-answer, a page
+ * of regex backslashes failed to parse as a JSON parameter, and a PNG could not
+ * be sent at all. None of that is discoverable from a refusal — a truncated
+ * write reports success — so the tools that invite it name where the bytes
+ * should go instead, in the description itself, for a client that reads
+ * nothing else. WHY, and how the route is used, is one of the shared rules
+ * (`agent-instructions/shared-file-rules.ts`): said in full on three
+ * descriptions it took each of them past the length a client cuts at.
  */
-const IMAGE_CONVENTION_NOTE = ' Images: keep them in an `assets/` folder next to the page that uses them and link them with a relative path, e.g. `![Approval screen](./assets/approval-screen.png)`; the page renders them inline.';
+const UPLOAD_ROUTE_NOTE = ' Large, escape-heavy or binary content does not go through here: use `request_file_upload` + `apply_file_upload`.';
 /**
  * A path input that names the clone folder, and says what happens when it does
  * not. The tools are rooted at the WORKSPACE dir, one level above the git clone,
@@ -202,6 +175,9 @@ const RESERVED_ROOT_NAME_TARGETS = {
     copy_file: ['dest'],
     move_file: ['dest'],
     unzip: ['destination'],
+    // The folder the upload lands in. Each of its own paths is checked again
+    // inside the handler — an archive chooses its entry names, not the caller.
+    apply_file_upload: ['destination'],
 };
 function asText(content) {
     return typeof content === 'string' ? content : content.toString('utf8');
@@ -219,14 +195,6 @@ function asBytes(content) {
  * `read_file`, which extracts unbudgeted) will cover the rest.
  */
 const UNCACHED_DOCS_PER_GREP = 20;
-/**
- * THE binary capability contract, stated once and appended (in `mount`) to
- * every file tool's description — which is also what `tools_info` returns.
- * The split it states is enforced by the reader registry: the text tools
- * refuse what their reader marks not `textEditable` (and binary content under
- * any name) with a `binary_not_writable` refusal; the byte tools never look.
- */
-export const CONTENT_RULE = ' Content rule (the same on every file tool): read_file returns text for text files and extracted text for documents (.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf, .eml/.msg); write_file, write_files and edit_file accept TEXT only — they refuse documents, images, archives and other binary files (legacy .doc/.ppt/.xls included) with kind `binary_not_writable`, naming the file\'s kind and the tool to use instead; copy_file, move_file, delete_file and unzip act on bytes of any kind; new binary content arrives through upload (`request_upload_token` + `apply_upload` where offered, otherwise Upload in the app). file_stat reports `contentMode` (`text` | `document` | `binary`) so you can decide before acting.';
 /** What a `binary_not_writable` refusal points to, in the order to try them. */
 const BINARY_USE_INSTEAD = ['upload', 'copy_file', 'move_file'];
 /**
@@ -237,7 +205,7 @@ const BINARY_USE_INSTEAD = ['upload', 'copy_file', 'move_file'];
  */
 function binaryNotWritable(fileKind, explanation) {
     return new ToolError(`${explanation} [binary_not_writable: this file's kind is ${fileKind}; write_file, write_files and edit_file accept text only. ` +
-        'Use upload for new bytes (`request_upload_token` + `apply_upload` where offered, otherwise Upload in the app), ' +
+        'Use upload for new bytes (`request_file_upload` + `apply_file_upload`, or Upload in the app), ' +
         'or copy_file / move_file to place bytes that are already in the workspace.]', 415, { kind: 'binary_not_writable', fileKind, useInstead: [...BINARY_USE_INSTEAD] });
 }
 /** The generic why, for a reader without format-specific refusal copy. */
@@ -314,30 +282,6 @@ const WRITE_MODE_INPUT = {
         'holds something; `overwrite` replaces what is there, and creates the file when there is nothing; `update` replaces an ' +
         'EXISTING file and refuses (`missing`) a path that holds nothing.',
 };
-/** The same three modes, said once, for both tool descriptions. */
-const WRITE_MODE_NOTE = ' `mode` decides what may happen at a path and DEFAULTS TO `create`: `create` writes a new file and refuses a path that ' +
-    'already exists (`exists`, with the path — pass `mode: overwrite` to replace it), `overwrite` replaces what is there ' +
-    '(creating it if there is nothing), `update` replaces an existing file and refuses a path that does not exist (`missing`). ' +
-    'A refused path is left exactly as it was.';
-/**
- * What an agent needs to know about escape sequences in the content it sends,
- * on the three tools that take content as a JSON string.
- *
- * The three write routes — the MCP endpoint, the `/api/agent/tools/<name>`
- * route and `call_tool_chain` — were measured end to end against raw requests
- * and a byte-level read of the stored file (see
- * `__tests__/escape-sequences.routes.test.ts`): each stores content exactly as
- * the JSON string value decodes ONCE. So when an escape arrives already
- * decoded, the decoding happened in the client that built the request, and no
- * tool here can tell that content from content that was meant to be decoded.
- * Hence a warning rather than a fix, and the pointer to the one route whose
- * payload is bytes rather than a JSON string.
- */
-const ESCAPE_SEQUENCE_NOTE = ' Escape sequences: some clients decode them in arguments before sending, so content meant to CONTAIN an escape rather ' +
-    'than what it stands for (the six characters backslash, `u`, `0`, `0`, `4`, `1`, say, rather than the letter `A`) can ' +
-    'reach this tool already decoded — what arrives is stored byte for byte, so when that distinction matters, verify what ' +
-    'landed (`read_file`, or a hash) and send such content through the upload route (`request_upload_token` + `apply_upload` ' +
-    'where offered, otherwise Upload in the app), which lands it unchanged.';
 /** The refusal `create` gives on a path that already holds something. */
 function pathExists(path) {
     return new ToolError(`"${displayPath(path)}" already exists — pass mode: overwrite to replace it, or write to a different path.`, 409, { code: 'exists', path });
@@ -361,6 +305,144 @@ function decideWrite(mode, path, exists) {
         return 'updated';
     return exists ? 'replaced' : 'created';
 }
+/**
+ * How many of an upload's paths the answer NAMES before it stops and says how
+ * many there were. A 300-file zip's full outcome list is pages of text an agent
+ * pays for on every call; 25 is enough to see the shape of what happened, and
+ * `total` plus `truncated` say that there is more. `all: true` asks for the
+ * rest, for a caller that really does have to read each one.
+ */
+const APPLY_ANSWER_CAP = 25;
+/**
+ * How many entries of one uploaded archive are landed, and how many bytes of
+ * uncompressed content in total.
+ *
+ * Tighter than `unzip`'s own caps on purpose. An apply lands its whole set as
+ * ONE commit, which means every entry's bytes are held in memory at once —
+ * the property that makes the commit atomic is the one that makes a zip bomb
+ * expensive. The upload itself is already bounded by the deployment's upload
+ * limit; these bound what that upload is allowed to expand into.
+ */
+const APPLY_MAX_ENTRIES = 5_000;
+const APPLY_MAX_TOTAL_BYTES = 128 * 1024 * 1024; // 128 MB uncompressed
+/**
+ * Turn a stored upload into one planned path per file.
+ *
+ * A single file is one path: the destination plus the name it was sent with.
+ * A zip is one path per member, with the member's folder structure kept under
+ * the destination — judged by the same entry rules `unzip` applies
+ * (`zip-entry-rules.ts`), plus one `unzip` does not have: an entry that is a
+ * symbolic LINK is refused outright. A zip stores a link as a member whose
+ * bytes are its target text, so a reader that ignored the mode bits would
+ * write that text out as a file — content nobody sent, under a name that was
+ * meant to point elsewhere.
+ */
+/** The refusal an entry gets when the archive would expand past what one commit lands. */
+function tooLargeToApply() {
+    return `This archive expands past the ${APPLY_MAX_TOTAL_BYTES} byte total the apply lands in one commit; this entry was not applied.`;
+}
+async function planUpload(upload, destination, kbDirName) {
+    const bytes = await nodeFs.readFile(upload.absolutePath);
+    if (upload.kind !== 'zip') {
+        return [{ path: `${destination}/${upload.filename}`, content: bytes }];
+    }
+    let zip;
+    try {
+        zip = new AdmZip(bytes);
+    }
+    catch (err) {
+        throw new ToolError(`"${upload.filename}" could not be opened as a .zip archive: ${err instanceof Error ? err.message : String(err)}`, 422, { code: 'unreadable_archive' });
+    }
+    const planned = [];
+    let seen = 0;
+    let totalBytes = 0;
+    for (const entry of zip.getEntries()) {
+        const rawName = zipEntryName(entry.entryName);
+        if (isZipNoiseEntry(rawName))
+            continue;
+        if (seen >= APPLY_MAX_ENTRIES) {
+            planned.push({
+                path: rawName || '(empty)',
+                error: 'too_many_entries',
+                message: `This archive holds more than ${APPLY_MAX_ENTRIES} entries; the rest were not applied.`,
+            });
+            continue;
+        }
+        seen++;
+        const nameRefusal = zipEntryNameRefusal(rawName);
+        if (nameRefusal !== null) {
+            planned.push({ path: rawName || '(empty)', error: 'invalid_entry', message: nameRefusal });
+            continue;
+        }
+        if (isSymlinkZipEntry(entry)) {
+            planned.push({
+                path: rawName,
+                error: 'link',
+                message: `"${rawName}" is a symbolic link, not a file; an upload lands files, never links.`,
+            });
+            continue;
+        }
+        // A folder comes into being with the files under it (the write path mkdirs
+        // each parent), so a directory member has nothing of its own to land.
+        if (entry.isDirectory)
+            continue;
+        const segments = zipEntrySegments(rawName);
+        const target = [destination, ...segments].join('/');
+        // Belt and braces: `zipEntryNameRefusal` already refuses a `..` segment
+        // and a root-anchored name, so nothing should reach here that climbs out.
+        // The check stays because the cost of being wrong about that is bytes
+        // landing outside the folder the caller named.
+        if (!target.startsWith(`${destination}/`) || !isInsideRepo(target, kbDirName)) {
+            planned.push({ path: rawName, error: 'invalid_entry', message: 'Path escapes destination' });
+            continue;
+        }
+        // Through the one bounded reader `unzip` uses too, capped at what is left
+        // of the budget: a deflate stream can expand a thousandfold, and the
+        // header's declared size is the archive's claim, not a fact — an entry
+        // declaring ZERO would otherwise be inflated with no cap at all (see
+        // `readZipEntry`). A read that fails is this entry's outcome and no more.
+        const read = readZipEntry(entry, APPLY_MAX_TOTAL_BYTES - totalBytes);
+        if (!read.ok) {
+            planned.push(read.reason === 'too_large'
+                ? { path: rawName, error: 'too_large', message: tooLargeToApply() }
+                : { path: rawName, error: 'unreadable_entry', message: `"${rawName}" could not be read: ${read.detail}.` });
+            continue;
+        }
+        totalBytes += read.data.byteLength;
+        planned.push({ path: target, content: read.data });
+    }
+    return planned;
+}
+/**
+ * Record on `entry` that this path was refused, saying what the gate that
+ * refused it said. Four kinds of refusal count as one path's outcome: a
+ * typed tool refusal (`exists`, `platform_file`, the mode gate), a permission
+ * refusal (the caller may not write this path, where the DESTINATION was
+ * writable), the git folder in any spelling, and a path-shape refusal from the
+ * repository rules. Anything else
+ * is not a verdict about this path — it is a gate failing — so it travels on
+ * and the whole apply fails loudly, exactly as it does in `write_files`.
+ */
+function refuseEntry(entry, err) {
+    entry.outcome = 'refused';
+    if (err instanceof ToolError) {
+        const details = (err.details ?? {});
+        entry.error = details.code ?? details.kind ?? 'refused';
+        entry.message = err.message;
+        return;
+    }
+    if (err instanceof AccessDeniedError) {
+        entry.error = 'write-denied';
+        entry.message = err.message;
+        return;
+    }
+    if (err instanceof GitInternalsError || err instanceof WorkflowValidationError) {
+        entry.error = err.payload?.kind ?? 'refused';
+        entry.message = err.message;
+        return;
+    }
+    throw err;
+}
 /** The three modes, as a set the handler can check a raw argument against. */
 const WRITE_MODES = ['create', 'overwrite', 'update'];
 /**
@@ -541,7 +623,16 @@ skillSaveCheck,
  * would be made on. Optional so tool harnesses need not wire it; the read
  * verdict alone then decides, which differs only at a root.
  */
-changeGate) {
+changeGate, 
+/**
+ * The upload-token store behind `request_file_upload` / `apply_file_upload`
+ * — the route an agent lands bytes by, without their content passing
+ * through the model. Optional for the same reason the two above are: a tool
+ * harness that is about the file primitives need not stand one up. Every
+ * real composition wires it (`create-core-server.ts`), and without it the
+ * two tools are not mounted at all rather than mounted and broken.
+ */
+uploads) {
     const { kbDirName } = kb;
     /**
      * The one extension→reader registry every read-shaped decision routes
@@ -1083,10 +1174,14 @@ changeGate) {
     const linkRefusal = (path) => `"${path}" is a symbolic link; the agent tools never follow or remove links.`;
     const mount = (spec) => {
         const path = `/api/agent/tools/${spec.name}`;
-        // Every workspace entrypoint carries the agent-guide reminder, every file
-        // tool the one content rule, and every tool a permission can refuse the
-        // proposal route — appended once here so no tool (especially the
-        // read-only ones a session hits first) can miss them.
+        // Every description ends with ONE sentence pointing at the rules these
+        // tools share — the content rule, the agent guide, the write modes, the
+        // dry-run protocol, the proposal route. They used to be appended here in
+        // FULL, which made a description several thousand characters of text the
+        // agent had already read on the tool above, and clients cut a long
+        // description from the END, where what is specific to the tool sits. The
+        // rules themselves are in the handshake instructions and in the managed
+        // guide (see `shared-file-rules.ts`), stated once and from one text.
         // Whether a call to this tool MUST name a branch, read off the tool's own
         // declaration rather than assumed of the family. Every tool mounted here
         // requires `branch` today; keying on the schema means a tool that declares
@@ -1094,10 +1189,8 @@ changeGate) {
         // own route) is not handed a refusal it never asked for.
         const requiresBranch = (spec.inputs.required ?? []).includes('branch');
         const describe = () => (typeof spec.description === 'function' ? spec.description() : spec.description) +
-            (spec.proposable ? PROPOSAL_ROUTE_NOTE : '') +
-            (spec.fileTool === false ? '' : CONTENT_RULE) +
-            kbConventionsNote(kb.layout) +
-            (spec.gated ? agentAccessGate.notes.gatedToolNote() : '');
+            (spec.gated ? agentAccessGate.notes.gatedToolNote() : '') +
+            sharedRulesPointer(kb.layout);
         const def = toolDef({
             name: spec.name,
             description: describe(),
@@ -1246,7 +1339,13 @@ changeGate) {
     mount({
         name: 'read_file',
         gated: true,
-        description: 'Read a workspace file as text. Returns `{ path, content }`. Images (.png/.jpg/.jpeg/.gif/.webp) return the IMAGE ITSELF as native MCP image content (plus a one-line text note naming the file), so you can look at the picture — up to 3.5 MB of raw image data; a larger image gets an honest refusal asking for a locally downscaled copy or a smaller export (`.svg` is text and reads as text). Images come back only on a DIRECT call: inside `call_tool_chain` an image read yields an `{ image_omitted, note }` stub instead. Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods) and PDFs return their EXTRACTED text under an honest `[extracted text of …]` header, with `[slide N]`/`[sheet: Name]`/`[page N]` markers — the extraction is READ-ONLY (layout/images omitted; such files cannot be edited as text, only replaced by uploading a new version). Email files (.eml/.msg) return their EXTRACTED text the same way: a `[from]`/`[to]`/`[subject]`/`[date]` header block, the body (plain-text part preferred; an HTML-only body is stripped to text), and an `[attachments]` name list — attachments are listed, never extracted. Other binary files return a one-line description instead of raw bytes. Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref; ignored for an image) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. A spill ref is workspace-independent: `branch` is ignored for it.',
+        description: 'Read a workspace file as text. Returns `{ path, content }`. What comes back for a document, an email file, an image ' +
+            'or any other binary file is the content rule\'s business (see the shared rules): text files as text, documents and ' +
+            'email files as extracted text, an image as the picture itself, anything else as a one-line description. ' +
+            'Optional `offset`/`limit` slice the content (characters for a file, bytes for a `__tool_chain_spill__/…` ref; ignored ' +
+            'for an image) — use them to page through large files or a `call_tool_chain` spill rather than reading multi-MB in full. ' +
+            'It also reads a `__tool_chain_spill__/…` ref back from a truncated `call_tool_chain`: such a ref belongs to no ' +
+            'workspace, so `branch` is ignored for it.',
         inputs: {
             type: 'object',
             properties: {
@@ -1350,12 +1449,17 @@ changeGate) {
     mount({
         name: 'file_stat',
         gated: true,
-        description: () => 'Get a file/directory\'s metadata (name, type, size, …) without returning content. A file also reports `contentMode`: `text` (read, write and edit it as text), `document` (read returns an extraction; replace it by upload) or `binary` (bytes: copy, move, delete, or replace by upload), plus `kind` (`text` | `document` | `image` | `binary`), `mime`, `mimeSource` and `textEditable` — decided by the same file readers read_file, grep and the write tools use, so an extensionless text file is `text/plain`.' +
-            ' Every entry also reports what you may DO with it. ' +
-            `\`managed\` is true for a platform item — a platform file (${platformFileList(kb.layout)}) or a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`); managed items are never movable or deletable through these tools. ` +
-            '`access: { read, write, download, owner }` is your own verdict under the access rules; pass `explainAccess: true` to learn why, and who else holds each verb. `movable` and `deletable` say whether `move_file` / `delete_file` / `delete_folder` would be allowed for you, judged like their dry runs: not managed, no symbolic link, and on a protected branch you hold write on the item AND on every file under a folder (on a draft branch writes are not gated). `movable` judges the source side only; the destination is judged by a `move_file` dry run. ' +
-            'For a folder, `descendants` is the number of files under it at any depth; counting stops at 10000 and `descendantsTruncated` says so, and past that point `movable` and `deletable` are false because a folder that large was not judged in full — run the `move_file` or `delete_folder` dry run for the real verdict. ' +
-            'Call this before a move or delete to see what it would touch.',
+        description: 'Get a file/directory\'s metadata (name, type, size, …) without returning content, and what you may DO with it. ' +
+            'A file also reports `contentMode`, `kind`, `mime`, `mimeSource` and `textEditable` — decided by the same readers ' +
+            'read_file, grep and the write tools use, so an extensionless text file is `text/plain`. ' +
+            '`access: { read, write, download, owner }` is your own verdict under the access rules; pass `explainAccess: true` to ' +
+            'learn why, and who else holds each verb. ' +
+            'Call this before a move or delete: `managed`, `movable` and `deletable` answer the shared rules on what these tools ' +
+            'never move or delete, judged like the dry runs (on a draft branch writes are not gated); `movable` judges the SOURCE ' +
+            'side only, so the destination still wants a `move_file` dry run. ' +
+            'For a folder, `descendants` counts the files under it at any depth; counting stops at 10000 and ' +
+            '`descendantsTruncated` says so, past which `movable` and `deletable` are false — a folder that large was not judged ' +
+            'in full, so run the `move_file` or `delete_folder` dry run for the real verdict.',
         inputs: {
             type: 'object',
             properties: {
@@ -1645,9 +1749,7 @@ changeGate) {
         gated: true,
         description: 'Write a workspace TEXT file. The change is committed + pushed as you. Returns `{ path, bytes, outcome }`, where `outcome` is ' +
             '`created`, `replaced` or `updated`.' +
-            WRITE_MODE_NOTE +
-            IMAGE_CONVENTION_NOTE +
-            ESCAPE_SEQUENCE_NOTE,
+            UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1725,9 +1827,7 @@ changeGate) {
             '`created` / `replaced` / `updated` for a path it wrote, or `refused` with `error` (the code) and `message` (why) for a ' +
             'path it could not. `count` is how many were written. A path it refuses — the mode said no, or the file is not text — ' +
             'does not stop the others; read `files` to see what landed.' +
-            WRITE_MODE_NOTE +
-            IMAGE_CONVENTION_NOTE +
-            ESCAPE_SEQUENCE_NOTE,
+            UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1891,7 +1991,7 @@ changeGate) {
         name: 'edit_file',
         gated: true,
         description: 'Replace an exact string in a workspace TEXT file. `old_string` must appear exactly once unless `replace_all`. Committed + pushed as you.' +
-            ESCAPE_SEQUENCE_NOTE,
+            UPLOAD_ROUTE_NOTE,
         inputs: {
             type: 'object',
             properties: {
@@ -1940,8 +2040,7 @@ changeGate) {
     mount({
         name: 'delete_file',
         gated: true,
-        description: () => 'Delete ONE workspace file (a symbolic link is refused: links are never followed or removed). Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`. ' +
-            `A platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) and git metadata are refused.`,
+        description: 'Delete ONE workspace file. Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`.',
         inputs: {
             type: 'object',
             properties: {
@@ -1995,10 +2094,12 @@ changeGate) {
         name: 'delete_folder',
         gated: true,
         description: 'Delete a workspace FOLDER and every file under it, at any depth; the whole folder lands as ONE committed + pushed change as you — all of it or none of it — then the empty folder is removed. This is the one way a folder goes away: the folder that held it stays, even if this was all it had, and a folder holding nothing but its empty-folder placeholder counts as empty. ' +
-            'Preflight first: `dryRun: true` changes nothing and answers `{ path, kind: "folder", descendants, files, filesTruncated, allowed, reason? }` — `descendants` is the file count, `files` names up to 100 of them. ' +
-            'A non-empty folder is deleted only with `confirm: true`; without it the call deletes nothing and returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — dry-run, check the impact, then confirm. ' +
-            'Refused (in a dry run as `allowed: false` with the `reason`): a platform folder (the repository root or a reserved root folder such as `KnowledgeBase/`), git metadata, a folder holding a symbolic link (links are never removed), and a folder holding any file you may not write. A path that is a file is refused with a pointer to `delete_file`, and a path through a symbolic link is refused (links are never followed). ' +
-            'The folder\'s own platform files (`access.md`, `.bevelignore`) go with it in that same one change, so its files are never left ungoverned part-way; you must be able to write those platform files too.',
+            'The dry run answers `{ path, kind: "folder", descendants, files, filesTruncated, allowed, reason? }` — `descendants` is ' +
+            'the file count, `files` names up to 100 of them — and a non-empty folder wants `confirm: true`. ' +
+            'Beyond what the shared rules refuse, a folder HOLDING a symbolic link, or any file you may not write, is refused ' +
+            '(the link itself is never removed), and a path that is a FILE ' +
+            'is refused with a pointer to `delete_file`. You must be able to write the folder\'s own platform files too: they go ' +
+            'with it in that same one change, so its files are never left ungoverned part-way.',
         inputs: {
             type: 'object',
             properties: {
@@ -2159,10 +2260,14 @@ changeGate) {
     mount({
         name: 'move_file',
         gated: true,
-        description: () => 'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Lands as a delete + create, committed + pushed as you. ' +
-            `Rules: the destination must not exist — a move never overwrites a file or merges into a folder; a platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) is refused with "<name> is a platform file and stays in its folder." — a folder that moves takes its own platform files along, still in their folder; a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`) and git metadata are refused; a move cannot create a platform file or folder at \`dest\` either (renaming a note to \`access.md\` is refused); a path through a symbolic link is refused, since links are never followed; on a protected branch you must be able to write both ends — for a folder, every file under it at its old and its new path. ` +
-            'Access follows the destination folder. Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, with every `access.md` inside a moved folder counted at its new place. ' +
-            'A move whose `accessChanges` is true runs only with `confirm: true`; without it the call moves nothing and returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — dry-run, check the impact, then confirm.',
+        // A plain string again: what refuses a move names the guide, and that is in
+        // the shared rules now, which are rebuilt from the layout where they live.
+        description: 'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Lands as a delete + create, committed + pushed as you. ' +
+            'The destination must not exist — a move never overwrites a file or merges into a folder. Access follows the ' +
+            'DESTINATION folder, so a move can change what you (and others) may do with the file: the dry run answers ' +
+            '`{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }`, where `access` is your ' +
+            'own `{ read, write, download, owner }` at the source and at the destination AS IT WILL BE once the move has landed, ' +
+            'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`.',
         inputs: {
             type: 'object',
             properties: {
@@ -2498,6 +2603,300 @@ changeGate) {
             }), 'Nothing to extract');
         },
     });
+    // ── uploads (bytes that never pass through the model) ───────────────────
+    //
+    // The pair exists because MCP tool arguments are JSON. Every byte an agent
+    // sends through `write_file` is first typed out by the model, which
+    // truncates long files, mangles backslash and `\u` escapes, and cannot carry
+    // a PNG at all. `request_file_upload` answers an address; the agent POSTs
+    // the file (or one zip holding many) there with any HTTP client;
+    // `apply_file_upload` lands it on a branch in one commit. The bytes go from
+    // the agent's disk to the server's and never enter a prompt.
+    //
+    /**
+     * Why one of an upload's paths may not be landed, judged on the path ALONE —
+     * or undefined when nothing about the name itself refuses it.
+     *
+     * The platform files are the whole of it. `access.md` governs who may read
+     * and write the folder it sits in, `roles.yaml` says which roles exist, and
+     * the agent guide is read as instructions: each is configuration the platform
+     * obeys, and each has a write path that CHECKS the change (the roles gate
+     * refuses an edit that would lock every admin out; a folder's access rules
+     * are judged against who is asking). Bytes arriving by upload meet none of
+     * those gates — they are a buffer the sender chose — so an upload never
+     * lands one, whatever else the caller may write. `unzip` has refused
+     * `roles.yaml` from an archive for the same reason; this is that rule, over
+     * all four names.
+     */
+    const platformFileReason = (wsPath) => {
+        const rel = toKbRelative(wsPath, kbDirName);
+        return rel !== null && isPlatformFile(rel, kb.layout) ? platformFileUploadRefusal(rel) : undefined;
+    };
+    /**
+     * `apply_file_upload`'s handler: resolve the stored bytes into one path per
+     * file, judge each path the way `write_files` judges its own, and land the
+     * survivors as ONE commit.
+     *
+     * The judging is deliberately the same shape as `write_files`, down to the
+     * second verdict under the lock, because the promise the ticket makes is
+     * that an upload is judged "exactly as `write_file` would judge it". Three
+     * gates run per path and a path that fails one is that path's outcome and no
+     * more: the deployment's write hook, the platform-file rule above, and the
+     * `mode`. What is judged ONCE for the whole call is the destination — a
+     * caller who may not write the folder at all gets one refusal naming the
+     * change-request route, rather than the same refusal repeated per entry.
+     */
+    const applyFileUpload = async (a, ctx, uploads) => {
+        const branch = a.branch;
+        const token = a.token;
+        if (typeof token !== 'string' || token === '') {
+            throw new ToolError('Name the `token` `request_file_upload` answered with, after POSTing the file to its `uploadUrl`.', 400, { code: 'token-required' });
+        }
+        const mode = modeOf(a);
+        const destination = a.destination.replace(/\/+$/, '');
+        assertInsideRepo(destination, kbDirName);
+        // CLAIMED, not consumed: an apply refused whole (a protected destination,
+        // an archive that will not open) leaves the token alive so the caller can
+        // retry somewhere else rather than send the bytes again. The claim is what
+        // keeps it single-use meanwhile — a second apply finds the token in use.
+        const upload = uploads.claim(token, ctx.user.id);
+        let spent = false;
+        try {
+            const fs = await ctx.getFilesystem(branch);
+            const root = await workspaceRoot(branch, ctx);
+            // The destination, once, for the whole call. On a protected branch a
+            // caller who may not write the folder gets the lock gate's own refusal —
+            // which `rethrowAsWriteDenial` turns into `write-denied` with the
+            // change-request steps — and nothing lands.
+            const blockedDest = await writeBlocked(branch, ctx, [destination]);
+            if (blockedDest.length > 0)
+                throw await writeRefusal(branch, blockedDest[0], 'dir');
+            if ((await kindOf(fs, destination)) === 'file') {
+                throw new ToolError(`"${displayPath(destination)}" is a file, not a folder — \`destination\` names the folder the upload lands in.`, 409, { code: 'not_a_folder' });
+            }
+            const planned = await planUpload(upload, destination, kbDirName);
+            const paths = planned.filter((p) => p.content !== undefined).map((p) => p.path);
+            // One batched access read for every path, like `write_files` — empty on
+            // a draft branch, where changes reach a protected branch only through a
+            // change request.
+            const blocked = new Set(await writeBlocked(branch, ctx, paths));
+            const writes = [];
+            const outcomes = [];
+            /** The `files` entry for `writes[i]`, so the under-lock verdict can revise it. */
+            const entryOf = [];
+            for (const item of planned) {
+                const entry = { path: item.path };
+                outcomes.push(entry);
+                if (item.content === undefined) {
+                    entry.outcome = 'refused';
+                    entry.error = item.error;
+                    entry.message = item.message;
+                    continue;
+                }
+                const wsPathOf = item.path;
+                try {
+                    if (blocked.has(wsPathOf))
+                        throw await writeRefusal(branch, wsPathOf);
+                    const platform = platformFileReason(wsPathOf);
+                    if (platform !== undefined)
+                        throw new ToolError(platform, 422, { code: 'platform_file' });
+                    // The git folder is never a workspace path, in any spelling. A ZIP
+                    // entry's name has already met this rule in `zipEntryNameRefusal`; a
+                    // SINGLE uploaded file's has not — `.git` is a name the upload
+                    // route's `validateFilename` accepts — and the preflight that reads
+                    // the caller's own arguments never sees it either, because the name
+                    // came from the upload, not from the call. Asked here so that path
+                    // is REFUSED like any other, with the rest of the upload landing,
+                    // rather than failing the whole apply from inside `writeFiles`.
+                    assertNoGitInternalsSegment(wsPathOf);
+                    assertRepoRootNameFree(wsPathOf, kbDirName);
+                    // A link already on disk under the destination must not redirect
+                    // these bytes — the rule `unzip` applies per entry, applied here on
+                    // the path the write will take.
+                    const link = await symlinkOnPath(root, wsPathOf);
+                    if (link !== undefined) {
+                        throw new ToolError(`"${wsPathOf}" goes through the symbolic link "${link}"; an upload never follows links.`, 400, { code: 'symlink' });
+                    }
+                    writePolicy.assertPathWritable(ctx.sessionId, wsPathOf);
+                    await assertAgentWriteAllowed(agentAccessGate, ctx, branch, wsPathOf);
+                    // An earlier entry of this same upload counts as existing, as it
+                    // does in `write_files`: two `create` entries for one path are a
+                    // mistake the commit would otherwise hide.
+                    const exists = writes.some((w) => w.path === wsPathOf) || (await kindOf(fs, wsPathOf)) !== null;
+                    entry.outcome = decideWrite(mode, wsPathOf, exists);
+                    writes.push({ path: wsPathOf, content: item.content });
+                    entryOf.push(entry);
+                }
+                catch (err) {
+                    refuseEntry(entry, err);
+                }
+            }
+            // The mode gate again, with every path's lock held — the verdict the
+            // answer carries, for the reason `write_file` states at length. A path
+            // whose verdict changed under the lock is dropped from the batch and
+            // reported refused, leaving the rest to land.
+            const recheck = async (pending) => {
+                const kept = [];
+                for (let i = 0; i < pending.length; i++) {
+                    const entry = entryOf[i];
+                    try {
+                        const exists = kept.some((k) => k.path === pending[i].path) || (await kindOf(fs, pending[i].path)) !== null;
+                        entry.outcome = decideWrite(mode, pending[i].path, exists);
+                        kept.push(pending[i]);
+                    }
+                    catch (err) {
+                        refuseEntry(entry, err);
+                    }
+                }
+                return kept;
+            };
+            if (writes.length > 0) {
+                // `write: true` guarantees a LockingFilesystem here; `writeFiles` lands
+                // the whole set as ONE commit and takes a Buffer as content, so bytes
+                // reach disk exactly as they were sent — no text decode anywhere on
+                // the way, which is what makes a PNG and a backslash-heavy page land
+                // with the checksum they were uploaded with.
+                const batching = fs;
+                // In the DESTINATION folder's TURN, which `delete_folder` takes over the
+                // same subtree (and `keepFolderOf` with it). `writeFiles` creates the
+                // destination, and any folder above a zip entry on the way to it, as
+                // part of landing the batch — and a folder delete running between that
+                // creation and the commit enumerates the folder's files BEFORE these
+                // exist and then removes the folder they are landing in, which is an
+                // answer saying `created` for bytes that are already gone. The turn is
+                // taken OUTSIDE `writeFiles`, so it is held across the under-lock
+                // recheck and the commit both, and in the same order the delete takes
+                // its own (the folder's turn first, then each path's lock), which is
+                // what keeps two callers from waiting on each other's half.
+                await ctx.workspaceService.withFolderTurn(workspaceIdForBranch(branch), destination, async () => {
+                    await batching.writeFiles(writes, `Apply upload of ${writes.length} file(s)`, [], recheck);
+                });
+            }
+            // The token is spent once an ANSWER exists, even an answer in which
+            // every path was refused: the apply ran and said what happened at each
+            // path, and re-running it would say the same. Only a refusal that landed
+            // nothing AND answered nothing (thrown above) gives the token back.
+            spent = true;
+            await uploads.consume(token);
+            const listed = a.all === true ? outcomes : outcomes.slice(0, APPLY_ANSWER_CAP);
+            return {
+                destination,
+                count: outcomes.filter((o) => o.outcome !== 'refused').length,
+                total: outcomes.length,
+                files: listed,
+                ...(listed.length < outcomes.length ? { truncated: true } : {}),
+            };
+        }
+        finally {
+            if (!spent)
+                uploads.release(token);
+        }
+    };
+    // Mounted only when the composition supplied a store — see the `uploads`
+    // parameter. Core always does.
+    if (uploads) {
+        mount({
+            name: 'request_file_upload',
+            fileTool: false,
+            description: 
+            // Within the description cap (`tool-registry/description-length.ts`):
+            // why a file goes this way is one of the shared rules, and the header
+            // spelling of the token is on the `uploadUrl` output, where the
+            // address it changes is.
+            'Ask for a one-time address to send FILE BYTES to, so their content never passes through this conversation. ' +
+                'Use it for anything `write_file` cannot carry faithfully: a large file, a file full of backslashes or `\\u` ' +
+                'escapes, a binary file (a PNG, a PDF, a zip), or many files at once (zip them). ' +
+                'Returns `{ uploadUrl, token, expiresAt, expiresInSeconds, maxBytes }`. THEN: ' +
+                '(1) POST the file as the raw request body to `uploadUrl` with `?filename=<name>` — ' +
+                '`curl -X POST --data-binary @skill.zip "<uploadUrl>?filename=skill.zip"` — which answers what it received; ' +
+                '(2) call `apply_file_upload` with the same `token`, a `branch` and a destination folder. ' +
+                'One token carries one file or one zip, is bound to you and expires at `expiresAt`: an upload nobody applies ' +
+                'by then is deleted, and one over `maxBytes` is refused when you send it, naming the limit.',
+            inputs: { type: 'object', properties: {}, additionalProperties: false },
+            outputs: {
+                type: 'object',
+                properties: {
+                    uploadUrl: str('The absolute URL to POST the bytes to. Carries the token; add `?filename=<name>`. To keep the token out ' +
+                        'of a URL — when the command line you send from is logged or shared — POST to this address without its ' +
+                        'last (token) segment and send the token in an `x-upload-token` header instead.'),
+                    token: str('The token itself — what `apply_file_upload` takes, and what an `x-upload-token` header carries when you ' +
+                        'would rather it not sit in a URL. Treat it as a credential.'),
+                    expiresAt: str('ISO-8601 instant after which the token, and any bytes sent with it, are gone.'),
+                    expiresInSeconds: int('Seconds from now until `expiresAt`.'),
+                    maxBytes: int('The largest upload this deployment accepts, in bytes.'),
+                },
+                required: ['uploadUrl', 'token', 'expiresAt', 'expiresInSeconds', 'maxBytes'],
+            },
+            // A read-scoped caller has nothing to do with an upload token: the only
+            // thing it unlocks is a write. Refused at the handler factory, by scope,
+            // before the token is minted.
+            write: true,
+            handler: async (_a, ctx) => uploads.issue(ctx.user),
+        });
+        mount({
+            name: 'apply_file_upload',
+            gated: true,
+            description: 'Land a file you have already uploaded (see `request_file_upload`) in a folder on a branch, in ONE commit, as you. ' +
+                'A single file lands under the name it was sent with; a zip lands as its entries, keeping their folder structure. ' +
+                'Returns `{ destination, count, total, files }`: one entry per path, each `{ path, outcome }` — `created` / ' +
+                '`replaced` / `updated`, or `refused` with `error` (the code) and `message` (why). `count` is how many landed and ' +
+                '`total` how many paths there were; `files` is cut to the first 25 unless you pass `all: true`. ' +
+                'Every path is judged one by one — by your write access, the platform-file rules and what is already there — ' +
+                'exactly as `write_file` judges it, and a refused path does not stop the others. ' +
+                'The token is single-use: it is spent by the apply that lands it, and refused if you use it twice, let it ' +
+                'expire, or present one issued to somebody else. `mode` means what it means on `write_file`.',
+            inputs: {
+                type: 'object',
+                properties: {
+                    branch: BRANCH_INPUT,
+                    token: str('The `token` from `request_file_upload`, after you have POSTed the file to its `uploadUrl`.'),
+                    destination: wsPath(kbDirName, 'Folder the upload lands in (created if it is not there yet)'),
+                    mode: WRITE_MODE_INPUT,
+                    all: {
+                        type: 'boolean',
+                        description: 'List EVERY path in `files` instead of the first 25. `total` always says how many there were, so ask for ' +
+                            'all only when you need to read each outcome.',
+                    },
+                    sessionId: SESSION_ID_INPUT,
+                },
+                required: ['branch', 'token', 'destination'],
+                additionalProperties: false,
+            },
+            outputs: {
+                type: 'object',
+                properties: {
+                    destination: str('The folder the upload was applied to (echoes the input).'),
+                    count: int('How many paths landed — the entries in `files` whose `outcome` is not `refused`.'),
+                    total: int('How many paths the upload held, whether or not `files` lists them all.'),
+                    files: {
+                        type: 'array',
+                        description: 'One entry per path, in the order the upload held them. Cut to 25 unless `all` was true.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                path: str('The workspace path this entry was judged at.'),
+                                outcome: {
+                                    type: 'string',
+                                    enum: ['created', 'replaced', 'updated', 'refused'],
+                                    description: 'What happened at this path. `refused` means nothing was written there.',
+                                },
+                                error: str('Present when `outcome` is `refused`: the refusal code — e.g. `exists`, `missing`, `invalid_entry`, `platform_file`, `write-denied`.'),
+                                message: str('Present when `outcome` is `refused`: the full refusal, the same one `write_file` would have given.'),
+                            },
+                            required: ['path', 'outcome'],
+                        },
+                    },
+                    truncated: { type: 'boolean', description: 'True when `files` was cut: `total` is larger than what it lists. Pass `all: true` for the rest.' },
+                },
+                required: ['destination', 'count', 'total', 'files'],
+            },
+            write: true,
+            // So a protected-branch refusal arrives as `write-denied`, with the
+            // change-request steps, exactly as it does from write_file.
+            proposable: true,
+            handler: async (a, ctx) => applyFileUpload(a, ctx, uploads),
+        });
+    }
     // ── shell (internal-only) ───────────────────────────────────────────────
     mount({
         name: 'execute_command',