airaknit 1.1.2-rc.9

package/src/shared/branding.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test"
+import {
+  APP_NAME,
+  CLI_COMMAND,
+  LOG_PREFIX,
+  PACKAGE_NAME,
+  RUNTIME_PROFILE_ENV_VAR,
+  SDK_CLIENT_APP,
+  getDataDir,
+  getDataDirDisplay,
+  getDataRootName,
+  getCliInvocation,
+  getRuntimeProfile,
+} from "./branding"
+
+describe("runtime profile helpers", () => {
+  test("defaults to the prod profile when unset", () => {
+    expect(APP_NAME).toBe("Tinkaria")
+    expect(CLI_COMMAND).toBe("tinkaria")
+    expect(PACKAGE_NAME).toBe("tinkaria")
+    expect(LOG_PREFIX).toBe("[tinkaria]")
+    expect(SDK_CLIENT_APP).toStartWith("tinkaria/")
+    expect(getCliInvocation("--port 4000")).toBe("tinkaria --port 4000")
+    expect(getRuntimeProfile({})).toBe("prod")
+    expect(getDataRootName({})).toBe(".tinkaria")
+    expect(getDataDir("/tmp/home", {})).toBe("/tmp/home/.tinkaria/data")
+    expect(getDataDirDisplay({})).toBe("~/.tinkaria/data")
+  })
+
+  test("switches to dev paths for the dev profile", () => {
+    const env = { [RUNTIME_PROFILE_ENV_VAR]: "dev" }
+
+    expect(getRuntimeProfile(env)).toBe("dev")
+    expect(getDataRootName(env)).toBe(".tinkaria-dev")
+    expect(getDataDir("/tmp/home", env)).toBe("/tmp/home/.tinkaria-dev/data")
+    expect(getDataDirDisplay(env)).toBe("~/.tinkaria-dev/data")
+  })
+
+  test("still honors the legacy runtime profile environment variable for compatibility", () => {
+    expect(getRuntimeProfile({ KANNA_RUNTIME_PROFILE: "dev" })).toBe("dev")
+  })
+})

package/src/shared/branding.ts

@@ -0,0 +1,54 @@
+export const APP_NAME = "Tinkaria"
+export const CLI_COMMAND = "tinkaria"
+export const DATA_ROOT_NAME = ".tinkaria"
+export const DEV_DATA_ROOT_NAME = ".tinkaria-dev"
+export const PACKAGE_NAME = "tinkaria"
+export const RUNTIME_PROFILE_ENV_VAR = "TINKARIA_RUNTIME_PROFILE"
+export const LEGACY_RUNTIME_PROFILE_ENV_VAR = "KANNA_RUNTIME_PROFILE"
+// Read version from package.json — JSON import works in both Bun and Vite
+import pkg from "../../package.json"
+export const SDK_CLIENT_APP = `tinkaria/${pkg.version}`
+export const LOG_PREFIX = "[tinkaria]"
+export const DEFAULT_NEW_PROJECT_ROOT = `~/${APP_NAME}`
+
+export type RuntimeProfile = "dev" | "prod"
+
+type RuntimeEnv = Record<string, string | undefined> | undefined
+
+function getRuntimeEnv(): RuntimeEnv {
+  const candidate = globalThis as typeof globalThis & {
+    process?: {
+      env?: Record<string, string | undefined>
+    }
+  }
+  return candidate.process?.env
+}
+
+export function getRuntimeProfile(env: RuntimeEnv = getRuntimeEnv()): RuntimeProfile {
+  const profile = env?.[RUNTIME_PROFILE_ENV_VAR] ?? env?.[LEGACY_RUNTIME_PROFILE_ENV_VAR]
+  return profile?.trim().toLowerCase() === "dev" ? "dev" : "prod"
+}
+
+export function getDataRootName(env: RuntimeEnv = getRuntimeEnv()) {
+  return getRuntimeProfile(env) === "dev" ? DEV_DATA_ROOT_NAME : DATA_ROOT_NAME
+}
+
+export function getDataRootDir(homeDir: string, env: RuntimeEnv = getRuntimeEnv()) {
+  return `${homeDir}/${getDataRootName(env)}`
+}
+
+export function getDataRootDirDisplay(env: RuntimeEnv = getRuntimeEnv()) {
+  return `~/${getDataRootName(env)}`
+}
+
+export function getDataDir(homeDir: string, env: RuntimeEnv = getRuntimeEnv()) {
+  return `${getDataRootDir(homeDir, env)}/data`
+}
+
+export function getDataDirDisplay(env: RuntimeEnv = getRuntimeEnv()) {
+  return `${getDataRootDirDisplay(env)}/data`
+}
+
+export function getCliInvocation(arg?: string) {
+  return arg ? `${CLI_COMMAND} ${arg}` : CLI_COMMAND
+}

