singularity-forge/packages/rpc-client/README.md

@gsd-build/rpc-client

Standalone RPC client SDK for GSD. Spawn the agent process, perform a v2 protocol handshake, send commands, and consume typed events via an async generator — all in a few lines of TypeScript.

Zero internal dependencies. Ships its own inlined types.

Installation

npm install @gsd-build/rpc-client

Quick Start

import { RpcClient } from '@gsd-build/rpc-client';

const client = new RpcClient({ cwd: process.cwd() });
await client.start();
const { sessionId } = await client.init({ clientId: 'my-app' });
console.log(`Session: ${sessionId}`);

await client.prompt('Create a hello world script');
for await (const event of client.events()) {
  if (event.type === 'execution_complete') break;
  console.log(event.type);
}
await client.shutdown();

API

Constructor

const client = new RpcClient(options?: RpcClientOptions);

Option	Type	Description
cliPath	string	Path to the CLI entry point
cwd	string	Working directory for the agent
env	Record<string, string>	Environment variables
provider	string	AI provider (e.g. "anthropic")
model	string	Model ID (e.g. "claude-sonnet")
args	string[]	Additional CLI arguments

Lifecycle

Method	Description
start()	Spawn the agent process
init(opts?)	v2 handshake — returns sessionId, capabilities
shutdown()	Graceful shutdown
stop()	Force-kill the process

Commands

Method	Description
prompt(message, images?)	Send a prompt
steer(message, images?)	Interrupt with a steering message
followUp(message, images?)	Queue a follow-up message
abort()	Abort current operation
subscribe(events)	Subscribe to event types (["*"] for all)

Events

// Async generator — recommended
for await (const event of client.events()) {
  console.log(event.type);
}

// Callback-based
const unsubscribe = client.onEvent((event) => {
  console.log(event.type);
});

Helpers

Method	Description
waitForIdle(timeout?)	Wait for agent_end event
collectEvents(timeout?)	Collect events until idle
promptAndWait(message, images?, t?)	Send prompt and collect events

Session & Model

Method	Description
getState()	Get session state
setModel(provider, modelId)	Set model
cycleModel()	Cycle to next model
getAvailableModels()	List available models
setThinkingLevel(level)	Set thinking level
cycleThinkingLevel()	Cycle thinking level
compact(instructions?)	Compact session context
getSessionStats()	Get session statistics
bash(command)	Execute a bash command
newSession(parent?)	Start a new session
sendUIResponse(id, response)	Respond to extension UI requests

Type Exports

All protocol types are exported from the package root:

import type {
  RpcCommand,
  RpcResponse,
  RpcInitResult,
  RpcExecutionCompleteEvent,
  RpcCostUpdateEvent,
  RpcV2Event,
  SessionStats,
  SdkAgentEvent,
  RpcClientOptions,
} from '@gsd-build/rpc-client';

License

MIT