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

package/dist/core/refusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../src/core/refusal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../src/core/refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAapE,iGAAiG;AACjG,SAAS,SAAS,CAAC,MAAe,EAAE,GAAW;IAC7C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAQ,MAAkC,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,iGAAiG;AACjG,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC9C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACpF,6FAA6F;IAC7F,iGAAiG;IACjG,6FAA6F;IAC7F,yBAAyB;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,oBAAoB,CAAC,OAAO,CAAe;aACtD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACZ,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAC1C,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAClC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,CAAC,CAAC;aACD,IAAI,CAAC,EAAE,CAAC;aACR,IAAI,EAAE,CAAC;QACV,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACnC,CAAC;IACD,mEAAmE;IACnE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACzD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1F,yFAAyF;IACzF,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACnF,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACpE,OAAO,YAAY,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEzD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAEvD,uEAAuE;IACvE,MAAM,YAAY,GAChB,SAAS,CAAC,IAAI,EAAE,eAAe,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,SAAS,CAAC;IACtF,MAAM,eAAe,GACnB,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,SAAS,CAAC;IAClF,MAAM,eAAe,GACnB,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI,SAAS,CAAC;IAEhF,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC7F,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEhD,gCAAgC;IAChC,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAChC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC;IACvE,CAAC;IACD,iCAAiC;IACjC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QACvD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IACnE,CAAC;IACD,gGAAgG;IAChG,IACE,SAAS,KAAK,sBAAsB;QACpC,SAAS,KAAK,sBAAsB;QACpC,MAAM,KAAK,sBAAsB;QACjC,SAAS,CAAC,MAAM,EAAE,gCAAgC,CAAC,KAAK,YAAY;QACpE,SAAS,CAAC,IAAI,EAAE,gCAAgC,CAAC,KAAK,YAAY,EAClE,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,sBAAsB,EAAE,WAAW,EAAE,CAAC;IAC9E,CAAC;IACD,oFAAoF;IACpF,4FAA4F;IAC5F,+FAA+F;IAC/F,IACE,SAAS,KAAK,kBAAkB;QAChC,SAAS,KAAK,kBAAkB;QAChC,MAAM,KAAK,kBAAkB,EAC7B,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,WAAW,EAAE,CAAC;IAC1E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IACtD,QAAQ;IACR,YAAY;IACZ,WAAW;IACX,cAAc;CACf,CAAC,CAAC;AAEH;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,OAAgB;IACxC,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACvD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,CAAC;QAChG,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACzD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,OAAO;QAAE,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;IAC7C,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAiB;IAC/C,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AACvF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,MAAM,IAAI,GACR,gFAAgF;QAChF,gEAAgE,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW;QAC7B,CAAC,CAAC,wBAAwB,IAAI,CAAC,WAAW,EAAE;QAC5C,CAAC,CAAC,oCAAoC,CAAC;IACzC,MAAM,IAAI,GACR,0FAA0F;QAC1F,wCAAwC,CAAC;IAC3C,OAAO,GAAG,IAAI,OAAO,MAAM,OAAO,IAAI,EAAE,CAAC;AAC3C,CAAC"}

