@johpaz/hive-sdk 0.0.14 → 0.0.15

package/packages/core/src/agent/providers/interface.ts

@@ -0,0 +1,195 @@
+/**
+ * Shared types and utilities for LLM providers.
+ */
+
+import type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart } from "./LLMClient.ts"
+export type { LLMCallOptions, LLMMessage, LLMResponse, LLMToolCall, ContentPart }
+
+import { logger } from "../../utils/logger.ts"
+const log = logger.child("llm-client")
+
+// ─── Provider interface ────────────────────────────────────────────────────────
+
+export interface LLMProvider {
+  call(options: LLMCallOptions): Promise<LLMResponse>
+}
+
+// ─── Shared constants ─────────────────────────────────────────────────────────
+
+// Models that only accept temperature=1 (reasoning/thinking models).
+export const FIXED_TEMPERATURE_1_MODELS = new Set(["kimi-k2.5", "kimi-k2", "kimi-k2-5"])
+
+export const OPENAI_COMPAT_BASE_URLS: Record<string, string> = {
+  groq: "https://api.groq.com/openai/v1",
+  mistral: "https://api.mistral.ai/v1",
+  openrouter: "https://openrouter.ai/api/v1",
+  deepseek: "https://api.deepseek.com/v1",
+  kimi: "https://api.moonshot.ai/v1",
+  "local-llama": "http://localhost:8080/v1",
+  nvidia: "https://integrate.api.nvidia.com/v1",
+  qwen: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+}
+
+// ─── Provider profiles ────────────────────────────────────────────────────────
+
+export interface ProviderProfile {
+  /** Normalize tool names to strict OpenAI format: [a-zA-Z0-9_-]{1,64} */
+  normalizeToolNames: boolean
+  /** Replacement string for invalid tool name chars, e.g. "__" */
+  toolNameReplacement: string
+  /** Value for the tool_choice parameter ("auto" | "any" for Mistral) */
+  toolChoiceAuto: string
+  /** Send parallel_tool_calls: false when true */
+  disableParallelToolCalls: boolean
+  /** Strip additionalProperties: false from tool parameter schemas */
+  stripAdditionalProperties: boolean
+  /** Retry the call without tools when these HTTP status codes are returned */
+  retryWithoutToolsOnCodes: number[]
+}
+
+const DEFAULT_PROFILE: ProviderProfile = {
+  normalizeToolNames: false,
+  toolNameReplacement: "__",
+  toolChoiceAuto: "auto",
+  disableParallelToolCalls: false,
+  stripAdditionalProperties: false,
+  retryWithoutToolsOnCodes: [],
+}
+
+export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
+  openai: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  kimi: { ...DEFAULT_PROFILE, normalizeToolNames: true, disableParallelToolCalls: true, retryWithoutToolsOnCodes: [422] },
+  deepseek: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  groq: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  mistral: { ...DEFAULT_PROFILE, normalizeToolNames: true, toolChoiceAuto: "any", stripAdditionalProperties: true },
+  openrouter: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  nvidia: { ...DEFAULT_PROFILE, normalizeToolNames: true },
+  qwen: { ...DEFAULT_PROFILE, normalizeToolNames: true, retryWithoutToolsOnCodes: [400, 422] },
+  "local-llama": { ...DEFAULT_PROFILE },
+}
+
+export function getProviderProfile(provider: string): ProviderProfile {
+  return PROVIDER_PROFILES[provider] ?? DEFAULT_PROFILE
+}
+
+// ─── Models that don't support tool calling ───────────────────────────────────
+
+export const NO_TOOL_MODELS = new Set([
+  "deepseek-reasoner",
+  "deepseek/deepseek-r1:free",
+])
+
+export function modelSupportsTools(provider: string, model: string): boolean {
+  if (NO_TOOL_MODELS.has(model)) return false
+  // DeepSeek R1 and OpenRouter-routed R1 variants don't support tools
+  if ((provider === "deepseek" || provider === "openrouter") && /[-/]r1\b/i.test(model)) return false
+  return true
+}
+
+// ─── Tool name & schema normalization ────────────────────────────────────────
+
+const OPENAI_TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/
+const NORMALIZE_CHARS_RE = /[^a-zA-Z0-9_-]/g
+
+/** Normalize a tool name to pass strict [a-zA-Z0-9_-]{1,64} validation. */
+export function normalizeToolName(name: string, replacement: string): string {
+  if (OPENAI_TOOL_NAME_RE.test(name)) return name
+  const escapedReplacement = replacement.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const collapseRE = new RegExp(`(${escapedReplacement}){2,}`, "g")
+  let n = name.replace(NORMALIZE_CHARS_RE, replacement).replace(collapseRE, replacement)
+  if (!/^[a-zA-Z_]/.test(n)) n = "_" + n
+  return n.slice(0, 64)
+}
+
+/** Strip provider-incompatible fields from a tool parameter schema. */
+export function normalizeToolSchema(
+  schema: Record<string, unknown>,
+  profile: ProviderProfile
+): Record<string, unknown> {
+  if (!profile.stripAdditionalProperties) return schema
+  return deepStripSchema(schema)
+}
+
+function deepStripSchema(obj: unknown): any {
+  if (typeof obj !== "object" || obj === null) return obj
+  if (Array.isArray(obj)) return obj.map(deepStripSchema)
+  const result: any = {}
+  for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+    if (k === "additionalProperties" && v === false) continue
+    result[k] = deepStripSchema(v)
+  }
+  return result
+}
+
+// ─── Temperature constraints ──────────────────────────────────────────────────
+
+/**
+ * Returns true when the model requires temperature=1.
+ * Used for Kimi K2 thinking mode which rejects any other temperature.
+ */
+export function requiresTemperature1(provider: string, model: string): boolean {
+  if (FIXED_TEMPERATURE_1_MODELS.has(model)) return true
+  if (provider === "kimi") {
+    const m = model.toLowerCase()
+    if (m.includes("k2")) return true
+  }
+  return false
+}
+
+// ─── Message sanitization ─────────────────────────────────────────────────────
+
+/**
+ * Remove tool_calls from assistant messages whose corresponding tool results
+ * are missing from the history (e.g. cleared by compaction). Providers like
+ * Kimi reject message sequences with orphaned tool_calls.
+ */
+export function sanitizeMessages(messages: LLMMessage[]): LLMMessage[] {
+  // Pass 0: collect all tool_call_ids that appear in assistant messages.
+  const knownToolCallIds = new Set<string>()
+  for (const m of messages) {
+    if (m.role === "assistant" && m.tool_calls?.length) {
+      for (const tc of m.tool_calls) knownToolCallIds.add(tc.id)
+    }
+  }
+
+  // Pass 1: determine which tool_call_ids are "dead"
+  const deadIds = new Set<string>()
+
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i]
+    if (m.role !== "assistant" || !m.tool_calls?.length) continue
+
+    const neededIds = new Set(m.tool_calls.map((tc) => tc.id))
+    let j = i + 1
+    while (j < messages.length && messages[j].role === "tool") {
+      if (messages[j].tool_call_id) neededIds.delete(messages[j].tool_call_id!)
+      j++
+    }
+    if (neededIds.size > 0) {
+      log.warn(`[llm-client] Stripping orphaned tool_calls (missing results for: ${[...neededIds].join(", ")})`)
+      for (const tc of m.tool_calls) deadIds.add(tc.id)
+    }
+  }
+
+  // Pass 2: rebuild message list, dropping/fixing affected messages
+  const result: LLMMessage[] = []
+  for (const m of messages) {
+    if (m.role === "tool" && m.tool_call_id) {
+      if (deadIds.has(m.tool_call_id) || !knownToolCallIds.has(m.tool_call_id)) {
+        log.warn(`[llm-client] Dropping orphaned tool result (tool_call_id: ${m.tool_call_id})`)
+        continue
+      }
+    }
+    if (m.role === "assistant" && m.tool_calls?.some((tc) => deadIds.has(tc.id))) {
+      const { tool_calls, ...rest } = m
+      const hasContent = typeof rest.content === "string"
+        ? rest.content.trim()
+        : Array.isArray(rest.content) && rest.content.length > 0
+      if (hasContent) result.push(rest as LLMMessage)
+      continue
+    }
+    result.push(m)
+  }
+
+  return result
+}

