airaknit 1.1.2-rc.9

package/src/server/claude-pty/parity-matrix.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtemp, rm, writeFile, appendFile, mkdir } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import type { Query } from "@anthropic-ai/claude-agent-sdk"
+import { createClaudeHarnessStream } from "./agent-normalizers"
+import { createJsonlEventParser } from "./jsonl-to-event"
+import { startTranscriptStream } from "./tui-source.adapter"
+import type { HarnessEvent } from "../harness-types"
+
+/**
+ * Phase 6 — SDK ↔ PTY HarnessEvent equivalence matrix.
+ *
+ * Drives both paths with the same Claude-SDK message fixtures and
+ * asserts they emit the same `HarnessEvent` sequence (after stripping
+ * volatile fields like `_id` and `createdAt`). The claude CLI mirrors
+ * SDKMessage shapes into the JSONL transcript verbatim, so a single
+ * fixture stands in for both:
+ * - SDK path: yielded from a fake `Query` iterable into
+ *   `createClaudeHarnessStream`.
+ * - PTY path: serialized to JSON and fed to `createJsonlEventParser`
+ *   one line per message.
+ */
+
+function fakeQuery(messages: unknown[]): Query {
+  const q = (async function* () {
+    for (const m of messages) yield m as never
+  })()
+  return q as unknown as Query
+}
+
+function normalize(events: HarnessEvent[]): unknown[] {
+  return events.map((ev) => {
+    if (ev.type === "transcript") {
+      const { _id: _i, createdAt: _c, ...rest } = ev.entry as unknown as Record<string, unknown> & {
+        _id?: string
+        createdAt?: number
+      }
+      return { type: ev.type, entry: rest }
+    }
+    return ev
+  })
+}
+
+async function collectSdk(messages: unknown[], configuredContextWindow?: number): Promise<HarnessEvent[]> {
+  const events: HarnessEvent[] = []
+  for await (const ev of createClaudeHarnessStream(fakeQuery(messages), configuredContextWindow)) {
+    events.push(ev)
+  }
+  return events
+}
+
+async function ptyEventsViaTranscriptStream(messages: unknown[], configuredContextWindow?: number): Promise<HarnessEvent[]> {
+  const tmpDir = await mkdtemp(path.join(tmpdir(), "kanna-parity-"))
+  const projectDir = path.join(tmpDir, "projects", "fake")
+  await mkdir(projectDir, { recursive: true })
+  const filePath = path.join(projectDir, "fixture.jsonl")
+  await writeFile(filePath, "")
+  const stream = await startTranscriptStream({ projectDir, knownFilePath: filePath, firstFileTimeoutMs: 2000 })
+  const parser = createJsonlEventParser({ configuredContextWindow })
+  const events: HarnessEvent[] = []
+  const writeAll = (async () => {
+    for (const m of messages) {
+      await appendFile(filePath, JSON.stringify(m) + "\n")
+      await new Promise<void>((r) => setTimeout(r, 30))
+    }
+    await appendFile(filePath, '{"type":"__parity_sentinel__"}\n')
+  })()
+  const collectDone = (async () => {
+    for await (const line of stream.lines) {
+      let parsed: { type?: string }
+      try { parsed = JSON.parse(line) as { type?: string } } catch { continue }
+      if (parsed.type === "__parity_sentinel__") break
+      for (const ev of parser.parse(line)) events.push(ev)
+    }
+  })()
+  await writeAll
+  await collectDone
+  stream.close()
+  await rm(tmpDir, { recursive: true, force: true })
+  return events
+}
+
+async function assertSameEvents(messages: unknown[], configuredContextWindow?: number): Promise<void> {
+  const sdk = await collectSdk(messages, configuredContextWindow)
+  const pty = await ptyEventsViaTranscriptStream(messages, configuredContextWindow)
+  expect(normalize(pty)).toEqual(normalize(sdk))
+}
+
+describe("SDK ↔ PTY HarnessEvent equivalence matrix", () => {
+  test("simple turn: system/init → assistant → result", async () => {
+    await assertSameEvents([
+      {
+        type: "system",
+        subtype: "init",
+        session_id: "sess-1",
+        model: "claude-sonnet-4-6",
+        tools: [],
+        mcp_servers: [],
+        slash_commands: [],
+        cwd: "/tmp",
+        permissionMode: "acceptEdits",
+        apiKeySource: "none",
+        claude_code_version: "0.0.0",
+        output_style: "default",
+        skills: [],
+        plugins: [],
+        uuid: "u1",
+      },
+      {
+        type: "assistant",
+        session_id: "sess-1",
+        message: {
+          id: "msg-1",
+          role: "assistant",
+          content: [{ type: "text", text: "hi" }],
+        },
+        usage: { input_tokens: 100, output_tokens: 25 },
+        uuid: "u2",
+      },
+      {
+        type: "result",
+        subtype: "success",
+        session_id: "sess-1",
+        result: "done",
+        is_error: false,
+        duration_ms: 500,
+        usage: { input_tokens: 100, output_tokens: 25 },
+        modelUsage: { "claude-sonnet-4-6": { contextWindow: 200000 } },
+        uuid: "u3",
+      },
+    ])
+  })
+
+  test("rate_limit_event (SDK-native shape)", async () => {
+    await assertSameEvents([
+      {
+        type: "rate_limit_event",
+        session_id: "sess-rl",
+        rate_limit_info: { status: "rejected", resetsAt: 1_748_800_000 },
+      },
+    ])
+  })
+
+  test("prompt-too-long error result", async () => {
+    await assertSameEvents([
+      {
+        type: "result",
+        subtype: "error",
+        session_id: "sess-err",
+        is_error: true,
+        result: "prompt is too long",
+        duration_ms: 0,
+        uuid: "u-err",
+      },
+    ])
+  })
+
+  test("multiple assistant messages dedupe on usage id (same id seen twice)", async () => {
+    await assertSameEvents([
+      {
+        type: "assistant",
+        session_id: "sess-d",
+        message: { id: "dup", role: "assistant", content: [{ type: "text", text: "a" }] },
+        usage: { input_tokens: 10, output_tokens: 3 },
+      },
+      {
+        type: "assistant",
+        session_id: "sess-d",
+        message: { id: "dup", role: "assistant", content: [{ type: "text", text: "a" }] },
+        usage: { input_tokens: 10, output_tokens: 3 },
+      },
+    ])
+  })
+
+  test("1M context window floor preserved against modelUsage.contextWindow=200k", async () => {
+    await assertSameEvents(
+      [
+        {
+          type: "assistant",
+          session_id: "sess-1m",
+          message: { id: "msg-1m", role: "assistant", content: [{ type: "text", text: "x" }] },
+          usage: { input_tokens: 100, output_tokens: 50 },
+        },
+        {
+          type: "result",
+          subtype: "success",
+          session_id: "sess-1m",
+          is_error: false,
+          duration_ms: 500,
+          usage: { input_tokens: 100, output_tokens: 50 },
+          modelUsage: { "claude-sonnet-4-6": { contextWindow: 200000 } },
+        },
+      ],
+      1_000_000,
+    )
+  })
+
+  test("session_token emitted from every message carrying session_id", async () => {
+    await assertSameEvents([
+      { type: "system", subtype: "init", session_id: "a", model: "m", tools: [], mcp_servers: [], slash_commands: [], cwd: "/", permissionMode: "acceptEdits", apiKeySource: "none", claude_code_version: "0", output_style: "d", skills: [], plugins: [], uuid: "1" },
+      { type: "assistant", session_id: "a", message: { id: "m1", role: "assistant", content: [] } },
+      { type: "result", subtype: "success", session_id: "a", is_error: false, duration_ms: 0, uuid: "r" },
+    ])
+  })
+
+  test("compact_boundary turn does not produce phantom context_window_updated", async () => {
+    await assertSameEvents([
+      {
+        type: "system",
+        subtype: "compact_boundary",
+        session_id: "sess-c",
+        compact_metadata: { trigger: "auto", pre_tokens: 50000 },
+        uuid: "cb",
+      },
+      {
+        type: "result",
+        subtype: "success",
+        session_id: "sess-c",
+        is_error: false,
+        duration_ms: 100,
+        usage: { input_tokens: 1000, cache_read_input_tokens: 49000, output_tokens: 0 },
+        uuid: "r-c",
+      },
+    ])
+  })
+})

