Protocol Documentation

aulo/v1/common.proto
aulo/v1/event.proto
aulo/v1/approval.proto
aulo/v1/audit.proto
aulo/v1/chat.proto
aulo/v1/config.proto
aulo/v1/mcp.proto
aulo/v1/plugin.proto
aulo/v1/session.proto
aulo/v1/voice.proto
Scalar Value Types

aulo/v1/common.proto

ModelRef

A provider-qualified model, for example provider "anthropic" and model "claude-sonnet-5-5". Both parts are the ids ConfigService.ListModels returns.

Field	Type	Label	Description
provider	string		Provider id from [providers.*] in the config. At most 64 bytes.
model	string		Model id as the provider names it. At most 128 bytes.

ApprovalDecision

How a human answered an approval. Voice never widens access: when ApprovalRequired.needs_click is true, only a deliberate click or key may produce one of these.

Name	Number	Description
APPROVAL_DECISION_UNSPECIFIED	0
APPROVAL_DECISION_ALLOW_ONCE	1	Run this call once.
APPROVAL_DECISION_ALLOW_CHAT	2	Allow this tool and subject for the rest of this chat.
APPROVAL_DECISION_ALLOW_ALWAYS	3	Allow this tool and subject from now on; stored as a grant.
APPROVAL_DECISION_DENY_ONCE	4	Refuse this call once.
APPROVAL_DECISION_DENY_ALWAYS	5	Refuse this tool and subject from now on; stored as a grant.

ToolCallStatus

Where a tool call is in its life.

Name	Number	Description
TOOL_CALL_STATUS_UNSPECIFIED	0
TOOL_CALL_STATUS_RUNNING	1
TOOL_CALL_STATUS_SUCCEEDED	2
TOOL_CALL_STATUS_FAILED	3
TOOL_CALL_STATUS_DENIED	4	Policy or a human refused it; it never ran.
TOOL_CALL_STATUS_CANCELLED	5	The turn was interrupted while it ran.

aulo/v1/event.proto

ApprovalRequired

The agent wants to run a call that policy sent to Ask. Any attached client may answer with ApprovalService.Decide or a Converse decision; no answer before the server timeout means deny.

Field	Type	Description
chat_id	string	ULID.
turn_id	string	ULID.
call_id	string	ULID.
tool	string	Tool name, for example "shell" or "mcp__server__tool". Untrusted: plugin and MCP names come from third parties. At most 128 bytes.
summary	string	Human-readable description of the call, built from model-chosen arguments. Untrusted; render as plain text. At most 2 KiB; secrets appear as handles.
needs_click	bool	Voice never widens access: when true, only a click or key approves.

ApprovalResolved

An approval was answered, so every other attached client can dismiss its prompt.

Field	Type	Description
call_id	string	ULID.
decision	ApprovalDecision
timed_out	bool	True when nobody answered in time and the server denied.

Event

One event pushed to a client. The first block of variants mirrors aulo-types AuloEvent one to one (same names, same fields), so the server maps them without a translation table. The second block carries the agent loop: the turn, its streamed text and its tool calls.

Events never carry audio samples: TTS audio travels as VoiceService TtsAudio messages so events stay small and the audio path stays bounded.

Field	Type	Description
voice_state	VoiceStateChanged	Mirrors of AuloEvent.
speech_started	SpeechStarted
speech_ended	SpeechEnded
transcript	Transcript
tts_chunk	TtsChunk
approval_required	ApprovalRequired
takeover_requested	TakeoverRequested
notice	Notice
turn_started	TurnStarted	Agent loop.
text_delta	TextDelta
tool_call_started	ToolCallStarted
tool_call_output	ToolCallOutput
tool_call_finished	ToolCallFinished
approval_resolved	ApprovalResolved
turn_finished	TurnFinished

Notice

Field	Type	Label	Description
level	NoticeLevel
message	string		Untrusted when it quotes a plugin, MCP server or engine. At most 2 KiB.
source	string	optional	The engine, server or plugin the notice is about, if any.

SpeechEnded

Field	Type	Label	Description
at_ms	uint64

SpeechStarted

