@cuongtran001/kanna 1.2.0 → 1.3.1

package/src/server/claude-steer-log.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, mock } from "bun:test"
+import {
+  isClaudeSteerLoggingEnabled,
+  isSendToStartingProfilingEnabled,
+  elapsedProfileMs,
+  logClaudeSteer,
+  logSendToStartingProfile,
+  type SendToStartingProfile,
+} from "./claude-steer-log"
+import { log } from "../shared/log"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function withEnv(key: string, value: string | undefined, fn: () => void) {
+  const previous = process.env[key]
+  if (value === undefined) {
+    delete process.env[key]
+  } else {
+    process.env[key] = value
+  }
+  try {
+    fn()
+  } finally {
+    if (previous === undefined) {
+      delete process.env[key]
+    } else {
+      process.env[key] = previous
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// isClaudeSteerLoggingEnabled
+// ---------------------------------------------------------------------------
+
+describe("isClaudeSteerLoggingEnabled", () => {
+  it("returns false when env var is unset", () => {
+    withEnv("KANNA_LOG_CLAUDE_STEER", undefined, () => {
+      expect(isClaudeSteerLoggingEnabled()).toBe(false)
+    })
+  })
+
+  it("returns false when env var is '0'", () => {
+    withEnv("KANNA_LOG_CLAUDE_STEER", "0", () => {
+      expect(isClaudeSteerLoggingEnabled()).toBe(false)
+    })
+  })
+
+  it("returns false when env var is any non-'1' string", () => {
+    withEnv("KANNA_LOG_CLAUDE_STEER", "true", () => {
+      expect(isClaudeSteerLoggingEnabled()).toBe(false)
+    })
+  })
+
+  it("returns true when env var is '1'", () => {
+    withEnv("KANNA_LOG_CLAUDE_STEER", "1", () => {
+      expect(isClaudeSteerLoggingEnabled()).toBe(true)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// isSendToStartingProfilingEnabled
+// ---------------------------------------------------------------------------
+
+describe("isSendToStartingProfilingEnabled", () => {
+  it("returns false when env var is unset", () => {
+    withEnv("KANNA_PROFILE_SEND_TO_STARTING", undefined, () => {
+      expect(isSendToStartingProfilingEnabled()).toBe(false)
+    })
+  })
+
+  it("returns true when env var is '1'", () => {
+    withEnv("KANNA_PROFILE_SEND_TO_STARTING", "1", () => {
+      expect(isSendToStartingProfilingEnabled()).toBe(true)
+    })
+  })
+
+  it("returns false when env var is '0'", () => {
+    withEnv("KANNA_PROFILE_SEND_TO_STARTING", "0", () => {
+      expect(isSendToStartingProfilingEnabled()).toBe(false)
+    })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// elapsedProfileMs
+// ---------------------------------------------------------------------------
+
+describe("elapsedProfileMs", () => {
+  it("returns a non-negative number", () => {
+    const start = performance.now()
+    const elapsed = elapsedProfileMs(start)
+    expect(elapsed).toBeGreaterThanOrEqual(0)
+  })
+
+  it("returns a number (not NaN)", () => {
+    const elapsed = elapsedProfileMs(performance.now())
+    expect(Number.isNaN(elapsed)).toBe(false)
+  })
+
+  it("returns a value with at most 1 decimal place", () => {
+    const elapsed = elapsedProfileMs(performance.now() - 100)
+    // toFixed(1) means at most one decimal digit
+    expect(elapsed.toString()).toMatch(/^\d+(\.\d)?$/)
+  })
+
+  it("returns a larger value for an earlier startedAt", () => {
+    const earlier = performance.now() - 200
+    const later = performance.now() - 50
+    expect(elapsedProfileMs(earlier)).toBeGreaterThanOrEqual(elapsedProfileMs(later))
+  })
+})
+
+// ---------------------------------------------------------------------------
+// logClaudeSteer
+// ---------------------------------------------------------------------------
+
+describe("logClaudeSteer", () => {
+  it("does not call log.info when logging is disabled", () => {
+    const spy = mock(() => {})
+    const original = log.info
+    log.info = spy
+    try {
+      withEnv("KANNA_LOG_CLAUDE_STEER", undefined, () => {
+        logClaudeSteer("test_stage", { foo: "bar" })
+      })
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      log.info = original
+    }
+  })
+
+  it("calls log.info with stage and details when enabled", () => {
+    const calls: Parameters<typeof log.info>[] = []
+    const original = log.info
+    log.info = (...args: Parameters<typeof log.info>) => { calls.push(args) }
+    try {
+      withEnv("KANNA_LOG_CLAUDE_STEER", "1", () => {
+        logClaudeSteer("my_stage", { key: "val" })
+      })
+      expect(calls.length).toBe(1)
+      const [prefix, json] = calls[0]
+      expect(prefix).toBe("[kanna/claude-steer]")
+      const parsed = JSON.parse(json as string)
+      expect(parsed.stage).toBe("my_stage")
+      expect(parsed.key).toBe("val")
+    } finally {
+      log.info = original
+    }
+  })
+
+  it("calls log.info with only stage when details omitted", () => {
+    const calls: Parameters<typeof log.info>[] = []
+    const original = log.info
+    log.info = (...args: Parameters<typeof log.info>) => { calls.push(args) }
+    try {
+      withEnv("KANNA_LOG_CLAUDE_STEER", "1", () => {
+        logClaudeSteer("no_details")
+      })
+      expect(calls.length).toBe(1)
+      const [, json] = calls[0]
+      const parsed = JSON.parse(json as string)
+      expect(parsed.stage).toBe("no_details")
+    } finally {
+      log.info = original
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// logSendToStartingProfile
+// ---------------------------------------------------------------------------
+
+describe("logSendToStartingProfile", () => {
+  it("is a no-op when profile is null", () => {
+    const spy = mock(() => {})
+    const original = log.info
+    log.info = spy
+    try {
+      withEnv("KANNA_PROFILE_SEND_TO_STARTING", "1", () => {
+        logSendToStartingProfile(null, "some_stage")
+      })
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      log.info = original
+    }
+  })
+
+  it("is a no-op when profile is undefined", () => {
+    const spy = mock(() => {})
+    const original = log.info
+    log.info = spy
+    try {
+      withEnv("KANNA_PROFILE_SEND_TO_STARTING", "1", () => {
+        logSendToStartingProfile(undefined, "some_stage")
+      })
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      log.info = original
+    }
+  })
+
+  it("is a no-op when profiling env var is not set", () => {
+    const spy = mock(() => {})
+    const original = log.info
+    log.info = spy
+    try {
+      const profile: SendToStartingProfile = { traceId: "abc", startedAt: performance.now() }
+      withEnv("KANNA_PROFILE_SEND_TO_STARTING", undefined, () => {
+        logSendToStartingProfile(profile, "some_stage")
+      })
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      log.info = original
+    }
+  })
+
+  it("logs traceId, stage, and elapsedMs when profile is provided and enabled", () => {
+    const calls: Parameters<typeof log.info>[] = []
+    const original = log.info
+    log.info = (...args: Parameters<typeof log.info>) => { calls.push(args) }
+    try {
+      const profile: SendToStartingProfile = { traceId: "trace-123", startedAt: performance.now() - 50 }
+      withEnv("KANNA_PROFILE_SEND_TO_STARTING", "1", () => {
+        logSendToStartingProfile(profile, "my_stage", { extra: 42 })
+      })
+      expect(calls.length).toBe(1)
+      const [prefix, json] = calls[0]
+      expect(prefix).toBe("[kanna/send->starting][server]")
+      const parsed = JSON.parse(json as string)
+      expect(parsed.traceId).toBe("trace-123")
+      expect(parsed.stage).toBe("my_stage")
+      expect(typeof parsed.elapsedMs).toBe("number")
+      expect(parsed.elapsedMs).toBeGreaterThanOrEqual(0)
+      expect(parsed.extra).toBe(42)
+    } finally {
+      log.info = original
+    }
+  })
+})

package/src/server/claude-steer-log.ts

@@ -0,0 +1,58 @@
+import { log } from "../shared/log"
+import type { AgentProvider, ModelOptions } from "../shared/types"
+
+// ---------------------------------------------------------------------------
+// Steer-logging and send-to-starting profiling helpers
+// Extracted from agent.ts — pure env/math utilities, no AgentCoordinator dep.
+// ---------------------------------------------------------------------------
+
+export interface SendToStartingProfile {
+  traceId: string
+  startedAt: number
+}
+
+export function isClaudeSteerLoggingEnabled() {
+  return process.env.KANNA_LOG_CLAUDE_STEER === "1"
+}
+
+export function logClaudeSteer(stage: string, details?: Record<string, unknown>) {
+  if (!isClaudeSteerLoggingEnabled()) return
+  log.info("[kanna/claude-steer]", JSON.stringify({
+    stage,
+    ...details,
+  }))
+}
+
+export interface SendMessageOptions {
+  provider?: AgentProvider
+  model?: string
+  modelOptions?: ModelOptions
+  effort?: string
+  planMode?: boolean
+  autoContinue?: { scheduleId: string }
+}
+
+export function isSendToStartingProfilingEnabled() {
+  return process.env.KANNA_PROFILE_SEND_TO_STARTING === "1"
+}
+
+export function elapsedProfileMs(startedAt: number) {
+  return Number((performance.now() - startedAt).toFixed(1))
+}
+
+export function logSendToStartingProfile(
+  profile: SendToStartingProfile | null | undefined,
+  stage: string,
+  details?: Record<string, unknown>
+) {
+  if (!profile || !isSendToStartingProfilingEnabled()) {
+    return
+  }
+
+  log.info("[kanna/send->starting][server]", JSON.stringify({
+    traceId: profile.traceId,
+    stage,
+    elapsedMs: elapsedProfileMs(profile.startedAt),
+    ...details,
+  }))
+}

package/src/server/claude-subagent-tool-response.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, mock } from "bun:test"
+import {
+  subagentPendingKey,
+  rejectPendingResolvers,
+  rejectPendingResolversForChat,
+  rejectPendingResolversForRun,
+  respondSubagentTool,
+  cancelSubagentRun,
+  type SubagentToolResponseDeps,
+} from "./claude-subagent-tool-response"
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeResolver() {
+  let resolveFn: ((v: unknown) => void) | undefined
+  let rejectFn: ((e: Error) => void) | undefined
+  const promise = new Promise<unknown>((res, rej) => {
+    resolveFn = res
+    rejectFn = rej
+  })
+  // Suppress unhandled-rejection noise in tests
+  promise.catch(() => undefined)
+  return {
+    promise,
+    resolve: (v: unknown) => resolveFn!(v),
+    reject: (e: Error) => rejectFn!(e),
+  }
+}
+
+function makeDeps(
+  overrides?: Partial<SubagentToolResponseDeps>,
+): SubagentToolResponseDeps {
+  return {
+    subagentPendingResolvers: new Map(),
+    store: {
+      appendSubagentEvent: mock(() => Promise.resolve()),
+    },
+    subagentOrchestrator: {
+      notifySubagentToolResolved: mock(() => undefined),
+      cancelRun: mock(() => undefined),
+    },
+    emitStateChange: mock(() => undefined),
+    ...overrides,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// subagentPendingKey
+// ---------------------------------------------------------------------------
+
+describe("subagentPendingKey", () => {
+  it("concatenates chatId, runId, and toolUseId with ::", () => {
+    expect(subagentPendingKey("chat1", "run1", "tool1")).toBe("chat1::run1::tool1")
+  })
+
+  it("handles empty segments", () => {
+    expect(subagentPendingKey("", "", "")).toBe("::::")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// rejectPendingResolvers
+// ---------------------------------------------------------------------------
+
+describe("rejectPendingResolvers", () => {
+  it("rejects entries matching predicate and removes them from the map", async () => {
+    const deps = makeDeps()
+    const r1 = makeResolver()
+    const r2 = makeResolver()
+    deps.subagentPendingResolvers.set("chat1::run1::t1", r1)
+    deps.subagentPendingResolvers.set("chat2::run2::t2", r2)
+
+    rejectPendingResolvers(
+      deps,
+      (k) => k.startsWith("chat1::"),
+      "test reason",
+    )
+
+    await expect(r1.promise).rejects.toThrow("test reason")
+    expect(deps.subagentPendingResolvers.has("chat1::run1::t1")).toBe(false)
+    // Non-matching entry untouched
+    expect(deps.subagentPendingResolvers.has("chat2::run2::t2")).toBe(true)
+  })
+
+  it("does nothing when no entries match predicate", () => {
+    const deps = makeDeps()
+    const r = makeResolver()
+    deps.subagentPendingResolvers.set("chat1::run1::t1", r)
+
+    rejectPendingResolvers(deps, () => false, "ignored")
+
+    expect(deps.subagentPendingResolvers.size).toBe(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// rejectPendingResolversForChat
+// ---------------------------------------------------------------------------
+
+describe("rejectPendingResolversForChat", () => {
+  it("rejects all resolvers belonging to the given chatId", async () => {
+    const deps = makeDeps()
+    const r1 = makeResolver()
+    const r2 = makeResolver()
+    const rOther = makeResolver()
+    deps.subagentPendingResolvers.set("chatA::run1::t1", r1)
+    deps.subagentPendingResolvers.set("chatA::run2::t2", r2)
+    deps.subagentPendingResolvers.set("chatB::run1::t1", rOther)
+
+    rejectPendingResolversForChat(deps, "chatA")
+
+    await expect(r1.promise).rejects.toThrow("chat cancelled")
+    await expect(r2.promise).rejects.toThrow("chat cancelled")
+    expect(deps.subagentPendingResolvers.has("chatB::run1::t1")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// rejectPendingResolversForRun
+// ---------------------------------------------------------------------------
+
+describe("rejectPendingResolversForRun", () => {
+  it("rejects all resolvers belonging to the given run", async () => {
+    const deps = makeDeps()
+    const rTarget = makeResolver()
+    const rOtherRun = makeResolver()
+    deps.subagentPendingResolvers.set("chatA::run1::t1", rTarget)
+    deps.subagentPendingResolvers.set("chatA::run2::t1", rOtherRun)
+
+    rejectPendingResolversForRun(deps, "chatA", "run1")
+
+    await expect(rTarget.promise).rejects.toThrow("subagent run terminated")
+    expect(deps.subagentPendingResolvers.has("chatA::run2::t1")).toBe(true)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// respondSubagentTool
+// ---------------------------------------------------------------------------
+
+describe("respondSubagentTool", () => {
+  it("resolves the pending resolver, appends event, notifies orchestrator, emits state", async () => {
+    const deps = makeDeps()
+    const resolver = makeResolver()
+    deps.subagentPendingResolvers.set("chatX::runY::toolZ", resolver)
+
+    const command = {
+      type: "chat.respondSubagentTool" as const,
+      chatId: "chatX",
+      runId: "runY",
+      toolUseId: "toolZ",
+      result: { content: "ok" },
+    }
+
+    await respondSubagentTool(deps, command)
+
+    // Resolver resolved with the result
+    await expect(resolver.promise).resolves.toEqual({ content: "ok" })
+    // Removed from the map
+    expect(deps.subagentPendingResolvers.has("chatX::runY::toolZ")).toBe(false)
+    // Event persisted
+    expect(deps.store.appendSubagentEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "subagent_tool_resolved",
+        chatId: "chatX",
+        runId: "runY",
+        toolUseId: "toolZ",
+        result: { content: "ok" },
+        resolution: "user",
+      }),
+    )
+    // Orchestrator notified
+    expect(deps.subagentOrchestrator.notifySubagentToolResolved).toHaveBeenCalledWith("runY")
+    // State emitted
+    expect(deps.emitStateChange).toHaveBeenCalledWith("chatX")
+  })
+
+  it("is idempotent: does nothing when resolver is not found", async () => {
+    const deps = makeDeps()
+
+    await respondSubagentTool(deps, {
+      type: "chat.respondSubagentTool",
+      chatId: "chatX",
+      runId: "runY",
+      toolUseId: "toolZ",
+      result: {},
+    })
+
+    expect(deps.store.appendSubagentEvent).not.toHaveBeenCalled()
+    expect(deps.subagentOrchestrator.notifySubagentToolResolved).not.toHaveBeenCalled()
+    expect(deps.emitStateChange).not.toHaveBeenCalled()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// cancelSubagentRun
+// ---------------------------------------------------------------------------
+
+describe("cancelSubagentRun", () => {
+  it("delegates to orchestrator.cancelRun", () => {
+    const deps = makeDeps()
+
+    cancelSubagentRun(deps, {
+      type: "chat.cancelSubagentRun",
+      chatId: "chatA",
+      runId: "runB",
+    })
+
+    expect(deps.subagentOrchestrator.cancelRun).toHaveBeenCalledWith("chatA", "runB")
+  })
+})

package/src/server/claude-subagent-tool-response.ts

@@ -0,0 +1,165 @@
+/**
+ * Standalone functions for managing subagent pending tool-response resolvers.
+ *
+ * Extracted from AgentCoordinator to keep agent.ts below the 600-LOC target.
+ * No direct IO — all side-effects are injected via SubagentToolResponseDeps.
+ */
+
+import type { AnyValue } from "../shared/errors"
+import type { SubagentRunEvent } from "./events"
+
+// ---------------------------------------------------------------------------
+// Deps interface
+// ---------------------------------------------------------------------------
+
+/** Minimal surface of SubagentOrchestrator required by this module. */
+export interface SubagentToolResponseOrchestratorDeps {
+  notifySubagentToolResolved(runId: string): void
+  cancelRun(chatId: string, runId: string): void
+}
+
+/** Minimal surface of EventStore required by this module. */
+export interface SubagentToolResponseStoreDeps {
+  appendSubagentEvent(event: SubagentRunEvent): Promise<void>
+}
+
+/** Dependency bag injected into every function in this module. */
+export interface SubagentToolResponseDeps {
+  /** The shared in-memory resolver map owned by AgentCoordinator. */
+  subagentPendingResolvers: Map<
+    string,
+    { resolve: (v: AnyValue) => void; reject: (e: Error) => void }
+  >
+  store: SubagentToolResponseStoreDeps
+  subagentOrchestrator: SubagentToolResponseOrchestratorDeps
+  emitStateChange: (chatId: string) => void
+}
+
+// ---------------------------------------------------------------------------
+// Command shape re-exports (inline to avoid protocol import cycle)
+// ---------------------------------------------------------------------------
+
+export type RespondSubagentToolCommand = {
+  type: "chat.respondSubagentTool"
+  chatId: string
+  runId: string
+  toolUseId: string
+  result: Record<string, unknown>
+}
+
+export type CancelSubagentRunCommand = {
+  type: "chat.cancelSubagentRun"
+  chatId: string
+  runId: string
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/** Builds the map key used to look up a pending subagent tool resolver. */
+export function subagentPendingKey(
+  chatId: string,
+  runId: string,
+  toolUseId: string,
+): string {
+  return `${chatId}::${runId}::${toolUseId}`
+}
+
+// ---------------------------------------------------------------------------
+// Resolver management
+// ---------------------------------------------------------------------------
+
+/**
+ * Rejects all pending resolvers whose key satisfies `predicate`.
+ * Mutates `deps.subagentPendingResolvers` in place.
+ */
+export function rejectPendingResolvers(
+  deps: Pick<SubagentToolResponseDeps, "subagentPendingResolvers">,
+  predicate: (key: string) => boolean,
+  reason: string,
+): void {
+  for (const [key, resolver] of deps.subagentPendingResolvers) {
+    if (!predicate(key)) continue
+    deps.subagentPendingResolvers.delete(key)
+    resolver.reject(new Error(reason))
+  }
+}
+
+/** Rejects all pending resolvers that belong to `chatId`. */
+export function rejectPendingResolversForChat(
+  deps: Pick<SubagentToolResponseDeps, "subagentPendingResolvers">,
+  chatId: string,
+): void {
+  const prefix = `${chatId}::`
+  rejectPendingResolvers(deps, (k) => k.startsWith(prefix), "chat cancelled")
+}
+
+/** Rejects all pending resolvers that belong to a specific run within `chatId`. */
+export function rejectPendingResolversForRun(
+  deps: Pick<SubagentToolResponseDeps, "subagentPendingResolvers">,
+  chatId: string,
+  runId: string,
+): void {
+  const prefix = `${chatId}::${runId}::`
+  rejectPendingResolvers(
+    deps,
+    (k) => k.startsWith(prefix),
+    "subagent run terminated",
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Command handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handles a `chat.respondSubagentTool` command from the client.
+ *
+ * Resolves the pending resolver for the given tool-use, persists a
+ * `subagent_tool_resolved` event, notifies the orchestrator, and emits a
+ * state-change.
+ *
+ * Idempotent: a double-submit (client retry, concurrent WS messages, or a
+ * response arriving after the run already terminated) is silently ignored.
+ */
+export async function respondSubagentTool(
+  deps: SubagentToolResponseDeps,
+  command: RespondSubagentToolCommand,
+): Promise<void> {
+  const key = subagentPendingKey(command.chatId, command.runId, command.toolUseId)
+  const resolver = deps.subagentPendingResolvers.get(key)
+  if (!resolver) {
+    // Idempotent: a double-submit (client retry, concurrent WS messages, or
+    // a response arriving after the run already terminated) should not
+    // surface a confusing error to the UI. Resolver-absent = already
+    // resolved or run died; nothing to do.
+    return
+  }
+  deps.subagentPendingResolvers.delete(key)
+  await deps.store.appendSubagentEvent({
+    v: 3,
+    type: "subagent_tool_resolved",
+    timestamp: Date.now(),
+    chatId: command.chatId,
+    runId: command.runId,
+    toolUseId: command.toolUseId,
+    result: command.result,
+    resolution: "user",
+  })
+  deps.subagentOrchestrator.notifySubagentToolResolved(command.runId)
+  resolver.resolve(command.result)
+  deps.emitStateChange(command.chatId)
+}
+
+/**
+ * Handles a `chat.cancelSubagentRun` command from the client.
+ *
+ * Cancels the named run via the orchestrator.
+ */
+export function cancelSubagentRun(
+  deps: Pick<SubagentToolResponseDeps, "subagentOrchestrator">,
+  command: CancelSubagentRunCommand,
+): void {
+  deps.subagentOrchestrator.cancelRun(command.chatId, command.runId)
+}