acprun

package
v0.14.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package acprun continues an existing agent session through an ACP adapter (claude-agent-acp, codex-acp): it starts the adapter, loads the session, sends prompts, streams updates as numbered events and relays permission requests. The session's own files stay the source of truth, so the agent CLI on the laptop continues the same conversation afterwards.

Index

Constants

View Source
const (
	KindUpdate     = "update"     // Data: one ACP session update (agent text, tool call, plan, ...)
	KindPermission = "permission" // Data: the ACP permission request sent to the approver
)

Event kinds.

Variables

View Source
var (
	ErrBusy        = errors.New("the session is already answering a message")
	ErrTooManyRuns = errors.New("too many sessions are busy; try again when one finishes")
	ErrNotRunning  = errors.New("the session is not running in aimux")
)

Errors returned by Manager.

View Source
var (
	ErrUnknownSession = errors.New("no such session")
	// ErrOpenInTerminal: replying to a session open in a terminal is left
	// out on purpose; typing into one can approve a permission prompt the
	// user never saw. Close it there to continue it here.
	ErrOpenInTerminal = errors.New("the session is open in a terminal on this machine; close it there to continue it here")
	// ErrOwnershipUnknown: without Claude's session registry aimux cannot
	// tell whether a terminal holds the session, so it does not risk a
	// second writer.
	ErrOwnershipUnknown = errors.New("cannot tell whether the session is open in a terminal: Claude's session registry is unavailable")
)

Router errors.

View Source
var ErrInUseElsewhere = errors.New("the session is being continued by another aimux process")

ErrInUseElsewhere: another aimux process (a second `aimux chat`, or the remote server) is already continuing the session.

Functions

func Reservation

func Reservation(home string) func(sessionID string) (release func(), err error)

Reservation is the session lock every aimux process shares: SessionLock in home/.aimux/locks, for ManagerOptions.Reserve. aimux chat and remote serve both use it, so they never continue one session at once.

func SessionLock

func SessionLock(dir, sessionID string) (release func(), err error)

SessionLock takes an exclusive, non-blocking lock on sessionID in dir, so separate aimux processes never drive one session at the same time. The OS drops the lock if the process dies. Call release to let go.

Types

type Approver

type Approver func(ctx context.Context, req acp.RequestPermissionRequest) (optionID string, ok bool)

Approver decides a permission request. It returns the chosen option ID, or ok=false to deny. It should return when ctx is done.

type Event

type Event struct {
	Seq  int64           `json:"seq"`
	Kind string          `json:"kind"`
	Data json.RawMessage `json:"data"`
}

Event is one thing that happened during a run, numbered so a client that reconnects can ask for everything after the last number it saw.

type Lookup

type Lookup func(sessionID string) (SessionInfo, error)

Lookup finds a session by ID.

type Manager

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

Manager keeps at most one run per session and decides when to start, reuse and close them.

func NewManager

func NewManager(opt ManagerOptions) *Manager

NewManager returns a Manager.

func (*Manager) Active

func (m *Manager) Active() []string

Active lists the sessions with a live run, sorted.

func (*Manager) Cancel

func (m *Manager) Cancel(sessionID string) error

Cancel stops the session's current turn wherever it is: starting the adapter, between accepting the turn and prompting, or in the prompt (then the agent is asked to stop). With no turn it returns ErrNotRunning and the adapter is left alone, since a cancel it kept would stop the next turn.

func (*Manager) Close

func (m *Manager) Close()

Close closes every run, cancels adapters still starting and waits for them, and refuses further messages.

func (*Manager) Drop

func (m *Manager) Drop(sessionID string) error

Drop closes the session's run if it is idle and releases its reservation. Returns nil when there is no run, or ErrBusy when a turn is running.

func (*Manager) Events

func (m *Manager) Events(sessionID string, after int64) ([]Event, error)

Events returns the session's run events numbered after seq.

func (*Manager) New

func (m *Manager) New(ctx context.Context, cwd string) (string, error)

New starts a new session in cwd and keeps its run for the session's messages, which go through Send as usual. The run counts against MaxRuns.

func (*Manager) Owns

func (m *Manager) Owns(pid int) bool

Owns reports whether pid is one of aimux's adapter processes or runs below one (the adapter starts the agent CLI as a child).

func (*Manager) ProbeReserved

func (m *Manager) ProbeReserved(sessionID string) error

ProbeReserved reports ErrInUseElsewhere when another process holds the session's reservation. It holds nothing; sessions this manager already runs are not probed (it holds their reservation itself).

func (*Manager) Reap

func (m *Manager) Reap() int

Reap closes runs idle longer than IdleTimeout and returns how many.

func (*Manager) Running

func (m *Manager) Running(sessionID string) bool

Running reports whether aimux has a run (starting or started) for the session.

func (*Manager) Send

func (m *Manager) Send(ctx context.Context, sessionID, cwd, text string, onEvent func(Event)) (string, error)

