@stage-labs/metro 0.1.0-beta.293 → 0.1.0-beta.295

package/runtime/node_modules/@metro-labs/http/src/connector-policy.ts

@@ -2,15 +2,24 @@ import { isRecord } from '@metro-labs/core/is-record';
 
 export type ConnectorDecision = 'allow' | 'ask' | 'deny';
 
+type ToolGroup = 'read' | 'write';
+
 export interface ConnectorPolicy {
   read?: ConnectorDecision;
   write?: ConnectorDecision;
   tools?: Record<string, ConnectorDecision>;
 }
 
+export interface ConnectorPolicyLayers {
+  organization: ConnectorPolicy;
+  agent: ConnectorPolicy;
+}
+
 const RANK: Record<ConnectorDecision, number> = { allow: 0, ask: 1, deny: 2 };
 const TOOL_RE = /^[A-Za-z0-9_.:/-]{1,256}$/;
 
+export const validConnectorToolName = (name: string): boolean => TOOL_RE.test(name) && !['__proto__', 'constructor', 'prototype'].includes(name);
+
 const decision = (value: unknown): value is ConnectorDecision => value === 'allow' || value === 'ask' || value === 'deny';
 
 export function connectorPolicyOf(value: unknown): ConnectorPolicy {
@@ -30,15 +39,23 @@ function toolPolicyOf(value: unknown): Record<string, ConnectorDecision> {
   if (!isRecord(value) || Object.keys(value).length > 2000) throw new Error('Invalid connector policy.');
   const out: Record<string, ConnectorDecision> = {};
   for (const [name, rule] of Object.entries(value)) {
-    if (!TOOL_RE.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name) || !decision(rule)) throw new Error('Invalid connector policy.');
+    if (!validConnectorToolName(name) || !decision(rule)) throw new Error('Invalid connector policy.');
     out[name] = rule;
   }
   return out;
 }
 
+export function connectorPolicyLayersOf(value: unknown): ConnectorPolicyLayers {
+  if (!isRecord(value) || Object.keys(value).some((key) => !['organization', 'agent'].includes(key))) throw new Error('Invalid connector policy layers.');
+  return { organization: connectorPolicyOf(value.organization), agent: connectorPolicyOf(value.agent) };
+}
+
 const strictest = (...values: (ConnectorDecision | undefined)[]): ConnectorDecision => values.reduce<ConnectorDecision>((held, next) => next !== undefined && RANK[next] > RANK[held] ? next : held, 'allow');
+const toolRule = (policy: ConnectorPolicy, name: string): ConnectorDecision | undefined => policy.tools !== undefined && Object.hasOwn(policy.tools, name) ? policy.tools[name] : undefined;
+const toolGroup = (groups: Record<string, ToolGroup>, name: string): ToolGroup => Object.hasOwn(groups, name) && groups[name] === 'read' ? 'read' : 'write';
+const access = (policy: ConnectorPolicy, name: string, group: ToolGroup): ConnectorDecision => toolRule(policy, name) ?? policy[group] ?? 'allow';
 
