@humwick/runner 0.0.0-stage → 0.130.0

package/src/runner-exit.ts

@@ -0,0 +1,12 @@
+import { formatRunnerExitLine } from "@humwick/sdk";
+
+/**
+ * #2619 — the ONLY way the runner process exits. Every exit writes the structured exit record
+ * (code + cause) to stderr first: the orchestrator parses it back from the log tail, which
+ * outlives a garbage-collected systemd unit. A guard test forbids a direct process.exit anywhere
+ * else in the runner.
+ */
+export function exitRunner(code: number, reason?: string): never {
+  try { console.error(formatRunnerExitLine(code, reason)); } catch { /* best-effort: the exit must still happen */ }
+  process.exit(code);
+}

package/src/runner-helpers.ts

@@ -0,0 +1,582 @@
+import { walkErrorChain } from "./transport-errors";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import type { AgentProfile, ContextState, LaunchMode, Message, ProviderCapabilities, ProviderState, QuotaState } from "@humwick/sdk";
+import { errMessage, isRelayInjectionCategory, isSpawnProvider } from "@humwick/sdk";
+import { getManifest } from "@humwick/providers";
+import type { BooleanCapabilityDefault, ProviderCapabilityCondition } from "@humwick/providers";
+import { targetMatchesAgentIdentity } from "@humwick/sdk/agent-target";
+import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
+import type { RunnerRelayInjectionEvent } from "./relay-injection-events";
+import { agentProfileProjectionReport } from "./profile-projection";
+import { assembleLaunch } from "./launch-assembly";
+import { supportsActiveTurnSteer } from "./delivery-policy";
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LOG_TAIL_BYTES = 128 * 1024;
+const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
+const PROVIDER_DISPLAY_NAMES: Record<string, string> = { claude: "Claude", codex: "Codex" };
+
+interface RuntimeProviderOptions {
+  provider: string;
+  model?: string;
+  effort?: string;
+  approvalMode: string;
+  headless: boolean;
+  /** #2773 — a headless-pipe launch has no terminal to read, write, or attach. */
+  launchMode?: LaunchMode;
+  startedAt: number;
+  adapter: ProviderAdapter;
+  providerConfig?: ProviderConfig;
+  /** #2950 — the running process accepts an in-place effort change (see runnerEffortSwitch). */
+  effortSwitch?: boolean;
+}
+
+export interface ProbeModelInfo {
+  model?: string;
+  effort?: string;
+}
+
+export interface RestartProviderOptions {
+  resumeId?: string;
+  suppressPrompt?: boolean;
+  systemPromptAppend?: string;
+  relayInjectionEvents?: RunnerRelayInjectionEvent[];
+}
+
+export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
+  agentId: string;
+  label?: string;
+  provider: string;
+  tags: string[];
+  capabilities: string[];
+  defaultTags: string[];
+  defaultCapabilities: string[];
+  allowBroadTargets?: boolean;
+}): boolean {
+  if (message.resolvedToAgent === target.agentId) return true;
+  if (message.to === target.agentId) return true;
+  if (target.label && message.to === `label:${target.label}`) return true;
+  if (target.allowBroadTargets === false) return false;
+  return targetMatchesAgentIdentity(message.to, {
+    id: target.agentId,
+    label: target.label,
+    tags: [...target.tags, ...target.defaultTags, target.provider],
+    capabilities: [...target.capabilities, ...target.defaultCapabilities],
+  });
+}
+
+export function runnerMessageShouldDirtyObligations(message: Pick<Message, "from">, agentId: string): boolean {
+  return message.from !== agentId;
+}
+
+export function taskIdFromMessage(message: Pick<Message, "payload">): number | undefined {
+  const taskId = message.payload?.taskId;
+  return Number.isSafeInteger(taskId) ? taskId as number : undefined;
+}
+
+export function stripRunnerClaimedGuidance(body: string): string {
+  return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
+}
+
+function relayInjectionEventsFromParam(value: unknown): RunnerRelayInjectionEvent[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const events = value.flatMap((item): RunnerRelayInjectionEvent[] => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+    const record = item as Record<string, unknown>;
+    const detail = record.detail;
+    if (!isRelayInjectionCategory(record.category)) return [];
+    if (typeof record.summary !== "string" || !record.summary.trim()) return [];
+    if (!detail || typeof detail !== "object" || Array.isArray(detail)) return [];
+    return [{ category: record.category, summary: record.summary, detail: detail as Record<string, unknown> }];
+  });
+  return events.length ? events : undefined;
+}
+
+export function restartOptionsFromCommand(params: Record<string, unknown>): RestartProviderOptions {
+  return {
+    systemPromptAppend: typeof params.systemPromptAppend === "string" ? params.systemPromptAppend : undefined,
+    relayInjectionEvents: relayInjectionEventsFromParam(params.relayInjectionEvents),
+  };
+}
+
+// Bound a runner's INITIAL relay registration. `connect` resolves on the first `registered`
+// frame and otherwise loops forever, so a token the relay rejects (401 at the WS upgrade)
+// hangs here silently. Race it against `timeoutMs`; on timeout, surface a fatal reason, tear
+// down the bus (stop the retry loop) and throw so the process exits and the orchestrator
+// observes it instead of a silent zombie. Reconnects after first registration stay infinite.
+export async function registerWithinDeadline(
+  bus: { connect: () => Promise<void>; close: () => Promise<void> },
+  timeoutMs: number,
+  relayUrl: string,
+  onFatal: (reason: string) => void,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(
+      `runner failed to register with the relay within ${timeoutMs}ms — aborting so the orchestrator `
+      + `observes the exit instead of a silent hang (relay ${relayUrl}; check the relay is reachable `
+      + `and the runner token is valid).`,
+    )), timeoutMs);
+  });
+  try {
+    await Promise.race([bus.connect(), deadline]);
+  } catch (error) {
+    onFatal(errMessage(error));
+    await bus.close().catch(() => {});
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function csvTags(raw: string | undefined): string[] {
+  return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+export function relayBusUrl(relayUrl: string): string {
+  const url = new URL(relayUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
+  url.search = "";
+  return url.toString();
+}
+
+export function runnerAgentStatus(status: "idle" | "busy" | "offline" | "error"): "idle" | "busy" | "offline" {
+  return status === "error" ? "offline" : status;
+}
+
+export function runnerBusErrorAction(code: string, stopped: boolean): "ignore" | "log" | "stop" {
+  if (code === "STALE_SESSION") return stopped ? "ignore" : "stop";
+  return "log";
+}
+
+export function runnerShouldResolveProviderExit(status: SemanticStatus, exitCommandInProgress: boolean): boolean {
+  return !exitCommandInProgress && (status === "offline" || status === "error");
+}
+
+export function runnerShouldRestartUnexpectedProviderExit(
+  status: SemanticStatus,
+  input: {
+    exitCommandInProgress: boolean;
+    stopped: boolean;
+    restartInProgress: boolean;
+    provider?: string;
+    headless: boolean;
+    lifecycle?: "persistent" | "transient";
+    hasTerminalSession: boolean;
+  },
+): boolean {
+  return status === "offline"
+    && !input.exitCommandInProgress
+    && !input.stopped
+    && !input.restartInProgress
+    && input.headless
+    && input.lifecycle !== "transient"
+    && input.hasTerminalSession;
+}
+
+// #1258 (L3): claude prints its resume banner ANSI-dimmed — the raw log bytes are
+// `\x1b[2mclaude --resume <uuid>\x1b[22m`, so `claude` is immediately preceded by the SGR
+// escape's trailing `m`. A leading `\b` in the extraction regex finds no word boundary
+// (`m`→`c` are both word chars) and yields zero matches, stranding the resume id as null.
+// Strip CSI escape sequences before matching so the banner reads as plain text.
+const ANSI_ESCAPE_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+function stripAnsi(text: string): string {
+  return text.replace(ANSI_ESCAPE_RE, "");
+}
+
+function resumeLogExtractionRe(provider: string): RegExp | undefined {
+  const manifest = getManifest(provider);
+  const resume = manifest?.resume as { supported: boolean; idPattern?: string } | undefined;
+  if (!resume?.supported || !resume.idPattern || !manifest?.probe?.command) return undefined;
+  return new RegExp(`\\b${manifest.probe.command}\\s+--resume\\s+(${resume.idPattern})\\b`, "gi");
+}
+
+export function latestResumeIdFromText(provider: string, text: string): string | undefined {
+  const re = resumeLogExtractionRe(provider);
+  if (!re) return undefined;
+  const cleaned = stripAnsi(text);
+  let latest: string | undefined;
+  for (let match = re.exec(cleaned); match; match = re.exec(cleaned)) {
+    latest = match[1];
+  }
+  return latest;
+}
+
+export function latestResumeIdFromLogFile(provider: string, path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(path);
+    const length = Math.min(stat.size, LOG_TAIL_BYTES);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, "r");
+    readSync(fd, buffer, 0, length, offset);
+    return latestResumeIdFromText(provider, buffer.toString("utf8"));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function providerExitDiagnostics(input: {
+  status: SemanticStatus;
+  runtimeMs: number;
+  processMeta?: Record<string, unknown>;
+  hasProcess: boolean;
+  exitCommandInProgress: boolean;
+  stopped: boolean;
+  restartInProgress: boolean;
+  restartPending: boolean;
+  headless: boolean;
+  provider: string;
+  logFile?: string;
+}): Record<string, unknown> {
+  const tmuxSession = typeof input.processMeta?.tmuxSession === "string" ? input.processMeta.tmuxSession : undefined;
+  const tmuxSocket = typeof input.processMeta?.tmuxSocket === "string" ? input.processMeta.tmuxSocket : undefined;
+  const exitSource = tmuxSession ? "tmux-session-ended" : input.hasProcess ? "process-exit" : "provider-status";
+  const claudeResumeId = getManifest(input.provider)?.resume?.supported && input.logFile ? latestResumeIdFromLogFile(input.provider, input.logFile) : undefined;
+  return {
+    status: input.status,
+    runtimeMs: Number.isFinite(input.runtimeMs) ? input.runtimeMs : null,
+    exitSource,
+    exitCommandInProgress: input.exitCommandInProgress,
+    stopped: input.stopped,
+    restartInProgress: input.restartInProgress,
+    restartPending: input.restartPending,
+    headless: input.headless,
+    hasTerminalSession: Boolean(tmuxSession),
+    tmuxSession: tmuxSession ?? null,
+    tmuxSocket: tmuxSocket ?? null,
+    claudeResumeId: claudeResumeId ?? null,
+  };
+}
+
+export function providerExitResumeId(diagnostics: Record<string, unknown>): string | undefined {
+  const value = diagnostics.claudeResumeId;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function providerManualRecoveryReason(diagnostics: Record<string, unknown>): string {
+  return providerExitResumeId(diagnostics)
+    ? "claude-exit-manual-resume-available"
+    : "claude-exit-manual-intervention-required";
+}
+
+export function providerDisplayName(provider: string): string {
+  return PROVIDER_DISPLAY_NAMES[provider] ?? provider;
+}
+
+export function providerMonitorUnavailableMessage(provider: string): string {
+  return `no ${providerDisplayName(provider)} monitor connected`;
+}
+
+export function providerManualRecoveryMessage(provider: string, diagnostics: Record<string, unknown>): string {
+  const displayName = providerDisplayName(provider);
+  return providerExitResumeId(diagnostics)
+    ? `${displayName} exited; runner will not auto-resume. Resume id captured for manual recovery.`
+    : `${displayName} exited; runner will not restart automatically.`;
+}
+
+export function providerExitLastError(provider: string, marker: Record<string, unknown>): string {
+  const resumeId = providerExitResumeId(marker);
+  const displayName = providerDisplayName(provider);
+  return resumeId
+    ? `${displayName} provider exited; resume id ${resumeId} captured for manual recovery`
+    : `${displayName} provider exited; manual intervention required`;
+}
+
+export function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
+  const raw = params.timeoutMs;
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
+  return Math.min(raw, 60_000);
+}
+
+// #1339: the Codex adapter rejects a delivery attempted while a turn is already in progress
+// (Codex has no queue-while-busy the way Claude's input buffer does), so the runner re-queues
+// and re-drains once the turn ends. That rejection is expected flow control, not a fault — the
+// drain loop retries roughly once a second during a long turn, so it must not spam the log.
+export const CODEX_TURN_IN_PROGRESS_MESSAGE = "codex turn in progress; deferring delivery until it completes";
+
+export function shouldLogDeliveryFailure(error: unknown): boolean {
+  const message = errMessage(error);
+  return message !== providerMonitorUnavailableMessage("claude")
+    && message !== CODEX_TURN_IN_PROGRESS_MESSAGE;
+}
+
+/** The same rejection, seen from the COMMAND side (#1565 F1): a serialized boundary payload that
+ *  met the turn the payload before it started is deferred until that turn ends, not failed. */
+export function isTurnInProgressDeliveryError(error: unknown): boolean {
+  return errMessage(error) === CODEX_TURN_IN_PROGRESS_MESSAGE;
+}
+
+/** Command types that put a payload into the provider's single input channel, and therefore take a
+ *  `ProviderInputQueue` ticket at dispatch so two of them can never interleave (#1565 F1). */
+export const PROVIDER_INPUT_COMMAND_TYPES: ReadonlySet<string> = new Set(["agent.clearContext", "agent.injectContext", "prompt.inject"]);
+
+export function runtimeTokenRenewDelayMs(expiresAtSeconds: number, nowMs = Date.now()): number | undefined {
+  const expiresAtMs = expiresAtSeconds * 1000;
+  const ttlMs = expiresAtMs - nowMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return undefined;
+  const leadMs = Math.min(60 * 60 * 1000, Math.max(60_000, Math.floor(ttlMs * 0.2)));
+  const jitterMs = Math.floor(Math.random() * Math.min(30_000, Math.max(0, leadMs / 2)));
+  return Math.max(1_000, ttlMs - leadMs - jitterMs);
+}
+
+export function runtimeTokenRenewTimerSchedule(delayMs: number): { delayMs: number; renew: boolean } | undefined {
+  if (!Number.isFinite(delayMs) || delayMs <= 0) return undefined;
+  if (delayMs > MAX_TIMER_DELAY_MS) return { delayMs: MAX_TIMER_DELAY_MS, renew: false };
+  return { delayMs, renew: true };
+}
+
+export function lifecycleCapabilities(): Record<string, true> {
+  return {
+    shutdownHard: true,
+    restartHard: true,
+    semanticStatus: true,
+    transportReconnect: true,
+  };
+}
+
+function resolveCondition(condition: ProviderCapabilityCondition, options: RuntimeProviderOptions): boolean {
+  switch (condition) {
+    case "always": return true;
+    case "never": return false;
+    case "headless": return options.headless;
+    case "interactive": return !options.headless;
+    case "approval:read-only": return options.approvalMode === "read-only";
+    case "approval:not-read-only": return options.approvalMode !== "read-only";
+    case "adapter:compact-supports-instructions": return Boolean(options.adapter.compactSupportsInstructions);
+    case "adapter:clear-context": return Boolean(options.adapter.clearContext);
+    default: return false;
+  }
+}
+
+function resolveBooleanDefault(def: BooleanCapabilityDefault, options: RuntimeProviderOptions): boolean {
+  if (typeof def === "boolean") return def;
+  return resolveCondition(def.when, options) ? def.value : def.otherwise;
+}
+
+export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo, quotaState?: QuotaState): ProviderCapabilities {
+  const manifest = getManifest(options.provider);
+  const capDefaults = manifest?.capabilityDefaults;
+  const model = options.model ?? probeModel?.model;
+  const effort = options.effort ?? probeModel?.effort;
+  const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
+  const shellMode = runtimeShellMode(options);
+  return {
+    lifecycle: {
+      managed: capDefaults?.lifecycle?.managed ?? true,
+      shutdownHard: capDefaults?.lifecycle?.shutdownHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.shutdownHard, options) : true,
+      restartHard: capDefaults?.lifecycle?.restartHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.restartHard, options) : true,
+      semanticStatus: capDefaults?.lifecycle?.semanticStatus ?? true,
+      reconnect: capDefaults?.lifecycle?.reconnect ?? true,
+    },
+    model: {
+      provider: options.provider,
+      alias: model,
+      id: model,
+      effort,
+      ...(options.effortSwitch ? { effortSwitch: true } : {}),
+      source: modelSource,
+      confidence: options.model ? "reported" : probeModel?.model ? "reported" : "unknown",
+      lastUpdatedAt: options.startedAt,
+    },
+    session: {
+      approvalMode: options.approvalMode,
+      fileRead: true,
+      fileWrite: options.approvalMode !== "read-only",
+      shell: shellMode !== "none",
+      shellMode,
+      source: "runtime",
+      confidence: "reported",
+      lastUpdatedAt: options.startedAt,
+    },
+    ...runtimeProviderContextCapabilities(options, contextState),
+    ...runtimeProviderQuotaCapabilities(options, quotaState),
+    ...runtimeProviderTerminalCapabilities(options),
+    liveSession: {
+      capture: true,
+      inject: Boolean(options.adapter.deliverInitialPrompt),
+      interrupt: Boolean(options.adapter.interrupt),
+      steer: supportsActiveTurnSteer(options.adapter, options.providerConfig),
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: capDefaults?.liveSession?.slashCommands ?? false,
+    },
+    source: "runtime",
+    confidence: "reported",
+    lastUpdatedAt: options.startedAt,
+  };
+}
+
+function runtimeShellMode(options: RuntimeProviderOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
+  const manifest = getManifest(options.provider);
+  const shellModeMap = manifest?.capabilityDefaults?.session?.shellMode;
+  if (options.approvalMode === "read-only") return (shellModeMap?.readOnly ?? "none") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  if (options.approvalMode === "open") return (shellModeMap?.open ?? "unrestricted") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  return (shellModeMap?.guarded ?? "guarded") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+}
+
+function runtimeProviderTerminalCapabilities(options: RuntimeProviderOptions): Pick<ProviderCapabilities, "terminal"> {
+  const manifest = getManifest(options.provider);
+  const termDefaults = manifest?.capabilityDefaults?.terminal;
+  if (!termDefaults || termDefaults.mode === "none" || options.launchMode === "headless") return {};
+  if (termDefaults.condition && !resolveCondition(termDefaults.condition, options)) return {};
+  if (termDefaults.mode === "live" && termDefaults.live) {
+    return { terminal: { live: termDefaults.live } };
+  }
+  if (termDefaults.mode === "attach" && termDefaults.attach) {
+    return { terminal: { attach: termDefaults.attach } };
+  }
+  return {};
+}
+
+// #557 — the agent-card projection now DESCRIBES the assembled launch (same source the
+// adapter turns into args), so it can't drift from reality. `config`/`providerConfig` are
+// the spawn inputs; when present we assemble (pure — no disk writes here) and report that.
+export function appliedAgentProfileMetadata(
+  provider: string,
+  profile: AgentProfile,
+  config?: RunnerSpawnConfig,
+  providerConfig?: ProviderConfig,
+): Record<string, unknown> {
+  const projection = isSpawnProvider(provider) && config && providerConfig
+    ? agentProfileProjectionReport({ assembled: assembleLaunch(provider, config, providerConfig) })
+    : undefined;
+  return {
+    name: profile.name,
+    base: profile.base,
+    provider: profile.provider ?? "any",
+    relay: profile.relay,
+    instructions: {
+      repoInstructions: profile.instructions.repoInstructions,
+      globalInstructions: profile.instructions.globalInstructions,
+      appendCount: profile.instructions.append.length,
+      hasSystem: Boolean(profile.instructions.system),
+    },
+    skills: profile.skills.filter((item) => item.enabled).length,
+    plugins: profile.plugins.filter((item) => item.enabled).length,
+    mcp: { mode: profile.mcp.mode },
+    hooks: { mode: profile.hooks.mode, refs: profile.hooks.refs?.filter((item) => item.enabled).length ?? 0 },
+    permissions: profile.permissions,
+    harnessSubagents: profile.harnessSubagents === true,
+    projection,
+  };
+}
+
+function runtimeProviderContextCapabilities(options: RuntimeProviderOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
+  const manifest = getManifest(options.provider);
+  const ctxDefaults = manifest?.capabilityDefaults?.context;
+  const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
+  context.compactInstructions = Boolean(options.adapter.compact && options.adapter.compactSupportsInstructions);
+  const supportsManagedContext = ctxDefaults?.managed ? resolveCondition(ctxDefaults.managed, options) : false;
+  if (contextState) {
+    context.stats = { source: contextState.source, confidence: contextState.confidence };
+    if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
+      context.windowTokens = contextState.tokensMax;
+    }
+  }
+  if (ctxDefaults) {
+    if (resolveBooleanDefault(ctxDefaults.compact, options)) context.compact = true;
+    if (resolveBooleanDefault(ctxDefaults.clear, options)) context.clear = true;
+    context.inject = ctxDefaults.inject;
+  }
+  if (supportsManagedContext && options.adapter.compact && (options.adapter.compactSupportsInstructions || options.adapter.compactReportsSubmission)) context.resume = "native";
+  else if (supportsManagedContext && options.adapter.clearContext) context.resume = "clear-inject";
+  return Object.keys(context).length ? { context } : {};
+}
+
+function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quotaState?: QuotaState): Pick<ProviderCapabilities, "quota"> {
+  const manifest = getManifest(options.provider);
+  const quotaDefaults = manifest?.capabilityDefaults?.quota;
+  if (!quotaDefaults?.supported) return {};
+  return {
+    quota: {
+      supported: true,
+      source: quotaState?.source ?? "probe",
+      unit: quotaState?.windows[0]?.unit ?? "%",
+      windows: quotaState?.windows.map((window) => ({
+        name: window.name,
+        unit: window.unit,
+        reset: window.resetsAt !== undefined,
+      })) ?? manifest!.quotaWindows.map(w => ({ name: w.name, unit: w.unit as "%" | "tokens" | "requests", reset: w.reset })),
+    },
+  };
+}
+
+export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): ProviderState | null {
+  const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
+  const state = providerTurn?.metadata?.providerState;
+  return state && typeof state === "object" && !Array.isArray(state) && typeof (state as { state?: unknown }).state === "string"
+    ? state as ProviderState
+    : null;
+}
+
+export function isHttpAuthError(error: unknown): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === 401 || status === 403;
+}
+
+// #2433 — outbox delivery-error classification. The runner outboxes must never poison
+// (permanently drop) an event over a CONNECTION-class failure: report-up chat rides the
+// session outbox, so a poisoned row is real message loss. These predicates split a send()
+// rejection into TRANSIENT (connect-phase transport failure, HTTP 5xx, or 429) versus
+// DETERMINISTIC client rejection (400/413/422 — the relay parsed and refused this exact
+// payload). Like the transport classifier in transport-errors.ts, the connect predicate walks
+// the `cause` chain and inspects `code`, `name`, and message text: Bun surfaces undici's
+// pre-send "Unable to connect" / "fetch failed" with the real code (ECONNREFUSED, ENOTFOUND…)
+// on a nested cause.
+// Connect-phase / mid-flight transport failure: refused, DNS, unreachable, socket lost, or a
+// client-side timeout. Always safe to retry for outbox events — every row carries an
+// idempotency key the relay dedups, so a resend can never double-apply.
+const CONNECT_ERROR_CODE_RE = /^(?:ECONNREFUSED|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|ETIMEDOUT|ECONNABORTED|ECONNRESET|EPIPE|ConnectionRefused)$/i;
+const CONNECT_ERROR_MESSAGE_RE = /unable to connect|econnrefused|enotfound|eai_again|ehostunreach|enetunreach|etimedout|connection refused|fetch failed|failed to fetch|getaddrinfo|\bdns\b|network|timeout|timed out|socket hang up|socket connection was closed|connection was closed unexpectedly/i;
+
+export function isConnectError(error: unknown): boolean {
+  return walkErrorChain(error, (code, _name, message) =>
+    CONNECT_ERROR_CODE_RE.test(code) || CONNECT_ERROR_MESSAGE_RE.test(message));
+}
+
+function httpErrorStatus(error: unknown): number | undefined {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return typeof status === "number" ? status : undefined;
+}
+
+// TRANSIENT for the outbox retry policy (#2433): connection-class transport failures plus
+// HTTP 5xx/429 (relay momentarily overloaded/restarting). Transient failures NEVER poison on
+// attempt count — the outbox parks the head on a slow periodic re-drive until the relay returns.
+export function isTransientDeliveryError(error: unknown): boolean {
+  if (isConnectError(error)) return true;
+  const status = httpErrorStatus(error);
+  return status !== undefined && (status >= 500 || status === 429);
+}
+
+// DETERMINISTIC client rejection (#2433): the relay is up, parsed the payload, and will refuse
+// it every time. Poison immediately so one genuinely-bad row cannot stall the queue.
+export function isDeterministicClientError(error: unknown): boolean {
+  const status = httpErrorStatus(error);
+  return status === 400 || status === 413 || status === 422;
+}
+
+export function isHttpStatusError(error: unknown, code: number): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === code;
+}
+
+export function httpErrorKey(error: unknown): string {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  if (typeof status === "number") return `status:${status}`;
+  return String(error);
+}
+
+export function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}