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

package/runtime/node_modules/@metro-labs/mcp/src/channels/media-note.ts

@@ -0,0 +1,85 @@
+import { stat } from 'node:fs/promises';
+
+const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+
+export interface SavedMedia {
+  contentType?: string;
+  attachmentFor?: string;
+  attachmentPath?: string;
+  localPath?: string;
+  url?: string;
+  mime?: string;
+  name?: string;
+  kind?: string;
+  index?: number;
+  reason?: string;
+}
+
+export interface MediaNote {
+  content: string;
+  kind: string;
+  name: string;
+  path: string;
+}
+
+export function mediaKind(mime?: string, name?: string): string {
+  const m = (mime ?? '').toLowerCase();
+  if (m.startsWith('image/')) return 'image';
+  if (m.startsWith('video/')) return 'video';
+  if (m.startsWith('audio/')) return 'audio';
+  const n = name ?? '';
+  if (/\.(png|jpe?g|gif|webp|heic)$/i.test(n)) return 'image';
+  if (/\.(mp4|mov|webm|m4v)$/i.test(n)) return 'video';
+  if (/\.(m4a|mp3|ogg|wav)$/i.test(n)) return 'audio';
+  return 'file';
+}
+
+async function fileSize(path: string): Promise<number> {
+  try {
+    return (await stat(path)).size;
+  } catch {
+    return 0;
+  }
+}
+
+function howToRead(url: string | undefined, tooBig: boolean): string {
+  if (!url)
+    return 'That path is on the daemon host, not on yours - this file is readable only by an agent running there.';
+  if (tooBig)
+    return 'Large file - fetch the Public URL only if you need the bytes, and do not inline it. The path is on the daemon host, not on yours.';
+  return 'Fetch the Public URL to view it. The path is on the daemon host, so the Read tool works only for an agent running there.';
+}
+
+export async function buildMediaNote(
+  p: SavedMedia,
+  caption: string,
+): Promise<MediaNote | null> {
+  const path = p.attachmentPath ?? p.localPath;
+  if (!path) return null;
+  const kind = p.kind ?? mediaKind(p.mime, p.name);
+  const name = p.name ?? path.split('/').pop() ?? 'attachment';
+  const size = await fileSize(path);
+  const sizeNote = size ? ` (${(size / 1024 / 1024).toFixed(2)} MB)` : '';
+  const content =
+    (caption ? `${caption}\n` : '') +
+    `[${kind} attachment received: ${name}${p.mime ? `, ${p.mime}` : ''}${sizeNote}]\n` +
+    (p.url ? `Public URL: ${p.url}\n` : '') +
+    `Daemon-host path: ${path}\n` +
+    howToRead(p.url, size > MAX_INLINE_BYTES);
+  return { content, kind, name, path };
+}
+
+export function buildMediaFailureNote(
+  p: SavedMedia,
+  caption: string,
+): MediaNote {
+  const kind = p.kind ?? mediaKind(p.mime, p.name);
+  const name = p.name ?? 'attachment';
+  const reason = p.reason ?? 'no reason reported';
+  const content =
+    (caption ? `${caption}\n` : '') +
+    `[${kind} attachment could not be fetched: ${name}]\n` +
+    `Reason: ${reason}\n` +
+    'The sender still has the file; nothing was saved. Ask them to resend it, or say why it could not be taken.';
+  return { content, kind, name, path: '' };
+}

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

