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

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

@@ -0,0 +1,29 @@
+import { eventInScope } from '../db/agent-scope.js';
+import { allowedAgents, type RequestIdentity } from './request-identity.js';
+import { sessionScopeKey } from './session-route.js';
+
+export class ChannelOwner {
+  private stream: RequestIdentity | undefined;
+
+  bindStream(identity: RequestIdentity): void {
+    this.stream = identity;
+  }
+
+  releaseStream(): void {
+    this.stream = undefined;
+  }
+
+  scope(): Set<string> {
+    return allowedAgents(this.stream);
+  }
+
+  streamBelongsTo(identity: RequestIdentity): boolean {
+    if (this.stream === undefined) return false;
+    return sessionScopeKey(this.stream) === sessionScopeKey(identity);
+  }
+
+  inScope(line: string): boolean {
+    if (this.stream === undefined) return false;
+    return eventInScope(this.scope(), line);
+  }
+}

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

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { forwardTrainCall } from '../daemon/train-call.js';
+import { errMsg, log } from '../daemon/log.js';
+import { TrainError } from '../daemon/train-error.js';
+import { type ToolContext, type ToolResult } from '../stations/types.js';
+
+export async function metroCall(
+  train: string,
+  action: string,
+  args: Record<string, unknown>,
+): Promise<{ result: unknown }> {
+  const line = typeof args.line === 'string' ? args.line : undefined;
+  log.info({ train, action, line }, 'metro: dispatching train call');
+  let response;
+  try {
+    response = await forwardTrainCall(train, action, args);
+  } catch (err) {
+    log.warn(
+      { train, action, line, err: errMsg(err) },
+      'metro: train call failed to dispatch',
+    );
+    throw new TrainError(
+      'metro_call_failed',
+      `metro ${action} ${train}: ${errMsg(err)}`,
+    );
+  }
+  if (response.error) {
+    log.warn(
+      { train, action, line, err: response.error },
+      'metro: train call returned error',
+    );
+    throw new TrainError(
+      'metro_call_error',
+      `metro ${action} ${train}: ${response.error}`,
+    );
+  }
+  log.info({ train, action, line }, 'metro: train call ok');
+  return { result: response.result ?? null };
+}
+
+export const ok = (text: string): ToolResult => ({
+  content: [{ type: 'text', text }],
+});
+export const okJson = (v: unknown): ToolResult => ({
+  content: [{ type: 'text', text: JSON.stringify(v, null, 2) }],
+});
+export const errResult = (text: string): ToolResult => ({
+  content: [{ type: 'text', text }],
+  isError: true,
+});
+export const toErr = (name: string, e: unknown): ToolResult =>
+  e instanceof TrainError
+    ? errResult(e.message)
+    : errResult(`metro ${name} failed: ${String(e)}`);
+
+export const makeCtx = (station: string): ToolContext => ({
+  call: (action, args) => metroCall(station, action, args),
+  ok,
+  okJson,
+  err: errResult,
+  readFile: (path) => readFile(path),
+});

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

