Documentation
¶
Overview ¶
Package client is the local control client behind Peen's CLI commands.
It speaks only the control HTTP API. It never opens SQLite, never builds an agent runtime, and never resolves a workspace itself, so a command cannot disagree with the running controller about durable state.
Index ¶
- type AttachEvent
- type Client
- func (c *Client) Attach(ctx context.Context, sessionID uuid.UUID, cursor *int64, ...) error
- func (c *Client) CancelSession(ctx context.Context, sessionID uuid.UUID) (api.CancelResponse, error)
- func (c *Client) EnsureRunning(ctx context.Context, options LaunchOptions) error
- func (c *Client) GetSession(ctx context.Context, sessionID uuid.UUID) (api.Session, error)
- func (c *Client) ListSessionFeed(ctx context.Context, sessionID uuid.UUID, cursor int64) (api.FeedPage, error)
- func (c *Client) ListSessions(ctx context.Context) (api.SessionPage, error)
- func (c *Client) OpenSession(ctx context.Context, request api.OpenSessionRequest) (api.OpenedSession, error)
- func (c *Client) OpenSystemSession(ctx context.Context) (api.OpenedSession, error)
- func (c *Client) Reachable(ctx context.Context) bool
- func (c *Client) ReconfigureSession(ctx context.Context, sessionID uuid.UUID, ...) (api.SessionAgentSpaceDecision, error)
- func (c *Client) RunTurn(ctx context.Context, sessionID uuid.UUID, data wsapi.MessageSendData, ...) (TurnResult, error)
- type DialFunc
- type LaunchOptions
- type Options
- type TurnConnection
- type TurnFrame
- type TurnHandler
- type TurnOutcome
- type TurnResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AttachEvent ¶
type AttachEvent struct {
Type string
Data []byte
// Sequence is the frame's position in the session feed. It is nil for an
// unsequenced live-only acknowledgement, which is never replayed.
Sequence *int64
}
AttachEvent is one event delivered to an attached client, live or replayed from the session feed during catch-up.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls one local controller.
func (*Client) Attach ¶
func (c *Client) Attach( ctx context.Context, sessionID uuid.UUID, cursor *int64, sink func(AttachEvent) error, ) error
Attach streams the controller's live feed for one session until the context ends or the controller closes the socket normally.
The filter is server side: the socket asks for one session's events rather than receiving every session's and discarding most.
cursor, when non-nil, replays the feed from that sequence before joining live. A nil cursor starts live at the session's current feed head, read first through GET /api/v1/session, so a later reconnect has a defined place to resume from. An unexpected close or read error reconnects with a doubling backoff and catches up every frame missed over REST before continuing live; a gap in the live stream itself (sequence > last+1) catches up the same way without a reconnect. A duplicate (sequence <= last) is dropped.
func (*Client) CancelSession ¶
func (c *Client) CancelSession( ctx context.Context, sessionID uuid.UUID, ) (api.CancelResponse, error)
CancelSession asks the controller to stop the session's active turn. It reports whether a turn was running: a session with nothing in flight is not an error, it simply has nothing to cancel.
func (*Client) EnsureRunning ¶
func (c *Client) EnsureRunning( ctx context.Context, options LaunchOptions, ) error
EnsureRunning connects to the local controller, starting one when none is listening.
The sequence is the documented one, and the lock is what makes it safe:
- try the configured endpoint;
- take the start lock;
- re-check the endpoint while holding it;
- start the controller only if it is still absent;
- wait for readiness.
Step 3 is why two clients racing to start a controller produce one: the loser re-checks after the winner has already started it.
func (*Client) GetSession ¶ added in v0.26.0
GetSession reads one durable session, including its feed head (feedSequence) and whether a turn is currently running.
func (*Client) ListSessionFeed ¶ added in v0.26.0
func (c *Client) ListSessionFeed( ctx context.Context, sessionID uuid.UUID, cursor int64, ) (api.FeedPage, error)
ListSessionFeed reads one page of the session's feed after cursor, oldest first, at the server's default page size.
func (*Client) ListSessions ¶
ListSessions reads one page of the controller's durable sessions.
func (*Client) OpenSession ¶
func (c *Client) OpenSession( ctx context.Context, request api.OpenSessionRequest, ) (api.OpenedSession, error)
OpenSession opens or resumes the session for one workspace. The request's agent space applies only when this call creates the session.
func (*Client) OpenSystemSession ¶ added in v0.45.0
OpenSystemSession opens or resumes the deployment's system session.
func (*Client) Reachable ¶
Reachable reports whether the controller answers its readiness probe. It is the discovery step: a false result means no controller is listening yet.
func (*Client) ReconfigureSession ¶ added in v0.27.0
func (c *Client) ReconfigureSession( ctx context.Context, sessionID uuid.UUID, request api.ReconfigureSessionRequest, ) (api.SessionAgentSpaceDecision, error)
ReconfigureSession moves the session to another agent space. The controller refuses it while a turn runs and stops the session's worker, so the next turn starts in the new agent space.
func (*Client) RunTurn ¶ added in v0.27.0
func (c *Client) RunTurn( ctx context.Context, sessionID uuid.UUID, data wsapi.MessageSendData, handler TurnHandler, ) (TurnResult, error)
RunTurn sends one message to the session over a new socket and streams the session's frames to handler until that message's turn ends.
The turn ends at the message's acknowledgement plus, when the message started a turn, that turn's turn.completed, turn.failed, or turn.cancelled frame. A message the controller queued into a turn already running ends with that turn. Frames of the session's other work, such as child agent runs, reach the handler too. A context cancel closes the socket; it does not cancel the turn on the controller.
type LaunchOptions ¶
type LaunchOptions struct {
// StateDirectory holds the controller's start lock. It is PEEN_STATE_DIR,
// never the configuration directory visible to every worker.
StateDirectory string
// ReadyTimeout bounds the wait for a started controller to answer.
ReadyTimeout time.Duration
// Executable overrides the binary a start runs. Empty uses this process's
// own executable, which is how `peen session open` starts `peen run`.
Executable string
// StartController overrides process launch. Tests supply their own.
StartController func(ctx context.Context, executable string) error
}
LaunchOptions configures the discovery and auto-start sequence.
type Options ¶
type Options struct {
// ListenAddress is the controller's configured HTTP address. A value
// without a host, such as ":8080", is resolved to loopback.
ListenAddress string
// Token is the controller's bearer token. Empty matches a deployment that
// configured none.
Token string
// HTTPClient overrides the transport. Tests supply their own.
HTTPClient *http.Client
// Dial replaces the network dial for both REST and the WebSocket. An
// in-process controller supplies its in-memory listener's dial here, and
// ListenAddress then only names the host in request URLs.
Dial DialFunc
}
Options configures one control client.
type TurnConnection ¶ added in v0.27.0
type TurnConnection struct {
// contains filtered or unexported fields
}
TurnConnection is the socket a turn runs on. A handler uses it to send more messages to the same session, such as the answer to a question the turn asked.
func (*TurnConnection) Reply ¶ added in v0.27.0
func (t *TurnConnection) Reply(message string) error
Reply sends message to the session. While the turn runs, the controller queues it into the turn, which is how the model receives an answer.
type TurnFrame ¶ added in v0.27.0
type TurnFrame struct {
// Raw is the frame exactly as the controller sent it.
Raw json.RawMessage
Type string
Data json.RawMessage
RequestID string
TriggeredBy string
}
TurnFrame is one server frame received while a turn runs.
type TurnHandler ¶ added in v0.27.0
type TurnHandler func(turn *TurnConnection, frame TurnFrame) error
TurnHandler receives every frame of the session while the turn runs, in the order the socket delivered them. An error stops the turn's stream.
type TurnOutcome ¶ added in v0.27.0
type TurnOutcome string
TurnOutcome is how a turn started by RunTurn ended.
const ( TurnOutcomeCompleted TurnOutcome = "completed" TurnOutcomeFailed TurnOutcome = "failed" TurnOutcomeCancelled TurnOutcome = "cancelled" )
type TurnResult ¶ added in v0.27.0
type TurnResult struct {
Outcome TurnOutcome
FailureCode string
FailureMessage string
}
TurnResult reports how the turn ended. FailureCode and FailureMessage come from a message.failed acknowledgement and are empty otherwise.