@north-light/api 0.3.446 → 0.3.447

package/dist/core/canvas/types.d.ts

@@ -0,0 +1,446 @@
+/** What a node is doing right now. `active` means the engine process — a detached
+ *  headless broker — is live, NOT that it holds a window or that anyone is
+ *  watching it (attachment is a separate axis: the `focuses` table tracks each
+ *  node's one viewer pane, and the broker records its helloed-viewer count).
+ *  Crucially, `active` does NOT mean the node is GENERATING right now: a live
+ *  engine sits dormant between turns (waiting on a child, a human, or just left
+ *  open), so `active` ≠ busy — it only means the process was never closed. To tell
+ *  whether an active node is actually working, check its pi session-file mtime or
+ *  CPU, not its status. UI shows active+idle; `done` is hidden but revivable;
+ *  `canceled` is a user-closed node (also hidden, also revivable — not a fault);
+ *  only `dead` is a fault. */
+export type NodeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** Does stopping finalize the node? terminal = worker (finalizes on push --final);
+ *  resident = an interactable conversation that parks and remains wakeable
+ *  without being forced to submit a final. */
+export type Lifecycle = 'terminal' | 'resident';
+/** base = hands-on worker; orchestrator = delegating manager. Bespoke per kind. */
+export type Mode = 'base' | 'orchestrator';
+/** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
+export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
+export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined';
+export type NodeOutcomeKind = 'result' | 'failure';
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export declare const OUTCOME_PAYLOAD_MAX_BYTES: number;
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: import('../fault-classifier.js').FaultKind;
+    error_class?: import('../events/types.js').ErrorClassCode;
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResult;
+    truncated?: true;
+}
+/** A declined structured result. `code` is opaque here — the requester validates it. */
+export interface DeclinedResult {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
+/** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
+ *  org chart, views, completion routing). `spawned_by` is audit only. */
+/** The pi launch recipe, persisted so the daemon can faithfully revive a node
+ *  as its *current* self. Rewritten on every polymorph (base→orchestrator). */
+export interface LaunchSpec {
+    /** Model id/pattern passed to pi `--model`. */
+    model?: string;
+    /** Original logical family/strength preference, retained after normalization. */
+    modelIntent?: import('../../types.js').ModelIntent;
+    /** True for an exact-consult launch: `model` is the verbatim captured
+     *  `provider/id:thinking` spec, bypassing the review floor/normalize and
+     *  every launch-time/turn-time provider fallback — an unavailable exact
+     *  model must fail rather than substitute. See `buildLaunchSpec`. */
+    modelExact?: boolean;
+    /** pi `--tools` allow-list. */
+    tools?: string[];
+    /** pi `-e` extension paths, loaded once; they self-gate on live {kind,mode}. */
+    extensions: string[];
+    /** Resolved system prompt text (passed via --append-system-prompt / --system-prompt). */
+    systemPrompt?: string;
+    /** Extra env injected into the pi process. */
+    env: Record<string, string>;
+}
+/** The repository fingerprint a refusal was decided against. An examination
+ *  that reads the same values can skip the whole proof cascade: nothing about
+ *  the refusal can have changed. */
+export interface ManagedWorktreeObservation {
+    /** Tip of `refs/heads/<base_ref>`, or null when it no longer resolves. */
+    base: string | null;
+    /** Tip of the base branch's upstream (or `origin/<base_ref>` fallback). */
+    upstream: string | null;
+    /** Tip of `refs/heads/<branch>`, or null when the branch is gone. */
+    branch: string | null;
+    /** `absent`, or a hash of the checkout's HEAD plus `git status --porcelain`. */
+    checkout: string | null;
+}
+/** Reconciliation bookkeeping owned SOLELY by the daemon's managed-worktree
+ *  sweep. Present only while a record is not yet reconciled; cleared when
+ *  cleanup completes. */
+export interface ManagedWorktreeSweep {
+    /** Structured code for why the last pass did not complete cleanup. */
+    reason: string;
+    detail?: string;
+    observed: ManagedWorktreeObservation;
+    /** Consecutive passes that examined this record without completing it. */
+    attempts: number;
+    last_attempt: string;
+    /** The sweep does not re-examine this record before this instant. */
+    next_attempt: string;
+    /** Set once `attempts` reaches the terminal backoff tier: this record needs a
+     *  human, and `crtr sys worktrees` lists it with its reason. It is still
+     *  fingerprint-checked at the capped interval, so work that lands later is
+     *  still cleaned up. */
+    quarantined?: true;
+}
+export interface ManagedWorktree {
+    state: 'open' | 'closed' | 'abandoned';
+    /** A closed worktree remains registered until its owner has exited, so Git
+     *  never deletes the caller's live checkout beneath it. The daemon sweep is
+     *  the one authority that turns `pending` into `complete`. */
+    cleanup?: 'pending' | 'complete';
+    path: string;
+    branch: string;
+    repo_root: string;
+    base_ref: string;
+    base_sha: string;
+    created: string;
+    closed?: string;
+    abandoned?: {
+        branch: string;
+        tip_sha: string;
+        at: string;
+        by: string;
+    };
+    /** Recorded by `close` when the rebase succeeded but fast-forwarding the base
+     *  was blocked. The sweep lands a dead node's commits ONLY for a record
+     *  carrying this: the daemon finishes a job someone started, it never invents
+     *  the intent to land. */
+    land_intent?: {
+        at: string;
+        blocked: string;
+    };
+    sweep?: ManagedWorktreeSweep;
+    /** Recorded ONLY by an explicit branch-moved `close` when the checkout's
+     *  actual branch has drifted from `branch` (its recorded `crtr/*` ref is
+     *  gone — ordinary PR work moved it there) but that branch's content was
+     *  proven, immediately before this was written, already contained in the
+     *  recorded base or its upstream. Authorizes ONLY the daemon sweep's later
+     *  checkout removal for this EXACT path + git common dir + observed branch
+     *  + observed SHA — the sweep re-verifies all four before acting and NEVER
+     *  deletes `observed_branch`, since it is not a `crtr/*` branch crouter
+     *  created. A mismatch on re-verification invalidates the authorization; a
+     *  fresh explicit close must re-establish it. Absent for every ordinary
+     *  managed worktree, and for `abandon`'s branch-moved path (which disposes
+     *  immediately instead of deferring, so it needs no persisted grant). */
+    disposal?: {
+        observed_branch: string;
+        observed_sha: string;
+        common_dir: string;
+        authorized: string;
+    };
+}
+/** Immutable companion provenance. The origin session/leaf/model coordinates
+ *  remain canonical in the review row rather than being duplicated into node
+ *  metadata. `kind` names the surface the companion serves: absent or `review`
+ *  is a human document review; `page_feedback` binds a page ticket's feedback
+ *  conversation, with review_id = ticket id and target_file = the page source. */
+export interface ReviewBinding {
+    kind?: 'review' | 'page_feedback';
+    review_id: string;
+    origin_node_id: string;
+    branch_file: string;
+    target_file: string;
+}
+/** A node's durable configuration, stored in SQL node columns. Sessions and
+ *  managed worktrees have their own SQL stores. */
+export interface NodeIdentity {
+    node_id: string;
+    name: string;
+    /** A 2-4 word kebab-case handle derived from the node's first prompt (named
+     *  headlessly by pi; see runtime/naming.ts). Shown in the editor label. */
+    description?: string;
+    /** The same first prompt named as PROSE — a sentence-case phrase with its
+     *  punctuation intact, produced by the same headless namer in the same call as
+     *  `description`. Kebab case is right for a tmux window and an editor label
+     *  and wrong for a conversation list, so a surface reading to a person takes
+     *  this. Absent on a node named before titles existed. */
+    title?: string;
+    /** A single Nerd Font glyph depicting the node's work, chosen by the same
+   *  headless namer that produced `description` (see runtime/naming.ts). Kept as
+   *  its own field rather than baked into the description so each surface decides
+   *  whether to render it; absent on a node named before icons existed, or when
+   *  the model returned nothing usable. */
+    icon?: string;
+    /** How many times this node has been (re)launched — born at 0, bumped on
+     *  every revive. Exposed to the pi footer as CRTR_CYCLES so a refresh/crash
+     *  cycle reads at a glance there. */
+    cycles?: number;
+    created: string;
+    /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
+    cwd: string;
+    /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
+     *  headless in-process engine). NULL ⇒ 'tmux' (every pre-broker node). */
+    host_kind?: 'tmux' | 'broker' | null;
+    /** The profile this node runs under, a stable profile-directory id
+     *  (`<slug>-<id>`, see `core/profiles/manifest.ts`). It is chosen once at spawn
+     *  (inherited from the spawner, or `--profile`) and is the runtime→resolver seam
+     *  (`CRTR_PROFILE_ID`) the memory/gate substrate reads. NULL only for historical
+     *  root/no-profile rows; new root conversations use the stable root profile id. */
+    profile_id?: string | null;
+    /** Role the node was born as: explore | developer | plan | review | general… */
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    /** The last {kind,mode,lifecycle} whose context delivery was acknowledged.
+     *  Meta-only (not a db column). Born equal to the initial persona; later
+     *  changes advance only after a baseline or provider-gated transition is
+     *  durably registered. Historical rows may omit `kind`; reads resolve it to
+     *  the current kind so they do not fabricate a transition. */
+    persona_ack?: {
+        kind?: string;
+        mode: Mode;
+        lifecycle: Lifecycle;
+    };
+    /** Spine parent — my manager (who subscribes to me); drives canvas nesting +
+     *  orphaning. null for a root (top-level, no manager). */
+    parent?: string | null;
+    /** Provenance — who spawned me (the `spawned_by` edge). Decoupled from
+     *  `parent` so an INDEPENDENT root (parent=null) still records its lineage.
+     *  Audit only; null for a user-opened root. Defaults to `parent` for a child. */
+    spawned_by?: string | null;
+    /** Actor that created this node; null when an external process did. Unlike
+     *  `parent` (manager) and `spawned_by` (provenance edge), this determines
+     *  whether birth is announced to the manager. */
+    creator?: string | null;
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
+    fork_from?: string | null;
+    /** Resolved absolute source session file used for every pre-bind fork retry. */
+    fork_source_file?: string | null;
+    /** Immutable review-companion binding. Undefined for ordinary nodes. */
+    review_binding?: ReviewBinding | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passive_default?: boolean;
+    /** The pi session id for `--session <id>` revival. */
+    pi_session_id?: string | null;
+    /** Absolute path to pi's session `.jsonl` file, captured at session_start via
+     *  ctx.sessionManager.getSessionFile(). Preferred over pi_session_id when
+     *  resuming: pi resolves a BARE `--session <id>` relative to the launch cwd
+     *  first (and shows an interactive cross-project "Fork? [y/N]" prompt when the
+     *  revive cwd differs from the session's creation cwd), whereas an absolute
+     *  PATH is opened directly — immune to any cwd discrepancy. Null for older
+     *  nodes booted before this field existed → revive falls back to the bare id. */
+    pi_session_file?: string | null;
+    /** True while a cycling (`--crtr-new-cycle`) launch remains unconfirmed. Set
+     *  monotonically by reviveNode before launch and cleared only by the stophook's
+     *  confirmed `session_start`. While true, reviveNode's locked arbitration
+     *  vetoes every caller's strict-resume preference so a failed cycle cannot
+     *  reopen the old context. */
+    cycle_pending?: boolean | null;
+    /** A caller-pinned model TIER (ultra/strong/medium/light) that overrides the
+     *  persona's declared default. Durable so it survives a polymorph: every
+     *  spec-rebuild path (promote/demote/lifecycle/reset) re-passes it to
+     *  buildLaunchSpec, while the persona default is recomputed fresh for the
+     *  (possibly new) kind. Null/undefined ⇒ use the persona default. */
+    model_override?: string | null;
+    /** Per-run allow-list; null inherits the full runtime vocabulary. */
+    scopes?: string[] | null;
+    grantee?: string;
+    sub?: string | null;
+    grant_id?: string | null;
+    client_id?: string | null;
+    metadata_json?: string | null;
+    run_id?: string | null;
+    event_cursor?: number | null;
+    last_activity_at?: string | null;
+    usage_json?: string | null;
+    deleting_at?: string | null;
+    /** Full pi launch recipe; rewritten on every polymorph. */
+    launch?: LaunchSpec;
+    /** Managed git worktree owned by this node (if any). */
+    managed_worktree?: ManagedWorktree | null;
+}
+/** A node's live runtime state, stored in the WAL-backed `nodes` row. Each
+ *  field is mutated by an atomic single-statement `UPDATE` (setStatus / setIntent /
+ *  setPresence / recordPid+clearPid). The daemon reconciles process and presence
+ *  state from tmux and broker reality. */
+export interface NodeRuntime {
+    /** What the node is doing right now. */
+    status: NodeStatus;
+    /** Why the node last stopped (done | refresh | idle-release). Drives reap-vs-revive.
+     *  Optional on the hydrated view (a fresh construction omits it); the row
+     *  column is always present, defaulting null. */
+    intent?: ExitIntent;
+    /** Controller whose next inbox delivery permits this terminal node to sleep.
+     * Mutable durable runtime state: ancestry never implies a wait. */
+    waiting_for?: string | null;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
+    /** Immutable basename of the committed canonical final report, or null. */
+    final_report?: string | null;
+    /** ISO timestamp carried by the committed canonical final report, or null. */
+    finalized_at?: string | null;
+    /** Durable terminal outcome. `outcome_at` is its write-once latch. */
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    /** Absolute wall-clock spawn deadline, or null when unbounded. */
+    deadline_at?: string | null;
+    /** Cumulative input tokens reported by the broker telemetry producer. */
+    telemetry_tokens_in?: number | null;
+    /** Latest live context-window token gauge reported by the broker. */
+    telemetry_context_tokens?: number | null;
+    /** Latest tool summary reported by the broker. */
+    telemetry_last_activity?: string | null;
+    /** Timestamp of the latest broker telemetry update. */
+    telemetry_updated_at?: string | null;
+    /** OS pid of the live broker process, recorded on boot (stophook session_start).
+     *  The daemon's authoritative liveness signal — every node is a detached broker,
+     *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
+     *  reviveNode until the fresh broker re-records it, so the relaunch gap reads as
+     *  a dead pid (guarded by the daemon's revive grace, not a double-spawn). */
+    pi_pid?: number | null;
+    /** Stable process-identity fingerprint (`pid.ts`'s `composeIdentity`) captured
+     *  at the SAME moment `pi_pid` is recorded (`recordPid`) — the LAUNCH-time
+     *  baseline `headlessBrokerHost.teardown()` compares `pi_pid`'s CURRENT
+     *  identity against before signaling anything:
+     *  a mismatch proves the OS has already recycled `pi_pid` for an unrelated
+     *  process since this node launched it, and teardown must refuse to signal
+     *  that stranger. `null` for a node booted before this field existed, or if
+     *  the launch-time identity capture itself failed (fail-open — no baseline
+     *  means no guard, not a false mismatch). Cleared to null alongside `pi_pid`
+     *  by `clearPid` and the boot-liveness sweep (a new boot invalidates both). */
+    pi_pid_identity?: string | null;
+    /** Presence: the tmux session (its root's home) and window this node renders
+     *  in while active. Cleared when the node goes done/dead and its window closes.
+     *  The row IS the presence registry (one atomic setPresence per move).
+     *  v3: a DERIVED CACHE of `pane`'s current location — reconciled from the pane,
+     *  never trusted when a user move could have desynced them. */
+    tmux_session?: string | null;
+    window?: string | null;
+    /** LOCATION's authoritative handle — the durable tmux `%pane_id` this node's
+     *  pane is anchored on. tmux preserves it across `move-pane`/`join-pane`/
+     *  `break-pane` and window renumbering, so `window`/`tmux_session` above are a
+     *  cache reconciled from it and pane-existence is the liveness probe. A
+     *  not-focused + not-generating node has `pane = null` (no pane). Authoritative
+     *  in the row exactly like `window`/`tmux_session` — a RUNTIME field, NOT meta
+     *  identity — written by the one atomic `setPresence` UPDATE. */
+    pane?: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
+}
+/** The hydrated node view `getNode()` returns: durable configuration and live
+ *  runtime from SQL, with session and worktree state from their named stores.
+ *  It retains the historical `NodeMeta` name for existing callers. */
+export type NodeMeta = NodeIdentity & NodeRuntime;
+/** The queryable projection of a node's SQL configuration and runtime state. */
+export interface NodeRow {
+    node_id: string;
+    name: string;
+    /** The pi-generated first-task description; see NodeIdentity.description.
+     *  Absent for a node not yet named — the column's NULL is mapped to undefined
+     *  at `rowFrom` so identity, row, and DTO all spell "unnamed" the same way. */
+    description?: string;
+    /** Relaunch count; see NodeIdentity.cycles. Absent on a row written before
+     *  this column. */
+    cycles?: number;
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+    status: NodeStatus;
+    cwd: string;
+    /** Which HOST launches + supervises this node; see NodeIdentity.host_kind. */
+    host_kind: 'tmux' | 'broker' | null;
+    /** The profile this node runs under; see NodeIdentity.profile_id. NULL only
+     *  for historical root/no-profile rows. */
+    profile_id: string | null;
+    /** Per-run allow-list; null inherits the full runtime vocabulary. */
+    scopes: string[] | null;
+    grantee?: string;
+    sub?: string | null;
+    grant_id?: string | null;
+    client_id?: string | null;
+    metadata_json?: string | null;
+    run_id?: string | null;
+    event_cursor?: number | null;
+    last_activity_at?: string | null;
+    usage_json?: string | null;
+    deleting_at?: string | null;
+    parent: string | null;
+    created: string;
+    /** Authoritative runtime columns (see NodeRuntime). */
+    intent: ExitIntent;
+    waiting_for: string | null;
+    frozen_at?: string | null;
+    respawn_failures?: number;
+    respawn_not_before?: string | null;
+    launched_at?: string | null;
+    last_settled_at?: string | null;
+    terminal_reason?: TerminalReason | null;
+    final_report?: string | null;
+    finalized_at?: string | null;
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    deadline_at?: string | null;
+    /** Cumulative input tokens reported by the broker telemetry producer. */
+    telemetry_tokens_in?: number | null;
+    /** Latest live context-window token gauge reported by the broker. */
+    telemetry_context_tokens?: number | null;
+    /** Latest tool summary reported by the broker. */
+    telemetry_last_activity?: string | null;
+    /** Timestamp of the latest broker telemetry update. */
+    telemetry_updated_at?: string | null;
+    pi_pid: number | null;
+    /** See `NodeRuntime.pi_pid_identity`. */
+    pi_pid_identity: string | null;
+    window: string | null;
+    tmux_session: string | null;
+    /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */
+    pane: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
+}
+/** A FOCUS row as stored in the `focuses` table (canvas.db, migration v6): one
+ *  durable on-screen viewport the user looks at, bound to one node. Plural —
+ *  many focuses live at once across windows and sessions (the plural
+ *  generalization of the old single focus pointer). Anchored on the durable tmux
+ *  `%pane_id`; `session` is a derived cache reconciled from the pane. `node_id`
+ *  is UNIQUE — a node occupies at most one focus (Q5). */
+export interface FocusRow {
+    /** Stable internal id for the viewport (the table's primary key). */
+    focus_id: string;
+    /** The durable `%pane_id` realizing the focus, or null before it is placed. */
+    pane: string | null;
+    /** Derived cache of the user session the pane lives in (reconciled from pane). */
+    session: string | null;
+    /** The node this focus shows. UNIQUE → a node occupies ≤1 focus. */
+    node_id: string;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionRef {
+    /** The node id at the other end of the edge. */
+    node_id: string;
+    active: boolean;
+    created: string;
+}

package/dist/core/canvas/types.js

@@ -0,0 +1,6 @@
+// The canvas vocabulary — the node + edge model the whole runtime hangs on.
+//
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the node graph and
+// runtime state. Each node directory holds only its artifacts.
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export const OUTCOME_PAYLOAD_MAX_BYTES = 64 * 1024;

package/dist/core/fault-classifier.d.ts

@@ -0,0 +1,34 @@
+import type { ErrorClass, OperationId } from './events/types.js';
+import { type ProviderFailureDetails } from './provider-failure.js';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
+export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';
+export interface FaultRetry {
+    disposition: FaultRetryDisposition;
+    by?: FaultRetryOwner;
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface FaultProviderError extends ProviderFailureDetails {
+    provider: string;
+    model: string;
+}
+export interface Fault {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    operation_id: OperationId;
+    anchorEntryId?: string;
+    providerError?: FaultProviderError;
+}
+export interface FaultClassification {
+    kind: FaultKind;
+    disposition: FaultRetryDisposition;
+}
+export declare function errorClassFromFault(fault: Pick<Fault, 'kind' | 'retry'>): ErrorClass;
+export declare function classify(link: FaultLink, raw: unknown): FaultClassification;

package/dist/core/fault-classifier.js

@@ -0,0 +1,96 @@
+import { hasManagedProviderCoolingDiagnostic } from './runtime/managed-provider-cooling.js';
+import { recognizeProviderError } from './provider-error-recognition.js';
+import { extractProviderFailureDetails } from './provider-failure.js';
+import { isRecord } from '../shared/predicates.js';
+const errorClassByFaultKind = {
+    'rate-limit': 'rate_limit',
+    overloaded: 'overloaded',
+    connection: 'connection',
+    auth: 'auth',
+    protocol: 'protocol',
+    'context-overflow': 'context_overflow',
+    wedged: 'wedged',
+    'model-not-found': 'model_not_found',
+    other: 'unknown',
+};
+export function errorClassFromFault(fault) {
+    return {
+        class: errorClassByFaultKind[fault.kind],
+        retry_disposition: fault.retry.disposition,
+    };
+}
+function faultKindFromProviderSignal(signal) {
+    switch (signal.kind) {
+        case 'rate-limit': return 'rate-limit';
+        case 'auth': return 'auth';
+        case 'protocol': return 'protocol';
+        case 'context-overflow': return 'context-overflow';
+        case 'overloaded':
+        case 'overloaded-only':
+        case 'transient-http': return 'overloaded';
+        case 'connection':
+        case 'connection-only': return 'connection';
+        case 'socket':
+        case 'service-unavailable':
+        case 'other': return 'other';
+    }
+}
+function classifyDisposition(link, kind) {
+    if (kind === 'auth' || kind === 'protocol' || kind === 'context-overflow')
+        return 'fatal';
+    if (link === 'pi→provider') {
+        if (kind === 'connection' || kind === 'rate-limit' || kind === 'overloaded')
+            return 'auto';
+        return 'fatal';
+    }
+    return 'manual';
+}
+function rawText(raw) {
+    if (typeof raw === 'string')
+        return raw;
+    if (!isRecord(raw))
+        return '';
+    const candidates = [
+        raw['message'],
+        raw['errorMessage'],
+        raw['reason'],
+        raw['body'],
+        raw['statusText'],
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate !== '')
+            return candidate;
+    }
+    const nested = raw['error'];
+    if (isRecord(nested)) {
+        const nestedMessage = nested['message'];
+        if (typeof nestedMessage === 'string' && nestedMessage !== '')
+            return nestedMessage;
+        const nestedReason = nested['reason'];
+        if (typeof nestedReason === 'string' && nestedReason !== '')
+            return nestedReason;
+    }
+    return '';
+}
+export function classify(link, raw) {
+    // This diagnostic is the stable machine carrier for an all-managed-pools
+    // cooldown. Do not make its retryability depend on explanatory error prose.
+    if (link === 'pi→provider' && hasManagedProviderCoolingDiagnostic(raw)) {
+        return { kind: 'rate-limit', disposition: 'auto' };
+    }
+    const value = isRecord(raw) ? raw : {};
+    const failure = extractProviderFailureDetails(raw);
+    const nested = failure?.causes ?? [];
+    const signal = recognizeProviderError({
+        code: value['code'] ?? failure?.code ?? nested.find((cause) => cause.code !== undefined)?.code,
+        errno: value['errno'] ?? failure?.errno ?? nested.find((cause) => cause.errno !== undefined)?.errno,
+        status: value['status'] ?? failure?.status,
+        wsCloseCode: value['code'],
+        wsCloseReason: value['reason'],
+        message: [rawText(raw), failure?.body, ...nested.flatMap((cause) => [cause.message, cause.body])]
+            .filter((part) => typeof part === 'string' && part !== '')
+            .join(' '),
+    });
+    const kind = faultKindFromProviderSignal(signal);
+    return { kind, disposition: classifyDisposition(link, kind) };
+}

package/dist/core/provider-error-recognition.d.ts

@@ -0,0 +1,27 @@
+export type ProviderErrorSignalKind = 'rate-limit' | 'auth' | 'protocol' | 'context-overflow' | 'overloaded' | 'overloaded-only' | 'transient-http' | 'connection' | 'connection-only' | 'socket' | 'service-unavailable' | 'other';
+export type ProviderErrorMatchedOn = 'errno' | 'status' | 'websocket-close' | 'text' | 'none';
+export interface ProviderErrorTextMatch {
+    kind: ProviderErrorSignalKind;
+    match: string;
+}
+export interface ProviderErrorSignal {
+    kind: ProviderErrorSignalKind;
+    matchedOn: ProviderErrorMatchedOn;
+    status?: number;
+    retryAfterMs?: number;
+    match?: string;
+    textKind?: ProviderErrorSignalKind;
+    textMatch?: string;
+    textMatches?: readonly ProviderErrorTextMatch[];
+}
+export interface ProviderErrorRecognitionInput {
+    status?: unknown;
+    retryAfterMs?: number;
+    code?: unknown;
+    errno?: unknown;
+    wsCloseCode?: unknown;
+    wsCloseReason?: unknown;
+    message?: string;
+}
+/** Recognizes provider failure facts. Consumers apply their own retry policy. */
+export declare function recognizeProviderError(input: ProviderErrorRecognitionInput): ProviderErrorSignal;