GthDeepAgent

Defined in: _worktrees/docs-release/gaunt-sloth/packages/agent/src/core/GthDeepAgent.ts:146

Deep agent: builds a createDeepAgent graph (deepagents). All run/stream/event plumbing lives in GthAbstractAgent; this class only knows how to construct the graph in init.

Differences from the lean GthLangChainAgent:

deepagents provides the filesystem tools (read_file/write_file/edit_file/ ls/glob/grep/execute) via its own middleware, backed by a FilesystemBackend. gsloth’s .aiignore + filesystem config are mapped onto deepagents permissions (see buildPermissions). Any resolved tool that reuses a deepagents filesystem-tool name is therefore superseded and dropped (createDeepAgent would otherwise throw on the collision). EXT-14: the FilesystemBackend itself is wrapped with guardFilesystemBackend before it reaches createDeepAgent, adding a realpath (symlink-resolved) containment check the permission globs alone can’t provide.
todos / subagents / summarization come from deepagents’ standard middleware.

The transport-agnostic param assembly lives in buildDeepAgentParams so the ACP entry (deepagents-acp) can reuse the exact same tool resolution, permission mapping and middleware hardening without re-running createDeepAgent locally.

Extends

GthAbstractAgent

Constructors

Constructor

new GthDeepAgent(statusUpdate, resolvers?): GthDeepAgent

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:95

Parameters

statusUpdate

StatusUpdateCallback

resolvers?

AgentResolvers

Returns

GthDeepAgent

Inherited from

GthAbstractAgent.constructor

Properties

agent

protected agent: GthCompiledGraph | null

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:45

Inherited from

GthAbstractAgent.agent

command

protected command: GthCommand | undefined

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:47

Inherited from

GthAbstractAgent.command

config

protected config: GthConfig | null

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:46

Inherited from

GthAbstractAgent.config

debugCapture

debugCapture: DebugCapture | undefined

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:55

Opt-in debug sink for the TUI /debug panel. Set AFTER 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 BOTH the lean and deep backends support it; the AG-UI server / non-TUI callers simply never set it, so those contracts are unchanged.

Inherited from

GthAbstractAgent.debugCapture

lastModelRequest

lastModelRequest: LastModelRequest | undefined

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:64

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 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.

Inherited from

GthAbstractAgent.lastModelRequest

resolvers

protected resolvers: AgentResolvers | undefined

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:44

Inherited from

GthAbstractAgent.resolvers

statusUpdate

protected statusUpdate: StatusUpdateCallback

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:43

Inherited from

GthAbstractAgent.statusUpdate

Methods

buildDeepAgentParams()

buildDeepAgentParams(command, configIn): Promise<GthDeepAgentParams>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/agent/src/core/GthDeepAgent.ts:401

Assemble the transport-agnostic GthDeepAgentParams: resolve tools (with the filesystem disabled so deepagents owns fs access), apply the allowedTools allow-list and the deepagents fs-name supersession safety-net, map .aiignore + filesystem mode onto deepagents permissions, and build the fs-denial-softening middleware. Shared by the local runner (init) and the deepagents-acp ACP entry.

Parameters

command

GthCommand | undefined

configIn

GthConfig

Returns

Promise<GthDeepAgentParams>

cleanup()

cleanup(): Promise<void>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:231

Returns

Promise<void>

Inherited from

GthAbstractAgent.cleanup

extractAndFlattenTools()

protected extractAndFlattenTools(tools): StructuredToolInterface<ToolInputSchemaBase, any, any>[]

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:238

Extract and flatten tools from toolkits, applying client-tool interrupt() stubbing. A tool with metadata.client === true has its body swapped for an interrupt() call so the run suspends and the client fulfils it (the C-a AG-UI bridge depends on this).

Parameters

tools

(StructuredToolInterface<ToolInputSchemaBase, any, any> | BaseToolkit | ServerTool)[]

Returns

StructuredToolInterface<ToolInputSchemaBase, any, any>[]

Inherited from

GthAbstractAgent.extractAndFlattenTools

getDeclaredMcpToolAnnotations()

