@gaunt-sloth/core 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/runtime/askStructured.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module runtime/askStructured
+ *
+ * A reusable, non-agentic "ask the LLM and get a schema-validated object back" primitive — the
+ * structured-output half the (later) `gth workflow` host calls. Deliberately mirrors the
+ * *mechanism* of the structured-evaluation calls ({@link judgeEvalCase} — the EVAL GRADER in
+ * `@gaunt-sloth/batch`'s `judge.ts` — and its in-core sibling {@link rateShellCommand}, the
+ * approvals AI rater in `core/shell/rater.ts`):
+ * `model.withStructuredOutput(schema)` for a single structured call, `.invoke([SystemMessage,
+ * HumanMessage])` raced against a wall-clock timeout via `Promise.race`, a defensive `safeParse`
+ * re-validation, `clearTimeout` in `finally`, and — crucially — it **never throws**, returning a
+ * failure object instead.
+ *
+ * Differences from those two: this one is **generic** over the Zod schema and takes the
+ * system/user strings from the caller (they hard-code a schema and build a rubric/safety
+ * prompt), and it reads the model from `config.llm` (like `runSingleShot`/`rateShellCommand`),
+ * so the workflow host can hand it the resolved {@link GthConfig} directly. `judgeEvalCase` could
+ * later be refactored to delegate to this primitive — out of scope here.
+ */
+import * as z from 'zod';
+import type { GthConfig } from '#src/config.js';
+/**
+ * Default wall-clock budget (ms) for the structured LLM call — same value as their
+ * `EVAL_JUDGE_DEFAULT_TIMEOUT_MS` / `JUDGE_DEFAULT_TIMEOUT_MS`, kept as this module's own constant
+ * since the primitive is conceptually independent of them.
+ */
+export declare const ASK_STRUCTURED_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * The exact `error` text {@link askStructured} returns when its wall-clock budget fires — i.e. the
+ * provider produced **no answer at all** within the budget.
+ *
+ * Exported as a builder rather than left as an inline literal because the three failure classes here
+ * (no response · an answer that does not fit the schema · a call that failed outright) are the
+ * question a reader of a red run has to answer first, and they are only distinguishable by this text.
+ * A caller that re-types the sentence to recognise it stops recognising it the day the wording moves,
+ * and silently re-files a stall as a rejection — which is precisely the confusion this exists to end.
+ */
+export declare function structuredCallTimedOutError(timeoutMs: number): string;
+/**
+ * The exact `error` text {@link askStructured} returns when the provider **did** answer and the
+ * answer failed the caller's own schema. The counterpart of {@link structuredCallTimedOutError};
+ * see that doc for why both are exported rather than written inline.
+ */
+export declare const STRUCTURED_CALL_UNPARSEABLE_ERROR = "Model returned unparseable output.";
+/**
+ * Which of {@link askStructured}'s three failure paths a result came from.
+ *
+ * - `timeout` — the budget fired and the provider had returned nothing at all.
+ * - `unparseable` — the provider answered, and the answer failed the caller's schema.
+ * - `call-failed` — the call threw before any answer arrived: a provider rejection (OpenAI's 400 on
+ *   a strict `json_schema` is the canonical one), an auth failure, a transport failure.
+ */
+export type StructuredFailureKind = 'timeout' | 'unparseable' | 'call-failed';
+/**
+ * Name which failure happened, given the `error` string and the budget the call was made with.
+ *
+ * The single place the three classes are told apart. A stall and a rejection are the two failures a
+ * reader has to distinguish first and the two that look most alike from the outside — a red that
+ * cannot say which happened sends the reader to re-run a real defect, or to investigate a provider
+ * hiccup. Every caller that wants to say which one it was calls this rather than matching the prose
+ * itself, so the wording can only be got wrong in one place, and that place has a test.
+ *
+ * @param error The `error` from a `{ ok: false }` {@link AskStructuredResult}.
+ * @param timeoutMs The budget passed to that same {@link askStructured} call — the timeout text
+ *   carries it, so a different value here reports a genuine timeout as `call-failed`.
+ */
+export declare function classifyStructuredFailure(error: string, timeoutMs: number): StructuredFailureKind;
+/** Inputs to {@link askStructured}. The caller supplies the model (via config), the two message
+ * texts, and an optional timeout — the Zod schema is a separate positional argument so `<T>` can
+ * be inferred from it. */
+export interface AskStructuredOptions {
+    config: GthConfig;
+    /** System-message text (instructions). May be empty. */
+    system: string;
+    /** Human-message text (the actual content/question). */
+    user: string;
+    /** Wall-clock budget in ms. Default {@link ASK_STRUCTURED_DEFAULT_TIMEOUT_MS} (30_000). */
+    timeoutMs?: number;
+}
+/** Discriminated result of {@link askStructured}: the parsed value on success, an error string on
+ * any failure (unusable model, timeout, unparseable output, or a thrown error). Never throws. */
+export type AskStructuredResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Ask the configured model for a single schema-validated object — a non-agentic structured-output
+ * call that mirrors their mechanism (see the module doc) and never throws.
+ *
+ * - No usable model (`config.llm` missing or lacking `withStructuredOutput`) →
+ *   `{ ok: false, error: 'No usable model configured.' }`.
+ * - Timeout → `ok: false` with the error {@link structuredCallTimedOutError} builds for that budget.
+ * - Output that fails `schema.safeParse` → `{ ok: false, error: {@link STRUCTURED_CALL_UNPARSEABLE_ERROR} }`.
+ * - Any thrown error → `{ ok: false, error: <message> }` — a provider rejection (e.g. OpenAI's 400 on
+ *   a strict `json_schema`), an auth or transport failure. Distinct from the two above BY CODE PATH,
+ *   so a caller can classify a failure by comparing against those two exported texts.
+ * - Success → `{ ok: true, value }` with the parsed data.
+ *
+ * @param schema The Zod schema the model output must satisfy; `<T>` is inferred from it.
+ * @param opts The model (via `config.llm`), the system/user message texts, and an optional timeout.
+ */
+export declare function askStructured<T>(schema: z.ZodType<T>, opts: AskStructuredOptions): Promise<AskStructuredResult<T>>;

