@lanes-sh/link 0.1.0 → 0.1.2

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,