@bridge4dev/runner 0.42.0 → 0.44.1

package/dist/adapters/error-policy.d.ts

@@ -0,0 +1,178 @@
+/**
+ * What a failed turn is allowed to do next — as DATA, not as branching (#252, #257).
+ *
+ * It lives beside `rate-limits.ts` and for the same reason: two CLIs describe the
+ * same class of accident in two vocabularies, a third provider is expected, and
+ * one table is easier to audit than two adapters' worth of `if`.
+ *
+ * ## How to read the table
+ *
+ * Every cause either CLI is known to report has its own row, including the ones
+ * that are never retried. Owner's instruction, 2026-08-16: the config should list
+ * them all with an explicit `retry: true | false`, so the answer to «why did the
+ * session not pick itself back up» is one line in one file rather than an absence.
+ *
+ * The dividing line is **whose fault it is**. Automatic retry is for failures that
+ * belong to the provider's own servers and have nothing to do with what the user
+ * asked for — a busy cluster, a 500, a dropped connection. Everything that depends
+ * on the account or the request — a dead key, an empty wallet, a refused policy, a
+ * context that no longer fits — is `retry: false` and stops the session, because
+ * asking again produces the same answer while burning tokens and, for policy and
+ * billing, sending a bad signal toward the account.
+ *
+ * ## The unit is the TURN, not the request
+ *
+ * The tempting table — «529 and 5xx are retryable» — is written for a single HTTP
+ * call. Ours is a turn: one turn is many calls, and by the time a 529 surfaces the
+ * agent may have run six rounds of tools, with a `git commit` and a `git push`
+ * already on disk. So a row here is a PERMISSION, never an instruction: the caller
+ * still has to ask «did this turn already do something» and narrow it. `refine()`
+ * below is that step, and it is not optional.
+ *
+ * ## Why codes and not sentences
+ *
+ * Both CLIs hand us a machine-readable cause and the runner used to throw it away.
+ * Sentences are not matched at all — see the note on `match`. We already have a
+ * scar from matching prose: `isAuthError` had to be strengthened because a bare
+ * `401` matched an MCP server's error and «unauthorized» contains «auth».
+ *
+ * ## Unknown means STOP
+ *
+ * A code that matches no row behaves exactly as it does today: the session stops
+ * and calls a human. The costs are wildly asymmetric — a wrong STOP costs one
+ * click, a wrong RETRY costs a second `git push`, a duplicated MCP write, tokens
+ * paid twice, and a transcript with duplicate tool_use ids (which is itself a 400
+ * that no retry can clear). It also makes an endless retry loop impossible by
+ * construction rather than by a counter someone might raise later.
+ */
+/** Verified against Claude Code CLI 2.1.233 and codex-cli 0.147.0 on 2026-08-16. */
+export type RetryBucket = 
+/** Nothing ran. The same turn may be sent again. */
+'retry'
+/** Work was partly done. Resume it; never re-send the prompt. */
+ | 'continue'
+/** A repeat cannot help. Stop and tell the person. */
+ | 'stop';
+export type BackoffProfile = 'standard' | 'slow';
+export interface ErrorRule {
+    /** Stable id — also the key the «same failure twice» guard compares. */
+    id: string;
+    provider: 'claude' | 'codex';
+    match: {
+        /** The provider's own machine-readable cause. */
+        codeIn?: readonly string[];
+        /** HTTP status, when the provider reported one. */
+        statusFrom?: number;
+        statusTo?: number;
+    };
+    /**
+     * The switch: may this cause EVER be retried automatically?
+     *
+     * `false` means today's behaviour — the session stops and asks for a person.
+     * Turning one on is a deliberate act with a reason written in `note`.
+     */
+    retry: boolean;
+    /** Read only when `retry` is true. */
+    bucket?: Exclude<RetryBucket, 'stop'>;
+    attempts?: number;
+    backoff?: BackoffProfile;
+    /**
+     * `false` → the row is INERT: counted, never acted on.
+     *
+     * How a provider we have not run yet gets into the table safely. Gemini and the
+     * Chinese providers are expected next, and several of them answer with HTTP 200
+     * and put the failure in the body, so their rows must not go live on a guess.
+     */
+    verified: boolean;
+    note: string;
+}
+/**
+ * The one place a provider is added, and the one place a retry is switched on.
+ *
+ * First match wins, so named causes precede status ranges.
+ */
+export declare const ERROR_RULES: readonly ErrorRule[];
+export interface FailureSignal {
+    provider: 'claude' | 'codex';
+    /**
+     * The provider's machine-readable cause — `assistant.error` for Claude,
+     * `codexErrorInfo` for Codex.
+     *
+     * **A decision can only start here or at `status`.** If both are absent the
+     * answer is `stop`, no matter what the text says.
+     */
+    code?: string | null;
+    /** HTTP status, when the provider reported one. */
+    status?: number | null;
+    /**
+     * The CLI's own sentence about the failure.
+     *
+     * Read in ONE direction: it can turn a `retry` into a `continue`, and it can
+     * never turn anything into a `retry`.
+     */
+    text?: string | null;
+    /** Did the turn emit anything at all before it broke — text, thinking, a tool call? */
+    produced?: boolean;
+    /** Did the turn run something a repeat cannot take back — git, or a write through MCP? */
+    irreversible?: boolean;
+}
+export interface RetryDecision {
+    bucket: RetryBucket;
+    attempts: number;
+    backoff: BackoffProfile;
+    /** Which row decided, or `null` when nothing matched and the default applied. */
+    ruleId: string | null;
+}
+/**
+ * What may this failure do next?
+ *
+ * First match wins. A row that is inert (`verified: false`) or switched off
+ * (`retry: false`) resolves to `stop` — but still reports its id, so the feed and
+ * the logs can say WHICH known cause stopped the session rather than «unknown».
+ */
+export declare function classifyFailure(signal: FailureSignal): RetryDecision;
+/**
+ * The ceiling no row can raise: total automatic retries in one session's life.
+ *
+ * Every other guard depends on the table being right. This one does not — it is
+ * arithmetic. If a code were misclassified, if a provider started answering with
+ * a cause we read wrongly, if two mechanisms both decided to retry, the session
+ * still cannot spin: after this many attempts it stops and asks for a person,
+ * exactly as it does today.
+ *
+ * Reset when a HUMAN sends a message, on the same reasoning as `clearAutoResume`:
+ * somebody typing into the session is the clearest possible evidence that the
+ * work is on track again.
+ */
+export declare const MAX_RETRIES_PER_SESSION = 12;
+/**
+ * Has this exact failure already been retried, and come straight back?
+ *
+ * Cheap insurance against a deterministic failure wearing a transient face — a
+ * context overflow surfacing as a 500, a malformed transcript that will fail
+ * identically forever. One repeat of the same row is enough to conclude the
+ * repeat is not helping, and spending the remaining attempts proves nothing.
+ */
+export declare function isRepeatOfSameFailure(previousRuleId: string | null | undefined, decision: RetryDecision): boolean;
+/**
+ * How long to wait before attempt `attempt` (1-based).
+ *
+ *   standard: max(10s, U(0, min(300s, 30s · 2^(n-1))))
+ *   slow:     max(30s, U(0, min(600s, 60s · 2^(n-1))))
+ *
+ * Full jitter, with a floor. The floor matters: pure full jitter can collapse to
+ * nearly zero, and a zero-length wait before restarting a process is pointless —
+ * the process takes longer than that to come up.
+ *
+ * The base is tens of seconds rather than one, because our attempt is not an HTTP
+ * request: it is a process re-reading a conversation, costing seconds and input
+ * tokens. By the time we see the failure at all, the CLI has already run its own
+ * retry ladder — `api_retry` reports up to ten of them — so answering that with
+ * another try one second later would just be noise.
+ *
+ * Jitter is not decoration: one machine runs several sessions and there are many
+ * machines, all watching the same API. Without it a recovering provider gets a
+ * synchronised volley from the whole fleet.
+ */
+export declare function retryDelayMs(profile: BackoffProfile, attempt: number, random?: () => number): number;
+//# sourceMappingURL=error-policy.d.ts.map

