@runuai/host 0.8.4 → 0.8.5

package/images/standard/Dockerfile

@@ -237,6 +237,15 @@ RUN if [ "$INSTALL_GROK" = "1" ]; then \
         || echo "[warn] grok install failed — grok engine unavailable in this image"; \
     fi
 
+# Cursor Agent (Anysphere) — installs to /home/node/.local/bin/cursor-agent.
+# Auth is CURSOR_API_KEY (env-injected by the adapter), so nothing to copy at
+# task-up — just the binary.
+ARG INSTALL_CURSOR=0
+RUN if [ "$INSTALL_CURSOR" = "1" ]; then \
+      bash -lc 'curl https://cursor.com/install -fsS | bash' \
+        || echo "[warn] cursor install failed — cursor engine unavailable in this image"; \
+    fi
+
 ENV PATH=/home/node/.local/bin:$PATH
 
 # ---------------------------------------------------------------------------

package/lib/agents/cursor.ts

@@ -0,0 +1,324 @@
+/**
+ * CursorSession — a real AgentSession backed by **Cursor Agent** (`cursor-agent`),
+ * run inside the task container:
+ *
+ *   docker exec -i -e CURSOR_API_KEY=… task-<id>-app-1 \
+ *     /home/node/.local/bin/cursor-agent -p "<prompt>" \
+ *     --output-format stream-json --stream-partial-output --force --trust \
+ *     -m <model> [--resume <sessionId>]
+ *
+ * One-shot per turn (like Kimi/Grok); sends serialized; continuity via
+ * `--resume <sessionId>` captured from the stream. Cursor's stream-json is
+ * essentially Claude Code's — the RICHEST of the extra engines (streaming text
+ * AND tool cards):
+ *
+ *   {"type":"system","subtype":"init","session_id":…}          → session id
+ *   {"type":"thinking","subtype":"delta"|"completed",…}        → skipped
+ *   {"type":"assistant","message":{content:[{text}]},"timestamp_ms":…}
+ *                                                              → message_delta
+ *   {"type":"tool_call","subtype":"started","call_id","tool_call":{…}}
+ *                                                              → tool_call card
+ *   {"type":"result","subtype":"success"|"error","result",session_id}
+ *                                                              → message_complete + end
+ *
+ * AUTH is a Cursor API key (`CURSOR_API_KEY`) — env-injected at exec, like the
+ * Claude token (no config-dir copy). Cloud never sees it (ADR-015). `-p` runs
+ * headless with `--force` (auto-run tools; the container is the sandbox) and
+ * `--trust` (skip the workspace-trust prompt). Cursor has no system-prompt
+ * flag, so the briefing folds into the first turn's prompt.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+
+import { newId } from "../ulid";
+import { register } from "./registry";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  RosterAgent,
+} from "./types";
+
+const CURSOR_BIN = "/home/node/.local/bin/cursor-agent";
+
+// A curated slice of Cursor's ~32 models (full ids from `cursor-agent
+// --list-models`). `auto` lets Cursor pick; the rest are the frontier. The UI
+// also accepts any typed id (unverified round-trip). UPDATE as Cursor's lineup
+// changes.
+const CURSOR_MODELS = [
+  "auto",
+  "composer-2.5",
+  "claude-opus-4-8-thinking-high",
+  "gpt-5.6-sol-high",
+  "cursor-grok-4.5-high",
+  "claude-fable-5-thinking-high",
+];
+const CURSOR_DEFAULT_MODEL = "auto";
+const CURSOR_EFFORTS: string[] = []; // effort is baked into the model id
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping.
+// ---------------------------------------------------------------------------
+
+function assistantText(msg: Record<string, unknown>): string {
+  const message = msg.message as { content?: unknown } | undefined;
+  const content = Array.isArray(message?.content) ? message!.content : [];
+  let out = "";
+  for (const raw of content) {
+    const block = raw as { type?: unknown; text?: unknown };
+    if (block.type === "text" && typeof block.text === "string") out += block.text;
+  }
+  return out;
+}
+
+/** "shellToolCall" → "shell", "readFileToolCall" → "readFile". */
+function prettyTool(name: string): string {
+  return name.replace(/ToolCall$/, "") || "tool";
+}
+
+export interface MappedCursorLine {
+  textDelta?: string;
+  toolCall?: { id: string; title: string; detail: string };
+  end?: boolean;
+  finalText?: string;
+  sessionId?: string;
+  errorText?: string;
+}
+
+export function mapCursorLine(line: string): MappedCursorLine {
+  const t = line.trim();
+  if (!t.startsWith("{")) return {};
+  let m: Record<string, unknown>;
+  try {
+    m = JSON.parse(t) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+
+  if (m.type === "system") {
+    return typeof m.session_id === "string" ? { sessionId: m.session_id } : {};
+  }
+  if (m.type === "assistant") {
+    // Streaming partials carry timestamp_ms; the final full message (finalized
+    // by `result`) does not — only stream the partials to avoid doubling.
+    if (typeof m.timestamp_ms === "number") {
+      const text = assistantText(m);
+      if (text) return { textDelta: text };
+    }
+    return {};
+  }
+  if (m.type === "tool_call" && m.subtype === "started") {
+    const tc = (m.tool_call ?? {}) as Record<string, unknown>;
+    const [name, spec] = Object.entries(tc)[0] ?? ["tool", {}];
+    const args = ((spec as Record<string, unknown>)?.args ?? {}) as Record<string, unknown>;
+    const pick = args.command ?? args.path ?? args.filePath ?? args.file_path ?? args.query;
+    return {
+      toolCall: {
+        id: typeof m.call_id === "string" ? m.call_id : newId(),
+        title: prettyTool(name),
+        detail: typeof pick === "string" ? pick : "",
+      },
+    };
+  }
+  if (m.type === "result") {
+    const errored = m.is_error === true;
+    return {
+      end: true,
+      sessionId: typeof m.session_id === "string" ? m.session_id : undefined,
+      finalText: typeof m.result === "string" ? m.result : undefined,
+      errorText: errored
+        ? typeof m.result === "string"
+          ? m.result
+          : "cursor turn failed"
+        : undefined,
+    };
+  }
+  // thinking / user / other → nothing.
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+export type Spawner = (args: string[]) => ChildProcess;
+const defaultSpawn: Spawner = (args) =>
+  spawn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+
+export class CursorSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "cursor";
+
+  private readonly containerName: string;
+  private readonly model?: string;
+  private readonly systemPreamble: string;
+  private readonly agentEnv: Record<string, string>;
+  private readonly spawner: Spawner;
+  private readonly apiKey: string;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private sessionId: string | null = null;
+  private current: ChildProcess | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private sentPreamble = false;
+  private closed = false;
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    containerName: string;
+    systemPreamble: string;
+    agentEnv?: Record<string, string>;
+    spawner?: Spawner;
+    apiKey?: string;
+  }) {
+    this.agentId = args.agent.id;
+    this.containerName = args.containerName;
+    this.model = args.agent.model;
+    this.systemPreamble = args.systemPreamble;
+    this.agentEnv = args.agentEnv ?? {};
+    this.spawner = args.spawner ?? defaultSpawn;
+    this.apiKey = args.apiKey ?? process.env.CURSOR_API_KEY ?? "";
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    this.queue = this.queue.then(() => this.runTurn(text));
+    return this.queue;
+  }
+
+  private buildArgs(prompt: string): string[] {
+    const args = ["exec", "-i", "-u", "node", "-e", `CURSOR_API_KEY=${this.apiKey}`];
+    for (const [k, v] of Object.entries(this.agentEnv)) {
+      args.push("-e", `${k}=${v}`);
+    }
+    args.push(
+      this.containerName,
+      CURSOR_BIN,
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--stream-partial-output",
+      "--force", // container is the sandbox — auto-run tools
+      "--trust", // skip the workspace-trust prompt in headless
+    );
+    if (this.model && this.model !== "auto") args.push("-m", this.model);
+    if (this.sessionId) args.push("--resume", this.sessionId);
+    return args;
+  }
+
+  private async runTurn(text: string): Promise<void> {
+    if (this.closed) return;
+    // No system-prompt flag — fold the briefing into the first turn; later
+    // turns carry it via the resumed session.
+    const prompt =
+      !this.sentPreamble && this.systemPreamble.trim().length > 0
+        ? `${this.systemPreamble}\n\n---\n\n${text}`
+        : text;
+    this.sentPreamble = true;
+
+    const child = this.spawner(this.buildArgs(prompt));
+    this.current = child;
+
+    let acc = "";
+    let sawText = false;
+    let buf = "";
+    const consume = (chunk: string): void => {
+      buf += chunk;
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const m = mapCursorLine(line);
+        if (m.sessionId) this.sessionId = m.sessionId;
+        if (typeof m.textDelta === "string") {
+          sawText = true;
+          acc += m.textDelta;
+          this.emit({ type: "message_delta", text: m.textDelta });
+        }
+        if (m.toolCall) {
+          this.emit({
+            type: "tool_call",
+            id: m.toolCall.id,
+            title: m.toolCall.title,
+            detail: m.toolCall.detail,
+          });
+        }
+        if (m.end) {
+          if (m.errorText) this.emit({ type: "error", message: m.errorText });
+          const finalText = m.finalText ?? acc;
+          if (sawText || finalText) {
+            this.emit({ type: "message_complete", text: finalText });
+          }
+        }
+      }
+    };
+    child.stdout?.on("data", (b: Buffer) => consume(b.toString("utf8")));
+    let stderr = "";
+    child.stderr?.on("data", (b: Buffer) => {
+      stderr += b.toString("utf8");
+    });
+
+    await new Promise<void>((resolve) => {
+      const finish = (code: number | null, spawnErr?: string): void => {
+        this.current = null;
+        if (buf.trim().length > 0) consume("\n");
+        if (this.closed) return resolve();
+        if (spawnErr) {
+          this.emit({ type: "error", message: `cursor spawn failed: ${spawnErr}` });
+        } else if (code !== 0) {
+          const tail = stderr.trim().slice(-500);
+          this.emit({
+            type: "error",
+            message: `cursor exited ${code ?? "null"}${tail ? `: ${tail}` : ""}`,
+          });
+        }
+        this.emit({ type: "turn_complete" });
+        resolve();
+      };
+      child.on("exit", (code) => finish(code));
+      child.on("error", (err) => finish(null, err.message));
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    this.current?.kill("SIGKILL");
+  }
+
+  async resolvePermission(): Promise<void> {
+    /* --force auto-approves; no permission requests are emitted */
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.current?.kill("SIGKILL");
+    this.current = null;
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+register({
+  kind: "cursor",
+  label: "Cursor",
+  supportedModels: () => [...CURSOR_MODELS],
+  defaultModel: CURSOR_DEFAULT_MODEL,
+  supportedEfforts: () => [...CURSOR_EFFORTS],
+  // Gated on a Cursor API key in the host env (loaded from .env.local); the
+  // adapter injects it into the container. No key → engine not advertised.
+  available: () => Boolean(process.env.CURSOR_API_KEY),
+  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
+    new CursorSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
+});

package/lib/agents/factory.ts

@@ -19,6 +19,7 @@ import "./claude";
 import "./codex";
 import "./kimi";
 import "./grok";
+import "./cursor";
 
 import { factoryFor } from "./registry";
 import type { AgentSession, AgentSessionFactory } from "./types";

package/lib/standard-image.ts

@@ -76,11 +76,18 @@ const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
  * into containers at task-up; claude/codex are always baked). Folded into the
  * build hash below, so logging into a new engine triggers a rebuild.
  */
-export function configuredOptionalEngines(): { kimi: boolean; grok: boolean } {
+export function configuredOptionalEngines(): {
+  kimi: boolean;
+  grok: boolean;
+  cursor: boolean;
+} {
   const home = process.env.UAI_OWNER_HOME?.trim() || homedir();
   return {
     kimi: existsSync(join(home, ".kimi-code", "credentials", "kimi-code.json")),
     grok: existsSync(join(home, ".grok", "auth.json")),
+    // Cursor auths via CURSOR_API_KEY (env, loaded from .env.local), not a
+    // config file — install it when the key is present.
+    cursor: Boolean(process.env.CURSOR_API_KEY),
   };
 }
 
@@ -333,9 +340,11 @@ export async function ensureStandardImage(): Promise<void> {
     `INSTALL_KIMI=${engines.kimi ? 1 : 0}`,
     "--build-arg",
     `INSTALL_GROK=${engines.grok ? 1 : 0}`,
+    "--build-arg",
+    `INSTALL_CURSOR=${engines.cursor ? 1 : 0}`,
   ];
   const contextHash = await hashBuildContext(
-    `kimi=${engines.kimi ? 1 : 0};grok=${engines.grok ? 1 : 0}`,
+    `kimi=${engines.kimi ? 1 : 0};grok=${engines.grok ? 1 : 0};cursor=${engines.cursor ? 1 : 0}`,
   );
   const inspect = await run("docker", [
     "image",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",