@@ -0,0 +1,91 @@
+import type {
+  EventStore,
+  EventId,
+  StreamId,
+} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { frameInScope, frameLine } from './frame-scope.js';
+
+export const EVENT_STORE_MAX = 500;
+
+interface StoredEvent {
+  eventId: EventId;
+  streamId: StreamId;
+  message: JSONRPCMessage;
+  line: string | undefined;
+  owner: Set<string>;
+}
+
+export interface EventStoreDeps {
+  scopeOf: () => Set<string>;
+  max?: number;
+}
+
+export interface ScopedReplay {
+  send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+  scope: Set<string> | undefined;
+  onWithheld?: (eventId: EventId, line: string | undefined) => void;
+}
+
+const SEP = '_';
+
+const encodeEventId = (streamId: StreamId, seq: number): EventId =>
+  `${streamId}${SEP}${seq}`;
+
+const decodeStreamId = (eventId: EventId): StreamId | undefined => {
+  const idx = eventId.lastIndexOf(SEP);
+  if (idx <= 0) return undefined;
+  return eventId.slice(0, idx);
+};
+
+export class BoundedEventStore implements EventStore {
+  private readonly max: number;
+  private readonly scopeOf: () => Set<string>;
+  private readonly events: StoredEvent[] = [];
+  private seq = 0;
+
+  constructor(deps: EventStoreDeps) {
+    this.scopeOf = deps.scopeOf;
+    this.max = deps.max ?? EVENT_STORE_MAX;
+  }
+
+  storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId> {
+    const eventId = encodeEventId(streamId, ++this.seq);
+    this.events.push({
+      eventId,
+      streamId,
+      message,
+      line: frameLine(message),
+      owner: new Set(this.scopeOf()),
+    });
+    if (this.events.length > this.max) this.events.shift();
+    return Promise.resolve(eventId);
+  }
+
+  getStreamIdForEventId(eventId: EventId): Promise<StreamId | undefined> {
+    return Promise.resolve(decodeStreamId(eventId));
+  }
+
+  async replayEventsAfter(
+    lastEventId: EventId,
+    { send, scope, onWithheld }: ScopedReplay,
+  ): Promise<StreamId> {
+    const streamId = decodeStreamId(lastEventId);
+    if (streamId === undefined) return '';
+    const allowed = scope ?? new Set<string>();
+    let seen = false;
+    for (const e of this.events) {
+      if (e.streamId !== streamId) continue;
+      if (!seen) {
+        if (e.eventId === lastEventId) seen = true;
+        continue;
+      }
+      if (!frameInScope(allowed, e)) {
+        onWithheld?.(e.eventId, e.line);
+        continue;
+      }
+      await send(e.eventId, e.message);
+    }
+    return streamId;
+  }
+}

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

@@ -0,0 +1,21 @@
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { eventInScope } from '../db/agent-scope.js';
+import { str } from './str.js';
+
+export interface FrameOrigin {
+  line: string | undefined;
+  owner: Set<string>;
+}
+
+export function frameLine(message: JSONRPCMessage): string | undefined {
+  const params: unknown = (message as { params?: unknown }).params;
+  if (typeof params !== 'object' || params === null) return undefined;
+  const meta: unknown = (params as { meta?: unknown }).meta;
+  if (typeof meta !== 'object' || meta === null) return undefined;
+  return str((meta as { line?: unknown }).line) || undefined;
+}
+
+export function frameInScope(scope: Set<string>, origin: FrameOrigin): boolean {
+  if (origin.line !== undefined) return eventInScope(scope, origin.line);
+  return origin.owner.size > 0 && [...origin.owner].every((id) => scope.has(id));
+}

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

