airaknit 1.1.2-rc.9

package/src/server/claude-pty/tui-source.adapter.ts

@@ -0,0 +1,343 @@
+import { readdir, stat, open } from "node:fs/promises"
+import { existsSync, watch } from "node:fs"
+import path from "node:path"
+import { awaitClaudeSessionForPid } from "./claude-session-registry.adapter"
+import { computeJsonlPath } from "./jsonl-path.adapter"
+
+export async function findLatestTranscript(
+  projectDir: string,
+  opts: { minMtimeMs?: number } = {},
+): Promise<string | null> {
+  if (!existsSync(projectDir)) return null
+  let entries: string[]
+  try {
+    entries = await readdir(projectDir)
+  } catch {
+    return null
+  }
+  const jsonlNames = entries.filter((n) => n.endsWith(".jsonl"))
+  if (jsonlNames.length === 0) return null
+  const floor = opts.minMtimeMs ?? 0
+  let bestPath: string | null = null
+  let bestMtime = 0
+  for (const name of jsonlNames) {
+    const full = path.join(projectDir, name)
+    try {
+      const s = await stat(full)
+      // Skip stale JSONLs from prior sessions in the same project dir.
+      // Without this floor, kanna's watcher locks onto the most-recently-
+      // touched OLD transcript while claude is still in the middle of
+      // creating its new one — events from the new session are lost.
+      if (s.mtimeMs < floor) continue
+      if (s.mtimeMs > bestMtime) {
+        bestMtime = s.mtimeMs
+        bestPath = full
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return bestPath
+}
+
+export interface TranscriptStream {
+  lines: AsyncIterable<string>
+  filePath: Promise<string>
+  close(): void
+}
+
+export interface StartTranscriptStreamArgs {
+  projectDir: string
+  knownFilePath?: string
+  /**
+   * Mtime floor (ms) for JSONL discovery. When `knownFilePath` is unset
+   * AND the session-registry lookup (via `claudeChildPid`) fails,
+   * `findLatestTranscript` filters out files older than this — set to
+   * spawn-start time so stale JSONLs from prior sessions in the same
+   * project dir cannot win the race. The registry lookup, when it
+   * succeeds, makes this floor moot.
+   */
+  minMtimeMs?: number
+  pollMode?: boolean
+  pollIntervalMs?: number
+  firstFileTimeoutMs?: number
+  /**
+   * Live PID of the spawned `claude` child. When set together with
+   * `homeDir`, `locateFirstFile` first polls `${homeDir}/.claude/sessions/<pid>.json`
+   * (claude-code's own per-PID registry) to obtain the real session UUID,
+   * then computes the JSONL path directly. This is race-free under
+   * concurrent claude spawns sharing the same projectDir — the legacy
+   * mtime heuristic can pick the wrong file when other claude TUIs run
+   * in the same cwd. Falls back to `findLatestTranscript` if the
+   * registry file does not appear within `sessionRegistryTimeoutMs`.
+   */
+  claudeChildPid?: number
+  homeDir?: string
+  sessionRegistryTimeoutMs?: number
+  sessionRegistryPollMs?: number
+}
+
+const DEFAULT_FIRST_FILE_TIMEOUT_MS = 20_000
+const DEFAULT_POLL_INTERVAL_MS = 50
+const DEFAULT_SESSION_REGISTRY_TIMEOUT_MS = 2_000
+const DEFAULT_SESSION_REGISTRY_POLL_MS = 20
+const DEFAULT_SAFETY_POLL_MS = 500
+
+export async function startTranscriptStream(args: StartTranscriptStreamArgs): Promise<TranscriptStream> {
+  const lineQueue: string[] = []
+  const lineWaiters: Array<(r: IteratorResult<string, undefined>) => void> = []
+  let buffer = ""
+  let position = 0
+  let closed = false
+  let watcher: ReturnType<typeof watch> | null = null
+  let pollTimer: ReturnType<typeof setInterval> | null = null
+
+  function pushLine(line: string) {
+    const w = lineWaiters.shift()
+    if (w) w({ value: line, done: false })
+    else lineQueue.push(line)
+  }
+
+  function endLines() {
+    const done: IteratorReturnResult<undefined> = { value: undefined, done: true }
+    while (lineWaiters.length > 0) {
+      const w = lineWaiters.shift()
+      if (w) w(done)
+    }
+  }
+
+  async function readNewBytes(filePath: string) {
+    try {
+      const s = await stat(filePath)
+      if (s.size <= position) return
+      const fd = await open(filePath, "r")
+      try {
+        const length = s.size - position
+        const buf = Buffer.alloc(length)
+        await fd.read(buf, 0, length, position)
+        position = s.size
+        buffer += buf.toString("utf8")
+        const parts = buffer.split("\n")
+        buffer = parts.pop() ?? ""
+        for (const line of parts) {
+          if (line.length === 0) continue
+          pushLine(line)
+        }
+      } finally {
+        await fd.close()
+      }
+    } catch {
+      /* file rotated / truncated mid-read; next tick recovers */
+    }
+  }
+
+  function startFollowing(filePath: string) {
+    if (args.pollMode) {
+      const interval = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+      pollTimer = setInterval(() => { void readNewBytes(filePath) }, interval)
+    } else {
+      try {
+        watcher = watch(filePath, () => { void readNewBytes(filePath) })
+      } catch {
+        const interval = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+        pollTimer = setInterval(() => { void readNewBytes(filePath) }, interval)
+      }
+      // Safety-net poll alongside fs.watch: macOS FSEvents was observed to
+      // coalesce or drop events when claude appended several lines in rapid
+      // succession at turn end (final `assistant` + `system/turn_duration`
+      // rows silently lost). The watcher handles low-latency streaming;
+      // this poll guarantees eventual delivery within DEFAULT_SAFETY_POLL_MS.
+      pollTimer = setInterval(() => { void readNewBytes(filePath) }, DEFAULT_SAFETY_POLL_MS)
+    }
+    void readNewBytes(filePath)
+  }
+
+  async function locateFirstFile(): Promise<string> {
+    if (args.knownFilePath) return args.knownFilePath
+    // Preferred path: read claude's per-PID session file to learn the real
+    // session UUID, then compute the JSONL path directly. Race-free.
+    if (args.claudeChildPid && args.homeDir) {
+      const entry = await awaitClaudeSessionForPid({
+        homeDir: args.homeDir,
+        pid: args.claudeChildPid,
+        timeoutMs: args.sessionRegistryTimeoutMs ?? DEFAULT_SESSION_REGISTRY_TIMEOUT_MS,
+        pollIntervalMs: args.sessionRegistryPollMs ?? DEFAULT_SESSION_REGISTRY_POLL_MS,
+      })
+      if (entry) {
+        const computed = computeJsonlPath({
+          homeDir: args.homeDir,
+          cwd: entry.cwd,
+          sessionId: entry.sessionId,
+        })
+        // Registry resolved: the JSONL path is AUTHORITATIVE for this
+        // child pid. Poll existsSync until close or timeout. Do NOT fall
+        // back to mtime — when the registry-resolved JSONL never appears
+        // (e.g. claude was spawned but no prompt was ever sent), mtime
+        // discovery silently picks the newest unrelated JSONL in the
+        // shared project dir, causing cross-session transcript bleed.
+        // Without a timeout, a missed first prompt wedges the driver
+        // forever; bound the wait by firstFileTimeoutMs so the caller
+        // can surface a failure event and the user can retry.
+        const jsonlPollMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+        const jsonlTimeoutMs = args.firstFileTimeoutMs ?? DEFAULT_FIRST_FILE_TIMEOUT_MS
+        const jsonlPollStart = Date.now()
+        while (!closed) {
+          if (existsSync(computed)) return computed
+          if (Date.now() - jsonlPollStart > jsonlTimeoutMs) {
+            throw new Error(
+              `registry-resolved JSONL ${computed} did not appear in ${jsonlTimeoutMs}ms (claude TUI likely missed first prompt)`,
+            )
+          }
+          await new Promise((r) => setTimeout(r, jsonlPollMs))
+        }
+        throw new Error("transcript stream closed before registry-resolved JSONL appeared")
+      }
+    }
+    const timeoutMs = args.firstFileTimeoutMs ?? DEFAULT_FIRST_FILE_TIMEOUT_MS
+    const findOpts = { minMtimeMs: args.minMtimeMs }
+    const existing = await findLatestTranscript(args.projectDir, findOpts)
+    if (existing) return existing
+    return new Promise<string>((resolve, reject) => {
+      const start = Date.now()
+      const pollMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
+      const timer = setInterval(async () => {
+        if (closed) {
+          clearInterval(timer)
+          reject(new Error("transcript stream closed before first file appeared"))
+          return
+        }
+        if (Date.now() - start > timeoutMs) {
+          clearInterval(timer)
+          reject(new Error(`transcript file did not appear in ${timeoutMs}ms under ${args.projectDir}`))
+          return
+        }
+        const found = await findLatestTranscript(args.projectDir, findOpts)
+        if (found) {
+          clearInterval(timer)
+          resolve(found)
+        }
+      }, pollMs)
+    })
+  }
+
+  const filePathPromise = locateFirstFile()
+  void filePathPromise
+    .then((fp) => { if (!closed) startFollowing(fp) })
+    .catch(() => {
+      /* surfaced via filePath rejection */
+    })
+
+  const lines: AsyncIterable<string> = {
+    [Symbol.asyncIterator]() {
+      return {
+        next(): Promise<IteratorResult<string, undefined>> {
+          if (lineQueue.length > 0) {
+            const v = lineQueue.shift()
+            if (v !== undefined) return Promise.resolve({ value: v, done: false })
+          }
+          if (closed) return Promise.resolve({ value: undefined, done: true as const })
+          return new Promise((resolve) => lineWaiters.push(resolve))
+        },
+      }
+    },
+  }
+
+  return {
+    lines,
+    filePath: filePathPromise,
+    close() {
+      if (closed) return
+      closed = true
+      if (watcher) try { watcher.close() } catch { /* swallow */ }
+      if (pollTimer) clearInterval(pollTimer)
+      endLines()
+    },
+  }
+}
+
+export async function waitForResultEntry(
+  stream: TranscriptStream,
+  opts: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<{ rawLine: string; parsed: { type: string } }> {
+  const timeoutMs = opts.timeoutMs
+  return new Promise((resolve, reject) => {
+    let settled = false
+
+    const timer = timeoutMs !== undefined
+      ? setTimeout(() => {
+          if (settled) return
+          settled = true
+          stream.close()
+          reject(new Error(`waitForResultEntry timed out after ${timeoutMs}ms`))
+        }, timeoutMs)
+      : null
+
+    const onAbort = () => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      stream.close()
+      reject(new Error("aborted"))
+    }
+
+    if (opts.signal) {
+      if (opts.signal.aborted) {
+        onAbort()
+        return
+      }
+      opts.signal.addEventListener("abort", onAbort, { once: true })
+    }
+
+    async function consume() {
+      try {
+        for await (const line of stream.lines) {
+          if (settled) return
+          let parsed: { type?: string; subtype?: string; error?: string; isApiErrorMessage?: boolean; apiErrorStatus?: number }
+          try { parsed = JSON.parse(line) as typeof parsed } catch { continue }
+          // Two completion markers:
+          //   - `type: "result"` — SDK / `claude -p` output (one-shot)
+          //   - `type: "system", subtype: "turn_duration"` — interactive TUI
+          //     turn end (interactive mode never writes a `result` row).
+          // Reference: canon/index.ts:711 turnDurationMsFromRows.
+          const isTurnEnd =
+            parsed.type === "result" ||
+            (parsed.type === "system" && parsed.subtype === "turn_duration")
+          if (isTurnEnd) {
+            settled = true
+            if (timer) clearTimeout(timer)
+            if (opts.signal) opts.signal.removeEventListener("abort", onAbort)
+            resolve({ rawLine: line, parsed: { type: parsed.type ?? "result" } })
+            return
+          }
+          // Rate-limit responses (HTTP 429) arrive as assistant messages rather
+          // than result entries — surface them immediately so callers can
+          // distinguish a transient limit from a structural probe failure.
+          if (parsed.type === "assistant" && parsed.isApiErrorMessage && parsed.apiErrorStatus === 429) {
+            settled = true
+            if (timer) clearTimeout(timer)
+            if (opts.signal) opts.signal.removeEventListener("abort", onAbort)
+            const rlErr = new Error("rate_limited") as Error & { code: string }
+            rlErr.code = "rate_limited"
+            reject(rlErr)
+            return
+          }
+        }
+        if (!settled) {
+          settled = true
+          if (timer) clearTimeout(timer)
+          if (opts.signal) opts.signal.removeEventListener("abort", onAbort)
+          reject(new Error("transcript stream ended before result entry"))
+        }
+      } catch (err) {
+        if (!settled) {
+          settled = true
+          if (timer) clearTimeout(timer)
+          if (opts.signal) opts.signal.removeEventListener("abort", onAbort)
+          reject(err)
+        }
+      }
+    }
+
+    void consume()
+  })
+}

package/src/server/claude-pty/tunnel-gateway.ts

@@ -0,0 +1,12 @@
+export type ProposeFromToolResult =
+  | { status: "ok"; url: string; tunnelId: string }
+  | { status: "invalid_port"; reason: string }
+  | { status: "no_tunnel"; reason: string }
+  | { status: "error"; reason: string }
+
+export interface TunnelGateway {
+  getPublicUrl(): string | null
+  isActive(): boolean
+  getTokenForRequest?(): string | null
+  proposeFromTool(args: { chatId: string; port: number }): Promise<ProposeFromToolResult>
+}

package/src/server/claude-pty-mcp/canonical-args.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto"
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value)
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`
+  }
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`
+}
+
+export function canonicalArgsHash(args: unknown): string {
+  return createHash("sha256").update(canonicalJson(args)).digest("hex")
+}

package/src/server/claude-pty-mcp/fs-stat.adapter.ts

@@ -0,0 +1,8 @@
+import { stat } from "node:fs/promises"
+import type { Stats } from "node:fs"
+
+export type PathInfo = Stats
+
+export async function statPathOrNull(p: string): Promise<PathInfo | null> {
+  return await stat(p).catch(() => null)
+}

package/src/server/claude-pty-mcp/history-primer.ts

@@ -0,0 +1,90 @@
+import type { AgentProvider, TranscriptEntry } from "../../shared/types"
+
+// Policy: renderEntry handles message-shaped TranscriptEntry kinds only
+// (user_prompt, assistant_text, tool_call). All other kinds — slash-command
+// echoes, errors, autocontinue markers, status, etc. — are intentionally
+// omitted. The primer is a context bridge, not a full transcript replay.
+// TODO: PRIMER_MAX_CHARS is provider-blind; per-provider tuning + telemetry
+// are phase-1 follow-ups.
+export const PRIMER_MAX_CHARS = 60_000
+
+export function shouldInjectPrimer(
+  sessionTokensByProvider: Partial<Record<AgentProvider, string | null>>,
+  targetProvider: AgentProvider,
+  userClearedContext: boolean,
+): boolean {
+  if (userClearedContext) return true
+  return sessionTokensByProvider[targetProvider] == null
+}
+
+interface RenderedEntry {
+  text: string
+  createdAt: number
+}
+
+function renderEntry(entry: TranscriptEntry): RenderedEntry | null {
+  const ts = new Date(entry.createdAt).toISOString().replace("T", " ").slice(0, 19)
+  if (entry.kind === "user_prompt") {
+    return { text: `[user, ${ts}]\n${entry.content}\n`, createdAt: entry.createdAt }
+  }
+  if (entry.kind === "assistant_text") {
+    return { text: `[assistant, ${ts}]\n${entry.text}\n`, createdAt: entry.createdAt }
+  }
+  if (entry.kind === "tool_call") {
+    return { text: `[tool, ${ts}] ${entry.tool.toolName}\n`, createdAt: entry.createdAt }
+  }
+  return null
+}
+
+export function buildHistoryPrimer(
+  entries: TranscriptEntry[],
+  _targetProvider: AgentProvider,
+  userText: string,
+): string | null {
+  const hasAssistant = entries.some((entry) => entry.kind === "assistant_text")
+  if (!hasAssistant) return null
+
+  const rendered = entries
+    .map(renderEntry)
+    .filter((entry): entry is RenderedEntry => entry !== null)
+
+  const header = "The following is the prior conversation in this chat. The first part is context only; the actual request follows after the marker line.\n\n--- BEGIN PRIOR CONVERSATION ---\n"
+  const footer = "--- END PRIOR CONVERSATION ---\n\n"
+  const overhead = header.length + footer.length + userText.length
+  const budget = Math.max(0, PRIMER_MAX_CHARS - overhead)
+
+  const selected: RenderedEntry[] = []
+  let used = 0
+  let truncated = false
+  for (let i = rendered.length - 1; i >= 0; i -= 1) {
+    const candidate = rendered[i]
+    if (used + candidate.text.length > budget) {
+      truncated = i > 0 || selected.length === 0 ? true : truncated
+      break
+    }
+    selected.unshift(candidate)
+    used += candidate.text.length
+  }
+
+  const truncMarker = truncated ? "[... earlier conversation omitted ...]\n" : ""
+  return `${header}${truncMarker}${selected.map((entry) => entry.text).join("")}${footer}${userText}`
+}
+
+export function extractPreviousAssistantReply(entries: TranscriptEntry[]): string | null {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i]
+    if (entry.kind === "assistant_text") return entry.text
+  }
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i]
+    if (entry.kind !== "tool_call") continue
+    const tool = entry.tool
+    const input = (tool as { input?: unknown }).input
+    const cmd = input && typeof input === "object" && "command" in (input as Record<string, unknown>)
+      ? (input as { command?: string }).command ?? ""
+      : ""
+    const suffix = cmd ? `: ${cmd}` : ""
+    return `${tool.toolName}${suffix}`.trim()
+  }
+  return null
+}

