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

package/dist/modules/mcp/request-context.d.ts

@@ -0,0 +1,25 @@
+import type { RequestAudit } from '../audit/index.js';
+/**
+ * What ONE MCP request brings to the tool client it runs on: the bearer its
+ * loopback calls carry, and the Audit log's view of it.
+ *
+ * The client is cached across requests (see {@link SurfaceCache}), so neither
+ * may live on the client. A connection-key request's loopback bearer is its
+ * own key — per-key metering rides on it, and a revoked key must stop working
+ * on its very next request even while the person's client is warm. An OAuth
+ * or session request's bearer is an internal token minted for that request,
+ * with a lifetime: baked into a cached client it would outlive nothing and
+ * expire under a page kept open for a day. So the client reads both from
+ * here, at call time, and a request supplies its own.
+ */
+export interface McpRequestContext {
+    /** The bearer this request's loopback calls carry (`${CONNECTION_KEY}` of every platform-hosted manual). */
+    loopbackBearer: string;
+    /** The request's Audit log view, or null when the request is attributed to nothing. */
+    audit: RequestAudit | null;
+}
+/** Run `fn` as part of the request `ctx`: every tool call it makes, however deep, reads `ctx`. */
+export declare function runInRequest<T>(ctx: McpRequestContext, fn: () => T): T;
+/** The request the current call belongs to, or undefined outside one. */
+export declare function currentRequest(): McpRequestContext | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/modules/mcp/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/request-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,4GAA4G;IAC5G,cAAc,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAID,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,IAAI,iBAAiB,GAAG,SAAS,CAE9D"}

package/dist/modules/mcp/request-context.js

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** Run `fn` as part of the request `ctx`: every tool call it makes, however deep, reads `ctx`. */
+export function runInRequest(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+/** The request the current call belongs to, or undefined outside one. */
+export function currentRequest() {
+    return storage.getStore();
+}
+//# sourceMappingURL=request-context.js.map

package/dist/modules/mcp/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../../src/modules/mcp/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAuBrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAqB,CAAC;AAE3D,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAI,GAAsB,EAAE,EAAW;IACjE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/modules/mcp/shared-definitions.d.ts

@@ -0,0 +1,56 @@
+import type { CallTemplate } 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 declare class SharedDefinitions {
+    private readonly maxEntries;
+    private readonly byContent;
+    private readonly interfaceCaches;
+    /** `maxEntries` bounds each map; 0 shares nothing. */
+    constructor(maxEntries?: number);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    share(client: CodeModeUtcpClient, rawTemplates: ReadonlyMap<string, CallTemplate>): Promise<void>;
+    /** The flattened catalog a surface lists, shared the same way. */
+    listing(tools: ProxiedTool[]): ProxiedTool[];
+    /** The generated-interface cache of one exact tool set. */
+    private interfaceCache;
+}
+//# sourceMappingURL=shared-definitions.d.ts.map

package/dist/modules/mcp/shared-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-definitions.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/shared-definitions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAiB;IAKhB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAE1E,sDAAsD;gBACzB,UAAU,SAAO;IAE9C;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;IAepC;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvG,kEAAkE;IAClE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;IAI5C,2DAA2D;IAC3D,OAAO,CAAC,cAAc;CAYvB"}

package/dist/modules/mcp/shared-definitions.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+/**
+ * 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 {
+    maxEntries;
+    byContent = new Map();
+    interfaceCaches = new Map();
+    /** `maxEntries` bounds each map; 0 shares nothing. */
+    constructor(maxEntries = 1000) {
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * 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(kind, value) {
+        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;
+        }
+        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, rawTemplates) {
+        const repo = client.config.tool_repository;
+        const templates = await repo.getManualCallTemplates();
+        const everyTool = [];
+        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 } : 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.toolFunctionCache = this.interfaceCache(fingerprint(everyTool));
+    }
+    /** The flattened catalog a surface lists, shared the same way. */
+    listing(tools) {
+        return this.intern('listing', tools);
+    }
+    /** The generated-interface cache of one exact tool set. */
+    interfaceCache(toolSet) {
+        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, maxEntries) {
+    while (map.size >= maxEntries) {
+        const oldest = map.keys().next().value;
+        if (oldest === undefined)
+            break;
+        map.delete(oldest);
+    }
+}
+function fingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+//# sourceMappingURL=shared-definitions.js.map