package/dist/runtime/askStructured.js

@@ -0,0 +1,120 @@
+/**
+ * @module runtime/askStructured
+ *
+ * A reusable, non-agentic "ask the LLM and get a schema-validated object back" primitive — the
+ * structured-output half the (later) `gth workflow` host calls. Deliberately mirrors the
+ * *mechanism* of the structured-evaluation calls ({@link judgeEvalCase} — the EVAL GRADER in
+ * `@gaunt-sloth/batch`'s `judge.ts` — and its in-core sibling {@link rateShellCommand}, the
+ * approvals AI rater in `core/shell/rater.ts`):
+ * `model.withStructuredOutput(schema)` for a single structured call, `.invoke([SystemMessage,
+ * HumanMessage])` raced against a wall-clock timeout via `Promise.race`, a defensive `safeParse`
+ * re-validation, `clearTimeout` in `finally`, and — crucially — it **never throws**, returning a
+ * failure object instead.
+ *
+ * Differences from those two: this one is **generic** over the Zod schema and takes the
+ * system/user strings from the caller (they hard-code a schema and build a rubric/safety
+ * prompt), and it reads the model from `config.llm` (like `runSingleShot`/`rateShellCommand`),
+ * so the workflow host can hand it the resolved {@link GthConfig} directly. `judgeEvalCase` could
+ * later be refactored to delegate to this primitive — out of scope here.
+ */
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { structuredOutputBoundary } from '#src/runtime/structuredOutput.js';
+/**
+ * Default wall-clock budget (ms) for the structured LLM call — same value as their
+ * `EVAL_JUDGE_DEFAULT_TIMEOUT_MS` / `JUDGE_DEFAULT_TIMEOUT_MS`, kept as this module's own constant
+ * since the primitive is conceptually independent of them.
+ */
+export const ASK_STRUCTURED_DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * The exact `error` text {@link askStructured} returns when its wall-clock budget fires — i.e. the
+ * provider produced **no answer at all** within the budget.
+ *
+ * Exported as a builder rather than left as an inline literal because the three failure classes here
+ * (no response · an answer that does not fit the schema · a call that failed outright) are the
+ * question a reader of a red run has to answer first, and they are only distinguishable by this text.
+ * A caller that re-types the sentence to recognise it stops recognising it the day the wording moves,
+ * and silently re-files a stall as a rejection — which is precisely the confusion this exists to end.
+ */
+export function structuredCallTimedOutError(timeoutMs) {
+    return `Structured call timed out after ${timeoutMs}ms with no response from the provider.`;
+}
+/**
+ * The exact `error` text {@link askStructured} returns when the provider **did** answer and the
+ * answer failed the caller's own schema. The counterpart of {@link structuredCallTimedOutError};
+ * see that doc for why both are exported rather than written inline.
+ */
+export const STRUCTURED_CALL_UNPARSEABLE_ERROR = 'Model returned unparseable output.';
+/**
+ * Name which failure happened, given the `error` string and the budget the call was made with.
+ *
+ * The single place the three classes are told apart. A stall and a rejection are the two failures a
+ * reader has to distinguish first and the two that look most alike from the outside — a red that
+ * cannot say which happened sends the reader to re-run a real defect, or to investigate a provider
+ * hiccup. Every caller that wants to say which one it was calls this rather than matching the prose
+ * itself, so the wording can only be got wrong in one place, and that place has a test.
+ *
+ * @param error The `error` from a `{ ok: false }` {@link AskStructuredResult}.
+ * @param timeoutMs The budget passed to that same {@link askStructured} call — the timeout text
+ *   carries it, so a different value here reports a genuine timeout as `call-failed`.
+ */
+export function classifyStructuredFailure(error, timeoutMs) {
+    if (error === structuredCallTimedOutError(timeoutMs))
+        return 'timeout';
+    if (error === STRUCTURED_CALL_UNPARSEABLE_ERROR)
+        return 'unparseable';
+    return 'call-failed';
+}
+/**
+ * Ask the configured model for a single schema-validated object — a non-agentic structured-output
+ * call that mirrors their mechanism (see the module doc) and never throws.
+ *
+ * - No usable model (`config.llm` missing or lacking `withStructuredOutput`) →
+ *   `{ ok: false, error: 'No usable model configured.' }`.
+ * - Timeout → `ok: false` with the error {@link structuredCallTimedOutError} builds for that budget.
+ * - Output that fails `schema.safeParse` → `{ ok: false, error: {@link STRUCTURED_CALL_UNPARSEABLE_ERROR} }`.
+ * - Any thrown error → `{ ok: false, error: <message> }` — a provider rejection (e.g. OpenAI's 400 on
+ *   a strict `json_schema`), an auth or transport failure. Distinct from the two above BY CODE PATH,
+ *   so a caller can classify a failure by comparing against those two exported texts.
+ * - Success → `{ ok: true, value }` with the parsed data.
+ *
+ * @param schema The Zod schema the model output must satisfy; `<T>` is inferred from it.
+ * @param opts The model (via `config.llm`), the system/user message texts, and an optional timeout.
+ */
+export async function askStructured(schema, opts) {
+    const { config, system, user } = opts;
+    const timeoutMs = opts.timeoutMs ?? ASK_STRUCTURED_DEFAULT_TIMEOUT_MS;
+    const model = config.llm;
+    if (!model || typeof model.withStructuredOutput !== 'function') {
+        return { ok: false, error: 'No usable model configured.' };
+    }
+    let timer;
+    try {
+        // EXT-88 — caller schemas are arbitrary, so this is the call site with the widest exposure to
+        // the optional-field problem the boundary exists for; it also does the defensive re-validation
+        // below, against the caller's own schema, so `<T>` is exactly what the caller declared.
+        const boundary = structuredOutputBoundary(schema);
+        const structured = model.withStructuredOutput(boundary.wireSchema);
+        const invokePromise = structured.invoke([new SystemMessage(system), new HumanMessage(user)]);
+        const TIMEOUT = Symbol('ask-structured-timeout');
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(TIMEOUT), timeoutMs);
+        });
+        const raced = await Promise.race([invokePromise, timeoutPromise]);
+        if (raced === TIMEOUT) {
+            return { ok: false, error: structuredCallTimedOutError(timeoutMs) };
+        }
+        const parsed = boundary.safeParse(raced);
+        if (!parsed.success) {
+            return { ok: false, error: STRUCTURED_CALL_UNPARSEABLE_ERROR };
+        }
+        return { ok: true, value: parsed.data };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=askStructured.js.map

