@bevel-software/platform-core-backend 0.1.0

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -0,0 +1,202 @@
+import type { Router, RequestHandler } from 'express';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
+import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
+import type { IToolManualService } from './tool-manuals.contract.js';
+
+/**
+ * What `list_tool_setup` needs from the secrets vault (structurally satisfied
+ * by `ISecretsVaultService.statusFor`). A local port keeps this module free of
+ * a secrets-vault import — the same decoupling discipline as
+ * `McpAuthDiscoveryPort` in the service.
+ */
+export interface VariableStatusPort {
+  statusFor(
+    userId: string,
+    keys: string[],
+  ): Promise<{ key: string; adminConfigured: boolean; userConfigured: boolean; userAuthorized?: boolean }[]>;
+}
+
+/**
+ * Registers the tool-manual catalog tools (both surfaces) and hosts their
+ * endpoints:
+ *
+ *  - `list_local_tools` — local-only manuals (`remote: false`) the remote proxy
+ *    can't serve; the agent reads their `.tool` path and self-configures.
+ *  - `list_tool_setup` — configuration status of every accessible manual, so an
+ *    agent can EXPLAIN the remaining setup to the admin. Deliberately
+ *    read-only: secret VALUES are never set (or returned) through a tool — the
+ *    admin pastes them into the tool editor; users sign in on /connect.
+ */
+export function registerToolManualsTools(
+  registry: IToolRegistry,
+  router: Router,
+  toolAuth: RequestHandler,
+  toolHandler: ToolHandlerFactory,
+  toolManualService: IToolManualService,
+  deps: {
+    accessControl: IAccessControl;
+    variableStatus: VariableStatusPort;
+  },
+): void {
+  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+
+  router.post(
+    '/agent/tools/list_local_tools',
+    toolAuth,
+    toolHandler(async (_args, ctx: ToolContext) => ({
+      tools: await toolManualService.listLocalOnly(ctx.user.email),
+    })),
+  );
+
+  const defaultWs = workspaceIdForBranch(DEFAULT_BRANCH);
+  const varKey = (manualName: string, varName: string) => utcpNamespacedKey(manualName, varName);
+
+  const listSetupDef = toolDef({
+    name: 'list_tool_setup',
+    description:
+      'Configuration status of every `.tool` the current user can access: what each tool needs set up and ' +
+      'what is already configured. Results are scoped to the caller — a `.tool` the caller cannot READ is ' +
+      'absent entirely, and all status flags reflect the caller\'s own state. Per tool: `setup` describes ' +
+      'an MCP server\'s sign-in requirement (`open` = none; `oauth-auto` = sign-in was configured ' +
+      'automatically; `oauth-manual` = the provider does not support automatic registration, so a writer ' +
+      'must declare the OAuth provider in the `.tool` file and paste its client secret into the tool ' +
+      'editor). Per variable: whether the shared (admin) value is set, whether the CURRENT user has ' +
+      'set/authorized their own, and whether it is an OAuth sign-in (users authorize those on the /connect ' +
+      'page, never by typing a value). `canWrite` = the caller may write THAT `.tool` FILE (per-file access ' +
+      'from its frontmatter `write:`/`owner:` verbs and the access.md chain — NOT a platform role), which ' +
+      'is exactly what gates setting its shared secrets: the people who manage the file configure the tool. ' +
+      'Secret VALUES are never returned and can never be set through a tool — an admin enters them in the ' +
+      'tool editor; users sign in on /connect.',
+    path: '/api/agent/tools/list_tool_setup',
+    inputs: { type: 'object', properties: {}, required: [], additionalProperties: false },
+    outputs: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              slug: { type: 'string' },
+              name: { type: 'string', description: 'The manual id — the namespace secrets bind to.' },
+              path: { type: 'string' },
+              type: { type: 'string' },
+              setup: {
+                type: ['object', 'null'],
+                description: 'MCP auto-discovery setup requirement; null for non-mcp tools.',
+                properties: { kind: { type: 'string' }, reason: { type: 'string' } },
+              },
+              canWrite: { type: 'boolean' },
+              variables: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name: { type: 'string' },
+                    scope: { type: 'string', description: '`admin` (one shared value) or `user` (per user).' },
+                    label: { type: ['string', 'null'] },
+                    oauth: { type: 'boolean', description: 'Filled by signing in on /connect, not by a value.' },
+                    adminConfigured: {
+                      type: 'boolean',
+                      description:
+                        'Shared value set (plain admin vars), or the owner finished provider setup (OAuth vars).',
+                    },
+                    userConfigured: { type: 'boolean' },
+                    authorized: { type: ['boolean', 'null'], description: 'OAuth vars: current user signed in.' },
+                  },
+                  required: ['name', 'scope', 'oauth', 'adminConfigured', 'userConfigured'],
+                },
+              },
+            },
+            required: ['slug', 'name', 'path', 'type', 'canWrite', 'variables'],
+          },
+        },
+      },
+      required: ['tools'],
+    },
+    tags: ['tools'],
+  });
+  registry.registerInternalTool(listSetupDef);
+  registry.registerExternalTool(listSetupDef);
+  router.post(
+    '/agent/tools/list_tool_setup',
+    toolAuth,
+    toolHandler(async (_args, ctx: ToolContext) => {
+      const manuals = await toolManualService.listAccessible(ctx.user.email);
+      const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
+      const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
+      const statusByKey = new Map(status.map((s) => [s.key, s]));
+      const tools = await Promise.all(
+        manuals.map(async (m) => ({
+          slug: m.slug,
+          name: m.name,
+          path: m.path,
+          type: m.type,
+          setup: m.setup ?? null,
+          canWrite: await deps.accessControl.canWrite(defaultWs, ctx.user.email, m.path),
+          variables: (m.variables ?? []).map((v) => {
+            const st = statusByKey.get(varKey(m.name, v.name));
+            const isOAuth = v.oauth != null;
+            return {
+              name: v.name,
+              scope: v.scope,
+              label: v.label ?? null,
+              oauth: isOAuth,
+              adminConfigured: st?.adminConfigured ?? false,
+              userConfigured: st?.userConfigured ?? false,
+              authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+            };
+          }),
+        })),
+      );
+      return { tools };
+    }),
+  );
+}
+
+/** "Local-only tools configured for you: `a`, `b`." (or a none note), filtered to what the caller may read. */
+async function localToolsLine(svc: IToolManualService, userEmail?: string): Promise<string> {
+  if (!userEmail) return 'No local-only tools are currently configured.';
+  const tools = await svc.listLocalOnly(userEmail);
+  if (tools.length === 0) return 'No local-only tools are currently configured.';
+  return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
+}
+
+async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
+  return toolDef({
+    name: 'list_local_tools',
+    description:
+      'List tools your workspace admins configured that run ONLY in a local environment ' +
+      '(e.g. a self-hosted MCP server on localhost) and therefore cannot be called through this ' +
+      'remote endpoint. Each entry gives the tool’s name and its `.tool` file path in the knowledge ' +
+      'base — read that file with `read_file` and configure the tool yourself in your local setup ' +
+      '(e.g. add the MCP server to your client). ' +
+      (await localToolsLine(svc, userEmail)),
+    path: '/api/agent/tools/list_local_tools',
+    inputs: { type: 'object', properties: {}, additionalProperties: false },
+    outputs: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'array',
+          description: 'Local-only tools (name + KB path).',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              path: { type: 'string', description: 'KB path of the `.tool` file (read it with read_file).' },
+            },
+          },
+        },
+      },
+    },
+    tags: ['tools'],
+  });
+}

