@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

package/runtime/node_modules/@metro-labs/daemon/src/mcp/profile-tool.ts

@@ -0,0 +1,96 @@
+import type { ToolDef } from './tool-def.js';
+import type { CanonicalAttachment, Station, ToolResult } from '@metro-labs/core/stations/types';
+import { PROFILE_FIELDS, type ProfileField } from '@metro-labs/core/stations/profile';
+import { str } from '@metro-labs/core/str';
+import { STATIONS, stationByName } from '../stations/registry.js';
+import { cleanupAttachments, resolveAttachments, type ResolvedAttachment } from '../stations/attach-resolve.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+
+const SOURCE = { type: 'string' };
+
+export const SET_PROFILE_TOOL: ToolDef = {
+  name: 'set_profile',
+  group: 'write',
+  description:
+    'Change how one of your accounts presents itself on its network: the display name, the bio ' +
+    '(about line) and the avatar. Args: station (required), account? (which account of that station; ' +
+    'needed only when you have several), name?, bio?, avatar? (an image given like an attachment: ' +
+    'exactly one of upload, url, path, data, plus mime and name). At least one of name, bio, avatar. ' +
+    'Each station takes what its network allows (`list_accounts` reports the fields under ' +
+    '`profiles`); a field the station cannot set is refused by name, never dropped. Discord changes ' +
+    'the bot username and app description (Discord allows two username changes an hour); Telegram ' +
+    'bots set their name, description and photo; a Telegram user account sets its first name, bio ' +
+    '(70 chars) and photo; WhatsApp sets the profile name, about and picture; XMTP writes the ' +
+    'name, description and avatar records of the account\'s <label>.stage.base.eth name on Base, ' +
+    'so it needs a name first (claimed on the channel page, never by you). Visible to everyone ' +
+    'who talks to the account, so do it when asked, not on your own. Returns {account, applied}.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      station: { type: 'string', description: 'discord-bot | telegram-bot | telegram | whatsapp | xmtp' },
+      account: { type: 'string', description: 'The account id on that station, from list_accounts.' },
+      name: { type: 'string', description: 'The display name.' },
+      bio: { type: 'string', description: 'The bio or about line.' },
+      avatar: {
+        type: 'object',
+        description: 'The new picture, as an attachment source.',
+        properties: { upload: SOURCE, url: SOURCE, path: SOURCE, data: SOURCE, mime: SOURCE, name: SOURCE },
+      },
+    },
+    required: ['station'],
+  },
+};
+
+export const profileCapabilities = (): Record<string, ProfileField[]> => {
+  const out: Record<string, ProfileField[]> = {};
+  for (const s of STATIONS) if (s.profileFields !== undefined) out[s.name] = [...s.profileFields];
+  return out;
+};
+
+const asked = (a: Record<string, unknown>): ProfileField[] => PROFILE_FIELDS.filter((f) => a[f] !== undefined);
+
+type Target = { station: Station } | { refused: string };
+
+function targetOf(a: Record<string, unknown>): Target {
+  const name = str(a.station);
+  if (!name) return { refused: 'set_profile requires `station`' };
+  const station = stationByName(name);
+  if (!station) return { refused: `no station named ${name}` };
+  const fields = station.profileFields;
+  if (fields === undefined) return { refused: `${name} accounts have no profile metro can set` };
+  const wanted = asked(a);
+  if (wanted.length === 0) return { refused: 'set_profile needs at least one of name, bio, avatar' };
+  const refused = wanted.filter((f) => !fields.has(f));
+  if (refused.length > 0) return { refused: `${name} cannot set ${refused.join(', ')}; it takes ${[...fields].join(', ')}` };
+  return { station };
+}
+
+function trainArgs(a: Record<string, unknown>, picture: ResolvedAttachment | undefined): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  if (typeof a.account === 'string') args.account = a.account;
+  if (typeof a.name === 'string') args.name = a.name;
+  if (typeof a.bio === 'string') args.bio = a.bio;
+  if (picture !== undefined) args.avatar = { path: picture.path, mime: picture.mime, name: picture.name };
+  return args;
+}
+
+export async function dispatchSetProfile(a: Record<string, unknown>): Promise<ToolResult> {
+  const target = targetOf(a);
+  if ('refused' in target) return errResult(target.refused);
+  const avatar = a.avatar === undefined ? [] : [a.avatar as CanonicalAttachment];
+  let resolved: ResolvedAttachment[];
+  try {
+    resolved = await resolveAttachments(avatar, { allowed: allowedAgents(currentIdentity()) });
+  } catch (e) {
+    return toErr('set_profile', e);
+  }
+  try {
+    const { result } = await makeCtx(target.station.name).call('set_profile', trainArgs(a, resolved[0]));
+    return okJson(result);
+  } catch (e) {
+    return toErr('set_profile', e);
+  } finally {
+    await cleanupAttachments(resolved);
+  }
+}

