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

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

@@ -43,6 +43,7 @@ import {
   EXTERNAL_KB_MANUAL_NAME,
   MAX_CAPABILITIES,
   type IToolManualService,
+  type ConnectorScope,
   type ToolManualDescriptor,
   type ToolManualDescriptorBase,
   type ToolManualSummary,
@@ -58,6 +59,7 @@ import {
   type ToolProbeTarget,
   type ToolVariableScope,
   type ToolVariableOAuth,
+  type LiveDeclaration,
 } from './tool-manuals.contract.js';
 
 const CACHE_TTL_MS = 60_000;
@@ -181,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;
 }
 
 /**
@@ -190,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();
@@ -208,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>;
@@ -304,8 +319,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.accessibleManuals(userEmail)).map(toSummary);
   }
 
-  async listAccessibleCatalog(userEmail: string): Promise<AccessibleCatalog> {
-    const { manuals, invalid } = await this.accessibleScan(userEmail);
+  async listAccessibleCatalog(userEmail: string, within?: ConnectorScope): Promise<AccessibleCatalog> {
+    const { manuals, invalid } = await this.accessibleScan(userEmail, within);
     return { tools: manuals.map(toSummary), invalid };
   }
 
@@ -313,8 +328,8 @@ export class ToolManualService implements IToolManualService {
     return (await this.scan()).manuals.map(toSummary);
   }
 
-  async catalogFingerprints(userEmail: string): Promise<string[]> {
-    return (await this.accessibleManuals(userEmail)).map(manualFingerprint);
+  async catalogFingerprints(userEmail: string, within?: ConnectorScope): Promise<string[]> {
+    return (await this.accessibleManuals(userEmail, within)).map(manualFingerprint);
   }
 
   async getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null> {
@@ -341,14 +356,47 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  async listLocalOnly(userEmail: string): Promise<{ slug: string; name: string; path: string }[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  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 }));
   }
 
   async listDeclaredOnlyOnBranch(
     userEmail: string,
     branch: string,
+    within?: ConnectorScope,
   ): Promise<{ name: string; path: string; type: ToolManualType }[]> {
     if (!branch || branch === this.kb.defaultBranch) return [];
     // Only a draft this process already holds a clone of — the one the caller
@@ -377,7 +425,7 @@ export class ToolManualService implements IToolManualService {
       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 }));
   }
 
@@ -456,8 +504,11 @@ export class ToolManualService implements IToolManualService {
     return { name: m.name, type: m.type, remote: m.remote, healthCheck: m.healthCheck, callTemplate };
   }
 
-  async toManualCallTemplates(userEmail: string, opts?: { remoteOnly?: boolean }): Promise<CallTemplate[]> {
-    const manuals = await this.accessibleManuals(userEmail);
+  async toManualCallTemplates(
+    userEmail: string,
+    opts?: { remoteOnly?: boolean; within?: ConnectorScope },
+  ): Promise<CallTemplate[]> {
+    const manuals = await this.accessibleManuals(userEmail, opts?.within);
     const out: CallTemplate[] = [];
     for (const m of manuals) {
       // Remote consumers (the hosted MCP proxy) don't get local-only manuals —
@@ -474,11 +525,17 @@ export class ToolManualService implements IToolManualService {
     return out;
   }
 
-  async resolveInlineManual(userEmail: string, slug: string): Promise<UtcpManualDict | null> {
+  async resolveInlineManual(
+    userEmail: string,
+    slug: string,
+    opts?: { within?: ConnectorScope },
+  ): Promise<UtcpManualDict | null> {
     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',
@@ -590,8 +647,8 @@ export class ToolManualService implements IToolManualService {
     };
   }
 
-  private async accessibleManuals(userEmail: string): Promise<ToolManualDescriptor[]> {
-    return (await this.accessibleScan(userEmail)).manuals;
+  private async accessibleManuals(userEmail: string, within?: ConnectorScope): Promise<ToolManualDescriptor[]> {
+    return (await this.accessibleScan(userEmail, within)).manuals;
   }
 
   /**
@@ -599,22 +656,33 @@ export 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 async accessibleScan(userEmail: string): Promise<ScanResult> {
-    const { manuals, invalid } = await this.scan();
-    if (manuals.length === 0 && invalid.length === 0) return emptyScan();
+  private async accessibleScan(userEmail: string, within?: ConnectorScope): Promise<ScanResult> {
+    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).
     // 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: string) => 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)),
     };
   }
 
@@ -639,14 +707,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;
   }
 
   /**
@@ -817,11 +885,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,
@@ -880,11 +949,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);
@@ -905,6 +985,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
@@ -913,7 +994,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);
       }
@@ -949,6 +1032,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),
@@ -997,7 +1082,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 };
   }
 }
 
@@ -1109,6 +1194,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 —
@@ -1132,34 +1265,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

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

@@ -5,20 +5,34 @@ import type { ToolContext, ToolHandlerFactory } from '../tool-helpers/index.js';
 import { toolDef, declareRouteTool } from '../tool-helpers/index.js';
 import type { IAccessControl } from '../access/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
-import type { IToolManualService } from './tool-manuals.contract.js';
+import type { ConnectorScope, IToolManualService } from './tool-manuals.contract.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
+import { 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;
+      userKind?: 'static' | 'oauth' | null;
+      grantedScopes?: string;
+    }[]
+  >;
 }
 
 /**
@@ -51,7 +65,9 @@ export function registerToolManualsTools(
     hiddenTools?: HiddenToolSource;
   },
 ): void {
-  registry.registerExternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
+  registry.registerExternalTool((ctx) =>
+    buildListLocalToolsDef(toolManualService, ctx.userEmail, ctx.connectionScope?.connectorFilter()),
+  );
   registry.registerInternalTool((ctx) => buildListLocalToolsDef(toolManualService, ctx.userEmail));
   // The def above is built per catalog listing (its description names the
   // tools configured for THIS caller), so declare the arguments here as well:
@@ -59,12 +75,22 @@ export function registerToolManualsTools(
   // against them too.
   declareRouteTool('list_local_tools', LIST_LOCAL_TOOLS_INPUTS);
 
+  // The local server's discovery read (`discovery`): it asks this route at
+  // startup for the connectors it must materialize, whatever tools the
+  // connection is offered — a connection made as an agent configuration that omits
+  // the tool is answered its connectors, not refused, or the local server
+  // could not start for that agent at all.
   router.post(
     '/agent/tools/list_local_tools',
     toolAuth,
-    toolHandler(async (_args, ctx: ToolContext) => ({
-      tools: await toolManualService.listLocalOnly(ctx.user.email),
-    })),
+    toolHandler(async (_args, ctx: ToolContext) => {
+      const within = ctx.connectionScope?.connectorFilter();
+      return {
+        tools: await (within
+          ? toolManualService.listLocalOnly(ctx.user.email, within)
+          : toolManualService.listLocalOnly(ctx.user.email)),
+      };
+    }, { discovery: true }),
   );
 
   // A FUNCTION, not a constant — this factory runs at boot, and on a
@@ -228,7 +254,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'],
@@ -243,12 +271,17 @@ export function registerToolManualsTools(
     toolHandler(async (args, ctx: ToolContext) => {
       // The in-app agent is focused on its own draft; an external caller names it.
       const branch = typeof args.branch === 'string' && args.branch ? args.branch : ctx.focusedBranch;
+      const within = ctx.connectionScope?.connectorFilter();
       // The catalog comes back whole — what parsed AND what was refused — from
       // ONE scan, so the refused files cost no second walk of the workspace and
       // the two halves cannot disagree about which files made it.
       const [{ tools: manuals, invalid }, pending] = await Promise.all([
-        toolManualService.listAccessibleCatalog(ctx.user.email),
-        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch) : Promise.resolve([]),
+        // Only the connectors the caller's connection loads: setup is counted
+        // for the tools this connection can call, not every one the person can.
+        within
+          ? toolManualService.listAccessibleCatalog(ctx.user.email, within)
+          : toolManualService.listAccessibleCatalog(ctx.user.email),
+        branch ? toolManualService.listDeclaredOnlyOnBranch(ctx.user.email, branch, within) : Promise.resolve([]),
       ]);
       const allKeys = manuals.flatMap((m) => (m.variables ?? []).map((v) => varKey(m.name, v.name)));
       const status = await deps.variableStatus.statusFor(ctx.user.id, allKeys);
@@ -285,25 +318,48 @@ export function registerToolManualsTools(
         }),
       );
       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(' ') };
     }),
   );
 }
 
 /** "Local-only tools configured for you: `a`, `b`." (or a none note), filtered to what the caller may read. */
