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

package/dist/modules/tool-helpers/route-tool-schemas.js

@@ -0,0 +1,113 @@
+import { logger } from '../../shared/logging.js';
+const log = logger('tools');
+/**
+ * What every route-hosted tool declared, by the last segment of its route and
+ * then by the whole route. Process-wide, because the declarations are made by
+ * CODE — a module's or a deployment's `toolDef` — which is the same for every
+ * tenant a process serves: two tenants mount the same tools with the same
+ * arguments. A route re-declared with DIFFERENT arguments would break that, so
+ * it is logged (once per route) rather than passing silently.
+ */
+const byLastSegment = new Map();
+/** Tool name → its declaration. */
+const byName = new Map();
+/** Routes already reported as re-declared with other arguments. */
+const conflicting = new Set();
+/** A route path as declarations and requests are compared: no query, no trailing slash. */
+function normalizePath(path) {
+    const withoutQuery = path.split('?')[0] ?? '';
+    return withoutQuery.length > 1 ? withoutQuery.replace(/\/+$/, '') : withoutQuery;
+}
+/** Does this flat input schema require any argument at all? */
+function requiresAnything(inputs) {
+    const required = inputs.required;
+    return Array.isArray(required) && required.length > 0;
+}
+/**
+ * The flat inputs inside the `body` envelope every module-hosted tool advertises
+ * — the only standard-http way to ride multiple fields in a JSON body.
+ *
+ * The envelope is required only when something inside it is. A tool whose flat
+ * inputs are all optional is legitimately called as `Bevel.<name>({})` — agents
+ * have always called `list_branches` and `start_session` that way, and the
+ * endpoint reads `req.body` as `{}` either way — so declaring `body` required
+ * would make the schema disagree with the tool, and a check must never refuse a
+ * call the tool accepts.
+ */
+export function bodyEnvelope(inputs) {
+    return {
+        type: 'object',
+        properties: { body: inputs },
+        ...(requiresAnything(inputs) ? { required: ['body'] } : {}),
+        additionalProperties: false,
+    };
+}
+/**
+ * Record what the route-hosted tool `name` takes, and answer with the wire
+ * schema its def must advertise.
+ *
+ * `toolDef` calls this for every tool it builds, so declaring a tool IS
+ * declaring its arguments to the check. A module that builds its def lazily
+ * (the skill tools rebuild theirs per catalog listing, to name the skills that
+ * exist now) calls it once at registration as well, so a direct REST call that
+ * lands before the first catalog listing is checked too.
+ *
+ * Idempotent in effect: a tool whose def is rebuilt re-declares the same
+ * arguments, and the last declaration for a name is the one in force.
+ */
+export function declareRouteTool(name, inputs, refusesItself = [], path = `/api/agent/tools/${name}`) {
+    const wire = bodyEnvelope(inputs);
+    if (!name)
+        return wire;
+    const route = normalizePath(path);
+    const entry = { name, path: route, flat: inputs, wire, refusesItself: new Set(refusesItself) };
+    const segment = routeToolName(route);
+    const same = (byLastSegment.get(segment) ?? []).filter((e) => e.path !== route);
+    const previous = (byLastSegment.get(segment) ?? []).find((e) => e.path === route);
+    if (previous && !conflicting.has(route) && JSON.stringify(previous.flat) !== JSON.stringify(inputs)) {
+        conflicting.add(route);
+        log.warn(`the route "${route}" was declared again with other arguments; calls are checked against the latest.`);
+    }
+    byLastSegment.set(segment, [...same, entry]);
+    byName.set(name, entry);
+    return wire;
+}
+/** What the tool named `name` takes, or `undefined` when nothing declared it. */
+export function routeToolSchemas(name) {
+    return byName.get(name);
+}
+/**
+ * What the tool hosted at the route a request arrived on takes, or
+ * `undefined` when no tool is declared there. `requestPath` is the request's
+ * WHOLE path (`req.originalUrl`): it ends with the declared route whatever
+ * the app is mounted under — a tenant's loopback prefix included.
+ */
+export function routeToolSchemasForRequest(requestPath) {
+    const path = normalizePath(requestPath);
+    const candidates = byLastSegment.get(routeToolName(path)) ?? [];
+    // The route that fits the request BEST wins, not the first one declared: an
+    // exact match, then the longest declared route the path ends with, so
+    // `/api/foo` is never checked against a `/foo` declared before it. A path
+    // shorter than every declaration (a test mounting a route bare) comes last.
+    const exact = candidates.find((e) => path === e.path);
+    if (exact)
+        return exact;
+    const longest = (list) => [...list].sort((a, b) => b.path.length - a.path.length)[0];
+    return (longest(candidates.filter((e) => path.endsWith(e.path))) ??
+        longest(candidates.filter((e) => e.path.endsWith(path))));
+}
+/**
+ * The tool a request to `/api/agent/tools/<name>` is for: the last segment of
+ * the path, query and trailing slash left out.
+ *
+ * Read off the path rather than taken as a parameter, because the path is the
+ * only thing every mounting style agrees on — the modules mount their routes on
+ * a router at `/api`, the tests mount theirs wherever they like, and a
+ * deployment mounts its own.
+ */
+export function routeToolName(path) {
+    const withoutQuery = path.split('?')[0] ?? '';
+    const segments = withoutQuery.split('/').filter((s) => s.length > 0);
+    return segments[segments.length - 1] ?? '';
+}
+//# sourceMappingURL=route-tool-schemas.js.map

