Documentation
¶
Overview ¶
Package client is the Go client for the Sessions API.
It wraps the generated gRPC stubs with the bookkeeping every caller would otherwise write for itself: dialing, reading the session frame off an Exec stream, walking pagination, and draining streams to completion. Before it existed, agentctl and the langflow adapter had each reimplemented the same loops, which is a sign the contract was leaving work on the caller's side of the line.
It is a convenience over the contract, never a gate in front of it. Sessions returns the underlying stub, so anything the SDK does not model is still reachable without abandoning it.
The SDK adds no auth or transport security, because the reference implementation has none: see docs/security.md before pointing this at anything you do not control the network around.
Index ¶
- type Client
- func (c *Client) Approve(ctx context.Context, uid string, decision api.ApprovalDecision) (*v1.ApproveResponse, error)
- func (c *Client) Close() error
- func (c *Client) CreateSession(ctx context.Context, s *v1.Session) (*v1.Session, error)
- func (c *Client) DeleteSession(ctx context.Context, uid string) (*v1.Session, error)
- func (c *Client) Exec(ctx context.Context, opts ExecOptions) (*TurnResult, error)
- func (c *Client) Fork(ctx context.Context, uid string, opts ForkOptions) ([]*v1.Session, error)
- func (c *Client) GetSession(ctx context.Context, uid string) (*v1.Session, error)
- func (c *Client) ListSessions(ctx context.Context, project string) ([]*v1.Session, error)
- func (c *Client) ListSessionsPage(ctx context.Context, project string, pageSize int32, token string) (*v1.ListSessionsResponse, error)
- func (c *Client) Replay(ctx context.Context, uid string, fromSeq, toSeq int64) ([]*v1.LogRecord, error)
- func (c *Client) Resume(ctx context.Context, uid string, boot bool) (*v1.Session, error)
- func (c *Client) Sessions() v1.SessionsClient
- func (c *Client) Suspend(ctx context.Context, uid string) (*v1.Session, error)
- type ExecOptions
- type ForkOptions
- type Option
- type TurnResult
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to a Sessions server.
func Dial ¶
Dial connects to a Sessions server.
The connection is insecure unless WithDialOptions supplies credentials, which matches what the server currently offers: nothing in the reference implementation terminates TLS.
func (*Client) Approve ¶
func (c *Client) Approve(ctx context.Context, uid string, decision api.ApprovalDecision) (*v1.ApproveResponse, error)
Approve commits only a decision, returning the original decision record on an exact retry. It never resumes compute; call Resume separately to continue. Identity is provenance, not authorization. ApprovalDecision represents a supplied bool, including an explicit denial.
func (*Client) CreateSession ¶
CreateSession registers a session without running anything. It is only needed to set metadata the server cannot infer; Exec creates one on its own otherwise.
func (*Client) DeleteSession ¶
DeleteSession permanently tombstones uid. PENDING acknowledges durable intent only: actors and fork pins remain retained, and GetSession and Replay stay available for audit. It does not stop compute or erase data; callers must inspect the returned deletion state.
Example ¶
Compile the new quickstart snippet in its caller context; it is not run against a server.
package main
import (
"context"
"fmt"
"github.com/agent-primitives/sessions/client"
)
func main() {
_ = func(ctx context.Context, c *client.Client, turn *client.TurnResult) error {
deleted, err := c.DeleteSession(ctx, turn.Session.GetMetadata().GetUid())
if err != nil {
return err
}
fmt.Println(deleted.GetDeletionState(), deleted.GetDeletionRequestedTime())
return nil
}
}
Output:
func (*Client) Exec ¶
func (c *Client) Exec(ctx context.Context, opts ExecOptions) (*TurnResult, error)
Exec runs one turn and returns when it completes.
It reads the stream to completion, which is what the contract requires: every Exec stream opens with the session frame, so an execution error arrives after it and a caller that reads a single frame would see the session instead of the failure.
func (*Client) Fork ¶
Fork branches a session into one or more children, each continuing independently from the same point. Children inherit the parent's project, harness, and model, but not its name.
func (*Client) GetSession ¶
GetSession returns a session's metadata and current log cursor.
func (*Client) ListSessions ¶
ListSessions returns every session in a project, newest first, walking pagination internally.
Walking every page is the default because stopping at the first one silently under-reports, which is a worse failure than being slow: a caller that does not know pagination exists gets a truthful answer rather than a partial one. Use ListSessionsPage for explicit control.
func (*Client) ListSessionsPage ¶
func (c *Client) ListSessionsPage(ctx context.Context, project string, pageSize int32, token string) (*v1.ListSessionsResponse, error)
ListSessionsPage returns one page. pageSize 0 uses the server default; an empty token starts at the first page.
func (*Client) Replay ¶
func (c *Client) Replay(ctx context.Context, uid string, fromSeq, toSeq int64) ([]*v1.LogRecord, error)
Replay re-delivers a session's committed records. It is read-only: no model is invoked and no event is appended.
func (*Client) Resume ¶
Resume brings a suspended session back. boot is sent as ResumeRequest.boot, which is deprecated: the reference service ignores it, and the Runtime backend chooses how the session comes back. It is still sent so a server that reads the field sees what the caller asked for.
func (*Client) Sessions ¶
func (c *Client) Sessions() v1.SessionsClient
Sessions returns the underlying stub, so the SDK is a convenience rather than a ceiling.
type ExecOptions ¶
type ExecOptions struct {
// Session to run against. Empty creates one, whose uid comes back on TurnResult.Session.
Session string
// Inputs for this turn. Empty recovers a current approval-bearing invocation using its
// recorded inputs/config/route; unrelated inputless Exec retains server behavior.
Inputs []string
// Harness overrides the session's configured harness for this turn.
Harness string
// Config is opaque per-execution configuration passed to the harness. It is journaled in
// EXECUTION_START and exposed by Replay; do not put credentials here.
// Nil sends no config; it is not carried over from earlier turns.
Config []byte
// ExpectedLastSeq opts into the single-writer compare-and-swap. Nil appends at the current
// head. A stale value comes back as codes.Aborted rather than interleaving silently.
ExpectedLastSeq *int64
// OnSession is called for each session frame: the initial frame before the turn runs,
// and the final current frame after approval parking or recovery. The initial UID remains
// available even when the execution subsequently fails.
OnSession func(*v1.Session)
// OnRecord is called for each committed record as it arrives, for callers that want to react
// during the turn rather than after it.
OnRecord func(*v1.LogRecord)
// OnDelta is called for each streaming chunk. The server does not emit deltas yet, so this is
// wired for when it does rather than exercised today.
OnDelta func(*v1.Delta)
}
ExecOptions describes one turn.
type ForkOptions ¶
type ForkOptions struct {
// AtSeq is the branch point. 0 forks at the head, which is the only point a memory-snapshot
// harness can fork from.
AtSeq int64
// Count is how many children to create. 0 means one.
Count int32
// Names labels the children in order. It must be empty or exactly Count entries.
Names []string
}
ForkOptions describes a fan-out.
type Option ¶
type Option func(*config)
Option configures a Client.
func WithDialOptions ¶
func WithDialOptions(opts ...grpc.DialOption) Option
WithDialOptions appends gRPC dial options, for credentials, interceptors, or a custom dialer.
func WithProject ¶
WithProject sets the project used by calls that take one and were given none. It is a default for convenience, not an access boundary: project is an exact-match filter, and any caller may name any project. See docs/security.md.
type TurnResult ¶
type TurnResult struct {
// Session is the latest session frame. For an approval pause/recovery it carries the final
// cursor and pending approval; the initial frame supplies the UID even on failure.
Session *v1.Session
// Records committed by this turn, in order.
Records []*v1.LogRecord
// Output is the assistant text this turn committed. It reads the log rather than accumulating
// streamed chunks, so it reflects what was durably recorded.
Output string
// LastSeq is the log head after the turn. Feed it to the next turn's ExpectedLastSeq to keep
// the strict single-writer check without a separate GetSession.
LastSeq int64
}
TurnResult is one completed or approval-paused turn.
Source Files