airaknit 1.1.2-rc.9

package/src/server/claude-pty/resolve-binary.adapter.ts

@@ -0,0 +1,106 @@
+import { stat } from "node:fs/promises"
+import path from "node:path"
+import { promisify } from "node:util"
+import { execFile } from "node:child_process"
+
+const execFileAsync = promisify(execFile)
+
+export interface ResolveClaudeBinaryArgs {
+  env: NodeJS.ProcessEnv
+  homeDir: string
+  cwd?: string
+  platform?: NodeJS.Platform
+  arch?: NodeJS.Architecture
+}
+
+export interface ResolveClaudeBinaryResult {
+  path: string
+  source: "env-CLAUDE_EXECUTABLE" | "env-CLAUDE_CODE_EXECPATH" | "PATH" | "node_modules"
+  triedPaths: string[]
+}
+
+function expandTilde(p: string, home: string): string {
+  return p.replace(/^~(?=\/|$)/, home)
+}
+
+async function isExecutableFile(p: string): Promise<boolean> {
+  try {
+    const s = await stat(p)
+    return s.isFile()
+  } catch {
+    return false
+  }
+}
+
+async function whichClaude(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): Promise<string | null> {
+  const cmd = platform === "win32" ? "where" : "which"
+  try {
+    const { stdout } = await execFileAsync(cmd, ["claude"], { env, timeout: 2000 })
+    const first = stdout.split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0)
+    if (!first) return null
+    if (!(await isExecutableFile(first))) return null
+    return first
+  } catch {
+    return null
+  }
+}
+
+function buildNodeModulesCandidates(cwd: string, platform: NodeJS.Platform, arch: NodeJS.Architecture): string[] {
+  const tag = `${platform}-${arch}`
+  const pkgDir = `@anthropic-ai/claude-agent-sdk-${tag}`
+  const candidates: string[] = []
+  let dir = path.resolve(cwd)
+  while (true) {
+    candidates.push(path.join(dir, "node_modules", pkgDir, "claude"))
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return candidates
+}
+
+export async function resolveClaudeBinary(args: ResolveClaudeBinaryArgs): Promise<ResolveClaudeBinaryResult> {
+  const env = args.env
+  const home = args.homeDir
+  const cwd = args.cwd ?? process.cwd()
+  const platform = args.platform ?? process.platform
+  const arch = args.arch ?? process.arch
+  const tried: string[] = []
+
+  if (env.CLAUDE_EXECUTABLE) {
+    const candidate = expandTilde(env.CLAUDE_EXECUTABLE, home)
+    tried.push(`CLAUDE_EXECUTABLE=${candidate}`)
+    if (await isExecutableFile(candidate)) {
+      return { path: candidate, source: "env-CLAUDE_EXECUTABLE", triedPaths: tried }
+    }
+  }
+
+  if (env.CLAUDE_CODE_EXECPATH) {
+    const candidate = expandTilde(env.CLAUDE_CODE_EXECPATH, home)
+    tried.push(`CLAUDE_CODE_EXECPATH=${candidate}`)
+    if (await isExecutableFile(candidate)) {
+      return { path: candidate, source: "env-CLAUDE_CODE_EXECPATH", triedPaths: tried }
+    }
+  }
+
+  const fromPath = await whichClaude(env, platform)
+  tried.push(`PATH lookup: ${fromPath ?? "<not found>"}`)
+  if (fromPath) {
+    return { path: fromPath, source: "PATH", triedPaths: tried }
+  }
+
+  const candidates = buildNodeModulesCandidates(cwd, platform, arch)
+  for (const candidate of candidates) {
+    tried.push(candidate)
+    if (await isExecutableFile(candidate)) {
+      return { path: candidate, source: "node_modules", triedPaths: tried }
+    }
+  }
+
+  throw new Error(
+    `Unable to locate the \`claude\` CLI binary. Set CLAUDE_EXECUTABLE to an absolute path, `
+    + `install \`@anthropic-ai/claude-code\` globally so \`claude\` is on PATH, or install `
+    + `\`@anthropic-ai/claude-agent-sdk\` so the platform-bundled binary exists in node_modules. `
+    + `Tried:\n  - ${tried.join("\n  - ")}`,
+  )
+}

package/src/server/claude-pty/resolve-binary.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { resolveClaudeBinary } from "./resolve-binary.adapter"
+
+describe("resolveClaudeBinary", () => {
+  let workDir: string
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(path.join(tmpdir(), "kanna-resolve-binary-"))
+  })
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true })
+  })
+
+  async function makeExec(p: string): Promise<void> {
+    await mkdir(path.dirname(p), { recursive: true })
+    await writeFile(p, "#!/bin/sh\necho fake\n", { encoding: "utf8" })
+    await chmod(p, 0o755)
+  }
+
+  test("returns CLAUDE_EXECUTABLE when set and exists", async () => {
+    const bin = path.join(workDir, "fake-claude")
+    await makeExec(bin)
+    const result = await resolveClaudeBinary({
+      env: { CLAUDE_EXECUTABLE: bin, PATH: "" },
+      homeDir: workDir,
+      cwd: workDir,
+      platform: "darwin",
+      arch: "arm64",
+    })
+    expect(result.source).toBe("env-CLAUDE_EXECUTABLE")
+    expect(result.path).toBe(bin)
+  })
+
+  test("expands tilde in CLAUDE_EXECUTABLE", async () => {
+    const bin = path.join(workDir, "tilde-claude")
+    await makeExec(bin)
+    const result = await resolveClaudeBinary({
+      env: { CLAUDE_EXECUTABLE: "~/tilde-claude", PATH: "" },
+      homeDir: workDir,
+      cwd: workDir,
+      platform: "darwin",
+      arch: "arm64",
+    })
+    expect(result.path).toBe(bin)
+  })
+
+  test("falls back to CLAUDE_CODE_EXECPATH when CLAUDE_EXECUTABLE missing file", async () => {
+    const bin = path.join(workDir, "execpath-claude")
+    await makeExec(bin)
+    const result = await resolveClaudeBinary({
+      env: {
+        CLAUDE_EXECUTABLE: path.join(workDir, "does-not-exist"),
+        CLAUDE_CODE_EXECPATH: bin,
+        PATH: "",
+      },
+      homeDir: workDir,
+      cwd: workDir,
+      platform: "darwin",
+      arch: "arm64",
+    })
+    expect(result.source).toBe("env-CLAUDE_CODE_EXECPATH")
+    expect(result.path).toBe(bin)
+  })
+
+  test("falls back to node_modules platform-bundled binary", async () => {
+    const inner = path.join(workDir, "nested", "deep")
+    await mkdir(inner, { recursive: true })
+    const bundled = path.join(workDir, "node_modules", "@anthropic-ai", "claude-agent-sdk-darwin-arm64", "claude")
+    await makeExec(bundled)
+    const result = await resolveClaudeBinary({
+      env: { PATH: "" },
+      homeDir: workDir,
+      cwd: inner,
+      platform: "darwin",
+      arch: "arm64",
+    })
+    expect(result.source).toBe("node_modules")
+    expect(result.path).toBe(bundled)
+  })
+
+  test("walks parent dirs when looking up node_modules bundled binary", async () => {
+    const inner = path.join(workDir, "a", "b", "c")
+    await mkdir(inner, { recursive: true })
+    const bundled = path.join(workDir, "node_modules", "@anthropic-ai", "claude-agent-sdk-linux-x64", "claude")
+    await makeExec(bundled)
+    const result = await resolveClaudeBinary({
+      env: { PATH: "" },
+      homeDir: workDir,
+      cwd: inner,
+      platform: "linux",
+      arch: "x64",
+    })
+    expect(result.path).toBe(bundled)
+  })
+
+  test("throws with all tried paths when nothing resolves", async () => {
+    let err: unknown
+    try {
+      await resolveClaudeBinary({
+        env: { CLAUDE_EXECUTABLE: path.join(workDir, "missing"), PATH: "" },
+        homeDir: workDir,
+        cwd: workDir,
+        platform: "darwin",
+        arch: "arm64",
+      })
+    } catch (caught) {
+      err = caught
+    }
+    expect(err).toBeInstanceOf(Error)
+    expect((err as Error).message).toContain("Unable to locate")
+    expect((err as Error).message).toContain("CLAUDE_EXECUTABLE")
+    expect((err as Error).message).toContain("node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64/claude")
+  }, 10_000)
+})

