agent

package
v0.3.49 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// OpenCode role agent names installed by the hooks.OpenCodeInstaller and
	// selected by OpenCode.BuildCmd.
	OpenCodeMasterAgentName     = "questmaster-master"
	OpenCodeStandaloneAgentName = "questmaster-standalone"
	OpenCodeWorkerAgentName     = "questmaster-worker"
)

Variables

This section is empty.

Functions

func CodexDefaultModel added in v0.3.49 

func CodexDefaultModel(role SessionRole) string

CodexDefaultModel returns the role's built-in Codex model.

func UsesCodexFilter added in v0.3.36 

func UsesCodexFilter(name string) bool

UsesCodexFilter reports whether the named agent's pane should be read with the Codex-specific line filter.

func UsesHookActivityState added in v0.3.36 

func UsesHookActivityState(name string) bool

UsesHookActivityState reports whether the named agent's activity state is driven by a hook/sidecar/plugin event stream that callers consume (Pi, OpenCode) rather than by reading the pane directly.

func UsesSidecarState added in v0.3.36 

func UsesSidecarState(name string) bool

UsesSidecarState reports whether the named agent emits the activity-sidecar event stream (Pi) and shares the rich read path.

func ValidateOpenCodeReasoningVersion added in v0.3.47 

func ValidateOpenCodeReasoningVersion(binary string) error

ValidateOpenCodeReasoningVersion ensures the per-launch variant surface is available before Questmaster creates the tmux session.

func ValidateReasoningEffort added in v0.3.47 

func ValidateReasoningEffort(provider, model, effort string) error

ValidateReasoningEffort rejects values that the selected harness cannot launch. Model-specific validation remains with the native harness.

Types

type Agent 

type Agent interface {
	Name() string
	DisplayName() string
	// Description is a one-line blurb of what the harness is good for, used to
	// assemble the master prompt's harness guide. Each agent owns its own copy
	// in its provider source file; return "" to omit it from the guide.
	Description() string
	Binary() string

	BuildCmd(opts CmdOpts) string
	ResumeKey() string
	ResumeFileName() string
	EnvVar() string
	MasterPrompt() string
	StandalonePrompt() string
	WorkerPrompt() string

	FilterPaneLines(raw string, max int) []string

	PreLaunchSetup(ctx context.Context, client TmuxClient, session string) error
	BinaryEnvVar() string
	FallbackPath() string
}

Agent represents any CLI coding agent that can run in a tmux pane.

func Resolve 

func Resolve(name string, registry *Registry) (Agent, error)

Resolve returns an agent by name, preferring the configured registry and falling back to built-in providers when the current config does not bind it.

type AgentConfig 

type AgentConfig struct {
	CLI           string `toml:"cli"`
	Model         string `toml:"model"`
	OpenCodeAgent string `toml:"opencode_agent"`
}

AgentConfig describes one configured agent provider.

type Claude 

type Claude struct {
	// contains filtered or unexported fields
}

Claude implements the built-in Claude provider.

func NewClaude 

func NewClaude(cfg AgentConfig) *Claude

NewClaude constructs a Claude provider from config.

func (Claude) Binary 

func (b Claude) Binary() string

func (Claude) BinaryEnvVar 

func (b Claude) BinaryEnvVar() string

func (*Claude) BuildCmd 

func (c *Claude) BuildCmd(opts CmdOpts) string

func (Claude) Description added in v0.3.12 

func (b Claude) Description() string

func (Claude) DisplayName 

func (b Claude) DisplayName() string

func (Claude) EnvVar 

func (b Claude) EnvVar() string

func (Claude) FallbackPath 

func (b Claude) FallbackPath() string

func (Claude) FilterPaneLines 

func (b Claude) FilterPaneLines(raw string, max int) []string

func (Claude) MasterPrompt 

func (b Claude) MasterPrompt() string

func (Claude) Name 

func (b Claude) Name() string

func (*Claude) PreLaunchSetup 

