@johpaz/hive-sdk 0.0.12 → 0.0.15

package/packages/core/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hive/core",
+  "version": "0.0.15",
+  "description": "Hive Core — Agentes AI con Context Engineering, FTS5, ACE, Swarm",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent/index.ts",
+    "./agent/providers": "./src/agent/providers/index.ts",
+    "./agent/selectors": "./src/agent/selectors/index.ts",
+    "./tools": "./src/tools/index.ts",
+    "./skills": "./src/skills/index.ts",
+    "./storage": "./src/storage/index.ts",
+    "./swarm": "./src/swarm/index.ts",
+    "./swarm/strategies": "./src/swarm/strategies/index.ts",
+    "./swarm/presets": "./src/swarm/presets/index.ts",
+    "./ace": "./src/ace/index.ts",
+    "./ethics": "./src/ethics/index.ts",
+    "./canvas": "./src/canvas/index.ts",
+    "./config": "./src/config/index.ts",
+    "./mcp": "./src/mcp/index.ts",
+    "./mcp/transports": "./src/mcp/transports/index.ts",
+    "./memory": "./src/memory/index.ts",
+    "./multimodal": "./src/multimodal/index.ts",
+    "./security": "./src/security/index.ts",
+    "./state": "./src/state/index.ts",
+    "./utils": "./src/utils/index.ts",
+    "./gateway": "./src/gateway/index.ts",
+    "./api": "./src/api/index.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@google/genai": "^1.43.0",
+    "@modelcontextprotocol/sdk": "latest",
+    "@sapphire/snowflake": "latest",
+    "async-mutex": "^0.5.0",
+    "cron-parser": "^5.5.0",
+    "croner": "^10.0.1",
+    "docx": "^9.6.1",
+    "groq-sdk": "^0.37.0",
+    "jszip": "^3.10.1",
+    "pdf-lib": "^1.17.1",
+    "mammoth": "^1.12.0",
+    "ollama": "^0.6.3",
+    "openai": "^6.18.0",
+    "pdfjs-dist": "^5.6.205",
+    "pptxgenjs": "^4.0.1",
+    "toon-format-parser": "^1.1.0",
+    "xlsx": "^0.18.5",
+    "zod": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/packages/core/src/ace/Curator.ts