package/src/server/claude-pty/runtime-dir.adapter.ts

@@ -0,0 +1,19 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { tmpdir } from "node:os"
+
+export async function createRuntimeDir(prefix: string): Promise<string> {
+  return await mkdtemp(path.join(tmpdir(), prefix))
+}
+
+export async function writeRuntimeFile(
+  filePath: string,
+  contents: string,
+  options?: { encoding?: BufferEncoding; mode?: number },
+): Promise<void> {
+  await writeFile(filePath, contents, options)
+}
+
+export async function removeRuntimeDir(dir: string): Promise<void> {
+  await rm(dir, { recursive: true, force: true })
+}

package/src/server/claude-pty/settings-writer.adapter.ts

@@ -0,0 +1,27 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+export interface WriteSpawnSettingsResult {
+  settingsPath: string
+}
+
+export async function writeSpawnSettings(args: {
+  runtimeDir: string
+}): Promise<WriteSpawnSettingsResult> {
+  await mkdir(args.runtimeDir, { recursive: true, mode: 0o700 })
+  const settingsPath = path.join(args.runtimeDir, "settings.local.json")
+  const body = {
+    spinnerTipsEnabled: false,
+    showTurnDuration: false,
+    syntaxHighlightingDisabled: true,
+    // Auto-allow every mcp__kanna__* tool at the claude CLI permission gate.
+    // Approval still flows through kanna's toolCallback (durable + auditable)
+    // when KANNA_MCP_TOOL_CALLBACKS=1; this just stops the CLI from blocking
+    // tool_call before our MCP server sees the request.
+    permissions: {
+      allow: ["mcp__kanna__*"],
+    },
+  }
+  await writeFile(settingsPath, JSON.stringify(body, null, 2), { encoding: "utf8", mode: 0o600 })
+  return { settingsPath }
+}

