@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.320

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/events.ts

@@ -0,0 +1,165 @@
+import { Line } from './lines.js';
+import { errMsg, log } from './log.js';
+
+export const userSelf = (): Line =>
+  (process.env.METRO_FROM ?? 'metro://user') as Line;
+
+export type StructuredEvent =
+  | { type: 'msg' }
+  | { type: 'react'; emoji?: string; targetId?: string }
+  | { type: 'edit'; targetId?: string }
+  | { type: 'delete'; targetId?: string }
+  | { type: 'reply'; replyTo?: string }
+  | { type: 'system'; source?: string; eventName?: string };
+
+export interface MetroEvent {
+  id: string;
+  ts: string;
+  station: string;
+  line: Line;
+  lineName?: string;
+  from: Line;
+  fromName?: string;
+  fromDisplayName?: string;
+  to: Line;
+  text?: string;
+  messageId?: string;
+  replyTo?: string;
+  isPrivate?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  senderVerified?: boolean;
+  payload?: unknown;
+  display?: string;
+  event?: StructuredEvent;
+  agent?: string;
+  seq?: number;
+}
+
+function isExternalWebhook(e: MetroEvent): boolean {
+  return e.station === 'webhook' && !Line.isLocal(e.from);
+}
+
+function webhookEventName(e: MetroEvent): string | undefined {
+  const headers = (e.payload as { headers?: Record<string, string> } | undefined)
+    ?.headers;
+  return headers?.['x-github-event'] ?? headers?.['x-intercom-topic'];
+}
+
+export function classifyEvent(e: MetroEvent): StructuredEvent {
+  if (isExternalWebhook(e)) {
+    return {
+      type: 'system',
+      source: 'webhook',
+      eventName: webhookEventName(e),
+    };
+  }
+  const emoji =
+    (e.payload as { emoji?: string } | undefined)?.emoji ??
+    e.text?.match(/^\[react (.+)\]$/)?.[1];
+  if (emoji) return { type: 'react', emoji, targetId: e.replyTo };
+  if (e.replyTo) return { type: 'reply', replyTo: e.replyTo };
+  return { type: 'msg' };
+}
+
+export function formatDisplay(e: MetroEvent): string {
+  const headerFor = (icon: string, parts: (string | undefined)[]): string =>
+    `**${icon} ${parts.filter(Boolean).join(' · ')}**`;
+  const body = e.text ?? '';
+  if (isExternalWebhook(e)) {
+    const ev = webhookEventName(e);
+    return `${headerFor('🪝', ['webhook', e.lineName, ev])}\n> ${body}`;
+  }
+  if (Line.isLocal(e.from)) {
+    return `${headerFor('📤', [e.station, '→', e.fromName ?? e.to])}\n> ${body}`;
+  }
+  return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
+}
+
+export { mintId } from './ids.js';
+
+export type BusListener = (event: MetroEvent, busSeq: number) => void;
+
+export interface BufferedEvent {
+  busSeq: number;
+  event: MetroEvent;
+}
+
+export const BUS_BUFFER_MAX = 500;
+
+export interface RunEventMetadata {
+  isPrivate?: boolean;
+  senderVerified?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  emoji?: string;
+  removed?: boolean;
+  targetId?: string;
+  attachmentCount?: number;
+  attachmentTypes?: ('image' | 'video' | 'audio' | 'file')[];
+  attachmentStatus?: 'saved' | 'failed';
+  attachmentFor?: string;
+}
+
+export interface RunEvent {
+  id: string;
+  seq: number;
+  ts: string;
+  kind: StructuredEvent['type'];
+  direction: 'inbound' | 'outbound' | 'system';
+  agentId: string;
+  station: string;
+  accountId: string | null;
+  line: string;
+  lineName?: string;
+  from?: string;
+  fromName?: string;
+  fromDisplayName?: string;
+  to?: string;
+  text?: string;
+  truncated: boolean;
+  messageId?: string;
+  replyTo?: string;
+  metadata: RunEventMetadata;
+}
+
+export interface RunEventsPage {
+  events: RunEvent[];
+  cursor: string;
+  hasMore: boolean;
+  reset: boolean;
+  retention: { capacity: number; oldestAt: string | null; oldestSeq: number | null };
+}
+
+const listeners = new Set<BusListener>();
+const buffer: BufferedEvent[] = [];
+let busSeq = 0;
+
+export function publishEvent(event: MetroEvent): void {
+  busSeq += 1;
+  const seq = busSeq;
+  buffer.push({ busSeq: seq, event });
+  if (buffer.length > BUS_BUFFER_MAX) buffer.shift();
+  for (const fn of [...listeners]) {
+    try {
+      fn(event, seq);
+    } catch (err) {
+      log.error({ busSeq: seq, err: errMsg(err) }, 'bus: a listener threw');
+    }
+  }
+}
+
+export function currentBusSeq(): number {
+  return busSeq;
+}
+
+export function bufferedSince(afterBusSeq: number): BufferedEvent[] {
+  return buffer.filter((b) => b.busSeq > afterBusSeq);
+}
+
+export function subscribeEvents(fn: BusListener): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/ids.ts

