@bevel-software/platform-core-backend 0.25.2 → 0.27.0

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

@@ -2,16 +2,16 @@ 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 { hasHttpStatus, 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, GitInternalsError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { 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, assertRepoRootNameFree, assertRepoRootNameFreeArgs, isInsideRepo, normalizePathArgs, } from '../kb-fs/repo-path.js';
+import { assertInsideRepo, assertRepoRootNameFree, assertRepoRootNameFreeArgs, isInsideRepo, normalizePathArgs, normalizeWorkspacePath, } 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';
@@ -24,17 +24,24 @@ 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 { folderPlaceholderPath, isFolderPlaceholder, isPlatformFile, isPlatformFolder, platformFileCreationRefusal, platformFileRefusal, platformFileUploadRefusal, platformFolderRefusal, entryExistsMessage, } from '@bevel-software/platform-shared';
+import { folderPlaceholderPath, isFolderPlaceholder, isPlatformFile, isPlatformFolder, platformFileCreationRefusal, platformFileRefusal, platformFileUploadRefusal, platformFolderRefusal, isRepositoryOwnFile, repositoryOwnFileDeleteRefusal, entryExistsMessage, } from '@bevel-software/platform-shared';
 import { AccessDeniedError } from '../access-model/access-errors.js';
+import { AGENT_GUIDE_FILE, isAgentGuidePath, isManagedGuide, withPlatformGuideAppended, } from '../agent-guide/agent-guide.js';
 import { removeEmptyDirs } from './empty-dirs.js';
+import { FIRST_RUN_SECTION_ID, firstRunNote, knowledgeFolderIsNew } from './first-run.js';
+import { planMoveLinks } from './move-links.js';
+import { MoveLockedError, MoveRacedError } from '../kb-fs/locking-filesystem.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 { buildDownload } from './agent-download.builder.js';
+import { DOWNLOAD_MAX_FILES, ZIP_DOWNLOAD_MAX_BYTES } from './workspace.service.js';
 import { isSymlinkZipEntry, isZipNoiseEntry, readZipEntry, zipEntryName, zipEntryNameRefusal, zipEntrySegments, } from './zip-entry-rules.js';
 const log = logger('workspace-tools');
+/** Types that run scripts wherever they are opened, sent by `request_file_download` as plain bytes. */
+const ACTIVE_CONTENT_TYPES = new Set(['image/svg+xml', 'text/html', 'application/xhtml+xml']);
 /** How many files `file_stat` counts under a folder before it stops and says so. */
 const DESCENDANTS_CAP = 10_000;
 /** How many of a folder's files a `delete_folder` answer names. */
@@ -540,7 +547,9 @@ async function searchRootKind(fs, path) {
     }
 }
 /** JS grep over the workspace tree (read methods only) — bounded by match + depth caps. */