package/src/modules/tool-registry/__tests__/tool-registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../tool-registry.js';
+import type { UtcpTool } from '../tool.contract.js';
+
+function fakeTool(name: string): UtcpTool {
+  return {
+    name,
+    description: `the ${name} tool`,
+    inputs: { type: 'object', properties: {} },
+    outputs: { type: 'object', properties: {} },
+    tags: [],
+    tool_call_template: { call_template_type: 'http' } as never,
+  } as UtcpTool;
+}
+
+describe('ToolRegistry', () => {
+  it('keeps external and internal catalogs separate', async () => {
+    const r = new ToolRegistry();
+    r.registerExternalTool(fakeTool('ask'));
+    r.registerInternalTool(fakeTool('commit_change'));
+    expect((await r.listExternal()).map((t) => t.name)).toEqual(['ask']);
+    expect((await r.listInternal()).map((t) => t.name)).toEqual(['commit_change']);
+  });
+
+  it('a `both` tool registers into both catalogs', async () => {
+    const r = new ToolRegistry();
+    const t = fakeTool('list_branches');
+    r.registerExternalTool(t);
+    r.registerInternalTool(t);
+    expect((await r.listExternal()).map((x) => x.name)).toContain('list_branches');
+    expect((await r.listInternal()).map((x) => x.name)).toContain('list_branches');
+  });
+
+  it('resolves a ToolProvider lazily and appends it after static tools', async () => {
+    const r = new ToolRegistry();
+    r.registerExternalTool(fakeTool('ask'));
+    r.registerExternalTool(() => fakeTool('list_skills'));
+    expect((await r.listExternal()).map((t) => t.name)).toEqual(['ask', 'list_skills']);
+  });
+
+  it('resolves an async (Promise-returning) ToolProvider', async () => {
+    const r = new ToolRegistry();
+    r.registerExternalTool(async () => fakeTool('list_skills'));
+    expect((await r.listExternal()).map((t) => t.name)).toEqual(['list_skills']);
+  });
+
+  it('passes the ToolManualContext through to providers', async () => {
+    const r = new ToolRegistry();
+    let received: { userEmail?: string } | undefined;
+    r.registerExternalTool((ctx) => {
+      received = ctx;
+      return fakeTool('list_skills');
+    });
+    await r.listExternal({ userEmail: 'a@b.eu' });
+    expect(received).toEqual({ userEmail: 'a@b.eu' });
+  });
+
+  it('throws on a duplicate name within a surface, but not across surfaces', () => {
+    const r = new ToolRegistry();
+    r.registerExternalTool(fakeTool('ask'));
+    expect(() => r.registerExternalTool(fakeTool('ask'))).toThrow(/Duplicate external/);
+    expect(() => r.registerInternalTool(fakeTool('ask'))).not.toThrow();
+  });
+});

