@gaunt-sloth/core 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/core/reasoningBlocks.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * CFG-33 — the bridge between a provider's reasoning SHAPE and gaunt-sloth's reasoning channel, for
+ * the providers that carry thinking INSIDE `content` rather than beside it.
+ *
+ * Most providers hand thinking over out-of-band, in `additional_kwargs.reasoning_content` (or
+ * `reasoning`), which {@link pickReasoningDelta} in `GthAbstractAgent` reads. Google Gemini does not:
+ * a thought summary arrives as a content BLOCK marked `thought: true` and typed exactly like an
+ * answer block (`type: 'text'`). Two consequences follow, and the second is the dangerous one:
+ *
+ *  1. `additional_kwargs` carries nothing, so the reasoning channel stays empty — the `/reasoning`
+ *     panel shows nothing at all on `google-genai`/`vertexai`.
+ *  2. `BaseMessage.text` maps every `type: 'text'` block, so the thought summary is folded into the
+ *     ANSWER — it would print inline in the answer on every surface, and into `writeOutputToFile`.
+ *
+ * These helpers classify content once, so each consumer can take the half it wants. They are pure,
+ * shape-driven and provider-agnostic: content that carries no reasoning block is passed through with
+ * byte-identical results (and, for {@link stripReasoningBlocks}, the very same array reference), so
+ * no other provider's rendering changes.
+ */
+/** One classified slice of assistant output: answer prose vs. the model's thinking. */
+export type ThinkSegment = {
+    kind: 'answer' | 'reasoning';
+    text: string;
+};
+/**
+ * Is this content block the model's THINKING rather than its answer?
+ *
+ * Deliberately narrow: ONLY Gemini's `thought: true` marker on an otherwise ordinary text block.
+ * Providers whose thinking arrives as a distinct block TYPE (Anthropic's `thinking` blocks) are NOT
+ * matched here — `BaseMessage.text` already excludes them from the answer, and their reasoning
+ * already reaches the channel via `additional_kwargs.reasoning_content`, so matching them too would
+ * emit that provider's thinking TWICE.
+ */
+export declare function isReasoningContentBlock(block: unknown): boolean;
+/**
+ * Classify an assistant message's `content` into ORDERED answer/reasoning segments, preserving the
+ * order the model emitted them in (a thought summary that precedes the answer stays before it).
+ *
+ * The concatenation of the `answer` segments is EXACTLY what `BaseMessage.text` returns once the
+ * reasoning blocks are removed — the same block rules, the same empty join — so for content that
+ * carries no reasoning block this is a drop-in for `.text`.
+ */
+export declare function segmentAssistantContent(content: unknown): ThinkSegment[];
+/**
+ * The ANSWER text of an assistant message's content — what `BaseMessage.text` would return minus any
+ * reasoning block. Used by the surfaces that render answer text directly and have never shown
+ * reasoning (the plain console stream), so a thought summary cannot leak into the answer there.
+ */
+export declare function answerTextOf(content: unknown): string;
+/**
+ * The same content with its reasoning blocks removed, for consumers that render the block ARRAY
+ * rather than its text (`renderAssistantContent` / `materializeBinaryOutputs` on the non-streaming
+ * path). Returns the INPUT REFERENCE unchanged whenever nothing matched, so every other provider's
+ * content object is untouched and identity comparisons still hold.
+ *
+ * Only the rendering path strips: the message kept in graph state is left intact, so the thought
+ * parts (and any `thoughtSignature` riding with them) still replay to the provider as history.
+ */
+export declare function stripReasoningBlocks(content: unknown): unknown;

package/dist/core/reasoningBlocks.js