package/src/shared/compression.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test"
+import { isGzipped, compressPayload, decompressPayload } from "./compression"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function makeJson(sizeHint: number): string {
+  const entry = { kind: "text", id: "msg-001", content: "x".repeat(200), timestamp: "2026-03-31T00:00:00Z" }
+  const entries: typeof entry[] = []
+  while (JSON.stringify(entries).length < sizeHint) {
+    entries.push({ ...entry, id: `msg-${entries.length}` })
+  }
+  return JSON.stringify(entries)
+}
+
+describe("isGzipped", () => {
+  test("detects gzip magic bytes", () => {
+    expect(isGzipped(new Uint8Array([0x1f, 0x8b, 0x08]))).toBe(true)
+  })
+
+  test("rejects plain JSON", () => {
+    expect(isGzipped(encoder.encode('{"hello":"world"}'))).toBe(false)
+  })
+
+  test("rejects empty input", () => {
+    expect(isGzipped(new Uint8Array([]))).toBe(false)
+  })
+
+  test("rejects single-byte input", () => {
+    expect(isGzipped(new Uint8Array([0x1f]))).toBe(false)
+  })
+})
+
+describe("compressPayload", () => {
+  test("passes through small payloads unchanged", () => {
+    const small = encoder.encode('{"tiny":true}')
+    const result = compressPayload(small)
+    expect(result).toBe(small) // same reference — no copy
+  })
+
+  test("compresses payloads above 64 KB threshold", () => {
+    const largeJson = makeJson(100_000)
+    const raw = encoder.encode(largeJson)
+    expect(raw.length).toBeGreaterThan(65_536)
+
+    const compressed = compressPayload(raw)
+    expect(compressed.length).toBeLessThan(raw.length)
+    expect(isGzipped(compressed)).toBe(true)
+  })
+
+  test("compressed output is valid gzip that roundtrips", async () => {
+    const largeJson = makeJson(100_000)
+    const raw = encoder.encode(largeJson)
+    const compressed = compressPayload(raw)
+
+    const decompressed = await decompressPayload(compressed)
+    expect(decoder.decode(decompressed)).toBe(largeJson)
+  })
+})
+
+describe("decompressPayload", () => {
+  test("passes through non-gzipped data unchanged", async () => {
+    const plain = encoder.encode('{"hello":"world"}')
+    const result = await decompressPayload(plain)
+    expect(decoder.decode(result)).toBe('{"hello":"world"}')
+  })
+
+  test("decompresses gzipped data correctly", async () => {
+    const largeJson = makeJson(100_000)
+    const raw = encoder.encode(largeJson)
+    const compressed = compressPayload(raw)
+
+    const result = await decompressPayload(compressed)
+    expect(decoder.decode(result)).toBe(largeJson)
+  })
+
+  test("roundtrip: compressPayload -> decompressPayload", async () => {
+    const largeJson = makeJson(200_000)
+    const raw = encoder.encode(largeJson)
+    const compressed = compressPayload(raw)
+    const decompressed = await decompressPayload(compressed)
+
+    expect(decoder.decode(decompressed)).toBe(largeJson)
+  })
+})

package/src/shared/compression.ts

