gsd-pi 2.53.0 → 2.54.0-dev.e1efc1a

package/packages/rpc-client/README.md

@@ -0,0 +1,125 @@
+# @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
+
+```bash
+npm install @gsd-build/rpc-client
+```
+
+## Quick Start
+
+```typescript
+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
+
+```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 '@gsd-build/rpc-client';
+```
+
+## License
+
+MIT

package/packages/rpc-client/examples/basic-usage.ts

@@ -0,0 +1,13 @@
+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();

package/packages/rpc-client/package.json

@@ -1,7 +1,16 @@
 {
-  "name": "@gsd/rpc-client",
-  "version": "2.51.0",
+  "name": "@gsd-build/rpc-client",
+  "version": "2.52.0",
   "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gsd-build/gsd-2.git",
+    "directory": "packages/rpc-client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,8 +21,13 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.test.*"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/rpc-client.test.js"
+  },
   "engines": {
     "node": ">=22.0.0"
   }

package/packages/rpc-client/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @gsd-build/rpc-client — standalone RPC client SDK for GSD.
+ *
+ * Re-exports all types, JSONL utilities, and the RpcClient class.
+ */
+
+export * from "./rpc-types.js";
+export { serializeJsonLine, attachJsonlLineReader } from "./jsonl.js";
+export { RpcClient } from "./rpc-client.js";
+export type { RpcClientOptions, RpcEventListener, SdkAgentEvent } from "./rpc-client.js";

package/packages/rpc-client/src/jsonl.ts

@@ -0,0 +1,64 @@
+import type { Readable } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
+
+/**
+ * Serialize a single strict JSONL record.
+ *
+ * Framing is LF-only. Payload strings may contain other Unicode separators such as
+ * U+2028 and U+2029. Clients must split records on `\n` only.
+ */
+export function serializeJsonLine(value: unknown): string {
+	return `${JSON.stringify(value)}\n`;
+}
+
+/**
+ * Attach an LF-only JSONL reader to a stream.
+ *
+ * This intentionally does not use Node readline. Readline splits on additional
+ * Unicode separators that are valid inside JSON strings and therefore does not
+ * implement strict JSONL framing.
+ */
+export function attachJsonlLineReader(stream: Readable, onLine: (line: string) => void): () => void {
+	const decoder = new StringDecoder("utf8");
+	let buffer = "";
+
+	const emitLine = (line: string) => {
+		onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+	};
+
+	const onData = (chunk: string | Buffer) => {
+		buffer += typeof chunk === "string" ? chunk : decoder.write(chunk);
+
+		while (true) {
+			const newlineIndex = buffer.indexOf("\n");
+			if (newlineIndex === -1) {
+				return;
+			}
+
+			emitLine(buffer.slice(0, newlineIndex));
+			buffer = buffer.slice(newlineIndex + 1);
+		}
+	};
+
+	const onEnd = () => {
+		buffer += decoder.end();
+		if (buffer.length > 0) {
+			emitLine(buffer);
+			buffer = "";
+		}
+	};
+
+	const onError = (_err: Error) => {
+		// Stream errors are non-fatal for JSONL reading
+	};
+
+	stream.on("data", onData);
+	stream.on("end", onEnd);
+	stream.on("error", onError);
+
+	return () => {
+		stream.off("data", onData);
+		stream.off("end", onEnd);
+		stream.off("error", onError);
+	};
+}