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
- Variables
- func Reservation(home string) func(sessionID string) (release func(), err error)
- func SessionLock(dir, sessionID string) (release func(), err error)
- type Approver
- type Event
- type Lookup
- type Manager
- func (m *Manager) Active() []string
- func (m *Manager) Cancel(sessionID string) error
- func (m *Manager) Close()
- func (m *Manager) Drop(sessionID string) error
- func (m *Manager) Events(sessionID string, after int64) ([]Event, error)
- func (m *Manager) New(ctx context.Context, cwd string) (string, error)
- func (m *Manager) Owns(pid int) bool
- func (m *Manager) ProbeReserved(sessionID string) error
- func (m *Manager) Reap() int
- func (m *Manager) Running(sessionID string) bool
- func (m *Manager) Send(ctx context.Context, sessionID, cwd, text string, onEvent func(Event)) (string, error)
- type ManagerOptions
- type Router
- type Run
- type Runner
- type SessionInfo
- type SessionLookup
- type Spec
- type StartFunc
- type StartNewFunc
Constants ¶
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 ¶
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.
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.
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 ¶
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 ¶
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 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 (*Manager) Cancel ¶
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 ¶
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) New ¶
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 ¶
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 ¶
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) Running ¶
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 ¶
Router sends a message to a session the right way for its state.
type Run ¶
type Run struct {
// contains filtered or unexported fields
}
Run is one adapter process driving one loaded session.
func Start ¶
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 ¶
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.
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.