@@ -0,0 +1,75 @@
+import { str } from '../mcp/str.js';
+
+export interface PendingAtt {
+  kind?: string;
+  name?: string;
+}
+
+export interface PendingMsg {
+  line: string;
+  from: string;
+  station: string;
+  text: string;
+  ts: string;
+  messageId: string;
+  lineName: string;
+  fromName: string;
+  fromDisplayName: string;
+  attachments: PendingAtt[];
+  saved: Set<number>;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface MediaCtx {
+  line: string;
+  from: string;
+  station: string;
+  text?: string;
+  ts?: string;
+  messageId?: string;
+  lineName?: string;
+  fromName?: string;
+  fromDisplayName?: string;
+}
+
+export function capSet(set: Set<string>, max: number): void {
+  while (set.size > max) {
+    const oldest = set.values().next();
+    if (oldest.done) break;
+    set.delete(oldest.value);
+  }
+}
+
+export const tsMeta = (v: unknown): Record<string, string> => {
+  const ts = str(v);
+  return ts ? { ts } : {};
+};
+
+export const displayNameMeta = (v: unknown): Record<string, string> => {
+  const name = str(v);
+  return name ? { from_display_name: name } : {};
+};
+
+export const senderMeta = (c: MediaCtx): Record<string, string> => ({
+  ...tsMeta(c.ts),
+  ...(c.messageId ? { message_id: c.messageId } : {}),
+  ...(c.lineName ? { line_name: c.lineName } : {}),
+  ...(c.fromName ? { from_name: c.fromName } : {}),
+  ...displayNameMeta(c.fromDisplayName),
+});
+
+export function takeMediaCtx(buf: PendingMsg): MediaCtx {
+  const ctx: MediaCtx = {
+    line: buf.line,
+    from: buf.from,
+    station: buf.station,
+    text: buf.text,
+    ts: buf.ts,
+    messageId: buf.messageId,
+    lineName: buf.lineName,
+    fromName: buf.fromName,
+    fromDisplayName: buf.fromDisplayName,
+  };
+  buf.text = '';
+  return ctx;
+}

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

@@ -0,0 +1,129 @@
+import {
+  bufferedSince,
+  currentBusSeq,
+  subscribeEvents,
+  type MetroEvent,
+} from '../daemon/events.js';
+import type { InboundRelay } from './inbound.js';
+
+export interface ReplayLedger {
+  startAt: number;
+  delivered: Set<number>;
+}
+
+export const newReplayLedger = (startAt = -1): ReplayLedger => ({
+  startAt,
+  delivered: new Set<number>(),
+});
+
+interface ChannelRelayDeps {
+  relay: InboundRelay;
+  log: (...a: unknown[]) => void;
+  inScope: (line: string) => boolean;
+  ledger?: ReplayLedger;
+}
+
+const PENDING_MAX = 2000;
+
+export class ChannelRelay {
+  private readonly deps: ChannelRelayDeps;
+  private readonly ledger: ReplayLedger;
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(deps: ChannelRelayDeps) {
+    this.deps = deps;
+    this.ledger = deps.ledger ?? newReplayLedger();
+  }
+
+  start(): () => void {
+    if (this.ledger.startAt < 0) this.ledger.startAt = currentBusSeq();
+    return subscribeEvents((event, busSeq) => {
+      this.enqueue(event, busSeq, false);
+    });
+  }
+
+  replayMissed(): void {
+    const missed = bufferedSince(this.ledger.startAt).filter(
+      (b) => !this.ledger.delivered.has(b.busSeq),
+    );
+    const first = missed.at(0);
+    const last = missed.at(-1);
+    if (!first || !last) return;
+    this.deps.log(
+      'relay: replay',
+      `(${missed.length} events)`,
+      'range',
+      `${first.busSeq}..${last.busSeq}`,
+    );
+    for (const b of missed) this.enqueue(b.event, b.busSeq, true);
+  }
+
+  private enqueue(event: MetroEvent, busSeq: number, replay: boolean): void {
+    const { delivered } = this.ledger;
+    if (delivered.has(busSeq)) return;
+    delivered.add(busSeq);
+    if (delivered.size > PENDING_MAX) {
+      const cutoff = busSeq - PENDING_MAX;
+      for (const s of delivered) if (s <= cutoff) delivered.delete(s);
+    }
+    this.chain = this.chain.then(() =>
+      this.deliver(event, busSeq, replay).catch((err: unknown) => {
+        this.deps.log(
+          'relay: delivery step failed; chain kept alive',
+          'busSeq',
+          busSeq,
+          'line',
+          event.line,
+          err,
+        );
+      }),
+    );
+  }
+
+  private withhold(event: MetroEvent, busSeq: number): void {
+    this.ledger.delivered.delete(busSeq);
+    this.deps.log(
+      'relay: withheld (line outside the channel session scope)',
+      'busSeq',
+      busSeq,
+      'line',
+      event.line,
+    );
+  }
+
+  private async deliver(
+    event: MetroEvent,
+    busSeq: number,
+    replay: boolean,
+  ): Promise<void> {
+    if (!this.deps.inScope(event.line)) {
+      this.withhold(event, busSeq);
+      return;
+    }
+    this.deps.log(
+      'relay: notify',
+      'busSeq',
+      busSeq,
+      'id',
+      event.id,
+      'replay',
+      replay,
+    );
+    try {
+      await this.deps.relay.handleEvent(
+        event as unknown as Record<string, unknown>,
+        replay,
+      );
+    } catch (err) {
+      this.ledger.delivered.delete(busSeq);
+      this.deps.log(
+        'channel delivery failed; bounded replay on reconnect',
+        'busSeq',
+        busSeq,
+        'line',
+        event.line,
+        err,
+      );
+    }
+  }
+}

package/runtime/node_modules/@metro-labs/mcp/src/channels/webhook-note.ts

@@ -0,0 +1,51 @@
+const MAX_BODY_CHARS = 8 * 1024;
+
+const HEADERS_KEPT = [
+  'x-github-event',
+  'x-github-delivery',
+  'x-intercom-topic',
+  'x-request-id',
+  'user-agent',
+];
+
+interface WebhookPayload {
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+function renderBody(body: unknown): string {
+  if (body === undefined || body === null) return '';
+  const text =
+    typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+  if (text.length <= MAX_BODY_CHARS) return text;
+  return (
+    text.slice(0, MAX_BODY_CHARS) +
+    `\n[truncated: ${String(text.length - MAX_BODY_CHARS)} more characters]`
+  );
+}
+
+function renderHeaders(headers: Record<string, string> | undefined): string {
+  if (!headers) return '';
+  const kept = HEADERS_KEPT.flatMap((k) =>
+    headers[k] === undefined ? [] : [`${k}: ${headers[k]}`],
+  );
+  return kept.length === 0 ? '' : kept.join('\n') + '\n';
+}
+
+export function buildWebhookNote(
+  summary: string,
+  lineName: string | undefined,
+  payload: unknown,
+): string {
+  const p = (
+    payload !== null && typeof payload === 'object' ? payload : {}
+  ) as WebhookPayload;
+  const label = lineName ? `${lineName}: ` : '';
+  const body = renderBody(p.body);
+  return (
+    `[webhook received] ${label}${summary}\n` +
+    renderHeaders(p.headers) +
+    (body ? `\n${body}\n` : '') +
+    'Inbound only: this line takes no send, reply or react.'
+  );
+}

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

@@ -0,0 +1,311 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from './log.js';
+import { ApiError } from './api-error.js';
+import {
+  apiFailure,
+  bodyField,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from './api-http.js';
+import {
+  isStationName,
+  parseAccountId,
+  type AccountRef,
+} from '../db/account-attach.js';
+import type { StationName } from '../db/schema.js';
+import {
+  ATTACHABLE_STATIONS,
+  isAttachStation,
+  type AttachInput,
+  type OneTimeSecret,
+  type PreparedAccount,
+} from '../stations/attach.js';
+import {
+  INTERACTIVE_STATIONS,
+  isInteractiveStation,
+  type InteractiveStation,
+} from '../stations/attach-interactive.js';
+import {
+  ATTACH_ID_RE,
+  type AttachOwner,
+  type AttachView,
+} from './attach-session.js';
+
+export interface AttachSessionApi {
+  start: (
+    owner: AttachOwner,
+    station: InteractiveStation,
+    input: Record<string, unknown>,
+  ) => Promise<AttachView>;
+  view: (owner: AttachOwner, attachId: string) => AttachView;
+  submit: (
+    owner: AttachOwner,
+    attachId: string,
+    input: { code?: unknown; password?: unknown },
+  ) => Promise<AttachView>;
+  cancel: (owner: AttachOwner, attachId: string) => Promise<void>;
+}
+
+export interface AccountApiDeps {
+  attachSessions: AttachSessionApi;
+  prepareAccount: (input: AttachInput) => Promise<PreparedAccount>;
+  attachAccount: (
+    email: string,
+    agentId: string,
+    station: StationName,
+    config: Record<string, unknown>,
+  ) => Promise<AccountRef>;
+  detachAccount: (
+    email: string,
+    agentId: string,
+    station: StationName,
+    accountId: string,
+  ) => Promise<AccountRef>;
+  syncStations: (station: StationName) => Promise<void>;
+}
+
+export type AccountRoute =
+  | { kind: 'start' }
+  | { kind: 'session'; attachId: string }
+  | { kind: 'step'; attachId: string }
+  | { kind: 'account'; station: StationName; accountId: string };
+
+export const ATTACHABLE: string[] = [
+  ...ATTACHABLE_STATIONS,
+  ...INTERACTIVE_STATIONS,
+];
+
+const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
+  start: ['POST'],
+  session: ['GET', 'DELETE'],
+  step: ['POST'],
+  account: ['DELETE'],
+};
+
+function twoSegmentRoute(head: string, tail: string): AccountRoute | null {
+  if (ATTACH_ID_RE.test(head))
+    return tail === 'step' ? { kind: 'step', attachId: head } : null;
+  if (!isStationName(head)) return null;
+  const accountId = parseAccountId(tail);
+  return accountId === null ? null : { kind: 'account', station: head, accountId };
+}
+
+export function accountRoute(rest: string[]): AccountRoute | null {
+  const [head, tail] = rest;
+  if (head === undefined) return null;
+  if (rest.length === 1)
+    return head === 'start'
+      ? { kind: 'start' }
+      : ATTACH_ID_RE.test(head)
+        ? { kind: 'session', attachId: head }
+        : null;
+  if (rest.length !== 2 || tail === undefined) return null;
+  return twoSegmentRoute(head, tail);
+}
+
+export function accountRouteAllows(
+  route: AccountRoute,
+  method: string | undefined,
+): boolean {
+  return ROUTE_METHODS[route.kind].includes(method ?? '');
+}
+
+async function activate(
+  deps: AccountApiDeps,
+  station: StationName,
+): Promise<boolean> {
+  try {
+    await deps.syncStations(station);
+    return true;
+  } catch (err) {
+    log.warn(
+      { station, err: errMsg(err) },
+      'account-api: station reload failed, the change lands at the next boot',
+    );
+    return false;
+  }
+}
+
+interface AttachPayload {
+  status: 'done';
+  agentId: string;
+  station: string;
+  accountId: string;
+  identity: Record<string, string>;
+  activated: boolean;
+  secret?: OneTimeSecret;
+}
+
+async function storeAccount(
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  station: StationName,
+  prepared: PreparedAccount,
+): Promise<AccountRef> {
+  try {
+    return await deps.attachAccount(
+      session.email,
+      agentId,
+      station,
+      prepared.config,
+    );
+  } catch (err) {
+    prepared.discard?.();
+    throw err;
+  }
+}
+
+function ownerOf(session: ApiSession, agentId: string): AttachOwner {
+  return { email: session.email, agentId };
+}
+
+function asInput(body: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of ['apiId', 'apiHash', 'phone'])
+    out[key] = bodyField(body, key);
+  return out;
+}
+
+async function handleStart(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const station = bodyField(body, 'station');
+  if (isInteractiveStation(station)) {
+    const view = await deps.attachSessions.start(
+      ownerOf(session, agentId),
+      station,
+      asInput(body),
+    );
+    sendJson(req, res, 201, view);
+    return;
+  }
+  if (!isAttachStation(station))
+    throw new ApiError(`station must be one of ${ATTACHABLE.join(', ')}`, 400);
+  const prepared = await deps.prepareAccount({
+    station,
+    token: bodyField(body, 'token'),
+  });
+  const ref = await storeAccount(deps, session, agentId, station, prepared);
+  log.info(
+    { agentId: ref.agentId, station, account: ref.accountId },
+    'account-api: attached a station account',
+  );
+  const payload: AttachPayload = {
+    status: 'done',
+    agentId: ref.agentId,
+    station,
+    accountId: ref.accountId,
+    identity: prepared.identity,
+    activated: await activate(deps, station),
+  };
+  sendJson(
+    req,
+    res,
+    201,
+    prepared.secret === undefined
+      ? payload
+      : { ...payload, secret: prepared.secret },
+  );
+}
+
+async function handleDetach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const ref = await deps.detachAccount(
+    session.email,
+    agentId,
+    target.station,
+    target.accountId,
+  );
+  log.info(
+    { agentId: ref.agentId, station: ref.station, account: ref.accountId },
+    'account-api: detached a station account',
+  );
+  sendJson(req, res, 200, {
+    agentId: ref.agentId,
+    station: ref.station,
+    accountId: ref.accountId,
+    detached: true,
+    activated: await activate(deps, ref.station),
+  });
+}
+
+async function handleSession(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  if (req.method === 'DELETE') {
+    await deps.attachSessions.cancel(owner, attachId);
+    sendJson(req, res, 200, { attachId, cancelled: true });
+    return;
+  }
+  sendJson(req, res, 200, deps.attachSessions.view(owner, attachId));
+}
+
+async function handleStep(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  attachId: string,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const view = await deps.attachSessions.submit(owner, attachId, {
+    code: bodyField(body, 'code'),
+    password: bodyField(body, 'password'),
+  });
+  sendJson(req, res, 200, view);
+}
+
+async function dispatchRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  if (route.kind === 'start')
+    return handleStart(req, res, deps, session, agentId);
+  if (route.kind === 'session')
+    return handleSession(
+      req,
+      res,
+      deps,
+      ownerOf(session, agentId),
+      route.attachId,
+    );
+  if (route.kind === 'step')
+    return handleStep(req, res, deps, ownerOf(session, agentId), route.attachId);
+  return handleDetach(req, res, deps, session, agentId, route);
+}
+
+export async function handleAccountRoute(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  session: ApiSession,
+  agentId: string,
+  route: AccountRoute,
+): Promise<void> {
+  try {
+    await dispatchRoute(req, res, deps, session, agentId, route);
+  } catch (err) {
+    apiFailure(req, res, err);
+  }
+}