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

package/dist/config/types.d.ts

@@ -7,7 +7,48 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
 import type { StatusLevel } from '#src/core/types.js';
-import type { GthDevToolsConfig } from '#src/config/shell-policy.js';
+import type { ApprovalsConfig, BuiltInToolsSetting } from '#src/config/shell-policy.js';
+import type { GthAcpSessionMode, GthOutputHeaderRung } from '#src/config/schema.js';
+/**
+ * GS2-43 — the seven configurable prompt segments. Each maps to a prompt file with a
+ * well-known default name (`.gsloth.backstory.md`, `.gsloth.guidelines.md`,
+ * `.gsloth.system.md`, `.gsloth.chat.md`, `.gsloth.code.md`, `.gsloth.exec.md`,
+ * `.gsloth.review.md`) and can be retargeted / disabled / composed via
+ * {@link GthConfig.prompts}.
+ */
+export type PromptSegmentName = 'backstory' | 'guidelines' | 'system' | 'chat' | 'code' | 'exec' | 'review';
+/**
+ * GS2-43 — configuration for one prompt segment.
+ */
+export interface PromptSegmentConfig {
+    /**
+     * File to read for this segment. Resolved like every prompt file: the config dir
+     * (`.gsloth/.gsloth-settings[/<profile>]/`) first, then relative to the project root.
+     */
+    path?: string;
+    /**
+     * `false` drops the segment entirely — even its bundled default. Default `true`.
+     */
+    enabled?: boolean;
+    /**
+     * `'replace'` (default): the {@link path} file replaces the built-in segment content.
+     * `'append'`: the file content is appended after the built-in content.
+     */
+    mode?: 'replace' | 'append';
+}
+/**
+ * GS2-43 — one segment's setting: a `string` path (shorthand for `{ path }`) or a
+ * {@link PromptSegmentConfig} object.
+ */
+export type PromptSegmentSetting = string | PromptSegmentConfig;
+/**
+ * GS2-43 — the unified `prompts` config object. Replaces the removed flat
+ * `projectGuidelines` / `projectReviewInstructions` keys and makes all seven prompt
+ * segments retargetable through config. Sibling keys are trivially addable (GS2-44 will
+ * add `agents` for AGENTS.md auto-discovery), so keep segment names and future siblings
+ * in this one flat namespace.
+ */
+export type PromptsConfig = Partial<Record<PromptSegmentName, PromptSegmentSetting>>;
 /**
  * Shared per-command tooling configuration (the knobs every actionable command carries).
  * Reused across the per-command types in {@link GthConfig.commands} and by
@@ -18,12 +59,41 @@ import type { GthDevToolsConfig } from '#src/config/shell-policy.js';
  */
 export interface CommandToolingConfig {
     filesystem?: string[] | 'all' | 'read' | 'none';
-    builtInTools?: string[];
+    builtInTools?: BuiltInToolsSetting;
+    /**
+     * §9.1 — per-command approvals posture. It overrides only the fields it NAMES: `mode`,
+     * `rater`, `raterTimeoutMs` and `allow` replace the root's, while `deny` and `escalate`
+     * concatenate with it. See {@link GthConfig.approvals}.
+     */
+    approvals?: ApprovalsConfig;
     customTools?: CustomToolsConfig | false;
     /** See {@link GthConfig.allowedTools}. */
     allowedTools?: string[];
     binaryFormats?: false | BinaryFormatConfig[];
 }