package/src/modules/tool-registry/manual.routes.ts

@@ -0,0 +1,87 @@
+import express, { type Request, type RequestHandler } from 'express';
+import { UtcpManualSerializer } from '@utcp/sdk';
+import type { IToolRegistry, ToolManualContext, UtcpTool } from './tool.contract.js';
+import { requireInternalSource } from '../tool-auth/tool-auth.middleware.js';
+
+/** Resolve a connection-key/internal-token user id to its email (for per-caller provider defs). */
+export type ResolveUserEmail = (userId: string) => Promise<string | undefined>;
+
+const manualSerializer = new UtcpManualSerializer();
+
+/**
+ * Serialize a catalog slice into a UTCP manual. The manual is the registry's
+ * exposure format, so the version pins (`utcp_version` / `manual_version`) live
+ * right here at the endpoint — bump them when the served spec format changes.
+ * Each tool already carries its own `tool_call_template`, so this is otherwise a
+ * thin wrapper.
+ */
+function toManual(tools: UtcpTool[]) {
+  return manualSerializer.validateDict({
+    utcp_version: '1.1.0',
+    manual_version: '1.0.0',
+    tools,
+  });
+}
+
+/**
+ * The two discovery endpoints — dynamically-built UTCP specs over the catalog:
+ *   GET /agent/utcp           — external tools (pipeline-agent, MCP proxy)
+ *   GET /agent/internal/utcp  — internal tools (our agent's code-mode client)
+ *
+ * Both are gated by `manualAuth` — a read-only superset of `toolAuth` that also
+ * accepts a browser JWT (`source: 'session'`) so a logged-in user can browse the
+ * catalog with their session; tool EXECUTION routes keep the strict `toolAuth`,
+ * so a JWT can read the manual but never invoke a tool. The internal catalog
+ * additionally requires `requireInternalSource`, so neither an external
+ * connection key nor a browser session can enumerate the internal tool surface.
+ * Both must mount BEFORE the JWT-protected `/api` mounts (Express fires the outer
+ * JWT middleware before route matching otherwise). The catalog is resolved **per
+ * request** (`registry.list*` awaits any `ToolProvider`s), so a tool whose def is
+ * built lazily — e.g. the skill tools, whose description names the current skills
+ * — stays current without a restart. Static tools resolve to the same def every
+ * time, so this is cheap.
+ *
+ * The internal catalog is ALSO scope-filtered: a read-scoped caller (e.g. a
+ * consumer persona's internal token) is served only the tools it can actually
+ * invoke — write-tagged tools are dropped so its `list_tools`/manual never
+ * advertises a tool that would 403 at call time. The call-time write-scope
+ * refusal in `toolHandler` stays as the enforcement; this is least-information
+ * on top of it. (External callers are always write-scoped, so the external
+ * manual needs no variant.)
+ */
+function isWriteTool(tool: { tags?: string[] }): boolean {
+  return (tool.tags ?? []).includes('write');
+}
+
+export function createManualRoutes(
+  registry: IToolRegistry,
+  manualAuth: RequestHandler,
+  resolveUserEmail?: ResolveUserEmail,
+): express.Router {
+  const router = express.Router();
+
+  // Build the per-caller context once per request: resolve the caller's email
+  // so a `ToolProvider` (e.g. the skill tools) can tailor its def to who's
+  // asking. Best-effort — a failure just yields an empty (global) context.
+  async function context(req: Request): Promise<ToolManualContext> {
+    const userId = req.toolAuth?.userId;
+    if (!userId) return {};
+    if (!resolveUserEmail) return { userId };
+    try {
+      return { userId, userEmail: await resolveUserEmail(userId) };
+    } catch {
+      return { userId };
+    }
+  }
+
+  router.get('/agent/utcp', manualAuth, async (req, res) => {
+    res.json(toManual(await registry.listExternal(await context(req))));
+  });
+  router.get('/agent/internal/utcp', manualAuth, requireInternalSource, async (req, res) => {
+    const internal = await registry.listInternal(await context(req));
+    const tools = req.toolAuth?.scope === 'read' ? internal.filter((t) => !isWriteTool(t)) : internal;
+    res.json(toManual(tools));
+  });
+
+  return router;
+}

