@stage-labs/metro 0.1.0-beta.30 → 0.1.0-beta.301

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/session-slot.ts

@@ -0,0 +1,141 @@
+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, type SessionKind } 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,
+    private readonly kind: SessionKind = 'chat',
+  ) {
+    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({
+      kind: this.kind,
+      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, 'kind', this.kind, 'adopted', adoptId !== undefined);
+    return session;
+  }
+
+  close(): Promise<void> {
+    return this.change(async () => {
+      await this.session?.close();
+    });
+  }
+}

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

@@ -0,0 +1,270 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { InboundRelay } from '../channels/inbound.js';
+import { answerPrompt, forgetPromptsOf, promptLine } from '../approvals/pending.js';
+import { noteOwnerLine } from '../approvals/owner-line.js';
+import { ChannelRelay, type ReplayLedger } from '../channels/relay.js';
+import { errMsg } from '@metro-labs/core/log';
+import { allowlistForLine, mayApprove, senderPermitted } from '../agents/map.js';
+import { accountStationNames, stationByName } from '../stations/registry.js';
+import { eventInScope } from '../agents/scope.js';
+import { MCP_INSTRUCTIONS, VOICE_MCP_INSTRUCTIONS } from './instructions.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 { sharedCalls } from '../voice/shared.js';
+import { CALL_STATE } from '@metro-labs/core/call';
+import { clientDiagnostic, diagnosticTag, type SessionDiagnostic } from './diagnostics.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, verified?: boolean): boolean =>
+  senderPermitted(allowlistForLine(line), from, verified);
+
+const approves = (station: string): boolean => stationByName(station)?.approvals !== false;
+
+const noteDirect = (line: string, from: string): void => {
+  if (mayApprove(line, from)) noteOwnerLine(line, from);
+};
+
+async function answerPermission(requestId: string, behavior: 'allow' | 'deny', line: string, from: string): Promise<boolean> {
+  if (promptLine(requestId) !== line || !mayApprove(line, from)) return false;
+  return (await answerPrompt(requestId, behavior, 'chat', line)) !== undefined;
+}
+
+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 type SessionKind = 'chat' | 'voice';
+
+const CHANNEL_CAPABILITIES = { experimental: { 'claude/channel': {}, 'claude/channel/permission': {} } };
+
+export interface SessionInit {
+  kind?: SessionKind;
+  id: string;
+  scope: Set<string>;
+  adopted: boolean;
+  ledger: ReplayLedger;
+  live: () => boolean;
+  onClosed: (session: McpSession) => void;
+}
+
+export class McpSession {
+  readonly id: string;
+  readonly scope: Set<string>;
+  readonly eventStore: BoundedEventStore;
+  readonly transport: StreamableHTTPServerTransport;
+  readonly server: Server;
+  readonly relay: InboundRelay;
+  readonly channel: ChannelRelay;
+  readonly live: () => boolean;
+  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 readonly kind: SessionKind;
+  private readonly openedAt = new Date().toISOString();
+  private clientInitializedAt: string | null = null;
+  private lastStreamAttachedAt: string | null = null;
+  private lastStreamDetachedAt: string | null = null;
+
+  private constructor(init: SessionInit) {
+    this.id = init.id;
+    this.kind = init.kind ?? 'chat';
+    this.scope = init.scope;
+    this.live = init.live;
+    this.issuedSchema = init.adopted ? undefined : toolSchemaSignature();
+    this.onClosed = init.onClosed;
+    this.eventStore = new BoundedEventStore();
+    this.transport = makeTransport(init.id, this.eventStore, init.adopted);
+    const voice = init.kind === 'voice';
+    this.server = new Server(
+      { name: 'metro', version: '0.1.0' },
+      {
+        capabilities: { ...(voice ? {} : CHANNEL_CAPABILITIES), tools: { listChanged: true } },
+        instructions: voice ? VOICE_MCP_INSTRUCTIONS : MCP_INSTRUCTIONS,
+      },
+    );
+    this.server.oninitialized = (): void => {
+      this.clientInitializedAt = new Date().toISOString();
+    };
+    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,
+      approves,
+      noteDirect,
+      answerPermission,
+      callMeta: (event) => voice ? () => ({}) : sharedCalls.bindChat(event, this.scope),
+    });
+    if (!voice)
+      registerPermissionRelay({
+        mcp: this.server,
+        relay: this.relay,
+        inScope: (line) => this.inScope(line),
+        live: this.live,
+        log: channelLog,
+      });
+    this.channel = new ChannelRelay({
+      relay: this.relay,
+      log: channelLog,
+      inScope: (line) => this.live() && this.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;
+  }
+
+  diagnostics(): SessionDiagnostic {
+    return {
+      tag: diagnosticTag(this.id),
+      openedAt: this.openedAt,
+      transportInitialized: web(this.transport)?._initialized === true,
+      clientInitializedAt: this.clientInitializedAt,
+      client: clientDiagnostic(this.server.getClientVersion()),
+      subscribed: this.unsubscribe !== undefined,
+      streamAttached: this.streamAttached,
+      lastStreamAttachedAt: this.lastStreamAttachedAt,
+      lastStreamDetachedAt: this.lastStreamDetachedAt,
+      stream: this.sink?.diagnostics() ?? null,
+    };
+  }
+
+  inScope(line: string): boolean {
+    return this.streamAttached && eventInScope(this.scope, line);
+  }
+
+  startChannel(): void {
+    this.unsubscribe ??= this.channel.start();
+  }
+
+  stopChannel(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+
+  replayMissed(): void {
+    if (this.live()) this.channel.replayMissed();
+  }
+
+  bindSink(sink: RawGetSink | undefined): void {
+    if (this.closed) {
+      sink?.close();
+      return;
+    }
+    if (sink === undefined && this.sink !== undefined) this.lastStreamDetachedAt = new Date().toISOString();
+    this.sink = sink;
+    if (sink !== undefined) {
+      this.lastStreamAttachedAt = new Date().toISOString();
+      this.announceCallState();
+      this.announceToolSchema();
+    }
+  }
+
+  private announceCallState(): void {
+    if (this.kind !== 'chat' || !this.streamAttached || this.server.getClientVersion()?.name !== 'metro-sdk-runner') return;
+    const active = sharedCalls.snapshot();
+    const route = active !== null && this.scope.has(active.agentId) && eventInScope(this.scope, active.line) ? active : null;
+    this.server.notification({ method: CALL_STATE, params: { route, ...(route === null ? {} : { meta: { line: route.line } }) } }).catch((err: unknown) => {
+      channelLog('session: call state notification failed', errMsg(err));
+      if (route !== null) sharedCalls.end(route);
+    });
+  }
+
+  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, '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;
+    if (sink !== undefined) this.lastStreamDetachedAt = new Date().toISOString();
+    this.sink = undefined;
+    sink?.close();
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.kind === 'chat') sharedCalls.revoke();
+    this.onClosed(this);
+    forgetPromptsOf(this.server);
+    this.dropStream();
+    this.stopChannel();
+    await this.server.close().catch(() => undefined);
+  }
+}

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

