@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,191 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  BodyTooLargeError,
+  readBody as readBodyBuffer,
+} from '../routes/http.js';
+import {
+  allowedAgents,
+  authenticate,
+  runWithIdentity,
+  type RequestIdentity,
+} from './request-identity.js';
+import {
+  headerValue,
+  isStandaloneGet,
+  serveChannelGet,
+} from './raw-get-stream.js';
+import { channelLog, type McpSession } from './session.js';
+import {
+  SessionCapacityError,
+  SessionRegistry,
+  type AgentLiveness,
+} from './session-registry.js';
+import { routeSession, sessionScopeKey } from './session-route.js';
+
+const isInitialize = (b: unknown): boolean =>
+  !!b &&
+  typeof b === 'object' &&
+  (b as { method?: string }).method === 'initialize';
+
+const MCP_BODY_MAX = 32 * 1024 * 1024;
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  const raw = (await readBodyBuffer(req, MCP_BODY_MAX)).toString('utf8');
+  try {
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+type ParsedBody = { ok: true; body: unknown } | { ok: false };
+
+async function readOrReject(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<ParsedBody> {
+  try {
+    const body = req.method === 'POST' ? await readBody(req) : undefined;
+    return { ok: true, body };
+  } catch (err) {
+    if (!(err instanceof BodyTooLargeError)) throw err;
+    res.writeHead(413).end('payload too large');
+    return { ok: false };
+  }
+}
+
+async function resolveSession(
+  registry: SessionRegistry,
+  req: IncomingMessage,
+  body: unknown,
+  identity: RequestIdentity,
+  res: ServerResponse,
+): Promise<McpSession | undefined> {
+  const presented = headerValue(req, 'mcp-session-id');
+  const scopeKey = sessionScopeKey(identity);
+  const route = routeSession({
+    isInitialize: isInitialize(body),
+    presented,
+    ownership: registry.ownership(presented, scopeKey),
+    hasOwnSession: registry.forScope(scopeKey) !== undefined,
+  });
+  if (route.kind === 'reject') {
+    channelLog(
+      'session: refused',
+      'status',
+      route.status,
+      'presented',
+      presented ?? '(none)',
+      'scope',
+      scopeKey,
+    );
+    res.writeHead(route.status).end(route.message);
+    return undefined;
+  }
+  if (route.kind === 'use') {
+    const found =
+      presented === undefined
+        ? registry.forScope(scopeKey)
+        : registry.get(presented);
+    if (found) return found;
+    res.writeHead(404).end('Session not found');
+    return undefined;
+  }
+  try {
+    return await registry.create(identity, route.adoptId);
+  } catch (err) {
+    if (!(err instanceof SessionCapacityError)) throw err;
+    res.writeHead(503).end(err.message);
+    return undefined;
+  }
+}
+
+async function serveGet(
+  session: McpSession,
+  req: IncomingMessage,
+  res: ServerResponse,
+  identity: RequestIdentity,
+): Promise<void> {
+  if (session.currentSink && !session.owner.streamBelongsTo(identity)) {
+    channelLog(
+      'session: refused stream takeover',
+      'session',
+      session.id,
+      'scope',
+      session.scopeKey,
+    );
+    res.writeHead(409).end('Conflict: stream held by another identity');
+    return;
+  }
+  const served = await serveChannelGet({
+    transport: session.transport,
+    eventStore: session.eventStore,
+    scope: allowedAgents(identity),
+    req,
+    res,
+    previous: session.currentSink,
+    log: channelLog,
+    registerSink: (sink) => {
+      session.bindSink(sink, identity);
+    },
+  });
+  if (served) session.channel.replayMissed();
+}
+
+let activeRegistry: SessionRegistry | undefined;
+
+export function agentLiveness(): Map<string, AgentLiveness> {
+  return activeRegistry?.liveness() ?? new Map<string, AgentLiveness>();
+}
+
+export async function closeAgentSession(agentId: string): Promise<boolean> {
+  const scopeKey = sessionScopeKey({ kind: 'agent', agentId });
+  return (await activeRegistry?.closeScope(scopeKey)) ?? false;
+}
+
+export async function createMetroMcp(): Promise<{
+  httpHandler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+  startInbound: () => void;
+}> {
+  await activeRegistry?.closeAll();
+  const registry = new SessionRegistry(channelLog);
+  activeRegistry = registry;
+
+  const httpHandler = async (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<void> => {
+    const identity = authenticate(req);
+    if (!identity) {
+      res.writeHead(401).end('unauthorized');
+      return;
+    }
+    const parsed = await readOrReject(req, res);
+    if (!parsed.ok) return;
+    await runWithIdentity(identity, async () => {
+      const session = await resolveSession(
+        registry,
+        req,
+        parsed.body,
+        identity,
+        res,
+      );
+      if (!session) return;
+      session.touch();
+      if (isStandaloneGet(req)) {
+        await serveGet(session, req, res, identity);
+        return;
+      }
+      await session.transport.handleRequest(req, res, parsed.body);
+    });
+  };
+
+  const startInbound = (): void => {
+    registry.startInbound();
+    channelLog(
+      'inbound: per-session bus subscriptions (bounded replay on reconnect)',
+    );
+  };
+
+  return { httpHandler, startInbound };
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/member-tools.ts

@@ -0,0 +1,72 @@
+import { stationForLine } from '../stations/registry.js';
+import type {
+  MemberCapability,
+  MemberList,
+  MetroMember,
+  ToolResult,
+} from '@metro-labs/core/stations/types';
+import { makeCtx, okJson, toErr } from './ctx.js';
+import { str } from '@metro-labs/core/str';
+
+export interface MemberListResult {
+  line: string;
+  station: string;
+  memberCount: number;
+  members: MetroMember[];
+  capability: MemberCapability;
+}
+
+export function wrapMemberList(
+  line: string,
+  station: string,
+  list: MemberList,
+): MemberListResult {
+  const members = Array.isArray(list.members) ? list.members : [];
+  return {
+    line,
+    station,
+    memberCount: members.length,
+    members,
+    capability: list.capability,
+  };
+}
+
+export function unsupportedMembers(
+  line: string,
+  station: string,
+  reason: string,
+): MemberListResult {
+  return {
+    line,
+    station,
+    memberCount: 0,
+    members: [],
+    capability: { supported: false, complete: false, reason },
+  };
+}
+
+export async function dispatchListMembers(
+  a: Record<string, unknown>,
+): Promise<ToolResult> {
+  const line = str(a.line);
+  if (!line) return okJson(unsupportedMembers('', '', 'list_members requires `line`'));
+  const station = stationForLine(line);
+  if (!station)
+    return okJson(unsupportedMembers(line, '', `no station for line ${line}`));
+  if (!station.hasAccounts || !station.hasTrain)
+    return okJson(
+      unsupportedMembers(
+        line,
+        station.name,
+        `${station.name} lines have no member roster`,
+      ),
+    );
+  const args: Record<string, unknown> = { line };
+  if (typeof a.limit === 'number') args.limit = a.limit;
+  try {
+    const { result } = await makeCtx(station.name).call('listMembers', args);
+    return okJson(wrapMemberList(line, station.name, result as MemberList));
+  } catch (e) {
+    return toErr('list_members', e);
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp/permission-relay.ts

@@ -0,0 +1,66 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { InboundRelay } from '../channels/inbound.js';
+import type { ChannelOwner } from './channel-owner.js';
+import { metroCall } from './ctx.js';
+
+const PermissionRequestSchema = z.object({
+  method: z.literal('notifications/claude/channel/permission_request'),
+  params: z.object({
+    request_id: z.string(),
+    tool_name: z.string(),
+    description: z.string(),
+    input_preview: z.string(),
+  }),
+});
+
+type PermissionRequest = z.infer<typeof PermissionRequestSchema>;
+
+const trainOf = (line: string): string => line.split('/')[2] ?? '';
+
+async function metroSend(line: string, text: string): Promise<void> {
+  await metroCall(trainOf(line), 'send', { line, text });
+}
+
+function promptBody(params: PermissionRequest['params']): string {
+  return (
+    `Claude wants to run ${params.tool_name}: ${params.description}\n` +
+    (params.input_preview ? `\n${params.input_preview}\n` : '') +
+    `\nReply "yes ${params.request_id}" or "no ${params.request_id}"`
+  );
+}
+
+export interface PermissionRelayDeps {
+  mcp: Server;
+  relay: InboundRelay;
+  owner: ChannelOwner;
+  log: (...a: unknown[]) => void;
+}
+
+export function registerPermissionRelay(deps: PermissionRelayDeps): void {
+  const { mcp, relay, owner, log } = deps;
+  mcp.setNotificationHandler(
+    PermissionRequestSchema as never,
+    async (n: PermissionRequest) => {
+      const { params } = n;
+      const line = relay.knownLine;
+      if (!line) {
+        log('permission_request but no known line to relay to', params.request_id);
+        return;
+      }
+      if (!owner.inScope(line)) {
+        log(
+          'permission_request: known line is outside the channel session scope',
+          params.request_id,
+        );
+        return;
+      }
+      relay.registerPermission(params.request_id);
+      try {
+        await metroSend(line, promptBody(params));
+      } catch (e) {
+        log('relay send failed', e);
+      }
+    },
+  );
+}

package/runtime/node_modules/@metro-labs/daemon/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/daemon/src/mcp/request-identity.ts

@@ -0,0 +1,47 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage } from 'node:http';
+import { agentIdForKey } from '../agents/keys.js';
+
+export type RequestIdentity =
+  | { kind: 'agent'; agentId: string }
+  | { kind: 'session'; subject: 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 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 {
+  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> {
+  if (identity?.kind === 'session') return new Set(identity.agentIds);
+  if (identity?.kind === 'agent') return new Set([identity.agentId]);
+  return new Set();
+}