func (c *Claude) PreLaunchSetup(ctx context.Context, client TmuxClient, session string) error

PreLaunchSetup clears CLAUDECODE so a nested Claude launch starts clean. It overrides the no-op base behaviour.

func (Claude) ResumeFileName 

func (b Claude) ResumeFileName() string

func (Claude) ResumeKey 

func (b Claude) ResumeKey() string

func (Claude) StandalonePrompt 

func (b Claude) StandalonePrompt() string

func (Claude) WorkerPrompt 

func (b Claude) WorkerPrompt() string

type CmdOpts 

type CmdOpts struct {
	Binary      string
	AgentPath   string
	ResumeID    string
	Prompt      string
	SystemBrief string
	Title       string
	Role        SessionRole
	// Model is an explicit per-spawn model override. When empty, providers apply
	// their role default through resolveModel.
	Model string
	// ReasoningEffort is an explicit per-spawn reasoning override. When empty,
	// providers retain their hardcoded role default.
	ReasoningEffort string
}

CmdOpts controls agent launch command construction.

Prompt is an initial user-turn message injected after launch (what the user would type first). SystemBrief is appended after the standalone or worker system prompt so rare session-specific overrides still load as persistent identity rather than conversational input.

type Codex 

type Codex struct {
	// contains filtered or unexported fields
}

Codex implements the built-in Codex provider.

func NewCodex 

func NewCodex(cfg AgentConfig) *Codex

NewCodex constructs a Codex provider from config.

func (Codex) Binary 

func (b Codex) Binary() string

func (Codex) BinaryEnvVar 

func (b Codex) BinaryEnvVar() string

func (*Codex) BuildCmd 

func (c *Codex) BuildCmd(opts CmdOpts) string

func (Codex) Description added in v0.3.12 

func (b Codex) Description() string

func (Codex) DisplayName 

func (b Codex) DisplayName() string

func (Codex) EnvVar 

func (b Codex) EnvVar() string

func (Codex) FallbackPath 

func (b Codex) FallbackPath() string

func (Codex) FilterPaneLines 

func (b Codex) FilterPaneLines(raw string, max int) []string

func (Codex) MasterPrompt 

func (b Codex) MasterPrompt() string

func (Codex) Name 

func (b Codex) Name() string

func (Codex) PreLaunchSetup 

func (b Codex) PreLaunchSetup(context.Context, TmuxClient, string) error

func (Codex) ResumeFileName 

func (b Codex) ResumeFileName() string

func (Codex) ResumeKey 

func (b Codex) ResumeKey() string

func (Codex) StandalonePrompt 

func (b Codex) StandalonePrompt() string

func (Codex) WorkerPrompt 

func (b Codex) WorkerPrompt() string

type Config 

type Config struct {
	Agents map[string]AgentConfig `toml:"agents"`
	Roles  RolesConfig            `toml:"roles"`
}

Config is the resolved questmaster agent configuration.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the built-in Claude primary layout. The agent set is derived from providerDefs so a new built-in harness is picked up here automatically.

func LoadConfig 

func LoadConfig(overrides *ConfigOverrides) (*Config, error)

LoadConfig returns the built-in config with optional per-session role overrides applied.

type ConfigOverrides 

type ConfigOverrides struct {
	Primary string
}

ConfigOverrides are per-session role overrides.

type OpenCode added in v0.3.36 

type OpenCode struct {
	// contains filtered or unexported fields
}

OpenCode implements the built-in OpenCode provider.

OpenCode 1.17.11 has proven TUI support for --agent, --prompt, --model, and --session. It does not expose a proven role/system prompt CLI flag, so Questmaster role prompts are represented by role-specific OpenCode agent names installed by hooks.OpenCodeInstaller.

func NewOpenCode added in v0.3.36 

func NewOpenCode(cfg AgentConfig) *OpenCode

NewOpenCode constructs an OpenCode provider from config.

func (OpenCode) Binary added in v0.3.36 