package/dist/runtime/askStructured.js.map

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

package/dist/runtime/conversation.d.ts

@@ -0,0 +1,64 @@
+import type { GthConfig } from '#src/config.js';
+import type { AgentResolvers, GthAgentFactory, GthCommand } from '#src/core/types.js';
+import type { SingleShotOptions } from '#src/runtime/singleShot.js';
+import type { GthRunStats } from '#src/core/types.js';
+/**
+ * One turn's result inside a {@link runConversation} run: the per-turn `ok`/`answer` plus that
+ * turn's run stats (GS2-16 {@link GthRunStats} — token usage + invoked tools), captured PER TURN (a
+ * per-invoke delta, not the cumulative conversation total). `ok` is `false` when that turn's agent
+ * invocation failed (`error` set, `answer` empty). Extends `GthRunStats` rather than restating its
+ * fields — same shape {@link ../runtime/singleShot.js SingleShotResult} uses.
+ */
+export interface ConversationTurnResult extends GthRunStats {
+    /** `true` when this turn completed without error, `false` when it failed. */
+    ok: boolean;
+    /** This turn's full answer text (`runner.processMessages()`'s return value). Empty on failure. */
+    answer: string;
+    /** Set when `ok` is `false`: why this turn failed. */
+    error?: string;
+}
+/**
+ * Run a scripted MULTI-TURN conversation and return one {@link ConversationTurnResult} per turn.
+ *
+ * This is the **conversational** counterpart to {@link ../runtime/singleShot.js runSingleShot}
+ * (which is stateless — a fresh agent per call). It builds the agent + resolves tools ONCE, then
+ * runs each turn against the ACCUMULATED message history so cross-turn "memory" / identity behaviour
+ * is real, and cleans up ONCE at the end (reusing runSingleShot's cleanup discipline — the resolvers
+ * are the caller's to tear down, exactly as with runSingleShot).
+ *
+ * **History mechanism = stateless replay of the growing message array.** Messages accumulate as
+ * `[user1, ai1, user2, ai2, …]`: per turn a `HumanMessage(user)` is appended, the agent runs on the
+ * WHOLE array, and its answer is appended as an `AIMessage` so the next turn sees it. The system
+ * prompt is NOT seeded here — the agent composes it via `createAgent({ systemPrompt })` (BATCH-13;
+ * see `runSingleShot`), so the replayed array carries only human/assistant turns. Before each
+ * turn the runner's thread is rotated ({@link GthAgentRunner.resetThread}) so the checkpointer starts
+ * empty and the replayed array is the sole history (no `add_messages` double-append). This mirrors
+ * the AG-UI server's "client is the source of truth for history — it sends the full message list
+ * every turn" model and reuses the existing `processMessages` + `resetThread` machinery with no new
+ * agent surface. **Known limitation (unverified pending a live pass):** replay carries prior
+ * *answers* (as `AIMessage` text) but NOT prior tool-call / tool-result messages — a checkpointer-
+ * thread approach (send only the new message, let `add_messages` accumulate) would preserve those.
+ *
+ * **Per-turn tool capture (GS2-16):** `processMessages` resets the analytics tally at its top, so
+ * `getRunStats()` read right after each turn returns THAT turn's tool/token delta (not cumulative).
+ *
+ * A turn that fails is recorded (`ok:false`, `error`) and the conversation STOPS (later turns depend
+ * on the broken context), so the returned array may be shorter than `userMessages` — the caller
+ * (`gth eval`'s runner) fails the un-run turns.
+ *
+ * @param source - The source label (used for output/session-file naming), e.g. `EVAL-<cellId>`.
+ * @param _preamble - Deprecated/ignored (BATCH-13): the agent composes the system prompt itself (via
+ *   `createAgent({ systemPrompt })`); seeding it here too produced a second system message that
+ *   `@langchain/anthropic` rejects. Retained positionally so existing callers need no change.
+ * @param userMessages - The ordered user turns to send (one conversation).
+ * @param config - The resolved config.
+ * @param resolvers - Optional agent resolvers (tools/middleware); the caller owns their cleanup.
+ * @param command - The originating command (defaults to `ask`); selects the agent mode prompt.
+ * @param agentFactory - Optional backend factory (B5); omitted = the runner's lean default, which
+ *   is also what the shared backend seam resolves to.
+ * @param options - GS2-95: `displayCommand` names the run in the header when the caller's own name
+ *   differs from the `command` it runs under (`gth eval` runs its conversations in `ask` mode).
+ *   Header only — it never reaches the mode prompt.
+ * @returns One {@link ConversationTurnResult} per turn attempted, in turn order.
+ */
+export declare function runConversation(source: string, _preamble: string, userMessages: string[], config: GthConfig, resolvers?: AgentResolvers, command?: GthCommand, agentFactory?: GthAgentFactory, options?: SingleShotOptions): Promise<ConversationTurnResult[]>;

