@johpaz/hive-sdk 0.1.4 → 0.1.6

package/packages/core/src/agent/conversation-store.ts

@@ -0,0 +1,381 @@
+/**
+ * Conversation Store — persists message history in the `conversations` HiveDB collection.
+ * Replaces the LangGraph BunSqliteSaver + lg_checkpoints approach.
+ *
+ * Also manages: summaries and scratchpad, both HiveDB document collections.
+ */
+
+import { col, nextId, bumpRollup } from "../storage/hive"
+import { getHiveDb } from "../storage/hivedb"
+import { logger } from "../utils/logger"
+import type { LLMMessage, ContentPart } from "./llm-client"
+import { estimateTokens } from "../utils/toon"
+import type { ConversationDoc, SummaryDoc, MessageSource } from "../storage/collections"
+
+const log = logger.child("conv-store")
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface StoredMessage {
+  /** Per-thread monotonic sequence number (NOT globally unique — scope every comparison to a single threadId). */
+  id: number
+  thread_id: string
+  channel: string
+  role: "user" | "assistant" | "tool"
+  /** Provenance of this turn. Never null — legacy rows are normalized to "legacy_internal" on read. */
+  source: MessageSource
+  content: string
+  tool_calls_json: string | null
+  tool_call_id: string | null
+  reasoning_content: string | null  // Kimi K2 thinking — must be round-tripped
+  content_multimodal: string | null // JSON array of ContentPart[]
+  token_count: number
+  created_at: number
+}
+
+// ─── Internal events (delegation fan-in, etc.) ────────────────────────────────
+//
+// These are system-authored turns (async delegation outcomes) that must reach
+// the model as input but must never be persisted with role:"system" — doing so
+// causes every LLM provider to hoist them permanently into the system
+// instruction on every subsequent turn (see gemini.ts/anthropic.ts, which
+// concatenate ALL role:"system" messages into systemInstruction/system). They
+// are persisted as role:"user" + a source tag instead, and wrapped with a
+// framing marker only at serialization time (toAPIMessages), so stored content
+// stays clean and the wording can evolve without a migration.
+
+export const INTERNAL_SOURCES: ReadonlySet<string> =
+  new Set(["task_complete", "delegation_summary", "legacy_internal"])
+
+export function isInternalSource(source: string | null | undefined): boolean {
+  return !!source && INTERNAL_SOURCES.has(source)
+}
+
+export function formatInternalEvent(source: string, content: string): string {
+  return `<hive:internal_event source="${source}">\n` +
+    `Evento interno del sistema — NO es un mensaje del usuario. No lo cites literalmente, no expongas IDs internos (task_id, worker_id) ni JSON crudo. Respondé al usuario de forma natural y breve.\n\n` +
+    `${content}\n` +
+    `</hive:internal_event>`
+}
+
+function storageId(threadId: string, seq: number): string {
+  return `${threadId}:${String(seq).padStart(15, "0")}`
+}
+
+function toStoredMessage(id: string, doc: ConversationDoc): StoredMessage {
+  const seq = parseInt(id.slice(id.lastIndexOf(":") + 1), 10)
+  // Legacy rows (written before `source` existed) used role:"system" as the
+  // sole marker for internal events. Normalize them here so every downstream
+  // reader (getRecentMessages, compaction, context-compiler) sees a single
+  // consistent shape and never has to special-case role:"system" again.
+  const legacyInternal = doc.role === "system"
+  return {
+    id: seq,
+    thread_id: doc.thread_id,
+    channel: doc.channel,
+    role: legacyInternal ? "user" : (doc.role as StoredMessage["role"]),
+    source: doc.source ?? (legacyInternal ? "legacy_internal" : "message"),
+    content: doc.content,
+    tool_calls_json: doc.tool_calls_json,
+    tool_call_id: doc.tool_call_id,
+    reasoning_content: doc.reasoning_content,
+    content_multimodal: doc.content_multimodal,
+    token_count: doc.token_count,
+    created_at: doc.created_at,
+  }
+}
+
+// ─── Message operations ───────────────────────────────────────────────────────
+
+const recentMessageTimestamps: number[] = []
+
+export function getRecentMessageCount(windowMs = 5 * 60_000): number {
+  const cutoff = Date.now() - windowMs
+  while (recentMessageTimestamps.length && recentMessageTimestamps[0] < cutoff) {
+    recentMessageTimestamps.shift()
+  }
+  return recentMessageTimestamps.length
+}
+
+export async function addMessage(
+  threadId: string,
+  role: StoredMessage["role"],
+  content: string | ContentPart[],
+  opts?: {
+    channel?: string
+    tool_calls?: LLMMessage["tool_calls"]
+    tool_call_id?: string
+    reasoning_content?: string
+    source?: MessageSource
+  }
+): Promise<number> {
+  // Handle multimodal content by extracting text for the content column
+  const textContent = typeof content === "string"
+    ? content
+    : Array.isArray(content)
+      ? content.filter(p => p.type === "text").map(p => (p as any).text).join("\n")
+      : String(content)
+
+  const content_multimodal = Array.isArray(content) ? JSON.stringify(content) : null
+  const tool_calls_json = opts?.tool_calls ? JSON.stringify(opts.tool_calls) : null
+
+  const paddedSeq = await nextId(`conversations:${threadId}`)
+  const seq = parseInt(paddedSeq, 10)
+  const now = Date.now()
+
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  await conversationsCol.put(storageId(threadId, seq), {
+    id: storageId(threadId, seq),
+    thread_id: threadId,
+    channel: opts?.channel ?? "webchat",
+    role,
+    content: textContent,
+    content_multimodal,
+    tool_calls_json,
+    tool_call_id: opts?.tool_call_id ?? null,
+    reasoning_content: opts?.reasoning_content ?? null,
+    source: opts?.source ?? "message",
+    // Estimate tokens: content + tool_calls JSON
+    token_count: Math.max(1, estimateTokens(textContent) + estimateTokens(tool_calls_json ?? "")),
+    created_at: now,
+    updated_at: now,
+  }, { expectedVersion: 0 })
+
+  // Fire-and-forget — never block message persistence on the activity chart rollup.
+  const hour = new Date(now).toISOString().slice(0, 13)
+  bumpRollup("activityRollups", hour, { messageCount: 1 }).catch(() => {})
+  recentMessageTimestamps.push(now)
+
+  return seq
+}
+
+/**
+ * Returns all messages for the thread ordered oldest → newest.
+ */
+export async function getHistory(threadId: string, limit = 200): Promise<StoredMessage[]> {
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  const entries = await conversationsCol.scan({ prefix: `${threadId}:`, limit })
+  return entries.map(e => toStoredMessage(e.id, e.doc))
+}
+
+/**
+ * Returns only the last N messages (oldest → newest order),
+ * with leading orphaned tool messages stripped from the window start.
+ *
+ * A tool message is "orphaned" when the assistant message that issued its
+ * tool_call_id is not present in the loaded window (it was compacted away).
+ * Sending orphaned tool messages to the LLM causes provider errors.
+ */
+export async function getRecentMessages(threadId: string, n: number): Promise<StoredMessage[]> {
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  const entries = await conversationsCol.scan({ prefix: `${threadId}:`, reverse: true })
+  const nonTool = entries.filter(e => e.doc.role !== "tool").slice(0, n)
+  const rows = nonTool.map(e => toStoredMessage(e.id, e.doc)).reverse()
+  return stripLeadingOrphanedTools(rows)
+}
+
+function stripLeadingOrphanedTools(rows: StoredMessage[]): StoredMessage[] {
+  // Collect all tool_call_ids referenced by assistant messages in this window
+  const knownIds = new Set<string>()
+  for (const r of rows) {
+    if (r.role === "assistant" && r.tool_calls_json) {
+      try {
+        const tcs = JSON.parse(r.tool_calls_json) as Array<{ id: string }>
+        for (const tc of tcs) knownIds.add(tc.id)
+      } catch { /* ignore malformed JSON */ }
+    }
+  }
+
+  // Drop tool messages at the start of the window whose assistant is missing
+  let start = 0
+  while (
+    start < rows.length &&
+    rows[start].role === "tool" &&
+    rows[start].tool_call_id !== null &&
+    !knownIds.has(rows[start].tool_call_id!)
+  ) {
+    start++
+  }
+
+  if (start > 0) {
+    log.warn(`[conv-store] Stripped ${start} leading orphaned tool message(s) from window (tool_call_ids outside window)`)
+  }
+  return start > 0 ? rows.slice(start) : rows
+}
+
+export async function getMessageCount(threadId: string): Promise<number> {
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  const entries = await conversationsCol.scan({ prefix: `${threadId}:` })
+  return entries.length
+}
+
+export async function getTotalTokens(threadId: string): Promise<number> {
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  const entries = await conversationsCol.scan({ prefix: `${threadId}:` })
+  return entries.reduce((sum, e) => sum + e.doc.token_count, 0)
+}
+
+/**
+ * Messages after a given message ID (for incremental summary updates).
+ */
+export async function getMessagesAfter(threadId: string, afterId: number): Promise<StoredMessage[]> {
+  const conversationsCol = await col<ConversationDoc>("conversations")
+  const entries = await conversationsCol.scan({ prefix: `${threadId}:` })
+  return entries
+    .map(e => toStoredMessage(e.id, e.doc))
+    .filter(m => m.id > afterId)
+}
+
+// ─── Convert stored messages → LLMMessage array ───────────────────────────────
+
+export function toAPIMessages(rows: StoredMessage[]): LLMMessage[] {
+  return rows.map((r) => {
+    let content: string | ContentPart[] = r.content
+    if (r.content_multimodal) {
+      try { content = JSON.parse(r.content_multimodal) } catch { /* ignore */ }
+    }
+    // Internal events (delegation fan-in) are wrapped at serialization time —
+    // never at authoring time — so stored content stays clean and legacy rows
+    // (normalized to source:"legacy_internal" in toStoredMessage) get wrapped
+    // for free. Internal events are never multimodal in practice.
+    if (isInternalSource(r.source) && typeof content === "string") {
+      content = formatInternalEvent(r.source, content)
+    }
+    const msg: LLMMessage = { role: r.role, content }
+    // Note: tool_calls and tool_call_id are NOT reconstructed from DB.
+    // Tool results are kept in-memory during iteration but not persisted,
+    // so historical messages only contain text conversation.
+    if (r.reasoning_content) msg.reasoning_content = r.reasoning_content
+    return msg
+  })
+}
+
+// ─── Summaries ────────────────────────────────────────────────────────────────
+
+export interface Summary {
+  summary: string
+  last_message_id: number
+  messages_covered: number
+}
+
+export async function getSummary(threadId: string): Promise<Summary | null> {
+  const summariesCol = await col<SummaryDoc>("summaries")
+  const entry = await summariesCol.get(threadId)
+  if (!entry) return null
+  return {
+    summary: entry.doc.summary,
+    last_message_id: entry.doc.last_message_id ? parseInt(entry.doc.last_message_id, 10) : 0,
+    messages_covered: entry.doc.messages_covered,
+  }
+}
+
+export async function saveSummary(
+  threadId: string,
+  summary: string,
+  messagesCovered: number,
+  lastMessageId: number
+): Promise<void> {
+  const summariesCol = await col<SummaryDoc>("summaries")
+  const existing = await summariesCol.get(threadId)
+  await summariesCol.put(threadId, {
+    thread_id: threadId,
+    summary,
+    messages_covered: messagesCovered,
+    last_message_id: String(lastMessageId),
+  }, existing ? { expectedVersion: existing.version } : { expectedVersion: 0 })
+}
+
+// ─── Scratchpad (HiveDB collection) ────────────────────────────────────────────
+//
+// Persistent key-value notes per conversation. Lives in a HiveDB document
+// collection instead of SQLite: id = "<threadId>:<key>", so a per-thread
+// listing is a prefix scan and no secondary index is needed.
+
+export interface ScratchpadDoc {
+  threadId: string
+  key: string
+  value: string
+  source: string | null
+  createdAt: number
+  updatedAt: number
+  /** Monotonic per-process counter — tiebreaker for notes saved within the same clock tick. */
+  seq: number
+}
+
+let scratchpadSeq = 0
+
+/** Wire shape for the admin notes panel — mirrors the old SQLite row (snake_case, epoch seconds). */
+export interface ScratchpadNoteRow {
+  id: string
+  thread_id: string
+  key: string
+  value: string
+  source: string | null
+  created_at: number
+  updated_at: number
+}
+
+function scratchpadNoteId(threadId: string, key: string): string {
+  return `${threadId}:${key}`
+}
+
+async function scratchpadCollection() {
+  const db = await getHiveDb()
+  return db.collection<ScratchpadDoc>("scratchpad")
+}
+
+export async function saveScratchpadNote(
+  threadId: string,
+  key: string,
+  value: string,
+  source?: string
+): Promise<void> {
+  const col = await scratchpadCollection()
+  const id = scratchpadNoteId(threadId, key)
+  const existing = await col.get(id)
+  const now = Date.now()
+  await col.put(id, {
+    threadId,
+    key,
+    value,
+    source: source ?? null,
+    createdAt: existing?.doc.createdAt ?? now,
+    updatedAt: now,
+    seq: scratchpadSeq++,
+  })
+}
+
+function byMostRecent(a: { doc: ScratchpadDoc }, b: { doc: ScratchpadDoc }): number {
+  return b.doc.updatedAt - a.doc.updatedAt || b.doc.seq - a.doc.seq
+}
+
+export async function getScratchpad(threadId: string): Promise<Array<{ key: string; value: string }>> {
+  const col = await scratchpadCollection()
+  const entries = await col.scan({ prefix: `${threadId}:` })
+  return entries
+    .sort(byMostRecent)
+    .map((e) => ({ key: e.doc.key, value: e.doc.value }))
+}
+
+/** All notes across every thread, most recently updated first — used by the admin notes panel. */
+export async function listAllScratchpadNotes(limit: number): Promise<ScratchpadNoteRow[]> {
+  const col = await scratchpadCollection()
+  const entries = await col.scan({})
+  return entries
+    .sort(byMostRecent)
+    .slice(0, limit)
+    .map((e) => ({
+      id: e.id,
+      thread_id: e.doc.threadId,
+      key: e.doc.key,
+      value: e.doc.value,
+      source: e.doc.source,
+      created_at: Math.floor(e.doc.createdAt / 1000),
+      updated_at: Math.floor(e.doc.updatedAt / 1000),
+    }))
+}
+
+export async function deleteScratchpadNote(threadId: string, key: string): Promise<void> {
+  const col = await scratchpadCollection()
+  await col.delete(scratchpadNoteId(threadId, key))
+}