-export function combineConnectorPolicies(global: ConnectorPolicy, assignment: ConnectorPolicy): ConnectorPolicy {
+export function combineConnectorPolicies(global: ConnectorPolicy, assignment: ConnectorPolicy, groups?: Record<string, ToolGroup>): ConnectorPolicy {
   const policies = [connectorPolicyOf(global), connectorPolicyOf(assignment)];
   const neutral = (policy: ConnectorPolicy): boolean => (policy.read ?? 'allow') === 'allow' && (policy.write ?? 'allow') === 'allow' && Object.keys(policy.tools ?? {}).length === 0;
   if (neutral(assignment)) return connectorPolicyOf(global);
@@ -48,9 +65,28 @@ export function combineConnectorPolicies(global: ConnectorPolicy, assignment: Co
     write: strictest(...policies.map((policy) => policy.write)),
   };
   const names = new Set(policies.flatMap((policy) => Object.keys(policy.tools ?? {})));
+  if (groups === undefined && names.size > 2000) return { read: 'deny', write: 'deny' };
   if (names.size > 0) {
     out.tools = {};
-    for (const name of names) out.tools[name] = strictest(...policies.flatMap((policy) => [policy.read, policy.write, policy.tools?.[name]]));
+    for (const name of names) {
+      out.tools[name] = groups === undefined
+        ? strictest(...policies.flatMap((policy) => [policy.read, policy.write, toolRule(policy, name)]))
+        : strictest(...policies.map((policy) => access(policy, name, toolGroup(groups, name))));
+    }
   }
   return out;
 }
+
+export function effectiveConnectorPolicy(row: { policy: ConnectorPolicy; policyLayers?: ConnectorPolicyLayers }, groups: Record<string, ToolGroup>): ConnectorPolicy {
+  const layers = row.policyLayers;
+  return layers === undefined ? connectorPolicyOf(row.policy) : combineConnectorPolicies(layers.organization, layers.agent, groups);
+}
+
+export function connectorPoliciesBlocked(layers: ConnectorPolicyLayers): boolean {
+  const policies = [layers.organization, layers.agent];
+  const names = new Set(policies.flatMap((policy) => Object.keys(policy.tools ?? {})));
+  return (['read', 'write'] as const).every((group) =>
+    strictest(...policies.map((policy) => policy[group])) === 'deny' &&
+    [...names].every((name) => strictest(...policies.map((policy) => access(policy, name, group))) === 'deny'),
+  );
+}

package/runtime/node_modules/@metro-labs/http/src/connector-tools.ts

@@ -0,0 +1,94 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authHeaders, INITIALIZE, mcpPost, payloadOf, type ConnectorAuth } from './connector-mcp.js';
+import { ConnectorUnauthorized, refused } from './connector-url.js';
+
+export interface RemoteTool {
+  name: string;
+  title: string;
+  description: string;
+  readOnly: boolean;
+}
+
+const TIMEOUT_MS = 15_000;
+const MAX_PAGES = 100;
+const MAX_TOOLS = 2000;
+
+function resultOf(text: string, contentType: string): Record<string, unknown> | null {
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+}
+
+async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown, fetchImpl?: FetchLike): Promise<Record<string, unknown> | null> {
+  const res = await mcpPost(url, auth, body, { timeoutMs: TIMEOUT_MS, headers: Object.fromEntries(session), fetch: fetchImpl });
+  const id = res.headers.get('mcp-session-id');
+  if (id !== null && id !== '') session.set('mcp-session-id', id);
+  const text = await res.text().catch(() => '');
+  if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorized(`${url.hostname} rejected the credential; connect it again`, 400);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)}`);
+  return resultOf(text, res.headers.get('content-type') ?? '');
+}
+
+function toTool(raw: unknown): RemoteTool | null {
+  if (!isRecord(raw) || typeof raw.name !== 'string') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : {};
+  const title = typeof raw.title === 'string' && raw.title !== '' ? raw.title : raw.name;
+  return { name: raw.name, title, description: typeof raw.description === 'string' ? raw.description : '', readOnly: annotations.readOnlyHint === true };
+}
+
+async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<void> {
+  if (!session.has('mcp-session-id')) return;
+  try {
+    const send = fetchImpl ?? fetch;
+    const res = await send(url.toString(), { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
+    if (res.ok) await res.body?.pipeTo(new WritableStream<Uint8Array>());
+    else await res.body?.cancel();
+  } catch (err) {
+    log.debug(fetchImpl === undefined ? { host: url.hostname, err: errMsg(err) } : {}, 'connector-tools: the remote declined to end the session');
+  }
+}
+
+function addTools(result: Record<string, unknown> | null, tools: Map<string, RemoteTool>): unknown {
+  if (result === null || !Array.isArray(result.tools)) throw refused('The provider did not return a complete tool list.');
+  for (const raw of result.tools) {
+    const tool = toTool(raw);
+    if (tool === null || tools.has(tool.name)) throw refused('The provider returned an invalid tool list.');
+    tools.set(tool.name, tool);
+    if (tools.size > MAX_TOOLS) throw refused('The provider returned too many tools.');
+  }
+  return result.nextCursor;
+}
+
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const tools = new Map<string, RemoteTool>();
+  const cursors = new Set<string>();
+  let cursor = '';
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } }, fetchImpl);
+    const next = addTools(result, tools);
+    if (next === undefined || next === null || next === '') return [...tools.values()];
+    if (typeof next !== 'string' || cursors.has(next)) throw refused('The provider did not return a complete tool list.');
+    cursors.add(next);
+    cursor = next;
+  }
+  throw refused('The provider did not return a complete tool list.');
+}
+
+export async function listRemoteTools(url: URL, auth: ConnectorAuth, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const session = new Map<string, string>();
+  try {
+    const init = await rpc(url, auth, session, INITIALIZE, fetchImpl);
+    if (init === null || typeof init.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+    session.set('mcp-protocol-version', init.protocolVersion);
+    await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' }, fetchImpl);
+    return await walkTools(url, auth, session, fetchImpl);
+  } finally {
+    await endSession(url, auth, session, fetchImpl);
+  }
+}

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.293"
+  "version": "0.1.0-beta.295"
 }

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

@@ -26,6 +26,9 @@ const FAILURE = {
   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.',
+  module: 'The SDK runtime could not load a required module. Prepare the SDK runtime again.',
+  configuration: 'The SDK launch configuration is missing or invalid. Check Harness and the Model page before starting.',
+  process_exit: 'The SDK process exited unexpectedly. Check its reported exit code or signal before retrying.',
   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.',
@@ -33,8 +36,40 @@ const FAILURE = {
 } 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];
+const ERROR_CODES = ['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC', 'ENOMEM', 'ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ERR_DLOPEN_FAILED', 'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'] as const;
+const SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGINT', 'SIGHUP', 'SIGPIPE'] as const;
+
+export interface RunnerDiagnostic {
+  source: 'exception' | 'stderr';
+  errorCode?: (typeof ERROR_CODES)[number];
+  httpStatus?: number;
+  exitCode?: number;
+  signal?: (typeof SIGNALS)[number];
+}
+
+const boundedNumber = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : undefined;
+
+export function runnerDiagnostic(raw: unknown): RunnerDiagnostic | undefined {
+  if (!isRecord(raw) || (raw.source !== 'exception' && raw.source !== 'stderr')) return undefined;
+  const errorCode = ERROR_CODES.find((code) => code === raw.errorCode);
+  const signal = SIGNALS.find((value) => value === raw.signal);
+  const httpStatus = boundedNumber(raw.httpStatus, 400, 599);
+  const exitCode = boundedNumber(raw.exitCode, 0, 255);
+  return {
+    source: raw.source,
+    ...(errorCode === undefined ? {} : { errorCode }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null, diagnostic?: RunnerDiagnostic): string {
+  const summary = code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+  const safe = runnerDiagnostic(diagnostic);
+  if (safe === undefined) return summary;
+  const details = [safe.errorCode, safe.httpStatus === undefined ? null : `HTTP ${safe.httpStatus}`, safe.exitCode === undefined ? null : `exit ${safe.exitCode}`, safe.signal].filter((value) => value !== undefined && value !== null);
+  return details.length === 0 ? summary : `${summary} Observed: ${details.join(', ')} (${safe.source === 'stderr' ? 'startup stderr' : 'exception'}).`;
 }
 
 export interface RunnerTask {
@@ -70,6 +105,7 @@ export interface RunnerEvent {
   toolUseId?: string;
   taskId: string | null;
   code?: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
 }
 
 export interface RunnerFailure extends RunnerEvent {
@@ -146,16 +182,17 @@ 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);
+export const runnerFailureCode = (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;
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
   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 } : {}),
+    ...(failureKind(raw.kind) && runnerFailureCode(raw.code) ? { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) } : {}),
   };
 }
 
@@ -184,7 +221,7 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
 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),
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool, activeFailure.diagnostic) : safeError(raw.lastError),
     ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
     ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
   };

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.293",
+  "version": "0.1.0-beta.295",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/runtime/sdk-runner/src/activity.ts

@@ -3,11 +3,13 @@ import { readFileSync } from 'node:fs';
 import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import { isRecord } from '@metro-labs/core/is-record';
 import { log } from '@metro-labs/core/log';
-import { runnerFailureSummary, type RunnerActivity, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, type RunnerPhase, type RunnerTool } from '@metro-labs/core/runner-activity';
+import { runnerFailureSummary, type RunnerActivity, type RunnerDiagnostic, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, type RunnerPhase, type RunnerTool } from '@metro-labs/core/runner-activity';
 import { writeAtomic } from '@metro-labs/core/secure-fs';
 import { ActivityTasks, activityName } from './activity-tasks.js';
 import type { ApprovalAsk } from './approvals.js';
 import type { SavedTask } from './task-state.js';
+import { sessionFailure } from './errors.js';
+export { failureSummary } from './errors.js';
 
 const HEARTBEAT_MS = 5_000;
 const MAX_TRACKED = 200;
@@ -18,19 +20,10 @@ type System = Extract<SDKMessage, { type: 'system' }>;
 interface TrackedTool extends RunnerTool { parent: string | null }
 interface Approval { tool: string | null; taskId: string | null; worker: boolean }
 
-function sessionFailureCode(err: unknown): RunnerFailureCode {
-  const text = err instanceof Error ? err.message : String(err);
-  for (const code of ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection'] as const)
-    if (text === runnerFailureSummary(code)) return code;
-  if (/saved Agent SDK state/i.test(text)) return 'saved_state';
-  if (/unauthorized|authentication|invalid.*key|\b40[13]\b/i.test(text)) return 'authentication';
-  if (/ENOENT|not found|executable|spawn/i.test(text)) return 'executable';
-  if (/ECONN|network|fetch failed|timed? ?out/i.test(text)) return 'connection';
-  return 'session_error';
+function copyEvent<T extends RunnerEvent>(event: T): T {
+  return { ...event, ...(event.diagnostic === undefined ? {} : { diagnostic: { ...event.diagnostic } }) };
 }
 
-export function failureSummary(err: unknown): string { return runnerFailureSummary(sessionFailureCode(err)); }
-
 const PROVIDER_ERRORS: Record<NonNullable<Extract<SDKMessage, { type: 'assistant' }>['error']>, RunnerFailureCode> = {
   authentication_failed: 'authentication', oauth_org_not_allowed: 'authentication', cloud_credential_error: 'authentication', account_on_hold: 'authentication', verification_required: 'authentication',
   billing_error: 'billing', rate_limit: 'rate_limit', overloaded: 'provider_unavailable', server_error: 'provider_unavailable',
@@ -94,9 +87,9 @@ export class Activity {
     const s = this.state;
     return {
       ...s, tools: [...s.tools], activeTools: s.activeTools.map((tool) => ({ ...tool })),
-      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map((event) => ({ ...event })),
+      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map(copyEvent),
       ...(s.inputs === undefined ? {} : { inputs: s.inputs.map((input) => ({ ...input })) }),
-      activeFailure: s.activeFailure ? { ...s.activeFailure } : null, lastFailure: s.lastFailure ? { ...s.lastFailure } : null,
+      activeFailure: s.activeFailure ? copyEvent(s.activeFailure) : null, lastFailure: s.lastFailure ? copyEvent(s.lastFailure) : null,
     };
   }
 
@@ -154,13 +147,14 @@ export class Activity {
     this.update();
   }
 
-  fail(message: string): void {
+  fail(err: unknown): void {
     this.failed = true;
-    const failure = this.failure('session_failed', sessionFailureCode(message), true);
+    const safe = sessionFailure(err);
+    const failure = this.failure('session_failed', safe.code, true, null, null, {}, safe.diagnostic);
     if (failure.code === 'interrupted') this.interrupted = failure;
     this.state.phase = 'error';
     this.state.mainPhase = 'error';
-    log.error({ reason: failure.code }, 'sdk-runner: activity error');
+    log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: this.state.lastError }, 'sdk-runner: activity error');
     this.flush();
   }
 
@@ -335,12 +329,12 @@ export class Activity {
     this.state.lastError = this.interrupted === null ? null : runnerFailureSummary(this.interrupted.code);
   }
 
-  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}): RunnerFailure {
-    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }) };
+  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}, diagnostic?: RunnerDiagnostic): RunnerFailure {
+    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }), ...(diagnostic === undefined ? {} : { diagnostic }) };
     this.state.lastFailure = failure;
     if (active) {
       this.state.activeFailure = failure;
-      this.state.lastError = runnerFailureSummary(code, tool);
+      this.state.lastError = runnerFailureSummary(code, tool, diagnostic);
     }
     this.record(failure);
     return failure;

package/runtime/sdk-runner/src/app.ts

@@ -4,7 +4,7 @@ import { AutomationStore } from '@metro-labs/core/automation-store';
 import { errMsg, log } from '@metro-labs/core/log';
 import { skillSourceRoot } from '@metro-labs/core/skill-source';
 import { SkillsRefresh } from './skills.js';
-import { failureSummary, type Activity } from './activity.js';
+import type { Activity } from './activity.js';
 import { approvalsThrough } from './approvals.js';
 import type { RunnerConfig } from './config.js';
 import { MetroLink } from './link.js';
@@ -79,7 +79,7 @@ export async function startAgent(cfg: RunnerConfig, hooks: AppHooks): Promise<Ru
     hooks.activity?.start();
     return await connected(cfg, hooks, release);
   } catch (err) {
-    hooks.activity?.fail(failureSummary(err));
+    hooks.activity?.fail(err);
     hooks.activity?.stop();
     await release().catch(() => { log.warn('sdk-runner: releasing process ownership failed'); });
     throw err;

package/runtime/sdk-runner/src/errors.ts

@@ -0,0 +1,131 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { runnerDiagnostic, runnerFailureCode, runnerFailureSummary, type RunnerDiagnostic, type RunnerFailureCode } from '@metro-labs/core/runner-activity';
+
+const SCAN_MAX = 2_048;
+const ERROR_FAILURES: Record<NonNullable<RunnerDiagnostic['errorCode']>, RunnerFailureCode> = {
+  ENOENT: 'executable', EACCES: 'executable', EPERM: 'executable', ENOEXEC: 'executable', ENOMEM: 'executable',
+  ERR_MODULE_NOT_FOUND: 'module', MODULE_NOT_FOUND: 'module', ERR_DLOPEN_FAILED: 'module',
+  ECONNREFUSED: 'connection', ECONNRESET: 'connection', ENOTFOUND: 'connection', EAI_AGAIN: 'connection', ETIMEDOUT: 'connection',
+  CERT_HAS_EXPIRED: 'connection', UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'connection',
+};
+const KNOWN = ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection', 'module', 'configuration', 'process_exit', 'session_error'] as const;
+
+export interface SessionFailure {
+  code: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
+}
+
+function normalizeFailure(raw: unknown): SessionFailure {
+  if (!isRecord(raw) || !runnerFailureCode(raw.code)) return { code: 'session_error' };
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
+  return { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export class SessionError extends Error {
+  readonly failure: SessionFailure;
+
+  constructor(failure: SessionFailure) {
+    const safe = normalizeFailure(failure);
+    super(runnerFailureSummary(safe.code, null, safe.diagnostic));
+    this.failure = safe;
+  }
+}
+
+function statusFailure(status: number | undefined): RunnerFailureCode | null {
+  if (status === undefined) return null;
+  if (status === 401 || status === 403) return 'authentication';
+  if (status === 402) return 'billing';
+  if (status === 429) return 'rate_limit';
+  return status >= 500 ? 'provider_unavailable' : 'invalid_request';
+}
+
+const TEXT_FAILURES: [RunnerFailureCode, RegExp][] = [
+  ['authentication', /\bunauthorized\b|\bauthentication (?:failed|error)\b|\binvalid(?:[ -]api)?[ -]key\b/i],
+  ['module', /cannot find (?:module|package)|error (?:while )?loading shared libraries|module not found/i],
+  ['configuration', /METRO_(?:RUNNER_MCP_URL|AGENT_KEY) is not set|invalid (?:configuration|settings)|failed to parse (?:configuration|settings)|unknown (?:option|argument)/i],
+  ['executable', /executable|spawn|command not found/i],
+  ['connection', /network|fetch failed|timed? ?out/i],
+];
+
+function errorText(value: unknown): string {
+  if (typeof value === 'string') return value.slice(0, SCAN_MAX);
+  return isRecord(value) && typeof value.message === 'string' ? value.message.slice(0, SCAN_MAX) : '';
+}
+
+function evidence(raw: Record<string, unknown>, message: string, source: RunnerDiagnostic['source']): RunnerDiagnostic | undefined {
+  const errorCodes = message.match(/\b[A-Z][A-Z_]{2,40}\b/g) ?? [];
+  return runnerDiagnostic({
+    source, errorCode: raw.code ?? errorCodes.find((code) => Object.hasOwn(ERROR_FAILURES, code)),
+    httpStatus: raw.status ?? raw.statusCode ?? Number(/(?:^|\bHTTP(?:\/[12](?:\.\d)?)?\s+|\bstatus(?: code)?[:= ]+)([45]\d\d)\b/i.exec(message)?.[1]),
+    exitCode: raw.exitCode ?? Number(/^Claude Code process exited with code (\d{1,3})\b/.exec(message)?.[1]),
+    signal: raw.signal ?? /^Claude Code process terminated by signal (SIG[A-Z]{1,8})\b/.exec(message)?.[1],
+  });
+}
+
+function diagnosticCode(message: string, diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  if (/saved Agent SDK state/i.test(message)) return 'saved_state';
+  if (diagnostic?.errorCode !== undefined) return ERROR_FAILURES[diagnostic.errorCode];
+  return statusFailure(diagnostic?.httpStatus);
+}
+
+function processFailure(diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  return diagnostic?.exitCode !== undefined || diagnostic?.signal !== undefined ? 'process_exit' : null;
+}
+
+function classify(value: unknown, source: RunnerDiagnostic['source']): SessionFailure {
+  const message = errorText(value);
+  const known = KNOWN.find((code) => message === runnerFailureSummary(code));
+  if (known !== undefined) return { code: known };
+  const diagnostic = evidence(isRecord(value) ? value : {}, message, source);
+  const code = diagnosticCode(message, diagnostic) ?? TEXT_FAILURES.find(([, pattern]) => pattern.test(message))?.[0] ?? processFailure(diagnostic) ?? 'session_error';
+  return code === 'session_error' ? { code } : { code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export function sessionFailure(err: unknown): SessionFailure {
+  try {
+    if (err instanceof SessionError) return normalizeFailure(err.failure);
+    let current = err;
+    let result: SessionFailure = { code: 'session_error' };
+    for (let depth = 0; depth < 4; depth++) {
+      const next = classify(current, 'exception');
+      if (next.code !== 'session_error') result = next;
+      if (!isRecord(current) || current.cause === undefined) break;
+      current = current.cause;
+    }
+    return result;
+  } catch {
+    return { code: 'session_error' };
+  }
+}
+
+export const failureSummary = (err: unknown): string => {
+  const failure = sessionFailure(err);
+  return runnerFailureSummary(failure.code, null, failure.diagnostic);
+};
+
+export class StartupDiagnostics {
+  private tail = '';
+  private observed: SessionFailure | null = null;
+
+  stderr(text: string): void {
+    const head = text.slice(0, SCAN_MAX);
+    const candidates = [head, (this.tail + head).slice(-SCAN_MAX), text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : ''];
+    for (const candidate of candidates) {
+      const failure = classify(candidate, 'stderr');
+      if (failure.code !== 'session_error' && (failure.code !== 'process_exit' || this.observed === null)) this.observed = failure;
+    }
+    this.tail = (this.tail + (text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : text)).slice(-SCAN_MAX);
+  }
+
+  failure(err: unknown): SessionFailure {
+    const failure = sessionFailure(err);
+    const observed = this.observed;
+    if (observed === null || !['session_error', 'process_exit'].includes(failure.code)) return failure;
+    return { ...observed, diagnostic: runnerDiagnostic({ ...failure.diagnostic, ...observed.diagnostic }) };
+  }
+
+  clear(): void {
+    this.tail = '';
+    this.observed = null;
+  }
+}

package/runtime/sdk-runner/src/main.ts

@@ -3,6 +3,7 @@ import { log } from '@metro-labs/core/log';
 import { Activity, failureSummary } from './activity.js';
 import { startAgent, type RunningAgent } from './app.js';
 import { runnerConfig } from './config.js';
+import { sessionFailure } from './errors.js';
 
 let agent: RunningAgent | null = null;
 let starting: Promise<RunningAgent> | null = null;
@@ -45,9 +46,10 @@ try {
     await agent.done;
     if (!exiting) activity.fail('The Agent SDK session ended unexpectedly.');
   } catch (err) {
-    if (!exiting) activity.fail(failureSummary(err));
+    if (!exiting) activity.fail(err);
   }
 } catch (err) {
-  log.error({ reason: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
+  const failure = sessionFailure(err);
+  log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
 }
 await exit(1);

package/runtime/sdk-runner/src/runner.ts

@@ -18,6 +18,7 @@ import type { SessionStore } from './session-store.js';
 import { completedCommand, SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
 import { TaskRecovery } from './task-recovery.js';
 import { METRO_SERVER, type MetroTools } from './tool-proxy.js';
+import { failureSummary, SessionError, StartupDiagnostics } from './errors.js';
 
 const STARTUP_WAIT = 'CLAUDE_CODE_MCP_STARTUP_WAIT_MS';
 export const COMPACT_AT = 120_000;
@@ -53,9 +54,6 @@ export function runnerOptions(cfg: RunnerConfig, tools: MetroTools, canUseTool:
     includePartialMessages: true,
     extraArgs: { 'system-prompt-snapshot': 'off' },
     ...(resume === null ? {} : { resume }),
-    stderr: (text: string) => {
-      log.debug({ text: text.slice(0, 500) }, 'sdk-runner: claude stderr');
-    },
   };
 }
 
@@ -98,6 +96,7 @@ export class Runner {
   readonly automation: Automation | null;
   private readonly recovery: TaskRecovery;
   private readonly watch: SessionWatch;
+  private readonly diagnostics = new StartupDiagnostics();
   private readonly tasks = new ActivityTasks(() => undefined);
   private readonly skillWork = new SkillWork();
   private compactTimer: ReturnType<typeof setTimeout> | null = null;
@@ -149,7 +148,13 @@ export class Runner {
     if (this.session !== null) throw new Error('the runner was already started');
     if (options.resume === undefined) this.watch.restoreContext(0);
     else this.maybeCompact(true);
-    this.session = (this.parts.open ?? query)({ prompt: this.inbox, options });
+    try {
+      this.session = (this.parts.open ?? query)({ prompt: this.inbox, options: { ...options, stderr: (text) => { if (this.sessionId === null) this.diagnostics.stderr(text); } } });
+    } catch (err) {
+      const failure = this.diagnostics.failure(err);
+      this.diagnostics.clear();
+      throw new SessionError(failure);
+    }
     this.model = options.model ?? null;
     this.queueModel(this.model);
     this.parts.skills?.start({
@@ -185,15 +190,22 @@ export class Runner {
         this.maybeCompact();
         observe?.(message);
       }
+    } catch (err) {
+      throw new SessionError(this.diagnostics.failure(err));
     } finally {
-      this.cancelCompact();
-      this.parts.skills?.close();
-      this.automation?.close(false);
-      this.recovery.close(false);
-      this.ended = true;
+      this.finishRun();
     }
   }
 
+  private finishRun(): void {
+    this.diagnostics.clear();
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.automation?.close(false);
+    this.recovery.close(false);
+    this.ended = true;
+  }
+
   chat(event: ChannelEvent): Uuid {
     try {
       const uuid = this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
@@ -228,8 +240,9 @@ export class Runner {
     this.switching = this.switching
       .then(() => this.applyModel(model))
       .catch((err: unknown) => {
-        this.parts.activity?.fail('The SDK could not apply the selected model. Check the Model page.');
-        log.warn({ model, err: errMsg(err) }, 'sdk-runner: the session could not take the model the Model page picked');
+        const failure = new SessionError(this.diagnostics.failure(err));
+        this.parts.activity?.fail(failure);
+        log.warn({ reason: failure.failure.code, diagnostic: failure.failure.diagnostic, summary: failureSummary(failure) }, 'sdk-runner: the session could not take the model the Model page picked');
       });
   }
 
@@ -333,6 +346,7 @@ export class Runner {
     const id = typeof m.session_id === 'string' ? m.session_id : null;
     if (id === null || id === this.sessionId) return;
     this.sessionId = id;
+    this.diagnostics.clear();
     log.info({ session: id, model: m.model, claude: m.claude_code_version }, 'sdk-runner: session up');
     try {
       this.parts.store.save(id);