getDeclaredMcpToolAnnotations(): ReadonlyMap<string, DeclaredToolAnnotations>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:145

EXT-70 §4.7.1 — what the MCP servers declared for their tools at the last init, keyed by registered tool name (empty before it, and on a session with no MCP servers).

Returns

ReadonlyMap<string, DeclaredToolAnnotations>

Inherited from

GthAbstractAgent.getDeclaredMcpToolAnnotations

getEffectiveConfig()

getEffectiveConfig(config, command): GthConfig

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:232

Parameters

config

GthConfig

command

GthCommand | undefined

Returns

GthConfig

Inherited from

GthAbstractAgent.getEffectiveConfig

getPendingToolInterrupts()

getPendingToolInterrupts(runConfig): Promise<PendingToolInterrupt[]>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:229

Inspect the checkpointed state for the thread and return the tool calls currently pending human approval (empty array when the run finished normally). A LangGraph humanInTheLoopMiddleware interrupt parks one HITLRequest per suspended super-step in state.tasks[].interrupts[].value.actionRequests (each { name, args }); this flattens those into PendingToolInterrupts. Defensive throughout — a graph without getState, or any unexpected shape, yields [] rather than throwing, so a missing HITL setup degrades to “no approval needed” instead of breaking the run.

Parameters

runConfig

RunnableConfig

Returns

Promise<PendingToolInterrupt[]>

Inherited from

GthAbstractAgent.getPendingToolInterrupts

getRegisteredToolNames()

getRegisteredToolNames(): string[]

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:140

EXT-58 — the tool names registered with the graph at the last 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.

Returns

string[]

Inherited from

GthAbstractAgent.getRegisteredToolNames

getRunStats()

getRunStats(): GthRunStats

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:153

GS2-16 — the analytics harvested since the last resetRunStats. Never throws.

Returns

GthRunStats

Inherited from

GthAbstractAgent.getRunStats

headerStatus()

protected headerStatus(message): void

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:104

GS2-63 — emit one line of the technical run-header preamble (the Workdir/Model/Tools/Middleware block) UNLESS it is opted out via output.header: false. The opt-out only ever reaches here in non-TUI text modes: the interactive TUI forces output.header on 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 statusUpdate directly.

Parameters

message

string

Returns

void

Inherited from

GthAbstractAgent.headerStatus

init()

init(command, configIn, checkpointer?): Promise<void>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/agent/src/core/GthDeepAgent.ts:150

Build the underlying compiled graph and assign it to agent. This is the only part that differs between the lean and deep agents.

Parameters

command

GthCommand | undefined

configIn

GthConfig

checkpointer?

BaseCheckpointSaver<number>

Returns

Promise<void>

Overrides

GthAbstractAgent.init

invoke()

invoke(messages, runConfig): Promise<string>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:182

Invoke LLM with a message and runnable config. For streaming use #stream method, streaming is preferred if model API supports it. Please note that this when tools are involved, this method will anyway do multiple LLM calls within LangChain dependency.

Parameters

messages

Message[]

runConfig

RunnableConfig

Returns

Promise<string>

Inherited from

GthAbstractAgent.invoke

processEventStream()

protected processEventStream(stream): AsyncGenerator<AgentStreamEvent>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:230

Parameters

stream

IterableReadableStream<[BaseMessage<MessageStructure<MessageToolSet>, MessageType>, Record<string, unknown>]>

Returns

AsyncGenerator<AgentStreamEvent>

Inherited from

GthAbstractAgent.processEventStream

recordRunStats()

protected recordRunStats(message): void

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:155

GS2-16 — fold one message (or chunk) into the run tally. Fully guarded (fail-soft).

Parameters

message

unknown

Returns

void

Inherited from

GthAbstractAgent.recordRunStats

registerApprovalsAwareTools()

