@stage-labs/metro 0.1.0-beta.261 → 0.1.0-beta.263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.261",
+  "version": "0.1.0-beta.263",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.261",
+  "version": "0.1.0-beta.263",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

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

@@ -85,7 +85,51 @@ export interface BufferedEvent {
   event: MetroEvent;
 }
 
-const BUS_BUFFER_MAX = 500;
+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[] = [];

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

@@ -7,6 +7,36 @@ export type RunnerPhase = (typeof PHASES)[number];
 export type RunnerTaskState = (typeof TASK_STATES)[number];
 export type RunnerEventKind = (typeof EVENTS)[number];
 
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
+  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+}
+
 export interface RunnerTask {
   id: string;
   kind: string | null;
@@ -30,10 +60,18 @@ export interface RunnerTool {
 }
 
 export interface RunnerEvent {
+  id?: string;
   at: number;
   kind: RunnerEventKind;
   tool: string | null;
+  toolUseId?: string;
   taskId: string | null;
+  code?: RunnerFailureCode;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
 }
 
 export interface RunnerActivity {
@@ -53,6 +91,8 @@ export interface RunnerActivity {
   tasks: RunnerTask[];
   events: RunnerEvent[];
   lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
 }
 
 const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -76,9 +116,30 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
+const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
-  return { at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId) };
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
 }
 
 function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
@@ -90,6 +151,15 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
   return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
 }
 
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
 export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
   if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
   return {
@@ -98,6 +168,6 @@ export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
     pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
     tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
     tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
-    lastError: typeof raw.lastError === 'string' ? raw.lastError.slice(0, 300) : null,
+    ...failureFields(raw),
   };
 }

package/runtime/node_modules/@metro-labs/daemon/src/agents/map.ts

@@ -16,6 +16,8 @@ export function setAgentMap(map: AgentMap, names: AgentNameMap): void {
   agentNames = names;
 }
 
+export const knownAgentIds = (): string[] => Object.keys(agentNames);
+
 export function setAllowlistMap(map: AllowlistMap): void {
   allowlistMap = map;
 }

package/runtime/node_modules/@metro-labs/daemon/src/claude/session-continuity.ts

@@ -18,12 +18,21 @@ function sdkSavedSession(home: string): Record<string, unknown> | null {
   }
 }
 
