@bevel-software/platform-core-backend 0.30.0 → 0.31.0

package/src/modules/mcp/shared-definitions.ts

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import type { CallTemplate, Tool as UtcpTool } from '@utcp/sdk';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import type { ProxiedTool } from '@bevel-software/platform-mcp-core';
+
+/**
+ * Tool definitions held once for every cached client that discovered the same
+ * ones.
+ *
+ * Two hundred people whose catalogs are identical would otherwise hold two
+ * hundred copies of the same descriptions and schemas: a client's repository
+ * keeps what discovery parsed, and every build parses its own. After a build,
+ * each manual's discovered tools are swapped for the first copy of identical
+ * tools this process has seen, so the descriptions, schemas and call templates
+ * are one object graph no matter how many clients point at it. A client keeps
+ * only what is its own: the repository's per-tool shells, its variables and
+ * its secrets loader.
+ *
+ * Identity is the CONTENT of the definitions, not the manual's name or its
+ * template: the knowledge base's manual is filtered per caller, so two people
+ * can get different tools from the same template, and only identical content
+ * may be shared. Definitions are tool schemas and call TEMPLATES — `${VAR}`
+ * placeholders, never a resolved value — so sharing them shares no secret.
+ *
+ * Nothing here is read back for correctness: a definition dropped from these
+ * maps (they are bounded) only stops the NEXT build from sharing it.
+ */
+export class SharedDefinitions {
+  private readonly byContent = new Map<string, unknown>();
+  private readonly interfaceCaches = new Map<string, Map<string, string>>();
+
+  /** `maxEntries` bounds each map; 0 shares nothing. */
+  constructor(private readonly maxEntries = 1000) {}
+
+  /**
+   * The first-seen copy of `value` (by its JSON), or `value` itself when it is
+   * the first. Kinds share no key space: a tool list and a listing could
+   * otherwise serialise alike.
+   */
+  intern<T>(kind: string, value: T): T {
+    const key = `${kind}\u0000${fingerprint(value)}`;
+    const held = this.byContent.get(key);
+    if (held !== undefined) {
+      // Recently used goes last, so the first entry is the one to drop.
+      this.byContent.delete(key);
+      this.byContent.set(key, held);
+      return held as T;
+    }
+    if (this.maxEntries <= 0) return value;
+    bound(this.byContent, this.maxEntries);
+    this.byContent.set(key, value);
+    return value;
+  }
+
+  /**
+   * Point `client`'s repository at shared definitions: every manual's tools,
+   * and the client's cache of generated TypeScript interfaces.
+   *
+   * `rawTemplates` are the manuals as fetched, by the name they are registered
+   * under. Registration stores the template AFTER variable substitution — for
+   * a platform-hosted manual, with the bearer of the request that built the
+   * client in its headers. Nothing calls through a stored template (each
+   * tool's own template is substituted at call time), but a cached client
+   * must hold no request's credential, so the stored template is put back to
+   * its placeholders.
+   */
+  async share(client: CodeModeUtcpClient, rawTemplates: ReadonlyMap<string, CallTemplate>): Promise<void> {
+    const repo = client.config.tool_repository;
+    const templates = await repo.getManualCallTemplates();
+    const everyTool: UtcpTool[] = [];
+    for (const stored of templates) {
+      const name = String(stored.name ?? '');
+      const manual = await repo.getManual(name);
+      if (!manual) continue;
+      const tools = this.intern('tools', manual.tools);
+      everyTool.push(...tools);
+      const raw = rawTemplates.get(name);
+      const template = raw ? ({ ...raw, name } as CallTemplate) : stored;
+      await repo.saveManual(template, { ...manual, tools });
+    }
+    // `toolFunctionCache` is filled lazily by `tools_info` and every chain,
+    // keyed by tool name and derived from the definitions alone. Shared by
+    // every client holding the very same tool set, it is generated once for
+    // all of them instead of once per person.
+    (client as unknown as { toolFunctionCache: Map<string, string> }).toolFunctionCache = this.interfaceCache(
+      fingerprint(everyTool),
+    );
+  }
+
+  /** The flattened catalog a surface lists, shared the same way. */
+  listing(tools: ProxiedTool[]): ProxiedTool[] {
+    return this.intern('listing', tools);
+  }
+
+  /** The generated-interface cache of one exact tool set. */
+  private interfaceCache(toolSet: string): Map<string, string> {
+    let cache = this.interfaceCaches.get(toolSet);
+    if (cache) {
+      this.interfaceCaches.delete(toolSet);
+    } else {
+      cache = new Map();
+      if (this.maxEntries <= 0) return cache;
+      bound(this.interfaceCaches, this.maxEntries);
+    }
+    this.interfaceCaches.set(toolSet, cache);
+    return cache;
+  }
+}
+
+/** Make room for one more entry, dropping the least recently used. */
+function bound(map: Map<string, unknown>, maxEntries: number): void {
+  while (map.size >= maxEntries) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+function fingerprint(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}

package/src/modules/mcp/surface-cache.ts

@@ -0,0 +1,154 @@
+/**
+ * The hosted MCP server's memory of built tool surfaces: one per caller and
+ * catalog revision, built once and reused until something it was built from
+ * changes.
+ *
+ * Keyed by whatever the service says identifies a surface — the person, the
+ * kind of caller, the key's scope and the catalog revision. A catalog change
+ * needs no listener: it is a new revision, so a new key, and the old entry
+ * ages out unused. What the revision cannot see (a secret) is evicted
+ * explicitly through {@link evictWhere} / {@link clear}.
+ *
+ * Bounded twice: an entry unused for `idleTtlMs` is dropped, and at most
+ * `maxEntries` are held, the least recently used going first. `maxEntries: 0`
+ * keeps nothing, which is the per-request build this replaced: the escape
+ * hatch if the cache ever has to be switched off.
+ *
+ * Single-flight: concurrent misses on one key share one build. A build that
+ * fails is not remembered, so the next request tries again. A build that was
+ * in flight when its key was evicted answers the requests waiting on it but is
+ * not kept: it was built from what the eviction said is stale. A build still
+ * running after `buildTimeoutMs` is let go the same way, so a discovery that
+ * hangs holds up the requests already waiting on it, not every later one.
+ *
+ * Holds references only. A surface owns no connection (its `mcp` manuals route
+ * to the downstream pool, which owns and closes those), so dropping an entry
+ * is the whole teardown.
+ */
+export interface SurfaceCacheOptions {
+  /** Drop an entry unused for this long. Default one hour. */
+  idleTtlMs?: number;
+  /** Hold at most this many entries. Default 500; 0 keeps nothing. */
+  maxEntries?: number;
+  /** Let go of a build still running after this long; the next request starts another. Default two minutes. */
+  buildTimeoutMs?: number;
+  /** Clock, for tests. */
+  now?: () => number;
+}
+
+export const SURFACE_IDLE_TTL_MS = 60 * 60 * 1000;
+export const SURFACE_BUILD_TIMEOUT_MS = 2 * 60 * 1000;
+export const SURFACE_MAX_ENTRIES = 500;
+
+interface Entry<V> {
+  value: Promise<V>;
+  startedAt: number;
+  lastUsed: number;
+  /** An absolute end, for a value that must not live its full idle time (see `maxAgeMs`). */
+  expiresAt: number;
+  /** False once the entry was evicted while its build was still running. */
+  live: boolean;
+  settled: boolean;
+}
+
+export class SurfaceCache<V> {
+  private readonly entries = new Map<string, Entry<V>>();
+  private readonly idleTtlMs: number;
+  private readonly maxEntries: number;
+  private readonly buildTimeoutMs: number;
+  private readonly now: () => number;
+
+  constructor(opts: SurfaceCacheOptions = {}) {
+    this.idleTtlMs = opts.idleTtlMs ?? SURFACE_IDLE_TTL_MS;
+    this.maxEntries = opts.maxEntries ?? SURFACE_MAX_ENTRIES;
+    this.buildTimeoutMs = opts.buildTimeoutMs ?? SURFACE_BUILD_TIMEOUT_MS;
+    this.now = opts.now ?? Date.now;
+  }
+
+  /**
+   * The value for `key`, built by `build` when none is held. `hit` says
+   * whether this call found one (or joined a build already running).
+   *
+   * `maxAgeMs`, read off a built value, ends that entry early whatever its
+   * use: a surface built while one of its manuals was failing is kept only
+   * as long as that failure would be remembered anyway.
+   */
+  async get(
+    key: string,
+    build: () => Promise<V>,
+    maxAgeMs?: (value: V) => number | undefined,
+  ): Promise<{ value: V; hit: boolean }> {
+    this.sweep();
+    const now = this.now();
+    const held = this.entries.get(key);
+    if (held) {
+      held.lastUsed = now;
+      // Most recently used goes last, so the first entry is always the one to drop.
+      this.entries.delete(key);
+      this.entries.set(key, held);
+      return { value: await held.value, hit: true };
+    }
+    if (this.maxEntries <= 0) return { value: await build(), hit: false };
+    while (this.entries.size >= this.maxEntries) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest === undefined) break;
+      this.drop(oldest);
+    }
+    const entry: Entry<V> = {
+      value: build(),
+      startedAt: now,
+      lastUsed: now,
+      expiresAt: Number.POSITIVE_INFINITY,
+      live: true,
+      settled: false,
+    };
+    this.entries.set(key, entry);
+    try {
+      const value = await entry.value;
+      entry.settled = true;
+      const maxAge = maxAgeMs?.(value);
+      if (maxAge !== undefined) entry.expiresAt = this.now() + maxAge;
+      if (!entry.live) this.forget(key, entry);
+      return { value, hit: false };
+    } catch (err) {
+      this.forget(key, entry);
+      throw err;
+    }
+  }
+
+  /** Drop every entry whose key matches. A build in flight still answers its waiters, and is not kept. */
+  evictWhere(predicate: (key: string) => boolean): void {
+    for (const key of [...this.entries.keys()]) {
+      if (predicate(key)) this.drop(key);
+    }
+  }
+
+  /** Drop everything. */
+  clear(): void {
+    this.evictWhere(() => true);
+  }
+
+  private drop(key: string): void {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    entry.live = false;
+    this.entries.delete(key);
+  }
+
+  /** Remove `entry` only if it is still the one under `key` (a newer build may have taken its place). */
+  private forget(key: string, entry: Entry<V>): void {
+    if (this.entries.get(key) === entry) this.entries.delete(key);
+  }
+
+  /** Drop what has been idle too long, or outlived its own end, and let go of a build that has run too long. */
+  private sweep(): void {
+    const now = this.now();
+    for (const [key, entry] of this.entries) {
+      if (!entry.settled) {
+        if (now - entry.startedAt >= this.buildTimeoutMs) this.drop(key);
+        continue;
+      }
+      if (now - entry.lastUsed >= this.idleTtlMs || now >= entry.expiresAt) this.drop(key);
+    }
+  }
+}

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 import { ReadOnlyFilesystem } from '../kb-fs/read-only-filesystem.js';
 import {
   makeAgentRolesYamlWriteValidator,
@@ -76,6 +77,36 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     if (!user) throw new ToolError('Your account is no longer available.', 401);
 
     const { loadActiveGroups } = deps;
+    const validatorCache = new Map<string, WriteValidator>();
+    /**
+     * The agent's pre-disk `roles.yaml` gate for `branch`'s workspace
+     * (cached): refuses a write that would leave the file unparseable (an
+     * app-wide admin lockout), that creates a role, or that adds a
+     * `- group:` entry naming no group — agents manage membership; roles are
+     * pre-set. ONE gate for every agent write to the workspace: the file
+     * tools take it before a byte lands, and `update_branch` takes it for a
+     * resolution's content before the merge.
+     */
+    const getWriteValidator = async (branch: string): Promise<WriteValidator> => {
+      assertBranchProvided(branch);
+      const cached = validatorCache.get(branch);
+      if (cached) return cached;
+      const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
+      const basePath = await deps.workspaceService.getWorkspacePath(ws.id);
+      const validator = makeAgentRolesYamlWriteValidator(
+        deps.kbDirName,
+        () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
+        loadActiveGroups &&
+          (async () => {
+            // A source that exists but cannot be read leaves group entries
+            // unchecked rather than refusing every one.
+            const active = await loadActiveGroups((file) => readTextIfExists(path.join(basePath, deps.kbDirName, file)));
+            return active.health.ok ? active : null;
+          }),
+      );
+      validatorCache.set(branch, validator);
+      return validator;
+    };
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
       // THE choke point: every knowledge-base tool resolves its workspace
@@ -94,6 +125,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
+      // (The write validator below is built through `getWriteValidator`.)
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);
       const workspaceId = ws.id;
       const basePath = await deps.workspaceService.getWorkspacePath(workspaceId);
