@bevel-software/platform-core-backend 0.1.0

package/src/modules/tool-helpers/__tests__/phase0-loopback-spike.test.ts

@@ -0,0 +1,129 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import '@utcp/http'; // registers the http CallTemplate serializer + protocol
+import { HttpCallTemplateSerializer } from '@utcp/http';
+import { CodeModeUtcpClient } from '../../code-mode/index.js';
+
+const httpTemplate = new HttpCallTemplateSerializer();
+
+/**
+ * PHASE 0 SPIKE (gates the unified-registry plan): prove the agent's INTERNAL
+ * execution model works — a real `CodeModeUtcpClient` discovers an HTTP UTCP
+ * manual over loopback and calls its tools from inside `call_tool_chain`, with a
+ * bearer token resolved from per-client config. Also benchmark per-op loopback
+ * latency (R1). This mirrors what each agent turn will do against the internal
+ * manual endpoint. Throwaway once the real registry e2e lands.
+ */
+
+const MANUAL = 'bevel';
+
+// The internal UTCP manual a module-hosted endpoint would serve. Tools use the
+// `{body}` wrapper (body_field:'body') so multi-field args ride the JSON body —
+// the only standard-http way to do that (verified in @utcp/http callTool).
+function manual(): unknown {
+  const httpTool = (name: string, bodyProps: Record<string, unknown>) => ({
+    name,
+    description: `the ${name} tool`,
+    inputs: {
+      type: 'object',
+      properties: { body: { type: 'object', properties: bodyProps } },
+      required: ['body'],
+    },
+    outputs: { type: 'object', properties: {} },
+    tags: [],
+    tool_call_template: {
+      call_template_type: 'http',
+      http_method: 'POST',
+      url: `\${API_URL}/api/agent/tools/${name}`,
+      content_type: 'application/json',
+      headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+      body_field: 'body',
+    },
+  });
+  return {
+    utcp_version: '1.1.0',
+    manual_version: '1.0.0',
+    tools: [httpTool('list_branches', {}), httpTool('echo', { msg: { type: 'string' } })],
+  };
+}
+
+let httpServer: HttpServer | undefined;
+let seenAuth: string | undefined;
+
+async function startApp(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/internal/utcp', (_req, res) => res.json(manual()));
+  app.post('/api/agent/tools/list_branches', (req, res) => {
+    seenAuth = req.headers.authorization;
+    res.json({ branches: ['current-company-state', 'target-company-state'] });
+  });
+  app.post('/api/agent/tools/echo', (req, res) => {
+    res.json({ echoed: (req.body as { msg?: string })?.msg ?? null });
+  });
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+async function buildClient(baseUrl: string, token: string): Promise<CodeModeUtcpClient> {
+  // Per-client config carries the loopback base URL + the scoped token under the
+  // manual namespace (`<MANUAL>_API_URL` / `<MANUAL>_CONNECTION_KEY`).
+  const client = await CodeModeUtcpClient.create(process.cwd(), {
+    variables: { [`${MANUAL}_API_URL`]: baseUrl, [`${MANUAL}_CONNECTION_KEY`]: token },
+  } as never);
+  await client.registerManual(
+    httpTemplate.validateDict({
+      name: MANUAL,
+      call_template_type: 'http',
+      http_method: 'GET',
+      url: '${API_URL}/api/agent/internal/utcp',
+      content_type: 'application/json',
+      headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+    }),
+  );
+  return client;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  seenAuth = undefined;
+});
+
+describe('Phase 0 — internal loopback execution', () => {
+  it('discovers an http manual and calls its tools from inside call_tool_chain', async () => {
+    const base = await startApp();
+    const client = await buildClient(base, 'internal-token-abc');
+
+    const tools = await client.getTools();
+    expect(tools.map((t) => t.name).sort()).toEqual([`${MANUAL}.echo`, `${MANUAL}.list_branches`]);
+
+    const { result } = await client.callToolChain(
+      `return { a: ${MANUAL}.list_branches({ body: {} }), b: ${MANUAL}.echo({ body: { msg: 'hi' } }) };`,
+      20_000,
+    );
+    expect(result.a).toEqual({ branches: ['current-company-state', 'target-company-state'] });
+    expect(result.b).toEqual({ echoed: 'hi' });
+    // The per-client token reached the loopback endpoint.
+    expect(seenAuth).toBe('Bearer internal-token-abc');
+  });
+
+  it('benchmark: per-op loopback latency inside a code-mode loop', async () => {
+    const base = await startApp();
+    const client = await buildClient(base, 'tok');
+    const N = 30;
+    const t0 = performance.now();
+    const { result } = await client.callToolChain(
+      `let n = 0; for (let i = 0; i < ${N}; i++) { ${MANUAL}.echo({ body: { msg: 'x' } }); n++; } return n;`,
+      30_000,
+    );
+    const ms = performance.now() - t0;
+    expect(result).toBe(N);
+    // eslint-disable-next-line no-console
+    console.log(`[phase0] ${N} loopback tool calls in one code-mode chain: ${ms.toFixed(0)}ms total, ${(ms / N).toFixed(1)}ms/op`);
+  });
+});

