ext

type Action ¶ added in v0.4.0

type Action interface {
	// contains filtered or unexported methods
}

Action represents an intent requested by an extension command or shortcut. Commands enqueue actions; the TUI drains and applies them after the handler returns.

type ActionAttachImage ¶ added in v0.5.0

type ActionAttachImage struct{ Image any }

ActionAttachImage attaches an image to the next message. Image is typed as any to avoid importing core.ImageContent.

type ActionDetachImage ¶ added in v0.5.0

type ActionDetachImage struct{}

ActionDetachImage removes a pending image attachment.

type ActionExec ¶ added in v0.5.0

type ActionExec struct{ Cmd any }

ActionExec hands the terminal to an external process (e.g., $EDITOR). Cmd is typed as any to avoid importing os/exec from ext/. The TUI asserts *exec.Cmd and uses tea.ExecProcess.

type ActionNotify ¶ added in v0.4.0

type ActionNotify struct{ Message string }

ActionNotify sends a transient notification.

type ActionQuit ¶ added in v0.4.0

type ActionQuit struct{}

ActionQuit signals the TUI to exit.

type ActionRunAsync ¶ added in v0.5.0

type ActionRunAsync struct{ Fn func() Action }

ActionRunAsync runs Fn in a goroutine. The returned Action (if non-nil) is enqueued when Fn completes. Use for expensive event handler work.

type ActionSendMessage ¶ added in v0.16.8

type ActionSendMessage struct{ Content string }

ActionSendMessage injects a user message into the agent loop.

type ActionSetSessionTitle ¶ added in v0.5.0

type ActionSetSessionTitle struct{ Title string }

ActionSetSessionTitle sets the current session's title.

type ActionSetStatus ¶ added in v0.4.0

type ActionSetStatus struct{ Key, Text string }

ActionSetStatus updates a status bar widget (e.g. "model").

type ActionShowMessage ¶ added in v0.4.0

type ActionShowMessage struct{ Text string }

ActionShowMessage displays a message in the conversation view.

type ActionShowPicker ¶ added in v0.4.0

type ActionShowPicker struct {
	Title    string
	Items    []PickerItem
	OnSelect func(PickerItem)
}

ActionShowPicker opens a modal picker.

type ActionSwapSession ¶ added in v0.4.0

type ActionSwapSession struct{ Session any }

ActionSwapSession replaces the active session. Session is typed as any to avoid importing session/ from ext/.

type AgentAPI ¶

type AgentAPI interface {
	AgentReader
	AgentWriter
}

AgentAPI is the subset of *core.Agent that the extension runtime needs. Using an interface keeps ext/ from depending on agent implementation details.

Removed from interface (used only via *core.Agent in tui/ and cmd/):

• SetTools, SetTurnContext, IsRunning

type AgentReader ¶ added in v0.16.8

type AgentReader interface {
	Messages() []core.Message
	StepMode() bool
	Provider() core.StreamProvider
	System() string
}

AgentReader provides read-only access to agent state.

type AgentWriter ¶ added in v0.16.8

type AgentWriter interface {
	Steer(msg core.Message)
	FollowUp(msg core.Message)
	SetModel(m core.Model)
	SetProvider(p core.StreamProvider)
	SetMessages(msgs []core.Message)
	SetStepMode(on bool)
}

AgentWriter provides mutation access to the agent.

type App ¶

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

App is the single extension API surface. Extensions receive this in their factory function and call methods to register tools, commands, etc.

After registration, Bind() wires the runtime references (agent, session) so runtime methods like SendMessage() and Model() work.

CAPABILITY GATE — before adding a new callback or field to App, answer:

1. Can this be a Tool? → RegisterTool (agent-callable action)
2. Can this be a Command? → RegisterCommand (user-invoked /slash)
3. Can this be a Shortcut? → RegisterShortcut (keyboard binding)
4. Can this be a PromptSection? → RegisterPromptSection (system prompt injection)
5. Can this be an Interceptor? → RegisterInterceptor (before/after tool hook)
6. Can this be a MessageHook? → RegisterMessageHook (before user message reaches LLM)

