Documentation
¶
Overview ¶
Package protocol defines the versioned JSON contract between K-brain and clients such as LiveAgent. Provider-specific wire shapes stay in internal/ai.
Index ¶
- Constants
- type BranchSessionRequest
- type CancelRequest
- type ClientTool
- type ClientToolImage
- type ClientToolRequest
- type ClientToolResolution
- type ClientToolResultRequest
- type CompactAccepted
- type CompactRequest
- type ContentBlock
- type CreateSessionRequest
- type EditSessionRequest
- type Event
- type GenerateEvent
- type GenerateRequest
- type GenerateResponse
- type GoalRequest
- type GoalState
- type HistoryMessageRef
- type HostedSearch
- type HostedSearchSource
- type Message
- type ModelRef
- type PageCursor
- type PermissionDecision
- type PermissionDecisionRequest
- type PermissionOption
- type PermissionRequest
- type PromptRequest
- type Question
- type QuestionAnswer
- type QuestionAnswerRequest
- type QuestionOption
- type QuestionRequest
- type QuestionResolution
- type ResumeRequest
- type RunAccepted
- type RunOptions
- type RunTerminal
- type Session
- type SessionPage
- type SessionSummary
- type ShareStatus
- type ShareUpdateRequest
- type SlashCommand
- type SlashCommandList
- type Subagent
- type SubagentEvent
- type TextDelta
- type TextGenerateRequest
- type TextGenerateResponse
- type ToolCall
- type ToolCallEvent
- type ToolDefinition
- type ToolResult
- type ToolResultEvent
- type ToolSelection
- type ToolStatus
- type UpdateSessionRequest
- type Usage
- type WorkspaceRoot
Constants ¶
const ( Version = "kbrain.agent.v1" RoleSystem = "system" RoleDeveloper = "developer" RoleUser = "user" RoleAssistant = "assistant" RoleTool = "tool" ContentText = "text" ContentThinking = "thinking" ContentImage = "image" ContentFile = "file" ContentToolCall = "tool_call" ContentToolResult = "tool_result" EventRunAccepted = "run.accepted" EventUserMessage = "user.message.appended" EventAssistantMessage = "assistant.message.created" EventTextDelta = "assistant.text.delta" EventThinkingDelta = "assistant.thinking.delta" EventHostedSearch = "assistant.sources" EventToolCall = "tool.call" EventToolResult = "tool.result" EventToolStatus = "tool.status" EventPermissionRequest = "permission.requested" EventPermissionResult = "permission.resolved" EventQuestionRequested = "question.requested" EventQuestionResolved = "question.resolved" EventClientToolRequested = "client_tool.requested" EventClientToolResolved = "client_tool.resolved" EventSubagentStarted = "subagent.started" EventSubagentUpdate = "subagent.updated" EventSubagentCompleted = "subagent.completed" EventSubagentFailed = "subagent.failed" EventUsage = "usage.updated" EventHistoryUpdated = "history.updated" EventCompactionStarted = "compaction.started" EventCompactionCompleted = "compaction.completed" EventRunCompleted = "run.completed" EventRunFailed = "run.failed" EventRunCancelled = "run.cancelled" EventHookWarning = "hook.warning" EventGoalUpdated = "goal.updated" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BranchSessionRequest ¶
type BranchSessionRequest struct {
ExpectedRevision string `json:"expected_revision,omitempty"`
MessageRef HistoryMessageRef `json:"message_ref"`
Title string `json:"title,omitempty"`
}
type CancelRequest ¶
type ClientTool ¶ added in v0.107.3
type ClientTool struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters json.RawMessage `json:"parameters"`
}
type ClientToolImage ¶ added in v0.107.3
type ClientToolRequest ¶ added in v0.107.3
type ClientToolResolution ¶ added in v0.107.3
type ClientToolResolution struct {
CallID string `json:"call_id"`
ToolCallID string `json:"tool_call_id"`
RunID string `json:"run_id"`
Tool string `json:"tool"`
Text string `json:"text"`
ImageCount int `json:"image_count,omitempty"`
IsError bool `json:"is_error,omitempty"`
TimedOut bool `json:"timed_out,omitempty"`
Cancelled bool `json:"cancelled,omitempty"`
}
type ClientToolResultRequest ¶ added in v0.107.3
type ClientToolResultRequest struct {
ConversationID string `json:"conversation_id"`
RunID string `json:"run_id"`
Text string `json:"text"`
Images []ClientToolImage `json:"images,omitempty"`
IsError bool `json:"is_error,omitempty"`
}
type CompactAccepted ¶
type CompactRequest ¶
type ContentBlock ¶
type ContentBlock struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
ImageURL string `json:"image_url,omitempty"`
FileURL string `json:"file_url,omitempty"`
Filename string `json:"filename,omitempty"`
MimeType string `json:"mime_type,omitempty"`
ToolCall *ToolCall `json:"tool_call,omitempty"`
ToolResult *ToolResult `json:"tool_result,omitempty"`
}
func (ContentBlock) Validate ¶
func (b ContentBlock) Validate() error
type CreateSessionRequest ¶
type EditSessionRequest ¶
type EditSessionRequest struct {
ExpectedRevision string `json:"expected_revision"`
MessageRef HistoryMessageRef `json:"message_ref"`
Replacement Message `json:"replacement"`
}
type Event ¶
type Event struct {
Version string `json:"version"`
Seq int64 `json:"seq"`
ID string `json:"id,omitempty"`
ConversationID string `json:"conversation_id"`
RunID string `json:"run_id"`
ParentRunID string `json:"parent_run_id,omitempty"`
Type string `json:"type"`
CreatedAt time.Time `json:"created_at"`
Payload json.RawMessage `json:"payload,omitempty"`
}
type GenerateEvent ¶ added in v0.107.6
type GenerateEvent struct {
Version string `json:"version"`
Type string `json:"type"`
Text string `json:"text,omitempty"`
Response *GenerateResponse `json:"response,omitempty"`
Error string `json:"error,omitempty"`
}
type GenerateRequest ¶ added in v0.107.6
type GenerateRequest struct {
Model ModelRef `json:"model"`
Messages []Message `json:"messages"`
Tools []ToolDefinition `json:"tools,omitempty"`
MaxOutputTokens int `json:"max_output_tokens,omitempty"`
Reasoning string `json:"reasoning,omitempty"`
CacheKey string `json:"cache_key,omitempty"`
Stream bool `json:"stream,omitempty"`
}
GenerateRequest is one model inference, not an agent/tool execution loop. Clients select a configured route; credentials and upstream URLs remain local.
type GenerateResponse ¶ added in v0.107.6
type GoalRequest ¶ added in v0.107.6
type GoalRequest struct {
Action string `json:"action"`
Goal string `json:"goal,omitempty"`
Run *PromptRequest `json:"run,omitempty"`
}
GoalRequest manages the session goal. Set and resume start a run with Run's request identity, model and options; later rounds reuse that run's options. Pause stops the running round and keeps the goal; update replaces the goal text without starting a run; clear drops the goal.
type GoalState ¶ added in v0.107.6
type GoalState struct {
Version string `json:"version"`
ConversationID string `json:"conversation_id"`
Goal string `json:"goal"`
Status string `json:"status"`
Round int `json:"round"`
MaxRounds int `json:"max_rounds"`
Reason string `json:"reason,omitempty"`
NextClientRequestID string `json:"next_client_request_id,omitempty"`
NextPrompt string `json:"next_prompt,omitempty"`
// StartedAt is when the current goal was set or last resumed (RFC 3339); the
// desktop goal bar shows the elapsed time from it.
StartedAt string `json:"started_at,omitempty"`
Run *RunAccepted `json:"run,omitempty"`
}
GoalState is the session goal snapshot returned by the goal route and carried by goal.updated events. Status is none, active, continuing, met, paused or cleared. A continuing event names the request id of the round the backend starts next. Reason explains a pause: user, restored, max_rounds, busy, start_failed, cancelled, failed, or awaiting_input when a round asked the user for input; the user's next plain run then resumes the goal as its round.
type HistoryMessageRef ¶
type HistoryMessageRef struct {
SegmentIndex int `json:"segment_index,omitempty"`
MessageIndex int `json:"message_index,omitempty"`
SegmentID string `json:"segment_id,omitempty"`
MessageID string `json:"message_id,omitempty"`
Role string `json:"role,omitempty"`
ContentHash string `json:"content_hash,omitempty"`
}
type HostedSearch ¶
type HostedSearchSource ¶
type Message ¶
type Message struct {
ID string `json:"id,omitempty"`
Role string `json:"role"`
Content []ContentBlock `json:"content,omitempty"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
Name string `json:"name,omitempty"`
Model string `json:"model,omitempty"`
Provider string `json:"provider,omitempty"`
Usage *Usage `json:"usage,omitempty"`
HostedSearch []HostedSearch `json:"hosted_search,omitempty"`
StopReason string `json:"stop_reason,omitempty"`
CreatedAt *time.Time `json:"created_at,omitempty"`
}
func FromAIMessage ¶
FromAIMessage converts the provider-neutral message into the canonical protocol shape. Use FromAIMessageValidated when malformed provider data must be rejected instead of returned for inspection. FromAIMessage converts a provider message into the canonical protocol shape.
type PageCursor ¶
type PermissionDecision ¶
type PermissionDecisionRequest ¶
type PermissionDecisionRequest struct {
ConversationID string `json:"conversation_id"`
RunID string `json:"run_id"`
Decision PermissionDecision `json:"decision"`
}
type PermissionOption ¶
type PermissionRequest ¶
type PromptRequest ¶
type PromptRequest struct {
ResumeMessageID string `json:"resume_message_id,omitempty"`
TurnID string `json:"turn_id,omitempty"`
ConversationID string `json:"conversation_id"`
ClientRequestID string `json:"client_request_id"`
Prompt string `json:"prompt,omitempty"`
Content []ContentBlock `json:"content,omitempty"`
Model *ModelRef `json:"model,omitempty"`
Options *RunOptions `json:"options,omitempty"`
HookPolicy string `json:"hook_policy,omitempty"`
HookScopeID string `json:"hook_scope_id,omitempty"`
StopRequested bool `json:"stop_requested,omitempty"`
// PromptCommand marks Prompt as "/name args" naming a prompt command. The backend
// expands it for the model while history keeps the text the user typed.
PromptCommand bool `json:"prompt_command,omitempty"`
// Snapshot is request-only text resolved at acceptance; it is never part of the wire.
Snapshot string `json:"-"`
}
type Question ¶
type Question struct {
ID string `json:"id"`
Header string `json:"header,omitempty"`
Prompt string `json:"prompt"`
Options []QuestionOption `json:"options"`
Multiple bool `json:"multiple,omitempty"`
}
type QuestionAnswer ¶
type QuestionAnswerRequest ¶
type QuestionAnswerRequest struct {
ConversationID string `json:"conversation_id"`
RunID string `json:"run_id"`
QuestionID string `json:"question_id"`
Answers []QuestionAnswer `json:"answers"`
}
type QuestionOption ¶
type QuestionRequest ¶
type QuestionResolution ¶
type QuestionResolution struct {
QuestionID string `json:"question_id"`
ToolCallID string `json:"tool_call_id"`
RunID string `json:"run_id"`
Kind string `json:"kind"`
Questions []Question `json:"questions"`
Answers []QuestionAnswer `json:"answers"`
Text string `json:"text"`
TimedOut bool `json:"timed_out,omitempty"`
Cancelled bool `json:"cancelled,omitempty"`
}
type ResumeRequest ¶
type RunAccepted ¶
type RunOptions ¶
type RunOptions struct {
Reasoning string `json:"reasoning,omitempty"`
Mode string `json:"mode,omitempty"`
Search string `json:"search,omitempty"`
ApprovalPolicy string `json:"approval_policy,omitempty"`
PermissionMode string `json:"permission_mode,omitempty"`
WorkspaceRoots []WorkspaceRoot `json:"workspace_roots,omitempty"`
Tools *ToolSelection `json:"tools,omitempty"`
PlanModeEnabled bool `json:"plan_mode_enabled,omitempty"`
MCPServerIDs []string `json:"mcp_server_ids,omitempty"`
// ClientTools are tools the connected client executes itself (for example the LiveAgent
// desktop Browser). They are offered to the model for this run only; a call is published
// as client_tool.requested and completes when the client posts the result.
ClientTools []ClientTool `json:"client_tools,omitempty"`
}
type RunTerminal ¶
type Session ¶
type Session struct {
SessionSummary
Revision string `json:"revision"`
Messages []Message `json:"messages"`
Tasks []Subagent `json:"tasks,omitempty"`
LastSeq int64 `json:"last_seq"`
}
type SessionPage ¶
type SessionPage struct {
Sessions []SessionSummary `json:"sessions"`
TotalCount int `json:"total_count"`
Next *PageCursor `json:"next,omitempty"`
Version string `json:"version"`
}
type SessionSummary ¶
type SessionSummary struct {
ID string `json:"id"`
Title string `json:"title,omitempty"`
CWD string `json:"cwd,omitempty"`
Model ModelRef `json:"model"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
MessageCount int `json:"message_count"`
Pinned bool `json:"pinned,omitempty"`
Archived bool `json:"archived,omitempty"`
}
type ShareStatus ¶
type ShareStatus struct {
}
type ShareUpdateRequest ¶
type ShareUpdateRequest struct {
}
type SlashCommand ¶ added in v0.107.6
type SlashCommand struct {
Name string `json:"name"`
Description string `json:"description"`
ArgumentHint string `json:"argument_hint,omitempty"`
Kind string `json:"kind"`
Source string `json:"source"`
}
SlashCommand is one entry of the desktop slash command catalog. Kind "action" is handled by the client by name; kind "prompt" is sent as a run with prompt_command.
type SlashCommandList ¶ added in v0.107.6
type SlashCommandList struct {
Version string `json:"version"`
Commands []SlashCommand `json:"commands"`
}
type Subagent ¶
type Subagent struct {
ID string `json:"id"`
ParentID string `json:"parent_id,omitempty"`
Description string `json:"description"`
Status string `json:"status"`
Model ModelRef `json:"model"`
Attempt int `json:"attempt,omitempty"`
Report string `json:"report,omitempty"`
Error string `json:"error,omitempty"`
StartedAt *time.Time `json:"started_at,omitempty"`
UpdatedAt *time.Time `json:"updated_at,omitempty"`
EndedAt *time.Time `json:"ended_at,omitempty"`
}
type SubagentEvent ¶
type SubagentEvent struct {
Subagent Subagent `json:"subagent"`
}
type TextGenerateRequest ¶
type TextGenerateRequest struct {
Model ModelRef `json:"model"`
Messages []Message `json:"messages"`
Output string `json:"output,omitempty"`
}
TextGenerateRequest is the stateless, no-tools auxiliary generation contract. Messages use the same canonical model as session history but only text blocks and system/developer/user/assistant roles are accepted by the backend.
type TextGenerateResponse ¶
type ToolCall ¶
type ToolCall struct {
ID string `json:"id"`
Name string `json:"name"`
Arguments json.RawMessage `json:"arguments"`
}
type ToolCallEvent ¶
type ToolCallEvent struct {
ToolCall ToolCall `json:"tool_call"`
}
type ToolDefinition ¶
type ToolDefinition struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Parameters json.RawMessage `json:"parameters,omitempty"`
}
type ToolResult ¶
type ToolResultEvent ¶
type ToolResultEvent struct {
ToolResult ToolResult `json:"tool_result"`
}
type ToolSelection ¶
type ToolStatus ¶
type UpdateSessionRequest ¶
type UpdateSessionRequest struct {
Model *ModelRef `json:"model,omitempty"`
Title *string `json:"title,omitempty"`
Pinned *bool `json:"pinned,omitempty"`
Archived *bool `json:"archived,omitempty"`
// CWD moves the session to another workspace. It must be an absolute path to an
// existing directory; tools in later turns run there.
CWD *string `json:"cwd,omitempty"`
}
type Usage ¶
type Usage struct {
InputTokens int `json:"input_tokens,omitempty"`
OutputTokens int `json:"output_tokens,omitempty"`
CachedTokens int `json:"cached_tokens,omitempty"`
CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
}