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

package/src/modules/tool-manuals/tool-manuals.service.ts

@@ -59,6 +59,7 @@ import {
   type ToolProbeTarget,
   type ToolVariableScope,
   type ToolVariableOAuth,
+  type LiveDeclaration,
 } from './tool-manuals.contract.js';
 
 const CACHE_TTL_MS = 60_000;
@@ -182,6 +183,19 @@ export function describeManualFault(err: unknown): string {
 interface ScanResult {
   manuals: ToolManualDescriptor[];
   invalid: InvalidToolManual[];
+  /**
+   * Every manual the parse refused whose file still says which manual it is,
+   * by slug, with the reason. Not a listing surface (`invalid` is that, by
+   * path): it lets a sign-in started on a refused declaration answer why,
+   * where the slug alone would otherwise find nothing.
+   */
+  refused: RefusedManual[];
+}
+
+interface RefusedManual {
+  slug: string;
+  path: string;
+  reason: string;
 }
 
 /**
@@ -191,7 +205,7 @@ interface ScanResult {
  * convention instance is one push away from every empty scan in the process
  * inheriting another's contents.
  */
-const emptyScan = (): ScanResult => ({ manuals: [], invalid: [] });
+const emptyScan = (): ScanResult => ({ manuals: [], invalid: [], refused: [] });
 
 const manualSerializer = new UtcpManualSerializer();
 const callTemplateSerializer = new CallTemplateSerializer();
@@ -209,8 +223,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>;
@@ -342,6 +356,38 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
+  async liveDeclaration(
+    userEmail: string,
+    slug: string,
+    varName: string,
+  ): Promise<LiveDeclaration | null> {
+    // 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: string, within?: ConnectorScope): Promise<{ slug: string; name: string; path: string }[]> {
     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 }));
@@ -408,6 +454,20 @@ export class ToolManualService implements IToolManualService {
       }));
   }
 
