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 Build
- 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 PermissionAutoResolved
- type PermissionDecision
- type PermissionDecisionRequest
- type PermissionOption
- type PermissionRequest
- type PermissionRule
- type PermissionRuleCreate
- type PermissionRulesResponse
- type PermissionSuggestion
- type PromptRequest
- type ProtocolInfo
- type Question
- type QuestionAnswer
- type QuestionAnswerRequest
- type QuestionOption
- type QuestionRequest
- type QuestionResolution
- type ResumeRequest
- type RunAccepted
- type RunOptions
- type RunSandbox
- type RunTerminal
- type Session
- type SessionChange
- type SessionChanges
- type SessionPage
- type SessionSnapshotInfo
- type SessionSnapshotPage
- type SessionSummary
- type SessionWorkdir
- 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 ( ProtocolName = "kbrain.agent" ProtocolMajor = 1 // ProtocolMinor counts additive revisions inside major 1. It is for logs // only; clients gate features on capabilities, never on this number. ProtocolMinor = 1 // StartupContract versions the `kn backend` flags, ready line and exit // conventions independently of the HTTP protocol. StartupContract = 1 )
Structured handshake fields defined by docs/compatibility.md section 2. The legacy Version string stays the primary v1 marker; Name/Major must agree with it or clients reject the health response as a broken contract.
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" EventRunProgress = "run.progress" 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" )
const EventPermissionAutoResolved = "permission.auto_resolved"
EventPermissionAutoResolved says a gated call ran without asking because a remembered rule or the read-only allowance covered it (capability permission_rules).
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 Build ¶ added in v0.107.6
type Build struct {
Version string `json:"version"`
Revision string `json:"revision,omitempty"`
Channel string `json:"channel"`
}
Build is the immutable identity of the running binary as injected at link time. releaseSequence is deliberately absent until signed release metadata (S3) gives it a trustworthy source.
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 PermissionAutoResolved ¶ added in v0.107.6
type PermissionAutoResolved struct {
ToolCallID string `json:"tool_call_id,omitempty"`
Tool string `json:"tool"`
Command string `json:"command,omitempty"`
// Source is "rule" or "read_only".
Source string `json:"source"`
Rule string `json:"rule,omitempty"`
Scope string `json:"scope,omitempty"`
}
PermissionAutoResolved is the payload of permission.auto_resolved.
type PermissionDecision ¶
type PermissionDecision struct {
PermissionID string `json:"permission_id"`
Decision string `json:"decision"`
Reason string `json:"reason,omitempty"`
// Scope picks where allow_always stores the suggested rules: session, project
// or user. Empty keeps the pre-rules meaning, this session only.
Scope string `json:"scope,omitempty"`
}
type PermissionDecisionRequest ¶
type PermissionDecisionRequest struct {
ConversationID string `json:"conversation_id"`
RunID string `json:"run_id"`
Decision PermissionDecision `json:"decision"`
}
type PermissionOption ¶
type PermissionRequest ¶
type PermissionRequest struct {
PermissionID string `json:"permission_id"`
Tool string `json:"tool"`
Command string `json:"command,omitempty"`
// Shell runs Command, when the tool runs one.
Shell string `json:"shell,omitempty"`
Rule string `json:"rule,omitempty"`
Description string `json:"description,omitempty"`
Options []PermissionOption `json:"options,omitempty"`
// Suggestion is what allow_always would remember; absent when the action can
// only be allowed once (capability permission_rules).
Suggestion *PermissionSuggestion `json:"suggestion,omitempty"`
// Scope "session" means approving also grants this kind of action for the
// rest of the session, so clients can say so before the user decides.
Scope string `json:"scope,omitempty"`
// ToolCallID is the model tool call awaiting this decision, when known, so
// clients can show the prompt beside that call.
ToolCallID string `json:"tool_call_id,omitempty"`
}
type PermissionRule ¶ added in v0.107.6
type PermissionRule struct {
ID string `json:"id"`
Rule string `json:"rule"`
Effect string `json:"effect"`
Scope string `json:"scope"`
CreatedAt string `json:"created_at,omitempty"`
SourceSession string `json:"source_session,omitempty"`
}
PermissionRule is one remembered rule as the rules API returns it.
type PermissionRuleCreate ¶ added in v0.107.6
type PermissionRuleCreate struct {
Rule string `json:"rule"`
Effect string `json:"effect"`
Scope string `json:"scope"`
Workspace string `json:"workspace,omitempty"`
SessionID string `json:"session_id,omitempty"`
}
PermissionRuleCreate is the body of POST /v1/permissions/rules. Workspace names the project for project scope; SessionID the session for session scope.
type PermissionRulesResponse ¶ added in v0.107.6
type PermissionRulesResponse struct {
ProjectRoot string `json:"project_root,omitempty"`
Rules []PermissionRule `json:"rules"`
}
PermissionRulesResponse answers GET /v1/permissions/rules.
type PermissionSuggestion ¶ added in v0.107.6
type PermissionSuggestion struct {
Rules []string `json:"rules"`
DefaultScope string `json:"default_scope"`
}
PermissionSuggestion lists the rules allow_always stores, all of them together, and the scope a client should preselect.
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 ProtocolInfo ¶ added in v0.107.6
type ProtocolInfo struct {
Name string `json:"name"`
Major int `json:"major"`
Minor int `json:"minor"`
}
func CurrentProtocol ¶ added in v0.107.6
func CurrentProtocol() ProtocolInfo
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"`
// ReviewScope "per_run" (capability ai_review_per_run) lets the permission mode alone decide
// AI review: only auto_review reviews, with the session's model when no reviewer is set.
// Without it the global aiApproval mode keeps applying as before.
ReviewScope string `json:"review_scope,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"`
// Sandbox (capability run_sandbox) confines the run's shell commands, hooks
// and terminals with the platform sandbox. It can only tighten a sandbox the
// server is configured with. The run is refused when the machine cannot
// enforce it; it never falls back to running unconfined.
Sandbox *RunSandbox `json:"sandbox,omitempty"`
}
type RunSandbox ¶ added in v0.107.16
RunSandbox is a run's request for OS-level confinement. Mode "workspace" lets commands read the machine (credential and LiveAgent data directories masked) and write only the workspace roots and temporary directories. Network false blocks network access.
type RunTerminal ¶
type SessionChange ¶ added in v0.107.6
type SessionChange struct {
ID string `json:"id"`
Revision string `json:"revision"`
Kind string `json:"kind"`
Listed bool `json:"listed"`
Session *SessionSummary `json:"session,omitempty"`
}
type SessionChanges ¶ added in v0.107.6
type SessionChanges struct {
Epoch string `json:"epoch"`
HeadRevision string `json:"head_revision"`
MinSince string `json:"min_since"`
NextSince *string `json:"next_since"`
Reset bool `json:"reset"`
ResetReason string `json:"reset_reason,omitempty"`
More bool `json:"more"`
Changes []SessionChange `json:"changes"`
}
type SessionPage ¶
type SessionPage struct {
Sessions []SessionSummary `json:"sessions"`
TotalCount int `json:"total_count"`
Next *PageCursor `json:"next,omitempty"`
Version string `json:"version"`
Epoch string `json:"epoch,omitempty"`
Revision string `json:"revision,omitempty"`
}
type SessionSnapshotInfo ¶ added in v0.107.6
type SessionSnapshotPage ¶ added in v0.107.6
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"`
// ForkedFrom names the session this one was branched from; ForkSeq is the last copied message.
ForkedFrom string `json:"forked_from,omitempty"`
ForkSeq int `json:"fork_seq,omitempty"`
}
type SessionWorkdir ¶ added in v0.107.6
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"`
}