protected registerApprovalsAwareTools<T>(tools, options): T[]

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:130

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:

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 applyRungAwareToolDescriptions.
Records the registered tool names for getRegisteredToolNames, which feeds the rater’s granted-alternative list (§4.4).
EXT-70 §4.7.1 — records what the MCP servers declared about their own tools, for 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 same set the caller wires into the approval interrupt (humanInTheLoopMiddleware‘s interruptOn on lean, deepagents’ interruptOn on deep). That shared parameter is what makes it impossible for a description to promise an approval the gate will not ask for — §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 — deepagents’ own filesystem tools on the deep backend. Their descriptions are deepagents’, not ours, so they cannot be suffixed here; they are recorded only so the rater’s suggestion list reflects what the deep model actually has.

Type Parameters

T

T extends DescribableTool

Parameters

tools

T[]

options

additionalToolNames?

readonly string[]

gatedTools

readonly string[]

rung

"write" | "read-only" | "auto-safe" | "full-auto" | "bypass"

Returns

T[]

Inherited from

GthAbstractAgent.registerApprovalsAwareTools

resetRunStats()

resetRunStats(): void

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:151

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 interactive session.

Returns

void

Inherited from

GthAbstractAgent.resetRunStats

setLastModelRequest()

protected setLastModelRequest(messages, extras?): void

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:71

GS2-56 — stash the last model request (the as-sent messages + 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.

Parameters

messages

BaseMessage<MessageStructure<MessageToolSet>, MessageType>[]

extras?

DebugRequestExtras

Returns

void

Inherited from

GthAbstractAgent.setLastModelRequest

stream()

stream(messages, runConfig): Promise<IterableReadableStream<string>>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:187

Induce LLM to stream AI messages with a user message and runnable config. When stream is not appropriate use invoke.

Parameters

messages

Message[]

runConfig

RunnableConfig

Returns

Promise<IterableReadableStream<string>>

Inherited from

GthAbstractAgent.stream

streamResume()

streamResume(resumeValue, runConfig): Promise<IterableReadableStream<string>>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:194

Resume a graph suspended on a human-in-the-loop interrupt() and stream the continuation as text. Identical plumbing to stream (Esc-to-interrupt, binary handling), except the graph input is a Command({ resume }) instead of fresh messages — so the suspended tool-approval interrupt is answered and the run continues on the same thread.

Parameters

resumeValue

unknown

runConfig

RunnableConfig

Returns

Promise<IterableReadableStream<string>>

Inherited from

GthAbstractAgent.streamResume

streamWithEvents()

streamWithEvents(messages, runConfig, signal?): AsyncGenerator<AgentStreamEvent>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:210

Stream agent events as typed AgentStreamEvent objects. Yields text deltas, tool call lifecycle events, and tool results.

If a tool with metadata.client === true triggers interrupt(), the underlying graph throws GraphInterrupt; this generator catches it and ends cleanly so the caller’s transport (e.g. AG-UI SSE) can finish the run with the tool call hanging. Resume the suspended graph via streamWithEventsResume on the same thread id.

Parameters

messages

Message[]

runConfig

RunnableConfig

signal?

AbortSignal

Returns

AsyncGenerator<AgentStreamEvent>

Inherited from

GthAbstractAgent.streamWithEvents

streamWithEventsResume()

streamWithEventsResume(resumeValue, runConfig, queuedMessages?, signal?): AsyncGenerator<AgentStreamEvent>

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:219

Resume a graph that was suspended via interrupt() with the supplied value.

The runnable config must carry the same thread_id used when the graph was suspended (the checkpointer keys state by thread). The resume value is whatever the suspending tool needs back — for frontend-fulfilled tools this is the value the client sends in forwardedProps.command.resume.

Parameters

resumeValue

unknown

runConfig

RunnableConfig

queuedMessages?

BaseMessage<MessageStructure<MessageToolSet>, MessageType>[]

signal?

AbortSignal

Returns

AsyncGenerator<AgentStreamEvent>

Inherited from

GthAbstractAgent.streamWithEventsResume

surfaceRefusal()

protected surfaceRefusal(info): string

Defined in: _worktrees/docs-release/gaunt-sloth/packages/core/dist/core/GthAbstractAgent.d.ts:175

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 invoke and streaming streamFromInput paths so both render a refusal identically. A refusal is a successful (if declined) response — never a retry.

Parameters

info

RefusalInfo

Returns

string

Inherited from

GthAbstractAgent.surfaceRefusal