Field	Type	Label	Description
at_ms	uint64		Offset into the capture stream, so clients can align it with audio.

TakeoverRequested

Field	Type	Description
chat_id	string	ULID.
call_id	string	ULID.
reason	TakeoverReason

TextDelta

A streamed piece of the assistant reply. Concatenate deltas of one turn in arrival order.

Field	Type	Label	Description
turn_id	string		ULID.
text	string		Untrusted model output. At most 16 KiB per delta.

ToolCallFinished

Field	Type	Label	Description
call_id	string		ULID.
status	ToolCallStatus

ToolCallOutput

A streamed piece of tool output.

Field	Type	Label	Description
call_id	string		ULID.
text	string		Untrusted: tool, web and plugin output. At most 16 KiB per event and truncated server-side beyond a per-call total.

ToolCallStarted

Field	Type	Description
turn_id	string	ULID.
call_id	string	ULID.
tool	string	Untrusted; see ApprovalRequired.tool.
arguments_json	string	Model-chosen arguments as a JSON object. Untrusted. Truncated server-side to 16 KiB for display; the persisted call keeps the full text.

Transcript

Field	Type	Label	Description
turn_id	string		ULID.
kind	TranscriptKind
text	string		Untrusted: STT output of whatever was said or played near the microphone. At most 64 KiB; the server truncates longer text.
language	string	optional	BCP 47 tag when the engine detected or was told the language.

TtsChunk

Metadata of one synthesized audio chunk. The samples follow in the matching TtsAudio message (same turn_id and seq) on the Talk stream.

Field	Type	Description
turn_id	string	ULID.
seq	uint32	Position in the reply, so a client can detect a dropped chunk.
sample_rate_hz	uint32
channels	uint32	Rust side is u8; protobuf has no 8-bit integer.
duration_ms	uint32
last	bool	True on the last chunk of the reply.

TurnFinished

Field	Type	Label	Description
turn_id	string		ULID.
reason	TurnEndReason
error	string	optional	Set when reason is FAILED. Server-written, no secrets, at most 2 KiB.

TurnStarted

A user turn was accepted and the agent started on it.

Field	Type	Label	Description
turn_id	string		ULID, assigned by the server.

VoiceStateChanged

AuloEvent::VoiceState. Named Changed because the enum already owns the name.

Field	Type	Label	Description
state	VoiceState

NoticeLevel

Severity of a Notice.

Name	Number	Description
NOTICE_LEVEL_UNSPECIFIED	0
NOTICE_LEVEL_INFO	1
NOTICE_LEVEL_WARN	2
NOTICE_LEVEL_ERROR	3

TakeoverReason

What a human has to do themselves because the agent must not.

Name	Number	Description
TAKEOVER_REASON_UNSPECIFIED	0
TAKEOVER_REASON_PASSWORD	1
TAKEOVER_REASON_TWO_FACTOR	2
TAKEOVER_REASON_CAPTCHA	3
TAKEOVER_REASON_OTHER	4

TranscriptKind

Whether a transcript may still change.

Name	Number	Description
TRANSCRIPT_KIND_UNSPECIFIED	0
TRANSCRIPT_KIND_PARTIAL	1	A streaming hypothesis the engine may revise.
TRANSCRIPT_KIND_FINAL	2	The engine's committed text for the utterance.

TurnEndReason

Why a turn ended.

Name	Number	Description
TURN_END_REASON_UNSPECIFIED	0
TURN_END_REASON_COMPLETED	1
TURN_END_REASON_INTERRUPTED	2
TURN_END_REASON_FAILED	3
TURN_END_REASON_MAX_STEPS	4	The agent hit its step limit before finishing.

VoiceState

Where the voice pipeline is for the current client.

Name	Number	Description
VOICE_STATE_UNSPECIFIED	0
VOICE_STATE_IDLE	1
VOICE_STATE_LISTENING	2
VOICE_STATE_THINKING	3
VOICE_STATE_SPEAKING	4

aulo/v1/approval.proto

DecideRequest

Field	Type	Label	Description
call_id	string		ULID.
decision	ApprovalDecision

