Schemas

Interfaces

StepContext

Snapshot of run state handed to hooks around a single iteration.

messages is the live list the runner is about to send to the LM (during beforeStep) or just sent (during shouldStop / afterStep). Hooks should treat it as read-only — to mutate, return a StepDecision with messages: ..., which the runner installs in place after the hook chain finishes.

lastResponse and lastCell reference the previous iteration's output (null on iteration 0). During shouldStop and afterStep, the in-flight resp and cell are passed alongside the context as explicit args.

Properties

iteration

iteration: number

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

messages

messages: object[]

Defined in: src/schemas/hooks.ts:57

role

role: "system" | "user" | "assistant" | "tool"

content

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; })[]

String form is preserved verbatim for back-compat; the ContentPart array form (Phase 3) lets producers attach images and files to any message and annotate individual parts with Anthropic-flavored cache_control. Consumers that only care about the textual portion can call messageToText to flatten either form to a string. See docs/concepts/multimodal-content-and-cache-control.md for the cross-language design.

name?

optional name?: string | null

tool_calls?

optional tool_calls?: object[] | null

tool_call_id?

optional tool_call_id?: string | null

usage

usage: object

Defined in: src/schemas/hooks.ts:58

prompt

prompt: number

completion

completion: number

cost_usd?

optional cost_usd?: number | null

cache_creation_input_tokens?

optional cache_creation_input_tokens?: number | null

cache_read_input_tokens?

optional cache_read_input_tokens?: number | null

elapsedS

elapsedS: number

Defined in: src/schemas/hooks.ts:59

lastResponse

lastResponse: {[key: string]: unknown; 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; })[]; usage: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; }; finish_reason: "length" | "error" | "stop"; tool_calls: object[]; reasoning?: string | null; } | null

Defined in: src/schemas/hooks.ts:60

Union Members

Type Literal

{[key: string]: unknown; 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; })[]; usage: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; }; finish_reason: "length" | "error" | "stop"; tool_calls: object[]; reasoning?: string | null; }

Index Signature

[key: string]: unknown

content

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

usage: object

usage.prompt

prompt: number

usage.completion

completion: number

usage.cost_usd?

optional cost_usd?: number | null

usage.cache_creation_input_tokens?

optional cache_creation_input_tokens?: number | null

usage.cache_read_input_tokens?

optional cache_read_input_tokens?: number | null

finish_reason

finish_reason: "length" | "error" | "stop"

tool_calls

tool_calls: object[]

reasoning?

optional reasoning?: string | null

null

lastCell

lastCell: JsonDict | null

Defined in: src/schemas/hooks.ts:69

Optional cell that was produced on the previous iteration. The TypeScript runner doesn't currently surface a typed Cell counterpart to the Python schemas.execution.Cell, so this is left as a free-form JSON dict for forward-compat. null means "no cell" — i.e. the iteration before this one didn't run a REPL cell, or this is the first iteration.

specId

specId: string

Defined in: src/schemas/hooks.ts:70

principal

principal: string

Defined in: src/schemas/hooks.ts:71

StepDecision

Defined in: src/schemas/hooks.ts:90

Outcome of a beforeStep hook. All-undefined means "no change".

request: when set, replaces the InferenceRequest the runner was about to send. Use this to override temperature, max_tokens, stop, or to fully replace the message list.

messages: shorthand for "rewrite the message history but leave everything else on the request alone". When both request and messages are set, request.messages wins.

stop: short-circuit the run. The runner emits final with source: "prepare_step" and AgentResult.final = final ?? lastResponse.content ?? "(stopped by hook)". reason flows into the trace event payload for observability.

Properties

request?

optional request?: { messages: object[]; response_format: "text" | "json"; max_tokens?: number | null; temperature?: number | null; top_p?: number | null; top_k?: number | null; frequency_penalty?: number | null; presence_penalty?: number | null; seed?: number | null; logit_bias?: Record<string, number> | null; stop: string[]; tools: object[]; tool_choice: { kind: "named"; name: string; } | "auto" | "required" | "none"; parallel_tool_calls?: boolean | null; user?: string | null; reasoning?: { effort?: "minimal" | "low" | "medium" | "high" | null; max_tokens?: number | null; summary?: "auto" | "concise" | "detailed" | null; } | null; } | null

Defined in: src/schemas/hooks.ts:91

Union Members

Type Literal

{ messages: object[]; response_format: "text" | "json"; max_tokens?: number | null; temperature?: number | null; top_p?: number | null; top_k?: number | null; frequency_penalty?: number | null; presence_penalty?: number | null; seed?: number | null; logit_bias?: Record<string, number> | null; stop: string[]; tools: object[]; tool_choice: { kind: "named"; name: string; } | "auto" | "required" | "none"; parallel_tool_calls?: boolean | null; user?: string | null; reasoning?: { effort?: "minimal" | "low" | "medium" | "high" | null; max_tokens?: number | null; summary?: "auto" | "concise" | "detailed" | null; } | null; }

messages

messages: object[]

response_format

response_format: "text" | "json"

max_tokens?

optional max_tokens?: number | null

temperature?

optional temperature?: number | null

top_p?

optional top_p?: number | null

Nucleus-sampling cutoff. Forwarded verbatim as top_p by every OpenAI-compatible adapter and as top_p by Anthropic. null/omitted (the default) leaves the field off so the provider default applies. Setting both temperature and top_p is allowed by the wire formats but most providers recommend tuning only one.

top_k?

optional top_k?: number | null

