rovecode 0.4.0-beta.3 → 0.4.0

package/src/providers/thinking.ts

@@ -0,0 +1,189 @@
+/** ONE effort dial (core/types.ts ThinkingEffort: auto | off | low | medium | high), every wire it can reach.
+ *  This module answers, for a model on a protocol, two questions the adapters and the humans both ask:
+ *  which request fields carry the level, and — in one sentence — what the model will actually receive.
+ *  stream.ts spreads `thinkingPlan(...).fields` into the body; /effort and `rovecode model show` print `says`.
+ *
+ *  Rules (Berkay, 2026-09-04): `auto` sends NOTHING and leaves the endpoint's own default standing (the
+ *  Claude 5 family reasons adaptively on its own; the old default "off" switched that off). `off` is an
+ *  explicit disable where the API has one, otherwise nothing. A level maps onto the endpoint's own
+ *  vocabulary; where the vocabulary has fewer steps, medium rounds UP (a rovecode "medium" asks for more
+ *  than "low"). A model that always reasons, or has no reasoning mode, gets nothing — sending a dial such a
+ *  model rejects is a 400, not a downgrade (grok-4, gpt-4-class on OpenAI proper).
+ *
+ *  Dialects are matched by MODEL ID, provider-agnostic (the same GLM under kaesra, zai or openrouter is one
+ *  family) — except OpenRouter, whose unified `reasoning` object wins for every model it fronts, and Groq's
+ *  Qwen vocabulary. The catalog's word is stronger than any regex: a model models.dev lists WITHOUT a
+ *  reasoning mode (ModelRef.reasoning === false, stamped by cli/runtime.ts buildDef) gets nothing.
+ *
+ *  Only Anthropic and GLM-5.3 are measured live (stream.ts header, profiles.ts header). The other
+ *  vocabularies are the vendors' published API docs as of 2026-09 — docs/thinking.md carries the matrix
+ *  and marks each row measured or documented. */
+
+import type { ModelRef, ThinkingEffort } from "../core/types.ts";
+import { GLM_53_MODEL_RE, wireProfileFor } from "./profiles.ts";
+
+export type WireProtocol = "openai" | "anthropic";
+type Level = "low" | "medium" | "high";
+type Setting = "auto" | "off" | Level;
+
+export interface ThinkingPlan {
+  /** the dialect that answered (docs/thinking.md row) */
+  dialect: string;
+  /** spread into the request body */
+  fields: Record<string, unknown>;
+  /** one sentence for the human: the exact field, or why nothing goes */
+  says: string;
+}
+
+/** undefined (a bare ModelRef) is auto — the runtime stamps every ref, but adapters must not care */
+const setting = (e: ThinkingEffort | undefined): Setting => e ?? "auto";
+const NOTHING_AUTO = "nothing — auto: the endpoint's own default stands";
+
+// ------------------------------------------------------------------ Anthropic (Messages API), two shapes
+
+/** Anthropic has TWO request shapes and no model exposes both — see the measured table in stream.ts.
+ *  The shape is learned per provider+model from a wrong-shape 400 (stream.ts anthropicPost). */
+export type AnthropicThinkingShape = "effort" | "budget";
+
+/** The budget in tokens per level for the older `thinking.enabled` shape. Steps ~x4 apart so the
+ *  levels are felt. The endpoint requires ≥1024 and max_tokens strictly greater (anthropicMaxTokens). */
+export function thinkingBudget(effort: ThinkingEffort | undefined): number | null {
+  switch (effort) {
+    case "low": return 2_048;
+    case "medium": return 8_192;
+    case "high": return 24_576;
+    default: return null; // "off", "auto" and unset: no budget
+  }
+}
+
+/** the request fields that carry the effort, for one shape */
+export function anthropicThinking(effort: ThinkingEffort | undefined, shape: AnthropicThinkingShape): Record<string, unknown> {
+  if (effort === undefined || effort === "auto") return {};              // unset / auto: leave the model's default alone (Claude 5: adaptive, high)
+  if (effort === "off") return { thinking: { type: "disabled" } };       // explicit, deliberate: opus-5 thinks unless told not to
+  if (shape === "effort") return { output_config: { effort } };          // low | medium | high (the API also has xhigh/max)
+  const budget = thinkingBudget(effort);
+  return budget === null ? {} : { thinking: { type: "enabled", budget_tokens: budget } };
+}
+
+function anthropicPlan(level: Setting, shape: AnthropicThinkingShape): ThinkingPlan {
+  const fields = anthropicThinking(level, shape);
+  const says = level === "auto" ? NOTHING_AUTO
+    : level === "off" ? 'thinking: { type: "disabled" } — an explicit off; Claude 5 reasons by default'
+    : `${JSON.stringify(fields).slice(1, -1).replace(/"(\w+)":/g, "$1: ").replace(/,/g, ", ")} (the ${shape} shape — learned from the endpoint, kept per model)`;
+  return { dialect: `anthropic/${shape}`, fields, says };
+}
+
+// ------------------------------------------------------------------ OpenAI-compatible dialects
+
+interface Dialect {
+  id: string;
+  matches(m: ModelRef): boolean;
+  /** never called with "auto" — that is answered centrally with nothing */
+  plan(level: "off" | Level, m: ModelRef): { fields: Record<string, unknown>; says: string };
+}
+
+const q = (s: string): string => JSON.stringify(s);
+const nothing = (why: string): { fields: Record<string, unknown>; says: string } => ({ fields: {}, says: `nothing — ${why}` });
+const word = (w: string, note = ""): { fields: Record<string, unknown>; says: string } => ({ fields: { reasoning_effort: w }, says: `reasoning_effort: ${q(w)}${note ? ` (${note})` : ""}` });
+const onOff = (on: boolean, vendor: string): { fields: Record<string, unknown>; says: string } => ({
+  fields: { thinking: { type: on ? "enabled" : "disabled" } },
+  says: `thinking: { type: ${q(on ? "enabled" : "disabled")} } (${vendor} has an on/off switch, no levels)`,
+});
+const id = (re: RegExp) => (m: ModelRef): boolean => re.test(m.model);
+
+const DIALECTS: readonly Dialect[] = [
+  // the catalog's word first: models.dev says this model has no reasoning mode — a dial would be rejected or ignored
+  { id: "catalog: no reasoning mode", matches: (m) => m.reasoning === false,
+    plan: (_l, m) => nothing(`the catalog lists ${m.model} without a reasoning mode, so no dial is sent`) },
+  // OpenRouter normalizes every upstream behind one object; its own words (low|medium|high, enabled)
+  { id: "openrouter", matches: (m) => m.provider === "openrouter",
+    plan: (l) => l === "off"
+      ? { fields: { reasoning: { enabled: false } }, says: "reasoning: { enabled: false } (OpenRouter's unified field; a model that always reasons ignores it)" }
+      : { fields: { reasoning: { effort: l } }, says: `reasoning: { effort: ${q(l)} } (OpenRouter's unified field, translated per upstream)` } },
+  // GLM-5.3: measured (profiles.ts) — low|high|max, medium rounds up to high, cannot be switched off. The
+  // words come from the wire profile; ROVECODE_PROFILE=off means "no GLM tuning at all", so the plain
+  // OpenAI word goes instead (the A/B the off-switch exists for), and off sends nothing either way.
+  { id: "glm-5.3", matches: id(GLM_53_MODEL_RE),
+    plan: (l, m) => {
+      if (l === "off") return nothing("GLM-5.3 cannot switch thinking off (Z.ai: thinking.type accepts enabled only); the endpoint default is max");
+      const profile = wireProfileFor(m);
+      if (profile === null) return word(l, "ROVECODE_PROFILE=off: the plain word, not GLM's low | high | max");
+      return word(profile.reasoningEffort(l)!, "GLM's words are low | high | max; medium rounds up");
+    } },
+  { id: "glm", matches: id(/(^|[/:])glm-(4\.[5-9]|4\.\d{2,}|5(\.\d+)?)(?=[-:]|$)/i), plan: (l) => onOff(l !== "off", "GLM") },
+  { id: "deepseek", matches: id(/deepseek/i),
+    plan: (l, m) => /reasoner|r1/i.test(m.model) ? nothing(`${m.model} always thinks — no dial`) : onOff(l !== "off", "DeepSeek") },
+  { id: "qwen", matches: id(/(^|[/:])(qwen|qwq)/i),
+    plan: (l, m) => {
+      if (m.provider === "groq") return l === "off" ? word("none", "Groq's Qwen words are none | default") : word("default", "Groq's Qwen words are none | default");
+      if (l === "off") return { fields: { enable_thinking: false }, says: "enable_thinking: false (DashScope / most Qwen hosts; a vLLM host wants chat_template_kwargs instead and ignores this)" };
+      const budget = thinkingBudget(l)!;
+      return { fields: { enable_thinking: true, thinking_budget: budget }, says: `enable_thinking: true, thinking_budget: ${budget} (DashScope's fields; a host without them ignores both)` };
+    } },
+  { id: "kimi", matches: id(/kimi|moonshot/i),
+    plan: (l, m) => /thinking/i.test(m.model) ? nothing(`${m.model} always thinks — no dial`)
+      : /k2[.-]5|k2\.5/i.test(m.model) ? onOff(l !== "off", "Moonshot K2.5") : nothing(`${m.model} has no thinking mode (the -thinking variant does)`) },
+  { id: "gemini", matches: id(/gemini/i),
+    plan: (l, m) => l !== "off" ? word(l, "Google's OpenAI-compatible layer maps low | medium | high to a thinking budget")
+      : /flash/i.test(m.model) ? { fields: { extra_body: { google: { thinking_config: { thinking_budget: 0 } } } }, says: "extra_body.google.thinking_config.thinking_budget: 0 (Flash can switch thinking off; Pro cannot)" }
+      : nothing(`${m.model} cannot switch thinking off (Gemini Pro keeps a minimum budget)`) },
+  // xAI (docs.x.ai, fetched 2026-09-04): grok-4.3 / 4.5 / 4.6 / 4.20 take reasoning_effort none | low | medium | high;
+  // the retired grok-4-0709 / grok-4-fast slugs are served by grok-4.3 since 2026-05-15, so they take the same words
+  { id: "grok", matches: id(/grok/i),
+    plan: (l, m) => /non-reasoning/i.test(m.model) ? nothing(`${m.model} has no reasoning mode`)
+      : /grok-3-mini/i.test(m.model) ? (l === "off" ? nothing("grok-3-mini cannot switch reasoning off") : word(l === "low" ? "low" : "high", "xAI's words for grok-3-mini are low | high; medium rounds up"))
+      : l === "off" ? word("none", "xAI's explicit off (grok-4.3 and later; retired grok-4 slugs are served by grok-4.3)") : word(l, "xAI's words are none | low | medium | high") },
+  { id: "gpt-oss", matches: id(/gpt-oss/i), plan: (l) => l === "off" ? nothing("gpt-oss cannot switch reasoning off (low is the floor)") : word(l) },
+  { id: "openai o-series", matches: id(/(^|[/:])o[134](-|$)/i), plan: (l, m) => l === "off" ? nothing(`${m.model} cannot switch reasoning off`) : word(l) },
+  { id: "openai gpt-5", matches: id(/(^|[/:])gpt-5/i),
+    plan: (l, m) => l !== "off" ? word(l)
+      : /gpt-5\.[1-9]/i.test(m.model) ? word("none", "gpt-5.1 and later: the explicit off") : word("minimal", "gpt-5 has no off; minimal is its floor") },
+  { id: "openai gpt-4 class", matches: id(/(^|[/:])(gpt-4|gpt-3\.5|chatgpt)/i), plan: (_l, m) => nothing(`${m.model} has no reasoning mode and OpenAI rejects reasoning_effort for it`) },
+  { id: "mistral", matches: id(/magistral|mistral|codestral|ministral|pixtral/i),
+    plan: (_l, m) => /magistral/i.test(m.model) ? nothing("Magistral always reasons — no dial") : nothing(`${m.model} has no reasoning mode`) },
+  { id: "minimax", matches: id(/minimax/i), plan: (_l, m) => nothing(`${m.model} always reasons — no dial`) },
+  // the floor for anything else: the OpenAI word; off sends nothing (no common explicit disable)
+  { id: "openai-compatible default", matches: () => true,
+    plan: (l) => l === "off" ? nothing("off sends nothing here: no common explicit disable on OpenAI-compatible endpoints; a model without a reasoning mode ignores the word anyway")
+      : word(l, "the OpenAI word; a model without a reasoning mode ignores it") },
+];
+
+/** the dialect a model on the OpenAI-compatible wire speaks (for docs and the matrix) */
+export function dialectFor(model: ModelRef): Dialect["id"] {
+  return DIALECTS.find((d) => d.matches(model))!.id;
+}
+
+/** what goes on the wire for this model, on this protocol, at its effort — and the sentence that says so */
+export function thinkingPlan(model: ModelRef, protocol: WireProtocol, opts: { shape?: AnthropicThinkingShape } = {}): ThinkingPlan {
+  const level = setting(model.effort);
+  if (protocol === "anthropic") return anthropicPlan(level, opts.shape ?? "effort");
+  const d = DIALECTS.find((x) => x.matches(model))!;
+  if (level === "auto") return { dialect: d.id, fields: {}, says: NOTHING_AUTO };
+  return { dialect: d.id, ...d.plan(level, model) };
+}
+
+/** the five rows `rovecode model show` prints: level → what this model receives */
+export function thinkingTable(model: ModelRef, protocol: WireProtocol, opts: { shape?: AnthropicThinkingShape } = {}): { level: ThinkingEffort; says: string }[] {
+  return (["auto", "off", "low", "medium", "high"] as const).map((level) => ({ level, says: thinkingPlan({ ...model, effort: level }, protocol, opts).says }));
+}
+
+/** the one line the /effort note appends: `<provider/model> receives: <says>` */
+export function thinkingLine(model: ModelRef, protocol: WireProtocol, opts: { shape?: AnthropicThinkingShape } = {}): string {
+  return `${model.provider}/${model.model} receives: ${thinkingPlan(model, protocol, opts).says}`;
+}
+
+/** `rovecode model show`: the model, its protocol and dialect, then every level with what it puts on the
+ *  wire — the current level marked. `model.effort` is the current level. */
+export function thinkingReport(model: ModelRef, protocol: WireProtocol, opts: { shape?: AnthropicThinkingShape; source?: string; catalog?: string } = {}): string[] {
+  const current = setting(model.effort);
+  const dialect = protocol === "anthropic" ? `anthropic (${opts.shape ?? "effort"} shape)` : dialectFor(model);
+  const lines = [
+    `${model.provider}/${model.model}${opts.source ? `  (${opts.source})` : ""}`,
+    `  protocol  ${protocol}`,
+    `  dialect   ${dialect}${model.reasoning === false ? "  — the catalog lists no reasoning mode" : model.reasoning === true ? "  — the catalog lists a reasoning mode" : ""}`,
+    ...(opts.catalog ? [`  prices    ${opts.catalog}`] : []), // where the numbers /cost uses come from — models.dev, or rovecode's own table
+    `  effort    ${current}  (ROVECODE_EFFORT / --effort / /effort)`,
+  ];
+  for (const row of thinkingTable(model, protocol, opts)) lines.push(`  ${row.level === current ? "*" : " "} ${row.level.padEnd(7)} ${row.says}`);
+  return lines;
+}

package/src/providers/wire-messages.ts

@@ -0,0 +1,129 @@
+/** Wire message lowering (ADR-003 seam; extracted from stream.ts for the 400-line cap): harness
+ *  Message[] → OpenAI chat-completions / Anthropic Messages request shapes. Text and tool shapes
+ *  are byte-identical to the pre-#34 stream.ts lowering. Port #34 adds image parts:
+ *  - vision model: a USER message carrying images becomes a content-block array in part order —
+ *    OpenAI `{type:"image_url", image_url:{url:"data:<mime>;base64,<data>", detail:"auto"}}`,
+ *    Anthropic `{type:"image", source:{type:"base64", media_type, data}}`; image-free messages
+ *    keep their plain-string content, so nothing changes for existing histories;
+ *  - no vision (`vision: false` — stream.ts asks the models.dev catalog): each image lowers to
+ *    imagePlaceholder() text and the message stays a plain string. The session keeps the real
+ *    image; only the request is substituted (cline media.ts:6-12 pattern, opencode
+ *    provider/transform.ts:409-441 unsupportedParts);
+ *  - a sidecar that cannot be read lowers to a placeholder too — a request body never throws.
+ *  Images on assistant/tool messages are nothing this harness produces (tool results with images
+ *  are out of scope for #34): an assistant message WITHOUT tool calls lowers them to placeholder
+ *  text (lowerContent's non-user branch); a tool-role message emits its tool_result parts only and
+ *  an assistant message WITH tool calls emits partsText + tool_calls, so image parts on those two
+ *  shapes are dropped from the request — never turned into blocks. */
+
+import type { Message, ImagePart } from "../core/types.ts";
+import { partsText } from "../core/loop.ts";
+import { anthropicImageBlock, openaiImageBlock, imagePlaceholder } from "../core/images.ts";
+
+export interface WireOptions {
+  /** the target model accepts image input; default true (unknown models are given the image —
+   *  a wrong guess fails loudly at the provider instead of silently dropping the user's image) */
+  vision?: boolean;
+}
+
+type Block = Record<string, unknown>;
+
+/** Content for a non-tool message: the pre-#34 plain string when no image is present; blocks in
+ *  part order for a user message the model can see; placeholder text otherwise (text parts glue
+ *  with "" exactly as partsText does, each image is its own line). */
+function lowerContent(m: Message, vision: boolean, toBlock: (p: ImagePart) => Block | undefined): string | Block[] {
+  if (!m.parts.some((p) => p.kind === "image")) return partsText(m.parts);
+  if (vision && m.role === "user") {
+    const blocks: Block[] = [];
+    for (const p of m.parts) {
+      if (p.kind === "text") { if (p.text) blocks.push({ type: "text", text: p.text }); }
+      else if (p.kind === "image") blocks.push(toBlock(p) ?? { type: "text", text: imagePlaceholder(p, "file unavailable") });
+    }
+    return blocks;
+  }
+  const pieces: string[] = [];
+  let text = "";
+  for (const p of m.parts) {
+    if (p.kind === "text") text += p.text;
+    else if (p.kind === "image") {
+      if (text) { pieces.push(text); text = ""; }
+      pieces.push(imagePlaceholder(p, vision ? "file unavailable" : undefined));
+    }
+  }
+  if (text) pieces.push(text);
+  return pieces.join("\n");
+}
+
+export function toOpenAiMessages(messages: Message[], opts: WireOptions = {}): Record<string, unknown>[] {
+  const vision = opts.vision ?? true;
+  const out: Record<string, unknown>[] = [];
+  for (const m of messages) {
+    const calls = m.parts.filter((p) => p.kind === "tool_call");
+    const results = m.parts.filter((p) => p.kind === "tool_result");
+    if (m.role === "tool") {
+      for (const r of results) {
+        if (r.kind === "tool_result") out.push({ role: "tool", tool_call_id: r.callId, content: r.output });
+      }
+      continue;
+    }
+    if (m.role === "assistant" && calls.length > 0) {
+      out.push({
+        role: "assistant",
+        content: partsText(m.parts) || null,
+        tool_calls: calls.map((c) => c.kind === "tool_call" ? {
+          id: c.id, type: "function", function: { name: c.tool, arguments: JSON.stringify(c.args) },
+        } : {}),
+      });
+    } else {
+      const content = lowerContent(m, vision, (p) => openaiImageBlock(p));
+      if (content.length > 0 || m.role === "system") out.push({ role: m.role, content });
+    }
+  }
+  return out;
+}
+
+/** StreamOptions.tools carries bare ToolSchema entries (name/description/args) — that is what
+ *  every call site (loop → adapters) passes. Tolerate a {schema} wrapper (a full Tool object)
+ *  too, so a mis-passed registry entry degrades gracefully instead of throwing mid-request. */
+export function asToolSchema(t: unknown): { name: string; description: string; args: Record<string, unknown> } {
+  const o = t as { name?: string; description?: string; args?: Record<string, unknown>; schema?: { name: string; description: string; args: Record<string, unknown> } };
+  return o.schema ?? { name: o.name ?? "unknown", description: o.description ?? "", args: o.args ?? {} };
+}
+
+export function toOpenAiToolSchemas(tools: unknown[]): Record<string, unknown>[] {
+  return tools.map((t) => {
+    const s = asToolSchema(t);
+    return { type: "function", function: { name: s.name, description: s.description, parameters: s.args } };
+  });
+}
+
+export function toAnthropicMessages(messages: Message[], opts: WireOptions = {}): Record<string, unknown>[] {
+  const vision = opts.vision ?? true;
+  const out: Record<string, unknown>[] = [];
+  for (const m of messages) {
+    if (m.role === "system") continue;
+    const calls = m.parts.filter((p) => p.kind === "tool_call");
+    const results = m.parts.filter((p) => p.kind === "tool_result");
+    if (m.role === "tool") {
+      for (const r of results) {
+        if (r.kind === "tool_result") {
+          out.push({ role: "user", content: [{ type: "tool_result", tool_use_id: r.callId, content: r.output, is_error: !r.ok }] });
+        }
+      }
+      continue;
+    }
+    if (m.role === "assistant" && calls.length > 0) {
+      const text = partsText(m.parts);
+      const content: Block[] = [];
+      if (text) content.push({ type: "text", text });
+      for (const c of calls) {
+        if (c.kind === "tool_call") content.push({ type: "tool_use", id: c.id, name: c.tool, input: c.args });
+      }
+      out.push({ role: "assistant", content });
+    } else {
+      const content = lowerContent(m, vision, anthropicImageBlock);
+      if (content.length > 0) out.push({ role: m.role === "user" ? "user" : "assistant", content });
+    }
+  }
+  return out;
+}

