airaknit 1.1.2-rc.9

package/src/nats/nats-daemon-callout.ts

@@ -0,0 +1,194 @@
+/**
+ * NATS daemon — callout mode (Stage A, PR1).
+ *
+ * Spawns the bundled nats-server binary directly (via resolveBinary()) with a
+ * self-generated auth-callout config, discovers the TCP + WS ports from stderr,
+ * starts the CalloutResponder as the auth-service connection, then writes the
+ * JSON handshake to stdout (same shape as nats-daemon.ts so NatsDaemonManager
+ * can parse it).
+ *
+ * Invoked by NatsDaemonManager when NATS_AUTH_MODE=callout.
+ * NOT used in token mode — that path stays in nats-daemon.ts unchanged.
+ */
+
+import { spawn } from "node:child_process"
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { resolveBinary } from "@lagz0ne/nats-embedded"
+import { ensureCalloutKeys } from "./auth-callout/keys"
+import { buildCalloutConfig } from "./auth-callout/callout-config"
+import { CalloutResponder } from "./auth-callout/responder"
+
+const LOG_PREFIX = "[nats-daemon-callout]"
+
+const host = process.env.NATS_HOST ?? "127.0.0.1"
+const port = process.env.NATS_PORT ? Number(process.env.NATS_PORT) : -1
+const wsPort = process.env.NATS_WS_PORT ? Number(process.env.NATS_WS_PORT) : -1
+const storeDir = process.env.NATS_STORE_DIR
+const dataDir = process.env.NATS_DATA_DIR
+// Opt-in localhost-only HTTP monitoring for diagnostics (/connz, /subsz, /varz).
+const monitorPort = process.env.NATS_MONITOR_PORT ? Number(process.env.NATS_MONITOR_PORT) : undefined
+
+if (!dataDir) {
+  console.error(LOG_PREFIX, "NATS_DATA_DIR is required in callout mode (key storage)")
+  process.exit(1)
+}
+
+// ── 1. Ensure signing keys ────────────────────────────────────────────────────
+
+const keys = await ensureCalloutKeys(dataDir)
+console.warn(LOG_PREFIX, `Callout account public key: ${keys.accountPublicKey}`)
+console.warn(LOG_PREFIX, `Auth-service user public key: ${keys.authUserPublicKey}`)
+
+// ── 2. Generate config and write to temp file ─────────────────────────────────
+
+const configContent = buildCalloutConfig({
+  host,
+  port,
+  wsPort,
+  storeDir,
+  monitorPort,
+  accountPublicKey: keys.accountPublicKey,
+  authUserPublicKey: keys.authUserPublicKey,
+})
+
+const configDir = mkdtempSync(join(tmpdir(), "nats-callout-"))
+const configPath = join(configDir, "callout.conf")
+writeFileSync(configPath, configContent)
+
+// ── 3. Spawn binary directly, parse ports from stderr ─────────────────────────
+
+const binaryPath = resolveBinary()
+console.warn(LOG_PREFIX, `Spawning binary: ${binaryPath}`)
+
+const child = spawn(binaryPath, ["-c", configPath], {
+  stdio: ["ignore", "pipe", "pipe"],
+})
+
+interface PortResult {
+  tcpPort: number
+  wsPort: number
+}
+
+const portResult = await new Promise<PortResult>((resolve, reject) => {
+  const timeout = setTimeout(() => {
+    child.kill("SIGKILL")
+    reject(new Error("nats-server (callout mode) did not start within 10s"))
+  }, 10_000)
+
+  child.on("error", (err) => {
+    clearTimeout(timeout)
+    reject(err)
+  })
+
+  child.on("exit", (code) => {
+    clearTimeout(timeout)
+    reject(new Error(`nats-server exited with code ${code} before ready`))
+  })
+
+  let tcpPort: number | null = null
+  let wsPort: number | null = null
+  let buffer = ""
+
+  const onStderr = (chunk: Buffer) => {
+    const text = chunk.toString()
+    buffer += text
+    const lines = buffer.split("\n")
+    buffer = lines.pop() ?? ""
+
+    for (const line of lines) {
+      // "Listening for client connections on host:port"
+      const tcpMatch = line.match(/Listening for client connections on .+:(\d+)/)
+      if (tcpMatch) tcpPort = Number(tcpMatch[1])
+
+      // "Listening for websocket clients on host:port"
+      const wsMatch = line.match(/Listening for websocket clients on .+:(\d+)/)
+      if (wsMatch) wsPort = Number(wsMatch[1])
+
+      if (tcpPort !== null && wsPort !== null) {
+        clearTimeout(timeout)
+        child.removeAllListeners("exit")
+        child.stderr.removeListener("data", onStderr)
+        resolve({ tcpPort, wsPort })
+        return
+      }
+    }
+  }
+
+  child.stderr.on("data", onStderr)
+})
+
+const natsUrl = `nats://${host}:${portResult.tcpPort}`
+const wsUrl = `ws://${host}:${portResult.wsPort}`
+
+// Observability (decision 0012): forward nats-server's own runtime logs onward
+// (to this process's stderr, which the daemon manager pipes into VictoriaLogs).
+// Previously the stderr listener was removed after port parsing and stdout was
+// discarded, hiding the entire NATS layer — slow-consumer drops, per-connection
+// delivery errors, auth violations, and disconnects. Continuously draining also
+// prevents the pipe buffer from backing up.
+function forwardNatsServerOutput(stream: NodeJS.ReadableStream | null): void {
+  if (!stream) return
+  let buf = ""
+  stream.on("data", (chunk: Buffer) => {
+    buf += chunk.toString()
+    const lines = buf.split("\n")
+    buf = lines.pop() ?? ""
+    for (const line of lines) {
+      if (line.trim()) console.warn("[nats-server]", line)
+    }
+  })
+}
+forwardNatsServerOutput(child.stdout)
+forwardNatsServerOutput(child.stderr)
+
+console.warn(LOG_PREFIX, `nats-server ready — url: ${natsUrl}, ws: ${wsUrl}`)
+
+// ── 4. Start the callout responder ────────────────────────────────────────────
+
+const responder = new CalloutResponder({
+  natsUrl,
+  authUserKp: keys.authUserKp,
+  accountKp: keys.accountKp,
+  accountPublicKey: keys.accountPublicKey,
+  accountName: "CALLOUT_ACCOUNT",
+  tokenSecret: keys.tokenSecret,
+})
+
+await responder.start()
+console.warn(LOG_PREFIX, "Callout responder started")
+
+// ── 5. Emit handshake JSON to stdout (same shape as nats-daemon.ts) ───────────
+
+const info = {
+  url: natsUrl,
+  wsUrl,
+  wsPort: portResult.wsPort,
+  pid: process.pid,
+}
+
+process.stdout.write(JSON.stringify(info) + "\n")
+
+// ── 6. Lifecycle ──────────────────────────────────────────────────────────────
+
+async function shutdown(signal: string) {
+  console.warn(LOG_PREFIX, `Received ${signal}, shutting down`)
+  await responder.stop()
+  child.kill("SIGTERM")
+  try {
+    rmSync(configDir, { recursive: true })
+  } catch { /* best-effort */ }
+  process.exit(0)
+}
+
+process.on("SIGTERM", () => void shutdown("SIGTERM"))
+process.on("SIGINT", () => void shutdown("SIGINT"))
+
+// Keep the process alive until nats-server exits.
+await new Promise<void>((resolve) => {
+  child.on("exit", () => resolve())
+})
+
+// Clean up config dir on abnormal exit.
+try { rmSync(configDir, { recursive: true }) } catch { /* best-effort */ }