Send delivers text to the session, starting a run if there is none, and blocks until the agent's turn ends. It refuses with ErrBusy while the session is still answering, and with ErrTooManyRuns when every run slot is busy. A failed turn closes the run so the next message starts fresh.

type ManagerOptions

type ManagerOptions struct {
	Start StartFunc
	// MaxRuns caps live adapters; each one is a full agent process. Default 2.
	MaxRuns int
	// IdleTimeout is how long an idle run is kept before Reap closes it.
	// Default 5 minutes.
	IdleTimeout time.Duration
	Now         func() time.Time
	// Fingerprint identifies the session's on-disk state (for example the
	// session file's size and modification time). When it differs from the
	// one recorded after aimux's last turn, the session was continued
	// elsewhere and the cached adapter is replaced so the session reloads.
	// Nil or "" disables the check.
	Fingerprint func(sessionID string) string
	// Reserve claims the session for this process before an adapter starts
	// and returns its release, called when the adapter is gone for good. It
	// keeps separate aimux processes from driving one session (SessionLock).
	// Nil disables it.
	Reserve func(sessionID string) (release func(), err error)
	// StartNew starts a new session (New). Nil: new sessions are not offered.
	StartNew StartNewFunc
	// StartTimeout bounds starting an adapter and loading the session.
	// Default 3 minutes (the first npx run downloads the adapter).
	StartTimeout time.Duration
	// ParentPID returns a process's parent, for telling aimux's own adapter
	// processes from the user's terminals. Default discovery.GetParentPID.
	ParentPID func(pid int) int
}

ManagerOptions configures a Manager. Zero values give the defaults.

type Router

type Router struct {
	Lookup  Lookup
	Manager *Manager
}

Router sends a message to a session the right way for its state.

func (*Router) Check

func (r *Router) Check(sessionID string) error

Check reports whether Send would accept sessionID, without sending.

func (*Router) Send

func (r *Router) Send(ctx context.Context, sessionID, text string, onEvent func(Event)) (string, error)

Send continues sessionID with text through the manager, unless the session is unknown or open in a terminal that aimux does not drive.

type Run

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

Run is one adapter process driving one loaded session.

func Start

func Start(ctx context.Context, spec Spec, sessionID string, approve Approver) (*Run, error)

Start launches the adapter, initializes it and loads sessionID. Updates the agent replays while loading are history and are not reported as events.

func StartNew

func StartNew(ctx context.Context, spec Spec, approve Approver) (*Run, error)

StartNew launches the adapter and starts a new session in spec.Cwd; its id is r.SessionID(). The agent writes the session file on the first prompt.

func (*Run) Cancel

func (r *Run) Cancel()

Cancel asks the agent to stop the current turn; Prompt then returns "cancelled". A Cancel before the prompt is sent ends that prompt at once.

func (*Run) Close

func (r *Run) Close() error

Close stops the adapter and everything it started. It is safe to call twice.

func (*Run) Events

func (r *Run) Events(after int64) []Event

Events returns the events numbered after seq, oldest first.

func (*Run) PID

func (r *Run) PID() int

PID is the adapter's process ID.

func (*Run) Prompt

func (r *Run) Prompt(ctx context.Context, text string, onEvent func(Event)) (string, error)

Prompt sends text and blocks until the agent ends its turn, calling onEvent for each event of this turn. It returns the ACP stop reason.

func (*Run) SessionID

func (r *Run) SessionID() string

SessionID is the session this run continues.

type Runner

type Runner interface {
	PID() int // the adapter process
	Prompt(ctx context.Context, text string, onEvent func(Event)) (string, error)
	Cancel()
	Events(after int64) []Event
	Close() error
}

Runner is a started run; *Run implements it.

type SessionInfo

type SessionInfo struct {
	Provider       string
	Cwd            string
	OpenInTerminal bool  // some live process holds the session
	Holders        []int // those processes
}

SessionInfo is what the router needs to know about a session.

type SessionLookup

type SessionLookup struct {
	Provider string               // SessionInfo.Provider, e.g. "claude"
	Store    harness.SessionStore // provider.Claude for Claude Code
	Live     harness.LiveSessions // discovery.LiveCache for Claude Code
}

SessionLookup finds one harness's sessions: its session store gives the working directory, and its live sessions under the Strict rule (harness.Mode) say which processes hold the session. The session list reads the same source under List, so the two can differ only where that table says.

func (SessionLookup) Lookup

func (l SessionLookup) Lookup(sessionID string) (SessionInfo, error)

Lookup is a Router.Lookup.

type Spec

type Spec struct {
	Command string
	Args    []string
	Cwd     string   // the session's working directory
	Env     []string // extra KEY=VALUE pairs on top of aimux's environment
}

Spec is how to launch an ACP adapter.

type StartFunc

type StartFunc func(ctx context.Context, sessionID, cwd string) (Runner, error)

StartFunc starts a run that continues sessionID in cwd.

type StartNewFunc

type StartNewFunc func(ctx context.Context, cwd string) (Runner, string, error)

StartNewFunc starts a run for a new session in cwd and returns its id.

Jump to

Keyboard shortcuts

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