DecideResponse

Grant

A standing answer stored by an ALLOW_ALWAYS or DENY_ALWAYS decision.

Field	Type	Label	Description
id	string		ULID.
subject	string		What the grant covers, written by aulo-policy; opaque to clients, which show it and never build one.
scope	string
decision	GrantDecision
expires_at	google.protobuf.Timestamp	optional	Absent means it never expires.
created_at	google.protobuf.Timestamp

ListGrantsRequest

Field	Type	Label	Description
page_size	uint32
page_token	string

ListGrantsResponse

Field	Type	Label	Description
grants	Grant	repeated
next_page_token	string

ListPendingRequest

Field	Type	Label	Description
chat_id	string	optional	Only this chat.

ListPendingResponse

Field	Type	Label	Description
approvals	ApprovalRequired	repeated

RevokeGrantRequest

Field	Type	Label	Description
grant_id	string		ULID.

RevokeGrantResponse

GrantDecision

Name	Number	Description
GRANT_DECISION_UNSPECIFIED	0
GRANT_DECISION_ALLOW	1
GRANT_DECISION_DENY	2

ApprovalService

Human answers to the questions policy asks, and the standing grants those answers create. Scope: control.

Method Name	Request Type	Response Type	Description
ListPending	ListPendingRequest	ListPendingResponse	Approvals still waiting, oldest first. Lets a client that attached late show prompts it missed.
Decide	DecideRequest	DecideResponse	Answers one pending approval. Always a deliberate click or key from the client's own UI: spoken answers are resolved inside the daemon and never arrive here, so a client must not forward a spoken yes for a call whose needs_click is true. An unknown or already answered call_id fails with NOT_FOUND.
ListGrants	ListGrantsRequest	ListGrantsResponse
RevokeGrant	RevokeGrantRequest	RevokeGrantResponse

aulo/v1/audit.proto

AuditEntry

Field	Type	Description
seq	uint64	Position in the chain, assigned by the database.
prev_hash	string	Hex digests; hash covers prev_hash and the row's content.
hash	string
kind	string	Row kind, for example "tool_call" or "approval".
payload_json	string	JSON object. Untrusted: it quotes model-chosen arguments and tool output.
created_at	google.protobuf.Timestamp

ExportRequest

Field	Type	Label	Description
from_seq	uint64	optional	Inclusive bounds on seq; absent means from the first or to the last row.
to_seq	uint64	optional

ExportResponse

Field	Type	Label	Description
chunk	bytes		A slice of the JSON Lines stream, at most 64 KiB. A row may span chunks; concatenate in order.

QueryRequest

Field	Type	Label	Description
page_size	uint32
page_token	string
kind	string	optional	Only rows of this kind.
since	google.protobuf.Timestamp	optional	Only rows created at or after / before these instants.
until	google.protobuf.Timestamp	optional

QueryResponse

Field	Type	Label	Description
entries	AuditEntry	repeated
next_page_token	string

VerifyRequest

VerifyResponse

Field	Type	Label	Description
ok	bool
rows_checked	uint64
first_bad_seq	uint64	optional	Set when ok is false: the first row whose hash does not match.

AuditService

The append-only, hash-chained audit log of tool calls, approvals, egress and plugin loads. Read only: no RPC writes or deletes rows. Scope: admin, because payloads can contain what a user asked the agent to do.

Method Name	Request Type	Response Type	Description
Query	QueryRequest	QueryResponse	Oldest first (seq ascending).
Verify	VerifyRequest	VerifyResponse	Recomputes the whole hash chain.
Export	ExportRequest	ExportResponse stream	Streams rows as JSON Lines, one AuditEntry per line, in chunks.

aulo/v1/chat.proto

Chat

Field	Type	Label	Description
id	string		ULID.
bot_id	string	optional	The bot (agent persona) the chat belongs to; absent for the default bot.
title	string		Untrusted when generated by the model. At most 200 bytes.
model	ModelRef		The model the next turn uses; changed by a SwitchModel submission.
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

CreateChatRequest