+const inputState = (value: unknown): boolean => value === undefined || value === 'queued' || value === 'started';
+
+function sdkInput(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return typeof value.text === 'string' && typeof value.at === 'number' && Number.isFinite(value.at) && (value.uuid === undefined || sessionId(value.uuid) !== null) && inputState(value.state);
+}
+
+const sdkInputs = (value: unknown): value is unknown[] | undefined => value === undefined || (Array.isArray(value) && value.every(sdkInput));
+
 export function sdkPending(home: string): number | null {
   const state = sdkSavedSession(home);
   if (state === null) return null;
   if (state.sessionId !== undefined && state.sessionId !== null && sessionId(state.sessionId) === null) return null;
-  if (state.unanswered === undefined) return 0;
-  return Array.isArray(state.unanswered) ? state.unanswered.length : null;
+  if (!sdkInputs(state.unanswered) || !sdkInputs(state.interrupted)) return null;
+  return state.unanswered?.length ?? 0;
 }
 
 function projectFolder(home: string, dir: string): string {

package/runtime/node_modules/@metro-labs/daemon/src/monitor/run-event.ts

@@ -0,0 +1,139 @@
+import { classifyEvent, userSelf, type BufferedEvent, type MetroEvent, type RunEvent, type RunEventMetadata } from '@metro-labs/core/events';
+import { isRecord } from '@metro-labs/core/is-record';
+import { Line } from '@metro-labs/core/lines';
+import { STATIONS } from '@metro-labs/core/station-names';
+import { accountFromLine, allowlistForLine, lineReceives, senderPermitted } from '../agents/map.js';
+import { eventInScope } from '../agents/scope.js';
+
+const TEXT_MAX = 8_000;
+const FIELD_MAX = 512;
+const LINE_MAX = 2_048;
+const ACCOUNT_STATIONS = new Set<string>(STATIONS);
+const KINDS = new Set(['msg', 'reply', 'react', 'edit', 'delete', 'system']);
+
+function safeText(value: unknown, max: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  return value.slice(0, max).replace(/https?:\/\/[^\s<>"']+|\/(?:attach|api\/uploads|api\/webhooks|api\/threema)\/[^\s<>"']*/gi, (url) => /\/(?:attach|api\/uploads|api\/webhooks|api\/threema)\//i.test(url) ? '[private link]' : url).slice(0, max);
+}
+
+function validLine(line: string): boolean {
+  return typeof line === 'string' && line.length <= LINE_MAX && /^metro:\/\/[a-z][a-z0-9-]*\/[^\s?#]+$/.test(line) && !line.includes('//', 8) && !line.endsWith('/');
+}
+
+const isSelf = (line: string): boolean => line === userSelf();
+const isSynthetic = (payload: unknown): boolean => isRecord(payload) && (payload.contentType === 'attachmentSaved' || payload.contentType === 'attachmentFailed' || payload.contentType === 'transcript');
+
+function sameAccount(line: string, other: string): boolean {
+  if (!validLine(other)) return false;
+  const a = accountFromLine(line);
+  const b = accountFromLine(other);
+  return a !== undefined && b !== undefined && a.station === b.station && a.accountId === b.accountId;
+}
+
+function permittedTraffic(event: MetroEvent): boolean {
+  if (!isSelf(event.to) && !sameAccount(event.line, event.to)) return false;
+  const allowlist = allowlistForLine(event.line);
+  if (isSelf(event.from)) return !isSynthetic(event.payload) || senderPermitted(allowlist, '');
+  return sameAccount(event.line, event.from) && senderPermitted(allowlist, event.from, event.senderVerified);
+}
+
+function visible(event: MetroEvent, allowed: Set<string>): boolean {
+  if (!validLine(event.line) || !eventInScope(allowed, event.line) || !lineReceives(event.line)) return false;
+  const station = Line.station(event.line);
+  if (station !== event.station) return false;
+  if (!ACCOUNT_STATIONS.has(station)) return station === 'claude' && event.event?.type === 'system' && event.isPrivate !== true;
+  return permittedTraffic(event);
+}
+
+function attachmentType(value: unknown): 'image' | 'video' | 'audio' | 'file' {
+  if (!isRecord(value)) return 'file';
+  const mime = typeof value.mime === 'string' ? value.mime : value.contentType;
+  for (const kind of ['image', 'video', 'audio'] as const) {
+    if (value.kind === kind || (typeof mime === 'string' && mime.startsWith(`${kind}/`))) return kind;
+  }
+  return 'file';
+}
+
+function attachmentMetadata(payload: unknown): RunEventMetadata {
+  if (!isRecord(payload)) return {};
+  const saved = payload.contentType === 'attachmentSaved';
+  const failed = payload.contentType === 'attachmentFailed';
+  if (saved || failed) return {
+    attachmentCount: 1,
+    attachmentTypes: [attachmentType(payload)],
+    attachmentStatus: saved ? 'saved' : 'failed',
+    attachmentFor: safeText(payload.attachmentFor, FIELD_MAX),
+  };
+  if (!Array.isArray(payload.attachments) || payload.attachments.length === 0) return {};
+  return {
+    attachmentCount: payload.attachments.length,
+    attachmentTypes: [...new Set(payload.attachments.slice(0, 100).map(attachmentType))],
+  };
+}
+
+function reactionMetadata(event: MetroEvent): RunEventMetadata {
+  if (event.event?.type !== 'react') return {};
+  return {
+    emoji: safeText(event.event.emoji, 32),
+    ...(isRecord(event.payload) && typeof event.payload.removed === 'boolean' ? { removed: event.payload.removed } : {}),
+  };
+}
+
+function metadata(event: MetroEvent, system: boolean): RunEventMetadata {
+  const attachments = attachmentMetadata(event.payload);
+  if (system) return attachments;
+  const structured = event.event;
+  return {
+    ...attachments,
+    ...(typeof event.isPrivate === 'boolean' ? { isPrivate: event.isPrivate } : {}),
+    ...(typeof event.senderVerified === 'boolean' ? { senderVerified: event.senderVerified } : {}),
+    ...(typeof event.mentionsSelf === 'boolean' ? { mentionsSelf: event.mentionsSelf } : {}),
+    ...(typeof event.replyToSelf === 'boolean' ? { replyToSelf: event.replyToSelf } : {}),
+    ...reactionMetadata(event),
+    ...(structured !== undefined && 'targetId' in structured ? { targetId: safeText(structured.targetId, FIELD_MAX) } : {}),
+  };
+}
+
+function messageFields(event: MetroEvent, system: boolean): Partial<RunEvent> & { truncated: boolean } {
+  if (system) return { truncated: false };
+  return {
+    lineName: safeText(event.lineName, FIELD_MAX),
+    from: safeText(event.from, LINE_MAX),
+    fromName: safeText(event.fromName, FIELD_MAX),
+    fromDisplayName: safeText(event.fromDisplayName, FIELD_MAX),
+    to: safeText(event.to, LINE_MAX),
+    text: safeText(event.text, TEXT_MAX),
+    truncated: typeof event.text === 'string' && event.text.length > TEXT_MAX,
+  };
+}
+
+function validIdentity(event: MetroEvent): boolean {
+  return typeof event.id === 'string' && event.id.length <= FIELD_MAX
+    && typeof event.ts === 'string' && event.ts.length <= 64 && Number.isFinite(Date.parse(event.ts));
+}
+
+const replyId = (event: MetroEvent): string | undefined => event.replyTo ?? (event.event?.type === 'reply' ? event.event.replyTo : undefined);
+const accountId = (event: MetroEvent): string | null => ACCOUNT_STATIONS.has(event.station) ? accountFromLine(event.line)?.accountId ?? null : null;
+
+export function runEvent(entry: BufferedEvent, agentId: string): RunEvent | null {
+  const { event, busSeq } = entry;
+  if (!visible(event, new Set([agentId])) || !validIdentity(event)) return null;
+  const structured = event.event ?? classifyEvent(event);
+  if (!KINDS.has(structured.type)) return null;
+  const system = structured.type === 'system' || isSynthetic(event.payload);
+  return {
+    ...messageFields(event, system),
+    id: safeText(event.id, FIELD_MAX) ?? '',
+    seq: busSeq,
+    ts: new Date(event.ts).toISOString(),
+    kind: system ? 'system' : structured.type,
+    direction: system ? 'system' : isSelf(event.from) ? 'outbound' : 'inbound',
+    agentId,
+    station: event.station,
+    accountId: accountId(event),
+    line: event.line,
+    messageId: safeText(event.messageId, FIELD_MAX),
+    replyTo: safeText(replyId(event), FIELD_MAX),
+    metadata: metadata(event, system),
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/monitor/run-events.ts

@@ -0,0 +1,101 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { bufferedSince, BUS_BUFFER_MAX, currentBusSeq, type BufferedEvent, type RunEvent, type RunEventsPage } from '@metro-labs/core/events';
+import { ID_RE } from '@metro-labs/core/ids';
+import { ApiError } from '@metro-labs/http/api-error';
+import { sessionRoute } from '@metro-labs/http/api-http';
+import { accountEnabled, allowlistForAccount, knownAccounts, knownAgentIds } from '../agents/map.js';
+import { runEvent } from './run-event.js';
+
+const EPOCH = randomUUID();
+const DEFAULT_LIMIT = 100;
+const PAGE_BYTES_MAX = 1_000_000;
+const CURSOR_RE = /^([a-f0-9-]{36}):([a-f0-9]{64}):(0|[1-9]\d{0,15})$/;
+
+interface Cursor { epoch: string; policy: string; seq: number }
+interface Query { agentId: string; limit: number; cursor: Cursor | null }
+
+function cursorOf(raw: string | null): Cursor | null {
+  if (raw === null) return null;
+  const match = CURSOR_RE.exec(raw);
+  if (!match || !Number.isSafeInteger(Number(match[3]))) throw new ApiError('invalid run events cursor', 400);
+  return { epoch: match[1] ?? '', policy: match[2] ?? '', seq: Number(match[3]) };
+}
+
+function limitOf(raw: string | null): number {
+  if (raw === null) return DEFAULT_LIMIT;
+  const limit = Number(raw);
+  if (!/^[1-9]\d{0,2}$/.test(raw) || limit > BUS_BUFFER_MAX) throw new ApiError('limit must be between 1 and 500', 400);
+  return limit;
+}
+
+function queryOf(url: string): Query {
+  const params = new URL(url, 'http://localhost').searchParams;
+  for (const key of params.keys()) {
+    if (!['agent', 'limit', 'cursor'].includes(key) || params.getAll(key).length !== 1) throw new ApiError('invalid run events query', 400);
+  }
+  const agentId = params.get('agent') ?? '';
+  if (!ID_RE.test(agentId)) throw new ApiError('agent must be an agent id', 400);
+  return { agentId, limit: limitOf(params.get('limit')), cursor: cursorOf(params.get('cursor')) };
+}
+
+function policyOf(agentId: string, owner: string): string {
+  const accounts = knownAccounts().filter((account) => account.agentId === agentId).map(({ station, id }) => [
+    station, id, accountEnabled(station, id), allowlistForAccount(station, id) ?? [],
+  ]);
+  return createHash('sha256').update(JSON.stringify([owner, agentId, accounts])).digest('hex');
+}
+
+function bounded(events: RunEvent[], limit: number): RunEvent[] {
+  const rows: RunEvent[] = [];
+  let bytes = 0;
+  for (const event of events.slice(0, limit)) {
+    bytes += Buffer.byteLength(JSON.stringify(event)) + 1;
+    if (bytes > PAGE_BYTES_MAX) break;
+    rows.push(event);
+  }
+  return rows;
+}
+
+function resetNeeded(cursor: Cursor | null, policy: string, oldest: number, newest: number): boolean {
+  return cursor === null || cursor.epoch !== EPOCH || cursor.policy !== policy || cursor.seq < oldest - 1 || cursor.seq > newest;
+}
+
+function page(query: Query, owner: string): RunEventsPage {
+  const { agentId, limit, cursor } = query;
+  if (!knownAgentIds().includes(agentId)) throw new ApiError('no such agent', 404);
+  const policy = policyOf(agentId, owner);
+  const buffered = bufferedSince(0);
+  const newest = currentBusSeq();
+  const oldest = buffered[0]?.busSeq ?? newest + 1;
+  const reset = resetNeeded(cursor, policy, oldest, newest);
+  const visible = buffered.filter((entry) => reset || entry.busSeq > (cursor?.seq ?? newest)).flatMap((entry) => {
+    const event = runEvent(entry, agentId);
+    return event === null ? [] : [event];
+  });
+  const pending = reset ? visible.slice(-limit) : visible;
+  const events = bounded(pending, limit);
+  const hasMore = pending.length > events.length;
+  return {
+    events, cursor: `${EPOCH}:${policy}:${pageSeq(events, hasMore, newest)}`, hasMore, reset,
+    retention: retention(buffered, agentId),
+  };
+}
+
+const pageSeq = (events: RunEvent[], hasMore: boolean, newest: number): number => hasMore ? events.at(-1)?.seq ?? newest : newest;
+function retention(buffered: BufferedEvent[], agentId: string): RunEventsPage['retention'] {
+  let oldestAt: string | null = null;
+  for (const entry of buffered) {
+    const event = runEvent(entry, agentId);
+    if (event === null) continue;
+    oldestAt = event.ts;
+    break;
+  }
+  return { capacity: BUS_BUFFER_MAX, oldestAt, oldestSeq: buffered[0]?.busSeq ?? null };
+}
+
+export function handleRunEventsRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, {
+    methods: { '/api/run/events': ['GET'] }, admin: false, label: 'run-events',
+  }, (session) => Promise.resolve(page(queryOf(req.url ?? ''), session.subject)));
+}

package/runtime/node_modules/@metro-labs/daemon/src/routes/session-apis.ts

@@ -22,6 +22,7 @@ import { handleSchedulesRequest } from '../agent-user/schedules-api.js';
 import { handleFilesRequest } from '../agent-user/files-api.js';
 import { handleVaultRequest } from '../vault/api.js';
 import { handleVoiceRequest } from '../voice/api.js';
+import { handleRunEventsRequest } from '../monitor/run-events.js';
 
 export interface SessionApis {
   agentApi?: AgentApiDeps;
@@ -50,6 +51,7 @@ export function handleSessionApis(
 ): boolean {
   const routes: (() => boolean)[] = [
     () => handleSessionApiRequest(req, res),
+    () => handleRunEventsRequest(req, res),
     () => handleApprovalsRequest(req, res),
     ...when(apis.connectorTransfers, (d) => d.handle(req, res)),
     ...when(apis.connectorApi, (d) => handleConnectorApiRequest(req, res, d)),

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.261"
+  "version": "0.1.0-beta.263"
 }

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

@@ -85,7 +85,51 @@ export interface BufferedEvent {
   event: MetroEvent;
 }
 
-const BUS_BUFFER_MAX = 500;
+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[] = [];

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

@@ -7,6 +7,36 @@ export type RunnerPhase = (typeof PHASES)[number];
 export type RunnerTaskState = (typeof TASK_STATES)[number];
 export type RunnerEventKind = (typeof EVENTS)[number];
 
+const FAILURE = {
+  authentication: 'The provider refused authentication. Check the Model page.',
+  billing: 'The provider refused billing. Check the Model page.',
+  rate_limit: 'The provider rate limit was reached. Retry later or check the Model page.',
+  provider_unavailable: 'The provider is unavailable. Retry later or check the Model page.',
+  invalid_request: 'The provider rejected the request. Check Conversations and the Model page.',
+  output_limit: 'The model reached its output token limit. Check Conversations.',
+  provider_error: 'SDK turn failed (provider_error). Check Conversations and the Model page.',
+  error_during_execution: 'SDK turn failed (error_during_execution). Check Conversations and the Model page.',
+  error_max_turns: 'SDK turn failed (error_max_turns). Check Conversations and the Model page.',
+  error_max_budget_usd: 'SDK turn failed (error_max_budget_usd). Check Conversations and the Model page.',
+  error_max_structured_output_retries: 'SDK turn failed (error_max_structured_output_retries). Check Conversations and the Model page.',
+  read_token_limit: 'Read exceeded its token limit. Read a smaller range with offset and limit, or search the file.',
+  tool_error: 'A tool failed. See its result in Conversations.',
+  task_error: 'A background task failed. See Conversations and Terminal.',
+  compact_error: 'Conversation compaction failed.',
+  status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
+  saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
+  executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  connection: 'The SDK connection failed. Check the server and provider connection.',
+  session_ended: 'The Agent SDK session ended unexpectedly.',
+  interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
+  session_error: 'The Agent SDK session failed. Check Terminal and the Model page.',
+} as const;
+export type RunnerFailureCode = keyof typeof FAILURE;
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
+  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+}
+
 export interface RunnerTask {
   id: string;
   kind: string | null;
@@ -30,10 +60,18 @@ export interface RunnerTool {
 }
 
 export interface RunnerEvent {
+  id?: string;
   at: number;
   kind: RunnerEventKind;
   tool: string | null;
+  toolUseId?: string;
   taskId: string | null;
+  code?: RunnerFailureCode;
+}
+
+export interface RunnerFailure extends RunnerEvent {
+  id: string;
+  code: RunnerFailureCode;
 }
 
 export interface RunnerActivity {
@@ -53,6 +91,8 @@ export interface RunnerActivity {
   tasks: RunnerTask[];
   events: RunnerEvent[];
   lastError: string | null;
+  activeFailure?: RunnerFailure | null;
+  lastFailure?: RunnerFailure | null;
 }
 
 const count = (value: unknown): number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -76,9 +116,30 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
+const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
+
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
-  return { at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId) };
+  return {
+    at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
+    ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
+    ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
+    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+  };
+}
+
+function failure(raw: unknown): RunnerFailure | null {
+  const parsed = event(raw);
+  return parsed?.id !== undefined && parsed.code !== undefined ? { ...parsed, id: parsed.id, code: parsed.code } : null;
+}
+
+function safeError(raw: unknown): string | null {
+  if (typeof raw !== 'string' || raw.length === 0) return null;
+  const known = Object.values(FAILURE).find((text) => text === raw);
+  if (known !== undefined) return known;
+  const tool = /^([A-Za-z0-9_.:-]{1,128}) failed\. See its result in Conversations\.$/.exec(raw)?.[1];
+  return tool === undefined ? FAILURE.session_error : runnerFailureSummary('tool_error', tool);
 }
 
 function list<T>(raw: unknown, parse: (item: unknown) => T | null, max: number): T[] {
@@ -90,6 +151,15 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
   return typeof value === 'string' && /^\d{1,32}$/.test(value) ? { procStart: value } : {};
 }
 
+function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
+  const activeFailure = failure(raw.activeFailure);
+  return {
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
+    ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
+  };
+}
+
 export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
   if (!isRecord(raw) || raw.runner !== 'sdk' || !phase(raw.phase) || count(raw.pid) === 0 || count(raw.updatedAt) === 0) return null;
   return {
@@ -98,6 +168,6 @@ export function parseRunnerActivity(raw: unknown): RunnerActivity | null {
     pending: count(raw.pending), workers: count(raw.workers), approvals: count(raw.approvals),
     tools: list(raw.tools, name, 20), activeTools: list(raw.activeTools, tool, 20),
     tasks: list(raw.tasks, task, 30), events: list(raw.events, event, 40),
-    lastError: typeof raw.lastError === 'string' ? raw.lastError.slice(0, 300) : null,
+    ...failureFields(raw),
   };
 }