@@ -0,0 +1,158 @@
+/**
+ * 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
+ *   - Archive unused workers
+ *
+ * Never rewrites the whole playbook — only incremental edits.
+ */
+
+import { logger } from "../utils/logger.ts"
+
+const log = logger.child("curator")
+
+const DAYS_BEFORE_ARCHIVE = 14   // archive workers not used in N days
+const MAX_HARMFUL_BEFORE_PRUNE = 3
+
+/** Entry point — called by reflector.ts after it inserts new reflections */
+export async function runCurator(): Promise<void> {
+  try {
+    const { getDb } = await import("../storage/SQLiteStorage.ts")
+    const db = getDb()
+
+    // Process unprocessed reflections (those newer than last run)
+    const lastProcessed = (db.query<any, []>(
+      "SELECT COALESCE(MAX(source_reflection_id), 0) as mid FROM playbook"
+    ).get() as any)?.mid ?? 0
+
+    const reflections = (db.query as any)(
+      "SELECT * FROM reflections WHERE id > ? ORDER BY id ASC"
+    ).all(lastProcessed)
+
+    if (reflections.length === 0) {
+      log.debug("[curator] No new reflections to process")
+    } else {
+      log.info(`[curator] Processing ${reflections.length} new reflections`)
+      for (const reflection of reflections) {
+        processReflection(db, reflection)
+      }
+    }
+
+    // Prune rules where harmful > helpful (consistently bad rules)
+    db.query(`
+      UPDATE playbook
+      SET active = 0, updated_at = unixepoch()
+      WHERE active = 1
+        AND harmful_count > helpful_count
+        AND harmful_count >= ?
+    `).run(MAX_HARMFUL_BEFORE_PRUNE)
+
+    // Archive unused workers
+    const cutoff = Math.floor(Date.now() / 1000) - (DAYS_BEFORE_ARCHIVE * 86400)
+    const staleworkers = (db.query as any)(`
+      SELECT a.id, a.name
+      FROM agents a
+      WHERE a.role = 'worker'
+        AND a.status != 'archived'
+        AND a.enabled = 1
+        AND (
+          SELECT MAX(t.created_at) FROM traces t WHERE t.agent_id = a.id
+        ) < ?
+    `).all(cutoff)
+
+    for (const worker of staleworkers) {
+      db.query(
+        "UPDATE agents SET status = 'archived', updated_at = unixepoch() WHERE id = ?"
+      ).run(worker.id)
+
+      // Add playbook note about archival
+      addOrUpdateRule(db, {
+        rule: `Worker '${worker.name}' was archived due to inactivity (>${DAYS_BEFORE_ARCHIVE} days unused).`,
+        category: "agent_creation",
+        applicable_to: null,
+        sourceReflectionId: null,
+      })
+
+      log.info(`[curator] Archived inactive worker: ${worker.name} (${worker.id})`)
+    }
+
+    log.info("[curator] Playbook updated")
+  } catch (err) {
+    log.warn("[curator] Error:", err)
+  }
+}
+
+// ─── Process a single reflection ─────────────────────────────────────────────
+
+function processReflection(db: any, reflection: any): void {
+  const category = mapInsightTypeToCategory(reflection.insight_type)
+
+  // Check if a similar rule already exists (fuzzy check by first 60 chars)
+  const prefix = reflection.description.substring(0, 60)
+  const existing = (db.query as any)(
+    "SELECT id, helpful_count FROM playbook WHERE rule LIKE ? AND active = 1 LIMIT 1"
+  ).get(`${prefix}%`)
+
+  if (existing) {
+    // Reinforce existing rule
+    db.query(
+      "UPDATE playbook SET helpful_count = helpful_count + 1, updated_at = unixepoch() WHERE id = ?"
+    ).run(existing.id)
+    return
+  }
+
+  // Insert new rule
+  db.query(`
+    INSERT INTO playbook (rule, category, applicable_to, helpful_count, source_reflection_id)
+    VALUES (?, ?, ?, 1, ?)
+  `).run(
+    reflection.description,
+    category,
+    reflection.affected_tools
+      ? JSON.stringify(JSON.parse(reflection.affected_tools))
+      : null,
+    reflection.id,
+  )
+}
+
+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",
+  }
+  return map[type] ?? "optimization"
+}
+
+function addOrUpdateRule(
+  db: any,
+  opts: {
+    rule: string
+    category: string
+    applicable_to: string | null
+    sourceReflectionId: number | null
+  }
+): void {
+  const prefix = opts.rule.substring(0, 60)
+  const existing = (db.query as any)(
+    "SELECT id FROM playbook WHERE rule LIKE ? LIMIT 1"
+  ).get(`${prefix}%`)
+
+  if (existing) {
+    db.query(
+      "UPDATE playbook SET helpful_count = helpful_count + 1, updated_at = unixepoch() WHERE id = ?"
+    ).run(existing.id)
+  } else {
+    db.query(`
+      INSERT INTO playbook (rule, category, applicable_to, helpful_count, source_reflection_id)
+      VALUES (?, ?, ?, 1, ?)
+    `).run(opts.rule, opts.category, opts.applicable_to, opts.sourceReflectionId)
+  }
+}

package/packages/core/src/ace/Reflector.ts