package/src/nats/nats-daemon.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect, afterEach } from "bun:test"
+import { connect } from "@nats-io/transport-node"
+
+function createDaemonTestEnv(token: string): NodeJS.ProcessEnv {
+  const {
+    NATS_DATA_DIR: _natsDataDir,
+    NATS_URL: _natsUrl,
+    NATS_MODE: _natsMode,
+    NATS_WS_PORT: _natsWsPort,
+    NATS_PORT: _natsPort,
+    NATS_STORE_DIR: _natsStoreDir,
+    NATS_HTTP_PORT: _natsHttpPort,
+    ...spawnEnv
+  } = process.env
+
+  return {
+    ...spawnEnv,
+    NATS_TOKEN: token,
+  }
+}
+
+describe("nats-daemon", () => {
+  let proc: ReturnType<typeof Bun.spawn> | null = null
+
+  afterEach(async () => {
+    if (proc) {
+      proc.kill("SIGTERM")
+      await proc.exited
+      proc = null
+    }
+  })
+
+  test("starts and outputs JSON with url, wsUrl, wsPort, pid", async () => {
+    const token = "test-token-" + Date.now()
+    proc = Bun.spawn(["bun", "run", "src/nats/nats-daemon.ts"], {
+      env: createDaemonTestEnv(token),
+      stdio: ["ignore", "pipe", "inherit"],
+    })
+    const reader = proc.stdout.getReader()
+    const { value } = await reader.read()
+    const info = JSON.parse(new TextDecoder().decode(value))
+    expect(info).toHaveProperty("url")
+    expect(info).toHaveProperty("wsUrl")
+    expect(info).toHaveProperty("wsPort")
+    expect(info).toHaveProperty("pid")
+    expect(typeof info.pid).toBe("number")
+  })
+
+  test("accepts NATS connections with token auth", async () => {
+    const token = "test-token-" + Date.now()
+    proc = Bun.spawn(["bun", "run", "src/nats/nats-daemon.ts"], {
+      env: createDaemonTestEnv(token),
+      stdio: ["ignore", "pipe", "inherit"],
+    })
+    const reader = proc.stdout.getReader()
+    const { value } = await reader.read()
+    const info = JSON.parse(new TextDecoder().decode(value))
+
+    const nc = await connect({ servers: info.url, token })
+    expect(nc).toBeDefined()
+    await nc.drain()
+  })
+
+  test("shuts down cleanly on SIGTERM", async () => {
+    proc = Bun.spawn(["bun", "run", "src/nats/nats-daemon.ts"], {
+      env: createDaemonTestEnv("test"),
+      stdio: ["ignore", "pipe", "inherit"],
+    })
+    const reader = proc.stdout.getReader()
+    await reader.read() // wait for startup
+
+    proc.kill("SIGTERM")
+    const exitCode = await proc.exited
+    expect(exitCode).toBe(0)
+    proc = null // already exited
+  })
+})