package/dist/adapters/error-policy.js

@@ -0,0 +1,370 @@
+/**
+ * What a failed turn is allowed to do next — as DATA, not as branching (#252, #257).
+ *
+ * It lives beside `rate-limits.ts` and for the same reason: two CLIs describe the
+ * same class of accident in two vocabularies, a third provider is expected, and
+ * one table is easier to audit than two adapters' worth of `if`.
+ *
+ * ## How to read the table
+ *
+ * Every cause either CLI is known to report has its own row, including the ones
+ * that are never retried. Owner's instruction, 2026-08-16: the config should list
+ * them all with an explicit `retry: true | false`, so the answer to «why did the
+ * session not pick itself back up» is one line in one file rather than an absence.
+ *
+ * The dividing line is **whose fault it is**. Automatic retry is for failures that
+ * belong to the provider's own servers and have nothing to do with what the user
+ * asked for — a busy cluster, a 500, a dropped connection. Everything that depends
+ * on the account or the request — a dead key, an empty wallet, a refused policy, a
+ * context that no longer fits — is `retry: false` and stops the session, because
+ * asking again produces the same answer while burning tokens and, for policy and
+ * billing, sending a bad signal toward the account.
+ *
+ * ## The unit is the TURN, not the request
+ *
+ * The tempting table — «529 and 5xx are retryable» — is written for a single HTTP
+ * call. Ours is a turn: one turn is many calls, and by the time a 529 surfaces the
+ * agent may have run six rounds of tools, with a `git commit` and a `git push`
+ * already on disk. So a row here is a PERMISSION, never an instruction: the caller
+ * still has to ask «did this turn already do something» and narrow it. `refine()`
+ * below is that step, and it is not optional.
+ *
+ * ## Why codes and not sentences
+ *
+ * Both CLIs hand us a machine-readable cause and the runner used to throw it away.
+ * Sentences are not matched at all — see the note on `match`. We already have a
+ * scar from matching prose: `isAuthError` had to be strengthened because a bare
+ * `401` matched an MCP server's error and «unauthorized» contains «auth».
+ *
+ * ## Unknown means STOP
+ *
+ * A code that matches no row behaves exactly as it does today: the session stops
+ * and calls a human. The costs are wildly asymmetric — a wrong STOP costs one
+ * click, a wrong RETRY costs a second `git push`, a duplicated MCP write, tokens
+ * paid twice, and a transcript with duplicate tool_use ids (which is itself a 400
+ * that no retry can clear). It also makes an endless retry loop impossible by
+ * construction rather than by a counter someone might raise later.
+ */
+/**
+ * The one place a provider is added, and the one place a retry is switched on.
+ *
+ * First match wins, so named causes precede status ranges.
+ */
+export const ERROR_RULES = [
+    // ══ Claude — `assistant.error` / `api_retry.error`, a closed enum of ten ══
+    // ── Their servers. Retried. ──
+    {
+        id: 'claude.overloaded',
+        provider: 'claude',
+        match: { codeIn: ['overloaded'] },
+        retry: true,
+        bucket: 'retry',
+        attempts: 5,
+        backoff: 'slow',
+        verified: true,
+        note: '529. Their cluster is busy; nothing to do with this session. The reason #252 exists.',
+    },
+    {
+        id: 'claude.server_error',
+        provider: 'claude',
+        match: { codeIn: ['server_error'] },
+        retry: true,
+        bucket: 'retry',
+        attempts: 5,
+        backoff: 'slow',
+        verified: true,
+        note: '500/502/503 on their side. Same weather, same treatment.',
+    },
+    // ── The account or the request. Never retried. ──
+    {
+        id: 'claude.rate_limit',
+        provider: 'claude',
+        match: { codeIn: ['rate_limit'] },
+        retry: false,
+        verified: true,
+        note: 'A 429 is not their servers failing — it is this account being asked to slow down, and on ' +
+            'a subscription it usually means the plan window is spent. That case already has a better ' +
+            'answer than a repeat: the session pauses until the window reopens (#258). Retrying into ' +
+            'a limit changes nothing and hammering one is how a longer one is earned.',
+    },
+    {
+        id: 'claude.authentication_failed',
+        provider: 'claude',
+        match: { codeIn: ['authentication_failed'] },
+        retry: false,
+        verified: true,
+        note: 'The login is gone or rejected. A person has to sign in; a repeat cannot.',
+    },
+    {
+        id: 'claude.oauth_org_not_allowed',
+        provider: 'claude',
+        match: { codeIn: ['oauth_org_not_allowed'] },
+        retry: false,
+        verified: true,
+        note: 'The organization is not permitted. An administrative answer, not a transient one.',
+    },
+    {
+        id: 'claude.billing_error',
+        provider: 'claude',
+        match: { codeIn: ['billing_error'] },
+        retry: false,
+        verified: true,
+        note: 'Empty wallet. Repeating a declined charge helps nobody and looks bad on the account.',
+    },
+    {
+        id: 'claude.invalid_request',
+        provider: 'claude',
+        match: { codeIn: ['invalid_request'] },
+        retry: false,
+        verified: true,
+        note: 'The API refused the request itself. Deterministic — it will refuse the identical request ' +
+            'identically. Often a malformed transcript, which a repeat can only make worse.',
+    },
+    {
+        id: 'claude.model_not_found',
+        provider: 'claude',
+        match: { codeIn: ['model_not_found'] },
+        retry: false,
+        verified: true,
+        note: 'The chosen model does not exist for this account. A settings problem.',
+    },
+    {
+        id: 'claude.max_output_tokens',
+        provider: 'claude',
+        match: { codeIn: ['max_output_tokens'] },
+        retry: false,
+        verified: true,
+        note: 'The answer hit its own ceiling. Nothing failed on their side, and the same turn would hit ' +
+            'the same ceiling again.',
+    },
+    {
+        id: 'claude.unknown',
+        provider: 'claude',
+        match: { codeIn: ['unknown'] },
+        retry: false,
+        verified: true,
+        note: 'The CLI could not name the cause either. Listed rather than left to the default so that ' +
+            'reading the table answers the question, and so nobody later mistakes silence for an ' +
+            'oversight and «fixes» it into a retry.',
+    },
+    // ══ Codex — `turn.error.codexErrorInfo`, plus the HTTP status when given ══
+    // ── Their servers. Retried. ──
+    {
+        id: 'codex.http_connection',
+        provider: 'codex',
+        match: { codeIn: ['httpConnectionFailed'] },
+        retry: true,
+        bucket: 'retry',
+        attempts: 3,
+        backoff: 'standard',
+        verified: true,
+        note: 'The request never landed. Narrowed to «resume» by the guard if the turn had begun.',
+    },
+    {
+        id: 'codex.stream_connection',
+        provider: 'codex',
+        match: { codeIn: ['responseStreamConnectionFailed'] },
+        retry: true,
+        bucket: 'continue',
+        attempts: 1,
+        backoff: 'standard',
+        verified: true,
+        note: 'The stream died after it had started — the same shape as Claude’s «mid-response». Resumed, ' +
+            'never re-sent: work may already be on disk.',
+    },
+    {
+        id: 'codex.http_5xx',
+        provider: 'codex',
+        match: { statusFrom: 500, statusTo: 599 },
+        retry: true,
+        bucket: 'retry',
+        attempts: 5,
+        backoff: 'slow',
+        verified: true,
+        note: 'Their side. Matched after the named causes so a code always wins over a number.',
+    },
+    // ── The account, the request, or the content. Never retried. ──
+    {
+        id: 'codex.usage_limit',
+        provider: 'codex',
+        match: { codeIn: ['usageLimitExceeded'] },
+        retry: false,
+        verified: true,
+        note: 'Out of plan. That is a pause until the window reopens (#258), not a repeat.',
+    },
+    {
+        id: 'codex.session_budget',
+        provider: 'codex',
+        match: { codeIn: ['sessionBudgetExceeded'] },
+        retry: false,
+        verified: true,
+        note: 'The session spent the budget it was given. Raising it is a human decision.',
+    },
+    {
+        id: 'codex.context_window',
+        provider: 'codex',
+        match: { codeIn: ['contextWindowExceeded'] },
+        retry: false,
+        verified: true,
+        note: 'The conversation no longer fits. Deterministic: the identical turn overflows identically. ' +
+            'The remedy is a compact, and choosing to compact is not ours to make silently.',
+    },
+    {
+        id: 'codex.policy',
+        provider: 'codex',
+        match: { codeIn: ['cyberPolicy'] },
+        retry: false,
+        verified: true,
+        note: 'Refused on content policy — about what was asked, not about their weather. Re-sending a ' +
+            'refused request is the one repeat that actively harms the account.',
+    },
+    {
+        id: 'codex.http_4xx',
+        provider: 'codex',
+        match: { statusFrom: 400, statusTo: 499 },
+        retry: false,
+        verified: true,
+        note: 'Our request, not their servers. 429 included: Codex does not honour Retry-After, so a ' +
+            'repeat is pure noise.',
+    },
+];
+const DEFAULT_DECISION = {
+    bucket: 'stop',
+    attempts: 0,
+    backoff: 'standard',
+    ruleId: null,
+};
+function matches(rule, signal) {
+    if (rule.provider !== signal.provider)
+        return false;
+    const { codeIn, statusFrom, statusTo } = rule.match;
+    if (codeIn) {
+        return signal.code !== null && signal.code !== undefined && codeIn.includes(signal.code);
+    }
+    if (statusFrom !== undefined && statusTo !== undefined) {
+        return (signal.status !== null &&
+            signal.status !== undefined &&
+            signal.status >= statusFrom &&
+            signal.status <= statusTo);
+    }
+    return false;
+}
+/** Phrases with which the CLI says «the answer above is partial». */
+const PARTIAL_PHRASES = ['may be incomplete', 'mid-response'];
+/**
+ * Tighten a permission to fit what the turn actually did.
+ *
+ * Strictly one-way: every branch either keeps the bucket or makes it more
+ * cautious, and nothing here can produce a `retry`. Being too careful costs the
+ * agent a look at its own work; being too bold costs a second `git push`.
+ * `auto-resume.ts` records what the bold version felt like — a re-sent prompt
+ * ran a fifteen-minute command twice, four minutes apart.
+ */
+function refine(bucket, signal) {
+    // Something irreversible already happened this turn. Neither repeating nor
+    // resuming is safe enough to do without a person looking.
+    if (signal.irreversible === true)
+        return 'stop';
+    // Work was produced, so «send it again» is off the table whatever the cause says.
+    if (signal.produced === true && bucket === 'retry')
+        return 'continue';
+    // The CLI said the answer above is partial. It is allowed to make us more
+    // careful even when we counted no output ourselves — the phase it reports is
+    // its own, and it knows things our counting does not.
+    if (bucket === 'retry') {
+        const text = signal.text ?? '';
+        if (PARTIAL_PHRASES.some((phrase) => text.includes(phrase)))
+            return 'continue';
+    }
+    return bucket;
+}
+/**
+ * What may this failure do next?
+ *
+ * First match wins. A row that is inert (`verified: false`) or switched off
+ * (`retry: false`) resolves to `stop` — but still reports its id, so the feed and
+ * the logs can say WHICH known cause stopped the session rather than «unknown».
+ */
+export function classifyFailure(signal) {
+    // No machine-readable cause, no retry. This is the single most important line
+    // in the file: it is what makes it impossible for a sentence — an agent's own
+    // prose, a quoted error in a report, a document about this feature — to start
+    // a retry. Text only ever narrows a decision that a code already opened.
+    const hasCode = signal.code !== null && signal.code !== undefined && signal.code !== '';
+    const hasStatus = signal.status !== null && signal.status !== undefined;
+    if (!hasCode && !hasStatus)
+        return DEFAULT_DECISION;
+    for (const rule of ERROR_RULES) {
+        if (!matches(rule, signal))
+            continue;
+        if (!rule.verified || !rule.retry) {
+            return { ...DEFAULT_DECISION, ruleId: rule.id };
+        }
+        const bucket = refine(rule.bucket ?? 'retry', signal);
+        return {
+            bucket,
+            // A narrowed permission also loses the generous allowance: resuming replays
+            // context and can still double an effect if the agent misjudges what it did.
+            attempts: bucket === 'stop' ? 0 : bucket === 'continue' ? 1 : Math.max(0, rule.attempts ?? 0),
+            backoff: rule.backoff ?? 'standard',
+            ruleId: rule.id,
+        };
+    }
+    return DEFAULT_DECISION;
+}
+/**
+ * The ceiling no row can raise: total automatic retries in one session's life.
+ *
+ * Every other guard depends on the table being right. This one does not — it is
+ * arithmetic. If a code were misclassified, if a provider started answering with
+ * a cause we read wrongly, if two mechanisms both decided to retry, the session
+ * still cannot spin: after this many attempts it stops and asks for a person,
+ * exactly as it does today.
+ *
+ * Reset when a HUMAN sends a message, on the same reasoning as `clearAutoResume`:
+ * somebody typing into the session is the clearest possible evidence that the
+ * work is on track again.
+ */
+export const MAX_RETRIES_PER_SESSION = 12;
+/**
+ * Has this exact failure already been retried, and come straight back?
+ *
+ * Cheap insurance against a deterministic failure wearing a transient face — a
+ * context overflow surfacing as a 500, a malformed transcript that will fail
+ * identically forever. One repeat of the same row is enough to conclude the
+ * repeat is not helping, and spending the remaining attempts proves nothing.
+ */
+export function isRepeatOfSameFailure(previousRuleId, decision) {
+    return (previousRuleId !== null &&
+        previousRuleId !== undefined &&
+        decision.ruleId !== null &&
+        previousRuleId === decision.ruleId);
+}
+/**
+ * How long to wait before attempt `attempt` (1-based).
+ *
+ *   standard: max(10s, U(0, min(300s, 30s · 2^(n-1))))
+ *   slow:     max(30s, U(0, min(600s, 60s · 2^(n-1))))
+ *
+ * Full jitter, with a floor. The floor matters: pure full jitter can collapse to
+ * nearly zero, and a zero-length wait before restarting a process is pointless —
+ * the process takes longer than that to come up.
+ *
+ * The base is tens of seconds rather than one, because our attempt is not an HTTP
+ * request: it is a process re-reading a conversation, costing seconds and input
+ * tokens. By the time we see the failure at all, the CLI has already run its own
+ * retry ladder — `api_retry` reports up to ten of them — so answering that with
+ * another try one second later would just be noise.
+ *
+ * Jitter is not decoration: one machine runs several sessions and there are many
+ * machines, all watching the same API. Without it a recovering provider gets a
+ * synchronised volley from the whole fleet.
+ */
+export function retryDelayMs(profile, attempt, random = Math.random) {
+    const floor = profile === 'slow' ? 30_000 : 10_000;
+    const base = profile === 'slow' ? 60_000 : 30_000;
+    const cap = profile === 'slow' ? 600_000 : 300_000;
+    const ceiling = Math.min(cap, base * 2 ** Math.max(0, attempt - 1));
+    return Math.max(floor, Math.round(random() * ceiling));
+}
+//# sourceMappingURL=error-policy.js.map

