@bevel-software/platform-core-backend 0.32.0 → 0.33.0

package/migrations/meta/_journal.json

@@ -141,6 +141,20 @@
       "when": 1792404850653,
       "tag": "0019_oauth_token_rotated_at",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1792491287956,
+      "tag": "0020_change_request_body_is_the_description",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1792491290917,
+      "tag": "0021_data_migrations_ledger",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.32.0",
-    "@bevel-software/platform-shared": "0.32.0"
+    "@bevel-software/platform-mcp-core": "0.33.0",
+    "@bevel-software/platform-shared": "0.33.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/core/__tests__/damaged-document.tools.test.ts

@@ -0,0 +1,374 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import express, { type RequestHandler } from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { LocalFilesystem } from '@mastra/core/workspace';
+import { ToolRegistry } from '../../modules/tool-registry/tool-registry.js';
+import { createManualRoutes } from '../../modules/tool-registry/manual.routes.js';
+import { createToolHandlerFactory } from '../../modules/tool-helpers/tool-handler.js';
+import type { ToolContext } from '../../modules/tool-helpers/tool.contract.js';
+import type { ToolAuth } from '../../modules/tool-auth/tool-auth.middleware.js';
+import { registerWorkspaceTools } from '../../modules/workspace/workspace.tools.js';
+import { RoutineWritePolicyService } from '../../modules/workspace/routine-write-policy.js';
+import { WorkflowHooks } from '../../modules/workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../modules/workspace/agent-access.gate.js';
+import { SpillStore } from '../../modules/workspace/spill-store.js';
+import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
+import { DocExtractService, type UnreadableDocument } from '../../modules/workspace/file-readers/doc-extract.service.js';
+import type { IDocumentExtractor } from '../../modules/workspace/file-readers/document-extractor.contract.js';
+import { WorkerDocumentExtractor, type WorkerDocumentExtractorOptions } from '../../modules/workspace/file-readers/extract-in-worker.js';
+import type { IAccessControl } from '../../modules/access/access-control.interface.js';
+import { createMcpRoutes } from '../../modules/mcp/mcp.routes.js';
+import { McpService } from '../../modules/mcp/mcp.service.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
+import { xrefPdf } from '../../modules/workspace/file-readers/__tests__/fixtures/damaged-pdf.js';
+
+/**
+ * A damaged document, on every surface that extracts: `read_file`, `grep`,
+ * `file_stat` and `call_tool_chain` answer it with the same one-line notice,
+ * extract it once, never again for the same bytes, and the server keeps
+ * answering its health route throughout. The fixture is a synthetic PDF with
+ * a damaged cross-reference table (`fixtures/damaged-pdf.ts`).
+ *
+ * It lives with the composition root's tests because it composes the server
+ * across modules — the tool registry, the tool handler, the MCP proxy — as
+ * `create-core-server.ts` does.
+ */
+
+const KB = 'knowledge-base';
+const BRANCH = 'main';
+const BEARER = 'bevel_key_user_a';
+const DAMAGED = `${KB}/Legal/Supplier-Agreement.pdf`;
+const PDFJS_SAYS = "could not extract the PDF's text (Bad (uncompressed) XRef entry: 4R)";
+const NOTICE = `[${DAMAGED} ${PDFJS_SAYS} — the file may be corrupt or mislabeled. To fix it, replace the document by uploading a new version.]`;
+
+const fakeAuth: RequestHandler = (req, _res, next) => {
+  req.toolAuth = { source: 'internal', userId: 'u', scope: 'write' };
+  req.userId = 'u';
+  req.externalApiKeyId = 'tok-a';
+  next();
+};
+const passthrough: RequestHandler = (_req, _res, next) => next();
+
+interface Platform {
+  baseUrl: string;
+  /** Extractions the worker was actually asked for. */
+  extractions(): number;
+  /** Fresh failures the service reported. */
+  told: UnreadableDocument[];
+  write(path: string, bytes: Buffer | string): Promise<void>;
+  stop(): Promise<void>;
+}
+
+const running: Platform[] = [];
+afterEach(async () => {
+  for (const p of running.splice(0)) await p.stop().catch(() => {});
+});
+
+async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {}): Promise<Platform> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'damaged-doc-'));
+  const fs = new LocalFilesystem({ basePath: tempDir, contained: true });
+  const worker = new WorkerDocumentExtractor(extractorOpts);
+  let extractions = 0;
+  const counting: IDocumentExtractor = {
+    extract: (ext, bytes) => {
+      extractions++;
+      return worker.extract(ext, bytes);
+    },
+    close: () => worker.close(),
+  };
+  const told: UnreadableDocument[] = [];
+  const docExtract = new DocExtractService(join(tempDir, '.doc-extract'), counting, { onUnreadable: (d) => told.push(d) });
+  const matcher = new WorkerPatternMatcher();
+
+  const registry = new ToolRegistry();
+  const resolve = async (auth: ToolAuth, signal: AbortSignal, sessionId?: string): Promise<ToolContext> => ({
+    user: { id: 'u', email: 'e@x', name: 'N' },
+    scope: auth.scope,
+    source: auth.source,
+    sessionId,
+    abortSignal: signal,
+    workspaceService: { getWorkspacePath: async () => tempDir } as never,
+    workflowService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => fs,
+  });
+  // Everyone may do everything: what this suite is about is extraction, not access.
+  const allowAll = new Proxy(
+    {},
+    {
+      get: (_target, verb) =>
+        typeof verb === 'string' && verb.endsWith('Batch')
+          ? async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true]))
+          : async () => true,
+    },
+  ) as IAccessControl;
+
+  const app = express();
+  app.use(express.json());
+  // What the server's own health route does: answer at once, if the thread is free to.
+  app.get('/api/health', (_req, res) => {
+    res.json({ status: 'ok' });
+  });
+  const router = express.Router();
+  registerWorkspaceTools(
+    registry,
+    router,
+    fakeAuth,
+    createToolHandlerFactory(resolve),
+    new SpillStore(join(tempDir, 'spills')),
+    docExtract,
+    allowAll,
+    testKbContext({ kbDirName: KB }),
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    new RoutineWritePolicyService(),
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    matcher,
+  );
+  app.use('/api', router);
+  const httpServer = await new Promise<HttpServer>((res) => {
+    const s = app.listen(0, '127.0.0.1', () => res(s));
+  });
+  const baseUrl = `http://127.0.0.1:${(httpServer.address() as AddressInfo).port}`;
+
+  // `call_tool_chain`: the real MCP proxy, dispatching back over loopback.
+  app.get('/api/agent/all-tools', (_req, res) => {
+    res.json({
+      manuals: [
+        {
+          name: 'KNOWLEDGE_BASE',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        },
+      ],
+    });
+  });
+  const mcp = new McpService({
+    loopbackBaseUrl: baseUrl,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tempDir, 'spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+  });
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(mcp, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
+  app.use('/api', createManualRoutes(registry, passthrough));
+
+  const write = async (path: string, bytes: Buffer | string) => {
+    await mkdir(dirname(join(tempDir, path)), { recursive: true });
+    await writeFile(join(tempDir, path), bytes);
+  };
+  await write(DAMAGED, xrefPdf('Hello damaged', { damage: true }));
+  await write(`${KB}/Legal/notes.md`, 'Hello from the notes\n');
+  await write(`${KB}/Legal/sound.pdf`, xrefPdf('Hello sound', { damage: false }));
+
+  let stopped = false;
+  const platform: Platform = {
+    baseUrl,
+    extractions: () => extractions,
+    told,
+    write,
+    async stop() {
+      if (stopped) return;
+      stopped = true;
+      mcp.onSecretsChanged(null);
+      httpServer.closeAllConnections();
+      await new Promise<void>((r) => httpServer.close(() => r()));
+      await Promise.all([worker.close(), matcher.close()]);
+      await rm(tempDir, { recursive: true, force: true });
+    },
+  };
+  running.push(platform);
+  return platform;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- tool answers, read by shape
+async function tool(baseUrl: string, name: string, body: object): Promise<any> {
+  const res = await fetch(`${baseUrl}/api/agent/tools/${name}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${BEARER}` },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  expect(res.status, text).toBe(200);
+  return JSON.parse(text);
+}
+
+/** `call_tool_chain` over the MCP endpoint; answers what the chain returned. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- the chain's result, read by shape
+async function chain(baseUrl: string, code: string): Promise<any> {
+  const res = await fetch(`${baseUrl}/api/mcp`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      Authorization: `Bearer ${BEARER}`,
+    },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'call_tool_chain', arguments: { code } } }),
+  });
+  const text = await res.text();
+  const lines = text.startsWith('event:') || text.startsWith('data:')
+    ? text.split('\n').filter((l) => l.startsWith('data:')).map((l) => JSON.parse(l.slice(5)))
+    : [JSON.parse(text)];
+  const result = lines[lines.length - 1]?.result;
+  expect(result?.isError, JSON.stringify(lines)).toBeFalsy();
+  const answer = JSON.parse((result.content as Array<{ text: string }>)[0]!.text);
+  expect(answer.success, JSON.stringify(answer)).toBe(true);
+  return answer.result;
+}
+
+/**
+ * Run `work` while asking the health route every 50 ms; answers the slowest
+ * health answer seen, in ms, and what `work` answered.
+ */
+async function timingHealth<T>(baseUrl: string, work: () => Promise<T>): Promise<{ slowest: number; answer: T }> {
+  let slowest = 0;
+  let done = false;
+  const probes: Promise<void>[] = [];
+  const probe = async () => {
+    const started = Date.now();
+    const res = await fetch(`${baseUrl}/api/health`);
+    await res.text();
+    slowest = Math.max(slowest, Date.now() - started);
+  };
+  const loop = (async () => {
+    while (!done) {
+      probes.push(probe());
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  })();
+  const answer = await work();
+  done = true;
+  await loop;
+  await Promise.all(probes);
+  return { slowest, answer };
+}
+
+describe('a PDF with a damaged cross-reference table', () => {
+  it('read_file answers the one-line notice with pdf.js’s message — once extracted, never again', async () => {
+    const p = await startPlatform();
+    const first = await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: DAMAGED });
+    expect(first.content).toBe(NOTICE);
+    const second = await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: DAMAGED });
+    expect(second.content).toBe(NOTICE);
+    expect(p.extractions()).toBe(1);
+    // Reported once, for the workspace it was read in.
+    expect(p.told).toEqual([{ workspaceId: 'main', path: DAMAGED, reason: PDFJS_SAYS }]);
+  });
+
+  it('file_stat answers the remembered notice — and extracts nothing to do so', async () => {
+    const p = await startPlatform();
+    const before = await tool(p.baseUrl, 'file_stat', { branch: BRANCH, path: DAMAGED });
+    expect(before.unreadable).toBeUndefined();
+    expect(before.contentMode).toBe('document');
+    expect(p.extractions()).toBe(0);
+    await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: DAMAGED });
+    const after = await tool(p.baseUrl, 'file_stat', { branch: BRANCH, path: DAMAGED });
+    expect(after.unreadable).toBe(NOTICE);
+    expect(p.extractions()).toBe(1);
+  });
+
+  it('call_tool_chain gets the same notice as a direct read_file', async () => {
+    const p = await startPlatform();
+    const result = await chain(
+      p.baseUrl,
+      `return KNOWLEDGE_BASE.read_file({ body: { branch: ${JSON.stringify(BRANCH)}, path: ${JSON.stringify(DAMAGED)} } });`,
+    );
+    expect(result.content).toBe(NOTICE);
+  });
+
+  it('grep skips it — every other file’s matches come back — and the next grep does not extract it again', async () => {
+    const p = await startPlatform();
+    const first = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'Hello', path: `${KB}/Legal` });
+    const paths = (first.matches as Array<{ path: string }>).map((m) => m.path).sort();
+    expect(paths).toEqual([`${KB}/Legal/notes.md`, `${KB}/Legal/sound.pdf`]);
+    const extracted = p.extractions();
+    expect(extracted).toBe(2);
+    const second = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'Hello', path: `${KB}/Legal` });
+    expect(second.matches).toEqual(first.matches);
+    expect(p.extractions()).toBe(extracted);
+  });
+
+  it('grep spends no extraction budget on a remembered failure', async () => {
+    const p = await startPlatform();
+    // 21 different damaged documents — one more than a grep's budget of 20 cold extractions.
+    for (let i = 0; i < 21; i++) await p.write(`${KB}/Many/damaged-${String(i).padStart(2, '0')}.pdf`, xrefPdf(`copy ${i}`, { damage: true }));
+    const first = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'copy', path: `${KB}/Many` });
+    expect(first.note).toMatch(/^1 document\(s\) .* were not searched/);
+    // The twenty it remembers cost nothing now, so the twenty-first fits.
+    const second = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'copy', path: `${KB}/Many` });
+    expect(second.note).toBeUndefined();
+    expect(p.extractions()).toBe(21);
+    const third = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'copy', path: `${KB}/Many` });
+    expect(third.note).toBeUndefined();
+    expect(p.extractions()).toBe(21);
+  });
+
+  it('a repaired version, saved over it, is extracted and reads normally', async () => {
+    const p = await startPlatform();
+    await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: DAMAGED });
+    await p.write(DAMAGED, xrefPdf('Hello repaired', { damage: false }));
+    const repaired = await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: DAMAGED });
+    expect(repaired.content).toBe(`[extracted text of ${DAMAGED} — 1 page; layout, images and formatting omitted]\n[page 1]\nHello repaired`);
+  });
+});
+
+describe('an extraction that runs long', () => {
+  const trouble = (budgetMs?: number): WorkerDocumentExtractorOptions => ({
+    entry: {
+      url: new URL('../../modules/workspace/file-readers/__tests__/fixtures/pdf-in-trouble.worker.ts', import.meta.url),
+      execArgv: ['--import', 'tsx'],
+    },
+    ...(budgetMs === undefined ? {} : { budgetMs }),
+  });
+
+  it('is stopped at the budget and answered with the timeout notice; within the hour the notice comes at once', async () => {
+    const p = await startPlatform(trouble(500));
+    await p.write(`${KB}/Legal/stuck.pdf`, xrefPdf('HANG', { damage: false }));
+    const first = await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: `${KB}/Legal/stuck.pdf` });
+    expect(first.content).toContain('could not be read: extracting its text took longer than 0.5 seconds');
+    const started = Date.now();
+    const again = await tool(p.baseUrl, 'read_file', { branch: BRANCH, path: `${KB}/Legal/stuck.pdf` });
+    expect(again.content).toBe(first.content);
+    expect(Date.now() - started).toBeLessThan(400);
+    expect(p.extractions()).toBe(1);
+    const grep = await tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'HANG', path: `${KB}/Legal/stuck.pdf` });
+    expect(grep.matches).toEqual([]);
+    expect(p.extractions()).toBe(1);
+    expect(p.told).toEqual([
+      { workspaceId: 'main', path: `${KB}/Legal/stuck.pdf`, reason: 'extracting its text took longer than 0.5 seconds' },
+    ]);
+  });
+
+  it('leaves /api/health answering under a second, on every surface that extracts', async () => {
+    const p = await startPlatform(trouble());
+    for (const name of ['a', 'b', 'c', 'd']) await p.write(`${KB}/Slow/${name}.pdf`, xrefPdf(`SLOW ${name}`, { damage: false }));
+    const surfaces: Array<[string, () => Promise<unknown>]> = [
+      ['read_file', () => tool(p.baseUrl, 'read_file', { branch: BRANCH, path: `${KB}/Slow/a.pdf` })],
+      ['grep', () => tool(p.baseUrl, 'grep', { branch: BRANCH, pattern: 'SLOW', path: `${KB}/Slow/b.pdf` })],
+      ['file_stat', () => tool(p.baseUrl, 'file_stat', { branch: BRANCH, path: `${KB}/Slow/c.pdf` })],
+      [
+        'call_tool_chain',
+        () => chain(p.baseUrl, `return KNOWLEDGE_BASE.read_file({ body: { branch: "main", path: "${KB}/Slow/d.pdf" } });`),
+      ],
+    ];
+    for (const [surface, work] of surfaces) {
+      const { slowest } = await timingHealth(p.baseUrl, work);
+      expect(slowest, surface).toBeLessThan(1_000);
+    }
+    // Three of the four extracted (file_stat never does), each spinning 1.5 s in its worker.
+    expect(p.extractions()).toBe(3);
+  });
+});

