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

package/runtime/node_modules/@metro-labs/daemon/src/boot/paths.ts

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from '@metro-labs/core/log';
+import { ensureSecureDir } from '@metro-labs/core/secure-fs';
+
+export const STATE_DIR =
+  process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+ensureSecureDir(STATE_DIR);
+
+
+export function trainsDir(): string {
+  const env = process.env.METRO_TRAINS_DIR?.trim();
+  if (env !== undefined && env !== '') return env;
+  return fileURLToPath(new URL('../../trains', import.meta.url));
+}
+
+function readLockPid(lockFile: string): number {
+  try {
+    return Number(readFileSync(lockFile, 'utf8').trim());
+  } catch {
+    return NaN;
+  }
+}
+
+function namesMetro(text: string): boolean {
+  return text.includes('server.ts') || text.includes('metro');
+}
+
+function holderIsMetro(pid: number): boolean {
+  try {
+    return namesMetro(readFileSync(`/proc/${pid}/cmdline`, 'utf8'));
+  } catch {
+    return holderCommand(pid);
+  }
+}
+
+function holderCommand(pid: number): boolean {
+  try {
+    return namesMetro(
+      execFileSync('ps', ['-o', 'command=', '-p', String(pid)], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function lockHeldByLiveDaemon(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return false;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  return holderIsMetro(pid);
+}
+
+function writeOwnLock(lockFile: string): void {
+  const fd = openSync(lockFile, 'wx');
+  writeSync(fd, String(process.pid));
+  closeSync(fd);
+  process.on('exit', () => {
+    try {
+      if (readFileSync(lockFile, 'utf8').trim() === String(process.pid))
+        unlinkSync(lockFile);
+    } catch {
+    }
+  });
+}
+
+export function acquireLock(lockFile: string): void {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      writeOwnLock(lockFile);
+      return;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+      const pid = readLockPid(lockFile);
+      if (lockHeldByLiveDaemon(pid)) {
+        log.info(
+          { pid },
+          'a healthy `metro` daemon is already running; exiting (no second dispatcher)',
+        );
+        process.exit(0);
+      }
+      try {
+        unlinkSync(lockFile);
+      } catch {
+      }
+    }
+  }
+  throw new Error(
+    `metro: could not acquire dispatcher lock (${lockFile}) after retries`,
+  );
+}

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

@@ -0,0 +1,26 @@
+import { str } from '@metro-labs/core/str';
+
+export type Addressed = 'direct' | 'mention' | 'reply';
+
+interface AddressFacts {
+  isPrivate?: unknown;
+  mentionsSelf?: unknown;
+  replyToSelf?: unknown;
+}
+
+export function addressedBy(facts: AddressFacts, replyTo: string, sent: ReadonlySet<string>): Addressed | undefined {
+  if (facts.isPrivate === true) return 'direct';
+  if (facts.mentionsSelf === true) return 'mention';
+  if (facts.replyToSelf === true || (replyTo !== '' && sent.has(replyTo))) return 'reply';
+  return undefined;
+}
+
+export function replyMeta(ev: Record<string, unknown>, sent: ReadonlySet<string>): Record<string, string> {
+  const replyTo = str(ev.replyTo);
+  const addressed = addressedBy(ev, replyTo, sent);
+  return {
+    ...(replyTo ? { reply_to: replyTo } : {}),
+    ...(addressed === undefined ? {} : { addressed }),
+    ...(typeof ev.senderVerified === 'boolean' ? { sender_verified: String(ev.senderVerified) } : {}),
+  };
+}

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

@@ -0,0 +1,390 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { str } from '@metro-labs/core/str';
+import {
+  buildMediaFailureNote,
+  buildMediaNote,
+  type MediaNote,
+  type SavedMedia,
+} from './media-note.js';
+import { buildWebhookNote } from './webhook-note.js';
+import { replyMeta } from './addressed.js';
+import { reactContent, reactionEmoji } from './react-note.js';
+import {
+  capSet,
+  displayNameMeta,
+  missingAttachmentNames,
+  senderMeta,
+  tsMeta,
+  takeMediaCtx,
+  type MediaCtx,
+  type PendingAtt,
+  type PendingMsg,
+} from './pending.js';
+import { agentUser } from '../agent-user/user.js';
+
+const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i;
+
+const accountStrippedLine = (line: string): string => {
+  const parts = line.split('/');
+  if (parts.length < 5) return line;
+  return [parts[0], parts[1], parts[2], ...parts.slice(4)].join('/');
+};
+
+const dedupeKey = (station: string, line: string, kind: string, messageId: string): string =>
+  `${station} ${accountStrippedLine(line)} ${kind} ${messageId}`;
+
+interface InboundDeps {
+  mcp: Server;
+  log: (...a: unknown[]) => void;
+  getStations: () => Set<string>;
+  senderAllowed: (from: string, line: string, verified?: boolean) => boolean;
+  approves?: (station: string) => boolean;
+  noteDirect?: (line: string, from: string) => void;
+  callMeta?: (event: Record<string, unknown>) => () => Record<string, string>;
+  answerPermission?: (requestId: string, behavior: 'allow' | 'deny', line: string, from: string) => Promise<boolean>;
+}
+
+const ATTACH_TIMEOUT_MS = 15_000;
+const LATE_ATTACH_WINDOW_MS = 15 * 60_000;
+const DEDUPE_TTL_MS = 30_000;
+const DEDUPE_MAX = 2_000;
+const ALLOWED_LINES_MAX = 2_000;
+const SENT_IDS_MAX = 2_000;
+
+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 sentIds = new Set<string>();
+  private lastLine: string | undefined;
+
+  constructor(deps: InboundDeps) {
+    this.deps = deps;
+  }
+
+  get knownLine(): string | undefined {
+    return this.lastLine;
+  }
+
+  dropPending(): void {
+    for (const e of this.pendingAttachments.values()) clearTimeout(e.timer);
+    this.pendingAttachments.clear();
+  }
+
+  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),
+        ...ctx.reply,
+        kind: note.kind,
+        mime: p.mime ?? '',
+        name: note.name,
+        ...extra,
+        ...ctx.callMeta?.(),
+      },
+    });
+  }
+
+  private async surfaceMedia(ctx: MediaCtx, p: SavedMedia): Promise<void> {
+    const ownUser = agentUser() !== null;
+    const note = await buildMediaNote(p, ctx.text ?? '', !ownUser);
+    if (!note) return;
+    await this.surfaceNote(ctx, p, note, {
+      ...(p.url ? { url: p.url } : {}),
+      ...(ownUser ? {} : { 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;
+    const missing = missingAttachmentNames(e);
+    if (!missing.length) {
+      this.pendingAttachments.delete(id);
+      return;
+    }
+    e.timer = setTimeout(() => { this.pendingAttachments.delete(id); }, LATE_ATTACH_WINDOW_MS);
+    const ctx = takeMediaCtx(e);
+    await this.notify('notifications/claude/channel', {
+      content:
+        (ctx.text ? `${ctx.text}\n` : '') +
+        `[attachment(s) still downloading: ${missing.join(', ')}; they follow in a separate note]`,
+      meta: {
+        line: ctx.line,
+        from: ctx.from,
+        station: ctx.station,
+        ...senderMeta(ctx),
+        ...ctx.reply,
+        ...ctx.callMeta?.(),
+      },
+    });
+  }
+
+  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>, replay: boolean): 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 (replay) ctx.callMeta = undefined;
+    if (type === 'attachmentFailed') await this.surfaceMediaFailure(ctx, p);
+    else await this.surfaceMedia(ctx, p);
+    return true;
+  }
+
+  private bufferAttachments(
+    ev: Record<string, unknown>,
+    base: EventBase,
+    atts: PendingAtt[],
+    replay: boolean,
+  ): 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),
+      reply: replyMeta(ev, this.sentIds),
+      callMeta: !replay && base.evType === 'msg' ? this.deps.callMeta?.(ev) : undefined,
+      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 content = reactContent(emoji, target, removed);
+    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(ev: Record<string, unknown>, base: EventBase): Promise<boolean> {
+    const answer = this.deps.answerPermission;
+    if (answer === undefined || base.evType !== 'msg' || !this.approves(base.station) || ev.senderVerified === false) return false;
+    const m = PERMISSION_REPLY_RE.exec(base.text);
+    if (m?.[1] === undefined || m[2] === undefined) return false;
+    return answer(m[2].toLowerCase(), m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny', base.line, base.from);
+  }
+
+  private approves(station: string): boolean {
+    return this.deps.approves?.(station) !== false;
+  }
+
+  private noteLine(base: EventBase, direct: boolean): void {
+    if (base.evType !== 'system' && this.approves(base.station)) {
+      this.lastLine = base.line;
+      if (direct) this.deps.noteDirect?.(base.line, base.from);
+    }
+    if (!base.line) return;
+    this.allowedLines.add(base.line);
+    capSet(this.allowedLines, ALLOWED_LINES_MAX);
+  }
+
+  private droppedSender(from: string, line: string, verified: unknown): boolean {
+    if (
+      from.startsWith('metro://claude') ||
+      from === 'metro://user' ||
+      !from.startsWith('metro://')
+    )
+      return true;
+    if (!this.deps.senderAllowed(from, line, typeof verified === 'boolean' ? verified : undefined)) {
+      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, ev.senderVerified)) 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,
+    replay: boolean,
+  ): Promise<void> {
+    if (base.evType === 'msg' && base.text.trim() === '') {
+      this.deps.log('drop: empty message', base.station, base.line, str(ev.messageId));
+      return;
+    }
+    if (await this.handlePermissionReply(ev, base)) 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),
+        ...(!replay && base.evType === 'msg' ? this.deps.callMeta?.(ev)?.() : {}),
+      },
+    });
+  }
+
+  async handleEvent(
+    ev: Record<string, unknown>,
+    replay = false,
+  ): Promise<void> {
+    if (await this.routeAttachment(ev, replay)) return;
+
+    const base = this.routable(ev, replay);
+    if (!base) return;
+    this.noteLine(base, ev.isPrivate === true);
+
+    const atts = (ev.payload as { attachments?: PendingAtt[] } | undefined)
+      ?.attachments;
+    if (Array.isArray(atts) && atts.length) {
+      this.bufferAttachments(ev, base, atts, replay);
+      return;
+    }
+
+    if (base.evType === 'react') {
+      await this.handleReact(ev, base);
+      return;
+    }
+    await this.emitMessage(ev, base, replay);
+  }
+}
+
+interface EventBase {
+  evType: string;
+  station: string;
+  from: string;
+  line: string;
+  text: string;
+}
+

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

