Package exports

@maniac-ai/agents

Classes

Maniac

Defined in: src/agents/app.ts:107

Constructors

Constructor

new Maniac(options?): Maniac

Defined in: src/agents/app.ts:210

Parameters

options?

agents?

Record<string, Agent> | Agent[]

model?

Model | null

policy?

PermissionPolicy | null

memory?

Memory | null

budget?

{ max_iterations: number; max_tokens?: number | null; max_cost_usd?: number | null; max_wall_seconds?: number | null; } | null

observationalMemory?

{ model: unknown; reflection_model?: unknown; message_chars: number; observation_chars: number; buffer_fraction: number; activation_fraction: number; block_after: number; activate_after_idle?: number | null; activate_on_provider_change: boolean; enable_reflection: boolean; reflection_buffer_activation: number; reflection_block_after: number; scope: "thread" | "resource"; chars_per_token: number; keep_recent_messages: number; estimator?: unknown; } | null

workingMemory?

{ model: unknown; template: string; scope: "thread" | "resource"; update_after_every_turn: boolean; max_chars: number; enable_update_tool: boolean; note_section: string; } | null

memoryRelevanceFilter?

{ model: unknown; min_chars_to_filter: number; filter_observations: boolean; filter_working_memory: boolean; keep_when_empty: boolean; instructions?: string | null; } | null

Configuration for the query-conditioned memory relevance filter. See Maniac.memoryRelevanceFilter.

memoryRelevanceFilterRunner?

MemoryRelevanceFilter | null

Optional pre-built MemoryRelevanceFilter. When omitted and memoryRelevanceFilter is set, one is auto- constructed. Pass null to opt out.

backgroundTasks?

BackgroundTasksConfig | null

See Maniac.backgroundTasks.

tracerFactory?

TracerFactory

conversationStore?

ConversationStore | null

Optional pre-built ConversationStore. When omitted, one is constructed from memory (if present). Required by chat / chatStream.

observationBuffer?

ObservationBuffer | null

Optional pre-built ObservationBuffer. When omitted and both memory and observationalMemory are provided, one is constructed automatically using the (auto-built) conversation + observation stores. Pass null to opt out even when config is supplied.

workingMemoryRunner?

WorkingMemoryRunner | null

Optional pre-built WorkingMemoryRunner. When omitted and both memory and workingMemory are provided, one is constructed automatically. Pass null to opt out.

checkpointStore?

RunCheckpointStore | null

Optional pre-built RunCheckpointStore. When omitted and memory is supplied, one is auto-constructed so Maniac.resumeCheckpoint works out of the box. Pass null to opt out even when memory is set.

persistPartialOnError?

boolean

See Maniac.persistPartialOnError.

Returns

Maniac

Properties

model?

optional model?: Model | null

Defined in: src/agents/app.ts:109

policy?

optional policy?: PermissionPolicy | null

Defined in: src/agents/app.ts:110

memory?

optional memory?: Memory | null

Defined in: src/agents/app.ts:111

budget?

optional budget?: { max_iterations: number; max_tokens?: number | null; max_cost_usd?: number | null; max_wall_seconds?: number | null; } | null

Defined in: src/agents/app.ts:112

observationalMemory?

optional observationalMemory?: { model: unknown; reflection_model?: unknown; message_chars: number; observation_chars: number; buffer_fraction: number; activation_fraction: number; block_after: number; activate_after_idle?: number | null; activate_on_provider_change: boolean; enable_reflection: boolean; reflection_buffer_activation: number; reflection_block_after: number; scope: "thread" | "resource"; chars_per_token: number; keep_recent_messages: number; estimator?: unknown; } | null

Defined in: src/agents/app.ts:113

Union Members

Type Literal

{ model: unknown; reflection_model?: unknown; message_chars: number; observation_chars: number; buffer_fraction: number; activation_fraction: number; block_after: number; activate_after_idle?: number | null; activate_on_provider_change: boolean; enable_reflection: boolean; reflection_buffer_activation: number; reflection_block_after: number; scope: "thread" | "resource"; chars_per_token: number; keep_recent_messages: number; estimator?: unknown; }

model

model: unknown

reflection_model?

optional reflection_model?: unknown

message_chars

message_chars: number

observation_chars

observation_chars: number

buffer_fraction

buffer_fraction: number

activation_fraction

activation_fraction: number

block_after

block_after: number

activate_after_idle?

optional activate_after_idle?: number | null

activate_on_provider_change

activate_on_provider_change: boolean

enable_reflection

enable_reflection: boolean

reflection_buffer_activation

reflection_buffer_activation: number

reflection_block_after

reflection_block_after: number

scope

scope: "thread" | "resource"

Storage scope for observations and reflections. "thread" (default) keeps the per-thread namespaces; "resource" is the Mastra-style cross-thread mode that persists under agent:<id>/resources/<rid>/observations and splices the union of every thread's observations for the same resource into the prefix. Per-thread last_observed_index accounting still runs under the per-thread state namespace either way. Pass resourceId on app.chat(...) to populate the namespace; runs without a resource id fall back to thread-scope behaviour even when the config opts in.

chars_per_token

chars_per_token: number

keep_recent_messages

keep_recent_messages: number

estimator?

optional estimator?: unknown

Optional TokenEstimator consulted by ObservationBuffer when computing per-message size. Typed as unknown to mirror the Python schema's Any field; the buffer feature-detects via typeof value.estimate === "function".

null

workingMemory?

optional workingMemory?: { model: unknown; template: string; scope: "thread" | "resource"; update_after_every_turn: boolean; max_chars: number; enable_update_tool: boolean; note_section: string; } | null