package/src/core/__tests__/public-config.test.ts

@@ -24,6 +24,11 @@ describe('GET /api/config payload', () => {
     expect(body.catalogRevision).toBe(true);
   });
 
+  /** The local bridge reads the read-only hints on every listing, on the same terms. */
+  it('advertises the tool-hints capability, on the same terms', () => {
+    expect(body.toolHints).toBe(true);
+  });
+
   it('carries the branch model and the two addresses it was handed', () => {
     expect(body.branchModel.defaultBranch).toBe(DEFAULT_BRANCH);
     expect(body.branchModel.protectedBranches).toContain(DEFAULT_BRANCH);

package/src/core/create-core-server.ts

@@ -13,13 +13,18 @@ import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
 import { createWorkflowRoutes } from '../modules/workflow/workflow.routes.js';
-import { createEventsRoutes } from '../modules/workflow/events.routes.js';
+import { createEventAccess, createEventsRoutes, EventDelivery } from '../modules/workflow/index.js';
 import { createAccessRoutes } from '../modules/access/access.routes.js';
 import { createAccessRequestRoutes } from '../modules/access/access-requests.routes.js';
+import { AccessRequestsService } from '../modules/access/access-requests.service.js';
 import { createMcpRoutes } from '../modules/mcp/mcp.routes.js';
 import { createOAuthConsentRoutes } from '../modules/mcp/oauth/oauth-consent.routes.js';
 import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { createManualRoutes } from '../modules/tool-registry/manual.routes.js';
+import {
+  createToolHintsAgentRoutes,
+  createToolHintsRoutes,
+} from '../modules/tool-registry/read-only-hints.js';
 import { createCatalogRevisionRoutes } from './catalog-revision.js';
 import {
   createToolManualsAgentRoutes,
@@ -539,11 +544,16 @@ export async function createCoreServer(
     agentAccessGate,
     core,
   });
+  // What MCP clients are told about each platform tool's effect: read by the
+  // agent manual (the hosted endpoint) and by `/agent/tool-hints` (hexis-mcp).
+  const { readOnlyHints } = core;
   toolsRouter.use(createManualRoutes(
     core.toolRegistry,
     core.manualAuthMiddleware,
     async (userId) => (await core.authService.getUserById(userId))?.email,
+    readOnlyHints,
   ));
+  toolsRouter.use(createToolHintsAgentRoutes(readOnlyHints, core.manualAuthMiddleware));
   // The aggregated manual list (KB + the caller's accessible `.tool`s) + inline
   // `.tool` sub-manuals. Mounted on the tools router so they share `manualAuth`
   // and sit before the JWT `/api` mounts.
@@ -666,7 +676,19 @@ export async function createCoreServer(
   // cookie — the cookie path is what makes EventSource work, since the
   // browser API can't set headers). Mounted as its own app.use so it
   // doesn't share an outer middleware chain with the JSON routes above.
-  app.use('/api', createEventsRoutes(core.eventBus, core.authMiddleware));
+  // Every event passes the delivery rule on its way to a session: the file
+  // routes' read verdict, read in the server's own checkouts — for an
+  // approval, the target branch's; a target with no checkout at its ref.
+  const eventDelivery = new EventDelivery(createEventAccess({
+    accessControl: core.accessControl,
+    kbDirName: core.kbDirName,
+    getChangeRequest: (number) => core.workflowService.getChangeRequest(number),
+    workspaces: {
+      hasWorkspace: (workspaceId) => core.workspaceService.hasBootstrappedWorkspace(workspaceId),
+      anyWorkspaceId: async () => (await core.workspaceService.findAnyWorkspaceId()) ?? core.kb.defaultWorkspaceId(),
+    },
+  }));
+  app.use('/api', createEventsRoutes(core.eventBus, core.authMiddleware, eventDelivery));
   app.use('/api', core.authMiddleware, createDiffRoutes(
     core.diffService,
     core.authService,
@@ -711,7 +733,12 @@ export async function createCoreServer(
       skillService: core.skillService,
       accessControl: core.accessControl,
       workflow: core.workflowService,
-      workspaceService: core.workspaceService,
+      requests: new AccessRequestsService({
+        workflow: core.workflowService,
+        workspaceService: core.workspaceService,
+        lifecycle: core.joinRequestsService,
+        kb: core.kb,
+      }),
       joinRequests: core.joinRequestsService,
       kb: core.kb,
       resolveUser: async (req) =>
@@ -747,6 +774,8 @@ export async function createCoreServer(
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
   app.use('/api', core.authMiddleware, createAdminAccessRoutes(core.adminAccess));
+  // The Tools page's read-only toggles: anyone signed in reads, admins write.
+  app.use('/api', core.authMiddleware, createToolHintsRoutes(readOnlyHints, core.adminAccess));
   // Groups admin (manual-mode CRUD; typed refusals in IdP mode) —
   // admin-gated inside.
   app.use('/api', core.authMiddleware, createGroupsAdminRoutes({

package/src/core/create-core-services.ts

@@ -34,6 +34,8 @@ import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-f
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
 import { DeploymentSettingsService, retireMergedBranchesOn } from '../modules/settings/deployment-settings.service.js';
+import { ToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.js';
+import type { IToolReadOnlyHints } from '../modules/tool-registry/read-only-hints.contract.js';
 import { KbSyncService } from '../modules/kb-sync/kb-sync.service.js';
 import { NodeFs } from '../modules/kb-fs/node-fs.js';
 import { assertKbDirNameFree } from '../modules/kb-fs/repo-path.js';
@@ -67,7 +69,11 @@ import { createDownloadFetcherIdentifier } from '../modules/workspace/agent-down
 import { WorkerPatternMatcher } from '../modules/workspace/bounded-matcher.js';
 import type { IPatternMatcher } from '../modules/workspace/pattern-matcher.contract.js';
 import type { Request } from 'express';
-import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
+import {
+  DocExtractService,
+  WorkerDocumentExtractor,
+  type IDocumentExtractor,
+} from '../modules/workspace/index.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountHooks, type IAccountHooks } from '../modules/auth/account-hooks.js';
@@ -75,6 +81,7 @@ import { AccountErasureService } from '../modules/auth/account-erasure.service.j
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
 import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
+import { AccessMutationService } from '../modules/access/access-mutation.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
@@ -122,7 +129,7 @@ import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
 import { FileLockService } from '../modules/workflow/file-lock.service.js';
-import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import { WorkflowEventBus } from '../modules/workflow/index.js';
 import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { StarterPackService } from '../modules/onboarding/starter-pack.service.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
@@ -256,6 +263,8 @@ export interface CoreServices {
    * download route can refuse a link presented by someone it was not issued to.
    */
   agentDownloadFetcher: (req: Request) => Promise<string[]>;
+  /** Runs every document extraction off the request thread under a budget; its workers end when the graph stops. */
+  documentExtractor: IDocumentExtractor;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -399,6 +408,8 @@ export interface CoreServices {
   /** The Audit log: what every connected agent and key called, and the revoke of an agent's grant. */
   agentAuditService: AgentAuditService;
   toolRegistry: ToolRegistry;
+  /** Each platform tool's and meta-tool's read-only hint, and an admin's overrides of them. */
+  readOnlyHints: IToolReadOnlyHints;
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
   toolHandlerFactory: ReturnType<typeof createToolHandlerFactory>;
@@ -791,9 +802,9 @@ export async function createCoreServices(
     // `<tenant>-down_`: recognisable by shape beside the upload token.
     tokenPrefix: config.uploadTokenPrefix.replace(/up_$/, 'down_'),
   });
-  // Office-document/PDF text extraction for `read_file`/`grep`, cached by
-  // content hash beside the workspaces root (see `DocExtractionCache`).
-  const docExtractService = new DocExtractService(config.docExtractCacheRoot);
+  // The worker threads every office/PDF/email extraction runs in, under a
+  // 10 s budget per file (see `WorkerDocumentExtractor`).
+  const documentExtractor = new WorkerDocumentExtractor();
   // The deployment owner counts as Admin for the two hardcoded `write`
   // rescues (`roles.yaml` and any `access.md`) — the SAME list
   // `AdminAccessService` below is given, so the admin surfaces and the write
@@ -952,6 +963,14 @@ export async function createCoreServices(
   // browser sessions. Single instance per Node process — survives across
   // requests, doesn't survive restarts (clients reconnect + resync).
   const eventBus = new WorkflowEventBus();
+  // Office-document/PDF/email text extraction for `read_file`/`grep`, cached
+  // by content hash beside the workspaces root (see `DocExtractionCache`),
+  // failures included. A fresh failure is told to the people looking at the
+  // file: the events route delivers it only to sessions that may read it.
+  const docExtractService = new DocExtractService(config.docExtractCacheRoot, documentExtractor, {
+    onUnreadable: ({ workspaceId, path, reason }) =>
+      eventBus.emit({ kind: 'document-unreadable', workspaceId, path, reason }),
+  });
   // In-process post-commit hook (distinct from the SSE bus): fires once per
   // committed change (batched paths) so catalogs refresh instantly and the
   // id-repair keeps the id namespace collision-free. Subscribers are registered
@@ -1038,6 +1057,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
+    new AccessMutationService(workspaceService, accessControl, kb.kbDirName),
     skillService,
     pluginLinkIndex,
     kb,
@@ -1386,6 +1406,8 @@ export async function createCoreServices(
       // the setup save applies lands without a restart.
       kbLayout: () => kb.layout,
       secretsScope,
+      // Read at listing time, by when the hints below exist.
+      readOnlyOverrides: () => readOnlyHints.overrides(),
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
     // set it?" and the manual catalog answers "which user-scoped vars does this
@@ -1454,6 +1476,9 @@ export async function createCoreServices(
   // `internalTokenService` minted above (shared with the agent factories) is
   // the same one the tool-auth middleware verifies internal tokens against.
   const toolRegistry = new ToolRegistry();
+  // What MCP clients are told about each platform tool's effect: its write
+  // declaration, or an admin's override from the Tools page.
+  const readOnlyHints = new ToolReadOnlyHints(toolRegistry, settings);
   const resolveToolContext = createToolContextResolver({
     authService,
     workspaceService,
@@ -1650,6 +1675,7 @@ export async function createCoreServices(
     agentDownloadStore,
     patternMatcher,
     agentDownloadFetcher,
+    documentExtractor,
     docExtractService,
     accessControl,
     creatorAccess,
@@ -1708,6 +1734,7 @@ export async function createCoreServices(
     mcpResourceMetadataUrl,
     agentAuditService,
     toolRegistry,
+    readOnlyHints,
     toolAuthMiddleware,
     manualAuthMiddleware,
     toolHandlerFactory,

package/src/core/lifecycle.ts

@@ -454,6 +454,12 @@ export interface CoreStopDeps {
    * caller that has not built one passes nothing.
    */
   patternMatcher?: { close(): Promise<void> };
+  /**
+   * The document extractor, whose worker threads are this graph's own for the
+   * same reason: ended here, so no extraction worker outlives its graph.
+   * Optional like the matcher.
+   */
+  documentExtractor?: { close(): Promise<void> };
   /**
    * The workflow service, for the tidy-up it runs after each sweep (closing
    * empty requests, removing leftover branches): detached from whatever
@@ -591,6 +597,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.patternMatcher) {
     await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
   }
+  // Likewise: an extraction still running is answered busy, and nothing about its file is remembered.
+  if (deps.documentExtractor) {
+    await bounded(deps.documentExtractor.close(), remaining(), 'ending the extraction workers', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);