package/dist/core/terminationNotice.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @packageDocumentation
+ * [[EXT-159]] — getting the typed termination reason to the person looking at the screen.
+ *
+ * `core/terminationReason.ts` decides *what* ended a run. This module decides *how that fact is
+ * said*, once, for every surface — the Ink TUI, the readline session, the non-interactive verbs,
+ * ACP and AG-UI — so a run states why it ended in the same vocabulary wherever it is being watched.
+ *
+ * **Recording it better is not the deliverable.** Most people never make a debug dump; the ones
+ * most likely to hit a silent stop have already quit, taking the live session state with them; and
+ * reading a dump is a skill that fails even for a maintainer holding one. So the reason has to
+ * reach the SESSION, at the moment it happens, on the surface in front of the user.
+ *
+ * **The prose is never the carrier.** Every surface commits the {@link GthTerminationReason} value
+ * itself and derives the words from it here, so a test — and a consumer — reads the classification
+ * structurally instead of matching a sentence. That is also why {@link terminationCode} exists: a
+ * user quoting one short token in a bug report hands a maintainer the fact that makes the report
+ * tractable, which is precisely what "the agent just stopped" could not.
+ *
+ * **An ABSENT reason is a signal, not a blank to fill.** The taxonomy's contract is that a turn
+ * with no reason is a site nobody classified, which is why an ordinary completion is recorded
+ * rather than left empty. Nothing here invents a category, a placeholder or a default for `null`:
+ * {@link terminationLogLine} states the absence as an absence, and
+ * {@link displayTermination} says nothing to the user, because "we did not classify this" is a
+ * defect report aimed at us and not an explanation aimed at them.
+ */
+import type { GthTerminationReason } from '#src/core/terminationReason.js';
+/**
+ * The opening of every termination notice title.
+ *
+ * Exported because two surfaces put the notice into a channel that also carries other messages —
+ * ACP's `agent_message`, where the agent speaks about the session — so something has to be able to
+ * tell one from the other without transcribing the wording. A consumer keying on this constant
+ * moves with the copy; one keying on a copy of the string does not, and finds out when the two have
+ * silently disagreed for a while.
+ */
+export declare const TERMINATION_NOTICE_TITLE_PREFIX = "Run ended: ";
+/** A termination reason, rendered for a surface that shows a title and body lines. */
+export interface GthTerminationNotice {
+    /**
+     * **The carrier.** The classification travels as this value; the strings below are derived from
+     * it and are never the only place it exists.
+     */
+    reason: GthTerminationReason;
+    /** The one line that says what happened. */
+    title: string;
+    /** The supporting lines: the quotable code, what was seen, and what may help. */
+    lines: string[];
+}
+/**
+ * The short token a user can quote and a maintainer can act on: the category and the site that
+ * classified it.
+ *
+ * Both halves, always. Several sites share a category and several categories reach one site, so
+ * either alone loses the fact that separates two failures which look identical on screen — the
+ * standing example being an `empty_response` whose as-is retry has already been spent at
+ * `runner.empty-after-fallback` and one where it has not been spent at all.
+ */
+export declare function terminationCode(reason: GthTerminationReason): string;
+/**
+ * Is this reason worth telling the person watching?
+ *
+ * Two categories are not. `completed` is the ordinary end of a turn, and announcing it would put a
+ * line under every successful answer. `suspended` is a run that has PAUSED rather than ended — the
+ * graph is parked on a tool-approval interrupt and about to continue — so announcing it would
+ * report the middle of a working turn as its end.
+ *
+ * Everything else is announced, deliberately including the ones that look self-explanatory.
+ * `cancelled` is announced because a turn cancelled by a stray escape sequence is exactly the shape
+ * that gets misattributed to the provider for months ([[TUI-C62]]), and a user who did not knowingly
+ * press anything is owed the fact that a cancellation is what happened. `approval_stop` is announced
+ * because the gate's own prose explains the DECISION while this states the CLASSIFICATION, which is
+ * the half a bug report needs.
+ *
+ * Announcing is a separate decision from recording: everything is recorded, including the
+ * categories this returns `false` for.
+ */
+export declare function shouldAnnounceTermination(reason: GthTerminationReason): boolean;
+/**
+ * Render a reason for a surface that shows a title and body lines.
+ *
+ * **The `??` on the label lookup is a runtime floor, and it takes nothing away from the build-time
+ * one.** That a 23rd category fails the build comes from the category-label table being a `Record`
+ * over the whole union, which this expression cannot weaken. What it covers is the case the type
+ * system never saw: a reason that arrived from outside it — read back off an ACP `_meta`, handed
+ * over by an embedder, or revived from a dump — whose category is a string the table has no entry
+ * for. Without the fallback that renders as the literal word `undefined` in the one line the user
+ * is being shown, which is a worse answer than "the cause was not recognised" and is exactly the
+ * kind of second failure this module refuses to add to a first one.
+ */
+export declare function terminationNotice(reason: GthTerminationReason): GthTerminationNotice;
+/**
+ * One line for the debug log, stating either the whole classification or the absence of one.
+ *
+ * `null` is the case this function exists for. A turn that ended with nothing classifying it is the
+ * taxonomy's own defect signal, and it has to be written down as that — never as `completed`, never
+ * as `unknown`, and never omitted, because a missing line is indistinguishable from a session where
+ * this was never reached.
+ */
+export declare function terminationLogLine(reason: GthTerminationReason | null): string;
+/**
+ * Say why the run ended on a console surface (the readline session and the non-interactive verbs),
+ * and write the same fact to the debug log either way.
+ *
+ * Returns whether anything was shown, so a caller can tell "said nothing because the turn simply
+ * finished" from "said nothing because nothing classified it" without re-deriving the rule.
+ *
+ * Fail-soft in the strongest sense: explaining a failure must never become a second failure, so
+ * every path here is wrapped and a throw is swallowed.
+ */
+export declare function displayTermination(reason: GthTerminationReason | null): boolean;

