@gaunt-sloth/core 2.0.0-beta.3 → 2.0.0-beta.4

package/dist/core/terminationReason.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @packageDocumentation
+ * EXT-159 — the typed reason a run ended.
+ *
+ * A run can stop for a dozen unrelated causes — a rate limit, a provider-side fault, a full context
+ * window, a content-policy refusal, the approvals gate, a tool-error budget, the user pressing Esc
+ * — and every one of them used to reach the surface as one untyped sentence. This module is the
+ * single taxonomy those causes are classified into, so the fact "why did this end" is carried as a
+ * value rather than reconstructed from prose.
+ *
+ * **Two feeders converge here, and they are not interchangeable.**
+ *
+ * - A **metadata reader** (`detectStopMetadata` in `core/refusal.ts`, called from
+ *   `GthAbstractAgent`) handles reasons that arrive *on a message* — a stop/finish reason in
+ *   `response_metadata` or
+ *   `additional_kwargs`. It sits at that layer because that is the only place the metadata is
+ *   visible.
+ * - An **exception classifier** ({@link classifyThrownTermination}, called from the runner's
+ *   catches) handles reasons that arrive as a *thrown error*. Those are not in `response_metadata`
+ *   at all, so no metadata reader can ever see them.
+ *
+ * Built as one metadata reader the whole thrown-error half of the class falls outside it; built as
+ * two taxonomies every consumer grows its own. Hence: two feeders, one taxonomy.
+ *
+ * **Retryability is two facts, never a boolean.** `@langchain/core` exports a typed
+ * `ContextOverflowError` that stamps itself non-retryable in its own constructor. That is right for
+ * "send the same prompt again" and exactly backwards for the remedy this cause actually has, which
+ * is to send a *smaller* one. {@link GthTerminationReason} therefore carries
+ * {@link GthTerminationReason#retryableAsIs} and
+ * {@link GthTerminationReason#retryableAfterRemedy} separately, with the remedy named.
+ *
+ * Classification only. Nothing here surfaces anything, formats anything, or changes what a run
+ * does; the user-facing strings stay where they are and keep their own wording.
+ */
+/**
+ * What ended the run, as one closed vocabulary shared by every site and every consumer.
+ *
+ * Members are causes, not messages: two sites that stop for the same reason report the same
+ * category and are told apart by {@link GthTerminationSite}.
+ */
+export type GthTerminationCategory = 
+/** The model finished of its own accord — the ordinary end of a turn. */
+'completed'
+/** The turn produced no content at all (no refusal, no error, nothing). */
+ | 'empty_response'
+/** The model or the provider's safety system declined to answer. */
+ | 'content_refusal'
+/** The answer was cut off against the output cap rather than finished. */
+ | 'output_truncated'
+/** Prompt plus history exceeded the model's input window. */
+ | 'context_overflow'
+/** The provider refused for rate/quota reasons (HTTP 429). */
+ | 'rate_limited'
+/** Credentials were missing, wrong or unauthorised (HTTP 401/403). */
+ | 'auth_failed'
+/** The provider rejected the request itself (HTTP 400) for a reason retrying cannot change. */
+ | 'invalid_request'
+/** A fault on the provider's side (HTTP 5xx, "internal error during token generation"). */
+ | 'provider_error'
+/** The request never completed at the transport level. */
+ | 'network_error'
+/** A deadline elapsed before the run finished. */
+ | 'timeout'
+/** The user stopped it — Esc, a cancelled signal, a closed client. */
+ | 'cancelled'
+/** The approvals gate deliberately ended the run. */
+ | 'approval_stop'
+/** The tool-error budget ended the run rather than spend another model call. */
+ | 'tool_error_budget'
+/** The tool-loop guard ended a no-progress identical-call loop. */
+ | 'tool_loop_guard'
+/**
+ * The tool-approval interrupt drain gave up: the graph re-suspended on a gated tool call more
+ * times in one turn than the drain loop is willing to resume, so the RUNTIME ended the turn.
+ *
+ * Deliberately not `recursion_limit`, which states that the graph hit *its* recursion limit — a
+ * different bound, owned by LangGraph, with a different knob. Reporting one for the other would
+ * be the same false-category defect this taxonomy exists to remove, and `site` is what separates
+ * the two surfaces this bound has.
+ */
+ | 'interrupt_drain_guard'
+/** A tool threw, and the failure ended the turn. */
+ | 'tool_error'
+/** The graph suspended on an `interrupt()` and is waiting to be resumed. */
+ | 'suspended'
+/** The graph hit its recursion limit. */
+ | 'recursion_limit'
+/** The consumer stopped consuming the turn before it ended. */
+ | 'abandoned'
+/** Nothing in the taxonomy matched — recorded as such rather than guessed at. */
+ | 'unknown';
+/**
+ * Where the classification was made, as a stable identifier per termination site.
+ *
+ * The site is a distinct fact from the category: several sites classify into the same category (the
+ * runner's two exception wrappers both report whatever the classifier says), and several categories
+ * can be reported from one site (an aborted stream and a suspended graph leave `streamWithEvents`
+ * at the same place). Diagnosis needs both.
+ */
+export type GthTerminationSite = 
+/** `GthAgentRunner.processMessages` returned an answer. */
+'runner.completed'
+/** The streamed turn was empty and the non-streaming fallback was empty too. */
+ | 'runner.empty-after-fallback'
+/** The non-streaming turn produced no content. */
+ | 'runner.empty-invoke'
+/** An approvals stop re-thrown out of the stream drain. */
+ | 'runner.stream-approval-stop'
+/** An approvals stop re-thrown out of the turn. */
+ | 'runner.turn-approval-stop'
+/** The stream drain threw. */
+ | 'runner.stream-error'
+/** The turn threw. */
+ | 'runner.turn-error'
+/** The string path's tool-approval drain ran out of resume rounds. */
+ | 'runner.interrupt-guard-exhausted'
+/** `GthAgentRunner.processMessagesWithEvents` drained its stream to the end. */
+ | 'runner.events-completed'
+/** The typed-event turn ended having yielded no answer text at all. */
+ | 'runner.events-empty'
+/** The typed-event turn ended because its signal was aborted. */
+ | 'runner.events-cancelled'
+/** The typed-event turn threw. */
+ | 'runner.events-error'
+/** The consumer stopped consuming the typed-event turn before it ended. */
+ | 'runner.events-abandoned'
+/** The typed-event path's tool-approval drain ran out of resume rounds. */
+ | 'runner.events-interrupt-guard-exhausted'
+/** The metadata reader fired on the non-streaming `invoke` path. */
+ | 'agent.invoke-stop-metadata'
+/** The metadata reader fired on the string-streaming path. */
+ | 'agent.stream-stop-metadata'
+/** The metadata reader fired on the typed-event path. */
+ | 'agent.events-stop-metadata'
+/** A `ToolException` was turned into the turn's answer on the `invoke` path. */
+ | 'agent.invoke-tool-exception'
+/** The string-streaming path ended on Esc / an abort. */
+ | 'agent.stream-cancelled'
+/** `streamWithEvents` ended on a suspend or an abort. */
+ | 'agent.events-ended'
+/** `streamWithEventsResume` ended on a suspend or an abort. */
+ | 'agent.events-resume-ended'
+/** The tool-error budget's `jumpTo: 'end'`. */
+ | 'middleware.tool-error-budget'
+/** The tool-loop guard's `jumpTo: 'end'`. */
+ | 'middleware.tool-loop-guard';
+/**
+ * Which feeder produced the classification.
+ *
+ * `metadata` — read off a message's stop/finish reason. `exception` — classified from a thrown
+ * error. `control` — the runtime itself decided to end the run (a gate, a middleware, a
+ * cancellation, an ordinary completion), so there was nothing to classify.
+ */
+export type GthTerminationSource = 'metadata' | 'exception' | 'control';
+/**
+ * What would have to change before a retry is worth making.
+ *
+ * Named rather than implied, because {@link GthTerminationReason#retryableAfterRemedy} is only
+ * actionable if a consumer knows *which* remedy it is being told about.
+ */
+export type GthTerminationRemedy = 
+/** Send less: compact the history, drop context, summarise. */
+'reduce-context'
+/** Wait, then send the same thing again. */
+ | 'back-off'
+/** Send something different — rephrase, narrow, change approach. */
+ | 'change-request'
+/** Send it to a different model. */
+ | 'change-model'
+/** Repair credentials or configuration first. */
+ | 'fix-credentials'
+/** Nothing is wrong: the run is parked and can be continued where it stopped. */
+ | 'resume';
+/**
+ * The retry posture of a category — the two facts, plus the remedy the second one refers to.
+ *
+ * **Posture is per-CATEGORY, so anything acting on a reason must read its `site` as well.** One
+ * table decides the posture precisely so no site can invent its own, and the price of that is that
+ * the table cannot know how far a given site already got. The standing example is
+ * `empty_response`, which is `retryableAsIs: true` because an empty turn usually is worth asking
+ * again — yet `runner.empty-after-fallback` is reached only *because* that as-is retry was already
+ * spent, while `runner.events-empty` is reached with it never spent at all. A consumer reading the
+ * posture flags alone would retry the first of those a second time.
+ */
+export interface GthTerminationPosture {
+    /** Is sending the identical request again a sane thing to do? */
+    retryableAsIs: boolean;
+    /** Is sending it again worthwhile once {@link remedy} has been applied? */
+    retryableAfterRemedy: boolean;
+    /** The change that makes {@link retryableAfterRemedy} true; absent when it is `false`. */
+    remedy?: GthTerminationRemedy;
+}
+/** The retry posture of a category. */
+export declare function terminationPosture(category: GthTerminationCategory): GthTerminationPosture;
+/** Why a run ended, as one value. */
+export interface GthTerminationReason extends GthTerminationPosture {
+    /** The taxonomy member. */
+    category: GthTerminationCategory;
+    /** The site that classified it. */
+    site: GthTerminationSite;
+    /** Which feeder classified it. */
+    source: GthTerminationSource;
+    /** Provider family, where the classification knew one. */
+    provider?: string;
+    /**
+     * The raw token the classification was made from — a `finish_reason`, a `stop_reason`, an error
+     * name or status. Diagnostic detail, never the carrier of the classification itself.
+     */
+    detail?: string;
+}
+/**
+ * [[EXT-159]] — one observation of what the provider said about why a model message stopped.
+ *
+ * Recorded per finished model message, on every path, whether or not the provider said anything.
+ * No `finish_reason` was written to any log anywhere before this, so the artifact a maintainer
+ * reaches for first could not answer the question it exists to answer — and a turn where the
+ * provider stayed silent looked exactly like one that ended normally.
+ *
+ * **The absence is the observation.** `token: null` states that the message carried no stop or
+ * finish reason at all; it is never a stand-in for one, and no observation is invented for a
+ * message that was never seen.
+ */
+export interface GthFinishReasonObservation {
+    /** When the message was observed, as an ISO instant with a zone. */
+    at: string;
+    /** Which of the agent's three paths produced the message. */
+    path: 'invoke' | 'stream' | 'events';
+    /** The provider's raw token, lower-cased — or `null` when the message carried none. */
+    token: string | null;
+}
+/** The classification a feeder produces, before a site is attached to it. */
+export interface GthTerminationClassification {
+    category: GthTerminationCategory;
+    provider?: string;
+    detail?: string;
+}
+/**
+ * Build a {@link GthTerminationReason}: attach a site and a feeder to a classification and fill in
+ * the posture from the one table. Every site builds through here, so no site can invent a posture.
+ */
+export declare function terminationReason(site: GthTerminationSite, source: GthTerminationSource, classification: GthTerminationCategory | GthTerminationClassification): GthTerminationReason;
+/**
+ * Whether a thrown value is a context overflow.
+ *
+ * The predicate is `ContextOverflowError.isInstance`, never `lc_error_code`: the code is set
+ * asymmetrically across providers (Anthropic stamps both the class and the code, OpenAI only the
+ * class), so keying on it silently misses most of where the typed class actually works. The
+ * substring fallback then covers the providers LangChain does not type at all, and the case where
+ * a reworded provider message drops the class.
+ */
+export declare function isContextOverflow(error: unknown): boolean;
+/**
+ * The exception feeder: classify a thrown value into the taxonomy.
+ *
+ * Order matters. The typed and named cases are decided first, because a context overflow is also an
+ * HTTP 400 and an abort is also a `DOMException`; only once those are excluded does the status code
+ * and then the prose get a say. Never throws: an unclassifiable value is `unknown`, which is a
+ * recorded fact rather than a guess.
+ */
+export declare function classifyThrownTermination(error: unknown): GthTerminationClassification;
+/**
+ * Attach a reason to a thrown value and return it, so a `throw` site reads as one expression.
+ *
+ * Non-enumerable, so the reason never widens what an error serialises to (a logged or
+ * JSON-stringified error keeps exactly the shape it had), and first-write-wins so a re-throw
+ * through an outer wrapper cannot overwrite the inner, truer classification. Fail-soft: a frozen or
+ * primitive throw value is returned unchanged rather than turning a failure into a different one.
+ */
+export declare function attachTerminationReason<T>(error: T, reason: GthTerminationReason): T;
+/** The reason attached to a thrown value, following one `cause` link. Undefined when none is. */
+export declare function terminationReasonOf(error: unknown): GthTerminationReason | undefined;

package/dist/core/terminationReason.js

@@ -0,0 +1,405 @@
+/**
+ * @packageDocumentation
+ * EXT-159 — the typed reason a run ended.
+ *
+ * A run can stop for a dozen unrelated causes — a rate limit, a provider-side fault, a full context
+ * window, a content-policy refusal, the approvals gate, a tool-error budget, the user pressing Esc
+ * — and every one of them used to reach the surface as one untyped sentence. This module is the
+ * single taxonomy those causes are classified into, so the fact "why did this end" is carried as a
+ * value rather than reconstructed from prose.
+ *
+ * **Two feeders converge here, and they are not interchangeable.**
+ *
+ * - A **metadata reader** (`detectStopMetadata` in `core/refusal.ts`, called from
+ *   `GthAbstractAgent`) handles reasons that arrive *on a message* — a stop/finish reason in
+ *   `response_metadata` or
+ *   `additional_kwargs`. It sits at that layer because that is the only place the metadata is
+ *   visible.
+ * - An **exception classifier** ({@link classifyThrownTermination}, called from the runner's
+ *   catches) handles reasons that arrive as a *thrown error*. Those are not in `response_metadata`
+ *   at all, so no metadata reader can ever see them.
+ *
+ * Built as one metadata reader the whole thrown-error half of the class falls outside it; built as
+ * two taxonomies every consumer grows its own. Hence: two feeders, one taxonomy.
+ *
+ * **Retryability is two facts, never a boolean.** `@langchain/core` exports a typed
+ * `ContextOverflowError` that stamps itself non-retryable in its own constructor. That is right for
+ * "send the same prompt again" and exactly backwards for the remedy this cause actually has, which
+ * is to send a *smaller* one. {@link GthTerminationReason} therefore carries
+ * {@link GthTerminationReason#retryableAsIs} and
+ * {@link GthTerminationReason#retryableAfterRemedy} separately, with the remedy named.
+ *
+ * Classification only. Nothing here surfaces anything, formats anything, or changes what a run
+ * does; the user-facing strings stay where they are and keep their own wording.
+ */
+import { ContextOverflowError } from '@langchain/core/errors';
+/**
+ * The single posture table.
+ *
+ * One place decides what a category means for retrying, so the three consumers this taxonomy exists
+ * for — a retry posture, a "never retry a 400, a 429 is a different case" ruling, a nudge-or-back-off
+ * decision — read the same answer instead of each deriving its own.
+ */
+const POSTURE = {
+    // Nothing went wrong; there is nothing to retry.
+    completed: { retryableAsIs: false, retryableAfterRemedy: false },
+    // The one cause the runtime already retries as-is, and it is right to: an empty turn is usually
+    // transient. A model that keeps returning nothing needs a different model, not another attempt.
+    empty_response: { retryableAsIs: true, retryableAfterRemedy: true, remedy: 'change-model' },
+    // A refusal is deterministic for the same input, so the same prompt refuses again.
+    content_refusal: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    // The answer was cut off, not refused: asking for less, or for a continuation, gets the rest.
+    output_truncated: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    // THE case the two fields exist for. `ContextOverflowError.getRetryable()` is false, which is
+    // right for the same prompt and exactly wrong for the smaller one compaction exists to send.
+    context_overflow: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'reduce-context' },
+    // A 429 answered immediately is a 429 again; waiting is the whole remedy.
+    rate_limited: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'back-off' },
+    auth_failed: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'fix-credentials' },
+    // A rejected request is rejected identically every time, and a repaired request is a new request
+    // rather than a retry — so neither field is true and no remedy is named.
+    invalid_request: { retryableAsIs: false, retryableAfterRemedy: false },
+    // A provider-side fault is the transient case: the same request often succeeds on the next try.
+    provider_error: { retryableAsIs: true, retryableAfterRemedy: true, remedy: 'back-off' },
+    network_error: { retryableAsIs: true, retryableAfterRemedy: true, remedy: 'back-off' },
+    timeout: { retryableAsIs: true, retryableAfterRemedy: true, remedy: 'back-off' },
+    // The user chose to stop. Retrying without being asked overrides the one decision they made.
+    cancelled: { retryableAsIs: false, retryableAfterRemedy: false },
+    // The gate refused. Re-running the refused command automatically is the failure the gate exists
+    // to prevent, so neither field offers it.
+    approval_stop: { retryableAsIs: false, retryableAfterRemedy: false },
+    // Both guards end a loop that is going nowhere. Repeating it goes nowhere again; a changed
+    // approach is exactly what each guard's own notice asks the model for.
+    tool_error_budget: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    tool_loop_guard: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    // The same turn re-suspends the same way, so repeating it exhausts the same bound. Asking for
+    // less gated work in one turn is what gets under it.
+    interrupt_drain_guard: {
+        retryableAsIs: false,
+        retryableAfterRemedy: true,
+        remedy: 'change-request',
+    },
+    tool_error: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    // Not a failure at all: the run is parked mid-flight and continues where it stopped.
+    suspended: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'resume' },
+    recursion_limit: { retryableAsIs: false, retryableAfterRemedy: true, remedy: 'change-request' },
+    abandoned: { retryableAsIs: false, retryableAfterRemedy: false },
+    // Unclassified is not "probably fine": nothing is known, so nothing is offered.
+    unknown: { retryableAsIs: false, retryableAfterRemedy: false },
+};
+/** The retry posture of a category. */
+export function terminationPosture(category) {
+    return POSTURE[category] ?? POSTURE.unknown;
+}
+/**
+ * Build a {@link GthTerminationReason}: attach a site and a feeder to a classification and fill in
+ * the posture from the one table. Every site builds through here, so no site can invent a posture.
+ */
+export function terminationReason(site, source, classification) {
+    const resolved = typeof classification === 'string' ? { category: classification } : classification;
+    return {
+        category: resolved.category,
+        site,
+        source,
+        ...terminationPosture(resolved.category),
+        ...(resolved.provider === undefined ? {} : { provider: resolved.provider }),
+        ...(resolved.detail === undefined ? {} : { detail: resolved.detail }),
+    };
+}
+/**
+ * Substrings providers use when the input exceeds the model's window, matched case-insensitively.
+ *
+ * These sit **beside** `@langchain/core`'s own detection rather than behind it. LangChain types the
+ * error by substring-matching the provider's English prose in each provider package, so a provider
+ * rewording its 400 drops the typed class with nothing going red — and it covers only half our
+ * providers to begin with. A fallback that repeats the match here is what keeps the classification
+ * from quietly un-typing itself on a dependency bump.
+ */
+const CONTEXT_OVERFLOW_PATTERNS = [
+    'context_length_exceeded',
+    'context length exceeded',
+    'maximum context length',
+    'exceeds the context window',
+    'exceed the context window',
+    'input tokens exceed the configured limit',
+    'prompt is too long',
+    'too many tokens',
+    'reduce the length of the messages',
+    'request too large',
+];
+/** Substrings that mean the provider refused for rate or quota reasons. */
+const RATE_LIMIT_PATTERNS = [
+    'rate limit',
+    'rate_limit',
+    'ratelimit',
+    'too many requests',
+    'quota exceeded',
+    'resource_exhausted',
+    'resource exhausted',
+    'overloaded_error',
+];
+/** Substrings that mean the caller was not authorised. */
+const AUTH_PATTERNS = [
+    'unauthorized',
+    'unauthenticated',
+    'invalid api key',
+    'invalid_api_key',
+    'incorrect api key',
+    'api key not valid',
+    'permission denied',
+    'permission_denied',
+    'authentication_error',
+    'invalid_grant',
+    'forbidden',
+];
+/** Substrings that mean the fault was on the provider's side. */
+const PROVIDER_ERROR_PATTERNS = [
+    'internal error',
+    'internal server error',
+    'internal_server_error',
+    'service unavailable',
+    'bad gateway',
+    'server_error',
+    'overloaded',
+    'model is overloaded',
+    'try again later',
+];
+/** Substrings that mean the request never completed at the transport level. */
+const NETWORK_PATTERNS = [
+    'econnreset',
+    'econnrefused',
+    'enotfound',
+    'epipe',
+    'eai_again',
+    'socket hang up',
+    'fetch failed',
+    'network error',
+    'connection error',
+    'terminated',
+];
+/** Substrings that mean a deadline elapsed. */
+const TIMEOUT_PATTERNS = [
+    'etimedout',
+    'timed out',
+    'timeout',
+    'deadline exceeded',
+    'deadline_exceeded',
+];
+/** Substrings that mean the provider rejected the request itself. */
+const INVALID_REQUEST_PATTERNS = [
+    'invalid_request_error',
+    'invalid request',
+    'bad request',
+    'invalid argument',
+    'invalid_argument',
+];
+/** Read a property off an unknown value without asserting anything about its shape. */
+function field(source, key) {
+    if (!source || (typeof source !== 'object' && typeof source !== 'function'))
+        return undefined;
+    return source[key];
+}
+/** Whether `haystack` contains any of `patterns` (both compared lower-cased). */
+function containsAny(haystack, patterns) {
+    return patterns.some((pattern) => haystack.includes(pattern));
+}
+/**
+ * Every text an error carries that a classification may read: its message, its name, and the
+ * nested provider payloads SDKs hang off `error`, `cause`, `body` and `response.data`. Bounded to
+ * one nesting level per branch so a self-referential payload cannot spin.
+ */
+function errorText(error) {
+    const parts = [];
+    const push = (value) => {
+        if (typeof value === 'string')
+            parts.push(value);
+        else if (typeof value === 'number')
+            parts.push(String(value));
+    };
+    push(field(error, 'message'));
+    push(field(error, 'name'));
+    push(field(error, 'code'));
+    push(field(error, 'type'));
+    if (typeof error === 'string')
+        parts.push(error);
+    for (const key of ['error', 'cause', 'body', 'data', 'response']) {
+        const nested = field(error, key);
+        if (typeof nested === 'string') {
+            parts.push(nested);
+            continue;
+        }
+        push(field(nested, 'message'));
+        push(field(nested, 'type'));
+        push(field(nested, 'code'));
+        const inner = field(nested, 'error');
+        push(field(inner, 'message'));
+        push(field(inner, 'type'));
+        push(field(inner, 'code'));
+    }
+    // The separator is deliberately not a plain space: the prose patterns below are multi-word
+    // English, and joining two adjacent fragments with a space lets a pattern match ACROSS them —
+    // a fragment ending in "rate" beside one starting with "limit" would read as a rate limit.
+    // A newline cannot occur mid-pattern, so it breaks that adjacency without hiding anything.
+    return parts.join(' \n ').toLowerCase();
+}
+/** The HTTP status an SDK error carries, wherever it hangs it. Undefined when there is none. */
+function httpStatus(error) {
+    for (const holder of [error, field(error, 'response'), field(error, 'error')]) {
+        for (const key of ['status', 'statusCode', 'code']) {
+            const value = field(holder, key);
+            if (typeof value === 'number' && value >= 100 && value < 600)
+                return value;
+            if (typeof value === 'string' && /^[1-5]\d{2}$/.test(value))
+                return Number(value);
+        }
+    }
+    return undefined;
+}
+/** The `name` of an error, or `undefined` for anything that carries none. */
+function errorName(error) {
+    const name = field(error, 'name');
+    return typeof name === 'string' && name.length > 0 ? name : undefined;
+}
+/**
+ * Whether a thrown value is a context overflow.
+ *
+ * The predicate is `ContextOverflowError.isInstance`, never `lc_error_code`: the code is set
+ * asymmetrically across providers (Anthropic stamps both the class and the code, OpenAI only the
+ * class), so keying on it silently misses most of where the typed class actually works. The
+ * substring fallback then covers the providers LangChain does not type at all, and the case where
+ * a reworded provider message drops the class.
+ */
+export function isContextOverflow(error) {
+    try {
+        if (ContextOverflowError.isInstance(error))
+            return true;
+    }
+    catch {
+        /* fail-soft: a dependency that stops exporting the predicate must not break classification */
+    }
+    if (errorName(error) === 'ContextOverflowError')
+        return true;
+    return containsAny(errorText(error), CONTEXT_OVERFLOW_PATTERNS);
+}
+/**
+ * The exception feeder: classify a thrown value into the taxonomy.
+ *
+ * Order matters. The typed and named cases are decided first, because a context overflow is also an
+ * HTTP 400 and an abort is also a `DOMException`; only once those are excluded does the status code
+ * and then the prose get a say. Never throws: an unclassifiable value is `unknown`, which is a
+ * recorded fact rather than a guess.
+ */
+export function classifyThrownTermination(error) {
+    try {
+        const name = errorName(error);
+        const text = errorText(error);
+        const status = httpStatus(error);
+        // Typed / named first — these are unambiguous and several of them also carry a status that
+        // would classify them wrongly.
+        if (isContextOverflow(error)) {
+            return { category: 'context_overflow', detail: name ?? 'ContextOverflowError' };
+        }
+        if (name === 'AbortError' || name === 'ModelAbortError' || name === 'APIUserAbortError') {
+            return { category: 'cancelled', detail: name };
+        }
+        if (name === 'GraphInterrupt') {
+            return { category: 'suspended', detail: name };
+        }
+        if (name === 'ToolException') {
+            return { category: 'tool_error', detail: name };
+        }
+        if (name === 'GraphRecursionError' || text.includes('recursion limit')) {
+            return { category: 'recursion_limit', detail: name ?? 'recursion limit' };
+        }
+        if (name === 'TimeoutError' || name === 'APITimeoutError') {
+            return { category: 'timeout', detail: name };
+        }
+        if (name === 'APIConnectionError') {
+            return { category: 'network_error', detail: name };
+        }
+        // Status codes next: a number the provider set is stronger evidence than prose we matched.
+        if (status === 429)
+            return { category: 'rate_limited', detail: '429' };
+        if (status === 401 || status === 403)
+            return { category: 'auth_failed', detail: String(status) };
+        if (status === 408 || status === 504)
+            return { category: 'timeout', detail: String(status) };
+        if (status !== undefined && status >= 500) {
+            return { category: 'provider_error', detail: String(status) };
+        }
+        // Prose last, and in the order that keeps a specific signal from being eaten by a generic one:
+        // "quota exceeded" is a rate limit before it is an invalid request, and an auth failure often
+        // arrives as a 400 whose body says `invalid_grant`.
+        if (containsAny(text, RATE_LIMIT_PATTERNS))
+            return { category: 'rate_limited' };
+        if (containsAny(text, AUTH_PATTERNS))
+            return { category: 'auth_failed' };
+        if (containsAny(text, TIMEOUT_PATTERNS))
+            return { category: 'timeout' };
+        if (containsAny(text, NETWORK_PATTERNS))
+            return { category: 'network_error' };
+        if (containsAny(text, PROVIDER_ERROR_PATTERNS))
+            return { category: 'provider_error' };
+        if (status === 400 || containsAny(text, INVALID_REQUEST_PATTERNS)) {
+            // `detail` is the raw token the classification was made from, so it states the status the
+            // response ACTUALLY had. A 402 or 409 whose prose matches the patterns reaches this branch
+            // too (it is past the 429/401/403/408/5xx arms), and stamping a flat '400' on one would put
+            // a false statement in the field that exists to record what was seen.
+            return {
+                category: 'invalid_request',
+                detail: status === undefined ? undefined : String(status),
+            };
+        }
+        return { category: 'unknown', ...(name === undefined ? {} : { detail: name }) };
+    }
+    catch {
+        // Classification must never be the thing that breaks a run that was already failing.
+        return { category: 'unknown' };
+    }
+}
+/**
+ * The property a reason is carried on when it rides a thrown error.
+ *
+ * A run that ends by throwing crosses layers the runner does not own, and the message is not the
+ * carrier — that is the whole defect this taxonomy exists to fix. Attaching the value to the error
+ * lets any catcher upstream read the classification without re-deriving it from prose.
+ */
+const TERMINATION_REASON_KEY = 'gthTerminationReason';
+/**
+ * Attach a reason to a thrown value and return it, so a `throw` site reads as one expression.
+ *
+ * Non-enumerable, so the reason never widens what an error serialises to (a logged or
+ * JSON-stringified error keeps exactly the shape it had), and first-write-wins so a re-throw
+ * through an outer wrapper cannot overwrite the inner, truer classification. Fail-soft: a frozen or
+ * primitive throw value is returned unchanged rather than turning a failure into a different one.
+ */
+export function attachTerminationReason(error, reason) {
+    try {
+        if (!error || (typeof error !== 'object' && typeof error !== 'function'))
+            return error;
+        if (field(error, TERMINATION_REASON_KEY) !== undefined)
+            return error;
+        Object.defineProperty(error, TERMINATION_REASON_KEY, {
+            value: reason,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+    catch {
+        /* fail-soft */
+    }
+    return error;
+}
+/** The reason attached to a thrown value, following one `cause` link. Undefined when none is. */
+export function terminationReasonOf(error) {
+    const own = field(error, TERMINATION_REASON_KEY);
+    if (own && typeof own === 'object')
+        return own;
+    const cause = field(error, 'cause');
+    const inherited = field(cause, TERMINATION_REASON_KEY);
+    if (inherited && typeof inherited === 'object')
+        return inherited;
+    return undefined;
+}
+//# sourceMappingURL=terminationReason.js.map