feat[api|notask]: expose backendDevice stat in SDK for LLM and embed addons

[donriddo]

🎯 What problem does this PR solve?

• SDK does not expose the backendDevice (cpu/gpu) stat that LLM and embed addons now emit.
• SDK's embed() client function returns raw number[] / number[][], so consumers have no way to read addon runtime stats (totalTime, tokensPerSecond, totalTokens, backendDevice).
• SDK schemas do not forward the openclCacheDir, cache-type-k, and cache-type-v config fields accepted by the LLM and embed addons.

📝 How does it solve it?

• Add optional backendDevice: 'cpu' | 'gpu' to completionStatsSchema and embedStatsSchema (Zod), and to LlmStats / EmbedStats addon-response interfaces.
• Thread backendDevice through server/bare/ops/embed.ts and server/bare/plugins/llamacpp-completion/ops/completion-stream.ts so addon stats reach the client response.
• Change embed() return shape from Promise<number[] | number[][]> to Promise<{ embedding, stats? }>, matching the pattern used by completionStream(), diffusion(), translate(), and ocr(). Re-export EmbedStats from the SDK root for typed consumption.
• Update all embed() callers (examples + rag.ts JSDoc) to destructure the new shape.
• Add openclCacheDir (camelCase), 'cache-type-k', and 'cache-type-v' (kebab-case) to llmConfigBaseSchema; openclCacheDir also added to embedConfigBaseSchema. Key names match exactly what the native addons expect.
• LLM plugin (transformLlmConfig) restores openclCacheDir after the legacy camelCase-to-snake_case regex (which would otherwise mangle it to opencl_cache_dir, silently dropping the OpenCL kernel cache directory on Android and slowing first-time GPU startup). Embed plugin passes openclCacheDir through directly with no regex to fight against.

🧪 How was it tested?

• bun run lint (eslint + tsc) clean.
• bun run test:unit clean — new tests:
  • test/unit/embed-schemas.test.ts: backendDevice accepted for 'cpu' / 'gpu', rejected for unknown values, optional, and round-trips through embedResponseSchema.
  • test/unit/completion-stream-schemas.test.ts: same coverage on completionStatsSchema and completionStreamResponseSchema.

💥 Breaking Changes

embed() return shape — the client function now returns { embedding, stats? } instead of raw vectors. Every caller must destructure.

BEFORE (≤ 0.8.x):

const vectors = await embed({ modelId, text: "hello" });

AFTER:

const { embedding, stats } = await embed({ modelId, text: "hello" });
console.log(stats?.backendDevice); // "cpu" | "gpu" | undefined

🔌 API Changes

// CompletionStats
{
  timeToFirstToken?: number
  tokensPerSecond?: number
  cacheTokens?: number
  backendDevice?: "cpu" | "gpu"  // NEW
}

// EmbedStats (newly re-exported from SDK root)
{
  totalTime?: number
  tokensPerSecond?: number
  totalTokens?: number
  backendDevice?: "cpu" | "gpu"  // NEW
}

// LlmConfig — new optional fields
{
  openclCacheDir?: string     // camelCase
  'cache-type-k'?: string     // kebab-case
  'cache-type-v'?: string     // kebab-case
}

// EmbedConfig — new optional field
{
  openclCacheDir?: string
}

📋 Dependency bumps

• @qvac/embed-llamacpp: ^0.12.0 → ^0.13.4
• @qvac/llm-llamacpp: ^0.12.1 → ^0.14.4

[donriddo]

/review

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

**Requirements:**
- 1 Team Member approval ✅ (1/1)
- 1 Team Lead OR Management approval ✅ (1/1)



---
*This comment is automatically updated when reviews change.*

[gianni-cor]

/review