package/dist/modules/mcp/shared-definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-definitions.js","sourceRoot":"","sources":["../../../src/modules/mcp/shared-definitions.ts"],"names":[],"mappings":"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"}

package/dist/modules/mcp/surface-cache.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 declare const SURFACE_IDLE_TTL_MS: number;
+export declare const SURFACE_BUILD_TIMEOUT_MS: number;
+export declare const SURFACE_MAX_ENTRIES = 500;
+export declare class SurfaceCache<V> {
+    private readonly entries;
+    private readonly idleTtlMs;
+    private readonly maxEntries;
+    private readonly buildTimeoutMs;
+    private readonly now;
+    constructor(opts?: SurfaceCacheOptions);
+    /**
+     * 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.
+     */
+    get(key: string, build: () => Promise<V>, maxAgeMs?: (value: V) => number | undefined): Promise<{
+        value: V;
+        hit: boolean;
+    }>;
+    /** Drop every entry whose key matches. A build in flight still answers its waiters, and is not kept. */
+    evictWhere(predicate: (key: string) => boolean): void;
+    /** Drop everything. */
+    clear(): void;
+    private drop;
+    /** Remove `entry` only if it is still the one under `key` (a newer build may have taken its place). */
+    private forget;
+    /** 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;
+}
+//# sourceMappingURL=surface-cache.d.ts.map

package/dist/modules/mcp/surface-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-cache.d.ts","sourceRoot":"","sources":["../../../src/modules/mcp/surface-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAClD,eAAO,MAAM,wBAAwB,QAAgB,CAAC;AACtD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAavC,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,GAAE,mBAAwB;IAO1C;;;;;;;OAOG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,GAC1C,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,GAAG,EAAE,OAAO,CAAA;KAAE,CAAC;IAuCtC,wGAAwG;IACxG,UAAU,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IAMrD,uBAAuB;IACvB,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,IAAI;IAOZ,uGAAuG;IACvG,OAAO,CAAC,MAAM;IAId,8GAA8G;IAC9G,OAAO,CAAC,KAAK;CAUd"}

package/dist/modules/mcp/surface-cache.js

@@ -0,0 +1,104 @@
+export const SURFACE_IDLE_TTL_MS = 60 * 60 * 1000;
+export const SURFACE_BUILD_TIMEOUT_MS = 2 * 60 * 1000;
+export const SURFACE_MAX_ENTRIES = 500;
+export class SurfaceCache {
+    entries = new Map();
+    idleTtlMs;
+    maxEntries;
+    buildTimeoutMs;
+    now;
+    constructor(opts = {}) {
+        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, build, maxAgeMs) {
+        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 = {
+            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) {
+        for (const key of [...this.entries.keys()]) {
+            if (predicate(key))
+                this.drop(key);
+        }
+    }
+    /** Drop everything. */
+    clear() {
+        this.evictWhere(() => true);
+    }
+    drop(key) {
+        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). */
+    forget(key, entry) {
+        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. */
+    sweep() {
+        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);
+        }
+    }
+}
+//# sourceMappingURL=surface-cache.js.map

package/dist/modules/mcp/surface-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-cache.js","sourceRoot":"","sources":["../../../src/modules/mcp/surface-cache.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-helpers/tool-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAOxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAI1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,cAAc,CAAC;IAC9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CACjB,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAC/C,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,EAAE,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF;AAYD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB,CAuFnF"}
+{"version":3,"file":"tool-context.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAQxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAI1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,cAAc,CAAC;IAC9B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CACjB,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,KAC/C,OAAO,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE;YAAE,EAAE,EAAE,OAAO,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACpF;AAYD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,IAAI,EAAE,QAAQ,EACd,WAAW,EAAE,WAAW,EACxB,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,eAAe,GAAG,kBAAkB,CAyGnF"}

package/dist/modules/tool-helpers/tool-context.js