Defined in: src/agents/app.ts:114

Union Members

Type Literal

{ model: unknown; template: string; scope: "thread" | "resource"; update_after_every_turn: boolean; max_chars: number; enable_update_tool: boolean; note_section: string; }

model

model: unknown

Background Model (or provider/slug string resolved by the inference router) used by the updater. Cheap / fast models are appropriate; this runs on every chat boundary and never serves the user directly.

template

template: string

Markdown template the LM uses as the structural skeleton for the working-memory doc. Empty string means "no template" -- the LM produces a free-form doc.

scope

scope: "thread" | "resource"

"resource" (default) pools the doc across every thread for the same resourceId passed on app.chat(...). "thread" keeps a per-thread doc, useful for ephemeral session-only profiles.

update_after_every_turn

update_after_every_turn: boolean

When true (the default) the runner schedules a background update LM call after every chat turn. Set to false for hand- managed docs that the application updates directly via WorkingMemoryStore.save (or proactively via the remember(note) built-in tool).

max_chars

max_chars: number

Soft cap on the working-memory doc size, enforced by the updater prompt. Defaults to 4000 characters.

enable_update_tool

enable_update_tool: boolean

When true (the default) and this config is wired into a Maniac app, the built-in remember(note) tool is auto- injected into every agent so the agent can proactively persist user-flagged facts mid-turn (for example when the user says "please remember to always cite your sources"). Set false for hand-managed docs that only the reflective post-turn updater (or direct WorkingMemoryStore.save calls) should touch.

note_section

note_section: string

Markdown section header under which remember(note) appends new bullets. The tool creates the section as a ## <note_section> heading on the first call if it doesn't already exist in the doc.

null

memoryRelevanceFilterConfig?

optional memoryRelevanceFilterConfig?: { model: unknown; min_chars_to_filter: number; filter_observations: boolean; filter_working_memory: boolean; keep_when_empty: boolean; instructions?: string | null; } | null

Defined in: src/agents/app.ts:127

Optional configuration for the query-conditioned memory relevance filter. When set, a small LM pass runs ahead of every chat turn that carries a non-trivial memory prefix; the pass takes the new user message plus the spliced observation / reflection / working- memory blocks and rewrites the prefix to keep only the blocks relevant to the query. The raw conversation history tail is never filtered. Wired as a flag-style config (no agentAsTool ergonomics required); fail-open on LM errors.

Mirrors Python Maniac(memory_relevance_filter=...).

Union Members

Type Literal

{ model: unknown; min_chars_to_filter: number; filter_observations: boolean; filter_working_memory: boolean; keep_when_empty: boolean; instructions?: string | null; }

model

model: unknown

Background Model (or provider/slug string resolved via the inference router) used to score relevance. Cheap / fast models are the right choice: the filter runs on every chat turn that carries a non-trivial memory prefix and never serves the user directly. Required.

min_chars_to_filter

min_chars_to_filter: number

Skip the filter entirely when the candidate memory prefix is smaller than this many characters. Short prefixes are cheap to ship verbatim and the extra LM round-trip costs more than the savings. Set to 0 to filter unconditionally.

filter_observations

filter_observations: boolean

When true (the default) the filter considers active observation and reflection blocks as filterable candidates. Set false to leave the observation tier intact.

filter_working_memory

filter_working_memory: boolean

When true (the default) the filter splits the working-memory doc on ## markdown headers and considers each section as a filterable candidate. Set false to leave the doc intact.

keep_when_empty

keep_when_empty: boolean

Behaviour when the LM votes to drop every candidate. When true (the default) the original unfiltered prefix is preserved -- the filter assumes a wholesale-drop verdict is more often a parsing glitch than a true "nothing here matters" signal. Set false to trust the LM and ship a memory-free prefix.

instructions?

optional instructions?: string | null

Optional override of the system prompt used by the filter LM. The default prompt asks the model to keep blocks that are directly relevant or that carry persistent facts (user identity, preferences, standing instructions).

null

backgroundTasks?

optional backgroundTasks?: BackgroundTasksConfig | null

Defined in: src/agents/app.ts:137

App-level background-task scheduler config. When set with enabled: true, an internal BackgroundTaskDispatcher is constructed lazily on first use and exposed via Maniac.dispatcher; Maniac.runUntilIdle / Maniac.runStreamUntilIdle drive the dispatcher.

Mirrors Python Maniac(background_tasks=...).

tracerFactory

tracerFactory: TracerFactory

Defined in: src/agents/app.ts:138

conversationStore

readonly conversationStore: ConversationStore | null

Defined in: src/agents/app.ts:147

Conversation store used by chat/chatStream. Auto-built from memory when neither explicitly provided. May be null when the app has no memory -- in that case the chat APIs throw.

observationStore

readonly observationStore: ObservationStore | null

Defined in: src/agents/app.ts:153

Observation store backing the optional observationBuffer. Always present when both memory and observationalMemory were supplied; otherwise null.

observationBuffer

readonly observationBuffer: ObservationBuffer | null

Defined in: src/agents/app.ts:159

Background observational-memory orchestrator. Auto-built when both memory and observationalMemory are supplied. Owned by this app: call aclose on shutdown to drain pending background tasks.

workingMemoryStore

readonly workingMemoryStore: WorkingMemoryStore | null

Defined in: src/agents/app.ts:165

Working-memory store for the singleton mutable doc the agent carries across turns. Always present when memory and workingMemory are both supplied; otherwise null.

checkpointStore

readonly checkpointStore: RunCheckpointStore | null

