Chat & Context - Zero Runtime

ChatContext

Create a ChatContext, optionally seeded with messages. Also exposes ChatContext.empty(), ChatContext.fromContextMessages(...), and ChatContext.fromDict(...).

Constructor

new ChatContext(initialMessages?: ChatMessage[])

initialMessages

ChatMessage[]

addAttributedMessage

addAttributedMessage(role: ChatRole, content: string, agentId: string, messageId?: string, images?: ImageContent[]): ChatMessage

Like ChatContext.addMessage but tags the message with an authoring agentId.

role

ChatRole

required

content

string

required

agentId

string

required

messageId

string

images

ImageContent[]

returns

ChatMessage

addFunctionCall

addFunctionCall(name: string, args: string, callId?: string, messageId?: string, agentId?: string): ChatMessage

Record an assistant tool call as an ASSISTANT message carrying a FunctionCall.

name

string

required

args

string

required

callId

string

messageId

string

agentId

string

returns

ChatMessage

addFunctionOutput

addFunctionOutput(name: string, output: string, callId: string, isError?: boolean, messageId?: string, agentId?: string): ChatMessage

Record a tool result as a TOOL-role message linked to its callId.

name

string

required

output

string

required

callId

string

required

isError

boolean

messageId

string

agentId

string

returns

ChatMessage

addHandoff

addHandoff(toAgent: string, fromAgent?: string, reason?: string): AgentHandoff

Record a handoff to another agent and return it.

toAgent

string

required

fromAgent

string

reason

string

returns

AgentHandoff

addMessage

addMessage(role: ChatRole, content: string, messageId?: string, images?: ImageContent[], createdAt?: number | null, replace?: boolean): ChatMessage

Append a message and return it. Generates a messageId if none is given. With replace=true and role=SYSTEM, replaces the existing system message in place instead of appending a duplicate.

role

ChatRole

required

content

string

required

messageId

string

images

ImageContent[]

createdAt

number | null

replace

boolean

returns

ChatMessage

copy

copy(opts?: { excludeSystemMessages?: boolean; excludeEmptyMessages?: boolean }): ChatContext

Return a deep, independent copy of this context.

opts

{ excludeSystemMessages?: boolean; excludeEmptyMessages?: boolean }

returns

ChatContext

estimatedTokens

estimatedTokens(): number

Rough token estimate (~2 tokens per word).

returns

number

handoffs

handoffs(): AgentHandoff[]

Return a copy of the recorded handoffs.

returns

AgentHandoff[]

lastHandoff

lastHandoff(): AgentHandoff | null

The most recent handoff, or null if none.

returns

AgentHandoff | null

merge

merge(other: ChatContext | ChatMessage[]): ChatContext

Append another context’s messages in place, de-duped by messageId; returns this context.

other

ChatContext | ChatMessage[]

required

returns

ChatContext

messages

messages(): ChatMessage[]

Return a shallow copy of the messages.

returns

ChatMessage[]

toAnthropicMessages

toAnthropicMessages(): { messages: Array<Record<string, any>>; system: string | null }

Render as Anthropic Messages. The system text is returned separately in system (Anthropic takes it as a top-level field, not as a message).

returns

{ messages: Array<Record<string, any>>; system: string | null }

toContextMessages

toContextMessages(): ContextMessageProto[]

Serialize the conversation context for sending to Zero Runtime.

returns

ContextMessageProto[]

toDict

toDict(): { items: ContextMessageProto[]; handoffs: Array<Record<string, string>> }

Serialize the whole context (messages + handoffs) to a plain object.

returns

{ items: ContextMessageProto[]; handoffs: Array<Record<string, string>> }

toGoogleContents

toGoogleContents(): { contents: Array<Record<string, any>>; systemInstruction: string | null }

Render as Google Gemini contents, with the system text returned in systemInstruction.

returns

{ contents: Array<Record<string, any>>; systemInstruction: string | null }

toOpenaiMessages

toOpenaiMessages(opts?: { reasoningModel?: boolean }): Array<Record<string, any>>

Export to OpenAI chat messages (text, image parts, tool calls, tool results).

opts

{ reasoningModel?: boolean }

returns

Array<Record<string, any>>

truncate

truncate(opts?: { maxItems?: number; maxTokens?: number }): ChatContext

Return a new context trimmed to the most recent messages.

opts

{ maxItems?: number; maxTokens?: number }

returns

ChatContext

turnCount

turnCount(): number

Number of user turns in the context.

returns

number

ChatMessage

Create a ChatMessage.

Constructor

new ChatMessage(opts: ChatMessageOptions)

role

ChatRole

Author role. Defaults to ChatRole.USER.

content

string

Message text. Defaults to ''.

messageId

string

Stable message id. Defaults to ''.

toolCalls

FunctionCall[]

Tool calls requested in this message. Defaults to [].

toolCallId

string

Id of the tool call this message responds to. Defaults to ''.

images

ImageContent[]

Attached images. Defaults to [].

agentId

string

Id of the agent that authored the message (multi-agent attribution). Defaults to ''.

createdAt

number | null

Creation timestamp (epoch seconds), or null when unset. Defaults to null.

ChatContent

Create a ChatContent text block.

Constructor

new ChatContent(opts: ChatContentOptions)

type

string

Content kind. Defaults to 'text'.

text

string

The text body. Defaults to ''.

ChatRole

Author role of a ChatMessage.

enum ChatRole {
  SYSTEM = 'system',
  DEVELOPER = 'developer',
  USER = 'user',
  ASSISTANT = 'assistant',
  TOOL = 'tool',
}