package/dist/runtime/conversation.js

@@ -0,0 +1,171 @@
+import { defaultStatusCallback, display, displayError, displaySuccess, flushSessionLog, initSessionLogging, stopSessionLogging, } from '#src/utils/consoleUtils.js';
+import { getCommandOutputFilePath } from '#src/utils/fileUtils.js';
+import { GthAgentRunner } from '#src/core/GthAgentRunner.js';
+import { MemorySaver } from '@langchain/langgraph';
+import { AIMessage, HumanMessage } from '@langchain/core/messages';
+import { ProgressIndicator } from '#src/utils/ProgressIndicator.js';
+import { recordSessionSafe } from '#src/history/recordSession.js';
+import { getProjectDir, stdout } from '#src/utils/systemUtils.js';
+import { ApprovalStopError, approvalStopRows } from '#src/core/shell/approvalStop.js';
+/**
+ * Run a scripted MULTI-TURN conversation and return one {@link ConversationTurnResult} per turn.
+ *
+ * This is the **conversational** counterpart to {@link ../runtime/singleShot.js runSingleShot}
+ * (which is stateless — a fresh agent per call). It builds the agent + resolves tools ONCE, then
+ * runs each turn against the ACCUMULATED message history so cross-turn "memory" / identity behaviour
+ * is real, and cleans up ONCE at the end (reusing runSingleShot's cleanup discipline — the resolvers
+ * are the caller's to tear down, exactly as with runSingleShot).
+ *
+ * **History mechanism = stateless replay of the growing message array.** Messages accumulate as
+ * `[user1, ai1, user2, ai2, …]`: per turn a `HumanMessage(user)` is appended, the agent runs on the
+ * WHOLE array, and its answer is appended as an `AIMessage` so the next turn sees it. The system
+ * prompt is NOT seeded here — the agent composes it via `createAgent({ systemPrompt })` (BATCH-13;
+ * see `runSingleShot`), so the replayed array carries only human/assistant turns. Before each
+ * turn the runner's thread is rotated ({@link GthAgentRunner.resetThread}) so the checkpointer starts
+ * empty and the replayed array is the sole history (no `add_messages` double-append). This mirrors
+ * the AG-UI server's "client is the source of truth for history — it sends the full message list
+ * every turn" model and reuses the existing `processMessages` + `resetThread` machinery with no new
+ * agent surface. **Known limitation (unverified pending a live pass):** replay carries prior
+ * *answers* (as `AIMessage` text) but NOT prior tool-call / tool-result messages — a checkpointer-
+ * thread approach (send only the new message, let `add_messages` accumulate) would preserve those.
+ *
+ * **Per-turn tool capture (GS2-16):** `processMessages` resets the analytics tally at its top, so
+ * `getRunStats()` read right after each turn returns THAT turn's tool/token delta (not cumulative).
+ *
+ * A turn that fails is recorded (`ok:false`, `error`) and the conversation STOPS (later turns depend
+ * on the broken context), so the returned array may be shorter than `userMessages` — the caller
+ * (`gth eval`'s runner) fails the un-run turns.
+ *
+ * @param source - The source label (used for output/session-file naming), e.g. `EVAL-<cellId>`.
+ * @param _preamble - Deprecated/ignored (BATCH-13): the agent composes the system prompt itself (via
+ *   `createAgent({ systemPrompt })`); seeding it here too produced a second system message that
+ *   `@langchain/anthropic` rejects. Retained positionally so existing callers need no change.
+ * @param userMessages - The ordered user turns to send (one conversation).
+ * @param config - The resolved config.
+ * @param resolvers - Optional agent resolvers (tools/middleware); the caller owns their cleanup.
+ * @param command - The originating command (defaults to `ask`); selects the agent mode prompt.
+ * @param agentFactory - Optional backend factory (B5); omitted = the runner's lean default, which
+ *   is also what the shared backend seam resolves to.
+ * @param options - GS2-95: `displayCommand` names the run in the header when the caller's own name
+ *   differs from the `command` it runs under (`gth eval` runs its conversations in `ask` mode).
+ *   Header only — it never reaches the mode prompt.
+ * @returns One {@link ConversationTurnResult} per turn attempted, in turn order.
+ */
+export async function runConversation(source, _preamble, userMessages, config, resolvers, command = 'ask', agentFactory, options) {
+    const progressIndicator = config.streamOutput ? undefined : new ProgressIndicator('Thinking.');
+    try {
+        // Resolve output path and initialize session logging if enabled (same discipline as
+        // runSingleShot; a no-op when `writeOutputToFile` is off, as `gth eval` forces it —
+        // getCommandOutputFilePath null).
+        const filePath = getCommandOutputFilePath(config, source);
+        if (filePath) {
+            initSessionLogging(filePath, config.streamSessionInferenceLog);
+        }
+        // Build the agent + resolve tools ONCE for the whole conversation (the MCP connection / any
+        // OAuth / the toolset must persist across turns so cross-turn memory is real). Cleaned up once,
+        // in finally.
+        const runner = new GthAgentRunner(defaultStatusCallback, resolvers, agentFactory);
+        const results = [];
+        // The accumulated conversation: [user1, ai1, user2, ai2, …]. Each turn replays the whole array
+        // against a freshly-rotated thread (see the doc block). BATCH-13: NO leading SystemMessage — the
+        // agent composes the system prompt via `createAgent({ systemPrompt })` (same as runSingleShot);
+        // seeding a preamble SystemMessage here too made two system messages, which Anthropic rejects.
+        const messages = [];
+        try {
+            await runner.init(command, config, new MemorySaver(), {
+                displayCommand: options?.displayCommand,
+            });
+            for (const userMessage of userMessages) {
+                // Rotate to a fresh (empty) checkpointer thread so this turn's replay of the full `messages`
+                // array is the sole history the agent sees — no double-append from a prior checkpoint.
+                runner.resetThread();
+                messages.push(new HumanMessage(userMessage));
+                const startedAt = Date.now();
+                let answer = '';
+                let ok = true;
+                let error;
+                try {
+                    answer = await runner.processMessages(messages);
+                    // Append this turn's answer so the NEXT turn's replay includes it (cross-turn memory).
+                    messages.push(new AIMessage(answer));
+                }
+                catch (err) {
+                    ok = false;
+                    error = err instanceof Error ? err.message : String(err);
+                    // [[TUI-C71]] — the SAME branch `runSingleShot` carries, and for a sharper reason: this
+                    // surface wires no tool-approval callback either, so every escalation it meets is a
+                    // §6.2 `NonInteractiveEscalationError` — the error class that carries the command, the
+                    // rating, the rater's reason AND the whole negotiation transcript. The hostile path is
+                    // not an edge case here, it is the only path. `error` above keeps the neutralised
+                    // message for the turn record, which is a data consumer and wants the string.
+                    if (err instanceof ApprovalStopError) {
+                        displayError('Failed to get answer:');
+                        for (const row of approvalStopRows(err.parts, { columns: stdout.columns })) {
+                            displayError(row);
+                        }
+                    }
+                    else {
+                        displayError(`Failed to get answer: ${error}`);
+                    }
+                }
+                // GS2-16: read this turn's token/tool delta from the live agent (before cleanup). Fail-soft
+                // — analytics must never affect the run. `processMessages` reset the tally at its top, so
+                // this is THIS turn's usage, not the conversation's cumulative total.
+                let runStats = { tools: [] };
+                try {
+                    const s = runner.getRunStats?.();
+                    if (s)
+                        runStats = s;
+                }
+                catch {
+                    /* fail-soft */
+                }
+                // GS2-7 (B20): opt-in, fail-soft per-turn session history. A no-op unless `history.enabled`.
+                recordSessionSafe(config, {
+                    command,
+                    project: getProjectDir(),
+                    model: config.modelDisplayName,
+                    prompt: userMessage,
+                    response: answer,
+                    tokensInput: runStats.tokensInput,
+                    tokensOutput: runStats.tokensOutput,
+                    tools: runStats.tools.length > 0 ? runStats.tools : undefined,
+                    durationMs: Date.now() - startedAt,
+                });
+                results.push({ ok, answer, error, ...runStats });
+                // A failed turn breaks the conversation's context — stop rather than run later turns on it.
+                if (!ok)
+                    break;
+            }
+        }
+        finally {
+            await runner.cleanup();
+        }
+        progressIndicator?.stop();
+        if (config.writeOutputToFile === false) {
+            display('\n'); // something going on in some terminals, they swallow last line of output
+        }
+        if (filePath) {
+            try {
+                flushSessionLog();
+                stopSessionLogging();
+                displaySuccess(`\n\nThis report can be found in ${filePath}`);
+            }
+            catch (err) {
+                displayError(`Failed to write answer to file: ${filePath}`);
+                displayError(err instanceof Error ? err.message : String(err));
+            }
+        }
+        return results;
+    }
+    finally {
+        // EXT-53: the indicator owns a 1s setInterval — an active libuv handle that keeps Node's event
+        // loop from ever draining, so leaking it hangs the CLI forever after the work is done. The
+        // `stop()` above sits where it does for output ordering (before the trailing newline / the
+        // "report can be found in …" line); this `finally` guarantees the handle is also released when
+        // anything above throws — notably `runner.init()`, which has no catch, and `runner.cleanup()`.
+        // `stop()` is idempotent, so the normal path's second call is a no-op.
+        progressIndicator?.stop();
+    }
+}
+//# sourceMappingURL=conversation.js.map

