@bevel-software/platform-core-backend 0.34.0 → 0.36.1

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

@@ -46,7 +46,12 @@ export interface ToolVariableOAuth {
     /** Absent on an mcp.json server ⇒ discovered from the server's OAuth metadata. */
     authorizationUrl?: string;
     tokenUrl?: string;
-    clientId: string;
+    /**
+     * Required on an ordinary sign-in. Absent ONLY on a managed one (see
+     * `managed`), whose client is Bevel's and lives on the broker; an owner who
+     * brings their own app supplies it on the client-secret route instead.
+     */
+    clientId?: string;
     scopes?: string[];
     /**
      * Extra static query params appended to the authorization request — e.g.
@@ -71,6 +76,20 @@ export interface ToolVariableOAuth {
      * endpoints are declared by hand too.
      */
     resource?: string;
+    /**
+     * The sign-in goes through Bevel's managed OAuth app for a platform
+     * connector: the broker does the provider round-trip and hands the tokens
+     * to this deployment, and renews them on its behalf. Written by the
+     * connector template an admin enables; `clientId` is then absent. The
+     * broker decides the scopes it requests from its own copy of the
+     * connector's definition, so an edited file cannot widen them.
+     */
+    managed?: ManagedSignIn;
+}
+/** Which managed connector and scope set a sign-in belongs to. */
+export interface ManagedSignIn {
+    connectorId: string;
+    scopeSet: string;
 }
 /**
  * A `${VAR}` a `.tool` manual references, and who provisions its secret:
@@ -86,8 +105,11 @@ export interface ToolVariable {
     label?: string;
     /**
      * When present, this variable is OAuth-backed: the user signs in with the
-     * declared provider to obtain a token. Only valid with `scope:'user'` (each
-     * caller authorizes their own). The client secret is NOT declared here.
+     * declared provider to obtain a token. Valid with `scope:'user'` (each
+     * caller authorizes their own), or with `scope:'admin'` ONLY for a managed
+     * sign-in — one workspace connection an owner makes, read by every caller
+     * (the shared row then holds the tokens). The client secret is NOT
+     * declared here.
      */
     oauth?: ToolVariableOAuth;
 }
@@ -348,6 +370,16 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
  * whole readable catalog.
  */
 export type ConnectorScope = (definitionPath: string) => boolean;
