@gaunt-sloth/core 2.0.0-alpha.8 → 2.0.0-beta.0

package/dist/core/plainToolIndication.js

@@ -0,0 +1,174 @@
+/**
+ * @module plainToolIndication
+ * TUI-C30 — compact tool-call indication for the PLAIN surface (`--no-tui` readline sessions,
+ * piped/single-shot `ask`/`exec`/`review`/`pr`). The Ink TUI renders tool calls from the typed
+ * event stream; the plain surface streams strings, so until now a tool call only surfaced
+ * through the tools' own transient notices (`📁 Reading file: …`, `🔧 Executing …` + raw child
+ * output via the tool-output channel's default sink). This module watches the SAME LangGraph
+ * message stream the string path already iterates and, when each `ToolMessage` lands, prints
+ * one compact indication built from the shared {@link toolDisplay} registry:
+ *
+ *     ✓ 📁 read_file(path=README.md)
+ *         # Readme            ← up to the canonical 10 preview lines, dim
+ *         … (+42 more lines)
+ *
+ * Stream discipline (matches how the plain surface prints tool activity today): the block is
+ * emitted at INFO level through `displayToolIndication` — same stdout channel, same
+ * `consoleLevel` gate and session-log treatment as the existing tool notices — so scripted
+ * consumers that already silence INFO chatter silence this too. Colour is used exactly when the
+ * resolved `useColour` (the CFG-30 ladder in `config/colour.ts`) says so — TUI-C35 removed the
+ * local `&& stdout.isTTY` narrowing this module used to apply on top, which was redundant against
+ * the ladder's own rung-4 TTY auto-detection everywhere except `FORCE_COLOR` on a pipe, the one
+ * case that variable exists to serve. An ordinary piped run is therefore still clean monochrome
+ * (DL-7) — rung 4 decides that — with diff lines readable via their `+`/`-` prefixes.
+ *
+ * Live-output dedupe: shell-shaped results (`<COMMAND_OUTPUT>`) belong to tools whose child
+ * output ALREADY streamed raw via the channel's default sink, so those render with
+ * `liveOutputAlreadyShown` and show only the closing status line — never a repeat of output
+ * the user just watched.
+ */
+import { AIMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import { buildToolPreviewLines, getToolGlyph, isShellShapedResult, renderToolLineAnsi, summariseToolCall, } from '#src/core/toolDisplay.js';
+import { displayToolIndication } from '#src/utils/consoleUtils.js';
+import { getUseColour } from '#src/utils/systemUtils.js';
+const INDENT = '    ';
+/**
+ * Create the per-stream observer. State is scoped to one stream (one `agent.stream()` call);
+ * tool_call deltas are accumulated from `tool_call_chunks` (keyed by the provider's chunk
+ * `index`, which restarts per LLM round — the map is flushed into the by-id map whenever a
+ * `ToolMessage` arrives, mirroring `processEventStream`'s reset-per-round). Deliberately does
+ * NOT `concat()` whole `AIMessageChunk`s: only the tool-call slices are needed, which also
+ * sidesteps the TUI-C29 `__raw_response` aggregation-growth trap entirely.
+ *
+ * `emit` is injectable for tests; production uses the INFO-level `displayToolIndication`.
+ */
+export function createPlainToolIndication(emit = displayToolIndication) {
+    /** Streaming tool-call deltas for the CURRENT round, keyed by tool_call_chunk index. */
+    const streaming = new Map();
+    /** Completed calls awaiting their ToolMessage, keyed by tool call id. */
+    const byId = new Map();
+    const flushStreamingIntoById = () => {
+        for (const call of streaming.values()) {
+            if (call.id)
+                byId.set(call.id, call);
+        }
+        streaming.clear();
+    };
+    const renderToolMessage = (message) => {
+        const id = typeof message.tool_call_id === 'string' ? message.tool_call_id : '';
+        const tracked = id ? byId.get(id) : undefined;
+        if (id)
+            byId.delete(id);
+        const name = tracked?.name || (typeof message.name === 'string' ? message.name : '') || '';
+        const result = typeof message.content === 'string' ? message.content : JSON.stringify(message.content);
+        const isError = message.status === 'error';
+        // TUI-C35 — colour is exactly what the resolved ladder says, with no local narrowing.
+        // This used to AND in `stdout.isTTY`, which was redundant in every case but one: rung 4 of
+        // `config/colour.ts` already auto-detects from stdout's TTY status, so an unconfigured piped
+        // run is monochrome either way. The one case it changed was `FORCE_COLOR` into a pipe — which
+        // it suppressed, defeating the only thing that variable is for.
+        const colour = getUseColour();
+        const statusGlyph = isError
+            ? colour
+                ? '\x1b[31m✗\x1b[0m'
+                : '✗'
+            : colour
+                ? '\x1b[32m✓\x1b[0m'
+                : '✓';
+        const summary = summariseToolCall(name, tracked?.argsText);
+        const summaryText = colour ? `\x1b[2m${summary}\x1b[0m` : summary;
+        const head = `${statusGlyph} ${getToolGlyph(name)} ${summaryText}`;
+        const preview = buildToolPreviewLines({
+            name,
+            argsText: tracked?.argsText,
+            result,
+            isError,
+            // Shell-shaped results stream their child output live through the channel's default
+            // sink on this surface — suppress the duplicated body, keep the status tail. TUI-C32
+            // residual c: gate on the tool NAME + shape (not shape alone), so a non-shell tool whose
+            // result merely quotes `<COMMAND_OUTPUT>` keeps its preview body instead of being suppressed.
+            liveOutputAlreadyShown: isShellShapedResult(name, result),
+        });
+        const body = preview.map((line) => INDENT + renderToolLineAnsi(line, colour));
+        // Leading newline mirrors the historical notice framing (the model text stream may have
+        // left the cursor mid-line).
+        emit(['', head, ...body].join('\n'));
+    };
+    return {
+        observe(chunk) {
+            // Order matters: AIMessageChunk extends AIMessage, so test the chunk shape first
+            // (mirrors processEventStream).
+            if (AIMessageChunk.isInstance(chunk)) {
+                // TUI-C32 residual e — fail-soft, matching the ToolMessage branch: accumulating tool-call
+                // deltas (`JSON.stringify(tc.args)` can throw on an unserialisable arg, e.g. a BigInt) must
+                // never break the run's stream loop. On any error we simply skip this chunk's tracking.
+                try {
+                    const c = chunk;
+                    const deltas = c.tool_call_chunks ?? [];
+                    if (deltas.length > 0) {
+                        for (const delta of deltas) {
+                            const index = typeof delta.index === 'number' ? delta.index : 0;
+                            const entry = streaming.get(index) ?? { name: '', argsText: '' };
+                            if (delta.id)
+                                entry.id = delta.id;
+                            if (delta.name)
+                                entry.name = entry.name || delta.name;
+                            if (delta.args)
+                                entry.argsText += delta.args;
+                            streaming.set(index, entry);
+                        }
+                    }
+                    else {
+                        // Some providers surface COMPLETE tool_calls on a chunk instead of deltas.
+                        for (const tc of c.tool_calls ?? []) {
+                            if (tc.id) {
+                                byId.set(tc.id, {
+                                    id: tc.id,
+                                    name: tc.name,
+                                    argsText: JSON.stringify(tc.args ?? {}),
+                                });
+                            }
+                        }
+                    }
+                }
+                catch {
+                    /* indication is best-effort; the model-facing stream is untouched */
+                }
+                return;
+            }
+            if (AIMessage.isInstance(chunk)) {
+                // A non-chunk AIMessage (resumed/checkpoint-replayed runs) carries final tool_calls.
+                // TUI-C32 residual e — same fail-soft wrap as above/the ToolMessage branch.
+                try {
+                    const m = chunk;
+                    for (const tc of m.tool_calls ?? []) {
+                        if (tc.id) {
+                            byId.set(tc.id, {
+                                id: tc.id,
+                                name: tc.name,
+                                argsText: JSON.stringify(tc.args ?? {}),
+                            });
+                        }
+                    }
+                }
+                catch {
+                    /* indication is best-effort; the model-facing stream is untouched */
+                }
+                return;
+            }
+            if (chunk instanceof ToolMessage) {
+                // The round is over: park any streamed calls under their ids (chunk indexes restart
+                // next round), then render the arrived result. Fail-soft — rendering must never break
+                // the run.
+                try {
+                    flushStreamingIntoById();
+                    renderToolMessage(chunk);
+                }
+                catch {
+                    /* indication is best-effort; the model-facing stream is untouched */
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=plainToolIndication.js.map

package/dist/core/plainToolIndication.js.map

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

package/dist/core/reasoningBlocks.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ *
+ * A pure content transform with no opinion about graph state — what a caller does with the result is
+ * the caller's argument to make. Every caller in this package only READS the result — rendering it,
+ * or pulling a refusal's explanation out of it — so the message kept in state stays whole and its
+ * thought parts (and any `thoughtSignature` riding with them) still replay to the provider as
+ * history. The one caller that rewrites state instead is the subagent thought
+ * redaction in `@gaunt-sloth/agent`, which strips a FINISHED subagent's own messages; why that costs
+ * nothing is argued there.
+ */
+export declare function stripReasoningBlocks(content: unknown): unknown;

package/dist/core/reasoningBlocks.js

@@ -0,0 +1,103 @@
+/**
+ * @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.
+ *
+ * A pure content transform with no opinion about graph state — what a caller does with the result is
+ * the caller's argument to make. Every caller in this package only READS the result — rendering it,
+ * or pulling a refusal's explanation out of it — so the message kept in state stays whole and its
+ * thought parts (and any `thoughtSignature` riding with them) still replay to the provider as
+ * history. The one caller that rewrites state instead is the subagent thought
+ * redaction in `@gaunt-sloth/agent`, which strips a FINISHED subagent's own messages; why that costs
+ * nothing is argued there.
+ */
+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;;;;;;;;;;;;;GAaG;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/runHeader.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module runHeader
+ * GS2-95 — the ONE spelling of the run header, the single line every command opens with.
+ *
+ * Two unrelated writers render it: the agent's `compact` rung
+ * (`GthAbstractAgent#compactHeaderStatus`) and the review document's opening line
+ * (`@gaunt-sloth/review`'s `reviewHeadingBlock`). They emit at different moments, through different
+ * helpers, into different sinks — so the only thing that can keep them saying the same thing is a
+ * shared builder rather than two templates that happen to match today.
+ *
+ * It is a leaf with **no imports at all**, for the reason `modelLabel` is: the agent reaches it
+ * during module load, and pulling console/filesystem helpers in to format one line would drag that
+ * graph along.
+ *
+ * The header carries no markdown, in any mode. The honest condition for a `##` prefix is not "this
+ * run is under GitHub Actions" but "the consumer renders markdown", and those differ in both
+ * directions — the Ink TUI renders markdown, a GHA *job log* does not while a GHA *step summary*
+ * does. That property belongs to the SINK, and one run has several at once (the TUI on screen, a
+ * posted PR comment, a session log on disk), so no single flag can be right for all of them.
+ * Formatting a header is not worth a per-sink capability, so there is no prefix anywhere.
+ */
+/** The product name the header opens with — the part a reader is meant to recognise across runs. */
+export declare const RUN_HEADER_NAME = "Gaunt Sloth";
+/** Separates the header's parts: U+00B7 MIDDLE DOT, padded with a space on each side. */
+export declare const RUN_HEADER_SEPARATOR = " \u00B7 ";
+/**
+ * Build the run header: `Gaunt Sloth · <command> · <model> (<provider>)`.
+ *
+ * `command` is the name of the command the USER typed (`review`, `exec`, `eval`), never the init
+ * verb that selects the agent's mode prompt — the two differ for every command that runs its work
+ * through another verb's prompt, and a header naming the verb misnames the run.
+ *
+ * `label` is the caller's already-resolved `model (provider)` half — `modelProviderLabel`'s one
+ * spelling of "which model served this run" (DL-6). It is resolved by the caller rather than here
+ * because the two writers gate it differently, and it is **dropped rather than faked** when nothing
+ * resolves (DL-7): the line then ends after the command, with no placeholder and no empty `()`.
+ */
+export declare function runHeaderLine(command: string, label?: string): string;

package/dist/core/runHeader.js

@@ -0,0 +1,42 @@
+/**
+ * @module runHeader
+ * GS2-95 — the ONE spelling of the run header, the single line every command opens with.
+ *
+ * Two unrelated writers render it: the agent's `compact` rung
+ * (`GthAbstractAgent#compactHeaderStatus`) and the review document's opening line
+ * (`@gaunt-sloth/review`'s `reviewHeadingBlock`). They emit at different moments, through different
+ * helpers, into different sinks — so the only thing that can keep them saying the same thing is a
+ * shared builder rather than two templates that happen to match today.
+ *
+ * It is a leaf with **no imports at all**, for the reason `modelLabel` is: the agent reaches it
+ * during module load, and pulling console/filesystem helpers in to format one line would drag that
+ * graph along.
+ *
+ * The header carries no markdown, in any mode. The honest condition for a `##` prefix is not "this
+ * run is under GitHub Actions" but "the consumer renders markdown", and those differ in both
+ * directions — the Ink TUI renders markdown, a GHA *job log* does not while a GHA *step summary*
+ * does. That property belongs to the SINK, and one run has several at once (the TUI on screen, a
+ * posted PR comment, a session log on disk), so no single flag can be right for all of them.
+ * Formatting a header is not worth a per-sink capability, so there is no prefix anywhere.
+ */
+/** The product name the header opens with — the part a reader is meant to recognise across runs. */
+export const RUN_HEADER_NAME = 'Gaunt Sloth';
+/** Separates the header's parts: U+00B7 MIDDLE DOT, padded with a space on each side. */
+export const RUN_HEADER_SEPARATOR = ' · ';
+/**
+ * Build the run header: `Gaunt Sloth · <command> · <model> (<provider>)`.
+ *
+ * `command` is the name of the command the USER typed (`review`, `exec`, `eval`), never the init
+ * verb that selects the agent's mode prompt — the two differ for every command that runs its work
+ * through another verb's prompt, and a header naming the verb misnames the run.
+ *
+ * `label` is the caller's already-resolved `model (provider)` half — `modelProviderLabel`'s one
+ * spelling of "which model served this run" (DL-6). It is resolved by the caller rather than here
+ * because the two writers gate it differently, and it is **dropped rather than faked** when nothing
+ * resolves (DL-7): the line then ends after the command, with no placeholder and no empty `()`.
+ */
+export function runHeaderLine(command, label) {
+    const head = RUN_HEADER_NAME + RUN_HEADER_SEPARATOR + command;
+    return label ? head + RUN_HEADER_SEPARATOR + label : head;
+}
+//# sourceMappingURL=runHeader.js.map

package/dist/core/runHeader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runHeader.js","sourceRoot":"","sources":["../../src/core/runHeader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C,yFAAyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,KAAc;IAC3D,MAAM,IAAI,GAAG,eAAe,GAAG,oBAAoB,GAAG,OAAO,CAAC;IAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,oBAAoB,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC"}