@7n/llm-lib 2.7.5 → 2.7.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.7.6] - 2026-07-18
+
+### Fixed
+
+- `runOneShot`/`runAgentSkill` з нерозв'язаним `modelSpec` (`''`/`null` — consumer лишає вибір pi) більше не потрапляють у `chain.note()` як `model: ''`, через що `chain.mjs` мовчки класифікував їх cloud (`isLocalModel('') === false`) навіть коли pi фактично резолвив локальну модель. Тепер обидва раннери підставляють фактично резолвлену pi-модель (`session.model`, нове `formatModelSpec`), а `chain.note()` для випадків, коли резолвлена модель усе ж недоступна, веде окремий бакет `unknownCalls` замість неявного cloud.
+
 ## [2.7.5] - 2026-07-17
 
 ### Fixed

package/lib/agent-skill.mjs

@@ -18,7 +18,7 @@
  */
 
 import { env, stdout } from 'node:process'
-import { isLocalModel, resolveModel } from './model-tiers.mjs'
+import { formatModelSpec, isLocalModel, resolveModel } from './model-tiers.mjs'
 import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { failOnMemoryGuard } from './internal/memory-guard.mjs'
 import { writeTrace } from './trace.mjs'
@@ -194,23 +194,28 @@ export async function runAgentSkill(prompt, opts = {}) {
     failOnMemoryGuard(error, prompt)
   }
 
+  // spec порожній/нерозв'язаний ('' → pi сам вибирає дефолт) — беремо фактично
+  // резолвлену pi-модель із сесії, щоб chain.note()/trace не бачили порожній
+  // model і не потрапляли в неявний cloud-бакет (isLocalModel('') === false).
+  const resolvedModel = spec || formatModelSpec(session.model)
+
   const telemetry = {
     skill: skillId,
     tier,
-    model: spec || null,
+    model: resolvedModel,
     turnCount,
     toolCallCount,
     backstopHit,
     wallMs: clock() - startedAt
   }
