schema

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Jan 10, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package schema defines centaurx domain data types and request/response schemas.

Index

Constants

View Source
const AboutCopyrightMarker = "\x18"

AboutCopyrightMarker prefixes the copyright line in /version output.

View Source
const AboutLinkMarker = "\x19"

AboutLinkMarker prefixes the link line in /version output.

View Source
const AboutVersionMarker = "\x17"

AboutVersionMarker prefixes the version line in /version output.

View Source
const AgentMarker = "\x1c"

AgentMarker prefixes agent message lines (markdown-enabled).

View Source
const CommandMarker = "\x1a"

CommandMarker prefixes command execution lines (no markdown).

View Source
const DefaultBufferMaxLines = 5000

DefaultBufferMaxLines is the default per-tab buffer limit.

View Source
const HelpMarker = "\x16"

HelpMarker prefixes markdown-enabled help lines.

View Source
const ReasoningMarker = "\x1d"

ReasoningMarker prefixes reasoning lines (markdown-enabled).

View Source
const StderrMarker = "\x1f"

StderrMarker prefixes lines that originated from stderr.

View Source
const WorkedForMarker = "\x1e"

WorkedForMarker prefixes "worked for" separator lines.

Variables

View Source
var (
	// ErrInvalidRequest indicates a malformed request payload.
	ErrInvalidRequest = errors.New("invalid request")
	// ErrInvalidCodexAuth indicates the codex auth payload is invalid.
	ErrInvalidCodexAuth = errors.New("auth.json must be valid JSON")
	// ErrInvalidUser indicates an invalid user identifier.
	ErrInvalidUser = errors.New("invalid user")
	// ErrInvalidRepo indicates an invalid repo identifier.
	ErrInvalidRepo = errors.New("invalid repo")
	// ErrRepoExists indicates a repo already exists.
	ErrRepoExists = errors.New("repo already exists")
	// ErrRepoNotFound indicates a repo could not be found.
	ErrRepoNotFound = errors.New("repo not found")
	// ErrTabNotFound indicates a requested tab could not be found.
	ErrTabNotFound = errors.New("tab not found")
	// ErrNoTabs indicates no tabs exist for the user.
	ErrNoTabs = errors.New("no tabs")
	// ErrInvalidModel indicates an invalid model identifier.
	ErrInvalidModel = errors.New("invalid model")
	// ErrInvalidModelReasoningEffort indicates an invalid reasoning effort value.
	ErrInvalidModelReasoningEffort = errors.New("invalid model reasoning effort")
	// ErrEmptyPrompt indicates the prompt was empty.
	ErrEmptyPrompt = errors.New("empty prompt")
	// ErrRunnerUnavailable indicates no runner is configured.
	ErrRunnerUnavailable = errors.New("runner not configured")
	// ErrTabBusy indicates the tab is already running.
	ErrTabBusy = errors.New("tab is busy")
)

Functions

func FormatModelWithReasoning added in v0.2.0

func FormatModelWithReasoning(model ModelID, effort ModelReasoningEffort) string

FormatModelWithReasoning formats a model label that includes reasoning effort.

func ValidateUserID

func ValidateUserID(userID UserID) error

ValidateUserID ensures a user id matches [a-z0-9._-] with no normalization.

Types

type ActivateTabRequest

type ActivateTabRequest struct {
	UserID UserID
	TabID  TabID
}

ActivateTabRequest describes a request to activate a tab.

type ActivateTabResponse

type ActivateTabResponse struct {
	Tab TabSnapshot
}

ActivateTabResponse reports the activated tab snapshot.

type AppendHistoryRequest

type AppendHistoryRequest struct {
	UserID UserID
	TabID  TabID
	Entry  string
}

AppendHistoryRequest describes a request to append a history entry.

type AppendHistoryResponse

type AppendHistoryResponse struct {
	Entries []string
}

AppendHistoryResponse reports the updated history.

type AppendOutputRequest

type AppendOutputRequest struct {
	UserID UserID
	TabID  TabID
	Lines  []string
}

AppendOutputRequest describes a request to append output lines to a tab.

type AppendOutputResponse

type AppendOutputResponse struct {
	Tab TabSnapshot
}

AppendOutputResponse reports the updated tab snapshot.

type AppendSystemOutputRequest

type AppendSystemOutputRequest struct {
	UserID UserID
	Lines  []string
}

AppendSystemOutputRequest describes a request to append system output lines.

type AppendSystemOutputResponse

type AppendSystemOutputResponse struct{}

AppendSystemOutputResponse reports completion of the append.

type BufferSnapshot

type BufferSnapshot struct {
	TabID        TabID
	Lines        []string
	TotalLines   int
	ScrollOffset int
	AtBottom     bool
}