+/**
+ * GS2-33 — one profile-backed subagent declaration. When the parent agent spawns this subagent,
+ * the CHILD resolves the named config {@link profile} through the GS2-1 cascade, so it runs under
+ * THAT profile's model + tools + prompt (e.g. a cheap flash-lite profile for recall/search
+ * subagents while the parent runs on a strong model).
+ *
+ * No backend spawns subagents today — see the `subagents` field on {@link GthConfig}.
+ *
+ * The `profile` is a named profile block created by `gth config profile create <name>` — a
+ * `.gsloth/.gsloth-settings/<name>/` config dir, the same discovery convention `--profile` /
+ * `--identity-profile` resolve.
+ */
+export interface SubagentProfileSpec {
+    /** Identifier the model selects this subagent by (the task-tool subagent name). */
+    name: string;
+    /** Description shown to the model when it chooses a subagent. Defaults to a profile note. */
+    description?: string;
+    /**
+     * Named config profile whose model + tools + prompt the CHILD resolves. Threaded through the
+     * subagent-spawn config resolution as {@link CommandLineConfigOverrides.identityProfile}.
+     */
+    profile: string;
+}
 /**
  * This is a processed Gaunt Sloth config ready to be passed down into components.
  *
@@ -31,6 +101,39 @@ export interface CommandToolingConfig {
  */
 export interface GthConfig {
     llm: BaseChatModel;
+    /**
+     * Selects the agent backend.
+     *
+     * `lean` — the plain LangChain agent ({@link GthLangChainAgent}), given gsloth's full toolset
+     * (filesystem + hardened dev/shell + the `gth_checklist` planning tool) — is the only backend,
+     * and what runs when the key is omitted. Every command resolves the same one, so the key selects
+     * nothing today; it exists so a config can name what it runs on, and so a second backend has a
+     * name to arrive under.
+     *
+     * The retired `deep` value is a hard config error, not a coercion — see `RETIRED_AGENT_BACKENDS`
+     * in `config/schema.ts` for why substituting a different agent for the one a config named is the
+     * wrong kindness.
+     */
+    agent?: {
+        backend?: 'lean';
+    };
+    /**
+     * GS2-7 (B20) — local, opt-in session history store. DEFAULT OFF (absent = disabled): a default
+     * run persists nothing and behaves exactly as before. When `enabled`, each run is recorded to a
+     * local SQLite DB (`~/.gsloth/history.db` by default, overridable via `dbPath`) for
+     * `gth history search` / `gth insights`. Local only — no telemetry leaves the machine.
+     */
+    history?: {
+        enabled?: boolean;
+        dbPath?: string;
+    };
+    /**
+     * GS2-7 (B21) — opt-in file-backed memory (MEMORY.md / USER.md). DEFAULT OFF. Forward-compat
+     * toggle only; the feature is a deferred follow-up.
+     */
+    memory?: {
+        enabled?: boolean;
+    };
     /**
      * Binary format support configuration.
      * Disabled by default unless explicitly configured.
@@ -47,11 +150,12 @@ export interface GthConfig {
      */
     requirementSource: string;
     /**
-     * Path to project-specific guidelines.
-     * The default is `.gsloth.guidelines.md`; this config may be used to point Gaunt Sloth to a different file,
-     * for example, to AGENTS.md
+     * GS2-43 — the unified prompt-segment config (see {@link PromptsConfig}). Each of the seven
+     * segments (`backstory | guidelines | system | chat | code | exec | review`) accepts a string
+     * path (e.g. `"guidelines": "AGENTS.md"`) or an object (`{ path?, enabled?, mode? }`). When a
+     * segment is omitted its default-named file / bundled default applies unchanged.
      */
-    projectGuidelines: string;
+    prompts?: PromptsConfig;
     /**
      * Separate identity profile.
      * May include separate identity, guidelines and command protocol,
@@ -75,7 +179,6 @@ export interface GthConfig {
         locale?: string;
         timezone?: string;
     };
-    projectReviewInstructions: string;
     /**
      * If true, only use user-provided system prompts. Do not fall back to the
      * bundled `.gsloth.*.md` prompt files shipped with the installation.
@@ -83,7 +186,32 @@ export interface GthConfig {
      */
     noDefaultPrompts?: boolean;
     filesystem: string[] | 'all' | 'read' | 'none';
-    builtInTools?: string[];
+    /**
+     * Selects and configures the built-in tools the agent loads. Either a `string[]` of tool names
+     * (each enabled) or a registry keyed by tool name whose values enable (`true`), force-disable
+     * (`false`), or configure ({@link BuiltInToolConfig}) each tool. CFG-18 folded the former
+     * per-command `devTools` (the `run_*` commands + `run_shell_command`'s EXT-9/10/12 config) into
+     * this single registry: e.g. `{ "run_tests": { "command": "npm test" }, "run_shell_command": {
+     * "timeout": 300000 } }`. Settable at the root or per command (`commands.<command>.builtInTools`);
+     * a per-command value replaces the top-level one.
+     */
+    builtInTools?: BuiltInToolsSetting;
+    /**
+     * CFG-27 — the tool-approval **ladder**: one of the five rungs (`manual` · `write` ·
+     * `assisted` · `auto` · `bypass`), written either as the bare rung name or as an object
+     * carrying the rater's identity profile and the declared allow/deny lists. Each rung fully
+     * determines behaviour — there are no severity thresholds, no strictness levels and no
+     * independent rater switch.
+     *
+     * Settable at the root or per command (`commands.<command>.approvals`). §9.1 — a per-command
+     * value overrides only the fields it NAMES. `mode`, `rater` and `raterTimeoutMs` replace the
+     * root's; `deny` and `escalate` CONCATENATE across every scope, so a per-command rung can never
+     * discard the root's prohibitions; `allow` is REPLACED when the command states its own and
+     * inherited when it does not, so a scope may narrow what runs unprompted and may never widen
+     * what is prohibited (§3.1: a too-broad allow entry runs unrated, a missed deny entry does not).
+     * Absent = `assisted`, resolved by `resolveApprovals`.
+     */
+    approvals?: ApprovalsConfig;
     tools?: StructuredToolInterface[] | BaseToolkit[] | ServerTool[];
     /**
      * Restrict the agent to this allow-list of tool names, applied after every tool source
@@ -141,6 +269,8 @@ export interface GthConfig {
     /**
      * Should the output be written to md file.
      * (e.g. gth_2025-07-26_22-59-06_REVIEW.md).
+     * Defaults to `false` (no file is written); set to `true` for the standard
+     * `gth_<timestamp>_<COMMAND>.md` name.
      * Can be set to false with `-wn` or `-w0`
      * Can be set to a specific filename or path by passing a string:
      * - Bare filenames (e.g. `"review.md"`) are placed in `.gsloth/` when it exists, otherwise project root
@@ -157,6 +287,13 @@ export interface GthConfig {
      * Use colour in output
      */
     useColour: boolean;
+    /**
+     * Enable terminal mouse reporting in the Ink TUI, making its affordances clickable.
+     * On by default in an interactive terminal. While it is on the terminal's own text selection
+     * needs a modifier (Shift, or Option in some macOS terminals) — set this to `false`, or set
+     * `GTH_NO_MOUSE`, to get unmodified selection back.
+     */
+    useMouse: boolean;
     /**
      * Stream session log instead of writing it when inference streaming is complete.
      * (only works when {@link streamOutput} is true)
@@ -193,6 +330,24 @@ export interface GthConfig {
      * @see {@link https://modelcontextprotocol.io/}
      */
     mcpServers?: Record<string, unknown>;
+    /**
+     * TLS trust for outbound HTTPS. Primarily so an `http`-transport MCP server behind a
+     * private/corporate CA can be reached without prepending `NODE_EXTRA_CA_CERTS` on every
+     * invocation. The mechanism is a process-global undici dispatcher, so it applies to ALL
+     * outbound `fetch` this process makes (LLM provider calls included), not only MCP.
+     */
+    tls?: {
+        /**
+         * Extra CA certificate file(s) to trust IN ADDITION to Node's built-in roots. Paths resolve
+         * relative to the project dir (or `~`/absolute). Additive — never removes a default root.
+         */
+        extraCaCerts?: string[];
+        /**
+         * DANGER — `false` disables TLS certificate verification for ALL outbound HTTPS this process
+         * makes, not just MCP. Escape hatch only; a loud security warning is emitted every session.
+         */
+        rejectUnauthorized?: boolean;
+    };
     /**
      * A2A (Agent-to-Agent) protocol agents configuration.
      * Enables delegation of tasks to external AI agents.
@@ -213,27 +368,27 @@ export interface GthConfig {
             requirementSource?: string;
             rating?: RatingConfig;
         };
-        ask?: CommandToolingConfig & {
-            /**
-             * Dev tools (run commands etc.) for `ask --write` runs. Normally inherited from
-             * `commands.exec` / `commands.code` by the `--write` flag rather than set directly.
-             */
-            devTools?: GthDevToolsConfig;
-        };
+        ask?: CommandToolingConfig;
         chat?: CommandToolingConfig;