@@ -0,0 +1,98 @@
+/**
+ * @packageDocumentation
+ * CFG-33 — the bridge between a provider's reasoning SHAPE and gaunt-sloth's reasoning channel, for
+ * the providers that carry thinking INSIDE `content` rather than beside it.
+ *
+ * Most providers hand thinking over out-of-band, in `additional_kwargs.reasoning_content` (or
+ * `reasoning`), which {@link pickReasoningDelta} in `GthAbstractAgent` reads. Google Gemini does not:
+ * a thought summary arrives as a content BLOCK marked `thought: true` and typed exactly like an
+ * answer block (`type: 'text'`). Two consequences follow, and the second is the dangerous one:
+ *
+ *  1. `additional_kwargs` carries nothing, so the reasoning channel stays empty — the `/reasoning`
+ *     panel shows nothing at all on `google-genai`/`vertexai`.
+ *  2. `BaseMessage.text` maps every `type: 'text'` block, so the thought summary is folded into the
+ *     ANSWER — it would print inline in the answer on every surface, and into `writeOutputToFile`.
+ *
+ * These helpers classify content once, so each consumer can take the half it wants. They are pure,
+ * shape-driven and provider-agnostic: content that carries no reasoning block is passed through with
+ * byte-identical results (and, for {@link stripReasoningBlocks}, the very same array reference), so
+ * no other provider's rendering changes.
+ */
+function isContentBlock(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Is this content block the model's THINKING rather than its answer?
+ *
+ * Deliberately narrow: ONLY Gemini's `thought: true` marker on an otherwise ordinary text block.
+ * Providers whose thinking arrives as a distinct block TYPE (Anthropic's `thinking` blocks) are NOT
+ * matched here — `BaseMessage.text` already excludes them from the answer, and their reasoning
+ * already reaches the channel via `additional_kwargs.reasoning_content`, so matching them too would
+ * emit that provider's thinking TWICE.
+ */
+export function isReasoningContentBlock(block) {
+    return isContentBlock(block) && block.thought === true && block.type === 'text';
+}
+/**
+ * Classify an assistant message's `content` into ORDERED answer/reasoning segments, preserving the
+ * order the model emitted them in (a thought summary that precedes the answer stays before it).
+ *
+ * The concatenation of the `answer` segments is EXACTLY what `BaseMessage.text` returns once the
+ * reasoning blocks are removed — the same block rules, the same empty join — so for content that
+ * carries no reasoning block this is a drop-in for `.text`.
+ */
+export function segmentAssistantContent(content) {
+    if (typeof content === 'string') {
+        return content.length > 0 ? [{ kind: 'answer', text: content }] : [];
+    }
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const segments = [];
+    for (const block of content) {
+        if (typeof block === 'string') {
+            if (block.length > 0)
+                segments.push({ kind: 'answer', text: block });
+            continue;
+        }
+        if (!isContentBlock(block))
+            continue;
+        const text = typeof block.text === 'string' ? block.text : '';
+        if (text.length === 0)
+            continue;
+        if (isReasoningContentBlock(block)) {
+            segments.push({ kind: 'reasoning', text });
+        }
+        else if (block.type === 'text') {
+            segments.push({ kind: 'answer', text });
+        }
+    }
+    return segments;
+}
+/**
+ * The ANSWER text of an assistant message's content — what `BaseMessage.text` would return minus any
+ * reasoning block. Used by the surfaces that render answer text directly and have never shown
+ * reasoning (the plain console stream), so a thought summary cannot leak into the answer there.
+ */
+export function answerTextOf(content) {
+    return segmentAssistantContent(content)
+        .filter((segment) => segment.kind === 'answer')
+        .map((segment) => segment.text)
+        .join('');
+}
+/**
+ * The same content with its reasoning blocks removed, for consumers that render the block ARRAY
+ * rather than its text (`renderAssistantContent` / `materializeBinaryOutputs` on the non-streaming
+ * path). Returns the INPUT REFERENCE unchanged whenever nothing matched, so every other provider's
+ * content object is untouched and identity comparisons still hold.
+ *
+ * Only the rendering path strips: the message kept in graph state is left intact, so the thought
+ * parts (and any `thoughtSignature` riding with them) still replay to the provider as history.
+ */
+export function stripReasoningBlocks(content) {
+    if (!Array.isArray(content))
+        return content;
+    const kept = content.filter((block) => !isReasoningContentBlock(block));
+    return kept.length === content.length ? content : kept;
+}
+//# sourceMappingURL=reasoningBlocks.js.map

package/dist/core/reasoningBlocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoningBlocks.js","sourceRoot":"","sources":["../../src/core/reasoningBlocks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;AAClF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACrE,SAAS;QACX,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;YAAE,SAAS;QACrC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,IAAI,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO,uBAAuB,CAAC,OAAO,CAAC;SACpC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC;SAC9C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;SAC9B,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC"}

package/dist/core/refusal.d.ts

@@ -0,0 +1,53 @@
+/**
+ * EXT-37 — content-policy refusal detection for the agent run loop.
+ *
+ * A *successful* model response (HTTP 200) can carry a stop/finish reason that means the model — or
+ * the provider's safety system — declined to answer. The content is usually empty, so without this
+ * detection the response falls through the empty-response retry in {@link GthAgentRunner} and is
+ * mis-surfaced as "no content, try again" — burning a second, paid call to reproduce a
+ * DETERMINISTIC refusal. This module normalizes the per-provider shapes into one signal so the run
+ * loop can surface the refusal clearly and terminate (never retry the same prompt).
+ *
+ * Prior art: hermes-agent `conversation_loop.py` treats `finish_reason == "content_filter"` as a
+ * terminal, non-retryable "content policy blocked" outcome and surfaces the model's explanation.
+ *
+ * Detection lives here (and is called from {@link GthAbstractAgent}, the invoke/stream loop over
+ * messages/chunks) because that is the only layer where a message's `response_metadata` /
+ * `additional_kwargs` — where finish/stop reasons live — are visible; `GthAgentRunner` only ever
+ * sees the rendered string.
+ */
+/** One detected refusal, normalized across providers. */
+export interface RefusalInfo {
+    /** Best-effort provider family the signal came from (for logging / the surfaced message). */
+    provider: 'openai' | 'anthropic' | 'bedrock' | 'unknown';
+    /** The raw stop/finish reason token that flagged the refusal (e.g. `content_filter`). */
+    reason: string;
+    /** Any model-provided explanation text (empty string when the refusal carried none). */
+    explanation: string;
+}
+/**
+ * Inspect a finished model message (an `AIMessage` / `AIMessageChunk`, or any object exposing
+ * `response_metadata` / `additional_kwargs`) and return a {@link RefusalInfo} when its stop/finish
+ * reason indicates a content-policy refusal, else `null`. Defensive: any non-message / unexpected
+ * shape yields `null`, so a normal turn is never mistaken for a refusal.
+ *
+ * Covered shapes:
+ *  - OpenAI-family `finish_reason: 'content_filter'` (also under `additional_kwargs`).
+ *  - Anthropic `stop_reason: 'refusal'`.
+ *  - Bedrock Converse guardrail intervention: `stopReason`/`stop_reason`/`finish_reason` ===
+ *    `'guardrail_intervened'`, or `additional_kwargs['amazon-bedrock-guardrailAction'] ===
+ *    `'INTERVENED'`.
+ *  - Bedrock Converse content filter: `stopReason`/`stop_reason`/`finish_reason` ===
+ *    `'content_filtered'` (EXT-41 — a distinct `StopReason` enum value from `guardrail_intervened`
+ *    that was previously mapped to `null`, i.e. a silent empty turn / false negative).
+ */
+export declare function detectRefusal(message: unknown): RefusalInfo | null;
+/**
+ * Build the clear, user-facing message shown when the model declines. Framed as the model /
+ * provider's own policy decision (not a Gaunt Sloth fault) and stated as terminal — a refusal is
+ * deterministic for the same input, so retrying as-is will not help. Any model-provided explanation
+ * is included verbatim. This string is BOTH surfaced to the console and RETURNED as the turn's
+ * answer, so the non-interactive caller writes it to the output file and exits `ok` (it is a
+ * successful, if declined, response — not a failure to be re-wrapped as "Failed to get answer").
+ */
+export declare function buildRefusalMessage(info: RefusalInfo): string;

package/dist/core/refusal.js

@@ -0,0 +1,133 @@
+/**
+ * EXT-37 — content-policy refusal detection for the agent run loop.
+ *
+ * A *successful* model response (HTTP 200) can carry a stop/finish reason that means the model — or
+ * the provider's safety system — declined to answer. The content is usually empty, so without this
+ * detection the response falls through the empty-response retry in {@link GthAgentRunner} and is
+ * mis-surfaced as "no content, try again" — burning a second, paid call to reproduce a
+ * DETERMINISTIC refusal. This module normalizes the per-provider shapes into one signal so the run
+ * loop can surface the refusal clearly and terminate (never retry the same prompt).
+ *
+ * Prior art: hermes-agent `conversation_loop.py` treats `finish_reason == "content_filter"` as a
+ * terminal, non-retryable "content policy blocked" outcome and surfaces the model's explanation.
+ *
+ * Detection lives here (and is called from {@link GthAbstractAgent}, the invoke/stream loop over
+ * messages/chunks) because that is the only layer where a message's `response_metadata` /
+ * `additional_kwargs` — where finish/stop reasons live — are visible; `GthAgentRunner` only ever
+ * sees the rendered string.
+ */
+import { stripReasoningBlocks } from '#src/core/reasoningBlocks.js';
+/** Read a nested record field defensively (returns undefined for non-objects / missing keys). */
+function readField(source, key) {
+    if (!source || typeof source !== 'object')
+        return undefined;
+    return source[key];
+}
+/** Pull any human-readable explanation the refusal carried (message content, then reasoning). */
+function extractRefusalText(message) {
+    const content = readField(message, 'content');
+    if (typeof content === 'string' && content.trim().length > 0)
+        return content.trim();
+    // Content-block arrays (Anthropic / Bedrock): concatenate any text parts. CFG-33 — minus the
+    // model's own thinking: Gemini marks a thought summary `thought: true` and types it exactly like
+    // an answer part, so without this it would be pasted verbatim into the refusal notice as the
+    // model's "explanation".
+    if (Array.isArray(content)) {
+        const text = stripReasoningBlocks(content)
+            .map((part) => {
+            if (typeof part === 'string')
+                return part;
+            const t = readField(part, 'text');
+            return typeof t === 'string' ? t : '';
+        })
+            .join('')
+            .trim();
+        if (text.length > 0)
+            return text;
+    }
+    // Some refusals put the explanation only in the reasoning channel.
+    const kwargs = readField(message, 'additional_kwargs');
+    const reasoning = readField(kwargs, 'reasoning_content');
+    if (typeof reasoning === 'string' && reasoning.trim().length > 0)
+        return reasoning.trim();
+    // Anthropic exposes the declined text on a dedicated `refusal` field in some SDK shapes.
+    const refusalField = readField(kwargs, 'refusal') ?? readField(message, 'refusal');
+    if (typeof refusalField === 'string' && refusalField.trim().length > 0)
+        return refusalField.trim();
+    return '';
+}
+/**
+ * Inspect a finished model message (an `AIMessage` / `AIMessageChunk`, or any object exposing
+ * `response_metadata` / `additional_kwargs`) and return a {@link RefusalInfo} when its stop/finish
+ * reason indicates a content-policy refusal, else `null`. Defensive: any non-message / unexpected
+ * shape yields `null`, so a normal turn is never mistaken for a refusal.
+ *
+ * Covered shapes:
+ *  - OpenAI-family `finish_reason: 'content_filter'` (also under `additional_kwargs`).
+ *  - Anthropic `stop_reason: 'refusal'`.
+ *  - Bedrock Converse guardrail intervention: `stopReason`/`stop_reason`/`finish_reason` ===
+ *    `'guardrail_intervened'`, or `additional_kwargs['amazon-bedrock-guardrailAction'] ===
+ *    `'INTERVENED'`.
+ *  - Bedrock Converse content filter: `stopReason`/`stop_reason`/`finish_reason` ===
+ *    `'content_filtered'` (EXT-41 — a distinct `StopReason` enum value from `guardrail_intervened`
+ *    that was previously mapped to `null`, i.e. a silent empty turn / false negative).
+ */
+export function detectRefusal(message) {
+    if (!message || typeof message !== 'object')
+        return null;
+    const meta = readField(message, 'response_metadata');
+    const kwargs = readField(message, 'additional_kwargs');
+    // Gather the stop/finish reason from every place providers surface it.
+    const finishReason = readField(meta, 'finish_reason') ?? readField(kwargs, 'finish_reason') ?? undefined;
+    const stopReasonSnake = readField(meta, 'stop_reason') ?? readField(kwargs, 'stop_reason') ?? undefined;
+    const stopReasonCamel = readField(meta, 'stopReason') ?? readField(kwargs, 'stopReason') ?? undefined;
+    const asString = (v) => (typeof v === 'string' ? v : undefined);
+    const finish = asString(finishReason);
+    const stopSnake = asString(stopReasonSnake);
+    const stopCamel = asString(stopReasonCamel);
+    const explanation = extractRefusalText(message);
+    // OpenAI-family content filter.
+    if (finish === 'content_filter') {
+        return { provider: 'openai', reason: 'content_filter', explanation };
+    }
+    // Anthropic refusal stop reason.
+    if (stopSnake === 'refusal' || stopCamel === 'refusal') {
+        return { provider: 'anthropic', reason: 'refusal', explanation };
+    }
+    // Bedrock Converse guardrail intervention (camelCase `stopReason`, or snake / finish variants).
+    if (stopCamel === 'guardrail_intervened' ||
+        stopSnake === 'guardrail_intervened' ||
+        finish === 'guardrail_intervened' ||
+        readField(kwargs, 'amazon-bedrock-guardrailAction') === 'INTERVENED' ||
+        readField(meta, 'amazon-bedrock-guardrailAction') === 'INTERVENED') {
+        return { provider: 'bedrock', reason: 'guardrail_intervened', explanation };
+    }
+    // EXT-41 — Bedrock Converse content filter. A distinct `StopReason` enum value from
+    // `guardrail_intervened` (both live in the same AWS Converse `StopReason` enum); previously
+    // unmapped, so a content-filtered turn returned `null` → the silent empty-turn false negative.
+    if (stopCamel === 'content_filtered' ||
+        stopSnake === 'content_filtered' ||
+        finish === 'content_filtered') {
+        return { provider: 'bedrock', reason: 'content_filtered', explanation };
+    }
+    return null;
+}
+/**
+ * Build the clear, user-facing message shown when the model declines. Framed as the model /
+ * provider's own policy decision (not a Gaunt Sloth fault) and stated as terminal — a refusal is
+ * deterministic for the same input, so retrying as-is will not help. Any model-provided explanation
+ * is included verbatim. This string is BOTH surfaced to the console and RETURNED as the turn's
+ * answer, so the non-interactive caller writes it to the output file and exits `ok` (it is a
+ * successful, if declined, response — not a failure to be re-wrapped as "Failed to get answer").
+ */
+export function buildRefusalMessage(info) {
+    const head = 'The model declined to respond (safety refusal / content filter) — this is the ' +
+        "model/provider's own policy decision, not a Gaunt Sloth error.";
+    const detail = info.explanation
+        ? `Model's explanation: ${info.explanation}`
+        : 'The model provided no explanation.';
+    const hint = 'A refusal is deterministic for the same input — rephrase the request or try a different ' +
+        'model rather than re-running it as-is.';
+    return `${head}\n\n${detail}\n\n${hint}`;
+}
+//# sourceMappingURL=refusal.js.map

package/dist/core/refusal.js.map

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

package/dist/core/runStats.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ * GS2-16 — pure, fail-soft helpers that harvest per-run analytics (token usage + invoked tool
+ * names) from LangChain messages, so the opt-in history recorder can populate `gth insights`
+ * with real numbers instead of zeros.
+ *
+ * The extraction is deliberately structural and defensive (duck-typed reads guarded by a
+ * try/catch) rather than `instanceof`-based: the same accumulator serves both the non-streaming
+ * `invoke` path (a full `messages[]` from graph state) and the streaming paths (individual
+ * message chunks / `ToolMessage`s as they arrive), across providers whose message shapes vary.
+ * Nothing here may throw into a run — a missing/odd field just means that datum is skipped.
+ */
+import type { GthRunStats, GthToolResult } from '#src/core/types.js';
+/**
+ * BATCH-21 — cap on a captured tool-result `content` (characters). Keeps a giant payload (a whole
+ * file read, a long shell log) from bloating run stats; anything longer is truncated to this
+ * length. Sized so realistic structured payloads (the `gth eval` tool-result-assertion use case)
+ * survive intact.
+ */
+export declare const TOOL_RESULT_CONTENT_CAP = 8192;
+/** Mutable tally behind {@link finalizeRunStats}; see {@link createRunStatsAccumulator}. */
+export interface RunStatsAccumulator {
+    /** Running sum of input/prompt tokens. */
+    input: number;
+    /** Running sum of output/completion tokens. */
+    output: number;
+    /** Whether ANY message reported `usage_metadata` — gates whether tokens are recorded at all. */
+    sawUsage: boolean;
+    /** Deduplicated set of invoked tool names. */
+    tools: Set<string>;
+    /** BATCH-21 — one record per executed tool result (`ToolMessage`), in arrival order, un-deduped. */
+    toolResults: GthToolResult[];
+}
+/** A fresh, empty accumulator. */
+export declare function createRunStatsAccumulator(): RunStatsAccumulator;
+/**
+ * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
+ * shape is swallowed so a run is never affected. Harvests, when present:
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`),
+ * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured, and
+ * - (BATCH-21) a per-`ToolMessage` result record — `name` + `isError` (from `.status`) + capped
+ *   `content` — into `acc.toolResults`, so tool-RESULT assertions can grade what a tool returned.
+ */
+export declare function accumulateMessage(acc: RunStatsAccumulator, message: unknown): void;
+/** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */
+export declare function finalizeRunStats(acc: RunStatsAccumulator): GthRunStats;
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export declare function extractRunStats(messages: unknown): GthRunStats;

package/dist/core/runStats.js

@@ -0,0 +1,118 @@
+/**
+ * BATCH-21 — cap on a captured tool-result `content` (characters). Keeps a giant payload (a whole
+ * file read, a long shell log) from bloating run stats; anything longer is truncated to this
+ * length. Sized so realistic structured payloads (the `gth eval` tool-result-assertion use case)
+ * survive intact.
+ */
+export const TOOL_RESULT_CONTENT_CAP = 8192;
+/** A fresh, empty accumulator. */
+export function createRunStatsAccumulator() {
+    return { input: 0, output: 0, sawUsage: false, tools: new Set(), toolResults: [] };
+}
+/**
+ * BATCH-21 — derive a tool result's text payload from a `ToolMessage.content`, fail-soft. A string
+ * passes through; anything else non-`undefined` is JSON-stringified (the same derivation the
+ * `tool_result` stream event uses in `GthAbstractAgent`); the result is capped at
+ * {@link TOOL_RESULT_CONTENT_CAP}. Returns `undefined` (payload omitted) when nothing textual can
+ * be derived — never throws.
+ */
+function toolResultContentText(content) {
+    try {
+        let text;
+        if (typeof content === 'string') {
+            text = content;
+        }
+        else if (content !== undefined) {
+            text = JSON.stringify(content);
+        }
+        if (text === undefined)
+            return undefined;
+        return text.length > TOOL_RESULT_CONTENT_CAP ? text.slice(0, TOOL_RESULT_CONTENT_CAP) : text;
+    }
+    catch {
+        /* fail-soft: an unstringifiable payload just means no content is recorded */
+        return undefined;
+    }
+}
+/**
+ * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
+ * shape is swallowed so a run is never affected. Harvests, when present:
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`),
+ * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured, and
+ * - (BATCH-21) a per-`ToolMessage` result record — `name` + `isError` (from `.status`) + capped
+ *   `content` — into `acc.toolResults`, so tool-RESULT assertions can grade what a tool returned.
+ */
+export function accumulateMessage(acc, message) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const m = message;
+        if (!m || typeof m !== 'object')
+            return;
+        const usage = m.usage_metadata;
+        if (usage && typeof usage === 'object') {
+            acc.sawUsage = true;
+            if (typeof usage.input_tokens === 'number' && Number.isFinite(usage.input_tokens)) {
+                acc.input += usage.input_tokens;
+            }
+            if (typeof usage.output_tokens === 'number' && Number.isFinite(usage.output_tokens)) {
+                acc.output += usage.output_tokens;
+            }
+        }
+        // Requested tool calls (AIMessage / AIMessageChunk). Continuation chunks in a streamed
+        // tool call carry an empty name, so guard on a non-empty string; the Set dedupes repeats.
+        const toolCalls = m.tool_calls;
+        if (Array.isArray(toolCalls)) {
+            for (const tc of toolCalls) {
+                const name = tc?.name;
+                if (typeof name === 'string' && name.length > 0)
+                    acc.tools.add(name);
+            }
+        }
+        // Executed tool result (ToolMessage). Its `.name` is the tool that produced the result.
+        const type = typeof m.getType === 'function' ? m.getType() : m._getType?.();
+        if (type === 'tool' && typeof m.name === 'string' && m.name.length > 0) {
+            acc.tools.add(m.name);
+            // BATCH-21 — capture the RESULT record too (same capture site, same fail-soft discipline):
+            // `.status === 'error'` is LangChain's real tool-error signal, `.content` the returned
+            // payload (capped; omitted when no text can be derived). One record per ToolMessage, in
+            // arrival order — deliberately NOT deduplicated, unlike the name set above.
+            const content = toolResultContentText(m.content);
+            acc.toolResults.push({
+                name: m.name,
+                isError: m.status === 'error',
+                ...(content !== undefined ? { content } : {}),
+            });
+        }
+    }
+    catch {
+        /* fail-soft: never let stats capture affect a run */
+    }
+}
+/** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */
+export function finalizeRunStats(acc) {
+    return {
+        tokensInput: acc.sawUsage ? acc.input : undefined,
+        tokensOutput: acc.sawUsage ? acc.output : undefined,
+        tools: [...acc.tools],
+        toolResults: [...acc.toolResults],
+    };
+}
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export function extractRunStats(messages) {
+    const acc = createRunStatsAccumulator();
+    try {
+        if (Array.isArray(messages)) {
+            for (const m of messages)
+                accumulateMessage(acc, m);
+        }
+    }
+    catch {
+        /* fail-soft */
+    }
+    return finalizeRunStats(acc);
+}
+//# sourceMappingURL=runStats.js.map

package/dist/core/runStats.js.map

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

package/dist/core/shell/ShellCommandFailedError.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * body so a softening middleware can hand the model the exact observation it saw before — the
+ * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
+ *
+ * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
+ * `agent → core` dependency direction:
+ *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
+ *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ *
+ * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
+ * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export declare class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    readonly output: string;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    readonly exitCode: number | null;
+    /** The exact command string that was executed. */
+    readonly command: string;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    readonly toolName: string;
+    constructor(params: {
+        output: string;
+        exitCode: number | null;
+        command: string;
+        toolName: string;
+    });
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export declare function isShellCommandFailedError(e: unknown): e is ShellCommandFailedError;