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 CompactAccepted
- type CompactRequest
- type ContentBlock
- type CreateSessionRequest
- type EditSessionRequest
- type Event
- 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 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" 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" )
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 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 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"`
}
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"`
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"`
}
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 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 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"`
}