package/dist/adapters/rate-limits.d.ts

@@ -37,4 +37,26 @@ export declare function rateWindowKeyFromMinutes(minutes: number | null): AgentR
  * reads as «nothing spent» and is the safe end: it never invents a warning.
  */
 export declare function clampPercent(value: number): number;
+/**
+ * Claude's `utilization` is a FRACTION (0–1), not a percentage.
+ *
+ * This cost the owner a wrong number on screen: a weekly window truly at 95%
+ * flipped to «1%» for a minute or two whenever an event carried the field, and
+ * the next `/usage` probe put 95 back. `clampPercent(0.95)` is 0.95, and the
+ * panel rounds that to 1.
+ *
+ * The scale is not documented — `utilization?: number` is all the SDK types
+ * say — so it was read out of the shipped CLI binary (2.1.233), where the
+ * warning thresholds are:
+ *
+ *   five_hour: [{utilization: 0.9}]
+ *   seven_day: [{utilization: 0.75}, {utilization: 0.5}, {utilization: 0.25}]
+ *
+ * plus a bare `utilization < 0.7`. A field measured in percent would not be
+ * compared against 0.25 to mean «a quarter spent».
+ *
+ * `/usage` is the other unit and needs no conversion: its text prints `52% used`
+ * and `parseUsageText` already yields 52. One place converts, and it is this one.
+ */
+export declare function percentFromUtilization(utilization: number): number;
 //# sourceMappingURL=rate-limits.d.ts.map