package/src/nats/nats-daemon.ts

@@ -0,0 +1,50 @@
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { ensureToken } from "./nats-token"
+
+const LOG_PREFIX = "[nats-daemon]"
+
+const host = process.env.NATS_HOST ?? "127.0.0.1"
+const port = process.env.NATS_PORT ? Number(process.env.NATS_PORT) : -1
+const wsPort = process.env.NATS_WS_PORT ? Number(process.env.NATS_WS_PORT) : undefined
+const httpPort = process.env.NATS_HTTP_PORT ? Number(process.env.NATS_HTTP_PORT) : undefined
+const storeDir = process.env.NATS_STORE_DIR
+const dataDir = process.env.NATS_DATA_DIR
+
+// Token resolution: NATS_DATA_DIR (file-based) > NATS_TOKEN (env) > none
+const token = dataDir
+  ? await ensureToken(dataDir)
+  : process.env.NATS_TOKEN || undefined
+
+const server = await NatsServer.start({
+  host,
+  port,
+  websocket: wsPort ? { port: wsPort, no_tls: true } : true,
+  jetstream: true,
+  ...(httpPort ? { httpPort } : {}),
+  ...(storeDir ? { storeDir } : {}),
+  ...(token ? { token } : {}),
+})
+
+if (!server.wsUrl || !server.wsPort) {
+  console.warn(LOG_PREFIX, "NATS server started without WebSocket support")
+  await server.stop()
+  process.exit(1)
+}
+
+const info = {
+  url: server.url,
+  wsUrl: server.wsUrl,
+  wsPort: server.wsPort,
+  pid: process.pid,
+}
+
+process.stdout.write(JSON.stringify(info) + "\n")
+
+process.on("SIGTERM", async () => {
+  console.warn(LOG_PREFIX, "Received SIGTERM, shutting down")
+  await server.stop()
+  process.exit(0)
+})
+
+// Keep process alive until NATS server exits
+await server.exited

