airaknit 1.1.2-rc.9

package/src/shared/runner-protocol.test.ts

@@ -0,0 +1,277 @@
+import { describe, test, expect } from "bun:test"
+import {
+  runnerHeartbeatSubject,
+  runnerCmdSubject,
+  runnerEventsSubject,
+  RUNNER_REGISTRY_BUCKET,
+  RUNNER_EVENTS_STREAM,
+  ALL_RUNNER_EVENTS,
+  PROTOCOL_VERSION,
+  SUPPORTED_RANGE,
+  isProtocolSupported,
+  runnerLivenessState,
+  LIVENESS_DEGRADED_MS,
+  LIVENESS_OFFLINE_MS,
+  type RunnerTurnEvent,
+  type StartTurnCommand,
+  type CancelTurnCommand,
+  type RespondToolCommand,
+  type ShutdownCommand,
+  type RunnerRegistration,
+  type RunnerHeartbeat,
+} from "./runner-protocol"
+
+describe("runner protocol subjects", () => {
+  test("heartbeat subject", () => {
+    expect(runnerHeartbeatSubject("r1")).toBe("runtime.runner.heartbeat.r1")
+  })
+
+  test("command subjects", () => {
+    expect(runnerCmdSubject("r1", "start_turn")).toBe("runtime.runner.cmd.r1.start_turn")
+    expect(runnerCmdSubject("r1", "cancel_turn")).toBe("runtime.runner.cmd.r1.cancel_turn")
+    expect(runnerCmdSubject("r1", "respond_tool")).toBe("runtime.runner.cmd.r1.respond_tool")
+    expect(runnerCmdSubject("r1", "shutdown")).toBe("runtime.runner.cmd.r1.shutdown")
+  })
+
+  test("events subject", () => {
+    expect(runnerEventsSubject("chat-123")).toBe("runtime.runner.evt.chat-123")
+  })
+
+  test("registry bucket constant", () => {
+    expect(RUNNER_REGISTRY_BUCKET).toBe("runtime_runner_registry")
+  })
+
+  test("stream constants", () => {
+    expect(RUNNER_EVENTS_STREAM).toBe("KANNA_RUNNER_EVENTS")
+    expect(ALL_RUNNER_EVENTS).toBe("runtime.runner.evt.>")
+  })
+})
+
+// ── PR4 Stage 1 audit: StartTurnCommand secret boundary ─────────────
+
+describe("StartTurnCommand PR4 shape audit", () => {
+  const SECRET_PATTERN = /API_KEY|TOKEN|SECRET|Bearer|sk-/i
+
+  function hasSecretShapedKey(obj: Record<string, string>): boolean {
+    return Object.keys(obj).some((k) => SECRET_PATTERN.test(k))
+  }
+
+  function hasSecretShapedValue(obj: Record<string, string>): boolean {
+    return Object.values(obj).some((v) => SECRET_PATTERN.test(v))
+  }
+
+  test("StartTurnCommand type has no binaryPath field", () => {
+    // This is a type-level check enforced via the shape of a representative command.
+    // If binaryPath were re-introduced, the spread below would surface it.
+    const cmd: StartTurnCommand = {
+      chatId: "c1",
+      provider: "claude",
+      content: "hello",
+      model: "claude-sonnet-4-6",
+      planMode: false,
+      appendUserPrompt: true,
+      workspaceLocalPath: "/tmp/ws",
+      sessionToken: null,
+      chatTitle: "New Chat",
+      existingMessageCount: 0,
+      workspaceId: "p1",
+      extraEnv: { NODE_ENV: "production" },
+    }
+    // Serialise as the server would send it on the wire.
+    const wire = JSON.parse(JSON.stringify(cmd)) as Record<string, unknown>
+    expect("binaryPath" in wire).toBe(false)
+  })
+
+  test("resolveProfileOverrides returns no binaryPath in its shape (env only)", () => {
+    // We represent the server output by constructing the object it would spread.
+    // This mirrors the server calling resolveProfileOverrides and spreading into StartTurnCommand.
+    const profileOverrides: { extraEnv?: Record<string, string> } = {
+      extraEnv: { SOME_TEAM_FLAG: "1" },
+    }
+    const wire = JSON.parse(JSON.stringify(profileOverrides)) as Record<string, unknown>
+    expect("binaryPath" in wire).toBe(false)
+    expect("extraEnv" in wire).toBe(true)
+  })
+
+  test("extraEnv with no secret-shaped keys passes the audit guard", () => {
+    const safeEnv: Record<string, string> = {
+      NODE_ENV: "production",
+      SOME_TEAM_FLAG: "1",
+      LOG_LEVEL: "info",
+    }
+    expect(hasSecretShapedKey(safeEnv)).toBe(false)
+    expect(hasSecretShapedValue(safeEnv)).toBe(false)
+  })
+
+  test("extraEnv with secret-shaped keys is detected by the audit guard", () => {
+    const leakyEnv: Record<string, string> = {
+      ANTHROPIC_API_KEY: "sk-ant-abc123",
+      NODE_ENV: "production",
+    }
+    expect(hasSecretShapedKey(leakyEnv)).toBe(true)
+  })
+
+  test("extraEnv with Bearer-prefixed value is detected by the audit guard", () => {
+    const leakyEnv: Record<string, string> = {
+      AUTH_HEADER: "Bearer eyJhbGci...",
+    }
+    expect(hasSecretShapedValue(leakyEnv)).toBe(true)
+  })
+
+  test("a representative wire-serialised StartTurnCommand contains no binaryPath and no secret-shaped values", () => {
+    const cmd: StartTurnCommand = {
+      chatId: "c-audit",
+      provider: "codex",
+      content: "implement feature X",
+      model: "gpt-5.4",
+      planMode: false,
+      appendUserPrompt: true,
+      workspaceLocalPath: "/home/user/project",
+      sessionToken: null,
+      chatTitle: "Feature chat",
+      existingMessageCount: 0,
+      workspaceId: "ws-1",
+      extraEnv: { TEAM_FLAG: "on", NODE_ENV: "production" },
+    }
+    const wire = JSON.parse(JSON.stringify(cmd)) as Record<string, unknown>
+
+    expect("binaryPath" in wire).toBe(false)
+
+    const env = wire.extraEnv as Record<string, string> | undefined
+    if (env) {
+      expect(hasSecretShapedKey(env)).toBe(false)
+      expect(hasSecretShapedValue(env)).toBe(false)
+    }
+  })
+})
+
+describe("runner protocol types", () => {
+  test("RunnerTurnEvent discriminated union covers all event types", () => {
+    const events: RunnerTurnEvent[] = [
+      { type: "transcript", chatId: "c1", entry: { _id: "e1", kind: "assistant_text", text: "hi", createdAt: 1 } as any },
+      { type: "session_token", chatId: "c1", sessionToken: "tok" },
+      { type: "status_change", chatId: "c1", status: "running" as any },
+      { type: "pending_tool", chatId: "c1", tool: null },
+      { type: "turn_finished", chatId: "c1" },
+      { type: "turn_failed", chatId: "c1", error: "oops" },
+      { type: "turn_cancelled", chatId: "c1" },
+      { type: "title_generated", chatId: "c1", title: "My Chat" },
+      { type: "plan_mode_set", chatId: "c1", planMode: true },
+      { type: "provider_set", chatId: "c1", provider: "claude" },
+      { type: "context_cleared", chatId: "c1" },
+    ]
+    expect(events).toHaveLength(11)
+    // Verify each type is unique
+    const types = events.map(e => e.type)
+    expect(new Set(types).size).toBe(11)
+  })
+
+  test("StartTurnCommand has required fields", () => {
+    const cmd: StartTurnCommand = {
+      chatId: "c1", provider: "claude", content: "hello",
+      delegatedContext: "Forked parent chat context:\nUser: earlier work",
+      isSpawned: true,
+      model: "claude-sonnet-4-6", planMode: false, appendUserPrompt: true,
+      workspaceLocalPath: "/tmp", sessionToken: null, chatTitle: "New Chat",
+      existingMessageCount: 0, workspaceId: "p1",
+    }
+    expect(cmd.chatId).toBe("c1")
+    expect(cmd.provider).toBe("claude")
+    expect(cmd.delegatedContext).toContain("Forked parent chat context:")
+    expect(cmd.isSpawned).toBe(true)
+  })
+
+  test("CancelTurnCommand has required fields", () => {
+    const cmd: CancelTurnCommand = { chatId: "c1" }
+    expect(cmd.chatId).toBe("c1")
+  })
+
+  test("RespondToolCommand has required fields", () => {
+    const cmd: RespondToolCommand = { chatId: "c1", toolUseId: "t1", result: "approved" }
+    expect(cmd.chatId).toBe("c1")
+    expect(cmd.toolUseId).toBe("t1")
+  })
+
+  test("ShutdownCommand has required fields", () => {
+    const cmd: ShutdownCommand = { reason: "user_requested" }
+    expect(cmd.reason).toBe("user_requested")
+  })
+
+  test("RunnerRegistration has required fields", () => {
+    const reg: RunnerRegistration = {
+      runnerId: "r1", pid: 123, startedAt: Date.now(), providers: ["claude", "codex"],
+      protocolVersion: 1,
+    }
+    expect(reg.runnerId).toBe("r1")
+    expect(reg.protocolVersion).toBe(1)
+  })
+
+  test("RunnerHeartbeat has required fields", () => {
+    const hb: RunnerHeartbeat = {
+      runnerId: "r1", activeChatIds: ["c1", "c2"], ts: Date.now(),
+    }
+    expect(hb.runnerId).toBe("r1")
+    expect(hb.activeChatIds).toHaveLength(2)
+  })
+})
+
+describe("protocol version constants", () => {
+  test("PROTOCOL_VERSION is 1", () => {
+    expect(PROTOCOL_VERSION).toBe(1)
+  })
+
+  test("SUPPORTED_RANGE min=max=PROTOCOL_VERSION", () => {
+    expect(SUPPORTED_RANGE.min).toBe(PROTOCOL_VERSION)
+    expect(SUPPORTED_RANGE.max).toBe(PROTOCOL_VERSION)
+  })
+})
+
+describe("isProtocolSupported", () => {
+  test("returns true for v1 (current)", () => {
+    expect(isProtocolSupported(1)).toBe(true)
+  })
+
+  test("returns false for v0 (below range)", () => {
+    expect(isProtocolSupported(0)).toBe(false)
+  })
+
+  test("returns false for v2 (above range)", () => {
+    expect(isProtocolSupported(2)).toBe(false)
+  })
+
+  test("returns false for negative version", () => {
+    expect(isProtocolSupported(-1)).toBe(false)
+  })
+})
+
+describe("runnerLivenessState", () => {
+  const NOW = 1_000_000
+
+  test("null lastHeartbeatAt → offline", () => {
+    expect(runnerLivenessState(null, NOW)).toBe("offline")
+  })
+
+  test("age=0 → online", () => {
+    expect(runnerLivenessState(NOW, NOW)).toBe("online")
+  })
+
+  test("age=24_999 (just under LIVENESS_DEGRADED_MS) → online", () => {
+    expect(runnerLivenessState(NOW - (LIVENESS_DEGRADED_MS - 1), NOW)).toBe("online")
+  })
+
+  test("age=25_000 (at LIVENESS_DEGRADED_MS) → degraded", () => {
+    expect(runnerLivenessState(NOW - LIVENESS_DEGRADED_MS, NOW)).toBe("degraded")
+  })
+
+  test("age=59_999 (just under LIVENESS_OFFLINE_MS) → degraded", () => {
+    expect(runnerLivenessState(NOW - (LIVENESS_OFFLINE_MS - 1), NOW)).toBe("degraded")
+  })
+
+  test("age=60_000 (at LIVENESS_OFFLINE_MS) → offline", () => {
+    expect(runnerLivenessState(NOW - LIVENESS_OFFLINE_MS, NOW)).toBe("offline")
+  })
+
+  test("age=100_000 (well above LIVENESS_OFFLINE_MS) → offline", () => {
+    expect(runnerLivenessState(NOW - 100_000, NOW)).toBe("offline")
+  })
+})

