@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

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

@@ -0,0 +1,49 @@
+import { errMsg, log, logFatalSync } from '@metro-labs/core/log';
+
+export type CrashKind = 'unhandledRejection' | 'uncaughtException';
+
+const seen: Record<CrashKind, number> = {
+  unhandledRejection: 0,
+  uncaughtException: 0,
+};
+
+let ready = false;
+let installed = false;
+
+export function markDaemonReady(): void {
+  ready = true;
+}
+
+export function crashCount(kind: CrashKind): number {
+  return seen[kind];
+}
+
+function fields(kind: CrashKind, err: unknown): Record<string, unknown> {
+  return {
+    crash: kind,
+    seen: seen[kind],
+    err: errMsg(err),
+    errType: err instanceof Error ? err.name : typeof err,
+    stack: err instanceof Error ? err.stack : undefined,
+  };
+}
+
+function reportCrash(kind: CrashKind, err: unknown): void {
+  seen[kind] += 1;
+  if (!ready) {
+    logFatalSync(fields(kind, err), 'daemon: failed before it was ready');
+    process.exit(1);
+  }
+  log.error(fields(kind, err), 'daemon: kept running through a crash');
+}
+
+export function installCrashGuard(): void {
+  if (installed) return;
+  installed = true;
+  process.on('unhandledRejection', (reason: unknown) => {
+    reportCrash('unhandledRejection', reason);
+  });
+  process.on('uncaughtException', (err: unknown) => {
+    reportCrash('uncaughtException', err);
+  });
+}

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

@@ -0,0 +1,30 @@
+import { localOwner, setLocalOwner } from '../agents/file-admin.js';
+import { isOrganizationId } from '@metro-labs/http/workos-token';
+import { log } from '@metro-labs/core/log';
+
+const NO_ONE = 'nobody can sign in; restart with metro serve --owner <organization id>';
+
+const WALLET = `the owner is a wallet address, and wallets cannot sign in any more; ${NO_ONE}`;
+
+function keepsOrganization(wanted: string, stored: string | null): stored is string {
+  return wanted !== '' && stored !== null && isOrganizationId(stored) && !isOrganizationId(wanted);
+}
+
+function announce(owner: string | null): string | null {
+  if (owner === null) log.warn(`local daemon: no owner set, so ${NO_ONE}`);
+  else if (!isOrganizationId(owner)) log.warn(`local daemon: ${WALLET}`);
+  return owner;
+}
+
+export function applyLocalOwner(): string | null {
+  const wanted = process.env.METRO_OWNER?.trim() ?? '';
+  const stored = localOwner();
+  if (keepsOrganization(wanted, stored)) {
+    log.info({ owner: stored, ignored: wanted }, 'local daemon: this machine belongs to an organization, so the wallet in --owner is ignored');
+    return stored;
+  }
+  if (wanted === '') return announce(stored);
+  const owner = setLocalOwner(wanted);
+  log.info({ owner }, 'local daemon: owner set from METRO_OWNER');
+  return announce(owner);
+}

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

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process';
+import {
+  closeSync,
+  mkdirSync,
+  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';
+
+export const STATE_DIR =
+  process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+mkdirSync(STATE_DIR, { recursive: true });
+
+
+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,25 @@
+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 }),
+  };
+}

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

@@ -0,0 +1,24 @@
+import { accountFromLine, agentIdForAccount } from '../agents/map.js';
+
+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('/');
+};
+
+export const dedupeOwner = (line: string): string => {
+  const acct = accountFromLine(line);
+  if (!acct) return 'unowned';
+  const agentId = agentIdForAccount(acct.station, acct.accountId);
+  return agentId === undefined
+    ? `account:${acct.accountId}`
+    : `agent:${agentId}`;
+};
+
+export const dedupeKey = (
+  station: string,
+  line: string,
+  kind: string,
+  messageId: string,
+): string =>
+  `${dedupeOwner(line)} ${station} ${accountStrippedLine(line)} ${kind} ${messageId}`;

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

@@ -0,0 +1,380 @@
+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' && base.text.trim() === '') {
+      this.deps.log('drop: empty message', base.station, base.line, str(ev.messageId));
+      return;
+    }
+    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: '' };
+}