Field	Type	Label	Description
bot_id	string	optional	Defaults to the default bot.
title	string	optional	Defaults to an empty title that the cheap tier fills in after the first turn. At most 200 bytes.
model	ModelRef	optional	Defaults to the bot's configured main model.

CreateChatResponse

Field	Type	Label	Description
chat	Chat

DeleteChatRequest

Field	Type	Label	Description
chat_id	string		ULID.

DeleteChatResponse

GetChatRequest

Field	Type	Label	Description
chat_id	string		ULID.

GetChatResponse

Field	Type	Label	Description
chat	Chat

ListChatsRequest

Field	Type	Label	Description
page_size	uint32
page_token	string
bot_id	string	optional	Only chats of this bot.

ListChatsResponse

Field	Type	Label	Description
chats	Chat	repeated
next_page_token	string		Empty on the last page.

ListMessagesRequest

Field	Type	Description
chat_id	string	ULID.
page_size	uint32
page_token	string

ListMessagesResponse

Field	Type	Label	Description
messages	Message	repeated
next_page_token	string

Message

Field	Type	Label	Description
id	string		ULID.
chat_id	string		ULID.
role	MessageRole
content	string		Untrusted for every role except what the signed-in user typed. Text is never interpreted as markup by the server.
tool_calls	ToolCall	repeated	Calls the assistant made in this message, oldest first.
created_at	google.protobuf.Timestamp

RenameChatRequest

Field	Type	Label	Description
chat_id	string		ULID.
title	string		Non-empty, at most 200 bytes.

RenameChatResponse

Field	Type	Label	Description
chat	Chat

SearchMessagesRequest

Field	Type	Label	Description
query	string		Untrusted user input for the FTS index; at most 1 KiB. Treated as plain words, never as query syntax.
page_size	uint32
page_token	string
chat_id	string	optional	Only this chat.

SearchMessagesResponse

Field	Type	Label	Description
messages	Message	repeated
next_page_token	string

ToolCall

Field	Type	Label	Description
id	string		ULID.
name	string		Untrusted; see Event ApprovalRequired.tool.
arguments_json	string		Model-chosen arguments as a JSON object. Untrusted.
output	string	optional	Tool output, absent while running. Untrusted; the server caps it at 64 KiB here and keeps the full text only in storage.
status	ToolCallStatus
created_at	google.protobuf.Timestamp

MessageRole

Name	Number	Description
MESSAGE_ROLE_UNSPECIFIED	0
MESSAGE_ROLE_USER	1
MESSAGE_ROLE_ASSISTANT	2
MESSAGE_ROLE_TOOL	3

ChatService

Chat CRUD and message history. Scopes: reads need read; create, rename and delete need chat.

Method Name	Request Type	Response Type	Description
CreateChat	CreateChatRequest	CreateChatResponse
ListChats	ListChatsRequest	ListChatsResponse	Newest activity first (updated_at descending).
GetChat	GetChatRequest	GetChatResponse
RenameChat	RenameChatRequest	RenameChatResponse
DeleteChat	DeleteChatRequest	DeleteChatResponse	Deletes the chat with its messages, tool calls and usage rows. Permanent.
ListMessages	ListMessagesRequest	ListMessagesResponse	Oldest first (message id ascending).
SearchMessages	SearchMessagesRequest	SearchMessagesResponse	Full-text search across all chats, best match first.

aulo/v1/config.proto

AudioDevice

Field	Type	Description
id	string	Stable id of the device on this host. At most 256 bytes.
name	string	Untrusted: the OS or driver supplies it.
direction	AudioDirection
is_default	bool

GetConfigRequest

GetConfigResponse

Field	Type	Label	Description
config_json	string		The effective configuration as JSON that validates against schemas/aulo.schema.json. Secrets are never part of it; inline keys are rejected by the config loader.

ListAudioDevicesRequest

ListAudioDevicesResponse

Field	Type	Label	Description
devices	AudioDevice	repeated

ListModelsRequest

Field	Type	Label	Description
provider_id	string	optional	Only this provider.
page_size	uint32
page_token	string

ListModelsResponse

Field	Type	Label	Description
models	Model	repeated
next_page_token	string