BufferSnapshot represents the current scrollback view.

type CloseTabRequest

type CloseTabRequest struct {
	UserID UserID
	TabID  TabID
}

CloseTabRequest describes a request to close a tab.

type CloseTabResponse

type CloseTabResponse struct {
	Tab TabSnapshot
}

CloseTabResponse reports the closed tab snapshot.

type CreateTabRequest

type CreateTabRequest struct {
	UserID     UserID
	RepoName   RepoName
	RepoURL    string
	CreateRepo bool
	TabName    TabName
}

CreateTabRequest describes a request to create a tab.

type CreateTabResponse

type CreateTabResponse struct {
	Tab         TabSnapshot
	RepoCreated bool
}

CreateTabResponse reports the created tab and repo status.

type ErrorEvent

type ErrorEvent struct {
	Message string `json:"message,omitempty"`
}

ErrorEvent captures stream-level errors.

type EventType

type EventType string

EventType is the top-level type emitted by codex exec --json.

const (
	// EventThreadStarted indicates a new thread/session started.
	EventThreadStarted EventType = "thread.started"
	// EventTurnStarted indicates a turn started.
	EventTurnStarted EventType = "turn.started"
	// EventTurnCompleted indicates a turn completed successfully.
	EventTurnCompleted EventType = "turn.completed"
	// EventTurnFailed indicates a turn failed.
	EventTurnFailed EventType = "turn.failed"
	// EventItemStarted indicates an item started.
	EventItemStarted EventType = "item.started"
	// EventItemUpdated indicates an item updated.
	EventItemUpdated EventType = "item.updated"
	// EventItemCompleted indicates an item completed.
	EventItemCompleted EventType = "item.completed"
	// EventError indicates a stream-level error.
	EventError EventType = "error"
)

type ExecEvent

type ExecEvent struct {
	Type     EventType       `json:"type"`
	ThreadID SessionID       `json:"thread_id,omitempty"`
	Usage    *TurnUsage      `json:"usage,omitempty"`
	Item     *ItemEvent      `json:"item,omitempty"`
	Error    *ErrorEvent     `json:"error,omitempty"`
	Message  string          `json:"message,omitempty"`
	Raw      json.RawMessage `json:"-"`
}

ExecEvent is the normalized event shape for codex exec streams.

type FileChange

type FileChange struct {
	Path string `json:"path,omitempty"`
	Kind string `json:"kind,omitempty"`
}

FileChange is a summary of a file change event.

type GetBufferRequest

type GetBufferRequest struct {
	UserID UserID
	TabID  TabID
	Limit  int
}

GetBufferRequest describes a request to fetch buffer lines.

type GetBufferResponse

type GetBufferResponse struct {
	Buffer BufferSnapshot
}

GetBufferResponse reports the buffer snapshot.

type GetHistoryRequest

type GetHistoryRequest struct {
	UserID UserID
	TabID  TabID
}

GetHistoryRequest describes a request to fetch prompt history.

type GetHistoryResponse

type GetHistoryResponse struct {
	Entries []string
}

GetHistoryResponse reports the prompt history.

type GetSystemBufferRequest

type GetSystemBufferRequest struct {
	UserID UserID
	Limit  int
}

GetSystemBufferRequest describes a request to fetch system buffer lines.

type GetSystemBufferResponse

type GetSystemBufferResponse struct {
	Buffer SystemBufferSnapshot
}

GetSystemBufferResponse reports the system buffer snapshot.

type GetTabUsageRequest

type GetTabUsageRequest struct {
	UserID UserID
	TabID  TabID
}

GetTabUsageRequest describes a request to fetch latest usage for a tab.

type GetTabUsageResponse

type GetTabUsageResponse struct {
	Usage *TurnUsage
}

GetTabUsageResponse reports the last observed usage for a tab.

type ItemEvent

type ItemEvent struct {
	ID               string          `json:"id,omitempty"`
	Type             ItemType        `json:"type,omitempty"`
	Text             string          `json:"text,omitempty"`
	Command          string          `json:"command,omitempty"`
	AggregatedOutput string          `json:"aggregated_output,omitempty"`
	ExitCode         *int            `json:"exit_code,omitempty"`
	Status           string          `json:"status,omitempty"`
	Changes          []FileChange    `json:"changes,omitempty"`
	Query            string          `json:"query,omitempty"`
	Items            []TodoItem      `json:"items,omitempty"`
	Raw              json.RawMessage `json:"-"`
}

ItemEvent captures item payloads from item.* events.

type ItemType

type ItemType string

ItemType describes the item payload type in item.* events.

