@gaunt-sloth/core 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/providers/openrouter.js

@@ -1,6 +1,7 @@
 import { displayWarning } from '#src/utils/consoleUtils.js';
 import { env } from '#src/utils/systemUtils.js';
-import { writeFileIfNotExistsWithMessages } from '#src/utils/fileUtils.js';
+import { writeConfigFileWithMessages } from '#src/utils/fileUtils.js';
+import { buildInitConfigContent, getCuratedFallbackModel } from '#src/providers/modelDiscovery.js';
 // Function to process JSON config and create OpenRouter LLM instance
 // noinspection JSUnusedGlobalSymbols
 export async function processJsonConfig(llmConfig) {
@@ -13,13 +14,18 @@ export async function processJsonConfig(llmConfig) {
     const configFields = {
         ...llmConfig,
         apiKey: openRouterApiKey,
-        model: llmConfig.model || 'qwen/qwen3-coder',
+        model: llmConfig.model || getCuratedFallbackModel('openrouter'),
+        // TUI-C22 — OpenRouter returns a thinking model's reasoning in a top-level `reasoning` field
+        // that the ChatOpenAI completions converter drops. `__includeRawResponse` stashes the raw
+        // provider response under `additional_kwargs.__raw_response`, which GthAbstractAgent reads
+        // (`choices[0].delta.reasoning`) to populate the /reasoning panel. Kept opt-out via config.
+        __includeRawResponse: llmConfig.__includeRawResponse ?? true,
         configuration: {
             baseURL: 'https://openrouter.ai/api/v1',
             ...(llmConfig.configuration || {}),
             defaultHeaders: {
-                'HTTP-Referer': 'https://gaunt-sloth-assistant.github.io/',
-                'X-Title': 'Gaunt Sloth Assistant',
+                'HTTP-Referer': 'https://gauntsloth.app/',
+                'X-Title': 'Gaunt Sloth',
             },
         },
     };
@@ -39,18 +45,12 @@ function getApiKey(llmConfig) {
         return llmConfig.apiKey || env.OPEN_ROUTER_API_KEY || env.OPENROUTER_API_KEY;
     }
 }
-const jsonContent = `{
-  "llm": {
-    "type": "openrouter",
-    "model": "qwen/qwen3-coder"
-  }
-}`;
-export function init(configFileName) {
+export function init(configFileName, force = false, model) {
     // Determine which content to use based on file extension
     if (!configFileName.endsWith('.json')) {
         throw new Error('Only JSON config is supported.');
     }
-    writeFileIfNotExistsWithMessages(configFileName, jsonContent);
+    writeConfigFileWithMessages(configFileName, buildInitConfigContent('openrouter', model), force);
     displayWarning(`You need to edit your ${configFileName} to configure model, ` +
         'or define OPEN_ROUTER_API_KEY environment variable.');
 }

package/dist/providers/openrouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../../src/providers/openrouter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAQhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,qEAAqE;AACrE,qCAAqC;AACrC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmE;IAEnE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACzD,wEAAwE;IACxE,MAAM,gBAAgB,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,MAAM,EAAE,gBAAgB;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,kBAAkB;QAC5C,aAAa,EAAE;YACb,OAAO,EAAE,8BAA8B;YACvC,GAAG,CAAC,SAAS,CAAC,aAAa,IAAI,EAAE,CAAC;YAClC,cAAc,EAAE;gBACd,cAAc,EAAE,0CAA0C;gBAC1D,SAAS,EAAE,uBAAuB;aACnC;SACF;KACF,CAAC;IACF,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,IAAI,CAAC;IAClC,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,yBAAyB,CAAC;IACvD,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,SAAmE;IACpF,8DAA8D;IAC9D,MAAM,IAAI,GAAG,SAA0C,CAAC;IACxD,IAAI,IAAI,CAAC,yBAAyB,IAAI,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC1E,OAAO,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,OAAO,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,kBAAkB,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,yBAAyB,cAAc,uBAAuB;QAC5D,qDAAqD,CACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"openrouter.js","sourceRoot":"","sources":["../../src/providers/openrouter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAQhD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAEnG,qEAAqE;AACrE,qCAAqC;AACrC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmE;IAEnE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACzD,wEAAwE;IACxE,MAAM,gBAAgB,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,MAAM,EAAE,gBAAgB;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,uBAAuB,CAAC,YAAY,CAAC;QAC/D,6FAA6F;QAC7F,0FAA0F;QAC1F,2FAA2F;QAC3F,4FAA4F;QAC5F,oBAAoB,EAAE,SAAS,CAAC,oBAAoB,IAAI,IAAI;QAC5D,aAAa,EAAE;YACb,OAAO,EAAE,8BAA8B;YACvC,GAAG,CAAC,SAAS,CAAC,aAAa,IAAI,EAAE,CAAC;YAClC,cAAc,EAAE;gBACd,cAAc,EAAE,yBAAyB;gBACzC,SAAS,EAAE,aAAa;aACzB;SACF;KACF,CAAC;IACF,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,IAAI,CAAC;IAClC,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,yBAAyB,CAAC;IACvD,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,SAAmE;IACpF,8DAA8D;IAC9D,MAAM,IAAI,GAAG,SAA0C,CAAC;IACxD,IAAI,IAAI,CAAC,yBAAyB,IAAI,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC1E,OAAO,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,OAAO,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,mBAAmB,IAAI,GAAG,CAAC,kBAAkB,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,cAAsB,EAAE,KAAK,GAAG,KAAK,EAAE,KAAc;IACxE,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,2BAA2B,CAAC,cAAc,EAAE,sBAAsB,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAChG,cAAc,CACZ,yBAAyB,cAAc,uBAAuB;QAC5D,qDAAqD,CACxD,CAAC;AACJ,CAAC"}

package/dist/providers/vertexai.d.ts

@@ -1,6 +1,6 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { ChatGoogleParams } from '@langchain/google/node';
-export declare function init(configFileName: string): void;
+export declare function init(configFileName: string, force?: boolean, model?: string): void;
 export declare function processJsonConfig(llmConfig: ChatGoogleParams & {
     type?: string;
     apiKeyEnvironmentVariable?: string;

package/dist/providers/vertexai.js

@@ -11,19 +11,15 @@
  * Hopefully this issue will go away when LangChain switches to the new GenAI dependency.
  */
 import { displayWarning } from '#src/utils/consoleUtils.js';
-import { writeFileIfNotExistsWithMessages } from '#src/utils/fileUtils.js';
-const jsonContent = `{
-  "llm": {
-    "type": "vertexai",
-    "model": "gemini-3.5-flash"
-  }
-}`;
-export function init(configFileName) {
+import { writeConfigFileWithMessages } from '#src/utils/fileUtils.js';
+import { buildInitConfigContent, getCuratedFallbackModel } from '#src/providers/modelDiscovery.js';
+import { applyGeminiToolSchemaSanitizer } from '#src/providers/geminiSchemaSanitizer.js';
+export function init(configFileName, force = false, model) {
     // Determine which content to use based on file extension
     if (!configFileName.endsWith('.json')) {
         throw new Error('Only JSON config is supported.');
     }
-    writeFileIfNotExistsWithMessages(configFileName, jsonContent);
+    writeConfigFileWithMessages(configFileName, buildInitConfigContent('vertexai', model), force);
     displayWarning('For Google VertexAI you likely to need to do `gcloud auth login` and `gcloud auth application-default login`.');
 }
 // Function to process JSON config and create VertexAI LLM instance
@@ -31,11 +27,13 @@ export async function processJsonConfig(llmConfig) {
     const { ChatGoogle } = await import('@langchain/google/node');
     const configFields = {
         ...llmConfig,
-        model: llmConfig.model || 'gemini-3.5-flash',
+        model: llmConfig.model || getCuratedFallbackModel('vertexai'),
         vertexai: true,
     };
     delete configFields.type;
     delete configFields.apiKeyEnvironmentVariable;
-    return new ChatGoogle(configFields);
+    // GS2-58: normalise every tool's JSON-Schema at the ChatGoogle boundary so Gemini's OpenAPI-3.0
+    // subset accepts built-in, custom, and MCP tools alike (see geminiSchemaSanitizer).
+    return applyGeminiToolSchemaSanitizer(new ChatGoogle(configFields));
 }
 //# sourceMappingURL=vertexai.js.map

package/dist/providers/vertexai.js.map

@@ -1 +1 @@
-{"version":3,"file":"vertexai.js","sourceRoot":"","sources":["../../src/providers/vertexai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAI5D,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,+GAA+G,CAChH,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmF;IAEnF,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,kBAAkB;QAC5C,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,CAAC;IACzB,OAAO,YAAY,CAAC,yBAAyB,CAAC;IAC9C,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"vertexai.js","sourceRoot":"","sources":["../../src/providers/vertexai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAI5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AACnG,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAEzF,MAAM,UAAU,IAAI,CAAC,cAAsB,EAAE,KAAK,GAAG,KAAK,EAAE,KAAc;IACxE,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,2BAA2B,CAAC,cAAc,EAAE,sBAAsB,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9F,cAAc,CACZ,+GAA+G,CAChH,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmF;IAEnF,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,uBAAuB,CAAC,UAAU,CAAC;QAC7D,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,OAAO,YAAY,CAAC,IAAI,CAAC;IACzB,OAAO,YAAY,CAAC,yBAAyB,CAAC;IAC9C,gGAAgG;IAChG,oFAAoF;IACpF,OAAO,8BAA8B,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/providers/xai.d.ts

@@ -1,4 +1,4 @@
 import type { BaseChatModel, BaseChatModelParams } from '@langchain/core/language_models/chat_models';
 import type { ChatXAIInput } from '@langchain/xai';
 export declare function processJsonConfig(llmConfig: ChatXAIInput & BaseChatModelParams): Promise<BaseChatModel>;
-export declare function init(configFileName: string): void;
+export declare function init(configFileName: string, force?: boolean, model?: string): void;

package/dist/providers/xai.js

@@ -1,6 +1,7 @@
 import { displayWarning } from '#src/utils/consoleUtils.js';
 import { env } from '#src/utils/systemUtils.js';
-import { writeFileIfNotExistsWithMessages } from '#src/utils/fileUtils.js';
+import { writeConfigFileWithMessages } from '#src/utils/fileUtils.js';
+import { buildInitConfigContent, getCuratedFallbackModel } from '#src/providers/modelDiscovery.js';
 // Function to process JSON config and create XAI LLM instance
 export async function processJsonConfig(llmConfig) {
     const { ChatXAI } = await import('@langchain/xai');
@@ -9,21 +10,15 @@ export async function processJsonConfig(llmConfig) {
     return new ChatXAI({
         ...llmConfig,
         apiKey,
-        model: llmConfig.model || 'grok-4.3',
+        model: llmConfig.model || getCuratedFallbackModel('xai'),
     });
 }
-const jsonContent = `{
-  "llm": {
-    "type": "xai",
-    "model": "grok-4.3"
-  }
-}`;
-export function init(configFileName) {
+export function init(configFileName, force = false, model) {
     // Determine which content to use based on file extension
     if (!configFileName.endsWith('.json')) {
         throw new Error('Only JSON config is supported.');
     }
-    writeFileIfNotExistsWithMessages(configFileName, jsonContent);
+    writeConfigFileWithMessages(configFileName, buildInitConfigContent('xai', model), force);
     displayWarning(`You need to update your ${configFileName} to add your xAI API key, ` +
         'or define XAI_API_KEY environment variable.');
 }

package/dist/providers/xai.js.map

@@ -1 +1 @@
-{"version":3,"file":"xai.js","sourceRoot":"","sources":["../../src/providers/xai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAOhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA6C;IAE7C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACnD,wEAAwE;IACxE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,WAAW,CAAC;IACnD,OAAO,IAAI,OAAO,CAAC;QACjB,GAAG,SAAS;QACZ,MAAM;QACN,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,UAAU;KACrC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,2BAA2B,cAAc,4BAA4B;QACnE,6CAA6C,CAChD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"xai.js","sourceRoot":"","sources":["../../src/providers/xai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAOhD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAEnG,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA6C;IAE7C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACnD,wEAAwE;IACxE,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,WAAW,CAAC;IACnD,OAAO,IAAI,OAAO,CAAC;QACjB,GAAG,SAAS;QACZ,MAAM;QACN,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,uBAAuB,CAAC,KAAK,CAAC;KACzD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,cAAsB,EAAE,KAAK,GAAG,KAAK,EAAE,KAAc;IACxE,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,2BAA2B,CAAC,cAAc,EAAE,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IACzF,cAAc,CACZ,2BAA2B,cAAc,4BAA4B;QACnE,6CAA6C,CAChD,CAAC;AACJ,CAAC"}

package/dist/runtime/askStructured.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @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 LLM-as-judge calls ({@link judgeEvalCase} in `@gaunt-sloth/batch`'s
+ * `judge.ts`, and its in-core ancestor {@link judgeShellCommand} in `core/shell/judge.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 the judges: this one is **generic** over the Zod schema and takes the
+ * system/user strings from the caller (the judges hard-code a schema and build a rubric/safety
+ * prompt), and it reads the model from `config.llm` (like `runSingleShot`/`judgeShellCommand`),
+ * 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 the judges'
+ * `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;
+/** 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 the judges' 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, error: 'Structured call timed out after <ms>ms.' }`.
+ * - Output that fails `schema.safeParse` → `{ ok: false, error: 'Model returned unparseable output.' }`.
+ * - Any thrown error → `{ ok: false, error: <message> }`.
+ * - 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,76 @@
+/**
+ * @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 LLM-as-judge calls ({@link judgeEvalCase} in `@gaunt-sloth/batch`'s
+ * `judge.ts`, and its in-core ancestor {@link judgeShellCommand} in `core/shell/judge.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 the judges: this one is **generic** over the Zod schema and takes the
+ * system/user strings from the caller (the judges hard-code a schema and build a rubric/safety
+ * prompt), and it reads the model from `config.llm` (like `runSingleShot`/`judgeShellCommand`),
+ * 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';
+/**
+ * Default wall-clock budget (ms) for the structured LLM call — same value as the judges'
+ * `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;
+/**
+ * Ask the configured model for a single schema-validated object — a non-agentic structured-output
+ * call that mirrors the judges' 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, error: 'Structured call timed out after <ms>ms.' }`.
+ * - Output that fails `schema.safeParse` → `{ ok: false, error: 'Model returned unparseable output.' }`.
+ * - Any thrown error → `{ ok: false, error: <message> }`.
+ * - 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 {
+        // `withStructuredOutput`'s output type is constrained to a record shape, but the schema here is
+        // an unconstrained `z.ZodType<T>`; the cast is sound because we re-validate the result with
+        // `schema.safeParse` below (a fake or misbehaving model could return a non-conforming object).
+        const structured = model.withStructuredOutput(schema);
+        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: `Structured call timed out after ${timeoutMs}ms.` };
+        }
+        const parsed = schema.safeParse(raced);
+        if (!parsed.success) {
+            return { ok: false, error: 'Model returned unparseable output.' };
+        }
+        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":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC;AAmBxD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAoB,EACpB,IAA0B;IAE1B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,iCAAiC,CAAC;IAEtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC;IACzB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,KAAgD,CAAC;IACrD,IAAI,CAAC;QACH,gGAAgG;QAChG,4FAA4F;QAC5F,+FAA+F;QAC/F,MAAM,UAAU,GAAG,KAAK,CAAC,oBAAoB,CAAC,MAA4C,CAAC,CAAC;QAC5F,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE7F,MAAM,OAAO,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC;QACjD,MAAM,cAAc,GAAG,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,EAAE;YAC7D,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QAEH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC;QAClE,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mCAAmC,SAAS,KAAK,EAAE,CAAC;QACjF,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;QACpE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACtF,CAAC;YAAS,CAAC;QACT,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/runtime/conversation.d.ts

@@ -0,0 +1,59 @@
+import type { GthConfig } from '#src/config.js';
+import type { AgentResolvers, GthAgentFactory, GthCommand } from '#src/core/types.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.
+ * @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): Promise<ConversationTurnResult[]>;

package/dist/runtime/conversation.js

@@ -0,0 +1,137 @@
+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 } from '#src/utils/systemUtils.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.
+ * @returns One {@link ConversationTurnResult} per turn attempted, in turn order.
+ */
+export async function runConversation(source, _preamble, userMessages, config, resolvers, command = 'ask', agentFactory) {
+    const progressIndicator = config.streamOutput ? undefined : new ProgressIndicator('Thinking.');
+    // 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());
+        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 turn's 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);
+                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;
+}
+//# 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":"AACA,OAAO,EACL,qBAAqB,EACrB,OAAO,EACP,YAAY,EACZ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAkB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,SAAiB,EACjB,YAAsB,EACtB,MAAiB,EACjB,SAA0B,EAC1B,OAAO,GAAe,KAAK,EAC3B,YAA8B;IAE9B,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAE/F,mGAAmG;IACnG,qGAAqG;IACrG,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,IAAI,QAAQ,EAAE,CAAC;QACb,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,yBAAyB,CAAC,CAAC;IACjE,CAAC;IAED,oGAAoG;IACpG,oGAAoG;IACpG,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,qBAAqB,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAClF,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,+FAA+F;IAC/F,iGAAiG;IACjG,gGAAgG;IAChG,+FAA+F;IAC/F,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC,CAAC;QAEtD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,6FAA6F;YAC7F,8FAA8F;YAC9F,MAAM,CAAC,WAAW,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;YAE7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,EAAE,GAAG,IAAI,CAAC;YACd,IAAI,KAAyB,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;gBAChD,uFAAuF;gBACvF,QAAQ,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;YACvC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,EAAE,GAAG,KAAK,CAAC;gBACX,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACzD,YAAY,CAAC,yBAAyB,KAAK,EAAE,CAAC,CAAC;YACjD,CAAC;YAED,8FAA8F;YAC9F,gGAAgG;YAChG,8DAA8D;YAC9D,IAAI,QAAQ,GAAgB,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;gBACjC,IAAI,CAAC;oBAAE,QAAQ,GAAG,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,eAAe;YACjB,CAAC;YAED,6FAA6F;YAC7F,iBAAiB,CAAC,MAAM,EAAE;gBACxB,OAAO;gBACP,OAAO,EAAE,aAAa,EAAE;gBACxB,KAAK,EAAE,MAAM,CAAC,gBAAgB;gBAC9B,MAAM,EAAE,WAAW;gBACnB,QAAQ,EAAE,MAAM;gBAChB,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;gBAC7D,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aACnC,CAAC,CAAC;YAEH,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;YAEjD,4FAA4F;YAC5F,IAAI,CAAC,EAAE;gBAAE,MAAM;QACjB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAED,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAE1B,IAAI,MAAM,CAAC,iBAAiB,KAAK,KAAK,EAAE,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,yEAAyE;IAC1F,CAAC;IACD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC;YACH,eAAe,EAAE,CAAC;YAClB,kBAAkB,EAAE,CAAC;YACrB,cAAc,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;QAChE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,YAAY,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;YAC5D,YAAY,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/runtime/singleShot.d.ts

@@ -1,5 +1,18 @@
 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;
+}
 /**
  * Ask a question and get an answer from the LLM.
  *
@@ -8,12 +21,18 @@ 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 (unchanged behavior for existing callers). The app
+ *   layer passes `resolveAgentFactory(config, 'lean')` so an explicit `agent.backend` is honored.
+ * @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): Promise<SingleShotResult>;