acpclient

package
v0.23.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 (
	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
	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 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)

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