@@ -0,0 +1,200 @@
+/**
+ * ACE Reflector — analyzes recent traces and produces insights.
+ *
+ * Runs in the background (never blocks the main agent loop).
+ * Triggered by the tracer after N new traces.
+ *
+ * Output → `reflections` table → picked up by Curator.
+ */
+
+import { logger } from "../utils/logger.ts"
+
+const log = logger.child("reflector")
+
+const MAX_TRACES_TO_ANALYZE = 30
+const MIN_TRACES_TO_RUN = 10
+
+/** Main entry point — called from tracer.ts */
+export async function runReflector(): Promise<void> {
+  try {
+    const { getDb } = await import("../storage/SQLiteStorage.ts")
+    const db = getDb()
+
+    log.info(`[reflector] Starting reflection cycle...`)
+
+    // Fetch traces not yet covered by any reflection
+    log.debug(`[reflector] Querying last reflection ID...`)
+    const lastReflectionId = (db.query<any, []>(
+      "SELECT MAX(id) as mid FROM reflections"
+    ).get() as any)?.mid ?? 0
+    log.debug(`[reflector] Last reflection ID: ${lastReflectionId}`)
+
+    // Get last processed trace ID from reflections
+    log.debug(`[reflector] Querying last processed trace ID with json_each...`)
+    let lastProcessedTrace = 0
+    try {
+      const result = (db.query<any, []>(
+        `SELECT MAX(CAST(json_each.value AS INTEGER)) as max_id
+         FROM reflections, json_each(reflections.trace_ids)
+         WHERE reflections.id = (SELECT MAX(id) FROM reflections)`
+      ).get() as any)?.max_id ?? 0
+      lastProcessedTrace = result
+      log.debug(`[reflector] Last processed trace ID: ${lastProcessedTrace}`)
+    } catch (jsonErr) {
+      log.error(`[reflector] json_each query failed:`, jsonErr)
+      log.error(`[reflector] Full error details:`, {
+        message: (jsonErr as Error).message,
+        stack: (jsonErr as Error).stack,
+        errno: (jsonErr as any).errno,
+        byteOffset: (jsonErr as any).byteOffset,
+      })
+      throw jsonErr // Re-throw to see full stack trace in main catch
+    }
+
+    log.debug(`[reflector] Fetching traces from DB, lastProcessedTrace=${lastProcessedTrace}, limit=${MAX_TRACES_TO_ANALYZE}`)
+    const traces = db.query<any, [number, number]>(`
+      SELECT id, agent_id, agent_name, tool_used, input_summary,
+             output_summary, success, error_message, duration_ms, tokens_used, created_at
+      FROM traces
+      WHERE id > ?
+      ORDER BY id ASC
+      LIMIT ?
+    `).all(lastProcessedTrace, MAX_TRACES_TO_ANALYZE)
+
+    log.debug(`[reflector] Fetched ${traces.length} traces from DB`)
+
+    if (traces.length < MIN_TRACES_TO_RUN) {
+      log.debug(`[reflector] Not enough traces (${traces.length}/${MIN_TRACES_TO_RUN}), skipping`)
+      return
+    }
+
+    log.info(`[reflector] Analyzing ${traces.length} traces...`)
+
+    const insights = analyzeTracesLocally(traces)
+
+    if (insights.length === 0) {
+      log.debug("[reflector] No insights generated")
+      return
+    }
+
+    const traceIds = JSON.stringify(traces.map((t: any) => t.id))
+
+    for (const insight of insights) {
+      db.query(`
+        INSERT INTO reflections (trace_ids, insight_type, description, affected_tools, affected_agents, confidence)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(
+        traceIds,
+        insight.type,
+        insight.description,
+        insight.affectedTools ? JSON.stringify(insight.affectedTools) : null,
+        insight.affectedAgents ? JSON.stringify(insight.affectedAgents) : null,
+        insight.confidence,
+      )
+    }
+
+    log.info(`[reflector] Generated ${insights.length} insights`)
+
+    // Trigger curator
+    const { runCurator } = await import("./Curator.ts")
+    await runCurator()
+    
+    log.info(`[reflector] Reflection cycle completed successfully`)
+  } catch (err) {
+    log.error(`[reflector] Error during reflection:`, {
+      message: (err as Error).message,
+      stack: (err as Error).stack,
+      errno: (err as any).errno,
+      byteOffset: (err as any).byteOffset,
+      code: (err as any).code,
+    })
+  }
+}
+
+// ─── Local analysis (heuristic, no LLM call needed for basic patterns) ────────
+
+interface Insight {
+  type: "success_pattern" | "failure_pattern" | "optimization" | "ethics_violation"
+  description: string
+  affectedTools?: string[]
+  affectedAgents?: string[]
+  confidence: number
+}
+
+function analyzeTracesLocally(traces: any[]): Insight[] {
+  const insights: Insight[] = []
+
+  // ── Failure patterns ─────────────────────────────────────────────────────
+  const failures = traces.filter((t: any) => !t.success)
+  if (failures.length > 3) {
+    // Group by tool
+    const toolFailures: Record<string, number> = {}
+    for (const f of failures) {
+      if (f.tool_used) {
+        toolFailures[f.tool_used] = (toolFailures[f.tool_used] || 0) + 1
+      }
+    }
+    for (const [tool, count] of Object.entries(toolFailures)) {
+      if (count >= 3) {
+        insights.push({
+          type: "failure_pattern",
+          description: `Tool '${tool}' failed ${count} times recently. Consider verifying its configuration or avoiding it for this type of task.`,
+          affectedTools: [tool],
+          confidence: Math.min(0.9, count / 10),
+        })
+      }
+    }
+  }
+
+  // ── Slow tools ───────────────────────────────────────────────────────────
+  const slowThresholdMs = 5000
+  const slowTools: Record<string, number[]> = {}
+  for (const t of traces) {
+    if (t.tool_used && t.duration_ms > slowThresholdMs) {
+      if (!slowTools[t.tool_used]) slowTools[t.tool_used] = []
+      slowTools[t.tool_used].push(t.duration_ms)
+    }
+  }
+  for (const [tool, durations] of Object.entries(slowTools)) {
+    if (durations.length >= 3) {
+      const avg = Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+      insights.push({
+        type: "optimization",
+        description: `Tool '${tool}' is consistently slow (avg ${avg}ms). Cache results when possible or use a faster alternative.`,
+        affectedTools: [tool],
+        confidence: 0.6,
+      })
+    }
+  }
+
+  // ── High success pattern ─────────────────────────────────────────────────
+  const successByTool: Record<string, { ok: number; total: number }> = {}
+  for (const t of traces) {
+    if (!t.tool_used) continue
+    if (!successByTool[t.tool_used]) successByTool[t.tool_used] = { ok: 0, total: 0 }
+    successByTool[t.tool_used].total++
+    if (t.success) successByTool[t.tool_used].ok++
+  }
+  for (const [tool, stats] of Object.entries(successByTool)) {
+    if (stats.total >= 5 && stats.ok / stats.total >= 0.9) {
+      insights.push({
+        type: "success_pattern",
+        description: `Tool '${tool}' has a high success rate (${stats.ok}/${stats.total}). Prefer it for related tasks.`,
+        affectedTools: [tool],
+        confidence: stats.ok / stats.total,
+      })
+    }
+  }
+
+  // ── High token usage ─────────────────────────────────────────────────────
+  const highTokenTraces = traces.filter((t: any) => t.tokens_used > 4000)
+  if (highTokenTraces.length > 3) {
+    insights.push({
+      type: "optimization",
+      description: `${highTokenTraces.length} recent calls used >4000 tokens. Be more concise and use tool results as summaries, not raw dumps.`,
+      confidence: 0.7,
+    })
+  }
+
+  return insights
+}

package/packages/core/src/ace/Tracer.ts

@@ -0,0 +1,100 @@
+/**
+ * Tracer — ACE Generator output.
+ *
+ * Records every agent execution to the `traces` table.
+ * Fire-and-forget (non-blocking). Also updates playbook helpful/harmful counts
+ * based on execution outcome.
+ */
+
+import { logger } from "../utils/logger.ts"
+
+const log = logger.child("tracer")
+
+export interface TraceInput {
+  threadId: string
+  agentId: string
+  agentName: string
+  toolUsed?: string | null
+  inputSummary: string
+  outputSummary: string
+  success: boolean
+  errorMessage?: string | null
+  durationMs?: number
+  tokensUsed?: number
+}
+
+/**
+ * Save a trace record. Non-blocking — errors are swallowed so they never
+ * affect the main agent loop.
+ */
+export function saveTrace(trace: TraceInput): void {
+  // Run asynchronously so it never blocks the caller
+  Promise.resolve().then(async () => {
+    try {
+      const { getDb } = await import("../storage/SQLiteStorage.ts")
+      const db = getDb()
+
+      db.query(`
+        INSERT INTO traces
+          (thread_id, agent_id, agent_name, tool_used, input_summary,
+           output_summary, success, error_message, duration_ms, tokens_used)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        trace.threadId,
+        trace.agentId,
+        trace.agentName,
+        trace.toolUsed ?? null,
+        trace.inputSummary.substring(0, 500),
+        trace.outputSummary.substring(0, 500),
+        trace.success ? 1 : 0,
+        trace.errorMessage ?? null,
+        trace.durationMs ?? null,
+        trace.tokensUsed ?? null,
+      )
+
+      // Trigger reflector check in background
+      checkReflectorTrigger().catch(() => { /* ignore */ })
+    } catch (err) {
+      log.warn("[tracer] Failed to save trace:", err)
+    }
+  })
+}
+
+// ─── Reflector trigger ────────────────────────────────────────────────────────
+
+const REFLECTOR_TRACE_THRESHOLD = 20  // run reflector after N new traces
+
+let _tracesSinceLastReflection = 0
+
+async function checkReflectorTrigger(): Promise<void> {
+  _tracesSinceLastReflection++
+  if (_tracesSinceLastReflection < REFLECTOR_TRACE_THRESHOLD) return
+  _tracesSinceLastReflection = 0
+
+  // Lazy import to avoid circular deps
+  const { runReflector } = await import("./Reflector.ts")
+  runReflector().catch((err) => {
+    log.warn("[tracer] Reflector run failed:", err)
+  })
+}
+
+// ─── Usage recording ──────────────────────────────────────────────────────────
+
+export function recordLLMUsage(opts: {
+  provider: string
+  model: string
+  inputTokens: number
+  outputTokens: number
+}): void {
+  Promise.resolve().then(async () => {
+    try {
+      const { recordUsage } = await import("../storage/usage.ts")
+      recordUsage({
+        provider: opts.provider,
+        model: opts.model,
+        inputTokens: opts.inputTokens,
+        outputTokens: opts.outputTokens,
+      })
+    } catch { /* ignore */ }
+  })
+}

package/packages/core/src/ace/index.ts

@@ -0,0 +1,4 @@
+export { runCurator } from "./Curator.ts";
+export { runReflector } from "./Reflector.ts";
+export type { TraceInput } from "./Tracer.ts";
+export { saveTrace } from "./Tracer.ts";