app

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 42 Imported by: 0

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

View Source
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

func ErrorText(err error) string

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.

func Printable

func Printable(s string) string

Printable escapes what a terminal would act on rather than display, for text read from files.

func UserText

func UserText(m agentcore.Message) (text string, ok bool)

UserText returns what frontends show of a user message. ok is false for harness-added messages such as context or task notifications.

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 (h *AgentHub) ActiveAgents() []string

func (*AgentHub) IsActive

func (h *AgentHub) IsActive(agentName string) bool

func (*AgentHub) KnownAgents

func (h *AgentHub) KnownAgents() []AgentInfo

KnownAgents includes finished agents.

func (*AgentHub) MarkStopped

func (h *AgentHub) MarkStopped(agentName string)

func (*AgentHub) Publish

func (h *AgentHub) Publish(agentName string, ev agentcore.Event)

Publish sends under the lock so it can't race an unsubscribe closing the channel. The sends never block.

func (*AgentHub) Subscribe

func (h *AgentHub) Subscribe(agentName string) ([]agentcore.Event, <-chan agentcore.Event, func())

Subscribe returns the agent's history, oldest first, and a channel of later events; handle the history first. cancel closes the channel.

type AgentInfo

type AgentInfo struct {
	Name   string
	Active bool
}

type App

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

func Boot

func Boot(opts Options) (*App, error)

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) Close

func (a *App) Close()

func (*App) Connect

func (a *App) Connect(ctx context.Context) MCPReport

Connect is called by frontends once they have subscribed.

func (*App) Current

func (a *App) Current() *Conversation

func (*App) Cwd

func (a *App) Cwd() string

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) LoginMCP

func (a *App) LoginMCP(ctx context.Context, name string) (*MCPLogin, error)

LoginMCP starts an OAuth login to the MCP server name.

func (*App) LogoutMCP

func (a *App) LogoutMCP(ctx context.Context, name string) (MCPReport, error)

LogoutMCP forgets the server's OAuth token and connects it again without.

func (*App) MCPStatus

func (a *App) MCPStatus(ctx context.Context) []MCPServer

func (*App) Mode

func (a *App) Mode() interact.Mode

func (*App) ModelFacts

func (a *App) ModelFacts(prov, name string) (catalog.Model, bool)

func (*App) OfferPlugin

func (a *App) OfferPlugin(ctx context.Context, source string, project bool) (*PluginOffer, error)

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

func (a *App) PluginUpdates(ctx context.Context) []string

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

func (a *App) Plugins() []Plugin

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

func (a *App) RemovePlugin(ctx context.Context, ref string, project bool) (ReloadReport, error)

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) SetMode

func (a *App) SetMode(m interact.Mode)

func (*App) SetTrust

func (a *App) SetTrust(ctx context.Context, shown, agreed Surface) (ReloadReport, error)

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) Settings

func (a *App) Settings() config.Resolved

func (*App) Subscribe

func (a *App) Subscribe(fn func(Event)) (unsubscribe func())

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

func (a *App) ThinkingLevels(prov, name string) []string

ThinkingLevels includes "" for the provider default.

func (*App) Trust

func (a *App) Trust() Trust

func (*App) UpdatePlugins

func (a *App) UpdatePlugins(ctx context.Context, ref string) ([]PluginUpdate, error)

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) Compact

func (c *Conversation) Compact(ctx context.Context) error

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

func (c *Conversation) InvokeSkill(ctx context.Context, name, args string) (string, error)

InvokeSkill submits an inline skill as user input. A forked skill runs in a sub-agent and its output is returned.

func (*Conversation) Query

func (c *Conversation) Query(ctx context.Context, question string) (string, error)

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) Redo

func (c *Conversation) Redo() (changed []string, ok bool, err error)

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

func (c *Conversation) Submit(ctx context.Context, blocks []litellm.Block) error

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) Wait

func (c *Conversation) Wait(ctx context.Context) error

func (*Conversation) Worktree

func (c *Conversation) Worktree() string

type Event

type Event struct {
	Kind         Kind
	Session      session.Event
	Conversation *Conversation
	Mode         interact.Mode
}

type Extensions

type Extensions = extension.Set

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.

func (*MCPLogin) Wait

func (l *MCPLogin) Wait(ctx context.Context) (MCPReport, error)

Wait waits for the user to authorize, then connects the servers that failed.

type MCPReport

type MCPReport struct {
	Servers   int
	Connected int
	Tools     int
	Errors    []string
	Login     []string // servers that want an OAuth login: /mcp login
}

type MCPServer

type MCPServer = mcp.ServerStatus

type ModelFactory

type ModelFactory func(provider.ModelSpec) (agentcore.Model, error)

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 Plugin

type Plugin = extension.Plugin

type PluginContent

type PluginContent = plugin.Plugin

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 ReloadReport struct {
	Skills  int
	Plugins int // plugins that are on
	MCP     MCPReport
}

type SessionInfo

type SessionInfo = storage.SessionInfo

type Skill

type Skill = skill.Spec

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
}

type Surface

type Surface = extension.Surface

type Trust

type Trust = extension.Trust

type WorktreeExit

type WorktreeExit struct {
	Slug       string
	Dir        string
	Branch     string
	HadChanges bool
	Kept       bool // changes kept for review instead of removed
	// BranchKept means the clean checkout was removed but its branch was
	// kept, because it holds commits not reachable elsewhere.
	BranchKept bool
}

Jump to

Keyboard shortcuts

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