Only add a new BindOption/callback when NONE of the above apply — typically for TUI-specific lifecycle that extensions cannot express through existing primitives (e.g. session swapping, background agent management). See ext/architecture_test.go for automated boundary enforcement.

func NewApp(cwd string) *App

func (a *App) AvailableModels() []core.Model

func (a *App) BackgroundSafeTools() []core.Tool

func (a *App) Bind(agent AgentAPI, opts ...BindOption)

func (a *App) CWD() string

func (a *App) CancelBackground()

func (a *App) Commands() map[string]*Command

func (a *App) Compactor() *Compactor

func (a *App) ConversationMessages() []core.Message

func (a *App) CoreTools() []core.Tool

func (a *App) DispatchEvent(ctx context.Context, evt core.Event)

func (a *App) EnqueueAction(action Action)

func (a *App) ExtInfos() []ExtInfo

func (a *App) FindTool(name string) *core.Tool

func (a *App) ForkSession() (string, int, error)

func (a *App) IsBackgroundRunning() bool

func (a *App) LoadSession(path string) error

func (a *App) Notify(msg string)

func (a *App) PendingActions() []Action

func (a *App) PromptSections() []PromptSection

func (a *App) Provider() core.StreamProvider

func (a *App) Providers() map[string]*ProviderConfig

func (a *App) RegisterCommand(c *Command)

func (a *App) RegisterCompactor(c Compactor)

func (a *App) RegisterEventHandler(h EventHandler)

func (a *App) RegisterExtInfo(info ExtInfo)

func (a *App) RegisterInterceptor(i Interceptor)

func (a *App) RegisterMessageHook(h MessageHook)

func (a *App) RegisterPromptSection(s PromptSection)

func (a *App) RegisterProvider(name string, cfg *ProviderConfig)

func (a *App) RegisterRenderer(typ string, r Renderer)

func (a *App) RegisterShortcut(s *Shortcut)

func (a *App) RegisterStatusSection(s StatusSection)

func (a *App) RegisterStreamProvider(api string, factory StreamProviderFactory)

func (a *App) RegisterTool(t *ToolDef)

func (a *App) Renderers() map[string]Renderer

func (a *App) RequestQuit()

func (a *App) ResolveModel(id string) (core.Model, core.StreamProvider, error)

func (a *App) RunBackground(prompt string) error

func (a *App) RunMessageHooks(ctx context.Context, msg string) ([]string, error)

func (a *App) SendMessage(content string)

func (a *App) SessionTitle() string

func (a *App) Sessions() ([]SessionSummary, error)

func (a *App) SetConversationMessages(msgs []core.Message)

func (a *App) SetModel(m core.Model)

func (a *App) SetProvider(p core.StreamProvider)

func (a *App) SetSessionTitle(title string) error

func (a *App) SetStatus(key, text string)

func (a *App) Shortcuts() map[string]*Shortcut

func (a *App) ShowMessage(text string)

func (a *App) ShowPicker(title string, items []PickerItem, onSelect func(PickerItem))

func (a *App) StatusSections() []StatusSection

func (a *App) Steer(content string)

func (a *App) StreamProvider(api string, model core.Model) (core.StreamProvider, bool)

func (a *App) SwitchModel(id string) error

func (a *App) SyncModels() (int, error)

func (a *App) SystemPrompt() string

func (a *App) ToggleStepMode() bool

func (a *App) ToolDefs() []*ToolDef

func (a *App) Tools() []string

func (a *App) UnregisterExtension(name string)

type BindOption ¶

type BindOption func(*App)

BindOption configures optional runtime callbacks for sync operations that cannot be expressed as fire-and-forget actions.

func WithCancelBackground(fn func()) BindOption

func WithIsBackgroundRunning(fn func() bool) BindOption

func WithModelManager(mm ModelManager) BindOption

func WithRunBackground(fn func(prompt string) error) BindOption

func WithSessionManager(sm SessionManager) BindOption

type Command ¶

type Command struct {
	Name        string
	Description string
	Handler     func(args string, app *App) error
	Complete    func(prefix string) []string // tab completion; nil = no completion
	Immediate   bool                         // if true, executes during streaming without queuing
}

