client

package
v0.41.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 29 Imported by: 0

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

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 New

func New(options Options) (*Client, error)

New builds a client for the configured controller endpoint.

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:

  1. try the configured endpoint;
  2. take the start lock;
  3. re-check the endpoint while holding it;
  4. start the controller only if it is still absent;
  5. 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

func (c *Client) GetSession(
	ctx context.Context,
	sessionID uuid.UUID,
) (api.Session, error)

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

func (c *Client) ListSessions(ctx context.Context) (api.SessionPage, error)

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) Reachable

func (c *Client) Reachable(ctx context.Context) bool

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 DialFunc added in v0.27.0

type DialFunc func(
	ctx context.Context,
	network, address string,
) (net.Conn, error)

DialFunc opens one connection to 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.

Jump to

Keyboard shortcuts

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