const (
	// ItemAgentMessage represents assistant output.
	ItemAgentMessage ItemType = "agent_message"
	// ItemReasoning represents reasoning content.
	ItemReasoning ItemType = "reasoning"
	// ItemCommandExecution represents a command execution item.
	ItemCommandExecution ItemType = "command_execution"
	// ItemFileChange represents a file change item.
	ItemFileChange ItemType = "file_change"
	// ItemMcpToolCall represents an MCP tool call item.
	ItemMcpToolCall ItemType = "mcp_tool_call"
	// ItemWebSearch represents a web search item.
	ItemWebSearch ItemType = "web_search"
	// ItemTodoList represents a todo list item.
	ItemTodoList ItemType = "todo_list"
	// ItemError represents an error item.
	ItemError ItemType = "error"
)

type ListReposRequest

type ListReposRequest struct {
	UserID UserID
}

ListReposRequest describes a request to list repos.

type ListReposResponse

type ListReposResponse struct {
	Repos []RepoRef
}

ListReposResponse reports available repos.

type ListTabsRequest

type ListTabsRequest struct {
	UserID UserID
}

ListTabsRequest describes a request to list tabs.

type ListTabsResponse

type ListTabsResponse struct {
	Tabs       []TabSnapshot
	ActiveTab  TabID
	ActiveRepo RepoRef
	Theme      ThemeName
}

ListTabsResponse reports tabs and active context.

type ModelID

type ModelID string

ModelID identifies an LLM model.

func NormalizeModelID

func NormalizeModelID(model string) (ModelID, error)

NormalizeModelID validates and normalizes a model identifier. Allowed characters: A-Z, a-z, 0-9, '.', '_', '-'.

type ModelReasoningEffort added in v0.2.0

type ModelReasoningEffort string

ModelReasoningEffort identifies the reasoning effort level.

const (
	ModelReasoningLow    ModelReasoningEffort = "low"
	ModelReasoningMedium ModelReasoningEffort = "medium"
	ModelReasoningHigh   ModelReasoningEffort = "high"
	ModelReasoningXHigh  ModelReasoningEffort = "xhigh"
)

ModelReasoningLow and related constants define allowed reasoning effort values.

const DefaultModelReasoningEffort ModelReasoningEffort = ModelReasoningMedium

DefaultModelReasoningEffort is the default reasoning effort when none is specified.

func NormalizeModelReasoningEffort added in v0.2.0

func NormalizeModelReasoningEffort(value string) (ModelReasoningEffort, error)

NormalizeModelReasoningEffort validates and normalizes a reasoning effort value. Allowed values: low, medium, high, xhigh.

type OutputEvent

type OutputEvent struct {
	UserID UserID
	TabID  TabID
	Lines  []string
}

OutputEvent represents appended output lines for a tab.

type RenewSessionRequest

type RenewSessionRequest struct {
	UserID UserID
	TabID  TabID
}

RenewSessionRequest describes a request to reset a tab's exec session.

type RenewSessionResponse

type RenewSessionResponse struct {
	Tab TabSnapshot
}

RenewSessionResponse reports the updated tab snapshot.

type RepoName

type RepoName string

RepoName identifies a repository.

type RepoRef

type RepoRef struct {
	Name RepoName
	Path string
}

RepoRef identifies a repository available to the runner.

type SaveCodexAuthRequest

type SaveCodexAuthRequest struct {
	UserID   UserID
	AuthJSON []byte
}

SaveCodexAuthRequest describes a request to save codex auth.json contents.

type SaveCodexAuthResponse

type SaveCodexAuthResponse struct{}

SaveCodexAuthResponse reports completion of the write.

type ScrollBufferRequest

type ScrollBufferRequest struct {
	UserID UserID
	TabID  TabID
	Delta  int
	Limit  int
}

ScrollBufferRequest describes a request to scroll the buffer.

type ScrollBufferResponse

type ScrollBufferResponse struct {
	Buffer BufferSnapshot
}

ScrollBufferResponse reports the buffer snapshot after scrolling.

type SendPromptRequest

type SendPromptRequest struct {
	UserID UserID
	TabID  TabID
	Prompt string
}

SendPromptRequest describes a prompt submission.

type SendPromptResponse

type SendPromptResponse struct {
	Tab      TabSnapshot
	Accepted bool
}

SendPromptResponse reports prompt acceptance and tab state.

type ServiceConfig

type ServiceConfig struct {
	RepoRoot       string
	StateDir       string
	DefaultModel   ModelID
	AllowedModels  []ModelID
	DefaultTheme   ThemeName
	TabNameMax     int
	TabNameSuffix  string
	BufferMaxLines int
	// DisableAuditLogging disables audit trail debug logs for commands.
	DisableAuditLogging bool
}

ServiceConfig defines defaults and limits for the core service.