package/src/nats/nats-token.test.ts

@@ -0,0 +1,61 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { ensureToken, readToken } from "./nats-token"
+import { mkdtempSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+describe("nats-token", () => {
+  let dataDir: string
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), "nats-token-test-"))
+  })
+
+  afterEach(() => {
+    rmSync(dataDir, { recursive: true, force: true })
+  })
+
+  describe("ensureToken", () => {
+    test("generates and persists a token when none exists", async () => {
+      const token = await ensureToken(dataDir)
+      expect(token).toBeString()
+      expect(token.length).toBeGreaterThan(20)
+
+      // File should exist now
+      const file = Bun.file(join(dataDir, "nats.token"))
+      expect(await file.exists()).toBe(true)
+      expect((await file.text()).trim()).toBe(token)
+    })
+
+    test("returns existing token on subsequent calls", async () => {
+      const first = await ensureToken(dataDir)
+      const second = await ensureToken(dataDir)
+      expect(second).toBe(first)
+    })
+
+    test("creates data directory if it does not exist", async () => {
+      const nested = join(dataDir, "sub", "deep")
+      const token = await ensureToken(nested)
+      expect(token).toBeString()
+      expect(token.length).toBeGreaterThan(20)
+    })
+  })
+
+  describe("readToken", () => {
+    test("reads token written by ensureToken", async () => {
+      const written = await ensureToken(dataDir)
+      const read = await readToken(dataDir)
+      expect(read).toBe(written)
+    })
+
+    test("throws when token file does not exist", async () => {
+      expect(readToken(dataDir)).rejects.toThrow()
+    })
+
+    test("trims whitespace from token file", async () => {
+      await Bun.write(join(dataDir, "nats.token"), "  my-token-value  \n")
+      const token = await readToken(dataDir)
+      expect(token).toBe("my-token-value")
+    })
+  })
+})

package/src/nats/nats-token.ts

@@ -0,0 +1,59 @@
+import { join } from "node:path"
+import { mkdirSync } from "node:fs"
+
+const TOKEN_FILE = "nats.token"
+
+/** Generate a cryptographically random token string. */
+function generateToken(): string {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  return Buffer.from(bytes).toString("base64url")
+}
+
+/**
+ * Ensure a NATS auth token exists in `dataDir/nats.token`.
+ * If missing, generates one with atomic write (tmp + rename).
+ * Called by the NATS daemon only (single owner).
+ */
+export async function ensureToken(dataDir: string): Promise<string> {
+  const tokenPath = join(dataDir, TOKEN_FILE)
+  const file = Bun.file(tokenPath)
+
+  if (await file.exists()) {
+    const existing = (await file.text()).trim()
+    if (existing.length > 0) return existing
+  }
+
+  mkdirSync(dataDir, { recursive: true })
+
+  const token = generateToken()
+  const tmpPath = `${tokenPath}.tmp.${process.pid}`
+  await Bun.write(tmpPath, token + "\n")
+
+  // Atomic rename — prevents partial reads by other processes
+  const { renameSync } = await import("node:fs")
+  renameSync(tmpPath, tokenPath)
+
+  return token
+}
+
+/**
+ * Read the NATS auth token from `dataDir/nats.token`.
+ * Called by server and runner processes.
+ * Throws if the file does not exist (daemon not started yet).
+ */
+export async function readToken(dataDir: string): Promise<string> {
+  const tokenPath = join(dataDir, TOKEN_FILE)
+  const file = Bun.file(tokenPath)
+
+  if (!(await file.exists())) {
+    throw new Error(`NATS token file not found: ${tokenPath} — is the NATS daemon running?`)
+  }
+
+  const content = (await file.text()).trim()
+  if (content.length === 0) {
+    throw new Error(`NATS token file is empty: ${tokenPath}`)
+  }
+
+  return content
+}