package/src/server/claude-pty-mcp/http-server.adapter.ts

@@ -0,0 +1,33 @@
+import http from "node:http"
+import type { AddressInfo } from "node:net"
+
+export type HttpRequestHandler = (req: http.IncomingMessage, res: http.ServerResponse) => void
+
+export interface HttpServerHandle {
+  port: number
+  close: () => Promise<void>
+}
+
+export function createHttpServer(handler: HttpRequestHandler) {
+  return http.createServer(handler)
+}
+
+export function listen(server: http.Server, port: number, host: string): Promise<AddressInfo> {
+  return new Promise<AddressInfo>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, host, () => {
+      server.off("error", reject)
+      resolve(server.address() as AddressInfo)
+    })
+  })
+}
+
+export function closeHttpServer(server: http.Server): Promise<void> {
+  return new Promise<void>((resolve) => {
+    server.close(() => resolve())
+  })
+}
+
+export type HttpServer = http.Server
+export type HttpIncomingMessage = http.IncomingMessage
+export type HttpServerResponse = http.ServerResponse

package/src/server/claude-pty-mcp/mcp-http.ts

@@ -0,0 +1,177 @@
+import { randomBytes, randomUUID } from "node:crypto"
+import { closeHttpServer, createHttpServer, listen, type HttpIncomingMessage } from "./http-server.adapter"
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+import type { SdkMcpToolDefinition } from "@anthropic-ai/claude-agent-sdk"
+import { KANNA_MCP_SERVER_NAME } from "../../shared/tools"
+import { buildKannaMcpTools, type KannaMcpArgs } from "./mcp"
+import type { McpServerConfig } from "../../shared/types"
+
+export interface KannaMcpHttpHandle {
+  /** Full URL including path the claude CLI must POST/GET against. */
+  url: string
+  /** Bearer token the CLI must present in Authorization header. */
+  bearerToken: string
+  /** Tear down HTTP listener + MCP transport. Idempotent. */
+  close: () => Promise<void>
+}
+
+export interface StartKannaMcpHttpServerOptions {
+  args: KannaMcpArgs
+  /** Override host. Defaults to 127.0.0.1 (loopback-only). */
+  host?: string
+  /** Optional fixed port for tests. 0 = pick ephemeral. Defaults to 0. */
+  port?: number
+}
+
+/**
+ * Starts an in-process HTTP MCP server bound to loopback. The claude CLI
+ * subprocess (PTY driver) reaches kanna's tool-callback / tunnel-gateway /
+ * permission-policy state by connecting over HTTP. Bearer token in
+ * Authorization header gates each request — random per spawn, never reused.
+ *
+ * Loopback-only bind by design: tokens live in process memory and the
+ * --mcp-config JSON passed to the CLI; both are scoped to this machine.
+ */
+export async function startKannaMcpHttpServer(
+  opts: StartKannaMcpHttpServerOptions,
+): Promise<KannaMcpHttpHandle> {
+  const bearerToken = randomBytes(32).toString("hex")
+  const host = opts.host ?? "127.0.0.1"
+  const port = opts.port ?? 0
+
+  const mcp = new McpServer({
+    name: KANNA_MCP_SERVER_NAME,
+    version: "1.0.0",
+  })
+
+  const tools = buildKannaMcpTools(opts.args)
+  for (const def of tools) {
+    registerToolOnMcpServer(mcp, def)
+  }
+
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+  })
+  await mcp.connect(transport)
+
+  const httpServer = createHttpServer((req, res) => {
+    if (!authorize(req, bearerToken)) {
+      res.statusCode = 401
+      res.setHeader("WWW-Authenticate", "Bearer")
+      res.end("unauthorized")
+      return
+    }
+    void transport.handleRequest(req, res).catch((err) => {
+      if (!res.headersSent) {
+        res.statusCode = 500
+        res.end(String(err))
+      }
+    })
+  })
+
+  let address
+  try {
+    address = await listen(httpServer, port, host)
+  } catch (err) {
+    try { await transport.close() } catch { /* swallow */ }
+    throw err
+  }
+
+  const url = `http://${host}:${address.port}/mcp`
+
+  let closed = false
+  const close = async (): Promise<void> => {
+    if (closed) return
+    closed = true
+    try {
+      await transport.close()
+    } catch {
+      /* swallow */
+    }
+    await closeHttpServer(httpServer)
+  }
+
+  return { url, bearerToken, close }
+}
+
+function authorize(req: HttpIncomingMessage, bearerToken: string): boolean {
+  const header = req.headers.authorization
+  if (!header || typeof header !== "string") return false
+  const prefix = "Bearer "
+  if (!header.startsWith(prefix)) return false
+  const supplied = header.slice(prefix.length).trim()
+  return constantTimeEqual(supplied, bearerToken)
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let mismatch = 0
+  for (let i = 0; i < a.length; i++) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  }
+  return mismatch === 0
+}
+
+function registerToolOnMcpServer(
+  mcp: McpServer,
+  def: SdkMcpToolDefinition,
+): void {
+  mcp.registerTool(
+    def.name,
+    {
+      description: def.description,
+      inputSchema: def.inputSchema,
+    },
+    async (input: unknown, extra: unknown) => {
+      return await def.handler(input as never, extra)
+    },
+  )
+}
+
+/**
+ * Builds the --mcp-config JSON string the PTY driver passes to the claude
+ * CLI. Encodes the HTTP MCP server URL + bearer token under the kanna
+ * server name so the model sees tools as `mcp__kanna__<name>`.
+ *
+ * Optional `userServers` merges enabled user-configured MCP entries into
+ * the JSON. Disabled entries and any whose name collides with
+ * KANNA_MCP_SERVER_NAME are silently dropped.
+ */
+export function buildMcpConfigJson(
+  handle: { url: string; bearerToken: string },
+  userServers: readonly McpServerConfig[] = [],
+): string {
+  const mcpServers: Record<string, unknown> = {
+    [KANNA_MCP_SERVER_NAME]: {
+      type: "http",
+      url: handle.url,
+      headers: {
+        Authorization: `Bearer ${handle.bearerToken}`,
+      },
+    },
+  }
+  for (const s of userServers) {
+    if (!s.enabled) continue
+    if (s.name === KANNA_MCP_SERVER_NAME) continue
+    mcpServers[s.name] = toClaudeCliMcpEntry(s)
+  }
+  return JSON.stringify({ mcpServers })
+}
+
+function toClaudeCliMcpEntry(s: McpServerConfig): Record<string, unknown> {
+  if (s.transport === "stdio") {
+    return {
+      type: "stdio",
+      command: s.command,
+      args: s.args,
+      env: s.env,
+      ...(s.cwd ? { cwd: s.cwd } : {}),
+    }
+  }
+  return {
+    type: s.transport,
+    url: s.url,
+    headers: s.headers,
+  }
+}