@opengsd/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.

Public protocol types are shared through @opengsd/contracts and re-exported from this package for compatibility.

Installation

npm install @opengsd/rpc-client

Quick Start

import { RpcClient } from '@opengsd/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 identifier | | model | string | Model ID | | 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);
});

Agent events are delivered as SdkAgentEvent records. Lifecycle, turn, message, and tool-execution events may include optional sessionId and turnId fields for correlation. agent_end may also include abortOrigin with one of "session-transition", "user", "timeout", or "unknown"; treat "session-transition" as internal session-control flow rather than a user cancel or provider failure.

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 '@opengsd/rpc-client';

License

MIT