ListProvidersRequest

ListProvidersResponse

Field	Type	Label	Description
providers	Provider	repeated

Model

Field	Type	Description
ref	ModelRef
display_name	string	Untrusted: comes from a provider's server. At most 128 bytes.
served	bool	True when the provider's server reports it as served right now, as opposed to only being in the catalog.

Provider

Field	Type	Label	Description
id	string		Section name under [providers.*]. At most 64 bytes.
kind	string		Wire family, for example "openai", "anthropic" or "openai-compatible".
base_url	string	optional	Absent for hosted providers with a fixed endpoint.
key_set	bool		Whether a credential is available (keychain or env). The value is never sent.

SetConfigRequest

Field	Type	Label	Description
merge_patch_json	string		An RFC 7386 JSON merge patch applied to the user layer (~/.aulo/config.toml) and validated against the schema before it is written; unknown keys are rejected. At most 64 KiB.

SetConfigResponse

Field	Type	Label	Description
config_json	string		The effective configuration after the patch, as in GetConfigResponse.

SetDeviceRequest

Field	Type	Label	Description
direction	AudioDirection
device_id	string		Empty selects the system default.

SetDeviceResponse

SetProviderKeyRequest

Field	Type	Label	Description
provider_id	string
key	string		At most 4 KiB. Never echoed, logged or audited.

SetProviderKeyResponse

AudioDirection

Name	Number	Description
AUDIO_DIRECTION_UNSPECIFIED	0
AUDIO_DIRECTION_INPUT	1
AUDIO_DIRECTION_OUTPUT	2

ConfigService

Providers, models, audio devices and the configuration. Reads need read; every write needs admin.

Method Name	Request Type	Response Type	Description
ListProviders	ListProvidersRequest	ListProvidersResponse
SetProviderKey	SetProviderKeyRequest	SetProviderKeyResponse	Stores the key in the OS keychain. Write-only: no RPC ever returns a key, and the key must not appear in logs, audit rows or events. A remote client should only call it over TLS.
ListModels	ListModelsRequest	ListModelsResponse	The catalog merged with what the provider's server reports as served.
ListAudioDevices	ListAudioDevicesRequest	ListAudioDevicesResponse
SetDevice	SetDeviceRequest	SetDeviceResponse	Picks the audio device for a direction; the choice persists. An unplugged device falls back to the default with a Notice.
GetConfig	GetConfigRequest	GetConfigResponse
SetConfig	SetConfigRequest	SetConfigResponse

aulo/v1/mcp.proto

ListServersRequest

ListServersResponse

Field	Type	Label	Description
servers	McpServer	repeated

McpServer

Field	Type	Label	Description
name	string		Key under [mcp.servers]. At most 64 bytes.
state	McpServerState
last_error	string	optional	Why the server is FAILED. Untrusted: it can quote the server's own output. At most 2 KiB.

McpServiceDisableRequest

Field	Type	Label	Description
name	string

McpServiceDisableResponse

Field	Type	Label	Description
server	McpServer

McpServiceEnableRequest

Field	Type	Label	Description
name	string

McpServiceEnableResponse

Field	Type	Label	Description
server	McpServer

McpServiceRestartRequest

Field	Type	Label	Description
name	string

McpServiceRestartResponse

Field	Type	Label	Description
server	McpServer

ServerStatusRequest

Field	Type	Label	Description
name	string

ServerStatusResponse

Field	Type	Label	Description
server	McpServer
tools	string	repeated	Tool names as the model sees them (mcp__server__tool). Untrusted: the server chooses them.
recent_stderr	string	repeated	The last lines the server wrote to stderr, oldest first. Untrusted; the server keeps at most 100 lines of 4 KiB each.

McpServerState

Name	Number	Description
MCP_SERVER_STATE_UNSPECIFIED	0
MCP_SERVER_STATE_DISABLED	1
MCP_SERVER_STATE_STARTING	2
MCP_SERVER_STATE_READY	3
MCP_SERVER_STATE_FAILED	4

McpService

