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

package/dist/modules/workspace/agent-access.gate.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Agent access gate — the per-call seam every gated agent tool runs through.
+ *
+ * It decides nothing of its own. It calls the hooks a DEPLOYMENT registered
+ * (`WorkflowHooks`): one before an agent read of a knowledge-base path, one
+ * before an agent write. A hook that throws refuses the operation and the
+ * caller sees that hook's own message and status. With no hook registered —
+ * every core-only deployment — nothing is refused and nothing is recorded, and
+ * a call that carries no `sessionId` is an ordinary call.
+ *
+ * The gate owns exactly two skips, and they are the ones core can decide on
+ * its own identity model: the caller is not an agent (a person in the app, a
+ * browser JWT), or the caller is the recovery/merge bot. Everything else —
+ * which paths matter, whether a session id is required, what the refusal says
+ * — belongs to the hook.
+ *
+ * Lives beside `assertCanRead` in the workspace tools; it does NOT touch
+ * `acquireLock` (that gate is protected-branch-only, and this one applies on
+ * all branches and to reads).
+ */
+import type { JsonSchema } from '../tool-registry/tool.contract.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import type { WorkflowHooks } from '../workflow/workflow-hooks.js';
+/**
+ * What the `sessionId` input says on its own, before any deployment note. The
+ * id is the CONVERSATION's id: the in-process agent supplies its thread id
+ * automatically (via its per-run internal token), and an external agent mints
+ * one with `start_session` and passes it explicitly, because the MCP proxy is
+ * a pure passthrough and never injects args. The same id is the one `ask`
+ * takes, so a run's reads and its questions share one conversation.
+ */
+export declare const SESSION_ID_DESCRIPTION = "This conversation's id, so the server can tell one run's calls apart. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here \u2014 the same id `ask` takes. The in-process agent runtime supplies this automatically (do not set it yourself).";
+/**
+ * The `sessionId` input every gated tool declares. The description a MOUNTED
+ * tool ends up advertising is {@link ToolDescriptionNotes.sessionIdDescription},
+ * which appends whatever note the deployment registered; this constant is the
+ * unadorned default the notes are applied on top of.
+ */
+export declare const SESSION_ID_INPUT: JsonSchema;
+/**
+ * The registration point for the wording a DEPLOYMENT wants agents to read
+ * about the gated tools — the counterpart of the hooks, which carry its rule.
+ * A deployment that refuses some calls can say so here; core registers
+ * nothing, so a core-only deployment advertises the plain descriptions.
+ *
+ * Registration may land AFTER the tools are mounted (an overlay registers from
+ * the tool-surface hook), so mounted tools subscribe with {@link onChange} and
+ * rewrite their own description and `sessionId` input when a note arrives.
+ */
+export declare class ToolDescriptionNotes {
+    private gatedTool;
+    private sessionId;
+    private readonly listeners;
+    /** Append `note` to the description of every gated tool. */
+    registerGatedToolNote(note: string): void;
+    /** Append `note` to the description of the `sessionId` input. */
+    registerSessionIdNote(note: string): void;
+    /** The registered gated-tool note, `''` when none is registered. */
+    gatedToolNote(): string;
+    /** The `sessionId` input's description, with any registered note appended. */
+    sessionIdDescription(): string;
+    /** Re-run `listener` whenever a note is registered (mounted tools re-describe). */
+    onChange(listener: () => void): void;
+    private announce;
+}
+/** The per-deployment configuration the gate needs, built once in the composition root. */
+export interface AgentAccessGate {
+    /** Lowercased email of the recovery/merge bot, which never reaches the hooks. */
+    recoveryBotEmail: string;
+    /**
+     * The workflow lifecycle-hook registry holding the BLOCKING `agentRead` and
+     * `preWrite` hooks. Core registers none; a deployment registers against
+     * `workflowService.hooks` — pass that same instance here.
+     */
+    hooks: WorkflowHooks;
+    /** The notes a deployment adds to what agents read about these tools. */
+    notes: ToolDescriptionNotes;
+}
+/**
+ * Tell the registered read hooks about an agent read of `wsPath`. A hook that
+ * throws refuses the read with its own message and status; with none
+ * registered this is a no-op.
+ */
+export declare function notifyAgentRead(gate: AgentAccessGate, ctx: ToolContext, branch: string, wsPath: string): Promise<void>;
+/**
+ * Ask the registered write hooks whether an agent write may proceed. A hook
+ * that throws refuses it with its own message and status; with none registered
+ * this is a no-op.
+ *
+ * `wsPath` is omitted by the one write-capable tool with no resolvable target,
+ * `execute_command` — the hook then decides at the coarser session level.
+ */
+export declare function assertAgentWriteAllowed(gate: AgentAccessGate, ctx: ToolContext, branch: string, wsPath?: string): Promise<void>;
+//# sourceMappingURL=agent-access.gate.d.ts.map