FunctionCall

Create a FunctionCall.

Constructor

new FunctionCall(opts: FunctionCallOptions)

name

string

Name of the tool being called. Defaults to ''.

arguments

string

Call arguments as a JSON string. Defaults to ''.

callId

string

Unique id correlating this call with its output. Defaults to ''.

FunctionCallOutput

Create a FunctionCallOutput.

Constructor

new FunctionCallOutput(opts: FunctionCallOutputOptions)

name

string

Name of the tool that produced this output. Defaults to ''.

output

string

The tool’s result, serialized as a string. Defaults to ''.

callId

string

Id matching the originating FunctionCall. Defaults to ''.

isError

boolean

Whether the output represents an error. Defaults to false.

ImageContent

Create an ImageContent, or one of its helper constructors: fromUrl, fromDataUrl, fromBase64, fromBytes, fromFile, fromFrame. All accept a detail hint ('auto' | 'low' | 'high', default 'auto').

Constructor

new ImageContent(opts: ImageContentOptions)

type

string

Content kind. Defaults to 'image'.

url

string

Image URL or data: URL. Defaults to ''.

detail

string

Vision detail hint: 'auto', 'low', or 'high'. Defaults to 'auto'.

ContextWindow

Configure how conversation history is bounded and trimmed. See ContextWindowOptions.

Constructor

new ContextWindow(opts: ContextWindowOptions)

maxTokens

number | null

Maximum tokens of conversation history to keep. Defaults to null (no token limit).

maxContextItems

number | null

Maximum number of history items (messages/turns) to keep. Defaults to null (no item limit).

keepRecentTurns

number

Number of most recent turns always preserved verbatim when trimming. Defaults to 3.

maxToolCallsPerTurn

number

Maximum tool calls allowed within a single turn. Defaults to 10.

summaryLlm

LLM | null

Optional LLM used to summarize older history when trimming. Defaults to null (no summarization).

EncodeOptions

Create an EncodeOptions. Pass { resizeOptions: null } to preserve the source dimensions; omitting it resizes to 1024x1024.

Constructor

new EncodeOptions(init: EncodeOptionsInit)

format

ImageFormat

Output format. Default: 'JPEG'.

resizeOptions

ResizeOptions | null

Target dimensions, or null to keep the source size. Default: 1024x1024.

quality

number

JPEG quality, 0-100 (ignored for PNG). Default: 75.

ResizeOptions

Create a ResizeOptions from width and height in pixels.

Constructor

new ResizeOptions(width: number, height: number)

width

number

required

height

number

required

encode

function encode(frame: ImageFrame, options?: EncodeOptions | null): Promise<Buffer>

Encode an image frame to JPEG or PNG bytes, optionally resizing. Requires the optional sharp dependency. Uses EncodeOptions defaults when options is omitted or null.

frame

ImageFrame

required

options

EncodeOptions | null

returns

Promise<Buffer>

coerceImageToJpegBytes

function coerceImageToJpegBytes(frame: ImageFrame, opts: CoerceImageOptions = {}): Promise<Buffer>

Return JPEG-ready bytes for an image frame, re-encoding only when necessary. If frame is already encoded bytes (Buffer/Uint8Array/ArrayBuffer), it is returned as-is (assumed to be a valid JPEG/PNG) and sharp is not required. Otherwise the frame is encoded with options (or DEFAULT_REALTIME_ENCODE_OPTIONS).

frame

ImageFrame

required

opts

CoerceImageOptions

returns

Promise<Buffer>

DEFAULT_REALTIME_ENCODE_OPTIONS

Encode options applied by coerceImageToJpegBytes when a frame must be re-encoded.

const DEFAULT_REALTIME_ENCODE_OPTIONS = EncodeOptions({ format: 'JPEG', resizeOptions: ResizeOptions(DEFAULT_IMAGE_WIDTH, DEFAULT_IMAGE_HEIGHT), quality: DEFAULT_IMAGE_QUALITY, })

​ChatContext

​Constructor

​addAttributedMessage

​addFunctionCall

​addFunctionOutput

​addHandoff

​addMessage

​copy

​estimatedTokens

​handoffs

​lastHandoff

​merge

​messages

​toAnthropicMessages

​toContextMessages

​toDict

​toGoogleContents

​toOpenaiMessages

​truncate

​turnCount

​ChatMessage

​Constructor

​ChatContent

​Constructor

​ChatRole

​FunctionCall

​Constructor

​FunctionCallOutput

​Constructor

​ImageContent

​Constructor

​ContextWindow

​Constructor

​EncodeOptions

​Constructor

​ResizeOptions

​Constructor

​encode

​coerceImageToJpegBytes

​DEFAULT_REALTIME_ENCODE_OPTIONS

ChatContext

Constructor

addAttributedMessage

addFunctionCall

addFunctionOutput

addHandoff

addMessage

copy

estimatedTokens

handoffs

lastHandoff

merge

messages

toAnthropicMessages

toContextMessages

toDict

toGoogleContents

toOpenaiMessages

truncate

turnCount

ChatMessage

Constructor

ChatContent

Constructor

ChatRole

FunctionCall

Constructor

FunctionCallOutput

Constructor

ImageContent

Constructor

ContextWindow

Constructor

EncodeOptions

Constructor

ResizeOptions

Constructor

encode

coerceImageToJpegBytes

DEFAULT_REALTIME_ENCODE_OPTIONS