-async function localToolsLine(svc: IToolManualService, userEmail?: string): Promise<string> {
+async function localToolsLine(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<string> {
   if (!userEmail) return 'No local-only tools are currently configured.';
-  const tools = await svc.listLocalOnly(userEmail);
+  const tools = await (within ? svc.listLocalOnly(userEmail, within) : svc.listLocalOnly(userEmail));
   if (tools.length === 0) return 'No local-only tools are currently configured.';
   return `Local-only tools configured for you: ${tools.map((t) => `\`${t.name}\``).join(', ')}.`;
 }
@@ -311,7 +367,7 @@ async function localToolsLine(svc: IToolManualService, userEmail?: string): Prom
 /** `list_local_tools` takes nothing; a const so the route and the def share one declaration. */
 const LIST_LOCAL_TOOLS_INPUTS = { type: 'object' as const, properties: {}, additionalProperties: false };
 
-async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string): Promise<UtcpTool> {
+async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: string, within?: ConnectorScope): Promise<UtcpTool> {
   return toolDef({
     name: 'list_local_tools',
     description:
@@ -324,7 +380,7 @@ async function buildListLocalToolsDef(svc: IToolManualService, userEmail?: strin
       'machine. Otherwise each entry gives the tool’s name and its `.tool` file ' +
       'path in the knowledge base — read that file with `read_file` and wire the tool into your local ' +
       'setup by hand. ' +
-      (await localToolsLine(svc, userEmail)),
+      (await localToolsLine(svc, userEmail, within)),
     path: '/api/agent/tools/list_local_tools',
     inputs: LIST_LOCAL_TOOLS_INPUTS,
     outputs: {