package/src/shared/runner-protocol.ts

@@ -0,0 +1,210 @@
+import type { AgentProvider, TranscriptEntry, SessionStatus, PendingToolSnapshot } from "./types"
+
+// ── Protocol versioning ──────────────────────────────────────────────
+
+/** Current protocol version emitted by this runner build. */
+export const PROTOCOL_VERSION = 1
+
+/** Server-side supported protocol range. Runners outside [min, max] are incompatible. */
+export const SUPPORTED_RANGE: { min: number; max: number } = { min: 1, max: 1 }
+
+/** Returns true if v is within the supported protocol range. */
+export function isProtocolSupported(v: number): boolean {
+  return v >= SUPPORTED_RANGE.min && v <= SUPPORTED_RANGE.max
+}
+
+// ── Liveness ─────────────────────────────────────────────────────────
+
+/** Age threshold below which a runner is considered online (ms). */
+export const LIVENESS_DEGRADED_MS = 25_000
+
+/** Age threshold at-or-above which a runner is considered offline (ms). */
+export const LIVENESS_OFFLINE_MS = 60_000
+
+export type RunnerLivenessState = "online" | "degraded" | "offline"
+
+/**
+ * Compute liveness state from last heartbeat timestamp and current time.
+ * Pure function — no I/O or side effects.
+ */
+export function runnerLivenessState(
+  lastHeartbeatAt: number | null,
+  now: number,
+): RunnerLivenessState {
+  if (lastHeartbeatAt === null) return "offline"
+  const age = now - lastHeartbeatAt
+  if (age < LIVENESS_DEGRADED_MS) return "online"
+  if (age < LIVENESS_OFFLINE_MS) return "degraded"
+  return "offline"
+}
+
+// ── Subject helpers ──────────────────────────────────────────────────
+
+const PREFIX = "runtime.runner"
+
+export function runnerHeartbeatSubject(runnerId: string): string {
+  return `${PREFIX}.heartbeat.${runnerId}`
+}
+
+export function runnerCmdSubject(runnerId: string, cmd: string): string {
+  return `${PREFIX}.cmd.${runnerId}.${cmd}`
+}
+
+export function runnerEventsSubject(chatId: string): string {
+  return `${PREFIX}.evt.${chatId}`
+}
+
+// ── Constants ────────────────────────────────────────────────────────
+
+/** KV bucket name for runner registration entries */
+export const RUNNER_REGISTRY_BUCKET = "runtime_runner_registry"
+
+/** JetStream stream name for runner turn events */
+export const RUNNER_EVENTS_STREAM = "KANNA_RUNNER_EVENTS"
+
+/** Wildcard: all runner events */
+export const ALL_RUNNER_EVENTS = `${PREFIX}.evt.>`
+
+// ── Command types ────────────────────────────────────────────────────
+
+export interface StartTurnCommand {
+  chatId: string
+  provider: AgentProvider
+  content: string
+  delegatedContext?: string
+  isSpawned?: boolean
+  model: string
+  planMode: boolean
+  appendUserPrompt: boolean
+  workspaceLocalPath: string
+  sessionToken: string | null
+  chatTitle: string
+  existingMessageCount: number
+  workspaceId: string
+  /**
+   * Non-secret team env vars from the provider profile. The runner merges
+   * these with its own process.env (process.env wins on collision). Must
+   * NOT contain secrets (API keys, tokens, OAuth credentials) — secrets are
+   * resolved runner-side from local env and the OAuth pool and never transit
+   * the server↔runner boundary.
+   */
+  extraEnv?: Record<string, string>
+}
+
+export interface CancelTurnCommand {
+  chatId: string
+}
+
+export interface StopChatPtyCommand {
+  chatId: string
+}
+
+export interface RespondToolCommand {
+  chatId: string
+  toolUseId: string
+  result: string
+}
+
+export interface ShutdownCommand {
+  reason: string
+}
+
+// ── Turn event discriminated union ───────────────────────────────────
+
+interface RunnerTurnEventBase {
+  chatId: string
+}
+
+interface TranscriptEvent extends RunnerTurnEventBase {
+  type: "transcript"
+  entry: TranscriptEntry
+}
+
+interface SessionTokenEvent extends RunnerTurnEventBase {
+  type: "session_token"
+  sessionToken: string
+}
+
+interface StatusChangeEvent extends RunnerTurnEventBase {
+  type: "status_change"
+  status: SessionStatus
+}
+
+interface PendingToolEvent extends RunnerTurnEventBase {
+  type: "pending_tool"
+  tool: PendingToolSnapshot | null
+}
+
+interface TurnFinishedEvent extends RunnerTurnEventBase {
+  type: "turn_finished"
+}
+
+interface TurnFailedEvent extends RunnerTurnEventBase {
+  type: "turn_failed"
+  error: string
+}
+
+interface TurnCancelledEvent extends RunnerTurnEventBase {
+  type: "turn_cancelled"
+}
+
+interface TitleGeneratedEvent extends RunnerTurnEventBase {
+  type: "title_generated"
+  title: string
+}
+
+interface PlanModeSetEvent extends RunnerTurnEventBase {
+  type: "plan_mode_set"
+  planMode: boolean
+}
+
+interface ProviderSetEvent extends RunnerTurnEventBase {
+  type: "provider_set"
+  provider: AgentProvider
+}
+
+interface ContextClearedEvent extends RunnerTurnEventBase {
+  type: "context_cleared"
+}
+
+export type RunnerTurnEvent =
+  | TranscriptEvent
+  | SessionTokenEvent
+  | StatusChangeEvent
+  | PendingToolEvent
+  | TurnFinishedEvent
+  | TurnFailedEvent
+  | TurnCancelledEvent
+  | TitleGeneratedEvent
+  | PlanModeSetEvent
+  | ProviderSetEvent
+  | ContextClearedEvent
+
+// ── Registration & heartbeat ─────────────────────────────────────────
+
+export interface RunnerCapabilities {
+  providers: AgentProvider[]
+}
+
+export interface RunnerRegistration {
+  runnerId: string
+  pid: number
+  startedAt: number
+  providers: AgentProvider[]
+  /** Protocol version reported by the runner. Missing → treated as incompatible. */
+  protocolVersion: number
+  /** Optional capability probe (shape only; rich probe added in PR4). */
+  capabilities?: RunnerCapabilities
+  /**
+   * Timestamp (ms since epoch) of the runner's last KV self-write, piggybacked on
+   * the heartbeat loop. Used by the discover path (no live heartbeat subscription)
+   * to judge liveness via runnerLivenessState. Not written by the server.
+   */
+  lastSeenAt?: number
+}
+
+export interface RunnerHeartbeat {
+  runnerId: string
+  activeChatIds: string[]
+  ts: number
+}

