@terminus-ai/cli 0.0.1

package/bin/agentdev.mjs

@@ -0,0 +1,657 @@
+/**
+ * `terminus dev` for kind:"agent" packages.
+ *
+ * DEFAULT (local): a local web server on 127.0.0.1 serving a chat UI — the
+ * developer tests the agent the way its users will meet it. The agent loop
+ * runs on THIS machine in `terminus-agentd dev`, against a runtime-shaped
+ * workspace assembled under `.terminus/dev/agent/` (your whole
+ * package staged read-only in place; the rest of the root and output/
+ * writable).
+ * The system prompt and tool definitions are compiled
+ * by the backend (`POST /v1/agent-dev/compile`) from your local manifest —
+ * the same composition publishing produces — while exec runs natively in a
+ * workspace-write sandbox (jailed writes, no network) with prod-compat
+ * warnings when a program leans on something the hosted isolate lacks.
+ * Works immediately after `terminus init --kind agent`: no draft, no link.
+ * State stays local; models, web, skills, and connector calls are brokered
+ * through the platform under your own account. Sessions mirror into
+ * `.terminus/dev/agent/dev.db` (SQLite — prod sessions are DB rows,
+ * so local ones are too); outputs stay real files in the workspace lanes.
+ *
+ * `--remote`: the pre-publish fidelity gear — pushes the tree as your
+ * Studio draft and chats with it on the platform's real engine (real bashd
+ * isolate, real broker), through the SAME web UI. Interface constant,
+ * substrate swapped.
+ *
+ * One-shot mode for scripts and coding agents (headless, no server):
+ * `terminus dev --prompt "…" [--json] [--resume <session-id>]`.
+ *
+ * There is no terminal REPL: the browser is the interactive surface, the
+ * one-shot lane is the machine surface (decision of
+ * 2026-08-31).
+ */
+
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { randomUUID } from "node:crypto";
+
+import { pushDraft, readAppPackage } from "./apps.mjs";
+import { DEV_DIRECTORY, ensureDevDirectory } from "./files.mjs";
+import { lintBashCommand, lintPythonImports } from "./devlint.mjs";
+import { buildTriggerInput, listDevTriggers, runTriggerFiring } from "./devtriggers.mjs";
+import { resolveAgentd } from "./toolchain.mjs";
+import { CliError, parseFlags } from "./client.mjs";
+import { connect } from "./http.mjs";
+
+/** Send one message to a draft session and stream its turn's SSE frames,
+ * invoking onFrame per decoded JSON event. A refused turn throws what the
+ * backend said. */
+export async function streamTurn(api, sessionId, body, onFrame, signal) {
+  const response = await api.stream("POST /v1/terminus/sessions/{session_id}/messages", {
+    params: { session_id: sessionId },
+    body,
+    headers: { Accept: "text/event-stream" },
+    signal,
+  });
+  if (!response.body) throw new CliError("the turn answered with no event stream");
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const dispatch = (rawEvent) => {
+    const data = rawEvent
+      .split("\n")
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trimStart())
+      .join("\n");
+    if (!data || data === "[DONE]") return;
+    try {
+      onFrame(JSON.parse(data));
+    } catch {
+      // Skip malformed frames rather than kill the stream.
+    }
+  };
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    buffer = buffer.replace(/\r\n/g, "\n");
+    let separator = buffer.indexOf("\n\n");
+    while (separator !== -1) {
+      dispatch(buffer.slice(0, separator));
+      buffer = buffer.slice(separator + 2);
+      separator = buffer.indexOf("\n\n");
+    }
+  }
+  if (buffer.trim()) dispatch(buffer);
+}
+
+/** Fold a frame into the spend/error ledger (playground/agent-proto
+ * vocabulary). Presentation lives elsewhere; this is the accounting. */
+export function trackFrameSpend(frame, spend) {
+  if (frame.type === "usage") {
+    spend.tokens += (frame.input_tokens ?? 0) + (frame.output_tokens ?? 0);
+    const billed = Number.parseFloat(frame.billed_amount_usd);
+    const cost = Number.parseFloat(
+      Number.isFinite(billed) && billed > 0
+        ? frame.billed_amount_usd
+        : frame.est_provider_cost_usd,
+    );
+    if (Number.isFinite(cost)) spend.costUsd += cost;
+  }
+  if (frame.type === "error") spend.errored = true;
+}
+
+/** The prod-compat lint for one tool call: non-blocking warnings when a
+ * program leans on something the hosted isolate lacks. */
+export function compatWarningsForToolCall(frame) {
+  if (frame.name === "bash") return lintBashCommand(frame.input?.command);
+  if (frame.name === "python") return lintPythonImports(frame.input?.code);
+  return [];
+}
+
+/** Terminal renderer for the one-shot lane (presentation only). */
+function renderFrame(frame, options = {}) {
+  switch (frame.type) {
+    case "delta":
+      if (typeof frame.text === "string") process.stdout.write(frame.text);
+      return;
+    case "tool_call": {
+      process.stdout.write(`\n[tool] ${frame.name ?? "?"}\n`);
+      if (options.lint) {
+        for (const warning of compatWarningsForToolCall(frame)) console.error(warning);
+      }
+      return;
+    }
+    case "plan_update": {
+      const steps = Array.isArray(frame.steps) ? frame.steps : [];
+      process.stdout.write(
+        `\n[plan] ${steps
+          .map((step) => `${step.status === "completed" ? "✓" : step.status === "in_progress" ? "→" : "·"} ${step.step}`)
+          .join("  ")}\n`,
+      );
+      return;
+    }
+    case "notice":
+      if (typeof frame.message === "string") process.stdout.write(`\n[${frame.message}]\n`);
+      return;
+    case "error":
+      process.stdout.write(`\n[error] ${frame.message ?? "the turn failed"}\n`);
+      return;
+    default:
+    // Tool outputs, usage, queue updates, and lifecycle frames stay quiet.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Local engine (the default substrate)
+// ---------------------------------------------------------------------------
+
+/**
+ * Assemble the runtime-shaped dev workspace from the manifest: the WHOLE
+ * package stages read-only IN PLACE at the workspace root, verbatim
+ * (AGENT.md and terminus.json included — an agent works in its own source).
+ * Staged paths are the reserved names; `previousStaged` (from the last
+ * dev.json) is removed first so a dropped package file does not linger,
+ * while everything the agent wrote persists across reloads. Returns the
+ * staged path list. Mirrors the hosted reserved-names rule.
+ */
+export async function assembleDevWorkspace(manifest, workspaceDir, previousStaged = []) {
+  await mkdir(workspaceDir, { recursive: true });
+  // The previous in-place staging goes first, so a reloaded workspace never
+  // shows two generations of the same files.
+  for (const stale of previousStaged) {
+    const parts = String(stale).split("/");
+    if (parts.some((part) => !part || part === "." || part === "..")) continue;
+    await rm(path.join(workspaceDir, ...parts), { force: true }).catch(() => undefined);
+  }
+  // The intrinsic workspace: the ROOT is the agent's own writable folder
+  // with the package staged read-only in place; output/ holds deliverables,
+  // attachments/ the chat file exchange, memory/ its cross-session notes
+  // (markdown the agent chooses to keep — session history lives in the
+  // DATABASE and is browsed from the dev UI's History surface, never files).
+  for (const lane of ["output", "attachments", "memory"]) {
+    await mkdir(path.join(workspaceDir, lane), { recursive: true });
+  }
+  const staged = [];
+  for (const material of manifest.materials ?? []) {
+    if (material.role === "source") continue; // ledger-only plane
+    const relative = material.path ?? "";
+    if (!relative || relative.split("/").some((part) => part === "." || part === "..")) continue;
+    const target = path.join(workspaceDir, relative);
+    await mkdir(path.dirname(target), { recursive: true });
+    // A collision with a file the agent wrote resolves release-wins, same
+    // as hosted (the stored object is shadowed there, replaced here); a
+    // read-only file from the previous staging must be removed before the
+    // write, or writeFile dies with EACCES.
+    await rm(target, { force: true }).catch(() => undefined);
+    const bytes = material.encoding === "base64"
+      ? Buffer.from(material.content ?? "", "base64")
+      : Buffer.from(material.content ?? "", "utf8");
+    await writeFile(target, bytes);
+    // Read-only, as in production: bash writes over package files must fail
+    // locally the way the hosted commit predicate rejects them.
+    await chmod(target, 0o444);
+    staged.push(relative);
+  }
+  return staged;
+}
+
+/**
+ * One local dev engine: compile via the backend, assemble the workspace,
+ * spawn `terminus-agentd dev`, speak stdio frames. Presentation-free —
+ * every frame is handed to `onFrame` (the dev server's SSE fan-out, or the
+ * one-shot renderer).
+ */
+export class LocalDev {
+  constructor(dir, flags, api, { onFrame } = {}) {
+    this.dir = dir;
+    this.flags = flags;
+    this.api = api;
+    this.onFrame = onFrame ?? (() => {});
+    this.devRoot = path.join(dir, DEV_DIRECTORY, "agent");
+    this.workspace = path.join(this.devRoot, "workspace");
+    // The engine's JSONL session log is crash/resume plumbing — a WAL,
+    // not a data store — so it lives OUTSIDE the workspace: the agent never
+    // sees raw history (its memory is what it wrote to memory/), and the
+    // browsable record is the SQLite mirror behind the History surface.
+    this.sessionDir = path.join(this.devRoot, "engine");
+    this.configPath = path.join(this.devRoot, "dev.json");
+    this.sessionIdPath = path.join(this.devRoot, "session-id");
+    this.child = null;
+    this.sessionId = null;
+    this.spend = { tokens: 0, costUsd: 0, errored: false };
+    this.turnDone = null;
+    this.grants = null;
+    this.model = null;
+    /** A reader's pick in the dev page, which outranks the manifest's default
+     * for this run — the ENGINE has to start on it, or the page would be
+     * showing a model the agent is not answering as. */
+    this.modelOverride = null;
+    this.compiled = null;
+    this.exitNotice = null;
+  }
+
+  async currentSessionId() {
+    try {
+      const id = (await readFile(this.sessionIdPath, "utf8")).trim();
+      return /^[0-9a-f-]{36}$/.test(id) ? id : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async rememberSessionId(id) {
+    await writeFile(this.sessionIdPath, `${id}\n`).catch(() => undefined);
+  }
+
+  /** Compile via the backend, assemble the workspace, spawn the local host. */
+  async start() {
+    const pkg = await readAppPackage(this.dir, { includeSource: false });
+    if (pkg.manifest.kind !== "agent") {
+      throw new CliError(
+        `terminus dev chat is for kind 'agent' packages (found '${pkg.manifest.kind}')`,
+      );
+    }
+    // The compile door is rate-limited per user (30/min), and a hot reload
+    // fires on every saved keystroke-pause. Most of those saves do not change
+    // what the server would compose — a data file, a README, a save that
+    // rewrote identical bytes — so ask only when the input actually differs.
+    const compileKey = JSON.stringify(pkg.manifest);
+    let compiled;
+    if (this.compileKey === compileKey && this.compileCache) {
+      compiled = this.compileCache;
+    } else {
+      compiled = await this.api.json("POST /v1/agent-dev/compile", { body: pkg.manifest });
+      this.compileKey = compileKey;
+      this.compileCache = compiled;
+    }
+    this.compiled = compiled;
+    this.manifest = pkg.manifest;
+    this.grants = compiled.grants ?? {};
+    this.model = this.modelOverride ?? this.flags.model ?? compiled.model;
+    if (!this.model) {
+      throw new CliError(
+        "this agent has no model — set \"models\": { \"default\": \"provider:model\" } in terminus.json (or pass --model)",
+      );
+    }
+    // The dev folder ignores itself before anything is written into it.
+    await ensureDevDirectory(this.dir);
+    await mkdir(this.sessionDir, { recursive: true });
+    // The previous staging (recorded in the last dev config) is removed
+    // before restaging, so a file dropped from the package leaves the
+    // workspace too.
+    let previousStaged = [];
+    try {
+      previousStaged = JSON.parse(await readFile(this.configPath, "utf8")).reserved_paths ?? [];
+    } catch { /* first start, or an old config shape */ }
+    const staged = await assembleDevWorkspace(pkg.manifest, this.workspace, previousStaged);
+    this.reservedPaths = staged;
+    const resume = this.flags.resume ?? (await this.currentSessionId());
+    const devConfig = {
+      workspace: this.workspace,
+      reserved_paths: staged,
+      api_base: this.api.base,
+      model: this.model,
+      system_prompt: compiled.system_prompt,
+      capabilities: pkg.manifest.capabilities ?? {},
+      tools: compiled.tools ?? [],
+      session_dir: this.sessionDir,
+      ...(resume ? { resume } : {}),
+      ...(this.flags.sandbox ? { sandbox: this.flags.sandbox } : {}),
+    };
+    await writeFile(this.configPath, `${JSON.stringify(devConfig, null, 2)}\n`);
+    const agentd = await resolveAgentd(this.flags);
+    // The dev child gets a short-lived scoped runtime token, never the
+    // CLI's own session token — the same child-credential contract the
+    // Desktop uses for its local agents. Minted fresh per dev start.
+    const runtime = await this.api.json("POST /v1/auth/native-runtime-token");
+    // The child credential expires (the backend mints ~2h). The host owns
+    // reauthentication, so the expiry is surfaced for whoever runs this dev
+    // long enough to need a re-mint — the web dev arms a refresh off it.
+    this.runtimeExpiresAt = Date.parse(runtime.expires_at ?? "") || null;
+    this.exitNotice = null;
+    this.child = spawn(agentd, ["dev", "--config", this.configPath], {
+      env: {
+        ...process.env,
+        TERMINUS_DEV_TOKEN: runtime.token,
+        TERMINUS_API_BASE: this.api.base,
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.child.on("exit", (code) => {
+      this.exitNotice = `the dev host exited (${code ?? "signal"})`;
+      this.turnDone?.reject?.(new CliError(this.exitNotice));
+    });
+    // Ctrl-C reaches the whole foreground process group, so the child can be
+    // gone before a frame goes out; a torn stdin pipe at that point is an
+    // exit condition, not an error worth crashing over.
+    this.child.stdin.on("error", () => {});
+    this.child.stderr.on("data", (chunk) => {
+      const text = String(chunk).trim();
+      if (text) console.error(`[agentd] ${text}`);
+    });
+    const lines = readline.createInterface({ input: this.child.stdout });
+    lines.on("line", (line) => {
+      if (!line.trim()) return;
+      let frame;
+      try {
+        frame = JSON.parse(line);
+      } catch {
+        return;
+      }
+      this.handleFrame(frame);
+    });
+    return { staged, toolCount: (compiled.tools ?? []).length, compiled };
+  }
+
+  handleFrame(frame) {
+    if (frame.type === "session_started") {
+      if (typeof frame.session_id === "string") {
+        this.sessionId = frame.session_id;
+        void this.rememberSessionId(frame.session_id);
+      }
+    }
+    trackFrameSpend(frame, this.spend);
+    try {
+      this.onFrame(frame);
+    } catch {
+      // A broken subscriber must not kill the engine pump.
+    }
+    if (frame.type === "turn_done") this.turnDone?.resolve?.();
+  }
+
+  /** Send one user turn. `attachments` are inline images for vision models:
+   * `[{media_type, data}]`, data base64 — the same shape the stdio protocol
+   * and the hosted turn ledger carry. */
+  async send(text, attachments = []) {
+    if (!this.child) throw new CliError("the agent is not running");
+    const done = new Promise((resolve, reject) => {
+      this.turnDone = { resolve, reject };
+    });
+    if (!this.writeFrame({ type: "user_message", text, ...(attachments.length ? { attachments } : {}) })) {
+      this.turnDone = null;
+      throw new CliError(this.exitNotice ?? "the agent is not running");
+    }
+    try {
+      await done;
+    } finally {
+      this.turnDone = null;
+    }
+  }
+
+  interrupt() {
+    this.writeFrame({ type: "interrupt" });
+  }
+
+  /** Best-effort frame to the child; false when the pipe is already gone. */
+  writeFrame(frame) {
+    const stdin = this.child?.stdin;
+    if (!stdin || stdin.destroyed || !stdin.writable) return false;
+    try {
+      stdin.write(`${JSON.stringify(frame)}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  usageLine() {
+    if (this.spend.tokens === 0) return null;
+    const cost = this.spend.costUsd > 0 ? ` · $${this.spend.costUsd.toFixed(4)}` : "";
+    return `${this.spend.tokens} tok${cost} this session`;
+  }
+
+  async stop() {
+    const child = this.child;
+    if (!child) return;
+    // Ctrl-C usually killed the child with us; a dead child needs no
+    // shutdown frame and its `exit` already fired, so waiting would only
+    // burn the 3s timeout.
+    if (child.exitCode !== null || child.signalCode !== null) {
+      this.child = null;
+      return;
+    }
+    this.writeFrame({ type: "shutdown" });
+    this.child = null;
+    await new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolve();
+      }, 3000);
+      child.once("exit", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Remote engine (`--remote`): the pre-publish fidelity gear
+// ---------------------------------------------------------------------------
+
+/** One draft dev session: push, create, serial turns, delete. The web
+ * dev drives it through the same interface shape as LocalDev. */
+export class AgentDevSession {
+  constructor(api) {
+    this.api = api;
+    this.sessionId = null;
+    this.turnAbort = null;
+    this.spend = { tokens: 0, costUsd: 0, errored: false };
+  }
+
+  /** Stage the local tree as the server draft, then open a remote session
+   *  whose persona and grants the server compiles from that draft. */
+  async start(dir, model) {
+    const pkg = await readAppPackage(dir, { includeSource: true, includeContent: false });
+    if (pkg.manifest.kind !== "agent") {
+      throw new CliError(
+        `terminus dev chat is for kind 'agent' packages (found '${pkg.manifest.kind}')`,
+      );
+    }
+    const pushed = await pushDraft({
+      api: this.api,
+      manifest: pkg.manifest,
+      pkg,
+      message: "Staged by terminus dev --remote",
+    });
+    const session = await this.api.json("POST /v1/terminus/sessions", {
+      body: {
+        model: model ?? "",
+        surface: "agent_draft",
+        agent_app_id: pushed.appId,
+      },
+    });
+    this.sessionId = session.id;
+    return { address: pushed.address, model: session.model, revision: pushed.revision };
+  }
+
+  /** POST one message and stream its turn frames to `onFrame`; resolves on
+   *  the terminal frame. `attachments` are image content parts, forwarded on
+   *  the sessions door's ratified attachments field. */
+  async send(text, attachments, onFrame) {
+    if (!this.sessionId) throw new CliError("the remote session is not started");
+    const controller = new AbortController();
+    this.turnAbort = controller;
+    try {
+      await streamTurn(
+        this.api,
+        this.sessionId,
+        {
+          content: text,
+          client_request_id: randomUUID(),
+          ...(attachments?.length
+            ? {
+                attachments: attachments.map((image) => ({
+                  kind: "image",
+                  media_type: image.media_type,
+                  data: image.data,
+                })),
+              }
+            : {}),
+        },
+        (frame) => {
+          trackFrameSpend(frame, this.spend);
+          onFrame(frame);
+        },
+        controller.signal,
+      );
+    } catch (error) {
+      // Interrupted, whether before the turn answered or while it streamed.
+      if (controller.signal.aborted) {
+        onFrame({ type: "notice", message: "interrupted — the turn may still settle server-side" });
+        return;
+      }
+      throw error;
+    } finally {
+      if (this.turnAbort === controller) this.turnAbort = null;
+    }
+  }
+
+  interrupt() {
+    this.turnAbort?.abort();
+  }
+
+  usageLine() {
+    if (this.spend.tokens === 0) return null;
+    return `${this.spend.tokens} tok · $${this.spend.costUsd.toFixed(4)} this session`;
+  }
+
+  async stop() {
+    const sessionId = this.sessionId;
+    this.sessionId = null;
+    this.turnAbort?.abort();
+    if (sessionId) {
+      await this.api.json("DELETE /v1/terminus/sessions/{session_id}", {
+        params: { session_id: sessionId },
+      }).catch(() => undefined);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// One-shot lane (headless — the Codex/Claude Code/CI surface)
+// ---------------------------------------------------------------------------
+
+async function oneShotAgentDev(dir, flags, api) {
+  const dev = new LocalDev(dir, flags, api, {
+    onFrame: (frame) => {
+      if (flags.json) {
+        process.stdout.write(`${JSON.stringify(frame)}\n`);
+      } else {
+        renderFrame(frame, { lint: true });
+      }
+    },
+  });
+  await dev.start();
+  await dev.send(flags.prompt);
+  await dev.stop();
+  if (!flags.json) {
+    process.stdout.write("\n");
+    const usage = dev.usageLine();
+    if (usage) console.error(`[${usage}]`);
+  }
+  process.exitCode = dev.spend.errored ? 1 : 0;
+}
+
+/** One-shot trigger simulation (headless): fire one declared trigger the
+ * way the platform would — same input shape, same template resolution, same
+ * untrusted-event fence — with agent.run steps as real dev turns. The CI
+ * lane for standing-agent loops. */
+async function oneShotTriggerDev(dir, flags, api) {
+  const raw = JSON.parse(await readFile(path.join(dir, "terminus.json"), "utf8"));
+  const declared = listDevTriggers(raw);
+  const trigger = declared.find((candidate) => candidate.name === flags.trigger);
+  if (!trigger) {
+    const names = declared.map((entry) => `${entry.name} (${entry.kind})`).join(", ");
+    throw new CliError(
+      `no declared trigger named '${flags.trigger}'${
+        names ? ` — declared: ${names}` : " — this package declares no triggers"
+      }`,
+    );
+  }
+  let payload;
+  if (flags.payload) {
+    try {
+      payload = JSON.parse(await readFile(flags.payload, "utf8"));
+    } catch (error) {
+      throw new CliError(`--payload must name a JSON file: ${error?.message ?? error}`);
+    }
+  }
+  const emit = (frame) => {
+    if (flags.json) process.stdout.write(`${JSON.stringify(frame)}\n`);
+    else renderFrame(frame, { lint: true });
+  };
+  let collector = null;
+  const dev = new LocalDev(dir, flags, api, {
+    onFrame: (frame) => {
+      if (collector && frame.type === "delta" && typeof frame.text === "string") {
+        collector.text += frame.text;
+      }
+      emit(frame);
+    },
+  });
+  await dev.start();
+  try {
+    const built = await buildTriggerInput(trigger, { payload, devRoot: dev.devRoot });
+    emit({
+      type: "trigger_fired",
+      trigger: trigger.name,
+      kind: trigger.kind,
+      ...(built.baseline ? { baseline: true } : {}),
+      ...(built.unchanged ? { unchanged: true } : {}),
+    });
+    if (built.baseline) {
+      emit({
+        type: "notice",
+        message: `watch '${trigger.name}': first poll recorded the baseline — this firing tests the loop with the current content`,
+      });
+    }
+    await runTriggerFiring({
+      manifest: raw,
+      trigger,
+      input: built.input,
+      runTurn: async (prompt) => {
+        collector = { text: "" };
+        try {
+          await dev.send(prompt);
+          return collector.text;
+        } finally {
+          collector = null;
+        }
+      },
+      emit,
+    });
+  } finally {
+    await dev.stop();
+  }
+  if (!flags.json) {
+    process.stdout.write("\n");
+    const usage = dev.usageLine();
+    if (usage) console.error(`[${usage}]`);
+  }
+  process.exitCode = dev.spend.errored ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------------
+
+export async function agentDevCommand(dir, flags = parseFlags([], "dev"), commandArgs = []) {
+  const api = await connect(flags);
+  if (typeof flags.trigger === "string" && flags.trigger.length > 0) {
+    if (flags.remote) {
+      throw new CliError(
+        "trigger simulation runs on the local dev; drop --remote (publish exercises the real trigger plane)",
+      );
+    }
+    return oneShotTriggerDev(dir, flags, api);
+  }
+  if (typeof flags.prompt === "string" && flags.prompt.length > 0) {
+    if (flags.remote) {
+      throw new CliError(
+        "one-shot mode runs on the local dev; drop --remote (the web dev serves the remote gear)",
+      );
+    }
+    return oneShotAgentDev(dir, flags, api);
+  }
+  const { runDevServer } = await import("./devserver.mjs");
+  return runDevServer({ commandArgs, dir, flags, api });
+}