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

package/dist/modules/tool-manuals/tool-manuals.service.d.ts

@@ -7,7 +7,7 @@ import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/index.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
-import { type IToolManualService, type ToolManualDescriptor, type ToolManualSummary, type ToolManualDetail, type AccessibleCatalog, type UtcpManualDict, type ToolManualPreview, type ToolManualType, type ToolProbeTarget, type ToolVariableScope } from './tool-manuals.contract.js';
+import { type IToolManualService, type ConnectorScope, type ToolManualDescriptor, type ToolManualSummary, type ToolManualDetail, type AccessibleCatalog, type UtcpManualDict, type ToolManualPreview, type ToolManualType, type ToolProbeTarget, type ToolVariableScope, type LiveDeclaration } from './tool-manuals.contract.js';
 /**
  * Why one `.tool` was refused, in a form safe to hand an agent, a browser and a
  * log — the `reason` of an {@link InvalidToolManual}.
@@ -64,8 +64,8 @@ export interface McpAuthDiscoveryPort {
     /**
      * The sign-in endpoints for an OWNER-REGISTERED client: the same metadata
      * walk as `statusFor`, stopping short of dynamic registration — the manual
-     * already names its `clientId`. Nothing is persisted; the owner's
-     * client-secret save pins the completed provider. Optional so a port that
+     * already names its `clientId`. Nothing is persisted; every sign-in start
+     * completes the declaration afresh (`liveDeclaration`). Optional so a port that
      * only knows the zero-config path still satisfies the interface.
      */
     providerForDeclaredClient?(manualName: string, mcpUrl: string, clientId: string): Promise<McpAuthDiscoveryResult>;
@@ -140,16 +140,17 @@ export declare class ToolManualService implements IToolManualService {
     setHiddenTools(source: HiddenToolSource): void;
     invalidate(): void;
     listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
-    listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog>;
+    listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog>;
     listAllSummaries(): Promise<ToolManualSummary[]>;
-    catalogFingerprints(userEmail: string): Promise<string[]>;
+    catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]>;
     getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
-    listLocalOnly(userEmail: string): Promise<{
+    liveDeclaration(userEmail: string, slug: string, varName: string): Promise<LiveDeclaration | null>;
+    listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{
         slug: string;
         name: string;
         path: string;
     }[]>;
-    listDeclaredOnlyOnBranch(userEmail: string, branch: string): Promise<{
+    listDeclaredOnlyOnBranch(userEmail: string, branch: string, within?: ConnectorScope): Promise<{
         name: string;
         path: string;
         type: ToolManualType;
@@ -172,8 +173,11 @@ export declare class ToolManualService implements IToolManualService {
     probeTargetFor(userEmail: string, slug: string): Promise<ToolProbeTarget | null>;
     toManualCallTemplates(userEmail: string, opts?: {
         remoteOnly?: boolean;
+        within?: ConnectorScope;
     }): Promise<CallTemplate[]>;
-    resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null>;
+    resolveInlineManual(userEmail: string, slug: string, opts?: {
+        within?: ConnectorScope;
+    }): Promise<UtcpManualDict | null>;
     preview(content: string): Promise<ToolManualPreview>;
     /** Build the raw UTCP manual call-template dict for one descriptor (validated by the caller). */
     private buildCallTemplateDict;
@@ -183,8 +187,14 @@ export declare class ToolManualService implements IToolManualService {
      * ONE `canReadBatch`. Both halves are paths in the same workspace judged by
      * the same rule, and splitting them into two calls would pay a second
      * round-trip to ask the same question.
+     *
+     * `within` narrows the answer to a connection's connectors, AFTER the read
+     * gate: it can take a manual out of what the caller may read, never put one
+     * in. Absent, the answer is the caller's whole readable catalog.
      */
     private accessibleScan;
+    /** A scan cut to what this caller may read — see {@link accessibleScan}. */
+    private readableBy;
     private scan;
     private runScan;
     /**
@@ -221,11 +231,12 @@ export declare class ToolManualService implements IToolManualService {
      * (the owner registered an app with a provider that offers no dynamic
      * registration — HubSpot, Google) gets its endpoints, PKCE and resource
      * indicator from the server's own OAuth metadata, exactly as the zero-config
-     * path would. The descriptor is completed IN MEMORY: the client-secret route
-     * reads the completed declaration and pins it with the secret, so nothing
-     * here persists. When the metadata can't be had, the declaration stays
-     * incomplete and `setup.reason` says so — the secret route then refuses
-     * with the same reason instead of pinning a provider with no endpoints.
+     * path would. The descriptor is completed IN MEMORY, for the catalog's scan
+     * and for every sign-in start (`liveDeclaration`) alike, so nothing here
+     * persists. When the metadata can't be had, the declaration stays
+     * incomplete and `setup.reason` says so — the client-secret save and the
+     * sign-in start then refuse with the same reason instead of running a
+     * provider with no endpoints.
      */
     private completeDeclaredOAuth;
     /**

package/dist/modules/tool-manuals/tool-manuals.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-manuals.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-manuals.service.d.ts","sourceRoot":"","sources":["../../../src/modules/tool-manuals/tool-manuals.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/tool-manuals/tool-manuals.service.js

@@ -132,7 +132,7 @@ export function describeManualFault(err) {
  * convention instance is one push away from every empty scan in the process
  * inheriting another's contents.
  */
-const emptyScan = () => ({ manuals: [], invalid: [] });
+const emptyScan = () => ({ manuals: [], invalid: [], refused: [] });
 const manualSerializer = new UtcpManualSerializer();
 const callTemplateSerializer = new CallTemplateSerializer();
 // `findRequiredVariables` is a pure walk — one shared instance is fine.
@@ -208,15 +208,15 @@ export class ToolManualService {
     async listAccessible(userEmail) {
         return (await this.accessibleManuals(userEmail)).map(toSummary);
     }
-    async listAccessibleCatalog(userEmail) {
-        const { manuals, invalid } = await this.accessibleScan(userEmail);
+    async listAccessibleCatalog(userEmail, within) {
+        const { manuals, invalid } = await this.accessibleScan(userEmail, within);
         return { tools: manuals.map(toSummary), invalid };
     }
     async listAllSummaries() {
         return (await this.scan()).manuals.map(toSummary);
     }
-    async catalogFingerprints(userEmail) {
-        return (await this.accessibleManuals(userEmail)).map(manualFingerprint);
+    async catalogFingerprints(userEmail, within) {
+        return (await this.accessibleManuals(userEmail, within)).map(manualFingerprint);
     }
     async getDetail(userEmail, slug) {
         // Resolved through `accessibleManuals` rather than `scan()` + a canRead call
@@ -241,11 +241,39 @@ export class ToolManualService {
             hiddenTools: mayManage ? hidden : [],
         };
     }
-    async listLocalOnly(userEmail) {
-        const manuals = await this.accessibleManuals(userEmail);
+    async liveDeclaration(userEmail, slug, varName) {
+        // The disk walk the catalog's scan is built from, run afresh and never
+        // cached: a sign-in must follow the file as it is, and the catalog's scan
+        // can be a refresh behind it. The whole walk rather than the one file, so
+        // the descriptor comes out of exactly the parse, plugin discovery and
+        // namespace dedup the catalog applies — a sign-in start is rare and
+        // interactive, and a second, single-file reading of the same files is a
+        // second place for those rules to drift. A workspace that cannot be opened
+        // is an error here, never an empty answer: "no sign-in declared" would be
+        // the wrong diagnosis for a server that could not read its files.
+        const { manuals, refused } = await this.readableBy(await this.scanDisk(undefined, 'throw'), userEmail);
+        const m = manuals.find((x) => x.slug === slug);
+        if (!m) {
+            // The file is there and says it is this manual, but the parse refused
+            // it — e.g. its sign-in names an http:// or private token endpoint. That
+            // reason is the answer; "not found" would hide the one thing to fix.
+            const r = refused.find((x) => x.slug === slug);
+            return r ? { refused: r.reason } : null;
+        }
+        const variable = (m.variables ?? []).find((v) => v.name === varName);
+        // Completed by the catalog's own decoration, on this one fresh descriptor.
+        // Only when THIS variable is a sign-in: then the manual has a declared one,
+        // so the pass completes its endpoints from the server's metadata and never
+        // probes for (or registers) a zero-config client.
+        if (variable?.oauth)
+            await this.decorateMcpOAuth([m]);
+        return { manual: toSummary(m), ...(variable ? { variable } : {}) };
+    }
+    async listLocalOnly(userEmail, within) {
+        const manuals = await this.accessibleManuals(userEmail, within);
         return manuals.filter((m) => m.remote === false).map((m) => ({ slug: m.slug, name: m.name, path: m.path }));
     }
-    async listDeclaredOnlyOnBranch(userEmail, branch) {
+    async listDeclaredOnlyOnBranch(userEmail, branch, within) {
         if (!branch || branch === this.kb.defaultBranch)
             return [];
         // Only a draft this process already holds a clone of — the one the caller
@@ -273,7 +301,7 @@ export class ToolManualService {
         // the caller could not open with `read_file`.
         const allowed = await this.accessControl.canReadBatch(workspaceIdForBranch(branch), userEmail, pending.map((m) => m.path));
         return pending
-            .filter((m) => allowed.get(m.path) === true)
+            .filter((m) => allowed.get(m.path) === true && (within === undefined || within(m.path)))
             .map((m) => ({ name: m.name, path: m.path, type: m.type }));
     }
     async userScopedKeysForManual(manualName) {
@@ -348,7 +376,7 @@ export class ToolManualService {
         return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
     }
     async toManualCallTemplates(userEmail, opts) {
-        const manuals = await this.accessibleManuals(userEmail);
+        const manuals = await this.accessibleManuals(userEmail, opts?.within);
         const out = [];
         for (const m of manuals) {
             // Remote consumers (the hosted MCP proxy) don't get local-only manuals —
@@ -366,13 +394,16 @@ export class ToolManualService {
         }
         return out;
     }
-    async resolveInlineManual(userEmail, slug) {
+    async resolveInlineManual(userEmail, slug, opts) {
         const found = (await this.scan()).manuals.find((m) => m.slug === slug);
         if (!found || found.type !== 'inline')
             return null;
         const wsId = this.kb.defaultWorkspaceId();
         if (!(await this.accessControl.canRead(wsId, userEmail, found.path)))
             return null;
+        // After the read gate, as every narrowing is: a connection's scope can only take away.
+        if (opts?.within && !opts.within(found.path))
+            return null;
         try {
             return manualSerializer.validateDict({
                 utcp_version: '1.1.0',
@@ -484,31 +515,41 @@ export class ToolManualService {
             ...(m.headers ? { headers: m.headers } : {}),
         };
     }
-    async accessibleManuals(userEmail) {
-        return (await this.accessibleScan(userEmail)).manuals;
+    async accessibleManuals(userEmail, within) {
+        return (await this.accessibleScan(userEmail, within)).manuals;
     }
     /**
      * The scan cut to what this caller may read — manuals AND refusals, through
      * ONE `canReadBatch`. Both halves are paths in the same workspace judged by
      * the same rule, and splitting them into two calls would pay a second
      * round-trip to ask the same question.
+     *
+     * `within` narrows the answer to a connection's connectors, AFTER the read
+     * gate: it can take a manual out of what the caller may read, never put one
+     * in. Absent, the answer is the caller's whole readable catalog.
      */
-    async accessibleScan(userEmail) {
-        const { manuals, invalid } = await this.scan();
-        if (manuals.length === 0 && invalid.length === 0)
+    async accessibleScan(userEmail, within) {
+        return this.readableBy(await this.scan(), userEmail, within);
+    }
+    /** A scan cut to what this caller may read — see {@link accessibleScan}. */
+    async readableBy(scan, userEmail, within) {
+        const { manuals, invalid, refused } = scan;
+        if (manuals.length === 0 && invalid.length === 0 && refused.length === 0)
             return emptyScan();
         const wsId = this.kb.defaultWorkspaceId();
         const allowed = await this.accessControl.canReadBatch(wsId, userEmail, [
-            ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path)]),
+            ...new Set([...manuals.map((m) => m.path), ...invalid.map((i) => i.path), ...refused.map((r) => r.path)]),
         ]);
         // Fail closed: keep an entry only on an explicit `true` verdict (a missing
         // entry is treated as denied, matching the KB's default-deny read model).
         // A REFUSED file is gated the same way a listed one is: its path is a fact
         // about the knowledge base, and "there is a broken tool at this path" is
         // not something to tell someone who may not read that path.
+        const inScope = (p) => allowed.get(p) === true && (within === undefined || within(p));
         return {
-            manuals: manuals.filter((m) => allowed.get(m.path) === true),
-            invalid: invalid.filter((i) => allowed.get(i.path) === true),
+            manuals: manuals.filter((m) => inScope(m.path)),
+            invalid: invalid.filter((i) => inScope(i.path)),
+            refused: refused.filter((r) => inScope(r.path)),
         };
     }
     async scan() {
@@ -534,15 +575,15 @@ export class ToolManualService {
         // See `TtlCache.begin`: taken before the read so an `invalidate()` that
         // lands mid-scan discards this result instead of being overwritten by it.
         const token = this.cache.begin();
-        const { manuals, invalid } = await this.scanDisk();
+        const scanned = await this.scanDisk();
+        const { manuals } = scanned;
         await this.decorateMcpOAuth(manuals);
         // AFTER the oauth decoration, so an injected `${MCP_OAUTH}` header ref is
         // already declared and isn't re-surfaced as a bare admin key.
         for (const m of manuals)
             this.surfaceReferencedVariables(m);
-        const result = { manuals, invalid };
-        this.cache.set(result, token);
-        return result;
+        this.cache.set(scanned, token);
+        return scanned;
     }
     /**
      * Say what the scan refused — once per CHANGE, not once per scan. Every
@@ -713,11 +754,12 @@ export class ToolManualService {
      * (the owner registered an app with a provider that offers no dynamic
      * registration — HubSpot, Google) gets its endpoints, PKCE and resource
      * indicator from the server's own OAuth metadata, exactly as the zero-config
-     * path would. The descriptor is completed IN MEMORY: the client-secret route
-     * reads the completed declaration and pins it with the secret, so nothing
-     * here persists. When the metadata can't be had, the declaration stays
-     * incomplete and `setup.reason` says so — the secret route then refuses
-     * with the same reason instead of pinning a provider with no endpoints.
+     * path would. The descriptor is completed IN MEMORY, for the catalog's scan
+     * and for every sign-in start (`liveDeclaration`) alike, so nothing here
+     * persists. When the metadata can't be had, the declaration stays
+     * incomplete and `setup.reason` says so — the client-secret save and the
+     * sign-in start then refuse with the same reason instead of running a
+     * provider with no endpoints.
      */
     async completeDeclaredOAuth(discovery, m, v) {
         const declaredByHand = 'declare `authorizationUrl` and `tokenUrl` on the sign-in variable';
@@ -771,12 +813,22 @@ export class ToolManualService {
      * calls: a refusal lives only in the scan it came from, so a fixed file is a
      * valid manual on the very next scan.
      */
-    async scanDisk(branch = this.kb.defaultBranch) {
+    async scanDisk(branch = this.kb.defaultBranch, 
+    /**
+     * What a workspace that cannot be opened means. For the catalog, an empty
+     * scan: a listing surface answers "nothing released" and the next scan
+     * tries again. For a sign-in start (`liveDeclaration`), the error itself:
+     * an empty answer there would read as "this tool has no sign-in", a
+     * misconfiguration, when the server could not read its files at all.
+     */
+    workspaceFailure = 'empty') {
         let wsId;
         try {
             wsId = (await this.workspaceService.getOrCreateForBranch(branch)).id;
         }
-        catch {
+        catch (err) {
+            if (workspaceFailure === 'throw')
+                throw err;
             return emptyScan();
         }
         const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
@@ -795,6 +847,7 @@ export class ToolManualService {
         // The plugins (and their mcp.json text) come from the configured source, so
         // a dialect that expands servers from a registry lands here unchanged.
         const parsed = [];
+        const refused = [];
         const discovered = await this.source.discover(kbRoot);
         for (const plugin of discovered.plugins) {
             if (plugin.mcpJsonText === null)
@@ -804,7 +857,8 @@ export class ToolManualService {
             // (a URL, a header, an added or dropped server, a `local: true` flip)
             // moves every server's digest — which is correct, if slightly generous.
             const from = sourceDigest(plugin.mcpJsonText + '\u0000' + (plugin.manifestText ?? ''));
-            for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText, layout)) {
+            const onRefused = (slug, reason, path) => refused.push({ slug, path, reason: describeManualFault(reason) });
+            for (const d of descriptorsFromMcpJson(plugin.relFolder, plugin.mcpJsonText, plugin.manifestText, layout, onRefused)) {
                 d.sourceRevision = from;
                 parsed.push(d);
             }
@@ -841,6 +895,9 @@ export class ToolManualService {
                 // outage from where the author stands: the tool is gone from every
                 // listing, with nothing anywhere saying which file or why.
                 invalid.push({ path: f.rel, reason: describeManualFault(err) });
+                const slug = refusedToolManualName(baseName(f.rel), content);
+                if (slug !== null)
+                    refused.push({ slug, path: f.rel, reason: describeManualFault(err) });
                 continue;
             }
             // The route slug IS the id (unique after dedup below, snake_case → URL-safe),
@@ -888,7 +945,7 @@ export class ToolManualService {
         // served catalog — it would also flap the log every time an agent saves.
         if (branch === this.kb.defaultBranch)
             this.logInvalidOnChange(invalid);
-        return { manuals, invalid };
+        return { manuals, invalid, refused };
     }
 }
 // --- helpers ------------------------------------------------------------------
@@ -997,6 +1054,53 @@ function manualName(raw) {
         return `tool${name}`;
     return name;
 }
+/**
+ * The object a `.tool` file holds: its `---` block when fenced, the whole file
+ * when not. Throws when that is not an object.
+ */
+function toolFileObject(content) {
+    const fm = extractFrontmatter(content);
+    const source = fm ? fm.frontmatter : content;
+    const parsed = parseYaml(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('`.tool` file must be a YAML/JSON object (in the `---` block when fenced)');
+    }
+    return parsed;
+}
+/**
+ * A `.tool`'s manual name — its UTCP namespace, and the slug the scan serves it
+ * under. An explicit `id` is used VERBATIM, so it must be lowercase snake_case
+ * (UTCP's namespace grammar). With no explicit id, fall back to `name` then the
+ * filename and sanitize (legacy behaviour — keeps existing tools' namespaces).
+ */
+function toolManualName(obj, provisionalSlug) {
+    const explicitId = typeof obj.id === 'string' ? obj.id.trim() : '';
+    if (!explicitId)
+        return manualName(resolveDeclaredId(obj, provisionalSlug));
+    if (!isValidId(explicitId)) {
+        // The rejected id is NOT quoted back — see `describeManualFault`: this
+        // message becomes an `invalid[].reason` on an agent transcript, a browser
+        // and a log, and `id` is a field an author can paste anything into,
+        // including the token they meant for a header. The field name plus the
+        // rule is what the author needs; the value is in front of them.
+        throw new Error('tool `id` must be lowercase snake_case (letters, digits, underscores)');
+    }
+    return explicitId;
+}
+/**
+ * The manual name of a `.tool` the parser REFUSED, when the file still says
+ * which manual it is — by the same rule {@link normalizeToolManual} names a
+ * manual it accepts. `null` when even that cannot be read (unparseable YAML,
+ * a malformed `id`): then nothing can claim the refusal by name.
+ */
+function refusedToolManualName(provisionalSlug, content) {
+    try {
+        return toolManualName(toolFileObject(content), provisionalSlug);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Parse + normalize a `.tool` file into a descriptor. THE TOOL IS THE
  * FRONTMATTER: a fenced file's single `---` YAML block carries everything —
@@ -1016,34 +1120,9 @@ export function normalizeToolManual(provisionalSlug, repoPath, content) {
     // finds its verbs inside the fence, the id index finds `id`/`name`, and the
     // config keys live in the same object. A fence-less file is the legacy form
     // (the whole file is the object) — JSON `.tool`s can't carry fences.
-    const fm = extractFrontmatter(content);
-    const source = fm ? fm.frontmatter : content;
-    const parsed = parseYaml(source);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('`.tool` file must be a YAML/JSON object (in the `---` block when fenced)');
-    }
-    const obj = parsed;
+    const obj = toolFileObject(content);
     const type = normalizeType(obj.type);
-    // Identity: an explicit `id` is used VERBATIM as the UTCP manual namespace, so
-    // it must be lowercase snake_case (UTCP's namespace grammar). With no explicit
-    // id, fall back to `name` then the filename and sanitize (legacy behaviour —
-    // keeps existing tools' namespaces).
-    const explicitId = typeof obj.id === 'string' ? obj.id.trim() : '';
-    let name;
-    if (explicitId) {
-        if (!isValidId(explicitId)) {
-            // The rejected id is NOT quoted back — see `describeManualFault`: this
-            // message becomes an `invalid[].reason` on an agent transcript, a browser
-            // and a log, and `id` is a field an author can paste anything into,
-            // including the token they meant for a header. The field name plus the
-            // rule is what the author needs; the value is in front of them.
-            throw new Error('tool `id` must be lowercase snake_case (letters, digits, underscores)');
-        }
-        name = explicitId;
-    }
-    else {
-        name = manualName(resolveDeclaredId(obj, provisionalSlug));
-    }
+    const name = toolManualName(obj, provisionalSlug);
     // A `.tool` may not reproduce a built-in manual's UTCP namespace — that would
     // let it read the loopback creds seeded under that namespace on the agent's
     // code-mode client (internal token, connector creds, KB bearer).