agentconfig

Documentation

Overview

Package agentconfig implements the canonical agent configuration standard: one source of truth for Providers, Models and MCP Servers, plus adapters that generate each supported coding agent's native configuration (OpenCode, Pi, Oh My Pi, Claude Code, Codex) without clobbering settings the adapters do not manage.

Merge rules (CONTRACT: "merge, don't clobber"): adapters only write the sections they own. Existing entries in native files that the canonical config does not know about (per-agent servers, unrelated settings) are preserved untouched.

Index

• Constants
• func AllTargets() []string
• func ImportMCPRow(base *Config, id, transport, url, envJSON string, enabled bool) error
• func WriteFiles(files []OutFile) ([]string, error)
• type Config
  • func ImportFromEngine(dataDir string, base *Config) (*Config, error)
  • func (c *Config) Render(target, home string) ([]OutFile, []string, error)
  • func (c *Config) SortedModelIDs() []string
  • func (c *Config) Validate() error
• type Defaults
• type MCPServer
  • func (s MCPServer) IsEnabled() bool
• type Model
• type OutFile
• type Provider

Constants

const (
	TargetOpenCode = "opencode"
	TargetPi       = "pi"
	TargetOMP      = "omp"
	TargetClaude   = "claude"
	TargetCodex    = "codex"
)

Targets supported by the adapters.

const (
	TransportStdio = "stdio"
	TransportHTTP  = "http"
	TransportSSE   = "sse"
)

Transport constants for MCP servers.

const (
	ProtocolChatCompletions   = "chat-completions"
	ProtocolResponses         = "responses"
	ProtocolAnthropicMessages = "anthropic-messages"
)

Protocol constants for providers.

const Version = 1

Version is the canonical schema version.

Functions

func AllTargets

func AllTargets() []string

AllTargets lists every supported agent, stable order.

func ImportMCPRow

func ImportMCPRow(base *Config, id, transport, url, envJSON string, enabled bool) error

ImportMCPRow merges one server row (host-database independent) into the canonical config. env entries shaped "header:<Name>" become HTTP headers. (host database independent) into the canonical config. env entries shaped "header:<Name>" become headers.

func WriteFiles

func WriteFiles(files []OutFile) ([]string, error)

WriteFiles writes rendered files, backing up any existing file to "<path>.bak" first.

Types

type Config

type Config struct {
	Version    int                  `json:"version"`
	Providers  map[string]Provider  `json:"providers"`
	Models     map[string]Model     `json:"models"`
	MCPServers map[string]MCPServer `json:"mcpServers"`
	Defaults   Defaults             `json:"defaults,omitempty"`
}

Config is the canonical configuration schema.

func ImportFromEngine

func ImportFromEngine(dataDir string, base *Config) (*Config, error)

ImportFromEngine seeds a canonical Config from the rakit engine home: providers_config.json (profiles + active model) and mcp_servers.json. Entries already present in base (a previously loaded canonical config) are overwritten by engine values under the same key; unknown keys in base are preserved.

func (*Config) Render

func (c *Config) Render(target, home string) ([]OutFile, []string, error)

Render generates the native configuration files for one target. existing maps target-relative well-known paths (absolute) to their current bytes so adapters can merge instead of clobber. Notes carry human-readable warnings (skipped servers, protocol caveats).

func (*Config) SortedModelIDs

func (c *Config) SortedModelIDs() []string

SortedModelIDs returns full "provider/id" identifiers in stable order.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks referential integrity of the canonical config.

type Defaults

type Defaults struct {
	Model string `json:"model,omitempty"` // "<provider>/<id>"
}

Defaults holds cross-agent default selections.

type MCPServer

type MCPServer struct {
	Transport string            `json:"transport"` // stdio | http | sse
	Command   string            `json:"command,omitempty"`
	Args      []string          `json:"args,omitempty"`
	Env       map[string]string `json:"env,omitempty"`
	URL       string            `json:"url,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	Enabled   *bool             `json:"enabled,omitempty"`
}

MCPServer is one Model Context Protocol server.

func (MCPServer) IsEnabled

func (s MCPServer) IsEnabled() bool

Enabled returns whether the server is enabled (nil = true).

type Model

type Model struct {
	Provider        string `json:"provider"`
	ID              string `json:"id"`
	Name            string `json:"name,omitempty"`
	ContextWindow   int    `json:"contextWindow,omitempty"`
	MaxOutputTokens int    `json:"maxOutputTokens,omitempty"`
	Reasoning       bool   `json:"reasoning,omitempty"`
}

Model is a named model offered by a provider. The full identifier is "<provider>/<id>".

type OutFile

type OutFile struct {
	Path    string
	Content []byte
}

OutFile is one native config file an adapter wants written.

type Provider

type Provider struct {
	Name      string `json:"name"`
	Type      string `json:"type"` // openai-compatible | anthropic
	BaseURL   string `json:"baseUrl"`
	APIKey    string `json:"apiKey,omitempty"`    // literal; file must stay 0600
	APIKeyEnv string `json:"apiKeyEnv,omitempty"` // env var name (preferred)
	Protocol  string `json:"protocol,omitempty"`  // chat-completions | responses | anthropic-messages
}

Provider is one upstream API gateway.