acpclient

package
v0.24.0 Latest Latest
Warning

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

Go to latest
Published: Jul 2, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	FlowNodeTypeACP     = "acp"
	FlowNodeTypeAction  = "action"
	FlowNodeTypeCompute = "compute"

	FlowRunStatusRunning   = "running"
	FlowRunStatusCompleted = "completed"
	FlowRunStatusFailed    = "failed"

	FlowStepStatusCompleted = "completed"
	FlowStepStatusFailed    = "failed"
)
View Source
const (
	SessionStatusQueued          = "queued"
	SessionStatusRunning         = "running"
	SessionStatusCompleted       = "completed"
	SessionStatusCanceled        = "canceled"
	SessionStatusCancelRequested = "cancel_requested"

	PendingPromptStatusPending  = "pending"
	PendingPromptStatusCanceled = "canceled"

	QueuePromptStatusPending   = "pending"
	QueuePromptStatusRunning   = "running"
	QueuePromptStatusCompleted = "completed"
	QueuePromptStatusCanceled  = "canceled"
	QueuePromptStatusFailed    = "failed"
)

Variables

View Source
var (
	ErrSessionActive             = errors.New("acp client session is active")
	ErrSessionArchiveCollision   = errors.New("acp client archive destination session exists")
	ErrUnsupportedArchiveVersion = errors.New("unsupported acp client archive format version")
	ErrInvalidSessionArchive     = errors.New("invalid acp client archive")
)
View Source
var (
	ErrPathOutsideCWD = errors.New("acp client path is outside cwd")
	ErrWritesDisabled = errors.New("acp client filesystem writes are disabled")
)
View Source
var (
	ErrProfileNotFound       = errors.New("acp client profile not found")
	ErrProfileShadowsBuiltin = errors.New("acp client profile shadows built-in agent")
)
View Source
var (
	ErrMissingCommand = errors.New("acp client command is required")
	ErrShellCommand   = errors.New("acp client command must be an executable path/name, with args passed separately")
	ErrUnknownAgent   = errors.New("unknown acp client agent")
)
View Source
var (
	ErrSessionNotFound     = errors.New("acp client session not found")
	ErrQueuePromptNotFound = errors.New("acp client queue prompt not found")
	ErrInvalidOwnerLock    = errors.New("acp client owner lock is invalid")
)
View Source
var ErrDrainBusy = errors.New("acp client session is already being drained")
View Source
var ErrInvalidFlowDefinition = errors.New("invalid acp client flow definition")

Functions

func ExportSession added in v0.20.0

func ExportSession(store *Store, id, outputPath string, opts ExportOptions) error

Types

type ActionResult added in v0.23.0

type ActionResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
	Duration time.Duration
}

type ActionRunOptions added in v0.23.0

type ActionRunOptions struct {
	Command string
	Args    []string
	Cwd     string
	Env     map[string]string
	Input   json.RawMessage
}

type ActionRunner added in v0.23.0

type ActionRunner interface {
	RunAction(context.Context, ActionRunOptions) (ActionResult, error)
}

type AgentSpec

type AgentSpec struct {
	Name    string   `json:"name"`
	Command string   `json:"command"`
	Args    []string `json:"args,omitempty"`
	EnvKeys []string `json:"envKeys,omitempty"`
}

func (AgentSpec) Fingerprint

func (s AgentSpec) Fingerprint() string

func (AgentSpec) Validate

func (s AgentSpec) Validate() error

type Archive added in v0.20.0

type Archive struct {
	FormatVersion int                   `json:"format_version"`
	ExportedAt    string                `json:"exported_at"`
	ExportedBy    string                `json:"exported_by"`
	Session       ArchiveSession        `json:"session"`
	History       []ArchiveHistoryEvent `json:"history"`
}

type ArchiveHistoryEvent added in v0.20.0

type ArchiveHistoryEvent struct {
	Kind       string    `json:"kind"`
	ID         string    `json:"id,omitempty"`
	Prompt     string    `json:"prompt,omitempty"`
	Response   string    `json:"response,omitempty"`
	Status     string    `json:"status,omitempty"`
	StopReason string    `json:"stop_reason,omitempty"`
	CreatedAt  time.Time `json:"created_at,omitzero"`
	UpdatedAt  time.Time `json:"updated_at,omitzero"`
}

