@animalabs/agent-framework 0.7.4 → 0.9.0

package/src/mcpl/server-connection.ts

@@ -12,6 +12,9 @@
 import { EventEmitter } from 'node:events';
 
 import { openTransport, type McplTransport, type TransportCloseInfo } from './transport.js';
+import { maskNegotiatedCapabilities } from './capability-mask.js';
+import { CapabilityGrant, expandAdvertisementShorthand } from './capability-grant.js';
+import { CAPABILITY_DISABLED } from './errors.js';
 
 import type {
   McplServerConfig,
@@ -21,10 +24,10 @@ import type {
   JsonRpcResponse,
   BeforeInferenceParams,
   BeforeInferenceResult,
-  AfterInferenceParams,
-  AfterInferenceResult,
   FeatureSetsUpdateParams,
+  FeatureSetsUpdateResult,
   InferenceChunkParams,
+  InferenceLifecycleParams,
   StateRollbackParams,
   StateRollbackResult,
   ChannelsOpenParams,
@@ -88,7 +91,6 @@ interface RequestOptions {
  * - `'channels-register'`  — Server sent `channels/register`
  * - `'channels-changed'`   — Server sent `channels/changed`
  * - `'channels-incoming'`  — Server sent `channels/incoming`
- * - `'feature-sets-changed'` — Server sent `featureSets/changed`
  * - `'error'`              — Connection-level error
  * - `'close'`              — Connection closed
  * - `'connect-failed'`     — Initial connect failed; background retry scheduled
@@ -99,9 +101,77 @@ export class McplServerConnection extends EventEmitter {
   /** Unique server identifier from config. */
   readonly id: string;
 
-  /** MCPL capabilities negotiated during the initialize handshake, or null if the server does not support MCPL. */
+  /** MCPL capabilities negotiated during the initialize handshake — after
+   *  host-side capability scoping (enabledCapabilities/disabledCapabilities)
+   *  — or null if the server does not support MCPL. */
   capabilities: McplCapabilities | null;
 
+  /** Dotted paths of advertised capabilities the host config masked at the
+   *  last handshake (empty when no scoping is configured). Inbound methods
+   *  gated by a masked capability are rejected in setupMessageRouting. */
+  droppedCapabilities: ReadonlySet<string> = new Set();
+
+  /** OUTER standard MCP capabilities.tools was present at handshake (§5.1 —
+   *  the sole source of the `tools` capability path). */
+  mcpToolsAdvertised = false;
+
+  /** Host-owned per-server authority for host/command (config
+   *  allowHostCommands, default false). No capability path exists and the
+   *  grant cannot confer it — server params never decide admin authority. */
+  allowHostCommands = false;
+
+  /**
+   * The effective capability grant (§5.4) — the sole authorization
+   * allowlist for this connection. Starts EMPTY: until the initial policy
+   * exchange completes (§5.3) nothing is granted and every privileged
+   * inbound method is rejected. The framework computes the grant from the
+   * masked advertisement and activates it via establishGrant() only after
+   * the featureSets/update Request is answered (expansion activates on
+   * receipt, §6.7); revocations re-call establishGrant() BEFORE the
+   * corresponding Request is sent (reduction applies first, §6.7).
+   */
+  grant: CapabilityGrant = CapabilityGrant.empty();
+
+  /** True once the §5.3 initial policy Request has been answered. */
+  policyEstablished = false;
+
+  /**
+   * §17 manifest tracking (host side of RFC-003): what this host actually
+   * fetched and acted on — never the server's announcement log (§17.10:
+   * those are different facts). Read by the legibility surface.
+   */
+  manifestState: {
+    /** revision of the last VALIDATED fetched manifest (server-authored,
+     *  untrusted, equality-only) — null until a §17.4 fetch succeeds. */
+    lastValidatedRevision: string | null;
+    lastFetchedAt: number | null;
+    /** epoch ms of the last §6.7 receipt that activated a grant change. */
+    lastNegotiatedAt: number | null;
+  } = { lastValidatedRevision: null, lastFetchedAt: null, lastNegotiatedAt: null };
+
+  /**
+   * Activate (or replace) the effective grant. Ordering is the caller's
+   * contract per §6.7: call BEFORE sending a reducing featureSets/update,
+   * AFTER the receipt for an expanding one.
+   */
+  establishGrant(grant: CapabilityGrant): void {
+    this.grant = grant;
+    this.policyEstablished = true;
+  }
+
+  /** A §5.3 grant belongs to one initialized transport epoch. Reconnecting
+   * performs a fresh initialize handshake, so authority from the dead epoch
+   * must be revoked before the replacement transport is exposed. */
+  private resetPolicyForTransportBoundary(): void {
+    this.grant = CapabilityGrant.empty();
+    this.policyEstablished = false;
+    // §17 tracking is per-epoch for the same reason the grant is: these are
+    // facts about what THIS host fetched/negotiated on THIS initialized
+    // transport, and a fresh initialize starts a fresh manifest history
+    // (Sol, PR #84 review — they previously survived into the new epoch).
+    this.manifestState = { lastValidatedRevision: null, lastFetchedAt: null, lastNegotiatedAt: null };
+  }
+
   /** The active transport (stdio child or WebSocket). Null for a disconnected
    *  stub awaiting its first background reconnect. */
   private transport: McplTransport | null;
@@ -197,18 +267,15 @@ export class McplServerConnection extends EventEmitter {
   readyControlPlane(): void {
     this.controlPlaneReady = true;
     const pending = this.bufferedEvents;
-    const deferred: Array<{ event: string; args: unknown[] }> = [];
     this.bufferedEvents = [];
     for (const item of pending) {
-      if (McplServerConnection.isControlPlaneEvent(item.event)) {
-        super.emit(item.event, ...item.args);
-      } else {
-        deferred.push(item);
-      }
+      // Re-enter the ADMISSION gate (this.emit), never super.emit: control
+      // events include channels-register/changed, which are grant-gated —
+      // the old direct flush bypassed positive-grant enforcement entirely
+      // (PR #79 review blocker 3). Data-plane items re-buffer in order via
+      // the same call, since dataPlaneReady is still false.
+      this.emit(item.event, ...item.args);
     }
-    // Data events emitted by control handlers while the snapshot was flushing
-    // were appended to the new buffer. Preserve their order behind older data.
-    this.bufferedEvents = [...deferred, ...this.bufferedEvents];
   }
 
   /**
@@ -233,18 +300,62 @@ export class McplServerConnection extends EventEmitter {
         ? this.controlPlaneReady
         : this.dataPlaneReady)
     ) {
+      // Positive-grant admission (§5.4/§14.1), at the single choke-point
+      // every path shares: live routing AND buffer flushes re-enter here, so
+      // an event buffered while the connection was staged is authorized
+      // against the grant current at ADMISSION — by which time the §5.3
+      // policy exchange has settled. Rejecting earlier (at line receipt)
+      // answered staged traffic with -32002 before the grant existed, which
+      // both bounced conforming servers' startup pushes and made a FAILED
+      // startup observable to the server (a response where the ledger said
+      // nothing was released).
+      // host/command: host-owned authority, not a capability — no §6.2 path
+      // exists and none is invented here. Default DENY; only the operator's
+      // config confers it (PR #79 review blocker 9: any server could
+      // request undo/hide/unstick).
+      if (name === 'host-command' && !this.allowHostCommands) {
+        const responder = args[1] as { respondError?: (code: number, message: string, data?: unknown) => void } | undefined;
+        if (responder?.respondError) {
+          responder.respondError(CAPABILITY_DISABLED, 'host/command requires host-owned authority (McplServerConfig.allowHostCommands)', {});
+        } else {
+          console.error(`[mcpl] ${this.id}: discarded host/command — allowHostCommands not set`);
+        }
+        return true;
+      }
+      const requiredCap = McplServerConnection.EVENT_TO_REQUIRED_CAPABILITY[name];
+      if (requiredCap && !this.grant.has(requiredCap)) {
+        const phase = this.policyEstablished ? 'not in the effective grant' : 'initial policy not yet established (§5.3)';
+        const responder = args[1] as { respondError?: (code: number, message: string, data?: unknown) => void } | undefined;
+        if (responder?.respondError) {
+          responder.respondError(CAPABILITY_DISABLED, `${name} rejected: capability "${requiredCap}" ${phase}`, { capability: requiredCap });
+        } else {
+          console.error(`[mcpl] ${this.id}: discarded ${name} — "${requiredCap}" ${phase}`);
+        }
+        return true;
+      }
       return super.emit(event, ...args);
     }
     this.bufferedEvents.push({ event: name, args });
     return true;
   }
 
+  /** Event-name form of METHOD_TO_REQUIRED_CAPABILITY, for admission-time
+   *  enforcement in emit(). */
+  private static readonly EVENT_TO_REQUIRED_CAPABILITY: Record<string, string> = {
+    'push-event': 'pushEvents',
+    'inference-request': 'inferenceRequest',
+    'model-info': 'modelInfo',
+    'channels-register': 'channels.register',
+    'channels-changed': 'channels.register',
+    'channels-incoming': 'channels.incoming',
+    'channels-list': 'channels.register',
+  };
+
   private static isControlPlaneEvent(event: string): boolean {
     return event === 'stderr'
       || event === 'scope-elevate'
       || event === 'channels-register'
       || event === 'channels-changed'
-      || event === 'feature-sets-changed'
       || event === 'tools-list-changed'
       || event === 'connect-failed'
       || event === 'reconnect-failed'
@@ -273,9 +384,12 @@ export class McplServerConnection extends EventEmitter {
     config: McplServerConfig,
     hostCapabilities: McplHostCapabilities,
   ): Promise<McplServerConnection> {
-    const { transport, capabilities } = await McplServerConnection.handshake(config, hostCapabilities);
+    const { transport, capabilities, droppedCapabilities, mcpToolsAdvertised } = await McplServerConnection.handshake(config, hostCapabilities);
 
     const connection = new McplServerConnection(config.id, capabilities, transport);
+    connection.droppedCapabilities = droppedCapabilities;
+    connection.mcpToolsAdvertised = mcpToolsAdvertised;
+    connection.allowHostCommands = config.allowHostCommands === true;
     connection.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
     // Store config for reconnection
@@ -300,7 +414,7 @@ export class McplServerConnection extends EventEmitter {
   private static async handshake(
     config: McplServerConfig,
     hostCapabilities: McplHostCapabilities,
-  ): Promise<{ transport: McplTransport; capabilities: McplCapabilities | null }> {
+  ): Promise<{ transport: McplTransport; capabilities: McplCapabilities | null; droppedCapabilities: ReadonlySet<string>; mcpToolsAdvertised: boolean }> {
     const transport = await openTransport(config);
 
     try {
@@ -318,7 +432,7 @@ export class McplServerConnection extends EventEmitter {
 
       // Await the initialize response, racing an early transport close/error and
       // a timeout. All three paths clean up their listeners.
-      const capabilities = await new Promise<McplCapabilities | null>((resolve, reject) => {
+      const { mcpl: rawCapabilities, mcpToolsAdvertised } = await new Promise<{ mcpl: McplCapabilities | null; mcpToolsAdvertised: boolean }>((resolve, reject) => {
         const cleanup = () => {
           transport.off('line', onLine);
           transport.off('close', onClose);
@@ -341,7 +455,13 @@ export class McplServerConnection extends EventEmitter {
           const result = msg.result as Record<string, unknown> | undefined;
           const caps = result?.capabilities as Record<string, unknown> | undefined;
           const experimental = caps?.experimental as Record<string, unknown> | undefined;
-          resolve((experimental?.mcpl as McplCapabilities) ?? null);
+          // §5.1: `tools` capability is the OUTER standard MCP member — the
+          // experimental manifest cannot mint it. Carried alongside so the
+          // grant can join it into §6.4 derivation.
+          resolve({
+            mcpl: (experimental?.mcpl as McplCapabilities) ?? null,
+            mcpToolsAdvertised: caps?.tools !== undefined,
+          });
         };
         const onClose = (info: TransportCloseInfo) => {
           cleanup();
@@ -365,7 +485,20 @@ export class McplServerConnection extends EventEmitter {
       // Send `initialized` notification (no id)
       transport.writeLine(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }));
 
-      return { transport, capabilities };
+      // §5.1 boolean shorthand expands to explicit leaves BEFORE the config
+      // mask runs, so sub-leaf policy is addressable — `channels: true` with
+      // `disabledCapabilities: ['channels.streaming']` must actually drop
+      // streaming (PR #79 review blocker 1).
+      const capabilities = expandAdvertisementShorthand(rawCapabilities);
+      // Host-side capability scoping: intersect the server's advertisement
+      // with config policy so a masked capability behaves exactly as if it
+      // had never been advertised (hooks, streaming, queries all read this).
+      const { capabilities: scoped, dropped } = maskNegotiatedCapabilities(capabilities, config);
+      if (dropped.length > 0) {
+        console.error(`MCPL server "${config.id}" capabilities masked by host config: ${dropped.join(', ')}`);
+      }
+
+      return { transport, capabilities: scoped, droppedCapabilities: new Set(dropped), mcpToolsAdvertised };
     } catch (err) {
       // Never leak the child / socket if the handshake fails.
       await transport.close().catch(() => { /* best effort */ });
@@ -436,29 +569,53 @@ export class McplServerConnection extends EventEmitter {
     return this.sendRequest(McplMethod.BeforeInference, params as unknown as Record<string, unknown>) as Promise<BeforeInferenceResult>;
   }
 
-  /**
-   * Send `context/afterInference`.
-   * When `blocking` is true, sends as a request and awaits the result.
-   * When `blocking` is false (or omitted), sends as a notification.
-   */
-  sendAfterInference(params: AfterInferenceParams, blocking?: boolean): Promise<AfterInferenceResult | void> {
-    if (blocking) {
-      return this.sendRequest(McplMethod.AfterInference, params as unknown as Record<string, unknown>) as Promise<AfterInferenceResult>;
-    }
-    this.sendNotification(McplMethod.AfterInference, params as unknown as Record<string, unknown>);
-    return Promise.resolve();
-  }
 
-  /** Send `featureSets/update` notification. */
+  /** Send `featureSets/update` as a Notification. §6.7: valid ONLY for
+   *  purely descriptive metadata that does not alter the grant. Any grant
+   *  change — including the §5.3 initial policy — MUST use the Request form
+   *  below. */
   sendFeatureSetsUpdate(params: FeatureSetsUpdateParams): void {
     this.sendNotification(McplMethod.FeatureSetsUpdate, params as unknown as Record<string, unknown>);
   }
 
+  /**
+   * Send `featureSets/update` as a Request (§5.3, §6.7) and await the
+   * degradation receipt. A short timeout, distinct from tool-call timeouts:
+   * a pre-0.5 server treats the Request as a notification and never
+   * answers, and per §6.7 an unanswered expansion simply does not activate
+   * — the caller leaves the grant empty and the connection MCP-only.
+   */
+  sendFeatureSetsUpdateRequest(
+    params: FeatureSetsUpdateParams,
+    timeoutMs = 15_000,
+  ): Promise<FeatureSetsUpdateResult> {
+    return this.sendRequest(
+      McplMethod.FeatureSetsUpdate,
+      params as unknown as Record<string, unknown>,
+      { timeoutMs },
+    ) as Promise<FeatureSetsUpdateResult>;
+  }
+
   /** Send `inference/chunk` notification. */
   sendInferenceChunk(params: InferenceChunkParams): void {
     this.sendNotification(McplMethod.InferenceChunk, params as unknown as Record<string, unknown>);
   }
 
+  /** Send `inference/lifecycle` notification (§10.5). Best-effort. */
+  sendInferenceLifecycle(params: InferenceLifecycleParams): void {
+    this.sendNotification(McplMethod.InferenceLifecycle, params as unknown as Record<string, unknown>);
+  }
+
+  /**
+   * Fetch the server's complete current manifest (§17.4) — the
+   * experimental.mcpl object in the same shape initialize carries, never a
+   * delta. The fetched CONTENT is authoritative for every decision; the
+   * revision is only the cheap path (§17.1).
+   */
+  sendManifestRequest(timeoutMs = 15_000): Promise<McplCapabilities | null> {
+    return this.sendRequest(McplMethod.Manifest, {}, { timeoutMs }) as Promise<McplCapabilities | null>;
+  }
+
   /** Send `state/rollback` request and await result. */
   sendStateRollback(params: StateRollbackParams): Promise<StateRollbackResult> {
     return this.sendRequest(McplMethod.StateRollback, params as unknown as Record<string, unknown>) as Promise<StateRollbackResult>;
@@ -585,6 +742,7 @@ export class McplServerConnection extends EventEmitter {
       return;
     }
     this.closed = true;
+    this.resetPolicyForTransportBoundary();
 
     // Reject all pending requests
     for (const [id, pending] of this.pendingRequests) {
@@ -663,7 +821,7 @@ export class McplServerConnection extends EventEmitter {
     const attempt = Math.max(1, this.reconnectAttempts);
 
     try {
-      const { transport, capabilities } = await McplServerConnection.handshake(
+      const { transport, capabilities, droppedCapabilities, mcpToolsAdvertised } = await McplServerConnection.handshake(
         this.config,
         this.hostCapabilities,
       );
@@ -673,8 +831,12 @@ export class McplServerConnection extends EventEmitter {
       // awareness barrier synchronously, then releases control traffic needed
       // to establish the server while data remains held.
       this.pauseDataPlane();
+      this.resetPolicyForTransportBoundary();
       this.transport = transport;
       this.capabilities = capabilities;
+      this.droppedCapabilities = droppedCapabilities;
+      this.mcpToolsAdvertised = mcpToolsAdvertised;
+      this.allowHostCommands = this.config?.allowHostCommands === true;
       this.closed = false;
       this.nextRequestId = 1;
       this.pendingRequests.clear();
@@ -779,7 +941,16 @@ export class McplServerConnection extends EventEmitter {
     [McplMethod.ChannelsRegister]: 'channels-register',
     [McplMethod.ChannelsChanged]: 'channels-changed',
     [McplMethod.ChannelsIncoming]: 'channels-incoming',
-    [McplMethod.FeatureSetsChanged]: 'feature-sets-changed',
+    // §6.6/§12: a request bearing an id MUST get a result or an error —
+    // neither of these had an entry, so callers hung forever (AUDIT-001
+    // item 4, which also poisoned the audit's own usage evidence).
+    [McplMethod.ModelInfo]: 'model-info',
+    // §17.3: deliberately UNGATED (not in EVENT_TO_REQUIRED_CAPABILITY) —
+    // announcing conveys no authority, and gating it would silence exactly
+    // the servers whose grants just narrowed. The cost is the host's
+    // re-fetch, which the framework rate-limits (§17.8).
+    [McplMethod.ManifestChanged]: 'manifest-changed',
+    [McplMethod.ChannelsList]: 'channels-list',
     'notifications/tools/list_changed': 'tools-list-changed',
     // Host-level admin commands initiated from a surface (e.g. a Discord
     // slash command). Params: { command, ... }; host responds with a
@@ -787,6 +958,33 @@ export class McplServerConnection extends EventEmitter {
     'host/command': 'host-command',
   };
 
+  /**
+   * Inbound (server-initiated) method → required capability path, per SPEC
+   * §14.1's table plus the non-channel privileged methods. **Positive-grant
+   * enforcement** (§5.4): the method is admitted only when the effective
+   * grant contains the named path — absence is denial, and before the
+   * initial policy exchange completes the grant is empty, so everything
+   * privileged is rejected (§5.3).
+   *
+   * This replaces the earlier `droppedCapabilities` deny-list check, which
+   * could only deny what had been advertised-then-masked: a server that
+   * never advertised a capability at all was never denied. (Adjudicated in
+   * review of PR #75; the mask itself is retained as the config-policy
+   * layer feeding the grant.)
+   *
+   * Channel methods key on their specific sub-capabilities, not the bare
+   * `channels` parent — a bare parent grants nothing (§5.4).
+   */
+  private static readonly METHOD_TO_REQUIRED_CAPABILITY: Record<string, string> = {
+    [McplMethod.PushEvent]: 'pushEvents',
+    [McplMethod.InferenceRequest]: 'inferenceRequest',
+    [McplMethod.ModelInfo]: 'modelInfo',
+    [McplMethod.ChannelsRegister]: 'channels.register',
+    [McplMethod.ChannelsChanged]: 'channels.register',
+    [McplMethod.ChannelsIncoming]: 'channels.incoming',
+    [McplMethod.ChannelsList]: 'channels.register',
+  };
+
   /**
    * Bind all transport-level handlers (inbound routing, lifecycle, stderr) to a
    * transport. Called from the constructor and again from attemptReconnect when
@@ -823,6 +1021,35 @@ export class McplServerConnection extends EventEmitter {
       const request = msg as JsonRpcRequest;
       const eventName = McplServerConnection.METHOD_TO_EVENT[request.method];
 
+      // §7 is removed in 0.5.0: scope/elevate is no longer a method. Answer
+      // rather than hang (§6.6 — a method that will never be answered MUST
+      // return an error).
+      // featureSets/changed is REMOVED in 0.5.0 (§6.7 — it carried a
+      // server-authored change payload, the self-attestation defect; the
+      // need is met by §17's host-diffed manifest fetch). It was still
+      // routed, control-plane classified, and mutating declarations — a
+      // live ungated self-attestation path (PR #79 review blocker 4).
+      if (request.method === McplMethod.FeatureSetsChanged) {
+        if (request.id != null) {
+          this.sendErrorResponse(request.id, -32601, 'featureSets/changed removed in MCPL 0.5.0 (superseded by mcpl/manifestChanged, SPEC §17)');
+        } else {
+          console.error(`[mcpl] ${this.id}: discarded featureSets/changed — removed in 0.5.0 (§6.7/§17)`);
+        }
+        return;
+      }
+
+      if (request.method === McplMethod.ScopeElevate) {
+        if (request.id != null) {
+          this.sendErrorResponse(request.id, -32601, 'scope/elevate removed in MCPL 0.5.0 (SPEC §7)');
+        }
+        return;
+      }
+
+      // Positive-grant enforcement (§5.4, §14.1) happens at ADMISSION, in
+      // the emit() override below — the one choke-point that live routing
+      // and staged-buffer flushes share. See the comment there for why
+      // rejecting here, at line receipt, was wrong for staged connections.
+
       if (eventName) {
         // Emit the typed event with params and (for requests) a respond callback
         if (request.id != null) {
@@ -928,6 +1155,7 @@ export class McplServerConnection extends EventEmitter {
     transport.on('close', (info: TransportCloseInfo) => {
       if (!this.closed) {
         this.closed = true;
+        this.resetPolicyForTransportBoundary();
 
         // Reject all pending requests
         for (const [id, pending] of this.pendingRequests) {

package/src/mcpl/server-registry.ts

@@ -107,9 +107,10 @@ export class McplServerRegistry {
         case 'pushEvents':
           return caps.pushEvents === true;
         case 'contextHooks.beforeInference':
-          return caps.contextHooks?.beforeInference === true;
-        case 'contextHooks.afterInference':
-          return !!caps.contextHooks?.afterInference;
+          // Truthy, not ===true: §5.1 shorthand is expanded to the object
+          // form at handshake. (Prefer connection.grant for authorization —
+          // this query is advertisement-level only.)
+          return !!caps.contextHooks?.beforeInference;
         case 'inferenceRequest':
           return !!caps.inferenceRequest;
         case 'modelInfo':

package/src/mcpl/tags.ts

@@ -0,0 +1,50 @@
+/**
+ * Event-tag core closure (SPEC §16.3) and the addressed/ambient resolution.
+ *
+ * The `chat:*` core implications are NORMATIVE and spec-defined — a host
+ * expands them itself and never needs the producer's ontology to do so.
+ * Producer `implies` edges are advisory pending explicit acceptance (§16.4)
+ * and are NOT consumed here. Producer `suggestedTreatment` MUST NOT be
+ * auto-applied (§16.5) — nothing in this module reads it, deliberately.
+ *
+ * Tags are never authority (§16.6): expansion happens after admission, and
+ * nothing downstream may grant, admit, or authorize based on a tag.
+ */
+
+/** Normative core closure edges (§16.3). Closed vocabulary — chat:* only. */
+const CORE_IMPLIES: Readonly<Record<string, readonly string[]>> = {
+  'chat:mention': ['chat:addressed'],
+  'chat:reply': ['chat:addressed'],
+  'chat:dm': ['chat:addressed', 'chat:private'],
+};
+
+/**
+ * Expand a raw tag list over the normative core closure, then resolve the
+ * §16.2 mutual exclusion: `chat:addressed` and `chat:ambient` cannot both
+ * stand after expansion, and addressed wins — a message that is both
+ * specifically-to-you and background noise is specifically-to-you.
+ *
+ * Pure; input order is preserved for the tags that survive, with implied
+ * tags appended in first-cause order. Unknown and producer-namespaced tags
+ * pass through untouched.
+ */
+export function expandCoreTags(tags: readonly string[] | undefined): string[] {
+  if (!tags || tags.length === 0) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const add = (t: string): void => {
+    if (!seen.has(t)) {
+      seen.add(t);
+      out.push(t);
+    }
+  };
+  for (const t of tags) {
+    add(t);
+    for (const implied of CORE_IMPLIES[t] ?? []) add(implied);
+  }
+  if (seen.has('chat:addressed') && seen.has('chat:ambient')) {
+    const i = out.indexOf('chat:ambient');
+    if (i >= 0) out.splice(i, 1);
+  }
+  return out;
+}

package/src/mcpl/transport.ts

@@ -200,18 +200,46 @@ export class WebSocketTransport extends McplTransport {
    * when `config.token` is set. Rejects on connect error / timeout (and tears
    * the socket down) so a failed dial never leaks an open handle.
    */
-  static open(config: McplServerConfig): Promise<WebSocketTransport> {
-    const url = buildWebSocketUrl(config);
+  static async open(config: McplServerConfig): Promise<WebSocketTransport> {
+    // Resolve the per-dial credential first: the provider runs on every
+    // connect AND reconnect, so rotation happens at the transport layer and
+    // nothing above it ever holds a credential.
+    let token: string | null = config.token ?? null;
+    if (config.accessProvider) {
+      try {
+        token = (await config.accessProvider()) ?? token;
+      } catch (err) {
+        // Fall back to the static token (if any) rather than failing the dial
+        // outright — the server will refuse a stale credential loudly anyway.
+        console.error(
+          `[mcpl] server "${config.id}": access provider failed (${err instanceof Error ? err.message : err}) — dialing with configured fallback`,
+        );
+      }
+    }
+    const url = buildWebSocketUrl(config, token);
+    // Error strings travel: traces, logs, tool results the model reads. They
+    // get the endpoint, never the credential.
+    const redacted = buildWebSocketUrl({ ...config, token: undefined }, null);
     const ws = new WebSocket(url);
 
+    // A failed dial can emit 'error' MORE THAN ONCE on the raw socket (seen
+    // live 2026-08-03: an HTTP 502 upgrade-reject emits the "Expected 101"
+    // error and then a teardown error). WebSocket is an EventEmitter, so any
+    // 'error' with no listener throws at the top level and KILLS THE WHOLE
+    // AGENT PROCESS — a crashloop, since the dial happens at boot. Every
+    // settle path below must therefore leave a swallow listener behind; a
+    // remote server being down must never be able to take the host down.
+    const swallowLateErrors = () => { /* settled; retry loop owns recovery */ };
+
     return new Promise<WebSocketTransport>((resolve, reject) => {
       let settled = false;
       const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
         ws.removeAllListeners();
+        ws.on('error', swallowLateErrors);
         try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${url})`));
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${redacted})`));
       }, WS_OPEN_TIMEOUT_MS);
 
       ws.once('open', () => {
@@ -227,8 +255,9 @@ export class WebSocketTransport extends McplTransport {
         settled = true;
         clearTimeout(timer);
         ws.removeAllListeners();
+        ws.on('error', swallowLateErrors);
         try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${url})`));
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${redacted})`));
       });
     });
   }
@@ -261,7 +290,7 @@ export class WebSocketTransport extends McplTransport {
  * Build the dial URL: validate it's a ws(s):// URL and append the auth token as
  * a `token` query param when provided (preserving any existing query).
  */
-export function buildWebSocketUrl(config: McplServerConfig): string {
+export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: string | null): string {
   if (!config.url) {
     throw new Error(`MCPL server "${config.id}": websocket transport requires "url" (none provided)`);
   }
@@ -276,8 +305,9 @@ export function buildWebSocketUrl(config: McplServerConfig): string {
       `MCPL server "${config.id}": websocket url must be ws:// or wss://, got "${parsed.protocol}"`,
     );
   }
-  if (config.token) {
-    parsed.searchParams.set('token', config.token);
+  const token = tokenOverride !== undefined ? tokenOverride : config.token;
+  if (token) {
+    parsed.searchParams.set('token', token);
   }
   return parsed.toString();
 }