package/src/shared/runner-team-types.ts

@@ -0,0 +1,73 @@
+/**
+ * Runner team types (US-RTN).
+ *
+ * Operator-managed, display-only metadata for remote runners:
+ *  - TeamMember: a flat "member" the single operator manages (names only — no
+ *    auth, no accounts, no permissions).
+ *  - RunnerLabel: a human name + optional member assignment, keyed by runnerId.
+ *
+ * Persisted as EventStore events (see events.ts `RunnerTeamEvent`), mirroring
+ * provider profiles. This is intentionally separate from the runner-owned NATS
+ * KV registry (`runtime_runner_registry`), which the runner rewrites on every
+ * heartbeat and would clobber any server-set fields. Routing/eligibility never
+ * reads this data.
+ */
+
+/** A member of the operator's local "team". Names only — not an authenticated user. */
+export interface TeamMember {
+  id: string
+  name: string
+}
+
+/** Human label + member assignment for a single runner. Upserted by runnerId. */
+export interface RunnerLabel {
+  runnerId: string
+  /** Operator-given runner name. null ⇒ UI falls back to the short runnerId. */
+  name: string | null
+  /** Assigned member id, or null when unassigned. */
+  memberId: string | null
+  /** Unix epoch ms of the last label write. */
+  updatedAt: number
+}
+
+/** Stored runner-label record (currently identical to RunnerLabel; kept distinct for parity with ProviderProfileRecord). */
+export type RunnerLabelRecord = RunnerLabel
+
+/** Snapshot broadcast on the `runner-teams` subscription topic. */
+export interface RunnerTeamSnapshot {
+  members: TeamMember[]
+  runners: RunnerLabel[]
+}
+
+/**
+ * Resolve a runner's display name: the operator label when set, else a short
+ * form of the runnerId (last two dash-separated segments). Pure — unit-tested.
+ */
+export function resolveRunnerName(
+  runnerId: string,
+  labels: ReadonlyMap<string, RunnerLabel> | readonly RunnerLabel[],
+): string {
+  const label = Array.isArray(labels)
+    ? labels.find((l) => l.runnerId === runnerId)
+    : (labels as ReadonlyMap<string, RunnerLabel>).get(runnerId)
+  const name = label?.name?.trim()
+  if (name) return name
+  const parts = runnerId.split("-")
+  return parts.length > 1 ? parts.slice(-2).join("-") : runnerId
+}
+
+/** Resolve the member assigned to a runner, or null. Pure. */
+export function resolveRunnerMember(
+  runnerId: string,
+  labels: ReadonlyMap<string, RunnerLabel> | readonly RunnerLabel[],
+  members: ReadonlyMap<string, TeamMember> | readonly TeamMember[],
+): TeamMember | null {
+  const label = Array.isArray(labels)
+    ? labels.find((l) => l.runnerId === runnerId)
+    : (labels as ReadonlyMap<string, RunnerLabel>).get(runnerId)
+  if (!label?.memberId) return null
+  const memberId = label.memberId
+  return Array.isArray(members)
+    ? (members.find((m) => m.id === memberId) ?? null)
+    : ((members as ReadonlyMap<string, TeamMember>).get(memberId) ?? null)
+}