package/src/server/claude-pty/pid-registry.adapter.ts

@@ -0,0 +1,135 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import path from "node:path"
+import process from "node:process"
+
+/**
+ * On-disk registry of claude PTY children so a non-graceful server crash
+ * does not leak orphan claude processes (Bun.Terminal allocates a PTY via
+ * `setsid`, so the child lives in its own session and survives parent
+ * death). On the next server boot `reapStale()` SIGKILLs each recorded
+ * process group and removes its runtimeDir (mcp-config.json + settings).
+ *
+ * Mirrors {@link import("../terminal-pid-registry").TerminalPidRegistry}
+ * but adds `runtimeDir` so we can clean up the tmp dir kanna allocated
+ * for the spawn (otherwise it leaks every restart).
+ */
+export interface ClaudePtyEntry {
+  chatId: string
+  sessionId: string
+  pid: number
+  cwd: string
+  runtimeDir: string
+  createdAt: number
+}
+
+interface RegistryFile {
+  entries: ClaudePtyEntry[]
+}
+
+export class ClaudePtyRegistry {
+  private readonly filePath: string
+  private entries: ClaudePtyEntry[] = []
+  private loaded = false
+  private writeQueue: Promise<void> = Promise.resolve()
+
+  constructor(filePath: string) {
+    this.filePath = filePath
+  }
+
+  async register(entry: Omit<ClaudePtyEntry, "createdAt">): Promise<void> {
+    await this.loadIfNeeded()
+    const next = this.entries.filter((existing) => existing.sessionId !== entry.sessionId)
+    next.push({ ...entry, createdAt: Date.now() })
+    this.entries = next
+    await this.persist()
+  }
+
+  async unregister(sessionId: string): Promise<void> {
+    await this.loadIfNeeded()
+    this.entries = this.entries.filter((entry) => entry.sessionId !== sessionId)
+    await this.persist()
+  }
+
+  async reapStale(): Promise<ClaudePtyEntry[]> {
+    const stored = await this.readFromDisk()
+    if (stored.length === 0) {
+      this.entries = []
+      this.loaded = true
+      return []
+    }
+    for (const entry of stored) {
+      killPgroup(entry.pid)
+      // Best-effort: remove the spawn's runtimeDir (mcp-config.json +
+      // settings.local.json + any other kanna-side scratch). Children
+      // wrote nothing user-facing here, but the dir leaks per restart
+      // without cleanup.
+      if (entry.runtimeDir && entry.runtimeDir.length > 0) {
+        try { await rm(entry.runtimeDir, { recursive: true, force: true }) } catch {
+          /* swallow — best-effort */
+        }
+      }
+    }
+    this.entries = []
+    this.loaded = true
+    await this.persist()
+    return stored
+  }
+
+  private async loadIfNeeded() {
+    if (this.loaded) return
+    this.entries = await this.readFromDisk()
+    this.loaded = true
+  }
+
+  private async readFromDisk(): Promise<ClaudePtyEntry[]> {
+    let raw: string
+    try {
+      raw = await readFile(this.filePath, "utf8")
+    } catch {
+      return []
+    }
+    try {
+      const parsed = JSON.parse(raw) as Partial<RegistryFile>
+      if (!parsed || !Array.isArray(parsed.entries)) return []
+      return parsed.entries.filter(isValidEntry)
+    } catch {
+      return []
+    }
+  }
+
+  private async persist() {
+    const snapshot: RegistryFile = { entries: [...this.entries] }
+    const serialized = JSON.stringify(snapshot)
+    this.writeQueue = this.writeQueue
+      .catch(() => undefined)
+      .then(async () => {
+        await mkdir(path.dirname(this.filePath), { recursive: true })
+        await writeFile(this.filePath, serialized, "utf8")
+      })
+    await this.writeQueue
+  }
+}
+
+function isValidEntry(value: unknown): value is ClaudePtyEntry {
+  if (!value || typeof value !== "object") return false
+  const candidate = value as Partial<ClaudePtyEntry>
+  return (
+    typeof candidate.chatId === "string"
+    && typeof candidate.sessionId === "string"
+    && typeof candidate.pid === "number"
+    && Number.isFinite(candidate.pid)
+    && typeof candidate.cwd === "string"
+    && typeof candidate.runtimeDir === "string"
+    && typeof candidate.createdAt === "number"
+  )
+}
+
+export function killPgroup(pid: number) {
+  if (process.platform === "win32") return
+  if (!Number.isFinite(pid) || pid <= 0) return
+  try {
+    process.kill(-pid, "SIGKILL")
+  } catch {
+    // ESRCH (already gone) and EPERM (race with kernel reap) are fine.
+  }
+}