type ArchiveSession added in v0.20.0

type ArchiveSession struct {
	RecordID    string        `json:"record_id"`
	Name        *string       `json:"name,omitempty"`
	Agent       string        `json:"agent"`
	AgentName   string        `json:"agent_name,omitempty"`
	CWDRelative string        `json:"cwd_relative"`
	CWDOriginal string        `json:"cwd_original"`
	CreatedAt   string        `json:"created_at"`
	UpdatedAt   string        `json:"updated_at"`
	State       SessionRecord `json:"state"`
}

type Callbacks

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

func NewCallbacks

func NewCallbacks(opts RunOptions) *Callbacks

func (*Callbacks) Cwd

func (c *Callbacks) Cwd() string

func (*Callbacks) Reset

func (c *Callbacks) Reset()

func (*Callbacks) SessionUpdate

func (c *Callbacks) SessionUpdate(ctx context.Context, n acpsdk.SessionNotification) error

func (*Callbacks) Snapshot

func (c *Callbacks) Snapshot() ([]acpsdk.SessionNotification, string)

func (*Callbacks) UpdateCount

func (c *Callbacks) UpdateCount() int

func (*Callbacks) WaitForUpdate

func (c *Callbacks) WaitForUpdate(ctx context.Context, previous int)

type CancelRequest

type CancelRequest struct {
	SessionID   string    `json:"sessionId"`
	RequestedAt time.Time `json:"requestedAt"`
}

type Client

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

func NewInProcessClient

func NewInProcessClient(peerInput io.Writer, peerOutput io.Reader, opts RunOptions) *Client

func Start

func Start(ctx context.Context, spec AgentSpec, opts RunOptions) (*Client, error)

func (*Client) Close

func (c *Client) Close() error

func (*Client) RunPrompt

func (c *Client) RunPrompt(ctx context.Context, prompt string) (Result, error)

func (*Client) StartSession added in v0.19.0

func (c *Client) StartSession(ctx context.Context, existingSessionID string) (*SessionRunner, error)

type CompareAgent added in v0.20.0

type CompareAgent struct {
	Name string
	Spec AgentSpec
}

type CompareOptions added in v0.20.0

type CompareOptions struct {
	Cwd     string
	Timeout time.Duration
	Runner  CompareRunner
}

type CompareRow added in v0.20.0

type CompareRow struct {
	Agent      string `json:"agent"`
	Status     string `json:"status"`
	WallMS     int64  `json:"wall_ms"`
	StopReason string `json:"stop_reason,omitempty"`
	Final      string `json:"final,omitempty"`
	Error      string `json:"error,omitempty"`
}

func Compare added in v0.20.0

func Compare(ctx context.Context, agents []CompareAgent, prompt string, opts CompareOptions) ([]CompareRow, error)

type CompareRunner added in v0.20.0

type CompareRunner interface {
	RunPrompt(context.Context, AgentSpec, RunOptions, string) (Result, error)
}

type DrainOptions added in v0.19.0

type DrainOptions struct {
	Max         int
	Now         func() time.Time
	StartRunner func(context.Context, AgentSpec, RunOptions, string) (DrainPromptRunner, func() error, error)
}

type DrainPromptRunner added in v0.19.0

type DrainPromptRunner interface {
	SessionID() acpsdk.SessionId
	Prompt(context.Context, string) (Result, error)
}

type DrainResult added in v0.19.0

type DrainResult struct {
	SessionID    string
	ACPSessionID string
	Processed    int
	Completed    int
	Failed       int
	Canceled     int
	Remaining    int
}

func DrainQueue added in v0.19.0

func DrainQueue(ctx context.Context, store *Store, spec AgentSpec, opts RunOptions, sessionID string, drainOpts DrainOptions) (DrainResult, error)

type ExportOptions added in v0.20.0

type ExportOptions struct {
	HomeDir string
	Now     func() time.Time
}

type FlowDefinition added in v0.20.0

