Agent client - microsandbox

AgentClient is the low-level raw transport for talking to agentd through a running sandbox’s relay socket. For most applications, use Sandbox, Exec, and filesystem helpers instead. Reach for this API when you are building protocol-level tools or higher-level SDK helpers. All request and response bodies are raw CBOR bytes. The SDK handles framing and correlation ids, but it does not encode or decode the CBOR message body for you: decode it with a library such as fxamacker/cbor. The raw body is the full CBOR-encoded protocol Message body (v, t, p), not just the inner payload.

Typical flow

import (
    "context"

    "github.com/fxamacker/cbor/v2"
    m "github.com/superradcompany/microsandbox/sdk/go"
)

ctx := context.Background()

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

body, err := cbor.Marshal(map[string]any{                    // 2. build a CBOR Message
    "v": 1,
    "t": "core.fs.request",
    "p": fsRequestBytes,
})
if err != nil {
    return err
}

frame, err := client.Request(ctx, m.FlagSessionStart, body)  // 3. request / response
if err != nil {
    return err
}
_ = frame.Body

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 methods

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 methods

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

AgentClient

Returned by ConnectAgentSandbox() · ConnectAgentPath()

Low-level client for talking to agentd through the sandbox relay socket. All bodies are raw CBOR bytes: encode and decode them in your code with a library like fxamacker/cbor, and build typed convenience methods on top of this client. Construct it with one of the package-level connect functions.

Method	Returns	Description
`Request(ctx, flags, body)`	`(*RawFrame, error)`	Send one frame, await one response
`Stream(ctx, flags, body)`	`(*AgentStream, error)`	Open a streaming session
`Send(ctx, id, flags, body)`	`error`	Send a follow-up frame on a correlation id
`ReadyBytes()`	`([]byte, error)`	Cached `core.ready` handshake frame body
`Close()`	`error`	Release the handle (idempotent)
`CloseCtx(ctx)`	`error`	Release the handle with a context

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.

Method	Returns	Description
`Next(ctx)`	`(*RawFrame, error)`	Pull the next frame; `nil` at EOF
`ID()`	`uint32`	Protocol correlation id; pass to `Send()` for follow-up frames
`Close(ctx)`	`error`	Release the stream handle

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

​Constants

​FlagTerminal

​FlagSessionStart

​FlagShutdown

​Functions

​m.ConnectAgentSandbox()

​m.ConnectAgentPath()

​m.AgentSocketPath()

​AgentClient methods

​c.Request()

​c.Stream()

​c.Send()

​c.ReadyBytes()

​c.Close()

​c.CloseCtx()

​AgentStream methods

​s.Next()

​s.ID()

​s.Close()

​Types

​AgentClient

​AgentStream

​RawFrame

Constants

FlagTerminal

FlagSessionStart

FlagShutdown

Functions

m.ConnectAgentSandbox()

m.ConnectAgentPath()

m.AgentSocketPath()

AgentClient methods

c.Request()

c.Stream()

c.Send()

c.ReadyBytes()

c.Close()

c.CloseCtx()

AgentStream methods

s.Next()

s.ID()

s.Close()

Types

AgentClient

AgentStream

RawFrame