Agent client

Low-level raw CBOR transport for communicating with agentd through a sandbox relay.

Constants

FlagTerminal

const FlagTerminal uint8 = 0b0000_0001

Frame flag: this is the last message for the given correlation id. When a frame on an open stream carries this bit, no further frames will arrive for that id. Also available as FLAG_TERMINAL, the cross-SDK constant spelling.

FlagSessionStart

const FlagSessionStart uint8 = 0b0000_0010

Frame flag: this is the first message of a new session. Set it on the opening frame of a request/response RPC or a streaming session. Also available as FLAG_SESSION_START.

FlagShutdown

const FlagShutdown uint8 = 0b0000_0100

Frame flag: this message requests sandbox shutdown. Also available as FLAG_SHUTDOWN.

Functions

m.ConnectAgentSandbox()

func ConnectAgentSandbox(ctx context.Context, name string) (*AgentClient, error)

Example

client, err := m.ConnectAgentSandbox(ctx, "dev")
if err != nil {
    return err
}
defer client.Close()

Connect to a running sandbox by name. Resolves the sandbox’s relay socket path and performs the core.ready handshake. Sandbox names are limited to 128 UTF-8 bytes. Use context.WithTimeout to override the default 10s handshake timeout.

Parameters

ctxcontext.Context

Bounds the handshake; defaults to a 10s timeout if none is set.

namestring

Sandbox name, up to 128 UTF-8 bytes.

Returns

*AgentClient

Connected client.

error

Typed microsandbox error.

m.ConnectAgentPath()

func ConnectAgentPath(ctx context.Context, path string) (*AgentClient, error)

Example

path, err := m.AgentSocketPath("dev")
if err != nil {
    return err
}

client, err := m.ConnectAgentPath(ctx, path)
if err != nil {
    return err
}
defer client.Close()

Connect to an agentd relay socket by path. Use this when you already have the socket path, for example one returned by AgentSocketPath(). Use context.WithTimeout to override the default 10s handshake timeout.

Parameters

ctxcontext.Context

Bounds the handshake; defaults to a 10s timeout if none is set.

pathstring

Filesystem path of the relay socket.

Returns

*AgentClient

Connected client.

error

Typed microsandbox error.

m.AgentSocketPath()

func AgentSocketPath(name string) (string, error)

Example

path, err := m.AgentSocketPath("dev")
if err != nil {
    return err
}
fmt.Println(path)

Resolve a sandbox’s agentd relay socket path without connecting. Returns the same path ConnectAgentSandbox() would dial internally (preferring the hashed path, falling back to the legacy name-derived path), so you can talk to agentd over a raw byte transport (for example a transparent relay that splices bytes between a WebSocket and the socket) instead of this frame client. The sandbox need not be running; the path is derived from the name and the configured home directory.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

Returns

string

Relay socket path.

error

Typed microsandbox error.

AgentClient

Returned by ConnectAgentSandbox() · ConnectAgentPath()

Low-level client for raw agent frames.

c.Request()

func (c *AgentClient) Request(ctx context.Context, flags uint8, body []byte) (*RawFrame, error)

Example

frame, err := client.Request(ctx, m.FlagSessionStart, body)
if err != nil {
    return err
}

var msg map[string]any
if err := cbor.Unmarshal(frame.Body, &msg); err != nil {
    return err
}

Send one frame and await a single response frame. Use for request/response RPCs that produce exactly one terminal response (for example a core.fs.request to its core.fs.response).

Parameters

ctxcontext.Context

Cancels the request.

flagsuint8

Frame flag byte, e.g. FlagSessionStart.

body[]byte

CBOR-encoded protocol message body.

Returns

*RawFrame

The single response frame.

error

Typed microsandbox error.

c.Stream()

func (c *AgentClient) Stream(ctx context.Context, flags uint8, body []byte) (*AgentStream, error)

Example

stream, err := client.Stream(ctx, m.FlagSessionStart, body)
if err != nil {
    return err
}
defer stream.Close(ctx)

for {
    frame, err := stream.Next(ctx)
    if err != nil {
        return err
    }
    if frame == nil || frame.Flags&m.FlagTerminal != 0 {
        break
    }
}

Open a streaming session. The returned AgentStream carries the protocol correlation id (read it with ID() and pass it to Send() for follow-up frames), and yields frames one at a time via Next().

Parameters

ctxcontext.Context

Cancels opening the stream.

flagsuint8

Frame flag byte for the opening frame, e.g. FlagSessionStart.

body[]byte

CBOR-encoded protocol message body.

Returns

*AgentStream

Open stream of raw frames.

error

Typed microsandbox error.

c.Send()

