adapterprotocol

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package adapterprotocol defines the wire types for the ox adapter protocol.

External adapter authors import this package to get typed request/response structs, the protocol version constant, and standard error codes. This is the only ox package external adapters need to import.

The canonical protocol reference is adapter/protocol/spec.md.

Index

Constants

View Source 
const (
	TypeSession = "session"
	TypeVCS     = "vcs"
	TypeIndexer = "indexer"
	TypeTest    = "test"
)

AdapterType identifies what subsystem an adapter belongs to.

View Source 
const (
	CapSessionReader      = "session_reader"
	CapHookInstaller      = "hook_installer"
	CapIncrementalReader  = "incremental_reader"
	CapFileWatcher        = "file_watcher"
	CapSessionImporter    = "session_importer"
	CapServeMode          = "serve_mode"
	CapSubagentController = "subagent_controller"
	CapRulesInstaller     = "rules_installer"
	CapCommandsInstaller  = "commands_installer"
	CapCapturePrior       = "capture_prior"
)
View Source 
const (
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleSystem    = "system"
	RoleTool      = "tool"
)

Role constants for RawEntry.Role field.

View Source 
const (
	ErrCodeMethodNotFound = "method_not_found"
	ErrCodeInvalidParams  = "invalid_params"
	ErrCodeInternalError  = "internal_error"
)

Standard error codes for RPCError.Code.

View Source 
const (
	MethodFindSession    = "find-session"
	MethodReadFromOffset = "read-from-offset"
	MethodEndSession     = "end-session"
	MethodShutdown       = "shutdown"
)
View Source 
const (
	MethodSpawnSubagent  = "spawn-subagent"
	MethodSubagentStatus = "subagent-status"
	MethodCancelSubagent = "cancel-subagent"
)
View Source 
const (
	EventSubagentProgress  = "subagent.progress"
	EventSubagentCompleted = "subagent.completed"
	EventSubagentFailed    = "subagent.failed"
)
View Source 
const (
	WorkerStatusStarting  = "starting"
	WorkerStatusRunning   = "running"
	WorkerStatusCompleted = "completed"
	WorkerStatusFailed    = "failed"
	WorkerStatusCanceled  = "canceled"
	WorkerStatusTimedOut  = "timed_out"
	WorkerStatusCanceling = "canceling"
)
View Source 
const EntrySchemaVersion = 1

EntrySchemaVersion identifies the raw.jsonl entry format version. Bumped when field semantics change in a backward-incompatible way.

View Source 
const ProtocolVersion = 1

ProtocolVersion is the current adapter protocol version. Adapters return this in their info response. ox refuses adapters whose major version is lower than its own minimum supported.

Variables

This section is empty.

Functions

This section is empty.

Types

type CancelSubagentParams 

type CancelSubagentParams struct {
	WorkerID string `json:"worker_id"`
	Reason   string `json:"reason,omitempty"`
}

CancelSubagentParams are the params for the cancel-subagent serve method.

type CancelSubagentResult 

type CancelSubagentResult struct {
	WorkerID string `json:"worker_id"`
	Status   string `json:"status"` // "canceling"
}

CancelSubagentResult is the result for the cancel-subagent serve method.

type CapturePriorParams 

type CapturePriorParams struct {
	SessionID string `json:"session_id,omitempty"` // native session ID (optional; adapter finds most recent if empty)
	RepoRoot  string `json:"repo_root"`            // project root for session discovery
	AgentID   string `json:"agent_id"`             // ox agent ID for metadata
	Title     string `json:"title,omitempty"`      // optional session title
}

CapturePriorParams are the params for the capture-prior one-shot command. Each adapter implements its own logic to find and parse the most recent (or specified) session from the agent's native storage format.

type CapturePriorResult 

type CapturePriorResult struct {
	Entries   []RawEntry       `json:"entries"`
	Metadata  *SessionMetadata `json:"metadata,omitempty"`
	AgentType string           `json:"agent_type"`           // adapter name (e.g., "claude-code")
	SessionID string           `json:"session_id,omitempty"` // resolved native session ID
}

CapturePriorResult is the result for capture-prior.

type CheckCommandsResponse added in v0.6.4 

type CheckCommandsResponse struct {
	Installed   bool     `json:"installed"`
	Missing     []string `json:"missing,omitempty"`
	Stale       []string `json:"stale,omitempty"`
	CommandsDir string   `json:"commands_dir"`
	Total       int      `json:"total"`
}

