Documentation
¶
Overview ¶
Package app assembles codebot. App holds process-wide state (settings, models, permissions, extensions, MCP) and the current Conversation, which holds per-session state. Frontends use only these two types.
Index ¶
- Constants
- func ErrorText(err error) string
- func HiddenToolCall(tool string, args json.RawMessage) bool
- func Printable(s string) string
- func UserText(m agentcore.Message) (text string, ok bool)
- type AgentHub
- func (h *AgentHub) ActiveAgents() []string
- func (h *AgentHub) IsActive(agentName string) bool
- func (h *AgentHub) KnownAgents() []AgentInfo
- func (h *AgentHub) MarkStopped(agentName string)
- func (h *AgentHub) Publish(agentName string, ev agentcore.Event)
- func (h *AgentHub) Subscribe(agentName string) ([]agentcore.Event, <-chan agentcore.Event, func())
- type AgentInfo
- type App
- func (a *App) AcceptPlugin(ctx context.Context, o *PluginOffer) (ReloadReport, error)
- func (a *App) Close()
- func (a *App) Connect(ctx context.Context) MCPReport
- func (a *App) Current() *Conversation
- func (a *App) Cwd() string
- func (a *App) DenyTrust(ctx context.Context) (ReloadReport, error)
- func (a *App) Extensions() *Extensions
- func (a *App) InstallPlugins(ctx context.Context) (offers []*PluginOffer, fetched []string, errs []error)
- func (a *App) LoginMCP(ctx context.Context, name string) (*MCPLogin, error)
- func (a *App) LogoutMCP(ctx context.Context, name string) (MCPReport, error)
- func (a *App) MCPStatus(ctx context.Context) []MCPServer
- func (a *App) Mode() interact.Mode
- func (a *App) ModelFacts(prov, name string) (catalog.Model, bool)
- func (a *App) OfferPlugin(ctx context.Context, source string, project bool) (*PluginOffer, error)
- func (a *App) Open(id string) (*Conversation, error)
- func (a *App) PluginUpdates(ctx context.Context) []string
- func (a *App) Plugins() []Plugin
- func (a *App) Reload(ctx context.Context) (ReloadReport, error)
- func (a *App) RemovePlugin(ctx context.Context, ref string, project bool) (ReloadReport, error)
- func (a *App) Sessions() ([]SessionInfo, error)
- func (a *App) SetMode(m interact.Mode)
- func (a *App) SetTrust(ctx context.Context, shown, agreed Surface) (ReloadReport, error)
- func (a *App) Settings() config.Resolved
- func (a *App) Subscribe(fn func(Event)) (unsubscribe func())
- func (a *App) ThinkingLevels(prov, name string) []string
- func (a *App) Trust() Trust
- func (a *App) UpdatePlugins(ctx context.Context, ref string) ([]PluginUpdate, error)
- type Conversation
- func (c *Conversation) Agents() *AgentHub
- func (c *Conversation) Cancel()
- func (c *Conversation) Compact(ctx context.Context) error
- func (c *Conversation) Cwd() string
- func (c *Conversation) Diff() (string, error)
- func (c *Conversation) EnterWorktree(name string) (string, error)
- func (c *Conversation) ExitWorktree(discard bool) (WorktreeExit, error)
- func (c *Conversation) GitBranch() string
- func (c *Conversation) History() []agentcore.Message
- func (c *Conversation) ID() string
- func (c *Conversation) InvokeSkill(ctx context.Context, name, args string) (string, error)
- func (c *Conversation) Query(ctx context.Context, question string) (string, error)
- func (c *Conversation) Redo() (changed []string, ok bool, err error)
- func (c *Conversation) Reload()
- func (c *Conversation) SetModel(prov, name, effort string) error
- func (c *Conversation) Skills() []Skill
- func (c *Conversation) Status() Status
- func (c *Conversation) Submit(ctx context.Context, blocks []litellm.Block) error
- func (c *Conversation) Subscribe(fn func(session.Event)) (unsubscribe func())
- func (c *Conversation) Suggest(ctx context.Context) (string, error)
- func (c *Conversation) Tasks() *task.Runtime
- func (c *Conversation) Undo() (changed []string, ok bool, err error)
- func (c *Conversation) Wait(ctx context.Context) error
- func (c *Conversation) Worktree() string
- type Event
- type Extensions
- type Kind
- type MCPLogin
- type MCPReport
- type MCPServer
- type ModelFactory
- type Options
- type Plugin
- type PluginContent
- type PluginOffer
- type PluginUpdate
- type ReloadReport
- type SessionInfo
- type Skill
- type Status
- type Surface
- type Trust
- type WorktreeExit
Constants ¶
const ( PluginOn = extension.PluginOn PluginShadowed = extension.PluginShadowed PluginUntrusted = extension.PluginUntrusted PluginNotInstalled = extension.PluginNotInstalled PluginNotCached = extension.PluginNotCached PluginWaiting = extension.PluginWaiting PluginBroken = extension.PluginBroken )
Variables ¶
This section is empty.
Functions ¶
func ErrorText ¶
ErrorText formats err for the user. Actionable provider errors become a hint; other provider errors lose the vendor's error code. Context wrapped around the provider error is kept.
func HiddenToolCall ¶
func HiddenToolCall(tool string, args json.RawMessage) bool
HiddenToolCall reports bookkeeping calls that frontends leave out of the transcript: todo_write, shown as the todo list, and auto-memory reads, which load context the way AGENTS.md does.
Types ¶
type AgentHub ¶
type AgentHub struct {
// contains filtered or unexported fields
}
AgentHub fans out events from background sub-agent runs to observers such as the TUI. Publishing never blocks a run: a slow subscriber loses its oldest events. Each agent's events, except streamed deltas (the following MessageEnd repeats them), are kept in a bounded ring, so a late subscriber still sees the history, even of a finished agent.
func NewAgentHub ¶
func NewAgentHub() *AgentHub
func (*AgentHub) ActiveAgents ¶
func (*AgentHub) KnownAgents ¶
KnownAgents includes finished agents.
func (*AgentHub) MarkStopped ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
func (*App) AcceptPlugin ¶
func (a *App) AcceptPlugin(ctx context.Context, o *PluginOffer) (ReloadReport, error)
AcceptPlugin agrees to everything the plugin runs at the offered commit, then declares the plugin in the settings if needed. A plugin the user adds to the project is also trusted as a project item, since they wrote it there.
func (*App) Current ¶
func (a *App) Current() *Conversation
func (*App) DenyTrust ¶
func (a *App) DenyTrust(ctx context.Context) (ReloadReport, error)
DenyTrust marks the project untrusted: nothing it runs takes effect and the user is not asked again. The extensions then reload.
func (*App) Extensions ¶
func (a *App) Extensions() *Extensions
func (*App) InstallPlugins ¶
func (a *App) InstallPlugins(ctx context.Context) (offers []*PluginOffer, fetched []string, errs []error)
InstallPlugins readies declared plugins. An agreed git plugin missing from the cache is fetched at its commit. A plugin not yet agreed to, or running something new, is returned as an offer. The extensions reload if anything was fetched.
func (*App) OfferPlugin ¶
OfferPlugin reads the plugin at source: a git repository at its ref, or a directory relative to the working directory. AcceptPlugin then adds it to the user's settings, or the project's if project is set.
func (*App) Open ¶
func (a *App) Open(id string) (*Conversation, error)
Open replaces the current conversation with session id, or with a new session when id is "". On error the current conversation stays open.
func (*App) PluginUpdates ¶
PluginUpdates names the git plugins whose ref has moved past the agreed commit. It only queries the remotes, without fetching; a remote that does not answer is skipped silently.
func (*App) Plugins ¶
Plugins lists command-line plugins first, then those declared in settings, the project's before the user's.
func (*App) Reload ¶
func (a *App) Reload(ctx context.Context) (ReloadReport, error)
Reload rereads extensions and permission rules and restarts all MCP servers, including those of plugins under development. The conversation picks them up on its next run; other settings need a codebot restart.
func (*App) RemovePlugin ¶
RemovePlugin removes the plugin, by name or source, from the user's or the project's settings. Its consent and data stay, since another project may still declare it.
func (*App) Sessions ¶
func (a *App) Sessions() ([]SessionInfo, error)
Sessions returns the workspace's sessions, newest first.
func (*App) SetTrust ¶
SetTrust records the user's decision on the shown part of the project's surface: agreed is accepted and the rest of shown is declined. The extensions then reload.
func (*App) Subscribe ¶
Subscribe delivers App events and the current conversation's events, following it across Open, one at a time in order. fn runs on the goroutine that caused the event. It must not cause another event (switch the mode, open a conversation) or wait on the conversation.
func (*App) ThinkingLevels ¶
ThinkingLevels includes "" for the provider default.
func (*App) UpdatePlugins ¶
UpdatePlugins fetches agreed git plugins at their refs, or only the one ref names. An update that runs nothing new applies at once; the others wait for the user's consent.
type Conversation ¶
type Conversation struct {
// contains filtered or unexported fields
}
Conversation holds everything that lives as long as one session. Opening another session replaces the whole Conversation; nothing is reset.
func (*Conversation) Agents ¶
func (c *Conversation) Agents() *AgentHub
func (*Conversation) Cancel ¶
func (c *Conversation) Cancel()
func (*Conversation) Cwd ¶
func (c *Conversation) Cwd() string
Cwd is the workspace, or the worktree the agent entered.
func (*Conversation) Diff ¶
func (c *Conversation) Diff() (string, error)
Diff previews what Undo would revert.
func (*Conversation) EnterWorktree ¶
func (c *Conversation) EnterWorktree(name string) (string, error)
func (*Conversation) ExitWorktree ¶
func (c *Conversation) ExitWorktree(discard bool) (WorktreeExit, error)
ExitWorktree keeps a sandbox with uncommitted changes for review unless discard is set; otherwise it removes the sandbox and its branch. git refuses to drop a branch with unmerged commits.
func (*Conversation) GitBranch ¶
func (c *Conversation) GitBranch() string
GitBranch returns "" outside a repository.
func (*Conversation) History ¶
func (c *Conversation) History() []agentcore.Message
func (*Conversation) ID ¶
func (c *Conversation) ID() string
func (*Conversation) InvokeSkill ¶
InvokeSkill submits an inline skill as user input. A forked skill runs in a sub-agent and its output is returned.
func (*Conversation) Query ¶
Query answers a side question without adding to the history. It keeps the conversation's reasoning settings, because a request with different ones misses the prompt cache.
func (*Conversation) Reload ¶
func (c *Conversation) Reload()
Reload applies the App's reloaded extensions and re-reads the workspace. The model learns what changed when the next run starts.
func (*Conversation) SetModel ¶
func (c *Conversation) SetModel(prov, name, effort string) error
SetModel also saves the choice as the default in the user's settings. An empty effort means the provider default.
func (*Conversation) Skills ¶
func (c *Conversation) Skills() []Skill
func (*Conversation) Status ¶
func (c *Conversation) Status() Status
func (*Conversation) Submit ¶
Submit runs UserPromptSubmit hooks first: a blocking hook rejects the input, and context they add is posted before it.
func (*Conversation) Subscribe ¶
func (c *Conversation) Subscribe(fn func(session.Event)) (unsubscribe func())
func (*Conversation) Suggest ¶
func (c *Conversation) Suggest(ctx context.Context) (string, error)
Suggest predicts the user's next input, or "" when nothing fits. Like Query, it keeps the conversation's reasoning settings.
func (*Conversation) Tasks ¶
func (c *Conversation) Tasks() *task.Runtime
func (*Conversation) Undo ¶
func (c *Conversation) Undo() (changed []string, ok bool, err error)
Undo reverts the most recent run that changed files. ok is false when there is nothing to undo.
func (*Conversation) Worktree ¶
func (c *Conversation) Worktree() string
type Extensions ¶
type Kind ¶
type Kind int
const ( // SessionEvent carries an event of Conversation in Session. It can // arrive after Conversation was replaced or the App closed. SessionEvent Kind = iota // Opened means Conversation is now the current one. Opened // ModeChanged carries the new permission mode in Mode. ModeChanged MCPChanged // Reloaded means the extensions, including project trust, reloaded. Reloaded )
type MCPLogin ¶
type MCPLogin struct {
URL string // the page to open
// contains filtered or unexported fields
}
MCPLogin is an OAuth login waiting for the user to authorize in a browser.
type MCPServer ¶
type MCPServer = mcp.ServerStatus
type Options ¶
type Options struct {
Cwd string
Mode interact.Mode
// Resume is a session ID; "" starts a new session.
Resume string
UI interact.UI
// Interactive enables ask_user; headless frontends have no one to ask.
Interactive bool
// CacheTTL is passed as litellm.CacheControl.TTL. Use "1h" when a person
// is in the loop: they pause longer than the default five minutes.
CacheTTL string
// FS backs read, write and edit; nil means the local filesystem.
FS agentcoretools.FS
// NewModel overrides how models are built; nil uses litellm.
NewModel ModelFactory
// Trust trusts the project and the plugins it declares for this process,
// ignoring saved consent.
Trust bool
// PluginDirs are local plugins under development, loaded for this
// process only with everything they run allowed.
PluginDirs []string
}
type PluginContent ¶
type PluginOffer ¶
type PluginOffer struct {
// Source is the plugin's source as written in the settings of Scope.
Source string
Scope extension.Scope
Commit string
*plugin.Plugin
// Surface is everything the plugin runs; New is the part the user has
// not agreed to.
Surface, New Surface
// Problems are the parts that failed to load and were left out.
Problems []error
// contains filtered or unexported fields
}
PluginOffer is a plugin awaiting the user's consent: a new plugin, a declared one that runs something not agreed to, or a newer commit of a git plugin. It is taken or left as a whole.
type PluginUpdate ¶
type PluginUpdate struct {
Plugin Plugin
// Commit equals the plugin's own commit when it is up to date.
Commit string
// Offer is set when the new commit runs something the user has not
// agreed to; the plugin stays on its old commit until AcceptPlugin.
// When nil, the new commit was applied.
Offer *PluginOffer
Err error
}
type ReloadReport ¶
type SessionInfo ¶
type SessionInfo = storage.SessionInfo
type Status ¶
type Status struct {
session.Status
Mode interact.Mode
Cwd string
Worktree string // sandbox directory; "" outside a worktree
Tasks int // running background tasks
// SmallModel runs the explore sub-agent.
SmallModel string
// Reasoning reports whether the model accepts a reasoning effort. An
// empty Effort means the provider default.
Reasoning bool
}