package/dist/adapters/rate-limits.js

@@ -56,4 +56,28 @@ export function clampPercent(value) {
         return 0;
     return Math.min(100, Math.max(0, value));
 }
+/**
+ * Claude's `utilization` is a FRACTION (0–1), not a percentage.
+ *
+ * This cost the owner a wrong number on screen: a weekly window truly at 95%
+ * flipped to «1%» for a minute or two whenever an event carried the field, and
+ * the next `/usage` probe put 95 back. `clampPercent(0.95)` is 0.95, and the
+ * panel rounds that to 1.
+ *
+ * The scale is not documented — `utilization?: number` is all the SDK types
+ * say — so it was read out of the shipped CLI binary (2.1.233), where the
+ * warning thresholds are:
+ *
+ *   five_hour: [{utilization: 0.9}]
+ *   seven_day: [{utilization: 0.75}, {utilization: 0.5}, {utilization: 0.25}]
+ *
+ * plus a bare `utilization < 0.7`. A field measured in percent would not be
+ * compared against 0.25 to mean «a quarter spent».
+ *
+ * `/usage` is the other unit and needs no conversion: its text prints `52% used`
+ * and `parseUsageText` already yields 52. One place converts, and it is this one.
+ */
+export function percentFromUtilization(utilization) {
+    return clampPercent(utilization * 100);
+}
 //# sourceMappingURL=rate-limits.js.map