package/src/modules/tool-helpers/__tests__/phase4-tools.test.ts

@@ -0,0 +1,95 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../tool-context.js';
+import { createToolHandlerFactory } from '../tool-handler.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
+import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { SpillStore } from '../../workspace/spill-store.js';
+
+const WS = 'target-company-state';
+let recorded: unknown[][] = [];
+
+const externalApiKeyService = { verifyAndLoadToken: async () => null } as never;
+const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+const workspaceService = {
+  getOrCreateForUser: async () => ({ id: WS }),
+  getWorkspacePath: async () => '/tmp/ws',
+  unzipFile: async (ws: string, p: string, d?: string) => {
+    recorded.push(['unzip', ws, p, d]);
+    return { extracted: [p], skipped: [] };
+  },
+  readFile: async () => {
+    throw new Error('no such file');
+  },
+} as never;
+const workflowService = {} as never;
+const events = {} as never;
+const accessControl = {
+  canRead: async () => true,
+  canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+} as never;
+
+const internalToken = new InternalTokenService({ secret: 's' });
+let httpServer: HttpServer | undefined;
+
+async function start(): Promise<string> {
+  const registry = new ToolRegistry();
+  const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
+  const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
+  const th = createToolHandlerFactory(resolve);
+  const router = express.Router();
+  // NOTE (core split): this suite used to register the search, feedback and
+  // kb (citation) tools alongside the workspace tools. Those registrations —
+  // and their web_search / submit_feedback / cite_kb_node cases — moved to
+  // the enterprise repo with their modules; core registers only core tools.
+  registerWorkspaceTools(registry, router, toolAuth, th, new SpillStore('/tmp/bevel-test-spills'), accessControl, 'knowledge-base', {
+    service: {} as never,
+    enabled: false, // ontology boundary not under test here
+    kbDirName: 'knowledge-base',
+    recoveryBotEmail: 'recovery-bot@bevel.local',
+    hooks: new WorkflowHooks(),
+  }, new RoutineWritePolicyService(), {} as never /* sessionSink — start_session not exercised here */);
+  router.use(createManualRoutes(registry, toolAuth));
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', router);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+const tok = () => internalToken.mint({ userId: 'user-A' });
+const post = (url: string, body: unknown = {}) =>
+  fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${tok()}` }, body: JSON.stringify(body) });
+
+beforeEach(() => {
+  recorded = [];
+});
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('Phase 4 tools (core subset)', () => {
+  it('unzip calls workspaceService.unzipFile with the context workspace', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/unzip`, { path: 'a.zip', branch: WS });
+    expect(res.status).toBe(200);
+    expect(recorded).toContainEqual(['unzip', WS, 'a.zip', undefined]);
+  });
+
+  it('the registered core tool appears in the internal manual', async () => {
+    const base = await start();
+    const m = (await (await fetch(`${base}/api/agent/internal/utcp`, { headers: { authorization: `Bearer ${tok()}` } })).json()) as { tools: { name: string }[] };
+    const names = m.tools.map((t) => t.name);
+    expect(names).toContain('unzip');
+  });
+});

package/src/modules/tool-helpers/__tests__/tools-surface.test.ts