package/src/server/claude-pty/pid-registry.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdtemp, readFile, rm, writeFile, mkdir, stat } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { ClaudePtyRegistry } from "./pid-registry.adapter"
+
+let tempDir = ""
+let registryPath = ""
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(path.join(os.tmpdir(), "kanna-claude-pty-registry-"))
+  registryPath = path.join(tempDir, "claude-pty.json")
+})
+
+afterEach(async () => {
+  if (tempDir) {
+    await rm(tempDir, { recursive: true, force: true })
+  }
+})
+
+describe("ClaudePtyRegistry", () => {
+  test("register persists entries with sessionId, pid, cwd, runtimeDir", async () => {
+    const registry = new ClaudePtyRegistry(registryPath)
+    await registry.register({ chatId: "c1", sessionId: "s1", pid: 12345, cwd: "/tmp/a", runtimeDir: "/tmp/r1" })
+    await registry.register({ chatId: "c2", sessionId: "s2", pid: 23456, cwd: "/tmp/b", runtimeDir: "/tmp/r2" })
+
+    const raw = JSON.parse(await readFile(registryPath, "utf8")) as {
+      entries: Array<{ chatId: string; sessionId: string; pid: number; runtimeDir: string }>
+    }
+    expect(raw.entries).toHaveLength(2)
+    expect(raw.entries[0]).toMatchObject({ chatId: "c1", sessionId: "s1", pid: 12345, cwd: "/tmp/a", runtimeDir: "/tmp/r1" })
+    expect(raw.entries[1]).toMatchObject({ chatId: "c2", sessionId: "s2", pid: 23456, cwd: "/tmp/b", runtimeDir: "/tmp/r2" })
+  })
+
+  test("re-registering the same sessionId replaces the prior entry", async () => {
+    const registry = new ClaudePtyRegistry(registryPath)
+    await registry.register({ chatId: "c1", sessionId: "s1", pid: 100, cwd: "/tmp/old", runtimeDir: "/tmp/r-old" })
+    await registry.register({ chatId: "c1", sessionId: "s1", pid: 200, cwd: "/tmp/new", runtimeDir: "/tmp/r-new" })
+
+    const raw = JSON.parse(await readFile(registryPath, "utf8")) as { entries: Array<{ pid: number }> }
+    expect(raw.entries).toHaveLength(1)
+    expect(raw.entries[0]?.pid).toBe(200)
+  })
+
+  test("unregister removes only the matching sessionId", async () => {
+    const registry = new ClaudePtyRegistry(registryPath)
+    await registry.register({ chatId: "c1", sessionId: "s1", pid: 1, cwd: "/tmp/a", runtimeDir: "/tmp/r1" })
+    await registry.register({ chatId: "c2", sessionId: "s2", pid: 2, cwd: "/tmp/b", runtimeDir: "/tmp/r2" })
+    await registry.unregister("s1")
+
+    const raw = JSON.parse(await readFile(registryPath, "utf8")) as { entries: Array<{ sessionId: string }> }
+    expect(raw.entries).toHaveLength(1)
+    expect(raw.entries[0]?.sessionId).toBe("s2")
+  })
+
+  test("reapStale kills live process groups, removes runtimeDirs, and clears the file", async () => {
+    const child = Bun.spawn(
+      ["python3", "-c", "import os, sys, time; os.setsid(); sys.stdout.write('ready\\n'); sys.stdout.flush(); time.sleep(60)"],
+      { stdout: "pipe", stderr: "ignore", stdin: "ignore" },
+    )
+    const reader = child.stdout.getReader()
+    const decoded = new TextDecoder().decode((await reader.read()).value ?? new Uint8Array())
+    expect(decoded).toContain("ready")
+    reader.releaseLock()
+    const childPid = child.pid
+
+    const runtimeDir = path.join(tempDir, "spawn-runtime")
+    await mkdir(runtimeDir, { recursive: true })
+    await writeFile(path.join(runtimeDir, "mcp-config.json"), "{}", "utf8")
+
+    await writeFile(
+      registryPath,
+      JSON.stringify({
+        entries: [
+          { chatId: "c1", sessionId: "s1", pid: childPid, cwd: "/tmp/a", runtimeDir, createdAt: Date.now() },
+          { chatId: "c2", sessionId: "s2", pid: 999_999_999, cwd: "/tmp/b", runtimeDir: "/tmp/nonexistent", createdAt: Date.now() },
+        ],
+      }),
+      "utf8",
+    )
+
+    const registry = new ClaudePtyRegistry(registryPath)
+    const reaped = await registry.reapStale()
+
+    expect(reaped.map((entry) => entry.sessionId).sort()).toEqual(["s1", "s2"])
+
+    const exited = await Promise.race([
+      child.exited,
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 3_000)),
+    ])
+    expect(exited).not.toBe("timeout")
+    expect(child.signalCode).toBe("SIGKILL")
+    void childPid
+
+    // runtimeDir cleaned up
+    await expect(stat(runtimeDir)).rejects.toThrow()
+
+    const raw = JSON.parse(await readFile(registryPath, "utf8")) as { entries: unknown[] }
+    expect(raw.entries).toEqual([])
+  }, 30_000)
+
+  test("reapStale tolerates a missing registry file", async () => {
+    const registry = new ClaudePtyRegistry(registryPath)
+    const reaped = await registry.reapStale()
+    expect(reaped).toEqual([])
+  })
+
+  test("reapStale tolerates a malformed registry file", async () => {
+    await writeFile(registryPath, "not json", "utf8")
+    const registry = new ClaudePtyRegistry(registryPath)
+    const reaped = await registry.reapStale()
+    expect(reaped).toEqual([])
+  })
+
+  test("register creates the parent directory if missing", async () => {
+    const nestedPath = path.join(tempDir, "nested", "deep", "claude-pty.json")
+    const registry = new ClaudePtyRegistry(nestedPath)
+    await registry.register({ chatId: "c1", sessionId: "s1", pid: 1, cwd: "/tmp/a", runtimeDir: "/tmp/r1" })
+    const raw = JSON.parse(await readFile(nestedPath, "utf8")) as { entries: unknown[] }
+    expect(raw.entries).toHaveLength(1)
+  })
+})