+  async sharedSignInKeysForManual(
+    manualName: string,
+  ): Promise<{ key: string; name: string; label: string | null; oauthScopes?: string[] }[]> {
+    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: string): Promise<ToolVariableScope> {
     // UTCP looks up `<namespace-with-doubled-underscores>_<VAR>`. Find the manual
     // whose namespace prefixes this key; the declared var is the remainder. Match
@@ -616,11 +676,16 @@ export class ToolManualService implements IToolManualService {
    * in. Absent, the answer is the caller's whole readable catalog.
    */
   private async accessibleScan(userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
-    const { manuals, invalid } = await this.scan();
-    if (manuals.length === 0 && invalid.length === 0) return emptyScan();
+    return this.readableBy(await this.scan(), userEmail, within);
+  }
+
+  /** A scan cut to what this caller may read — see {@link accessibleScan}. */
+  private async readableBy(scan: ScanResult, userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
+    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).
@@ -631,6 +696,7 @@ export class ToolManualService implements IToolManualService {
     return {
       manuals: manuals.filter((m) => inScope(m.path)),
       invalid: invalid.filter((i) => inScope(i.path)),
+      refused: refused.filter((r) => inScope(r.path)),
     };
   }
 
@@ -655,14 +721,14 @@ export class ToolManualService implements IToolManualService {
     // 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;
   }
 
   /**
@@ -750,6 +816,10 @@ export class ToolManualService implements IToolManualService {
       if (m.type !== 'mcp') 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
@@ -833,11 +903,12 @@ export 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 async completeDeclaredOAuth(
     discovery: McpAuthDiscoveryPort,
@@ -856,8 +927,15 @@ export class ToolManualService implements IToolManualService {
       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',
@@ -896,11 +974,22 @@ export class ToolManualService implements IToolManualService {
    * calls: a refusal lives only in the scan it came from, so a fixed file is a
    * valid manual on the very next scan.
    */
-  private async scanDisk(branch: string = this.kb.defaultBranch): Promise<ScanResult> {
+  private async scanDisk(
+    branch: string = 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' | 'throw' = 'empty',
+  ): Promise<ScanResult> {
     let wsId: string;
     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);
@@ -921,6 +1010,7 @@ export class ToolManualService implements IToolManualService {
     // 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: ToolManualDescriptor[] = [];
+    const refused: RefusedManual[] = [];
     const discovered = await this.source.discover(kbRoot);
     for (const plugin of discovered.plugins) {
       if (plugin.mcpJsonText === null) continue; // no servers is the common case, not an error
@@ -929,7 +1019,9 @@ export class ToolManualService implements IToolManualService {
       // (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: string, reason: string, path: string) =>
+        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);
       }
@@ -965,6 +1057,8 @@ export class ToolManualService implements IToolManualService {
         // 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),
@@ -1013,7 +1107,7 @@ export class ToolManualService implements IToolManualService {
     // draft workspace, and a draft's half-written `.tool` is not news about the
     // 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 };
   }
 }
 
@@ -1125,6 +1219,54 @@ function manualName(raw: string): string {
   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: string): Record<string, unknown> {
+  const fm = extractFrontmatter(content);
+  const source = fm ? fm.frontmatter : content;
+  const parsed = parseYaml(source) as unknown;
+  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 as Record<string, unknown>;
+}
+
+/**
+ * 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: Record<string, unknown>, provisionalSlug: string): string {
+  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: string, content: string): string | null {
+  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 —
@@ -1148,34 +1290,9 @@ export function normalizeToolManual(
   // 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) as unknown;
-  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 as Record<string, unknown>;
+  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: string;
-  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
@@ -1487,8 +1604,11 @@ function normalizeVariables(raw: unknown): ToolVariable[] {
     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 {
@@ -1548,8 +1668,27 @@ function normalizeVariableOAuth(at: string, raw: unknown): ToolVariableOAuth | u
   };
   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: { connectorId: string; scopeSet: string } | undefined;
+  if (o.managed !== undefined) {
+    const m = o.managed as Record<string, unknown> | null;
+    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) throw new Error(`${at}.oauth.clientId\` is required`);
+  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: string[] | undefined;
   if (o.scopes !== undefined) {
     if (!Array.isArray(o.scopes) || !o.scopes.every((s) => typeof s === 'string')) {
@@ -1578,11 +1717,12 @@ function normalizeVariableOAuth(at: string, raw: unknown): ToolVariableOAuth | u
   return {
     authorizationUrl,
     tokenUrl,
-    clientId,
+    ...(clientId ? { clientId } : {}),
     ...(scopes ? { scopes } : {}),
     ...(authParams ? { authParams } : {}),
     ...(o.pkce === false ? { pkce: false } : {}),
     ...(resource ? { resource } : {}),
+    ...(managed ? { managed } : {}),
   };
 }
 

package/src/modules/tool-manuals/tool-manuals.tools.ts

@@ -7,18 +7,35 @@ import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
+import { scopesCovered, userSecretGap } from '../secrets-vault/index.js';
 
 /**
  * What `list_tool_setup` needs from the secrets vault (structurally satisfied
  * by `ISecretsVaultService.statusFor`). A local port keeps this module free of
- * a secrets-vault import — the same decoupling discipline as
- * `McpAuthDiscoveryPort` in the service.
+ * the vault service — the same decoupling discipline as
+ * `McpAuthDiscoveryPort` in the service. Only the vault's pure readiness rule
+ * (`userSecretGap`, its exported contract) is imported, the one the MCP proxy
+ * hides tools by.
  */
 export interface VariableStatusPort {
   statusFor(
     userId: string,
     keys: string[],
-  ): Promise<{ key: string; adminConfigured: boolean; userConfigured: boolean; userAuthorized?: boolean }[]>;
+  ): Promise<
+    {
+      key: string;
+      adminConfigured: boolean;
+      /** What the owner's row is: a sign-in needs an `oauth` one, not a key left from when the variable was static. */
+      adminKind?: 'static' | 'oauth' | null;
+      userConfigured: boolean;
+      userAuthorized?: boolean;
+      /** For a shared (workspace) sign-in: the owner's row holds tokens, and what they were granted. */
+      adminAuthorized?: boolean;
+      adminGrantedScopes?: string;
+      userKind?: 'static' | 'oauth' | null;
+      grantedScopes?: string;
+    }[]
+  >;
 }
 
 /**
@@ -102,18 +119,15 @@ export function registerToolManualsTools(
     // hidden tool's entry CONTAINS is on the field below rather than here.
     description:
       'Configuration status of every `.tool` the current user can access: what each needs set up and what is ' +
-      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot ' +
-      'READ is absent, and every flag is the caller\'s own. ' +
-      'Secret VALUES are never returned and can never be set through a tool: an admin enters them in the tool ' +
-      'editor; users sign in on /connect. ' +
-      'Setting a tool\'s shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter ' +
-      '`write:`/`owner:` verbs and the access.md chain), NOT by a platform role: who manages the file configures ' +
-      'the tool. ' +
-      '`hiddenTools` names the tools Hexis hides from agents for an invalid schema. ' +
-      'The listing is the RELEASED catalog, built from the default branch only: a server or `.tool` you declared on a ' +
-      'draft is not listed, callable or signed-in-able until it is merged. Pass `branch` (the draft you wrote the ' +
-      'declaration on) and `onBranchOnly` names every tool declared there that the default branch does not serve ' +
-      'yet — open a change request and ask the user to merge it.',
+      'configured, as `{ tools, invalid, onBranchOnly, note? }`. Scoped to the CALLER: a `.tool` it cannot READ is ' +
+      "absent, and a `user` variable's flags are the caller's own. An `admin` variable with `oauth` is a WORKSPACE " +
+      "connection: `authorized` is the owner's connection, which only a writer of the tool can make or remake. " +
+      'Secret VALUES are never returned or set through a tool: an admin enters them in the tool editor; users sign ' +
+      'in on /connect. Setting shared secrets is gated by `canWrite` on the `.tool` FILE (its frontmatter verbs and ' +
+      'the access.md chain), not by a platform role. `hiddenTools` names the tools Hexis hides for an invalid ' +
+      'schema. The listing is the RELEASED catalog (default branch only): a server or `.tool` declared on a draft is ' +
+      'not listed, callable or signed-in-able until merged. Pass `branch` and `onBranchOnly` names every tool ' +
+      'declared there that the default branch does not serve yet — open a change request and ask the user to merge it.',
     path: '/api/agent/tools/list_tool_setup',
     inputs: {
       type: 'object',
@@ -197,7 +211,22 @@ export function registerToolManualsTools(
                         'Shared value set (plain admin vars), or the owner finished provider setup (OAuth vars).',
                     },
                     userConfigured: { type: 'boolean' },
-                    authorized: { type: ['boolean', 'null'], description: 'OAuth vars: current user signed in.' },
+                    authorized: {
+                      type: ['boolean', 'null'],
+                      description:
+                        'OAuth vars: a token is stored that covers the declared scopes — the current user\'s for a `user` ' +
+                        'variable, the WORKSPACE connection an owner made for an `admin` one (a managed connector enabled ' +
+                        'as one shared connection; a reader cannot connect that, a writer of the tool can).',
+                    },
+                    managed: {
+                      type: 'object',
+                      description:
+                        'Present when the sign-in goes through a managed connector (the distribution\'s own OAuth app, a ' +
+                        'broker doing the round-trip): which connector and scope set. Members connect on /connect; an ' +
+                        'owner needs no client secret for it.',
+                      properties: { connectorId: { type: 'string' }, scopeSet: { type: 'string' } },
+                      required: ['connectorId', 'scopeSet'],
+                    },
                   },
                   required: ['name', 'scope', 'oauth', 'adminConfigured', 'userConfigured'],
                 },
@@ -240,7 +269,9 @@ export function registerToolManualsTools(
         },
         note: {
           type: 'string',
-          description: 'Present when `onBranchOnly` is non-empty: what it takes for those tools to go live.',
+          description:
+            'Present when something is left to do: what it takes for the tools in `onBranchOnly` to go live, and for ' +
+            'tools that need your own value or sign-in to work.',
         },
       },
       required: ['tools', 'invalid', 'onBranchOnly'],
@@ -288,6 +319,16 @@ export function registerToolManualsTools(
             variables: (m.variables ?? []).map((v) => {
               const st = statusByKey.get(varKey(m.name, v.name));
               const isOAuth = v.oauth != null;
+              // A sign-in counts as authorized when a token is stored AND it
+              // still covers what the tool declares — the one readiness rule,
+              // so this flag agrees with the sign-in note below. A shared
+              // sign-in (a managed workspace connection) reads the owner's
+              // row: it is everyone's once an owner has connected it.
+              const authorized = isOAuth
+                ? v.scope === 'admin'
+                  ? st?.adminAuthorized === true && scopesCovered(v.oauth?.scopes, st.adminGrantedScopes)
+                  : st?.userAuthorized === true && scopesCovered(v.oauth?.scopes, st.grantedScopes)
+                : null;
               return {
                 name: v.name,
                 scope: v.scope,
@@ -295,24 +336,48 @@ export function registerToolManualsTools(
                 oauth: isOAuth,
                 adminConfigured: st?.adminConfigured ?? false,
                 userConfigured: st?.userConfigured ?? false,
-                authorized: isOAuth ? (st?.userAuthorized ?? false) : null,
+                authorized,
+                ...(v.oauth?.managed ? { managed: v.oauth.managed } : {}),
               };
             }),
           };
         }),
       );
       const onBranchOnly = pending.map((p) => ({ ...p, branch: branch! }));
-      if (onBranchOnly.length === 0) return { tools, invalid, onBranchOnly };
-      return {
-        tools,
-        invalid,
-        onBranchOnly,
-        note:
+      const notes: string[] = [];
+      if (onBranchOnly.length > 0) {
+        notes.push(
           `${onBranchOnly.map((p) => `\`${p.name}\``).join(', ')} ${onBranchOnly.length === 1 ? 'is' : 'are'} declared on ` +
-          `\`${branch}\` only. Tools are served from \`${deps.kb.defaultBranch}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
-          'unlisted, uncallable and without a sign-in until that branch is merged: open a change request with ' +
-          `\`open_change_request\` (target \`${deps.kb.defaultBranch}\`), then ask the user to review and merge it in the app.`,
-      };
+            `\`${branch}\` only. Tools are served from \`${deps.kb.defaultBranch}\`, so ${onBranchOnly.length === 1 ? 'it stays' : 'they stay'} ` +
+            'unlisted, uncallable and without a sign-in until that branch is merged: open a change request with ' +
+            `\`open_change_request\` (target \`${deps.kb.defaultBranch}\`), then ask the user to review and merge it in the app.`,
+        );
+      }
+      // The person's own part, said where the agent is when a tool "does not work": the
+      // reconnect step is the one agents leave out (the agent-guide benchmark, 2026-10-26).
+      // By the rule the proxy hides a tool by (`userSecretGap`), so the note
+      // names every tool that is hidden for want of the caller's own value. A
+      // sign-in waits on the owner's provider setup (an OAuth admin row, not a
+      // key left from when the variable was static — the Connect page counts
+      // that setup incomplete and the sign-in start refuses it): until then
+      // there is nothing to sign in to.
+      const needYou = manuals.filter((m) =>
+        (m.variables ?? []).some((v) => {
+          if (v.scope !== 'user') return false;
+          const st = statusByKey.get(varKey(m.name, v.name));
+          const gap = userSecretGap({ oauth: v.oauth != null, oauthScopes: v.oauth?.scopes }, st);
+          return gap !== null && (v.oauth == null || (st?.adminConfigured === true && st.adminKind === 'oauth'));
+        }),
+      );
+      if (needYou.length > 0) {
+        notes.push(
+          `${needYou.map((t) => `\`${t.name}\``).join(', ')} ${needYou.length === 1 ? 'needs' : 'need'} your own value or sign-in. ` +
+            'Set it yourself on the Connect page, never in the chat; then reconnect your assistant, or start a new chat, ' +
+            'so the tool is listed.',
+        );
+      }
+      if (notes.length === 0) return { tools, invalid, onBranchOnly };
+      return { tools, invalid, onBranchOnly, note: notes.join(' ') };
     }),
   );
 }

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

@@ -3,8 +3,8 @@ import express from 'express';
 import { describe, expect, it } from 'vitest';
 import { inputSchemaDefect } from '@bevel-software/platform-mcp-core';
 import { ToolRegistry } from '../tool-registry.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerVersionControlTools } from '../../version-control/agent-tools/version-control.tools.js';
+import { registerChangeRequestReadTools } from '../../version-control/agent-tools/change-request-read.tools.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
 import { registerPluginsTools } from '../../plugins/plugins.tools.js';
@@ -58,8 +58,8 @@ const CORE_SERVER_SOURCE = new URL('../../../core/create-core-server.ts', import
 /** Every tool-registering module, by the name the server calls it under. */
 const MODULES: ReadonlyArray<{ name: string; register: (registry: ToolRegistry) => void }> = [
   {
-    name: 'registerWorkflowTools',
-    register: (registry) => registerWorkflowTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
+    name: 'registerVersionControlTools',
+    register: (registry) => registerVersionControlTools(registry, express.Router(), pass, handler, testKbContext(), async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never),
   },
   {
     name: 'registerChangeRequestReadTools',

package/src/modules/tool-registry/__tests__/read-only-hints.test.ts

@@ -13,8 +13,8 @@ import {
   createToolHintsRoutes,
 } from '../index.js';
 import { toolDef } from '../../tool-helpers/index.js';
-import { registerWorkflowTools } from '../../workflow/agent-tools/workflow.tools.js';
-import { registerChangeRequestReadTools } from '../../workflow/agent-tools/change-request-read.tools.js';
+import { registerVersionControlTools } from '../../version-control/agent-tools/version-control.tools.js';
+import { registerChangeRequestReadTools } from '../../version-control/agent-tools/change-request-read.tools.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { registerSkillsTools } from '../../skills/index.js';
 import { registerPluginsTools } from '../../plugins/index.js';
@@ -98,7 +98,7 @@ const INTERNAL_ONLY = new Set(['switch_branch']);
 function platformRegistry(): ToolRegistry {
   const registry = new ToolRegistry();
   const kb = testKbContext();
-  registerWorkflowTools(registry, express.Router(), pass, handler, kb, async () => true);
+  registerVersionControlTools(registry, express.Router(), pass, handler, kb, async () => true);
   registerChangeRequestReadTools(registry, express.Router(), pass, handler, nothing, kb);
   registerWorkspaceTools(
     registry,