package/dist/modules/tool-helpers/route-tool-schemas.js.map

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

package/dist/modules/tool-helpers/tool-def.d.ts

@@ -7,6 +7,52 @@ import type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
  * comes from this argument.
  */
 export declare const BRANCH_INPUT: JsonSchema;
+/**
+ * The optional `branch` of a tool that declares `defaults-to-default-branch`:
+ * the same input, saying what happens without it.
+ */
+export declare const DEFAULTED_BRANCH_INPUT: JsonSchema;
+/**
+ * How a tool treats its `branch` input — the declaration the tool handler
+ * resolves the branch from, once, before the tool runs:
+ *
+ *  - `required`: the call must name a branch. A call without one, or with an
+ *    empty or non-string one, is refused with the `branch-required` refusal
+ *    and the tool does not run. The default for a tool whose inputs require
+ *    `branch`.
+ *  - `defaults-to-default-branch`: a call without a branch runs on the
+ *    deployment's default branch, and an object answer without a `branch`
+ *    field gets one naming it. An empty or non-string branch is still refused:
+ *    only an ABSENT one is defaulted. Read-only tools only — a writing tool
+ *    declaring it fails at startup, since its write would land on the default
+ *    branch without the caller having named it.
+ *
+ * A tool that declares neither, and whose inputs have no `branch`, takes no
+ * branch.
+ *
+ * Under both declarations a branch that is given must exist: one that does not
+ * is answered 404 naming it, before the tool runs. The tool reads the resolved
+ * name from `ctx.branch` — or from `args.branch`, which the handler overwrites
+ * with it — and never sees a missing, empty or non-string one.
+ */
+export type BranchDeclaration = 'required' | 'defaults-to-default-branch';
+/**
+ * What the tool handler does with a call's `branch`: a {@link BranchDeclaration},
+ * `none` for a tool that takes no branch, or `own` for a tool with an OPTIONAL
+ * `branch` and no declaration (the platform's skill tools, `list_tool_setup`)
+ * — such a tool keeps its own handling of an absent branch, and gets only the
+ * 404 for a named branch that does not exist.
+ */
+export type BranchHandling = BranchDeclaration | 'none' | 'own';
+/** How the tool hosted at `path` treats its branch; `undefined` for a route no `toolDef` described. */
+export declare function branchHandlingFor(path: string): BranchHandling | undefined;
+/**
+ * The input schema with `branch` as `declaration` says: required, or optional
+ * with the sentence about the default. A tool that declares its own `branch`
+ * property with its own meaning (a fork base, a switch target) keeps that
+ * property under `required`.
+ */
+export declare function withBranchDeclaration(inputs: JsonSchema, declaration: BranchDeclaration): JsonSchema;
 /** Add a required `branch` property to an object input schema (KB tools). */
 export declare function withBranchInput(inputs: JsonSchema): JsonSchema;
 export interface ToolDefSpec {
@@ -19,6 +65,26 @@ export interface ToolDefSpec {
     tags?: string[];
     /** The route the owning module hosts, e.g. `/agent/tools/list_branches`. */
     path: string;
+    /**
+     * Arguments this tool's own handler refuses by name, with a message of its
+     * own. The generic argument check its route runs then says nothing about
+     * them, so that message is what the caller reads — which is the point of
+     * having written it. A missing `branch` needs no entry here: the route
+     * check leaves a call that names no branch to `branch-required`.
+     */
+    refusesItself?: string[];
+    /**
+     * How the tool treats `branch` — see {@link BranchDeclaration}. Given, the
+     * `branch` input is added to `inputs` to match. Omitted, a tool whose
+     * `inputs` require `branch` is `required`, and one without `branch` takes
+     * no branch.
+     */
+    branch?: BranchDeclaration;
+    /**
+     * The tool writes. A `write` tag says the same. A writing tool cannot
+     * declare `defaults-to-default-branch`.
+     */
+    write?: boolean;
 }
 /**
  * Build a self-describing UTCP `Tool` def for a module-hosted endpoint. The flat
@@ -28,6 +94,11 @@ export interface ToolDefSpec {
  * as the flat args. The URL + bearer are `${API_URL}` / `${CONNECTION_KEY}`
  * placeholders the consumer resolves (public URL + key for external; loopback +
  * internal token for our agent), so one def serves both surfaces.
+ *
+ * Also records the tool's branch handling for its route, which is what the
+ * tool handler mounted on that route resolves the branch from. Throws — at
+ * startup, where defs are built — for a writing tool that declares
+ * `defaults-to-default-branch`.
  */
 export declare function toolDef(spec: ToolDefSpec): UtcpTool;
 //# sourceMappingURL=tool-def.d.ts.map

package/dist/modules/tool-helpers/tool-def.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-def.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAK9E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAI1B,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAO9D;AAED,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAqBnD"}
+{"version":3,"file":"tool-def.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAM9E;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAI1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,UAMpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,4BAA4B,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,MAAM,GAAG,KAAK,CAAC;AAWhE,uGAAuG;AACvG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE1E;AAWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,GAAG,UAAU,CAapG;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAO9D;AAED,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CA8BnD"}

package/dist/modules/tool-helpers/tool-def.js

@@ -1,6 +1,7 @@
 import '@utcp/http';
 import { HttpCallTemplateSerializer } from '@utcp/http';
 import { ToolSerializer } from '@utcp/sdk';
+import { declareRouteTool } from './route-tool-schemas.js';
 const httpTemplate = new HttpCallTemplateSerializer();
 const toolSerializer = new ToolSerializer();
 /**
@@ -14,6 +15,57 @@ export const BRANCH_INPUT = {
     minLength: 1,
     description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
 };
+/**
+ * The optional `branch` of a tool that declares `defaults-to-default-branch`:
+ * the same input, saying what happens without it.
+ */
+export const DEFAULTED_BRANCH_INPUT = {
+    type: 'string',
+    minLength: 1,
+    description: "Optional: the branch (draft) to read. Without it the call runs on the deployment's default branch, " +
+        "and the answer's `branch` field names that branch.",
+};
+/**
+ * Every route path a `toolDef` was built for, with how its branch is handled.
+ * Kept here rather than on the registry so the tool handler finds a tool's
+ * declaration from its route alone: a deployment's tool is covered by building
+ * its def with `toolDef` and mounting its route with `toolHandler`, as it
+ * already does, with nothing in between to keep in step.
+ */
+const branchHandlingByPath = new Map();
+/** How the tool hosted at `path` treats its branch; `undefined` for a route no `toolDef` described. */
+export function branchHandlingFor(path) {
+    return branchHandlingByPath.get(path);
+}
+/** A tool's branch handling read off inputs that carry no declaration. */
+function inferBranchHandling(inputs) {
+    const o = inputs;
+    if ((o.required ?? []).includes('branch'))
+        return 'required';
+    return o.properties && 'branch' in o.properties ? 'own' : 'none';
+}
+/**
+ * The input schema with `branch` as `declaration` says: required, or optional
+ * with the sentence about the default. A tool that declares its own `branch`
+ * property with its own meaning (a fork base, a switch target) keeps that
+ * property under `required`.
+ */
+export function withBranchDeclaration(inputs, declaration) {
+    const o = inputs;
+    const properties = { ...(o.properties ?? {}) };
+    const others = (o.required ?? []).filter((r) => r !== 'branch');
+    if (declaration === 'required') {
+        properties.branch = properties.branch ?? BRANCH_INPUT;
+        return { ...inputs, properties, required: [...others, 'branch'] };
+    }
+    properties.branch = DEFAULTED_BRANCH_INPUT;
+    const out = { ...inputs, properties };
+    if (others.length > 0)
+        out.required = others;
+    else
+        delete out.required;
+    return out;
+}
 /** Add a required `branch` property to an object input schema (KB tools). */
 export function withBranchInput(inputs) {
     const o = inputs;
@@ -31,17 +83,29 @@ export function withBranchInput(inputs) {
  * as the flat args. The URL + bearer are `${API_URL}` / `${CONNECTION_KEY}`
  * placeholders the consumer resolves (public URL + key for external; loopback +
  * internal token for our agent), so one def serves both surfaces.
+ *
+ * Also records the tool's branch handling for its route, which is what the
+ * tool handler mounted on that route resolves the branch from. Throws — at
+ * startup, where defs are built — for a writing tool that declares
+ * `defaults-to-default-branch`.
  */
 export function toolDef(spec) {
+    if (spec.branch === 'defaults-to-default-branch' && (spec.write || (spec.tags ?? []).includes('write'))) {
+        throw new Error(`Tool "${spec.name}" writes, so it cannot declare branch: 'defaults-to-default-branch' — a write must ` +
+            "name its branch. Declare branch: 'required' instead.");
+    }
+    const inputs = spec.branch ? withBranchDeclaration(spec.inputs, spec.branch) : spec.inputs;
+    branchHandlingByPath.set(spec.path, spec.branch ?? inferBranchHandling(inputs));
+    // Declaring the tool IS declaring its arguments to the check that its route
+    // runs, which is why the envelope comes back from the declaration rather than
+    // being built here: a tool declared with this helper — the platform's own and
+    // a deployment's alike — refuses a call whose arguments do not match it on
+    // every way in, the REST route included, with no code of its own.
+    const wire = declareRouteTool(spec.name, inputs, spec.refusesItself, spec.path);
     return toolSerializer.validateDict({
         name: spec.name,
         description: spec.description,
-        inputs: {
-            type: 'object',
-            properties: { body: spec.inputs },
-            required: ['body'],
-            additionalProperties: false,
-        },
+        inputs: wire,
         outputs: spec.outputs ?? { type: 'object', properties: {} },
         tags: spec.tags ?? [],
         tool_call_template: httpTemplate.validateDict({

package/dist/modules/tool-helpers/tool-def.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-def.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,MAAM,YAAY,GAAG,IAAI,0BAA0B,EAAE,CAAC;AACtD,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAe;IACtC,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,qGAAqG;CACnH,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,MAAM,CAAC,GAAG,MAA0E,CAAC;IACrF,OAAO;QACL,GAAG,MAAM;QACT,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE;QAC7D,QAAQ,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;KAC5C,CAAC;AAClB,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,IAAiB;IACvC,OAAO,cAAc,CAAC,YAAY,CAAC;QACjC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;YACjC,QAAQ,EAAE,CAAC,MAAM,CAAC;YAClB,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC3D,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,kBAAkB,EAAE,YAAY,CAAC,YAAY,CAAC;YAC5C,kBAAkB,EAAE,MAAM;YAC1B,WAAW,EAAE,MAAM;YACnB,GAAG,EAAE,cAAc,IAAI,CAAC,IAAI,EAAE;YAC9B,YAAY,EAAE,kBAAkB;YAChC,OAAO,EAAE,EAAE,aAAa,EAAE,0BAA0B,EAAE;YACtD,UAAU,EAAE,MAAM;SACnB,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"tool-def.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-def.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-helpers/tool-handler.d.ts

@@ -1,20 +1,60 @@
 import type { Request, Response } from 'express';
 import { type ToolHandler } from './tool.contract.js';
+import { type BranchHandling } from './tool-def.js';
 import type { ResolveToolContext } from './tool-context.js';
 import { type IWriteAccess } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js';
 export interface ToolHandlerOptions {
     /** Mutating tool — refuse read-scoped callers up front (defense in depth). */
     write?: boolean;
+    /**
+     * Refuse read-scoped callers up front WITHOUT making the tool a write: the
+     * read-only-deployment gate below is not applied. For a tool a read-only
+     * credential may not use that is nonetheless a read — `request_file_download`
+     * takes bytes out, so a read-only deployment must still serve it.
+     */
+    writeScope?: boolean;
+    /**
+     * How this route treats `branch`, when it must differ from what its
+     * `toolDef` recorded. Only `execute_command` sets it (`own`): it falls back
+     * to an internal caller's focused branch rather than being refused.
+     */
+    branch?: BranchHandling;
+}
+/**
+ * What the tool handler needs to know about branches, asked at call time so a
+ * default branch renamed in the settings is the next call's default.
+ */
+export interface ToolBranchPort {
+    /** The deployment's default branch; `''` until one is configured. */
+    defaultBranch(): string;
+    /**
+     * True only when `branch` certainly does not exist. Creates no workspace
+     * and clones nothing. A name it cannot judge — malformed, or a remote it
+     * could not ask — is `false`: opening the branch then answers for it.
+     */
+    isMissing(branch: string): Promise<boolean>;
 }
 /**
  * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
- * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
- * handler, and serializes the result — JSON for a value, SSE for an
- * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
- * The handler receives `req.body` as the flat args (UTCP's `body_field` already
- * delivered the inner body as the request body).
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, CHECKS THE
+ * ARGUMENTS against what the tool declared, runs the handler, and serializes the
+ * result — JSON for a value, SSE for an async-iterable (streaming).
+ * `ToolError`/`hasHttpStatus` map to HTTP status. The handler receives
+ * `req.body` as the flat args (UTCP's `body_field` already delivered the inner
+ * body as the request body).
+ *
+ * The argument check is HERE, in the route, because the route is where every
+ * caller of a route-hosted tool arrives: an agent over MCP, a `call_tool_chain`
+ * chain, the in-process agent over loopback, and a script calling
+ * `POST /api/agent/tools/<name>` with a connection key. Checked one layer up,
+ * in the MCP dispatch, the last of those was left answering a 500 for a missing
+ * argument — or running: `grep` without a `pattern` matched every file. Every
+ * tool mounted through this factory gets it, a deployment's included, without
+ * saying so (see `route-argument-check.ts`).
  */
-export declare function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess?: IWriteAccess): (handler: ToolHandler, opts?: ToolHandlerOptions) => (req: Request, res: Response) => Promise<void>;
+export declare function createToolHandlerFactory(resolve: ResolveToolContext, writeAccess?: IWriteAccess, 
+/** Absent: no default branch to fall back on, and no existence check before the tool runs. */
+branches?: ToolBranchPort): (handler: ToolHandler, opts?: ToolHandlerOptions) => (req: Request, res: Response) => Promise<void>;
 export type ToolHandlerFactory = ReturnType<typeof createToolHandlerFactory>;
 //# sourceMappingURL=tool-handler.d.ts.map

package/dist/modules/tool-helpers/tool-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-handler.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIjD,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGhF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACrH,OAAO,sCAAsC,CAAC;AAU9C,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,kBAAkB,EAAE,WAAW,GAAE,YAA6B,IAClF,SAAS,WAAW,EAAE,OAAM,kBAAuB,MAC/D,KAAK,OAAO,EAAE,KAAK,QAAQ,KAAG,OAAO,CAAC,IAAI,CAAC,CA4F5D;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"tool-handler.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIjD,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOhF,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACrH,OAAO,sCAAsC,CAAC;AAU9C,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,aAAa,IAAI,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAsED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,GAAE,YAA6B;AAC1C,8FAA8F;AAC9F,QAAQ,CAAC,EAAE,cAAc,IAEG,SAAS,WAAW,EAAE,OAAM,kBAAuB,MAE/D,KAAK,OAAO,EAAE,KAAK,QAAQ,KAAG,OAAO,CAAC,IAAI,CAAC,CA0J5D;AASD,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/modules/tool-helpers/tool-handler.js

@@ -1,8 +1,10 @@
 import { logger } from '../../shared/logging.js';
 const log = logger('tools');
 import { hasHttpStatus, ToolError } from './tool.contract.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { assertBranchProvided, BranchNotFoundError, DefaultBranchUnsetError, WorkflowDomainError, } from '../../shared/domain-errors.js';
+import { branchHandlingFor } from './tool-def.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
+import { argumentsRefusal } from './route-argument-check.js';
 import { alwaysWritable, READ_ONLY_CODE, refuseWriteTool } from '../write-access/write-access.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 function isAsyncIterable(v) {
@@ -10,16 +12,96 @@ function isAsyncIterable(v) {
         v !== null &&
         typeof v[Symbol.asyncIterator] === 'function');
 }
+/**
+ * Refuse a branch that certainly does not exist. A fault while finding out —
+ * a storage error reading the workspaces root, say — is logged here in full
+ * and answered as a 500 that names the branch and nothing else: its message
+ * would carry the deployment's paths to the caller.
+ */
+async function assertBranchExists(branch, branches) {
+    let missing;
+    try {
+        missing = await branches?.isMissing(branch);
+    }
+    catch (err) {
+        log.error('branch existence check failed:', { branch, err });
+        throw new ToolError(`Could not check whether branch ${branch} exists.`, 500);
+    }
+    if (missing)
+        throw new BranchNotFoundError(branch);
+}
+/**
+ * The branch a call runs on, from the tool's handling and the call's
+ * arguments — or the refusal. `defaulted` says the caller named none.
+ */
+async function resolveBranch(handling, args, branches) {
+    if (handling === 'none')
+        return null;
+    const given = args.branch;
+    if (handling === 'own') {
+        // The tool reads its optional branch itself, absence and all; only a
+        // name it was given is ours to check, and only one that names something —
+        // what the tool makes of a value that does not is the tool's to answer.
+        if (namesSomething(given))
+            await assertBranchExists(given, branches);
+        return null;
+    }
+    // ABSENT, and only absent, is defaulted. An empty or non-string value is a
+    // caller that meant to name a branch and got it wrong: refused by name
+    // under both declarations rather than quietly read as the default.
+    if (handling === 'defaults-to-default-branch' && given === undefined) {
+        const fallback = branches?.defaultBranch() ?? '';
+        if (fallback.length === 0)
+            throw new DefaultBranchUnsetError();
+        return { branch: fallback, defaulted: true };
+    }
+    assertBranchProvided(given);
+    await assertBranchExists(given, branches);
+    return { branch: given, defaulted: false };
+}
+function namesSomething(v) {
+    try {
+        assertBranchProvided(v);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A plain JSON object answer — the only kind a `branch` field can be added to.
+ * A `Date`, a class instance or an array serializes as something else, and
+ * spreading it into `{ branch }` would lose that answer.
+ */
+function isPlainObject(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const prototype = Object.getPrototypeOf(v);
+    return prototype === Object.prototype || prototype === null;
+}
 /**
  * Wrap a pure tool handler into an Express handler. Resolves the `ToolContext`
- * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, runs the
- * handler, and serializes the result — JSON for a value, SSE for an
- * async-iterable (streaming). `ToolError`/`hasHttpStatus` map to HTTP status.
- * The handler receives `req.body` as the flat args (UTCP's `body_field` already
- * delivered the inner body as the request body).
+ * from `req.toolAuth` (set by `toolAuth`), enforces write-scope, CHECKS THE
+ * ARGUMENTS against what the tool declared, runs the handler, and serializes the
+ * result — JSON for a value, SSE for an async-iterable (streaming).
+ * `ToolError`/`hasHttpStatus` map to HTTP status. The handler receives
+ * `req.body` as the flat args (UTCP's `body_field` already delivered the inner
+ * body as the request body).
+ *
+ * The argument check is HERE, in the route, because the route is where every
+ * caller of a route-hosted tool arrives: an agent over MCP, a `call_tool_chain`
+ * chain, the in-process agent over loopback, and a script calling
+ * `POST /api/agent/tools/<name>` with a connection key. Checked one layer up,
+ * in the MCP dispatch, the last of those was left answering a 500 for a missing
+ * argument — or running: `grep` without a `pattern` matched every file. Every
+ * tool mounted through this factory gets it, a deployment's included, without
+ * saying so (see `route-argument-check.ts`).
  */
-export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable) {
+export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable, 
+/** Absent: no default branch to fall back on, and no existence check before the tool runs. */
+branches) {
     return function toolHandler(handler, opts = {}) {
+        let warnedHeldToRequired = false;
         return async (req, res) => {
             const auth = req.toolAuth;
             if (!auth) {
@@ -30,6 +112,12 @@ export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable)
                 res.status(403).json({ error: 'This tool requires write access.' });
                 return;
             }
+            // About the CREDENTIAL, not the deployment: the tool is a read, and a
+            // read-only deployment serves it — the key used here is what may not.
+            if (opts.writeScope && auth.scope === 'read') {
+                res.status(403).json({ error: 'This tool cannot be used with a read-only credential; use a full-scope key.' });
+                return;
+            }
             // Before anything is awaited: a client that goes away during the
             // write-access check below must still abort the call.
             //
@@ -61,6 +149,18 @@ export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable)
                 return;
             }
             const args = (body ?? {});
+            // Before the context is resolved and before the handler runs: nothing is
+            // read, written or sent on a call that does not match its tool. The more
+            // specific refusals each tool makes for itself (a missing `branch`,
+            // above all) are left to the handler and keep their own wording — this
+            // reports what the SCHEMA alone can settle.
+            // The WHOLE path: a module mounts its routes on a router, which sees only
+            // the part below its mount point.
+            const mismatch = argumentsRefusal(req.originalUrl, args, req.query);
+            if (mismatch) {
+                res.status(mismatch.status).json({ ...mismatch.details, error: mismatch.message });
+                return;
+            }
             // `sessionId` rides the tool body like `branch` does: the external MCP
             // proxy injects it (ask-tool continuity convention) and the in-process
             // agent passes its thread id. Surfaced on the context so the
@@ -69,8 +169,50 @@ export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable)
                 ? args.sessionId
                 : undefined;
             try {
+                // The branch is resolved HERE, once, before the tool runs: refused,
+                // defaulted or checked to exist, by what the tool declared — so no
+                // tool, the platform's or a deployment's, carries a guard of its own,
+                // and none can be handed a branch that is missing, empty or not a
+                // string. Its declaration comes from the `toolDef` built for this
+                // route; a route no `toolDef` described is read like an optional
+                // `branch` the tool handles itself.
+                //
+                // A writing route never defaults, whatever was recorded for it:
+                // `toolDef` refuses the declaration at startup for a tool it knows
+                // writes, and one only mounted as writing is held to `required` here,
+                // so its write cannot land on the default branch unasked. Its
+                // published schema still calls `branch` optional — the tool's
+                // declaration is wrong, not the call — so the mismatch is logged,
+                // once per route, for the tool's author to fix by declaring both
+                // `write: true` and `branch: 'required'` (`write` alone with the
+                // defaulting declaration makes `toolDef` throw at startup).
+                const declared = opts.branch ?? branchHandlingFor(req.baseUrl + (req.route?.path ?? req.path)) ?? 'own';
+                const heldToRequired = declared === 'defaults-to-default-branch' && opts.write === true;
+                const handling = heldToRequired ? 'required' : declared;
+                if (heldToRequired && !warnedHeldToRequired) {
+                    warnedHeldToRequired = true;
+                    log.warn(`Tool route ${req.baseUrl + (req.route?.path ?? req.path)} is mounted as writing but declared ` +
+                        `branch: 'defaults-to-default-branch'; it is held to 'required'. ` +
+                        `Declare both \`write: true\` and \`branch: 'required'\` to its toolDef.`);
+                }
+                const resolved = await resolveBranch(handling, args, branches);
+                // The tool can read no other branch than the resolved one: `args`
+                // carries it under the same name, and a tool that takes no branch
+                // gets none at all.
+                const toolArgs = resolved
+                    ? { ...args, branch: resolved.branch }
+                    : handling === 'none'
+                        ? withoutBranch(args)
+                        : args;
                 const ctx = await resolve(auth, abort.signal, sessionId);
-                const out = await handler(args, ctx);
+                if (resolved)
+                    ctx.branch = resolved.branch;
+                let out = await handler(toolArgs, ctx);
+                // A defaulted call's answer says which branch it ran on, so a caller
+                // that forgot its branch can see it was answered about another.
+                if (resolved?.defaulted && isPlainObject(out) && out.branch === undefined) {
+                    out = { ...out, branch: resolved.branch };
+                }
                 if (isAsyncIterable(out)) {
                     res.setHeader('Content-Type', 'text/event-stream');
                     res.setHeader('Cache-Control', 'no-cache');
@@ -119,4 +261,11 @@ export function createToolHandlerFactory(resolve, writeAccess = alwaysWritable)
         };
     };
 }
+function withoutBranch(args) {
+    if (!('branch' in args))
+        return args;
+    const rest = { ...args };
+    delete rest.branch;
+    return rest;
+}
 //# sourceMappingURL=tool-handler.js.map