package/src/server/claude-pty/preflight/binary-fingerprint.adapter.ts

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto"
+import { open } from "node:fs/promises"
+
+export async function computeBinarySha256(filePath: string): Promise<string> {
+  const fd = await open(filePath, "r")
+  try {
+    const hash = createHash("sha256")
+    const buf = Buffer.alloc(64 * 1024)
+    let pos = 0
+    while (true) {
+      const { bytesRead } = await fd.read(buf, 0, buf.length, pos)
+      if (bytesRead === 0) break
+      hash.update(buf.subarray(0, bytesRead))
+      pos += bytesRead
+    }
+    return hash.digest("hex")
+  } finally {
+    await fd.close()
+  }
+}

package/src/server/claude-pty/preflight/binary-fingerprint.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test"
+import { computeBinarySha256 } from "./binary-fingerprint.adapter"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+
+describe("computeBinarySha256", () => {
+  test("returns 64-char hex sha256 of file contents", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "kanna-binsha-"))
+    try {
+      const f = path.join(dir, "fake-claude")
+      await writeFile(f, "hello", "utf8")
+      const sha = await computeBinarySha256(f)
+      expect(sha).toMatch(/^[0-9a-f]{64}$/)
+    } finally { await rm(dir, { recursive: true, force: true }) }
+  })
+
+  test("identical content → identical sha", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "kanna-binsha-"))
+    try {
+      const a = path.join(dir, "a")
+      const b = path.join(dir, "b")
+      await writeFile(a, "x", "utf8")
+      await writeFile(b, "x", "utf8")
+      expect(await computeBinarySha256(a)).toBe(await computeBinarySha256(b))
+    } finally { await rm(dir, { recursive: true, force: true }) }
+  })
+
+  test("throws when file does not exist", async () => {
+    await expect(computeBinarySha256("/nonexistent/path")).rejects.toThrow()
+  })
+})