@@ -0,0 +1,42 @@
+/**
+ * Transparent gzip compression for NATS payloads.
+ *
+ * Large chat snapshots exceed NATS max_payload (8 MB).
+ * JSON compresses 10-20x, raising the effective ceiling to ~80-160 MB.
+ */
+
+const COMPRESS_THRESHOLD = 65_536
+
+export function isGzipped(data: Uint8Array): boolean {
+  return data.length >= 2 && data[0] === 0x1f && data[1] === 0x8b
+}
+
+// TS 5.8 widens Uint8Array to Uint8Array<ArrayBufferLike>, but Bun APIs require Uint8Array<ArrayBuffer>.
+// TextEncoder.encode() always backs by ArrayBuffer, making the narrowing safe.
+type BunBytes = Uint8Array<ArrayBuffer>
+
+function toBunBytes(data: Uint8Array): BunBytes {
+  if (data.buffer instanceof ArrayBuffer) {
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+  }
+
+  return new Uint8Array(data.slice())
+}
+
+export function compressPayload(raw: Uint8Array): Uint8Array {
+  if (raw.length <= COMPRESS_THRESHOLD) return raw
+  return Bun.gzipSync(toBunBytes(raw), { level: 1 })
+}
+
+export async function decompressPayload(data: Uint8Array): Promise<Uint8Array> {
+  if (!isGzipped(data)) return data
+  // Server (Bun): use synchronous gunzip — no stream overhead
+  if (typeof Bun !== "undefined") {
+    return Bun.gunzipSync(toBunBytes(data))
+  }
+  // Browser fallback: DecompressionStream
+  const ds = new DecompressionStream("gzip")
+  const writer = ds.writable.getWriter()
+  void writer.write(toBunBytes(data)).then(() => writer.close())
+  return new Uint8Array(await new Response(ds.readable).arrayBuffer())
+}

package/src/shared/coordination-store.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from "bun:test"
+import type { CoordinationStore } from "./coordination-store"
+
+describe("CoordinationStore interface", () => {
+  test("type-checks against EventStore shape", () => {
+    // This is a compile-time test — if CoordinationStore is incompatible
+    // with EventStore's methods, tsc will fail.
+    const mockStore: CoordinationStore = {
+      state: { coordinationByWorkspace: new Map() },
+      addTodo: async () => {},
+      claimTodo: async () => {},
+      completeTodo: async () => {},
+      abandonTodo: async () => {},
+      createClaim: async () => {},
+      releaseClaim: async () => {},
+      createWorktree: async () => {},
+      assignWorktree: async () => {},
+      removeWorktree: async () => {},
+      setRule: async () => {},
+      removeRule: async () => {},
+    }
+    expect(mockStore).toBeDefined()
+  })
+})

package/src/shared/coordination-store.ts

@@ -0,0 +1,26 @@
+import type { WorkspaceCoordinationState } from "../server/events"
+import type { WorkspaceCoordinationSnapshot, TodoPriority } from "./workspace-types"
+
+/**
+ * Minimal interface for project coordination operations.
+ * Implemented by EventStore (server-side, in-process) and
+ * NatsCoordinationClient (runner-side, over NATS).
+ */
+export interface CoordinationStore {
+  state: {
+    coordinationByWorkspace: Map<string, WorkspaceCoordinationState>
+  }
+  addTodo(workspaceId: string, todoId: string, description: string, priority: TodoPriority, createdBy: string): Promise<void>
+  claimTodo(workspaceId: string, todoId: string, sessionId: string): Promise<void>
+  completeTodo(workspaceId: string, todoId: string, outputs: string[]): Promise<void>
+  abandonTodo(workspaceId: string, todoId: string): Promise<void>
+  createClaim(workspaceId: string, claimId: string, intent: string, files: string[], sessionId: string): Promise<void>
+  releaseClaim(workspaceId: string, claimId: string): Promise<void>
+  createWorktree(workspaceId: string, worktreeId: string, branch: string, baseBranch: string, path: string): Promise<void>
+  assignWorktree(workspaceId: string, worktreeId: string, sessionId: string): Promise<void>
+  removeWorktree(workspaceId: string, worktreeId: string): Promise<void>
+  setRule(workspaceId: string, ruleId: string, content: string, setBy: string): Promise<void>
+  removeRule(workspaceId: string, ruleId: string): Promise<void>
+  /** Optional: fetch a full coordination snapshot (used when state is not in-process). */
+  getSnapshot?(workspaceId: string): Promise<WorkspaceCoordinationSnapshot>
+}