Defined in: src/agents/app.ts:173

Tier 3 #14: optional persistent checkpoint store. Auto-built from memory when neither explicitly provided so Maniac.resumeCheckpoint works out of the box. Pass null to opt out even when memory is set; pass a pre-built instance to share a store across multiple Maniac apps.

workingMemoryRunner

readonly workingMemoryRunner: WorkingMemoryRunner | null

Defined in: src/agents/app.ts:179

Background working-memory updater. Auto-built when memory and workingMemory are both supplied. Owned by this app: call aclose on shutdown to drain the pending updater.

memoryRelevanceFilter

readonly memoryRelevanceFilter: MemoryRelevanceFilter | null

Defined in: src/agents/app.ts:186

Query-conditioned memory relevance filter. Auto-built when memoryRelevanceFilter is supplied. The filter is fail-open (it logs and returns the input unchanged on any error) so wiring it in is safe even when the filter LM is flaky.

persistPartialOnError

readonly persistPartialOnError: boolean

Defined in: src/agents/app.ts:208

When true (the default), Maniac.chat / Maniac.chatStream persist the partial transcript to the configured ConversationStore for runs that finished with status='errored' or were aborted mid-turn by a thrown RunInterruptedError (LM provider crash, sub-agent throw, etc.) or RunCancelledError (cooperative cancel via the caller-supplied AbortSignal). The persisted turn is sealed so any unanswered tool_call.id from the last assistant message gets a synthetic {ok: false, error: "tool call interrupted before completion"} observation, keeping the next request well-formed for native tool-calling providers. Set to false to restore the v0.2 behaviour where errored / interrupted runs were silently dropped from the thread.

Reflectors (ObservationBuffer.afterTurn, WorkingMemoryRunner.afterTurn) always stay gated on status='completed' -- they summarize a finished exchange and would record inaccurate notes against a partial.

Accessors

dispatcher

Get Signature

get dispatcher(): BackgroundTaskDispatcher | null

Defined in: src/agents/app.ts:1079

Lazily-constructed background-task scheduler bound to Maniac.backgroundTasks. Returns null when no backgroundTasks config was supplied to the constructor.

Mirrors Python Maniac.background_task_manager.

Returns

BackgroundTaskDispatcher | null

Methods

register()

register(spec): void

Defined in: src/agents/app.ts:389

Parameters

spec

Agent

Returns

void

agent()

agent(spec): Agent

Defined in: src/agents/app.ts:396

Parameters

spec

Omit<Agent, "model"> & object

Returns

Agent

get()

get(agentId): Agent

Defined in: src/agents/app.ts:409

Parameters

agentId

string

Returns

Agent

run()

run<T>(agentId, query, options?): Promise<AgentResult<T>>

Defined in: src/agents/app.ts:417

Type Parameters

T

T = string

Parameters

agentId

string

query

string

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

Promise<AgentResult<T>>

runStream()

runStream<T>(agentId, query, options?): AsyncGenerator<StreamEnvelope<T>, void, undefined>

Defined in: src/agents/app.ts:429

Type Parameters

T

T = string

Parameters

agentId

string

query

string

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

AsyncGenerator<StreamEnvelope<T>, void, undefined>

chat()

chat<T>(agentId, message, options): Promise<AgentResult<T>>

Defined in: src/agents/app.ts:461

Thread-aware chat entry point. Mirrors Python Maniac.chat.

Runs one agent turn while owning the conversation thread:

1. Loads the spliced prefix via ObservationBuffer.loadThread (or ConversationStore.loadThread when no buffer is configured).
2. Binds a ChatTurnContext so runReplAgent can inject an observations proxy into REPL cells.
3. Runs the agent through runAgent.
4. Persists the new turn (user message + every newly-generated message) via ConversationStore.saveTurn.
5. Calls ObservationBuffer.afterTurn to advance state and schedule background observer/reflector tasks.

options.threadId is required; it scopes every memory namespace. Throws when the app has no conversationStore (which requires memory to have been supplied to the constructor).

Type Parameters

T

T = string

Parameters

agentId

string

message

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[]

options

ChatOptions

Returns

Promise<AgentResult<T>>

chatStream()

chatStream<T>(agentId, message, options): AsyncGenerator<StreamEnvelope<T>, void, undefined>

Defined in: src/agents/app.ts:616

Streaming twin of chat. Yields the same StreamEnvelope sequence as runAgentStream (every trace event followed by a terminal { type: "result" } envelope). Conversation persistence and afterTurn run after the terminal envelope is produced, matching Python Maniac.chat_stream.

Type Parameters

T

T = string

Parameters

agentId

string

message

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[]

options

ChatOptions

Returns

AsyncGenerator<StreamEnvelope<T>, void, undefined>

resume()

resume<T>(agentId, checkpoint, responses, options?): Promise<AgentResult<T>>

Defined in: src/agents/app.ts:823

Type Parameters

T

T = string

Parameters

agentId

string

checkpoint

schema_version

1 | 2 = ...

spec_id

string = ...

iteration

number = ...

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

root_messages

object[] = ...

subagent_sessions

object[] = ...

pending

object[] = ...

checkpoint_id?

string | null = ...

responses

object[]

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

Promise<AgentResult<T>>

resumeStream()

resumeStream<T>(agentId, checkpoint, responses, options?): AsyncGenerator<StreamEnvelope<T>, void, undefined>

Defined in: src/agents/app.ts:857

Streaming twin of Maniac.resume. Yields StreamEnvelopes for every trace event of the resumed run followed by the terminal { type: "result" } envelope. When the resumed run completes and threadId is set, afterTurn runs once after the terminal envelope, matching resume.