func NormalizeServiceConfig

func NormalizeServiceConfig(cfg ServiceConfig) (ServiceConfig, error)

NormalizeServiceConfig applies defaults and validates the config.

type SessionID

type SessionID string

SessionID identifies an exec session.

type SetModelRequest

type SetModelRequest struct {
	UserID UserID
	TabID  TabID
	Model  ModelID
	// ModelReasoningEffort optionally sets the reasoning effort for the tab.
	ModelReasoningEffort ModelReasoningEffort
}

SetModelRequest describes a request to set the model for a tab.

type SetModelResponse

type SetModelResponse struct {
	Tab TabSnapshot
}

SetModelResponse reports the updated tab snapshot.

type SetThemeRequest

type SetThemeRequest struct {
	UserID UserID
	Theme  ThemeName
}

SetThemeRequest describes a request to set the UI theme.

type SetThemeResponse

type SetThemeResponse struct {
	Theme ThemeName
}

SetThemeResponse reports the applied theme.

type StopSessionRequest

type StopSessionRequest struct {
	UserID UserID
	TabID  TabID
}

StopSessionRequest describes a request to stop a running session.

type StopSessionResponse

type StopSessionResponse struct {
	Tab TabSnapshot
}

StopSessionResponse reports the updated tab snapshot.

type SwitchRepoRequest

type SwitchRepoRequest struct {
	UserID   UserID
	TabID    TabID
	RepoName RepoName
}

SwitchRepoRequest describes a request to switch repos.

type SwitchRepoResponse

type SwitchRepoResponse struct {
	Tab TabSnapshot
}

SwitchRepoResponse reports the updated tab snapshot.

type SystemBufferSnapshot

type SystemBufferSnapshot struct {
	Lines        []string
	TotalLines   int
	ScrollOffset int
	AtBottom     bool
}

SystemBufferSnapshot represents output not tied to a tab.

type SystemOutputEvent

type SystemOutputEvent struct {
	UserID UserID
	Lines  []string
}

SystemOutputEvent represents output not tied to a tab.

type TabEvent

type TabEvent struct {
	UserID    UserID
	Type      TabEventType
	Tab       TabSnapshot
	ActiveTab TabID
	Theme     ThemeName
}

TabEvent represents a change to a tab or tab list.

type TabEventType

type TabEventType string

TabEventType describes tab lifecycle or state changes.

const (
	// TabEventCreated indicates a tab was created.
	TabEventCreated TabEventType = "created"
	// TabEventClosed indicates a tab was closed.
	TabEventClosed TabEventType = "closed"
	// TabEventActivated indicates a tab became active.
	TabEventActivated TabEventType = "activated"
	// TabEventUpdated indicates a tab was updated.
	TabEventUpdated TabEventType = "updated"
	// TabEventStatus indicates a tab status change.
	TabEventStatus TabEventType = "status"
)

type TabID

type TabID string

TabID identifies a tab session.

type TabName

type TabName string

TabName is the user-facing name of a tab.

type TabSnapshot

type TabSnapshot struct {
	ID                   TabID
	Name                 TabName
	Repo                 RepoRef
	Model                ModelID
	ModelReasoningEffort ModelReasoningEffort
	SessionID            SessionID
	Status               TabStatus
	Active               bool
}

TabSnapshot is a read-only view of tab state for transports.

type TabStatus

type TabStatus string

TabStatus describes the current state of a tab session.

const (
	// TabStatusIdle indicates a tab is idle.
	TabStatusIdle TabStatus = "idle"
	// TabStatusRunning indicates a tab is processing a prompt or command.
	TabStatusRunning TabStatus = "running"
	// TabStatusStopped indicates a tab has been stopped.
	TabStatusStopped TabStatus = "stopped"
)

type ThemeName

type ThemeName string

ThemeName identifies a UI theme.

const DefaultTheme ThemeName = "outrun"

DefaultTheme is the default UI theme name.

func AvailableThemes

func AvailableThemes() []ThemeName

AvailableThemes returns the supported theme names.

func NormalizeThemeName

func NormalizeThemeName(name string) (ThemeName, bool)

NormalizeThemeName returns a canonical theme name if supported.

type TodoItem

type TodoItem struct {
	Text      string `json:"text,omitempty"`
	Completed bool   `json:"completed,omitempty"`
}

TodoItem is a checklist entry for todo_list items.

type TurnUsage

type TurnUsage struct {
	InputTokens       int `json:"input_tokens,omitempty"`
	CachedInputTokens int `json:"cached_input_tokens,omitempty"`
	OutputTokens      int `json:"output_tokens,omitempty"`
}

TurnUsage captures token usage reported by codex.

type UserID

type UserID string

UserID identifies a user in the system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL