@dharta/cli 0.6.77

package/src/commands/dev.ts

@@ -0,0 +1,792 @@
+// `dharta dev` (RFC 0013 CLI-4): the consumer preview. Spawns the pinned
+// dharta-runtime serving this folder behind the same consumer session API
+// production serves, then drives it as a plain HTTP/SSE client — the
+// REPL has no privileged channel, so what works here works for the
+// widget (D4). Running the native harness CLI in the folder is the authoring mode;
+// this is the preview mode.
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import * as net from "node:net";
+import * as readline from "node:readline";
+import { randomUUID } from "node:crypto";
+import TOML from "@iarna/toml";
+import { resolveRuntime, spawnRuntime } from "../runtime.js";
+import { buildContext } from "../context.js";
+import { fetchRemoteEnv, prepareReleaseDir } from "./parity.js";
+import { parseDotenvFile } from "./env.js";
+import { describeFolder } from "../setup-scan.js";
+import { hasAgentMarker } from "../harnesses.js";
+import { normalizeNonBlank } from "../validators.js";
+
+export interface DevOptions {
+  dir?: string;
+  message?: string; // -m: one turn, then exit
+  user?: string; // --user: simulated end-user id (session metadata)
+  port?: number; // stable local port (default: an ephemeral free one)
+  verbose?: boolean; // stream runtime output + parity details
+  // Parity axes (RFC 0013 CLI-10); both need a logged-in context.
+  release?: string; // --release vN: run the exact built tree prod serves
+  envRemote?: boolean; // --env remote: bind prod env vars instead of .env
+  includeSecrets?: boolean; // with --env remote: fetch secret values (env:secrets:read)
+  project?: string; // -p override for the parity flags' project inference
+  // Test seams. `attach` skips the spawn and drives an existing server.
+  attach?: string;
+  fetchImpl?: typeof fetch;
+  input?: NodeJS.ReadableStream;
+  write?: (text: string) => void; // raw writes (text deltas)
+  log?: (line: string) => void;
+  healthTimeoutMs?: number;
+  turnIdleMs?: number; // abort a turn with no output for this long (default 60s)
+}
+
+interface SseEvent {
+  event: string;
+  data: Record<string, unknown>;
+}
+
+// `dharta dev [path]` in a multi-agent repo (RFC 0024 DEP-8): with no path
+// given, serve cwd if it is itself an agent; else the sole agent folder
+// directly below it; else ask which one. An explicit path always wins (the
+// caller skips this). Shallow by design - dev previews one local agent.
+export async function resolveAgentDir(dir: string, log: (l: string) => void): Promise<string> {
+  if (hasAgentMarker(dir)) return dir;
+
+  let subs: string[] = [];
+  try {
+    subs = (await fs.readdir(dir, { withFileTypes: true }))
+      .filter(
+        (e) =>
+          e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules" && hasAgentMarker(path.join(dir, e.name)),
+      )
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return dir; // unreadable: serve as-is, miniDoctor reports the real problem
+  }
+
+  if (subs.length === 1) {
+    log(`Running the only agent here: ./${subs[0]}`);
+    return path.join(dir, subs[0]);
+  }
+  if (subs.length > 1) {
+    throw new Error(`Multiple agents here (${subs.join(", ")}). Pick one, e.g. dharta dev ./${subs[0]}`);
+  }
+  return dir; // no agent here or one level down - serve cwd (miniDoctor warns)
+}
+
+export async function dev(opts: DevOptions = {}): Promise<void> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const write = opts.write ?? ((text: string) => process.stdout.write(text));
+  const fetchImpl = (opts.fetchImpl ?? globalThis.fetch).bind(globalThis);
+
+  if (opts.port !== undefined && (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)) {
+    throw new Error("--port must be an integer between 1 and 65535.");
+  }
+  const normalizedDir = opts.dir === undefined ? undefined : normalizeNonBlank(opts.dir, "--dir");
+  const normalizedUser = opts.user === undefined ? undefined : normalizeNonBlank(opts.user, "--user");
+  const normalizedMessage = opts.message === undefined ? undefined : normalizeNonBlank(opts.message, "--message");
+  if (opts.includeSecrets && !opts.envRemote) throw new Error("--include-secrets requires --env remote.");
+
+  let dir = path.resolve(normalizedDir ?? process.cwd());
+  if (normalizedDir !== undefined) {
+    await validateExplicitDevDir(dir);
+  }
+  // No explicit path given: pick the agent to preview (cwd, sole subdir, or
+  // ask) - RFC 0024 DEP-8. An explicit --dir / [path] is served as-is.
+  if (normalizedDir === undefined) dir = await resolveAgentDir(dir, log);
+  let childEnv: NodeJS.ProcessEnv | undefined;
+  if (opts.release || opts.envRemote) {
+    const ctx = await buildContext({ fetch: opts.fetchImpl });
+    const inferOpts = { dir: normalizedDir, project: opts.project, fetchImpl: opts.fetchImpl };
+    if (opts.release) {
+      const release = await prepareReleaseDir(ctx, opts.release, inferOpts);
+      log(
+        `Running release v${release.version} (${release.commitSha.slice(0, 8)}) - the exact tree prod serves. ` +
+          "Edits to it are NOT deploys; hot reload applies to this copy only.",
+      );
+      dir = release.dir;
+    }
+    if (opts.envRemote) {
+      const remote = await fetchRemoteEnv(ctx, { ...inferOpts, includeSecrets: opts.includeSecrets });
+      const names = Object.keys(remote.values);
+      childEnv = { ...process.env, ...remote.values };
+      log(`Bound ${names.length} prod env var${names.length === 1 ? "" : "s"}: ${names.join(", ") || "(none)"}`);
+      if (remote.withheld.length > 0) {
+        log(
+          `${remote.withheld.length} secret value(s) withheld (${remote.withheld.join(", ")}) - ` +
+            "calls through them will fail; --include-secrets with env:secrets:read fetches them (audited).",
+        );
+      }
+    }
+  }
+
+  const agentName = (await describeFolder(dir, ".")).name ?? path.basename(dir);
+  log(`Dharta dev mode: ${agentName}`);
+  log("");
+
+  for (const warning of await miniDoctor(dir)) log(`[doctor] ${warning}`);
+
+  let baseUrl = opts.attach;
+  let child: ReturnType<typeof spawnRuntime> | null = null;
+  let spawnError: Error | null = null;
+  let runtimeOutput: RuntimeOutputBuffer | null = null;
+  let killTurn: (() => void) | null = null; // set per-turn: aborts a wedged/crashed turn
+  if (!baseUrl) {
+    const runtime = await resolveRuntime();
+    const port = opts.port ?? (await freePort());
+    baseUrl = `http://127.0.0.1:${port}`;
+    log(`✓ Starting agent runtime (${runtime.description})…`);
+    child = spawnRuntime(runtime, ["dev-serve", dir, "--host", "127.0.0.1", "--port", String(port)], {
+      stdio: "pipe",
+      env: childEnv,
+    });
+    // A spawn error (binary missing, not executable) never fires `exit` —
+    // capture it so waitForHealthy fails fast with the remedy, not a
+    // stack trace after a 120s timeout.
+    child.on("error", (err) => {
+      spawnError = new Error(
+        `Could not launch the agent runtime (${err.message}).\n` +
+          "Run `dharta doctor` to diagnose; DHARTA_RUNTIME=/path/to/checkout is the escape hatch.",
+      );
+    });
+    runtimeOutput = forwardRuntimeOutput(child, { stream: !!opts.verbose, onFatal: () => killTurn?.() });
+  }
+
+  // The runtime must die with us, including on plain `kill` — an
+  // orphaned uvicorn keeps the port bound.
+  const onSignal = (signal: NodeJS.Signals) => {
+    if (child) child.kill("SIGTERM");
+    process.exit(signal === "SIGINT" ? 130 : 143);
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  let rl: readline.Interface | null = null;
+  try {
+    try {
+      await waitForHealthy(baseUrl, fetchImpl, child, opts.healthTimeoutMs ?? 120_000, () => spawnError);
+    } catch (err) {
+      // The remedial message says "see [runtime] output" - make that
+      // true even when the runtime stream was quieted by default.
+      runtimeOutput?.dump();
+      throw err;
+    }
+
+    log("✓ Agent ready");
+    log(`  Local agent API: ${baseUrl}/v1`);
+    if (opts.verbose) {
+      log("  Point @dharta/widget or your frontend at it.");
+      log("  Preview parity is code + config, not infrastructure: no microVM, no per-user");
+      log("  workspaces, and turns run on YOUR harness credentials (prod injects its own).");
+    }
+    // The agent turn spawns `claude` on YOUR credentials; with none it exits 1.
+    // Hard-stop here rather than drop into a chat that can only fail (spawn
+    // path only - an attached runtime carries its own credentials).
+    if (child && !process.env.ANTHROPIC_API_KEY && !process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+      log("");
+      log("! Error: No model credential found. Two options -");
+      log("  export ANTHROPIC_API_KEY=<your Anthropic API key>");
+      log("  OR");
+      log("  export CLAUDE_CODE_OAUTH_TOKEN=<Claude Code token from `claude setup-token`>");
+      process.exitCode = 1;
+      return;
+    }
+
+    const session = await createSession(baseUrl, fetchImpl, normalizedUser);
+    if (normalizedUser) log(`Simulating end user '${normalizedUser}'.`);
+
+    rl = readline.createInterface({
+      input: opts.input ?? process.stdin,
+      output: undefined,
+      terminal: false,
+    });
+    // SINGLE consumer for all input: turn text and approval answers pull
+    // from the same iterator. A second listener (rl.once("line")) would
+    // race the for-await loop — interactively the approval answer leaks
+    // back in as a user turn; with piped input it deadlocks outright.
+    const lines = rl[Symbol.asyncIterator]();
+    const ask = async (question: string): Promise<string | null> => {
+      write(question);
+      const { value, done } = await lines.next();
+      return done ? null : value; // null: input exhausted, nobody can answer
+    };
+
+    const idleMs = opts.turnIdleMs ?? 60_000;
+    // Run one turn but never hang: abort if the runtime crashes (onFatal) or
+    // goes silent for idleMs, then surface the buffered runtime output. The
+    // idle timer pauses while we wait on a human (approval prompt).
+    const runTurnWatched = async (turnText: string, prefix: string): Promise<void> => {
+      const controller = new AbortController();
+      let idle: ReturnType<typeof setTimeout> | undefined;
+      let produced = false; // did the agent write any content this turn?
+      const arm = () => {
+        clearTimeout(idle);
+        idle = setTimeout(() => controller.abort(), idleMs);
+      };
+      const tracked = (t: string) => {
+        if (t && !produced) {
+          produced = true;
+          if (prefix) write(prefix); // print "<agent>: " only once real output arrives
+        }
+        arm();
+        write(t);
+      };
+      const pausedAsk = async (q: string): Promise<string | null> => {
+        clearTimeout(idle); // don't time out while waiting on the human
+        const answer = await ask(q);
+        arm();
+        return answer;
+      };
+      killTurn = () => controller.abort();
+      arm();
+      const aborted = new Promise<never>((_, reject) => {
+        controller.signal.addEventListener("abort", () => reject(new Error("turn aborted")), { once: true });
+      });
+      const turn = runTurn(baseUrl as string, fetchImpl, session, turnText, { write: tracked, log, ask: pausedAsk }, controller.signal);
+      try {
+        // Race the turn against the abort. A real fetch unblocks its body read
+        // on signal, but racing also covers a stream that wedges open without
+        // ever erroring (the crashed-subprocess shape).
+        await Promise.race([turn, aborted]);
+        if (!produced) {
+          // The turn ended without crashing or stalling, but said nothing - the
+          // runtime swallowed the cause (often the missing credential above).
+          runtimeOutput?.dump();
+          log("[no response] the agent produced no output - see the note above, or rerun with `dharta dev --verbose`.");
+        }
+      } catch (err) {
+        if (controller.signal.aborted) {
+          turn.catch(() => {}); // detach the abandoned read
+          runtimeOutput?.dump();
+          throw new Error(
+            "No response - the agent runtime errored or went silent (see [runtime] output above). " +
+              "A missing model credential (ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN) is the usual cause.",
+          );
+        }
+        throw err;
+      } finally {
+        clearTimeout(idle);
+        killTurn = null;
+      }
+    };
+
+    if (normalizedMessage !== undefined) {
+      await runTurnWatched(normalizedMessage, "");
+      return;
+    }
+
+    log("  Chat with your agent. Type 'exit' to quit; edits to the harness instruction file hot-reload.");
+    for (;;) {
+      write("\nUser: ");
+      const { value, done } = await lines.next();
+      if (done) break;
+      const text = value.trim();
+      if (text === "") continue;
+      if (text === "exit" || text === "quit") break;
+      try {
+        await runTurnWatched(text, `\n${agentName}: `);
+      } catch (err) {
+        // One failed turn must not kill the session (or the runtime).
+        log(`[error] ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  } finally {
+    rl?.close();
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+    if (child) child.kill("SIGTERM");
+  }
+}
+
+async function validateExplicitDevDir(dir: string): Promise<void> {
+  try {
+    const stat = await fs.stat(dir);
+    if (!stat.isDirectory()) {
+      throw new Error(`Cannot run dev in ${dir}: expected a directory.`);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`Cannot run dev in ${dir}: directory does not exist.`);
+    }
+    throw error;
+  }
+}
+
+// --- mini-doctor -----------------------------------------------------------
+
+// The dev-start warnings half of declare-or-bind (DEV_PROD_PARITY §7):
+// the same conditions fail the push-time build, so nothing said here is
+// a surprise later. Full [env] tooling (env list/set/diff) is CLI-8.
+export async function miniDoctor(dir: string): Promise<string[]> {
+  const warnings: string[] = [];
+
+  const karta = await readOptionalLocalFile(path.join(dir, "dharta.toml"), "dharta.toml");
+  if (karta.warning) warnings.push(karta.warning);
+  const kartaToml = karta.content;
+  if (kartaToml === null) {
+    warnings.push(
+      "dharta.toml is missing - the push-time build will reject this folder. `dharta setup` scaffolds one.",
+    );
+  } else {
+    try {
+      const parsed = TOML.parse(kartaToml) as Record<string, unknown>;
+      const env = parsed.env as Record<string, unknown> | undefined;
+      if (env) {
+        const localEnv = await readOptionalLocalFile(path.join(dir, ".env"), ".env");
+        if (localEnv.warning) warnings.push(localEnv.warning);
+        const dotenv = parseDotenvFile(localEnv.content);
+        for (const [name, spec] of Object.entries(env)) {
+          const required =
+            typeof spec === "object" && spec !== null &&
+            (spec as { required?: unknown }).required === true;
+          if (required && !(name in process.env) && !(name in dotenv)) {
+            warnings.push(
+              `Required env var ${name} is unbound - add it to .env (the push-time build fails on this too).`,
+            );
+          }
+        }
+      }
+    } catch {
+      warnings.push("dharta.toml could not be parsed - fix it before pushing.");
+    }
+  }
+
+  const localMcp = await readOptionalLocalFile(path.join(dir, ".mcp.json"), ".mcp.json");
+  if (localMcp.warning) warnings.push(localMcp.warning);
+  const mcp = localMcp.content;
+  if (mcp !== null && /localhost|127\.0\.0\.1/.test(mcp)) {
+    warnings.push(
+      ".mcp.json points at localhost - that endpoint won't exist in production. " +
+        "Reference ${VAR} and bind it per environment (declare-or-bind).",
+    );
+  }
+
+  return warnings;
+}
+
+
+async function readOptionalLocalFile(file: string, label: string): Promise<{ content: string | null; warning?: string }> {
+  try {
+    return { content: await fs.readFile(file, "utf8") };
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { content: null };
+    if (code === "EISDIR") {
+      return { content: null, warning: `Cannot read ${label} at ${file}: expected a file, got a directory.` };
+    }
+    return { content: null, warning: `Cannot read ${label} at ${file}: ${(error as Error).message}` };
+  }
+}
+
+// --- runtime lifecycle -----------------------------------------------------
+
+// TOCTOU between this probe and the child binding is accepted: the
+// loser exits immediately and waitForHealthy reports it within ~500ms.
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const address = srv.address();
+      srv.close(() =>
+        typeof address === "object" && address
+          ? resolve(address.port)
+          : reject(new Error("could not allocate a local port")),
+      );
+    });
+    srv.on("error", reject);
+  });
+}
+
+interface RuntimeOutputBuffer {
+  dump(): void;
+}
+
+// Quiet by default: the runtime's banner/uvicorn lines are noise in
+// the REPL, but they are exactly what explains a failed start - so
+// always buffer, stream only with --verbose, and dump the buffer when
+// startup fails.
+function forwardRuntimeOutput(
+  child: ReturnType<typeof spawnRuntime>,
+  { stream: streamLive, onFatal }: { stream: boolean; onFatal?: () => void },
+): RuntimeOutputBuffer {
+  const buffered: string[] = [];
+  const emit = (line: string) => process.stderr.write(`[runtime] ${line}\n`);
+  for (const stream of [child.stdout, child.stderr]) {
+    let pending = "";
+    const handle = (line: string) => {
+      if (!line.trim()) return;
+      // An unhandled Python traceback means the in-flight turn crashed; the SSE
+      // stream can wedge open, so signal the turn to abort rather than hang on
+      // bytes that will never come.
+      if (onFatal && /Traceback \(most recent call last\)/.test(line)) onFatal();
+      if (streamLive) emit(line);
+      else {
+        buffered.push(line);
+        if (buffered.length > 200) buffered.shift();
+      }
+    };
+    stream?.on("data", (chunk: Buffer) => {
+      pending += chunk.toString("utf8");
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+      lines.forEach(handle);
+    });
+    stream?.on("end", () => handle(pending));
+  }
+  return {
+    dump() {
+      buffered.forEach(emit);
+      buffered.length = 0;
+    },
+  };
+}
+
+async function waitForHealthy(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  child: ReturnType<typeof spawnRuntime> | null,
+  timeoutMs: number,
+  spawnError: () => Error | null = () => null,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastDetail = "";
+  let exited = false;
+  child?.on("exit", () => {
+    exited = true;
+  });
+
+  while (Date.now() < deadline) {
+    const failed = spawnError();
+    if (failed) throw failed;
+    if (exited) {
+      throw new Error(
+        "The agent runtime exited before it became ready (see [runtime] output above). " +
+          "Run `dharta doctor` to diagnose; DHARTA_RUNTIME=/path/to/checkout is the escape hatch.",
+      );
+    }
+    try {
+      const res = await fetchImpl(`${baseUrl}/healthz`);
+      if (res.ok) return;
+      if (res.status === 503) {
+        const body = (await res.json().catch(() => null)) as { detail?: string } | null;
+        lastDetail = body?.detail ?? "";
+      }
+    } catch {
+      // not listening yet
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(
+    `The agent runtime did not become ready within ${Math.round(timeoutMs / 1000)}s` +
+      (lastDetail ? ` (${lastDetail})` : "") +
+      ". Run `dharta doctor` to diagnose.",
+  );
+}
+
+// --- protocol client -------------------------------------------------------
+
+async function createSession(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  endUserId?: string,
+): Promise<string> {
+  const res = await fetchAgentApi(baseUrl, fetchImpl, "/v1/sessions", "create a session", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
+    body: JSON.stringify({ metadata: endUserId ? { end_user_id: endUserId } : {} }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Could not create a session (HTTP ${res.status}). See the [runtime] output above for the cause.`,
+    );
+  }
+  const body = await readAgentJson<{ id: string }>(res, "create a session");
+  if (typeof body.id !== "string" || body.id.length === 0) {
+    throw new Error("Could not create a session: the agent API response did not include a session id.");
+  }
+  return body.id;
+}
+
+export interface TurnIo {
+  write: (text: string) => void;
+  log: (line: string) => void;
+  // Resolves to the user's answer, or null when the input stream is exhausted
+  // (no TTY, or piped input ran out) — i.e. no human is there to answer.
+  ask: (question: string) => Promise<string | null>;
+}
+
+interface PendingInput {
+  request_id: string;
+  message?: string;
+  tool?: string;
+  target?: string;
+}
+
+export async function runTurn(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  sessionId: string,
+  text: string,
+  io: TurnIo,
+  signal?: AbortSignal,
+): Promise<void> {
+  const res = await fetchAgentApi(
+    baseUrl,
+    fetchImpl,
+    `/v1/sessions/${sessionId}/messages`,
+    "send the message",
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+        "Idempotency-Key": randomUUID(),
+      },
+      body: JSON.stringify({ text, stream: true }),
+      signal,
+    },
+  );
+  if (!res.ok || !res.body) {
+    throw new Error(
+      `Turn failed (HTTP ${res.status}). Retry the message; if it persists, check ` +
+        "the [runtime] output (dharta dev) or `dharta logs [slug]` (deployed).",
+    );
+  }
+
+  const pending = await renderEventStream(parseSse(res.body), io);
+  await resolvePendingInputs(baseUrl, fetchImpl, sessionId, pending, io);
+}
+
+// Approval loop: the harness pauses on tool permissions; the decision
+// goes back over the same API the widget uses. The PUT's response is
+// itself a batch of events (it may pause again).
+async function resolvePendingInputs(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  sessionId: string,
+  first: PendingInput | null,
+  io: TurnIo,
+): Promise<void> {
+  let pending = first;
+  let abortHintShown = false;
+  while (pending) {
+    const prompt = pending.message ?? `The agent wants to use ${pending.tool ?? "a tool"}`;
+    const answer = await io.ask(`\n${prompt} - approve? [y=once / s=session / n=deny] `);
+    if (answer === null && !abortHintShown) {
+      // No TTY / piped input ran out: nobody can answer, so the tool is denied
+      // and the turn stalls. Name the bounded-authority fix once instead of
+      // leaving the failure unexplained (issue #857).
+      io.log(
+        `[approval] "${pending.tool ?? "a tool"}" is not on the .claude/settings.json allowlist and this ` +
+          `run is non-interactive, so it was denied. Allow the tools your agent needs in .claude/settings.json ` +
+          `(bounded authority), run \`dharta dev\` interactively to approve as you go, or set ` +
+          `runtime.permission_mode = "autonomous" in dharta.jsonc.`,
+      );
+      abortHintShown = true;
+    }
+    const decision =
+      answer === null
+        ? "deny"
+        : answer.trim().toLowerCase() === "y"
+          ? "approve_once"
+          : answer.trim().toLowerCase() === "s"
+            ? "approve_session"
+            : "deny";
+
+    const res = await fetchAgentApi(
+      baseUrl,
+      fetchImpl,
+      `/v1/sessions/${sessionId}/inputs/${pending.request_id}`,
+      "deliver the decision",
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
+        body: JSON.stringify({ decision }),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(
+        `Could not deliver the decision (HTTP ${res.status}). Re-send the message to retry.`,
+      );
+    }
+    const body = await readAgentJson<{ events?: Array<Record<string, unknown>> }>(res, "deliver the decision");
+
+    pending = null;
+    const renderer = makeRenderer(io);
+    for (const raw of body.events ?? []) {
+      const next = renderer(raw as { type?: string; data?: Record<string, unknown> });
+      if (next) pending = next;
+    }
+    renderer.finish();
+  }
+}
+
+async function fetchAgentApi(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  path: string,
+  operation: string,
+  init?: RequestInit,
+): Promise<Response> {
+  try {
+    return await fetchImpl(`${baseUrl}${path}`, init);
+  } catch (error) {
+    if (init?.signal?.aborted) throw error;
+    throw new Error(
+      `Could not ${operation}: could not reach the agent API at ${baseUrl} (${formatCause(error)}). ` +
+        "For local preview, rerun with `dharta dev --verbose` or run `dharta doctor`; " +
+        "for deployed agents, check `dharta logs [slug]`.",
+    );
+  }
+}
+
+async function readAgentJson<T>(res: Response, operation: string): Promise<T> {
+  try {
+    return (await res.json()) as T;
+  } catch (error) {
+    throw new Error(
+      `Could not ${operation}: the agent API returned invalid JSON (${formatCause(error)}). ` +
+        "Retry the command; if it persists, check the agent runtime output or `dharta logs [slug]`.",
+    );
+  }
+}
+
+function formatCause(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : String(error);
+}
+
+async function renderEventStream(
+  events: AsyncGenerator<SseEvent>,
+  io: TurnIo,
+): Promise<PendingInput | null> {
+  const renderer = makeRenderer(io);
+  let pending: PendingInput | null = null;
+  for await (const { data } of events) {
+    const next = renderer(data as { type?: string; data?: Record<string, unknown> });
+    if (next) pending = next;
+  }
+  renderer.finish();
+  return pending;
+}
+
+// Mirrors the Python CLIRenderer's contract: text events carry the
+// CUMULATIVE text per part id; print only the delta.
+function makeRenderer(io: TurnIo) {
+  const textByPart = new Map<string, string>();
+  let lineOpen = false;
+
+  const render = (event: {
+    type?: string;
+    data?: Record<string, unknown>;
+  }): PendingInput | null => {
+    const data = event.data ?? {};
+    switch (event.type) {
+      case "text": {
+        const part = data.part as { id?: string; text?: string } | undefined;
+        if (!part || typeof part.text !== "string") return null;
+        const id = part.id ?? "__default__";
+        const previous = textByPart.get(id) ?? "";
+        const delta = part.text.startsWith(previous)
+          ? part.text.slice(previous.length)
+          : part.text;
+        if (delta) {
+          io.write(delta);
+          lineOpen = true;
+        }
+        textByPart.set(id, part.text);
+        return null;
+      }
+      case "tool_use": {
+        const part = data.part as { tool?: string } | undefined;
+        if (lineOpen) {
+          io.write("\n");
+          lineOpen = false;
+        }
+        io.log(`[tool] ${part?.tool ?? "tool"}`);
+        return null;
+      }
+      case "input_required":
+        if (lineOpen) {
+          io.write("\n");
+          lineOpen = false;
+        }
+        return data as unknown as PendingInput;
+      case "error": {
+        if (lineOpen) {
+          io.write("\n");
+          lineOpen = false;
+        }
+        io.log(`[error] ${JSON.stringify(data)}`);
+        return null;
+      }
+      default:
+        return null;
+    }
+  };
+  render.finish = () => {
+    if (lineOpen) io.write("\n");
+  };
+  return render;
+}
+
+// Minimal SSE parser: "event:"/"data:" lines, frames separated by a
+// blank line (LF or CRLF). Enough for the runtime's encode_sse output.
+export async function* parseSse(
+  body: ReadableStream<Uint8Array> | NodeJS.ReadableStream,
+): AsyncGenerator<SseEvent> {
+  let buffer = "";
+  const decoder = new TextDecoder();
+
+  const chunks =
+    typeof (body as ReadableStream<Uint8Array>).getReader === "function"
+      ? webStreamChunks(body as ReadableStream<Uint8Array>)
+      : (body as NodeJS.ReadableStream);
+
+  for await (const chunk of chunks) {
+    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk as Uint8Array, { stream: true });
+    // Normalize CRLF so a \r\n-emitting server doesn't buffer forever.
+    buffer = buffer.replace(/\r\n/g, "\n");
+    let sep: number;
+    while ((sep = buffer.indexOf("\n\n")) !== -1) {
+      const frame = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const parsed = parseFrame(frame);
+      if (parsed) yield parsed;
+    }
+  }
+  const tail = parseFrame(buffer);
+  if (tail) yield tail;
+}
+
+async function* webStreamChunks(
+  stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<Uint8Array> {
+  const reader = stream.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (value) yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseFrame(frame: string): SseEvent | null {
+  let event = "";
+  const dataLines: string[] = [];
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) dataLines.push(line.slice(5).trim());
+  }
+  if (!event && dataLines.length === 0) return null;
+  let data: Record<string, unknown> = {};
+  try {
+    data = JSON.parse(dataLines.join("\n"));
+  } catch {
+    // non-JSON data: leave empty
+  }
+  return { event, data };
+}