package/src/shared/runtime-types.ts

@@ -0,0 +1,48 @@
+export type RuntimeSource = "managed" | "system"
+
+export interface RuntimeEntry {
+  provider: "claude" | "codex"
+  version: string
+  source: RuntimeSource
+  binaryPath: string
+  installedAt: number
+  packageName: string
+  capabilities?: RuntimeCapabilities
+}
+
+export interface RuntimeHealthStatus {
+  provider: string
+  version: string
+  binaryPath: string
+  status: "healthy" | "degraded" | "unavailable"
+  lastChecked: number
+  error?: string
+  latencyMs: number
+}
+
+export interface DiscoveredModel {
+  value: string
+  displayName: string
+  description: string
+  supportsEffort?: boolean
+  supportedEffortLevels?: string[]
+  supportsAdaptiveThinking?: boolean
+  supportsFastMode?: boolean
+  supportsAutoMode?: boolean
+}
+
+export interface RuntimeCapabilities {
+  models: DiscoveredModel[]
+  probedAt: number
+  runtimeVersion: string
+  error?: string
+}
+
+export interface RuntimeRegistryState {
+  entries: RuntimeEntry[]
+  defaults: Record<string, string>
+}
+
+export interface RuntimeSnapshot {
+  runtimes: (RuntimeEntry & { health: RuntimeHealthStatus })[]
+}

