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

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

@@ -0,0 +1,171 @@
+import { resolve } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { automationDatabase, validateAutomationDirectory } from './automation-files.js';
+import {
+  AUTOMATION_REQUEST_MAX, AUTOMATION_RETENTION_MS, AutomationError, assertAutomationUuid,
+  automationRequest, automationTerminal, parseAutomationRequest, parseAutomationResolution, parseAutomationStatus,
+  type AutomationOutcome, type AutomationRequest, type AutomationResolution, type AutomationStatus,
+} from './automation-types.js';
+import { isRecord } from './is-record.js';
+
+export type { AutomationOutcome, AutomationRequest, AutomationResolution, AutomationStatus, AutomationState, AutomationUuid } from './automation-types.js';
+
+function payload<T extends { uuid: string }>(row: unknown, parse: (value: unknown) => T): T {
+  try {
+    if (!isRecord(row) || typeof row.payload !== 'string') throw new AutomationError('corrupt-storage');
+    const value: unknown = JSON.parse(row.payload);
+    const parsed = parse(value);
+    if (parsed.uuid !== row.uuid) throw new AutomationError('corrupt-storage');
+    return parsed;
+  } catch (error) {
+    throw new AutomationError('corrupt-storage', { cause: error });
+  }
+}
+
+function request(row: unknown): AutomationRequest {
+  const parsed = payload(row, parseAutomationRequest);
+  if (!isRecord(row) || parsed.routine !== row.routine || parsed.slot !== row.slot) throw new AutomationError('corrupt-storage');
+  return parsed;
+}
+
+function requests(db: DatabaseSync): AutomationRequest[] {
+  const rows = db.prepare('SELECT * FROM requests ORDER BY slot, routine LIMIT 513').all();
+  if (rows.length > AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map(request);
+}
+
+function status(db: DatabaseSync, uuid: string): AutomationStatus | null {
+  const row = db.prepare('SELECT * FROM statuses WHERE uuid = ?').get(uuid);
+  return row === undefined ? null : payload(row, parseAutomationStatus);
+}
+
+function statuses(db: DatabaseSync): AutomationStatus[] {
+  const rows = db.prepare('SELECT * FROM statuses LIMIT 513').all();
+  if (rows.length > AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map((row) => payload(row, parseAutomationStatus));
+}
+
+function resolution(row: unknown): AutomationResolution {
+  const parsed = payload(row, parseAutomationResolution);
+  if (!isRecord(row) || parsed.outcome !== row.outcome) throw new AutomationError('corrupt-storage');
+  return parsed;
+}
+
+function resolutions(db: DatabaseSync): AutomationResolution[] {
+  const rows = db.prepare('SELECT * FROM resolutions ORDER BY uuid, outcome LIMIT 1025').all();
+  if (rows.length > 2 * AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map(resolution);
+}
+
+function requireRequest(db: DatabaseSync, uuid: string): AutomationRequest {
+  const row = db.prepare('SELECT * FROM requests WHERE uuid = ?').get(uuid);
+  if (row === undefined) throw new AutomationError('unknown-request');
+  return request(row);
+}
+
+function validate(db: DatabaseSync): void {
+  const known = new Set(requests(db).map((entry) => entry.uuid));
+  for (const entry of [...statuses(db), ...resolutions(db)]) {
+    if (!known.has(entry.uuid)) throw new AutomationError('corrupt-storage');
+  }
+  if (db.prepare('PRAGMA quick_check').get()?.quick_check !== 'ok') throw new AutomationError('corrupt-storage');
+}
+
+function expiredRequests(db: DatabaseSync, cutoff: number): AutomationRequest[] {
+  const saved = new Map(statuses(db).map((entry) => [entry.uuid, entry]));
+  return requests(db).filter((entry) => {
+    const current = saved.get(entry.uuid);
+    return current !== undefined && automationTerminal(current.state) && entry.slot < cutoff && current.updatedAt < cutoff;
+  });
+}
+
+export class AutomationStore {
+  readonly root: string;
+
+  constructor(root: string, private readonly now: () => number = Date.now) {
+    this.root = resolve(root);
+  }
+
+  validate(): void {
+    validateAutomationDirectory(this.root);
+  }
+
+  recover(): void {
+    automationDatabase(this.root, true, validate, undefined, true);
+  }
+
+  submit(routine: string, slot: number, prompt: string): AutomationRequest {
+    const proposed = automationRequest(routine, slot, prompt, this.now());
+    return automationDatabase(this.root, true, (db) => {
+      const accepted = automationRequest(routine, slot, prompt, this.now());
+      const existing = requests(db);
+      const found = existing.find((entry) => entry.routine === routine && entry.slot === slot);
+      if (found !== undefined) {
+        if (found.prompt !== prompt) throw new AutomationError('conflict');
+        return found;
+      }
+      if (existing.length >= AUTOMATION_REQUEST_MAX) throw new AutomationError('full');
+      db.prepare('INSERT INTO requests (uuid, routine, slot, payload) VALUES (?, ?, ?, ?)')
+        .run(accepted.uuid, routine, slot, JSON.stringify(accepted));
+      return accepted;
+    }, proposed);
+  }
+
+  requests(): AutomationRequest[] {
+    return automationDatabase(this.root, false, requests, []);
+  }
+
+  status(uuid: string): AutomationStatus | null {
+    assertAutomationUuid(uuid);
+    return automationDatabase(this.root, false, (db) => status(db, uuid), null);
+  }
+
+  statuses(): AutomationStatus[] {
+    return automationDatabase(this.root, false, statuses, []);
+  }
+
+  saveStatus(value: AutomationStatus): void {
+    const parsed = parseAutomationStatus(value);
+    automationDatabase(this.root, true, (db) => {
+      requireRequest(db, parsed.uuid);
+      db.prepare('INSERT INTO statuses (uuid, payload) VALUES (?, ?) ON CONFLICT(uuid) DO UPDATE SET payload = excluded.payload')
+        .run(parsed.uuid, JSON.stringify(parsed));
+    }, undefined);
+  }
+
+  finish(uuid: string, token: string, outcome: AutomationOutcome): AutomationResolution {
+    const proposed = parseAutomationResolution({ uuid, token, outcome, createdAt: this.now() });
+    const current = this.status(uuid);
+    if (current === null) throw new AutomationError('unknown-request');
+    if (current.token !== token) throw new AutomationError('invalid-token');
+    return automationDatabase(this.root, true, (db) => {
+      requireRequest(db, uuid);
+      if (status(db, uuid)?.token !== token) throw new AutomationError('invalid-token');
+      const row = db.prepare('SELECT * FROM resolutions WHERE uuid = ? AND outcome = ?').get(uuid, outcome);
+      if (row !== undefined) {
+        const found = resolution(row);
+        if (found.token !== token) throw new AutomationError('invalid-token');
+        return found;
+      }
+      db.prepare('INSERT INTO resolutions (uuid, outcome, payload) VALUES (?, ?, ?)').run(uuid, outcome, JSON.stringify(proposed));
+      return proposed;
+    }, proposed);
+  }
+
+  resolutions(): AutomationResolution[] {
+    return automationDatabase(this.root, false, resolutions, []);
+  }
+
+  prune(): number {
+    const cutoff = this.now() - AUTOMATION_RETENTION_MS;
+    if (!Number.isSafeInteger(cutoff)) throw new AutomationError('invalid-slot');
+    const eligible = automationDatabase(this.root, false, (db) => expiredRequests(db, cutoff).length > 0, false);
+    if (!eligible) return 0;
+    return automationDatabase(this.root, true, (db) => {
+      validate(db);
+      const expired = expiredRequests(db, cutoff);
+      for (const entry of expired) db.prepare('DELETE FROM requests WHERE uuid = ?').run(entry.uuid);
+      return expired.length;
+    }, 0);
+  }
+}

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

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from './is-record.js';
+
+export const AUTOMATION_PROMPT_MAX = 64 * 1024;
+const PROMPT_JSON_MAX = 128 * 1024 + 2;
+export const AUTOMATION_REQUEST_MAX = 512;
+export const AUTOMATION_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const AUTOMATION_ROUTINE_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const STATES = ['dispatched', 'consumed', 'awaiting-completion', 'completed', 'failed', 'interrupted', 'coalesced', 'cancelled'] as const;
+const DETAILS = ['sdk-completed', 'sdk-failed', 'runner-interrupted', 'newer-slot', 'owner-cancelled', 'worker-blocked', 'worker-completed'] as const;
+const TERMINAL = new Set<AutomationState>(['completed', 'coalesced', 'cancelled']);
+const ERRORS = {
+  'invalid-routine': 'Routine must be a lowercase name of at most 64 characters.',
+  'invalid-slot': 'Slot must be an integer timestamp within the past seven days or next five minutes.',
+  'invalid-prompt': 'Prompt must be text no larger than 64 KiB and 128 KiB plus quotes when JSON-encoded.',
+  'invalid-uuid': 'Automation identifier must be a canonical UUID.',
+  'invalid-request': 'Automation request is invalid.',
+  'invalid-status': 'Automation status is invalid.',
+  'invalid-resolution': 'Automation completion receipt is invalid.',
+  conflict: 'This routine and slot already have a different prompt.',
+  full: 'Automation queue is full. Only old terminal requests may be pruned.',
+  'unknown-request': 'Automation request does not exist.',
+  'invalid-token': 'Completion token does not match the dispatched request.',
+  'unsafe-storage': 'Automation storage must be private, owned by this user, and free of symlinks.',
+  'corrupt-storage': 'Automation storage is corrupt. No requests were discarded.',
+  'storage-unavailable': 'Automation storage is unavailable. No acceptance is confirmed.',
+} as const;
+
+export type AutomationUuid = `${string}-${string}-${string}-${string}-${string}`;
+export type AutomationState = (typeof STATES)[number];
+export type AutomationDetail = (typeof DETAILS)[number];
+export type AutomationOutcome = 'completed' | 'blocked';
+export type AutomationErrorCode = keyof typeof ERRORS;
+
+export class AutomationError extends Error {
+  constructor(readonly code: AutomationErrorCode, options?: ErrorOptions) {
+    super(ERRORS[code], options);
+    this.name = 'AutomationError';
+  }
+}
+
+export interface AutomationRequest {
+  version: 1;
+  routine: string;
+  slot: number;
+  uuid: AutomationUuid;
+  createdAt: number;
+  prompt: string;
+  digest: string;
+}
+
+export interface AutomationStatus {
+  uuid: AutomationUuid;
+  state: AutomationState;
+  updatedAt: number;
+  token: AutomationUuid;
+  detail?: AutomationDetail;
+}
+
+export interface AutomationResolution {
+  uuid: AutomationUuid;
+  token: AutomationUuid;
+  outcome: AutomationOutcome;
+  createdAt: number;
+}
+
+export function assertRoutine(routine: unknown): asserts routine is string {
+  if (typeof routine !== 'string' || !AUTOMATION_ROUTINE_RE.test(routine)) throw new AutomationError('invalid-routine');
+}
+
+export function assertAutomationUuid(uuid: unknown): asserts uuid is AutomationUuid {
+  if (typeof uuid !== 'string' || !UUID_RE.test(uuid)) throw new AutomationError('invalid-uuid');
+}
+
+function timestamp(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 8_640_000_000_000_000;
+}
+
+function promptValid(value: unknown): value is string {
+  return typeof value === 'string' && Buffer.byteLength(value, 'utf8') <= AUTOMATION_PROMPT_MAX && Buffer.byteLength(JSON.stringify(value), 'utf8') <= PROMPT_JSON_MAX;
+}
+
+function validSlot(slot: number, now: number): boolean {
+  return slot >= now - AUTOMATION_RETENTION_MS && slot <= now + 300_000;
+}
+
+function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function requestUuid(routine: string, slot: number): AutomationUuid {
+  const bytes = createHash('sha256').update(`${routine}\n${slot}`).digest();
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x80;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = bytes.subarray(0, 16).toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function automationRequest(routine: string, slot: number, prompt: string, now = Date.now()): AutomationRequest {
+  assertRoutine(routine);
+  if (!timestamp(now) || !timestamp(slot) || !validSlot(slot, now)) throw new AutomationError('invalid-slot');
+  if (!promptValid(prompt)) throw new AutomationError('invalid-prompt');
+  return { version: 1, routine, slot, uuid: requestUuid(routine, slot), createdAt: now, prompt, digest: hash(prompt) };
+}
+
+function fields(raw: Record<string, unknown>, required: string[], optional: string[] = []): boolean {
+  return required.every((key) => Object.hasOwn(raw, key)) && Object.keys(raw).every((key) => required.includes(key) || optional.includes(key));
+}
+
+export function parseAutomationRequest(raw: unknown): AutomationRequest {
+  if (!isRecord(raw) || !fields(raw, ['version', 'routine', 'slot', 'uuid', 'createdAt', 'prompt', 'digest'])) throw new AutomationError('invalid-request');
+  assertRoutine(raw.routine);
+  assertAutomationUuid(raw.uuid);
+  if (raw.version !== 1 || !timestamp(raw.slot) || !timestamp(raw.createdAt) || !promptValid(raw.prompt)) throw new AutomationError('invalid-request');
+  if (!validSlot(raw.slot, raw.createdAt) || raw.uuid !== requestUuid(raw.routine, raw.slot) || raw.digest !== hash(raw.prompt)) throw new AutomationError('invalid-request');
+  return { version: 1, routine: raw.routine, slot: raw.slot, uuid: raw.uuid, createdAt: raw.createdAt, prompt: raw.prompt, digest: raw.digest };
+}
+
+export function parseAutomationStatus(raw: unknown): AutomationStatus {
+  if (!isRecord(raw) || !fields(raw, ['uuid', 'state', 'updatedAt', 'token'], ['detail'])) throw new AutomationError('invalid-status');
+  assertAutomationUuid(raw.uuid);
+  assertAutomationUuid(raw.token);
+  const state = STATES.find((entry) => entry === raw.state);
+  if (state === undefined || !timestamp(raw.updatedAt)) throw new AutomationError('invalid-status');
+  const detail = DETAILS.find((entry) => entry === raw.detail);
+  if (raw.detail !== undefined && detail === undefined) throw new AutomationError('invalid-status');
+  return { uuid: raw.uuid, state, updatedAt: raw.updatedAt, token: raw.token, ...(detail === undefined ? {} : { detail }) };
+}
+
+export function parseAutomationResolution(raw: unknown): AutomationResolution {
+  if (!isRecord(raw) || !fields(raw, ['uuid', 'token', 'outcome', 'createdAt'])) throw new AutomationError('invalid-resolution');
+  assertAutomationUuid(raw.uuid);
+  assertAutomationUuid(raw.token);
+  if (!timestamp(raw.createdAt) || (raw.outcome !== 'completed' && raw.outcome !== 'blocked')) throw new AutomationError('invalid-resolution');
+  return { uuid: raw.uuid, token: raw.token, outcome: raw.outcome, createdAt: raw.createdAt };
+}
+
+export function automationTerminal(state: AutomationState): boolean {
+  return TERMINAL.has(state);
+}

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

@@ -0,0 +1,81 @@
+import { isRecord } from './is-record.js';
+
+export const CALL_NOTICE = 'notifications/metro/call';
+export const CALL_STATE = 'notifications/metro/call_state';
+
+export interface CallState {
+  route: CallRoute | null;
+}
+
+export interface CallRoute {
+  agentId: string;
+  line: string;
+  from: string;
+  callId: string;
+  generation: string;
+}
+
+export interface SpeechTarget {
+  callId: string;
+  generation: string;
+  sourceId: string;
+}
+
+export interface CallSource {
+  route: CallRoute;
+  sourceId: string;
+}
+
+export type SpeechStatus = 'accepted' | 'queued' | 'started' | 'completed' | 'interrupted' | 'failed';
+
+export type CallNotice =
+  | { type: 'started'; route: CallRoute; sourceId: string }
+  | { type: 'heard'; route: CallRoute; sourceId: string; text: string }
+  | { type: 'ended'; route: CallRoute }
+  | { type: 'speech'; route: CallRoute; sourceId: string; actionId: string; status: SpeechStatus };
+
+const filled = (value: unknown): value is string => typeof value === 'string' && value.length > 0 && value.length <= 2048;
+
+export function callRoute(value: unknown): CallRoute | null {
+  if (!isRecord(value)) return null;
+  const { agentId, line, from, callId, generation } = value;
+  return filled(agentId) && filled(line) && filled(from) && filled(callId) && filled(generation)
+    ? { agentId, line, from, callId, generation }
+    : null;
+}
+
+export function callState(value: unknown): CallState | null {
+  if (!isRecord(value)) return null;
+  if (value.route === null) return { route: null };
+  const route = callRoute(value.route);
+  return route === null ? null : { route };
+}
+
+export function speechTarget(value: unknown): SpeechTarget | null {
+  if (!isRecord(value)) return null;
+  const { callId, generation, sourceId } = value;
+  return filled(callId) && filled(generation) && filled(sourceId) ? { callId, generation, sourceId } : null;
+}
+
+const STATUSES: readonly SpeechStatus[] = ['accepted', 'queued', 'started', 'completed', 'interrupted', 'failed'];
+
+const speechStatus = (value: unknown): SpeechStatus | null => STATUSES.find((status) => status === value) ?? null;
+
+function sourcedNotice(value: Record<string, unknown>, route: CallRoute, sourceId: string): CallNotice | null {
+  if (value.type === 'started') return { type: 'started', route, sourceId };
+  if (value.type === 'heard') return typeof value.text === 'string' && value.text.length <= 32_000 ? { type: 'heard', route, sourceId, text: value.text } : null;
+  if (value.type !== 'speech' || !filled(value.actionId)) return null;
+  const status = speechStatus(value.status);
+  return status === null ? null : { type: 'speech', route, sourceId, actionId: value.actionId, status };
+}
+
+export function callNotice(value: unknown): CallNotice | null {
+  if (!isRecord(value)) return null;
+  const route = callRoute(value.route);
+  if (route === null) return null;
+  if (value.type === 'ended') return { type: 'ended', route };
+  return filled(value.sourceId) ? sourcedNotice(value, route, value.sourceId) : null;
+}
+
+export const sameCall = (a: CallRoute, b: CallRoute): boolean =>
+  a.agentId === b.agentId && a.line === b.line && a.from === b.from && a.callId === b.callId && a.generation === b.generation;

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

@@ -0,0 +1,7 @@
+export interface Endpoint {
+  id: string;
+  webhookId?: string;
+  label: string;
+  secret?: string;
+  createdAt: string;
+}

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),
+};