@@ -107,24 +139,10 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
                 branch: branchForWorkspaceId(workspaceId),
                 user,
                 kbDirName: deps.kbDirName,
-                // Reject an agent write that would leave roles.yaml unparseable
-                // (app-wide admin lockout) or that creates a role before it
-                // reaches disk, or that adds a `- group:` entry naming no group
-                // — the agent gets a tool error and the file is untouched.
-                // Agents manage membership; roles are pre-set.
-                validateWrite: makeAgentRolesYamlWriteValidator(
-                  deps.kbDirName,
-                  () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
-                  loadActiveGroups &&
-                    (async () => {
-                      // A source that exists but cannot be read leaves group
-                      // entries unchecked rather than refusing every one.
-                      const active = await loadActiveGroups((file) =>
-                        readTextIfExists(path.join(basePath, deps.kbDirName, file)),
-                      );
-                      return active.health.ok ? active : null;
-                    }),
-                ),
+                // The agent's pre-disk roles.yaml gate (`getWriteValidator`):
+                // the file tools and `update_branch`'s resolutions take the
+                // same one.
+                validateWrite: await getWriteValidator(branch),
                 creatorAccess: deps.creatorAccess,
               },
             )
@@ -155,6 +173,7 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
       workflowService: deps.workflowService,
       events: deps.events,
       getFilesystem,