package/src/server/claude-pty/settings-writer.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtemp, rm, readFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { writeSpawnSettings } from "./settings-writer.adapter"
+
+describe("writeSpawnSettings", () => {
+  test("writes per-spawn settings with claimed keys", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "kanna-settings-"))
+    try {
+      const result = await writeSpawnSettings({ runtimeDir: dir })
+      expect(result.settingsPath.startsWith(dir)).toBe(true)
+      const raw = await readFile(result.settingsPath, "utf8")
+      const parsed = JSON.parse(raw)
+      expect(parsed.spinnerTipsEnabled).toBe(false)
+      expect(parsed.showTurnDuration).toBe(false)
+      expect(parsed.permissions?.allow).toContain("mcp__kanna__*")
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/server/claude-pty/smoke-test-io.adapter.ts

@@ -0,0 +1,28 @@
+import { mkdir, mkdtemp, readFile, writeFile, rm } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { tmpdir } from "node:os"
+
+export function makeTempCwd(prefix: string): Promise<string> {
+  return mkdtemp(path.join(tmpdir(), prefix))
+}
+
+export function readTextFile(p: string): Promise<string> {
+  return readFile(p, "utf8")
+}
+
+export async function rmDirRecursive(p: string): Promise<void> {
+  await rm(p, { recursive: true, force: true })
+}
+
+export function fileExists(p: string): boolean {
+  return existsSync(p)
+}
+
+export async function mkdirRecursive(p: string): Promise<void> {
+  await mkdir(p, { recursive: true })
+}
+
+export async function writeFile0600(p: string, contents: string): Promise<void> {
+  await writeFile(p, contents, { encoding: "utf8", mode: 0o600 })
+}

package/src/server/claude-pty/smoke-test.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { createSmokeTestGate, createFileSmokeTestCache, type SmokeTestProbeFn, type SmokeTestCache } from "./smoke-test"
+
+let workHome: string
+
+function inMemoryCache(): SmokeTestCache {
+  const store = new Map<string, { result: "pass" | "fail"; ts: number }>()
+  return {
+    async get(key) { return store.get(key) ?? null },
+    async set(key, entry) { store.set(key, entry) },
+    async invalidate() { store.clear() },
+  }
+}
+
+beforeEach(async () => {
+  workHome = await mkdtemp(path.join(tmpdir(), "kanna-smoke-"))
+  await writeFile(path.join(workHome, "fake-claude"), "#!/bin/sh\necho fake\n", { mode: 0o755 })
+})
+
+afterEach(async () => {
+  await rm(workHome, { recursive: true, force: true })
+})
+
+describe("createSmokeTestGate", () => {
+  test("cached PASS skips probe", async () => {
+    let probeRan = false
+    const probe: SmokeTestProbeFn = async () => { probeRan = true; return "pass" }
+    const cache = inMemoryCache()
+    await cache.set("aaa|claude-opus-4-7", { result: "pass", ts: Date.now() })
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    const result = await gate.canSpawn({ binarySha256: "aaa", model: "claude-opus-4-7" })
+    expect(result.ok).toBe(true)
+    expect(probeRan).toBe(false)
+  })
+
+  test("cached FAIL refuses spawn without running probe", async () => {
+    let probeRan = false
+    const probe: SmokeTestProbeFn = async () => { probeRan = true; return "pass" }
+    const cache = inMemoryCache()
+    await cache.set("bbb|claude-opus-4-7", { result: "fail", ts: Date.now() })
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    const result = await gate.canSpawn({ binarySha256: "bbb", model: "claude-opus-4-7" })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toMatch(/disallowedTools/i)
+    expect(probeRan).toBe(false)
+  })
+
+  test("cache miss runs probe and caches PASS", async () => {
+    let probeRan = false
+    const probe: SmokeTestProbeFn = async () => { probeRan = true; return "pass" }
+    const cache = inMemoryCache()
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    const result = await gate.canSpawn({ binarySha256: "ccc", model: "m1" })
+    expect(result.ok).toBe(true)
+    expect(probeRan).toBe(true)
+    const cached = await cache.get("ccc|m1")
+    expect(cached?.result).toBe("pass")
+  })
+
+  test("cache miss runs probe and refuses spawn on FAIL", async () => {
+    const probe: SmokeTestProbeFn = async () => "fail"
+    const cache = inMemoryCache()
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    const result = await gate.canSpawn({ binarySha256: "ddd", model: "m1" })
+    expect(result.ok).toBe(false)
+    const cached = await cache.get("ddd|m1")
+    expect(cached?.result).toBe("fail")
+  })
+
+  test("probe error is re-thrown and NOT cached (no 24h poisoning)", async () => {
+    let probeRuns = 0
+    const probe: SmokeTestProbeFn = async () => {
+      probeRuns += 1
+      throw new Error("TUI ready timeout")
+    }
+    const cache = inMemoryCache()
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+
+    await expect(gate.canSpawn({ binarySha256: "transient", model: "m1" })).rejects.toThrow("TUI ready timeout")
+    // A transient probe error must leave the cache untouched so the next spawn
+    // re-probes instead of being refused for the full TTL.
+    expect(await cache.get("transient|m1")).toBeNull()
+    await expect(gate.canSpawn({ binarySha256: "transient", model: "m1" })).rejects.toThrow("TUI ready timeout")
+    expect(probeRuns).toBe(2)
+  })
+
+  test("expired cache entry triggers re-probe", async () => {
+    let probeRan = 0
+    const probe: SmokeTestProbeFn = async () => { probeRan++; return "pass" }
+    const cache = inMemoryCache()
+    let nowMs = 1_000_000
+    await cache.set("eee|m1", { result: "pass", ts: nowMs })
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 1000, now: () => nowMs })
+    await gate.canSpawn({ binarySha256: "eee", model: "m1" })
+    expect(probeRan).toBe(0)
+    nowMs += 2000
+    await gate.canSpawn({ binarySha256: "eee", model: "m1" })
+    expect(probeRan).toBe(1)
+  })
+})
+
+describe("createSmokeTestGate singleflight (adr-20260522-oauth-token-share-cap)", () => {
+  test("concurrent canSpawn calls on same (sha,model) collapse to one probe", async () => {
+    let probeStartCount = 0
+    const resolvers: Array<(r: "pass" | "fail") => void> = []
+    const probe: SmokeTestProbeFn = () => {
+      probeStartCount += 1
+      return new Promise<"pass" | "fail">((r) => { resolvers.push(r) })
+    }
+    const cache = inMemoryCache()
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+
+    const results = [
+      gate.canSpawn({ binarySha256: "fff", model: "m1" }),
+      gate.canSpawn({ binarySha256: "fff", model: "m1" }),
+      gate.canSpawn({ binarySha256: "fff", model: "m1" }),
+      gate.canSpawn({ binarySha256: "fff", model: "m1" }),
+      gate.canSpawn({ binarySha256: "fff", model: "m1" }),
+    ]
+    // Give the event loop one tick so each promise registers with inFlight.
+    await Promise.resolve()
+    expect(probeStartCount).toBe(1)
+    expect(resolvers).toHaveLength(1)
+    resolvers[0]("pass")
+    const resolved = await Promise.all(results)
+    for (const r of resolved) expect(r.ok).toBe(true)
+    expect(probeStartCount).toBe(1)
+  })
+
+  test("after a probe resolves, future cache-miss callers run a fresh probe", async () => {
+    let probeStartCount = 0
+    const probe: SmokeTestProbeFn = async () => { probeStartCount += 1; return "pass" }
+    const cache: SmokeTestCache = {
+      // Read-only cache: every get returns null so the gate must probe each time.
+      async get() { return null },
+      async set() { /* discard */ },
+      async invalidate() { /* noop */ },
+    }
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    await gate.canSpawn({ binarySha256: "ggg", model: "m1" })
+    await gate.canSpawn({ binarySha256: "ggg", model: "m1" })
+    // Two sequential cache-miss calls → two probes (singleflight only collapses concurrent ones).
+    expect(probeStartCount).toBe(2)
+  })
+
+  test("singleflight is keyed by (sha,model) — different keys probe independently", async () => {
+    let probeStartCount = 0
+    const resolvers: Array<(r: "pass" | "fail") => void> = []
+    const probe: SmokeTestProbeFn = () => {
+      probeStartCount += 1
+      return new Promise<"pass" | "fail">((r) => { resolvers.push(r) })
+    }
+    const cache = inMemoryCache()
+    const gate = createSmokeTestGate({ probe, cache, ttlMs: 24 * 3600 * 1000, now: () => Date.now() })
+    const a = gate.canSpawn({ binarySha256: "hhh", model: "m1" })
+    const b = gate.canSpawn({ binarySha256: "hhh", model: "m2" })
+    await Promise.resolve()
+    expect(probeStartCount).toBe(2)
+    expect(resolvers).toHaveLength(2)
+    resolvers[0]("pass")
+    resolvers[1]("pass")
+    await Promise.all([a, b])
+  })
+})
+
+describe("createFileSmokeTestCache", () => {
+  test("round-trips an entry through disk", async () => {
+    const dir = path.join(workHome, "smoke-cache")
+    const cache = createFileSmokeTestCache({ cacheDir: dir })
+    await cache.set("abc|m1", { result: "pass", ts: 1234 })
+    const got = await cache.get("abc|m1")
+    expect(got).toEqual({ result: "pass", ts: 1234 })
+  })
+
+  test("returns null on missing key", async () => {
+    const cache = createFileSmokeTestCache({ cacheDir: path.join(workHome, "smoke-cache-2") })
+    const got = await cache.get("missing|m1")
+    expect(got).toBeNull()
+  })
+
+  test("invalidate wipes the dir", async () => {
+    const dir = path.join(workHome, "smoke-cache-3")
+    const cache = createFileSmokeTestCache({ cacheDir: dir })
+    await cache.set("xxx|m", { result: "pass", ts: 1 })
+    await cache.invalidate()
+    expect(await cache.get("xxx|m")).toBeNull()
+  })
+})