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

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

package/dist/core/terminationReason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminationReason.js","sourceRoot":"","sources":["../../src/core/terminationReason.ts"],"names":[],"mappings":"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"}

package/dist/core/toolDisplay.d.ts

@@ -140,15 +140,62 @@ export declare function summariseToolCall(name: string, argsText: string | undef
 /**
  * The FULL (uncapped) body lines for a call: the registry formatter when one applies, else the
  * shape-based shell formatter, else the generic fallback (live output lines, then the final
- * result — both dim). Every line is secret-redacted. Used by the TUI's EXPANDED panel; cap it
- * with {@link capToolDisplayLines} for the collapsed preview.
+ * result — both dim). Every line is secret-redacted and then neutralised. Used by the TUI's
+ * EXPANDED panel; cap it with {@link capToolDisplayLines} for the collapsed preview.
  */
 export declare function buildToolBodyLines(input: ToolCallDisplayInput, secrets?: readonly string[]): ToolDisplayLine[];
+/** The strings the expanded panel paints beside the body, ready to draw. */
+export interface ToolExpansionText {
+    /** The streamed args text as one row's content, or `null` when the call carries no args. */
+    args: string | null;
+    /** The routed notice, one element per row the expansion draws. */
+    noticeLines: string[];
+}
+/**
+ * [[TUI-C102]] — the two untrusted strings the EXPANDED tool panel paints OUTSIDE the body: the
+ * raw streamed args text and the routed "🔧 Executing …" notice. Neither passes through
+ * {@link buildToolBodyLines}, and neither is ours: `argsText` is whatever the model streamed —
+ * under prompt injection, attacker-chosen, and for a shell call it is the command itself — and a
+ * notice quotes that same command back. Under [[TUI-C99]] this expansion is the route by which a
+ * human inspects a call they are being asked to permit, so it gets the treatment the rest of the
+ * display path already has.
+ *
+ * **Both the renderer and the row-count oracle must call this, on the same input.** Neutralised
+ * text is WIDER than the raw text it replaces, so a renderer that neutralises beside an estimator
+ * that measures the raw string disagree about how many rows the panel occupies — and a row
+ * miscount shows as content in the wrong place on screen rather than as an error anywhere. One
+ * helper for both sides is what stops them drifting apart again.
+ *
+ * Same order as everywhere else on this path: **redact the raw text, then neutralise.** A secret
+ * literal that carries a control character stops literal-matching the moment that character is
+ * rewritten. Redaction is here at all because the collapsed summary above this row already
+ * redacts, and an expansion that did not would print, under `/verbose`, the secret the row above
+ * it hid.
+ *
+ * The notice splits through the module's own `toLines`, so a `\r\n` inside a quoted command is one
+ * break there too; the args text is a single value and keeps its own newlines as visible `\x0a`,
+ * which is what a streamed JSON buffer carrying a real newline actually contains.
+ */
+export declare function buildToolExpansionText(input: {
+    argsText?: string;
+    notice?: string;
+}, secrets?: readonly string[]): ToolExpansionText;
 /**
  * Apply the canonical render cap: at most `maxLines` lines (each char-capped at
  * {@link TOOL_PREVIEW_LINE_MAX_CHARS} with `…`), plus a dim `… (+N more lines)` overflow
  * marker when anything was cut. The marker line is IN ADDITION to the cap so exactly how much
  * was hidden is always stated (DL-4 transparency).
+ *
+ * This stays a GENERIC width utility and does not neutralise: it measures a line by what it
+ * RENDERS as, so a caller passing genuinely styled text (the renderer's own SGR) gets a cap that
+ * counts the columns the user sees rather than the escapes' own bytes.
+ *
+ * **No production caller passes styled text today.** {@link buildToolPreviewLines} is the only
+ * one, and its lines arrive already neutralised from {@link buildToolBodyLines}, so on the tool
+ * path there is nothing left to discount. The discount is kept because this is public API — core
+ * exports every module — and a width utility that mismeasured styled text would be wrong for any
+ * caller that did pass some. It is a property of the utility, not a live requirement of the tool
+ * path, and the spec covering it says the same.
  */
 export declare function capToolDisplayLines(lines: ToolDisplayLine[], maxLines?: number): ToolDisplayLine[];
 /**