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

package/src/modules/workspace/__tests__/workspace.tools.test.ts

@@ -13,7 +13,8 @@ import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-import { CONTENT_RULE, registerWorkspaceTools } from '../workspace.tools.js';
+import { registerWorkspaceTools } from '../workspace.tools.js';
+import { sharedFileRules, sharedFileRulesSection, sharedRulesPointer } from '../../agent-instructions/shared-file-rules.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { UuidSessionSink, type ISessionSink } from '../session-sink.js';
 import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workflow-hooks.js';
@@ -30,7 +31,7 @@ import { assertValidBranchName } from '../../kb-fs/branch-name.js';
 import { normalizeWorkspacePath } from '../../kb-fs/repo-path.js';
 import { GIT_INTERNALS_MESSAGE, PathNotFoundError } from '../../../shared/domain-errors.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
-import { PROPOSAL_ROUTE_NOTE, proposalTitleFor } from '../write-denial.js';
+import { proposalTitleFor } from '../write-denial.js';
 import { NOT_FOUND_NEXT_STEP } from '../not-found.js';
 
 const KB_DIR = 'knowledge-base';
@@ -182,6 +183,25 @@ async function start(
     await check?.();
     return plainWriteFile(path, content, options as never);
   };
+  // `LockingFilesystem.rewriteFile`: read, compute and write with the path
+  // "locked". The other writer runs first — where the real filesystem would be
+  // acquiring the lock — so `rewrite` reads what that writer left.
+  (fs as unknown as Record<string, unknown>).rewriteFile = async (
+    path: string,
+    rewrite: (current: Buffer | null) => string | Promise<string>,
+  ) => {
+    await runRaceHook();
+    // Absent is null; any other read failure is a failure, as in the real one.
+    const current = await fs.readFile(path).then(
+      (c) => (Buffer.isBuffer(c) ? c : Buffer.from(String(c), 'utf8')),
+      (err: unknown) => {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+        throw err;
+      },
+    );
+    return plainWriteFile(path, await rewrite(current));
+  };
   (fs as unknown as Record<string, unknown>).writeFiles = async (
     writes: { path: string; content: string }[],
     _summary: string,
@@ -362,6 +382,98 @@ describe('workspace file primitives', () => {
     expect((await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/a.md`, old_string: 'nope', new_string: 'x' })).status).toBe(400);
   });
 
+  it('edit_file writes new_string exactly as sent, `$` patterns included', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/a.md`, old_string: 'world', new_string: "cost: $& $1 $' $$" });
+    expect(res.status).toBe(200);
+    expect(String(await fs.readFile(`${KB_DIR}/a.md`))).toBe("hello\ncost: $& $1 $' $$\n");
+  });
+
+  /**
+   * An edit is a promise about the text it replaces, so that text has to be
+   * found in the file as it is when the write lands — read with the path's
+   * lock held, not at a preflight anybody may invalidate. `raceHook` is the
+   * other writer, running exactly where the real filesystem acquires the lock.
+   */
+  describe('edit_file looks for old_string in the file the write actually lands on', () => {
+    const EMPTY_OWNER = '# Assignee\n\n# Log';
+    const claim = (base: string, who: string) =>
+      post(`${base}/api/agent/tools/edit_file`, {
+        path: `${KB_DIR}/ticket.md`,
+        old_string: EMPTY_OWNER,
+        new_string: `# Assignee\n${who}\n\n# Log`,
+      });
+
+    it('refuses when another writer replaced that text after the preflight, and keeps their write', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\ncoder1\n\n# Log\n- filed\n'); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(400);
+      expect(((await res.json()) as { error: string }).error).toContain('old_string not found');
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('# Assignee\ncoder1\n\n# Log\n- filed\n');
+    });
+
+    it('applies the edit to what the other writer left when the text is still there', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n- a line added meanwhile\n'); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(200);
+      // Their line is kept: the new content was computed from the file as it was under the lock.
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('# Assignee\ncoder2\n\n# Log\n- filed\n- a line added meanwhile\n');
+    });
+
+    it('refuses when the text became ambiguous after the preflight', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, `${EMPTY_OWNER}\n${EMPTY_OWNER}\n`); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(400);
+      expect(((await res.json()) as { error: string }).error).toContain('appears 2 times');
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe(`${EMPTY_OWNER}\n${EMPTY_OWNER}\n`);
+    });
+
+    it('answers not found when the file was deleted after the preflight, and does not recreate it', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, '# Assignee\n\n# Log\n- filed\n');
+      raceHook = async () => { await fs.deleteFile(`${KB_DIR}/ticket.md`); };
+      const res = await claim(base, 'coder2');
+      expect(res.status).toBe(404);
+      await expect(fs.readFile(`${KB_DIR}/ticket.md`)).rejects.toThrow();
+    });
+
+    // Every question the tool asks of the file is asked of the bytes it is
+    // about to replace. An extensionless file may hold anything, and the app's
+    // own upload can swap it for a binary between the preflight and the lock.
+    // The binary still CONTAINS `old_string` here, so nothing but the
+    // "may these bytes be edited as text" question can refuse it.
+    it('refuses when the file became binary after the preflight, and leaves those bytes alone', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/TICKET`, '# Assignee\n\n# Log\n- filed\n');
+      const binary = Buffer.concat([Buffer.from([0x00, 0xff, 0xfe, 0x00]), Buffer.from(`${EMPTY_OWNER}\n`, 'utf8')]);
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/TICKET`, binary); };
+      const res = await post(`${base}/api/agent/tools/edit_file`, {
+        path: `${KB_DIR}/TICKET`,
+        old_string: EMPTY_OWNER,
+        new_string: '# Assignee\ncoder2\n\n# Log',
+      });
+      expect(res.status).toBe(415);
+      expect(await res.json()).toMatchObject({ kind: 'binary_not_writable' });
+      const after = await fs.readFile(`${KB_DIR}/TICKET`);
+      expect(Buffer.from(after as Buffer).equals(binary)).toBe(true);
+    });
+
+    it('counts replace_all over the file as it is under the lock', async () => {
+      const base = await start();
+      await fs.writeFile(`${KB_DIR}/ticket.md`, 'x x\n');
+      raceHook = async () => { await fs.writeFile(`${KB_DIR}/ticket.md`, 'x x x\n'); };
+      const res = await post(`${base}/api/agent/tools/edit_file`, { path: `${KB_DIR}/ticket.md`, old_string: 'x', new_string: 'y', replace_all: true });
+      expect(await res.json()).toMatchObject({ replaced: 3 });
+      expect(String(await fs.readFile(`${KB_DIR}/ticket.md`))).toBe('y y y\n');
+    });
+  });
+
   it('list_files + file_stat', async () => {
     const base = await start();
     const root = (await (await post(`${base}/api/agent/tools/list_files`, {})).json()) as { entries: { name: string }[] };
@@ -920,19 +1032,26 @@ describe('write modes and per-path outcomes', () => {
     });
   });
 
