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

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

@@ -0,0 +1,172 @@
+import { randomUUID } from 'node:crypto';
+import { currentBusSeq } from '@metro-labs/core/events';
+import { errMsg } from '@metro-labs/core/log';
+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/daemon/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 `user:${identity.kind === 'session' ? identity.subject : 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/daemon/src/mcp/session.ts

@@ -0,0 +1,215 @@
+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 '@metro-labs/core/log';
+import {
+  allowlistForLine,
+  senderMatchesAllowlist,
+} from '../agents/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');
+      },
+    }, {
+      onSent: (id): void => {
+        this.relay.noteSent(id);
+      },
+    });
+    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);
+  }
+}

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

@@ -0,0 +1,215 @@
+import { createHash } from 'node:crypto';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { gatherAccounts } from './accounts.js';
+import {
+  STATIONS,
+  accountStationCapabilities,
+} from '../stations/registry.js';
+import type { Station, StationTool, ToolResult } from '@metro-labs/core/stations/types';
+import { COMMON_TOOLS, LIST_ACCOUNTS_TOOL } from './tool-schemas.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { dispatchMessageTool, type ToolHooks } from './call-tools.js';
+import { dispatchListMembers } from './member-tools.js';
+import {
+  dispatchAddMembers,
+  dispatchCreateGroup,
+  dispatchInviteLink,
+  dispatchRemoveMembers,
+} from './group-tools.js';
+import { dispatchCreateUpload } from './upload-tool.js';
+import { callTargetDenied, lineTargetDenied } from '../agents/scope.js';
+import { SOURCE_KEYS } from '../stations/attach-resolve.js';
+import { decodedLengthOf } from '../stations/attach-inline.js';
+import { log } from '@metro-labs/core/log';
+import {
+  allowedAgents,
+  currentIdentity,
+  type RequestIdentity,
+} from './request-identity.js';
+import { str } from '@metro-labs/core/str';
+
+const STATION_TOOLS = new Map<
+  string,
+  { station: Station; tool: StationTool }
+>();
+for (const s of STATIONS)
+  for (const t of s.tools) STATION_TOOLS.set(t.name, { station: s, tool: t });
+
+const CORE_DISPATCH: Record<
+  string,
+  (a: Record<string, unknown>) => Promise<ToolResult>
+> = {
+  list_members: dispatchListMembers,
+  create_group: dispatchCreateGroup,
+  add_members: dispatchAddMembers,
+  remove_members: dispatchRemoveMembers,
+  export_invite: dispatchInviteLink,
+  create_upload: dispatchCreateUpload,
+};
+
+const toolList = (): { tools: unknown[] } => ({
+  tools: [
+    ...COMMON_TOOLS,
+    ...STATIONS.flatMap((s) =>
+      s.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+    ),
+    LIST_ACCOUNTS_TOOL,
+  ],
+});
+
+let schemaSignature: string | undefined;
+
+export const toolSchemaSignature = (): string => {
+  schemaSignature ??= createHash('sha256')
+    .update(JSON.stringify(toolList()))
+    .digest('hex')
+    .slice(0, 16);
+  return schemaSignature;
+};
+
+async function handleListAccounts(
+  identity: RequestIdentity | undefined,
+): Promise<ToolResult> {
+  try {
+    return okJson({
+      accounts: await gatherAccounts(allowedAgents(identity)),
+      capabilities: accountStationCapabilities(),
+    });
+  } catch (e) {
+    return errResult(`metro list_accounts failed: ${String(e)}`);
+  }
+}
+
+function stationForTool(
+  name: string,
+  args: Record<string, unknown>,
+): string | undefined {
+  if (name === 'create_group') return str(args.station) || undefined;
+  return STATION_TOOLS.get(name)?.station.name;
+}
+
+export function scopeDenied(
+  identity: RequestIdentity | undefined,
+  name: string,
+  args: Record<string, unknown>,
+): boolean {
+  const allowed = allowedAgents(identity);
+  const station = stationForTool(name, args);
+  if (station !== undefined) return callTargetDenied(allowed, station, args);
+  return lineTargetDenied(allowed, args);
+}
+
+const sourceOf = (entry: unknown): string => {
+  const att = (entry ?? {}) as Record<string, unknown>;
+  const named = SOURCE_KEYS.filter(
+    (k) => typeof att[k] === 'string' && att[k] !== '',
+  );
+  if (named.length === 0) return 'none';
+  return named
+    .map((k) =>
+      k === 'data' ? `data(${decodedLengthOf(String(att.data))}B)` : k,
+    )
+    .join('+');
+};
+
+export const attachmentShape = (
+  a: Record<string, unknown>,
+): string[] | undefined =>
+  Array.isArray(a.attachments) ? a.attachments.map(sourceOf) : undefined;
+
+function logToolFailure(
+  name: string,
+  a: Record<string, unknown>,
+  result: ToolResult,
+): void {
+  log.warn(
+    {
+      tool: name,
+      agents: [...allowedAgents(currentIdentity())],
+      line: str(a.line),
+      attachments: attachmentShape(a),
+      err: result.content[0]?.text,
+    },
+    'mcp: tool call failed',
+  );
+}
+
+async function runTool(
+  req: { params: { name: string; arguments?: Record<string, unknown> } },
+  hooks: ToolHooks,
+): Promise<ToolResult> {
+  const name = req.params.name;
+  const a = req.params.arguments ?? {};
+
+  const identity = currentIdentity();
+  if (name !== 'list_accounts' && scopeDenied(identity, name, a))
+    return errResult('metro: this account is outside your authorized scope');
+
+  const owned = STATION_TOOLS.get(name);
+  if (owned) {
+    try {
+      return await owned.tool.handle(a, makeCtx(owned.station.name));
+    } catch (e) {
+      return toErr(name, e);
+    }
+  }
+
+  const core = CORE_DISPATCH[name];
+  if (core) return core(a);
+
+  if (name === 'list_accounts') return handleListAccounts(identity);
+
+  return dispatchMessageTool(name, a, hooks);
+}
+
+export async function callToolHandler(
+  req: { params: { name: string; arguments?: Record<string, unknown> } },
+  hooks: ToolHooks = {},
+): Promise<ToolResult> {
+  const result = await runTool(req, hooks);
+  if (result.isError === true)
+    logToolFailure(req.params.name, req.params.arguments ?? {}, result);
+  return result;
+}
+
+const TOOL_LIST_CHANGED = 'notifications/tools/list_changed';
+
+export interface SchemaNotice {
+  markCurrent: () => void;
+  deliver: (send: () => Promise<void>) => void;
+}
+
+interface NotifyingExtra {
+  sendNotification: (n: { method: string }) => Promise<void>;
+}
+
+export function registerToolHandlers(
+  server: Server,
+  notice?: SchemaNotice,
+  hooks: ToolHooks = {},
+): void {
+  server.setRequestHandler(ListToolsRequestSchema, () => {
+    notice?.markCurrent();
+    return toolList();
+  });
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    ((
+      req: { params: { name: string; arguments?: Record<string, unknown> } },
+      extra: NotifyingExtra,
+    ): Promise<ToolResult> => {
+      notice?.deliver(() =>
+        extra.sendNotification({ method: TOOL_LIST_CHANGED }),
+      );
+      return callToolHandler(req, hooks);
+    }) as Parameters<typeof server.setRequestHandler>[1],
+  );
+}