package/src/shared/dev-ports.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test"
+import {
+  DEFAULT_DEV_CLIENT_PORT,
+  getDefaultDevServerPort,
+  parseDevArgs,
+  resolveDevPorts,
+  stripPortArg,
+} from "./dev-ports"
+
+describe("getDefaultDevServerPort", () => {
+  test("derives the default backend port from the client port", () => {
+    expect(getDefaultDevServerPort()).toBe(DEFAULT_DEV_CLIENT_PORT + 1)
+    expect(getDefaultDevServerPort(4000)).toBe(4001)
+  })
+})
+
+describe("resolveDevPorts", () => {
+  test("uses default dev ports when no port override is provided", () => {
+    expect(resolveDevPorts([])).toEqual({
+      clientPort: DEFAULT_DEV_CLIENT_PORT,
+      serverPort: DEFAULT_DEV_CLIENT_PORT + 1,
+    })
+  })
+
+  test("treats --port as the client port and derives the backend port", () => {
+    expect(resolveDevPorts(["--remote", "--port", "4000"])).toEqual({
+      clientPort: 4000,
+      serverPort: 4001,
+    })
+  })
+
+  test("uses the last provided --port value", () => {
+    expect(resolveDevPorts(["--port", "4000", "--port", "4100"])).toEqual({
+      clientPort: 4100,
+      serverPort: 4101,
+    })
+  })
+
+  test("throws when --port is missing a value", () => {
+    expect(() => resolveDevPorts(["--port"])).toThrow("Missing value for --port")
+    expect(() => resolveDevPorts(["--port", "--remote"])).toThrow("Missing value for --port")
+  })
+})
+
+describe("stripPortArg", () => {
+  test("removes --port and its value while preserving other args", () => {
+    expect(stripPortArg(["--remote", "--port", "4000", "--host", "dev-box"])).toEqual([
+      "--remote",
+      "--host",
+      "dev-box",
+    ])
+  })
+})
+
+describe("parseDevArgs", () => {
+  test("derives dev share options from the client port", () => {
+    expect(parseDevArgs(["--share", "--port", "3333"], "dev-machine")).toEqual({
+      clientPort: 3333,
+      serverPort: 3334,
+      share: true,
+      backendTargetHost: "127.0.0.1",
+      allowedHosts: true,
+      serverArgs: [],
+    })
+  })
+
+  test("rejects combining --share with --host or --remote", () => {
+    expect(() => parseDevArgs(["--share", "--host", "dev-box"], "dev-machine")).toThrow("--share cannot be used with --host")
+    expect(() => parseDevArgs(["--host", "dev-box", "--share"], "dev-machine")).toThrow("--share cannot be used with --host")
+    expect(() => parseDevArgs(["--share", "--remote"], "dev-machine")).toThrow("--share cannot be used with --remote")
+    expect(() => parseDevArgs(["--remote", "--share"], "dev-machine")).toThrow("--share cannot be used with --remote")
+  })
+
+  test("preserves existing remote host behavior when share is off", () => {
+    expect(parseDevArgs(["--remote", "--port", "3333"], "dev-machine")).toEqual({
+      clientPort: 3333,
+      serverPort: 3334,
+      share: false,
+      backendTargetHost: "127.0.0.1",
+      allowedHosts: true,
+      serverArgs: ["--remote"],
+    })
+  })
+})

package/src/shared/dev-ports.ts

