@lanes-sh/link 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A self-hosted MCP gateway for your accounts, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://github.com/lanes-sh/link#readme",

package/src/cli/commands/operate/outputs.ts

@@ -1,6 +1,6 @@
 import { listProfiles } from '#profile';
 import { fileURLToPath } from 'node:url';
-import { deployedUrl, endpointUrl } from '../../endpoint-url.ts';
+import { deployedUrl, endpointHealth, localUrl } from '../../endpoint-url.ts';
 import { announce, heading, print, style, warn } from '../../output.ts';
 import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
 
@@ -9,11 +9,6 @@ export interface OutputsFlags extends GlobalFlags {
   readonly json?: boolean | undefined;
 }
 
-interface Health {
-  readonly profile: string;
-  readonly profiles: readonly string[];
-}
-
 /**
  * What an agent harness needs to reach this endpoint.
  *
@@ -34,9 +29,11 @@ export async function outputs(flags: OutputsFlags): Promise<void> {
     const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
     const declared = runtime.config.targets[runtime.target]?.deploy;
     const deployed = await deployedUrl(declared);
-    const url = deployed ?? (await endpointUrl(runtime.config, runtime.target));
+    // Not `endpointUrl`, which would ask the platform a second time for an
+    // answer this line already has.
+    const url = deployed ?? localUrl(runtime.config);
 
-    const live = await health(url, token);
+    const live = await endpointHealth(url, token);
     const mine = live?.profile === runtime.resolution.profile;
 
     // Live if it is up, otherwise what `start` would serve: the whole
@@ -174,33 +171,3 @@ async function tokenInvocation(
   return { command: `bun run ${entry} link token show --raw${suffix}`, onPath: false };
 }
 
-/**
- * Ask the endpoint who it is.
- *
- * The profile name is checked by the caller, not just the port: two workspaces
- * can assign the same port, and reporting "running" because something
- * unrelated answers would send someone to register an endpoint serving another
- * workspace's accounts.
- *
- * The token is sent because `/health` names profiles only to a caller that
- * holds one. Anonymously it answers `{status: "ok"}` and nothing else — that
- * list is what this endpoint holds, and a deployed URL is readable by anyone.
- * An endpoint that answers without naming itself is therefore reported as
- * something else's, which is the honest reading: this token does not open it.
- */
-async function health(url: string, token: string): Promise<Health | null> {
-  try {
-    const probe = new URL(url);
-    probe.pathname = '/health';
-    const response = await fetch(probe, {
-      headers: { authorization: `Bearer ${token}` },
-      signal: AbortSignal.timeout(700),
-    });
-    if (!response.ok) return null;
-
-    const body = (await response.json()) as Partial<Health>;
-    return body.profile ? { profile: body.profile, profiles: body.profiles ?? [body.profile] } : null;
-  } catch {
-    return null;
-  }
-}

package/src/cli/commands/operate/tools.ts