package/src/modules/tool-registry/tool-registry.ts

@@ -0,0 +1,55 @@
+import type {
+  IToolRegistry,
+  ToolListProvider,
+  ToolManualContext,
+  ToolProvider,
+  UtcpTool,
+} from './tool.contract.js';
+
+/**
+ * The tool catalog. Modules call `registerExternalTool` / `registerInternalTool`
+ * (both, for a `both` tool) with a self-describing UTCP `Tool` def, or a
+ * `ToolProvider` callable for a tool whose def is built lazily at list time. The
+ * catalog only aggregates and lists them — the two manual endpoints serialize
+ * each list per request. Insertion order is preserved (static tools first, then
+ * provider-built ones); a duplicate static name within a surface throws.
+ */
+export class ToolRegistry implements IToolRegistry {
+  private readonly external = new Map<string, UtcpTool>();
+  private readonly internal = new Map<string, UtcpTool>();
+  private readonly externalProviders: ToolProvider[] = [];
+  private readonly internalProviders: ToolProvider[] = [];
+  private readonly internalListProviders: ToolListProvider[] = [];
+
+  registerExternalTool(tool: UtcpTool | ToolProvider): void {
+    if (typeof tool === 'function') this.externalProviders.push(tool);
+    else this.add(this.external, tool, 'external');
+  }
+
+  registerInternalTool(tool: UtcpTool | ToolProvider): void {
+    if (typeof tool === 'function') this.internalProviders.push(tool);
+    else this.add(this.internal, tool, 'internal');
+  }
+
+  registerInternalTools(provider: ToolListProvider): void {
+    this.internalListProviders.push(provider);
+  }
+
+  async listExternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
+    const dynamic = await Promise.all(this.externalProviders.map((p) => p(ctx)));
+    return [...this.external.values(), ...dynamic];
+  }
+
+  async listInternal(ctx: ToolManualContext = {}): Promise<UtcpTool[]> {
+    const dynamic = await Promise.all(this.internalProviders.map((p) => p(ctx)));
+    const lists = await Promise.all(this.internalListProviders.map((p) => p(ctx)));
+    return [...this.internal.values(), ...dynamic, ...lists.flat()];
+  }
+
+  private add(into: Map<string, UtcpTool>, tool: UtcpTool, surface: string): void {
+    if (into.has(tool.name)) {
+      throw new Error(`Duplicate ${surface} tool name: "${tool.name}"`);
+    }
+    into.set(tool.name, tool);
+  }
+}