type FlowDefinition struct {
	FormatVersion int        `json:"format_version"`
	Name          string     `json:"name,omitempty"`
	Requires      []string   `json:"requires,omitempty"`
	StartAt       string     `json:"start_at"`
	Nodes         []FlowNode `json:"nodes"`
	Edges         []FlowEdge `json:"edges,omitempty"`
}

func LoadFlowDefinition added in v0.20.0

func LoadFlowDefinition(path string) (FlowDefinition, error)

func (FlowDefinition) Validate added in v0.20.0

func (def FlowDefinition) Validate() error

type FlowEdge added in v0.20.0

type FlowEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type FlowNode added in v0.20.0

type FlowNode struct {
	ID      string            `json:"id"`
	Type    string            `json:"type"`
	Prompt  string            `json:"prompt,omitempty"`
	Agent   string            `json:"agent,omitempty"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Session string            `json:"session,omitempty"`
	Cwd     string            `json:"cwd,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	Input   json.RawMessage   `json:"input,omitempty"`
	Value   json.RawMessage   `json:"value,omitempty"`
	Select  string            `json:"select,omitempty"`
}

type FlowPromptRunner added in v0.20.0

type FlowPromptRunner interface {
	SessionID() acpsdk.SessionId
	Prompt(context.Context, string) (Result, error)
}

type FlowRunOptions added in v0.20.0

type FlowRunOptions struct {
	RunID              string
	RunRoot            string
	Cwd                string
	DefaultAgent       string
	DefaultCommand     string
	DefaultArgs        []string
	Registry           Registry
	AllowedPermissions []string
	ActionOutputLimit  int
	ActionRunner       ActionRunner
	StartRunner        func(context.Context, AgentSpec, RunOptions, string) (FlowPromptRunner, func() error, error)
}

type FlowRunResult added in v0.20.0

type FlowRunResult struct {
	RunID   string                     `json:"run_id"`
	Status  string                     `json:"status"`
	RunDir  string                     `json:"run_dir,omitempty"`
	Outputs map[string]json.RawMessage `json:"outputs"`
	Steps   []FlowStepRecord           `json:"steps"`
}

func RunFlow added in v0.20.0

func RunFlow(ctx context.Context, def FlowDefinition, input map[string]any, opts FlowRunOptions) (FlowRunResult, error)

type FlowRunState added in v0.20.0

type FlowRunState struct {
	RunID  string           `json:"run_id"`
	Status string           `json:"status"`
	Steps  []FlowStepRecord `json:"steps"`
}

type FlowRunStore added in v0.20.0

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

func NewFlowRunStore added in v0.20.0

func NewFlowRunStore(rootDir, runID string) (*FlowRunStore, error)

func (*FlowRunStore) Dir added in v0.20.0

func (s *FlowRunStore) Dir() string

func (*FlowRunStore) WriteDefinition added in v0.20.0

func (s *FlowRunStore) WriteDefinition(def FlowDefinition) error

func (*FlowRunStore) WriteInput added in v0.20.0

func (s *FlowRunStore) WriteInput(input any) error

func (*FlowRunStore) WriteState added in v0.20.0

func (s *FlowRunStore) WriteState(state FlowRunState) error

func (*FlowRunStore) WriteStep added in v0.20.0

func (s *FlowRunStore) WriteStep(nodeID string, output json.RawMessage) error

type FlowStepRecord added in v0.20.0

type FlowStepRecord struct {
	NodeID string          `json:"node_id"`
	Type   string          `json:"type,omitempty"`
	Status string          `json:"status"`
	Output json.RawMessage `json:"output,omitempty"`
	Error  string          `json:"error,omitempty"`
}

type ImportOptions added in v0.20.0

type ImportOptions struct {
	SessionID          string
	Cwd                string
	HomeDir            string
	Agent              string
	CommandFingerprint string
}

type OwnerLock

type OwnerLock struct {
	SessionID          string    `json:"sessionId"`
	PID                int       `json:"pid"`
	CommandFingerprint string    `json:"commandFingerprint"`
	StartedAt          time.Time `json:"startedAt"`
}

type PendingPrompt

type PendingPrompt struct {
	ID         string     `json:"id"`
	Prompt     string     `json:"prompt"`
	Status     string     `json:"status"`
	CreatedAt  time.Time  `json:"createdAt"`
	CanceledAt *time.Time `json:"canceledAt,omitempty"`
}