package/src/runner/coordination-mcp-integration.test.ts

@@ -0,0 +1,134 @@
+import { describe, test, expect, afterEach, beforeEach } from "bun:test"
+import { mkdtempSync, rmSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { connect, type NatsConnection } from "@nats-io/transport-node"
+import { EventStore } from "../server/event-store"
+import { registerCommandResponders } from "../server/nats-responders"
+import { NatsCoordinationClient } from "./nats-coordination-client"
+import { createCoordinationMcpServer } from "../server/coordination-mcp"
+
+describe("coordination MCP via runner NATS client", () => {
+  let natsServer: NatsServer
+  let serverNc: NatsConnection
+  let clientNc: NatsConnection
+  let store: EventStore
+  let tmpDir: string
+  let dispose: (() => void) | null = null
+
+  beforeEach(async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), "coord-mcp-int-test-"))
+    natsServer = await NatsServer.start()
+    serverNc = await connect({ servers: natsServer.url })
+    clientNc = await connect({ servers: natsServer.url })
+
+    store = new EventStore(tmpDir)
+    await store.initialize()
+
+    const { dispose: d } = registerCommandResponders({
+      nc: serverNc,
+      store,
+      agent: {
+        send: async () => ({ chatId: "c" }),
+        cancel: async () => {},
+        disposeChat: async () => {},
+        respondTool: async () => {},
+        getActiveStatuses: () => new Map(),
+      } as never,
+      terminals: {
+        createTerminal: () => ({ terminalId: "t1", title: "bash", cwd: "/tmp", shell: "/bin/bash", cols: 80, rows: 24, scrollback: 0, serializedState: "", status: "running", exitCode: null }),
+        write: () => {},
+        resize: () => {},
+        close: () => {},
+        closeByCwd: () => {},
+        getSnapshot: () => null,
+        onEvent: () => () => {},
+      } as never,
+      refreshDiscovery: async () => [],
+      updateManager: null,
+      publisher: {
+        addSubscription: () => {},
+        removeSubscription: () => {},
+        getSnapshot: async () => null,
+        broadcastSnapshots: async () => {},
+        publishChatMessage: () => {},
+        refreshSessions: async () => {},
+        dispose: () => {},
+      } as never,
+      onStateChange: () => {},
+      directoryPolicy: null,
+      repoManager: null,
+      clonePolicy: null,
+    })
+    dispose = d
+    await serverNc.flush()
+  })
+
+  afterEach(async () => {
+    dispose?.()
+    dispose = null
+    await clientNc?.drain()
+    await serverNc?.drain()
+    await natsServer?.stop()
+    rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  test("NatsCoordinationClient can add a todo via NATS and retrieve via getSnapshot", async () => {
+    const project = await store.openProject("/tmp/test-coord-mcp-runner", "Test")
+    const workspaceId = project.id
+
+    const client = new NatsCoordinationClient(clientNc)
+
+    await client.addTodo(workspaceId, "t-1", "Implement feature X", "high", "session-runner")
+
+    // Verify via direct store (server-side truth)
+    const serverSnapshot = await store.state.coordinationByWorkspace.get(workspaceId)
+    expect(serverSnapshot?.todos.get("t-1")?.description).toBe("Implement feature X")
+
+    // Verify via getSnapshot (NATS round-trip)
+    const snapshot = await client.getSnapshot(workspaceId)
+    expect(snapshot.todos).toHaveLength(1)
+    expect(snapshot.todos[0].description).toBe("Implement feature X")
+    expect(snapshot.todos[0].status).toBe("open")
+  })
+
+  test("createCoordinationMcpServer works with NatsCoordinationClient", () => {
+    const client = new NatsCoordinationClient(clientNc)
+    const mcpServer = createCoordinationMcpServer(client)
+    // The MCP server should be defined with tools
+    expect(mcpServer).toBeDefined()
+    expect(typeof mcpServer).toBe("object")
+  })
+
+  test("NatsCoordinationClient full coordination lifecycle via NATS", async () => {
+    const project = await store.openProject("/tmp/test-coord-lifecycle", "Lifecycle")
+    const workspaceId = project.id
+
+    const client = new NatsCoordinationClient(clientNc)
+
+    // Add and claim a todo
+    await client.addTodo(workspaceId, "t-1", "Build feature", "normal", "session-a")
+    await client.claimTodo(workspaceId, "t-1", "session-b")
+
+    let snapshot = await client.getSnapshot(workspaceId)
+    expect(snapshot.todos[0].status).toBe("claimed")
+
+    // Complete the todo
+    await client.completeTodo(workspaceId, "t-1", ["feature.ts"])
+    snapshot = await client.getSnapshot(workspaceId)
+    expect(snapshot.todos[0].status).toBe("complete")
+
+    // Create a file claim
+    await client.createClaim(workspaceId, "c-1", "Refactor auth", ["src/auth.ts"], "session-a")
+    snapshot = await client.getSnapshot(workspaceId)
+    expect(snapshot.claims).toHaveLength(1)
+    expect(snapshot.claims[0].status).toBe("active")
+
+    // Set a rule
+    await client.setRule(workspaceId, "r-1", "No any types", "session-a")
+    snapshot = await client.getSnapshot(workspaceId)
+    expect(snapshot.rules).toHaveLength(1)
+    expect(snapshot.rules[0].content).toBe("No any types")
+  })
+})

