@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

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

@@ -0,0 +1,245 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID } from 'node:crypto';
+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 GetStreamDiagnostic {
+  tag: string;
+  openedAt: string;
+  attachedAt: string | null;
+  closedAt: string | null;
+  ownsMapping: boolean;
+}
+
+export interface RawGetSink {
+  closed: boolean;
+  attach: (transport: StreamableHTTPServerTransport) => void;
+  close: () => void;
+  diagnostics: () => GetStreamDiagnostic;
+}
+
+const streamEnded = (sink: RawGetSink, res: ServerResponse): boolean =>
+  sink.closed || res.destroyed || res.writableEnded;
+
+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;
+  previous?: () => RawGetSink | undefined;
+}
+
+function primeStream(transport: StreamableHTTPServerTransport, res: ServerResponse): void {
+  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);
+}
+
+export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
+  const { transport, eventStore, scope, req, res, log, registerSink } = opts;
+  primeStream(transport, res);
+
+  let active = transport;
+  let entry: StreamEntry | undefined;
+  const tag = randomUUID();
+  const openedAt = new Date().toISOString();
+  let attachedAt: string | null = null;
+  let closedAt: string | null = null;
+  const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
+  const closeStream = (): void => {
+    if (sink.closed) return;
+    sink.closed = true;
+    closedAt = new Date().toISOString();
+    if (timers.keepalive) clearInterval(timers.keepalive);
+    const mapping = web(active)?._streamMapping;
+    if (entry !== undefined && mapping?.get(STANDALONE_STREAM_ID) === entry) {
+      mapping.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;
+      entry = {
+        controller: {
+          enqueue: (chunk: Uint8Array): void => {
+            if (streamEnded(sink, res)) {
+              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);
+      attachedAt = new Date().toISOString();
+    },
+    close: closeStream,
+    diagnostics: () => ({
+      tag,
+      openedAt,
+      attachedAt,
+      closedAt,
+      ownsMapping: entry !== undefined && web(active)?._streamMapping?.get(STANDALONE_STREAM_ID) === entry,
+    }),
+  };
+
+  res.on('close', closeStream);
+  res.on('error', closeStream);
+  req.on('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)',
+        );
+      },
+    });
+  }
+
+  if (streamEnded(sink, res)) {
+    closeStream();
+    return;
+  }
+  opts.previous?.()?.close();
+  sink.attach(transport);
+  registerSink(sink);
+  if (sink.closed) return;
+
+  timers.keepalive = setInterval(() => {
+    if (streamEnded(sink, res)) {
+      closeStream();
+      return;
+    }
+    try {
+      res.write(COMMENT);
+    } catch (err) {
+      log('raw-get-stream: keepalive write failed', err);
+      closeStream();
+    }
+  }, KEEPALIVE_MS);
+  timers.keepalive.unref?.();
+}
+
+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;
+  }
+  opts.previous()?.close();
+  await serveStandaloneGet(opts);
+  return true;
+}

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

@@ -0,0 +1,87 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { str } from '@metro-labs/core/str';
+import type { ReadFilter, Station, ToolResult } from '@metro-labs/core/stations/types';
+import { agentIdForAccount, accountFromLine, knownAccounts } from '../agents/map.js';
+import { attachmentUrl } from '../files/attach-serve.js';
+import { stationByName } from '../stations/registry.js';
+import { errResult, makeCtx, okJson, toErr } from './ctx.js';
+import { agentUser } from '../agent-user/user.js';
+
+const FILTERS: readonly (readonly [string, ReadFilter, string])[] = [
+  ['query', 'query', 'query'],
+  ['from', 'from', 'from'],
+  ['until', 'until', 'until'],
+  ['unread_only', 'unread_only', 'unreadOnly'],
+  ['message_id', 'message_id', 'messageId'],
+];
+
+const given = (v: unknown): boolean => v !== undefined && v !== null && v !== '' && v !== false;
+
+export function stationOfAccount(account: string): string | undefined {
+  const hits = knownAccounts().filter((a) => a.id === account);
+  return hits.length === 1 ? hits[0]?.station : undefined;
+}
+
+function readArgs(a: Record<string, unknown>): Record<string, unknown> {
+  const args: Record<string, unknown> = {};
+  if (str(a.line)) args.line = str(a.line);
+  if (str(a.account)) args.account = str(a.account);
+  if (typeof a.limit === 'number') args.limit = a.limit;
+  if (a.before) args.before = str(a.before);
+  if (a.since) args.since = str(a.since);
+  for (const [snake, , camel] of FILTERS)
+    if (given(a[snake])) args[camel] = typeof a[snake] === 'boolean' ? a[snake] : str(a[snake]);
+  return args;
+}
+
+function ignoredFilters(station: Station, a: Record<string, unknown>): string[] {
+  const supported = station.readFilters ?? new Set<ReadFilter>();
+  return FILTERS.filter(([snake, filter]) => given(a[snake]) && !supported.has(filter)).map(([snake]) => snake);
+}
+
+function withUrls(result: unknown, agentId: string | undefined): unknown {
+  if (agentId === undefined || !isRecord(result) || !isRecord(result.message)) return result;
+  const files = result.message.attachments;
+  if (!Array.isArray(files)) return result;
+  const attachments = files.map((f: unknown) => {
+    if (!isRecord(f) || typeof f.local_path !== 'string') return f;
+    const url = attachmentUrl(f.local_path, agentId);
+    const shown = agentUser() === null ? f : Object.fromEntries(Object.entries(f).filter(([key]) => key !== 'local_path'));
+    return url === null ? shown : { ...shown, url };
+  });
+  return { ...result, message: { ...result.message, attachments } };
+}
+
+function answer(result: unknown, ignored: string[]): unknown {
+  if (ignored.length === 0) return result;
+  return isRecord(result) && !Array.isArray(result) ? { ...result, ignored } : { result, ignored };
+}
+
+function accountOfCall(station: Station, a: Record<string, unknown>, result: unknown): string | undefined {
+  const named = str(a.account) || (isRecord(result) ? str(result.account) : '');
+  const account = named || accountFromLine(str(a.line))?.accountId;
+  return account === undefined ? undefined : agentIdForAccount(station.name, account);
+}
+
+export async function runRead(station: Station, a: Record<string, unknown>): Promise<ToolResult> {
+  try {
+    const response = await makeCtx(station.name).call('read', readArgs(a));
+    const result = withUrls(response.result, accountOfCall(station, a, response.result));
+    return okJson(answer(result, ignoredFilters(station, a)));
+  } catch (e) {
+    return toErr('read', e);
+  }
+}
+
+export function linelessRead(a: Record<string, unknown>): Promise<ToolResult> | ToolResult {
+  const account = str(a.account);
+  if (!account) return errResult('read requires `line` or `account`');
+  const name = stationOfAccount(account);
+  const station = name === undefined ? undefined : stationByName(name);
+  if (station === undefined) return errResult(`no account ${account} on this box; list_accounts names them`);
+  if (!station.messageVerbs.has('read'))
+    return errResult(`${station.name} does not support read; it supports ${[...station.messageVerbs].join(', ')}.`);
+  if (!station.readFilters?.has('account'))
+    return errResult(`${station.name} reads one conversation at a time; give a \`line\` instead of an account`);
+  return runRead(station, a);
+}

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();
+    });
+  }
+}