type Profile added in v0.24.0

type Profile struct {
	Name          string    `json:"name"`
	Spec          AgentSpec `json:"spec"`
	Cwd           string    `json:"cwd,omitempty"`
	SourceKind    string    `json:"sourceKind,omitempty"`
	SourceID      string    `json:"sourceId,omitempty"`
	Hash          string    `json:"hash"`
	Trusted       bool      `json:"trusted,omitempty"`
	CreatedAt     time.Time `json:"createdAt"`
	UpdatedAt     time.Time `json:"updatedAt"`
	PluginName    string    `json:"pluginName,omitempty"`
	PluginVersion string    `json:"pluginVersion,omitempty"`
}

func (Profile) DescriptorHash added in v0.24.0

func (p Profile) DescriptorHash() string

type ProfileStore added in v0.24.0

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

func NewDefaultProfileStore added in v0.24.0

func NewDefaultProfileStore() (*ProfileStore, error)

func NewProfileStore added in v0.24.0

func NewProfileStore(path string) *ProfileStore

func (*ProfileStore) Add added in v0.24.0

func (s *ProfileStore) Add(profile Profile) error

func (*ProfileStore) Get added in v0.24.0

func (s *ProfileStore) Get(name string) (Profile, error)

func (*ProfileStore) List added in v0.24.0

func (s *ProfileStore) List() ([]Profile, error)

func (*ProfileStore) Path added in v0.24.0

func (s *ProfileStore) Path() string

func (*ProfileStore) Remove added in v0.24.0

func (s *ProfileStore) Remove(name string) error

func (*ProfileStore) Trust added in v0.24.0

func (s *ProfileStore) Trust(name string) error

type QueuedPrompt added in v0.19.0

type QueuedPrompt struct {
	ID          string     `json:"id"`
	Prompt      string     `json:"prompt"`
	Status      string     `json:"status"`
	CreatedAt   time.Time  `json:"createdAt"`
	StartedAt   *time.Time `json:"startedAt,omitempty"`
	CompletedAt *time.Time `json:"completedAt,omitempty"`
	CanceledAt  *time.Time `json:"canceledAt,omitempty"`
	Response    string     `json:"response,omitempty"`
	StopReason  string     `json:"stopReason,omitempty"`
	Error       string     `json:"error,omitempty"`
}

type Registry

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

func DefaultRegistry

func DefaultRegistry() Registry

func NewRegistry

func NewRegistry(specs []AgentSpec) Registry

func (Registry) Lookup

func (r Registry) Lookup(name string) (AgentSpec, bool)

func (Registry) Resolve

func (r Registry) Resolve(opts RunOptions) (AgentSpec, error)

func (Registry) WithProfiles added in v0.24.0

func (r Registry) WithProfiles(profiles []Profile) (Registry, error)

type Result

type Result struct {
	SessionID  acpsdk.SessionId
	StopReason acpsdk.StopReason
	Updates    []acpsdk.SessionNotification
	Text       string
	Stderr     string
	Duration   time.Duration
}

type RunOptions

type RunOptions struct {
	Agent           string
	Command         string
	Args            []string
	Cwd             string
	AllowWrites     bool
	Timeout         time.Duration
	SessionStarted  func(sessionID string) error
	CancelRequested func(sessionID string) bool
}

type SessionRecord

type SessionRecord struct {
	ID                 string         `json:"id"`
	ACPSessionID       string         `json:"acpSessionId,omitempty"`
	Agent              string         `json:"agent"`
	CommandFingerprint string         `json:"commandFingerprint"`
	Cwd                string         `json:"cwd"`
	Status             string         `json:"status"`
	CreatedAt          time.Time      `json:"createdAt"`
	UpdatedAt          time.Time      `json:"updatedAt"`
	LastStopReason     string         `json:"lastStopReason,omitempty"`
	Summary            string         `json:"summary,omitempty"`
	Turns              []TurnSummary  `json:"turns,omitempty"`
	PendingPrompt      *PendingPrompt `json:"pendingPrompt,omitempty"`
	PromptQueue        []QueuedPrompt `json:"promptQueue,omitempty"`
}

