@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.21

package/runtime/node_modules/@metro-labs/mcp/src/mcp/raw-get-stream.ts

@@ -0,0 +1,207 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type {
+  StreamableHTTPServerTransport,
+  EventId,
+} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+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 COMMENT = ':\n\n';
+const RETRY_DIRECTIVE = `retry: ${RECONNECT_RETRY_MS}\n\n`;
+
+interface StreamEntry {
+  controller: { enqueue: (chunk: Uint8Array) => void };
+  encoder: { encode: (input: string) => Uint8Array };
+  cleanup: () => void;
+}
+
+export interface WebTransport {
+  sessionId?: string;
+  _initialized?: boolean;
+  _streamMapping?: Map<string, StreamEntry>;
+}
+
+interface AdaptedTransport {
+  _webStandardTransport?: WebTransport;
+}
+
+export const web = (
+  transport: StreamableHTTPServerTransport,
+): WebTransport | undefined =>
+  (transport as unknown as AdaptedTransport)._webStandardTransport;
+
+export const isStandaloneGet = (req: IncomingMessage): boolean => {
+  if (req.method !== 'GET') return false;
+  const accept = req.headers.accept;
+  const value = Array.isArray(accept) ? accept.join(',') : (accept ?? '');
+  return value.includes('text/event-stream');
+};
+
+export const headerValue = (
+  req: IncomingMessage,
+  name: string,
+): string | undefined => {
+  const raw = req.headers[name];
+  if (Array.isArray(raw)) return raw[0];
+  return typeof raw === 'string' ? raw : undefined;
+};
+
+export interface RawGetSink {
+  closed: boolean;
+  attach: (transport: StreamableHTTPServerTransport) => void;
+  close: () => void;
+}
+
+export interface ValidateResult {
+  ok: boolean;
+  status?: number;
+  message?: string;
+}
+
+export function validateStandaloneSession(
+  transport: StreamableHTTPServerTransport,
+  req: IncomingMessage,
+): ValidateResult {
+  const inner = web(transport);
+  if (!inner) return { ok: false, status: 500, message: 'transport not ready' };
+  if (!inner._initialized)
+    return {
+      ok: false,
+      status: 400,
+      message: 'Bad Request: Server not initialized',
+    };
+  const presented = headerValue(req, 'mcp-session-id');
+  if (!presented)
+    return {
+      ok: false,
+      status: 400,
+      message: 'Bad Request: Mcp-Session-Id header is required',
+    };
+  if (presented !== inner.sessionId)
+    return { ok: false, status: 404, message: 'Session not found' };
+  return { ok: true };
+}
+
+export interface ServeOpts {
+  transport: StreamableHTTPServerTransport;
+  eventStore: BoundedEventStore;
+  scope: Set<string>;
+  req: IncomingMessage;
+  res: ServerResponse;
+  log: (...a: unknown[]) => void;
+  registerSink: (sink: RawGetSink | undefined) => void;
+}
+
+export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
+  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+  const sessionId = web(transport)?.sessionId;
+
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+  });
+  res.flushHeaders?.();
+  res.write(RETRY_DIRECTIVE);
+  res.write(COMMENT);
+
+  let active = transport;
+  const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
+  const closeStream = (): void => {
+    if (sink.closed) return;
+    sink.closed = true;
+    if (timers.keepalive) clearInterval(timers.keepalive);
+    web(active)?._streamMapping?.delete(STANDALONE_STREAM_ID);
+    registerSink(undefined);
+    try {
+      res.end();
+    } catch {
+      log('raw-get-stream: end failed');
+    }
+  };
+  const sink: RawGetSink = {
+    closed: false,
+    attach: (next: StreamableHTTPServerTransport): void => {
+      active = next;
+      const entry: StreamEntry = {
+        controller: {
+          enqueue: (chunk: Uint8Array): void => {
+            if (sink.closed) return;
+            if (res.destroyed || res.writableEnded) {
+              closeStream();
+              return;
+            }
+            res.write(Buffer.from(chunk));
+          },
+        },
+        encoder: { encode: (input: string): Uint8Array => Buffer.from(input) },
+        cleanup: closeStream,
+      };
+      web(next)?._streamMapping?.set(STANDALONE_STREAM_ID, entry);
+    },
+    close: closeStream,
+  };
+
+  const lastEventId = headerValue(req, 'last-event-id');
+  if (lastEventId) {
+    await eventStore.replayEventsAfter(lastEventId, {
+      scope,
+      send: (id: EventId, message: JSONRPCMessage): Promise<void> => {
+        if (!sink.closed)
+          res.write(`event: message\nid: ${id}\ndata: ${JSON.stringify(message)}\n\n`);
+        return Promise.resolve();
+      },
+      onWithheld: (id: EventId, line: string | undefined): void => {
+        log(
+          'raw-get-stream: withheld replay (frame outside the reconnecting session scope)',
+          'id',
+          id,
+          'line',
+          line ?? '(none)',
+        );
+      },
+    });
+  }
+
+  sink.attach(transport);
+  registerSink(sink);
+
+  timers.keepalive = setInterval(() => {
+    if (sink.closed) return;
+    if (res.destroyed || res.writableEnded) {
+      closeStream();
+      return;
+    }
+    try {
+      res.write(COMMENT);
+    } catch (err) {
+      log('raw-get-stream: keepalive write failed', err);
+      closeStream();
+    }
+  }, 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;
+}
+
+export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
+  const check = validateStandaloneSession(opts.transport, opts.req);
+  if (!check.ok) {
+    opts.res.writeHead(check.status ?? 400).end(check.message ?? 'bad request');
+    return false;
+  }
+  if (opts.previous && !opts.previous.closed) opts.previous.close();
+  await serveStandaloneGet(opts);
+  return true;
+}

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