@@ -0,0 +1,129 @@
+import { stationByName, stationForLine } from '../stations/registry.js';
+import type {
+  GroupOp,
+  GroupResult,
+  MemberOutcome,
+  Station,
+  ToolResult,
+} from '../stations/types.js';
+import { makeCtx, okJson, toErr } from './ctx.js';
+import { str } from './str.js';
+
+export interface GroupOpResult {
+  op: GroupOp;
+  line: string;
+  station: string;
+  supported: boolean;
+  reason?: string;
+  id?: string;
+  name?: string;
+  members: MemberOutcome[];
+  inviteLink?: string;
+}
+
+export function wrapGroupResult(
+  op: GroupOp,
+  line: string,
+  station: string,
+  r: GroupResult,
+): GroupOpResult {
+  const out: GroupOpResult = {
+    op,
+    line: r.line ?? line,
+    station,
+    supported: r.capability.supported,
+    members: Array.isArray(r.members) ? r.members : [],
+  };
+  if (r.capability.reason) out.reason = r.capability.reason;
+  if (r.id) out.id = r.id;
+  if (r.name) out.name = r.name;
+  if (r.inviteLink) out.inviteLink = r.inviteLink;
+  return out;
+}
+
+export function unsupportedGroup(
+  op: GroupOp,
+  line: string,
+  station: string,
+  reason: string,
+): GroupOpResult {
+  return { op, line, station, supported: false, reason, members: [] };
+}
+
+const defaultReason = (op: GroupOp, station: string): string =>
+  `${op} is not supported on ${station}`;
+
+const supportsOp = (station: Station, op: GroupOp): boolean =>
+  station.groupOps?.has(op) ?? false;
+
+function strList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v) => typeof v === 'string' && v.length > 0) as string[];
+}
+
+function forwardArgs(a: Record<string, unknown>): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  const members = strList(a.members);
+  if (members.length) args.members = members;
+  for (const key of ['name', 'account', 'parent', 'addresses', 'inboxIds'])
+    if (a[key] !== undefined) args[key] = a[key];
+  if (a.private !== undefined) args.private = a.private;
+  return args;
+}
+
+async function runGroupOp(
+  op: GroupOp,
+  verb: string,
+  line: string,
+  station: Station,
+  args: Record<string, unknown>,
+): Promise<ToolResult> {
+  if (!supportsOp(station, op))
+    return okJson(
+      unsupportedGroup(op, line, station.name, defaultReason(op, station.name)),
+    );
+  try {
+    const { result } = await makeCtx(station.name).call(verb, args);
+    return okJson(wrapGroupResult(op, line, station.name, result as GroupResult));
+  } catch (e) {
+    return toErr(op, e);
+  }
+}
+
+export async function dispatchCreateGroup(
+  a: Record<string, unknown>,
+): Promise<ToolResult> {
+  const name = str(a.station);
+  if (!name)
+    return okJson(unsupportedGroup('create_group', '', '', 'create_group requires `station`'));
+  const station = stationByName(name);
+  if (!station)
+    return okJson(unsupportedGroup('create_group', '', name, `no station named ${name}`));
+  return runGroupOp('create_group', 'groupCreate', '', station, forwardArgs(a));
+}
+
+async function dispatchLineOp(
+  op: GroupOp,
+  verb: string,
+  a: Record<string, unknown>,
+): Promise<ToolResult> {
+  const line = str(a.line);
+  if (!line) return okJson(unsupportedGroup(op, '', '', `${op} requires \`line\``));
+  const station = stationForLine(line);
+  if (!station)
+    return okJson(unsupportedGroup(op, line, '', `no station for line ${line}`));
+  return runGroupOp(op, verb, line, station, { line, ...forwardArgs(a) });
+}
+
+export const dispatchAddMembers = (
+  a: Record<string, unknown>,
+): Promise<ToolResult> => dispatchLineOp('add_members', 'groupAddMembers', a);
+
+export const dispatchRemoveMembers = (
+  a: Record<string, unknown>,
+): Promise<ToolResult> =>
+  dispatchLineOp('remove_members', 'groupRemoveMembers', a);
+
+export const dispatchInviteLink = (
+  a: Record<string, unknown>,
+): Promise<ToolResult> => dispatchLineOp('invite_link', 'groupInviteLink', a);

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

@@ -0,0 +1,192 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  BodyTooLargeError,
+  readBody as readBodyBuffer,
+} from '../daemon/http.js';
+import {
+  allowedAgents,
+  authConfigFromEnv,
+  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, authConfigFromEnv());
+    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/mcp/src/mcp/member-tools.ts

@@ -0,0 +1,72 @@
+import { stationForLine } from '../stations/registry.js';
+import type {
+  MemberCapability,
+  MemberList,
+  MetroMember,
+  ToolResult,
+} from '../stations/types.js';
+import { makeCtx, okJson, toErr } from './ctx.js';
+import { str } from './str.js';
+
+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/mcp/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);
+      }
+    },
+  );
+}