Top-k sampling cutoff. Native on Anthropic (top_k) and most OpenAI-compatible open-model gateways (OpenRouter, llama.cpp, mlx, vLLM, ...). Not part of vanilla OpenAI Chat Completions — sending it to api.openai.com is rejected server-side, mirroring the existing reasoning_effort contract (forwarded verbatim; unsupported endpoints surface the rejection). null/omitted leaves it off.

frequency_penalty?

optional frequency_penalty?: number | null

OpenAI frequency_penalty (typically -2.0..2.0). Forwarded by OpenAI-compatible adapters and LiteLLM; Anthropic has no equivalent and silently ignores it. null/omitted leaves it off.

presence_penalty?

optional presence_penalty?: number | null

OpenAI presence_penalty (typically -2.0..2.0). Forwarded by OpenAI-compatible adapters and LiteLLM; Anthropic has no equivalent and silently ignores it. null/omitted leaves it off.

seed?

optional seed?: number | null

Best-effort deterministic-sampling seed. Forwarded as seed by OpenAI-compatible adapters and LiteLLM (providers treat it as a hint, not a hard guarantee); Anthropic has no equivalent and silently ignores it. null/omitted leaves it off.

logit_bias?

optional logit_bias?: Record<string, number> | null

Per-token logit bias map (token-id string -> bias, typically -100..100). Forwarded as logit_bias by OpenAI-compatible adapters and LiteLLM; Anthropic has no equivalent and silently ignores it. null/omitted leaves it off.

stop

stop: string[]

tools

tools: object[]

tool_choice

tool_choice: { kind: "named"; name: string; } | "auto" | "required" | "none"

parallel_tool_calls?

optional parallel_tool_calls?: boolean | null

Whether the provider may emit multiple tool calls in a single turn. OpenAI-compatible adapters forward it as parallel_tool_calls (only when tools is non-empty, the provider's own constraint). Anthropic expresses the inverse via tool_choice.disable_parallel_tool_use: a value of false is translated to disable_parallel_tool_use: true; true/null leave Anthropic's default (parallel allowed) untouched. null/omitted leaves it off for OpenAI-compatible providers.

user?

optional user?: string | null

Opaque stable end-user identifier for provider-side abuse monitoring. OpenAI-compatible adapters forward it as user; Anthropic maps it to metadata.user_id. null/omitted leaves it off.

reasoning?

optional reasoning?: { effort?: "minimal" | "low" | "medium" | "high" | null; max_tokens?: number | null; summary?: "auto" | "concise" | "detailed" | null; } | null

Optional reasoning configuration. See ReasoningConfigSchema. null/omitted means "use the provider default" -- exactly the pre-Phase-4 behavior, so adapters can ignore this field unmodified when callers don't set it.

Union Members

Type Literal

{ effort?: "minimal" | "low" | "medium" | "high" | null; max_tokens?: number | null; summary?: "auto" | "concise" | "detailed" | null; }

effort?

optional effort?: "minimal" | "low" | "medium" | "high" | null

max_tokens?

optional max_tokens?: number | null

Hard cap on the reasoning token budget. When set:

Anthropic adapter forwards it as thinking.budget_tokens.
OpenAI-compatible adapter ignores it (chat completions has no per-call budget knob beyond max_completion_tokens); callers wanting a hard cap on OpenAI should set InferenceRequest.max_tokens.

summary?

optional summary?: "auto" | "concise" | "detailed" | null

OpenAI Responses-style summary verbosity. Recognized by adapters that hit the Responses API; ignored by chat-completions adapters.

null

messages?

optional messages?: object[] | null

Defined in: src/schemas/hooks.ts:92

stop?

optional stop?: boolean

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

final?

optional final?: string | null

Defined in: src/schemas/hooks.ts:94

reason?

optional reason?: string | null

Defined in: src/schemas/hooks.ts:95

Continuation

Defined in: src/schemas/hooks.ts:111

Outcome of a beforeFinalize hook that vetoes termination.

Returning a Continuation from beforeFinalize tells the runner: "the model emitted a tool-call-less response that would terminate the run, but the task isn't really done yet — append this nudge as a user message and iterate again." The runner counts the rejected turn as a real iteration so the budget eventually wins.

userMessage is the body the runner appends as role: "user". reason is recorded on the trace event so a post-mortem can attribute the veto to the right hook without parsing message text.

Properties

userMessage

userMessage: string

Defined in: src/schemas/hooks.ts:112

reason?

optional reason?: string | null

Defined in: src/schemas/hooks.ts:113

StepHook

Defined in: src/schemas/hooks.ts:124

Four-method observer/transformer around one root iteration.

Implementations may extend BaseStepHook (re-exported from @maniac-ai/agents) to inherit no-op defaults and override only the methods they care about. Direct implementers must define all four methods.

Methods

beforeStep()

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

Defined in: src/schemas/hooks.ts:125

Parameters

ctx

StepContext

Returns

Promise<StepDecision | null | undefined>

beforeFinalize()

beforeFinalize(ctx, resp): Promise<Continuation | null | undefined>

Defined in: src/schemas/hooks.ts:126

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; })[] = ...

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>

shouldStop()

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

Defined in: src/schemas/hooks.ts:130

Parameters

ctx

StepContext

resp

content

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>

afterStep()

afterStep(ctx, resp, cell): Promise<void>

Defined in: src/schemas/hooks.ts:135

Parameters

ctx

StepContext

resp

content

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>

Type Aliases

PrepareStep

PrepareStep = (ctx) => StepDecision | null | undefined | Promise<StepDecision | null | undefined>

Defined in: src/schemas/hooks.ts:147

Sugar form of beforeStep. Sync or async; returning null / undefined is the no-op. Agent({ prepare_step: ... }) wraps a callable into a synthesized StepHook.