types

Canonical message/tool types.

AgentContext #

Per-call payload handed to a provider's :complete.

Fields for AgentContext type contract

Field	Type	Required	Summary
:max-tokens #	number	yes	Maximum output token budget requested for the provider call.
:messages #	[Message]	yes	Canonical conversation history to convert into provider wire format.
:system-prompt #	string|nil		Fully rendered system prompt for the current step, or nil when omitted.
:tools #	[Tool]	yes	Provider-visible tool specs available for this step.

AgentTool #

Tool extended with execution metadata for the agent loop. Registered through (api.register :tool ...).

Fields for AgentTool type contract

Field	Type	Required	Summary
:description #	string	yes	Provider-facing description included in the tool schema.
:execute #	(args ?yield-fn) -> AgentToolResult	yes	Runtime callback that executes the tool with decoded arguments.
:label #	string		UI label.
:name #	string	yes	Registry name used to merge and dispatch the tool.
:parameters #	JSONSchema	yes	Provider-facing argument schema used for validation and prompting.

AgentToolResult #

Outcome of a tool execution.

Fields for AgentToolResult type contract

Field	Type	Required	Summary
:content #	[TextContent]	yes	Text content returned to the provider as the tool observation.
:details #	any		Opaque presenter payload (UI-only).
:is-error? #	boolean	yes	True when the tool observation represents a failed call.

AssistantMessage #

Single model response. Content is always an array, even when empty.

Fields for AssistantMessage type contract

Field	Type	Required	Summary
:api #	keyword		:openai-completions | :openai-responses | :anthropic-messages | :openai-codex
:content #	[TextContent|ThinkingContent|ToolCall]	yes	Ordered assistant output blocks, including visible text, reasoning, and tool calls.
:error-message #	string		Present only when stop-reason = :error.
:model #	string		Provider model identifier that produced this response.
:provider #	keyword		Registered provider :name (e.g. :openai, :anthropic).
:role #	:assistant	yes	Message role discriminator for model-authored turns.
:stop-reason #	StopReason		Normalized reason the provider stopped generation.
:timestamp #	number	yes	Milliseconds since epoch when the assistant message was recorded.
:usage #	Usage		Optional token accounting returned by the provider for this response.

Message #

Union of UserMessage, AssistantMessage, ToolResultMessage. Stored on agent.messages and passed to providers in AgentContext.messages.

Members for Message type contract

Member	Kind	Summary
UserMessage #	variant	UserMessage is a Message union variant.
AssistantMessage #	variant	AssistantMessage is a Message union variant.
ToolResultMessage #	variant	ToolResultMessage is a Message union variant.

StopReason #

Why the assistant stopped producing output.

Members for StopReason type contract

Member	Kind	Summary
:stop #	enum	:stop is a StopReason enum value.
:length #	enum	:length is a StopReason enum value.
:tool-use #	enum	:tool-use is a StopReason enum value.
:error #	enum	:error is a StopReason enum value.
:aborted #	enum	:aborted is a StopReason enum value.

TextContent #

Plain visible text block.

Fields for TextContent type contract

Field	Type	Required	Summary
:text #	string	yes	Visible UTF-8 text payload.
:type #	:text	yes	Content-block discriminator for visible text.

ThinkingContent #

Reasoning/extended-thinking block. Surfaces both Anthropic extended thinking and OpenAI reasoning items.

Fields for ThinkingContent type contract

Field	Type	Required	Summary
:redacted? #	boolean		True when the provider redacted visible text.
:thinking #	string	yes	Reasoning or extended-thinking text emitted by the provider.
:thinking-signature #	string		Opaque echo signature; required for multi-turn extended thinking.
:type #	:thinking	yes	Content-block discriminator for provider reasoning text.

Tool #

Provider-agnostic tool spec — what providers see in AgentContext.tools.

Fields for Tool type contract

Field	Type	Required	Summary
:description #	string	yes	Provider-visible explanation of when and how to call the tool.
:name #	string	yes	Provider-visible tool name used in tool-call blocks.
:parameters #	JSONSchema	yes	{:type :object :properties {...} :required [...]}

ToolCall #

Assistant request to invoke a tool. Arguments are a parsed Lua table — providers JSON-decode wire arguments before constructing this block.

Fields for ToolCall type contract

Field	Type	Required	Summary
:arguments #	table	yes	Decoded argument table validated by the target tool implementation.
:id #	string	yes	Provider- or agent-generated id used to match the eventual tool result.
:name #	string	yes	Registered tool name to execute.
:type #	:tool-call	yes	Content-block discriminator for tool invocation requests.

ToolResultMessage #

Result of a single tool call, carried back to the provider on the next turn.

Fields for ToolResultMessage type contract

Field	Type	Required	Summary
:content #	[TextContent]	yes	Tool output blocks returned to the provider on the next turn.
:details #	any		Opaque presenter payload (UI-only).
:is-error? #	boolean	yes	True when the tool result should be treated as an error observation.
:role #	:tool-result	yes	Message role discriminator for tool execution results.
:timestamp #	number	yes	Milliseconds since epoch when the tool result was recorded.
:tool-call-id #	string	yes	Matches the originating ToolCall.id.
:tool-name #	string	yes	Tool name that produced the result, copied from the originating call.

Usage #

Token usage counters returned by the provider (best-effort — providers fill what they can).

Fields for Usage type contract

Field	Type	Required	Summary
:cache-read #	number		Provider cache-read tokens credited for the response.
:cache-write #	number		Provider cache-write tokens billed or recorded for the response.
:input #	number		Input or prompt tokens counted for the response.
:output #	number		Generated output tokens counted for the response.
:total-tokens #	number		Provider-reported total tokens, or the best available aggregate.

UserMessage #

Single user turn. Content is either a plain string or an array of TextContent blocks.

Fields for UserMessage type contract

Field	Type	Required	Summary
:content #	string|[TextContent]	yes	Visible user input as plain text or canonical text content blocks.
:role #	:user	yes	Message role discriminator for user-authored turns.
:timestamp #	number	yes	Milliseconds since epoch.