@@ -0,0 +1,28 @@
+import { randomBytes, randomInt } from 'node:crypto';
+
+const ID_BYTES = 8;
+const REROLLS = 16;
+const APPROVAL_LETTERS = 'abcdefghijkmnopqrstuvwxyz';
+const APPROVAL_LENGTH = 5;
+
+export const approvalId = (): string => Array.from({ length: APPROVAL_LENGTH }, () => APPROVAL_LETTERS[randomInt(APPROVAL_LETTERS.length)]).join('');
+
+export const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{10}$/;
+
+export const mintId = (): string =>
+  `msg_${randomBytes(6).toString('base64url')}`;
+
+export function newId(): string {
+  for (let attempt = 0; attempt < REROLLS; attempt += 1) {
+    const id = randomBytes(ID_BYTES).toString('base64url');
+    if (ID_RE.test(id)) return id;
+  }
+  throw new Error('could not generate an id');
+}
+
+export function parseId(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  return ID_RE.test(raw) ? raw : null;
+}
+
+export const AGENT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{1,31}$/;

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/is-record.ts

@@ -0,0 +1,2 @@
+export const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/lines.ts

@@ -0,0 +1,78 @@
+export type Line = string & { readonly __line: unique symbol };
+export const asLine = (s: string): Line => s as Line;
+
+const PREFIX = 'metro://';
+const build = (station: string, ...seg: (string | number)[]): Line =>
+  asLine(`${PREFIX}${station}/${seg.map(String).join('/')}`);
+
+function parseAccountScoped(
+  line: Line | string,
+  station: string,
+  validate?: (resource: string) => boolean,
+): { accountId: string; resource: string } | null {
+  const p = Line.parse(line);
+  if (p?.station !== station || p.path.length !== 2) return null;
+  const [accountId, resource] = p.path;
+  if (accountId === undefined || resource === undefined) return null;
+  if (validate && !validate(resource)) return null;
+  return { accountId, resource };
+}
+
+const isSnowflake = (s: string): boolean => /^\d+$/.test(s);
+const isThreemaResource = (s: string): boolean =>
+  /^(?:[A-Z0-9]{8}|\*[A-Z0-9]{7})(?:-[0-9a-f]{16})?$/i.test(s);
+const isMailResource = (s: string): boolean => /^[A-Za-z0-9=_%.@+-]+$/.test(s);
+const isSignedInt = (s: string): boolean => /^-?\d+$/.test(s);
+
+const topicPart = (topicId: string | undefined): { topicId?: number } | null => {
+  if (topicId === undefined) return {};
+  return isSnowflake(topicId) ? { topicId: Number(topicId) } : null;
+};
+
+function parseTelegramLine(
+  line: Line | string,
+): { accountId: string; chatId: number; topicId?: number } | null {
+  const p = Line.parse(line);
+  if (p?.station !== 'telegram-bot') return null;
+  const [accountId, chatId, topicId, ...extra] = p.path;
+  if (accountId === undefined || chatId === undefined || extra.length > 0) return null;
+  if (!isSignedInt(chatId)) return null;
+  const topic = topicPart(topicId);
+  return topic === null ? null : { accountId, chatId: Number(chatId), ...topic };
+}
+
+export const Line = {
+  claude: (orgId: string, sessionId: string): Line =>
+    build('claude', orgId, sessionId),
+  webhook: (endpointId: string): Line => build('webhook', endpointId),
+  user: (station: string, id: string | number): Line =>
+    build(station, 'user', id),
+
+  parse(line: Line | string): { station: string; path: string[] } | null {
+    if (!line.startsWith(PREFIX)) return null;
+    const rest = line.slice(PREFIX.length);
+    const slash = rest.indexOf('/');
+    if (slash <= 0) return null;
+    const path = rest
+      .slice(slash + 1)
+      .split('/')
+      .filter(Boolean);
+    return path.length ? { station: rest.slice(0, slash), path } : null;
+  },
+  station: (line: Line | string): string | null =>
+    Line.parse(line)?.station ?? null,
+  isLocal: (line: Line | string): boolean => Line.station(line) === 'claude',
+
+  parseXmtp: (line: Line | string) => parseAccountScoped(line, 'xmtp'),
+
+  parseDiscord: (line: Line | string) =>
+    parseAccountScoped(line, 'discord-bot', isSnowflake),
+
+  parseTelegram: (line: Line | string) => parseTelegramLine(line),
+
+  parseThreema: (line: Line | string) =>
+    parseAccountScoped(line, 'threema', isThreemaResource),
+
+  parseMail: (line: Line | string, station: 'outlook' | 'gmail') =>
+    parseAccountScoped(line, station, isMailResource),
+};

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/log.ts

