Navigate

API reference

@pyric/cli/bridge

11 published symbols from @pyric/cli

Generated from the TypeScript declarations shipped at this import path.

Interfaces

Bridge

Properties

PropertyModifierTypeDescription
callerIdentityreadonlyCallerIdentityStoreThe identity this bridge attributes to its own MCP callers, written by auth_impersonate / auth_reset and read by auth_whoami. Held per bridge rather than per MCP session so the CLI and an agent talking to the same bridge read the same answer. dispatch consults it: anything other than the default { mode: 'app-session' } rides the forwarded tool-call frame as actAs, and the peer runs the tool under it.
consumersreadonlyConsumerRegistryRegistry of connected remote consumers.
instanceIdreadonlystringStable per-process identity (see HealthReport.instanceId).
projectreadonlystring-
projectKey?readonlystring-
startedAtreadonlystring-
tabToolsreadonlyTabToolsTools a connected tab of the app answers; a live host sends service reads there.
versionreadonlystring-
workerSessionsreadonly{ attach: WorkerSessionLease; close: void; }-
workerSessions.attachpublicWorkerSessionLease-
workerSessions.closepublicvoid-

Methods

broadcastConsumerPresence()
broadcastConsumerPresence(): void;

Broadcast presence snapshot to sandbox peer and Studio consumers.

Returns

void

detachConsumer()
detachConsumer(clientSessionId: string, socket?: object): void;

Detach an in-flight consumer’s pending ops without notifying peer or tombstoning session. With socket, only the ops that socket dispatched are rejected.

Parameters
ParameterType
clientSessionIdstring
socket?object
Returns

void

disconnectConsumer()
disconnectConsumer(clientSessionId: string): void;

Tear down consumer subscriptions, cancel pending ops, and notify peer.

Parameters
ParameterType
clientSessionIdstring
Returns

void

dispatch()
dispatch(
   name: string,
   args: Record<string, unknown>,
   signal?: AbortSignal,
callerId?: string): Promise<BridgeToolResult>;

Dispatch a tool call to the connected sandbox peer.

Parameters
ParameterType
namestring
argsRecord<string, unknown>
signal?AbortSignal
callerId?string
Returns

Promise<BridgeToolResult>

dispatchWorkerOp()
dispatchWorkerOp(
   op: WorkerOpPayload,
   clientSessionId?: string,
socket?: object): Promise<unknown>;

Relay a generic worker op to the peer’s SharedWorker. Resolves with the worker’s res.value; rejects with an Error carrying .code.

Parameters
ParameterType
opWorkerOpPayload
clientSessionId?string
socket?object
Returns

Promise<unknown>

forwardWorkerMessage()
forwardWorkerMessage(message: InboundMessage, clientSessionId: string): void;
Parameters
ParameterType
messageInboundMessage
clientSessionIdstring
Returns

void

handleSandboxMessage()
handleSandboxMessage(msg: BridgeMessage, generation?: number): void;

Handle a message from the sandbox peer (tool-result, pong, …). generation is the peer generation the transport captured at registration; when provided, worker-res/worker-snap frames from a stale generation are dropped.

Parameters
ParameterType
msgBridgeMessage
generation?number
Returns

void

health()
health(): HealthReport;

/health endpoint payload.

Returns

HealthReport

interruptConsumer()
interruptConsumer(clientSessionId: string, socket?: object): void;

A consumer’s socket was lost while its session lives on for re-attach: fail the socket’s operations in flight, drop it from presence, and tell a host that owns worker ports the session was interrupted, so the host runs its RTDB onDisconnect operations (ADR-0019). With socket, only the operations that socket dispatched fail.

Parameters
ParameterType
clientSessionIdstring
socket?object
Returns

void

isSandboxConnected()
isSandboxConnected(): boolean;

True if a sandbox peer is currently registered.

Returns

boolean

onSandboxPeerConnected()
onSandboxPeerConnected(listener: () => void): () => void;

Register a browser-side peer. Returns a disconnect function the caller MUST invoke when the WS closes. Last-wins: a new registration disconnects the previous peer (its pending calls fail with a clear error).

capabilities come from the peer’s hello — the bridge only sends worker-* frames to a peer that declared 'worker-relay'.

onReplaced fires when a NEWER registration displaces this peer. The transport MUST use it to close the old socket: the browser side’s close handler tears down its relayed worker subscriptions — without this, a replaced tab’s SharedWorker listeners would live until the tab closed, streaming snaps the bridge drops as stale-generation forever.

Parameters
ParameterType
listener() => void
Returns
(): void;
Returns

void

peerCapabilities()
peerCapabilities(): string[];
Returns

string[]

peerGeneration()
peerGeneration(): number;

Generation counter of the CURRENT peer registration (0 = no peer has ever registered). The transport captures this right after registering and tags every inbound message with it, so a frame arriving on a REPLACED peer’s socket (tab refresh mid-flight) can never resolve a new peer’s pending call or deliver a stale subscription snapshot.

Returns

number

recordToolEvent()
recordToolEvent(event: BridgeToolEvent): void;

Record a tool event in the bridge’s audit pipeline. In-process sandbox tools use this path; forwarded tools log inside dispatch().