+/** A manual as its file reads now — see {@link IToolManualService.liveDeclaration}. */
+export type LiveDeclaration = {
+    manual: ToolManualSummary;
+    variable?: ToolVariable;
+    refused?: undefined;
+} | {
+    refused: string;
+    manual?: undefined;
+    variable?: undefined;
+};
 export interface IToolManualService {
     /** The `.tool` manuals the user can read, as summaries. */
     listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
@@ -377,6 +409,23 @@ export interface IToolManualService {
      * confirm that a tool the caller can't see exists).
      */
     getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+    /**
+     * One manual's declaration as its file reads on the default branch NOW, for a
+     * sign-in about to start: the files are parsed afresh, never served from the
+     * catalog's cached scan, so an edit made seconds ago is already what this
+     * answers. A sign-in variable that names only its `clientId` is completed from
+     * the server's OAuth metadata by the same walk the catalog completes it with;
+     * when that fails, the endpoints stay absent and `manual.setup.reason` says why.
+     *
+     * `refused` when the file declaring this slug is one the parse refuses as it
+     * reads now (an endpoint failing the https/SSRF check, say): the parser's
+     * reason, so the sign-in can say why instead of finding nothing. `null` when
+     * no readable manual has this slug (fail-closed, like {@link getDetail});
+     * `variable` absent when the file declares no variable of that name. Nothing
+     * the platform synthesises from discovery (the zero-config sign-in variable)
+     * is in the answer: it is not in any file.
+     */
+    liveDeclaration(userEmail: string, slug: string, varName: string): Promise<LiveDeclaration | null>;
     /**
      * Wire where a hidden tool's schema finding comes from (the MCP proxy, which
      * is constructed after this service — setter injection for the same reason
@@ -494,6 +543,24 @@ export interface IToolManualService {
         oauth: boolean;
         oauthScopes?: string[];
     }[]>;
+    /**
+     * The SHARED (`admin`-scoped) sign-ins a manual declares — a managed
+     * connector enabled as a workspace connection. The pre-call check reads
+     * these so a tool whose one connection nobody has made yet is reported as
+     * missing its sign-in, labelled "(a tool owner connects this for the
+     * workspace)", instead of failing opaquely at the provider.
+     *
+     * `key` is the vault key as UTCP derives it (`utcpNamespacedKey`): the
+     * manual's name with every non-word character made `_` and every `_` then
+     * doubled, an `_`, and the variable's name (`my-tool` + `ACCESS_TOKEN` →
+     * `my__tool_ACCESS_TOKEN`). Read it from here; never compose it by hand.
+     */
+    sharedSignInKeysForManual(manualName: string): Promise<{
+        key: string;
+        name: string;
+        label: string | null;
+        oauthScopes?: string[];
+    }[]>;
     /** Drop the cached catalog (call after a merge to the default branch). */
     invalidate(): void;
 }

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

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

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 ConnectorScope, 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>;
@@ -144,6 +144,7 @@ export declare class ToolManualService implements IToolManualService {
     listAllSummaries(): Promise<ToolManualSummary[]>;
     catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]>;
     getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+    liveDeclaration(userEmail: string, slug: string, varName: string): Promise<LiveDeclaration | null>;
     listLocalOnly(userEmail: string, within?: ConnectorScope): Promise<{
         slug: string;
         name: string;
@@ -161,6 +162,12 @@ export declare class ToolManualService implements IToolManualService {
         oauth: boolean;
         oauthScopes?: string[];
     }[]>;
+    sharedSignInKeysForManual(manualName: string): Promise<{
+        key: string;
+        name: string;
+        label: string | null;
+        oauthScopes?: string[];
+    }[]>;
     scopeOfVariable(effectiveKey: string): Promise<ToolVariableScope>;
     /**
      * The probe config for a manual this caller can read — the internal
@@ -192,6 +199,8 @@ export declare class ToolManualService implements IToolManualService {
      * 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;
     /**
@@ -228,11 +237,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.
@@ -241,6 +241,34 @@ export class ToolManualService {
             hiddenTools: mayManage ? hidden : [],
         };
     }
+    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 }));
@@ -296,6 +324,17 @@ export class ToolManualService {
             oauthScopes: v.oauth?.scopes,
         }));
     }
+    async sharedSignInKeysForManual(manualName) {
+        const manual = (await this.scan()).manuals.find((m) => m.name === manualName);
+        return (manual?.variables ?? [])
+            .filter((v) => v.scope === 'admin' && v.oauth != null)
+            .map((v) => ({
+            key: utcpNamespacedKey(manualName, v.name),
+            name: v.name,
+            label: v.label ?? null,
+            oauthScopes: v.oauth?.scopes,
+        }));
+    }
     async scopeOfVariable(effectiveKey) {
         // UTCP looks up `<namespace-with-doubled-underscores>_<VAR>`. Find the manual
         // whose namespace prefixes this key; the declared var is the remainder. Match
@@ -501,12 +540,16 @@ export class ToolManualService {
      * in. Absent, the answer is the caller's whole readable catalog.
      */
     async accessibleScan(userEmail, within) {
-        const { manuals, invalid } = await this.scan();
-        if (manuals.length === 0 && invalid.length === 0)
+        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).
@@ -517,6 +560,7 @@ export class ToolManualService {
         return {
             manuals: manuals.filter((m) => inScope(m.path)),
             invalid: invalid.filter((i) => inScope(i.path)),
+            refused: refused.filter((r) => inScope(r.path)),
         };
     }
     async scan() {
@@ -542,15 +586,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
@@ -638,6 +682,11 @@ export class ToolManualService {
                 continue;
             const oauthVar = (m.variables ?? []).find((v) => v.oauth != null);
             if (oauthVar) {
+                // A MANAGED sign-in has nothing for an owner to set up here: its
+                // client is the broker's, its endpoints are in the file. No setup
+                // kind, so no surface asks for a client secret it does not need.
+                if (oauthVar.oauth?.managed)
+                    continue;
                 // An owner-registered client is `oauth-manual` by definition — whether
                 // the declaration is complete or still needs its endpoints discovered.
                 // Explicit wins over discovery: never registered over, never probed
@@ -721,11 +770,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';
@@ -740,8 +790,15 @@ export class ToolManualService {
             m.setup = { kind: 'oauth-manual', reason: `sign-in endpoint discovery is unavailable — ${declaredByHand}` };
             return;
         }
+        // A file-declared sign-in carries its client id unless it is managed, and
+        // a managed one has nothing to discover: its endpoints are in the file.
+        const clientId = v.oauth?.clientId;
+        if (!clientId) {
+            m.setup = { kind: 'oauth-manual', reason: `the sign-in names no client id — ${declaredByHand}` };
+            return;
+        }
         try {
-            const found = await discovery.providerForDeclaredClient(m.name, m.url, v.oauth.clientId);
+            const found = await discovery.providerForDeclaredClient(m.name, m.url, clientId);
             if (found.status !== 'oauth') {
                 m.setup = {
                     kind: 'oauth-manual',
@@ -779,12 +836,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);
@@ -803,6 +870,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)
@@ -812,7 +880,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);
             }
@@ -849,6 +918,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),
@@ -896,7 +968,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 ------------------------------------------------------------------
@@ -1005,6 +1077,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 —
@@ -1024,34 +1143,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).
@@ -1343,8 +1437,11 @@ function normalizeVariables(raw) {
         const label = typeof e.label === 'string' && e.label.trim() ? e.label.trim() : undefined;
         const oauth = normalizeVariableOAuth(at, e.oauth);
         // OAuth is inherently per-caller — each user signs in for their own token. An
-        // admin-shared OAuth token would leak one user's token to all callers.
-        if (oauth && scope !== 'user') {
+        // admin-shared OAuth token would leak one user's token to all callers. The
+        // one exception is a MANAGED sign-in enabled as a workspace connection:
+        // there the shared token is the point (one CRM account for the company),
+        // and only an owner of the tool can make it.
+        if (oauth && scope !== 'user' && !oauth.managed) {
             throw new Error(`${at}\` has \`oauth\`, so its \`scope\` must be \`user\``);
         }
         return {
@@ -1404,9 +1501,28 @@ function normalizeVariableOAuth(at, raw) {
     };
     const authorizationUrl = safeUrl(o.authorizationUrl, 'authorizationUrl');
     const tokenUrl = safeUrl(o.tokenUrl, 'tokenUrl');
+    // A managed sign-in names the platform connector it goes through instead
+    // of a client id: the client is the broker's. Both parts are ids of OURS
+    // (matched against the catalog later), so the shape check here is all the
+    // file gets — and neither value is repeated in a refusal.
+    let managed;
+    if (o.managed !== undefined) {
+        const m = o.managed;
+        const connectorId = m && typeof m === 'object' && typeof m.connectorId === 'string' ? m.connectorId.trim() : '';
+        const scopeSet = m && typeof m === 'object' && typeof m.scopeSet === 'string' ? m.scopeSet.trim() : '';
+        if (!isValidId(connectorId) || !isValidId(scopeSet)) {
+            throw new Error(`${at}.oauth.managed\` must be { connectorId, scopeSet } (lowercase snake_case ids)`);
+        }
+        managed = { connectorId, scopeSet };
+    }
     const clientId = typeof o.clientId === 'string' && o.clientId.trim() ? o.clientId.trim() : '';
-    if (!clientId)
+    if (!clientId && !managed)
         throw new Error(`${at}.oauth.clientId\` is required`);
+    // One client or the other: a managed sign-in runs with the broker's app, and
+    // a client id beside it would be a declaration two flows claim.
+    if (clientId && managed) {
+        throw new Error(`${at}.oauth\` names both \`managed\` and a \`clientId\`; a managed sign-in has no client of its own`);
+    }
     let scopes;
     if (o.scopes !== undefined) {
         if (!Array.isArray(o.scopes) || !o.scopes.every((s) => typeof s === 'string')) {
@@ -1435,11 +1551,12 @@ function normalizeVariableOAuth(at, raw) {
     return {
         authorizationUrl,
         tokenUrl,
-        clientId,
+        ...(clientId ? { clientId } : {}),
         ...(scopes ? { scopes } : {}),
         ...(authParams ? { authParams } : {}),
         ...(o.pkce === false ? { pkce: false } : {}),
         ...(resource ? { resource } : {}),
+        ...(managed ? { managed } : {}),
     };
 }
 /**