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

package/dist/constants.d.ts

@@ -3,6 +3,12 @@ export declare const GSLOTH_SETTINGS_DIR = ".gsloth-settings";
 export declare const GSLOTH_AUTH = ".gsloth-auth";
 export declare const USER_PROJECT_CONFIG_JS = ".gsloth.config.js";
 export declare const USER_PROJECT_CONFIG_JSON = ".gsloth.config.json";
+/**
+ * GS2-69 — the `.jsonc` filename variant. Both JSON names are parsed by the same lenient
+ * {@link import('#src/config/jsonc.js').parseJsonc}; this one just carries the conventional
+ * extension so editors/review tools expect the comments. `.json` wins when both exist.
+ */
+export declare const USER_PROJECT_CONFIG_JSONC = ".gsloth.config.jsonc";
 export declare const USER_PROJECT_CONFIG_MJS = ".gsloth.config.mjs";
 export declare const USER_PROJECT_CONFIG_TS = ".gsloth.config.ts";
 export declare const GSLOTH_BACKSTORY = ".gsloth.backstory.md";
@@ -26,7 +32,7 @@ export declare const AIIGNORE_FILE = ".aiignore";
  * The channel is **major-pinned** (`/schema/v2/…`, not `latest` or `alpha`) so a config never
  * revalidates against a future major it was not written for. The hosted copy is kept in sync with
  * this package's generated schema by the deploy runbook in
- * `websites/gauntsloth.app/schema/README.md` (interim, hand-run) and, in time, PLAT-9's automated
+ * `websites/gauntsloth-site/schema/README.md` (interim, hand-run) and, in time, PLAT-9's automated
  * release step. The schema still ships inside the package (`files: ["./schema/*"]`) as an offline
  * artifact and golden-snapshot source of truth; it is just no longer what the pointer references.
  */
@@ -36,3 +42,24 @@ export declare const CONFIG_SCHEMA_POINTER = "https://gauntsloth.app/schema/v2/g
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export declare const SHELL_ALLOWLIST_FILE = "shell-allowlist.json";
+/**
+ * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
+ * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped
+ * `${MCP_TOOL_NAME_PREFIX}__<serverName>__<toolName>` (the `__` separator is the mcp-adapters
+ * convention). Single-sourced here so the resolver that sets the prefix (EXT-32) and any consumer
+ * that groups tools back by server (the [[TUI-C20]] MCP debug tab) can never silently drift apart.
+ */
+export declare const MCP_TOOL_NAME_PREFIX = "mcp";
+/**
+ * GS2-35 — the canonical Git co-author identity for agent-authored commits. When Gaunt Sloth writes
+ * a commit (via `run_shell_command` `git commit`) the co-author is *Gaunt Sloth itself*, NOT the
+ * underlying model: the commit was produced by the assistant, so attributing it to the model that
+ * served the session is factually wrong. The email is what makes the trailer resolve to the real
+ * Gaunt Sloth account, so it is the half that must not move. This name is the BASE the composed
+ * trailer is built from, not the whole emitted value: the resolved active model decorates it as
+ * `Gaunt Sloth (provider:model)` (EXT-83). Config (`commit.coAuthor`) overrides
+ * this; single-sourced so the config default and the prompt-guidance fallback
+ * ({@link import('#src/utils/systemPromptNotes.js').appendCommitCoAuthorNote}) can never drift.
+ */
+export declare const DEFAULT_COMMIT_CO_AUTHOR_NAME = "Gaunt Sloth";
+export declare const DEFAULT_COMMIT_CO_AUTHOR_EMAIL = "code@gauntsloth.app";

package/dist/constants.js

@@ -3,6 +3,12 @@ export const GSLOTH_SETTINGS_DIR = '.gsloth-settings';
 export const GSLOTH_AUTH = '.gsloth-auth';
 export const USER_PROJECT_CONFIG_JS = '.gsloth.config.js';
 export const USER_PROJECT_CONFIG_JSON = '.gsloth.config.json';
