agent

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: 2 Imported by: 0

Documentation

Overview

Package agent defines the contract between pocketagent and a coding agent backend. Adapters live in subpackages and depend only on this package.

Index

Constants

This section is empty.

Variables

Modes lists every mode in order of increasing trust.

Functions

This section is empty.

Types

type Agent

type Agent interface {
	// Caps reports what the agent supports, so callers can adapt instead of
	// failing (for example by saving images to files).
	Caps() Caps
	// Run executes one user turn. Cancelling ctx stops it.
	Run(ctx context.Context, req Request, h Handler) (Result, error)
}

Agent runs turns of a conversation with one coding agent.

Optional behaviour is expressed as separate interfaces that an Agent may also implement: ModelLister, ToolProvider and io.Closer.

type Block

type Block struct {
	Text     string
	Image    []byte
	MimeType string
}

Block is one piece of the user's prompt: text or an image.

func (Block) IsImage

func (b Block) IsImage() bool

type Caps

type Caps struct {
	Images      bool   // accepts image blocks
	Resume      bool   // can continue a previous session
	DenyMessage bool   // a denial can carry the user's reason to the agent
	Modes       []Mode // modes the agent can honour
}

func (Caps) SupportsMode added in v0.6.0

func (c Caps) SupportsMode(m Mode) bool

SupportsMode reports whether m is in c.Modes.

type Decision

type Decision struct {
	OptionID string
	Message  string
}

Decision answers a Permission. An empty OptionID means cancelled. Message is the user's reason for denying, if they gave one.

type Factory added in v0.6.0

type Factory func(Spec) (Agent, error)

Factory builds an Agent from its configuration.

type Handler

type Handler interface {
	Session(id string)
	Message(markdown string) // a complete block of assistant text
	ToolCall(title string, kind Kind)
	Permission(ctx context.Context, p Permission) Decision
	SendFile(ctx context.Context, path, caption string) error
}

Handler is the conversation as seen by the agent during a turn: it receives the agent's output and answers its requests.

type Kind

type Kind string

Kind classifies a tool call. The values follow the Agent Client Protocol.

const (
	KindRead    Kind = "read"
	KindEdit    Kind = "edit"
	KindDelete  Kind = "delete"
	KindMove    Kind = "move"
	KindSearch  Kind = "search"
	KindExecute Kind = "execute"
	KindThink   Kind = "think"
	KindFetch   Kind = "fetch"
	KindOther   Kind = "other"
)

type Mode

type Mode string

Mode is the permission preset for a conversation.

const (
	ModeAsk   Mode = "ask"   // ask before anything not auto-allowed
	ModeEdits Mode = "edits" // file edits allowed, commands still ask
	ModePlan  Mode = "plan"  // read-only planning, if the agent supports it
	ModeFull  Mode = "full"  // allow everything
)

type ModelLister added in v0.6.0

type ModelLister interface {
	Models(conv string) []string
}

ModelLister is implemented by agents that can name models for a picker.

type NoOptions added in v0.6.0

type NoOptions struct{}

NoOptions is an empty Options, for tests and adapters built in code.

func (NoOptions) Decode added in v0.6.0

func (NoOptions) Decode(any) error

type Option

type Option struct {
	ID    string
	Label string
	Kind  OptionKind
}

Option is one choice offered for a Permission.

func DefaultOptions

func DefaultOptions() []Option

DefaultOptions is offered when an agent does not supply its own choices.

type OptionKind

type OptionKind string
const (
	AllowOnce    OptionKind = "allow_once"
	AllowAlways  OptionKind = "allow_always"
	RejectOnce   OptionKind = "reject_once"
	RejectAlways OptionKind = "reject_always"
)

func (OptionKind) Allows

func (k OptionKind) Allows() bool

type Options added in v0.6.0

type Options interface {
	Decode(v any) error
}

Options decodes adapter-specific settings into a struct, rejecting unknown keys.

type Permission

type Permission struct {
	Tool    string // short display name, e.g. "Bash"
	Key     string // key for "always allow"; empty when the agent remembers itself
	Kind    Kind
	Title   string
	Detail  string // plain text: the command, diff or arguments
	Options []Option
}

Permission asks the user whether a tool call may run.

func (Permission) Find added in v0.6.0

func (p Permission) Find(id string) (Option, bool)

Find returns the option with the given id.

func (Permission) First added in v0.6.0

func (p Permission) First(match func(OptionKind) bool) (Option, bool)

First returns the first option for which match is true.

type Request

type Request struct {
	Conv        string // stable conversation key
	SessionID   string // resume this session if set
	Cwd         string
	Model       string // empty means the agent's default
	Mode        Mode
	Prompt      []Block
	AlwaysAllow []string // permission keys the user chose "always allow" for
	Tools       *ToolServer
}

type Result

type Result struct {
	SessionID  string
	CostUSD    float64 // cost of this turn, if the agent reports it
	StopReason string
	Final      string // the reply, when it was not already sent through Handler.Message
}

type Spec added in v0.6.0

type Spec struct {
	Name    string
	Command []string // the agent's executable and arguments
	Wrap    []string // prefix for the command, e.g. a container runner; supports {cwd}
	Env     []string // extra KEY=VALUE environment
	Options Options  // adapter-specific settings
}

Spec is an agent's configuration, independent of the config file format.

type Tool added in v0.6.0

type Tool struct {
	Name        string
	Description string
	Schema      map[string]any // JSON Schema of the arguments
	Call        func(ctx context.Context, h Handler, args json.RawMessage) (string, error)
}

Tool is an MCP tool served to agents. Call runs with the Handler of the conversation whose agent invoked it.

type ToolProvider added in v0.6.0

type ToolProvider interface {
	Tools() []Tool
}

ToolProvider is implemented by agents that need extra tools on the tool server (for example a permission-prompt hook).

type ToolServer added in v0.6.0

type ToolServer struct {
	Name    string
	URL     string
	Headers map[string]string
}

ToolServer is an HTTP MCP server the agent should connect to for the duration of the turn.

Directories

Path Synopsis
Package acp drives any agent that speaks the Agent Client Protocol (https://agentclientprotocol.com).
Package acp drives any agent that speaks the Agent Client Protocol (https://agentclientprotocol.com).
Package claudecode drives the Claude Code CLI headless, using its stream-json input and output.
Package claudecode drives the Claude Code CLI headless, using its stream-json input and output.
Package command wraps any CLI that takes a prompt and prints a reply, configured as an argv template.
Package command wraps any CLI that takes a prompt and prints a reply, configured as an argv template.

Jump to

Keyboard shortcuts

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