package/packages/core/src/agent/providers/ollama.ts

@@ -0,0 +1,175 @@
+import { logger } from "../../utils/logger.ts"
+import { sanitizeMessages } from "./interface"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
+import type { ContentPart, LLMMessage } from "./LLMClient.ts"
+
+const log = logger.child("llm-client")
+
+export class OllamaProvider implements LLMProvider {
+  private _convertMessage(msg: LLMMessage): any {
+    if (typeof msg.content === "string") {
+      return { role: msg.role, content: msg.content }
+    }
+
+    let textContent = ""
+    const images: string[] = []
+
+    for (const part of msg.content) {
+      if (part.type === "text") {
+        textContent += part.text
+      } else if (part.type === "image_base64") {
+        images.push(part.base64)
+      } else if (part.type === "document") {
+        textContent += `\n[Document: ${part.fileName || "file"}] (base64 content not displayed)`
+      } else if (part.type === "image_url") {
+        const url = part.image_url.url
+        if (url.startsWith("data:")) {
+          const match = url.match(/^data:([^;]+);base64,(.+)$/)
+          if (match) images.push(match[2])
+        } else {
+          textContent += `\n[Image URL: ${url}]`
+        }
+      }
+    }
+
+    return { role: msg.role, content: textContent.trim(), ...(images.length > 0 ? { images } : {}) }
+  }
+
+  async call(options: LLMCallOptions): Promise<LLMResponse> {
+    const { Ollama } = await import("ollama")
+
+    const modelName = options.model.replace(/^ollama\//, "")
+    const host = options.baseUrl?.trim() || process.env.OLLAMA_HOST || "http://localhost:11434"
+    const isCloud = host.includes("ollama.com")
+    const headers: Record<string, string> = {}
+    if (isCloud && options.apiKey) headers["Authorization"] = `Bearer ${options.apiKey}`
+
+    const client = new Ollama({
+      host,
+      ...(Object.keys(headers).length ? { headers } : {}),
+    })
+
+    const messages = sanitizeMessages(options.messages).map((m): any => {
+      if (m.role === "assistant" && m.tool_calls?.length) {
+        return {
+          role: "assistant",
+          content: typeof m.content === "string" ? m.content : m.content.map(p => (p as any).text || "").join(""),
+          tool_calls: m.tool_calls.map((tc) => ({
+            function: {
+              name: tc.function.name,
+              arguments: (() => {
+                try { return JSON.parse(tc.function.arguments) } catch { return {} }
+              })(),
+            },
+          })),
+        }
+      }
+      if (m.role === "tool") return { role: "tool", content: typeof m.content === "string" ? m.content : JSON.stringify(m.content) }
+      return this._convertMessage(m)
+    })
+
+    const tools = options.tools?.map((t) => ({
+      type: "function" as const,
+      function: {
+        name: t.function.name,
+        description: t.function.description,
+        parameters: t.function.parameters,
+      },
+    }))
+
+    // Default num_ctx to 4096 for local models — prevents OOM on small models (2B-7B)
+    // when Ollama's default (32k+) is too large for available RAM/VRAM.
+    // Users can override via providers.num_ctx in DB.
+    const runtimeOptions: Record<string, unknown> = {
+      num_ctx: options.numCtx ?? 4096,
+    }
+    if (options.numGpu !== undefined) runtimeOptions.num_gpu = options.numGpu
+    if (options.temperature !== undefined) runtimeOptions.temperature = options.temperature
+
+    try {
+
+      log.info(
+        `[llm-client] ollama/${modelName} @ ${isCloud ? "ollama.com" : host} stream=true` +
+        ` — ${messages.length} msgs, ${tools?.length ?? 0} tools` +
+        ` num_ctx=${runtimeOptions.num_ctx}`
+      )
+
+      const stream = await client.chat({
+        model: modelName,
+        messages,
+        tools: tools?.length ? tools : undefined,
+        options: Object.keys(runtimeOptions).length ? runtimeOptions : undefined,
+        stream: true,
+      })
+
+      let content = ""
+      let promptEvalCount = 0
+      let evalCount = 0
+      const tool_calls: LLMToolCall[] = []
+
+      for await (const part of stream) {
+        const delta = part.message?.content ?? ""
+        if (delta) {
+          content += delta
+          if (options.onToken) options.onToken(delta)
+        }
+
+        if (part.message?.tool_calls?.length) {
+          for (const tc of part.message.tool_calls) {
+            tool_calls.push({
+              id: crypto.randomUUID(),
+              type: "function" as const,
+              function: {
+                name: (tc as any).function.name,
+                arguments: JSON.stringify((tc as any).function.arguments ?? {}),
+              },
+            })
+          }
+        }
+
+        if (part.prompt_eval_count !== undefined) promptEvalCount = part.prompt_eval_count
+        if (part.eval_count !== undefined) evalCount = part.eval_count
+      }
+
+      return {
+        content,
+        tool_calls: tool_calls.length ? tool_calls : undefined,
+        stop_reason: tool_calls.length > 0 ? "tool_calls" : "stop",
+        usage:
+          evalCount > 0
+            ? { input_tokens: promptEvalCount, output_tokens: evalCount }
+            : undefined,
+      }
+    } catch (error: any) {
+      log.error(`[llm-client] FAILED call to ollama/${modelName} at ${host}`)
+      log.error(`[llm-client] Error details: ${error.message || error}`)
+      if (options.numCtx) log.error(`[llm-client] Context requested: num_ctx=${options.numCtx}`)
+      if (options.tools?.length) log.error(`[llm-client] Tools defined: ${options.tools.length}`)
+
+      // If the model runner crashed (likely OOM) and tools were sent, retry without tools.
+      // The model can still answer conversationally — tools will be unavailable this turn.
+      // Match by error message string OR HTTP 500 with tools (resilient to Ollama message changes).
+      if (
+        (error.message?.includes("model runner has unexpectedly stopped") || error.status === 500) &&
+        tools?.length
+      ) {
+        log.warn(`[llm-client] OOM with tools — retrying without tools (num_ctx=${runtimeOptions.num_ctx})`)
+        const stream2 = await client.chat({
+          model: modelName,
+          messages,
+          tools: undefined,
+          options: runtimeOptions,
+          stream: true,
+        })
+        let content = ""
+        for await (const part of stream2) {
+          const delta = part.message?.content ?? ""
+          if (delta) { content += delta; if (options.onToken) options.onToken(delta) }
+        }
+        return { content, tool_calls: undefined, stop_reason: "stop" }
+      }
+
+      throw error
+    }
+  }
+}

package/packages/core/src/agent/providers/openai-compat.ts

@@ -0,0 +1,231 @@
+import { logger } from "../../utils/logger.ts"
+import {
+  sanitizeMessages, requiresTemperature1, OPENAI_COMPAT_BASE_URLS,
+  getProviderProfile, modelSupportsTools, normalizeToolName, normalizeToolSchema,
+} from "./interface"
+import type { LLMCallOptions, LLMProvider, LLMResponse, LLMToolCall } from "./interface"
+import type { ContentPart, LLMMessage } from "./LLMClient.ts"
+
+const log = logger.child("llm-client")
+
+export class OpenAICompatProvider implements LLMProvider {
+  private _convertContentPart(part: ContentPart): any {
+    switch (part.type) {
+      case "text":
+        return { type: "text", text: part.text }
+      case "image_url":
+        return { type: "image_url", image_url: { url: part.image_url.url } }
+      case "image_base64":
+        return { type: "image_url", image_url: { url: `data:${part.mimeType};base64,${part.base64}` } }
+      case "document":
+        return { type: "text", text: `[Document: ${part.fileName || "file"}] (base64 content not displayed)` }
+      default:
+        return { type: "text", text: JSON.stringify(part) }
+    }
+  }
+
+  private _convertMessage(msg: LLMMessage): any {
+    if (Array.isArray(msg.content)) {
+      return { ...msg, content: msg.content.map(p => this._convertContentPart(p)) }
+    }
+    return msg
+  }
+
+  async call(options: LLMCallOptions): Promise<LLMResponse> {
+    const { default: OpenAI } = await import("openai")
+
+    const baseURL = options.baseUrl?.trim() || OPENAI_COMPAT_BASE_URLS[options.provider] || undefined
+    const isLocal = baseURL?.includes("localhost") || baseURL?.includes("127.0.0.1") || baseURL?.includes("::1")
+    const apiKey = options.apiKey || (isLocal ? "ollama" : undefined)
+
+    if (!apiKey) {
+      throw new Error(`API key missing for provider: ${options.provider}. Configure it in Settings → Providers.`)
+    }
+
+    const client = new OpenAI({ apiKey, baseURL })
+
+    const isKimi = options.provider === "kimi"
+    const isDeepSeek = options.provider === "deepseek"
+    // Kimi K2 and DeepSeek reasoner require reasoning_content to be round-tripped
+    const needsReasoningRoundtrip = isKimi || isDeepSeek
+
+    const sanitized = sanitizeMessages(options.messages)
+    const rawMessages = needsReasoningRoundtrip
+      ? sanitized
+      : sanitized.map(({ reasoning_content: _rc, ...rest }) => rest as typeof sanitized[number])
+    const messagesForProvider = rawMessages.map(m => this._convertMessage(m))
+
+    const providerPrefix = new RegExp(`^${options.provider}\\/`, "i")
+    const body: any = {
+      model: options.model.replace(providerPrefix, ""),
+      messages: messagesForProvider,
+      temperature: requiresTemperature1(options.provider, options.model) ? 1 : (options.temperature ?? 0.7),
+    }
+    if (options.maxTokens) body.max_tokens = options.maxTokens
+    if (options.numCtx && isLocal) body.num_ctx = options.numCtx
+
+    // Per-provider profile drives tool call behavior
+    const profile = getProviderProfile(options.provider)
+    const sendTools = modelSupportsTools(options.provider, options.model) && !!(options.tools?.length)
+
+    // Map from wire name (normalized) → original name for denormalizing responses
+    const toolNameMap = new Map<string, string>()
+
+    if (sendTools) {
+      const preparedTools = options.tools!.map((t) => {
+        const originalName = t.function.name
+        const wireName = profile.normalizeToolNames
+          ? normalizeToolName(originalName, profile.toolNameReplacement)
+          : originalName
+        if (wireName !== originalName) toolNameMap.set(wireName, originalName)
+        return {
+          ...t,
+          function: {
+            ...t.function,
+            name: wireName,
+            parameters: normalizeToolSchema(t.function.parameters as Record<string, unknown>, profile),
+          },
+        }
+      })
+      body.tools = preparedTools
+      body.tool_choice = profile.toolChoiceAuto
+      if (profile.disableParallelToolCalls) body.parallel_tool_calls = false
+    }
+
+    log.info(`[llm-client] ${options.provider}/${body.model} — ${options.messages.length} msgs, ${options.tools?.length ?? 0} tools${sendTools ? "" : " (tools suppressed)"}`)
+
+    if (options.onToken) {
+      return this._streamCall(client, body, options, toolNameMap, sendTools, profile)
+    }
+
+    let response
+    try {
+      response = await client.chat.completions.create(body)
+    } catch (err: any) {
+      const status = err?.status ?? err?.response?.status
+      if (sendTools && profile.retryWithoutToolsOnCodes.includes(status)) {
+        log.warn(`[llm-client] ${options.provider}: tools rejected (HTTP ${status}) — retrying without tools`)
+        const bodyNoTools = { ...body }
+        delete bodyNoTools.tools
+        delete bodyNoTools.tool_choice
+        delete bodyNoTools.parallel_tool_calls
+        response = await client.chat.completions.create(bodyNoTools)
+      } else {
+        throw err
+      }
+    }
+
+    const choice = response.choices[0]
+    const msg = choice.message
+
+    const tool_calls: LLMToolCall[] | undefined = (msg.tool_calls as any[])?.map((tc: any) => ({
+      id: tc.id,
+      type: "function" as const,
+      function: {
+        name: toolNameMap.get(tc.function.name) ?? tc.function.name,
+        arguments: tc.function.arguments,
+      },
+    }))
+
+    return {
+      content: msg.content ?? "",
+      tool_calls: tool_calls?.length ? tool_calls : undefined,
+      reasoning_content: (msg as any).reasoning_content ?? undefined,
+      stop_reason:
+        choice.finish_reason === "tool_calls" ? "tool_calls"
+          : choice.finish_reason === "length" ? "max_tokens"
+            : "stop",
+      usage: response.usage ? {
+        input_tokens: response.usage.prompt_tokens,
+        output_tokens: response.usage.completion_tokens,
+      } : undefined,
+    }
+  }
+
+  private async _streamCall(
+    client: any,
+    body: any,
+    options: LLMCallOptions,
+    toolNameMap: Map<string, string>,
+    sendTools: boolean,
+    profile: ReturnType<typeof getProviderProfile>,
+  ): Promise<LLMResponse> {
+    let stream
+    try {
+      stream = await client.chat.completions.create({ ...body, stream: true })
+    } catch (err: any) {
+      const status = err?.status ?? err?.response?.status
+      if (sendTools && profile.retryWithoutToolsOnCodes.includes(status)) {
+        log.warn(`[llm-client] ${options.provider}: tools rejected (HTTP ${status}) — retrying stream without tools`)
+        const bodyNoTools = { ...body }
+        delete bodyNoTools.tools
+        delete bodyNoTools.tool_choice
+        delete bodyNoTools.parallel_tool_calls
+        stream = await client.chat.completions.create({ ...bodyNoTools, stream: true })
+      } else {
+        throw err
+      }
+    }
+
+    let content = ""
+    let reasoning_content = ""
+    let finish_reason = "stop"
+    const toolCallMap: Map<number, { id: string; name: string; arguments: string }> = new Map()
+    let input_tokens = 0
+    let output_tokens = 0
+
+    for await (const chunk of stream) {
+      const choice = chunk.choices?.[0]
+      if (!choice) continue
+
+      const delta = choice.delta as any
+      if (delta.content) {
+        content += delta.content
+        options.onToken!(delta.content)
+      }
+      if (delta.reasoning_content) {
+        reasoning_content += delta.reasoning_content
+      }
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx: number = tc.index
+          if (!toolCallMap.has(idx)) {
+            toolCallMap.set(idx, { id: tc.id ?? "", name: tc.function?.name ?? "", arguments: "" })
+          }
+          const entry = toolCallMap.get(idx)!
+          if (tc.id) entry.id = tc.id
+          if (tc.function?.name) entry.name = tc.function.name
+          if (tc.function?.arguments) entry.arguments += tc.function.arguments
+        }
+      }
+      if (choice.finish_reason) finish_reason = choice.finish_reason
+
+      if (chunk.usage) {
+        input_tokens = chunk.usage.prompt_tokens ?? 0
+        output_tokens = chunk.usage.completion_tokens ?? 0
+      }
+    }
+
+    const tool_calls: LLMToolCall[] = [...toolCallMap.values()].map((tc) => ({
+      id: tc.id,
+      type: "function" as const,
+      function: {
+        name: toolNameMap.get(tc.name) ?? tc.name,
+        arguments: tc.arguments || "{}",
+      },
+    }))
+
+    return {
+      content,
+      tool_calls: tool_calls.length ? tool_calls : undefined,
+      reasoning_content: reasoning_content || undefined,
+      stop_reason:
+        finish_reason === "tool_calls" ? "tool_calls"
+          : finish_reason === "length" ? "max_tokens"
+            : "stop",
+      usage: input_tokens > 0 || output_tokens > 0
+        ? { input_tokens, output_tokens }
+        : undefined,
+    }
+  }
+}

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

@@ -0,0 +1 @@
+export * from "./providers/index.ts";