@@ -0,0 +1,100 @@
+export const DEFAULT_DEV_CLIENT_PORT = 5174
+
+export function getDefaultDevServerPort(clientPort = DEFAULT_DEV_CLIENT_PORT) {
+  return clientPort + 1
+}
+
+export interface DevArgResolution {
+  clientPort: number
+  serverPort: number
+  share: boolean
+  backendTargetHost: string
+  allowedHosts: true | string[]
+  serverArgs: string[]
+}
+
+export function resolveDevPorts(args: string[]) {
+  let clientPort = DEFAULT_DEV_CLIENT_PORT
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg !== "--port") continue
+
+    const next = args[index + 1]
+    if (!next || next.startsWith("-")) {
+      throw new Error("Missing value for --port")
+    }
+
+    const parsed = Number(next)
+    if (!Number.isFinite(parsed)) throw new Error(`Invalid port: ${next}`)
+    clientPort = parsed
+    index += 1
+  }
+
+  return {
+    clientPort,
+    serverPort: getDefaultDevServerPort(clientPort),
+  }
+}
+
+export function stripPortArg(args: string[]) {
+  const stripped: string[] = []
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === "--port") {
+      index += 1
+      continue
+    }
+
+    stripped.push(arg)
+  }
+
+  return stripped
+}
+
+export function parseDevArgs(args: string[], localHostname: string): DevArgResolution {
+  const { clientPort, serverPort } = resolveDevPorts(args)
+  const serverArgs = stripPortArg(args).filter((arg) => arg !== "--share")
+  let share = false
+  let sawHost = false
+  let sawRemote = false
+  let backendTargetHost = "127.0.0.1"
+  let allowAllHosts = false
+  const hosts = new Set<string>(["localhost", "127.0.0.1", "0.0.0.0", localHostname])
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === "--share") {
+      if (sawHost) throw new Error("--share cannot be used with --host")
+      if (sawRemote) throw new Error("--share cannot be used with --remote")
+      share = true
+      continue
+    }
+    if (arg === "--remote") {
+      if (share) throw new Error("--share cannot be used with --remote")
+      sawRemote = true
+      backendTargetHost = "127.0.0.1"
+      allowAllHosts = true
+      continue
+    }
+    if (arg !== "--host") continue
+
+    const next = args[index + 1]
+    if (!next || next.startsWith("-")) continue
+    if (share) throw new Error("--share cannot be used with --host")
+    sawHost = true
+    hosts.add(next)
+    backendTargetHost = next === "0.0.0.0" ? "127.0.0.1" : next
+    index += 1
+  }
+
+  return {
+    clientPort,
+    serverPort,
+    share,
+    backendTargetHost,
+    allowedHosts: share || allowAllHosts ? true : [...hosts],
+    serverArgs,
+  }
+}

package/src/shared/extension-types.ts

@@ -0,0 +1,45 @@
+/** Extension manifest — shared metadata declaring identity and detection probes */
+export interface ExtensionManifest {
+  id: string
+  name: string
+  icon: string
+  detect: string[]
+}
+
+/** A single route declared by a server extension */
+export interface ExtensionRoute {
+  method: "GET" | "POST"
+  path: string
+  handler: (req: Request, params: Record<string, string>) => Promise<Response>
+}
+
+/** Server-side extension — declares routes scoped to a project path */
+export interface ServerExtension extends ExtensionManifest {
+  routes(ctx: { projectPath: string }): ExtensionRoute[]
+}
+
+/** Props passed to every client extension component */
+export interface ExtensionProps {
+  localPath: string
+  groupKey: string
+}
+
+/** Result of filesystem probe detection */
+export interface DetectionResult {
+  extensionId: string
+  name: string
+  icon: string
+  detected: boolean
+}
+
+/** Persisted user preference for an extension (level 3 of the hierarchy) */
+export interface ExtensionPreference {
+  extensionId: string
+  enabled: boolean
+  updatedAt: number
+}
+
+/** Snapshot published to subscribers of extension-preferences topic */
+export interface ExtensionPreferencesSnapshot {
+  preferences: ExtensionPreference[]
+}

package/src/shared/fork-presets.ts