func ImportSession added in v0.20.0

func ImportSession(store *Store, archivePath string, opts ImportOptions) (SessionRecord, error)

type SessionRunner added in v0.19.0

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

func (*SessionRunner) Prompt added in v0.19.0

func (r *SessionRunner) Prompt(ctx context.Context, prompt string) (Result, error)

func (*SessionRunner) SessionID added in v0.19.0

func (r *SessionRunner) SessionID() acpsdk.SessionId

type Store

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

func NewDefaultStore

func NewDefaultStore() (*Store, error)

func NewStore

func NewStore(path string) *Store

func (*Store) AcquireOwner added in v0.19.0

func (s *Store) AcquireOwner(owner OwnerLock) error

func (*Store) AppendQueuedPrompt added in v0.19.0

func (s *Store) AppendQueuedPrompt(rec SessionRecord, prompt QueuedPrompt) (SessionRecord, error)

func (*Store) CancelPendingQueue added in v0.19.0

func (s *Store) CancelPendingQueue(id string, when time.Time) (int, error)

func (*Store) CancelRequest

func (s *Store) CancelRequest(id string) (CancelRequest, error)

func (*Store) ClearOwner

func (s *Store) ClearOwner(id string) error

func (*Store) Get

func (s *Store) Get(id string) (SessionRecord, error)

func (*Store) List

func (s *Store) List() ([]SessionRecord, error)

func (*Store) MarkPendingCanceled

func (s *Store) MarkPendingCanceled(id string, when time.Time) error

func (*Store) MarkQueueCompleted added in v0.19.0

func (s *Store) MarkQueueCompleted(id, queueID, response, stopReason string, when time.Time) error

func (*Store) MarkQueueFailed added in v0.19.0

func (s *Store) MarkQueueFailed(id, queueID, message string, when time.Time) error

func (*Store) MarkQueueRunning added in v0.19.0

func (s *Store) MarkQueueRunning(id, queueID string, when time.Time) error

func (*Store) NextQueuedPrompt added in v0.19.0

func (s *Store) NextQueuedPrompt(id string) (QueuedPrompt, bool, error)

func (*Store) Owner

func (s *Store) Owner(id string) (OwnerLock, error)

func (*Store) Path

func (s *Store) Path() string

func (*Store) RecoverStaleQueue added in v0.19.0

func (s *Store) RecoverStaleQueue(id string, when time.Time) (int, error)

func (*Store) RequestCancel

func (s *Store) RequestCancel(id string, when time.Time) error

func (*Store) Upsert

func (s *Store) Upsert(rec SessionRecord) error

func (*Store) WriteOwner

func (s *Store) WriteOwner(owner OwnerLock) error

type TurnSummary

type TurnSummary struct {
	Prompt     string    `json:"prompt"`
	Response   string    `json:"response"`
	StopReason string    `json:"stopReason"`
	CreatedAt  time.Time `json:"createdAt"`
}

type WatchCycle added in v0.23.0

type WatchCycle struct {
	SessionID     string
	ACPSessionID  string
	Cycle         int
	PendingBefore int
	Processed     int
	Completed     int
	Failed        int
	Canceled      int
	Remaining     int
	Idle          bool
	StartedAt     time.Time
	CompletedAt   time.Time
}

type WatchOptions added in v0.23.0

type WatchOptions struct {
	Interval      time.Duration
	MaxPerCycle   int
	MaxCycles     int
	StopWhenEmpty bool
	Now           func() time.Time
	Sleep         func(context.Context, time.Duration) error
	StartRunner   func(context.Context, AgentSpec, RunOptions, string) (DrainPromptRunner, func() error, error)
}

type WatchResult added in v0.23.0

type WatchResult struct {
	SessionID    string
	ACPSessionID string
	Cycles       int
	Processed    int
	Completed    int
	Failed       int
	Canceled     int
	Remaining    int
}

func WatchQueue added in v0.23.0

func WatchQueue(ctx context.Context, store *Store, spec AgentSpec, opts RunOptions, sessionID string, watchOpts WatchOptions, onCycle func(WatchCycle)) (WatchResult, error)

Jump to

Keyboard shortcuts

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