-        code?: CommandToolingConfig & {
-            devTools?: GthDevToolsConfig;
-        };
+        /**
+         * `gth code` — interactive coding session. Carries the do-the-job tool/filesystem knobs; the
+         * dev/shell tools (CFG-18) are configured via {@link CommandToolingConfig.builtInTools}.
+         */
+        code?: CommandToolingConfig;
         /**
          * `gth exec` — prompt-as-script runtime. Like `code`, an exec run may need to actually
          * do the job (read/write files, run commands), so it carries the same tool/filesystem knobs.
          */
-        exec?: CommandToolingConfig & {
-            devTools?: GthDevToolsConfig;
-        };
+        exec?: CommandToolingConfig;
         api?: {
             filesystem?: string[] | 'all' | 'read' | 'none';
-            builtInTools?: string[];
+            builtInTools?: BuiltInToolsSetting;
+            /**
+             * §9.1 — per-command approvals posture. It overrides only the fields it NAMES: `mode`,
+             * `rater`, `raterTimeoutMs` and `allow` replace the root's, while `deny` and `escalate`
+             * concatenate with it. See {@link GthConfig.approvals}.
+             */
+            approvals?: ApprovalsConfig;
             port?: number;
             cors?: {
                 allowOrigin?: string;
@@ -242,14 +397,93 @@ export interface GthConfig {
             };
         };
     };
