@johpaz/hive-sdk 0.1.4 → 0.1.5

package/packages/core/src/agent/llm-client.ts

@@ -0,0 +1,266 @@
+/**
+ * LLM client — direct official SDKs, no abstraction layers.
+ *
+ *   gemini / google  → native Gemini REST API (v1beta, ?key=)
+ *   anthropic        → @anthropic-ai/sdk
+ *   ollama           → ollama npm package
+ *   openai           → openai npm package
+ *   groq / mistral / openrouter / deepseek / kimi / nvidia / qwen
+ *                    → openai npm package (OpenAI-compatible endpoint, per-provider adapter)
+ *
+ * Public interface (LLMMessage, callLLM, resolveProviderConfig) is stable.
+ */
+
+import { logger } from "../utils/logger"
+import { loadConfig } from "../config/loader"
+import { withRetry, isRetryableError, type RetryPolicy } from "../resilience/retry"
+import { GeminiProvider } from "./llm-providers/gemini"
+import { AnthropicProvider } from "./llm-providers/anthropic"
+import { OllamaProvider } from "./llm-providers/ollama"
+import { OpenAIProvider } from "./llm-providers/openai"
+import { GroqProvider } from "./llm-providers/groq"
+import { MistralProvider } from "./llm-providers/mistral"
+import { OpenRouterProvider } from "./llm-providers/openrouter"
+import { DeepSeekProvider } from "./llm-providers/deepseek"
+import { KimiProvider } from "./llm-providers/kimi"
+import { NvidiaProvider } from "./llm-providers/nvidia"
+import { QwenProvider } from "./llm-providers/qwen"
+import { MiniMaxProvider } from "./llm-providers/minimax"
+import { OpenCodeGoProvider } from "./llm-providers/opencode-go"
+import { HiveAgentsProvider } from "./llm-providers/hiveagents"
+import { ZaiProvider } from "./llm-providers/z-ai"
+import { ModelScopeProvider } from "./llm-providers/modelscope"
+import type { LLMProvider } from "./llm-providers/interface"
+
+const log = logger.child("llm-client")
+
+// ─── Canonical types ───────────────────────────────────────────────────────────
+
+export interface LLMToolCall {
+  id: string
+  type: "function"
+  function: { name: string; arguments: string }
+  /** Gemini 3.x thought signature — must be round-tripped for tool-calling. */
+  thought_signature?: string
+}
+
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string } }
+  | { type: "image_base64"; base64: string; mimeType: string }
+  | { type: "document"; base64: string; mimeType: string; fileName?: string }
+
+/** Raw Anthropic extended-thinking content block, round-tripped verbatim (signature required by the API when tool_use follows). */
+export interface ThinkingBlock {
+  type: "thinking" | "redacted_thinking"
+  thinking?: string
+  signature?: string
+  data?: string
+}
+
+export interface LLMMessage {
+  role: "system" | "user" | "assistant" | "tool"
+  content: string | ContentPart[]
+  tool_calls?: LLMToolCall[]
+  tool_call_id?: string
+  name?: string
+  /** Kimi K2 thinking mode — must be round-tripped when tool calls are present. */
+  reasoning_content?: string
+  /** Anthropic extended thinking — must be round-tripped verbatim when tool calls are present. */
+  thinking_blocks?: ThinkingBlock[]
+}
+
+export interface LLMToolDef {
+  type: "function"
+  function: {
+    name: string
+    description: string
+    parameters: Record<string, unknown>
+  }
+}
+
+export interface LLMCallOptions {
+  provider: string
+  model: string
+  apiKey: string
+  baseUrl?: string
+  numCtx?: number
+  contextWindow?: number
+  messages: LLMMessage[]
+  tools?: LLMToolDef[]
+  temperature?: number
+  maxTokens?: number
+  numGpu?: number
+  onToken?: (token: string) => void
+  /** Live reasoning/thinking tokens as they stream, for display only (never sent back to the LLM). */
+  onReasoningToken?: (token: string) => void
+  signal?: AbortSignal
+  /** Enable extended thinking for supported models (Anthropic Claude 3.7+). */
+  thinking?: { enabled: boolean; budget_tokens?: number }
+}
+
+export interface LLMResponse {
+  content: string
+  tool_calls?: LLMToolCall[]
+  stop_reason: "stop" | "tool_calls" | "max_tokens" | "error"
+  usage?: { input_tokens: number; output_tokens: number; thinking_tokens?: number }
+  /** Kimi K2 / DeepSeek thinking mode — must be round-tripped in assistant messages. */
+  reasoning_content?: string
+  /** Anthropic extended thinking content (not sent to LLM, for display only). */
+  thinking_content?: string
+  /** Anthropic extended thinking raw blocks — must be round-tripped verbatim when tool calls follow. */
+  thinking_blocks?: ThinkingBlock[]
+  /**
+   * Set only when stop_reason === "error". `content` carries a human-readable
+   * version of the same failure for display, but it is NOT model output —
+   * callers must check this field before persisting `content` anywhere durable
+   * (conversation history, summaries, task results).
+   */
+  error?: {
+    message: string
+    status?: number
+    /** The model id no longer resolves at the provider (HTTP 404/410) — the config needs to change, retrying won't help. */
+    modelUnavailable?: boolean
+  }
+}
+
+// ─── Provider factory ─────────────────────────────────────────────────────────
+
+function getProvider(provider: string): LLMProvider {
+  switch (provider) {
+    case "gemini":
+    case "google":      return new GeminiProvider()
+    case "anthropic":   return new AnthropicProvider()
+    case "ollama":      return new OllamaProvider()
+    case "openai":      return new OpenAIProvider()
+    case "groq":        return new GroqProvider()
+    case "mistral":     return new MistralProvider()
+    case "openrouter":  return new OpenRouterProvider()
+    case "deepseek":    return new DeepSeekProvider()
+    case "kimi":        return new KimiProvider()
+    case "nvidia":      return new NvidiaProvider()
+    case "qwen":        return new QwenProvider()
+    case "minimax":     return new MiniMaxProvider()
+    case "opencode-go": return new OpenCodeGoProvider()
+    case "hiveagents":  return new HiveAgentsProvider()
+    case "z-ai":        return new ZaiProvider()
+    case "modelscope":  return new ModelScopeProvider()
+    default:
+      log.warn(`[llm-client] Unknown provider "${provider}" — falling back to OpenAI-compatible endpoint`)
+      return new OpenAIProvider()
+  }
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Call any LLM provider. Returns a canonical LLMResponse regardless of provider.
+ *
+ * Retries transient failures (429/5xx/timeout/network) with exponential
+ * backoff + jitter per `config.retry`, honoring `Retry-After` when the
+ * provider sends one. An aborted signal never retries. Note: this retries
+ * the whole call, so a failure that happens mid-stream (after onToken has
+ * already fired) can produce a duplicated partial response — acceptable
+ * because provider failures overwhelmingly happen before the stream starts
+ * (auth/rate-limit/connection errors).
+ */
+export async function callLLM(options: LLMCallOptions): Promise<LLMResponse> {
+  const retryCfg = loadConfig().retry
+  const policy: RetryPolicy = {
+    maxAttempts: retryCfg?.maxAttempts ?? 3,
+    initialDelayMs: retryCfg?.initialDelayMs ?? 1000,
+    backoffMultiplier: retryCfg?.backoffMultiplier ?? 2,
+    maxDelayMs: retryCfg?.maxDelayMs ?? 30000,
+  }
+  try {
+    return await withRetry(
+      () => getProvider(options.provider).call(options),
+      policy,
+      (err) => !options.signal?.aborted && isRetryableError(err)
+    )
+  } catch (err) {
+    const cleanModel = options.model.replace(new RegExp(`^${options.provider}\\/`), "")
+    const status = extractErrorStatus(err)
+    const modelUnavailable = status === 404 || status === 410
+    const msg = modelUnavailable
+      ? `El modelo "${cleanModel}" ya no existe en ${options.provider} (HTTP ${status}). `
+        + `El proveedor lo retiró de su catálogo; reintentar no sirve. `
+        + `Elegí otro modelo en Ajustes → Proveedores.`
+      : (err as Error).message
+    log.error(`[llm-client] Error calling ${options.provider}/${cleanModel}: ${msg}`, err)
+    return {
+      content: `[LLM Error] ${msg}`,
+      stop_reason: "error",
+      error: { message: msg, status, modelUnavailable },
+    }
+  }
+}
+
+/** Provider SDKs disagree on where the HTTP status lands; check every shape we've seen. */
+function extractErrorStatus(err: unknown): number | undefined {
+  const e = err as { status?: number; statusCode?: number; response?: { status?: number } }
+  return e?.status ?? e?.statusCode ?? e?.response?.status
+}
+
+/**
+ * Default provider/model resolved from the DB, used when an agent has none configured:
+ * 1. the coordinator agent's config, 2. the first active LLM model of an active provider.
+ * Returns null when the DB has no usable LLM (e.g. fresh install before setup).
+ */
+export async function getDefaultLLM(): Promise<{ provider: string; model: string } | null> {
+  const { col, fromIndexable } = await import("../storage/hive")
+  const agentsCol = await col<import("../storage/collections").AgentDoc>("agents")
+  const modelsCol = await col<import("../storage/collections").ModelDoc>("models")
+  const providersCol = await col<import("../storage/collections").ProviderDoc>("providers")
+
+  const coordinators = await agentsCol.findBy("role", "coordinator")
+  const coordinator = coordinators[0]
+  const coordinatorProvider = fromIndexable(coordinator?.doc.provider_id ?? null)
+  const coordinatorModel = fromIndexable(coordinator?.doc.model_id ?? null)
+  if (coordinatorProvider && coordinatorModel) {
+    return { provider: coordinatorProvider, model: coordinatorModel }
+  }
+
+  const activeModels = (await modelsCol.findBy("model_type", "llm")).filter(m => m.doc.active)
+  for (const m of activeModels) {
+    const provider = await providersCol.get(m.doc.provider_id)
+    if (provider?.doc.active) {
+      return { provider: m.doc.provider_id, model: m.doc.id }
+    }
+  }
+  return null
+}
+
+/**
+ * Resolve provider config from DB (decrypts API key).
+ */
+export async function resolveProviderConfig(
+  providerId: string,
+  modelId: string
+): Promise<Pick<LLMCallOptions, "provider" | "model" | "apiKey" | "baseUrl" | "numCtx" | "numGpu" | "contextWindow">> {
+  const { col } = await import("../storage/hive")
+  const { loadProviderApiKey } = await import("../storage/crypto")
+  const providersCol = await col<import("../storage/collections").ProviderDoc>("providers")
+  const modelsCol = await col<import("../storage/collections").ModelDoc>("models")
+
+  const providerEntry = await providersCol.get(providerId)
+  const providerRow = (providerEntry?.doc.enabled && providerEntry?.doc.active) ? providerEntry.doc : undefined
+
+  // Load model's context window for token budget management
+  const modelEntry = await modelsCol.get(modelId)
+
+  let apiKey = await loadProviderApiKey(providerId)
+  if (!apiKey) {
+    apiKey = process.env[`${providerId.toUpperCase()}_API_KEY`] || ""
+  }
+
+  return {
+    provider: providerId,
+    model: modelId,
+    apiKey,
+    baseUrl: providerRow?.base_url || undefined,
+    numCtx: providerRow?.num_ctx ?? undefined,
+    numGpu: providerRow?.num_gpu ?? undefined,
+    contextWindow: modelEntry?.doc.context_window ?? undefined,
+  }
+}

package/packages/core/src/agent/llm-providers/anthropic.ts

@@ -0,0 +1,264 @@
+import { logger } from "../../utils/logger"
+import { normalizeToolName, resolveMaxTokens, ensureArrayItems } from "./interface"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall, ThinkingBlock } from "./interface"
+import type { ContentPart, LLMMessage } from "../llm-client"
+
+const log = logger.child("llm-client")
+
+// Models that accept the explicit `thinking: { type: "enabled" }` parameter, per
+// the "Extended thinking" row of platform.claude.com/docs/en/about-claude/models/overview.
+// This is an allowlist on purpose: from Opus 4.7 onward Anthropic replaced extended
+// thinking with *adaptive* thinking, which is server-side and always on — those models
+// reject the parameter, so being absent here is the correct behavior, not an omission.
+const THINKING_CAPABLE_MODELS = new Set([
+  "claude-3-7-sonnet-20250219",
+  "claude-sonnet-4-5",
+  "claude-sonnet-4-5-20250929",
+  "claude-sonnet-4-6",  // deprecated but still accepted
+  "claude-opus-4-5",
+  "claude-opus-4-5-20251101",
+  "claude-opus-4-6",    // deprecated but still accepted
+  "claude-haiku-4-5",
+  "claude-haiku-4-5-20251001",
+])
+
+function supportsThinking(model: string): boolean {
+  return THINKING_CAPABLE_MODELS.has(model)
+}
+
+/** Anthropic's documented shape for context-length errors: 400 + invalid_request_error + a "too long"/"maximum" message. */
+function isAnthropicContextOverflowError(err: any): boolean {
+  const status = err?.status
+  if (status !== 400) return false
+  const type = err?.error?.type ?? err?.type
+  const msg = (err?.error?.message ?? err?.message ?? "").toLowerCase()
+  if (type && type !== "invalid_request_error") return false
+  return msg.includes("too long") || msg.includes("maximum context") || msg.includes("prompt is too long") || msg.includes("context length")
+}
+
+/** Keeps the first `thinking`/`tool_use` round-trip block intact per message, keeps only the last ~33% of the conversation, and shrinks max_tokens. */
+function compactAnthropicBody(body: any): void {
+  const keepRatio = Math.max(1, Math.floor(body.messages.length / 3))
+  body.messages = body.messages.slice(-keepRatio)
+  if (body.max_tokens) body.max_tokens = Math.min(body.max_tokens, 4096)
+}
+
+export class AnthropicProvider implements LLMProvider {
+  private _convertContentPart(part: ContentPart): any {
+    switch (part.type) {
+      case "text":
+        return { type: "text", text: part.text }
+      case "image_url": {
+        const url = part.image_url.url
+        if (url.startsWith("data:")) {
+          const match = url.match(/^data:([^;]+);base64,(.+)$/)
+          if (match) return { type: "image", source: { type: "base64", media_type: match[1], data: match[2] } }
+        }
+        return { type: "image", source: { type: "url", url } }
+      }
+      case "image_base64":
+        return { type: "image", source: { type: "base64", media_type: part.mimeType, data: part.base64 } }
+      case "document":
+        return { type: "document", source: { type: "base64", media_type: part.mimeType, data: part.base64 } }
+      default:
+        return { type: "text", text: JSON.stringify(part) }
+    }
+  }
+
+  private _convertUserContent(msg: LLMMessage): any[] {
+    if (Array.isArray(msg.content)) {
+      return msg.content.map(p => this._convertContentPart(p))
+    }
+    return [{ type: "text", text: msg.content }]
+  }
+
+  async call(options: LLMCallOptions): Promise<LLMResponse> {
+    const Anthropic = await import("@anthropic-ai/sdk")
+    const client = new Anthropic.default({ apiKey: options.apiKey })
+
+    // Anthropic requires tool names to match ^[a-zA-Z0-9_-]{1,128}$
+    // Native Hive tools use dots (e.g. cron.create) which violate this.
+    const toolNameMap = new Map<string, string>() // wireName -> originalName
+
+    const systemText = options.messages
+      .filter((m) => m.role === "system")
+      .map((m) => m.content)
+      .join("\n\n")
+
+    const anthropicMessages: any[] = []
+
+    for (const msg of options.messages) {
+      if (msg.role === "system") continue
+
+      if (msg.role === "tool") {
+        const block = { type: "tool_result", tool_use_id: msg.tool_call_id, content: msg.content }
+        const last = anthropicMessages[anthropicMessages.length - 1]
+        if (last?.role === "user" && Array.isArray(last.content)) {
+          last.content.push(block)
+        } else {
+          anthropicMessages.push({ role: "user", content: [block] })
+        }
+        continue
+      }
+
+      if (msg.role === "assistant" && msg.tool_calls?.length) {
+        const content: any[] = []
+        // Extended thinking blocks must be replayed verbatim (with signature) before
+        // any tool_use block, or the API rejects the request with a 400.
+        if (msg.thinking_blocks?.length) {
+          for (const tb of msg.thinking_blocks) {
+            content.push(
+              tb.type === "thinking"
+                ? { type: "thinking", thinking: tb.thinking, signature: tb.signature }
+                : { type: "redacted_thinking", data: tb.data }
+            )
+          }
+        }
+        if (msg.content) content.push({ type: "text", text: msg.content })
+        for (const tc of msg.tool_calls) {
+          let input: Record<string, unknown>
+          try { input = JSON.parse(tc.function.arguments || "{}") } catch { input = {} }
+          const wireName = normalizeToolName(tc.function.name, "_")
+          if (wireName !== tc.function.name) toolNameMap.set(wireName, tc.function.name)
+          content.push({ type: "tool_use", id: tc.id, name: wireName, input })
+        }
+        anthropicMessages.push({ role: "assistant", content })
+        continue
+      }
+
+      anthropicMessages.push({ role: msg.role, content: Array.isArray(msg.content) ? this._convertUserContent(msg) : msg.content })
+    }
+
+    const tools: any[] = (options.tools ?? []).map((t) => {
+      const originalName = t.function.name
+      const wireName = normalizeToolName(originalName, "_")
+      if (wireName !== originalName) toolNameMap.set(wireName, originalName)
+      return {
+        name: wireName,
+        description: t.function.description,
+        input_schema: ensureArrayItems(t.function.parameters),
+      }
+    })
+
+    const body: any = {
+      model: options.model,
+      max_tokens: resolveMaxTokens(options.maxTokens, options.contextWindow) ?? 16384,
+      messages: anthropicMessages,
+    }
+    if (systemText) body.system = systemText
+    if (tools.length) body.tools = tools
+
+    // Extended thinking — only for supported models
+    const thinkingEnabled = options.thinking?.enabled && supportsThinking(options.model)
+    if (thinkingEnabled) {
+      body.thinking = { type: "enabled", budget_tokens: options.thinking?.budget_tokens ?? 10000 }
+    }
+
+    log.info(
+      `[llm-client] anthropic/${options.model} — ${anthropicMessages.length} msgs, ${tools.length} tools` +
+      (thinkingEnabled ? ` thinking=${body.thinking.budget_tokens}tok` : "")
+    )
+
+    // Streaming via messages.stream()
+    const useStream = true  // Always stream for better UX
+    if (useStream) {
+      for (let attempt = 0; attempt < 2; attempt++) {
+        let content = ""
+        let thinking_content = ""
+        const tool_calls: LLMToolCall[] = []
+
+        try {
+          const stream = client.messages.stream(body, options.signal ? { signal: options.signal } : undefined)
+
+          // Track partial tool inputs by index
+          const partialInputs: Record<number, string> = {}
+          const toolMeta: Record<number, { id: string; name: string }> = {}
+          // Track thinking/redacted_thinking blocks by index — needed both for live
+          // display (onReasoningToken) and to round-trip the signed block verbatim
+          // in the next turn if this response also contains tool calls.
+          const thinkingBlockState: Record<number, { type: "thinking" | "redacted_thinking"; thinking: string; signature: string; data: string }> = {}
+
+          for await (const event of stream) {
+            if (event.type === "content_block_start") {
+              if (event.content_block.type === "tool_use") {
+                const wireName = event.content_block.name
+                const originalName = toolNameMap.get(wireName) ?? wireName
+                toolMeta[event.index] = { id: event.content_block.id, name: originalName }
+                partialInputs[event.index] = ""
+              } else if (event.content_block.type === "thinking") {
+                thinkingBlockState[event.index] = { type: "thinking", thinking: "", signature: "", data: "" }
+              } else if ((event.content_block as any).type === "redacted_thinking") {
+                thinkingBlockState[event.index] = { type: "redacted_thinking", thinking: "", signature: "", data: (event.content_block as any).data ?? "" }
+              }
+            } else if (event.type === "content_block_delta") {
+              if (event.delta.type === "text_delta") {
+                content += event.delta.text
+                if (options.onToken) options.onToken(event.delta.text)
+              } else if (event.delta.type === "thinking_delta") {
+                thinking_content += event.delta.thinking
+                options.onReasoningToken?.(event.delta.thinking)
+                if (thinkingBlockState[event.index]) thinkingBlockState[event.index].thinking += event.delta.thinking
+              } else if ((event.delta as any).type === "signature_delta") {
+                if (thinkingBlockState[event.index]) thinkingBlockState[event.index].signature += (event.delta as any).signature
+              } else if (event.delta.type === "input_json_delta") {
+                if (partialInputs[event.index] !== undefined) {
+                  partialInputs[event.index] += event.delta.partial_json
+                }
+              }
+            }
+          }
+
+          const thinking_blocks: ThinkingBlock[] = Object.keys(thinkingBlockState)
+            .map(Number)
+            .sort((a, b) => a - b)
+            .map((idx) => {
+              const b = thinkingBlockState[idx]
+              return b.type === "thinking"
+                ? { type: "thinking" as const, thinking: b.thinking, signature: b.signature }
+                : { type: "redacted_thinking" as const, data: b.data }
+            })
+
+          const finalMsg = await stream.finalMessage()
+
+          // Build tool_calls from accumulated partial inputs
+          for (const [idx, meta] of Object.entries(toolMeta)) {
+            const args = partialInputs[Number(idx)] ?? "{}"
+            tool_calls.push({
+              id: meta.id,
+              type: "function",
+              function: { name: meta.name, arguments: args },
+            })
+          }
+
+          const usage = finalMsg.usage
+          return {
+            content,
+            thinking_content: thinking_content || undefined,
+            thinking_blocks: thinking_blocks.length ? thinking_blocks : undefined,
+            tool_calls: tool_calls.length ? tool_calls : undefined,
+            stop_reason:
+              finalMsg.stop_reason === "tool_use" ? "tool_calls"
+                : finalMsg.stop_reason === "max_tokens" ? "max_tokens"
+                  : "stop",
+            usage: {
+              input_tokens: usage.input_tokens,
+              output_tokens: usage.output_tokens,
+              thinking_tokens: (usage as any).thinking_tokens ?? 0,
+            },
+          }
+        } catch (err: any) {
+          if (attempt === 0 && isAnthropicContextOverflowError(err)) {
+            log.warn(`[llm-client] anthropic: context overflow — compacting messages and retrying`)
+            const originalCount = body.messages.length
+            compactAnthropicBody(body)
+            log.info(`[llm-client] anthropic: compacted ${originalCount} msgs → ${body.messages.length} msgs, max_tokens=${body.max_tokens}`)
+            continue
+          }
+          throw err
+        }
+      }
+    }
+
+    throw new Error("unreachable")
+  }
+}

package/packages/core/src/agent/llm-providers/deepseek.ts

@@ -0,0 +1,8 @@
+import { OpenAICompatBase } from "./openai-compat-base"
+
+export class DeepSeekProvider extends OpenAICompatBase {
+  constructor() { super("deepseek") }
+
+  /** DeepSeek reasoner models return reasoning_content that must be round-tripped. */
+  protected needsReasoningRoundtrip(): boolean { return true }
+}