Type Parameters

T

T = string

Parameters

agentId

string

checkpoint

schema_version

1 | 2 = ...

spec_id

string = ...

iteration

number = ...

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

root_messages

object[] = ...

subagent_sessions

object[] = ...

pending

object[] = ...

checkpoint_id?

string | null = ...

responses

object[]

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

AsyncGenerator<StreamEnvelope<T>, void, undefined>

resumeCheckpoint()

resumeCheckpoint<T>(agentId, checkpointId, responses, options?): Promise<AgentResult<T>>

Defined in: src/agents/app.ts:908

Tier 3 #14: resume a paused run via its durable checkpoint id.

Looks the checkpoint up in either the agent or thread namespace (when threadId is supplied), hands the rehydrated payload to Maniac.resume, and marks the stored record as resolved when the run completes successfully. Throws when no checkpointStore is configured (pass memory or an explicit checkpointStore to the constructor).

Idempotency: each resume goes through a compare-and-swap RunCheckpointStore.claim that transitions the record from pending → resolving before the run starts. A second concurrent call (or a retry after the first one completes) sees the record in resolving / resolved and throws CheckpointNotPendingError instead of re-executing the approved tool. Callers (e.g. the channels webhook handler) should treat that error as "someone else already handled this" and surface a no-op response.

Type Parameters

T

T = string

Parameters

agentId

string

checkpointId

string

responses

object[]

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

Promise<AgentResult<T>>

resumeCheckpointStream()

resumeCheckpointStream<T>(agentId, checkpointId, responses, options?): AsyncGenerator<StreamEnvelope<T>, void, undefined>

Defined in: src/agents/app.ts:946

Streaming twin of Maniac.resumeCheckpoint. Yields the same StreamEnvelope sequence as resumeStream, including the new { type: "paused" } variant before any terminal { type: "result", result.status === "paused" } if the resume re-pauses. Same compare-and-swap claim semantics as resumeCheckpoint: throws CheckpointNotPendingError (before yielding any envelopes) when the record is not pending.

Type Parameters

T

T = string

Parameters

agentId

string

checkpointId

string

responses

object[]

options?

Omit<RunOptions, "tracer"> & object = {}

Returns

AsyncGenerator<StreamEnvelope<T>, void, undefined>

listPendingCheckpoints()

listPendingCheckpoints(agentId, options?): Promise<StoredCheckpoint[]>

Defined in: src/agents/app.ts:998

List unresolved checkpoints for an agent (and optional thread). Convenience over RunCheckpointStore.listPending.

Parameters

agentId

string

options?

threadId?

string | null

maxRecords?

number

Returns

Promise<StoredCheckpoint[]>

enqueueBackground()

enqueueBackground(agentId, prompt, options?): object

Defined in: src/agents/app.ts:1094

Enqueue a background agent run. Returns the queued task record synchronously; the run begins as soon as a slot is free under the dispatcher's concurrency caps.

Throws when no backgroundTasks config was supplied or the config has enabled: false.

Parameters

agentId

string

prompt

string

options?

Omit<BackgroundTaskInput, "spec" | "prompt"> = {}

Returns

object

id

id: string

task_id

task_id: string

agent_id

agent_id: string

thread_id

thread_id: string

tool_call_id

tool_call_id: string

tool_name

tool_name: string

toolset?

optional toolset?: string | null

args

args: JsonDict

status

status: "queued" | "running" | "completed" | "failed" | "cancelled"

enqueued_at

enqueued_at: string

started_at?

optional started_at?: string | null

finished_at?

optional finished_at?: string | null

ack_value?

optional ack_value?: unknown

result?

optional result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null

Union Members

Type Literal

{ ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; }

ok

ok: boolean

value?

optional value?: unknown

error?

optional error?: string | null

metadata

metadata: Record<string, unknown>

cause?

optional cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null

Optional structured cause for failed results. Populated by the tool() helper (and any adapter that wants to preserve thrown error context), so consumers can distinguish validation vs. runtime failures and read the original error name/stack without the public ok: false discriminator changing shape.

null

retries

retries: number

error?

optional error?: string | null

runUntilIdle()

runUntilIdle(agentId?, prompt?, options?): Promise<void>

Defined in: src/agents/app.ts:1118

Block until every background task already enqueued has terminated. When agentId and prompt are supplied, also enqueues a fresh task before draining (mirrors Python Maniac.run_until_idle(agent_id, query)).

Parameters

agentId?

string

prompt?

string

options?

Omit<BackgroundTaskInput, "spec" | "prompt"> = {}

Returns

Promise<void>

runStreamUntilIdle()

runStreamUntilIdle(agentId?, prompt?, options?): AsyncGenerator<BackgroundStreamItem, void, undefined>

Defined in: src/agents/app.ts:1141

Streaming twin of runUntilIdle. Yields a tagged BackgroundStreamItem for every event emitted by every in-flight background task and for every terminal record. Returns when the dispatcher is idle.

Parameters

agentId?

string

prompt?

string

options?

Omit<BackgroundTaskInput, "spec" | "prompt"> = {}

Returns

AsyncGenerator<BackgroundStreamItem, void, undefined>

aclose()

aclose(): Promise<void>

Defined in: src/agents/app.ts:1164

Drain pending background observational-memory tasks (and the background-task dispatcher, if one was constructed) and refuse new ones. Idempotent. Long-lived programs should call this on shutdown to avoid losing in-flight work.

Returns

Promise<void>

CheckpointNotPendingError

Defined in: src/agents/app.ts:1337

