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

package/src/modules/tool-helpers/__tests__/route-argument-check.test.ts

@@ -0,0 +1,337 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createToolHandlerFactory } from '../tool-handler.js';
+import { declareRouteTool, routeToolName, routeToolSchemas } from '../route-tool-schemas.js';
+import { toolDef } from '../tool-def.js';
+import type { ToolContext } from '../tool.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+
+/**
+ * The route's argument check at the level of the helper that runs it: what it
+ * does with a tool nothing declared, what it leaves to the tool's own refusals,
+ * and that it never touches the arguments of a call that matches.
+ */
+
+let server: HttpServer | undefined;
+const calls: Array<Record<string, unknown>> = [];
+
+afterEach(async () => {
+  // A spy on `console.warn` is restored here, not at the end of its test, so
+  // a failing assertion cannot leave warnings silenced for the rest of the file.
+  vi.restoreAllMocks();
+  if (server) await new Promise<void>((r) => server!.close(() => r()));
+  server = undefined;
+  calls.length = 0;
+});
+
+/** One route per tool name, mounted exactly as a module (or a deployment) mounts it. */
+async function mount(...tools: string[]): Promise<string> {
+  const toolHandler = createToolHandlerFactory(
+    async (auth: ToolAuth, abortSignal: AbortSignal): Promise<ToolContext> =>
+      ({ user: { id: 'u', email: 'e@x.io', name: 'N' }, scope: auth.scope, source: auth.source, abortSignal }) as unknown as ToolContext,
+  );
+  const app = express();
+  app.use(express.json());
+  for (const tool of tools) {
+    app.post(
+      `/api/agent/tools/${tool}`,
+      (req, _res, next) => {
+        req.toolAuth = { source: 'external', userId: 'u', scope: 'write' };
+        next();
+      },
+      toolHandler(async (args) => {
+        calls.push(args);
+        return { ran: tool, args };
+      }),
+    );
+  }
+  server = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, '127.0.0.1', () => r(s));
+  });
+  return `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+}
+
+const post = (base: string, tool: string, body: unknown) =>
+  fetch(`${base}/api/agent/tools/${tool}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: 'Bearer k' },
+    body: JSON.stringify(body),
+  });
+
+describe('routeToolName', () => {
+  it('is the last segment of the route, query and trailing slash aside', () => {
+    expect(routeToolName('/api/agent/tools/write_file')).toBe('write_file');
+    expect(routeToolName('/agent/tools/grep/')).toBe('grep');
+    expect(routeToolName('/api/agent/tools/grep?x=1')).toBe('grep');
+    expect(routeToolName('/')).toBe('');
+  });
+});
+
+describe('a tool declared with `toolDef`', () => {
+  it('is checked by its route without the module saying so', async () => {
+    toolDef({
+      name: 'declared_by_tooldef',
+      description: 'A tool a deployment adds.',
+      path: '/api/agent/tools/declared_by_tooldef',
+      inputs: {
+        type: 'object',
+        properties: { q: { type: 'string', description: 'What to look for.' } },
+        required: ['q'],
+        additionalProperties: false,
+      },
+    });
+    const base = await mount('declared_by_tooldef');
+    const res = await post(base, 'declared_by_tooldef', {});
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string; kind: string };
+    expect(body.kind).toBe('arguments-do-not-match');
+    expect(body.error).toContain('"q" is required, and was not given.');
+    expect(body.error).toContain('q (string, required) — What to look for.');
+    expect(body.error.split('\n').pop()).toBe('Call: KNOWLEDGE_BASE.declared_by_tooldef({ body: { q: "..." } })');
+    expect(calls).toEqual([]);
+  });
+
+  it('receives a matching call with exactly the arguments that were sent', async () => {
+    toolDef({
+      name: 'untouched_arguments',
+      description: 'A tool that reports what it was given.',
+      path: '/api/agent/tools/untouched_arguments',
+      inputs: {
+        type: 'object',
+        properties: { q: { type: 'string' }, limit: { type: 'integer' }, deep: { type: 'object', properties: {} } },
+        required: ['q'],
+        additionalProperties: false,
+      },
+    });
+    const base = await mount('untouched_arguments');
+    const sent = { q: 'hello', limit: 3, deep: { a: 1 } };
+    const res = await post(base, 'untouched_arguments', sent);
+    expect(res.status).toBe(200);
+    expect(calls).toEqual([sent]);
+    expect(Object.keys(calls[0])).toEqual(['q', 'limit', 'deep']);
+  });
+});
+
+describe('a tool with nothing to check against', () => {
+  it('is called unchecked, and the reason is logged once for that tool', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const base = await mount('nobody_declared_me');
+    expect((await post(base, 'nobody_declared_me', { whatever: 1 })).status).toBe(200);
+    expect((await post(base, 'nobody_declared_me', { whatever: 1 })).status).toBe(200);
+    expect(calls).toHaveLength(2);
+    const mine = warn.mock.calls.filter((c) => c.join(' ').includes('nobody_declared_me'));
+    expect(mine).toHaveLength(1);
+    expect(mine[0].join(' ')).toContain('no input schema is declared for its route');
+  });
+
+  it('is called unchecked when the schema uses a keyword the check cannot reason about', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    declareRouteTool('uncheckable_schema', { anyOf: [{ type: 'object' }, { type: 'string' }] } as never);
+    const base = await mount('uncheckable_schema');
+    expect((await post(base, 'uncheckable_schema', { anything: true })).status).toBe(200);
+    const mine = warn.mock.calls.filter((c) => c.join(' ').includes('uncheckable_schema'));
+    expect(mine).toHaveLength(1);
+    expect(mine[0].join(' ')).toContain('anyOf');
+  });
+});
+
+describe('a call made in the wrong shape', () => {
+  it('refuses a flat call to a tool whose arguments are all optional, instead of running it on defaults', async () => {
+    // Over the http protocol a flat call's arguments ride the query string
+    // and the body is empty — which matches an all-optional tool as `{}`.
+    declareRouteTool('all_optional', {
+      type: 'object',
+      properties: { branch: { type: 'string' }, limit: { type: 'integer' } },
+      additionalProperties: false,
+    } as never);
+    const base = await mount('all_optional');
+    const res = await fetch(`${base}/api/agent/tools/all_optional?branch=main`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer k' },
+      body: '{}',
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { kind: string; error: string };
+    expect(body.kind).toBe('arguments-do-not-match');
+    expect(body.error).toContain('This tool takes its arguments under "body", not at the top level.');
+    expect(calls).toHaveLength(0);
+  });
+
+  it('refuses a flat call to a tool that requires a branch the same way, rather than as a missing branch', async () => {
+    declareRouteTool('flat_with_branch', {
+      type: 'object',
+      properties: { branch: { type: 'string' }, path: { type: 'string' } },
+      required: ['branch', 'path'],
+      additionalProperties: false,
+    } as never);
+    const base = await mount('flat_with_branch');
+    const res = await fetch(`${base}/api/agent/tools/flat_with_branch?branch=main&path=a.md`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer k' },
+      body: '{}',
+    });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: string }).error.split('\n')[1]).toBe(
+      'This tool takes its arguments under "body", not at the top level.',
+    );
+  });
+});
+
+describe('a call whose URL also carries a query string', () => {
+  it('runs when the body supplies the argument the query string repeats', async () => {
+    declareRouteTool('query_echo', {
+      type: 'object',
+      properties: { branch: { type: 'string' }, limit: { type: 'integer' } },
+      additionalProperties: false,
+    } as never);
+    const base = await mount('query_echo');
+    const res = await fetch(`${base}/api/agent/tools/query_echo?branch=main`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer k' },
+      body: JSON.stringify({ branch: 'main', limit: 2 }),
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toEqual([{ branch: 'main', limit: 2 }]);
+  });
+});
+
+describe('routes that overlap', () => {
+  it('check a request against the route that fits it best, not the one declared first', async () => {
+    toolDef({
+      name: 'short_overlap',
+      description: 'Declared at the shorter route, first.',
+      path: '/overlap_tool',
+      inputs: { type: 'object', properties: { a: { type: 'string' } }, required: ['a'], additionalProperties: false },
+    });
+    toolDef({
+      name: 'overlap_tool',
+      description: 'Declared at the longer route, second.',
+      path: '/api/agent/tools/overlap_tool',
+      inputs: { type: 'object', properties: { b: { type: 'string' } }, required: ['b'], additionalProperties: false },
+    });
+    const base = await mount('overlap_tool');
+    expect((await post(base, 'overlap_tool', { b: 'x' })).status).toBe(200);
+    const res = await post(base, 'overlap_tool', { a: 'x' });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { error: string }).error).toContain('The arguments do not match the "overlap_tool" tool.');
+  });
+});
+
+describe('a tool whose route does not end in its name', () => {
+  it('is found by its route and checked under its own name', async () => {
+    toolDef({
+      name: 'named_apart',
+      description: 'A tool hosted at a route of another name.',
+      path: '/api/things/personal',
+      inputs: { type: 'object', properties: {}, additionalProperties: false },
+    });
+    const toolHandler = createToolHandlerFactory(
+      async (auth: ToolAuth, abortSignal: AbortSignal): Promise<ToolContext> =>
+        ({ user: { id: 'u' }, scope: auth.scope, source: auth.source, abortSignal }) as unknown as ToolContext,
+    );
+    const app = express();
+    app.use(express.json());
+    // Mounted on a router, as the modules mount theirs: the handler sees only
+    // the part of the path below `/api`, and must still find the tool.
+    const router = express.Router();
+    router.post(
+      '/things/personal',
+      (req, _res, next) => {
+        req.toolAuth = { source: 'external', userId: 'u', scope: 'write' };
+        next();
+      },
+      toolHandler(async (args) => {
+        calls.push(args);
+        return { ok: true };
+      }),
+    );
+    app.use('/api', router);
+    server = await new Promise<HttpServer>((r) => {
+      const s = app.listen(0, '127.0.0.1', () => r(s));
+    });
+    const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+    const res = await fetch(`${base}/api/things/personal`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ stray: 1 }),
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('The arguments do not match the "named_apart" tool.');
+    expect(body.error).toContain('"stray" is not an argument of this tool.');
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe('what the check says nothing about', () => {
+  it('leaves `branch` to the one refusal that names it — absent, empty or a stringified nothing', async () => {
+    declareRouteTool('needs_a_branch', {
+      type: 'object',
+      properties: { branch: { type: 'string' }, path: { type: 'string' } },
+      required: ['branch', 'path'],
+      additionalProperties: false,
+    } as never);
+    const base = await mount('needs_a_branch');
+    for (const branch of [undefined, '', null, 42, ['main'], 'undefined', 'null']) {
+      const res = await post(base, 'needs_a_branch', { path: 'a.md', ...(branch === undefined ? {} : { branch }) });
+      // Forwarded, so the handler's own `branch-required` answers — and with a
+      // valid branch the same call would be checked like any other.
+      expect(res.status, String(branch)).toBe(200);
+    }
+    expect(calls).toHaveLength(7);
+  });
+
+  it('leaves an argument the tool refuses by name to the tool', async () => {
+    toolDef({
+      name: 'refuses_its_own_name',
+      description: 'A tool with a refusal of its own.',
+      path: '/api/agent/tools/refuses_its_own_name',
+      inputs: {
+        type: 'object',
+        properties: { name: { type: 'string' }, other: { type: 'string' } },
+        required: ['name', 'other'],
+        additionalProperties: false,
+      },
+      refusesItself: ['name'],
+    });
+    expect(routeToolSchemas('refuses_its_own_name')?.refusesItself.has('name')).toBe(true);
+    const base = await mount('refuses_its_own_name');
+    // Only `name` is missing: forwarded, so the tool's own message answers.
+    expect((await post(base, 'refuses_its_own_name', { other: 'o' })).status).toBe(200);
+    // `other` is missing too, and that one IS reported.
+    const res = await post(base, 'refuses_its_own_name', { name: 'n' });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('"other" is required, and was not given.');
+    expect(body.error).not.toContain('"name" is required');
+  });
+
+  it('filters by the whole quoted name: a dotted argument is not its first segment, and a nested line is kept', async () => {
+    toolDef({
+      name: 'refuses_by_whole_name',
+      description: 'A tool whose refused argument is the first segment of another, and the name of a nested object.',
+      path: '/api/agent/tools/refuses_by_whole_name',
+      inputs: {
+        type: 'object',
+        properties: {
+          a: { type: 'string' },
+          'a.b': { type: 'string' },
+          body: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+        },
+        required: ['a', 'a.b', 'body'],
+        additionalProperties: false,
+      },
+      refusesItself: ['a', 'body'],
+    });
+    const base = await mount('refuses_by_whole_name');
+    const res = await post(base, 'refuses_by_whole_name', { body: {} });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    // `a` is the tool's own; `a.b` is another argument and IS reported…
+    expect(body.error).not.toContain('"a" is required');
+    expect(body.error).toContain('"a.b" is required, and was not given.');
+    // …and a line about `body.path` is about `body.path`, not about `body`.
+    expect(body.error).toContain('"body.path" is required, and was not given.');
+  });
+});

package/src/modules/tool-helpers/index.ts

@@ -11,8 +11,41 @@
  *   const ctx = await validateToken(bearerToken, body);   // verify + resolve, throws ToolError
  *   const fs = await ctx.getFilesystem();                  // lock-aware (write) / read-only (read)
  *   const def = toolDef({ name, description, inputs, path }); // self-describing UTCP Tool to register
+ *
+ * ## The branch
+ *
+ * A tool that works on a knowledge-base branch declares how, and the tool
+ * handler resolves the branch before the tool runs — the tool itself carries
+ * no guard and reads the result from `ctx.branch`:
+ *
+ *   toolDef({ name, description, inputs, path, branch: 'required' });
+ *   toolDef({ name, description, inputs, path, branch: 'defaults-to-default-branch' });
+ *
+ *  - `required` (what a tool whose `inputs` require `branch` gets without
+ *    saying so): a call without a branch, or with an empty or non-string one,
+ *    is answered 400 `branch-required` and the tool does not run.
+ *  - `defaults-to-default-branch`, for a READ-ONLY tool: a call without a
+ *    branch runs on the deployment's default branch, the input schema shows
+ *    `branch` as optional and says so, and an object answer without a
+ *    `branch` field gets one naming the branch used. A deployment with no
+ *    default branch configured answers such a call 503
+ *    `default-branch-unset`. A writing tool (`write: true`, or a `write`
+ *    tag) that declares it makes `toolDef` throw at startup, naming the tool.
+ *  - neither, with no `branch` in `inputs`: the tool takes no branch. A stray
+ *    `branch` in a call is refused by the argument check when the schema
+ *    forbids extra arguments (every platform tool's does), and dropped before
+ *    the tool runs when the schema leaves extras open.
+ *
+ * Under either branch declaration, a given branch that does not exist is
+ * answered 404 `branch-not-found`, naming it, before the tool runs.
  */
 export { createToolValidator, type ValidateToken, type ToolValidatorDeps } from './validate-token.js';
-export { toolDef, type ToolDefSpec } from './tool-def.js';
+export {
+  toolDef,
+  BRANCH_INPUT,
+  DEFAULTED_BRANCH_INPUT,
+  type ToolDefSpec,
+  type BranchDeclaration,
+} from './tool-def.js';
 export { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from './tool.contract.js';
 export type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';

package/src/modules/tool-helpers/route-argument-check.ts

@@ -0,0 +1,149 @@
+import {
+  ARGS_UNDER_BODY_LINE,
+  ARGUMENTS_DO_NOT_MATCH_KIND,
+  argumentsDoNotMatchMessage,
+  checkFor,
+} from '@bevel-software/platform-mcp-core';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
+import { branchProvided } from '../../shared/domain-errors.js';
+import { logger } from '../../shared/logging.js';
+import { ToolError } from './tool.contract.js';
+import { routeToolName, routeToolSchemasForRequest } from './route-tool-schemas.js';
+import { DEFAULTED_BRANCH_INPUT } from './tool-def.js';
+
+const log = logger('tools');
+
+/**
+ * The argument check of a tool THIS SERVER HOSTS AS A ROUTE, run in that
+ * route's handler.
+ *
+ * It lives here, and not in the MCP layer, because the route is the one place
+ * every caller of such a tool arrives at: an agent over MCP, a `call_tool_chain`
+ * chain, the in-process agent over loopback, and a runner or script calling
+ * `POST /api/agent/tools/<name>` with a connection key. A check one layer up
+ * covered the first two and left the last answering a 500 for a missing
+ * argument, or — worse — running: `grep` without a `pattern` matched every file
+ * in the knowledge base.
+ *
+ * The arguments are checked FLAT, which is what the handler receives and what a
+ * script sends. The call example at the end of the refusal is generated from the
+ * wire schema instead, so the line an agent is invited to copy is the line it
+ * would really type.
+ */
+
+/** Tools called without a check, so the reason is logged once each (never per call). */
+const unchecked = new Set<string>();
+
+function noteUnchecked(toolName: string, reason: string): null {
+  if (!unchecked.has(toolName)) {
+    unchecked.add(toolName);
+    log.warn(
+      `calling "${toolName}" without checking its arguments — ${reason}. Its calls are passed through as they are.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * The names the tool declares at its top level. Used only to recognise the
+ * mirror-image wrong shape below; nothing is checked against it.
+ */
+function declaredNames(flat: unknown): string[] {
+  const properties = (flat as { properties?: unknown }).properties;
+  return typeof properties === 'object' && properties !== null ? Object.keys(properties) : [];
+}
+
+/** Does this tool require a `branch`? Read off its own declaration, never assumed. */
+function requiresBranch(flat: unknown): boolean {
+  const required = (flat as { required?: unknown }).required;
+  return Array.isArray(required) && required.includes('branch');
+}
+
+/** Does this tool declare `defaults-to-default-branch`? Its `branch` is then the defaulted input. */
+function defaultsBranch(flat: unknown): boolean {
+  return (flat as { properties?: Record<string, unknown> }).properties?.branch === DEFAULTED_BRANCH_INPUT;
+}
+
+/**
+ * Did this call pass the tool's arguments at the top level, to a tool that takes
+ * them under `body`?
+ *
+ * The http protocol sends the argument named by the template's `body_field`
+ * (`body`, for every tool `toolDef` declares) as the request body and EVERY
+ * OTHER argument as a query parameter. So a flat call to one of these tools
+ * arrives with an empty body and the arguments in the query string — which is
+ * what this recognises, so the refusal can name the mistake instead of listing
+ * every argument as missing and leaving the agent to guess why.
+ */
+function argumentsCameAsQuery(flat: unknown, query: unknown, args: Record<string, unknown>): boolean {
+  if (typeof query !== 'object' || query === null) return false;
+  const sent = Object.keys(query as Record<string, unknown>);
+  if (sent.length === 0) return false;
+  const names = new Set(declaredNames(flat));
+  // An argument the body DOES carry was not misplaced, whatever else the URL
+  // holds: only one that reached the route by the query string alone was.
+  // An OWN property of the body: `?toString=` would otherwise read as carried
+  // by an empty `{}` through its prototype, and the tool would run without it.
+  return sent.some((name) => names.has(name) && !Object.prototype.hasOwnProperty.call(args, name));
+}
+
+/**
+ * The refusal this call deserves, or `null` when the arguments match the tool
+ * (or when it has nothing to check them against, which is logged once).
+ *
+ * Never changes the call: a checker that repaired arguments would hide the
+ * mistake it exists to report.
+ */
+export function argumentsRefusal(
+  requestPath: string,
+  args: Record<string, unknown>,
+  query?: unknown,
+): ToolError | null {
+  const schemas = routeToolSchemasForRequest(requestPath);
+  if (!schemas) return noteUnchecked(routeToolName(requestPath), 'no input schema is declared for its route');
+  const toolName = schemas.name;
+  const check = checkFor(schemas.flat);
+  if (!check.checkable) return noteUnchecked(toolName, check.reason);
+  // The shape first, before anything may wave the call through: arguments
+  // passed flat reach this route as query parameters and leave the body
+  // empty, so a call whose arguments are all optional would otherwise MATCH —
+  // as `{}` — and run on defaults, silently dropping what was passed.
+  const cameAsQuery = argumentsCameAsQuery(schemas.flat, query, args);
+  // A call that names no branch is answered by the refusal that NAMES it, and
+  // that refusal comes first, exactly as it does today. It says what a branch
+  // is and what to pass, and it is one message rather than a list; putting a
+  // second fault ahead of it would replace an answer the caller can act on
+  // with one it has to read twice. Whatever else is wrong with such a call is
+  // reported on the next one, which at least names its workspace.
+  // A tool that defaults its branch is defaulted only when the branch is
+  // ABSENT; an empty or non-string one gets the same refusal by name.
+  if (!cameAsQuery && !branchProvided(args.branch)) {
+    if (requiresBranch(schemas.flat)) return null;
+    if (args.branch !== undefined && defaultsBranch(schemas.flat)) return null;
+  }
+  // A mismatch about an argument the tool refuses itself is dropped, so the
+  // tool's own message — which says what that argument is FOR — is the one the
+  // caller reads. Every mismatch line opens with the argument it is about.
+  const mismatches = check
+    .check(args)
+    // The whole quoted name: an argument may carry a dot of its own, and a
+    // nested line (`"body.path"`) names nothing in `refusesItself` anyway.
+    .filter((line) => !schemas.refusesItself.has(/^"([^"]+)"/.exec(line)?.[1] ?? ''));
+  // The shape first, when that is what went wrong: the lines below (every
+  // required argument missing) are its symptoms, not the mistake.
+  if (cameAsQuery) mismatches.unshift(ARGS_UNDER_BODY_LINE);
+  if (mismatches.length === 0) return null;
+  // The namespace of the example is the one manual the whole catalog is served
+  // as, so the line matches the `Call:` line at the top of this tool's own
+  // description. A connection that renames the manual (the local stdio server
+  // names it after the deployment) reads a different namespace there; the
+  // arguments, which are what the refusal is about, are the same either way.
+  const message = argumentsDoNotMatchMessage(
+    toolName,
+    `${EXTERNAL_KB_MANUAL_NAME}.${toolName}`,
+    schemas.flat,
+    mismatches,
+    { exampleInputs: schemas.wire },
+  );
+  return new ToolError(message, 400, { kind: ARGUMENTS_DO_NOT_MATCH_KIND });
+}