func (b OpenCode) Binary() string

func (OpenCode) BinaryEnvVar added in v0.3.36 

func (b OpenCode) BinaryEnvVar() string

func (*OpenCode) BuildCmd added in v0.3.36 

func (o *OpenCode) BuildCmd(opts CmdOpts) string

func (OpenCode) Description added in v0.3.36 

func (b OpenCode) Description() string

func (OpenCode) DisplayName added in v0.3.36 

func (b OpenCode) DisplayName() string

func (OpenCode) EnvVar added in v0.3.36 

func (b OpenCode) EnvVar() string

func (OpenCode) FallbackPath added in v0.3.36 

func (b OpenCode) FallbackPath() string

func (OpenCode) FilterPaneLines added in v0.3.36 

func (b OpenCode) FilterPaneLines(raw string, max int) []string

func (OpenCode) MasterPrompt added in v0.3.36 

func (b OpenCode) MasterPrompt() string

func (OpenCode) Name added in v0.3.36 

func (b OpenCode) Name() string

func (OpenCode) PreLaunchSetup added in v0.3.36 

func (b OpenCode) PreLaunchSetup(context.Context, TmuxClient, string) error

func (OpenCode) ResumeFileName added in v0.3.36 

func (b OpenCode) ResumeFileName() string

func (OpenCode) ResumeKey added in v0.3.36 

func (b OpenCode) ResumeKey() string

func (OpenCode) StandalonePrompt added in v0.3.36 

func (b OpenCode) StandalonePrompt() string

func (OpenCode) WorkerPrompt added in v0.3.36 

func (b OpenCode) WorkerPrompt() string

type Pi 

type Pi struct {
	// contains filtered or unexported fields
}

Pi implements the built-in Pi provider.

Structured Pi read output is handled by internal/message via hook state; FilterPaneLines remains the generic fallback for other callers.

func NewPi 

func NewPi(cfg AgentConfig) *Pi

NewPi constructs a Pi provider from config.

func (Pi) Binary 

func (b Pi) Binary() string

func (Pi) BinaryEnvVar 

func (b Pi) BinaryEnvVar() string

func (*Pi) BuildCmd 

func (p *Pi) BuildCmd(opts CmdOpts) string

func (Pi) Description added in v0.3.12 

func (b Pi) Description() string

func (Pi) DisplayName 

func (b Pi) DisplayName() string

func (Pi) EnvVar 

func (b Pi) EnvVar() string

func (Pi) FallbackPath 

func (b Pi) FallbackPath() string

func (Pi) FilterPaneLines 

func (b Pi) FilterPaneLines(raw string, max int) []string

func (Pi) MasterPrompt 

func (b Pi) MasterPrompt() string

func (Pi) Name 

func (b Pi) Name() string

func (Pi) PreLaunchSetup 

func (b Pi) PreLaunchSetup(context.Context, TmuxClient, string) error

func (Pi) ResumeFileName 

func (b Pi) ResumeFileName() string

func (Pi) ResumeKey 

func (b Pi) ResumeKey() string

func (Pi) StandalonePrompt 

func (b Pi) StandalonePrompt() string

func (Pi) WorkerPrompt 

func (b Pi) WorkerPrompt() string

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry resolves configured role bindings to built-in agent providers.

func NewRegistry 

func NewRegistry(cfg *Config) (*Registry, error)

NewRegistry builds a registry from a loaded config.

func (*Registry) Bindings 

func (r *Registry) Bindings() []*RoleBinding

Bindings returns configured role bindings in primary-first order.

func (*Registry) ForRole 

func (r *Registry) ForRole(role Role) (*RoleBinding, error)

ForRole returns the binding for a configured role.

func (*Registry) Get 

func (r *Registry) Get(name string) (Agent, error)

Get returns a configured agent provider by name.

func (*Registry) Names 

func (r *Registry) Names() []string

Names returns configured agent definition names in sorted order.

type Role 

type Role string

Role identifies a logical agent slot in a session. 