@@ -0,0 +1,73 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage } from 'node:http';
+import { verifySession } from '../daemon/session.js';
+import { agentIdForKey } from '../db/key-map.js';
+
+export type RequestIdentity =
+  | { kind: 'agent'; agentId: string }
+  | { kind: 'google'; email: string; agentIds: 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 interface AuthConfig {
+  sessionSecret: string;
+}
+
+export function authConfigFromEnv(): AuthConfig {
+  return { sessionSecret: process.env.METRO_SESSION_SECRET?.trim() ?? '' };
+}
+
+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;
+}
+
+const looksLikeJwt = (token: string): boolean =>
+  /^[\w-]+\.[\w-]+\.[\w-]+$/.test(token);
+
+export function authenticate(
+  req: IncomingMessage,
+  cfg: AuthConfig,
+): RequestIdentity | null {
+  const token = extractToken(req);
+  if (!token) return null;
+
+  const agentId = agentIdForKey(token);
+  if (agentId !== undefined) return { kind: 'agent', agentId };
+
+  if (cfg.sessionSecret !== '' && looksLikeJwt(token)) {
+    try {
+      const { email, agentIds } = verifySession(token, cfg.sessionSecret);
+      return { kind: 'google', email, agentIds };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function allowedAgents(
+  identity: RequestIdentity | undefined,
+): Set<string> {
+  if (identity?.kind === 'google') return new Set(identity.agentIds);
+  if (identity?.kind === 'agent') return new Set([identity.agentId]);
+  return new Set();
+}

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

@@ -0,0 +1,172 @@
+import { randomUUID } from 'node:crypto';
+import { currentBusSeq } from '../daemon/events.js';
+import { errMsg } from '../daemon/log.js';
+import { newReplayLedger, type ReplayLedger } from '../channels/relay.js';
+import { McpSession, channelLog } from './session.js';
+import { agentsInScopeKey } from './session-route.js';
+import { sessionScopeKey, type SessionOwnership } from './session-route.js';
+import type { RequestIdentity } from './request-identity.js';
+
+export const MAX_SESSIONS = 64;
+export const SESSION_IDLE_MS = 10 * 60_000;
+export const LEDGER_MAX = 256;
+const SWEEP_MS = 60_000;
+
+export interface AgentLiveness {
+  connected: boolean;
+  lastSeenAt: number;
+}
+
+export class SessionCapacityError extends Error {
+  constructor() {
+    super('too many live MCP sessions');
+  }
+}
+
+export class SessionRegistry {
+  private readonly byId = new Map<string, McpSession>();
+  private readonly byScope = new Map<string, McpSession>();
+  private readonly ledgers = new Map<string, ReplayLedger>();
+  private readonly sweeper: ReturnType<typeof setInterval>;
+  private readonly log: (...a: unknown[]) => void;
+  private started = false;
+  private floor = 0;
+
+  constructor(log: (...a: unknown[]) => void = channelLog) {
+    this.log = log;
+    this.sweeper = setInterval(() => {
+      this.sweep(Date.now());
+    }, SWEEP_MS);
+    this.sweeper.unref?.();
+  }
+
+  get size(): number {
+    return this.byId.size;
+  }
+
+  get(sessionId: string): McpSession | undefined {
+    return this.byId.get(sessionId);
+  }
+
+  liveness(): Map<string, AgentLiveness> {
+    const out = new Map<string, AgentLiveness>();
+    for (const session of this.byId.values())
+      for (const id of agentsInScopeKey(session.scopeKey)) {
+        const prev = out.get(id);
+        out.set(id, {
+          connected: (prev?.connected ?? false) || session.streamAttached,
+          lastSeenAt: Math.max(prev?.lastSeenAt ?? 0, session.lastSeenAt),
+        });
+      }
+    return out;
+  }
+
+  forScope(scopeKey: string): McpSession | undefined {
+    return this.byScope.get(scopeKey);
+  }
+
+  ownership(
+    presented: string | undefined,
+    scopeKey: string,
+  ): SessionOwnership {
+    if (presented === undefined) return 'none';
+    const found = this.byId.get(presented);
+    if (!found) return 'none';
+    return found.scopeKey === scopeKey ? 'mine' : 'theirs';
+  }
+
+  startInbound(): void {
+    if (this.started) return;
+    this.started = true;
+    this.floor = currentBusSeq();
+    for (const session of this.byId.values()) session.startChannel();
+  }
+
+  async create(
+    identity: RequestIdentity,
+    adoptId?: string,
+  ): Promise<McpSession> {
+    const scopeKey = sessionScopeKey(identity);
+    const id = adoptId ?? randomUUID();
+    await this.byScope.get(scopeKey)?.close();
+    await this.byId.get(id)?.close();
+    await this.makeRoom();
+    const session = await McpSession.open({
+      id,
+      scopeKey,
+      adopted: adoptId !== undefined,
+      ledger: this.ledgerFor(scopeKey),
+      onClosed: (s) => {
+        this.forget(s);
+      },
+    });
+    this.byId.set(id, session);
+    this.byScope.set(scopeKey, session);
+    if (this.started) session.startChannel();
+    this.log('session: opened', 'id', id, 'scope', scopeKey, 'live', this.byId.size);
+    return session;
+  }
+
+  async closeScope(scopeKey: string): Promise<boolean> {
+    const session = this.byScope.get(scopeKey);
+    if (!session) return false;
+    this.log('session: closed, credential rotated', 'id', session.id, 'scope', scopeKey);
+    await session.close();
+    return true;
+  }
+
+  async closeAll(): Promise<void> {
+    clearInterval(this.sweeper);
+    for (const session of [...this.byId.values()]) await session.close();
+    this.ledgers.clear();
+  }
+
+  sweep(now: number): number {
+    let reaped = 0;
+    for (const session of [...this.byId.values()]) {
+      if (session.streamAttached) continue;
+      if (now - session.lastSeenAt <= SESSION_IDLE_MS) continue;
+      this.log('session: reaped idle', 'id', session.id, 'scope', session.scopeKey);
+      session.close().catch((err: unknown) => {
+        this.log('session: reap close failed', 'id', session.id, errMsg(err));
+      });
+      reaped += 1;
+    }
+    return reaped;
+  }
+
+  private forget(session: McpSession): void {
+    if (this.byId.get(session.id) === session) this.byId.delete(session.id);
+    if (this.byScope.get(session.scopeKey) === session)
+      this.byScope.delete(session.scopeKey);
+  }
+
+  private async makeRoom(): Promise<void> {
+    if (this.byId.size < MAX_SESSIONS) return;
+    this.sweep(Date.now());
+    if (this.byId.size < MAX_SESSIONS) return;
+    const idle = [...this.byId.values()]
+      .filter((s) => !s.streamAttached)
+      .sort((a, b) => a.lastSeenAt - b.lastSeenAt)
+      .at(0);
+    if (!idle) throw new SessionCapacityError();
+    await idle.close();
+  }
+
+  private ledgerFor(scopeKey: string): ReplayLedger {
+    const found = this.ledgers.get(scopeKey);
+    if (found) {
+      this.ledgers.delete(scopeKey);
+      this.ledgers.set(scopeKey, found);
+      return found;
+    }
+    const fresh = newReplayLedger(this.started ? this.floor : currentBusSeq());
+    this.ledgers.set(scopeKey, fresh);
+    while (this.ledgers.size > LEDGER_MAX) {
+      const oldest = this.ledgers.keys().next();
+      if (oldest.done) break;
+      this.ledgers.delete(oldest.value);
+    }
+    return fresh;
+  }
+}

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

@@ -0,0 +1,43 @@
+import { allowedAgents, type RequestIdentity } from './request-identity.js';
+
+export function sessionScopeKey(identity: RequestIdentity): string {
+  const ids = [...allowedAgents(identity)].sort();
+  if (ids.length > 0) return `${AGENTS_PREFIX}${ids.join(',')}`;
+  return `email:${identity.kind === 'google' ? identity.email : identity.agentId}`;
+}
+
+const AGENTS_PREFIX = 'agents:';
+
+export function agentsInScopeKey(scopeKey: string): string[] {
+  if (!scopeKey.startsWith(AGENTS_PREFIX)) return [];
+  return scopeKey.slice(AGENTS_PREFIX.length).split(',').filter(Boolean);
+}
+
+export type SessionOwnership = 'none' | 'mine' | 'theirs';
+
+export type SessionRoute =
+  | { kind: 'create'; adoptId?: string }
+  | { kind: 'use' }
+  | { kind: 'reject'; status: number; message: string };
+
+export interface SessionRouteInput {
+  isInitialize: boolean;
+  presented: string | undefined;
+  ownership: SessionOwnership;
+  hasOwnSession: boolean;
+}
+
+const NO_SESSION_HEADER = 'Bad Request: Mcp-Session-Id header is required';
+const NOT_FOUND = 'Session not found';
+
+export function routeSession(input: SessionRouteInput): SessionRoute {
+  if (input.isInitialize) return { kind: 'create' };
+  if (input.presented === undefined)
+    return input.hasOwnSession
+      ? { kind: 'use' }
+      : { kind: 'reject', status: 400, message: NO_SESSION_HEADER };
+  if (input.ownership === 'mine') return { kind: 'use' };
+  if (input.ownership === 'theirs')
+    return { kind: 'reject', status: 404, message: NOT_FOUND };
+  return { kind: 'create', adoptId: input.presented };
+}

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

@@ -0,0 +1,211 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { InboundRelay } from '../channels/inbound.js';
+import { ChannelRelay, type ReplayLedger } from '../channels/relay.js';
+import { errMsg } from '../daemon/log.js';
+import {
+  allowlistForLine,
+  senderMatchesAllowlist,
+} from '../db/agent-map.js';
+import { accountStationNames } from '../stations/registry.js';
+import { MCP_INSTRUCTIONS } from './tool-schemas.js';
+import { ChannelOwner } from './channel-owner.js';
+import { BoundedEventStore } from './event-store.js';
+import { registerPermissionRelay } from './permission-relay.js';
+import { registerToolHandlers, toolSchemaSignature } from './tool-dispatch.js';
+import { web, type RawGetSink } from './raw-get-stream.js';
+import type { RequestIdentity } from './request-identity.js';
+
+export const channelLog = (...a: unknown[]): void => {
+  console.error('[metro-mcp]', ...a);
+};
+
+const getStations = (): Set<string> => new Set(accountStationNames());
+
+const senderAllowed = (from: string, line: string): boolean => {
+  const allowlist = allowlistForLine(line);
+  return allowlist ? senderMatchesAllowlist(allowlist, from) : true;
+};
+
+function makeTransport(
+  id: string,
+  eventStore: BoundedEventStore,
+  adopted: boolean,
+): StreamableHTTPServerTransport {
+  const t = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => id,
+    eventStore,
+  });
+  if (!adopted) return t;
+  const inner = web(t);
+  if (inner) {
+    inner.sessionId = id;
+    inner._initialized = true;
+  }
+  return t;
+}
+
+export interface SessionInit {
+  id: string;
+  scopeKey: string;
+  adopted: boolean;
+  ledger: ReplayLedger;
+  onClosed: (session: McpSession) => void;
+}
+
+export class McpSession {
+  readonly id: string;
+  readonly scopeKey: string;
+  readonly owner = new ChannelOwner();
+  readonly eventStore: BoundedEventStore;
+  readonly transport: StreamableHTTPServerTransport;
+  readonly server: Server;
+  readonly relay: InboundRelay;
+  readonly channel: ChannelRelay;
+  lastSeenAt = Date.now();
+  private sink: RawGetSink | undefined;
+  private unsubscribe: (() => void) | undefined;
+  private closed = false;
+  private issuedSchema: string | undefined;
+  private announcing = false;
+  private readonly onClosed: (session: McpSession) => void;
+
+  private constructor(init: SessionInit) {
+    this.id = init.id;
+    this.scopeKey = init.scopeKey;
+    this.issuedSchema = init.adopted ? undefined : toolSchemaSignature();
+    this.onClosed = init.onClosed;
+    this.eventStore = new BoundedEventStore({
+      scopeOf: () => this.owner.scope(),
+    });
+    this.transport = makeTransport(init.id, this.eventStore, init.adopted);
+    this.server = new Server(
+      { name: 'metro', version: '0.1.0' },
+      {
+        capabilities: {
+          experimental: {
+            'claude/channel': {},
+            'claude/channel/permission': {},
+          },
+          tools: { listChanged: true },
+        },
+        instructions: MCP_INSTRUCTIONS,
+      },
+    );
+    registerToolHandlers(this.server, {
+      markCurrent: (): void => {
+        this.issuedSchema = toolSchemaSignature();
+      },
+      deliver: (send): void => {
+        this.deliverSchemaNotice(send, 'request');
+      },
+    });
+    this.relay = new InboundRelay({
+      mcp: this.server,
+      log: channelLog,
+      getStations,
+      senderAllowed,
+    });
+    registerPermissionRelay({
+      mcp: this.server,
+      relay: this.relay,
+      owner: this.owner,
+      log: channelLog,
+    });
+    this.channel = new ChannelRelay({
+      relay: this.relay,
+      log: channelLog,
+      inScope: (line) => this.owner.inScope(line),
+      ledger: init.ledger,
+    });
+  }
+
+  static async open(init: SessionInit): Promise<McpSession> {
+    const session = new McpSession(init);
+    await session.server.connect(session.transport);
+    session.server.onclose = (): void => {
+      session.close().catch((err: unknown) => {
+        channelLog('session: close failed', 'id', init.id, errMsg(err));
+      });
+    };
+    return session;
+  }
+
+  get streamAttached(): boolean {
+    return this.sink !== undefined && !this.sink.closed;
+  }
+
+  get currentSink(): RawGetSink | undefined {
+    return this.sink;
+  }
+
+  touch(): void {
+    this.lastSeenAt = Date.now();
+  }
+
+  startChannel(): void {
+    this.unsubscribe ??= this.channel.start();
+  }
+
+  bindSink(sink: RawGetSink | undefined, identity: RequestIdentity): void {
+    this.sink = sink;
+    if (sink === undefined) {
+      this.owner.releaseStream();
+      return;
+    }
+    this.owner.bindStream(identity);
+    this.announceToolSchema();
+  }
+
+  private get schemaNoticeDue(): boolean {
+    return this.issuedSchema !== toolSchemaSignature();
+  }
+
+  private announceToolSchema(): void {
+    if (!this.streamAttached) return;
+    this.deliverSchemaNotice(
+      () => this.server.sendToolListChanged(),
+      'stream',
+    );
+  }
+
+  private deliverSchemaNotice(send: () => Promise<void>, via: string): void {
+    if (!this.schemaNoticeDue || this.announcing) return;
+    this.announcing = true;
+    channelLog(
+      'session: tool list changed',
+      'id',
+      this.id,
+      'scope',
+      this.scopeKey,
+      'via',
+      via,
+    );
+    send()
+      .then(() => {
+        this.issuedSchema = toolSchemaSignature();
+        this.announcing = false;
+      })
+      .catch((err: unknown) => {
+        this.announcing = false;
+        channelLog('session: tool list changed notice failed', errMsg(err));
+      });
+  }
+
+  dropStream(): void {
+    const sink = this.sink;
+    this.sink = undefined;
+    this.owner.releaseStream();
+    sink?.close();
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.onClosed(this);
+    this.dropStream();
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    await this.server.close().catch(() => undefined);
+  }
+}