package/src/shared/sandbox-types.ts

@@ -0,0 +1,53 @@
+export type SandboxStatus = "creating" | "running" | "stopped" | "error"
+
+export interface ResourceLimits {
+  cpuShares: number
+  memoryMb: number
+  diskMb: number
+  pidsLimit: number
+}
+
+export const DEFAULT_RESOURCE_LIMITS: ResourceLimits = {
+  cpuShares: 512,
+  memoryMb: 2048,
+  diskMb: 10240,
+  pidsLimit: 256,
+}
+
+export interface SandboxRecord {
+  id: string
+  workspaceId: string
+  containerId: string | null
+  status: SandboxStatus
+  resourceLimits: ResourceLimits
+  natsUrl: string
+  createdAt: number
+  updatedAt: number
+  lastHealthCheck: number | null
+  error: string | null
+}
+
+export interface SandboxHealthReport {
+  sandboxId: string
+  workspaceId: string
+  status: "healthy" | "unhealthy" | "unreachable"
+  uptimeMs: number
+  memoryUsageMb: number
+  cpuPercent: number
+  natsConnected: boolean
+}
+
+export interface ContainerInspect {
+  id: string
+  status: string
+  running: boolean
+  startedAt: string
+  memoryUsage: number
+  cpuPercent: number
+}
+
+export interface SandboxSnapshot {
+  workspaceId: string
+  sandbox: SandboxRecord | null
+  health: SandboxHealthReport | null
+}

package/src/shared/tailwind-build.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test"
+
+const INDEX_CSS_PATH = new URL("../index.css", import.meta.url)
+
+describe("tailwind build entry", () => {
+  test('constrains Tailwind source scanning to the app source tree', async () => {
+    const css = await Bun.file(INDEX_CSS_PATH).text()
+
+    expect(css).toContain('@import "tailwindcss" source(".");')
+    expect(css).not.toContain('@import "tailwindcss";')
+  })
+})