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

package/runtime/node_modules/@metro-labs/daemon/src/channels/inbound.ts

@@ -0,0 +1,377 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { str } from '@metro-labs/core/str';
+import { dedupeKey } from './dedupe.js';
+import {
+  buildMediaFailureNote,
+  buildMediaNote,
+  type MediaNote,
+  type SavedMedia,
+} from './media-note.js';
+import { buildWebhookNote } from './webhook-note.js';
+import { replyMeta } from './addressed.js';
+import {
+  capSet,
+  displayNameMeta,
+  senderMeta,
+  tsMeta,
+  takeMediaCtx,
+  type MediaCtx,
+  type PendingAtt,
+  type PendingMsg,
+} from './pending.js';
+
+interface InboundDeps {
+  mcp: Server;
+  log: (...a: unknown[]) => void;
+  getStations: () => Set<string>;
+  senderAllowed: (from: string, line: string) => boolean;
+}
+
+const ATTACH_TIMEOUT_MS = 15_000;
+const DEDUPE_TTL_MS = 30_000;
+const DEDUPE_MAX = 2_000;
+const ALLOWED_LINES_MAX = 2_000;
+const PENDING_PERMISSIONS_MAX = 500;
+const SENT_IDS_MAX = 2_000;
+
+const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i;
+
+const shortId = (id: string): string =>
+  id.length > 10 ? `${id.slice(0, 6)}…` : id;
+
+export class InboundRelay {
+  private readonly deps: InboundDeps;
+  private readonly pendingAttachments = new Map<string, PendingMsg>();
+  private readonly seenEvents = new Map<string, number>();
+  private readonly allowedLines = new Set<string>();
+  private readonly pendingPermissions = new Set<string>();
+  private readonly sentIds = new Set<string>();
+  private lastLine: string | undefined;
+
+  constructor(deps: InboundDeps) {
+    this.deps = deps;
+  }
+
+  get knownLine(): string | undefined {
+    return this.lastLine;
+  }
+
+  registerPermission(requestId: string): void {
+    this.pendingPermissions.add(requestId);
+    capSet(this.pendingPermissions, PENDING_PERMISSIONS_MAX);
+  }
+
+  noteSent(messageId: string): void {
+    if (!messageId) return;
+    this.sentIds.add(messageId);
+    capSet(this.sentIds, SENT_IDS_MAX);
+  }
+
+  private notify(method: string, params: Record<string, unknown>): Promise<void> {
+    return this.deps.mcp.notification({ method, params });
+  }
+
+  private isDuplicate(
+    station: string,
+    line: string,
+    kind: string,
+    messageId: string,
+  ): boolean {
+    if (!messageId) return false;
+    const key = dedupeKey(station, line, kind, messageId);
+    const now = Date.now();
+    if (this.seenEvents.size >= DEDUPE_MAX) {
+      for (const [k, t] of this.seenEvents) {
+        if (now - t > DEDUPE_TTL_MS) this.seenEvents.delete(k);
+      }
+    }
+    const prev = this.seenEvents.get(key);
+    if (prev !== undefined && now - prev < DEDUPE_TTL_MS) return true;
+    this.seenEvents.set(key, now);
+    return false;
+  }
+
+  private surfaceNote(
+    ctx: MediaCtx,
+    p: SavedMedia,
+    note: MediaNote,
+    extra: Record<string, unknown>,
+  ): Promise<void> {
+    return this.notify('notifications/claude/channel', {
+      content: note.content,
+      meta: {
+        line: ctx.line,
+        from: ctx.from,
+        station: ctx.station,
+        ...senderMeta(ctx),
+        kind: note.kind,
+        mime: p.mime ?? '',
+        name: note.name,
+        ...extra,
+      },
+    });
+  }
+
+  private async surfaceMedia(ctx: MediaCtx, p: SavedMedia): Promise<void> {
+    const note = await buildMediaNote(p, ctx.text ?? '');
+    if (!note) return;
+    await this.surfaceNote(ctx, p, note, {
+      ...(p.url ? { url: p.url } : {}),
+      local_path: note.path,
+    });
+  }
+
+  private surfaceMediaFailure(ctx: MediaCtx, p: SavedMedia): Promise<void> {
+    return this.surfaceNote(ctx, p, buildMediaFailureNote(p, ctx.text ?? ''), {
+      attachment_error: p.reason ?? '',
+    });
+  }
+
+  private async flushPendingFallback(id: string): Promise<void> {
+    const e = this.pendingAttachments.get(id);
+    if (!e) return;
+    this.pendingAttachments.delete(id);
+    const missing = e.attachments.filter((_, i) => !e.saved.has(i));
+    if (!missing.length) return;
+    const names = missing
+      .map((a) => a.name ?? a.kind ?? 'attachment')
+      .join(', ');
+    await this.notify('notifications/claude/channel', {
+      content:
+        (e.text ? `${e.text}\n` : '') +
+        `[attachment(s) could not be fetched in time: ${names}]`,
+      meta: {
+        line: e.line,
+        from: e.from,
+        station: e.station,
+        ...tsMeta(e.ts),
+        message_id: e.messageId,
+        line_name: e.lineName,
+        from_name: e.fromName,
+        ...displayNameMeta(e.fromDisplayName),
+      },
+    });
+  }
+
+  private mediaCtxFor(
+    ev: Record<string, unknown>,
+    payload: SavedMedia,
+  ): MediaCtx | null {
+    const forId = str(payload.attachmentFor);
+    const buf = forId ? this.pendingAttachments.get(forId) : undefined;
+    if (buf) {
+      buf.saved.add(typeof payload.index === 'number' ? payload.index : 0);
+      const ctx = takeMediaCtx(buf);
+      if (buf.saved.size >= buf.attachments.length) {
+        clearTimeout(buf.timer);
+        this.pendingAttachments.delete(forId);
+      }
+      return ctx;
+    }
+    const line = str(ev.line);
+    if (!line || !this.allowedLines.has(line)) return null;
+    return {
+      line,
+      from: 'metro://attachment',
+      station: str(ev.station) || 'xmtp',
+      ts: str(ev.ts),
+    };
+  }
+
+  private async routeAttachment(ev: Record<string, unknown>): Promise<boolean> {
+    const p = ev.payload as SavedMedia | undefined;
+    if (!p) return false;
+    const type = p.contentType;
+    if (type !== 'attachmentSaved' && type !== 'attachmentFailed') return false;
+    const ctx = this.mediaCtxFor(ev, p);
+    if (!ctx) return true;
+    if (type === 'attachmentFailed') await this.surfaceMediaFailure(ctx, p);
+    else await this.surfaceMedia(ctx, p);
+    return true;
+  }
+
+  private bufferAttachments(
+    ev: Record<string, unknown>,
+    base: { line: string; from: string; station: string; text: string },
+    atts: PendingAtt[],
+  ): void {
+    const id = str(ev.id);
+    if (!id) return;
+    const existing = this.pendingAttachments.get(id);
+    if (existing) clearTimeout(existing.timer);
+    this.pendingAttachments.set(id, {
+      ...base,
+      ts: str(ev.ts),
+      messageId: str(ev.messageId),
+      lineName: str(ev.lineName),
+      fromName: str(ev.fromName),
+      fromDisplayName: str(ev.fromDisplayName),
+      attachments: atts.map((a) => ({ kind: a.kind, name: a.name })),
+      saved: new Set<number>(),
+      timer: setTimeout(() => {
+        this.flushPendingFallback(id).catch((err: unknown) => {
+          this.deps.log(
+            'inbound: attachment fallback not delivered',
+            'id',
+            id,
+            'line',
+            base.line,
+            err,
+          );
+        });
+      }, ATTACH_TIMEOUT_MS),
+    });
+  }
+
+  private async handleReact(
+    ev: Record<string, unknown>,
+    base: { line: string; from: string; station: string; text: string },
+  ): Promise<void> {
+    const re = ev.event as { emoji?: unknown; targetId?: string };
+    const emoji = reactionEmoji(re.emoji);
+    const target = re.targetId ?? str(ev.messageId);
+    const removed =
+      (ev.payload as { removed?: boolean } | undefined)?.removed === true ||
+      / \(removed\)\]?$/.test(base.text);
+    const verb = removed ? 'removed from' : 'reacted to';
+    const label = removed ? emoji || 'reaction' : emoji || 'reacted';
+    const content = `${label} ${verb} message ${shortId(target)}`.trim();
+    await this.notify('notifications/claude/channel', {
+      content,
+      meta: {
+        line: base.line,
+        from: base.from,
+        station: base.station,
+        ...tsMeta(ev.ts),
+        message_id: str(ev.messageId),
+        line_name: str(ev.lineName),
+        from_name: str(ev.fromName),
+        ...displayNameMeta(ev.fromDisplayName),
+        reaction: emoji,
+        target_id: target,
+      },
+    });
+  }
+
+  private async handlePermissionReply(text: string): Promise<boolean> {
+    const m = PERMISSION_REPLY_RE.exec(text);
+    if (m?.[1] === undefined || m[2] === undefined || !this.pendingPermissions.size)
+      return false;
+    const id = m[2].toLowerCase();
+    if (!this.pendingPermissions.has(id)) return false;
+    this.pendingPermissions.delete(id);
+    await this.notify('notifications/claude/channel/permission', {
+      request_id: id,
+      behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',
+    });
+    return true;
+  }
+
+  private droppedSender(from: string, line: string): boolean {
+    if (
+      from.startsWith('metro://claude') ||
+      from === 'metro://user' ||
+      !from.startsWith('metro://')
+    )
+      return true;
+    if (!this.deps.senderAllowed(from, line)) {
+      this.deps.log('drop: sender not allowed', from);
+      return true;
+    }
+    return false;
+  }
+
+  private routable(
+    ev: Record<string, unknown>,
+    replay: boolean,
+  ): EventBase | null {
+    const rawType = ev.event ? (ev.event as { type?: string }).type : 'msg';
+    const evType = rawType === 'reply' ? 'msg' : rawType;
+    if (evType !== 'msg' && evType !== 'react' && evType !== 'system')
+      return null;
+    const station = str(ev.station);
+    if (!this.deps.getStations().has(station)) return null;
+    const from = str(ev.from);
+    const line = str(ev.line);
+    if (this.droppedSender(from, line)) return null;
+    const text = str(ev.text);
+    if (!replay && this.isDuplicate(station, line, evType, str(ev.messageId))) {
+      this.deps.log(
+        'drop: duplicate (per-account) event',
+        evType,
+        station,
+        str(ev.messageId),
+      );
+      return null;
+    }
+    return { evType, station, from, line, text };
+  }
+
+  private async emitMessage(
+    ev: Record<string, unknown>,
+    base: EventBase,
+  ): Promise<void> {
+    if (base.evType === 'msg' && (await this.handlePermissionReply(base.text)))
+      return;
+    await this.notify('notifications/claude/channel', {
+      content:
+        base.evType === 'system'
+          ? buildWebhookNote(base.text, str(ev.lineName), ev.payload)
+          : base.text,
+      meta: {
+        line: base.line,
+        from: base.from,
+        station: base.station,
+        ...tsMeta(ev.ts),
+        message_id: str(ev.messageId),
+        line_name: str(ev.lineName),
+        from_name: str(ev.fromName),
+        ...displayNameMeta(ev.fromDisplayName),
+        ...replyMeta(ev, this.sentIds),
+      },
+    });
+  }
+
+  async handleEvent(
+    ev: Record<string, unknown>,
+    replay = false,
+  ): Promise<void> {
+    if (await this.routeAttachment(ev)) return;
+
+    const base = this.routable(ev, replay);
+    if (!base) return;
+    if (base.evType !== 'system') this.lastLine = base.line;
+    if (base.line) {
+      this.allowedLines.add(base.line);
+      capSet(this.allowedLines, ALLOWED_LINES_MAX);
+    }
+
+    const atts = (ev.payload as { attachments?: PendingAtt[] } | undefined)
+      ?.attachments;
+    if (Array.isArray(atts) && atts.length) {
+      this.bufferAttachments(ev, base, atts);
+      return;
+    }
+
+    if (base.evType === 'react') {
+      await this.handleReact(ev, base);
+      return;
+    }
+
+    await this.emitMessage(ev, base);
+  }
+}
+
+interface EventBase {
+  evType: string;
+  station: string;
+  from: string;
+  line: string;
+  text: string;
+}
+
+function reactionEmoji(raw: unknown): string {
+  if (typeof raw === 'string') return raw;
+  const obj = raw as { name?: string; reaction?: string } | undefined;
+  return obj?.name ?? obj?.reaction ?? '';
+}

package/runtime/node_modules/@metro-labs/daemon/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/daemon/src/channels/pending.ts

@@ -0,0 +1,75 @@
+import { str } from '@metro-labs/core/str';
+
+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/daemon/src/channels/relay.ts

@@ -0,0 +1,129 @@
+import {
+  bufferedSince,
+  currentBusSeq,
+  subscribeEvents,
+  type MetroEvent,
+} from '@metro-labs/core/events';
+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,
+      );
+    }
+  }
+}