Thrown by Maniac.resumeCheckpoint / Maniac.resumeCheckpointStream when the targeted checkpoint is not in the pending state (typically because a sibling resume has already taken the claim or because the run already finished). Callers — most notably the channels webhook handler — should treat this as "the request was a duplicate" and surface a no-op response instead of failing the HTTP call.

Extends

• Error

Constructors

Constructor

new CheckpointNotPendingError(checkpointId, status): CheckpointNotPendingError

Defined in: src/agents/app.ts:1340

Parameters

checkpointId

string

status

CheckpointStatus

Returns

CheckpointNotPendingError

Overrides

Error.constructor

Properties

checkpointId

readonly checkpointId: string

Defined in: src/agents/app.ts:1338

status

readonly status: CheckpointStatus

Defined in: src/agents/app.ts:1339

stackTraceLimit

static stackTraceLimit: number

Defined in: node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

cause?

optional cause?: unknown

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Error.cause

name

name: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from

Error.name

message

message: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

stack?

optional stack?: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters

err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

BackgroundTaskDispatcher

Defined in: src/agents/backgroundTasks.ts:133

Schedules background agent runs with concurrency caps + lifecycle hooks. See module docstring for the full contract.

Constructors

Constructor

new BackgroundTaskDispatcher(options): BackgroundTaskDispatcher

Defined in: src/agents/backgroundTasks.ts:149

Parameters

options

DispatcherOptions

Returns

BackgroundTaskDispatcher

Accessors

config

Get Signature

get config(): BackgroundTasksConfig

Defined in: src/agents/backgroundTasks.ts:161

Returns

BackgroundTasksConfig

closed

Get Signature

get closed(): boolean

Defined in: src/agents/backgroundTasks.ts:165

Returns

boolean

store

Get Signature

get store(): BackgroundTaskStore | null

Defined in: src/agents/backgroundTasks.ts:169

Returns

BackgroundTaskStore | null

errors

Get Signature

get errors(): readonly Error[]

Defined in: src/agents/backgroundTasks.ts:174

Hooks / dispatch errors observed during the lifetime of this dispatcher.

Returns

readonly Error[]

Methods

pendingCount()

pendingCount(agentId?): number

Defined in: src/agents/backgroundTasks.ts:182

Number of in-flight tasks. With no args, counts globally; with agentId, narrows to that agent's pending count.

Parameters

agentId?

string

Returns

number

enqueue()

enqueue(input): object

Defined in: src/agents/backgroundTasks.ts:198

Enqueue a background agent run. Returns the queued task record synchronously. The actual run begins as soon as a slot is free under the dispatcher's concurrency caps.

Throws when the dispatcher is closed or the configured backpressure policy is reject and the queue is saturated.

Parameters

input

BackgroundTaskInput

Returns

object

id

id: string

task_id

task_id: string

agent_id

agent_id: string

thread_id

thread_id: string

tool_call_id

tool_call_id: string

tool_name

tool_name: string

toolset?

optional toolset?: string | null

args

args: JsonDict

status

status: "queued" | "running" | "completed" | "failed" | "cancelled"

enqueued_at

enqueued_at: string

started_at?

optional started_at?: string | null

finished_at?

optional finished_at?: string | null

ack_value?

optional ack_value?: unknown

result?

optional result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null

Union Members

Type Literal

{ ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; }

ok

ok: boolean

value?

optional value?: unknown

error?

optional error?: string | null

metadata

metadata: Record<string, unknown>

cause?

optional cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null

Optional structured cause for failed results. Populated by the tool() helper (and any adapter that wants to preserve thrown error context), so consumers can distinguish validation vs. runtime failures and read the original error name/stack without the public ok: false discriminator changing shape.

null

retries

retries: number

error?

optional error?: string | null

awaitTask()

awaitTask(taskId, timeoutMs?): Promise<{ id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; }>

Defined in: src/agents/backgroundTasks.ts:288

Wait for a single task to terminate. Returns the terminal record (completed / failed / cancelled). Throws when no task with the given id is known.

timeoutMs (default default_wait_timeout_s from the config) caps the wait; on timeout the in-flight controller is NOT aborted and the most recent record is returned.

Parameters

taskId

string

timeoutMs?

number

Returns

Promise<{ id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; }>

awaitTasks()

awaitTasks(taskIds, options?): Promise<Map<string, { id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; } | null>>

Defined in: src/agents/backgroundTasks.ts:335

Wait on several tasks at once.

mode === "all" blocks until every listed task terminates (or the overall timeoutMs lapses). mode === "any" returns as soon as the first listed task terminates; other tasks keep running.

Returns a Map<taskId, BackgroundTaskRecord | null> keyed by every id passed in. A record's status reflects the latest known state, so an un-finished task at timeout shows up with its in-flight status (queued or running). The in-flight tasks are NOT aborted on timeout — matching awaitTask.

Throws when any id is unknown (neither in-flight nor in the buffered completions). The Python sibling is BackgroundAgentRunDispatcher.await_tasks.

Parameters

taskIds

string[]

options?

mode?

"any" | "all"

timeoutMs?

number

Returns

Promise<Map<string, { id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; } | null>>

cancelTask()

cancelTask(taskId, reason?): boolean

Defined in: src/agents/backgroundTasks.ts:426

Cancel the task with the given id. Returns true if a cancel signal was delivered; false if the task already terminated or is unknown.

Parameters

taskId

string

reason?

unknown

Returns

boolean

listPending()

listPending(): object[]

Defined in: src/agents/backgroundTasks.ts:435

Snapshot of currently in-flight task records.

Returns

object[]

taskEvents()