The MCP servers aulo is a client of. Reads need read; Enable, Disable and Restart need control. A broken server is a notice and a FAILED state, never an RPC error for the others. Enable, Disable and Restart messages carry the service name because PluginService has RPCs of the same names and message names are package-wide.

Method Name	Request Type	Response Type	Description
ListServers	ListServersRequest	ListServersResponse
ServerStatus	ServerStatusRequest	ServerStatusResponse	One server with its tool names and recent stderr.
Enable	McpServiceEnableRequest	McpServiceEnableResponse
Disable	McpServiceDisableRequest	McpServiceDisableResponse
Restart	McpServiceRestartRequest	McpServiceRestartResponse

aulo/v1/plugin.proto

Plugin

Field	Type	Description
id	string	Manifest id. At most 64 bytes.
name	string	Untrusted: the plugin's own manifest text. At most 128 bytes.
version	string
kind	PluginKind
enabled	bool

PluginServiceDisableRequest

Field	Type	Label	Description
id	string

PluginServiceDisableResponse

Field	Type	Label	Description
plugin	Plugin

PluginServiceEnableRequest

Field	Type	Label	Description
id	string

PluginServiceEnableResponse

Field	Type	Label	Description
plugin	Plugin

PluginServiceInstallRequest

Field	Type	Label	Description
source	string		A filesystem path on the daemon's host or a git URL. Untrusted; at most 2 KiB. A relative path is rejected.

PluginServiceInstallResponse

Field	Type	Label	Description
plugin	Plugin

PluginServiceListRequest

PluginServiceListResponse

Field	Type	Label	Description
plugins	Plugin	repeated

PluginServiceRemoveRequest

Field	Type	Label	Description
id	string

PluginServiceRemoveResponse

PluginKind

How the host runs the plugin.

Name	Number	Description
PLUGIN_KIND_UNSPECIFIED	0
PLUGIN_KIND_MCP_PROCESS	1
PLUGIN_KIND_GRPC_PROCESS	2
PLUGIN_KIND_WASM	3

PluginService

Installed plugins (spec section 9). Scope: List needs read; every other RPC needs admin, because a plugin is code that runs on the host.

Method Name	Request Type	Response Type	Description
List	PluginServiceListRequest	PluginServiceListResponse
Install	PluginServiceInstallRequest	PluginServiceInstallResponse	Installs from a local path or a git URL and leaves the plugin disabled until Enable. The manifest is validated and the plugin's declared capabilities are shown for approval before anything runs.
Enable	PluginServiceEnableRequest	PluginServiceEnableResponse
Disable	PluginServiceDisableRequest	PluginServiceDisableResponse
Remove	PluginServiceRemoveRequest	PluginServiceRemoveResponse

aulo/v1/session.proto

Attach

Binds the stream to a chat. Must be the first message and may be sent once.

Field	Type	Label	Description
chat_id	string		ULID.

ConverseRequest

A client submission. Names follow the agent loop's Submission type.

Field	Type	Label	Description
attach	Attach
user_turn	UserTurn
decide_approval	DecideApproval
interrupt	Interrupt
switch_model	SwitchModel
takeover_done	TakeoverDone

ConverseResponse

Field	Type	Label	Description
event	Event

DecideApproval

Answers an ApprovalRequired. The same decision as ApprovalService.Decide; both reach one approval queue and the first answer wins.

Field	Type	Label	Description
call_id	string		ULID.
decision	ApprovalDecision

Interrupt

Stops the running turn and its tool calls within 200 ms.

Field	Type	Label	Description
all	bool		Kill switch: stop every running turn, tool call and speech on the daemon, not only this chat. Requires the `control` scope.

SwitchModel

Changes the model for this chat from the next turn on.

Field	Type	Label	Description
model	ModelRef

TakeoverDone

The human finished what a TakeoverRequested asked for; the turn resumes only after this arrives.

Field	Type	Label	Description
call_id	string		ULID.

UserTurn

A user message. The server answers with TurnStarted.

Field	Type	Label	Description
text	string		At most 64 KiB; longer text is rejected, not truncated, so a client never sends a prompt the user did not write.

SessionService

Text conversation with the agent. Scope: chat; an Interrupt with all=true needs control.

