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

package/dist/runtime/singleShot.js

@@ -2,10 +2,11 @@ import { defaultStatusCallback, display, displayError, displaySuccess, flushSess
 import { getCommandOutputFilePath } from '#src/utils/fileUtils.js';
 import { GthAgentRunner } from '#src/core/GthAgentRunner.js';
 import { MemorySaver } from '@langchain/langgraph';
-import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { HumanMessage } from '@langchain/core/messages';
 import { ProgressIndicator } from '#src/utils/ProgressIndicator.js';
 import { recordSessionSafe } from '#src/history/recordSession.js';
-import { getProjectDir } from '#src/utils/systemUtils.js';
+import { getProjectDir, stdout } from '#src/utils/systemUtils.js';
+import { ApprovalStopError, approvalStopRows } from '#src/core/shell/approvalStop.js';
 /**
  * Ask a question and get an answer from the LLM.
  *
@@ -14,82 +15,127 @@ import { getProjectDir } from '#src/utils/systemUtils.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
  * @param agentFactory - Optional backend factory (B5). When omitted the runner uses its built-in
- *   lean {@link GthLangChainAgent} default (unchanged behavior for existing callers). The app
- *   layer passes `resolveAgentFactory(config, 'lean')` so an explicit `agent.backend` is honored.
- * @returns `true` when the run completed without error, `false` when it failed (so callers
- *   such as `exec` can set a non-zero exit code).
+ *   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 async function runSingleShot(source, preamble, content, config, resolvers, command = 'ask', agentFactory) {
+export async function runSingleShot(source, 
+// BATCH-13: `_preamble` is retained for signature stability but is NO LONGER injected as a
+// SystemMessage. The agent (lean `GthLangChainAgent`, since GS2-21) COMPOSES the full system
+// prompt itself from the config — backstory + guidelines +
+// per-command mode prompt + system prompt, PLUS the model-identity (GS2-34) and MCP-instructions
+// (EXT-32) notes — and hand it to `createAgent` as `systemPrompt`. Also passing this preamble as a
+// leading SystemMessage produced TWO system messages, which `@langchain/anthropic` rejects
+// ("System messages are only permitted as the first passed message"), breaking EVERY single-shot
+// run (ask/exec/batch/eval) on Anthropic on BOTH backends (Google/OpenAI silently merged them).
+// The agent's composed prompt is a superset of this preamble, so dropping it is content-preserving.
+_preamble, content, config, resolvers, command = 'ask', agentFactory, options) {
     const progressIndicator = config.streamOutput ? undefined : new ProgressIndicator('Thinking.');
-    const messages = [new SystemMessage(preamble), new HumanMessage(content)];
-    // Resolve output path and initialize session logging if enabled
-    const filePath = getCommandOutputFilePath(config, source);
-    if (filePath) {
-        initSessionLogging(filePath, config.streamSessionInferenceLog);
-    }
-    // Run via Agent Runner (consistent with interactive session)
-    const runner = new GthAgentRunner(defaultStatusCallback, resolvers, agentFactory);
-    let succeeded = true;
-    let responseText = '';
-    const startedAt = Date.now();
     try {
-        await runner.init(command, config, new MemorySaver());
-        responseText = await runner.processMessages(messages);
-    }
-    catch (err) {
-        succeeded = false;
-        displayError(`Failed to get answer: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    finally {
-        await runner.cleanup();
-    }
-    // GS2-16: live token usage + invoked tool names for this run (fail-soft; empty when the
-    // provider reported no usage / the runner has no stats). Read post-cleanup — the runner
-    // snapshots stats at cleanup() so this still reflects the finished run.
-    let runStats = { tools: [] };
-    try {
-        const s = runner.getRunStats?.();
-        if (s)
-            runStats = s;
-    }
-    catch {
-        /* fail-soft: analytics must never affect this run */
-    }
-    // GS2-7 (B20): opt-in, fail-soft session history. A no-op unless `history.enabled`; never throws
-    // (recordSessionSafe is fully guarded) so a DB problem can't abort or alter this run.
-    // GS2-16 threads token/tool analytics; costUsd is intentionally left unset (no reliable price).
-    recordSessionSafe(config, {
-        command,
-        project: getProjectDir(),
-        model: config.modelDisplayName,
-        prompt: content,
-        response: responseText,
-        tokensInput: runStats.tokensInput,
-        tokensOutput: runStats.tokensOutput,
-        tools: runStats.tools.length > 0 ? runStats.tools : undefined,
-        durationMs: Date.now() - startedAt,
-    });
-    progressIndicator?.stop();
-    if (config.writeOutputToFile === false) {
-        display('\n'); // something going on in some terminals, they swallow last line of output
-    }
-    if (filePath) {
+        // Only the human turn: the agent supplies the system prompt via `createAgent({ systemPrompt })`.
+        const messages = [new HumanMessage(content)];
+        // Resolve output path and initialize session logging if enabled
+        const filePath = getCommandOutputFilePath(config, source);
+        if (filePath) {
+            initSessionLogging(filePath, config.streamSessionInferenceLog);
+        }
+        // Run via Agent Runner (consistent with interactive session)
+        const runner = new GthAgentRunner(defaultStatusCallback, resolvers, agentFactory);
+        let succeeded = true;
+        let responseText = '';
+        const startedAt = Date.now();
+        try {
+            await runner.init(command, config, new MemorySaver(), {
+                displayCommand: options?.displayCommand,
+            });
+            responseText = await runner.processMessages(messages);
+        }
+        catch (err) {
+            succeeded = false;
+            // [[TUI-C71]] — §6.2's escalation and §4.2's halt reach a person HERE and nowhere else on
+            // this path: there is no prompt to attach anything to, so this message is the whole
+            // explanation and it is built almost entirely out of model-authored text. Its untrusted
+            // halves go through the [[TUI-C26]] gutter, one row per line, so a payload crafted to forge
+            // terminal chrome cannot reach column 0 even on a line the terminal would have wrapped. The
+            // rows are printed on the same channel as the wrapper so a redirected stderr still carries
+            // the whole thing.
+            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: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        finally {
+            await runner.cleanup();
+        }
+        // GS2-16: live token usage + invoked tool names for this run (fail-soft; empty when the
+        // provider reported no usage / the runner has no stats). Read post-cleanup — the runner
+        // snapshots stats at cleanup() so this still reflects the finished run.
+        let runStats = { tools: [] };
         try {
-            flushSessionLog();
-            stopSessionLogging();
-            displaySuccess(`\n\nThis report can be found in ${filePath}`);
+            const s = runner.getRunStats?.();
+            if (s)
+                runStats = s;
         }
-        catch (error) {
-            displayError(`Failed to write answer to file: ${filePath}`);
-            displayError(error instanceof Error ? error.message : String(error));
+        catch {
+            /* fail-soft: analytics must never affect this run */
         }
+        // GS2-7 (B20): opt-in, fail-soft session history. A no-op unless `history.enabled`; never throws
+        // (recordSessionSafe is fully guarded) so a DB problem can't abort or alter this run.
+        // GS2-16 threads token/tool analytics; costUsd is intentionally left unset (no reliable price).
+        recordSessionSafe(config, {
+            command,
+            project: getProjectDir(),
+            model: config.modelDisplayName,
+            prompt: content,
+            response: responseText,
+            tokensInput: runStats.tokensInput,
+            tokensOutput: runStats.tokensOutput,
+            tools: runStats.tools.length > 0 ? runStats.tools : undefined,
+            durationMs: Date.now() - startedAt,
+        });
+        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 (error) {
+                displayError(`Failed to write answer to file: ${filePath}`);
+                displayError(error instanceof Error ? error.message : String(error));
+            }
+        }
+        return { ok: succeeded, answer: responseText, ...runStats };
+    }
+    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.cleanup()`, which is outside the inner catch.
+        // `stop()` is idempotent, so the normal path's second call is a no-op.
+        progressIndicator?.stop();
     }
-    return succeeded;
 }
 //# sourceMappingURL=singleShot.js.map

package/dist/runtime/singleShot.js.map

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

package/dist/runtime/structuredOutput.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @module runtime/structuredOutput
+ *
+ * EXT-88 — the **`withStructuredOutput` boundary**. Every `withStructuredOutput` call in this
+ * project goes through {@link structuredOutputBoundary}: `rateShellCommand` (the approvals rater),
+ * {@link askStructured} (arbitrary caller schemas, including `gth workflow` scripts) and
+ * `@gaunt-sloth/batch`'s eval judge. Review's rating step is deliberately not one of them — it
+ * reaches its schema through a bound TOOL, which is a different path with different rules.
+ *
+ * ## The problem it exists to solve
+ *
+ * A single Zod object normally does two jobs at once — it is converted into the JSON Schema the
+ * provider is sent, and it validates the answer that comes back. Those two jobs want **opposite**
+ * things from an optional field, and Zod has only one knob for both:
+ *
+ * - **On the wire**, OpenAI's strict `json_schema` rule is *"`required` must be supplied and must
+ *   include every key in `properties`"*. A `.optional()` field is left out of `required`, and the
+ *   OpenAI API rejects the whole request with `400 Invalid schema for response_format`. Optionality
+ *   there is spelled as a **nullable type on a required key**, not as an absent key.
+ * - **On the way back**, providers do not agree. Some (ChatGroq) rewrite the schema themselves so
+ *   every property is required-and-nullable, and their models answer `null`. Others (Anthropic,
+ *   Google GenAI, Ollama) leave the field genuinely optional and their models may simply omit it.
+ *   Zod's `.optional()` admits `undefined` and **not** `null`, so the first group's answer is
+ *   rejected by the very schema that asked for it — and the caller sees a parse failure that looks
+ *   like a bad model rather than a self-contradicting request.
+ *
+ * ## The shape that satisfies both
+ *
+ * For every field the caller declared `.optional()`, the boundary sends
+ * `inner.nullable().prefault(null)` instead. That one node is the wire/validation twin:
+ *
+ * - **Wire** — `prefault` does not change the parsed *output* type, so the key lands in `required`
+ *   and its type is `["string","null"]` / `anyOf: [T, null]`. Strict mode is satisfied, and the
+ *   model is given a legal way to say "nothing here". Unlike `.default()`, `prefault` emits **no
+ *   `default` keyword** into the JSON Schema, so nothing extra is added to what the provider sees.
+ * - **Validation** — the same node accepts the value, accepts `null`, and accepts the key being
+ *   **missing** (which is what `prefault` supplies the `null` for). All three arms are needed: the
+ *   third is what keeps the providers that do *not* hoist working.
+ *
+ * The `null` never escapes: {@link StructuredOutputBoundary.safeParse} strips it back to the key
+ * being **absent** and then validates with the caller's **original** schema, so the parsed type is
+ * exactly what the caller declared — an optional string stays `string | undefined` and never
+ * becomes `string | null | undefined`.
+ *
+ * ## Two properties that must not be lost in a "simplification"
+ *
+ * - **Every `.describe()` survives into the emitted JSON Schema.** The descriptions are the only
+ *   place the model is told what the fields mean. Expressing the null-to-absent step with
+ *   `.transform()` on the field is the obvious-looking alternative and it costs the field its
+ *   description — worse, the conversion OpenAI's path uses refuses to represent a transform at all.
+ *   Normalization therefore happens in **code**, after the parse, never in the schema.
+ * - **A genuinely malformed answer still fails.** This boundary removes a *false* parse failure; it
+ *   is not a blanket "accept anything". A wrong type in an optional field is still rejected, because
+ *   the final validation is the caller's own untouched schema. In particular `.catch()` must not be
+ *   used to express any of this — it would swallow real failures.
+ *
+ * ## Coverage, and the deliberate limits
+ *
+ * The rewrite descends through objects, arrays, tuples, records and the single-child wrappers
+ * (`nullable`, `readonly`, `default`, `prefault`, `nonoptional`), so an optional nested inside an
+ * object inside an array is handled.
+ *
+ * It deliberately stops at **unions** (including discriminated unions), **intersections**, `lazy`,
+ * `map`, `set`, `pipe`/`transform` and `custom`, leaving those subtrees exactly as the caller wrote
+ * them, and it leaves a **recursive** schema alone in its entirety. The reason is one rule: the
+ * rewrite and the normalization must cover **precisely the same set**. At a union the incoming value
+ * gives no reliable answer to *which branch was taken*, so a `null` could not be stripped back out;
+ * rewriting there while being unable to normalize would manufacture the very parse failure this
+ * module removes. Recursion is refused for the neighbouring reason — a rewrite that stopped at the
+ * cycle would make a key required at one depth and optional at the next, which satisfies no
+ * provider's strict rule and is harder to reason about than the caller's own schema.
+ *
+ * An optional inside one of those constructs keeps today's behaviour — correct everywhere it is
+ * correct today, and still rejected by OpenAI's strict rule, which is a visible error rather than a
+ * silent one.
+ */
+import * as z from 'zod';
+/**
+ * The two halves of one structured-output call: what to send, and how to read the answer.
+ *
+ * @typeParam T The caller's own parsed type — unchanged by the boundary.
+ */
+export interface StructuredOutputBoundary<T> {
+    /**
+     * The schema to hand to `model.withStructuredOutput(...)`. Identical (by reference) to the
+     * caller's schema when it contains no optional field, so a schema that never had the problem is
+     * sent byte-for-byte as it is today.
+     */
+    wireSchema: z.ZodType<Record<string, unknown>>;
+    /**
+     * Validate a model answer: normalize every `null` that stands for "no value" back to the key being
+     * absent, then validate with the caller's **original** schema. Never throws — a malformed answer
+     * comes back as `success: false`, exactly as `schema.safeParse` would.
+     */
+    safeParse(raw: unknown): z.ZodSafeParseResult<T>;
+}
+/**
+ * Build the {@link StructuredOutputBoundary} for a schema — the one entry point every
+ * `withStructuredOutput` call in this project goes through. See the module doc for what it does and
+ * why.
+ *
+ * @param schema The caller's schema, used unchanged for the final validation.
+ */
+export declare function structuredOutputBoundary<T>(schema: z.ZodType<T>): StructuredOutputBoundary<T>;