@@ -0,0 +1,89 @@
+import { stat } from 'node:fs/promises';
+
+const MAX_INLINE_BYTES = 4 * 1024 * 1024;
+
+export interface SavedMedia {
+  contentType?: string;
+  attachmentFor?: string;
+  attachmentPath?: string;
+  url?: string;
+  mime?: string;
+  name?: string;
+  kind?: string;
+  index?: number;
+  reason?: string;
+}
+
+export interface MediaNote {
+  content: string;
+  kind: string;
+  name: string;
+  path: string;
+}
+
+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.';
+}
+
+const headline = (kind: string, name: string, mime: string | undefined, size: number): string =>
+  `[${kind} attachment received: ${name}${mime ? `, ${mime}` : ''}${size ? ` (${(size / 1024 / 1024).toFixed(2)} MB)` : ''}]\n`;
+
+const whereItIs = (path: string, url: string | undefined, size: number, showPath: boolean): string =>
+  showPath ? `Daemon-host path: ${path}\n${howToRead(url, size > MAX_INLINE_BYTES)}` : 'Fetch the Public URL to get the file.';
+
+export async function buildMediaNote(
+  p: SavedMedia,
+  caption: string,
+  showPath = true,
+): Promise<MediaNote | null> {
+  const path = p.attachmentPath;
+  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 content =
+    (caption ? `${caption}\n` : '') +
+    headline(kind, name, p.mime, size) +
+    (p.url ? `Public URL: ${p.url}\n` : '') +
+    whereItIs(path, p.url, size, showPath);
+  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,87 @@
+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;
+  reply: Record<string, string>;
+  callMeta?: () => Record<string, 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;
+  reply?: Record<string, string>;
+  callMeta?: () => Record<string, 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 missingAttachmentNames(buf: PendingMsg): string[] {
+  return buf.attachments
+    .filter((_, i) => !buf.saved.has(i))
+    .map((a) => a.name ?? a.kind ?? 'attachment');
+}
+
+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,
+    reply: buf.reply,
+    callMeta: buf.callMeta,
+  };
+  buf.text = '';
+  return ctx;
+}