+      getWriteValidator,
     };
   };
 }

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

@@ -2,6 +2,7 @@ import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared
 import type { LocalFilesystem } from '@mastra/core/workspace';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { WriteValidator } from '../kb-fs/index.js';
 
 /**
  * The hosting/execution contract a module works against when it lets `toolHelpers`
@@ -63,6 +64,13 @@ export interface ToolContext {
   events: WorkflowEventBus;
   /** Build the lock-aware filesystem for `branch`'s workspace (cached). The tool supplies `branch` from its own input. */
   getFilesystem(branch: string): Promise<LocalFilesystem>;
+  /**
+   * The agent's pre-disk write gate for `branch`'s workspace (cached) — the
+   * one the filesystem above runs before a byte lands (`roles.yaml`: must
+   * parse, no new role, no unknown group). A tool that writes content by
+   * another road than that filesystem (a merge resolution) takes it too.
+   */
+  getWriteValidator(branch: string): Promise<WriteValidator>;
 }
 
 /**

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

@@ -59,7 +59,7 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
     name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true),
+    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
   },
   {
     name: 'registerChangeRequestReadTools',

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

@@ -117,7 +117,7 @@ async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = em
     undefined,
     new WorkerPatternMatcher(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true);
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {

package/src/modules/workflow/__tests__/workflow.routes.history-read-gate.test.ts

@@ -41,7 +41,12 @@ async function makeHarness(): Promise<Harness> {
   const accessControl = { canRead, canReadAtRef } as unknown as IAccessControl;
   const workflow = {
     listChangesForFile: vi.fn(async () => []),
-    compareFile: vi.fn(async () => ''),
+    compareFile: vi.fn(async (_w: string, _p: string, from: string, to: string, authorize?: (s: { from: string[]; to: string[] }) => Promise<void>) => {
+      // Each branch resolves to its served commit and, for `b`, a second one (a
+      // local head past the published tip): the verdict is asked at both.
+      await authorize?.({ from: [`sha-of-${from}`], to: [`sha-of-${to}`, `other-sha-of-${to}`] });
+      return { diff: '', from: `sha-of-${from}`, to: `sha-of-${to}` };
+    }),
     showFileAtChange: vi.fn(async () => ''),
     fileAtChange: vi.fn(async () => ({ baseline: null, current: 'x' })),
   };
@@ -113,23 +118,29 @@ describe('history routes enforce the read model', () => {
     expect(h.workflow.listChangesForFile).not.toHaveBeenCalled();
   });
 
-  it('compare-file authorizes at every ref the comparison could serve', async () => {
-    // The comparison prefers a local ref (and the working tree) over
-    // `origin/<branch>`, so BOTH candidates are authorized per branch.
+  it('compare-file authorizes at the two commits the diff was served from, never at a ref', async () => {
+    // The diff is made first, pinned to the commit each side was read at,
+    // and authorized at those before any of it is answered: a branch ref a
+    // fetch moves meanwhile cannot have swapped in content the verdict never
+    // saw.
     h = await makeHarness();
     const res = await get(`/compare-file?from=a&to=b&path=${OPEN}`);
     expect(res.status).toBe(200);
     const refs = h.canReadAtRef.mock.calls.map((c) => c[1]).sort();
-    expect(refs).toEqual(['a', 'b', 'origin/a', 'origin/b']);
+    expect(refs).toEqual(['other-sha-of-b', 'sha-of-a', 'sha-of-b']);
 
-    // Any RESOLVABLE ref denying the read refuses the diff.
-    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === 'b' ? false : true));
-    expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
+    // Any commit a side resolves to denying the read refuses the diff — the
+    // served one or the other (a grant at the served commit never outruns a
+    // denial at the branch's other tip) — disclosing none of it.
+    for (const denying of ['sha-of-a', 'sha-of-b', 'other-sha-of-b']) {
+      h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === denying ? false : true));
+      const denied = await get(`/compare-file?from=a&to=b&path=${OPEN}`);
+      expect(denied.status, denying).toBe(403);
+      expect(await denied.json()).not.toHaveProperty('diff');
+    }
 
-    // A branch none of whose refs resolve cannot be authorized: refused.
-    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) =>
-      ref.endsWith('b') ? null : true,
-    );
+    // A commit whose rules cannot be read grants nothing: refused.
+    h.canReadAtRef.mockImplementation(async (_w: string, ref: string) => (ref === 'sha-of-b' ? null : true));
     expect((await get(`/compare-file?from=a&to=b&path=${OPEN}`)).status).toBe(403);
   });