Parameters
ParameterType
eventBridgeToolEvent
Returns

void

registerSandboxPeer()
registerSandboxPeer(
   send: SendToPeer,
   tools: string[],
   sandboxId: string,
   capabilities?: string[],
   onReplaced?: () => void): () => void;
Parameters
ParameterType
sendSendToPeer
toolsstring[]
sandboxIdstring
capabilities?string[]
onReplaced?() => void
Returns
(): void;
Returns

void

subscribeWorker()
subscribeWorker(
   sub: WorkerSubPayload,
   onSnap: (value: unknown) => void,
   clientSessionId?: string): () => void;

Register a worker subscription. Survives peer churn and is re-issued. Returns the unsubscribe function.

Parameters
ParameterType
subWorkerSubPayload
onSnap(value: unknown) => void
clientSessionId?string
Returns
(): void;
Returns

void

toolNames()
toolNames(): string[];

Tool names the bridge currently exposes to MCP.

Returns

string[]


BridgeOptions

Properties

PropertyTypeDescription
callTimeoutMs?numberPer-call request timeout in ms when forwarding to the browser. Defaults to 30s; the bridge rejects the MCP call with a clear “sandbox call timed out” error after this.
logger?BridgeLoggerPayload-free protocol diagnostics; defaults to the bridge stderr logger.
mode?"sandbox" | "live"Runtime mode stamped onto MCP envelopes and tool events. Defaults to 'sandbox'.
onToolEvent?(event: BridgeToolEvent) => voidHook called whenever a tool finishes (success or failure). Use this for the audit log — write the entry to disk here. The bridge does not own audit-log persistence.
project?stringSandbox label surfaced in /health and audit-log paths.
projectKey?stringLocal project directory identity supplied by the owning serve session.
tabRoute?(tabs: TabTools, name: string, args: Record<string, unknown>) => ToolResult<unknown> | Promise<ToolResult<unknown>>A live host’s routing of a forwarded call: a tab’s answer or a refusal, or undefined to forward it to the sandbox peer as usual.
versionstringBridge version surfaced in /health + Hello messages.

HealthReport

Health report returned by the bridge’s GET /health endpoint.

Properties

PropertyTypeDescription
instanceIdstringRandom identity, stable for this bridge process’s lifetime. The discovery pointer (.pyric/serve.json) records the same value, so a proxy can confirm it reached the SAME server the pointer names — two sandboxes can collide on one port across loopback families (IPv4 *:P + IPv6 [::1]:P), and mode alone can’t tell them apart. (Not version — that’s hardcoded.)
mode"sandbox"Constant provenance marker: the programmatic bridge is sandbox-only.
projectstringSandbox identifier surfaced in health and audit metadata.
sandboxConnectedbooleanWhether a browser tab is currently connected over /sandbox.
startedAtstringISO timestamp the bridge started.
status"ok"-
versionstringBridge package version.

ServerHandle

Properties

PropertyModifierType
auditLogPathreadonlystring
bridgereadonlyBridge
mcpUrlreadonlystring
portreadonlynumber
sessionTokenreadonlystring
urlreadonlystring

Methods

stop()
stop(): Promise<void>;
Returns

Promise<void>


StartServerOptions

Properties

PropertyTypeDescription
allowedHosts?string[]Extra hostnames allowed past the WS-upgrade rebinding/origin guard (besides the loopback set the bridge binds to). Mirrors serve’s --allowed-host.
auditWriter?AuditWriterOverride the audit writer (testing).
disableAuditLog?booleanDisable the audit log writer (useful in tests).
logger?BridgeLoggerPremortem #U1 — logger; defaults to stderr [pyric] prefix.
maxSessions?numberPremortem #A2 — refuse new sessions when this many are active. Default 50.
port?numberPort to bind. Default: 5174. Env: PYRIC_PORT.
project?stringSandbox label surfaced in health and audit metadata.
projectDir?string-
requireSessionToken?booleanRequire x-pyric-session-token on /mcp and for full /health details. Default: false.
sessionIdleMs?numberPremortem #A2 — kill idle sessions after this many ms. Default 10 min.
sessionToken?stringPer-boot capability token used when requireSessionToken is enabled; minted per boot when omitted.
silent?booleanConvenience: install a silent logger (tests).

Variables

DEFAULT_BRIDGE_PORT

const DEFAULT_BRIDGE_PORT: 5174 = 5174;

Default port the standalone bridge binds to.


DEFAULT_HEALTH_PATH

const DEFAULT_HEALTH_PATH: "/health" = "/health";

Default health endpoint path.


DEFAULT_MCP_PATH

const DEFAULT_MCP_PATH: "/mcp" = "/mcp";

Default HTTP path the MCP client connects to.


DEFAULT_SANDBOX_PATH

const DEFAULT_SANDBOX_PATH: "/sandbox" = "/sandbox";

Default WS path the browser connects to.

Functions

createBridge()

function createBridge(opts: BridgeOptions): Bridge;

Parameters

ParameterType
optsBridgeOptions

Returns

Bridge


startServer()

function startServer(opts?: StartServerOptions): Promise<ServerHandle>;

Parameters

ParameterType
opts?StartServerOptions

Returns

Promise<ServerHandle>