CheckCommandsResponse is returned by `check-commands`.

type CheckHooksResponse 

type CheckHooksResponse struct {
	Installed bool     `json:"installed"`
	Scope     string   `json:"scope"`
	HookFiles []string `json:"hook_files"`
}

CheckHooksResponse is returned by `check-hooks`.

type CheckRulesResponse 

type CheckRulesResponse struct {
	Installed bool     `json:"installed"`
	Missing   []string `json:"missing,omitempty"`
	Stale     []string `json:"stale,omitempty"`
	RulesDir  string   `json:"rules_dir"`
}

CheckRulesResponse is returned by `check-rules`.

type CommandsParams added in v0.6.4 

type CommandsParams struct {
	RepoRoot string `json:"repo_root"`
	Version  string `json:"version"` // ox version for stamped content
}

CommandsParams are passed to install-commands, check-commands, and uninstall-commands.

type DetectResponse 

type DetectResponse struct {
	Detected bool   `json:"detected"`
	Reason   string `json:"reason"`
}

DetectResponse is returned by the `detect` subcommand.

type DiagnoseIssue 

type DiagnoseIssue struct {
	Slug     string `json:"slug"`
	Severity string `json:"severity"` // "error", "warning", "info"
	Title    string `json:"title"`
	Detail   string `json:"detail"`
	Fix      string `json:"fix,omitempty"`
	FixSafe  bool   `json:"fix_safe"`
}

DiagnoseIssue is a single diagnostic finding.

type DiagnoseParams 

type DiagnoseParams struct {
	RepoRoot string `json:"repo_root"`
	Scope    string `json:"scope"`   // "project" or "user"
	Version  string `json:"version"` // ox version for stale-rules detection
}

DiagnoseParams are passed to `diagnose`.

type DiagnoseResult 

type DiagnoseResult struct {
	OK     bool            `json:"ok"`
	Issues []DiagnoseIssue `json:"issues"`
}

DiagnoseResult is returned by `diagnose`.

type EndSessionParams 

type EndSessionParams struct {
	AgentID string `json:"agent_id"`
	RepoID  string `json:"repo_id"`
}

EndSessionParams are the params for end-session.

type EntriesEventData 

type EntriesEventData struct {
	Entries   []RawEntry `json:"entries"`
	NewOffset int64      `json:"new_offset"`
}

EntriesEventData is the data payload for "entries" events.

type EntryIssue 

type EntryIssue struct {
	Index   int    `json:"index"`
	Field   string `json:"field"`
	Message string `json:"message"`
	IsError bool   `json:"is_error"` // false = warning
}

EntryIssue describes a problem found during entry validation.

func ValidateEntries 

func ValidateEntries(entries []RawEntry) []EntryIssue

ValidateEntries checks a batch of entries and returns all issues found. Returns nil if all entries are valid.

func (EntryIssue) String 

func (i EntryIssue) String() string

type Event 

type Event struct {
	Event   string          `json:"event"` // "entries"
	AgentID string          `json:"agent_id"`
	Data    json.RawMessage `json:"data"`
}

Event is an adapter-initiated push message (no request ID).

type FindSessionParams 

type FindSessionParams struct {
	AgentID        string `json:"agent_id"`
	RepoID         string `json:"repo_id"`
	TeamID         string `json:"team_id,omitempty"`
	RepoRoot       string `json:"repo_root"`
	Since          string `json:"since"`                      // RFC3339
	AgentSessionID string `json:"agent_session_id,omitempty"` // native session ID from agent, enables direct file lookup
}

FindSessionParams are the params for the find-session serve method.

type FindSessionResult 

type FindSessionResult struct {
	SessionFile string `json:"session_file"`
	Offset      int64  `json:"offset"`
}

FindSessionResult is the result for the find-session serve method.

type HookParams 

type HookParams struct {
	RepoRoot string `json:"repo_root"`
	Scope    string `json:"scope"` // "project" or "user"
}

HookParams are passed to install-hooks, check-hooks, and uninstall-hooks.

type ImportSessionParams 

type ImportSessionParams struct {
	SessionID string `json:"session_id"` // native session identifier (agent-specific)
	RepoRoot  string `json:"repo_root"`  // project root for context
}

ImportSessionParams are the params for the import-session one-shot command. It reads an entire session by its native agent session identifier.

type ImportSessionResult 

