Agent client

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

Constants

FLAG_TERMINAL

const FLAG_TERMINAL = 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.

FLAG_SESSION_START

const FLAG_SESSION_START = 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.

FLAG_SHUTDOWN

const FLAG_SHUTDOWN = 0b0000_0100

Frame flag: this message requests sandbox shutdown.

AgentClient

Low-level client for raw agent frames.

AgentClient.connectSandbox()

static connectSandbox(name: string, opts?: AgentConnectOptions): Promise<AgentClient>

Example

const client = await AgentClient.connectSandbox("dev", { timeoutMs: 5000 });

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.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

optsAgentConnectOptions

Optional connect settings, e.g. handshake timeout.

Returns

Promise<AgentClient>

Connected client.

AgentClient.connect()

static connect(path: string, opts?: AgentConnectOptions): Promise<AgentClient>

Example

const path = AgentClient.socketPath("dev");
const client = await AgentClient.connect(path);

Connect to an agentd relay socket by path. Use this when you already have the socket path, for example one returned by socketPath().

Parameters

pathstring

Filesystem path of the relay socket.

optsAgentConnectOptions

Optional connect settings, e.g. handshake timeout.

Returns

Promise<AgentClient>

Connected client.

AgentClient.socketPath()

static socketPath(name: string): string

Example

const path = AgentClient.socketPath("dev");

Resolve a sandbox’s agentd relay socket path without connecting. Returns the same path connectSandbox() would dial, so you can talk to agentd over a raw byte transport (for example a transparent relay that splices bytes to and from the socket) instead of this frame client. The sandbox need not be running. Sandbox names are limited to 128 UTF-8 bytes.

Parameters

namestring

Sandbox name, up to 128 UTF-8 bytes.

Returns

string

Relay socket path.

Instance methods

client.request()

request(flags: number, body: Buffer): Promise<RawFrame>

Example

import { encode, decode } from "cbor-x";
import { FLAG_SESSION_START } from "microsandbox";

const body = encode({ v: 1, t: "core.fs.request", p: encode({ op: { Stat: { path: "/etc" } } }) });
const frame = await client.request(FLAG_SESSION_START, body);
console.log(decode(frame.body));

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

Parameters

flagsnumber

Frame flag byte, e.g. FLAG_SESSION_START.

bodyBuffer

CBOR-encoded protocol message body.

Returns

Promise<RawFrame>

The single response frame.

client.stream()

stream(flags: number, body: Buffer): Promise<AgentStream>

Example

import { FLAG_SESSION_START, FLAG_TERMINAL } from "microsandbox";

const stream = await client.stream(FLAG_SESSION_START, body);
for await (const frame of stream) {
  if ((frame.flags & FLAG_TERMINAL) !== 0) break;
}

Open a streaming session. The returned AgentStream carries the protocol correlation id (pass it to send() for follow-up frames) and is also an async iterator of raw frames.

Parameters

flagsnumber

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

bodyBuffer

CBOR-encoded protocol message body.

Returns

Promise<AgentStream>

Open stream of raw frames.

client.send()

send(id: number, flags: number, body: Buffer): Promise<void>

Example

await client.send(stream.id, 0, encode({ v: 1, t: "core.pty.stdin", p: encode({ data: "ls\n" }) }));

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 of the AgentStream returned by stream().

Parameters

idnumber

Correlation id of an open session.

flagsnumber

Frame flag byte.

bodyBuffer

CBOR-encoded protocol message body.

client.readyBytes()

readyBytes(): Buffer

Example

import { decode } from "cbor-x";

const ready = decode(client.readyBytes());

Return the cached handshake core.ready frame body as CBOR bytes. Captured during connect, so this is a synchronous accessor with no protocol traffic.

Returns

Buffer

CBOR-encoded core.ready frame body.

client.close()

close(): Promise<void>

Example

await client.close();

Close the connection. Idempotent: calling it more than once is safe.

AgentStream

Returned by stream()

An open raw agent stream. Implements AsyncIterableIterator<RawFrame>, so it can be driven with for await. The iterator ends after a frame carrying FLAG_TERMINAL or when the underlying stream is exhausted.

stream.id

number Protocol correlation id; pass to send() for follow-up frames

stream.next()

next()

Pull the next frame; done once terminal or exhausted

Returns

Promise<IteratorResult<RawFrame>>

stream.close()

close()

Release the stream handle early (idempotent)

Returns

Promise<void>

stream.return()

return()

Async-iterator early-exit hook; closes the stream

Returns

Promise<IteratorResult<RawFrame>>

stream.Symbol.asyncIterator

[Symbol.asyncIterator]()

Returns itself so the stream is iterable

Returns

AgentStream

Types

RawFrame

Returned by request() · iterated from AgentStream

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

Field	Type	Description
id	`number`	Correlation id from the frame header
flags	`number`	Frame flags (`FLAG_TERMINAL`, `FLAG_SESSION_START`, …)
body	`Buffer`	Raw CBOR-encoded body bytes

AgentConnectOptions

Used by connectSandbox() · connect()

Options for connecting to an agent relay.

Field	Type	Description
timeoutMs	`number`	Handshake timeout in milliseconds. Defaults to `10_000`.

Getting Started

SDKs

CLI

Constants

FLAG_TERMINAL

FLAG_SESSION_START

FLAG_SHUTDOWN

AgentClient

AgentClient.connectSandbox()

AgentClient.connect()

AgentClient.socketPath()

client.request()

client.stream()

client.send()

client.readyBytes()

client.close()

AgentStream

stream.id

stream.next()

stream.close()

stream.return()

stream.Symbol.asyncIterator

Types

RawFrame

AgentConnectOptions

​Constants

​FLAG_TERMINAL

​FLAG_SESSION_START

​FLAG_SHUTDOWN

​AgentClient

​AgentClient.connectSandbox()

​AgentClient.connect()

​AgentClient.socketPath()

​client.request()

​client.stream()

​client.send()

​client.readyBytes()

​client.close()

​AgentStream

​stream.id

​stream.next()

​stream.close()

​stream.return()

​stream.Symbol.asyncIterator

​Types

​RawFrame

​AgentConnectOptions

Constants

FLAG_TERMINAL

FLAG_SESSION_START

FLAG_SHUTDOWN

AgentClient

AgentClient.connectSandbox()

AgentClient.connect()

AgentClient.socketPath()

client.request()

client.stream()

client.send()

client.readyBytes()

client.close()

AgentStream

stream.id

stream.next()

stream.close()

stream.return()

stream.Symbol.asyncIterator

Types

RawFrame

AgentConnectOptions