package/src/sdk/client.ts

@@ -0,0 +1,225 @@
+/** @rovecode/sdk — local-mode client (Faz F1, docs/design/sdk-blueprint.md §2-3).
+ *
+ *  ONE interface over the harness core, two planned transports: "local" imports the core
+ *  in-process (this file), "remote" will speak HTTP/SSE to `rovecode serve` against the same
+ *  types. The client is render-only and loop-free: every run goes through the ONE agentLoop
+ *  via bootRuntime (ADR-003), exactly like cmdRun — the SDK adds a contract, not a second engine.
+ *
+ *  Event model: RunEvent stays untouched (session replay purity); the SDK unions it with
+ *  `agent_tree_update`, synthesized from TaskManager.subscribe — the tree is derived state,
+ *  not transcript, so it never enters the session JSONL. */
+
+import { join } from "node:path";
+import type { ApprovalFn, ModelRef, RunEvent, StreamFn } from "../core/types.ts";
+import type { RunConfig } from "../core/types.ts";
+import { agentLoop, SteeringQueue } from "../core/loop.ts";
+import { listSessions, type SessionSummary } from "../core/session.ts";
+import type { TaskId, TaskInfo, TaskStatus, WaitOptions } from "../core/tasks.ts";
+import { bootRuntime, type Runtime } from "../cli/runtime.ts";
+
+/** A node in the live subagent tree (TaskManager flattened, parent edge explicit). */
+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 {
+  cwd?: string;
+  /** test seam — injected stream wins over provider resolution; null forces "no provider" */
+  stream?: StreamFn | null;
+  /** permission level: true = "auto" (yolo). Default "ask" + the approval callback. */
+  yolo?: boolean;
+  /** the SDK's human-equivalent: a request the rules mark "prompt" lands here */
+  approval?: ApprovalFn;
+}
+
+export interface SessionHandle {
+  readonly id: string;
+  /** Run one prompt; yields the loop's events verbatim plus agent_tree_update. */
+  prompt(goal: string, opts?: { signal?: AbortSignal }): AsyncGenerator<SdkEvent, void>;
+}
+
+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 → sdk AgentNode (parent edge: StartOptions.caller). */
+export function agentTree(tasks: TaskInfo[]): AgentNode[] {
+  return tasks.map((t) => ({
+    id: t.id, parent: t.parent ?? null, label: t.label, agent: t.agent, goal: t.goal,
+    status: t.status, depth: t.depth, isolated: t.isolated, createdAt: t.createdAt,
+    ...(t.startedAt !== undefined ? { startedAt: t.startedAt } : {}),
+    ...(t.finishedAt !== undefined ? { finishedAt: t.finishedAt } : {}),
+    ...(t.summary !== undefined ? { summary: t.summary } : {}),
+    ...(t.error !== undefined ? { error: t.error } : {}),
+  }));
+}
+
+/** Push-queue: producers push, one consumer drains via async iteration. */
+class EventQueue {
+  private buf: SdkEvent[] = [];
+  private wake: (() => void) | null = null;
+  private closed = false;
+  push(e: SdkEvent): void {
+    if (this.closed) return;
+    this.buf.push(e);
+    this.wake?.();
+  }
+  close(): void { this.closed = true; this.wake?.(); }
+  async *drain(): AsyncGenerator<SdkEvent, void> {
+    for (;;) {
+      const e = this.buf.shift();
+      if (e !== undefined) { yield e; continue; }
+      if (this.closed) return;
+      await new Promise<void>((r) => { this.wake = r; });
+      this.wake = null;
+    }
+  }
+}
+
+export async function createClient(opts: ClientOptions = {}): Promise<RovecodeClient> {
+  const cwd = opts.cwd ?? process.cwd();
+  const sessionsRoot = join(cwd, ".rovecode", "sessions");
+  const runtimes = new Map<string, Runtime>();
+  const listeners = new Set<(e: SdkEvent) => void>();
+  const broadcast = (e: SdkEvent): void => { for (const fn of listeners) fn(e); };
+
+  async function runtimeFor(id: string): Promise<Runtime> {
+    const hit = runtimes.get(id);
+    if (hit) return hit;
+    const rtOpts = { cwd, sessionId: id, ...(opts.stream !== undefined ? { stream: opts.stream } : {}) };
+    const rt = await bootRuntime(rtOpts);
+    // background-task status flips become tree events, even between prompts
+    rt.tasks.subscribe(() => {
+      broadcast({ type: "agent_tree_update", sessionId: id, tree: agentTree(rt.tasks.list()) });
+    });
+    runtimes.set(id, rt);
+    return rt;
+  }
+
+  function requireRuntime(id: string): Runtime {
+    const rt = runtimes.get(id);
+    if (!rt) throw new Error(`unknown session '${id}' — session.create() it first (SDK v1 tracks live sessions only)`);
+    return rt;
+  }
+
+  return {
+    cwd,
+    session: {
+      async create(createOpts: { id?: string } = {}): Promise<SessionHandle> {
+        const id = createOpts.id ?? `sdk-${Date.now().toString(36)}`;
+        const rt = await runtimeFor(id);
+        const why = rt.noProviderReason();
+        if (why !== null && rt.stream === null) throw new Error(`no provider: ${why}`);
+        return {
+          id,
+          async *prompt(goal: string, pOpts: { signal?: AbortSignal } = {}): AsyncGenerator<SdkEvent, void> {
+            const stream = rt.stream;
+            if (stream === null) { yield { type: "run_end", status: "error", summary: rt.noProviderReason() ?? "no provider configured" }; return; }
+            const model: ModelRef = rt.provider
+              ? { provider: rt.provider.id, model: process.env.ROVECODE_MODEL ?? rt.provider.defaultModel ?? "gpt-4o-mini" }
+              : { provider: "mock", model: "default" };
+            const ac = new AbortController();
+            const follow = (): void => ac.abort();
+            if (pOpts.signal?.aborted) ac.abort();
+            else pOpts.signal?.addEventListener("abort", follow, { once: true });
+            rt.tasks.bindRun(ac.signal);
+            const level = opts.yolo === true ? "auto" : "ask";
+            const cfg: RunConfig = rt.buildCfg(level, opts.approval);
+            const queue = new EventQueue();
+            // tree updates that land DURING the prompt join its stream, so a consumer
+            // of `for await (ev of session.prompt(…))` sees the whole picture
+            const unsub = rt.tasks.subscribe(() => {
+              queue.push({ type: "agent_tree_update", sessionId: id, tree: agentTree(rt.tasks.list()) });
+            });
+            // the loop runs CONCURRENTLY, pushing into the queue the generator drains:
+            // loop events and background tree updates interleave in real time. The queue
+            // is unbounded (events are small); the loop's own backpressure story is for
+            // the wire, not for a local consumer.
+            let failure: unknown;
+            const run = (async (): Promise<void> => {
+              try {
+                for await (const ev of agentLoop(rt.buildDef(model), goal, {}, cfg, {
+                  stream, registry: rt.registry, store: rt.store,
+                  tools: rt.registry.list().map((t) => t.schema),
+                  guard: rt.guard, planReminder: rt.planReminder, cwd: rt.cwd,
+                  signal: ac.signal, hooks: rt.hooks,
+                }, rt.steering)) {
+                  broadcast(ev);
+                  queue.push(ev);
+                }
+              } catch (e) {
+                failure = e;
+              } finally {
+                queue.close();
+              }
+            })();
+            try {
+              yield* queue.drain();
+            } finally {
+              unsub();
+              await run;
+              pOpts.signal?.removeEventListener("abort", follow);
+            }
+            if (failure !== undefined) throw failure;
+          },
+        };
+      },
+      list(): SessionSummary[] { return listSessions(sessionsRoot); },
+    },
+    task: {
+      start(sessionId, req) {
+        const rt = requireRuntime(sessionId);
+        return rt.tasks.start(
+          { agent: req.agent ?? "default", goal: req.goal, isolated: req.isolated === true },
+          { ...(req.label !== undefined ? { label: req.label } : {}) },
+        );
+      },
+      list(sessionId) { return requireRuntime(sessionId).tasks.list(); },
+      wait(sessionId, id, waitOpts) { return requireRuntime(sessionId).tasks.result(id, waitOpts); },
+      cancel(sessionId, id) { return requireRuntime(sessionId).tasks.cancel(id) !== undefined; },
+    },
+    agent: {
+      tree(sessionId) { return agentTree(requireRuntime(sessionId).tasks.list()); },
+    },
+    events: {
+      subscribe(fn) { listeners.add(fn); return () => { listeners.delete(fn); }; },
+    },
+    async close(): Promise<void> {
+      for (const rt of runtimes.values()) {
+        rt.tasks.cancelAll();
+        await rt.tasks.drain(2_000);
+        await rt.hooks.close();
+        await rt.mcp?.close().catch(() => {});
+      }
+      runtimes.clear();
+      listeners.clear();
+    },
+  };
+}

package/src/sdk/index.ts

@@ -0,0 +1,3 @@
+/** @rovecode/sdk — public surface (docs/design/sdk-blueprint.md §3). */
+export { createClient, agentTree } from "./client.ts";
+export type { AgentNode, ClientOptions, RovecodeClient, SdkEvent, SessionHandle } from "./client.ts";