@@ -0,0 +1,343 @@
+import { capabilityIdForToolName } from '#server/mcp';
+import { deployedUrl, endpointHealth, localUrl } from '../../endpoint-url.ts';
+import { announce, emit, heading, print, style, warn } from '../../output.ts';
+import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
+
+export interface ToolsFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+}
+
+/**
+ * What a client is actually being told, asked over the wire.
+ *
+ * Not derived from the config, and that is the whole reason this exists.
+ * `doctor` answers whether the credentials resolve and `outputs` answers where
+ * the endpoint is; neither answers the question that follows a client showing
+ * the wrong tools, which is what the endpoint would hand it right now. Working
+ * that out previously meant hand-rolling a `tools/list` with `curl` and a token
+ * pulled out of the secret store, and reading a byte count out of a request log
+ * to guess at the answer.
+ *
+ * The `listChanged` line is here for the same reason. A client refreshes by
+ * asking again, and a server that claims it will announce changes gives it a
+ * reason not to — so a surface that looks stale in a client and current here is
+ * explained by that flag more often than by anything else (ADR-032).
+ */
+export async function tools(flags: ToolsFlags): Promise<void> {
+  const runtime = await openRuntime(flags);
+
+  try {
+    const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
+    const declared = runtime.config.targets[runtime.target]?.deploy;
+    const deployed = await deployedUrl(declared);
+    // Not `endpointUrl`, which asks the platform a second time for an answer
+    // this line already has.
+    const url = deployed ?? localUrl(runtime.config);
+
+    // Before trusting anything the surface says: two workspaces can assign the
+    // same port, and `secrets push` makes their tokens match, so a `--target
+    // cloud` whose deployment could not be located answers from loopback with a
+    // token that works. Reporting that as the deployed endpoint's surface is
+    // the failure `endpoint-url.ts` calls "silent in the worst way".
+    const live = await endpointHealth(url, token);
+    const mine = live?.profile === runtime.resolution.profile;
+
+    const surface = await askEndpoint(url, token);
+    const providers = [...new Set(runtime.registry.capabilities().map(({ id }) => id))];
+
+    await emit(
+      flags.json,
+      {
+        url,
+        target: runtime.target,
+        // Both, because `--target cloud` reaching loopback is indistinguishable
+        // from success without them.
+        deployed: deployed !== null,
+        answering: mine,
+        ...surfaceJson(surface),
+      },
+      () => {
+        announce(runtime.resolution);
+
+        heading('Endpoint');
+        print(`  ${url}  ${reachability(mine, deployed !== null, surface)}`);
+
+        if (declared && !deployed) {
+          // The case the ownership probe cannot catch on its own: the address
+          // is loopback because the platform could not be asked, not because
+          // this target is local.
+          print(
+            warn(
+              `could not ask ${declared.platform} where "${declared.service}" is — this is the local endpoint, not the deployed one`,
+            ),
+          );
+        } else if (live && !mine) {
+          print(warn(`something else is serving this port: profile "${live.profile}"`));
+        }
+
+        if (!surface.reachable) {
+          print(fail(surface));
+          return;
+        }
+
+        heading(`Advertised to a client (${surface.names.length})`);
+        for (const [provider, names] of groupByProvider(surface.names, providers)) {
+          print(`  ${style.bold(provider)}  ${style.dim(`${names.length}`)}`);
+          for (const name of names) print(`    ${name}`);
+        }
+
+        heading('How a client sees it');
+        print(`  payload:      ${kb(surface.bytes)} for the whole list`);
+        print(`  listChanged:  ${listChangedLine(surface.listChanged)}`);
+        print(
+          style.dim(
+            '  Tools only — a skill is a prompt, and is not counted here or by `connect`.',
+          ),
+        );
+      },
+    );
+
+    // Non-zero for the same reason `doctor` does it: a command whose whole job
+    // is to answer a question exits failing when it could not answer.
+    if (!surface.reachable) process.exitCode = 1;
+  } finally {
+    await runtime.close();
+  }
+}
+
+/**
+ * What is at this address, in one word.
+ *
+ * The refusal case is why this is not just `mine`. `/health` is asked with the
+ * same token, so an endpoint belonging to another workspace fails that probe
+ * too — and reporting "not running" above a refusal that begins "it is
+ * answering" is the command contradicting itself in two consecutive lines.
+ */
+function reachability(mine: boolean, deployed: boolean, surface: Surface): string {
+  if (mine) return style.green(deployed ? 'deployed' : 'running');
+  if (surface.refused) return style.yellow('answering, but not for this token');
+  return style.dim(deployed ? 'not answering' : 'not running');
+}
+
+/**
+ * Why the surface could not be read, said as the thing that happened.
+ *
+ * Refused and unreachable are different problems with different fixes, and
+ * folding them together sends someone to check whether the endpoint is up when
+ * it answered them perfectly well and declined their token.
+ */
+function fail(surface: Surface): string {
+  if (surface.refused) {
+    return (
+      warn(`the endpoint refused this token: ${surface.reason}`) +
+      `\n${style.dim('  It is answering. Either the token was rotated without re-registering, or\n  this address belongs to another workspace.')}`
+    );
+  }
+
+  return (
+    warn(`could not ask it: ${surface.reason}`) +
+    `\n${style.dim('  Nothing here reads the config to guess instead — an endpoint that cannot\n  be asked is exactly the case where a guess would be believed.')}`
+  );
+}
+
+interface Surface {
+  readonly reachable: boolean;
+  readonly reason?: string;
+  /** It answered, and declined. Distinct from not answering at all. */
+  readonly refused?: boolean;
+  readonly names: readonly string[];
+  readonly bytes: number;
+  readonly listChanged?: boolean | undefined;
+}
+
+/**
+ * `tools` as a count, matching `/reload` and `connect`; the names beside it.
+ *
+ * One key, one meaning. `ReloadResult.tools` and `PublishOutcome.tools` are both
+ * numbers, and the count is what `docs/connect.md` tells an operator to compare
+ * against their client — shipping the same key here as an array would make
+ * `.tools > 5` true for a single tool.
+ */
+function surfaceJson(surface: Surface): Record<string, unknown> {
+  return {
+    reachable: surface.reachable,
+    ...(surface.reason !== undefined ? { reason: surface.reason } : {}),
+    ...(surface.refused !== undefined ? { refused: surface.refused } : {}),
+    tools: surface.names.length,
+    names: surface.names,
+    bytes: surface.bytes,
+    ...(surface.listChanged !== undefined ? { listChanged: surface.listChanged } : {}),
+  };
+}
+
+/**
+ * One `initialize`, one `tools/list`, exactly as a 2025-era client sends them.
+ *
+ * Deliberately hand-rolled rather than run through an MCP client library: the
+ * subject is what the endpoint puts on the wire, and a library that negotiated
+ * a newer revision would answer a different question than the one asked.
+ */
+export async function askEndpoint(url: string, token: string): Promise<Surface> {
+  const post = async (body: unknown): Promise<{ text: string; result: Record<string, unknown> }> => {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        // Both, and not one: the streamable HTTP transport answers 406 to a
+        // client that will not accept an event stream, whatever it then sends.
+        accept: 'application/json, text/event-stream',
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+
+    const text = await response.text();
+    if (!response.ok) throw new Refusal(response.status, text);
+
+    return { text, result: parse(text) };
+  };
+
+  try {
+    const init = await post({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'lanes-link-cli', version: '0.0.0' },
+      },
+    });
+
+    const capabilities = init.result['capabilities'] as
+      | { tools?: { listChanged?: boolean } }
+      | undefined;
+
+    const listed = await post({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+    const names = ((listed.result['tools'] as Array<{ name?: string }> | undefined) ?? [])
+      .map((tool) => tool.name ?? '')
+      .filter((name) => name.length > 0)
+      .sort();
+
+    return {
+      reachable: true,
+      names,
+      bytes: Buffer.byteLength(listed.text),
+      listChanged: capabilities?.tools?.listChanged,
+    };
+  } catch (error) {
+    if (error instanceof Refusal) {
+      return { reachable: false, refused: error.refused, reason: error.message, names: [], bytes: 0 };
+    }
+
+    return {
+      reachable: false,
+      reason: error instanceof Error ? error.message : String(error),
+      names: [],
+      bytes: 0,
+    };
+  }
+}
+
+/** An endpoint that answered and would not serve this call. */
+class Refusal extends Error {
+  readonly refused: boolean;
+
+  constructor(status: number, body: string) {
+    // The transport puts the actionable reason in a JSON-RPC error body for
+    // 400/406/415, and discarding it leaves only a number to act on.
+    const detail = errorMessage(body);
+    super(detail ? `${status} — ${detail}` : `answered ${status}`);
+    this.refused = status === 401 || status === 403;
+  }
+}
+
+function errorMessage(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as { error?: { message?: string } | string };
+    if (typeof parsed.error === 'string') return parsed.error;
+    return parsed.error?.message ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The JSON payload of a response that may or may not be framed as SSE.
+ *
+ * Three shapes reach here and all three are legal. A plain JSON body; an event
+ * stream whose payload line is `data: {…}`; and one where the space after the
+ * colon is absent, which the spec permits. The stream may also open with
+ * comment lines — the transport arms a keep-alive on every POST, so a handler
+ * that runs long enough emits `: keepalive` before anything else — so the
+ * payload is found by scanning rather than by inspecting the first characters.
+ */
+export function parse(text: string): Record<string, unknown> {
+  const data = text.split('\n').find((line) => line.startsWith('data:'));
+  const body = data === undefined ? text : data.slice('data:'.length).trim();
+
+  const message = JSON.parse(body) as {
+    result?: Record<string, unknown>;
+    error?: { message?: string };
+  };
+
+  if (message.error) throw new Error(message.error.message ?? 'the endpoint returned an error');
+  return message.result ?? {};
+}
+
+/**
+ * Group by provider, resolving each wire name back to the capability it is.
+ *
+ * A wire name is the capability id with its dots replaced (`naming.ts`), so
+ * `icloud_mail.send_message` arrives as `icloud_mail_send_message` and there is
+ * nothing left in the string to say where the provider ends. Splitting on the
+ * first underscore would file it under `icloud`, which is not a provider.
+ *
+ * `capabilityIdForToolName` answers it exactly against a set of known ids, and
+ * falls back to that first-underscore split when it recognises none — which is
+ * reachable here, because the registry is the *invoking profile's* while the
+ * endpoint may serve several, and under `--target cloud` may run an image this
+ * checkout does not have. So the fallback is detected rather than trusted: a
+ * name that resolves to nothing known is grouped as unattributed, because a
+ * guessed heading with a confident count is worse than an honest "these did not
+ * match anything I know about".
+ */
+export function groupByProvider(
+  names: readonly string[],
+  capabilityIds: readonly string[],
+): Map<string, string[]> {
+  const known = new Set(capabilityIds);
+  const grouped = new Map<string, string[]>();
+
+  for (const name of names) {
+    const id = capabilityIdForToolName(name, capabilityIds);
+    const provider = known.has(id) ? id.slice(0, id.indexOf('.')) : UNATTRIBUTED;
+
+    const bucket = grouped.get(provider);
+    if (bucket) bucket.push(name);
+    else grouped.set(provider, [name]);
+  }
+
+  return new Map([...grouped].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/** Named rather than spelled inline, so the output and the test agree. */
+export const UNATTRIBUTED = '(not in this profile)';
+
+function kb(bytes: number): string {
+  return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+function listChangedLine(declared: boolean | undefined): string {
+  if (declared === undefined) return style.dim('not declared');
+  if (declared === false) {
+    return `false  ${style.dim('— a client re-reads this list rather than waiting to be told')}`;
+  }
+
+  // Worth a warning rather than a value, because it is the shape of a bug that
+  // presents as "the endpoint is wrong" when the endpoint is right: a client
+  // that trusts the promise keeps the list it first fetched, for as long as it
+  // is registered.
+  return style.yellow('true') + style.dim('  — but nothing here sends the notification');
+}

package/src/cli/commands/operate.ts

@@ -20,6 +20,7 @@
 export { check, doctor, plan } from './operate/inspect.ts';
 export { status } from './operate/status.ts';
 export { outputs, type OutputsFlags } from './operate/outputs.ts';
+export { tools, type ToolsFlags } from './operate/tools.ts';
 export { start } from './operate/serve.ts';
 export { auditTail, auditVerify, markdownCell } from './operate/audit.ts';
 export { attachFile } from './operate/attach.ts';

package/src/cli/endpoint-url.ts

@@ -17,7 +17,52 @@ import type { Config, DeployConfig } from '#profile';
  */
 export async function endpointUrl(config: Config, target: string): Promise<string> {
   const deployed = await deployedUrl(config.targets[target]?.deploy);
-  return deployed ?? `http://${config.instance.host}:${config.instance.port}/mcp`;
+  return deployed ?? localUrl(config);
+}
+
+/**
+ * Where `lanes link start` would listen, from config alone.
+ *
+ * Split out so a caller that has already asked `deployedUrl` can name the
+ * fallback without asking again — `endpointUrl` is the two together, and going
+ * through it after a null costs a second `gcloud run services describe` that is
+ * already known to answer nothing.
+ */
+export function localUrl(config: Config): string {
+  return `http://${config.instance.host}:${config.instance.port}/mcp`;
+}
+
+/**
+ * Who is answering at this URL, if anyone.
+ *
+ * Shared for the reason `endpointUrl` above is: two workspaces can assign the
+ * same port, so an endpoint answering is not the same as *this* profile's
+ * endpoint answering. A command that skips this check reports another
+ * workspace's surface under this profile's heading.
+ *
+ * Anonymous would be enough to prove a socket is bound, but the profile list is
+ * behind the token, and the profile is the whole point of asking.
+ */
+export async function endpointHealth(url: string, token: string): Promise<EndpointHealth | null> {
+  try {
+    const probe = new URL(url);
+    probe.pathname = '/health';
+    const response = await fetch(probe, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(700),
+    });
+    if (!response.ok) return null;
+
+    const body = (await response.json()) as Partial<EndpointHealth>;
+    return body.profile ? { profile: body.profile, profiles: body.profiles ?? [body.profile] } : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface EndpointHealth {
+  readonly profile: string;
+  readonly profiles: readonly string[];
 }
 
 /**

package/src/cli/main.ts

@@ -14,6 +14,7 @@ import {
   status,
   tokenRotate,
   tokenShow,
+  tools,
 } from './commands/operate.ts';
 import { profileAdd, profileDefault, profileList } from './commands/profile.ts';
 import { removeProfile as profileRemove } from './commands/profile/remove.ts';
@@ -250,6 +251,13 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'outputs':
       return outputs({ ...global, show, json });
 
+    // Beside `outputs` because it answers the next question. `outputs` says
+    // where the endpoint is; this says what it would hand a client that asked
+    // right now — which is the only way to tell a stale client from a wrong
+    // endpoint without reading request sizes out of a log.
+    case 'tools':
+      return tools({ ...global, json });
+
     // Undocumented alias for `mcp skill`, which is where it moved when `skills`
     // arrived. Anyone who learned the old spelling keeps it.
     case 'skill':

package/src/cli/publish.ts

@@ -29,6 +29,14 @@ export interface PublishOutcome {
   readonly published?: string;
   /** Whether a running endpoint confirmed it is now serving the edit. */
   readonly served: boolean;
+  /**
+   * How many tools the endpoint advertises now, when it answered.
+   *
+   * Reported rather than inferred, for the same reason `served` is: the number
+   * that matters is the one the endpoint would hand a client, and only the
+   * endpoint knows it.
+   */
+  readonly tools?: number;
   /** The endpoint that was told, or would have been. */
   readonly url?: string;
   /** Why it is not being served yet, in a form fit to print. */
@@ -142,7 +150,11 @@ async function notifyReload(input: {
       return { served: false, url, reason: `the endpoint answered ${response.status}` };
     }
 
-    const body = (await response.json()) as { reloaded?: unknown; reason?: unknown };
+    const body = (await response.json()) as {
+      reloaded?: unknown;
+      reason?: unknown;
+      tools?: unknown;
+    };
     if (body.reloaded !== true) {
       return {
         served: false,
@@ -154,7 +166,11 @@ async function notifyReload(input: {
       };
     }
 
-    return { served: true, url };
+    return {
+      served: true,
+      url,
+      ...(typeof body.tools === 'number' ? { tools: body.tools } : {}),
+    };
   } catch {
     // Nothing listening, scaled to zero, or unreachable from here — all of
     // which resolve themselves the next time the endpoint starts, because the
@@ -175,7 +191,34 @@ function message(error: unknown): string {
  * is now: the endpoint either answered or it did not.
  */
 export function nextAfterEdit(outcome: PublishOutcome): string {
-  if (outcome.served) return 'Serving it now — the endpoint has re-read its config.';
+  if (outcome.served) {
+    const served = 'Serving it now — the endpoint has re-read its config.';
+    if (outcome.tools === undefined) return served;
+
+    // The second half of the truth, and the half an operator is actually
+    // looking at. The endpoint re-reading its config is not the same event as
+    // the client in front of them learning about it: a client fetches
+    // `tools/list` when it connects and holds the answer, and this endpoint
+    // cannot tell it otherwise — it is stateless, so there is no stream on
+    // which to send `notifications/tools/list_changed`, and it no longer claims
+    // there is (ADR-032).
+    //
+    // So the tool count goes here, where the change happened, and so does the
+    // one action that picks it up. Without this line the command reports
+    // success and the operator watches a connector that never changes.
+    //
+    // Worded for either direction, because `policy deny` prints this too and a
+    // deny is the case this file already calls "the one kind of staleness worth
+    // being strict about". "Pick them up" was written for a `connect` and read
+    // as nonsense after a deny, where the client is holding one tool too many
+    // rather than one too few — and where the stale entry is a tool the model
+    // will keep calling until it is gone.
+    return (
+      `${served}\n` +
+      `  ${outcome.tools} tools are advertised now. A client connected before this is still\n` +
+      `  holding the list it fetched then — reconnect it to match.`
+    );
+  }
 
   // Naming the URL, because the likeliest reason nothing answered is that the
   // endpoint is somewhere else: `lanes link start --port` moves the socket

package/src/cli/usage.ts

@@ -84,6 +84,7 @@ ${style.bold('Deploying')}
 ${style.bold('Inspection')}
   ${PROGRAM} check                      static validation, no external calls
   ${PROGRAM} doctor [--json]            credentials resolve, stores reachable
+  ${PROGRAM} tools [--json]             what the endpoint advertises to a client
   ${PROGRAM} plan                       what reconcile would change
   ${PROGRAM} audit tail [--limit N] [--denied-only] [--format md]
   ${PROGRAM} audit verify           has anything in the log been altered or removed

package/src/deployments/deploy.ts

@@ -211,11 +211,38 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   print(`  ${url}/mcp`);
   print(await healthLine(url));
   print('');
-  print(style.dim(`  Register it with: lanes link outputs --target ${target}`));
+  print(registerLine(target));
 
   reportUnauthorised(prepared.warnings, target);
 }
 
+/**
+ * How to register the endpoint, and when.
+ *
+ * The ordering is the whole point of the second half. A client captures
+ * `tools/list` when it connects and keeps it: this endpoint is stateless, so
+ * there is no stream on which to send `notifications/tools/list_changed`, and
+ * `buildMcpServer` no longer pretends otherwise. A first deploy necessarily
+ * publishes a profile whose only connection is `setup.main` — the accounts come
+ * after — so a connector registered in that window captures a two-tool surface
+ * and holds it. The endpoint is right, every reload lands, and the client shows
+ * two tools until someone removes and re-adds it.
+ *
+ * Unconditional, and that is the correction that matters. This was gated on
+ * `prepared.warnings.length`, which is zero in precisely the case it describes:
+ * a fresh profile declares only `setup.main`, `setup` is a local provider with
+ * no credential, so `prepareSecrets` has nothing to warn about. The advice
+ * appeared only on a later re-deploy, by which point the connector is usually
+ * registered and the ordering is no longer available to get right.
+ */
+function registerLine(target: string): string {
+  return style.dim(
+    `  Connect your accounts first, then register with: lanes link outputs --target ${target}\n` +
+      '  A client keeps the tool list it fetched when it connected, so one registered\n' +
+      '  before the accounts holds a surface without them until it is re-added.',
+  );
+}
+
 /**
  * The accounts a browser still has to authorise, and the step after them.
  *

package/src/server/endpoint.ts

@@ -267,7 +267,13 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
           close: () => closeAll(reopened.runtimes).then(() => {}),
         };
       },
-      { primary: primary.resolution.profile, log: { debug() {}, info() {}, warn() {}, error() {} } },
+      // The same logger the request handler gets, rather than the inline no-op
+      // this used to be. What a generation has to say is exactly what nobody
+      // could see when a reload went wrong: `could not reload config`, `could
+      // not refresh skills`, and every `mcp handler error` the endpoint raises
+      // all went to those empty methods. A silent endpoint is not a quiet one —
+      // it is one whose failures have to be reconstructed from request sizes.
+      { primary: primary.resolution.profile, log: options.log ?? silentLogger() },
     );
 
     const server = serve({
@@ -282,6 +288,10 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       ...(options.host !== undefined ? { host: options.host } : {}),
     });
 
+    // After `serve()`, so the record means the socket is bound. Recording it
+    // from the constructor claimed an endpoint that a failed bind never served.
+    generations.announce();
+
     return {
       url: server.url,
       profiles: [...runtimes.keys()],

package/src/server/generation.ts

@@ -0,0 +1,217 @@
+import { createMcpHandler, type McpHttpHandler, type McpRequestContext } from '@modelcontextprotocol/server';
+import { ownerPrincipal, type Principal } from '#auth';
+import {
+  buildMcpServer,
+  toolNameFor,
+  visibleCapabilities,
+  visibleToolCount,
+  type ProfileRuntime,
+} from '#server/mcp';
+import type { GenerationDeps, OpenedWorkspace } from './generations.ts';
+
+/**
+ * One boot's worth of runtimes, and everything derived from them.
+ *
+ * Immutable in what it serves. The memos inside still recompute on
+ * `registry.revision`, because skills can be replaced *within* a generation
+ * (ADR-014) — that is the one mutable surface the registry has, and it predates
+ * this.
+ *
+ * Lives beside `generations.ts` rather than in it: that file is about which
+ * generation is current and what a reload does to it, and this one is about
+ * what a generation holds. Neither needs the other's detail.
+ */
+export class Generation {
+  readonly epoch: number;
+  readonly profiles: ReadonlyMap<string, ProfileRuntime>;
+
+  readonly #opened: OpenedWorkspace;
+  readonly #deps: GenerationDeps;
+  readonly #handlers = new Map<string, McpHttpHandler>();
+
+  /** In-flight requests pinned to this generation. */
+  #pins = 0;
+  /** Replaced by a newer generation, so it closes when the last pin drops. */
+  #retired = false;
+  #closed = false;
+
+  /** How stale a registry may be before the next request re-reads its skills. */
+  static readonly SKILL_POLL_MS = 2_000;
+  #polledAt = 0;
+
+  /**
+   * Every capability id across every profile, granted or not.
+   *
+   * Used only to spell a refusal correctly: a tool that exists but is not
+   * permitted should appear in the audit under its real id.
+   */
+  readonly allCapabilityIds: () => readonly string[];
+
+  /**
+   * Wire names the endpoint advertises.
+   *
+   * M1 has a single principal per profile, so this set does not vary by caller.
+   * When delegated principals arrive it becomes a per-principal lookup; the call
+   * site already reads as one.
+   */
+  readonly visible: () => ReadonlySet<string>;
+
+  /**
+   * How many tools this generation advertises (ADR-032).
+   *
+   * Not `visible().size`: that set spans every reachable capability, and a
+   * resource or a prompt is in it without being in `tools/list`.
+   */
+  readonly toolCount: () => number;
+
+  constructor(epoch: number, opened: OpenedWorkspace, deps: GenerationDeps) {
+    this.epoch = epoch;
+    this.profiles = opened.profiles;
+    this.#opened = opened;
+    this.#deps = deps;
+
+    this.allCapabilityIds = this.#memo(() => [
+      ...new Set(
+        [...this.profiles.values()].flatMap((runtime) =>
+          runtime.registry.capabilities().map(({ id }) => id),
+        ),
+      ),
+    ]);
+
+    this.visible = this.#memo(
+      () =>
+        new Set(
+          visibleCapabilities({
+            profiles: this.profiles,
+            principal: ownerPrincipal(deps.primary),
+          }).map(toolNameFor),
+        ),
+    );
+
+    this.toolCount = this.#memo(() =>
+      visibleToolCount({ profiles: this.profiles, principal: ownerPrincipal(deps.primary) }),
+    );
+  }
+
+  /** The profile names this generation serves, in declaration order. */
+  names(): string[] {
+    return [...this.profiles.keys()];
+  }
+
+  pin(): void {
+    this.#pins += 1;
+  }
+
+  /** Drop a pin, closing the generation if it was retired and this was the last. */
+  async unpin(): Promise<void> {
+    this.#pins -= 1;
+    if (this.#retired && this.#pins <= 0) await this.close();
+  }
+
+  /** Mark superseded. Closes immediately when nothing is using it. */
+  async retire(): Promise<void> {
+    this.#retired = true;
+    if (this.#pins <= 0) await this.close();
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+
+    await Promise.all([...this.#handlers.values()].map((handler) => handler.close()));
+    this.#handlers.clear();
+    await this.#opened.close();
+  }
+
+  /**
+   * Work derived from the registries, recomputed when one of them changes.
+   *
+   * Skills can be replaced in a registry (ADR-014), and a stale `visible()` is
+   * not cosmetic: it gates the refusal-audit path, so a newly added skill would
+   * be recorded as a refusal on its first `prompts/get` even though the call
+   * succeeded.
+   */
+  #generation(): number {
+    return [...this.profiles.values()].reduce(
+      (total, runtime) => total + runtime.registry.revision,
+      0,
+    );
+  }
+
+  #memo<T>(compute: () => T): () => T {
+    let at = -1;
+    let value: T;
+    return () => {
+      const now = this.#generation();
+      if (now !== at) {
+        value = compute();
+        at = now;
+      }
+      return value;
+    };
+  }
+
+  /**
+   * Re-read the skills, at most once per poll interval.
+   *
+   * A skill written elsewhere — `lanes link skills add` in another terminal —
+   * cannot announce itself, so the endpoint has to look. Bounded rather than
+   * per-request because looking costs a `list()`, which on S3 is a network call.
+   * A write made *through* MCP does not wait for this; it refreshes directly.
+   */
+  async refreshSkills(): Promise<void> {
+    const now = Date.now();
+    if (now - this.#polledAt < Generation.SKILL_POLL_MS) return;
+    this.#polledAt = now;
+
+    await Promise.all(
+      [...this.profiles.values()].map(async (runtime) => {
+        try {
+          await runtime.refreshSkills?.();
+        } catch (error) {
+          // A skills directory that has gone unreadable, or one skill file
+          // someone is mid-edit, must not take the endpoint down with it. The
+          // previously loaded skills stay registered.
+          this.#deps.log.warn('could not refresh skills', { message: (error as Error).message });
+        }
+      }),
+    );
+  }
+
+  /**
+   * One handler per (principal, client label), memoised within this generation.
+   *
+   * The MCP surface depends only on resolved policy, so rebuilding the wiring
+   * per request would be pure waste. Reuse is safe because `createMcpHandler`
+   * still constructs a fresh server instance per request — what is memoised is
+   * the factory wiring, never session state. Memoised *here* rather than on the
+   * request handler because the factory closes over this generation's profiles:
+   * a handler outliving its generation is the stale-config bug.
+   */
+  handlerFor(principal: Principal, clientLabel: string | undefined): McpHttpHandler {
+    const key = `${principal.id}\u0000${clientLabel ?? ''}`;
+    const existing = this.#handlers.get(key);
+    if (existing) return existing;
+
+    const handler = createMcpHandler(
+      // The principal is closed over rather than read back out of `authInfo`:
+      // this handler is already keyed on it, and re-deriving identity from a
+      // field the SDK treats as opaque pass-through would create a second
+      // source of truth for who is calling.
+      (_context: McpRequestContext) =>
+        buildMcpServer({
+          profiles: this.profiles,
+          principal,
+          clientLabel,
+          ...(this.#deps.version ? { version: this.#deps.version } : {}),
+        }),
+      {
+        onerror: (error: Error) =>
+          this.#deps.log.error('mcp handler error', { message: error.message }),
+      },
+    );
+
+    this.#handlers.set(key, handler);
+    return handler;
+  }
+}

package/src/server/generations.ts

@@ -1,20 +1,15 @@
-import {
-  createMcpHandler,
-  type McpHttpHandler,
-  type McpRequestContext,
-} from '@modelcontextprotocol/server';
-import { ownerPrincipal, type Principal } from '#auth';
 import type { Logger } from '#connectivity';
 import { clearUpstreamTokens } from '#connectivity/auth/index.ts';
-import {
-  buildMcpServer,
-  toolNameFor,
-  visibleCapabilities,
-  type ProfileRuntime,
-} from '#server/mcp';
+import type { ProfileRuntime } from '#server/mcp';
+import { Generation } from './generation.ts';
 
 /**
- * Which runtimes are current, and when the ones they replaced are closed.
+ * Which generation is current, and the reload that replaces it.
+ *
+ * The generation itself — one boot's runtimes and every cache derived from
+ * them — is `generation.ts`. Split when this file outgrew its budget, along the
+ * seam it already had: what a generation *is* is a different subject from when
+ * one is swapped, and only the latter needs to know about reloading at all.
  *
  * This is a different subject from what an HTTP request does, which is why it
  * is not in `index.ts`. The endpoint used to hold one map of profile runtimes
@@ -59,202 +54,18 @@ export interface GenerationDeps {
   readonly version?: string | undefined;
 }
 
-/**
- * One boot's worth of runtimes, and everything derived from them.
- *
- * Immutable in what it serves. The memos inside still recompute on
- * `registry.revision`, because skills can be replaced *within* a generation
- * (ADR-014) — that is the one mutable surface the registry has, and it predates
- * this.
- */
-export class Generation {
-  readonly epoch: number;
-  readonly profiles: ReadonlyMap<string, ProfileRuntime>;
-
-  readonly #opened: OpenedWorkspace;
-  readonly #deps: GenerationDeps;
-  readonly #handlers = new Map<string, McpHttpHandler>();
-
-  /** In-flight requests pinned to this generation. */
-  #pins = 0;
-  /** Replaced by a newer generation, so it closes when the last pin drops. */
-  #retired = false;
-  #closed = false;
-
-  /** How stale a registry may be before the next request re-reads its skills. */
-  static readonly SKILL_POLL_MS = 2_000;
-  #polledAt = 0;
-
-  /**
-   * Every capability id across every profile, granted or not.
-   *
-   * Used only to spell a refusal correctly: a tool that exists but is not
-   * permitted should appear in the audit under its real id.
-   */
-  readonly allCapabilityIds: () => readonly string[];
-
-  /**
-   * Wire names the endpoint advertises.
-   *
-   * M1 has a single principal per profile, so this set does not vary by caller.
-   * When delegated principals arrive it becomes a per-principal lookup; the call
-   * site already reads as one.
-   */
-  readonly visible: () => ReadonlySet<string>;
-
-  constructor(epoch: number, opened: OpenedWorkspace, deps: GenerationDeps) {
-    this.epoch = epoch;
-    this.profiles = opened.profiles;
-    this.#opened = opened;
-    this.#deps = deps;
-
-    this.allCapabilityIds = this.#memo(() => [
-      ...new Set(
-        [...this.profiles.values()].flatMap((runtime) =>
-          runtime.registry.capabilities().map(({ id }) => id),
-        ),
-      ),
-    ]);
-
-    this.visible = this.#memo(
-      () =>
-        new Set(
-          visibleCapabilities({
-            profiles: this.profiles,
-            principal: ownerPrincipal(deps.primary),
-          }).map(toolNameFor),
-        ),
-    );
-  }
-
-  /** The profile names this generation serves, in declaration order. */
-  names(): string[] {
-    return [...this.profiles.keys()];
-  }
-
-  pin(): void {
-    this.#pins += 1;
-  }
-
-  /** Drop a pin, closing the generation if it was retired and this was the last. */
-  async unpin(): Promise<void> {
-    this.#pins -= 1;
-    if (this.#retired && this.#pins <= 0) await this.close();
-  }
-
-  /** Mark superseded. Closes immediately when nothing is using it. */
-  async retire(): Promise<void> {
-    this.#retired = true;
-    if (this.#pins <= 0) await this.close();
-  }
-
-  async close(): Promise<void> {
-    if (this.#closed) return;
-    this.#closed = true;
-
-    await Promise.all([...this.#handlers.values()].map((handler) => handler.close()));
-    this.#handlers.clear();
-    await this.#opened.close();
-  }
-
-  /**
-   * Work derived from the registries, recomputed when one of them changes.
-   *
-   * Skills can be replaced in a registry (ADR-014), and a stale `visible()` is
-   * not cosmetic: it gates the refusal-audit path, so a newly added skill would
-   * be recorded as a refusal on its first `prompts/get` even though the call
-   * succeeded.
-   */
-  #generation(): number {
-    return [...this.profiles.values()].reduce(
-      (total, runtime) => total + runtime.registry.revision,
-      0,
-    );
-  }
-
-  #memo<T>(compute: () => T): () => T {
-    let at = -1;
-    let value: T;
-    return () => {
-      const now = this.#generation();
-      if (now !== at) {
-        value = compute();
-        at = now;
-      }
-      return value;
-    };
-  }
-
-  /**
-   * Re-read the skills, at most once per poll interval.
-   *
-   * A skill written elsewhere — `lanes link skills add` in another terminal —
-   * cannot announce itself, so the endpoint has to look. Bounded rather than
-   * per-request because looking costs a `list()`, which on S3 is a network call.
-   * A write made *through* MCP does not wait for this; it refreshes directly.
-   */
-  async refreshSkills(): Promise<void> {
-    const now = Date.now();
-    if (now - this.#polledAt < Generation.SKILL_POLL_MS) return;
-    this.#polledAt = now;
-
-    await Promise.all(
-      [...this.profiles.values()].map(async (runtime) => {
-        try {
-          await runtime.refreshSkills?.();
-        } catch (error) {
-          // A skills directory that has gone unreadable, or one skill file
-          // someone is mid-edit, must not take the endpoint down with it. The
-          // previously loaded skills stay registered.
-          this.#deps.log.warn('could not refresh skills', { message: (error as Error).message });
-        }
-      }),
-    );
-  }
-
-  /**
-   * One handler per (principal, client label), memoised within this generation.
-   *
-   * The MCP surface depends only on resolved policy, so rebuilding the wiring
-   * per request would be pure waste. Reuse is safe because `createMcpHandler`
-   * still constructs a fresh server instance per request — what is memoised is
-   * the factory wiring, never session state. Memoised *here* rather than on the
-   * request handler because the factory closes over this generation's profiles:
-   * a handler outliving its generation is the stale-config bug.
-   */
-  handlerFor(principal: Principal, clientLabel: string | undefined): McpHttpHandler {
-    const key = `${principal.id}\u0000${clientLabel ?? ''}`;
-    const existing = this.#handlers.get(key);
-    if (existing) return existing;
-
-    const handler = createMcpHandler(
-      // The principal is closed over rather than read back out of `authInfo`:
-      // this handler is already keyed on it, and re-deriving identity from a
-      // field the SDK treats as opaque pass-through would create a second
-      // source of truth for who is calling.
-      (_context: McpRequestContext) =>
-        buildMcpServer({
-          profiles: this.profiles,
-          principal,
-          clientLabel,
-          ...(this.#deps.version ? { version: this.#deps.version } : {}),
-        }),
-      {
-        onerror: (error: Error) =>
-          this.#deps.log.error('mcp handler error', { message: error.message }),
-      },
-    );
-
-    this.#handlers.set(key, handler);
-    return handler;
-  }
-}
-
 /** What a reload did, as the `/reload` route reports it. */
 export interface ReloadResult {
   readonly reloaded: boolean;
   readonly epoch: number;
   readonly profiles: readonly string[];
+  /**
+   * How many tools the generation now serving advertises (ADR-032).
+   *
+   * What `connect` prints: the edit landing and the surface a client sees are
+   * different events, and the gap is where a stale tool list hides.
+   */
+  readonly tools: number;
   /** Why it did not reload. Absent on success. */
   readonly reason?: string;
 }
@@ -280,6 +91,29 @@ export class Generations {
     this.#deps = deps;
   }
 
+  /**
+   * Record what the current generation advertises.
+   *
+   * Called by the endpoint once the socket is bound, not from the constructor
+   * where it used to be: a `serving` record written before `serve()` returns is
+   * a claim about an endpoint that a failed bind means never served, and a
+   * crash-looping revision emitted one per attempt. `advertising` rather than
+   * `serving` because the container writes its own `serving <url>` to the same
+   * stream, and one word covering two different records is a filter that
+   * returns both and distinguishes neither.
+   *
+   * The boot emission is the more useful of the two: a fresh revision comes up
+   * holding whatever config held at deploy time — often one `setup.main` and
+   * two tools — and a client registered in that window keeps what it was
+   * handed. This is what makes that window visible afterwards (ADR-032).
+   */
+  announce(): void {
+    this.#deps.log.info('advertising', {
+      epoch: this.#current.epoch,
+      tools: this.#current.toolCount(),
+    });
+  }
+
   get current(): Generation {
     return this.#current;
   }
@@ -330,6 +164,7 @@ export class Generations {
         reloaded: false,
         epoch: previous.epoch,
         profiles: previous.names(),
+        tools: previous.toolCount(),
         reason,
       };
     }
@@ -337,21 +172,44 @@ export class Generations {
     this.#epoch += 1;
     this.#current = new Generation(this.#epoch, opened, this.#deps);
 
-    // Module-global and keyed per connection, so it survives a reload that
-    // replaced everything else. Re-connecting `<provider>.<id>` to a different
-    // account would otherwise serve the previous account's access token until
-    // it expired — up to an hour after the config said otherwise. Unchanged
-    // connections pay one refresh.
-    clearUpstreamTokens();
+    // Past this line the reload has *landed*: the new generation is what
+    // requests get. Everything below is tidying and reporting, and none of it
+    // can un-land the swap — so a throw here must not be reported as a failed
+    // reload. It would be: `/reload` has no try/catch of its own, so the
+    // exception becomes a 500, and `connect` reads that as "saved, and the
+    // endpoint will serve this when it next starts" for config the endpoint is
+    // already serving. `previous.retire()` closes the audit log, which on a
+    // cloud target is a network write, so this is reachable rather than
+    // theoretical.
+    try {
+      // Module-global and keyed per connection, so it survives a reload that
+      // replaced everything else. Re-connecting `<provider>.<id>` to a different
+      // account would otherwise serve the previous account's access token until
+      // it expired — up to an hour after the config said otherwise. Unchanged
+      // connections pay one refresh.
+      clearUpstreamTokens();
+
+      // After the swap: a request arriving during the retire already gets the
+      // new generation, and this only waits on requests that started before it.
+      await previous.retire();
+    } catch (error) {
+      this.#deps.log.error('reload landed, but retiring the previous generation failed', {
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+
+    const tools = this.#current.toolCount();
 
-    // After the swap: a request arriving during the retire already gets the new
-    // generation, and this only waits on requests that started before it.
-    await previous.retire();
+    // The only record of what the endpoint advertises: `tools/list` is neither
+    // logged nor audited, so nothing else could tell a generation serving two
+    // tools from one serving forty. Once per reload, on a memoised read.
+    this.#deps.log.info('advertising', { epoch: this.#current.epoch, tools });
 
     return {
       reloaded: true,
       epoch: this.#current.epoch,
       profiles: this.#current.names(),
+      tools,
     };
   }
 

package/src/server/harness.ts

@@ -252,6 +252,11 @@ export function startHarness(options: HarnessOptions): Harness {
     log,
   });
 
+  // As `startEndpoint` does, and after `serve()` for the same reason: the
+  // record means the socket is bound. Here because this harness claims to be
+  // the real wiring, and a boot step it omits is a boot step no test can see.
+  generations.announce();
+
   return {
     server,
     state,

package/src/server/index.ts

@@ -3,7 +3,8 @@ import type { Logger } from '#connectivity';
 import { capabilityIdForToolName } from '#server/mcp';
 import { ATTACHMENTS_PATH, stageAttachment } from './attachments.ts';
 import { allowedHostnamesFor, rebindingRefusal } from './rebinding.ts';
-import type { Generation, Generations } from './generations.ts';
+import type { Generation } from './generation.ts';
+import type { Generations } from './generations.ts';
 import { callerKey, failedAuthLimiter, FAILED_AUTH_PER_MINUTE, tooManyAttempts } from './edge.ts';
 import {
   handleAuthorization,

package/src/server/mcp/build.ts

@@ -45,7 +45,42 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
     // Second argument, not the first: `instructions` is a `ServerOptions` field,
     // and `Implementation` would take it as an unknown extra and drop it from
     // `initialize` without complaining.
-    { instructions: serverInstructions(names, merged) },
+    {
+      instructions: serverInstructions(names, merged),
+      // Declared `false` because it is false, and the SDK defaults it to `true`.
+      //
+      // `listChanged` is a promise to send `notifications/tools/list_changed`
+      // when the surface changes. This endpoint cannot keep it: it is stateless
+      // streamable HTTP, so there is no stream to deliver a notification on and
+      // this very server instance is discarded once the response is written.
+      // Nothing in `src/` sends one, and nothing can.
+      //
+      // Leaving the default on is not a harmless inaccuracy. A client that
+      // believes it will be told has no reason to ask again, so it keeps the
+      // list it captured when it first connected — and the surface here grows
+      // every time an account is connected (ADR-029). That combination cost a
+      // connector registered before `connect` ran its whole tool list: it held
+      // the two setup tools for as long as it lived, and no refresh replaced
+      // them, because the refresh was an `initialize` that never went on to ask
+      // for `tools/list`.
+      //
+      // Saying `false` costs a re-list per session and buys a surface that is
+      // never stale.
+      //
+      // `tools` unconditionally, because the argument above is about tools and
+      // an endpoint that serves none should still answer "none right now"
+      // rather than "this server does not do tools". Resources and prompts only
+      // when the profile has some: declaring a capability installs its handler
+      // set, so a client that gates its list calls on what is advertised would
+      // otherwise issue `resources/list`, `resources/templates/list` and
+      // `prompts/list` — three stateless POSTs, each rebuilding the whole
+      // server — to be told nothing is there.
+      capabilities: {
+        tools: { listChanged: false },
+        ...(offers(merged, isResource) ? { resources: { listChanged: false } } : {}),
+        ...(offers(merged, isPrompt) ? { prompts: { listChanged: false } } : {}),
+      },
+    },
   );
 
   for (const [id, entry] of merged) {
@@ -66,3 +101,22 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
 
   return server;
 }
+
+/**
+ * Whether any reachable capability registers as this kind.
+ *
+ * Reads the same `merged` map the registration loop below consumes and asks it
+ * the same question `isResource`/`isPrompt` answer there, so what is advertised
+ * and what is registered cannot disagree. A discovered capability is always a
+ * tool, which is why it is not consulted here.
+ */
+function offers(
+  merged: ReturnType<typeof mergeCapabilities>,
+  kind: typeof isResource | typeof isPrompt,
+): boolean {
+  for (const entry of merged.values()) {
+    if (!entry.discovered && entry.capability && kind(entry.capability)) return true;
+  }
+
+  return false;
+}

package/src/server/mcp/index.ts

@@ -26,6 +26,7 @@ export {
   mergeCapabilities,
   oneProfile,
   visibleCapabilities,
+  visibleToolCount,
   type BuildServerOptions,
   type MergedCapability,
   type ProfileRuntime,

package/src/server/mcp/visibility.ts

@@ -1,3 +1,4 @@
+import { isTool } from '#connectivity';
 import type { Principal } from '#auth';
 import type { Config } from '#profile';
 import type { ProviderRegistry } from '#registry';
@@ -114,6 +115,27 @@ export function visibleCapabilities(options: BuildServerOptions): string[] {
   return [...mergeCapabilities(options).keys()];
 }
 
+/**
+ * How many of those are tools, as `tools/list` would count them.
+ *
+ * Not the same number as `visibleCapabilities().length`, and the difference is
+ * the kind of thing that only shows up when someone reads it: a reachable
+ * capability may register as a resource or a prompt instead, so counting ids
+ * and calling the answer "tools" overstates the list by however many of those
+ * a profile has. The kind is decided here exactly as `buildMcpServer` decides
+ * it — a discovered capability is always a tool, an authored one is asked.
+ */
+export function visibleToolCount(options: BuildServerOptions): number {
+  let count = 0;
+
+  for (const entry of mergeCapabilities(options).values()) {
+    if (entry.discovered) count += 1;
+    else if (entry.capability && isTool(entry.capability)) count += 1;
+  }
+
+  return count;
+}
+
 /**
  * Say which accounts are reachable, grouped by profile.
  *