package/packages/core/src/agent/curator.ts

@@ -0,0 +1,276 @@
+/**
+ * ACE Curator — converts reflections into playbook rules.
+ *
+ * Runs after the Reflector. Performs incremental edits to the playbook:
+ *   - New insights → new rules
+ *   - Repeated patterns → increment helpful_count
+ *   - Contradicted rules → increment harmful_count or deactivate
+ *   - Deactivate rules where harmful_count > helpful_count
+ *
+ * Never rewrites the whole playbook — only incremental edits.
+ *
+ * "Last processed reflection" is tracked via a `cursors` collection doc
+ * (id="curator:lastReflection") instead of SQL's MAX(source_reflection_id).
+ */
+
+import { logger } from "../utils/logger"
+import { col, nextId, toIndexable, fromIndexable } from "../storage/hive"
+import type {
+  ReflectionDoc,
+  PlaybookDoc,
+  AgentDoc,
+  CursorDoc,
+  AgentProposalDoc,
+  TraceDoc,
+} from "../storage/collections"
+
+const log = logger.child("curator")
+
+const MAX_HARMFUL_BEFORE_PRUNE = 3
+const CURSOR_ID = "curator:lastReflection"
+
+/** Entry point — called by reflector.ts after it inserts new reflections */
+export async function runCurator(): Promise<void> {
+  try {
+    const cursorsCol = await col<CursorDoc>("cursors")
+    const playbookCol = await col<PlaybookDoc>("playbook")
+    const reflectionsCol = await col<ReflectionDoc>("reflections")
+    // Process unprocessed reflections (those newer than last run)
+    const cursorEntry = await cursorsCol.get(CURSOR_ID)
+    const lastProcessed = cursorEntry?.doc.value ?? null
+
+    let candidates = lastProcessed
+      ? await reflectionsCol.scan({ start: lastProcessed })
+      : await reflectionsCol.scan({})
+    if (lastProcessed && candidates[0]?.id === lastProcessed) candidates = candidates.slice(1)
+
+    if (candidates.length === 0) {
+      log.debug("[curator] No new reflections to process")
+    } else {
+      log.info(`[curator] Processing ${candidates.length} new reflections`)
+      const allPlaybook = await playbookCol.scan({})
+      for (const entry of candidates) {
+        await processReflection(playbookCol, allPlaybook, entry.doc)
+      }
+      const newCursor = candidates[candidates.length - 1].id
+      await cursorsCol.put(CURSOR_ID, { value: newCursor }, cursorEntry ? { expectedVersion: cursorEntry.version } : { expectedVersion: 0 })
+    }
+
+    // Prune rules where harmful > helpful (consistently bad rules)
+    const allActive = (await playbookCol.scan({})).filter(e => e.doc.active)
+    for (const entry of allActive) {
+      if (entry.doc.harmful_count > entry.doc.helpful_count && entry.doc.harmful_count >= MAX_HARMFUL_BEFORE_PRUNE) {
+        await playbookCol.put(entry.id, { ...entry.doc, active: false, updated_at: Date.now() }, { expectedVersion: entry.version })
+      }
+    }
+
+    await curateAgentStructure()
+
+    log.info("[curator] Playbook updated")
+  } catch (err) {
+    log.warn("[curator] Error:", err)
+  }
+}
+
+async function curateAgentStructure(): Promise<void> {
+  const agentsCol = await col<AgentDoc>("agents")
+  const proposalsCol = await col<AgentProposalDoc>("agentProposals")
+  const tracesCol = await col<TraceDoc>("traces")
+  const now = Date.now()
+
+  // A catalog agent is a capability, not a disposable worker: disabling
+  // `workspace_file_operator` takes filesystem work away from the whole hive
+  // and nothing replaces it, so a bad streak can never switch one off by
+  // itself. It raises a proposal for a human to decide instead — and the ACE
+  // counters keep accumulating either way, so routing still sees the signal.
+  for (const entry of await agentsCol.findBy("source", "catalog")) {
+    if (!entry.doc.enabled) continue
+    const helpful = entry.doc.helpful_count ?? 0
+    const harmful = entry.doc.harmful_count ?? 0
+    if (harmful > helpful && harmful >= MAX_HARMFUL_BEFORE_PRUNE) {
+      await ensureAgentProposal(proposalsCol, {
+        type: "disable_agent",
+        agentId: entry.id,
+        change: { active: false, reason: "harmful_count exceeded helpful_count" },
+        evidence: [],
+        confidence: 1,
+      })
+      log.warn(`[curator] Catalog agent '${entry.doc.name}' (${entry.id}) is failing verification (helpful=${helpful}, harmful=${harmful}) — proposed for review, left enabled`)
+    }
+  }
+
+  const traces = (await tracesCol.scan({})).map((entry) => entry.doc)
+  const agents = new Map((await agentsCol.scan({})).map((entry) => [entry.id, entry.doc]))
+
+  // Recurrent successful free workers are candidates for a learned template.
+  const freeSuccess = new Map<string, TraceDoc[]>()
+  for (const trace of traces) {
+    const agent = agents.get(trace.agent_id)
+    if (!trace.success || trace.tool_used || trace.catalog_agent_id || agent?.role !== "worker" || agent.source === "catalog") continue
+    const bucket = freeSuccess.get(trace.agent_id) ?? []
+    bucket.push(trace)
+    freeSuccess.set(trace.agent_id, bucket)
+  }
+  for (const [agentId, evidence] of freeSuccess) {
+    if (evidence.length < 5) continue
+    const agent = agents.get(agentId)!
+    await ensureAgentProposal(proposalsCol, {
+      type: "create_agent",
+      agentId: `candidate:${agentId}`,
+      change: {
+        suggested_name: agent.name,
+        suggested_description: agent.description,
+        observed_tasks: evidence.slice(-5).map((trace) => trace.input_summary),
+      },
+      evidence: evidence.slice(-5).map((trace) => trace.id),
+      confidence: Math.min(0.95, 0.5 + evidence.length * 0.05),
+    })
+  }
+
+  // Repeated failures identify a loadout mismatch. This remains a proposal;
+  // permissions are never changed automatically.
+  const failures = new Map<string, TraceDoc[]>()
+  for (const trace of traces) {
+    if (trace.success || !trace.catalog_agent_id || !trace.tool_used) continue
+    const key = `${trace.catalog_agent_id}\0${trace.tool_used}`
+    const bucket = failures.get(key) ?? []
+    bucket.push(trace)
+    failures.set(key, bucket)
+  }
+  for (const [key, evidence] of failures) {
+    if (evidence.length < 3) continue
+    const [agentId, tool] = key.split("\0")
+    await ensureAgentProposal(proposalsCol, {
+      type: "move_tool",
+      agentId,
+      change: { tool, reason: "repeated failures; review ownership or remove from loadout" },
+      evidence: evidence.slice(-10).map((trace) => trace.id),
+      confidence: Math.min(0.95, 0.55 + evidence.length * 0.05),
+    })
+  }
+
+  const { syncCatalogAgentsToIndex } = await import("./catalog-selector")
+  await syncCatalogAgentsToIndex()
+}
+
+async function ensureAgentProposal(
+  proposalsCol: Awaited<ReturnType<typeof col<AgentProposalDoc>>>,
+  input: {
+    type: AgentProposalDoc["type"]
+    agentId: string
+    change: unknown
+    evidence: string[]
+    confidence: number
+  },
+): Promise<void> {
+  const existing = (await proposalsCol.findBy("agent_id", input.agentId))
+    .find((entry) => entry.doc.type === input.type && entry.doc.status === "proposed")
+  if (existing) return
+  const id = await nextId("agentProposals")
+  const now = Date.now()
+  await proposalsCol.put(id, {
+    id,
+    type: input.type,
+    agent_id: input.agentId,
+    proposed_change_json: JSON.stringify(input.change),
+    evidence_trace_ids_json: JSON.stringify(input.evidence),
+    confidence: input.confidence,
+    status: "proposed",
+    created_at: now,
+    updated_at: now,
+  }, { expectedVersion: 0 })
+}
+
+// ─── Process a single reflection ─────────────────────────────────────────────
+
+async function processReflection(
+  playbookCol: Awaited<ReturnType<typeof col<PlaybookDoc>>>,
+  allPlaybook: Array<{ id: string; version: number; doc: PlaybookDoc }>,
+  reflection: ReflectionDoc
+): Promise<void> {
+  const category = mapInsightTypeToCategory(reflection.insight_type)
+  const applicable: string[] = reflection.affected_tools ? JSON.parse(reflection.affected_tools) : []
+  if (reflection.affected_agents) {
+    const agentsCol = await col<AgentDoc>("agents")
+    for (const agentId of JSON.parse(reflection.affected_agents) as string[]) {
+      const agent = await agentsCol.get(agentId)
+      if (agent?.doc.source === "catalog") applicable.push(`agent:${agent.doc.id}`)
+    }
+  }
+  const applicableTo = applicable.length ? JSON.stringify([...new Set(applicable)]) : null
+
+  // Check if a similar rule already exists (fuzzy check by first 60 chars)
+  const prefix = reflection.description.substring(0, 60)
+  const existing = allPlaybook.find(e => e.doc.active && e.doc.rule.startsWith(prefix))
+
+  if (existing) {
+    // Reinforce existing rule
+    await playbookCol.put(existing.id, { ...existing.doc, helpful_count: existing.doc.helpful_count + 1, updated_at: Date.now() }, { expectedVersion: existing.version })
+    return
+  }
+
+  // Insert new rule
+  const id = await nextId("playbook")
+  const now = Date.now()
+  await playbookCol.put(id, {
+    id,
+    rule: reflection.description,
+    category,
+    applicable_to: applicableTo,
+    helpful_count: 1,
+    harmful_count: 0,
+    active: true,
+    source_reflection_id: toIndexable(reflection.id),
+    created_at: now,
+    updated_at: now,
+  }, { expectedVersion: 0 })
+  allPlaybook.push({ id, version: 1, doc: { id, rule: reflection.description, category, applicable_to: applicableTo, helpful_count: 1, harmful_count: 0, active: true, source_reflection_id: toIndexable(reflection.id), created_at: now, updated_at: now } })
+}
+
+function mapInsightTypeToCategory(
+  type: string
+): "tool_selection" | "response_quality" | "error_avoidance" | "optimization" | "agent_creation" {
+  const map: Record<string, any> = {
+    success_pattern: "tool_selection",
+    failure_pattern: "error_avoidance",
+    optimization: "optimization",
+    ethics_violation: "error_avoidance",
+    // G9 evaluateHarness() insights (reflector.ts's analyzeCausalThreads)
+    root_cause: "error_avoidance",
+    learning_proposal: "response_quality",
+  }
+  return map[type] ?? "optimization"
+}
+
+async function addOrUpdateRule(
+  playbookCol: Awaited<ReturnType<typeof col<PlaybookDoc>>>,
+  allPlaybook: Array<{ id: string; version: number; doc: PlaybookDoc }>,
+  opts: {
+    rule: string
+    category: string
+    applicable_to: string | null
+    sourceReflectionId: string | null
+  }
+): Promise<void> {
+  const prefix = opts.rule.substring(0, 60)
+  const existing = allPlaybook.find(e => e.doc.rule.startsWith(prefix))
+
+  if (existing) {
+    await playbookCol.put(existing.id, { ...existing.doc, helpful_count: existing.doc.helpful_count + 1, updated_at: Date.now() }, { expectedVersion: existing.version })
+  } else {
+    const id = await nextId("playbook")
+    const now = Date.now()
+    await playbookCol.put(id, {
+      id,
+      rule: opts.rule,
+      category: opts.category as PlaybookDoc["category"],
+      applicable_to: opts.applicable_to,
+      helpful_count: 1,
+      harmful_count: 0,
+      active: true,
+      source_reflection_id: toIndexable(opts.sourceReflectionId),
+      created_at: now,
+      updated_at: now,
+    }, { expectedVersion: 0 })
+  }
+}