+/**
+ * GS2-69 — the `.jsonc` filename variant. Both JSON names are parsed by the same lenient
+ * {@link import('#src/config/jsonc.js').parseJsonc}; this one just carries the conventional
+ * extension so editors/review tools expect the comments. `.json` wins when both exist.
+ */
+export const USER_PROJECT_CONFIG_JSONC = '.gsloth.config.jsonc';
 export const USER_PROJECT_CONFIG_MJS = '.gsloth.config.mjs';
 export const USER_PROJECT_CONFIG_TS = '.gsloth.config.ts';
 export const GSLOTH_BACKSTORY = '.gsloth.backstory.md';
@@ -26,7 +32,7 @@ export const AIIGNORE_FILE = '.aiignore';
  * The channel is **major-pinned** (`/schema/v2/…`, not `latest` or `alpha`) so a config never
  * revalidates against a future major it was not written for. The hosted copy is kept in sync with
  * this package's generated schema by the deploy runbook in
- * `websites/gauntsloth.app/schema/README.md` (interim, hand-run) and, in time, PLAT-9's automated
+ * `websites/gauntsloth-site/schema/README.md` (interim, hand-run) and, in time, PLAT-9's automated
  * release step. The schema still ships inside the package (`files: ["./schema/*"]`) as an offline
  * artifact and golden-snapshot source of truth; it is just no longer what the pointer references.
  */
@@ -36,4 +42,25 @@ export const CONFIG_SCHEMA_POINTER = 'https://gauntsloth.app/schema/v2/gsloth-co
  * Lives under `.gsloth/.gsloth-settings/` like other project settings.
  */
 export const SHELL_ALLOWLIST_FILE = 'shell-allowlist.json';
+/**
+ * The `additionalToolNamePrefix` handed to `MultiServerMCPClient` so every MCP tool name is
+ * namespaced. Combined with `prefixToolNameWithServerName`, the adapter emits tool names shaped
+ * `${MCP_TOOL_NAME_PREFIX}__<serverName>__<toolName>` (the `__` separator is the mcp-adapters
+ * convention). Single-sourced here so the resolver that sets the prefix (EXT-32) and any consumer
+ * that groups tools back by server (the [[TUI-C20]] MCP debug tab) can never silently drift apart.
+ */
+export const MCP_TOOL_NAME_PREFIX = 'mcp';
+/**
+ * GS2-35 — the canonical Git co-author identity for agent-authored commits. When Gaunt Sloth writes
+ * a commit (via `run_shell_command` `git commit`) the co-author is *Gaunt Sloth itself*, NOT the
+ * underlying model: the commit was produced by the assistant, so attributing it to the model that
+ * served the session is factually wrong. The email is what makes the trailer resolve to the real
+ * Gaunt Sloth account, so it is the half that must not move. This name is the BASE the composed
+ * trailer is built from, not the whole emitted value: the resolved active model decorates it as
+ * `Gaunt Sloth (provider:model)` (EXT-83). Config (`commit.coAuthor`) overrides
+ * this; single-sourced so the config default and the prompt-guidance fallback
+ * ({@link import('#src/utils/systemPromptNotes.js').appendCommitCoAuthorNote}) can never drift.
+ */
+export const DEFAULT_COMMIT_CO_AUTHOR_NAME = 'Gaunt Sloth';
+export const DEFAULT_COMMIT_CO_AUTHOR_EMAIL = 'code@gauntsloth.app';
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AACpC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAC9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,sBAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAClG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,aAAa,CAAC;AAC3D,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAC"}

package/dist/core/GthAbstractAgent.d.ts