-  it('both descriptions state the default and all three modes, and `mode` is an input on each', async () => {
+  it('states the three modes on the `mode` input of each write tool, and once in the shared rules', async () => {
     await start();
     const tools = await toolRegistry.listInternal();
+    // The paragraph that said this in BOTH descriptions is one shared rule now.
+    // What stays on the tool is the input the agent fills, which is where the
+    // decision is actually taken.
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'write-mode')!;
+    expect(rule.body).toContain('DEFAULTS TO `create`');
+    expect(rule.body).toContain('On write_file and write_files');
+    expect(sharedFileRulesSection(testKbContext().layout).split(rule.body)).toHaveLength(2);
     for (const name of ['write_file', 'write_files']) {
       const def = tools.find((t) => t.name === name)!;
-      expect(def.description, name).toContain('DEFAULTS TO `create`');
-      for (const mode of ['`create`', '`overwrite`', '`update`']) {
-        expect(def.description, `${name} ${mode}`).toContain(mode);
-      }
+      expect(def.description, name).not.toContain('DEFAULTS TO `create`');
       const body = (def.inputs as { properties: { body: { properties: Record<string, { enum?: string[]; description?: string }> } } }).properties.body;
       expect(body.properties.mode, name).toBeDefined();
       expect(body.properties.mode.enum, name).toEqual(['create', 'overwrite', 'update']);
       expect(body.properties.mode.description, name).toContain('default `create`');
+      for (const mode of ['`create`', '`overwrite`', '`update`']) {
+        expect(body.properties.mode.description, `${name} ${mode}`).toContain(mode);
+      }
     }
   });
 
@@ -1595,28 +1714,36 @@ describe('office documents and PDFs', () => {
     expect(await readContent(base, `${KB_DIR}/deck.pptx`)).toContain('Original');
   });
 
-  it('every file tool states the SAME content rule — refused families, the byte tools and the upload path — so agents learn before the call', async () => {
+  it('every mounted tool ends with the one sentence pointing at the shared rules, and repeats none of them', async () => {
     await start();
     const tools = await toolRegistry.listInternal();
-    const fileTools = ['read_file', 'list_files', 'file_stat', 'grep', 'write_file', 'write_files', 'edit_file', 'delete_file', 'mkdir', 'move_file', 'copy_file', 'unzip'];
-    for (const name of fileTools) {
+    const pointer = sharedRulesPointer(testKbContext().layout);
+    // The shell is in the list too: it carried the agent-guide reminder before,
+    // and that reminder is one of the rules that moved.
+    const mounted = ['read_file', 'list_files', 'file_stat', 'grep', 'write_file', 'write_files', 'edit_file', 'delete_file', 'delete_folder', 'mkdir', 'move_file', 'copy_file', 'unzip', 'execute_command'];
+    for (const name of mounted) {
       const def = tools.find((t) => t.name === name);
       expect(def, name).toBeDefined();
-      // One constant, verbatim — the description is what tools_info returns.
-      expect(def!.description, name).toContain(CONTENT_RULE);
-      expect(def!.description, name).toContain('`binary_not_writable`');
-      expect(def!.description, name).toContain('copy_file, move_file, delete_file and unzip act on bytes of any kind');
-      expect(def!.description, name).toContain('`request_upload_token` + `apply_upload`');
-      expect(def!.description, name).toContain('`contentMode`');
-      // Modern extractable formats…
-      expect(def!.description, name).toContain('.docx/.pptx/.xlsx/.odt/.odp/.ods/.pdf');
-      // …email files (extractions too, so the same refusal applies)…
-      expect(def!.description, name).toContain('.eml/.msg');
-      // …the legacy binary family the refusal also covers…
-      expect(def!.description, name).toContain('.doc/.ppt/.xls');
+      expect(def!.description!.endsWith(pointer), name).toBe(true);
+      // Once, at the end — not once per paragraph that used to be appended.
+      expect(def!.description!.split(pointer), name).toHaveLength(2);
+      // EVERY shared rule, in full, is in the two shared places now (see
+      // agent-instructions/__tests__/shared-file-rules.test.ts) and in no
+      // description. Checked on the whole body rather than on a phrase: the
+      // drift this PR exists to prevent is a paragraph pasted back onto a
+      // tool, and naming only two marker phrases would catch two of eight.
+      for (const rule of sharedFileRules(testKbContext().layout)) {
+        expect(def!.description, `${name} / ${rule.id}`).not.toContain(rule.body);
+      }
+      // The two lead-in labels the paragraphs used to arrive under are gone
+      // with them — a description carrying one is carrying the old text.
+      expect(def!.description, name).not.toContain('Content rule (the same on every file tool)');
+      expect(def!.description, name).not.toContain('Before your first read or change in a workspace');
     }
-    // The shell is not a file tool: it does not carry the rule.
-    expect(tools.find((t) => t.name === 'execute_command')!.description).not.toContain(CONTENT_RULE);
+    // start_session carried none of the shared paragraphs and gains no pointer:
+    // it touches no file. External-only, so it is looked up on that surface.
+    const external = await toolRegistry.listExternal();
+    expect(external.find((t) => t.name === 'start_session')!.description).not.toContain(pointer);
   });
 
   describe('binary capability contract: a text file, a document, an image and a zip', () => {
@@ -1762,14 +1889,15 @@ describe('office documents and PDFs', () => {
     });
   });
 
-  it('the page-writing tools say where images go, so an agent writes the link a page will render', async () => {
+  it('says where the images a page uses go — once, in the shared rules', async () => {
     await start();
     const tools = await toolRegistry.listInternal();
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'images-in-pages')!;
+    expect(rule.body).toContain('`assets/` folder next to the page');
+    expect(rule.body).toContain('![Approval screen](./assets/approval-screen.png)');
+    expect(sharedFileRulesSection(testKbContext().layout)).toContain(rule.body);
     for (const name of ['write_file', 'write_files']) {
-      const def = tools.find((t) => t.name === name);
-      expect(def, name).toBeDefined();
-      expect(def!.description, name).toContain('`assets/` folder next to the page');
-      expect(def!.description, name).toContain('![Approval screen](./assets/approval-screen.png)');
+      expect(tools.find((t) => t.name === name)!.description, name).not.toContain('`assets/` folder next to the page');
     }
   });
 });
@@ -3313,8 +3441,12 @@ describe('preflight for moves and deletes', () => {
       expect(d.description).toMatch(/FILE or FOLDER/);
       expect(d.description).toMatch(/folder moves recursively/);
       expect(d.description).toMatch(/destination must not exist/);
-      expect(d.description).toContain('is a platform file and stays in its folder.');
-      expect(d.description).toContain('`dryRun: true`');
+      // What refuses a move, and the dry-run/confirm protocol it shares with the
+      // deletes, are shared rules — stated once, in the two shared places.
+      const rules = sharedFileRulesSection(testKbContext().layout);
+      expect(rules).toContain('is a platform file and stays in its folder.');
+      expect(rules).toContain('`dryRun: true`');
+      expect(rules).toContain('`confirm: true`');
       expect(d.description).toContain('`confirm: true`');
       expect(Object.keys(d.inputs.properties.body.properties)).toEqual(expect.arrayContaining(['dryRun', 'confirm']));
       // What the description promises a dry run returns is what it returns.
@@ -3324,7 +3456,10 @@ describe('preflight for moves and deletes', () => {
         expect(dry.body, key).toHaveProperty(key);
       }
       const unconfirmed = await call(base, 'move_file', { src: KB('Sales/deal.md'), dest: KB('HR/deal.md') });
-      expect(d.description).toContain('confirmationRequired: true');
+      // What an unconfirmed call answers is the shared protocol's promise; the
+      // field is still declared in this tool's own `outputs`.
+      expect(rules).toContain('confirmationRequired: true');
+      expect(declaredOutputs(d)).toContain('confirmationRequired');
       expect(unconfirmed.body.confirmationRequired).toBe(true);
       for (const body of [dry.body, unconfirmed.body]) {
         expect(declaredOutputs(d)).toEqual(expect.arrayContaining(Object.keys(body)));
@@ -3334,9 +3469,12 @@ describe('preflight for moves and deletes', () => {
     it('delete_folder states the confirm rule and refusals, and declares every field it returns', async () => {
       const base = await seeded();
       const d = await def('delete_folder');
-      expect(d.description).toContain('`dryRun: true`');
-      expect(d.description).toContain('A non-empty folder is deleted only with `confirm: true`');
-      expect(d.description).toContain('platform folder');
+      expect(d.description).toContain('a non-empty folder wants `confirm: true`');
+      // The protocol itself, and what a platform folder does to it, are shared.
+      const rules = sharedFileRulesSection(testKbContext().layout);
+      expect(rules).toContain('`dryRun: true`');
+      expect(rules).toContain('A non-empty folder is deleted, and a move that changes your access runs, only with `confirm: true`');
+      expect(rules).toContain('platform folder');
       const dry = await call(base, 'delete_folder', { path: KB('Sales/archive'), dryRun: true });
       const unconfirmed = await call(base, 'delete_folder', { path: KB('Sales/archive') });
       const confirmed = await call(base, 'delete_folder', { path: KB('Sales/archive'), confirm: true });
@@ -3354,8 +3492,12 @@ describe('preflight for moves and deletes', () => {
         expect(stat.description, key).toContain(`\`${key}`);
         expect(body, key).toHaveProperty(key);
       }
+      expect(stat.description).toContain('shared rules on what these tools never move or delete');
+      // The proposal route applies to every tool a permission can refuse, so it
+      // is stated once in the shared rules rather than on each of them.
+      expect(sharedFileRulesSection(testKbContext().layout)).toContain('`write-denied`');
       for (const name of ['move_file', 'delete_file', 'delete_folder']) {
-        expect((await def(name)).description, name).toContain('`write-denied`');
+        expect((await def(name)).description, name).toContain(sharedRulesPointer(testKbContext().layout));
       }
     });
   });
@@ -3414,7 +3556,7 @@ describe('a write refused for permissions says whether and how to propose it', (
       throw err;
     };
     const target = fs as unknown as Record<string, unknown>;
-    for (const m of ['writeFile', 'deleteFile', 'moveFile', 'mkdir']) target[m] = refuse;
+    for (const m of ['writeFile', 'rewriteFile', 'deleteFile', 'moveFile', 'mkdir']) target[m] = refuse;
     target.copyFile = async (_src: string, dest: string) => refuse(dest);
     // `delete_folder` lands through the same batch with NO writes and the
     // folder's files as `deletes` — in production the refusal comes from the
@@ -3602,14 +3744,18 @@ describe('a write refused for permissions says whether and how to propose it', (
     expect(res.json).toEqual({ error: 'old_string not found in the file.' });
   });
 
-  it('each write tool mentions the proposal route in its description; read tools do not', async () => {
+  it('states the proposal route in the shared rules, not in each write tool description', async () => {
     await start();
     const tools = await toolRegistry.listInternal();
-    for (const name of ['write_file', 'edit_file', 'write_files', 'move_file', 'delete_file', 'delete_folder', 'copy_file', 'mkdir']) {
-      expect(tools.find((t) => t.name === name)?.description, name).toContain(PROPOSAL_ROUTE_NOTE.trim());
-    }
-    for (const name of ['read_file', 'grep', 'list_files']) {
-      expect(tools.find((t) => t.name === name)?.description, name).not.toContain(PROPOSAL_ROUTE_NOTE.trim());
+    // It applies to every tool a permission can refuse, so it is a shared rule:
+    // stated in the handshake instructions and in the managed guide, and in no
+    // description. The refusal ITSELF still spells the steps out — that is what
+    // the tests above this one assert.
+    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'refused-for-permissions')!;
+    expect(sharedFileRulesSection(testKbContext().layout)).toContain(rule.body);
+    for (const def of tools) {
+      expect(def.description ?? '', def.name).not.toContain('If this is refused for permissions');
+      expect(def.description ?? '', def.name).not.toContain(rule.body);
     }
   });
 });
@@ -4129,18 +4275,22 @@ describe('tool descriptions and the deployment note', () => {
     expect(all.get('read_file')!.description).not.toContain('Stay within one');
   });
 
-  it('a registered note lands at the END of every gated tool\'s description and on the sessionId input', async () => {
+  it("a registered note lands after every gated tool's own text, ahead of the shared-rules pointer, and on the sessionId input", async () => {
     await start();
     notes.registerGatedToolNote(' One folder per conversation.');
     notes.registerSessionIdNote(' It also pins that folder.');
     const all = await defs();
+    // The POINTER is last, always: that is the one sentence an agent needs to
+    // find the shared rules, and a description cut short must not lose it. The
+    // deployment's note sits directly before it, after the tool's own text.
+    const pointer = sharedRulesPointer(testKbContext().layout);
     for (const name of ['read_file', 'list_files', 'file_stat', 'grep', 'write_file', 'write_files', 'edit_file', 'delete_file', 'delete_folder', 'mkdir', 'move_file', 'copy_file', 'unzip']) {
-      expect(all.get(name)!.description.endsWith(' One folder per conversation.'), name).toBe(true);
+      expect(all.get(name)!.description.endsWith(` One folder per conversation.${pointer}`), name).toBe(true);
       expect(sessionIdDescriptionOf(all.get(name)!), name).toBe(`${SESSION_ID_DESCRIPTION} It also pins that folder.`);
     }
     // `execute_command` is internal-only, so it is checked on that surface.
     const internal = new Map((await toolRegistry.listInternal()).map((t) => [t.name, t]));
-    expect(internal.get('execute_command')!.description.endsWith(' One folder per conversation.')).toBe(true);
+    expect(internal.get('execute_command')!.description.endsWith(` One folder per conversation.${pointer}`)).toBe(true);
   });
 
   it('a tool that is not gated carries no note', async () => {

package/src/modules/workspace/agent-upload.routes.ts

@@ -0,0 +1,214 @@
+import express from 'express';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { AgentUploadStore, UploadTokenError, overLimit } from './agent-upload.store.js';
+
+const log = logger('agent-uploads');
+
+/** The route's own prefix, under `/api`. One spelling, shared with the raw-body test below. */
+export const AGENT_UPLOAD_ROUTE = '/agent/uploads/:token';
+
+/**
+ * The same endpoint with the token in the `x-upload-token` HEADER instead of
+ * the path — the address `uploadUrl` is, without its last segment.
+ *
+ * Two spellings because a token in a URL is a credential in a place that keeps
+ * copies: an access log, a proxy log, a shell history, a `ps` listing of the
+ * `curl` that sent it. The path form is what `request_file_upload` answers,
+ * because one address an agent can paste into any client is the thing that
+ * makes this route usable at all; the header form is for a caller that would
+ * rather its credential not be written down on the way. Both reach the same
+ * handler and are judged identically — same token, same single use.
+ */
+export const AGENT_UPLOAD_HEADER_ROUTE = '/agent/uploads';
+
+/**
+ * Whether `path` is the agent upload route, and so must reach its handler with
+ * the body still a STREAM.
+ *
+ * The app installs a global `express.json()`. It only claims a JSON
+ * content-type, but `curl --data-binary @file.zip -H 'content-type:
+ * application/json'` is a request an agent can and will make — and once the
+ * parser has drained the stream there are no bytes left to store, so the
+ * upload would answer "0 bytes received" for a file that was sent in full.
+ * Exempting the path is the same move `/api/sync` makes for its HMAC body, and
+ * for the same reason: whoever needs the exact bytes has to see them first.
+ *
+ * Case-insensitive, because Express routing is: `/api/Agent/uploads/x` reaches
+ * this router, and a check that said no would let the parser eat that body.
+ */
+export function isAgentUploadRawBodyPath(path: string): boolean {
+  // Trailing slashes trimmed first, so the header form's bare address matches
+  // in every spelling Express routes to it (`/api/agent/uploads` and
+  // `/api/agent/uploads/` are one route): missing one of them would hand that
+  // request to the JSON parser, and the bytes it drains are gone.
+  const lower = path.toLowerCase().replace(/\/+$/, '');
+  return lower === '/api/agent/uploads' || lower.startsWith('/api/agent/uploads/');
+}
+
+export interface AgentUploadRouteDeps {
+  uploads: AgentUploadStore;
+}
+
+/**
+ * `POST /api/agent/uploads/:token` — the one endpoint on this server
+ * authenticated by a single-use token and nothing else.
+ *
+ * It exists because MCP tool arguments are JSON, so every byte an agent sends
+ * through a tool passes through the model first. A 37 KB page gets truncated
+ * mid-response; a file of regex backslashes fails to parse as a JSON string; a
+ * PNG cannot be sent at all. Here the agent asks for a token, sends the file
+ * with any HTTP client it has, and then names the token in
+ * `apply_file_upload`. The bytes never enter a prompt.
+ *
+ * What the route itself may do is deliberately almost nothing: it stores bytes
+ * against a token, in a directory beside the workspaces root, and answers what
+ * it received. It resolves no workspace, writes nothing into one, and commits
+ * nothing — every access, platform-file and branch rule is applied later, by
+ * the apply tool, against the branch the caller then names. A token that is
+ * unknown, spent, expired or someone else's gets one 404 that says which of
+ * those it was: none of them.
+ */
+export function createAgentUploadRoutes(deps: AgentUploadRouteDeps): express.Router {
+  const router = express.Router();
+  const { uploads } = deps;
+
+  const handle: express.RequestHandler = async (req, res) => {
+    const token = tokenOf(req);
+    try {
+      // THE TOKEN FIRST, before anything about the request is read, parsed,
+      // judged or quoted back. This route is authenticated by the token and
+      // nothing else, which cuts two ways. Without the check up here, anyone
+      // could make the process buffer the deployment's whole upload limit per
+      // request against tokens they invented, as many at a time as they liked;
+      // and a caller holding no token could learn which of its OTHER guesses
+      // were well formed — "that is not a usable file name" is an answer only
+      // somebody entitled to send a file should get. One refusal, nothing else.
+      // `receive` below asks again, under the same record, because that is
+      // where the token is actually spent.
+      uploads.assertOpen(token);
+      const filename = fileNameOf(req);
+      if (filename === null) {
+        res.status(400).json({
+          error:
+            'Name the file you are sending: add `?filename=<name>` to the upload URL (or send it as the ' +
+            '`x-upload-filename` header). A single file lands under that name, and a name ending in `.zip` is ' +
+            'read as an archive.',
+        });
+        return;
+      }
+      const invalid = validateFilename(filename);
+      if (invalid !== null || filename.includes('/')) {
+        res.status(400).json({
+          error: `"${filename}" is not a usable file name: ${invalid ?? 'a name cannot contain "/"'}. Send one plain file name.`,
+        });
+        return;
+      }
+      // Then the declared length, so a caller sending something far too large
+      // is told the limit before it spends the bandwidth. The real total is
+      // counted by the store as the bytes arrive — `content-length` is the
+      // sender's claim, not a fact.
+      const declared = Number.parseInt(req.headers['content-length'] ?? '', 10);
+      if (Number.isFinite(declared) && declared > uploads.maxBytes) {
+        res.status(413).json({ error: overLimit(declared, uploads.maxBytes) });
+        return;
+      }
+      // The request itself, as a stream: the store writes the bytes to disk as
+      // they arrive and never holds the body. It refuses an empty body, one
+      // past the limit and an unreadable archive with its own status.
+      res.json(await uploads.receive(token, filename, req));
+    } catch (err) {
+      if (err instanceof UploadTokenError) {
+        res.status(err.status).json({ error: err.message });
+        return;
+      }
+      // The detail stays in the log. An unexpected failure here is a
+      // filesystem error, and its message quotes the absolute path of the
+      // store's root — a place the caller is told nothing else about.
+      log.error('upload failed:', { err });
+      res.status(500).json({ error: 'Upload failed' });
+    }
+  };
+
+  // Both spellings of the one endpoint: the token in the path, or in the
+  // `x-upload-token` header on the bare address.
+  router.post(AGENT_UPLOAD_ROUTE, handle);
+  router.post(AGENT_UPLOAD_HEADER_ROUTE, handle);
+
+  return router;
+}
+
+/**
+ * The token the sender presented: the `:token` path segment, or the
+ * `x-upload-token` header when the bytes went to the bare address.
+ *
+ * The path wins when both are present — it is the address the sender actually
+ * POSTed to, and a header left over from an earlier upload must not quietly
+ * redirect these bytes onto a different token.
+ *
+ * No token at all answers the empty string rather than its own refusal, so it
+ * goes through `assertOpen` like any other unusable token and gets the same
+ * single 404. A caller holding nothing is told nothing it did not already
+ * know — not even whether this endpoint wanted a header.
+ */
+function tokenOf(req: express.Request): string {
+  const inPath = req.params.token;
+  if (typeof inPath === 'string' && inPath.trim() !== '') return inPath.trim();
+  const header = req.headers['x-upload-token'];
+  if (typeof header === 'string' && header.trim() !== '') return header.trim();
+  return '';
+}
+
+/**
+ * The name the sender gave the file: the `filename` query parameter, the
+ * `x-upload-filename` header, or a `content-disposition`'s own `filename=`.
+ * Three spellings because three kinds of client are expected to use this —
+ * `curl` with a query string, a scripted `fetch` with a header, and a client
+ * that sends the disposition it would send to any upload endpoint.
+ */
+function fileNameOf(req: express.Request): string | null {
+  const query = req.query.filename;
+  if (typeof query === 'string' && query.trim() !== '') return query.trim();
+  const header = req.headers['x-upload-filename'];
+  if (typeof header === 'string' && header.trim() !== '') return header.trim();
+  const disposition = req.headers['content-disposition'];
+  if (typeof disposition === 'string') return dispositionFilename(disposition);
+  return null;
+}
+
+/**
+ * The `filename` a `content-disposition` names, or null when it names none.
+ *
+ * A QUOTED value is read to its closing quote, not to the first semicolon: a
+ * semicolon separates the header's parameters only OUTSIDE the quotes, and
+ * `filename="report;final.md"` is one perfectly ordinary name that a
+ * semicolon-first reading landed as `report`. An unquoted value ends at the
+ * next parameter, as it must.
+ *
+ * Percent-decoded only in the extended `filename*=UTF-8''…` form, which is the
+ * only one where the encoding is part of the grammar. A plain `filename=` value
+ * is the name itself, so `50%20off.md` stays `50%20off.md` rather than losing
+ * its `%20` to a decode nobody asked for.
+ *
+ * The parameter name is matched at a boundary — the start of the header or a
+ * `;` — because `filename` is a suffix of other perfectly legal parameter
+ * names: without it, `inline; xfilename=wrong.md` read `wrong.md` as the name
+ * the sender gave, from a parameter that says nothing of the kind.
+ */
+export function dispositionFilename(disposition: string): string | null {
+  const match = /(?:^|;)\s*filename(\*?)\s*=\s*(?:"([^"]*)"|([^;]*))/i.exec(disposition);
+  if (!match) return null;
+  const extended = match[1] === '*';
+  const raw = (match[2] ?? match[3] ?? '').trim();
+  if (!extended) return raw === '' ? null : raw;
+  // `UTF-8''name`, or any other charset and language the sender declares.
+  const encoded = raw.replace(/^[^']*'[^']*'/, '');
+  try {
+    const decoded = decodeURIComponent(encoded).trim();
+    if (decoded !== '') return decoded;
+  } catch {
+    const kept = encoded.trim();
+    if (kept !== '') return kept;
+  }
+  return null;
+}