kanna-code 0.41.7 → 0.42.0

package/src/server/cursor-cli.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, test } from "bun:test"
+import { PassThrough } from "node:stream"
+import { CursorCliManager, normalizeCursorUsage, parseCursorLine, type CursorChildProcess } from "./cursor-cli"
+import type { HarnessEvent } from "./harness-types"
+
+function transcriptEntries(events: HarnessEvent[]) {
+  return events.flatMap((event) => (event.type === "transcript" && event.entry ? [event.entry] : []))
+}
+
+function firstEntry(line: string, model = "composer-2.5") {
+  return transcriptEntries(parseCursorLine(line, model))[0]
+}
+
+describe("parseCursorLine", () => {
+  test("init emits a session token and a cursor system_init entry", () => {
+    const events = parseCursorLine(
+      `{"type":"system","subtype":"init","apiKeySource":"env","cwd":"/repo","session_id":"sess-1","model":"Composer 2.5 Fast"}`,
+      "composer-2.5-fast",
+    )
+    expect(events[0]).toEqual({ type: "session_token", sessionToken: "sess-1" })
+    // Uses the configured model id, not the display label ("Composer 2.5 Fast") from the event.
+    expect(transcriptEntries(events)[0]).toMatchObject({
+      kind: "system_init",
+      provider: "cursor",
+      model: "composer-2.5-fast",
+    })
+  })
+
+  test("assistant text becomes an assistant_text entry", () => {
+    const line = `{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I found the bug"}]},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({ kind: "assistant_text", text: "I found the bug" })
+  })
+
+  test("shell tool call maps onto Bash", () => {
+    const line = `{"type":"tool_call","subtype":"started","call_id":"c-1","tool_call":{"shellToolCall":{"args":{"command":"ls -la","description":"List files"}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({
+      kind: "tool_call",
+      tool: { toolKind: "bash", toolId: "c-1", input: { command: "ls -la" } },
+    })
+  })
+
+  test("read tool call maps onto Read with the file path", () => {
+    const line = `{"type":"tool_call","subtype":"started","call_id":"c-2","tool_call":{"readToolCall":{"args":{"path":"/repo/note.txt"}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({
+      kind: "tool_call",
+      tool: { toolKind: "read_file", input: { filePath: "/repo/note.txt" } },
+    })
+  })
+
+  test("edit tool call maps Cursor's path/streamContent onto Write", () => {
+    const line = `{"type":"tool_call","subtype":"started","call_id":"c-3","tool_call":{"editToolCall":{"args":{"path":"/repo/calc.py","streamContent":"def add(a, b):\\n    return a + b\\n"}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({
+      kind: "tool_call",
+      tool: { toolKind: "write_file", input: { filePath: "/repo/calc.py", content: expect.stringContaining("def add") } },
+    })
+  })
+
+  test("glob / grep / updateTodos map onto Glob / Grep / TodoWrite", () => {
+    expect(firstEntry(`{"type":"tool_call","subtype":"started","call_id":"g-1","tool_call":{"globToolCall":{"args":{"targetDirectory":"/repo","globPattern":"**/*.py"}}},"session_id":"s"}`))
+      .toMatchObject({ kind: "tool_call", tool: { toolKind: "glob", input: { pattern: "**/*.py" } } })
+
+    expect(firstEntry(`{"type":"tool_call","subtype":"started","call_id":"g-2","tool_call":{"grepToolCall":{"args":{"pattern":"def add","path":"/repo"}}},"session_id":"s"}`))
+      .toMatchObject({ kind: "tool_call", tool: { toolKind: "grep", input: { pattern: "def add" } } })
+
+    expect(firstEntry(`{"type":"tool_call","subtype":"started","call_id":"t-1","tool_call":{"updateTodosToolCall":{"args":{"todos":[{"content":"step","status":"pending"}]}}},"session_id":"s"}`))
+      .toMatchObject({ kind: "tool_call", tool: { toolKind: "todo_write", input: { todos: [{ content: "step", status: "pending" }] } } })
+  })
+
+  test("an unmapped tool falls through to unknown_tool rather than being dropped", () => {
+    const line = `{"type":"tool_call","subtype":"started","call_id":"u-1","tool_call":{"mysteryToolCall":{"args":{"foo":"bar"}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({ kind: "tool_call", tool: { toolKind: "unknown_tool" } })
+  })
+
+  test("completed tool call becomes a tool_result keyed by call id", () => {
+    const line = `{"type":"tool_call","subtype":"completed","call_id":"c-2","tool_call":{"readToolCall":{"args":{"path":"/repo/note.txt"},"result":{"success":{"content":"hello world\\n","isEmpty":false}}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({
+      kind: "tool_result",
+      toolId: "c-2",
+      isError: false,
+      content: { content: "hello world\n", isEmpty: false },
+    })
+  })
+
+  test("a failed tool call is flagged as an error result", () => {
+    const line = `{"type":"tool_call","subtype":"completed","call_id":"c-9","tool_call":{"shellToolCall":{"args":{"command":"nope"},"result":{"error":{"message":"boom"}}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({ kind: "tool_result", toolId: "c-9", isError: true })
+  })
+
+  test("a completed tool with no structured result is not a false-positive error", () => {
+    const line = `{"type":"tool_call","subtype":"completed","call_id":"c-7","tool_call":{"shellToolCall":{"args":{"command":"ls"}}},"session_id":"s"}`
+    expect(firstEntry(line)).toMatchObject({ kind: "tool_result", toolId: "c-7", isError: false })
+  })
+
+  test("result emits a context-window update followed by a success result", () => {
+    const line = `{"type":"result","subtype":"success","duration_ms":15609,"is_error":false,"result":"Done","session_id":"s","usage":{"inputTokens":17640,"outputTokens":138,"cacheReadTokens":27968,"cacheWriteTokens":0}}`
+    const entries = transcriptEntries(parseCursorLine(line, "composer-2.5"))
+    expect(entries.map((entry) => entry.kind)).toEqual(["context_window_updated", "result"])
+    expect(entries[1]).toMatchObject({ kind: "result", isError: false, subtype: "success", result: "Done", durationMs: 15609 })
+  })
+
+  test("error result is surfaced as an error result entry", () => {
+    const line = `{"type":"result","subtype":"error","is_error":true,"result":"boom","session_id":"s"}`
+    const entries = transcriptEntries(parseCursorLine(line, "composer-2.5"))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]).toMatchObject({ kind: "result", isError: true, subtype: "error", result: "boom" })
+  })
+
+  test("prompt echo, reasoning, and malformed lines produce no entries", () => {
+    expect(parseCursorLine(`{"type":"user","message":{"content":[{"type":"text","text":"hi"}]}}`, "composer-2.5")).toEqual([])
+    expect(parseCursorLine(`{"type":"thinking","subtype":"delta"}`, "composer-2.5")).toEqual([])
+    expect(parseCursorLine("not json", "composer-2.5")).toEqual([])
+    expect(parseCursorLine("", "composer-2.5")).toEqual([])
+  })
+})
+
+describe("normalizeCursorUsage", () => {
+  test("sums direct + cache tokens into the context window snapshot", () => {
+    const usage = normalizeCursorUsage({ inputTokens: 17640, outputTokens: 138, cacheReadTokens: 27968, cacheWriteTokens: 0 })
+    expect(usage).toMatchObject({
+      inputTokens: 17640 + 27968,
+      cachedInputTokens: 27968,
+      outputTokens: 138,
+      usedTokens: 17640 + 27968 + 138,
+    })
+  })
+
+  test("returns null when there is no usage", () => {
+    expect(normalizeCursorUsage(undefined)).toBeNull()
+    expect(normalizeCursorUsage({ inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 })).toBeNull()
+  })
+})
+
+// Exercises the injectable `spawnProcess` seam: argv/stdin/resume wiring, stdout
+// stream -> events, and the "process ended without a result" error synthesis.
+function makeFakeChild() {
+  const stdin = new PassThrough()
+  const stdout = new PassThrough()
+  const stderr = new PassThrough()
+  let onClose: ((code: number | null) => void) | undefined
+  const child = {
+    stdin,
+    stdout,
+    stderr,
+    kill: () => true,
+    once(event: "close" | "error", listener: (arg: never) => void) {
+      if (event === "close") onClose = listener as unknown as (code: number | null) => void
+      return child
+    },
+  } as unknown as CursorChildProcess
+  return { child, stdin, stdout, stderr, close: (code: number | null) => onClose?.(code) }
+}
+
+describe("CursorCliManager.startTurn", () => {
+  test("passes --force/--model/--resume and writes the prompt to stdin", async () => {
+    const fake = makeFakeChild()
+    let captured: { cwd: string; argv: string[] } | undefined
+    const manager = new CursorCliManager({ spawnProcess: (args) => { captured = args; return fake.child } })
+
+    const stdinText = new Promise<string>((resolve) => {
+      let data = ""
+      fake.stdin.on("data", (chunk) => { data += chunk.toString() })
+      fake.stdin.on("end", () => resolve(data))
+    })
+
+    const turn = await manager.startTurn({ cwd: "/repo", content: "fix the bug", model: "composer-2.5-fast", sessionToken: "sess-9" })
+
+    expect(turn.provider).toBe("cursor")
+    expect(captured?.cwd).toBe("/repo")
+    expect(captured?.argv).toEqual([
+      "-p", "--output-format", "stream-json", "--force", "--model", "composer-2.5-fast", "--resume", "sess-9",
+    ])
+    expect(await stdinText).toBe("fix the bug")
+  })
+
+  test("omits --resume when there is no session token", async () => {
+    const fake = makeFakeChild()
+    let captured: { cwd: string; argv: string[] } | undefined
+    const manager = new CursorCliManager({ spawnProcess: (args) => { captured = args; return fake.child } })
+    await manager.startTurn({ cwd: "/repo", content: "hi", model: "composer-2.5", sessionToken: null })
+    expect(captured?.argv).not.toContain("--resume")
+  })
+
+  test("parses stdout NDJSON into events without synthesizing an error", async () => {
+    const fake = makeFakeChild()
+    const manager = new CursorCliManager({ spawnProcess: () => fake.child })
+    const turn = await manager.startTurn({ cwd: "/repo", content: "hi", model: "composer-2.5", sessionToken: null })
+    const iter = turn.stream[Symbol.asyncIterator]()
+
+    fake.stdout.write(`{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"hi there"}]},"session_id":"s"}\n`)
+    fake.stdout.write(`{"type":"result","subtype":"success","is_error":false,"result":"done","session_id":"s"}\n`)
+
+    // The consumer awaits each event as it is pushed, so this is deterministic without timers.
+    expect((await iter.next()).value).toMatchObject({ type: "transcript", entry: { kind: "assistant_text", text: "hi there" } })
+    expect((await iter.next()).value).toMatchObject({ type: "transcript", entry: { kind: "result", isError: false } })
+
+    fake.stdout.end()
+    fake.close(0)
+    expect((await iter.next()).done).toBe(true)
+  })
+
+  test("synthesizes an error result (with stderr) when the process ends without one", async () => {
+    const fake = makeFakeChild()
+    const manager = new CursorCliManager({ spawnProcess: () => fake.child })
+    const turn = await manager.startTurn({ cwd: "/repo", content: "hi", model: "bad-model", sessionToken: null })
+    const iter = turn.stream[Symbol.asyncIterator]()
+
+    // Awaiting stderr's "end" guarantees the manager's "data" handler ran first.
+    fake.stderr.end("Cannot use this model: bad-model")
+    await new Promise<void>((resolve) => fake.stderr.once("end", resolve))
+    fake.stdout.end()
+    fake.close(1)
+
+    expect((await iter.next()).value).toMatchObject({
+      type: "transcript",
+      entry: { kind: "result", isError: true, subtype: "error", result: expect.stringContaining("Cannot use this model") },
+    })
+    expect((await iter.next()).done).toBe(true)
+  })
+})

package/src/server/cursor-cli.ts

@@ -0,0 +1,376 @@
+import { spawn } from "node:child_process"
+import { randomUUID } from "node:crypto"
+import { createInterface } from "node:readline"
+import type { Readable, Writable } from "node:stream"
+import type { ContextWindowUsageSnapshot } from "../shared/types"
+import { asNumber, asRecord, asString } from "../shared/json"
+import { normalizeToolCall } from "../shared/tools"
+import type { HarnessEvent, HarnessTurn } from "./harness-types"
+import { AsyncQueue } from "./async-queue"
+import { timestamped } from "./transcript"
+
+/**
+ * Adapter for the Cursor CLI (`cursor-agent` binary).
+ *
+ * Unlike Claude (SDK) and Codex (persistent JSON-RPC `app-server`), Cursor runs
+ * one headless process per turn:
+ *
+ *   cursor-agent -p --output-format stream-json --force --model <id> [--resume <session>]
+ *
+ * with the prompt written to stdin. It emits NDJSON on stdout. `--force` is required
+ * in headless mode, otherwise the process blocks on a "Workspace Trust" prompt.
+ * Auth is via the CURSOR_API_KEY environment variable (inherited from the parent).
+ *
+ * Stream event types (one JSON object per line):
+ *   - { type: "system", subtype: "init", session_id, model, cwd, apiKeySource }
+ *   - { type: "user", ... }                              (prompt echo — ignored)
+ *   - { type: "assistant", message: { content: [{ type: "text", text }] } }
+ *   - { type: "thinking", subtype: "delta"|"completed" } (reasoning — ignored)
+ *   - { type: "tool_call", subtype: "started"|"completed", call_id, tool_call: { <name>ToolCall: {...} } }
+ *   - { type: "result", subtype: "success", is_error, duration_ms, result, session_id, usage }
+ */
+
+// Minimal child-process surface so tests can inject a fake without rebuilding ChildProcess.
+export interface CursorChildProcess {
+  readonly stdin: Writable | null
+  readonly stdout: Readable | null
+  readonly stderr: Readable | null
+  kill(signal?: NodeJS.Signals): boolean
+  once(event: "close", listener: (code: number | null) => void): unknown
+  once(event: "error", listener: (err: Error) => void): unknown
+}
+
+export type SpawnCursorAgent = (args: { cwd: string; argv: string[] }) => CursorChildProcess
+
+export interface StartCursorTurnArgs {
+  cwd: string
+  content: string
+  /** Concrete model id to spawn, e.g. "composer-2.5" or "composer-2.5-fast". */
+  model: string
+  /** Previous Cursor session id to resume, if any. */
+  sessionToken: string | null
+}
+
+/**
+ * Map Cursor's token usage into Kanna's context-window snapshot. Mirrors
+ * `normalizeClaudeUsageSnapshot` in agent.ts. Cursor does not report a max
+ * context window, so `maxTokens` is left undefined.
+ */
+export function normalizeCursorUsage(value: unknown): ContextWindowUsageSnapshot | null {
+  const usage = asRecord(value)
+  if (!usage) return null
+
+  const directInputTokens = asNumber(usage.inputTokens) ?? 0
+  const cacheReadTokens = asNumber(usage.cacheReadTokens) ?? 0
+  const cacheWriteTokens = asNumber(usage.cacheWriteTokens) ?? 0
+  const outputTokens = asNumber(usage.outputTokens) ?? 0
+
+  const inputTokens = directInputTokens + cacheReadTokens + cacheWriteTokens
+  const usedTokens = inputTokens + outputTokens
+  if (usedTokens <= 0) return null
+
+  return {
+    usedTokens,
+    inputTokens,
+    ...(cacheReadTokens > 0 ? { cachedInputTokens: cacheReadTokens } : {}),
+    ...(outputTokens > 0 ? { outputTokens } : {}),
+    lastUsedTokens: usedTokens,
+    lastInputTokens: inputTokens,
+    ...(cacheReadTokens > 0 ? { lastCachedInputTokens: cacheReadTokens } : {}),
+    ...(outputTokens > 0 ? { lastOutputTokens: outputTokens } : {}),
+    compactsAutomatically: false,
+  }
+}
+
+/**
+ * Translate a Cursor tool call into the Claude-style tool name + snake_case
+ * argument keys that `normalizeToolCall` understands, so tools render natively
+ * in the UI. Unknown tools fall through to `unknown_tool`.
+ */
+function translateCursorTool(
+  rawName: string,
+  args: Record<string, unknown>
+): { toolName: string; input: Record<string, unknown> } {
+  // Tool keys and argument names are taken from observed `cursor-agent` stream
+  // output. Anything unmapped falls through to `unknown_tool`, which still renders.
+  switch (rawName.toLowerCase().replace(/[^a-z]/g, "")) {
+    case "shell":
+      return { toolName: "Bash", input: { command: args.command ?? "", description: args.description } }
+    case "read":
+      return { toolName: "Read", input: { file_path: args.path ?? "" } }
+    case "edit":
+      // Cursor's edit emits the full new file content (`streamContent`) rather than
+      // an old/new diff, so it maps cleanly onto Write.
+      return { toolName: "Write", input: { file_path: args.path ?? "", content: args.streamContent ?? "" } }
+    case "glob":
+      return { toolName: "Glob", input: { pattern: args.globPattern ?? "" } }
+    case "grep":
+      return { toolName: "Grep", input: { pattern: args.pattern ?? "" } }
+    case "updatetodos":
+      return { toolName: "TodoWrite", input: { todos: Array.isArray(args.todos) ? args.todos : [] } }
+    default:
+      return { toolName: rawName, input: args }
+  }
+}
+
+/**
+ * Cursor nests tool calls under keys like "shellToolCall", "readToolCall".
+ * Returns the raw tool name, its args, and the completed result (if present).
+ */
+function extractCursorTool(toolCall: unknown): {
+  rawName: string
+  args: Record<string, unknown>
+  result?: unknown
+} {
+  const obj = asRecord(toolCall)
+  if (obj) {
+    for (const [k, v] of Object.entries(obj)) {
+      if (k.endsWith("ToolCall")) {
+        const inner = asRecord(v)
+        return {
+          rawName: k.slice(0, -"ToolCall".length),
+          args: asRecord(inner?.args) ?? {},
+          result: inner?.result,
+        }
+      }
+    }
+    // Fallback: { name, args }
+    const name = asString(obj.name)
+    if (name) {
+      return { rawName: name, args: asRecord(obj.args) ?? {}, result: obj.result }
+    }
+  }
+  return { rawName: "unknown", args: {} }
+}
+
+function extractAssistantText(message: unknown): string {
+  const content = asRecord(message)?.content
+  if (!Array.isArray(content)) return ""
+  return content
+    .filter((item): item is Record<string, unknown> => asRecord(item)?.type === "text")
+    .map((item) => asString(item.text) ?? "")
+    .join("")
+}
+
+/**
+ * Parse a single NDJSON line from `cursor-agent` into Kanna harness events.
+ * Pure and side-effect free so it can be unit tested against captured fixtures.
+ */
+export function parseCursorLine(line: string, configuredModel: string): HarnessEvent[] {
+  const trimmed = line.trim()
+  if (!trimmed) return []
+
+  let value: Record<string, unknown> | null
+  try {
+    value = asRecord(JSON.parse(trimmed))
+  } catch {
+    return []
+  }
+  if (!value) return []
+
+  const type = asString(value.type)
+  const debugRaw = trimmed
+
+  switch (type) {
+    case "system": {
+      if (asString(value.subtype) !== "init") return []
+      const events: HarnessEvent[] = []
+      const sessionId = asString(value.session_id)
+      if (sessionId) events.push({ type: "session_token", sessionToken: sessionId })
+      events.push({
+        type: "transcript",
+        entry: timestamped({
+          kind: "system_init",
+          provider: "cursor",
+          model: configuredModel,
+          tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebSearch", "TodoWrite"],
+          agents: [],
+          slashCommands: [],
+          mcpServers: [],
+          debugRaw,
+        }),
+      })
+      return events
+    }
+
+    case "assistant": {
+      const text = extractAssistantText(value.message)
+      if (!text) return []
+      return [{ type: "transcript", entry: timestamped({ kind: "assistant_text", text, debugRaw }) }]
+    }
+
+    case "tool_call": {
+      const subtype = asString(value.subtype)
+      const callId = asString(value.call_id) ?? randomUUID()
+      const { rawName, args, result } = extractCursorTool(value.tool_call)
+
+      if (subtype === "started") {
+        const { toolName, input } = translateCursorTool(rawName, args)
+        return [
+          {
+            type: "transcript",
+            entry: timestamped({
+              kind: "tool_call",
+              tool: normalizeToolCall({ toolName, toolId: callId, input }),
+              debugRaw,
+            }),
+          },
+        ]
+      }
+
+      if (subtype === "completed") {
+        // Only flag an error when Cursor explicitly reports one. A missing/non-object
+        // result (e.g. a bare string) is treated as success rather than a false error.
+        const resultRecord = asRecord(result)
+        const isError = Boolean(resultRecord && ("error" in resultRecord || "failure" in resultRecord))
+        const content = resultRecord?.success ?? resultRecord?.error ?? resultRecord?.failure ?? result
+        return [
+          {
+            type: "transcript",
+            entry: timestamped({
+              kind: "tool_result",
+              toolId: callId,
+              content,
+              isError,
+              debugRaw,
+            }),
+          },
+        ]
+      }
+
+      return []
+    }
+
+    case "result": {
+      const events: HarnessEvent[] = []
+      const usage = normalizeCursorUsage(value.usage)
+      if (usage) {
+        events.push({
+          type: "transcript",
+          entry: timestamped({ kind: "context_window_updated", usage }),
+        })
+      }
+      const isError = Boolean(value.is_error)
+      events.push({
+        type: "transcript",
+        entry: timestamped({
+          kind: "result",
+          subtype: isError ? "error" : "success",
+          isError,
+          durationMs: asNumber(value.duration_ms) ?? 0,
+          result: asString(value.result) ?? "",
+          debugRaw,
+        }),
+      })
+      return events
+    }
+
+    // "user" (prompt echo), "thinking" (reasoning), and unknown types are dropped —
+    // Kanna already records the user prompt and has no reasoning transcript kind.
+    default:
+      return []
+  }
+}
+
+export class CursorCliManager {
+  private readonly spawnProcess: SpawnCursorAgent
+
+  constructor(args: { spawnProcess?: SpawnCursorAgent } = {}) {
+    this.spawnProcess =
+      args.spawnProcess ??
+      (({ cwd, argv }) =>
+        spawn("cursor-agent", argv, {
+          cwd,
+          stdio: ["pipe", "pipe", "pipe"],
+          env: process.env,
+        }) as unknown as CursorChildProcess)
+  }
+
+  async startTurn(args: StartCursorTurnArgs): Promise<HarnessTurn> {
+    const argv = [
+      "-p",
+      "--output-format",
+      "stream-json",
+      "--force",
+      "--model",
+      args.model,
+    ]
+    if (args.sessionToken) {
+      argv.push("--resume", args.sessionToken)
+    }
+
+    const child = this.spawnProcess({ cwd: args.cwd, argv })
+    const queue = new AsyncQueue<HarnessEvent>()
+
+    let sawResult = false
+    let finished = false
+    let stderr = ""
+
+    const finalize = (code: number | null) => {
+      if (finished) return
+      finished = true
+      if (!sawResult) {
+        const detail = stderr.trim() || `cursor-agent exited with code ${code ?? "unknown"}`
+        queue.push({
+          type: "transcript",
+          entry: timestamped({
+            kind: "result",
+            subtype: "error",
+            isError: true,
+            durationMs: 0,
+            result: detail,
+          }),
+        })
+      }
+      queue.finish()
+    }
+
+    if (child.stdout) {
+      const rl = createInterface({ input: child.stdout })
+      rl.on("line", (line) => {
+        for (const event of parseCursorLine(line, args.model)) {
+          if (event.type === "transcript" && event.entry?.kind === "result") {
+            sawResult = true
+          }
+          queue.push(event)
+        }
+      })
+    }
+
+    if (child.stderr) {
+      child.stderr.on("data", (chunk: Buffer | string) => {
+        stderr += chunk.toString()
+      })
+    }
+
+    child.once("error", (err) => {
+      stderr += `\n${err.message}`
+      finalize(null)
+    })
+    child.once("close", (code) => finalize(code))
+
+    // Send the prompt over stdin and close it so the agent starts.
+    if (child.stdin) {
+      child.stdin.end(args.content)
+    }
+
+    return {
+      provider: "cursor",
+      stream: queue,
+      interrupt: async () => {
+        try {
+          child.kill("SIGINT")
+        } catch {
+          // process already gone
+        }
+      },
+      close: () => {
+        try {
+          child.kill()
+        } catch {
+          // process already gone
+        }
+      },
+    }
+  }
+}

package/src/server/paths.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process"
 import { mkdir, stat } from "node:fs/promises"
 import { homedir } from "node:os"
 import path from "node:path"
@@ -26,6 +27,69 @@ export async function ensureProjectDirectory(localPath: string) {
   }
 }
 
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Pick a clone destination that doesn't already exist.
+ * Tries `localPath` first, then falls back to `fallbackPath` if provided.
+ * Returns the resolved absolute path that was chosen.
+ */
+export async function resolveClonePath(localPath: string, fallbackPath?: string): Promise<string> {
+  const primary = resolveLocalPath(localPath)
+  if (!(await pathExists(primary))) {
+    return primary
+  }
+  if (fallbackPath) {
+    const secondary = resolveLocalPath(fallbackPath)
+    if (!(await pathExists(secondary))) {
+      return secondary
+    }
+  }
+  throw new Error(`Destination path '${primary}' already exists`)
+}
+
+/**
+ * Clone a git repository into the given local path.
+ * The parent directory is created if it doesn't exist.
+ * Rejects if `git clone` exits with a non-zero code.
+ */
+export async function cloneRepository(cloneUrl: string, resolvedPath: string): Promise<void> {
+  const parentDir = path.dirname(resolvedPath)
+
+  await mkdir(parentDir, { recursive: true })
+
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn("git", ["clone", cloneUrl, resolvedPath], {
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    let stderr = ""
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString()
+    })
+
+    child.on("error", (err) => {
+      reject(new Error(`Failed to start git clone: ${err.message}`))
+    })
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve()
+      } else {
+        const message = stderr.trim() || `git clone exited with code ${code}`
+        reject(new Error(message))
+      }
+    })
+  })
+}
+
 export function getProjectUploadDir(localPath: string) {
   return path.join(resolveLocalPath(localPath), ".kanna", "uploads")
 }