package/src/runner/nats-coordination-client.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect, mock } from "bun:test"
+import { NatsCoordinationClient } from "./nats-coordination-client"
+
+describe("NatsCoordinationClient", () => {
+  test("addTodo sends NATS command and returns", async () => {
+    const mockNc = {
+      request: mock(() => Promise.resolve({
+        data: new TextEncoder().encode(JSON.stringify({ ok: true, result: { ok: true } })),
+      })),
+    }
+    const client = new NatsCoordinationClient(mockNc as any)
+
+    await client.addTodo("proj-1", "todo-1", "Fix bug", "normal", "session-1")
+
+    expect(mockNc.request).toHaveBeenCalled()
+    const callArgs = mockNc.request.mock.calls[0]
+    expect(callArgs[0]).toBe("runtime.cmd.workspace.todo.add")
+  })
+
+  test("state.coordinationByWorkspace returns empty map initially", () => {
+    const client = new NatsCoordinationClient({} as any)
+    expect(client.state.coordinationByWorkspace.size).toBe(0)
+  })
+
+  test("throws when server returns error", async () => {
+    const mockNc = {
+      request: mock(() => Promise.resolve({
+        data: new TextEncoder().encode(JSON.stringify({ ok: false, error: "Project not found" })),
+      })),
+    }
+    const client = new NatsCoordinationClient(mockNc as any)
+    await expect(client.addTodo("proj-1", "todo-1", "Fix bug", "normal", "session-1")).rejects.toThrow("Project not found")
+  })
+
+  test("implements CoordinationStore interface", () => {
+    const client = new NatsCoordinationClient({} as any)
+    expect(typeof client.addTodo).toBe("function")
+    expect(typeof client.claimTodo).toBe("function")
+    expect(typeof client.completeTodo).toBe("function")
+    expect(typeof client.abandonTodo).toBe("function")
+    expect(typeof client.createClaim).toBe("function")
+    expect(typeof client.releaseClaim).toBe("function")
+    expect(typeof client.createWorktree).toBe("function")
+    expect(typeof client.assignWorktree).toBe("function")
+    expect(typeof client.removeWorktree).toBe("function")
+    expect(typeof client.setRule).toBe("function")
+    expect(typeof client.removeRule).toBe("function")
+  })
+})