package/runtime/node_modules/@metro-labs/{mcp → daemon}/src/mcp/raw-get-stream.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
 import type {
   StreamableHTTPServerTransport,
   EventId,
@@ -8,7 +9,7 @@ import type { BoundedEventStore } from './event-store.js';
 
 const STANDALONE_STREAM_ID = '_GET_stream';
 const KEEPALIVE_MS = 15_000;
-const RECONNECT_RETRY_MS = 15_000;
+const RECONNECT_RETRY_MS = 1_000;
 const COMMENT = ':\n\n';
 const RETRY_DIRECTIVE = `retry: ${RECONNECT_RETRY_MS}\n\n`;
 
@@ -49,12 +50,24 @@ export const headerValue = (
   return typeof raw === 'string' ? raw : undefined;
 };
 
+export interface GetStreamDiagnostic {
+  tag: string;
+  openedAt: string;
+  attachedAt: string | null;
+  closedAt: string | null;
+  ownsMapping: boolean;
+}
+
 export interface RawGetSink {
   closed: boolean;
   attach: (transport: StreamableHTTPServerTransport) => void;
   close: () => void;
+  diagnostics: () => GetStreamDiagnostic;
 }
 
+const streamEnded = (sink: RawGetSink, res: ServerResponse): boolean =>
+  sink.closed || res.destroyed || res.writableEnded;
+
 export interface ValidateResult {
   ok: boolean;
   status?: number;
@@ -93,12 +106,11 @@ export interface ServeOpts {
   res: ServerResponse;
   log: (...a: unknown[]) => void;
   registerSink: (sink: RawGetSink | undefined) => void;
+  previous?: () => RawGetSink | undefined;
 }
 
-export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
-  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+function primeStream(transport: StreamableHTTPServerTransport, res: ServerResponse): void {
   const sessionId = web(transport)?.sessionId;
-
   res.writeHead(200, {
     'content-type': 'text/event-stream',
     'cache-control': 'no-cache, no-transform',
@@ -109,15 +121,29 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
   res.flushHeaders?.();
   res.write(RETRY_DIRECTIVE);
   res.write(COMMENT);
+}
+
+export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
+  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+  primeStream(transport, res);
 
   let active = transport;
+  let entry: StreamEntry | undefined;
+  const tag = randomUUID();
+  const openedAt = new Date().toISOString();
+  let attachedAt: string | null = null;
+  let closedAt: string | null = null;
   const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
   const closeStream = (): void => {
     if (sink.closed) return;
     sink.closed = true;
+    closedAt = new Date().toISOString();
     if (timers.keepalive) clearInterval(timers.keepalive);
-    web(active)?._streamMapping?.delete(STANDALONE_STREAM_ID);
-    registerSink(undefined);
+    const mapping = web(active)?._streamMapping;
+    if (entry !== undefined && mapping?.get(STANDALONE_STREAM_ID) === entry) {
+      mapping.delete(STANDALONE_STREAM_ID);
+      registerSink(undefined);
+    }
     try {
       res.end();
     } catch {
@@ -128,11 +154,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     closed: false,
     attach: (next: StreamableHTTPServerTransport): void => {
       active = next;
-      const entry: StreamEntry = {
+      entry = {
         controller: {
           enqueue: (chunk: Uint8Array): void => {
-            if (sink.closed) return;
-            if (res.destroyed || res.writableEnded) {
+            if (streamEnded(sink, res)) {
               closeStream();
               return;
             }
@@ -143,10 +168,22 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
         cleanup: closeStream,
       };
       web(next)?._streamMapping?.set(STANDALONE_STREAM_ID, entry);
+      attachedAt = new Date().toISOString();
     },
     close: closeStream,
+    diagnostics: () => ({
+      tag,
+      openedAt,
+      attachedAt,
+      closedAt,
+      ownsMapping: entry !== undefined && web(active)?._streamMapping?.get(STANDALONE_STREAM_ID) === entry,
+    }),
   };
 
+  res.on('close', closeStream);
+  res.on('error', closeStream);
+  req.on('close', closeStream);
+
   const lastEventId = headerValue(req, 'last-event-id');
   if (lastEventId) {
     await eventStore.replayEventsAfter(lastEventId, {
@@ -168,12 +205,17 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     });
   }
 
+  if (streamEnded(sink, res)) {
+    closeStream();
+    return;
+  }
+  opts.previous?.()?.close();
   sink.attach(transport);
   registerSink(sink);
+  if (sink.closed) return;
 
   timers.keepalive = setInterval(() => {
-    if (sink.closed) return;
-    if (res.destroyed || res.writableEnded) {
+    if (streamEnded(sink, res)) {
       closeStream();
       return;
     }
@@ -185,14 +227,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     }
   }, KEEPALIVE_MS);
   timers.keepalive.unref?.();
-
-  res.on('close', closeStream);
-  res.on('error', closeStream);
-  req.on('close', closeStream);
 }
 
 export interface ChannelGetOpts extends ServeOpts {
-  previous: RawGetSink | undefined;
+  previous: () => RawGetSink | undefined;
 }
 
 export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
@@ -201,7 +239,7 @@ export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
     opts.res.writeHead(check.status ?? 400).end(check.message ?? 'bad request');
     return false;
   }
-  if (opts.previous && !opts.previous.closed) opts.previous.close();
+  opts.previous()?.close();
   await serveStandaloneGet(opts);
   return true;
 }

package/runtime/node_modules/@metro-labs/daemon/src/mcp/read-tool.ts

@@ -0,0 +1,87 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { str } from '@metro-labs/core/str';
+import type { ReadFilter, Station, ToolResult } from '@metro-labs/core/stations/types';
+import { agentIdForAccount, accountFromLine, knownAccounts } from '../agents/map.js';
+import { attachmentUrl } from '../files/attach-serve.js';
+import { stationByName } from '../stations/registry.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { agentUser } from '../agent-user/user.js';
+
+const FILTERS: readonly (readonly [string, ReadFilter, string])[] = [
+  ['query', 'query', 'query'],
+  ['from', 'from', 'from'],
+  ['until', 'until', 'until'],
+  ['unread_only', 'unread_only', 'unreadOnly'],
+  ['message_id', 'message_id', 'messageId'],
+];
+
+const given = (v: unknown): boolean => v !== undefined && v !== null && v !== '' && v !== false;
+
+export function stationOfAccount(account: string): string | undefined {
+  const hits = knownAccounts().filter((a) => a.id === account);
+  return hits.length === 1 ? hits[0]?.station : undefined;
+}
+
+function readArgs(a: Record<string, unknown>): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  if (str(a.line)) args.line = str(a.line);
+  if (str(a.account)) args.account = str(a.account);
+  if (typeof a.limit === 'number') args.limit = a.limit;
+  if (a.before) args.before = str(a.before);
+  if (a.since) args.since = str(a.since);
+  for (const [snake, , camel] of FILTERS)
+    if (given(a[snake])) args[camel] = typeof a[snake] === 'boolean' ? a[snake] : str(a[snake]);
+  return args;
+}
+
+function ignoredFilters(station: Station, a: Record<string, unknown>): string[] {
+  const supported = station.readFilters ?? new Set<ReadFilter>();
+  return FILTERS.filter(([snake, filter]) => given(a[snake]) && !supported.has(filter)).map(([snake]) => snake);
+}
+
+function withUrls(result: unknown, agentId: string | undefined): unknown {
+  if (agentId === undefined || !isRecord(result) || !isRecord(result.message)) return result;
+  const files = result.message.attachments;
+  if (!Array.isArray(files)) return result;
+  const attachments = files.map((f: unknown) => {
+    if (!isRecord(f) || typeof f.local_path !== 'string') return f;
+    const url = attachmentUrl(f.local_path, agentId);
+    const shown = agentUser() === null ? f : Object.fromEntries(Object.entries(f).filter(([key]) => key !== 'local_path'));
+    return url === null ? shown : { ...shown, url };
+  });
+  return { ...result, message: { ...result.message, attachments } };
+}
+
+function answer(result: unknown, ignored: string[]): unknown {
+  if (ignored.length === 0) return result;
+  return isRecord(result) && !Array.isArray(result) ? { ...result, ignored } : { result, ignored };
+}
+
+function accountOfCall(station: Station, a: Record<string, unknown>, result: unknown): string | undefined {
+  const named = str(a.account) || (isRecord(result) ? str(result.account) : '');
+  const account = named || accountFromLine(str(a.line))?.accountId;
+  return account === undefined ? undefined : agentIdForAccount(station.name, account);
+}
+
+export async function runRead(station: Station, a: Record<string, unknown>): Promise<ToolResult> {
+  try {
+    const response = await makeCtx(station.name).call('read', readArgs(a));
+    const result = withUrls(response.result, accountOfCall(station, a, response.result));
+    return okJson(answer(result, ignoredFilters(station, a)));
+  } catch (e) {
+    return toErr('read', e);
+  }
+}
+
+export function linelessRead(a: Record<string, unknown>): Promise<ToolResult> | ToolResult {
+  const account = str(a.account);
+  if (!account) return errResult('read requires `line` or `account`');
+  const name = stationOfAccount(account);
+  const station = name === undefined ? undefined : stationByName(name);
+  if (station === undefined) return errResult(`no account ${account} on this box; list_accounts names them`);
+  if (!station.messageVerbs.has('read'))
+    return errResult(`${station.name} does not support read; it supports ${[...station.messageVerbs].join(', ')}.`);
+  if (!station.readFilters?.has('account'))
+    return errResult(`${station.name} reads one conversation at a time; give a \`line\` instead of an account`);
+  return runRead(station, a);
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/request-identity.ts

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage } from 'node:http';
+import { cameThroughProxy } from '@metro-labs/http/api-http';
+import { agentIdForKey } from '../agents/keys.js';
+
+export interface RequestIdentity {
+  kind: 'agent';
+  agentId: string;
+}
+
+const storage = new AsyncLocalStorage<RequestIdentity>();
+
+export function runWithIdentity<T>(
+  identity: RequestIdentity,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return storage.run(identity, fn);
+}
+
+export function currentIdentity(): RequestIdentity | undefined {
+  return storage.getStore();
+}
+
+export function extractToken(req: IncomingMessage): string | undefined {
+  const header = req.headers.authorization;
+  if (header?.startsWith('Bearer ')) {
+    const t = header.slice(7).trim();
+    if (t) return t;
+  }
+  const qt = new URL(req.url ?? '/', 'http://localhost').searchParams.get(
+    'token',
+  );
+  return qt ?? undefined;
+}
+
+export function authenticate(req: IncomingMessage): RequestIdentity | null {
+  if (cameThroughProxy(req)) return null;
+  const token = extractToken(req);
+  if (!token) return null;
+  const agentId = agentIdForKey(token);
+  return agentId === undefined ? null : { kind: 'agent', agentId };
+}
+
+export function allowedAgents(
+  identity: RequestIdentity | undefined,
+): Set<string> {
+  return identity ? new Set([identity.agentId]) : new Set();
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/server-approvals.ts

@@ -0,0 +1,118 @@
+import type { MetroEvent } from '@metro-labs/core/events';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { McpApproval, McpDecision } from '@metro-labs/http/mcp-server-protocol';
+import { holdPrompt, isPromptHeld, type Behavior } from '../approvals/pending.js';
+import { ownerLine } from '../approvals/owner-line.js';
+import { metroNotice } from '../channels/notice.js';
+import { announcedLine, noteAnnounced } from '../mcp-server/announced.js';
+import type { AnswerOutcome } from '../mcp-server/link.js';
+import { serverPromptBody } from './permission-prompt.js';
+import { metroSend, relayLine } from './permission-relay.js';
+import { channelLog, type McpSession } from './session.js';
+
+const RECENT_MS = 10 * 60_000;
+const RECENT_MAX = 1_000;
+
+const owner = {};
+const recent = new Map<string, number>();
+let current: () => McpSession | undefined = () => undefined;
+
+export function connectServerApprovals(session: () => McpSession | undefined): void {
+  current = session;
+}
+
+function promptLineFor(requestId: string): string | undefined {
+  const session = current();
+  if (session === undefined) return undefined;
+  return relayLine({ relay: session.relay, inScope: (line) => session.inScope(line), live: session.live, log: channelLog }, requestId);
+}
+
+const noticeLineFor = (line: string | undefined): string | undefined => line ?? current()?.relay.knownLine ?? ownerLine()?.line;
+
+function remember(id: string, now = Date.now()): void {
+  for (const [seen, at] of recent) if (now - at >= RECENT_MS) recent.delete(seen);
+  recent.set(id, now);
+  while (recent.size > RECENT_MAX) {
+    const oldest = recent.keys().next();
+    if (oldest.done) break;
+    recent.delete(oldest.value);
+  }
+}
+
+const answeredRecently = (id: string, now = Date.now()): boolean => now - (recent.get(id) ?? -Infinity) < RECENT_MS;
+
+const noticeText = (tool: string, id: string, behavior: Behavior): string =>
+  behavior === 'allow' ? `Approved: ${tool} (${id}). Call tool_call again with the same arguments and approval: "${id}".` : `Denied: ${tool} (${id}).`;
+
+const requestedAt = (at: number, now = Date.now()): number => (Number.isFinite(at) && at > 0 ? Math.min(at, now) : now);
+
+const askedBy = (approval: McpApproval): string => {
+  if (approval.origin !== 'key') return '';
+  return approval.keyLabel === undefined ? ' (from an access key)' : ` (from an access key: ${approval.keyLabel})`;
+};
+
+interface Held {
+  id: string;
+  tool: string;
+  line: string | undefined;
+  tellAgent: boolean;
+  answer: (decision: McpDecision) => Promise<AnswerOutcome>;
+  publish: (event: MetroEvent) => void;
+}
+
+async function deliver(held: Held, behavior: Behavior): Promise<void> {
+  const outcome = await held.answer(behavior);
+  if (outcome !== 'acknowledged') {
+    log.info({ id: held.id, outcome }, 'mcp-server: the answer was not taken, so the agent is not told');
+    return;
+  }
+  if (!held.tellAgent) {
+    log.info({ id: held.id }, 'mcp-server: the call came with an access key, not from this agent\'s session, so the agent is not told');
+    return;
+  }
+  const line = noticeLineFor(held.line);
+  if (line === undefined) {
+    log.warn({ id: held.id }, 'mcp-server: no chat is known to tell the agent the answer');
+    return;
+  }
+  held.publish(metroNotice(line, noticeText(held.tool, held.id, behavior)));
+}
+
+function sender(held: Held): (behavior: Behavior) => Promise<void> {
+  return (behavior) => {
+    remember(held.id);
+    deliver(held, behavior).catch((err: unknown) => {
+      log.warn({ id: held.id, err: errMsg(err) }, 'mcp-server: the answer could not be delivered');
+    });
+    return Promise.resolve();
+  };
+}
+
+function announce(id: string, line: string, text: string): void {
+  metroSend(line, text).then(() => {
+    noteAnnounced(id, line);
+  }).catch((err: unknown) => {
+    log.warn({ id, err: errMsg(err) }, 'mcp-server: the approval prompt could not be posted');
+  });
+}
+
+export function holdServerApproval(approval: McpApproval, answer: Held['answer'], publish: Held['publish']): boolean {
+  if (isPromptHeld(approval.id) || answeredRecently(approval.id)) return false;
+  const tool = `${approval.connector}.${approval.tool}`;
+  const announced = announcedLine(approval.id);
+  const line = announced ?? promptLineFor(approval.id);
+  const held: Held = { id: approval.id, tool, line, tellAgent: approval.origin !== 'key', answer, publish };
+  holdPrompt(
+    { requestId: approval.id, tool, description: approval.connector, preview: approval.preview, line, at: requestedAt(approval.requestedAt), origin: 'mcp-server' },
+    owner,
+    sender(held),
+    line === undefined ? undefined : async (text) => metroSend(line, text),
+  );
+  log.info({ id: approval.id, tool, origin: approval.origin ?? null, inChat: line !== undefined, announced: announced !== undefined }, 'mcp-server: an approval is waiting for the owner');
+  if (line !== undefined && announced === undefined) announce(approval.id, line, serverPromptBody({ requestId: approval.id, tool: `${tool}${askedBy(approval)}`, preview: approval.preview }));
+  return true;
+}
+
+export function forgetServerApprovals(): void {
+  recent.clear();
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/session-slot.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { currentBusSeq } from '@metro-labs/core/events';
+import { errMsg } from '@metro-labs/core/log';
+import { newReplayLedger } from '../channels/relay.js';
+import { McpSession, channelLog } from './session.js';
+import { allowedAgents, type RequestIdentity } from './request-identity.js';
+import { diagnosticTag, type SessionDiagnostic, type SlotDiagnostic } from './diagnostics.js';
+
+interface SlotReplacement {
+  at: string;
+  reason: 'initialize' | 'adopt';
+  tag: string;
+  scope: Set<string>;
+  previousScope: Set<string>;
+  previous: SessionDiagnostic | null;
+}
+
+const sharesScope = (left: Set<string>, right: Set<string>): boolean => [...left].some((id) => right.has(id));
+
+export class SessionSlot {
+  private session: McpSession | undefined;
+  private readonly ledger = newReplayLedger();
+  private started = false;
+  private live: boolean;
+  private changing: Promise<void> = Promise.resolve();
+  private readonly replacements: SlotReplacement[] = [];
+
+  constructor(live = true) {
+    this.live = live;
+  }
+
+  get current(): McpSession | undefined {
+    return this.session;
+  }
+
+  get liveEvents(): boolean {
+    return this.live;
+  }
+
+  diagnostics(scope: Set<string>): SlotDiagnostic {
+    return {
+      started: this.started,
+      liveEvents: this.live,
+      current: this.session !== undefined && sharesScope(scope, this.session.scope) ? this.session.diagnostics() : null,
+      replacements: this.replacements.filter((replacement) => sharesScope(scope, replacement.scope)).map((replacement) => ({
+        at: replacement.at,
+        reason: replacement.reason,
+        tag: replacement.tag,
+        previous: sharesScope(scope, replacement.previousScope) ? replacement.previous : null,
+      })),
+    };
+  }
+
+  startInbound(): void {
+    if (this.started) return;
+    this.started = true;
+    if (this.ledger.startAt < 0) this.ledger.startAt = currentBusSeq();
+    if (this.live) this.session?.startChannel();
+  }
+
+  setLive(on: boolean): void {
+    if (this.live === on) return;
+    this.live = on;
+    channelLog('inbound: live events', on ? 'on' : 'off');
+    if (!on) {
+      this.session?.stopChannel();
+      this.session?.relay.dropPending();
+      return;
+    }
+    this.ledger.startAt = currentBusSeq();
+    if (this.started) this.session?.startChannel();
+  }
+
+  open(identity: RequestIdentity, adoptId?: string): Promise<McpSession> {
+    return this.change(() => this.replace(identity, adoptId));
+  }
+
+  private change<T>(run: () => Promise<T>): Promise<T> {
+    const changed = this.changing.then(run);
+    this.changing = changed.then(() => undefined).catch((err: unknown) => {
+      channelLog('session: change failed', errMsg(err));
+    });
+    return changed;
+  }
+
+  private previousSlot(): Pick<SlotReplacement, 'previous' | 'previousScope'> {
+    return {
+      previous: this.session?.diagnostics() ?? null,
+      previousScope: this.session?.scope ?? new Set<string>(),
+    };
+  }
+
+  private recordReplacement(session: McpSession, adoptId: string | undefined, previous: Pick<SlotReplacement, 'previous' | 'previousScope'>): void {
+    this.replacements.push({
+      at: new Date().toISOString(),
+      reason: adoptId === undefined ? 'initialize' : 'adopt',
+      tag: diagnosticTag(session.id),
+      scope: session.scope,
+      ...previous,
+    });
+    if (this.replacements.length > 8) this.replacements.shift();
+  }
+
+  private async replace(identity: RequestIdentity, adoptId?: string): Promise<McpSession> {
+    if (adoptId !== undefined && this.session?.id === adoptId) return this.session;
+    const previous = this.previousSlot();
+    await this.session?.close();
+    if (this.ledger.startAt < 0) this.ledger.startAt = currentBusSeq();
+    const id = adoptId ?? randomUUID();
+    const session = await McpSession.open({
+      id,
+      scope: allowedAgents(identity),
+      adopted: adoptId !== undefined,
+      ledger: this.ledger,
+      live: () => this.live,
+      onClosed: (s) => {
+        if (this.session === s) this.session = undefined;
+        s.channel.whenIdle().then(() => {
+          if (this.session?.streamAttached) this.session.replayMissed();
+        }).catch((err: unknown) => {
+          channelLog('session: handoff replay failed', errMsg(err));
+        });
+      },
+    });
+    this.session = session;
+    this.recordReplacement(session, adoptId, previous);
+    if (this.started && this.live) session.startChannel();
+    channelLog('session: opened', 'id', id, 'adopted', adoptId !== undefined);
+    return session;
+  }
+
+  close(): Promise<void> {
+    return this.change(async () => {
+      await this.session?.close();
+    });
+  }
+}