21113e18a9
After fixing forensics.md and error-classifier.ts last fire, swept the rest of the tree for the same class of stale reference: - scripts/validate-pack.js: criticalPackages list used \`@sf\` and \`@sf-build\` scopes — neither exists in node_modules; this is in CI (.github/workflows/ci.yml) + prepublishOnly, so the validation step was failing to find anything. Now \`@singularity-forge/pi-coding-agent\` and \`@singularity-forge/rpc-client\` (the actual scope). - src/resources/skills/github-workflows/references/gh/SKILL.md: same GraphQL bug as forensics.md — owner:"sf-build" name:"sf-2" — and three \`gh project\` commands using owner sf-build. The gh issue create command above already used singularity-forge/sf-run, so the follow-up calls always failed. Also retitled "sf-2 Backlog" to "sf-run Backlog". - src/resources/extensions/sf/bootstrap/system-context.ts: deprecation warning linked to https://github.com/sf-build/SF/issues/1492. - packages/mcp-server/README.md, packages/rpc-client/README.md: 9 refs to \`@sf-build/...\` for installable package names — would mislead anyone copy-pasting into npm install. - docs/user-docs/troubleshooting.md (+ zh-CN): GitHub Issues link pointed at github.com/sf-build/SF/issues. - docs/user-docs/getting-started.md (+ zh-CN): clone URL was correct but the next \`cd\` was \`cd sf-2/docker\` — won't exist after a fresh clone of sf-run. - docs/dev/ci-cd-pipeline.md: GHCR org was \`sf-build\`. Code comments containing "sf-2" / "sf-build" in non-active places (parsers.ts banner, error message URLs in tests, dev-doc absolute paths from a contributor's Mac) left alone — they're informational and not addressed by users or runtime. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# @singularity-forge/rpc-client
|
|
|
|
Standalone RPC client SDK for SF. 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
|
|
|
|
```bash
|
|
npm install @singularity-forge/rpc-client
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { RpcClient } from '@singularity-forge/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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
import type {
|
|
RpcCommand,
|
|
RpcResponse,
|
|
RpcInitResult,
|
|
RpcExecutionCompleteEvent,
|
|
RpcCostUpdateEvent,
|
|
RpcV2Event,
|
|
SessionStats,
|
|
SdkAgentEvent,
|
|
RpcClientOptions,
|
|
} from '@singularity-forge/rpc-client';
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|