package/src/modules/tool-registry/tool.contract.ts

@@ -0,0 +1,52 @@
+import type { JsonSchema, Tool as UtcpTool } from '@utcp/sdk';
+
+export type { JsonSchema, UtcpTool };
+
+/**
+ * Per-request context handed to a `ToolProvider` when the manual is built, so a
+ * provider can tailor its def to the caller (e.g. the skill tools name only the
+ * skills THIS user may read).
+ */
+export interface ToolManualContext {
+  /** The requesting user's email, when it could be resolved. */
+  userEmail?: string;
+  /** The requesting user's id, when it could be resolved (for per-user gating). */
+  userId?: string;
+}
+
+/**
+ * A lazy tool definition: a callable that produces a UTCP `Tool` at list time.
+ * Use it for a tool whose def must reflect live state when the manual is built
+ * (e.g. the skill tools, whose description names the currently-available
+ * skills). Resolved on every `listExternal`/`listInternal` call, so the manual
+ * stays current without a restart. Static tools are passed as a plain `UtcpTool`.
+ */
+export type ToolProvider = (ctx: ToolManualContext) => UtcpTool | Promise<UtcpTool>;
+
+/**
+ * A lazy provider that yields ZERO OR MORE tool defs at list time. Unlike
+ * {@link ToolProvider} (exactly one tool), a list provider can return `[]` to
+ * contribute nothing — the mechanism a Connector uses to expose its tool family
+ * only while it is enabled + configured, and hide it otherwise, with no restart.
+ */
+export type ToolListProvider = (ctx: ToolManualContext) => UtcpTool[] | Promise<UtcpTool[]>;
+
+/**
+ * The registry is a pure CATALOG of self-describing UTCP `Tool` defs (each
+ * carries its own `tool_call_template`). It never knows how a tool executes —
+ * the owning module hosts the endpoint. `external`/`internal` are two separate
+ * lists; a tool that's both is registered into both. A tool is registered as a
+ * plain `UtcpTool` (static) or a `ToolProvider` (resolved per list call).
+ */
+export interface IToolRegistry {
+  registerExternalTool(tool: UtcpTool | ToolProvider): void;
+  registerInternalTool(tool: UtcpTool | ToolProvider): void;
+  /**
+   * Register a provider that contributes zero-or-more INTERNAL tools per list
+   * call. Used by the connector host to expose a connector's tool family only
+   * while it is enabled + configured.
+   */
+  registerInternalTools(provider: ToolListProvider): void;
+  listExternal(ctx?: ToolManualContext): Promise<UtcpTool[]>;
+  listInternal(ctx?: ToolManualContext): Promise<UtcpTool[]>;
+}