@@ -0,0 +1,11 @@
+export const speechSchema = {
+  type: 'object',
+  description: 'Speak text only in the exact active Stage call, without posting it in chat. Copy callId, generation and sourceId from its authenticated call input or call_id, call_generation and call_source_id from the requesting channel message. Use only for a call reply or an explicit owner request to speak in that call. Normal chat and worker results stay silent. One action per source; retries do not repeat speech. Accepted or queued is not heard. Completed means audio transport drained, not proof the caller heard it.',
+  properties: {
+    callId: { type: 'string' },
+    generation: { type: 'string' },
+    sourceId: { type: 'string' },
+  },
+  required: ['callId', 'generation', 'sourceId'],
+  additionalProperties: false,
+} as const;

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

@@ -0,0 +1,15 @@
+import { speechTarget } from '@metro-labs/core/call';
+import type { ToolResult } from '@metro-labs/core/stations/types';
+import { sharedCalls } from '../voice/shared.js';
+import { allowedAgents, currentIdentity } from './request-identity.js';
+import { errResult, okJson } from './ctx.js';
+
+export function sendSpeech(line: string, args: Record<string, unknown>): ToolResult {
+  const target = speechTarget(args.speech);
+  if (target === null) return errResult('Call speech needs callId, generation and sourceId from its authenticated source.');
+  if (['reply_to', 'subject', 'attachments', 'frame', 'wallet', 'account'].some((key) => args[key] !== undefined))
+    return errResult('Call speech cannot include chat content, media or an account override. Nothing was sent.');
+  if (typeof args.text !== 'string') return errResult('Call speech needs text.');
+  const receipt = sharedCalls.speak(line, target, args.text, allowedAgents(currentIdentity()));
+  return okJson({ speech: receipt, delivery: 'Audio transport status only. No proof the caller heard it. No chat message was posted.' });
+}

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

