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

package/dist/core/contextWindow.d.ts

@@ -0,0 +1,146 @@
+import { type CatalogOptions, type ProviderCatalog } from '#src/providers/modelCatalog.js';
+import type { ProviderId } from '#src/providers/modelDiscovery.js';
+/**
+ * GS2-59 — default context window (`num_ctx`) for Ollama models. Ollama's OWN default is 4096, but
+ * gaunt-sloth's agentic prompt (system + full lean toolset + a tool result) already lands ~4000
+ * tokens; at 4096 a thinking model (e.g. gemma4:31b) spends its entire remaining budget on the
+ * reasoning field and emits EMPTY `content` on the turn after a tool executes — the GS2-59
+ * blank-answer regression. The OpenAI-compat `/v1` shim IGNORES `num_ctx`; the native `/api/chat`
+ * path honors it.
+ *
+ * 16384 is chosen as the largest window that is BOTH safely above the ~4000-token starvation point
+ * (4× headroom for reasoning + a few tool results) AND fits constrained consumer VRAM: Ollama
+ * preallocates the KV cache at `num_ctx`, so on a box where a large model already spills partly to
+ * CPU (e.g. a 19GB model on ~18GB of GPU), a 32768 cache tips the GPU allocation into an
+ * out-of-memory error. 16384 was verified live to run the agentic tool→synthesis turn on such a
+ * box; 32768 OOM'd it. Overridable per config via `llm.numCtx` — raise it if you have the VRAM and
+ * run long sessions, lower it on very tight hardware. NOTE: a per-request `num_ctx` overrides the
+ * daemon's `OLLAMA_CONTEXT_LENGTH`, so a user who tuned their server window higher should set
+ * `llm.numCtx` to match rather than rely on the server default.
+ *
+ * It lives here rather than in the provider module because two things now need it — the client the
+ * provider builds and the guard that has to know what that client will send — and a second copy is
+ * how the guard would come to reason about a window the request does not use.
+ */
+export declare const DEFAULT_OLLAMA_NUM_CTX = 16384;
+/**
+ * The model's context window in tokens, or `null` when it is not known.
+ *
+ * Asynchronous because a source may have to ask the provider. Called on every model call, so an
+ * implementation that does I/O is expected to memoise; {@link resolveContextWindowSource} does.
+ */
+export type ContextWindowSource = () => Promise<number | null>;
+/** A source that never knows — the honest answer for every provider no source is wired for. */
+export declare const UNKNOWN_CONTEXT_WINDOW: ContextWindowSource;
+/**
+ * The fields the window resolver reads off a chat model, without depending on its class.
+ *
+ * Structural rather than a `ChatOllama` import on purpose: the provider module loads
+ * `@langchain/ollama` dynamically so a session that never uses ollama never pays for it, and typing
+ * against the class here would undo that.
+ */
+export interface OllamaLikeModel {
+    _llmType?: () => string;
+    numCtx?: number;
+    model?: string;
+    baseUrl?: string;
+}
+/**
+ * **The ollama window: what we send, capped by what the model can hold.**
+ *
+ * The effective window is `numCtx` — the number gaunt-sloth puts on every native `/api/chat`
+ * request, which overrides the daemon's own `OLLAMA_CONTEXT_LENGTH` — and never the daemon default,
+ * because the request is what decides. It is then capped by the model's own `context_length` from
+ * `/api/show`: asking for more than the model has does not buy more room, so guarding against the
+ * larger number would let exactly the truncation this guard exists to prevent happen anyway.
+ *
+ * **Fail-soft in one direction only.** No daemon, a slow daemon, an unreadable answer — the
+ * configured number stands, because that is still the number the request will carry. Nothing here
+ * throws, and nothing here degrades a known window to unknown.
+ */
+export declare function createOllamaContextWindowSource(llm: OllamaLikeModel): ContextWindowSource;
+/** Where a resolved context window came from — carried so `/status` can say, and a wrong one is
+ * diagnosable instead of mysterious. */
+export type ContextWindowOrigin = 'ollama' | 'models.dev' | 'profile' | 'unknown';
+/** A resolved window and its provenance. `tokens: null` means "not known", and never "zero". */
+export interface ContextWindowReading {
+    tokens: number | null;
+    origin: ContextWindowOrigin;
+}
+/** How each origin is described to a user, in a sentence that says where to go to change it. */
+export declare const CONTEXT_WINDOW_ORIGIN_LABELS: Readonly<Record<ContextWindowOrigin, string>>;
+/**
+ * The model's window as the LangChain provider package declares it: `llm.profile.maxInputTokens`.
+ *
+ * A getter on `BaseLanguageModel` that the base class answers with `{}` and each provider package
+ * overrides, so an id its table has never heard of yields `undefined` rather than an error —
+ * measured: `gpt-4o-mini` gives 128000 and `mistralai/mistral-7b-instruct` gives nothing. Wrapped
+ * in a `try` because it is a getter on someone else's object and a throw here would take down a
+ * resolution that has a perfectly good answer to fall back to.
+ */
+export declare function readProfileContextWindow(llm: unknown): number | null;
+/** What {@link resolveContextWindow} needs beyond the model itself — all of it injectable. */
+export interface ContextWindowResolutionOptions {
+    /**
+     * The gth provider namespace (`anthropic`, `google-genai`, …) — `config.modelProviderType`, NOT
+     * the model class's `_llmType()`. The two disagree exactly where it matters: `huggingface`
+     * reports `openai`, and both Gemini providers report `google`, so keying the catalog on the
+     * class's own label would read the wrong provider's slice or none at all.
+     */
+    providerId?: string;
+    /** The model id as models.dev keys it — `llm.model`, e.g. `claude-sonnet-4-5`. */
+    modelId?: string;
+    /**
+     * Options threaded to {@link getProviderCatalog} (cache dir, TTL, fetch impl) for hermetic tests.
+     *
+     * **`cacheOnly` defaults to `true` here and nowhere else.** This resolution sits in front of the
+     * first model call of a session, and a cold `api.json` fetch is a few MB behind a 10 s timeout —
+     * a delay the user would experience as the agent hanging before it said anything, to decide a
+     * threshold that already has a fallback. `gth init` passes `cacheOnly: false` because it is an
+     * explicit, interactive step that can afford to wait, and filling the cache there is what makes
+     * the runtime read a hit.
+     */
+    catalogOptions?: CatalogOptions;
+    /** Catalog reader override; {@link getProviderCatalog} when omitted. Injected by the tests. */
+    catalogReader?: (_providerId: ProviderId, _options: CatalogOptions) => Promise<ProviderCatalog | null>;
+    /** Profile reader override; {@link readProfileContextWindow} when omitted. Injected by the tests. */
+    profileReader?: (_llm: unknown) => number | null;
+}
+/**
+ * One resolution, read two ways: {@link ResolvedContextWindow.source} for the guard, which wants
+ * only the number, and {@link ResolvedContextWindow.read} for `/status`, which also wants the
+ * provenance.
+ *
+ * They are handed out as a pair from a single factory call, over a single memoised promise, so the
+ * number `/status` prints is by construction the number the guard enforced. Two independent
+ * resolvers could disagree — a stale catalog on one and a fresh fetch on the other — and a
+ * `/status` that describes a threshold nobody is using is worse than no `/status` line at all.
+ */
+export interface ResolvedContextWindow {
+    /** The window in tokens, or `null` for unknown. Memoised; safe to call before every model call. */
+    source: ContextWindowSource;
+    /** The same resolution with its provenance attached. Shares the memoised promise. */
+    read: () => Promise<ContextWindowReading>;
+}
+/**
+ * **The one place a model is matched to a context window.** Tries ollama, then models.dev, then the
+ * LangChain profile, and answers `{ tokens: null, origin: 'unknown' }` when none of them knows.
+ *
+ * **There is deliberately no `?? DEFAULT` anywhere on this path.** One fallback turns every unknown
+ * window into a confident wrong number, which is the 4097 failure this file opens by naming.
+ *
+ * The whole resolution is memoised as a PROMISE, for the reason the ollama source already gives:
+ * this runs before every model call, the answer cannot change during a session, and holding the
+ * promise rather than the value means concurrent calls share one catalog read instead of racing to
+ * make several.
+ */
+export declare function resolveContextWindow(llm: unknown, options?: ContextWindowResolutionOptions): ResolvedContextWindow;
+/**
+ * The window as a bare number, for a caller that does not need the provenance.
+ *
+ * A thin wrapper over {@link resolveContextWindow} rather than a second implementation, so the two
+ * cannot answer differently. With no options it consults only the sources that need no
+ * configuration — ollama and the profile — which is why a plain object with neither still answers
+ * `null`.
+ */
+export declare function resolveContextWindowSource(llm: unknown, options?: ContextWindowResolutionOptions): ContextWindowSource;