package/dist/runtime/conversation.js.map

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

package/dist/runtime/singleShot.d.ts

@@ -1,5 +1,30 @@
 import type { GthConfig } from '#src/config.js';
-import type { AgentResolvers, GthCommand } from '#src/core/types.js';
+import type { AgentResolvers, GthAgentFactory, GthCommand } from '#src/core/types.js';
+import type { GthRunStats } from '#src/core/types.js';
+/**
+ * Result of a {@link runSingleShot} run: the pass/fail contract callers such as `ask`/`exec` have
+ * always used (`ok`), plus the SUT's answer text and run stats (GS2-16's {@link GthRunStats}) that
+ * were already computed internally but previously discarded. Extends `GthRunStats` rather than
+ * restating `tokensInput`/`tokensOutput`/`tools` as parallel fields.
+ */
+export interface SingleShotResult extends GthRunStats {
+    /** `true` when the run completed without error, `false` when it failed. */
+    ok: boolean;
+    /** The SUT's full answer text (`runner.processMessages()`'s return value). Empty on failure. */
+    answer: string;
+}
+/** Options that qualify a {@link runSingleShot} run without changing how it behaves. */
+export interface SingleShotOptions {
+    /**
+     * GS2-95 — the name of the command the USER typed, for the run header (`eval`, `batch`,
+     * `workflow`, `gth-batch`). Omit it and the header names `command`, which is right for every
+     * caller whose verb IS its name (`ask`, `exec`).
+     *
+     * It is deliberately NOT `command`: that argument selects the agent's mode prompt, so a caller
+     * that renamed itself through it would change which system prompt its runs execute under.
+     */
+    displayCommand?: string;
+}
 /**
  * Ask a question and get an answer from the LLM.
  *
@@ -8,12 +33,21 @@ import type { AgentResolvers, GthCommand } from '#src/core/types.js';
  * is forwarded to the agent so it can pick the right mode prompt (e.g. exec-mode for `exec`).
  *
  * @param source - The source of the question (used for file naming)
- * @param preamble - The preamble to send to the LLM
+ * @param _preamble - Deprecated/ignored (BATCH-13): the agent composes the system prompt itself;
+ *   see the body comment. Retained positionally so existing callers need no change.
  * @param content - The content of the question
  * @param config - The resolved config
  * @param resolvers - Optional agent resolvers (tools/middleware)
  * @param command - The originating command (defaults to `ask`); selects the agent mode prompt
- * @returns `true` when the run completed without error, `false` when it failed (so callers
- *   such as `exec` can set a non-zero exit code).
+ * @param agentFactory - Optional backend factory (B5). When omitted the runner uses its built-in
+ *   lean {@link GthLangChainAgent} default. The app layer passes `resolveAgentFactory(config,
+ *   'lean')`, which resolves to the same agent through the shared backend seam.
+ * @param options - GS2-95: `displayCommand` names the run in the header when the caller's own name
+ *   differs from the `command` it runs under (`gth eval` runs cases in `ask` mode). Header only —
+ *   it never reaches the mode prompt.
+ * @returns A {@link SingleShotResult}: `ok` is `true` when the run completed without error, `false`
+ *   when it failed (so callers such as `exec` can set a non-zero exit code); `answer`/`tokensInput`/
+ *   `tokensOutput`/`tools` carry the SUT's answer text and run stats for callers that need them
+ *   (e.g. `gth batch`/`gth eval`).
  */
-export declare function runSingleShot(source: string, preamble: string, content: string, config: GthConfig, resolvers?: AgentResolvers, command?: GthCommand): Promise<boolean>;
+export declare function runSingleShot(source: string, _preamble: string, content: string, config: GthConfig, resolvers?: AgentResolvers, command?: GthCommand, agentFactory?: GthAgentFactory, options?: SingleShotOptions): Promise<SingleShotResult>;