@@ -0,0 +1,96 @@
+import type { GroupOp, Station, StationTool, ToolGroup } from '@metro-labs/core/stations/types';
+import { STATIONS } from '../stations/registry.js';
+import { COMMON_TOOLS, LIST_ACCOUNTS_TOOL } from './tool-schemas.js';
+import { SET_PROFILE_TOOL } from './profile-tool.js';
+import { GET_PROFILE_TOOL } from './profile-lookup.js';
+import { LIST_CHANNELS_TOOL } from './channel-tool.js';
+import type { ToolDef } from './tool-def.js';
+
+const defOf = (tool: StationTool): ToolDef => ({
+  name: tool.name,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  ...(tool.group === undefined ? {} : { group: tool.group }),
+  ...(tool.destructive === true ? { destructive: true } : {}),
+});
+
+export const TOOL_DEFS: ToolDef[] = [
+  ...COMMON_TOOLS,
+  ...STATIONS.flatMap((s) => s.tools.map(defOf)),
+  LIST_ACCOUNTS_TOOL,
+  LIST_CHANNELS_TOOL,
+  SET_PROFILE_TOOL,
+  GET_PROFILE_TOOL,
+];
+
+const BY_NAME = new Map(TOOL_DEFS.map((d) => [d.name, d] as const));
+
+export const declaredGroup = (name: string): ToolGroup | undefined => BY_NAME.get(name)?.group;
+
+export const toolGroupOf = (name: string): ToolGroup => declaredGroup(name) ?? 'write';
+
+export interface ToolAnnotations {
+  readOnlyHint: boolean;
+  destructiveHint?: boolean;
+}
+
+export interface PublishedTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: ToolAnnotations;
+  _meta?: Record<string, boolean>;
+}
+
+const ALWAYS_LOADED = new Set(['react', 'typing', 'send', 'reply']);
+const ALWAYS_LOAD = { 'anthropic/alwaysLoad': true };
+
+const annotationsOf = (def: ToolDef): ToolAnnotations =>
+  toolGroupOf(def.name) === 'read'
+    ? { readOnlyHint: true }
+    : { readOnlyHint: false, destructiveHint: def.destructive === true };
+
+export const listedTools = (): PublishedTool[] =>
+  TOOL_DEFS.map((def) => ({
+    name: def.name,
+    description: def.description,
+    inputSchema: def.inputSchema,
+    annotations: annotationsOf(def),
+    ...(ALWAYS_LOADED.has(def.name) ? { _meta: ALWAYS_LOAD } : {}),
+  }));
+
+const STATION_OF_TOOL = new Map(STATIONS.flatMap((s) => s.tools.map((t) => [t.name, s.name] as const)));
+
+export const stationToolOwners = (): Record<string, string> => Object.fromEntries(STATION_OF_TOOL);
+
+export function stationForTool(name: string, args: Record<string, unknown>): string | undefined {
+  if (name === 'create_group' || name === 'set_profile')
+    return typeof args.station === 'string' && args.station !== '' ? args.station : undefined;
+  return STATION_OF_TOOL.get(name);
+}
+
+const GROUP_OP_TOOLS: Record<GroupOp, string> = {
+  create_group: 'create_group',
+  add_members: 'add_members',
+  remove_members: 'remove_members',
+  invite_link: 'export_invite',
+};
+
+export interface GroupedTool {
+  name: string;
+  group: ToolGroup;
+}
+
+export const stationToolGroups = (): Record<string, GroupedTool[]> =>
+  Object.fromEntries(STATIONS.filter((s) => s.hasAccounts).map((s) => [s.name, channelToolsOf(s)]));
+
+export function channelToolsOf(station: Station): GroupedTool[] {
+  const names: string[] = [...station.messageVerbs];
+  if (station.hasTrain && station.hasAccounts) names.push('list_members');
+  if (station.hasTrain && station.discoversChannels === true) names.push('list_channels');
+  names.push(...Array.from(station.groupOps ?? [], (op) => GROUP_OP_TOOLS[op]));
+  if ((station.profileFields?.size ?? 0) > 0) names.push('set_profile');
+  if (station.readsProfiles === true) names.push('get_profile');
+  names.push(...station.tools.map((t) => t.name));
+  return names.map((name) => ({ name, group: toolGroupOf(name) }));
+}

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

@@ -0,0 +1,9 @@
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  group?: ToolGroup;
+  destructive?: boolean;
+}