-  chain?.note({ model: spec || null, usage, error })
+  chain?.note({ model: resolvedModel, usage, error })
   trace({
     caller,
     backend: 'pi-ai',
     kind: 'skill',
     skill: skillId,
     tier,
-    model: spec || null,
+    model: resolvedModel,
     cwd,
     turnCount,
     toolCallCount,
@@ -224,7 +229,7 @@ export async function runAgentSkill(prompt, opts = {}) {
     chainId: chain?.traceFields()?.chainId,
     caller,
     step: chain?.traceFields()?.chainStep,
-    model: spec || null,
+    model: resolvedModel,
     promptHash: pHash,
     prompt,
     output: outputText,

package/lib/chain.mjs

@@ -104,6 +104,7 @@ export function startChain({ kind, unit, cwd, meta = {}, deps = {} }) {
   let step = 0
   let localCalls = 0
   let cloudCalls = 0
+  let unknownCalls = 0
   let errors = 0
   let finalModel = null
   let ended = null
@@ -126,15 +127,23 @@ export function startChain({ kind, unit, cwd, meta = {}, deps = {} }) {
 
     /**
      * Раннер репортує результат кроку — акумуляція local/cloud/usage/errors.
+     * `call.model` falsy (нерозв'язаний modelSpec, напр. `''`/`null` — консюмер
+     * лишив вибір pi) — бакет `unknownCalls`, НЕ cloud: без факту резолву модель
+     * могла піти на локальний pi-дефолт, і мовчазний запис у cloudCalls/usageCloud
+     * спотворює local/cloud cost-аналітику для будь-кого, хто не передає `model`.
      * @param {{ model?: string|null, usage?: object|null, error?: string|null, stopReason?: string|null }} call результат виклику
      * @returns {void}
      */
     note(call = {}) {
-      const local = call.model ? isLocal(call.model) : false
-      if (local) localCalls++
-      else cloudCalls++
+      if (!call.model) {
+        unknownCalls++
+      } else if (isLocal(call.model)) {
+        localCalls++
+      } else {
+        cloudCalls++
+        addUsage(usageCloud, call.usage)
+      }
       addUsage(usage, call.usage)
-      if (!local) addUsage(usageCloud, call.usage)
       if (call.error) errors++
       else if (call.model) finalModel = call.model
     },
@@ -179,6 +188,7 @@ export function startChain({ kind, unit, cwd, meta = {}, deps = {} }) {
         steps: step,
         localCalls,
         cloudCalls,
+        unknownCalls,
         escalated: localCalls > 0 && cloudCalls > 0,
         finalModel,
         errors,

package/lib/docs/agent-skill.md

@@ -3,7 +3,7 @@ type: JS Module
 title: agent-skill.mjs
 resource: llm-lib/lib/agent-skill.mjs
 docgen:
-  crc: 196f6fcf
+  crc: 085ebccf
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/docs/chain.md

@@ -3,7 +3,7 @@ type: JS Module
 title: chain.mjs
 resource: llm-lib/lib/chain.mjs
 docgen:
-  crc: c9259fcb
+  crc: 68b416b8
 ---
 
 ## Огляд

package/lib/docs/model-tiers.md

@@ -3,7 +3,7 @@ type: JS Module
 title: model-tiers.mjs
 resource: llm-lib/lib/model-tiers.mjs
 docgen:
-  crc: adfe6189
+  crc: ba67ab5c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/docs/one-shot.md

@@ -3,7 +3,7 @@ type: JS Module
 title: one-shot.mjs
 resource: llm-lib/lib/one-shot.mjs
 docgen:
-  crc: 286493bf
+  crc: 68779501
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/model-tiers.mjs

@@ -77,6 +77,19 @@ export function parseModelId(spec) {
   return { provider: spec.slice(0, i), id: spec.slice(i + 1) }
 }
 
+/**
+ * Форматує pi `Model`-об'єкт (`{provider, id}`) назад у `"provider/model-id"`.
+ * Інверсія {@link parseModelId} — застосовується до фактично резолвленої
+ * pi-моделі (`session.model`), коли consumer лишив `modelSpec` порожнім і pi
+ * сам вибрав дефолт (локальний чи хмарний).
+ * @param {{provider: string, id: string}|null|undefined} model pi Model-об'єкт
+ * @returns {string|null} `"provider/model-id"` або `null`, якщо модель відсутня
+ */
+export function formatModelSpec(model) {
+  if (!model || !model.provider || !model.id) return null
+  return `${model.provider}/${model.id}`
+}
+
 // ── Класифікація local vs cloud ──────────────────────────────────────────────
 
 /** Провайдери, що вважаються локальними. Override: `N_LLM_LOCAL_PROVIDERS` (кома-список). */

package/lib/one-shot.mjs

@@ -17,7 +17,7 @@
  * ретраїти нема куди, RAM-стеля фіксована (fail-fast політика пакета).
  */
 
-import { isLocalModel, resolveModel } from './model-tiers.mjs'
+import { formatModelSpec, isLocalModel, resolveModel } from './model-tiers.mjs'
 import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { failOnMemoryGuard } from './internal/memory-guard.mjs'
 import { writeTrace } from './trace.mjs'
@@ -158,12 +158,17 @@ export async function runOneShot({
     failOnMemoryGuard(promptError, userText)
   }
 
-  chain?.note({ model: spec, usage, error: promptError, stopReason })
+  // spec порожній/нерозв'язаний ('' → pi сам вибирає дефолт) — беремо фактично
+  // резолвлену pi-модель із сесії, щоб chain.note()/trace не бачили порожній
+  // model і не потрапляли в неявний cloud-бакет (isLocalModel('') === false).
+  const resolvedModel = spec || formatModelSpec(session.model)
+
+  chain?.note({ model: resolvedModel, usage, error: promptError, stopReason })
   trace({
     caller,
     backend: 'pi-ai',
     kind: 'one-shot',
-    model: spec,
+    model: resolvedModel,
     cwd: cwd ?? null,
     usage,
     stopReason,
@@ -175,12 +180,12 @@ export async function runOneShot({
     chainId: chain?.traceFields()?.chainId,
     caller,
     step: chain?.traceFields()?.chainStep,
-    model: spec,
+    model: resolvedModel,
     promptHash: pHash,
     prompt: userText,
     output: text.trim(),
     usage,
     error: promptError
   })
-  return { content: text.trim(), usage, error: promptError, model: spec, stopReason, caller }
+  return { content: text.trim(), usage, error: promptError, model: resolvedModel, stopReason, caller }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.7.5",
+  "version": "2.7.6",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",