package/dist/core/terminationNotice.js

@@ -0,0 +1,209 @@
+/**
+ * @packageDocumentation
+ * [[EXT-159]] — getting the typed termination reason to the person looking at the screen.
+ *
+ * `core/terminationReason.ts` decides *what* ended a run. This module decides *how that fact is
+ * said*, once, for every surface — the Ink TUI, the readline session, the non-interactive verbs,
+ * ACP and AG-UI — so a run states why it ended in the same vocabulary wherever it is being watched.
+ *
+ * **Recording it better is not the deliverable.** Most people never make a debug dump; the ones
+ * most likely to hit a silent stop have already quit, taking the live session state with them; and
+ * reading a dump is a skill that fails even for a maintainer holding one. So the reason has to
+ * reach the SESSION, at the moment it happens, on the surface in front of the user.
+ *
+ * **The prose is never the carrier.** Every surface commits the {@link GthTerminationReason} value
+ * itself and derives the words from it here, so a test — and a consumer — reads the classification
+ * structurally instead of matching a sentence. That is also why {@link terminationCode} exists: a
+ * user quoting one short token in a bug report hands a maintainer the fact that makes the report
+ * tractable, which is precisely what "the agent just stopped" could not.
+ *
+ * **An ABSENT reason is a signal, not a blank to fill.** The taxonomy's contract is that a turn
+ * with no reason is a site nobody classified, which is why an ordinary completion is recorded
+ * rather than left empty. Nothing here invents a category, a placeholder or a default for `null`:
+ * {@link terminationLogLine} states the absence as an absence, and
+ * {@link displayTermination} says nothing to the user, because "we did not classify this" is a
+ * defect report aimed at us and not an explanation aimed at them.
+ */
+import { display, displayWarning } from '#src/utils/consoleUtils.js';
+import { debugLog } from '#src/utils/debugUtils.js';
+/**
+ * What each category is called in a sentence a user reads.
+ *
+ * An exhaustive `Record` rather than a `switch` with a default: a 23rd category is then a build
+ * failure here instead of a run that silently reports the new cause in the old words.
+ */
+const CATEGORY_LABEL = {
+    completed: 'the model finished',
+    empty_response: 'the model returned nothing',
+    content_refusal: 'the model declined to answer',
+    output_truncated: 'the answer hit the output limit',
+    context_overflow: 'the conversation outgrew the model input window',
+    rate_limited: 'the provider rate-limited the request',
+    auth_failed: 'the provider rejected the credentials',
+    invalid_request: 'the provider rejected the request',
+    provider_error: 'the provider failed',
+    network_error: 'the connection failed',
+    timeout: 'a deadline elapsed',
+    cancelled: 'it was cancelled',
+    approval_stop: 'the approvals gate stopped it',
+    tool_error_budget: 'the tool-error budget ended the run',
+    tool_loop_guard: 'the tool-loop guard ended a repeating call',
+    interrupt_drain_guard: 'too many tool approvals in one turn',
+    tool_error: 'a tool failed',
+    suspended: 'it is waiting to be resumed',
+    recursion_limit: 'it hit the graph step limit',
+    abandoned: 'the client stopped listening',
+    unknown: 'the cause was not recognised',
+};
+/**
+ * What each remedy asks the user to actually do.
+ *
+ * Exhaustive for the same reason {@link CATEGORY_LABEL} is: the posture table names a remedy, and a
+ * remedy nobody worded is a retry hint the user never gets.
+ */
+const REMEDY_LABEL = {
+    'reduce-context': 'Send less — clear or compact the conversation, then try again.',
+    'back-off': 'Wait a moment, then send the same request again.',
+    'change-request': 'Try a different or narrower request.',
+    'change-model': 'Try a different model.',
+    'fix-credentials': 'Check the API credentials or configuration, then try again.',
+    resume: 'Nothing is wrong — the run is parked and can be continued where it stopped.',
+};
+/**
+ * The opening of every termination notice title.
+ *
+ * Exported because two surfaces put the notice into a channel that also carries other messages —
+ * ACP's `agent_message`, where the agent speaks about the session — so something has to be able to
+ * tell one from the other without transcribing the wording. A consumer keying on this constant
+ * moves with the copy; one keying on a copy of the string does not, and finds out when the two have
+ * silently disagreed for a while.
+ */
+export const TERMINATION_NOTICE_TITLE_PREFIX = 'Run ended: ';
+/**
+ * The short token a user can quote and a maintainer can act on: the category and the site that
+ * classified it.
+ *
+ * Both halves, always. Several sites share a category and several categories reach one site, so
+ * either alone loses the fact that separates two failures which look identical on screen — the
+ * standing example being an `empty_response` whose as-is retry has already been spent at
+ * `runner.empty-after-fallback` and one where it has not been spent at all.
+ */
+export function terminationCode(reason) {
+    return `${reason.category}@${reason.site}`;
+}
+/**
+ * Is this reason worth telling the person watching?
+ *
+ * Two categories are not. `completed` is the ordinary end of a turn, and announcing it would put a
+ * line under every successful answer. `suspended` is a run that has PAUSED rather than ended — the
+ * graph is parked on a tool-approval interrupt and about to continue — so announcing it would
+ * report the middle of a working turn as its end.
+ *
+ * Everything else is announced, deliberately including the ones that look self-explanatory.
+ * `cancelled` is announced because a turn cancelled by a stray escape sequence is exactly the shape
+ * that gets misattributed to the provider for months ([[TUI-C62]]), and a user who did not knowingly
+ * press anything is owed the fact that a cancellation is what happened. `approval_stop` is announced
+ * because the gate's own prose explains the DECISION while this states the CLASSIFICATION, which is
+ * the half a bug report needs.
+ *
+ * Announcing is a separate decision from recording: everything is recorded, including the
+ * categories this returns `false` for.
+ */
+export function shouldAnnounceTermination(reason) {
+    return reason.category !== 'completed' && reason.category !== 'suspended';
+}
+/**
+ * Render a reason for a surface that shows a title and body lines.
+ *
+ * **The `??` on the label lookup is a runtime floor, and it takes nothing away from the build-time
+ * one.** That a 23rd category fails the build comes from the category-label table being a `Record`
+ * over the whole union, which this expression cannot weaken. What it covers is the case the type
+ * system never saw: a reason that arrived from outside it — read back off an ACP `_meta`, handed
+ * over by an embedder, or revived from a dump — whose category is a string the table has no entry
+ * for. Without the fallback that renders as the literal word `undefined` in the one line the user
+ * is being shown, which is a worse answer than "the cause was not recognised" and is exactly the
+ * kind of second failure this module refuses to add to a first one.
+ */
+export function terminationNotice(reason) {
+    const lines = [`Reason code: ${terminationCode(reason)}`];
+    const seen = [];
+    if (reason.provider)
+        seen.push(`provider ${reason.provider}`);
+    if (reason.detail)
+        seen.push(`reported ${reason.detail}`);
+    if (seen.length > 0)
+        lines.push(`What was seen: ${seen.join(', ')}.`);
+    lines.push(retryAdvice(reason));
+    return {
+        reason,
+        title: `${TERMINATION_NOTICE_TITLE_PREFIX}${CATEGORY_LABEL[reason.category] ?? CATEGORY_LABEL.unknown}`,
+        lines,
+    };
+}
+/**
+ * The retry advice for a reason, read off the posture the taxonomy already decided.
+ *
+ * Read from the reason's own posture fields rather than re-deriving one from the category, so this
+ * cannot come to disagree with the single posture table the taxonomy exists to keep.
+ */
+function retryAdvice(reason) {
+    if (reason.retryableAsIs)
+        return 'Sending the same request again may work.';
+    if (reason.retryableAfterRemedy && reason.remedy)
+        return REMEDY_LABEL[reason.remedy];
+    return 'Sending the same request again will not help.';
+}
+/**
+ * One line for the debug log, stating either the whole classification or the absence of one.
+ *
+ * `null` is the case this function exists for. A turn that ended with nothing classifying it is the
+ * taxonomy's own defect signal, and it has to be written down as that — never as `completed`, never
+ * as `unknown`, and never omitted, because a missing line is indistinguishable from a session where
+ * this was never reached.
+ */
+export function terminationLogLine(reason) {
+    if (!reason) {
+        return ('EXT-159 termination: UNCLASSIFIED — no site classified how this turn ended. ' +
+            'An absent reason means a termination site we missed, not a turn that went well.');
+    }
+    const parts = [
+        `category=${reason.category}`,
+        `site=${reason.site}`,
+        `source=${reason.source}`,
+        `retryableAsIs=${reason.retryableAsIs}`,
+        `retryableAfterRemedy=${reason.retryableAfterRemedy}`,
+    ];
+    if (reason.remedy)
+        parts.push(`remedy=${reason.remedy}`);
+    if (reason.provider)
+        parts.push(`provider=${reason.provider}`);
+    if (reason.detail)
+        parts.push(`detail=${reason.detail}`);
+    return `EXT-159 termination: ${parts.join(' ')}`;
+}
+/**
+ * Say why the run ended on a console surface (the readline session and the non-interactive verbs),
+ * and write the same fact to the debug log either way.
+ *
+ * Returns whether anything was shown, so a caller can tell "said nothing because the turn simply
+ * finished" from "said nothing because nothing classified it" without re-deriving the rule.
+ *
+ * Fail-soft in the strongest sense: explaining a failure must never become a second failure, so
+ * every path here is wrapped and a throw is swallowed.
+ */
+export function displayTermination(reason) {
+    try {
+        debugLog(terminationLogLine(reason));
+        if (!reason || !shouldAnnounceTermination(reason))
+            return false;
+        const notice = terminationNotice(reason);
+        displayWarning(notice.title);
+        for (const line of notice.lines)
+            display(`  ${line}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=terminationNotice.js.map

package/dist/core/terminationNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminationNotice.js","sourceRoot":"","sources":["../../src/core/terminationNotice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAOH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,cAAc,GAAqD;IACvE,SAAS,EAAE,oBAAoB;IAC/B,cAAc,EAAE,4BAA4B;IAC5C,eAAe,EAAE,8BAA8B;IAC/C,gBAAgB,EAAE,iCAAiC;IACnD,gBAAgB,EAAE,iDAAiD;IACnE,YAAY,EAAE,uCAAuC;IACrD,WAAW,EAAE,uCAAuC;IACpD,eAAe,EAAE,mCAAmC;IACpD,cAAc,EAAE,qBAAqB;IACrC,aAAa,EAAE,uBAAuB;IACtC,OAAO,EAAE,oBAAoB;IAC7B,SAAS,EAAE,kBAAkB;IAC7B,aAAa,EAAE,+BAA+B;IAC9C,iBAAiB,EAAE,qCAAqC;IACxD,eAAe,EAAE,4CAA4C;IAC7D,qBAAqB,EAAE,qCAAqC;IAC5D,UAAU,EAAE,eAAe;IAC3B,SAAS,EAAE,6BAA6B;IACxC,eAAe,EAAE,6BAA6B;IAC9C,SAAS,EAAE,8BAA8B;IACzC,OAAO,EAAE,8BAA8B;CACxC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,YAAY,GAAmD;IACnE,gBAAgB,EAAE,gEAAgE;IAClF,UAAU,EAAE,kDAAkD;IAC9D,gBAAgB,EAAE,sCAAsC;IACxD,cAAc,EAAE,wBAAwB;IACxC,iBAAiB,EAAE,6DAA6D;IAChF,MAAM,EAAE,6EAA6E;CACtF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,aAAa,CAAC;AAe7D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAA4B;IAC1D,OAAO,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAA4B;IACpE,OAAO,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA4B;IAC5D,MAAM,KAAK,GAAa,CAAC,gBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,MAAM,CAAC,QAAQ;QAAE,IAAI,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1D,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAChC,OAAO;QACL,MAAM;QACN,KAAK,EAAE,GAAG,+BAA+B,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,cAAc,CAAC,OAAO,EAAE;QACvG,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,MAA4B;IAC/C,IAAI,MAAM,CAAC,aAAa;QAAE,OAAO,0CAA0C,CAAC;IAC5E,IAAI,MAAM,CAAC,oBAAoB,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACrF,OAAO,+CAA+C,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmC;IACpE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CACL,8EAA8E;YAC9E,iFAAiF,CAClF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG;QACZ,YAAY,MAAM,CAAC,QAAQ,EAAE;QAC7B,QAAQ,MAAM,CAAC,IAAI,EAAE;QACrB,UAAU,MAAM,CAAC,MAAM,EAAE;QACzB,iBAAiB,MAAM,CAAC,aAAa,EAAE;QACvC,wBAAwB,MAAM,CAAC,oBAAoB,EAAE;KACtD,CAAC;IACF,IAAI,MAAM,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,IAAI,MAAM,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,wBAAwB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAmC;IACpE,IAAI,CAAC;QACH,QAAQ,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAChE,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACzC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

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;