@@ -0,0 +1,42 @@
+import { writeSync } from 'node:fs';
+import pino from 'pino';
+import pinoPretty from 'pino-pretty';
+
+const stream = process.stderr.isTTY
+  ? pinoPretty({
+      colorize: true,
+      translateTime: 'HH:MM:ss',
+      ignore: 'pid,hostname,name',
+      destination: 2,
+    })
+  : pino.destination(2);
+
+export const log = pino(
+  { base: { name: 'metro' }, level: process.env.METRO_LOG_LEVEL ?? 'info' },
+  stream,
+);
+
+export const logFatalSync = (
+  fields: Record<string, unknown>,
+  msg: string,
+): void => {
+  const line = JSON.stringify({
+    level: 60,
+    time: Date.now(),
+    name: 'metro',
+    ...fields,
+    msg,
+  });
+  try {
+    writeSync(2, `${line}\n`);
+  } catch {
+    return;
+  }
+};
+
+export const errMsg = (err: unknown): string => {
+  if (err instanceof Error) return err.message;
+  if (err && typeof err === 'object' && 'message' in err)
+    return String(err.message);
+  return String(err);
+};

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/protocol.ts

@@ -0,0 +1,227 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join, parse as parsePath } from 'node:path';
+import { errMsg, log } from './log.js';
+import { coerceErrorInfo, type TrainErrorInfo } from './train-error.js';
+import type { StructuredEvent } from './events.js';
+import type { CallMsg } from './stations/station-runtime.js';
+
+export {
+  TrainError,
+  serializeTrainError,
+  type TrainErrorInfo,
+} from './train-error.js';
+
+const CALL_TIMEOUT_MS = 60_000;
+
+export interface Pending {
+  resolve: (r: TrainCallResponse) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+export interface CallTarget {
+  name: string;
+  pending: Map<string, Pending>;
+  proc: ({ stdin?: unknown } & Record<string, unknown>) | null;
+}
+
+const STDOUT_LINE_MAX = 4 * 1024 * 1024;
+
+export type TrainEvent = {
+  station?: string;
+  line?: string;
+  line_name?: string;
+  from?: string;
+  from_name?: string;
+  from_display_name?: string;
+  to?: string;
+  message_id?: string;
+  reply_to?: string;
+  is_private?: boolean;
+  mentions_self?: boolean;
+  reply_to_self?: boolean;
+  sender_verified?: boolean;
+  text?: string;
+  emoji?: string;
+  payload?: unknown;
+  ts?: string;
+  id?: string;
+  event?: StructuredEvent;
+} & Record<string, unknown>;
+
+export interface TrainCallResponse {
+  result?: unknown;
+  error?: string;
+  errorInfo?: TrainErrorInfo;
+}
+
+export type TrainMessage =
+  | {
+      op: 'response';
+      id: string;
+      result?: unknown;
+      error?: string;
+      errorInfo?: TrainErrorInfo;
+    }
+  | { op: 'log'; text?: string }
+  | { op: 'event'; event: TrainEvent }
+  | { op: 'ignore' };
+
+export function parseTrainLine(
+  name: string,
+  line: string,
+): TrainMessage | null {
+  let msg: {
+    op?: string;
+    id?: string;
+    result?: unknown;
+    error?: string;
+    errorInfo?: unknown;
+    text?: string;
+  } & Record<string, unknown>;
+  try {
+    msg = JSON.parse(line) as typeof msg;
+  } catch (err) {
+    log.warn(
+      { name, err: errMsg(err), line: line.slice(0, 200) },
+      'train: bad JSON',
+    );
+    return null;
+  }
+  if (msg.op === 'response') {
+    if (typeof msg.id !== 'string') return { op: 'ignore' };
+    return {
+      op: 'response',
+      id: msg.id,
+      result: msg.result,
+      error: msg.error,
+      errorInfo: coerceErrorInfo(msg.errorInfo),
+    };
+  }
+  if (msg.op === 'log') return { op: 'log', text: msg.text };
+  if (typeof msg.line !== 'string') {
+    log.warn(
+      { name, line: line.slice(0, 200) },
+      'train: event missing `line` (string) — dropped',
+    );
+    return { op: 'ignore' };
+  }
+  return { op: 'event', event: msg };
+}
+
+export function drainLines(
+  name: string,
+  buf: string,
+  onLine: (line: string) => void,
+): string {
+  if (buf.length > STDOUT_LINE_MAX && !buf.includes('\n')) {
+    log.warn(
+      { name, bytes: buf.length },
+      'train: dropping oversized stdout line',
+    );
+    return '';
+  }
+  let nl;
+  while ((nl = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    onLine(line);
+  }
+  return buf;
+}
+
+export function readCalls(
+  name: string,
+  handleCall: (msg: CallMsg) => Promise<void>,
+): void {
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk: Buffer | string) => {
+    buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    buf = drainLines(name, buf, (line) => {
+      try {
+        const msg = JSON.parse(line) as Partial<CallMsg>;
+        if (msg.op === 'call')
+          handleCall(msg as CallMsg).catch((e: unknown) => {
+            process.stderr.write(`call failed: ${errMsg(e)}\n`);
+          });
+      } catch (err: unknown) {
+        process.stderr.write(`bad stdin line: ${errMsg(err)}\n`);
+      }
+    });
+  });
+}
+
+function encodeCall(id: string, action: string, args: unknown): string {
+  return JSON.stringify({ op: 'call', id, action, args }) + '\n';
+}
+
+function isTrainFile(name: string): boolean {
+  return (
+    /\.(ts|js|mjs)$/.test(name) &&
+    !name.startsWith('_') &&
+    !name.startsWith('.')
+  );
+}
+
+export function listTrainFiles(dir: string): { name: string; path: string }[] {
+  return readdirSync(dir)
+    .filter(isTrainFile)
+    .map((f) => ({ name: parsePath(f).name, path: join(dir, f) }))
+    .filter((t) => {
+      try {
+        return statSync(t.path).isFile();
+      } catch {
+        return false;
+      }
+    });
+}
+
+export function mintCallId(seq: number): string {
+  return `req_${seq}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export function failAllPending(
+  pending: Map<string, Pending>,
+  reason: string,
+): void {
+  for (const p of pending.values()) {
+    clearTimeout(p.timer);
+    p.reject(new Error(reason));
+  }
+  pending.clear();
+}
+
+export function sendCall(
+  t: CallTarget,
+  id: string,
+  action: string,
+  args: unknown,
+): Promise<TrainCallResponse> {
+  return new Promise<TrainCallResponse>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      t.pending.delete(id);
+      reject(
+        new Error(
+          `train '${t.name}' call '${action}' timed out after ${CALL_TIMEOUT_MS}ms`,
+        ),
+      );
+    }, CALL_TIMEOUT_MS);
+    t.pending.set(id, { resolve, reject, timer });
+    try {
+      const stdin = (
+        t.proc as {
+          stdin?: { write: (s: string) => void; flush: () => void };
+        } | null
+      )?.stdin;
+      if (!stdin || typeof stdin === 'number')
+        throw new Error('stdin not piped');
+      stdin.write(encodeCall(id, action, args));
+      stdin.flush();
+    } catch (err) {
+      clearTimeout(timer);
+      t.pending.delete(id);
+      reject(new Error(`train '${t.name}' stdin write failed: ${errMsg(err)}`));
+    }
+  });
+}