func (c *AgentClient) Send(ctx context.Context, id uint32, flags uint8, body []byte) error

Example

if err := client.Send(ctx, stream.ID(), 0, stdinBytes); err != nil {
    return err
}

Send a follow-up frame on an existing correlation id (for example stdin, a signal, a resize, or data chunks on an open session). Use the id returned by AgentStream.ID().

Parameters

ctxcontext.Context

Cancels the send.

iduint32

Correlation id of an open session.

flagsuint8

Frame flag byte.

body[]byte

CBOR-encoded protocol message body.

Returns

error

Typed microsandbox error.

c.ReadyBytes()

func (c *AgentClient) ReadyBytes() ([]byte, error)

Example

ready, err := client.ReadyBytes()
if err != nil {
    return err
}

var msg map[string]any
if err := cbor.Unmarshal(ready, &msg); err != nil {
    return err
}

Return the cached handshake core.ready frame body as CBOR bytes. Captured during connect, so this reads from the cached handshake rather than producing protocol traffic.

Returns

[]byte

CBOR-encoded core.ready frame body.

error

Typed microsandbox error.

c.Close()

func (c *AgentClient) Close() error

Example

defer client.Close()

Release the client handle. Idempotent: calling it more than once is safe.

Returns

error

Typed microsandbox error.

c.CloseCtx()

func (c *AgentClient) CloseCtx(ctx context.Context) error

Example

if err := client.CloseCtx(ctx); err != nil {
    return err
}

Release the client handle with a caller-controlled context. Like Close(), but lets you bound or cancel the teardown.

Parameters

ctxcontext.Context

Cancels the close.

Returns

error

Typed microsandbox error.

AgentStream

Returned by Stream()

An open raw agent streaming session. Drive it by calling Next() until it returns nil, which happens after a frame carrying FlagTerminal or when the underlying stream is exhausted.

s.Next()

func (s *AgentStream) Next(ctx context.Context) (*RawFrame, error)

Example

for {
    frame, err := stream.Next(ctx)
    if err != nil {
        return err
    }
    if frame == nil {
        break
    }
}

Pull the next frame from the stream. Returns nil, nil at EOF, so loop until the frame is nil or carries FlagTerminal.

Parameters

ctxcontext.Context

Cancels waiting for the next frame.

Returns

*RawFrame

Next frame, or nil at EOF.

error

Typed microsandbox error.

s.ID()

func (s *AgentStream) ID() uint32

Example

id := stream.ID()
if err := client.Send(ctx, id, 0, stdinBytes); err != nil {
    return err
}

Return the protocol correlation id for this stream. Pass it to AgentClient.Send() for follow-up frames in the session.

Returns

uint32

Correlation id for this session.

s.Close()

func (s *AgentStream) Close(ctx context.Context) error

Example

defer stream.Close(ctx)

Release the stream handle.

Parameters

ctxcontext.Context

Cancels the close.

Returns

error

Typed microsandbox error.

Types

RawFrame

Returned by Request() · yielded by Next()

A raw protocol frame. Body is the CBOR-encoded Message body (v, t, p) as it appeared on the wire; decode it with a CBOR library such as fxamacker/cbor.

Field	Type	Description
ID	`uint32`	Correlation id from the frame header
Flags	`uint8`	Frame flags (`FlagTerminal`, `FlagSessionStart`, …)
Body	`[]byte`	Raw CBOR-encoded body bytes

Getting Started

SDKs

CLI

Constants

FlagTerminal

FlagSessionStart

FlagShutdown

Functions

m.ConnectAgentSandbox()

m.ConnectAgentPath()

m.AgentSocketPath()

AgentClient

c.Request()

c.Stream()

c.Send()

c.ReadyBytes()

c.Close()

c.CloseCtx()

AgentStream

s.Next()

s.ID()

s.Close()

Types

RawFrame

​Constants

​FlagTerminal

​FlagSessionStart

​FlagShutdown

​Functions

​m.ConnectAgentSandbox()

​m.ConnectAgentPath()

​m.AgentSocketPath()

​AgentClient

​c.Request()

​c.Stream()

​c.Send()

​c.ReadyBytes()

​c.Close()

​c.CloseCtx()

​AgentStream

​s.Next()

​s.ID()

​s.Close()

​Types

​RawFrame

Constants

FlagTerminal

FlagSessionStart

FlagShutdown

Functions

m.ConnectAgentSandbox()

m.ConnectAgentPath()

m.AgentSocketPath()

AgentClient

c.Request()

c.Stream()

c.Send()

c.ReadyBytes()

c.Close()

c.CloseCtx()

AgentStream

s.Next()

s.ID()

s.Close()

Types

RawFrame