@rovecode-labs/sdk 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @rovecode-labs/sdk
+
+Embed the [rovecode](https://github.com/9Code-Labs/rovecode-community) coding-agent harness in your
+own Bun/TypeScript process — sessions, streamed prompts, background subagent tasks, and the live
+agent tree. **One client = one engine**: the SDK boots the same runtime the CLI boots (no second
+loop), so everything the CLI can do, your process can do.
+
+```bash
+bun add @rovecode-labs/sdk
+```
+
+```ts
+import { createClient, mockStream } from "@rovecode-labs/sdk";
+
+const rc = await createClient({ cwd: process.cwd() }); // resolves your configured provider
+const session = await rc.session.create();
+
+for await (const ev of session.prompt("fix the failing test in src/auth.ts")) {
+  if (ev.type === "agent_tree_update") renderTree(ev.tree);   // live subagent tree
+  if (ev.type === "run_end") console.log(ev.status);
+}
+
+await rc.close();
+```
+
+## Surface
+
+- `createClient({ cwd?, stream?, yolo?, approval? })` → `Promise<RovecodeClient>`
+- `rc.session.create({ id? })` / `rc.session.list()`
+- `session.prompt(goal, { signal? })` → async generator of `SdkEvent` (every `RunEvent` of the run
+  plus `agent_tree_update` frames synthesized from the task registry)
+- `rc.task.start(sessionId, { agent?, goal, label?, isolated? })` · `list` · `wait` · `cancel`
+- `rc.agent.tree(sessionId)` — the current parent→children task tree
+- `rc.events.subscribe(fn)` — client-level tap of everything
+- `mockStream({ turns })` — scripted provider for tests: no keys, no network
+
+## Testing
+
+```ts
+import { createClient, mockStream, textTurn } from "@rovecode-labs/sdk";
+
+const rc = await createClient({ cwd: tmp, stream: mockStream({ turns: [textTurn("done")] }) });
+```
+
+## Notes
+
+- Requires **Bun ≥ 1.3.14** (the harness is Bun-native).
+- Runs fully local: provider keys come from your normal rovecode config (`rovecode connect`).
+- For a hosted/headless setup, run `rovecode serve` (the same repo) and drive it over HTTP —
+  a first-party `remote` transport on these exact types is on the roadmap.
+- 0.x surface: expect evolution, pinned by contract tests upstream.
+
+AGPL-3.0-only · 9Code Labs

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/** @rovecode-labs/sdk — public type surface.
+ *  The runtime types (RunEvent, TaskInfo…) live in the rovecode source tree; here they are
+ *  structural aliases so the SDK is usable without the AGPL source checkout. Shapes are
+ *  pinned by test/unit/sdk-client.test.ts in rovecode-community. */
+
+export type TaskId = string;
+export type TaskStatus = "queued" | "running" | "done" | "failed" | "cancelled";
+
+/** The agent loop's event union (run_start, turn_start, tool_call_*, turn_end, run_end, …). */
+export type RunEvent = { type: string; [key: string]: unknown };
+export type StreamFn = (...args: never[]) => unknown;
+export type ApprovalFn = (req: unknown) => Promise<unknown> | unknown;
+
+export interface AgentNode {
+  id: TaskId;
+  parent: TaskId | null;
+  label: string;
+  agent: string;
+  goal: string;
+  status: TaskStatus;
+  depth: number;
+  isolated: boolean;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  summary?: string;
+  error?: string;
+}
+
+export type SdkEvent = RunEvent | { type: "agent_tree_update"; sessionId: string; tree: AgentNode[] };
+
+export interface ClientOptions {
+  /** project root; default process.cwd() */
+  cwd?: string;
+  /** inject a provider stream (mockStream for tests); null = offline, omitted = resolve from config */
+  stream?: StreamFn | null;
+  /** pre-approve everything (deny rules still hold) */
+  yolo?: boolean;
+  /** approval callback; omitted = policy-only like the headless server */
+  approval?: ApprovalFn;
+}
+
+export interface SessionHandle {
+  readonly id: string;
+  prompt(goal: string, opts?: { signal?: AbortSignal }): AsyncGenerator<SdkEvent, void>;
+}
+
+export interface SessionSummary {
+  id: string;
+  [key: string]: unknown;
+}
+
+export interface TaskInfo {
+  id: TaskId;
+  label: string;
+  agent: string;
+  goal: string;
+  status: TaskStatus;
+  depth: number;
+  parent?: TaskId;
+  [key: string]: unknown;
+}
+
+export interface WaitOptions {
+  timeoutMs?: number;
+}
+
+export interface RovecodeClient {
+  readonly cwd: string;
+  session: {
+    create(opts?: { id?: string }): Promise<SessionHandle>;
+    list(): SessionSummary[];
+  };
+  task: {
+    start(sessionId: string, req: { agent?: string; goal: string; label?: string; isolated?: boolean }):
+      { ok: true; id: TaskId } | { ok: false; reason: string };
+    list(sessionId: string): TaskInfo[];
+    wait(sessionId: string, id: TaskId, opts?: WaitOptions): Promise<TaskInfo | undefined>;
+    cancel(sessionId: string, id: TaskId): boolean;
+  };
+  agent: { tree(sessionId: string): AgentNode[] };
+  events: { subscribe(fn: (e: SdkEvent) => void): () => void };
+  close(): Promise<void>;
+}
+
+/** tasks.ts TaskInfo → AgentNode (parent edge: StartOptions.caller). */
+export declare function agentTree(tasks: TaskInfo[]): AgentNode[];
+
+/** One client = one engine. Boots the same runtime the CLI boots; close() releases it. */
+export declare function createClient(opts?: ClientOptions): Promise<RovecodeClient>;
+
+/** Scripted provider stream for tests — no keys, no network. */
+export declare function mockStream(script: { turns: unknown[] }): StreamFn;
+
+/** Turn builders for mockStream scripts. */
+export declare function textTurn(text: string): unknown;
+export declare function toolTurn(calls: unknown[], opts?: { text?: string }): unknown;