Command is a slash command registered by an extension.

type Compactor ¶ added in v0.5.0

type Compactor struct {
	Name      string
	Threshold int // token threshold for auto-compact; 0 = use config default
	Compact   func(ctx context.Context, messages []core.Message) ([]core.Message, error)
}

Compactor controls conversation compaction (summarization to save tokens). Register one via App.RegisterCompactor. The Compact function receives all messages and returns the compacted set — giving full control over what to keep and how to summarize.

type EventHandler ¶ added in v0.5.0

type EventHandler struct {
	Name     string
	Priority int

	// Filter limits which events this handler sees. nil = all events.
	Filter func(core.Event) bool

	// Handle processes the event. Returns an optional Action to enqueue.
	// Return nil for no action.
	Handle func(ctx context.Context, evt core.Event) Action
}

EventHandler reacts to agent lifecycle events (Observe primitive). Lower priority runs first. Handle must be fast (<50ms) — return ActionRunAsync for expensive work.

type ExtInfo ¶ added in v0.2.0

type ExtInfo struct {
	Name            string   // human-readable name
	Version         string   // semver or empty
	Kind            string   // "builtin" or "external"
	Runtime         string   // "go", "bun", "node", "python", etc.
	Tools           []string // tool names registered by this extension
	Commands        []string // command names registered by this extension
	Interceptors    []string // interceptor names
	EventHandlers   []string // event handler names
	Shortcuts       []string // shortcut keys
	MessageHooks    []string // message hook names
	Compactor       string   // compactor name, empty if none
	PromptSections  []string // prompt section titles
	StreamProviders []string // stream provider API types (e.g. "openai")
}

ExtInfo describes a loaded extension for /extensions listing.

type Extension ¶

type Extension func(app *App) error

Extension is a function that registers tools, commands, interceptors, etc. Built-in tools and external extensions use the same signature.

type Interceptor ¶

type Interceptor struct {
	Name     string
	Priority int

	// Before is called before tool execution.
	// Return allow=false to block the tool call.
	// Return modified args to transform input.
	Before func(ctx context.Context, toolName string, args map[string]any) (allow bool, modifiedArgs map[string]any, err error)

	// After is called after tool execution.
	// Return modified result to transform output.
	After func(ctx context.Context, toolName string, result any) (any, error)
}

Interceptor wraps tool execution with before/after hooks. Higher priority runs first. Use priority 2000+ for security, 1000+ for logging.

type InterruptBehavior ¶ added in v0.17.0

type InterruptBehavior int

InterruptBehavior controls how a tool reacts to steering (mid-turn user input).

const (
	// InterruptCancel cancels the tool on steer and discards its result (default).
	InterruptCancel InterruptBehavior = iota
	// InterruptBlock keeps the tool running when steered; the steer is queued
	// for after the tool completes.
	InterruptBlock
)

type MessageHook ¶ added in v0.5.0

type MessageHook struct {
	Name     string
	Priority int

	// OnMessage sees the user message before the LLM call.
	// Returns additional context to inject for this turn only (ephemeral).
	// Empty string = no injection. Error = abort the message.
	OnMessage func(ctx context.Context, msg string) (string, error)
}

MessageHook runs before a user message is sent to the LLM. Lower priority runs first (same convention as prompt sections).

type ModelManager ¶ added in v0.4.0

type ModelManager interface {
	// Available returns all registered models.
	Available() []core.Model

	// Switch activates a model by its "provider/id" key.
	// Returns the model and a configured streaming provider.
	// The implementation handles provider creation and auth.
	Switch(id string) (core.Model, core.StreamProvider, error)

	// Sync updates the model catalog from an external source (e.g. models.dev).
	// Returns the number of models updated.
	Sync() (updated int, err error)
}

ModelManager provides model operations to commands and extensions. Implemented by the wiring layer which imports provider/ and config/.

type PickerItem ¶

type PickerItem struct {
	ID    string
	Label string
	Desc  string
}

PickerItem is an item in a picker/modal list. Used by commands to request a selection UI from the TUI.