@@ -1,22 +1,25 @@
-import { GthConfig, ServerTool } from '#src/config.js';
-import { AgentResolvers, AgentStreamEvent, GthAgentInterface, GthCommand, GthCompiledGraph, GthRunStats, Message, PendingToolInterrupt, StatusUpdateCallback } from '#src/core/types.js';
+import { GthConfig, ServerTool, type ApprovalRung, type DescribableTool } from '#src/config.js';
+import { AgentResolvers, AgentStreamEvent, GthAgentInitOptions, GthAgentInterface, GthCommand, GthCompiledGraph, GthRunStats, Message, PendingToolInterrupt, StatusUpdateCallback } from '#src/core/types.js';
+import type { GthOutputHeaderRung } from '#src/config/schema.js';
+import type { DeclaredToolAnnotations } from '#src/core/approvals/annotations.js';
+import type { DebugCapture, DebugRequestExtras, LastModelRequest } from '#src/core/debugCapture.js';
 import { BaseMessage } from '@langchain/core/messages';
 import { RunnableConfig } from '@langchain/core/runnables';
 import { BaseToolkit, StructuredToolInterface } from '@langchain/core/tools';
 import { IterableReadableStream } from '@langchain/core/utils/stream';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { type RefusalInfo } from '#src/core/refusal.js';
 /**
  * Shared, graph-agnostic agent plumbing.
  *
- * Both the lean {@link GthLangChainAgent} (`createAgent`, in core) and the deep
- * `GthDeepAgent` (`createDeepAgent`, in `@gaunt-sloth/agent`) differ only in how they
- * build the compiled LangGraph in {@link init}; everything downstream — invoking,
+ * A backend differs from another only in how it builds the compiled LangGraph in {@link init} —
+ * today that is the lean {@link GthLangChainAgent} (`createAgent`, in core); everything downstream — invoking,
  * streaming to the console, emitting typed {@link AgentStreamEvent}s, client-tool
  * `interrupt()` stubbing, suspend/resume, and cleanup — is identical and lives here.
  *
- * The base operates solely on the structural {@link GthCompiledGraph} surface, so it
- * does NOT import `langchain`/`deepagents` graph builders. Subclasses construct the
- * graph and assign it to {@link agent} in their `init()`.
+ * The base operates solely on the structural {@link GthCompiledGraph} surface, so it does NOT
+ * import a graph builder. Subclasses construct the graph and assign it to {@link agent} in their
+ * `init()`.
  */
 export declare abstract class GthAbstractAgent implements GthAgentInterface {
     protected statusUpdate: StatusUpdateCallback;
@@ -24,6 +27,42 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
     protected agent: GthCompiledGraph | null;
     protected config: GthConfig | null;
     protected command: GthCommand | undefined;
+    /**
+     * GS2-95 — the name of the command the USER typed, as the run header should say it. Set from
+     * {@link GthAgentInitOptions#displayCommand} by the backend's `init`, and read by exactly one
+     * thing: {@link compactHeaderStatus}.
+     *
+     * Separate from {@link command} because that field is not a label — it selects the mode prompt,
+     * the approvals posture and the command-specific filesystem config. Naming the header off it is
+     * why `gth eval` used to open with `ask`, and moving it to fix the header would silently change
+     * which system prompt those runs execute under. Left `undefined` by every command whose init verb
+     * IS its name, which is most of them.
+     */
+    protected displayCommand: string | undefined;
+    /**
+     * Opt-in debug sink for the TUI `/debug` panel. Set AFTER {@link init} via
+     * `runner.getAgent()`; read lazily inside each backend's `wrapModelCall` capture middleware
+     * so that when it is `undefined` (the normal path) the middleware is a transparent
+     * pass-through. Lives on the base so every backend supports it; the AG-UI server / non-TUI
+     * callers simply never set it, so those contracts are unchanged.
+     */
+    debugCapture: DebugCapture | undefined;
+    /**
+     * GS2-56 — the ALWAYS-ON snapshot of the most recent model request (extras + the as-sent,
+     * post-summarization messages), populated UNCONDITIONALLY at each backend's `wrapModelCall` feed
+     * site — NOT gated on {@link debugCapture} being attached. This is what lets `/debug-dump` render
+     * the full model input even when the TUI `/debug` panel was never opened and on non-TUI surfaces
+     * (the sink only ever fed the live `/debug` panel). O(1): a single overwritten reference retaining
+     * only the LAST call — no accumulation, so the "pay nothing until you need it" intent is kept.
+     */
+    lastModelRequest: LastModelRequest | undefined;
+    /**
+     * GS2-56 — stash the last model request (the as-sent messages + {@link DebugRequestExtras}).
+     * Called unconditionally from each backend's capture middleware, independent of the debug sink,
+     * so the snapshot is available to `/debug-dump` on every surface. Overwrites (retains only the
+     * most recent call). Callers already guard the invocation; kept trivial so it can never throw.
+     */
+    protected setLastModelRequest(messages: BaseMessage[], extras?: DebugRequestExtras): void;
     /**
      * GS2-16 — per-run analytics tally (token usage + invoked tool names) folded from the messages
      * flowing through {@link invoke} / the streaming paths. Reset at each turn boundary via
@@ -31,7 +70,115 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      * fully fail-soft (accumulation is guarded and never throws into a run).
      */
     private runStatsAcc;
+    /**
+     * EXT-58 — the names of the tools registered with the graph at the last {@link init}, recorded by
+     * {@link registerApprovalsAwareTools}. Read by `GthAgentRunner` to build the rater's
+     * granted-built-in list (§4.4), so a suggestion can only ever name a tool the model actually has.
+     */
+    private registeredToolNames;
+    /**
+     * EXT-70 §4.7.1 — what the connected MCP servers DECLARED about their own tools, captured from
+     * the same registration hook as {@link registeredToolNames} and keyed by the registered tool
+     * name. Read by `GthAgentRunner` as the `mcp` half of a `DeclaredToolAnnotationLookup`.
+     *
+     * It is a record of claims, never of decisions: no trust is applied here (that is
+     * `createEffectiveToolAnnotationSource`'s only job), and an absent tool yields the fail-closed
+     * defaults rather than "declared nothing".
+     */
+    private declaredMcpToolAnnotations;
     constructor(statusUpdate: StatusUpdateCallback, resolvers?: AgentResolvers);
+    /**
+     * GS2-101 — the run-header rung in force. An unset `output.header` resolves to `compact`: a run
+     * that was never configured opens with one attribution line and nothing else, and the technical
+     * preamble is opt-in via `output.header: 'debug'`.
+     *
+     * Defaulted HERE rather than in `DEFAULT_CONFIG` (the convention `injectModelContext` and
+     * `debugDump.redact` also follow) so the effective-config snapshot `gth config` prints does not
+     * grow a key nobody set.
+     */
+    protected get headerRung(): GthOutputHeaderRung;
+    /**
+     * GS2-93 — emit one line of the technical run-header preamble (the Workdir/Model/Tools/Middleware
+     * block). Only the `debug` rung shows it; `compact` replaces the whole block with
+     * {@link compactHeaderStatus}'s single line and `none` shows nothing. A non-`debug` rung only ever
+     * reaches here in non-TUI text modes: the interactive TUI forces `debug` before init (see
+     * `createTuiSession`), and the TUI event path never goes through the interrupt-hint site, so the
+     * whole preamble stays visible there. Only INFO header lines route through this — real model/tool
+     * output, warnings and errors keep using {@link statusUpdate} directly.
+     */
+    protected headerStatus(message: string): void;
+    /**
+     * GS2-93 — the `compact` rung's whole output: one line naming the command and the model that
+     * served it, in place of the preamble. Called once from the backend's `init`, after the command
+     * and effective config are in place. The string is {@link runHeaderLine}'s, shared with the review
+     * document's opening line so the two writers cannot drift.
+     *
+     * **This renders; it does not decide.** The word after the product name is
+     * {@link displayCommand} when the command supplied one and the init verb otherwise — GS2-93
+     * forbids a label table inside the agent, because naming a user-facing line is the command's call,
+     * not the runtime's.
+     *
+     * Two runs deliberately emit nothing here:
+     *
+     * - **`review` and `pr`** already open with `reviewHeadingBlock`, which renders this same line.
+     *   Emitting here as well would print the header twice on one screen.
+     * - **A run with no name at all** — the `pr` command's discovery sub-agent is the one such
+     *   caller, and it runs inside a `pr` whose header is already on screen. The name is what this
+     *   line is for, so with none there is nothing to say; inventing a word for it would be naming a
+     *   user-facing surface from inside the agent.
+     *
+     * The model half is the shared {@link modelProviderLabel} spelling (DL-6), and it is dropped
+     * rather than faked when nothing resolves (DL-7), leaving the command on its own.
+     */
+    protected compactHeaderStatus(): void;
+    /**
+     * EXT-58 (spec §4.5) — the ONE tool-registration hook both backends call with their final tool
+     * array, just before handing it to the graph builder. It does two things:
+     *
+     * 1. Appends the rung's approval sentence to every tool that is **not** auto-approved at that
+     *    rung, and leaves every granted tool's description untouched (the absence of the sentence is
+     *    what marks a tool free). See {@link applyRungAwareToolDescriptions}.
+     * 2. Records the registered tool names for {@link getRegisteredToolNames}, which feeds the
+     *    rater's granted-alternative list (§4.4).
+     * 3. EXT-70 §4.7.1 — records what the MCP servers declared about their own tools, for
+     *    {@link getDeclaredMcpToolAnnotations}. This is the ONE place a `tools/list` annotation
+     *    enters the approvals stack, and it enters as a claim: nothing here decides whether it is
+     *    believed.
+     *
+     * `gatedTools` MUST be the **LIVE gated set for the rung in force** — `resolveGatedToolNames` for
+     * that rung — and NOT the set the caller wires into the approval interrupt. The two are different
+     * on purpose: the interrupt is installed once, at agent init, and is deliberately
+     * rung-independent (`resolveInterruptToolNames`, the union over every rung) so that
+     * `/approvals <mode>` can move the mode underneath it for the rest of the session. Passing that
+     * wider set here would describe tools as needing approval that the live mode does not gate — and
+     * a call the live mode does not gate is auto-approved the moment it reaches the runner, so the
+     * sentence would be a promise nothing keeps.
+     *
+     * What keeps a description from promising an approval the gate will not ask for is therefore that
+     * both this and `GthAgentRunner`'s own check are projections of the SAME rule,
+     * `isToolGatedAtRung`, evaluated against the SAME live mode — §4.5's "a description that disagrees
+     * with what the gate will actually do is worse than no description at all".
+     *
+     * `additionalToolNames` covers tools the graph builder registers itself and that therefore never
+     * appear in `tools`. Their descriptions are not ours to write, so they cannot be suffixed here;
+     * they are recorded only so the rater's suggestion list reflects what the model actually has.
+     */
+    protected registerApprovalsAwareTools<T extends DescribableTool>(tools: T[], options: {
+        rung: ApprovalRung;
+        gatedTools: readonly string[];
+        additionalToolNames?: readonly string[];
+    }): T[];
+    /**
+     * EXT-58 — the tool names registered with the graph at the last {@link init} (empty before it).
+     * The runner intersects these with the built-in summaries table to build the rater's
+     * granted-alternative list, so the rater can never name a tool this session does not have.
+     */
+    getRegisteredToolNames(): string[];
+    /**
+     * EXT-70 §4.7.1 — what the MCP servers declared for their tools at the last {@link init}, keyed
+     * by registered tool name (empty before it, and on a session with no MCP servers).
+     */
+    getDeclaredMcpToolAnnotations(): ReadonlyMap<string, DeclaredToolAnnotations>;
     /**
      * GS2-16 — clear the per-run analytics tally so the next turn starts from zero. The runner
      * calls this at each turn boundary because it (and this agent) are reused across turns in an
@@ -50,10 +197,18 @@ export declare abstract class GthAbstractAgent implements GthAgentInterface {
      */
     private getStateMessageCount;
     /**
-     * Build the underlying compiled graph and assign it to {@link agent}. This is the only
-     * part that differs between the lean and deep agents.
+     * Build the underlying compiled graph and assign it to {@link agent}. This is the part a
+     * backend implements; everything else on the base is shared.
+     */
+    abstract init(command: GthCommand | undefined, configIn: GthConfig, checkpointer?: BaseCheckpointSaver | undefined, options?: GthAgentInitOptions): Promise<void>;
+    /**
+     * EXT-37 — surface a detected content-policy refusal: emit the clear, user-facing explanation at
+     * WARNING level (an empty-content refusal streams nothing, so without this the console shows
+     * nothing) and return the same message so it becomes the turn's terminal answer. Shared by the
+     * non-streaming {@link invoke} and streaming {@link streamFromInput} paths so both render a
+     * refusal identically. A refusal is a *successful* (if declined) response — never a retry.
      */
-    abstract init(command: GthCommand | undefined, configIn: GthConfig, checkpointer?: BaseCheckpointSaver | undefined): Promise<void>;
+    protected surfaceRefusal(info: RefusalInfo): string;
     /**
      * Invoke LLM with a message and runnable config.
      * For streaming use {@link #stream} method, streaming is preferred if model API supports it.