Method Name	Request Type	Response Type	Description
Converse	ConverseRequest stream	ConverseResponse stream	One stream drives one chat. The first request must be an Attach; anything else closes the stream with FAILED_PRECONDITION. The server answers with events of that chat only. Several clients may attach to one chat; each sees every event of it. History before the attach is read with ChatService.ListMessages, not replayed here.

aulo/v1/voice.proto

ListVoicesRequest

Field	Type	Label	Description
engine	string	optional	Defaults to the active engine.

ListVoicesResponse

Field	Type	Label	Description
voices	Voice	repeated

SetVoiceRequest

Field	Type	Label	Description
engine	string
voice_id	string
bot_id	string
chat_id	string

SetVoiceResponse

StartListeningRequest

StartListeningResponse

StopListeningRequest

StopListeningResponse

TalkRequest

Field	Type	Description
start	TalkStart
audio	bytes	One frame of microphone audio in the format given in Start, ideally 20 ms (640 bytes of PCM). At most 16 KiB (512 ms) of PCM; a larger frame closes the stream. Opus frames have the smaller caps given on the format. The server buffers audio in a fixed-size ring and counts overflow, so a client that sends faster than real time loses audio.
control	TalkControl

TalkResponse

Field	Type	Label	Description
event	Event
tts_audio	TtsAudio

TalkStart

Field	Type	Label	Description
chat_id	string		The chat that receives the final transcripts. ULID.
format	AudioFormat		Format of every audio frame that follows.

TtsAudio

Synthesized speech. Sample rate, channel count and duration come in the TtsChunk event with the same turn_id and seq, which is sent first.

Field	Type	Description
turn_id	string	ULID.
seq	uint32
pcm_s16le	bytes	Signed 16-bit little-endian PCM. At most 32 KiB per message.

Voice

Field	Type	Description
engine	string	TTS engine id from [voice.tts], for example "kokoro".
id	string	Engine-specific voice id. At most 128 bytes.
name	string	Display name; untrusted when a plugin engine supplies it.
language	string	BCP 47 tag.

AudioFormat

Name	Number	Description
AUDIO_FORMAT_UNSPECIFIED	0
AUDIO_FORMAT_PCM_S16LE_16KHZ_MONO	1	Signed 16-bit little-endian PCM, 16 kHz, mono: the default for remote clients.
AUDIO_FORMAT_OPUS_16KHZ_MONO	2	Opus (RFC 6716), 16 kHz, mono, for low-bandwidth clients. Every audio frame is exactly one Opus packet, ideally 20 ms. At most 1500 bytes and 6 Opus frames (120 ms); a packet over a cap, an empty packet or one that does not decode closes the stream.

TalkControl

Push-to-talk and playback control inside a Talk stream.

Name	Number	Description
TALK_CONTROL_UNSPECIFIED	0
TALK_CONTROL_START_LISTENING	1
TALK_CONTROL_STOP_LISTENING	2

VoiceService

Server-side voice pipeline for clients that have no audio stack of their own (remote clients) or want the daemon's. Scope: voice; SetVoice also needs control.

Method Name	Request Type	Response Type	Description
Talk	TalkRequest stream	TalkResponse stream	The client streams microphone audio and control; the server runs VAD, STT, the agent and TTS and streams back state, transcripts and synthesized audio. The first request must be a Start; anything else closes the stream with FAILED_PRECONDITION. The stream carries only events about this client's voice session: VoiceStateChanged, SpeechStarted, SpeechEnded, Transcript, TtsChunk, Notice, ApprovalRequired and TakeoverRequested.
StartListening	StartListeningRequest	StartListeningResponse	Push-to-talk for the daemon's own microphone (local mode). Does nothing useful for remote clients, which use TalkControl on their stream.
StopListening	StopListeningRequest	StopListeningResponse
ListVoices	ListVoicesRequest	ListVoicesResponse	Lists the voices of the active or named TTS engine.
SetVoice	SetVoiceRequest	SetVoiceResponse	Takes effect from the next utterance; a sentence being spoken finishes.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

Table of Contents