+    /**
+     * EXT-117 — the ACP (Agent Client Protocol) surface, i.e. a session an editor such as Zed opens.
+     *
+     * `mode` is the command an ACP session is resolved under, and it defaults to **`code`**: an
+     * editor asks for an agent that can do the job, and a read-only one is a worse default than an
+     * occasional prompt. Set `acp: { mode: 'chat' }` for a read-only editor agent.
+     *
+     * The deliberate consequence, because it is what makes this overridable without a second parallel
+     * config surface: the mode names an EXISTING command, so an ACP session is configured by that
+     * command's own block. At the default the session takes its `filesystem`, `approvals`,
+     * `builtInTools` and mode prompt from **{@link GthConfig.commands}`.code`** — the same settings
+     * `gth code` runs under — and at `chat` from `commands.chat`. There is no ACP-only copy of those
+     * knobs to keep in step.
+     *
+     * Defaulted at the read site (not in {@link DEFAULT_CONFIG}) to avoid churning the
+     * effective-config snapshot, à la {@link injectModelContext}.
+     */
+    acp?: {
+        mode?: GthAcpSessionMode;
+    };
+    /**
+     * GS2-35/EXT-83 — identity for the `Co-Authored-By` trailer of agent-authored git commits. Gaunt
+     * Sloth has no dedicated commit tool (it commits via `run_shell_command`), so this identity is
+     * injected into the code-mode system prompt, which instructs the agent to co-author commits as
+     * this account. Optional and defaulted, each field independently: when the name is unset the
+     * default is {@link DEFAULT_COMMIT_CO_AUTHOR_NAME} decorated with the resolved active model —
+     * `Gaunt Sloth (provider:model)` — falling back to the bare
+     * {@link DEFAULT_COMMIT_CO_AUTHOR_NAME} when no model resolves or {@link injectModelContext} is
+     * `false`; when the email is unset it is {@link DEFAULT_COMMIT_CO_AUTHOR_EMAIL}. A CONFIGURED
+     * name is emitted verbatim — the model identity decorates only the default.
+     */
+    commit?: {
+        coAuthor?: {
+            name?: string;
+            email?: string;
+        };
+    };
     modelDisplayName?: string;
     /**
-     * Transient (runtime-only) extra filesystem roots the agent is allowed to read/write for
-     * THIS run, in addition to the cwd sandbox. Populated by `gth exec --allow-dir <path>`
-     * (repeatable); never persisted to a config file. When set, the deep agent's
-     * {@link FilesystemBackend} drops `virtualMode` (so absolute paths and `..` resolve on the
-     * real filesystem) and access is constrained to cwd + these dirs via permission allow-rules.
-     * Removing the cwd-only sandbox is a guardrail removal, so callers announce it loudly.
+     * GS2-53 — the configured provider `type` string (`openrouter`/`deepseek`/`xai`/`anthropic`/…),
+     * stashed by the loader from the raw `llm.type` before the built `BaseChatModel` replaces the raw
+     * spec. INTERNAL (loader-set, never user-supplied), so it is deliberately absent from the config
+     * schema. {@link import('#src/utils/systemPromptNotes.js').resolveModelIdentity} PREFERS this over
+     * the live model's `_llmType()` for the injected identity, because that is the model class's own
+     * label rather than the gth provider namespace (`huggingface` reports `openai`, and both Gemini
+     * providers report `google`) and would otherwise mislabel the provider half. Absent for module
+     * configs (which hand us an already-built
+     * LLM with no raw `type`), where resolution falls back to the guarded `_llmType()`.
+     */
+    modelProviderType?: string;
+    /**
+     * GS2-34 — inject the resolved active `provider:model` identity into the assembled system prompt
+     * so the agent knows which model is serving it (to answer "what model are you?" and reason about
+     * its own capabilities/limits). Default ON (omitted = inject). Opt out with
+     * `injectModelContext: false` to keep reproducible / model-agnostic runs (e.g. review) blind to
+     * the identity — when off, the assembled prompt is exactly as it is without this feature.
+     *
+     * EXT-83 — it governs the model identity EVERYWHERE in the prompt, not just the identity line:
+     * in `code` mode the same resolved identity decorates the default git commit co-author name
+     * ({@link GthConfig.commit}), so turning this off also removes the model from the commit trailer,
+     * which degrades to the plain default name. The identity LINE applies in all modes; the trailer
+     * it also feeds is code-mode-only, like the cwd/os-shell notes. Defaulted at the read site (not
+     * in {@link DEFAULT_CONFIG}) to avoid churning the effective-config snapshot.
+     */
+    injectModelContext?: boolean;
+    /**
+     * GS2-47 — controls the shared secret-redaction pass applied to `/debug-dump` archives. Default
+     * ON (omitted = redact): secret-named env-var values, inline config secrets, provider-key/auth
+     * patterns and sensitive config fields are masked before any artifact hits disk. Set
+     * `debugDump.redact: false` (or run `/debug-dump --unsafe-no-redact`) to write a RAW archive, which
+     * the command flags with a loud "may contain secrets" warning. Defaulted at the read site (not in
+     * {@link DEFAULT_CONFIG}) to avoid churning the effective-config snapshot.
+     */
+    debugDump?: {
+        redact?: boolean;
+    };
+    /**
+     * Transient (runtime-only) extra filesystem roots the agent may read/write for THIS run, in
+     * addition to the cwd sandbox. Populated by `gth exec --allow-dir <path>` (repeatable); never
+     * persisted to a config file.
+     *
+     * **Currently inert.** The permission layer that widened the sandbox belonged to the deepagents
+     * backend; the filesystem toolkit the lean agent uses is rooted at the cwd and has no notion of
+     * extra roots. The field, the flag and the config merge policy are kept so a config and a script
+     * that already declare roots keep working when widening returns, and `gth exec` says plainly
+     * that the flag does nothing rather than announcing a widening that never happens — a warning
+     * about a guardrail that was not actually removed teaches the user to distrust the warnings.
      */
     allowDirs?: string[];
     /**
@@ -258,6 +492,83 @@ export interface GthConfig {
      * (read/write files, run commands) rather than only chat. Never persisted to a config file.
      */
     askWriteMode?: boolean;