const (
	RolePrimary Role = "primary"
)

type RoleBinding 

type RoleBinding struct {
	Role  Role
	Agent Agent
}

RoleBinding maps a role to an agent.

type RoleConfig 

type RoleConfig struct {
	Agent  string `toml:"agent"`
	Window int    `toml:"window"`
}

RoleConfig configures a single role binding.

type RolesConfig 

type RolesConfig struct {
	Primary *RoleConfig `toml:"primary"`
}

RolesConfig maps abstract roles to concrete agents.

type SessionRole 

type SessionRole int

SessionRole identifies the session type that determines the system prompt. 

const (
	RoleStandalone SessionRole = iota
	RoleMaster
	RoleWorker
)

type Spec added in v0.3.36 

type Spec struct {
	Name           string
	DisplayName    string
	Description    string
	DefaultCLI     string
	ResumeKey      string
	ResumeFileName string
	EnvVar         string
	BinaryEnvVar   string
	FallbackPath   string
	Filter         paneFilter
	State          StateMode
}

Spec is the static, per-agent metadata that does not vary between sessions: identity, the resume/env key naming, the binary discovery hints, and the pane-filter choice. It is the single place a new harness declares the rote half of the Agent interface; the behavioural half (BuildCmd, and any PreLaunchSetup) stays in the provider source file.

type StateMode added in v0.3.36 

type StateMode int

StateMode describes how a harness reports activity/state to questmaster. It is the single declared source for the runtime distinctions that callers (e.g. internal/message) previously hardcoded as agent-name checks. 

const (
	// StateNative covers harnesses whose pane is read directly and which do
	// not drive a hook/sidecar activity stream that callers consume for
	// structured reads or relay gating (Claude, Codex).
	StateNative StateMode = iota
	// StateSidecar covers Pi-style harnesses that emit the activity-sidecar
	// event stream (Pi) and share the rich read path.
	StateSidecar
	// StatePlugin covers harnesses whose activity state is driven by an
	// installed plugin event stream (OpenCode).
	StatePlugin
)

func StateModeOf added in v0.3.36 

func StateModeOf(name string) StateMode

StateModeOf reports how the named agent reports activity/state. Unknown agents are treated as StateNative.

type Stub 

type Stub struct {
	// contains filtered or unexported fields
}

Stub is a minimal reference provider for future agent adapters.

func NewStub 

func NewStub(cfg AgentConfig) *Stub

NewStub constructs the example stub provider.

func (*Stub) Binary 

func (s *Stub) Binary() string

func (*Stub) BinaryEnvVar 

func (s *Stub) BinaryEnvVar() string

func (*Stub) BuildCmd 

func (s *Stub) BuildCmd(CmdOpts) string

func (*Stub) Description added in v0.3.12 

func (s *Stub) Description() string

func (*Stub) DisplayName 

func (s *Stub) DisplayName() string

func (*Stub) EnvVar 

func (s *Stub) EnvVar() string

func (*Stub) FallbackPath 

func (s *Stub) FallbackPath() string

func (*Stub) FilterPaneLines 

func (s *Stub) FilterPaneLines(raw string, max int) []string

func (*Stub) MasterPrompt 

func (s *Stub) MasterPrompt() string

func (*Stub) Name 

func (s *Stub) Name() string

func (*Stub) PreLaunchSetup 

func (s *Stub) PreLaunchSetup(context.Context, TmuxClient, string) error

func (*Stub) ResumeFileName 

func (s *Stub) ResumeFileName() string

func (*Stub) ResumeKey 

func (s *Stub) ResumeKey() string

func (*Stub) StandalonePrompt 

func (s *Stub) StandalonePrompt() string

func (*Stub) WorkerPrompt 

func (s *Stub) WorkerPrompt() string

type TmuxClient 

type TmuxClient interface {
	UnsetEnvironment(ctx context.Context, session, key string) error
}

TmuxClient is the subset of tmux.Client used by agent providers.

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.