package/dist/adapters/types.d.ts

@@ -479,6 +479,36 @@ export type AgentEvent = {
      * for a window to open, which is what «waiting» means.
      */
     limitBlocked?: boolean;
+    /**
+     * Why it failed, in the provider's own machine-readable vocabulary (#252).
+     *
+     * Carried because the cause and the ending arrive on DIFFERENT messages:
+     * Claude puts the closed enum on the assistant message (`assistant.error`)
+     * and closes the turn with a separate `result`, which has no such field.
+     * The adapter remembers the last one it saw for the turn and hands it over
+     * here, so the supervisor can decide without re-reading the transcript or
+     * guessing from prose.
+     *
+     * Absent means «no machine-readable cause», which `classifyFailure` reads
+     * as «stop» — today's behaviour. Never inferred from text.
+     */
+    failureCode?: string;
+    /** HTTP status, when the provider named one alongside the cause. */
+    failureStatus?: number;
+    /**
+     * Did this turn put anything at all on the wire before it broke — a text
+     * block, a thought, a tool call?
+     *
+     * The discriminator #257 turns on. `false` means the turn is safe to send
+     * again; `true` means files may already be written and commands already
+     * run, so it may only be RESUMED.
+     */
+    produced?: boolean;
+    /**
+     * Did this turn run something a repeat cannot take back — git, or a write
+     * through MCP? Narrows even «resume» down to «ask a person».
+     */
+    irreversible?: boolean;
 } | {
     type: 'error';
     message: string;