taskEvents(taskId, lastN?): ({ ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "token"; payload: {[key: string]: unknown; model?: string; scope?: string; iteration?: number; toolset?: string | null; lm_span_id?: string | null; usage_delta?: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } | null; finish_reason?: string | null; raw_finish_reason?: string | null; }; delta: string; chunk_kind?: "text" | "reasoning" | "json_partial" | "object_partial" | "tool_call_partial" | "control" | null; content_part_kind?: "file" | "text" | "image" | null; partial_object?: JsonDict | null; tool_call_delta?: { index: number; id?: string | null; name?: string | null; arguments_partial: string; } | null; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "lm_call_start"; payload: {[key: string]: unknown; model: string; scope: string; iteration: number; toolset?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "lm_call"; payload: {[key: string]: unknown; model: string; scope: string; iteration: number; usage: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; }; finish_reason: string; toolset?: string | null; raw_finish_reason?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "tool"; payload: {[key: string]: unknown; tool_call_id: string; tool_name: string; toolset?: string | null; phase: "completed" | "failed" | "cancelled" | "started"; args?: JsonDict; result?: JsonDict | null; result_preview?: {[key: string]: unknown; ok?: boolean; value?: unknown; error?: string | null; metadata?: JsonDict | null; result_truncated?: boolean; value_omitted_reason?: string | null; } | null; ok?: boolean | null; allowed?: boolean | null; error?: string | null; reason?: string | null; started_at?: string | null; finished_at?: string | null; elapsed_ms?: number | null; decision?: {[key: string]: unknown; allowed: boolean; requires_approval: boolean; matched_rule_id?: string | null; reason?: string | null; } | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "tool_call_arguments_delta"; payload: {[key: string]: unknown; tool_call_id?: string | null; tool_name?: string | null; index: number; arguments_delta: string; sequence: number; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "cell"; payload: {[key: string]: unknown; cell_id: string; phase: "completed" | "failed" | "cancelled" | "started"; code?: string | null; result?: JsonDict | null; error?: string | null; elapsed_ms?: number | null; stdout_len?: number | null; stderr_len?: number | null; variables?: string[] | null; src?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "subagent"; payload: {[key: string]: unknown; phase: "error" | "completed" | "intent" | "start" | "paused" | "errored"; agent_id?: string | null; toolset?: string | null; role?: string | null; prompt_summary?: string | null; prompt?: string | null; parent_span_id?: string | null; background?: boolean | null; iterations?: number | null; reason?: string | null; max_depth?: number | null; repl?: boolean | null; usage?: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "agent"; payload: {[key: string]: unknown; phase: "completed" | "started"; agent_id: string; principal?: string | null; iterations?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "approval"; payload: {[key: string]: unknown; phase: "requested" | "approved" | "denied" | "resolved"; id?: string; toolset?: string | null; tool?: string | null; rule_id?: string | null; reason?: string | null; source: "guardrail" | "policy"; decision?: "approve" | "deny" | null; approvals: object[]; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "memory"; payload: {[key: string]: unknown; op: string; phase?: string | null; principal?: string | null; depth?: number | null; summary?: string | null; namespace?: string | null; agent_id?: string | null; thread_id?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "guardrail"; payload: {[key: string]: unknown; phase: string; boundary?: string | null; action?: string | null; decision?: string | null; rule_id?: string | null; reason?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "background_task"; payload: {[key: string]: unknown; phase: string; task_id: string; status?: string | null; progress?: number | null; output?: JsonDict | null; agent_id?: string | null; sub_agent_id?: string | null; tool?: string | null; attempt?: number | null; error?: string | null; iterations?: number | null; timeout_ms?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "step"; payload: {[key: string]: unknown; phase: "before" | "after" | "repair" | "stopped" | "finalize_vetoed"; turn_index: number; iteration?: number | null; source?: string | null; reason?: string | null; elapsed_ms?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "retry"; payload: {[key: string]: unknown; attempt: number; reason: string; model?: string | null; max_attempts?: number | null; delay_s?: number | null; fallback?: boolean | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "final"; payload: {[key: string]: unknown; source: string; iterations?: number | null; validated?: boolean | null; error?: string | null; pending?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "error"; payload: {[key: string]: unknown; message: string; kind_of_error?: string | null; cause?: string | null; retryable?: boolean | null; reason?: string | null; detail?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "stream_gap"; payload: {[key: string]: unknown; dropped_count_so_far: number; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "plan"; payload: {[key: string]: unknown; entries: object[]; }; })[]

Defined in: src/agents/backgroundTasks.ts:449

Snapshot of the last lastN events from a task's dedicated tracer. Used by the built-in bg_check tool to surface recent activity from a running background subagent. Returns an empty array when the task id is unknown.

lastN is clamped to [1, 256] so a misbehaving caller can't pin unbounded memory by requesting the entire event log of a long-running task.

Parameters

taskId

string

lastN?

number = 5

Returns

nextCompletion()

nextCompletion(timeoutMs?): Promise<{ id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; } | null>

Defined in: src/agents/backgroundTasks.ts:465

Pop the next terminal task record. Mirrors Python BackgroundTaskManager.next_completion. Resolves immediately if a completion is already buffered; otherwise waits for the next one. timeoutMs returns null on lapse without delivering a record.

Parameters

timeoutMs?

number

Returns

Promise<{ id: string; task_id: string; agent_id: string; thread_id: string; tool_call_id: string; tool_name: string; toolset?: string | null; args: JsonDict; status: "queued" | "running" | "completed" | "failed" | "cancelled"; enqueued_at: string; started_at?: string | null; finished_at?: string | null; ack_value?: unknown; result?: { ok: boolean; value?: unknown; error?: string | null; metadata: Record<string, unknown>; cause?: { kind: "validation" | "runtime"; name?: string; message?: string; stack?: string | null; code?: string | null; metadata?: JsonDict; } | null; } | null; retries: number; error?: string | null; } | null>

runUntilIdle()

runUntilIdle(): Promise<void>

Defined in: src/agents/backgroundTasks.ts:500

Block until every currently-pending task has terminated. Tasks enqueued during the await are also included.

Mirrors Python BackgroundTaskManager.wait_idle. Safe to call multiple times.

Returns

Promise<void>

runStreamUntilIdle()

runStreamUntilIdle(): AsyncGenerator<BackgroundStreamItem, void, undefined>

Defined in: src/agents/backgroundTasks.ts:516

Stream every task's trace events through one merged tracer.

Yields a tagged BackgroundStreamItem for every event emitted by every in-flight task and for every terminal record. Returns when the dispatcher is idle.

Tasks enqueued during iteration are picked up automatically.

Returns

AsyncGenerator<BackgroundStreamItem, void, undefined>

subscribeStream()

subscribeStream(listener): () => void

Defined in: src/agents/backgroundTasks.ts:583

Subscribe to the merged stream of every task's events + terminal records for as long as the returned unsubscribe function is not called.

Unlike runStreamUntilIdle, this does NOT auto-complete when the dispatcher goes idle: the subscriber stays attached across idle gaps, so tasks enqueued later in the same logical batch (e.g. an orchestrator turn that spawns children one at a time) are delivered without the caller re-subscribing — and therefore without a busy-poll loop. The listener owns its own lifecycle: it keeps receiving items until it calls the returned unsubscribe function.

Delivery is push-based and synchronous from enqueue's event pipe and from task completion, so there is no polling latency. A throwing listener is captured on errors and the subscription stays live (mirrors runStreamUntilIdle).

On subscribe, the listener is seeded with a snapshot of every event already emitted by every in-flight task so a late subscriber does not miss the early progress of an already-running task.

Parameters

listener

(item) => void

Returns

() => void

aclose()

aclose(reason?): Promise<void>

Defined in: src/agents/backgroundTasks.ts:631

Cancel pending tasks and refuse new ones. Workers receive a cancellation reason via their AbortSignal and report a cancelled record. Use runUntilIdle when you want to wait for natural completion instead.

Idempotent.

Parameters

reason?

unknown

Returns

Promise<void>

LMSummarizingCompactor

Defined in: src/agents/compaction.ts:141

LM-summarizing transcript compactor.

The TypeScript port of Python's LMSummarizingCompactor (see agents/compaction.py). Where the Python class plugs into the step-hook protocol, this class exposes a single compact(messages) method so callers can drive compaction from a runner extension or an explicit pre-iteration hook of their choosing.

Behaviour mirrors Python:

• Preserves the system prompt (messages[0]) and the original user task (messages[1]) so the agent keeps its grounding.
• Preserves the trailing keepRecent messages so the agent has fresh local context for the next turn.
• Folds the middle of the transcript into a single replacement message (role: "user") prefixed with summaryHeader.
• Refuses to split an assistant→tool pair across the head/tail boundary by walking the tail boundary back over leading role: "tool" messages (see safeTailStart).
• On any summarization failure (provider error, empty response) the compactor returns the input transcript unchanged — a flaky summarizer must never corrupt the run.

Constructors

Constructor

new LMSummarizingCompactor(options): LMSummarizingCompactor

Defined in: src/agents/compaction.ts:149

Parameters

options

LMSummarizingCompactorOptions

Returns

LMSummarizingCompactor

Methods

compact()

compact(messages): Promise<object[]>

Defined in: src/agents/compaction.ts:169

Parameters

messages

readonly object[]

Returns

Promise<object[]>

BaseStepHook

Defined in: src/agents/hooks.ts:44

No-op base for StepHook. Subclasses override only the methods they need; the rest stay as pass-throughs. Mirrors Python agents.hooks.BaseStepHook.

Extended by

• CallableStepHook

Implements

• StepHook

Constructors

Constructor

new BaseStepHook(): BaseStepHook

Returns

BaseStepHook

Methods

beforeStep()

beforeStep(_ctx): Promise<StepDecision | null | undefined>

Defined in: src/agents/hooks.ts:45

Parameters

_ctx

StepContext

Returns

Promise<StepDecision | null | undefined>

Implementation of

StepHook.beforeStep

beforeFinalize()

beforeFinalize(_ctx, _resp): Promise<Continuation | null | undefined>

Defined in: src/agents/hooks.ts:49

Parameters

_ctx

StepContext

_resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

Returns

Promise<Continuation | null | undefined>

Implementation of

StepHook.beforeFinalize

shouldStop()

shouldStop(_ctx, _resp, _cell): Promise<boolean>

Defined in: src/agents/hooks.ts:56

Parameters

_ctx

StepContext

_resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

_cell

JsonDict | null

Returns

Promise<boolean>

Implementation of

StepHook.shouldStop

afterStep()

afterStep(_ctx, _resp, _cell): Promise<void>

Defined in: src/agents/hooks.ts:64

Parameters

_ctx

StepContext

_resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

_cell

JsonDict | null

Returns

Promise<void>

Implementation of

StepHook.afterStep

CallableStepHook

Defined in: src/agents/hooks.ts:83

Adapter wrapping prepare_step / stop_when constructor sugar into a real StepHook. Used by the runner's spec-normalization step to translate the flat-callable sugar form into a synthesized hook so the composition runners only deal with one shape. Either argument may be null/undefined, in which case the corresponding lifecycle method is a pass-through.

Mirrors Python agents.hooks._CallableStepHook.

Extends

• BaseStepHook

Constructors

Constructor

new CallableStepHook(options?): CallableStepHook

Defined in: src/agents/hooks.ts:87

Parameters

options?

prepare?

PrepareStep | null

stop?

StopWhen | null

Returns

CallableStepHook

Overrides

BaseStepHook.constructor

Methods

beforeFinalize()

beforeFinalize(_ctx, _resp): Promise<Continuation | null | undefined>

Defined in: src/agents/hooks.ts:49

Parameters

_ctx

StepContext

_resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

Returns

Promise<Continuation | null | undefined>

Inherited from

BaseStepHook.beforeFinalize

afterStep()

afterStep(_ctx, _resp, _cell): Promise<void>

Defined in: src/agents/hooks.ts:64

Parameters

_ctx

StepContext

_resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

_cell

JsonDict | null

Returns

Promise<void>

Inherited from

BaseStepHook.afterStep

beforeStep()

beforeStep(ctx): Promise<StepDecision | null | undefined>

Defined in: src/agents/hooks.ts:93

Parameters

ctx

StepContext

Returns

Promise<StepDecision | null | undefined>

Overrides

BaseStepHook.beforeStep

shouldStop()

shouldStop(ctx, resp, _cell): Promise<boolean>

Defined in: src/agents/hooks.ts:109

Parameters

ctx

StepContext

resp

content

string | ({ type: "text"; text: string; cache_control?: { type: "ephemeral"; } | null; } | { type: "image"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; cache_control?: { type: "ephemeral"; } | null; } | { type: "file"; source: { kind: "base64"; media_type: string; data: string; } | { kind: "url"; url: string; }; filename?: string | null; cache_control?: { type: "ephemeral"; } | null; })[] = ...

The model's response content. Mirrors MessageSchema.content's union shape: a plain string for text-only responses (the overwhelming majority today), or a ContentPart array when the adapter streamed multimodal deltas (image / file blocks). The runner forwards this onto the assistant message verbatim, so the shape that flows into messages mirrors what came back from the LM. Consumers that only care about the textual portion can call messageToText.

usage

{ prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } = ...

usage.prompt

number = ...

usage.completion

number = ...

usage.cost_usd?

number | null = ...

usage.cache_creation_input_tokens?

number | null = ...

usage.cache_read_input_tokens?

number | null = ...

finish_reason

"length" | "error" | "stop" = ...

tool_calls

object[] = ...

reasoning?

string | null = ...

_cell

JsonDict | null

Returns

Promise<boolean>

Overrides

BaseStepHook.shouldStop

MemoryRelevanceFilter

Defined in: src/agents/memoryFilter.ts:485

Owns the per-turn relevance filter for one Maniac instance.

Construct with a MemoryRelevanceFilterConfig and call filterPrefix once per chat turn after the prefix has been loaded from the conversation store / observation buffer / working- memory store.

Constructors

Constructor

new MemoryRelevanceFilter(options): MemoryRelevanceFilter

Defined in: src/agents/memoryFilter.ts:489

Parameters

options

MemoryRelevanceFilterOptions

Returns

MemoryRelevanceFilter

Properties

config

readonly config: object

Defined in: src/agents/memoryFilter.ts:486

model

model: unknown

Background Model (or provider/slug string resolved via the inference router) used to score relevance. Cheap / fast models are the right choice: the filter runs on every chat turn that carries a non-trivial memory prefix and never serves the user directly. Required.

min_chars_to_filter

min_chars_to_filter: number

Skip the filter entirely when the candidate memory prefix is smaller than this many characters. Short prefixes are cheap to ship verbatim and the extra LM round-trip costs more than the savings. Set to 0 to filter unconditionally.

filter_observations

filter_observations: boolean

When true (the default) the filter considers active observation and reflection blocks as filterable candidates. Set false to leave the observation tier intact.

filter_working_memory

filter_working_memory: boolean

When true (the default) the filter splits the working-memory doc on ## markdown headers and considers each section as a filterable candidate. Set false to leave the doc intact.

keep_when_empty

keep_when_empty: boolean

Behaviour when the LM votes to drop every candidate. When true (the default) the original unfiltered prefix is preserved -- the filter assumes a wholesale-drop verdict is more often a parsing glitch than a true "nothing here matters" signal. Set false to trust the LM and ship a memory-free prefix.

instructions?

optional instructions?: string | null

Optional override of the system prompt used by the filter LM. The default prompt asks the model to keep blocks that are directly relevant or that carry persistent facts (user identity, preferences, standing instructions).

Accessors

closed

Get Signature

get closed(): boolean

Defined in: src/agents/memoryFilter.ts:493

Returns

boolean

Methods

filterPrefix()

filterPrefix(query, prefix, options?): Promise<object[]>

Defined in: src/agents/memoryFilter.ts:515

Return a filtered copy of prefix for the new query.

Behaviour:

• When the prefix carries no filterable memory blocks at all, the input is returned verbatim (no LM call).
• Tiers the config opted out of filtering skip the candidate list entirely; their blocks survive intact.
• When the total candidate body is below minCharsToFilter the LM call is skipped and the input is returned verbatim.
• LM errors, parse errors, and empty responses surface as a memory_filter_error trace event and the unfiltered prefix is returned. The filter is fail-open.
• When the LM votes to keep every candidate the original prefix is returned verbatim (fast path).

Parameters

query

string

prefix