type ImportSessionResult struct {
	Metadata *SessionMetadata `json:"metadata,omitempty"`
	Entries  []RawEntry       `json:"entries"`
}

ImportSessionResult is the result for import-session.

type InfoResponse 

type InfoResponse struct {
	ProtocolVersion int             `json:"protocol_version"`
	Name            string          `json:"name"`
	DisplayName     string          `json:"display_name"`
	Version         string          `json:"version"`
	Type            string          `json:"type"` // "session", "vcs", "indexer", "test"
	Capabilities    []string        `json:"capabilities"`
	HookEnvValues   []string        `json:"hook_env_values,omitempty"`
	RequiredEnv     []string        `json:"required_env,omitempty"`
	ServeMode       bool            `json:"serve_mode"`
	SubagentConfig  *SubagentConfig `json:"subagent_config,omitempty"`
}

InfoResponse is returned by the `info` subcommand.

type InstallCommandsResponse added in v0.6.4 

type InstallCommandsResponse struct {
	Installed    bool     `json:"installed"`
	FilesWritten []string `json:"files_written"`
}

InstallCommandsResponse is returned by `install-commands`.

type InstallHooksResponse 

type InstallHooksResponse struct {
	Installed    bool     `json:"installed"`
	FilesWritten []string `json:"files_written"`
	Hooks        []string `json:"hooks"`
}

InstallHooksResponse is returned by `install-hooks`.

type InstallRulesResponse 

type InstallRulesResponse struct {
	Installed    bool     `json:"installed"`
	FilesWritten []string `json:"files_written"`
}

InstallRulesResponse is returned by `install-rules`.

type RPCError 

type RPCError struct {
	Code    string `json:"code"` // "method_not_found", "invalid_params", "internal_error"
	Message string `json:"message"`
}

RPCError is a structured error in serve-mode responses.

type RawEntry 

type RawEntry struct {
	Timestamp  string `json:"timestamp"` // RFC3339 UTC
	Role       string `json:"role"`      // "user" | "assistant" | "system" | "tool"
	Content    string `json:"content"`
	EID        string `json:"eid,omitempty"` // 5-char alphanumeric entry identifier
	ToolName   string `json:"tool_name,omitempty"`
	ToolInput  string `json:"tool_input,omitempty"`
	ToolOutput string `json:"tool_output,omitempty"`
	IsError    bool   `json:"is_error,omitempty"`
	CallID     string `json:"call_id,omitempty"`
}

RawEntry represents a single conversation entry from any agent.

func (*RawEntry) Check 

func (e *RawEntry) Check(index int) []EntryIssue

Check returns all issues (errors and warnings) for a single entry. The index parameter is used for error reporting (-1 if not in a batch).

func (*RawEntry) Validate 

func (e *RawEntry) Validate() error

Validate checks that a RawEntry has valid field values. Returns nil if the entry is valid.

type ReadFromOffsetParams 

type ReadFromOffsetParams struct {
	AgentID     string `json:"agent_id"`
	RepoID      string `json:"repo_id"`
	SessionFile string `json:"session_file"`
	Offset      int64  `json:"offset"`
}

ReadFromOffsetParams are the params for read-from-offset.

type ReadFromOffsetResult 

type ReadFromOffsetResult struct {
	Entries   []RawEntry `json:"entries"`
	NewOffset int64      `json:"new_offset"`
}

ReadFromOffsetResult is the result for read-from-offset.

type ReadMetadataResult 

type ReadMetadataResult struct {
	AgentVersion string `json:"agent_version,omitempty"`
	Model        string `json:"model,omitempty"`
}

ReadMetadataResult is returned by `read-metadata`.

type ReadParams 

type ReadParams struct {
	SessionFile string `json:"session_file"`
}

ReadParams are passed to `read` and `read-metadata`.

type ReadResult 

type ReadResult struct {
	Entries  []RawEntry       `json:"entries"`
	Metadata *SessionMetadata `json:"metadata,omitempty"`
}

ReadResult is returned by `read`.

type Request 

type Request struct {
	ID     int             `json:"id"`
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
}

Request is a daemon-to-adapter request in serve mode.

type Response 

type Response struct {
	ID     int       `json:"id"`
	Result any       `json:"result,omitempty"`
	Error  *RPCError `json:"error,omitempty"`
}

Response is an adapter-to-daemon response in serve mode.

type RulesParams 

type RulesParams struct {
	RepoRoot string `json:"repo_root"`
	Version  string `json:"version"` // ox version for stamped content
}

