core

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Oct 4, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package core runs conversations: it chooses the agent, queues prompts, applies the permission policy, tracks cost and takes checkpoints.

The core is independent of any chat platform and any agent vendor. It declares the small interfaces it needs (UI, Store, ToolHost, Checkpointer) and is wired to implementations by the caller.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Approval added in v0.6.0

type Approval interface {
	Resolve(outcome string)
}

Approval is a permission request on screen.

type Checkpointer added in v0.6.0

type Checkpointer interface {
	Snapshot(ctx context.Context, dir string) (id string, err error)
	Diff(ctx context.Context, dir, from string) (string, error)
	Restore(ctx context.Context, dir, id string) error
}

Checkpointer snapshots a working tree so a turn can be shown and undone.

type ConvID added in v0.6.0

type ConvID string

ConvID identifies a conversation. The frontend chooses the format (for example a chat plus a thread); the core treats it as opaque.

type Core

type Core struct {
	Deps
	// contains filtered or unexported fields
}

func New

func New(d Deps) *Core

func (*Core) AddProject added in v0.8.0

func (c *Core) AddProject(conv ConvID, name, dir string) (ProjectInfo, error)

AddProject registers an existing folder as a project. dir defaults to the conversation's working directory and name to the folder's name.

func (*Core) AgentNames added in v0.6.0

func (c *Core) AgentNames() []string

AgentNames lists the configured agents, sorted.

func (*Core) AgentType added in v0.6.0

func (c *Core) AgentType(name string) string

AgentType is the adapter type of a configured agent.

func (*Core) Answer

func (c *Core) Answer(id, optionID string) bool

Answer delivers the user's choice for an approval. It returns false if the request is no longer pending.

func (*Core) BoundConversations added in v0.9.0

func (c *Core) BoundConversations() map[ConvID]string

BoundConversations maps each conversation that has a project to it.

func (*Core) Caps

func (c *Core) Caps(conv ConvID) agent.Caps

Caps reports what the conversation's agent supports.

func (*Core) Diff

func (c *Core) Diff(ctx context.Context, conv ConvID, all bool) (string, error)

Diff shows changes since the last checkpoint, or since HEAD when all is true.

func (*Core) Models

func (c *Core) Models(conv ConvID) []string

Models offers the configured models plus any the agent reports.

func (*Core) NewSession

func (c *Core) NewSession(conv ConvID)

func (*Core) ProjectAt added in v0.8.0

func (c *Core) ProjectAt(dir string) (ProjectInfo, bool)

ProjectAt returns the project whose folder is dir, if any.

func (*Core) Projects added in v0.8.0

func (c *Core) Projects() []ProjectInfo

Projects lists every project, from the config file and from chat, by name.

func (*Core) RemoveProject added in v0.8.0

func (c *Core) RemoveProject(name string) error

RemoveProject forgets a project added from chat. The folder is untouched.

func (*Core) ResumeSession

func (c *Core) ResumeSession(conv ConvID, id string) (store.SessionRecord, error)

func (*Core) Running

func (c *Core) Running(conv ConvID) (running bool, queued int)

Running reports whether the conversation is busy and how much is queued.

func (*Core) Sessions

func (c *Core) Sessions(conv ConvID) []store.SessionRecord

func (*Core) SetAgent

func (c *Core) SetAgent(conv ConvID, name string) error

func (*Core) SetCwd

func (c *Core) SetCwd(conv ConvID, dir string) (string, error)

func (*Core) SetMode

func (c *Core) SetMode(conv ConvID, mode agent.Mode) error

func (*Core) SetModel

func (c *Core) SetModel(conv ConvID, model string)

func (*Core) SetProject

func (c *Core) SetProject(conv ConvID, name string) error

func (*Core) SetUI

func (c *Core) SetUI(ui UI)

SetUI connects the frontend. It must be called before Submit.

func (*Core) Settings

func (c *Core) Settings(conv ConvID) Settings

func (*Core) Stop

func (c *Core) Stop(conv ConvID) (stopped bool, dropped int)

Stop cancels the current run and drops the queue.

func (*Core) Submit

func (c *Core) Submit(conv ConvID, in Input)

Submit runs the input now, or queues it if the conversation is busy. While an approval is pending, text input denies it with that text as the reason.

func (*Core) SuggestProjects added in v0.9.0

func (c *Core) SuggestProjects(limit int) []discover.Candidate

SuggestProjects proposes existing folders that aren't projects yet: folders where agents ran recently and folders in the usual code directories, most recent first.

func (*Core) ToggleVoice

func (c *Core) ToggleVoice(conv ConvID) (bool, error)

func (*Core) Undo

func (c *Core) Undo(ctx context.Context, conv ConvID) (store.Checkpoint, error)

Undo restores the working tree to the state before the last turn.

func (*Core) Usage

func (c *Core) Usage(user string) (today, month float64)

Usage is what a user spent today and over the last 30 days.

type Deps added in v0.6.0

type Deps struct {
	Config       *config.Config
	Agents       map[string]agent.Agent
	Store        Store
	Tools        ToolHost
	Checkpointer Checkpointer
	Transcriber  stt.Transcriber
	Speaker      tts.Speaker
}

Deps are the core's collaborators. Transcriber, Speaker and Checkpointer may be nil to disable those features.

type Input

type Input struct {
	User   string // opaque user id, used for budgets
	Blocks []agent.Block
	Text   string // the text part, used for titles and "deny with reason"
}

Input is one user message.

type Messenger added in v0.6.0

type Messenger interface {
	Reply(conv ConvID, markdown string) // agent output; long replies may become a file
	Notice(conv ConvID, text string)    // a short status line
	SendFile(ctx context.Context, conv ConvID, path, caption string) error
	SendVoice(ctx context.Context, conv ConvID, ogg []byte) error
}

Messenger sends things to a conversation.

type Progress

type Progress interface {
	ToolCall(title string)
	Flush() // called before agent text is sent, so tool lines stay above it
	Done(summary string)
}

Progress shows what the agent is doing during one turn.

type ProjectInfo added in v0.8.0

type ProjectInfo struct {
	Name       string
	Cwd        string
	FromConfig bool // defined in the config file, so it can't be removed from chat
}

ProjectInfo describes a project for listing.

type Settings

type Settings struct {
	Agent, Model, Cwd, Project string
	Mode                       agent.Mode
	SessionID                  string
	Voice                      bool
	AlwaysAllow                []string
	TotalCost                  float64
}

Settings is a conversation's effective configuration: conversation overrides, then the project, then the defaults.

type Store added in v0.6.0

type Store interface {
	Get(key string) store.Conversation
	Update(key string, fn func(*store.Conversation)) error
	AddSpend(user string, usd float64) error
	Spend(user string) (today, month float64)
	Projects() map[string]store.Project
	ProjectOf() map[string]string
	AddProject(name string, p store.Project) error
	RemoveProject(name string) error
}

Store persists conversations and spend.

type ToolHost added in v0.6.0

type ToolHost interface {
	Attach(conv string, h agent.Handler) (detach func())
	Server(agentName, conv string) *agent.ToolServer
}

ToolHost serves tools (send_file, approval hooks) to agent processes.

type UI

type UI interface {
	Messenger
	StartProgress(conv ConvID) Progress
	// AskApproval presents p; the choice comes back via Core.Answer(id, optionID).
	AskApproval(conv ConvID, id string, p agent.Permission) Approval
}

UI is implemented by the chat frontend.

Jump to

Keyboard shortcuts

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