@@ -0,0 +1,54 @@
+import { type PresetDefinition, getPreset } from "./preset-types"
+
+export type ForkPresetDefinition = PresetDefinition
+
+export const FORK_PRESETS: readonly ForkPresetDefinition[] = [
+  {
+    id: "implementation_branch",
+    label: "Implementation branch",
+    description: "Continue toward a concrete feature or code change.",
+    defaultIntent: "Continue this work as an implementation branch. Carry forward the essential technical context, note the main constraints, and focus the new session on the next concrete coding steps.",
+    generatorHint: "Bias toward an execution-ready brief with concrete next implementation steps.",
+  },
+  {
+    id: "alternative_approach",
+    label: "Alternative approach",
+    description: "Explore a different design or implementation path.",
+    defaultIntent: "Fork this into an alternative approach. Preserve only the key constraints and decisions from the current chat, then frame the new session around a distinctly different implementation strategy.",
+    generatorHint: "Emphasize the constraints and assumptions that still apply, but optimize for exploring a different solution path.",
+  },
+  {
+    id: "bug_investigation",
+    label: "Bug investigation",
+    description: "Turn the current state into a focused debugging branch.",
+    defaultIntent: "Fork this into a bug investigation. Extract the symptoms, likely causes, relevant files, and the strongest reproduction or verification steps so the new session can debug efficiently.",
+    generatorHint: "Prioritize symptoms, repro steps, affected surfaces, and likely fault boundaries.",
+  },
+  {
+    id: "cleanup_refactor",
+    label: "Cleanup / refactor",
+    description: "Narrow the work to code quality and simplification.",
+    defaultIntent: "Fork this into a cleanup and refactor pass. Keep the important behavioral constraints, identify the code areas most worth simplifying, and focus the new session on safer structural improvement.",
+    generatorHint: "Prioritize invariants, areas of complexity, and low-risk refactor opportunities.",
+  },
+  {
+    id: "tests",
+    label: "Write tests",
+    description: "Build a testing-focused branch from the current work.",
+    defaultIntent: "Fork this into a test-writing pass. Capture the intended behavior, risky edges, missing verification, and the best targets for regression or integration tests.",
+    generatorHint: "Emphasize expected behavior, regressions to guard against, and concrete verification targets.",
+  },
+  {
+    id: "docs_spec",
+    label: "Docs / spec",
+    description: "Extract the current work into a clearer brief or spec.",
+    defaultIntent: "Fork this into a docs or spec-writing session. Distill the relevant decisions, architecture, constraints, and open questions into a cleaner written brief for follow-up work.",
+    generatorHint: "Bias toward structured explanation, decisions, constraints, and unresolved questions.",
+  },
+] as const
+
+export const DEFAULT_FORK_PRESET_ID = FORK_PRESETS[0]!.id
+
+export function getForkPreset(id?: string | null): ForkPresetDefinition | null {
+  return getPreset(FORK_PRESETS, id)
+}

package/src/shared/harness-types.test.ts

@@ -0,0 +1,15 @@
+import { describe, test, expect } from "bun:test"
+
+describe("shared harness-types", () => {
+  test("HarnessEvent type and HarnessTurn type are exportable from shared", async () => {
+    // Dynamic import to test module resolution
+    const mod = await import("./harness-types")
+    // Module should export these (even if type-only, the module must resolve)
+    expect(mod).toBeDefined()
+  })
+
+  test("server re-export still resolves", async () => {
+    const mod = await import("../server/harness-types")
+    expect(mod).toBeDefined()
+  })
+})

package/src/shared/harness-types.ts

@@ -0,0 +1,21 @@
+import type { AccountInfo, AgentProvider, NormalizedToolCall, TranscriptEntry } from "./types"
+
+export interface HarnessEvent {
+  type: "transcript" | "session_token" | "rate_limit"
+  entry?: TranscriptEntry
+  sessionToken?: string
+  rateLimit?: { resetAt: number; tz: string }
+}
+
+export interface HarnessToolRequest {
+  tool: NormalizedToolCall & { toolKind: "ask_user_question" | "exit_plan_mode" }
+}
+
+export interface HarnessTurn {
+  provider: AgentProvider
+  stream: AsyncIterable<HarnessEvent>
+  getAccountInfo?: () => Promise<AccountInfo | null>
+  getContextUsage?: () => Promise<{ percentage: number; totalTokens: number; maxTokens: number } | null>
+  interrupt: () => Promise<void>
+  close: () => void
+}