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

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

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+import fs, { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, type Stats } from 'node:fs';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { AutomationError } from './automation-types.js';
+import { isRecord } from './is-record.js';
+
+const FILE = 'automation.sqlite';
+const SCHEMA = `
+CREATE TABLE requests (
+  uuid TEXT PRIMARY KEY NOT NULL,
+  routine TEXT NOT NULL,
+  slot INTEGER NOT NULL,
+  payload TEXT NOT NULL,
+  UNIQUE (routine, slot)
+);
+CREATE TABLE statuses (
+  uuid TEXT PRIMARY KEY NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  payload TEXT NOT NULL
+);
+CREATE TABLE resolutions (
+  uuid TEXT NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  outcome TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (uuid, outcome)
+);
+PRAGMA user_version = 1;
+`;
+
+function hasCode(error: unknown, code: string): boolean {
+  return isRecord(error) && error.code === code;
+}
+
+function metadata(path: string): Stats | null {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (hasCode(error, 'ENOENT')) return null;
+    throw error;
+  }
+}
+
+function uid(): number {
+  if (process.getuid === undefined) throw new AutomationError('unsafe-storage');
+  return process.getuid();
+}
+
+function checkDirectory(info: Stats, privateDirectory: boolean): void {
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new AutomationError('unsafe-storage');
+  if (privateDirectory) {
+    if (info.uid !== uid() || (info.mode & 0o7777) !== 0o700) throw new AutomationError('unsafe-storage');
+    return;
+  }
+  if (info.uid !== uid() && info.uid !== 0) throw new AutomationError('unsafe-storage');
+  if ((info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0) throw new AutomationError('unsafe-storage');
+}
+
+function syncDirectory(path: string): void {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function directory(root: string, create: boolean): boolean {
+  let current = parse(root).root;
+  const base = metadata(current);
+  if (base === null) throw new AutomationError('unsafe-storage');
+  checkDirectory(base, current === root);
+  for (const component of root.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, component);
+    let info = metadata(current);
+    if (info === null) {
+      if (!create) return false;
+      try {
+        mkdirSync(current, { mode: 0o700 });
+        syncDirectory(dirname(current));
+      } catch (error) {
+        if (!hasCode(error, 'EEXIST')) throw error;
+      }
+      info = metadata(current);
+    }
+    if (info === null) throw new AutomationError('unsafe-storage');
+    checkDirectory(info, current === root);
+  }
+  return true;
+}
+
+function checkFile(info: Stats, singleLink = false): void {
+  if (!info.isFile() || info.uid !== uid() || (info.mode & 0o7777) !== 0o600 || (singleLink && info.nlink !== 1)) throw new AutomationError('unsafe-storage');
+}
+
+function companions(path: string): void {
+  for (const suffix of ['-journal', '-wal', '-shm']) {
+    const info = metadata(`${path}${suffix}`);
+    if (info !== null) checkFile(info, true);
+  }
+}
+
+function sameFile(path: string, opened: Stats): void {
+  const current = metadata(path);
+  if (current === null || current.dev !== opened.dev || current.ino !== opened.ino) throw new AutomationError('unsafe-storage');
+  checkFile(current);
+}
+
+function initializeFile(path: string, fd: number): void {
+  const opened = fstatSync(fd);
+  checkFile(opened);
+  const db = new DatabaseSync(path);
+  try {
+    sameFile(path, opened);
+    db.exec('PRAGMA trusted_schema = OFF');
+    transaction(db, (database) => { database.exec(SCHEMA); });
+  } finally {
+    db.close();
+  }
+  fs.fsyncSync(fd);
+}
+
+function createFile(path: string): void {
+  if (metadata(path) !== null) return;
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    initializeFile(temporary, fd);
+    try {
+      fs.linkSync(temporary, path);
+    } catch (error) {
+      if (!hasCode(error, 'EEXIST')) throw error;
+    }
+  } finally {
+    closeSync(fd);
+    fs.unlinkSync(temporary);
+  }
+  syncDirectory(dirname(path));
+}
+
+function transaction<T>(db: DatabaseSync, action: (database: DatabaseSync) => T): T {
+  db.exec('PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; PRAGMA foreign_keys = ON; BEGIN IMMEDIATE');
+  try {
+    const result = action(db);
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+function useDatabase<T>(path: string, writable: boolean, action: (database: DatabaseSync) => T): T {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let db: DatabaseSync | undefined;
+  try {
+    const opened = fstatSync(fd);
+    checkFile(opened);
+    companions(path);
+    db = new DatabaseSync(path, { readOnly: !writable });
+    sameFile(path, opened);
+    db.exec('PRAGMA busy_timeout = 5000; PRAGMA trusted_schema = OFF');
+    if (db.prepare('PRAGMA user_version').get()?.user_version !== 1) throw new AutomationError('corrupt-storage');
+    if (writable) return transaction(db, action);
+    if (db.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete') throw new AutomationError('corrupt-storage');
+    db.exec('BEGIN');
+    try {
+      return action(db);
+    } finally {
+      db.exec('ROLLBACK');
+    }
+  } finally {
+    db?.close();
+    closeSync(fd);
+  }
+}
+
+function databasePath(root: string, writable: boolean, existingOnly: boolean): string | null {
+  const create = writable && !existingOnly;
+  const absolute = resolve(root);
+  if (!directory(absolute, create)) return null;
+  const path = join(absolute, FILE);
+  companions(path);
+  if (create) createFile(path);
+  const info = metadata(path);
+  if (info === null) {
+    if (create) throw new AutomationError('storage-unavailable');
+    return null;
+  }
+  checkFile(info);
+  return path;
+}
+
+export function validateAutomationDirectory(root: string): void {
+  try {
+    databasePath(root, false, false);
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}
+
+export function automationDatabase<T>(root: string, writable: boolean, action: (database: DatabaseSync) => T, missing: T, existingOnly = false): T {
+  try {
+    const path = databasePath(root, writable, existingOnly);
+    if (path === null) return missing;
+    const result = useDatabase(path, writable, action);
+    if (writable) {
+      companions(path);
+      syncDirectory(dirname(path));
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}

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/claude-token.ts

@@ -0,0 +1,3 @@
+const TOKEN_RE = /^sk-ant-oat01-[A-Za-z0-9_-]{32,512}$/;
+
+export const isClaudeToken = (value: string): boolean => TOKEN_RE.test(value);

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

@@ -0,0 +1,21 @@
+import { isRecord } from './is-record.js';
+
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'max', 'asked'] as const;
+
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+
+export interface RouteEffort {
+  main?: EffortLevel;
+  helpers?: EffortLevel;
+}
+
+export const EFFORT_DEFAULTS: Required<RouteEffort> = { main: 'low', helpers: 'max' };
+
+export const isEffortLevel = (value: unknown): value is EffortLevel => typeof value === 'string' && (EFFORT_LEVELS as readonly string[]).includes(value);
+
+export function readEffort(raw: unknown): RouteEffort {
+  if (!isRecord(raw)) return {};
+  return { ...(isEffortLevel(raw.main) ? { main: raw.main } : {}), ...(isEffortLevel(raw.helpers) ? { helpers: raw.helpers } : {}) };
+}
+
+export const effortSet = (effort: RouteEffort): boolean => effort.main !== undefined || effort.helpers !== undefined;

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