+    /**
+     * GS2-93 — output surface controls.
+     *
+     * `output.header` grades what a NON-TUI text run (`--no-tui`, `ask`, `exec`, `eval`, `pr`,
+     * `review`, piped/CI) opens with, across three rungs:
+     *
+     * - `debug` — the full technical preamble: the Workdir/Model/Tools/Middleware status block, the
+     *   `Press Escape or Q to interrupt` hint, and their surrounding blank lines.
+     * - `compact` (the DEFAULT, so an unset key opens with this) — no preamble, and one attribution
+     *   line naming the command and the model that served it. `review`/`pr` render their existing
+     *   attribution block instead of this line.
+     * - `none` — nothing at all, including the review attribution block, for a byte-clean stream a
+     *   caller can diff or template.
+     *
+     * The interactive TUI ignores the setting and always shows the full header. Only the opening is
+     * graded — never model/tool output, errors, or config-validation warnings, and never the live
+     * `Thinking…` indicator. Defaulted at the read site, not in {@link DEFAULT_CONFIG}, to avoid
+     * churning the effective-config snapshot.
+     */
+    output?: {
+        header?: GthOutputHeaderRung;
+    };
+    /**
+     * EXT-36 — the tool-loop guard: a repeated-identical-`(tool, args)` / no-progress detector that
+     * runs as a lean-backend `beforeModel` middleware, the orthogonal sibling of GS2-36's
+     * consecutive-tool-ERROR budget. It catches the case GS2-36 leaves open — a model re-issuing the
+     * SAME call verbatim, whether it keeps erroring or keeps "succeeding" with the same result.
+     *
+     * - `false` disables it entirely.
+     * - `true` / omitted → WARN on, HALT off, default threshold ({@link DEFAULT_TOOL_LOOP_THRESHOLD}).
+     * - object → per-field: `warn` (default ON) injects a control-flow-free nudge at the threshold;
+     *   `halt` (default OFF, opt-in) ends the run cleanly (`jumpTo:'end'`, never a throw) at the
+     *   threshold; `threshold` is the number of consecutive identical calls that trip it.
+     *
+     * WARN is provably harmless (no routing effect, one nudge per signature per streak). The WARN-on
+     * default is applied at the read site (not in {@link DEFAULT_CONFIG}) to avoid churning the
+     * effective-config snapshot.
+     */
+    toolLoopGuard?: boolean | {
+        warn?: boolean;
+        halt?: boolean;
+        threshold?: number;
+    };
+    /**
+     * CFG-37 — persistent surface preference for the `chat`/`code` interactive sessions, settable in
+     * both the global and the project config (the project layer wins). `true` asks for the Ink TUI,
+     * `false` for the plain readline session, absent leaves the terminal auto-detect in charge —
+     * which is why it must stay optional, exactly as {@link useColour}/{@link useMouse} do.
+     *
+     * This is the CONFIG-FILE preference, one rung of a chain rather than the answer: the
+     * `--tui`/`--no-tui` flags and the `GTH_NO_TUI` escape hatch both outrank it, and the capability
+     * gates (no TTY, `TERM=dumb`, `ink` not installed) outrank everything because they are checks and
+     * not preferences — so `true` degrades to readline rather than forcing a crash. Deliberately NOT
+     * in {@link DEFAULT_CONFIG}. The flag arrives separately as
+     * {@link CommandLineConfigOverrides.tui}; the two meet only in `shouldUseTui`.
+     */
+    tui?: boolean;
+    /**
+     * BATCH-19 — custom `gth eval` reporters, keyed by the NAME they are selected under
+     * (`gth eval … --reporter <name>`). Each value is a MODULE PATH, resolved relative to the project
+     * dir, whose **default export** is an `EvalReporterFactory` (`() => EvalReporter`). Loaded and
+     * registered through the SAME seam the bundled reporters (`text`, `junit`) use, so a config
+     * reporter can also override a built-in of the same name (config wins). A missing file, a failed
+     * import, or a non-function default export is a hard error (the eval harness exits 2). Trusted:
+     * it is the user's own config, which already executes arbitrary JS.
+     */
+    reporters?: Record<string, string>;
+    /**
+     * GS2-33 — profile-backed subagents. Each entry names a subagent and the {@link
+     * SubagentProfileSpec.profile named config profile} the CHILD resolves when the parent spawns it,
+     * so a subagent can run under a different model/tools/prompt than the parent (a cheap profile for
+     * recall/search while the parent runs on a strong model). **Currently honored by nothing:** its
+     * only consumer was the deep (deepagents) backend, whose `task` tool gained one selectable
+     * subagent per entry, and that backend has been removed. The key is still accepted and warns on
+     * use; the lean backend's own subagent primitive lands in GS2-25.
+     */
+    subagents?: SubagentProfileSpec[];
 }
 /**
  * `gth pr` command configuration.
@@ -291,6 +602,13 @@ export type ConsoleLevelInput = StatusLevel | keyof typeof StatusLevel | Lowerca
 export interface RawGthConfig extends Omit<GthConfig, 'llm' | 'consoleLevel'> {
     llm: LLMConfig;
     consoleLevel?: ConsoleLevelInput;
+    /**
+     * GS2-41 — profile composition. When set on a NAMED profile config, this profile inherits from
+     * the named base profile: the base resolves first, then this profile's fields merge on top
+     * (last-wins). Raw-config-only — resolved and consumed at load time (`resolveConfigExtends`), so
+     * it never appears on the resolved {@link GthConfig}.
+     */
+    extends?: string;
 }
 export type BinaryFormatType = 'image' | 'file' | 'audio' | 'video' | 'binary';
 export interface BinaryFormatConfig {
@@ -407,7 +725,7 @@ export interface LLMConfig extends Record<string, unknown> {
     configuration: Record<string, unknown>;
     apiKeyEnvironmentVariable?: string;
 }
-export declare const availableDefaultConfigs: readonly ["vertexai", "anthropic", "groq", "deepseek", "openai", "google-genai", "xai", "openrouter", "ollama"];
+export declare const availableDefaultConfigs: readonly ['vertexai', 'anthropic', 'groq', 'deepseek', 'openai', 'google-genai', 'xai', 'openrouter', 'huggingface', 'ollama'];
 export type ConfigType = (typeof availableDefaultConfigs)[number];
 export interface CommandLineConfigOverrides {
     /**
@@ -423,6 +741,8 @@ export interface CommandLineConfigOverrides {
     /**
      * Should the output be written to md file.
      * (e.g. gth_2025-07-26_22-59-06_REVIEW.md).
+     * Defaults to `false` (no file is written); set to `true` for the standard
+     * `gth_<timestamp>_<COMMAND>.md` name.
      * Can be set to false with `-wn` or `-w0`
      * Can be set to a specific filename or path by passing a string:
      * - Bare filenames (e.g. `"review.md"`) are placed in `.gsloth/` when it exists, otherwise project root
@@ -442,12 +762,30 @@ export interface CommandLineConfigOverrides {
      */
     identityProfile?: string;
     /**
-     * Interactive TUI activation override for chat/code sessions.
-     * - `true` (`--tui`): force the Ink TUI on where the terminal supports it (also overrides
-     *   the CI auto-off heuristic).
+     * Interactive TUI activation override for chat/code sessions, as passed on the command line.
+     * - `true` (`--tui`): force the Ink TUI on where the terminal supports it (it outranks the
+     *   `GTH_NO_TUI` escape hatch, the {@link GthConfig.tui} config key and the CI auto-off
+     *   heuristic).
      * - `false` (`--no-tui`): force the plain readline session.
-     * - `undefined` (default): auto-detect from the terminal.
-     * The decision itself lives in `gaunt-sloth`'s `shouldUseTui`; this only carries the flag.
+     * - `undefined` (default): defer to the next rung down — `GTH_NO_TUI`, then the
+     *   {@link GthConfig.tui} config key, then terminal auto-detect.
+     * This carries only the FLAG; the persistent preference is {@link GthConfig.tui}. The decision
+     * that ranks them lives in `gaunt-sloth`'s `shouldUseTui`.
      */
     tui?: boolean;
+    /**
+     * BATCH-1 fix — run with a different model than the configured `llm.model`, just for this
+     * `initConfig()` call. Used by `gth batch --models a,b,c` to build one genuinely fresh
+     * `GthConfig` (with its own freshly-constructed `.llm`) per distinct model in the matrix,
+     * instead of structurally cloning an already-instantiated LangChain model object (unsafe for
+     * any provider class that keeps state behind private `#fields`). Applied in
+     * {@link tryJsonConfig} by overriding `llmConfig.model` before the provider's
+     * `processJsonConfig()` builds the instance, so it flows through the same supported
+     * construction path every other model comes from.
+     *
+     * Only takes effect for JSON (`.gsloth.config.json`) configs — a `configure()`-style JS/MJS/TS
+     * module config already returns a fully-built `GthConfig` (LLM included) with no generic seam
+     * to re-target its model.
+     */
+    model?: string;
 }

package/dist/config/types.js

@@ -7,6 +7,7 @@ export const availableDefaultConfigs = [
     'google-genai',
     'xai',
     'openrouter',
+    'huggingface',
     'ollama',
 ];
 //# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AA+aA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,QAAQ;CACA,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAmuBA,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU;IACV,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,cAAc;IACd,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;CACA,CAAC"}

package/dist/config.d.ts

@@ -14,12 +14,46 @@
  * - `config/shell-policy.ts` — {@link GthDevToolsConfig} + the shell/dev-tools resolvers.
  * - `config/defaults.ts` — {@link DEFAULT_CONFIG}.
  * - `config/loader.ts` — discovery + the layered load/merge pipeline.
- * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator.
+ * - `config/providerKeys.ts` — {@link MissingProviderKeyError}, the catchable error a load raises
+ *   when a provider has no resolvable API key.
+ * - `config/configDiscovery.ts` — {@link ConfigDiscoveryError}, the catchable error a load raises
+ *   when a named identity profile does not resolve or a config layer is malformed.
+ * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator. Its
+ *   schema-owned *types* that appear in this barrel's own type surface are re-exported below; its
+ *   runtime helpers stay behind the `config/schema.js` deep path.
+ * - `config/tool-descriptions.ts` — EXT-58: the rung-aware tool-description suffixes (§4.5) and
+ *   the granted-built-in table the rater's alternative suggestion draws on (§4.4).
+ * - `config/filesystem-tools.ts` — the one interpretation of `filesystem`: which filesystem tools
+ *   it registers, shared by the toolkit filter and the system-prompt notes.
  *
  * Every name that was previously exported from `config.ts` is re-exported here, so the
  * public import path `@gaunt-sloth/core/config.js` (and `#src/config.js`) is unchanged.
  */
 export * from '#src/config/types.js';
 export * from '#src/config/shell-policy.js';
+export * from '#src/config/tool-descriptions.js';
+export * from '#src/config/filesystem-tools.js';
 export * from '#src/config/defaults.js';
 export * from '#src/config/loader.js';
+export * from '#src/config/profiles.js';
+export * from '#src/config/providerKeys.js';
+export * from '#src/config/configDiscovery.js';
+/**
+ * Schema-owned types that a consumer of this barrel would otherwise be unable to NAME: each one is
+ * the declared type of something already reachable here, so leaving it out lets a caller assign a
+ * value it cannot type.
+ *
+ * - {@link GthOutputHeaderRung} — the type of {@link GthConfig}'s `output.header`.
+ * - {@link GthAcpSessionMode} — the type of {@link GthConfig}'s `acp.mode`.
+ * - {@link RawConfigValidationResult} — the interface {@link ConfigLayerValidationReport} extends.
+ *
+ * These stay declared in `config/schema.ts` on purpose: `config/types.ts` importing the rung from
+ * the Zod schema is what keeps the type and the validator a single source of truth rather than a
+ * hand-written twin. The re-export is type-only, so it erases at emit and adds no runtime edge.
+ *
+ * The schema's runtime surface — `rawGthConfigSchema`, `generateConfigJsonSchema`,
+ * `validateRawGthConfig`, the deprecation scanners, `KNOWN_TOP_LEVEL_KEYS` — is deliberately NOT
+ * re-exported: it is validator internals, reachable at your own risk via the
+ * `@gaunt-sloth/core/config/schema.js` deep path.
+ */
+export type { GthAcpSessionMode, GthOutputHeaderRung, RawConfigValidationResult, } from '#src/config/schema.js';

package/dist/config.js

@@ -14,13 +14,28 @@
  * - `config/shell-policy.ts` — {@link GthDevToolsConfig} + the shell/dev-tools resolvers.
  * - `config/defaults.ts` — {@link DEFAULT_CONFIG}.
  * - `config/loader.ts` — discovery + the layered load/merge pipeline.
- * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator.
+ * - `config/providerKeys.ts` — {@link MissingProviderKeyError}, the catchable error a load raises
+ *   when a provider has no resolvable API key.
+ * - `config/configDiscovery.ts` — {@link ConfigDiscoveryError}, the catchable error a load raises
+ *   when a named identity profile does not resolve or a config layer is malformed.
+ * - `config/schema.ts` — the Zod schema (single source of truth) + JSON-Schema generator. Its
+ *   schema-owned *types* that appear in this barrel's own type surface are re-exported below; its
+ *   runtime helpers stay behind the `config/schema.js` deep path.
+ * - `config/tool-descriptions.ts` — EXT-58: the rung-aware tool-description suffixes (§4.5) and
+ *   the granted-built-in table the rater's alternative suggestion draws on (§4.4).
+ * - `config/filesystem-tools.ts` — the one interpretation of `filesystem`: which filesystem tools
+ *   it registers, shared by the toolkit filter and the system-prompt notes.
  *
  * Every name that was previously exported from `config.ts` is re-exported here, so the
  * public import path `@gaunt-sloth/core/config.js` (and `#src/config.js`) is unchanged.
  */
 export * from '#src/config/types.js';
 export * from '#src/config/shell-policy.js';
+export * from '#src/config/tool-descriptions.js';
+export * from '#src/config/filesystem-tools.js';
 export * from '#src/config/defaults.js';
 export * from '#src/config/loader.js';
+export * from '#src/config/profiles.js';
+export * from '#src/config/providerKeys.js';
+export * from '#src/config/configDiscovery.js';
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC"}