-async function grepWalk(fs, dir, re, out, max, depth, gate, notifyRead, docs) {
+async function grepWalk(fs, dir, re, out, max, depth, gate, notifyRead, docs, 
+/** A file the walk leaves to its caller: never opened, never counted against `max`. */
+skip = () => false) {
     if (out.length >= max || depth > 12)
         return;
     let entries;
@@ -562,7 +571,10 @@ async function grepWalk(fs, dir, re, out, max, depth, gate, notifyRead, docs) {
             continue;
         const p = dir ? `${dir}/${e.name}` : e.name;
         if (e.type === 'directory') {
-            await grepWalk(fs, p, re, out, max, depth + 1, gate, notifyRead, docs);
+            await grepWalk(fs, p, re, out, max, depth + 1, gate, notifyRead, docs, skip);
+        }
+        else if (skip(p)) {
+            continue;
         }
         else {
             // Opening a file is a read of it, even when the walk started at a root
@@ -605,7 +617,7 @@ const BATCH_SAVE_WARNINGS_OUTPUT = {
  * the tools were built has to be written here rather than onto the shared
  * `SESSION_ID_INPUT` constant.
  */
-function sessionIdInputOf(def) {
+export function sessionIdInputOf(def) {
     const inputs = def.inputs;
     return inputs?.properties?.body?.properties?.sessionId;
 }
@@ -640,7 +652,35 @@ changeGate,
  * 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) {
+uploads, 
+/**
+ * The platform's agent guide (see `modules/agent-guide`), which `read_file`
+ * and `file_stat` answer at the guide's name in the repository root — after
+ * the knowledge base's own file of that name, when it has one. Optional for
+ * the harnesses that are about the file primitives; without it the two
+ * tools read the disk and nothing else.
+ */
+agentGuide, 
+/**
+ * The download-link store behind `request_file_download` — the way an agent
+ * takes files OUT without their content passing through the model. Optional
+ * for the harnesses about the file primitives; without it the tool is not
+ * mounted.
+ */
+downloads, 
+/**
+ * The starter pack the knowledge base was filled from, if any (see
+ * `modules/onboarding`): its untouched pages do not end the `firstRun`
+ * note, and the note names the pages it suggests. Optional; without it the
+ * note reads the knowledge folder alone.
+ */
+starterPacks, 
+/**
+ * The one tree walk (see `shared/fs.contract.ts`), for the `firstRun`
+ * note's look at the knowledge folder. Optional for the harnesses about the
+ * file primitives; without it `start_session` answers the id alone.
+ */
+disk) {
     const { kbDirName } = kb;
     /**
      * The one extension→reader registry every read-shaped decision routes
@@ -979,6 +1019,26 @@ uploads) {
         const rel = toKbRelative(norm, kbDirName);
         return rel !== null && isPlatformFolder(rel, kb.layout) ? platformFolderRefusal(rel) : undefined;
     };
+    /**
+     * Why `delete_file` may not delete the FILE at `path` whoever asks, or
+     * undefined when the caller's write access decides. Narrower than
+     * {@link managedReason}: a nested `access.md` never moves, but whoever may
+     * write it may delete it — as in the app — and its folder then follows its
+     * parent's rules. The root's `access.md` and `roles.yaml` are deleted by
+     * nobody. Judged on the on-disk spelling, as `managedReason` is.
+     */
+    const fileDeleteRefusal = (path) => {
+        const norm = path.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+        if (isGitMetadata(norm))
+            return managedReason(norm, 'file');
+        const rel = toKbRelative(norm, kbDirName);
+        if (rel === null || !isPlatformFile(rel, kb.layout))
+            return undefined;
+        if (isRepositoryOwnFile(rel, kb.layout))
+            return repositoryOwnFileDeleteRefusal(rel);
+        const name = rel.slice(rel.lastIndexOf('/') + 1);
+        return name === 'access.md' ? undefined : `${name} is a platform file and cannot be deleted through the agent tools.`;
+    };
     /** The workspace root on disk for `branch`. */
     const workspaceRoot = (branch, ctx) => ctx.workspaceService.getWorkspacePath(workspaceIdForBranch(branch));
     /**
@@ -1190,23 +1250,22 @@ uploads) {
         // 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
-        // it optional (and resolves absence itself, as `list_tool_setup` does on its
-        // 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.gated ? agentAccessGate.notes.gatedToolNote() : '') +
-            sharedRulesPointer(kb.layout);
+            (spec.gated ? agentAccessGate.notes.gatedToolNote() : '');
         const def = toolDef({
             name: spec.name,
             description: describe(),
             path,
             inputs: spec.inputs,
             outputs: spec.outputs,
+            refusesItself: spec.refusesItself,
             tags: spec.write ? ['workspace', 'write'] : ['workspace'],
         });
+        // Every tool here declares `branch` required in its inputs, which is how
+        // `toolDef` records it: the tool handler refuses a branch-less call before
+        // the path work below and before any handler. Most of these tools would
+        // meet the same refusal one layer down at `getFilesystem`, but not all —
+        // `unzip` hands `branch` straight to the workspace service by id.
         registry.registerInternalTool(def);
         if (!spec.internalOnly)
             registry.registerExternalTool(def);
@@ -1253,17 +1312,6 @@ uploads) {
         // path, and exempting it there would be a workspace-relative path that
         // never reached the repository — the whole bug, spelled with a prefix.
         toolHandler(async (args, ctx) => {
-            // FIRST, before the path work and before any handler: every tool
-            // mounted here declares `branch` as a required, non-empty string, and
-            // nothing enforced that, so a call that named none was carried down
-            // until `workspaceIdForBranch` made a workspace directory out of the
-            // missing value. Most of these tools would meet the same refusal one
-            // layer down at `getFilesystem`, but not all of them do — `unzip`
-            // hands `branch` straight to the workspace service by id — so the
-            // check belongs on the mount every one of them shares rather than on
-            // the resolver only some of them reach.
-            if (requiresBranch && !spec.resolvesBranchItself)
-                assertBranchProvided(args.branch);
             // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
             if (spec.fileTool !== false)
                 await assertToolPathsNotGitInternals(args, ctx);
@@ -1291,7 +1339,9 @@ uploads) {
             catch (err) {
                 return rethrowAsWriteDenial(err, { tool: spec.name, branch: args.branch, userEmail: ctx.user.email, userId: ctx.user.id }, accessControl, kb, changeGate);
             }
-        }, { write: spec.write }));
+        }, 
+        // `execute_command` resolves its own branch (see `resolvesBranchItself`).
+        { write: spec.write, writeScope: spec.writeScope, ...(spec.resolvesBranchItself ? { branch: 'own' } : {}) }));
     };
     // ── session bootstrap (external agents) ─────────────────────────────────
     // Every read/write tool below takes a `sessionId`: the conversation the
@@ -1319,12 +1369,15 @@ uploads) {
     // transport hiccup on its first call as an unrecoverable start.
     const startSessionDef = toolDef({
         name: 'start_session',
-        description: 'Mint the id of this conversation, which the KnowledgeBase tools take as `sessionId`. Call this ONCE, at the start of your work and only once per run — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id explicitly as `sessionId` on every subsequent KnowledgeBase tool call (direct MCP calls and inside `call_tool_chain` alike). RETRYING IS SAFE: a call that fails created nothing, so retry it — there is no half-made session to clean up. If a retry lands after a success you simply hold two independent ids, which is harmless: keep passing the one id you have already used for the rest of the run and ignore the other. Returns `{ sessionId }`.',
+        description: 'Mint this conversation\'s id: the `sessionId` KnowledgeBase tools take. Call this ONCE, at the start of your work — minting a new id mid-run starts a second conversation as far as the server is concerned. The id is also a chat session in the app, so you can hand the SAME id to the `ask` tool: your reads and your questions are then one conversation. Pass the returned id as `sessionId` on every later KnowledgeBase tool call, inside `call_tool_chain` too. RETRYING IS SAFE: a call that fails created nothing, so retry it. If a retry lands after a success you hold two independent ids, which is harmless: keep passing the one you already used and ignore the other. Returns `{ sessionId }`, plus `firstRun` while the knowledge base is still empty: a note to act on.',
         path: '/api/agent/tools/start_session',
         inputs: { type: 'object', properties: {}, additionalProperties: false },
         outputs: {
             type: 'object',
-            properties: { sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.') },
+            properties: {
+                sessionId: str('The minted session id — pass it as `sessionId` on subsequent KnowledgeBase tool calls and to `ask`.'),
+                firstRun: str(`Present only while the knowledge base holds nothing but its starter guide (and a starter pack's untouched pages): what to offer the person (the guide's \`${FIRST_RUN_SECTION_ID}\` section says how).`),
+            },
             required: ['sessionId'],
         },
         tags: ['workspace'],
@@ -1341,9 +1394,99 @@ uploads) {
     // per-chat sessionIds over its lifetime.
     requireExternalSource, toolHandler(async (_args, ctx) => {
         const { sessionId } = await sessionSink.createSession(ctx.user.id, new Date());
-        return { sessionId };
+        const firstRun = await firstRunFor(ctx);
+        return firstRun ? { sessionId, firstRun } : { sessionId };
     }));
+    /**
+     * The `firstRun` note (see `first-run.ts`) while the default branch's
+     * knowledge folder holds nothing but the starter guide, else null. Asked of
+     * a clone that is ALREADY there — never one this call would have to make, so
+     * the first call of a conversation does no clone — and never allowed to fail
+     * the call: minting the id is what `start_session` is for, and the note is a
+     * courtesy on top of it.
+     */
+    const firstRunFor = async (ctx) => {
+        try {
+            if (!disk || !kb.isBranchModelConfigured())
+                return null;
+            const workspaceId = kb.defaultWorkspaceId();
+            if (!(await ctx.workspaceService.hasBootstrappedWorkspace(workspaceId)))
+                return null;
+            const knowledgeDir = kb.layout.knowledgeBaseDir;
+            // GATED LIKE A READ. The note says what the knowledge folder holds —
+            // nothing, or a pack's pages still as the pack wrote them — so it goes
+            // only to a caller who may read that folder, and judges the folder as
+            // THEY may see it: a page they may not read does not make it old for
+            // them (`mayRead` below), since reading the folder is no leave to learn
+            // what restricted pages sit in it.
+            if (!(await accessControl.canRead(workspaceId, ctx.user.email, knowledgeDir)))
+                return null;
+            const root = await ctx.workspaceService.getWorkspacePath(workspaceId);
+            const mayRead = async (rels) => {
+                const verdicts = await accessControl.canReadBatch(workspaceId, ctx.user.email, rels.map((rel) => `${knowledgeDir}/${rel}`));
+                return new Map(rels.map((rel) => [rel, verdicts.get(`${knowledgeDir}/${rel}`) === true]));
+            };
+            // A starter pack's pages, still as the pack wrote them, are tasks to
+            // fill in rather than pages anyone wrote: they leave the note standing,
+            // and the note names what the pack suggests drafting first. A pack
+            // page the caller may not read keeps the note away altogether: it
+            // names the pack and what it suggests drafting, which is about pages
+            // this caller is not to know of — in the checkout or gone from it.
+            const starter = (await starterPacks?.firstRunStarter()) ?? null;
+            const pages = starter ? await readableStarterPages(ctx, workspaceId, knowledgeDir, starter.pages) : undefined;
+            if (starter && pages && pages.size < starter.pages.size)
+                return null;
+            if (!(await knowledgeFolderIsNew(disk, join(root, kbDirName), knowledgeDir, pages, mayRead)))
+                return null;
+            return firstRunNote(`${kbDirName}/${knowledgeDir}`, starter ?? undefined);
+        }
+        catch (err) {
+            log.debug('start_session: could not tell whether the knowledge base is new', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    };
+    /** The starter pages (paths below the knowledge folder → text) the caller may read, and no other. */
+    const readableStarterPages = async (ctx, workspaceId, knowledgeDir, pages) => {
+        const rels = [...pages.keys()];
+        const verdicts = await accessControl.canReadBatch(workspaceId, ctx.user.email, rels.map((rel) => `${knowledgeDir}/${rel}`));
+        return new Map(rels.filter((rel) => verdicts.get(`${knowledgeDir}/${rel}`)).map((rel) => [rel, pages.get(rel)]));
+    };
     // ── reads ──────────────────────────────────────────────────────────────
+    /**
+     * What reading a workspace file ANSWERS, gate and all — `read_file`'s whole
+     * behaviour minus the spill ref and the `offset`/`limit` slice, which are
+     * that tool's own arguments.
+     *
+     * Factored out because a second tool has to answer the same way: `open_page`
+     * (see `modules/embed`) promises the file's text "the way `read_file` does",
+     * and the refusals `read_file` gives for a path the caller may not read or
+     * one that does not exist. Any of that re-derived there would be a second
+     * answer to a question with one correct answer — the access gate, the read
+     * hook, the extraction and the not-found message all have to match, and a
+     * copy drifts on the first change to any of them.
+     */
+    const readForTool = async (branch, p, ctx) => {
+        // The guide's name at the repository root answers with the platform's
+        // guide, which is text the code owns and every agent may read: no gate
+        // and no read hook for it. A file the knowledge base keeps under that
+        // name is ITS OWN conventions page and is read as any file is — gated,
+        // noted — and comes first, with the guide after it. A copy of the
+        // guide an earlier release wrote to disk (still on a draft, say) is
+        // recognised by its header and not served a second time.
+        if (agentGuide && isAgentGuidePath(toKbRelative(p, kbDirName) ?? '')) {
+            return { kind: 'text', text: await guideAt(branch, ctx, p) };
+        }
+        await notifyAgentRead(agentAccessGate, ctx, branch, p);
+        await assertCanRead(readGateFor(branch, ctx), p);
+        const fs = await ctx.getFilesystem(branch);
+        // Reading (extraction, image and binary handling included) happens AFTER
+        // the access gate and the read hook above — a document read is still a
+        // KB read. ONE registry dispatch picks the reader by extension.
+        const bytes = await orNotFound(p, async () => asBytes(await fs.readFile(p)));
+        return readers.readerFor(p).read(bytes, p);
+    };
     mount({
         name: 'read_file',
         gated: true,
@@ -1379,16 +1522,13 @@ uploads) {
             if (spillStore.isSpillRef(p)) {
                 return { path: p, content: await spillStore.read(p, offset, limit) };
             }
-            await notifyAgentRead(agentAccessGate, ctx, a.branch, p);
-            await assertCanRead(readGateFor(a.branch, ctx), p);
-            const fs = await ctx.getFilesystem(a.branch);
-            // Reading (extraction, image and binary handling included) happens AFTER
-            // the access gate and the read hook above — a document read is still a
-            // KB read. ONE registry dispatch picks the reader by
-            // extension; everything below just maps its ReadResult onto the tool's
-            // result shape.
-            const bytes = await orNotFound(p, async () => asBytes(await fs.readFile(p)));
-            const result = await readers.readerFor(p).read(bytes, p);
+            const slice = (content) => {
+                const start = offset && offset > 0 ? offset : 0;
+                return offset !== undefined || limit !== undefined
+                    ? content.slice(start, limit !== undefined ? start + limit : undefined)
+                    : content;
+            };
+            const result = await readForTool(a.branch, p, ctx);
             // Images return the picture itself as an MCP image content block, so a
             // multimodal model SEES it. The handler returns the `McpImageResult`
             // sentinel; the MCP result shaping (`toCallToolResult` in
@@ -1407,13 +1547,102 @@ uploads) {
             // document, unreadable binary, oversized image) IS the file's honest
             // textual answer, sliced like any other content.
             const content = result.kind === 'text' ? result.text : result.message;
-            const start = offset && offset > 0 ? offset : 0;
-            const sliced = offset !== undefined || limit !== undefined
-                ? content.slice(start, limit !== undefined ? start + limit : undefined)
-                : content;
-            return { path: p, content: sliced };
+            return { path: p, content: slice(content) };
         },
     });
+    /**
+     * The knowledge base's OWN file at the guide's path, read as any file is —
+     * through the read hook and the access gate — or null when there is none,
+     * when the caller MAY NOT READ IT, or when what is there is a copy of the
+     * platform's guide an earlier release wrote (recognised by its header),
+     * which the guide served beside it would only repeat. A file that is not
+     * text (a binary squatting the name) is read for what it is: its honest
+     * textual answer.
+     *
+     * A file the caller may not read answers EXACTLY as no file does: the guide
+     * alone, with nothing said. A refusal here would tell a caller the root
+     * denies that a conventions file exists, which is the one thing the
+     * platform never tells about a file someone may not read — a restricted
+     * node is indistinguishable from an absent one on every other read.
+     */
+    /** What a read of the guide's path answers: the guide, after the knowledge base's own readable file when it has one. */
+    const guideAt = async (branch, ctx, p) => {
+        const guide = await agentGuide();
+        const own = await ownGuideFile(branch, ctx, p);
+        return own === null ? guide : withPlatformGuideAppended(own, guide);
+    };
+    const ownGuideFile = async (branch, ctx, p) => {
+        const fs = await ctx.getFilesystem(branch);
+        // Existence first, then the gate, then the hook and the bytes — nothing of
+        // theirs is read, or noted as read, before they are allowed to read it.
+        if (!(await ownGuideReadable(fs, branch, ctx, p)))
+            return null;
+        await notifyAgentRead(agentAccessGate, ctx, branch, p);
+        // Gone between the probe and the read — a concurrent delete — is the
+        // absent case: the guide alone, as a read a moment later would answer.
+        const bytes = await fs.readFile(p).then(asBytes, (err) => {
+            if (isAbsence(err))
+                return null;
+            throw err;
+        });
+        if (bytes === null)
+            return null;
+        const result = await readers.readerFor(p).read(bytes, p);
+        const text = result.kind === 'text' ? result.text : result.kind === 'image' ? result.note : result.message;
+        return isManagedGuide(text) ? null : text;
+    };
+    /**
+     * Whether there is a file of the knowledge base's own at the guide's path
+     * that THIS caller may read. False for nothing there and for a file the
+     * access rules close to them, on purpose and without distinction (see
+     * {@link ownGuideFile}).
+     */
+    const ownGuideReadable = async (fs, branch, ctx, p) => {
+        // The permission verdict BEFORE the filesystem is asked anything, as on
+        // every other read: a caller the rules close the path to learns nothing
+        // from it — not that something is there, and not what the filesystem
+        // says about an entry it cannot stat.
+        const gate = readGateFor(branch, ctx);
+        const rel = toKbRelative(p, gate.kbDirName);
+        if (rel !== null && !(await gate.accessControl.canRead(gate.workspaceId, gate.userEmail, rel)))
+            return false;
+        return existsAt(fs, p);
+    };
+    /** Whether something is at `p` on `fs` — absence is false, any other failure is thrown. */
+    const existsAt = async (fs, p) => fs.stat(p).then(() => true, (err) => {
+        if (isAbsence(err))
+            return false;
+        throw err;
+    });
+    /**
+     * Whether what is at `p` is an entry of the knowledge base's own for the
+     * ordinary stat to describe: anything there except a plain file that is a
+     * copy of the guide an earlier release wrote (recognised by its header).
+     * A folder at the guide's name is theirs and is never read — reading a
+     * folder is an error, not an absence. Nothing there, at the stat or at the
+     * read a moment later (a concurrent delete), is the absent case, which the
+     * caller answers with the guide.
+     */
+    const isOwnEntryStill = async (fs, p) => {
+        const type = await fs.stat(p).then((st) => st.type, (err) => {
+            if (isAbsence(err))
+                return undefined;
+            throw err;
+        });
+        if (type === undefined)
+            return false;
+        if (type !== 'file')
+            return true;
+        const bytes = await fs.readFile(p).then(asBytes, (err) => {
+            if (isAbsence(err))
+                return null;
+            throw err;
+        });
+        if (bytes === null)
+            return false;
+        const result = await readers.readerFor(p).read(bytes, p);
+        return !(result.kind === 'text' && isManagedGuide(result.text));
+    };
     mount({
         name: 'list_files',
         gated: true,
@@ -1466,8 +1695,8 @@ uploads) {
             '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.',
+            '`descendantsTruncated` says so, past which `movable` and `deletable` are false (not judged in full): run the ' +
+            '`move_file` or `delete_folder` dry run for the real verdict.',
         inputs: {
             type: 'object',
             properties: {
@@ -1532,6 +1761,10 @@ uploads) {
                 },
                 textEditable: { type: 'boolean', description: 'Files only: whether write_file/write_files/edit_file accept this file as it is now.' },
                 mimeNote: str('Present when `mimeSource` is `fallback`: says the MIME type is a fallback, not a detected type.'),
+                platformGuide: {
+                    type: 'boolean',
+                    description: "True at the agent guide's name in the repository root when the knowledge base has no file of its own there: what read_file answers is the platform's guide, which is not on disk and cannot be written, moved or deleted.",
+                },
             },
             required: ['managed', 'movable', 'deletable', 'access'],
             additionalProperties: true,
@@ -1540,7 +1773,49 @@ uploads) {
         handler: async (a, ctx) => {
             const p = a.path;
             const branch = a.branch;
-            await notifyAgentRead(agentAccessGate, ctx, branch, p);
+            // The guide's name with no file of the knowledge base's own under it —
+            // or one the caller may not read, or a copy of the guide an earlier
+            // release wrote, none of which `read_file` serves: what a read answers
+            // there is the platform's guide, so stat says a text file is there to
+            // read — ungated, like the read — and that nothing can be moved,
+            // deleted or written at it through these tools. The three cases get
+            // ONE answer on purpose: a different one for the file the caller may
+            // not read would tell them it exists. A file of the knowledge base's
+            // own that the caller may read is a file like any other, and the
+            // ordinary answer below describes it.
+            let noted = false;
+            if (agentGuide && isAgentGuidePath(toKbRelative(p, kbDirName) ?? '')) {
+                const fs = await ctx.getFilesystem(branch);
+                const readable = await ownGuideReadable(fs, branch, ctx, p);
+                // Telling the organisation's own file from a stale copy READS it, so
+                // the read hook hears of it as it hears of a read_file there — after
+                // the gate, never before, and once (the ordinary stat below is told).
+                if (readable) {
+                    await notifyAgentRead(agentAccessGate, ctx, branch, p);
+                    noted = true;
+                }
+                const own = readable && (await isOwnEntryStill(fs, p));
+                if (!own) {
+                    const guide = await agentGuide();
+                    return {
+                        name: p.slice(p.lastIndexOf('/') + 1),
+                        type: 'file',
+                        size: Buffer.byteLength(guide, 'utf8'),
+                        managed: true,
+                        movable: false,
+                        deletable: false,
+                        access: { read: true, write: false, download: false, owner: false },
+                        contentMode: 'text',
+                        kind: 'text',
+                        mime: 'text/markdown',
+                        mimeSource: 'extension',
+                        textEditable: false,
+                        platformGuide: true,
+                    };
+                }
+            }
+            if (!noted)
+                await notifyAgentRead(agentAccessGate, ctx, branch, p);
             await assertCanRead(readGateFor(branch, ctx), p);
             // Nothing there is a 404, and the placeholder — never content — gets
             // exactly that answer: the one every file tool gives (see not-found.ts).
@@ -1571,7 +1846,11 @@ uploads) {
             // `mime` below, so it is never passed through.
             delete stat.mimeType;
             const kind = stat.type === 'directory' ? 'folder' : 'file';
-            const managed = managedReason(await onDiskSpelling(root, p), kind) !== undefined;
+            const onDisk = await onDiskSpelling(root, p);
+            const managed = managedReason(onDisk, kind) !== undefined;
+            // A nested `access.md` is managed — it never moves — yet deleted by
+            // whoever may write it, so a FILE's delete is judged on its own rule.
+            const undeletable = kind === 'file' ? fileDeleteRefusal(onDisk) !== undefined : managed;
             const verdicts = await accessAt(branch, ctx, p);
             const access = a.explainAccess === true ? { ...verdicts, ...(await explainAccessAt(branch, ctx, p, kind)) } : verdicts;
             const link = !plain || viaLink !== undefined;
@@ -1590,7 +1869,7 @@ uploads) {
             //     `movable`/`deletable` false rather than judging part of a folder
             //     and calling it the whole (`delete_folder`'s dry run, which walks
             //     uncapped, remains the authority for a folder that large).
-            const decided = managed || link;
+            const decided = (managed && undeletable) || link;
             const { files, links, truncated } = kind === 'folder'
                 ? await filesUnder(fs, p, DESCENDANTS_CAP)
                 : { files: [p], links: [], truncated: false };
@@ -1611,9 +1890,9 @@ uploads) {
             const out = {
                 ...stat,
                 managed,
-                movable: open,
+                movable: open && !managed,
                 // delete_folder also refuses a folder holding a link.
-                deletable: open && links.length === 0,
+                deletable: open && !undeletable && links.length === 0,
                 access,
             };
             if (kind === 'folder') {
@@ -1643,7 +1922,7 @@ uploads) {
     mount({
         name: 'grep',
         gated: true,
-        description: 'Regex content search across the workspace. Returns `{ matches: [{ path, line, text }] }` (capped). Use to find where something is defined/referenced. `path` may name a DIRECTORY (searches the subtree) or a single FILE (searches just that file); a path with nothing at it is an error, never an empty result. Searches INSIDE Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods), PDFs and email files (.eml/.msg) via their extracted text — matches there carry the extraction\'s line numbers, and the `[slide N]`/`[sheet: Name]`/`[page N]`/`[from]`/`[subject]` marker lines locate them; a bounded number of not-yet-extracted documents is extracted per call, and the result notes how many were skipped (re-run to cover them).',
+        description: 'Regex search across the workspace. Returns `{ matches: [{ path, line, text }] }` (capped). Use to find where something is defined/referenced. `path` may name a DIRECTORY (searches the subtree) or a single FILE (searches just that file); a path with nothing at it is an error, never an empty result. Searches INSIDE Office and OpenDocument files (.docx/.pptx/.xlsx, .odt/.odp/.ods), PDFs and email files (.eml/.msg) via their extracted text — matches there carry the extraction\'s line numbers, and the `[slide N]`/`[sheet: Name]`/`[page N]`/`[from]`/`[subject]` marker lines locate them; a bounded number of not-yet-extracted documents is extracted per call, and the result notes how many were skipped (re-run to cover them).',
         inputs: {
             type: 'object',
             properties: {
@@ -1694,10 +1973,6 @@ uploads) {
             // (an empty path is the handler's to explain), and here it would
             // otherwise name the workspace directory by another spelling.
             const searchRoot = typeof a.path === 'string' && a.path.length > 0 ? a.path : kbDirName;
-            // The search root itself goes to the read hook here; each file the walk
-            // actually opens goes to it per-file below, so a hook sees every path a
-            // grep reached rather than only the root it started from.
-            await notifyAgentRead(agentAccessGate, ctx, a.branch, searchRoot);
             const fs = await ctx.getFilesystem(a.branch);
             const gate = readGateFor(a.branch, ctx);
             const out = [];
@@ -1714,7 +1989,41 @@ uploads) {
                     : await searchRootKind(fs, searchRoot);
             /** Why a single-file search found nothing, when "no matches" would be a lie. */
             let fileNote;
-            if (kind === 'directory') {
+            // The guide is searched where it is read: a search of the repository
+            // root covers it, and a search of its own path is a search of what
+            // `read_file` answers there. The composed text is what is searched —
+            // the knowledge base's own readable file first, then the platform's
+            // guide — under the guide's path and with the line numbers a read of
+            // it gives. The walk leaves that one file to this: a match the walk
+            // made there would be the same line again, and one it COUNTED against
+            // `max_results` would be a file later in the tree never searched while
+            // the answer says nothing was cut. A file the caller may not read is
+            // absent from it, as it is from the read.
+            const guidePath = `${kbDirName}/${AGENT_GUIDE_FILE}`;
+            const rel = toKbRelative(searchRoot, kbDirName);
+            const coversGuide = agentGuide !== undefined && (kind === 'directory' ? rel === null : isAgentGuidePath(rel ?? ''));
+            // The search root goes to the read hook — once, and only when it is
+            // repository content: a folder, or a file of the knowledge base's own.
+            // The guide's own path is not told here, because `guideAt` tells the
+            // hook of the organisation's file there exactly as `read_file` does
+            // (after the gate), and the platform's guide alone is nobody's file to
+            // note. Each file the walk opens goes to the hook per file below, so a
+            // hook sees every path a grep reached rather than only its root.
+            if (!(coversGuide && kind !== 'directory')) {
+                await notifyAgentRead(agentAccessGate, ctx, a.branch, searchRoot);
+            }
+            if (coversGuide) {
+                if (kind === 'directory') {
+                    await grepWalk(fs, searchRoot, re, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs, (p) => p === guidePath);
+                }
+                const lines = (await guideAt(a.branch, ctx, guidePath)).split('\n');
+                for (let i = 0; i < lines.length && out.length < max; i++) {
+                    re.lastIndex = 0;
+                    if (re.test(lines[i]))
+                        out.push({ path: guidePath, line: i + 1, text: lines[i].slice(0, 300) });
+                }
+            }
+            else if (kind === 'directory') {
                 await grepWalk(fs, searchRoot, re, out, max, 0, gate, (p) => notifyAgentRead(agentAccessGate, ctx, a.branch, p), docs);
             }
             else {
@@ -1754,6 +2063,8 @@ uploads) {
     // ── writes (through the lock/commit pipeline) ───────────────────────────
     mount({
         name: 'write_file',
+        // A mode that is not one of the three answers `bad_mode`, which lists them.
+        refusesItself: ['mode'],
         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`.' +
@@ -1826,6 +2137,8 @@ uploads) {
     });
     mount({
         name: 'write_files',
+        // A mode that is not one of the three answers `bad_mode`, which lists them.
+        refusesItself: ['mode'],
         gated: true,
         description: 'Batch-write many files in ONE commit — far faster than calling write_file once per file when ' +
             'creating many files at once (e.g. seeding a knowledge base). Each entry is `{ path, content }`, and the files it ' +
@@ -1886,9 +2199,11 @@ uploads) {
         proposable: true,
         handler: async (a, ctx) => {
             const files = a.files ?? [];
+            // The mode is judged before anything else, so an empty batch with a mode
+            // that is not one answers `bad_mode` like any other call would.
+            const mode = modeOf(a);
             if (files.length === 0)
                 return { count: 0, files: [] };
-            const mode = modeOf(a);
             // The POLICY gate still judges the whole batch: a restricted run is a
             // call that should not have been made at all, not a per-path outcome.
             // The write hook is asked PER PATH, below, so a path it refuses is that
@@ -2113,11 +2428,9 @@ uploads) {
                 throw new ToolError(`"${path}" is a folder, not a file — use delete_folder to delete it and the files under it.`, 400);
             }
             const onDisk = await onDiskSpelling(root, path);
-            if (isGitMetadata(onDisk))
-                throw new ToolError(managedReason(onDisk, 'file'), 400);
-            if (managedReason(onDisk, 'file') !== undefined) {
-                throw new ToolError(`${onDisk.slice(onDisk.lastIndexOf('/') + 1)} is a platform file and cannot be deleted through the agent tools.`, 400);
-            }
+            const refused = fileDeleteRefusal(onDisk);
+            if (refused !== undefined)
+                throw new ToolError(refused, 400);
             await assertNoSymlinkOnPath(root, path, true);
             if ((await writeBlocked(branch, ctx, [path])).length > 0)
                 throw await writeRefusal(branch, path);
@@ -2299,12 +2612,13 @@ uploads) {
         gated: true,
         // 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. ' +
+        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. 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`.',
+            'with every `access.md` inside a moved folder counted at its new place, and a move whose `accessChanges` is true wants `confirm: true`. ' +
+            'Links are rewritten by default, in one commit with the move: those in the moved files and those in other markdown files pointing at them (`links` reports them). `rewriteLinks: false` turns that off. Path mentions in plain prose or code are never changed.',
         inputs: {
             type: 'object',
             properties: {
@@ -2313,6 +2627,7 @@ uploads) {
                 dest: wsPath(kbDirName, 'Destination path — the full new path; must not exist yet'),
                 dryRun: { type: 'boolean', description: 'Answer with the impact and change nothing.' },
                 confirm: { type: 'boolean', description: 'Required when the move changes your access. Set it only after a dry run.' },
+                rewriteLinks: { type: 'boolean', description: 'Rewrite the links into, out of and between the moved files (default true). `false` moves without touching any link.' },
                 sessionId: SESSION_ID_INPUT,
             },
             required: ['branch', 'src', 'dest'],
@@ -2333,6 +2648,11 @@ uploads) {
                 confirmationRequired: { type: 'boolean', description: 'True when the call stopped for want of `confirm: true`.' },
                 message: str('One sentence on what happened (or did not).'),
                 moved: { type: 'boolean', description: 'True once the move landed.' },
+                links: {
+                    type: 'object',
+                    description: 'The link rewrite, the same on a dry run and on the move: `{ filesEdited, linksRewritten, edits: [{ path, from, to }] (the first 100), ' +
+                        'notRewritten: [{ path, reason, links }], unsearched? }`. Absent with `rewriteLinks: false`.',
+                },
             },
             required: ['src', 'dest', 'moved'],
         },
@@ -2423,6 +2743,52 @@ uploads) {
                     : occupiedBy !== null
                         ? entryExistsMessage(occupiedBy, dest)
                         : undefined;
+            // The links are planned only for a move that may run: a refused one
+            // reads no page. The plan is the same on a dry run and on the move.
+            const rewriteLinks = a.rewriteLinks !== false;
+            const linkPlan = rewriteLinks && reason === undefined
+                ? await planMoveLinks({
+                    src,
+                    dest,
+                    branch,
+                    kbDirName,
+                    allFiles: await (async () => {
+                        const { files, links } = await filesUnder(fs, kbDirName);
+                        const symlinks = new Set(links);
+                        return files.filter((f) => !symlinks.has(f));
+                    })(),
+                    canRead: (paths) => resolveReadableMap((wid, email, rels) => accessControl.canReadBatch(wid, email, rels), workspaceIdForBranch(branch), ctx.user.email, kbDirName, paths),
+                    writeBlocked: (paths) => writeBlocked(branch, ctx, paths),
+                    // Through the guarded filesystem the tools read with, never the raw
+                    // disk: a page replaced by a link since the listing is refused there
+                    // instead of read through to wherever the link points.
+                    readText: async (p) => String(await fs.readFile(p, { encoding: 'utf8' })),
+                    // The read hook, for every page the answer would NAME — an edited
+                    // one, one left with its links listed — and for no page merely
+                    // searched: naming is the disclosure, and the hook's refusal makes
+                    // the page one the caller cannot read, covered by the one sentence.
+                    readRefused: async (path) => {
+                        try {
+                            await notifyAgentRead(agentAccessGate, ctx, branch, path);
+                            return false;
+                        }
+                        catch {
+                            return true;
+                        }
+                    },
+                    // The write hook, for a page the move would edit, at its post-move path.
+                    writeRefusal: async (_lockAt, path) => {
+                        try {
+                            await assertAgentWriteAllowed(agentAccessGate, ctx, branch, path);
+                            return null;
+                        }
+                        catch (err) {
+                            return `refused: ${err instanceof Error ? err.message : String(err)}`;
+                        }
+                    },
+                })
+                : undefined;
+            const moveReason = reason ?? linkPlan?.overCap;
             const impact = {
                 src,
                 dest,
@@ -2430,8 +2796,9 @@ uploads) {
                 descendants,
                 access: { before, after },
                 accessChanges,
-                allowed: reason === undefined,
-                ...(reason !== undefined ? { reason } : {}),
+                allowed: moveReason === undefined,
+                ...(moveReason !== undefined ? { reason: moveReason } : {}),
+                ...(linkPlan ? { links: linkPlan.report } : {}),
             };
             if (a.dryRun === true)
                 return { ...impact, dryRun: true, moved: false };
@@ -2446,6 +2813,8 @@ uploads) {
             }
             if (collision)
                 throw new ToolError(reason, 409);
+            if (linkPlan?.overCap !== undefined)
+                throw new ToolError(linkPlan.overCap, 400);
             if (accessChanges && a.confirm !== true) {
                 return {
                     ...impact,
@@ -2458,7 +2827,42 @@ uploads) {
             // no-replace move is what guarantees it. A destination created between
             // the two — by another agent, or by the sidebar, which moves without
             // taking this lock — comes back here as a refusal, not an overwrite.
-            await asEntryExists(() => fs.moveFile(src, dest));
+            if (linkPlan === undefined) {
+                await asEntryExists(() => fs.moveFile(src, dest));
+            }
+            else {
+                // The move and every link edit, one commit. Under the locks, each page
+                // is checked to still hold the bytes its edit was computed from.
+                const edits = linkPlan.edits.map((e) => ({ path: e.path, lockAt: e.lockAt, content: e.content }));
+                const check = async () => {
+                    for (const e of linkPlan.edits) {
+                        const now = await fs.readFile(e.lockAt, { encoding: 'utf8' }).then(String, () => null);
+                        if (now !== e.original) {
+                            throw new ToolError(`"${e.lockAt}" changed while the move was being planned, so nothing was moved. Run the move again.`, 409);
+                        }
+                    }
+                };
+                const summary = `Move ${src} to ${dest}`.slice(0, 200);
+                const locking = fs;
+                try {
+                    if (typeof locking.moveWithEdits === 'function') {
+                        await asEntryExists(() => locking.moveWithEdits(src, dest, edits, summary, check));
+                    }
+                    else {
+                        // A filesystem without the one-commit move (none the agent is
+                        // handed for writing): the move, then each edit.
+                        await check();
+                        await asEntryExists(() => fs.moveFile(src, dest));
+                        for (const e of edits)
+                            await fs.writeFile(e.path, e.content);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof MoveLockedError || err instanceof MoveRacedError)
+                        throw new ToolError(err.message, 409);
+                    throw err;
+                }
+            }
             // Moving the last file — or a whole folder — out leaves the folder it
             // came from in place, like a delete.
             await keepFolderOf(fs, ctx, branch, src, kbDirName);
@@ -2872,6 +3276,8 @@ uploads) {
         });
         mount({
             name: 'apply_file_upload',
+            // A mode that is not one of the three answers `bad_mode`, which lists them.
+            refusesItself: ['mode'],
             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. ' +
@@ -2934,6 +3340,169 @@ uploads) {
             handler: async (a, ctx) => applyFileUpload(a, ctx, uploads),
         });
     }
+    // ── downloads (bytes that never pass through the model, the other way) ──
+    // The twin of the upload pair: `read_file` answers content INTO the
+    // conversation, so an agent that needs exact bytes on its own disk had no
+    // way to get them. `request_file_download` judges every file on its own,
+    // captures the ones that pass, and answers a one-time link per file (and a
+    // zip per requested folder) that any HTTP client can fetch.
+    /** The type a file's link answers with: the reader's, as `file_stat` reports it — but never active content. */
+    const downloadContentType = (p, bytes) => {
+        const reader = readers.readerFor(p);
+        const mime = fileTypeOf(reader, p, needsContent(reader) ? bytes : undefined).mime;
+        // SVG and HTML run scripts wherever they are opened — saved to disk and
+        // re-opened under `file://`, too — so they go out as bytes, as the app's
+        // own Download button sends them.
+        return ACTIVE_CONTENT_TYPES.has(mime) ? 'application/octet-stream' : mime;
+    };
+    if (downloads) {
+        mount({
+            name: 'request_file_download',
+            gated: true,
+            description: 'Copy knowledge-base files onto your own disk without their content passing through the conversation — the ' +
+                'way out, as `request_file_upload` is the way in. Give `branch` and `paths` (files or folders). Every file, ' +
+                'each one inside a folder too, is included only if you may read AND download that file. Returns ' +
+                '`{ expiresAt, expiresInSeconds, files: [{ path, bytes, sha256, downloadUrl }], folders: [{ path, bytes, ' +
+                'downloadUrl, files }], refused: [{ path, reason }] }`: a link per file, with its own content type, and per ' +
+                `folder a zip at full repository paths (\`apply_file_upload\` it at \`${kbDirName}/\` to put every file back). ` +
+                'Fetch with any HTTP client (`curl -o <name> "<downloadUrl>"`, or the address without its last segment and an ' +
+                '`x-download-token` header). Each link works ONCE, for 15 minutes, and serves the files as they are now. ' +
+                'Refused: `not found` (missing or named-but-unreadable; folders omit unreadable files), ' +
+                '`download permission required`; no link when nothing is included. At most 500 MB per request.',
+            inputs: {
+                type: 'object',
+                properties: {
+                    branch: BRANCH_INPUT,
+                    paths: {
+                        type: 'array',
+                        minItems: 1,
+                        items: { type: 'string' },
+                        description: `Files and folders to download, under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), with or without a leading slash — a path without that prefix is placed under \`${kbDirName}/\`.`,
+                    },
+                    sessionId: SESSION_ID_INPUT,
+                },
+                required: ['branch', 'paths'],
+                additionalProperties: false,
+            },
+            outputs: {
+                type: 'object',
+                properties: {
+                    expiresAt: {
+                        type: ['string', 'null'],
+                        description: 'ISO-8601 instant after which every link of this answer is gone; null when no link was issued.',
+                    },
+                    expiresInSeconds: int('Seconds until `expiresAt`; 0 when no link was issued.'),
+                    files: {
+                        type: 'array',
+                        description: 'One entry per included file, each named once however many times it was asked for.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                path: str('The workspace path.'),
+                                bytes: int('Size in bytes.'),
+                                sha256: str('SHA-256 of the bytes the link serves, hex.'),
+                                downloadUrl: str('One-time link to the file itself.'),
+                            },
+                            required: ['path', 'bytes', 'sha256', 'downloadUrl'],
+                        },
+                    },
+                    folders: {
+                        type: 'array',
+                        description: 'One entry per requested folder that kept at least one file.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                path: str('The folder, as requested.'),
+                                bytes: int('Uncompressed total of the files in its zip.'),
+                                downloadUrl: str('One-time link to the zip.'),
+                                files: { type: 'array', items: { type: 'string' }, description: 'The workspace paths the zip holds.' },
+                            },
+                            required: ['path', 'bytes', 'downloadUrl', 'files'],
+                        },
+                    },
+                    refused: {
+                        type: 'array',
+                        description: 'Every path left out, with why.',
+                        items: {
+                            type: 'object',
+                            properties: { path: str('The path left out.'), reason: str('Why: `not found`, `download permission required`, or the deployment\'s own words.') },
+                            required: ['path', 'reason'],
+                        },
+                    },
+                },
+                required: ['expiresAt', 'expiresInSeconds', 'files', 'folders', 'refused'],
+            },
+            // A download is a READ: a read-only deployment still serves it. A
+            // read-only CREDENTIAL may not take bytes out, though.
+            write: false,
+            writeScope: true,
+            handler: async (a, ctx) => requestFileDownload(a, ctx, downloads),
+        });
+    }
+    /** `request_file_download`'s handler: judge, capture, and issue the links. */
+    async function requestFileDownload(a, ctx, store) {
+        const branch = a.branch;
+        const raw = a.paths;
+        if (!Array.isArray(raw) || raw.length === 0 || raw.some((p) => typeof p !== 'string' || p.trim() === '')) {
+            throw new ToolError('Name at least one path to download in `paths`: an array of file and folder paths.', 400);
+        }
+        // At the cap, say so before a branch is resolved; the slot below counts again.
+        store.assertCanIssue(ctx.user);
+        // Resolves (clones, if need be) the branch's workspace, as a read does —
+        // so an unknown branch is the call's refusal, not every path's.
+        await ctx.getFilesystem(branch);
+        const workspaceId = workspaceIdForBranch(branch);
+        const refusedSpelling = [];
+        const requested = [];
+        for (const p of raw) {
+            try {
+                // As written: a name may begin or end with a space, and trimming it
+                // would ask for another file. A trailing slash is the one spelling
+                // folded, so `Shared/` and `Shared` are one request, not two zips.
+                requested.push(normalizeWorkspacePath(p, kbDirName).replace(/\/+$/, ''));
+            }
+            catch (err) {
+                if (!hasHttpStatus(err))
+                    throw err;
+                refusedSpelling.push({ path: p, reason: err.message });
+            }
+        }
+        // A slot is taken before anything is built (a caller at the cap is told
+        // so at once) and given back when nothing is issued.
+        return store.withRequestSlot(ctx.user, async (issue) => {
+            const built = await buildDownload(requested, {
+                kbDirName,
+                maxBytes: ZIP_DOWNLOAD_MAX_BYTES,
+                maxFiles: DOWNLOAD_MAX_FILES,
+                candidatesAt: (p) => ctx.workspaceService.downloadCandidatesAt(workspaceId, p),
+                canReadBatch: (paths) => accessControl.canReadBatch(workspaceId, ctx.user.email, paths),
+                canDownloadBatch: (paths) => accessControl.canDownloadBatch(workspaceId, ctx.user.email, paths),
+                // The folder-level gate the app's zip route applies, before the files.
+                canDownloadFolder: (p) => accessControl.canDownload(workspaceId, ctx.user.email, toKbRelative(p, kbDirName) ?? p),
+                notifyRead: (p) => notifyAgentRead(agentAccessGate, ctx, branch, p),
+                readFile: (p) => ctx.workspaceService.readFileBinary(workspaceId, p),
+                contentTypeOf: downloadContentType,
+            });
+            const refused = [...refusedSpelling, ...built.refused];
+            if (built.artifacts.length === 0) {
+                return { expiresAt: null, expiresInSeconds: 0, files: [], folders: [], refused };
+            }
+            const issued = await issue(built.artifacts);
+            const urls = issued.downloadUrls;
+            return {
+                expiresAt: issued.expiresAt,
+                expiresInSeconds: issued.expiresInSeconds,
+                files: built.files.map((f, i) => ({ ...f, downloadUrl: urls[i] })),
+                folders: built.folders.map((f, i) => ({
+                    path: f.path,
+                    bytes: f.bytes,
+                    downloadUrl: urls[built.files.length + i],
+                    files: f.files,
+                })),
+                refused,
+            };
+        });
+    }
     // ── shell (internal-only) ───────────────────────────────────────────────
     mount({
         name: 'execute_command',
@@ -3116,5 +3685,7 @@ uploads) {
             });
         },
     });
+    // The one read `open_page` borrows — see `readForTool` above.
+    return { readForTool };
 }
 //# sourceMappingURL=workspace.tools.js.map