@@ -35,6 +35,33 @@ export function createToolContextResolver(deps) {
         if (!user)
             throw new ToolError('Your account is no longer available.', 401);
         const { loadActiveGroups } = deps;
+        const validatorCache = new Map();
+        /**
+         * 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) => {
+            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();
         const getFilesystem = async (branch) => {
             // THE choke point: every knowledge-base tool resolves its workspace
@@ -54,6 +81,7 @@ export function createToolContextResolver(deps) {
             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);
@@ -64,18 +92,10 @@ export function createToolContextResolver(deps) {
                     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,
                 })
                 : new ReadOnlyFilesystem({ basePath, contained: true });
@@ -104,6 +124,7 @@ export function createToolContextResolver(deps) {
             workflowService: deps.workflowService,
             events: deps.events,
             getFilesystem,
+            getWriteValidator,
         };
     };
 }

package/dist/modules/tool-helpers/tool-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EACL,gCAAgC,EAChC,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAI7C,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,EAAE,SAAS,EAAoB,MAAM,oBAAoB,CAAC;AA2BjE,+EAA+E;AAC/E,KAAK,UAAU,gBAAgB,CAAC,YAAoB;IAClD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,SAAS,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAChC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAQD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAqB;IAC7D,OAAO,KAAK,UAAU,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS;QACnE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,SAAS,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;QAE5E,MAAM,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;QACnD,MAAM,aAAa,GAAG,KAAK,EAAE,MAAc,EAA4B,EAAE;YACvE,oEAAoE;YACpE,yEAAyE;YACzE,yEAAyE;YACzE,yDAAyD;YACzD,EAAE;YACF,yEAAyE;YACzE,qEAAqE;YACrE,uEAAuE;YACvE,0EAA0E;YAC1E,0EAA0E;YAC1E,wEAAwE;YACxE,uEAAuE;YACvE,qCAAqC;YACrC,oBAAoB,CAAC,MAAM,CAAC,CAAC;YAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACnC,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAC1B,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACxE,MAAM,WAAW,GAAG,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;YAC3E,MAAM,EAAE,GACN,IAAI,CAAC,KAAK,KAAK,OAAO;gBACpB,CAAC,CAAC,IAAI,iBAAiB,CACnB,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,EAC7B;oBACE,QAAQ,EAAE,IAAI,CAAC,eAAe;oBAC9B,WAAW;oBACX,MAAM,EAAE,oBAAoB,CAAC,WAAW,CAAC;oBACzC,IAAI;oBACJ,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,gEAAgE;oBAChE,4DAA4D;oBAC5D,gEAAgE;oBAChE,2DAA2D;oBAC3D,+CAA+C;oBAC/C,aAAa,EAAE,gCAAgC,CAC7C,IAAI,CAAC,SAAS,EACd,GAAG,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC,EAChF,gBAAgB;wBACd,CAAC,KAAK,IAAI,EAAE;4BACV,uDAAuD;4BACvD,oDAAoD;4BACpD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE,CAC7C,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAC5D,CAAC;4BACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;wBAC1C,CAAC,CAAC,CACL;oBACD,aAAa,EAAE,IAAI,CAAC,aAAa;iBAClC,CACF;gBACH,CAAC,CAAC,IAAI,kBAAkB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACxB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QAEF,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,wEAAwE;YACxE,yEAAyE;YACzE,2EAA2E;YAC3E,0EAA0E;YAC1E,0EAA0E;YAC1E,SAAS,EAAE,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS;YACpF,sEAAsE;YACtE,0EAA0E;YAC1E,2EAA2E;YAC3E,4EAA4E;YAC5E,2DAA2D;YAC3D,aAAa,EAAE,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS;YAC1E,WAAW;YACX,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa;SACd,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool-context.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-helpers/tool.contract.d.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`
  * host its endpoint (`toolHandler`). It is NOT a registry concern — the registry
@@ -59,6 +60,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>;
 }
 /**
  * A tool's implementation: a pure function of `(args, ctx)`. Return a value for

package/dist/modules/tool-helpers/tool.contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAIxB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,wHAAwH;IACxH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAE/C;;;;;;;;GAQG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAF1C,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAK7C;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUtF"}
+{"version":3,"file":"tool.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAIxB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,eAAe,EAAE,gBAAgB,CAAC;IAClC,MAAM,EAAE,gBAAgB,CAAC;IACzB,wHAAwH;IACxH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACxD;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5D;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAE/C;;;;;;;;GAQG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAGhC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAF1C,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAK7C;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUtF"}

package/dist/modules/tool-helpers/tool.contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AA8EA;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGvB;IACA;IAHX,YACE,OAAe,EACN,MAAc,EACd,OAAiC;QAE1C,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAA0B;QAG1C,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,MAAM,GAAI,GAA4B,CAAC,MAAM,CAAC;IACpD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACxB,MAAM,IAAI,GAAG;QACb,MAAM,IAAI,GAAG;QACb,OAAQ,GAA6B,CAAC,OAAO,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool.contract.js","sourceRoot":"","sources":["../../../src/modules/tool-helpers/tool.contract.ts"],"names":[],"mappings":"AAsFA;;;;;;;;GAQG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGvB;IACA;IAHX,YACE,OAAe,EACN,MAAc,EACd,OAAiC;QAE1C,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAA0B;QAG1C,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,MAAM,GAAI,GAA4B,CAAC,MAAM,CAAC;IACpD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACxB,MAAM,IAAI,GAAG;QACb,MAAM,IAAI,GAAG;QACb,OAAQ,GAA6B,CAAC,OAAO,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

package/dist/modules/workflow/agent-tools/change-request-read.tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-request-read.tools.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/agent-tools/change-request-read.tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAEV,mBAAmB,EAGpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,sCAAsC,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAoB,MAAM,qCAAqC,CAAC;AAEpG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAsB/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,kBAAkB,EAC/B,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACxD,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,GACxC,IAAI,CA0fN;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,2EAA2E;IAC3E,aAAa,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACxD,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC;iCAOC,WAAW,KAAG,OAAO,CAAC,MAAM,CAAC;yBAUhE,WAAW,eACH,MAAM,QACb,MAAM,SACL,MAAM,EAAE,KACd,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;wBAahB,WAAW,UACR,MAAM,QACR;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KACzB,OAAO,CAAC,YAAY,CAAC;uBA8CE,MAAM,KAAG,SAAS;kBAIjB,WAAW,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EAW1E"}
+{"version":3,"file":"change-request-read.tools.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/agent-tools/change-request-read.tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAEV,mBAAmB,EAGpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,sCAAsC,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAoB,MAAM,qCAAqC,CAAC;AAEpG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAuB/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,kBAAkB,EAC/B,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACxD,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,GACxC,IAAI,CA0fN;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,2EAA2E;IAC3E,aAAa,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EACxD,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC;iCAOC,WAAW,KAAG,OAAO,CAAC,MAAM,CAAC;yBAI3C,WAAW,eAAe,MAAM,QAAQ,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;wBAI3G,WAAW,UACR,MAAM,QACR;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,KACzB,OAAO,CAAC,YAAY,CAAC;uBA8CE,MAAM,KAAG,SAAS;kBAIjB,WAAW,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;EAW1E"}

package/dist/modules/workflow/agent-tools/change-request-read.tools.js

@@ -1,5 +1,6 @@
 import { ToolError } from '../../tool-helpers/tool.contract.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
+import { readablePathsAt } from '../read-on-branch.js';
 import { PER_PAGE_DEFAULT, PER_PAGE_MAX, fileIsReadable, isAuthor, matchesAuthor, pathsOf, maySeeChangeRequest, pageOf, pagingOf, statesFor, toCrComment, toCrDetail, toCrFile, toCrReviews, toCrSummary, toCrViewer, visibleBlockers, visibleComments, } from './change-request-read-shape.js';
 /**
  * The five read tools over change requests, named and shaped after GitHub's
@@ -533,20 +534,8 @@ export function changeRequestScope(accessControl, kb) {
      * identically — reusing one avoids cloning a branch just to read a ref.
      */
     const repoGlobalWorkspaceId = async (ctx) => (await ctx.workspaceService.findAnyWorkspaceId()) ?? kb.defaultWorkspaceId();
-    /**
-     * Read verdicts for `paths` at `origin/<base>`, as a membership set of what
-     * the caller MAY read. A null answer (the ref or its `roles.yaml` does not
-     * resolve) withholds everything, which is the same reading the app's
-     * fork-point route gives it.
-     */
-    const readablePaths = async (ctx, workspaceId, base, paths) => {
-        if (paths.length === 0)
-            return new Set();
-        const verdicts = await accessControl.canReadBatchAtRef(workspaceId, `origin/${base}`, ctx.user.email, [...new Set(paths)]);
-        if (!verdicts)
-            return new Set();
-        return new Set([...verdicts].filter(([, allowed]) => allowed).map(([p]) => p));
-    };
+    /** What the caller MAY read of `paths` at `origin/<base>` — the one rule, `readablePathsAt`. */
+    const readablePaths = (ctx, workspaceId, base, paths) => readablePathsAt(accessControl, workspaceId, ctx.user.email, base, paths);
     const scopedDetail = async (ctx, number, opts) => {
         const workspaceId = await repoGlobalWorkspaceId(ctx);
         const detail = await ctx.workflowService.getChangeRequestDetail(number, {