RulesParams are passed to install-rules, check-rules, and uninstall-rules.

type SessionMetadata 

type SessionMetadata struct {
	AgentVersion string `json:"agent_version,omitempty"`
	Model        string `json:"model,omitempty"`
}

SessionMetadata contains metadata extracted from agent session files.

type SpawnSubagentParams 

type SpawnSubagentParams struct {
	WorkerID   string         `json:"worker_id"`
	AgentID    string         `json:"agent_id"`
	RepoID     string         `json:"repo_id"`
	TeamID     string         `json:"team_id,omitempty"`
	RepoRoot   string         `json:"repo_root"`
	Model      string         `json:"model,omitempty"`
	Task       string         `json:"task"`
	Context    map[string]any `json:"context,omitempty"`
	TimeoutSec int            `json:"timeout_sec,omitempty"`
}

SpawnSubagentParams are the params for the spawn-subagent serve method.

type SpawnSubagentResult 

type SpawnSubagentResult struct {
	WorkerID string `json:"worker_id"`
	Status   string `json:"status"` // "starting"
}

SpawnSubagentResult is the result for the spawn-subagent serve method.

type SubagentCompletedData 

type SubagentCompletedData struct {
	WorkerID      string   `json:"worker_id"`
	ExitCode      int      `json:"exit_code"`
	DurationSec   int      `json:"duration_sec"`
	FilesModified []string `json:"files_modified,omitempty"`
	Summary       string   `json:"summary,omitempty"`
	SessionFile   string   `json:"session_file,omitempty"`
	FinalOffset   int64    `json:"final_offset,omitempty"`
}

SubagentCompletedData is the data payload for "subagent.completed" events.

type SubagentConfig 

type SubagentConfig struct {
	MaxConcurrent  int      `json:"max_concurrent"`
	Models         []string `json:"models,omitempty"`
	DefaultModel   string   `json:"default_model,omitempty"`
	CredentialHint string   `json:"credential_hint,omitempty"`
}

SubagentConfig describes the adapter's subagent controller capabilities. Returned in InfoResponse when the adapter declares CapSubagentController.

type SubagentFailedData 

type SubagentFailedData struct {
	WorkerID    string `json:"worker_id"`
	ExitReason  string `json:"exit_reason"` // "error", "canceled", "timed_out", "adapter_crash"
	ExitCode    int    `json:"exit_code"`
	DurationSec int    `json:"duration_sec"`
	Error       string `json:"error,omitempty"`
	SessionFile string `json:"session_file,omitempty"`
}

SubagentFailedData is the data payload for "subagent.failed" events.

type SubagentProgressData 

type SubagentProgressData struct {
	WorkerID    string `json:"worker_id"`
	OutputType  string `json:"output_type"` // "tool_use", "message", "thinking", "error"
	Tool        string `json:"tool,omitempty"`
	Description string `json:"description,omitempty"`
	Offset      int64  `json:"offset,omitempty"`
}

SubagentProgressData is the data payload for "subagent.progress" events.

type SubagentStatusParams 

type SubagentStatusParams struct {
	WorkerID string `json:"worker_id"`
}

SubagentStatusParams are the params for the subagent-status serve method.

type SubagentStatusResult 

type SubagentStatusResult struct {
	WorkerID     string `json:"worker_id"`
	Status       string `json:"status"`
	StartedAt    string `json:"started_at,omitempty"`
	ElapsedSec   int    `json:"elapsed_sec,omitempty"`
	OutputLines  int    `json:"output_lines,omitempty"`
	LastActivity string `json:"last_activity,omitempty"`
}

SubagentStatusResult is the result for the subagent-status serve method.

type UninstallCommandsResponse added in v0.6.4 

type UninstallCommandsResponse struct {
	Uninstalled  bool     `json:"uninstalled"`
	FilesRemoved []string `json:"files_removed"`
}

UninstallCommandsResponse is returned by `uninstall-commands`.

type UninstallHooksResponse 

type UninstallHooksResponse struct {
	Uninstalled   bool     `json:"uninstalled"`
	FilesModified []string `json:"files_modified"`
}

UninstallHooksResponse is returned by `uninstall-hooks`.

type UninstallRulesResponse 

type UninstallRulesResponse struct {
	Uninstalled  bool     `json:"uninstalled"`
	FilesRemoved []string `json:"files_removed"`
}

UninstallRulesResponse is returned by `uninstall-rules`.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.