type PromptSection ¶

type PromptSection struct {
	Title     string // section heading (e.g. "Code Style")
	Content   string // markdown content
	Order     int    // lower = earlier in prompt; default 0
	TokenHint int    // estimated token count; 0 = unknown
}

PromptSection is a block of text injected into the system prompt. Extensions use this to add instructions, guidelines, or context.

type ProviderConfig ¶

type ProviderConfig struct {
	BaseURL string
	APIKey  string
	API     core.API
	Models  []core.Model
	Headers map[string]string
}

ProviderConfig registers a custom LLM provider from an extension.

type Renderer ¶

type Renderer func(message any, expanded bool) string

Renderer renders a custom message type for display. expanded controls whether the message is shown in full or collapsed.

type SessionManager ¶ added in v0.4.0

type SessionManager interface {
	// List returns all sessions, newest first.
	List() ([]SessionSummary, error)

	// Load opens a session by path.
	// Returns an opaque session handle for ActionSwapSession.
	Load(path string) (any, error)

	// Fork creates a branch of the current session.
	// Returns the parent short ID, forked session handle, message count, and any error.
	Fork() (parentID string, forked any, count int, err error)

	// SetTitle updates the current session's title.
	SetTitle(title string) error

	// Title returns the current session's title (empty if not set).
	Title() string
}

SessionManager provides session operations to commands and extensions. Implemented by the wiring layer (main.go/tui) which imports session/.

type SessionSummary ¶ added in v0.4.0

type SessionSummary struct {
	ID        string
	Path      string
	Title     string
	Model     string
	CWD       string
	CreatedAt time.Time
	Messages  int
	ParentID  string
}

SessionSummary is the ext-layer view of a session. Mirrors session.Summary without importing session/.

type Shortcut ¶

type Shortcut struct {
	Key         string // e.g. "ctrl+g"
	Description string
	Handler     func(app *App) (Action, error)
}

Shortcut is a keyboard shortcut registered by an extension.

type StatusSection ¶ added in v0.5.0

type StatusSection struct {
	Key   string     // unique key (e.g. "model", "tokens", "cost")
	Side  StatusSide // left or right side of status bar
	Order int        // lower = rendered first within the side
}

StatusSection defines an extensible status bar segment. Register via App.RegisterStatusSection. The TUI renders all registered sections sorted by Order within each side (left/right).

type StatusSide ¶ added in v0.5.0

type StatusSide int

StatusSide determines which side of the status bar a section appears on.

const (
	StatusLeft StatusSide = iota
	StatusRight
)

type StreamProviderFactory ¶ added in v0.16.11

type StreamProviderFactory func(model core.Model) core.StreamProvider

StreamProviderFactory creates a StreamProvider configured for a specific model. Registered per API type; called each time the agent selects a model served by that API.

type ToolDef ¶

type ToolDef struct {
	core.ToolSchema

	// Execute runs the tool. Same signature as core.ToolExecuteFn.
	Execute func(ctx context.Context, id string, args map[string]any) (*core.ToolResult, error)

	// PromptHint is a one-liner injected into the system prompt.
	// Example: "Read file contents with line numbers"
	PromptHint string

	// PromptGuides are bullets injected into the system prompt guidelines.
	// Example: ["Use offset/limit for files >2000 lines", "Prefer grep to find content"]
	PromptGuides []string

	// BackgroundSafe marks this tool as safe for background agent use (read-only).
	BackgroundSafe bool

	// ConcurrencySafe returns true if this tool call is safe to run concurrently
	// with other tool calls. Return false for destructive/mutating operations.
	// nil means always safe (default: parallel execution).
	ConcurrencySafe func(args map[string]any) bool

	// InterruptBehavior controls how this tool reacts to steering.
	// InterruptBlock keeps the tool running; InterruptCancel (default) cancels it.
	InterruptBehavior InterruptBehavior

	// Deferred marks this tool as rarely used. Only name+description sent in API schemas.
	// Full schema available via tool_search.
	Deferred bool
}

ToolDef extends core.ToolSchema with execution and optional UI rendering.