@gaunt-sloth/core 2.0.0-alpha.1 → 2.0.0-alpha.11

package/dist/runtime/singleShot.js

@@ -4,6 +4,8 @@ import { GthAgentRunner } from '#src/core/GthAgentRunner.js';
 import { MemorySaver } from '@langchain/langgraph';
 import { HumanMessage, SystemMessage } 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';
 /**
  * Ask a question and get an answer from the LLM.
  *
@@ -17,10 +19,13 @@ import { ProgressIndicator } from '#src/utils/ProgressIndicator.js';
  * @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).
  */
-export async function runSingleShot(source, preamble, content, config, resolvers, command = 'ask') {
+export async function runSingleShot(source, preamble, content, config, resolvers, command = 'ask', agentFactory) {
     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
@@ -29,11 +34,13 @@ export async function runSingleShot(source, preamble, content, config, resolvers
         initSessionLogging(filePath, config.streamSessionInferenceLog);
     }
     // Run via Agent Runner (consistent with interactive session)
-    const runner = new GthAgentRunner(defaultStatusCallback, resolvers);
+    const runner = new GthAgentRunner(defaultStatusCallback, resolvers, agentFactory);
     let succeeded = true;
+    let responseText = '';
+    const startedAt = Date.now();
     try {
         await runner.init(command, config, new MemorySaver());
-        await runner.processMessages(messages);
+        responseText = await runner.processMessages(messages);
     }
     catch (err) {
         succeeded = false;
@@ -42,6 +49,32 @@ export async function runSingleShot(source, preamble, content, config, resolvers
     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

package/dist/runtime/singleShot.js.map

@@ -1 +1 @@
-{"version":3,"file":"singleShot.js","sourceRoot":"","sources":["../../src/runtime/singleShot.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,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGpE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,QAAgB,EAChB,OAAe,EACf,MAAiB,EACjB,SAA0B,EAC1B,UAAsB,KAAK;IAE3B,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC/F,MAAM,QAAQ,GAAG,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC,EAAE,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAE1E,gEAAgE;IAChE,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,6DAA6D;IAC7D,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;IACpE,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,SAAS,GAAG,KAAK,CAAC;QAClB,YAAY,CAAC,yBAAyB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5F,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,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,mCAAmC,QAAQ,EAAE,CAAC,CAAC;YAC5D,YAAY,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"singleShot.js","sourceRoot":"","sources":["../../src/runtime/singleShot.ts"],"names":[],"mappings":"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"}

package/dist/utils/consoleUtils.d.ts

@@ -18,6 +18,19 @@ export declare const resetConsoleLevel: () => void;
 export declare const flushSessionLog: () => void;
 export declare const stopSessionLogging: () => void;
 export declare function displayError(message: string): void;
+/**
+ * Open a warning-capture window: from now until {@link endWarningCapture}, each
+ * `displayWarning` message is buffered (IN ADDITION to being printed/logged as usual). Used by
+ * the TUI session module to grab the transient load-time config advisories and thread them into
+ * the persistent notice surface. Idempotent-ish: a second call starts a fresh buffer.
+ */
+export declare const beginWarningCapture: () => void;
+/**
+ * Close the warning-capture window opened by {@link beginWarningCapture} and return everything
+ * collected (empty array if none / never opened). Always call this — a `try/finally` around the
+ * captured work — so a throw can't leak the capture state into later warnings.
+ */
+export declare const endWarningCapture: () => string[];
 export declare function displayWarning(message: string): void;
 export declare function displaySuccess(message: string): void;
 export declare function displayInfo(message: string): void;

package/dist/utils/consoleUtils.js

@@ -87,9 +87,40 @@ export function displayError(message) {
     writeToSessionLog(message + '\n');
     su.log(coloredMessage);
 }
+/**
+ * Optional capture buffer for warning advisories (TUI-C19). When a capture window is open
+ * (see {@link beginWarningCapture}), every {@link displayWarning} message is also collected
+ * here so a surface that takes over the screen — the Ink TUI — can re-surface warnings that
+ * would otherwise print once and scroll out of sight. `null` when no window is open, so the
+ * plain-CLI path and the session log are entirely untouched.
+ */
+let warningCapture = null;
+/**
+ * Open a warning-capture window: from now until {@link endWarningCapture}, each
+ * `displayWarning` message is buffered (IN ADDITION to being printed/logged as usual). Used by
+ * the TUI session module to grab the transient load-time config advisories and thread them into
+ * the persistent notice surface. Idempotent-ish: a second call starts a fresh buffer.
+ */
+export const beginWarningCapture = () => {
+    warningCapture = [];
+};
+/**
+ * Close the warning-capture window opened by {@link beginWarningCapture} and return everything
+ * collected (empty array if none / never opened). Always call this — a `try/finally` around the
+ * captured work — so a throw can't leak the capture state into later warnings.
+ */
+export const endWarningCapture = () => {
+    const captured = warningCapture ?? [];
+    warningCapture = null;
+    return captured;
+};
 export function displayWarning(message) {
     if (!shouldDisplayLevel(StatusLevel.WARNING))
         return;
+    // Collect into the active capture window (if any) so the TUI can re-surface it later. Done
+    // after the level guard so a user who quieted warnings sees them neither printed nor captured.
+    if (warningCapture)
+        warningCapture.push(message);
     const coloredMessage = colorText(message, 'yellow');
     writeToSessionLog(message + '\n');
     su.warn(coloredMessage);

package/dist/utils/consoleUtils.js.map

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

package/dist/utils/fileUtils.d.ts

@@ -60,11 +60,33 @@ export declare function readMultipleFilesFromProjectDir(fileNames: string | stri
  * package dir.
  */
 export declare function readFileFromInstallDir(filePath: string, packageDir?: string): string;
-export declare function writeFileIfNotExistsWithMessages(filePath: string, content: string): void;
+/**
+ * No-clobber write: writes `content` only when `filePath` does not already exist.
+ * @returns `true` when the file was written, `false` when it was skipped because it
+ *   already existed. Callers use the return value to avoid claiming success on a skip.
+ */
+export declare function writeFileIfNotExistsWithMessages(filePath: string, content: string): boolean;
+/**
+ * Unconditional write: writes (or overwrites) `content` at `filePath`, creating parent
+ * directories as needed. Use this only for the config-overwrite path (an explicit user /
+ * `--force` decision); the no-clobber {@link writeFileIfNotExistsWithMessages} still guards
+ * user-editable preamble files (guidelines / review).
+ */
+export declare function writeFileWithMessages(filePath: string, content: string): void;
+/**
+ * Config-file write that honours an overwrite flag.
+ * - `force === true`  → always (over)writes.
+ * - `force === false` → no-clobber (skips + warns when the file already exists).
+ * @returns `true` when a write happened, `false` when it was skipped.
+ */
+export declare function writeConfigFileWithMessages(filePath: string, content: string, force?: boolean): boolean;
 export declare function appendToFile(filePath: string, content: string): void;
 export declare function readFileSyncWithMessages(filePath: string, errorMessageIn?: string, noFileMessage?: string): string;
 /**
- * Dynamically imports a module from a file path from the outside of the installation dir
+ * Dynamically imports a module from a file path from the outside of the installation dir.
+ * `.ts` modules are loaded through jiti (Node's native dynamic `import()` cannot load
+ * TypeScript), so `.gsloth.config.ts` honours the same async `configure()` contract as
+ * `.js`/`.mjs`. All other extensions use native dynamic import.
  * @returns A promise that resolves to the imported module
  */
 export declare function importExternalFile(filePath: string): Promise<Record<string, any>>;

package/dist/utils/fileUtils.js

@@ -1,17 +1,18 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { getCurrentWorkDir } from '#src/utils/systemUtils.js';
+import { getProjectDir } from '#src/utils/systemUtils.js';
 import { GSLOTH_DIR, GSLOTH_SETTINGS_DIR } from '#src/constants.js';
 import { displayError, displayInfo, displaySuccess, displayWarning, } from '#src/utils/consoleUtils.js';
 import { wrapContent } from '#src/utils/llmUtils.js';
 import url from 'node:url';
+import { createJiti } from 'jiti';
 /**
  * Checks if .gsloth directory exists in the project root
  * @returns Boolean indicating whether .gsloth directory exists
  */
 export function gslothDirExists() {
-    const currentDir = getCurrentWorkDir();
+    const currentDir = getProjectDir();
     const gslothDirPath = resolve(currentDir, GSLOTH_DIR);
     return existsSync(gslothDirPath);
 }
@@ -21,7 +22,7 @@ export function gslothDirExists() {
  * @returns The resolved path where the file should be written
  */
 export function getGslothFilePath(filename) {
-    const currentDir = getCurrentWorkDir();
+    const currentDir = getProjectDir();
     if (gslothDirExists()) {
         const gslothDirPath = resolve(currentDir, GSLOTH_DIR);
         return resolve(gslothDirPath, filename);
@@ -40,7 +41,7 @@ export function getGslothFilePath(filename) {
  * @returns The resolved path where the configuration file should be written
  */
 export function getGslothConfigWritePath(filename) {
-    const currentDir = getCurrentWorkDir();
+    const currentDir = getProjectDir();
     if (gslothDirExists()) {
         const gslothDirPath = resolve(currentDir, GSLOTH_DIR);
         const gslothSettingsPath = resolve(gslothDirPath, GSLOTH_SETTINGS_DIR);
@@ -59,10 +60,10 @@ export function getGslothConfigWritePath(filename) {
  * @returns The resolved path where the configuration file should be found
  */
 export function getGslothConfigReadPath(filename, identityProfileRaw) {
-    const projectDir = getCurrentWorkDir();
+    const baseDir = getProjectDir();
     const identityProfile = identityProfileRaw?.trim();
     if (gslothDirExists()) {
-        const gslothDirPath = resolve(projectDir, GSLOTH_DIR);
+        const gslothDirPath = resolve(baseDir, GSLOTH_DIR);
         const gslothSettingsPath = resolve(gslothDirPath, GSLOTH_SETTINGS_DIR);
         const configPath = identityProfile
             ? resolve(gslothSettingsPath, identityProfile, filename)
@@ -71,7 +72,7 @@ export function getGslothConfigReadPath(filename, identityProfileRaw) {
             return configPath;
         }
     }
-    return resolve(projectDir, filename);
+    return resolve(baseDir, filename);
 }
 /**
  * Resolve an explicit output path string to an absolute file path.
@@ -80,7 +81,7 @@ export function getGslothConfigReadPath(filename, identityProfileRaw) {
  * - If it's a bare filename, place it under .gsloth/ when present, otherwise project root.
  */
 export function resolveOutputPath(writeOutputToFile) {
-    const currentDir = getCurrentWorkDir();
+    const currentDir = getProjectDir();
     const provided = String(writeOutputToFile).trim();
     // Detect if provided path contains path separators (cross-platform)
     const hasSeparator = provided.includes('/') || provided.includes('\\');
@@ -125,7 +126,7 @@ export function generateStandardFileName(command) {
     return `gth_${dateTimeStr}_${commandStr}.md`;
 }
 export function readFileFromProjectDir(fileName) {
-    const currentDir = getCurrentWorkDir();
+    const currentDir = getProjectDir();
     const filePath = resolve(currentDir, fileName);
     displayInfo(`Reading file ${filePath}...`);
     return readFileSyncWithMessages(filePath);
@@ -162,6 +163,11 @@ export function readFileFromInstallDir(filePath, packageDir = corePackageDir) {
         throw readFromInstallDirError;
     }
 }
+/**
+ * No-clobber write: writes `content` only when `filePath` does not already exist.
+ * @returns `true` when the file was written, `false` when it was skipped because it
+ *   already existed. Callers use the return value to avoid claiming success on a skip.
+ */
 export function writeFileIfNotExistsWithMessages(filePath, content) {
     displayInfo(`checking ${filePath} existence`);
     if (!existsSync(filePath)) {
@@ -172,10 +178,38 @@ export function writeFileIfNotExistsWithMessages(filePath, content) {
         }
         writeFileSync(filePath, content);
         displaySuccess(`Created ${filePath}`);
+        return true;
+    }
+    displayWarning(`${filePath} already exists`);
+    return false;
+}
+/**
+ * Unconditional write: writes (or overwrites) `content` at `filePath`, creating parent
+ * directories as needed. Use this only for the config-overwrite path (an explicit user /
+ * `--force` decision); the no-clobber {@link writeFileIfNotExistsWithMessages} still guards
+ * user-editable preamble files (guidelines / review).
+ */
+export function writeFileWithMessages(filePath, content) {
+    const parentDir = dirname(filePath);
+    if (!existsSync(parentDir)) {
+        mkdirSync(parentDir, { recursive: true });
     }
-    else {
-        displayWarning(`${filePath} already exists`);
+    const existed = existsSync(filePath);
+    writeFileSync(filePath, content);
+    displaySuccess(existed ? `Overwrote ${filePath}` : `Created ${filePath}`);
+}
+/**
+ * Config-file write that honours an overwrite flag.
+ * - `force === true`  → always (over)writes.
+ * - `force === false` → no-clobber (skips + warns when the file already exists).
+ * @returns `true` when a write happened, `false` when it was skipped.
+ */
+export function writeConfigFileWithMessages(filePath, content, force = false) {
+    if (force) {
+        writeFileWithMessages(filePath, content);
+        return true;
     }
+    return writeFileIfNotExistsWithMessages(filePath, content);
 }
 export function appendToFile(filePath, content) {
     try {
@@ -206,11 +240,19 @@ export function readFileSyncWithMessages(filePath, errorMessageIn, noFileMessage
     }
 }
 /**
- * Dynamically imports a module from a file path from the outside of the installation dir
+ * Dynamically imports a module from a file path from the outside of the installation dir.
+ * `.ts` modules are loaded through jiti (Node's native dynamic `import()` cannot load
+ * TypeScript), so `.gsloth.config.ts` honours the same async `configure()` contract as
+ * `.js`/`.mjs`. All other extensions use native dynamic import.
  * @returns A promise that resolves to the imported module
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function importExternalFile(filePath) {
+    if (filePath.endsWith('.ts')) {
+        const jiti = createJiti(import.meta.url);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return jiti.import(filePath);
+    }
     const configFileUrl = url.pathToFileURL(filePath).toString();
     return import(configFileUrl);
 }

package/dist/utils/fileUtils.js.map

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

package/dist/utils/systemPromptNotes.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared code-mode system-prompt augmentations (GS2-27).
+ *
+ * These notes describe capabilities that are IDENTICAL across both agent backends — the lean
+ * {@link import('#src/core/GthLangChainAgent.js').GthLangChainAgent} (`createAgent`, in core) and
+ * the deep `GthDeepAgent` (`createDeepAgent`, in `@gaunt-sloth/agent`): both expose the opt-in
+ * `run_shell_command` tool and both operate on the real filesystem cwd. They were originally
+ * composed ONLY inside `GthDeepAgent.init()` (EXT-13/EXT-26), so the now-default lean backend never
+ * received them — accidental deep-only drift of the same class GS2-21 fixed for the main prompt.
+ *
+ * They live here in core so BOTH backends compose from ONE source. `GthDeepAgent` re-exports them
+ * for back-compat with existing importers. The deepagents virtual-fs-namespace notes
+ * (`appendVirtualCwdNote` / `PATH_NAMESPACE_GUIDANCE` / the correction middleware) are NOT here:
+ * they are genuinely deep-only (a deepagents artifact — lean never runs virtualMode) and stay in
+ * `GthDeepAgent`.
+ */
+import type { McpServerInstruction } from '#src/core/types.js';
+/**
+ * EXT-26: the platform-agnostic tail shared by both {@link appendOsShellNote} branches.
+ *
+ * The recurring failure mode on non-POSIX hosts is not just wrong command NAMES but shell
+ * REDIRECTION quoting: a grouped/multi-line `echo` redirect on cmd.exe reported success yet wrote
+ * a 0-byte file. So on every platform we steer file creation/mutation to the built-in
+ * `write_file`/`edit_file` tools (which never touch the shell's quoting) and keep each shell
+ * command a single line. Kept short — this is prompt text an LLM reads, not documentation.
+ */
+export declare const OS_SHELL_GUIDANCE: string;
+/**
+ * EXT-26: append an OS + shell-dialect note to the composed code-mode system prompt.
+ *
+ * The model was never told its host OS or which shell `run_shell_command` uses, so on
+ * non-POSIX hosts it defaulted to POSIX idioms that fail (ran `ls` where cmd.exe has `dir`, a
+ * multi-line echo-redirect that wrote 0 bytes, a PowerShell here-string, `python -c` multi-line).
+ * This is ORTHOGONAL to the EXT-13/16/22 path-namespace notes: those say WHERE the model is (path
+ * form); this says WHAT shell it speaks (dialect). Backend-agnostic — the lean backend also exposes
+ * `run_shell_command`, so GS2-27 composes it in the shared path.
+ *
+ * The shell is derived from the SAME rule Node's `spawn(command, { shell: true })` uses — exactly
+ * how `run_shell_command` spawns (GthDevToolkit spawn) — so on `win32` it is cmd.exe (via
+ * `%ComSpec%`) and on POSIX it is `/bin/sh` (POSIX sh, NOT guaranteed bash). Computed from
+ * `process.platform` at call time so the text is correct per host. Returns the note alone when
+ * there is no base prompt. A single injection is authoritative (nothing in the base prompt
+ * contradicts shell dialect), so unlike EXT-22 no correction middleware is needed.
+ */
+export declare function appendOsShellNote(systemPrompt: string | undefined): string;
+/**
+ * EXT-13 (part b): append a real-cwd / path-model note to the composed code-mode system prompt.
+ *
+ * Code mode runs in REAL-path mode, so the filesystem tools and `run_shell_command` share one
+ * real-absolute-path namespace rooted at `cwd`. The shared `.gsloth.code.md` prompt already tells
+ * the model "the current working directory is provided to you separately"; this note is what
+ * provides it — without it the model assumes `/` is cwd and hands `/`-rooted paths to the real-fs
+ * shell. The cwd is injected dynamically (never baked into the .md). Backend-agnostic — the lean
+ * backend also runs real-fs code sessions and previously received NO cwd value, so GS2-27 composes
+ * it in the shared path. Returns the note alone when there is no base prompt.
+ */
+export declare function appendCwdNote(systemPrompt: string | undefined, cwd: string): string;
+/**
+ * EXT-32: hard per-server cap on injected MCP instruction length.
+ *
+ * A connected MCP server could advertise a very long `instructions` string that would then ride
+ * along in EVERY turn's system prompt and bloat context. This is a simple defensive constant (no
+ * config-schema plumbing — that stays out of this node): text beyond the cap is dropped and a
+ * truncation marker is appended so the model knows it was clipped. Generous enough that realistic
+ * server instructions pass through untouched.
+ */
+export declare const MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER = 4000;
+/** EXT-32: truncation marker appended when a server's instructions exceed the per-server cap. */
+export declare const MCP_INSTRUCTIONS_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * EXT-32: append connected MCP servers' discovery `instructions` to the composed system prompt.
+ *
+ * Each connected MCP server may return an `instructions` string in its `initialize` handshake that
+ * describes how to use its tools. We surface those to the model — but the text is **server-supplied
+ * and therefore a prompt-injection surface**, so it is:
+ *   - fenced in an explicit `[BEGIN/END MCP SERVER-PROVIDED CONTEXT]` block (never blended into
+ *     first-party prompt text),
+ *   - labelled per server (`--- Server: "name" ---`) so the model can attribute each block, and
+ *   - bracketed by a leading framing line AND a trailing first-party reassertion, so the LAST thing
+ *     the model reads is gsloth's own authority, not the server text — server instructions may not
+ *     override the system instructions, safety rules, or the user's directives.
+ *
+ * Backend-agnostic: composed through the shared path so BOTH the lean `GthLangChainAgent` and the
+ * deep `GthDeepAgent` inject it. Empty/absent contributes NOTHING: when no server supplied
+ * (non-whitespace) instructions the base prompt is returned unchanged — no empty header, no dangling
+ * label. Each server's text is trimmed and capped at {@link MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER}.
+ * Returns the block alone when there is no base prompt.
+ */
+export declare function appendMcpServerInstructionsNote(systemPrompt: string | undefined, instructions: McpServerInstruction[] | undefined): string | undefined;