@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/claude-prompt-helpers.ts

@@ -0,0 +1,139 @@
+/**
+ * Pure prompt-manipulation helpers — no IO, no side effects.
+ * Extracted from agent.ts to keep it lean.
+ */
+
+import type { ChatAttachment } from "../shared/types"
+import { isRecord } from "../shared/errors"
+
+// ---------------------------------------------------------------------------
+// XML helpers
+// ---------------------------------------------------------------------------
+
+function escapeXmlAttribute(value: string) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("\"", """)
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+}
+
+// ---------------------------------------------------------------------------
+// Attachment hint
+// ---------------------------------------------------------------------------
+
+export function buildAttachmentHintText(attachments: ChatAttachment[]) {
+  if (attachments.length === 0) return ""
+
+  const lines = attachments.map((attachment) => (
+    `<attachment kind="${escapeXmlAttribute(attachment.kind)}" mime_type="${escapeXmlAttribute(attachment.mimeType)}" path="${escapeXmlAttribute(attachment.absolutePath)}" project_path="${escapeXmlAttribute(attachment.relativePath)}" size_bytes="${attachment.size}" display_name="${escapeXmlAttribute(attachment.displayName)}" />`
+  ))
+
+  return [
+    "<kanna-attachments>",
+    ...lines,
+    "</kanna-attachments>",
+  ].join("\n")
+}
+
+export function buildPromptText(content: string, attachments: ChatAttachment[]) {
+  const attachmentHint = buildAttachmentHintText(attachments)
+  if (!attachmentHint) {
+    return content.trim()
+  }
+
+  const trimmed = content.trim()
+  return [
+    trimmed || "Please inspect the attached files.",
+    attachmentHint,
+  ].join("\n\n").trim()
+}
+
+// ---------------------------------------------------------------------------
+// Steered message
+// ---------------------------------------------------------------------------
+
+const STEERED_MESSAGE_PREFIX = `<system-message>
+The user would like to inform you of something while you continue to work. Acknowledge receipt immediately with a text response, then continue with the task at hand, incorporating the user's feedback if needed.
+</system-message>`
+
+export function buildSteeredMessageContent(content: string) {
+  return content.trim().length > 0
+    ? `${STEERED_MESSAGE_PREFIX}\n\n${content}`
+    : STEERED_MESSAGE_PREFIX
+}
+
+// ---------------------------------------------------------------------------
+// Error-message classifiers
+// ---------------------------------------------------------------------------
+
+export function isPromptTooLongMessage(message: string): boolean {
+  return /\bprompt\b.*\btoo\s+long\b/i.test(message)
+    || /\bprompt\b.*\btoo\s+large\b/i.test(message)
+}
+
+// The stored session token points at a conversation the Claude CLI never
+// persisted (e.g. a spawn interrupted before its first write). Every resume
+// then fails instantly — and the doomed spawn mints yet another unpersisted
+// session id, so without clearing the token the chat is wedged forever. The
+// message rides in result.errors (debugRaw); result text is empty.
+export function isNoConversationFoundMessage(message: string): boolean {
+  return /No conversation found with session ID/i.test(message)
+}
+
+// ---------------------------------------------------------------------------
+// SDK effort normaliser
+// ---------------------------------------------------------------------------
+
+/** Narrows a free-form effort string to the SDK-accepted union without a cast. */
+export function toSdkEffort(effort: string | undefined): "low" | "medium" | "high" | "xhigh" | "max" | undefined {
+  if (effort === "low" || effort === "medium" || effort === "high" || effort === "xhigh" || effort === "max") {
+    return effort
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// Background-task ID extraction
+// ---------------------------------------------------------------------------
+
+// Claude Code's BashTool emits this exact line in the tool_result when a command
+// is launched with `run_in_background: true`. It is the only observable launch
+// signal in Kanna's entry stream (the later `<task-notification>` line produces
+// no transcript entry). The id is alphanumeric. Global flag: one result may
+// report multiple launches in theory; capture every id.
+const BACKGROUND_TASK_LAUNCH_RE = /Command running in background with ID:\s*(\w+)/g
+
+/** Extract background-task ids from a tool_result entry's content (string or content blocks). */
+export function backgroundTaskIdsFromToolResult<T>(content: T): string[] {
+  let text = ""
+  if (typeof content === "string") {
+    text = content
+  } else if (Array.isArray(content)) {
+    for (const block of content) {
+      if (isRecord(block)) {
+        const blockText = block.text
+        if (typeof blockText === "string") {
+          text += `${blockText}\n`
+        }
+      }
+    }
+  } else {
+    return []
+  }
+  const ids: string[] = []
+  for (const match of text.matchAll(BACKGROUND_TASK_LAUNCH_RE)) {
+    if (match[1]) ids.push(match[1])
+  }
+  return ids
+}
+
+// ---------------------------------------------------------------------------
+// Env-var helpers
+// ---------------------------------------------------------------------------
+
+export function positiveIntegerFromEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") return fallback
+  const parsed = Number(value)
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback
+}

package/src/server/claude-sdk-queue.test.ts

@@ -0,0 +1,169 @@
+import { expect, test, describe } from "bun:test"
+import { AsyncMessageQueue, discardedToolResult, toClaudeMessageStream } from "./claude-sdk-queue"
+import type { ClaudeRawSdkMessage } from "./claude-message-normalizer"
+import type { NormalizedToolCall } from "../shared/types"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a fake Query (AsyncGenerator) from an array of objects */
+async function* fakeQuery(
+  items: Record<string, unknown>[]
+): AsyncGenerator<Record<string, unknown>, void> {
+  for (const item of items) {
+    yield item
+  }
+}
+
+/** Collect all values from an async iterable into an array */
+async function collect<T>(iter: AsyncIterable<T>): Promise<T[]> {
+  const out: T[] = []
+  for await (const v of iter) {
+    out.push(v)
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// AsyncMessageQueue
+// ---------------------------------------------------------------------------
+
+describe("AsyncMessageQueue", () => {
+  test("push + async iteration yields values in order", async () => {
+    const q = new AsyncMessageQueue<number>()
+    q.push(1)
+    q.push(2)
+    q.push(3)
+    q.close()
+    const result = await collect(q)
+    expect(result).toEqual([1, 2, 3])
+  })
+
+  test("close() ends iteration", async () => {
+    const q = new AsyncMessageQueue<string>()
+    q.push("a")
+    q.close()
+    const result = await collect(q)
+    expect(result).toEqual(["a"])
+  })
+
+  test("push after close throws", () => {
+    const q = new AsyncMessageQueue<number>()
+    q.close()
+    expect(() => q.push(42)).toThrow("Cannot push to a closed queue")
+  })
+
+  test("waiter is resolved immediately when queue had a pending value", async () => {
+    const q = new AsyncMessageQueue<string>()
+    // Start consuming before any push
+    const iter = q[Symbol.asyncIterator]()
+    const nextPromise = iter.next()
+    // Push while a waiter is registered
+    q.push("hello")
+    const result = await nextPromise
+    expect(result).toEqual({ done: false, value: "hello" })
+  })
+
+  test("multiple pushes before iteration are delivered in order", async () => {
+    const q = new AsyncMessageQueue<number>()
+    for (let i = 0; i < 5; i++) q.push(i)
+    q.close()
+    const result = await collect(q)
+    expect(result).toEqual([0, 1, 2, 3, 4])
+  })
+
+  test("close with pending waiters resolves them as done", async () => {
+    const q = new AsyncMessageQueue<number>()
+    const iter = q[Symbol.asyncIterator]()
+    const nextPromise = iter.next()
+    // Close while a waiter is pending
+    q.close()
+    const result = await nextPromise
+    expect(result).toEqual({ done: true, value: undefined })
+  })
+
+  test("close() is idempotent — calling twice does not throw", () => {
+    const q = new AsyncMessageQueue<number>()
+    q.push(1)
+    q.close()
+    expect(() => q.close()).not.toThrow()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// discardedToolResult
+// ---------------------------------------------------------------------------
+
+/** Build a minimal mock NormalizedToolCall with the given toolKind. */
+function makeTool<TKind extends "ask_user_question" | "exit_plan_mode">(
+  toolKind: TKind
+): NormalizedToolCall & { toolKind: TKind } {
+  return {
+    kind: "tool",
+    toolKind,
+    toolName: toolKind,
+    toolId: "t1",
+    input: {} as never,
+  } as unknown as NormalizedToolCall & { toolKind: TKind }
+}
+
+describe("discardedToolResult", () => {
+  test("ask_user_question variant returns answers: {}", () => {
+    const result = discardedToolResult(makeTool("ask_user_question"))
+    expect(result).toHaveProperty("answers")
+    expect((result as { answers: Record<string, string> }).answers).toEqual({})
+  })
+
+  test("exit_plan_mode variant does not have an answers field", () => {
+    const result = discardedToolResult(makeTool("exit_plan_mode"))
+    expect(result).not.toHaveProperty("answers")
+  })
+
+  test("ask_user_question result carries discarded: true", () => {
+    expect(discardedToolResult(makeTool("ask_user_question")).discarded).toBe(true)
+  })
+
+  test("exit_plan_mode result carries discarded: true", () => {
+    expect(discardedToolResult(makeTool("exit_plan_mode")).discarded).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// toClaudeMessageStream
+// ---------------------------------------------------------------------------
+
+describe("toClaudeMessageStream", () => {
+  test("passes through all SDK messages unchanged", async () => {
+    const messages: ClaudeRawSdkMessage[] = [
+      { type: "assistant", uuid: "a" },
+      { type: "system", uuid: "b" },
+    ]
+    // fakeQuery produces objects; cast to satisfy Query's AsyncGenerator shape
+    const q = fakeQuery(messages as Record<string, unknown>[])
+    const result = await collect(toClaudeMessageStream(q as never))
+    expect(result).toHaveLength(2)
+    expect(result[0]).toEqual(messages[0])
+    expect(result[1]).toEqual(messages[1])
+  })
+
+  test("yields empty sequence for an empty query", async () => {
+    const q = fakeQuery([])
+    const result = await collect(toClaudeMessageStream(q as never))
+    expect(result).toHaveLength(0)
+  })
+
+  test("yielded messages preserve their properties", async () => {
+    const msg: ClaudeRawSdkMessage = {
+      type: "result",
+      result: "DONE",
+      total_cost_usd: 0.001,
+      session_id: "sess-1",
+    }
+    const q = fakeQuery([msg as Record<string, unknown>])
+    const [yielded] = await collect(toClaudeMessageStream(q as never))
+    expect(yielded?.result).toBe("DONE")
+    expect(yielded?.total_cost_usd).toBe(0.001)
+    expect(yielded?.session_id).toBe("sess-1")
+  })
+})

package/src/server/claude-sdk-queue.ts

@@ -0,0 +1,82 @@
+import { type Query } from "@anthropic-ai/claude-agent-sdk"
+import { type ClaudeRawSdkMessage, isSdkToClaudeMessage } from "./claude-message-normalizer"
+import type { NormalizedToolCall } from "../shared/types"
+
+/**
+ * Generic async iterable queue used to buffer SDK user-message turns.
+ * Pure data structure — no IO.
+ */
+export class AsyncMessageQueue<T> implements AsyncIterable<T> {
+  private readonly values: T[] = []
+  private readonly waiters: Array<(result: IteratorResult<T, undefined>) => void> = []
+  private closed = false
+
+  push(value: T) {
+    if (this.closed) {
+      throw new Error("Cannot push to a closed queue")
+    }
+
+    const waiter = this.waiters.shift()
+    if (waiter) {
+      waiter({ done: false, value })
+      return
+    }
+
+    this.values.push(value)
+  }
+
+  close() {
+    if (this.closed) return
+    this.closed = true
+    while (this.waiters.length > 0) {
+      const waiter = this.waiters.shift()
+      waiter?.({ done: true, value: undefined })
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T, undefined> {
+    return {
+      next: async (): Promise<IteratorResult<T, undefined>> => {
+        if (this.values.length > 0) {
+          return { done: false, value: this.values.shift()! }
+        }
+
+        if (this.closed) {
+          return { done: true, value: undefined }
+        }
+
+        return await new Promise<IteratorResult<T, undefined>>((resolve) => {
+          this.waiters.push(resolve)
+        })
+      },
+    }
+  }
+}
+
+/**
+ * Builds the discard payload for ask_user_question / exit_plan_mode tools
+ * when a pending tool call is discarded (e.g. session closed mid-flight).
+ */
+export function discardedToolResult(
+  tool: NormalizedToolCall & { toolKind: "ask_user_question" | "exit_plan_mode" }
+) {
+  if (tool.toolKind === "ask_user_question") {
+    return {
+      discarded: true,
+      answers: {},
+    }
+  }
+
+  return {
+    discarded: true,
+  }
+}
+
+/**
+ * Filters the raw SDK stream to Claude-only messages.
+ */
+export async function* toClaudeMessageStream(q: Query): AsyncGenerator<ClaudeRawSdkMessage> {
+  for await (const m of q) {
+    if (isSdkToClaudeMessage(m)) yield m
+  }
+}