package/dist/modules/workspace/agent-access.gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-access.gate.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/agent-access.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,oWAC2T,CAAC;AAE/V;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAG9B,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,4DAA4D;IAC5D,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzC,iEAAiE;IACjE,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzC,oEAAoE;IACpE,aAAa,IAAI,MAAM;IAIvB,8EAA8E;IAC9E,oBAAoB,IAAI,MAAM;IAI9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAIpC,OAAO,CAAC,QAAQ;CAGjB;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,KAAK,EAAE,aAAa,CAAC;IACrB,yEAAyE;IACzE,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAwBD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/modules/workspace/agent-access.gate.js

@@ -0,0 +1,123 @@
+/**
+ * Agent access gate — the per-call seam every gated agent tool runs through.
+ *
+ * It decides nothing of its own. It calls the hooks a DEPLOYMENT registered
+ * (`WorkflowHooks`): one before an agent read of a knowledge-base path, one
+ * before an agent write. A hook that throws refuses the operation and the
+ * caller sees that hook's own message and status. With no hook registered —
+ * every core-only deployment — nothing is refused and nothing is recorded, and
+ * a call that carries no `sessionId` is an ordinary call.
+ *
+ * The gate owns exactly two skips, and they are the ones core can decide on
+ * its own identity model: the caller is not an agent (a person in the app, a
+ * browser JWT), or the caller is the recovery/merge bot. Everything else —
+ * which paths matter, whether a session id is required, what the refusal says
+ * — belongs to the hook.
+ *
+ * Lives beside `assertCanRead` in the workspace tools; it does NOT touch
+ * `acquireLock` (that gate is protected-branch-only, and this one applies on
+ * all branches and to reads).
+ */
+/**
+ * What the `sessionId` input says on its own, before any deployment note. The
+ * id is the CONVERSATION's id: the in-process agent supplies its thread id
+ * automatically (via its per-run internal token), and an external agent mints
+ * one with `start_session` and passes it explicitly, because the MCP proxy is
+ * a pure passthrough and never injects args. The same id is the one `ask`
+ * takes, so a run's reads and its questions share one conversation.
+ */
+export const SESSION_ID_DESCRIPTION = "This conversation's id, so the server can tell one run's calls apart. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here — the same id `ask` takes. The in-process agent runtime supplies this automatically (do not set it yourself).";
+/**
+ * The `sessionId` input every gated tool declares. The description a MOUNTED
+ * tool ends up advertising is {@link ToolDescriptionNotes.sessionIdDescription},
+ * which appends whatever note the deployment registered; this constant is the
+ * unadorned default the notes are applied on top of.
+ */
+export const SESSION_ID_INPUT = {
+    type: 'string',
+    description: SESSION_ID_DESCRIPTION,
+};
+/**
+ * The registration point for the wording a DEPLOYMENT wants agents to read
+ * about the gated tools — the counterpart of the hooks, which carry its rule.
+ * A deployment that refuses some calls can say so here; core registers
+ * nothing, so a core-only deployment advertises the plain descriptions.
+ *
+ * Registration may land AFTER the tools are mounted (an overlay registers from
+ * the tool-surface hook), so mounted tools subscribe with {@link onChange} and
+ * rewrite their own description and `sessionId` input when a note arrives.
+ */
+export class ToolDescriptionNotes {
+    gatedTool = '';
+    sessionId = '';
+    listeners = new Set();
+    /** Append `note` to the description of every gated tool. */
+    registerGatedToolNote(note) {
+        this.gatedTool = note;
+        this.announce();
+    }
+    /** Append `note` to the description of the `sessionId` input. */
+    registerSessionIdNote(note) {
+        this.sessionId = note;
+        this.announce();
+    }
+    /** The registered gated-tool note, `''` when none is registered. */
+    gatedToolNote() {
+        return this.gatedTool;
+    }
+    /** The `sessionId` input's description, with any registered note appended. */
+    sessionIdDescription() {
+        return SESSION_ID_DESCRIPTION + this.sessionId;
+    }
+    /** Re-run `listener` whenever a note is registered (mounted tools re-describe). */
+    onChange(listener) {
+        this.listeners.add(listener);
+    }
+    announce() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/** Only agent callers are gated; `session` (browser JWT) and humans are not. */
+function agentSourceOf(ctx) {
+    return ctx.source === 'internal' || ctx.source === 'external' ? ctx.source : null;
+}
+/**
+ * The hook context for this call, or `null` when the call never reaches a hook:
+ * the caller is a person rather than an agent, or is the recovery/merge bot,
+ * which legitimately spans everything.
+ */
+function operationContext(gate, ctx, branch, wsPath) {
+    const source = agentSourceOf(ctx);
+    if (source === null)
+        return null;
+    if (ctx.user.email.toLowerCase() === gate.recoveryBotEmail)
+        return null;
+    return { sessionId: ctx.sessionId, wsPath, branch, user: ctx.user, source };
+}
+/**
+ * Tell the registered read hooks about an agent read of `wsPath`. A hook that
+ * throws refuses the read with its own message and status; with none
+ * registered this is a no-op.
+ */
+export async function notifyAgentRead(gate, ctx, branch, wsPath) {
+    const op = operationContext(gate, ctx, branch, wsPath);
+    if (op === null)
+        return;
+    await gate.hooks.runAgentRead(op);
+}
+/**
+ * Ask the registered write hooks whether an agent write may proceed. A hook
+ * that throws refuses it with its own message and status; with none registered
+ * this is a no-op.
+ *
+ * `wsPath` is omitted by the one write-capable tool with no resolvable target,
+ * `execute_command` — the hook then decides at the coarser session level.
+ */
+export async function assertAgentWriteAllowed(gate, ctx, branch, wsPath) {
+    const op = operationContext(gate, ctx, branch, wsPath);
+    if (op === null)
+        return;
+    await gate.hooks.runPreWrite(op);
+}
+//# sourceMappingURL=agent-access.gate.js.map

package/dist/modules/workspace/agent-access.gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-access.gate.js","sourceRoot":"","sources":["../../../src/modules/workspace/agent-access.gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GACjC,4VAA4V,CAAC;AAE/V;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,sBAAsB;CACpC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,OAAO,oBAAoB;IACvB,SAAS,GAAG,EAAE,CAAC;IACf,SAAS,GAAG,EAAE,CAAC;IACN,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAEnD,4DAA4D;IAC5D,qBAAqB,CAAC,IAAY;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,iEAAiE;IACjE,qBAAqB,CAAC,IAAY;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,oEAAoE;IACpE,aAAa;QACX,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,8EAA8E;IAC9E,oBAAoB;QAClB,OAAO,sBAAsB,GAAG,IAAI,CAAC,SAAS,CAAC;IACjD,CAAC;IAED,mFAAmF;IACnF,QAAQ,CAAC,QAAoB;QAC3B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAEO,QAAQ;QACd,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,EAAE,CAAC;IACpD,CAAC;CACF;AAgBD,gFAAgF;AAChF,SAAS,aAAa,CAAC,GAAgB;IACrC,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAe;IAEf,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAc;IAEd,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO;IACxB,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAqB,EACrB,GAAgB,EAChB,MAAc,EACd,MAAe;IAEf,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO;IACxB,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/modules/workspace/agent-upload.routes.d.ts

@@ -0,0 +1,77 @@
+import express from 'express';
+import { AgentUploadStore } from './agent-upload.store.js';
+/** The route's own prefix, under `/api`. One spelling, shared with the raw-body test below. */
+export declare 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 declare 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 declare function isAgentUploadRawBodyPath(path: string): boolean;
+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 declare function createAgentUploadRoutes(deps: AgentUploadRouteDeps): express.Router;
+/**
+ * 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 declare function dispositionFilename(disposition: string): string | null;
+//# sourceMappingURL=agent-upload.routes.d.ts.map

package/dist/modules/workspace/agent-upload.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-upload.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/agent-upload.routes.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,EAAE,gBAAgB,EAA+B,MAAM,yBAAyB,CAAC;AAIxF,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO9D;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAmElF;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBtE"}

package/dist/modules/workspace/agent-upload.routes.js

@@ -0,0 +1,210 @@
+import express from 'express';
+import { validateFilename } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { 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) {
+    // 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/');
+}
+/**
+ * `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) {
+    const router = express.Router();
+    const { uploads } = deps;
+    const handle = 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) {
+    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) {
+    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) {
+    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;
+}
+//# sourceMappingURL=agent-upload.routes.js.map

package/dist/modules/workspace/agent-upload.routes.js.map

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