package/dist/core/contextWindow.js

@@ -0,0 +1,256 @@
+/**
+ * @packageDocumentation
+ * EXT-160 — **how many tokens the model in front of us will actually accept.**
+ *
+ * The pre-call context guard needs one number: the window, in tokens. This module resolves it, and
+ * its contract is the part that matters — **`null` means "unknown", and an unknown window never
+ * triggers anything.** A guard that guesses a window is worse than no guard: LangChain's own
+ * overflow fallback guesses 4097 for anything it does not recognise, which on a 262144-token local
+ * model would compact a conversation that had all the room in the world. So every source here
+ * either knows or says it does not.
+ *
+ * The source is **injectable and per-provider**, and there are three of them, tried in a fixed
+ * order by {@link resolveContextWindow}:
+ *
+ * 1. **ollama** — the number this session will actually put on the request (`num_ctx`), capped by
+ *    the model's own `context_length`. Ollama is the only provider that cannot report an overflow
+ *    at all: it silently drops the oldest tokens to fit and answers from the remainder, so knowing
+ *    the number beforehand is the only defence.
+ * 2. **models.dev** ([[EXT-161]]) — the cloud catalog's `limit.context`, read through the
+ *    cache-first slice `providers/modelCatalog.ts` already maintains.
+ * 3. **the LangChain profile** ([[EXT-161]]) — `llm.profile.maxInputTokens`, a backstop.
+ *
+ * **models.dev outranks the profile, and the order is a ruling rather than a preference.** The
+ * profile is a table compiled into a provider package, so it moves only when that package is
+ * republished and we bump it, while the catalog refreshes on a 24h TTL. That makes a profile
+ * **wrong as well as absent**: measured on this repo's pinned packages, `deepseek-chat` reports a
+ * 1,000,000-token window from `@langchain/deepseek`'s own table. Wrong-and-confident is the failure
+ * this order avoids — an overstated window means no preventive compaction at all, which is exactly
+ * the case the reactive seam then has to catch.
+ *
+ * **A model none of the three knows resolves to `null`, and `null` triggers nothing.** There is
+ * deliberately no default anywhere in this chain: LangChain's own overflow fallback guesses 4097
+ * for an unrecognised model, which on a 262144-token local model would compact a conversation that
+ * had all the room in the world, and on an unknown cloud model would compact at roughly 3.3k tokens
+ * with nothing on screen to say why.
+ */
+import { debugLog } from '#src/utils/debugUtils.js';
+import { getProviderCatalog, } from '#src/providers/modelCatalog.js';
+/**
+ * GS2-59 — default context window (`num_ctx`) for Ollama models. Ollama's OWN default is 4096, but
+ * gaunt-sloth's agentic prompt (system + full lean toolset + a tool result) already lands ~4000
+ * tokens; at 4096 a thinking model (e.g. gemma4:31b) spends its entire remaining budget on the
+ * reasoning field and emits EMPTY `content` on the turn after a tool executes — the GS2-59
+ * blank-answer regression. The OpenAI-compat `/v1` shim IGNORES `num_ctx`; the native `/api/chat`
+ * path honors it.
+ *
+ * 16384 is chosen as the largest window that is BOTH safely above the ~4000-token starvation point
+ * (4× headroom for reasoning + a few tool results) AND fits constrained consumer VRAM: Ollama
+ * preallocates the KV cache at `num_ctx`, so on a box where a large model already spills partly to
+ * CPU (e.g. a 19GB model on ~18GB of GPU), a 32768 cache tips the GPU allocation into an
+ * out-of-memory error. 16384 was verified live to run the agentic tool→synthesis turn on such a
+ * box; 32768 OOM'd it. Overridable per config via `llm.numCtx` — raise it if you have the VRAM and
+ * run long sessions, lower it on very tight hardware. NOTE: a per-request `num_ctx` overrides the
+ * daemon's `OLLAMA_CONTEXT_LENGTH`, so a user who tuned their server window higher should set
+ * `llm.numCtx` to match rather than rely on the server default.
+ *
+ * It lives here rather than in the provider module because two things now need it — the client the
+ * provider builds and the guard that has to know what that client will send — and a second copy is
+ * how the guard would come to reason about a window the request does not use.
+ */
+export const DEFAULT_OLLAMA_NUM_CTX = 16384;
+/** How long the daemon gets to answer `/api/show` before the cap is treated as unknown. */
+const SHOW_TIMEOUT_MS = 3000;
+/** A source that never knows — the honest answer for every provider no source is wired for. */
+export const UNKNOWN_CONTEXT_WINDOW = async () => null;
+/** Whether a resolved chat model is the native `ChatOllama` client (`_llmType()` is `'ollama'`). */
+function isOllamaModel(llm) {
+    try {
+        const type = llm?._llmType?.();
+        return type === 'ollama';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The model's own maximum from the daemon: `/api/show` reports `model_info` keyed by architecture,
+ * e.g. `gemma4.context_length`. Returns `null` on any failure — no daemon, a model the daemon does
+ * not have, a timeout, a response shaped differently by a future ollama — because a cap we could
+ * not read is not a cap of zero.
+ */
+async function readOllamaModelCap(baseUrl, model) {
+    try {
+        const response = await fetch(`${baseUrl.replace(/\/+$/, '')}/api/show`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ model }),
+            signal: AbortSignal.timeout(SHOW_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        const info = body?.model_info;
+        if (!info || typeof info !== 'object')
+            return null;
+        // Prefer the architecture the daemon itself names; fall back to any `*.context_length` key so a
+        // model whose `general.architecture` is missing still reports its window.
+        const architecture = info['general.architecture'];
+        const keys = typeof architecture === 'string' && architecture.length > 0
+            ? [`${architecture}.context_length`]
+            : Object.keys(info).filter((key) => key.endsWith('.context_length'));
+        for (const key of keys) {
+            const value = info[key];
+            if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+                return value;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * **The ollama window: what we send, capped by what the model can hold.**
+ *
+ * The effective window is `numCtx` — the number gaunt-sloth puts on every native `/api/chat`
+ * request, which overrides the daemon's own `OLLAMA_CONTEXT_LENGTH` — and never the daemon default,
+ * because the request is what decides. It is then capped by the model's own `context_length` from
+ * `/api/show`: asking for more than the model has does not buy more room, so guarding against the
+ * larger number would let exactly the truncation this guard exists to prevent happen anyway.
+ *
+ * **Fail-soft in one direction only.** No daemon, a slow daemon, an unreadable answer — the
+ * configured number stands, because that is still the number the request will carry. Nothing here
+ * throws, and nothing here degrades a known window to unknown.
+ */
+export function createOllamaContextWindowSource(llm) {
+    const configured = typeof llm.numCtx === 'number' && llm.numCtx > 0 ? llm.numCtx : undefined;
+    // `providers/ollama.ts` always sets `numCtx`, so the default below is reached only by a chat model
+    // a JS config built by hand.
+    const requested = configured ?? DEFAULT_OLLAMA_NUM_CTX;
+    const baseUrl = typeof llm.baseUrl === 'string' ? llm.baseUrl : undefined;
+    const model = typeof llm.model === 'string' ? llm.model : undefined;
+    // Memoised: the window cannot change during a session, and the guard runs before EVERY model
+    // call. A per-call `/api/show` would put a network round trip in front of each one. Held as the
+    // PROMISE so concurrent calls share the one request rather than racing to make several.
+    let pending;
+    return async () => {
+        if (!baseUrl || !model)
+            return requested;
+        pending ??= readOllamaModelCap(baseUrl, model);
+        const cap = await pending;
+        if (cap === null)
+            return requested;
+        const effective = Math.min(requested, cap);
+        if (effective !== requested) {
+            debugLog(`Ollama context window: requested num_ctx ${requested} exceeds ${model}'s own ` +
+                `${cap}; guarding against ${effective}.`);
+        }
+        return effective;
+    };
+}
+/** How each origin is described to a user, in a sentence that says where to go to change it. */
+export const CONTEXT_WINDOW_ORIGIN_LABELS = {
+    ollama: "this session's num_ctx, capped by the model's own context length",
+    'models.dev': 'the models.dev catalog',
+    profile: "the provider package's built-in model profile",
+    unknown: 'nowhere — no source knows this model, so nothing is compacted preventively',
+};
+/**
+ * The model's window as the LangChain provider package declares it: `llm.profile.maxInputTokens`.
+ *
+ * A getter on `BaseLanguageModel` that the base class answers with `{}` and each provider package
+ * overrides, so an id its table has never heard of yields `undefined` rather than an error —
+ * measured: `gpt-4o-mini` gives 128000 and `mistralai/mistral-7b-instruct` gives nothing. Wrapped
+ * in a `try` because it is a getter on someone else's object and a throw here would take down a
+ * resolution that has a perfectly good answer to fall back to.
+ */
+export function readProfileContextWindow(llm) {
+    try {
+        const profile = llm?.profile;
+        const max = profile?.maxInputTokens;
+        return typeof max === 'number' && Number.isFinite(max) && max > 0 ? max : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * **The one place a model is matched to a context window.** Tries ollama, then models.dev, then the
+ * LangChain profile, and answers `{ tokens: null, origin: 'unknown' }` when none of them knows.
+ *
+ * **There is deliberately no `?? DEFAULT` anywhere on this path.** One fallback turns every unknown
+ * window into a confident wrong number, which is the 4097 failure this file opens by naming.
+ *
+ * The whole resolution is memoised as a PROMISE, for the reason the ollama source already gives:
+ * this runs before every model call, the answer cannot change during a session, and holding the
+ * promise rather than the value means concurrent calls share one catalog read instead of racing to
+ * make several.
+ */
+export function resolveContextWindow(llm, options = {}) {
+    const ollamaSource = isOllamaModel(llm) ? createOllamaContextWindowSource(llm) : null;
+    const catalogReader = options.catalogReader ?? getProviderCatalog;
+    const profileReader = options.profileReader ?? readProfileContextWindow;
+    const providerId = options.providerId?.trim();
+    const modelId = options.modelId?.trim();
+    let pending;
+    const resolve = async () => {
+        // 1. Ollama — the number the request will actually carry. It is asked first and not merely
+        //    preferred: models.dev deliberately has no ollama entry (local models have no catalog
+        //    row), so for ollama there is nothing below this to fall through to.
+        if (ollamaSource) {
+            try {
+                const tokens = await ollamaSource();
+                if (tokens !== null && Number.isFinite(tokens) && tokens > 0) {
+                    return { tokens, origin: 'ollama' };
+                }
+            }
+            catch {
+                /* the ollama source is documented never to throw; a stub still might */
+            }
+        }
+        // 2. models.dev — RULED to outrank the profile. See the module docblock for why.
+        if (providerId && modelId) {
+            try {
+                const catalog = await catalogReader(providerId, {
+                    cacheOnly: true,
+                    ...options.catalogOptions,
+                });
+                const context = catalog?.models?.[modelId]?.limit?.context;
+                if (typeof context === 'number' && Number.isFinite(context) && context > 0) {
+                    return { tokens: context, origin: 'models.dev' };
+                }
+            }
+            catch {
+                // `getProviderCatalog` never throws by contract (catalog availability must never block a
+                // model), so this catches an injected stub only — but a resolution that fell over here
+                // would take the profile backstop down with it, which is the opposite of degrading well.
+            }
+        }
+        // 3. The profile — a backstop, recorded as such so a wrong threshold is diagnosable.
+        try {
+            const profile = profileReader(llm);
+            if (profile !== null && Number.isFinite(profile) && profile > 0) {
+                return { tokens: profile, origin: 'profile' };
+            }
+        }
+        catch {
+            /* see readProfileContextWindow: someone else's getter */
+        }
+        return { tokens: null, origin: 'unknown' };
+    };
+    const read = () => (pending ??= resolve());
+    return { read, source: async () => (await read()).tokens };
+}
+/**
+ * The window as a bare number, for a caller that does not need the provenance.
+ *
+ * A thin wrapper over {@link resolveContextWindow} rather than a second implementation, so the two
+ * cannot answer differently. With no options it consults only the sources that need no
+ * configuration — ollama and the profile — which is why a plain object with neither still answers
+ * `null`.
+ */
+export function resolveContextWindowSource(llm, options = {}) {
+    return resolveContextWindow(llm, options).source;
+}
+//# sourceMappingURL=contextWindow.js.map

package/dist/core/contextWindow.js.map

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

package/dist/core/exitOutputChannel.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module exitOutputChannel
+ * TUI-C56 — the queue for output that must OUTLIVE the session's own screen.
+ *
+ * TUI-C48 put the whole interactive session in the terminal's alternate screen. Ink treats
+ * alternate-screen teardown output as disposable by design: on unmount it restores the primary
+ * buffer without replaying prior frames, so everything the session painted — every notice, every
+ * answer — goes with the alternate buffer when the session ends. That is exactly what the
+ * full-screen surface is for, and it is the right default for a conversation.
+ *
+ * It is the wrong default for the handful of things a user must still have AFTER the session:
+ * a path they now have to go and open. The first of those is the `/debug-dump` archive, whose
+ * in-frame notice is genuinely useful mid-session and completely gone the moment the user exits —
+ * leaving them holding a diagnostic bundle they cannot find, with nothing having errored.
+ *
+ * So this is a channel, not a special case: a producer anywhere in the codebase can DEFER one
+ * block of text, and the surface that owns the terminal drains it once the terminal is its
+ * owner's again. Two halves, deliberately split:
+ *
+ * - **This module is the queue and nothing else.** No stream, no formatting, no policy about
+ *   when a line is worth printing. That keeps it surface-agnostic and directly testable.
+ * - **The surface owns the write.** Only the surface knows when its terminal is back (for the
+ *   Ink TUI: after `waitUntilExit()` has resolved, which is after Ink has left the alternate
+ *   screen) and whether writing is appropriate at all (a piped run must not get an extra line
+ *   its caller did not ask for). See `writeDeferredExitOutput` in the TUI session module.
+ *
+ * A surface whose output already survives its own exit — the readline (`--no-tui`) session, which
+ * never owned an alternate screen — simply never drains. Deferring is then a no-op that costs one
+ * array entry and prints nothing, which is what keeps the producers surface-agnostic: `/debug-dump`
+ * is one command with one behaviour, and the two surfaces differ only in whether the re-print is
+ * needed at all.
+ */
+/**
+ * Defer one block of text until the surface hands the terminal back.
+ *
+ * The text should stand on its own: it lands on a restored screen with none of the session's
+ * framing around it and possibly a long scrollback above it, so a bare value with no label is not
+ * enough for a reader to know what they are looking at.
+ */
+export declare function deferExitOutput(text: string): void;
+/**
+ * Take everything deferred so far, emptying the queue. Draining is destructive so a second drain
+ * — a surface with more than one exit path reaching the drain twice — cannot double-print.
+ */
+export declare function drainExitOutput(): string[];
+/**
+ * Discard anything deferred without emitting it. A surface calls this as it starts, so a block
+ * deferred by something earlier in the same process can never surface at the end of a session
+ * that had nothing to do with it.
+ */
+export declare function clearExitOutput(): void;

package/dist/core/exitOutputChannel.js

@@ -0,0 +1,65 @@
+/**
+ * @module exitOutputChannel
+ * TUI-C56 — the queue for output that must OUTLIVE the session's own screen.
+ *
+ * TUI-C48 put the whole interactive session in the terminal's alternate screen. Ink treats
+ * alternate-screen teardown output as disposable by design: on unmount it restores the primary
+ * buffer without replaying prior frames, so everything the session painted — every notice, every
+ * answer — goes with the alternate buffer when the session ends. That is exactly what the
+ * full-screen surface is for, and it is the right default for a conversation.
+ *
+ * It is the wrong default for the handful of things a user must still have AFTER the session:
+ * a path they now have to go and open. The first of those is the `/debug-dump` archive, whose
+ * in-frame notice is genuinely useful mid-session and completely gone the moment the user exits —
+ * leaving them holding a diagnostic bundle they cannot find, with nothing having errored.
+ *
+ * So this is a channel, not a special case: a producer anywhere in the codebase can DEFER one
+ * block of text, and the surface that owns the terminal drains it once the terminal is its
+ * owner's again. Two halves, deliberately split:
+ *
+ * - **This module is the queue and nothing else.** No stream, no formatting, no policy about
+ *   when a line is worth printing. That keeps it surface-agnostic and directly testable.
+ * - **The surface owns the write.** Only the surface knows when its terminal is back (for the
+ *   Ink TUI: after `waitUntilExit()` has resolved, which is after Ink has left the alternate
+ *   screen) and whether writing is appropriate at all (a piped run must not get an extra line
+ *   its caller did not ask for). See `writeDeferredExitOutput` in the TUI session module.
+ *
+ * A surface whose output already survives its own exit — the readline (`--no-tui`) session, which
+ * never owned an alternate screen — simply never drains. Deferring is then a no-op that costs one
+ * array entry and prints nothing, which is what keeps the producers surface-agnostic: `/debug-dump`
+ * is one command with one behaviour, and the two surfaces differ only in whether the re-print is
+ * needed at all.
+ */
+/**
+ * Blocks of deferred text, in the order they were deferred. Module-level, like the single
+ * subscriber in `toolOutputChannel`: one process hosts at most one interactive session, and no
+ * server surface reaches a producer (the slash-command registry is built only by the two
+ * interactive sessions).
+ */
+const deferred = [];
+/**
+ * Defer one block of text until the surface hands the terminal back.
+ *
+ * The text should stand on its own: it lands on a restored screen with none of the session's
+ * framing around it and possibly a long scrollback above it, so a bare value with no label is not
+ * enough for a reader to know what they are looking at.
+ */
+export function deferExitOutput(text) {
+    deferred.push(text);
+}
+/**
+ * Take everything deferred so far, emptying the queue. Draining is destructive so a second drain
+ * — a surface with more than one exit path reaching the drain twice — cannot double-print.
+ */
+export function drainExitOutput() {
+    return deferred.splice(0, deferred.length);
+}
+/**
+ * Discard anything deferred without emitting it. A surface calls this as it starts, so a block
+ * deferred by something earlier in the same process can never surface at the end of a session
+ * that had nothing to do with it.
+ */
+export function clearExitOutput() {
+    deferred.length = 0;
+}
+//# sourceMappingURL=exitOutputChannel.js.map

package/dist/core/exitOutputChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exitOutputChannel.js","sourceRoot":"","sources":["../../src/core/exitOutputChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH;;;;;GAKG;AACH,MAAM,QAAQ,GAAa,EAAE,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtB,CAAC"}

package/dist/core/refusal.d.ts

@@ -30,8 +30,15 @@ import type { GthTerminationClassification } from '#src/core/terminationReason.j
 /** 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`). */
+    provider: 'openai' | 'anthropic' | 'bedrock' | 'google' | 'unknown';
+    /**
+     * The stop/finish reason token that flagged the refusal, lower-cased (e.g. `content_filter`).
+     *
+     * Lower-cased rather than raw because the token's case is a per-provider spelling, not a fact:
+     * Gemini shouts `SAFETY` where OpenAI writes `content_filter`, and this value is matched, logged
+     * and carried into the taxonomy's `detail` — the same normalization
+     * {@link detectOutputTruncation} already applies to its own token.
+     */
     reason: string;
     /** Any model-provided explanation text (empty string when the refusal carried none). */
     explanation: string;
@@ -42,6 +49,9 @@ export interface RefusalInfo {
  * 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.
  *
+ * Reasons are compared lower-cased, because the case is a provider's spelling and not a fact —
+ * Gemini shouts `SAFETY` where OpenAI writes `content_filter`.
+ *
  * Covered shapes:
  *  - OpenAI-family `finish_reason: 'content_filter'` (also under `additional_kwargs`).
  *  - Anthropic `stop_reason: 'refusal'`.
@@ -51,6 +61,11 @@ export interface RefusalInfo {
  *  - 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).
+ *  - Gemini's safety reasons ({@link GEMINI_REFUSAL_REASONS}) under **camelCase `finishReason`**
+ *    (CFG-41). That key is the half that has to come first: `@langchain/google`'s streamed chunk
+ *    puts `model_provider` and nothing else in `response_metadata` and the reason only in
+ *    `additional_kwargs.finishReason`, so a token added without the key would sit on a branch that
+ *    never ran for Gemini.
  */
 export declare function detectRefusal(message: unknown): RefusalInfo | null;
 /**