@@ -0,0 +1,146 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { toolDef } from '../tool-def.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware, requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../tool-context.js';
+import { createToolHandlerFactory } from '../tool-handler.js';
+import { createManualRoutes } from '../../tool-registry/manual.routes.js';
+import type { ToolContext } from '../tool.contract.js';
+
+/**
+ * Integration test for the Phase 1 machinery: the ONE mechanism (host endpoint +
+ * register def), the dual `toolAuth` (connection key OR internal token resolving
+ * to a normalized context), write-scope enforcement, and the two manual
+ * endpoints — over a real express app.
+ */
+
+const WS = 'target-company-state';
+
+// Minimal service stubs (list_branches/touch don't touch the filesystem, so the
+// lazy LockingFilesystem is never built).
+const externalApiKeyService = {
+  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  verifyAndLoadToken: async (t: string) =>
+    t === 'bevel_good' ? { user: { id: 'user-A', email: 'e@x', name: 'N' }, tokenId: 'tok-1' } : null,
+} as never;
+const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+const workspaceService = {
+  getOrCreateForUser: async () => ({ id: WS }),
+  getWorkspacePath: async () => '/tmp/ws',
+} as never;
+const workflowService = { listBranches: async () => [{ name: 'main', isProtected: true }] } as never;
+const events = {} as never;
+
+let httpServer: HttpServer | undefined;
+const internalToken = new InternalTokenService({ secret: 'test-secret' });
+
+async function start(): Promise<string> {
+  const registry = new ToolRegistry();
+  const toolAuth = createToolAuthMiddleware(externalApiKeyService, internalToken);
+  const resolve = createToolContextResolver({ authService, workspaceService, workflowService, events, kbDirName: 'knowledge-base', creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} } });
+  const toolHandler = createToolHandlerFactory(resolve);
+
+  registry.registerExternalTool(
+    toolDef({ name: 'list_branches', description: 'list', path: '/api/agent/tools/list_branches', inputs: { type: 'object', properties: {} } }),
+  );
+  registry.registerInternalTool(
+    toolDef({ name: 'list_branches', description: 'list', path: '/api/agent/tools/list_branches', inputs: { type: 'object', properties: {} } }),
+  );
+  registry.registerInternalTool(
+    toolDef({ name: 'touch', description: 'write', path: '/api/agent/tools/touch', inputs: { type: 'object', properties: {} }, tags: ['write'] }),
+  );
+
+  const app = express();
+  app.use(express.json());
+  app.post(
+    '/api/agent/tools/list_branches',
+    toolAuth,
+    toolHandler(async (_a: Record<string, unknown>, ctx: ToolContext) => ({
+      branches: await ctx.workflowService.listBranches('ws'),
+      ranAs: ctx.user.id,
+      source: ctx.source,
+    })),
+  );
+  // `touch` is internal-only (registered only via registerInternalTool) AND
+  // write-tagged — so its route carries the internal-source gate, mirroring the
+  // production mount helpers.
+  app.post(
+    '/api/agent/tools/touch',
+    toolAuth,
+    requireInternalSource,
+    toolHandler(async () => ({ ok: true }), { write: true }),
+  );
+  // Internal-only route: mounted (our agent reaches it over loopback) but gated.
+  app.post(
+    '/api/agent/tools/secret_internal',
+    toolAuth,
+    requireInternalSource,
+    toolHandler(async () => ({ ok: true })),
+  );
+  app.use('/api', createManualRoutes(registry, toolAuth));
+
+  httpServer = await new Promise<HttpServer>((resolve2) => {
+    const s = app.listen(0, () => resolve2(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+const post = (url: string, bearer: string, body: unknown = {}) =>
+  fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` }, body: JSON.stringify(body) });
+
+const get = (url: string, bearer: string) => fetch(url, { headers: { authorization: `Bearer ${bearer}` } });
+
+describe('tools surface — dual auth + scope + manuals', () => {
+  it('dispatches the same tool under BOTH a connection key and an internal token', async () => {
+    const base = await start();
+    const keyRes = await post(`${base}/api/agent/tools/list_branches`, 'bevel_good');
+    expect(keyRes.status).toBe(200);
+    expect(await keyRes.json()).toMatchObject({ branches: [{ name: 'main' }], ranAs: 'user-A', source: 'external' });
+
+    const intTok = internalToken.mint({ userId: 'user-A' });
+    const intRes = await post(`${base}/api/agent/tools/list_branches`, intTok);
+    expect(intRes.status).toBe(200);
+    expect(await intRes.json()).toMatchObject({ source: 'internal', ranAs: 'user-A' });
+  });
+
+  it('rejects a bad/absent bearer (401)', async () => {
+    const base = await start();
+    expect((await post(`${base}/api/agent/tools/list_branches`, 'nonsense')).status).toBe(401);
+    expect((await fetch(`${base}/api/agent/tools/list_branches`, { method: 'POST' })).status).toBe(401);
+  });
+
+  it('serves filtered manuals: internal has list_branches+touch, external only list_branches', async () => {
+    const base = await start();
+    const intTok = internalToken.mint({ userId: 'user-A' });
+    const internal = (await (await get(`${base}/api/agent/internal/utcp`, intTok)).json()) as { tools: { name: string }[] };
+    const external = (await (await get(`${base}/api/agent/utcp`, 'bevel_good')).json()) as { tools: { name: string }[] };
+    expect(internal.tools.map((t) => t.name).sort()).toEqual(['list_branches', 'touch']);
+    expect(external.tools.map((t) => t.name)).toEqual(['list_branches']);
+  });
+
+  it('refuses internal-only surfaces to an external connection key (403), but admits an internal token', async () => {
+    const base = await start();
+    const intTok = internalToken.mint({ userId: 'user-A' });
+
+    // The internal tool catalog: external key authenticates but is not internal.
+    expect((await get(`${base}/api/agent/internal/utcp`, 'bevel_good')).status).toBe(403);
+    expect((await get(`${base}/api/agent/internal/utcp`, intTok)).status).toBe(200);
+
+    // Internal-only tool routes, reached directly by name, are gated the same
+    // way — an external write-scope key can't bypass the catalog filtering by
+    // POSTing the route directly. (`touch` is also write-tagged.)
+    expect((await post(`${base}/api/agent/tools/secret_internal`, 'bevel_good')).status).toBe(403);
+    expect((await post(`${base}/api/agent/tools/secret_internal`, intTok)).status).toBe(200);
+    expect((await post(`${base}/api/agent/tools/touch`, 'bevel_good')).status).toBe(403);
+    expect((await post(`${base}/api/agent/tools/touch`, intTok)).status).toBe(200);
+  });
+});

package/src/modules/tool-helpers/__tests__/validate-token.test.ts

@@ -0,0 +1,75 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolValidator } from '../validate-token.js';
+import { hasHttpStatus } from '../tool.contract.js';
+
+/**
+ * `validateToken` is the framework-agnostic SDK entry: bearer token → full
+ * `ToolContext`, fusing the shared verify core with the context resolver. These
+ * tests pin that contract (the same one a marketplace plugin will code against).
+ */
+
+const internalToken = new InternalTokenService({ secret: 'test-secret' });
+const externalApiKeyService = {
+  looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  verifyAndLoadToken: async (t: string) =>
+    t === 'bevel_ok' ? { user: { id: 'u-ext', email: 'e@x', name: 'Ext' }, tokenId: 'tk-1' } : null,
+} as never;
+const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
+
+let tempDir = '';
+const workspaceService = {
+  getWorkspacePath: async () => tempDir,
+  getOrCreateForUser: async () => ({ id: 'ext-ws' }),
+} as never;
+
+const validateToken = createToolValidator({
+  externalApiKeyService,
+  internalTokenService: internalToken,
+  authService,
+  workspaceService,
+  workflowService: {} as never,
+  events: {} as never,
+  kbDirName: 'knowledge-base',
+  creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+});
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'validate-token-'));
+  await writeFile(join(tempDir, 'a.md'), 'hi');
+});
+afterEach(async () => {
+  if (tempDir) await rm(tempDir, { recursive: true, force: true });
+  tempDir = '';
+});
+
+describe('validateToken (tool-author SDK entry)', () => {
+  it('resolves an internal token to a write-scoped identity context (no workspace bound)', async () => {
+    const tok = internalToken.mint({ userId: 'u1' });
+    const ctx = await validateToken(tok);
+    expect(ctx).toMatchObject({ source: 'internal', scope: 'write' });
+    expect(ctx.user.id).toBe('u1');
+  });
+
+  it('resolves an external connection key to a write-scoped identity context', async () => {
+    const ctx = await validateToken('bevel_ok');
+    expect(ctx).toMatchObject({ source: 'external', scope: 'write' });
+    expect(ctx.user.id).toBe('u-ext');
+  });
+
+  it('getFilesystem(branch) builds the filesystem for that branch\'s workspace', async () => {
+    const tok = internalToken.mint({ userId: 'u1' });
+    const fs = await (await validateToken(tok)).getFilesystem('some/draft');
+    expect((await fs.readFile('a.md')).toString()).toBe('hi');
+  });
+
+  it('throws a 401 ToolError on a bad token and an empty token', async () => {
+    for (const bad of ['garbage', 'bevel_nope', '', undefined]) {
+      const err = await validateToken(bad as string).catch((e) => e);
+      expect(hasHttpStatus(err) && err.status).toBe(401);
+    }
+  });
+});

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

@@ -0,0 +1,18 @@
+/**
+ * The tool-author SDK — everything needed to build a tool, in ONE import.
+ * Internal tools use it today; it is the surface a third-party marketplace
+ * plugin will code against (eventually shipped as a standalone `@bevel-software/tool-sdk`
+ * package). A tool author never needs the registry internals, the Express
+ * middleware, or the internal-token service — only what is re-exported here.
+ *
+ *   import { validateToken, toolDef, ToolError } from '<tool-sdk>';
+ *
+ *   // in your endpoint:
+ *   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
+ */
+export { createToolValidator, type ValidateToken, type ToolValidatorDeps } from './validate-token.js';
+export { toolDef, type ToolDefSpec } 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/tool-context.ts

@@ -0,0 +1,98 @@
+import { LocalFilesystem } from '@mastra/core/workspace';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import { LockingFilesystem } from '../workflow/locking-filesystem.js';
+import { ReadOnlyFilesystem } from '../workflow/read-only-filesystem.js';
+import { makeRolesYamlWriteValidator } from '../access/roles-yaml-guard.js';
+import type { ICreatorAccess } from '../access/creator-access.js';
+import { branchForWorkspaceId, type WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthService } from '../auth/auth.service.js';
+import { ToolError, type ToolContext } from './tool.contract.js';
+import type { ToolAuth } from '../tool-auth/tool-auth.middleware.js';
+
+export interface ToolContextDeps {
+  authService: AuthService;
+  workspaceService: WorkspaceService;
+  workflowService: IWorkflowService;
+  events: WorkflowEventBus;
+  /** KB dir name — used to recognise (and validate) writes to `roles.yaml`. */
+  kbDirName: string;
+  /**
+   * Creator read-grant planner, threaded into the LockingFilesystem so agent
+   * creations in unreadable spots stay visible to the driving user (see
+   * `modules/access/creator-access`).
+   */
+  creatorAccess: ICreatorAccess;
+}
+
+export type ResolveToolContext = (
+  auth: ToolAuth,
+  abortSignal: AbortSignal,
+  sessionId?: string,
+) => Promise<ToolContext>;
+
+/**
+ * Build the per-call `ToolContext` from a verified `ToolAuth`. Identity (user,
+ * scope, source) is resolved up front; the WORKSPACE is resolved on demand by
+ * `getFilesystem(branch)` and cached per branch. Internal and external callers
+ * are identical — the credential is identity-only, so the workspace always comes
+ * from the `branch` the tool passes (`getOrCreateForUser` clones the per-branch
+ * workspace if needed). A tool that never touches the KB never calls
+ * `getFilesystem`, so it resolves no workspace. Writes through the
+ * LockingFilesystem auto-commit+push as `user`. Framework-agnostic — never reads
+ * a request body; `branch` arrives as an explicit argument from the tool.
+ */
+export function createToolContextResolver(deps: ToolContextDeps): ResolveToolContext {
+  // Reject an agent write that would leave roles.yaml unparseable (app-wide
+  // admin lockout) before it reaches disk — the agent gets a tool error and the
+  // file is untouched, mirroring the human editor's save-time gate.
+  const validateRolesWrite = makeRolesYamlWriteValidator(deps.kbDirName);
+
+  return async function resolveToolContext(auth, abortSignal, sessionId) {
+    const user = await deps.authService.getUserById(auth.userId);
+    if (!user) throw new ToolError('Your account is no longer available.', 401);
+
+    const fsCache = new Map<string, LocalFilesystem>();
+    const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
+      const cached = fsCache.get(branch);
+      if (cached) return cached;
+      const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
+      const workspaceId = ws.id;
+      const basePath = await deps.workspaceService.getWorkspacePath(workspaceId);
+      const fs =
+        auth.scope === 'write'
+          ? new LockingFilesystem(
+              { basePath, contained: true },
+              {
+                workflow: deps.workflowService,
+                workspaceId,
+                branch: branchForWorkspaceId(workspaceId),
+                user,
+                validateWrite: validateRolesWrite,
+                creatorAccess: deps.creatorAccess,
+              },
+            )
+          : new ReadOnlyFilesystem({ basePath, contained: true });
+      fsCache.set(branch, fs);
+      return fs;
+    };
+
+    return {
+      user,
+      scope: auth.scope,
+      source: auth.source,
+      tokenId: auth.tokenId,
+      // For `internal` callers the signed token claim is the ONLY trustworthy
+      // session: honoring a body value would let one per-run token switch to a
+      // fresh `sessionId` and shed its accumulated touched-set. The body path is
+      // only for `external`/`session` callers, whose token carries no claim and
+      // whose `sessionId` is injected by the MCP proxy's continuity convention.
+      sessionId: auth.source === 'internal' ? auth.sessionId : sessionId ?? auth.sessionId,
+      abortSignal,
+      workspaceService: deps.workspaceService,
+      workflowService: deps.workflowService,
+      events: deps.events,
+      getFilesystem,
+    };
+  };
+}

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

@@ -0,0 +1,73 @@
+import '@utcp/http';
+import { HttpCallTemplateSerializer } from '@utcp/http';
+import { ToolSerializer } from '@utcp/sdk';
+import type { JsonSchema, UtcpTool } from '../tool-registry/tool.contract.js';
+
+const httpTemplate = new HttpCallTemplateSerializer();
+const toolSerializer = new ToolSerializer();
+
+/**
+ * The required `branch` input every KB tool declares — the model names the
+ * workspace (draft) the call acts on. Since the credential is identity-only
+ * (internal token == connection key), the workspace is never implied; it always
+ * comes from this argument.
+ */
+export const BRANCH_INPUT: JsonSchema = {
+  type: 'string',
+  minLength: 1,
+  description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
+};
+
+/** Add a required `branch` property to an object input schema (KB tools). */
+export function withBranchInput(inputs: JsonSchema): JsonSchema {
+  const o = inputs as { properties?: Record<string, JsonSchema>; required?: string[] };
+  return {
+    ...inputs,
+    properties: { ...(o.properties ?? {}), branch: BRANCH_INPUT },
+    required: [...new Set([...(o.required ?? []), 'branch'])],
+  } as JsonSchema;
+}
+
+export interface ToolDefSpec {
+  /** Unique within its surface; also the namespace member the agent calls (`Bevel.<name>`). */
+  name: string;
+  description: string;
+  /** The LOGICAL (flat) input schema — what the handler receives and the agent passes. */
+  inputs: JsonSchema;
+  outputs?: JsonSchema;
+  tags?: string[];
+  /** The route the owning module hosts, e.g. `/agent/tools/list_branches`. */
+  path: string;
+}
+
+/**
+ * Build a self-describing UTCP `Tool` def for a module-hosted endpoint. The flat
+ * `inputs` are wrapped under a single `body` property (`body_field: 'body'`) —
+ * the only standard-http way to ride multiple fields in the JSON body — so the
+ * agent calls `Bevel.<name>({ body: { ... } })` and the endpoint reads `req.body`
+ * 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.
+ */
+export function toolDef(spec: ToolDefSpec): UtcpTool {
+  return toolSerializer.validateDict({
+    name: spec.name,
+    description: spec.description,
+    inputs: {
+      type: 'object',
+      properties: { body: spec.inputs },
+      required: ['body'],
+      additionalProperties: false,
+    },
+    outputs: spec.outputs ?? { type: 'object', properties: {} },
+    tags: spec.tags ?? [],
+    tool_call_template: httpTemplate.validateDict({
+      call_template_type: 'http',
+      http_method: 'POST',
+      url: `\${API_URL}${spec.path}`,
+      content_type: 'application/json',
+      headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+      body_field: 'body',
+    }),
+  });
+}