@nodaro/shared 2.7.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/llm-models.test.ts

@@ -6,12 +6,18 @@ import {
   LLM_REASONING_EFFORTS,
   getLlmModel,
   getLlmTier,
+  getLlmModalityCaps,
+  VIDEO_ANALYSIS_LLM_MODELS,
   buildLlmCreditIdentifier,
   resolveLlmCreditId,
   motionGraphicsFeature,
   effectiveReasoningEffort,
   supportsAdvancedMode,
   availableReasoningEfforts,
+  LLM_VENDOR_ORDER,
+  LLM_VENDOR_LABELS,
+  groupLlmModelsByVendor,
+  orderedLlmModels,
 } from "../llm-models.js"
 import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
 import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
@@ -28,6 +34,7 @@ import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
 const EXPECTED_MODEL_IDS = [
   "gemini-3-flash",
   "gemini-3.6-flash",
+  "gemini-3.7-flash",
   "claude-haiku-4.5",
   "claude-sonnet-4.6",
   "gpt-5.2",
@@ -38,6 +45,7 @@ const EXPECTED_MODEL_IDS = [
   "gpt-5.6-luna",
   "gpt-5.6-terra",
   "gpt-5.6-sol",
+  "grok-4.6",
   "claude-sonnet-5",
   "claude-opus-4.8",
   "claude-opus-5",
@@ -86,13 +94,13 @@ describe("LLM_MODELS data integrity", () => {
     expect(new Set(ids).size).toBe(ids.length)
   })
 
-  it("has 4 economy, 4 standard, 8 premium models", () => {
+  it("has 5 economy, 5 standard, 8 premium models", () => {
     const tierCounts: Record<LlmTier, number> = { economy: 0, standard: 0, premium: 0 }
     for (const model of LLM_MODELS) {
       tierCounts[model.tier]++
     }
-    expect(tierCounts.economy).toBe(4)
-    expect(tierCounts.standard).toBe(4)
+    expect(tierCounts.economy).toBe(5)
+    expect(tierCounts.standard).toBe(5)
     expect(tierCounts.premium).toBe(8)
   })
 
@@ -103,11 +111,12 @@ describe("LLM_MODELS data integrity", () => {
     expect(formats).toContain("responses")
   })
 
-  it("all three vendors are represented", () => {
+  it("all four vendors are represented", () => {
     const vendors = new Set(LLM_MODELS.map((m) => m.vendor))
     expect(vendors).toContain("anthropic")
     expect(vendors).toContain("google")
     expect(vendors).toContain("openai")
+    expect(vendors).toContain("xai")
   })
 
   it("all models support images", () => {
@@ -472,6 +481,7 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "claude-sonnet-4.6",
         "gemini-3-flash",
         "gemini-3.6-flash",
+        "gemini-3.7-flash",
         "gemini-3.1-pro",
         "claude-sonnet-5",
         "claude-opus-4.8",
@@ -484,15 +494,18 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "gpt-5.6-luna",
         "gpt-5.6-terra",
         "gpt-5.6-sol",
+        // responses-format Grok — vision + text.format live-verified 2026-08-18.
+        "grok-4.6",
       ].sort(),
     )
   })
 
-  it("includes Anthropic (forced-tool), Gemini (response_format), and OpenAI (responses text.format) vendors", () => {
+  it("includes Anthropic (forced-tool), Gemini (response_format), and OpenAI/xAI (responses text.format) vendors", () => {
     const vendors = new Set(STRUCTURED_VISION_MODELS.map((m) => m.vendor))
     expect(vendors).toContain("anthropic")
     expect(vendors).toContain("google")
     expect(vendors).toContain("openai")
+    expect(vendors).toContain("xai")
   })
 
   it("excludes chat-completions GPT models — no native structured mode there (parse+retry only)", () => {
@@ -509,9 +522,9 @@ describe("STRUCTURED_VISION_MODELS", () => {
 })
 
 // ---------------------------------------------------------------------------
-// Reasoning effort registry (GPT-5.6 / Claude Sonnet 5 / Claude Opus 4.8)
-// grok-4.5 is DEFERRED — its chat endpoint is not live on the provider yet
-// (2026-07-13); its tests are intentionally omitted here.
+// Reasoning effort registry (GPT-5.6 / Claude Sonnet 5 / Claude Opus 4.8 /
+// Grok 4.6 — grok-4.5 was deferred on 2026-07-13 because its chat endpoint
+// wasn't live; grok-4.6 is its activation, live-verified 2026-08-18.)
 // ---------------------------------------------------------------------------
 describe("reasoning effort registry", () => {
   it("every reasoningEfforts list is a subset of the superset, in ascending order", () => {
@@ -526,6 +539,7 @@ describe("reasoning effort registry", () => {
     expect(getLlmTier("gpt-5.6-luna")).toBe("economy")
     expect(getLlmTier("gpt-5.6-terra")).toBe("standard")
     expect(getLlmTier("gpt-5.6-sol")).toBe("premium")
+    expect(getLlmTier("grok-4.6")).toBe("standard")
     expect(getLlmTier("claude-sonnet-5")).toBe("standard")
     expect(getLlmTier("claude-opus-4.8")).toBe("premium")
     expect(getLlmTier("gpt-5.5")).toBe("premium")
@@ -557,6 +571,62 @@ describe("reasoning effort registry", () => {
     expect(getLlmModel("claude-fable-5")?.reasoningEfforts).toEqual(["low", "medium", "high", "xhigh", "max"])
     expect(getLlmModel("claude-fable-5")?.directFallbackModel).toBe("claude-fable-5")
   })
+
+  it("grok-4.6: responses format on the grok family path, KIE's documented effort enum, no sampling params, reasons by default", () => {
+    const m = getLlmModel("grok-4.6")
+    expect(m?.vendor).toBe("xai")
+    expect(m?.kieFormat).toBe("responses")
+    expect(m?.kieSlugOrModel).toBe("grok-4-6")
+    expect(m?.structuredOutputMode).toBe("responses-json-schema")
+    // KIE's enum is low..xhigh with NO `none` — the endpoint reasons
+    // unconditionally (thinkingDefaultOn), so `none` would be a lie.
+    expect(m?.reasoningEfforts).toEqual(["low", "medium", "high", "xhigh"])
+    // Live-probed 2026-08-18: temperature is silently ignored — never send it.
+    expect(m?.supportsTemperature).toBe(false)
+    // Load-bearing: consumers floor max_tokens off this flag (a trivial probe
+    // spent 169/170 output tokens on reasoning with no reasoning param sent).
+    expect(m?.thinkingDefaultOn).toBe(true)
+    // KIE-only: no direct lane on either vendor SDK.
+    expect(m?.directFallbackModel).toBeUndefined()
+    expect(m?.directGeminiModel).toBeUndefined()
+  })
+
+  it("grok-4.6 resolves from its dash-form wire slug", () => {
+    expect(getLlmModel("grok-4-6")?.id).toBe("grok-4.6")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// gemini-3.7-flash exposure (both lanes live-verified 2026-08-18: KIE
+// chat-completions with reasoning_effort + enforced response_format, and the
+// direct Google id resolving on generativelanguage)
+// ---------------------------------------------------------------------------
+describe("gemini-3.7-flash exposure", () => {
+  it("KIE-first chat-completions with a direct lane — 3.6-flash's proven shape", () => {
+    const m = getLlmModel("gemini-3.7-flash")
+    expect(m?.tier).toBe("economy")
+    expect(m?.vendor).toBe("google")
+    expect(m?.kieFormat).toBe("chat-completions")
+    expect(m?.kieSlugOrModel).toBe("gemini-3-7-flash-openai")
+    // KIE-first on purpose (no preferDirect): the cheap lane serves Generate
+    // Text; the direct lane is Advanced mode + the reliability fallback.
+    expect(m?.preferDirect).toBeUndefined()
+    expect(m?.directGeminiModel).toBe("gemini-3.7-flash")
+    expect(m?.reasoningEfforts).toEqual(["low", "high"])
+    expect(m?.structuredOutputMode).toBe("kie-response-format")
+    expect(supportsAdvancedMode("gemini-3.7-flash")).toBe(true)
+    expect(availableReasoningEfforts("gemini-3.7-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("stays OUT of video-analysis — image-only modality caps by decision, not omission", () => {
+    // Full video+audio caps would auto-enroll it in VIDEO_ANALYSIS_LLM_MODELS
+    // and force a VA tier + pricing decision that is deliberately deferred
+    // while the smart-family A/B routes this model internally (2026-08-18).
+    // If this test goes red, someone flipped the caps — that flip is only
+    // valid TOGETHER with the VA-side tier/pricing decision.
+    expect(getLlmModalityCaps("gemini-3.7-flash")).toEqual({ image: true, video: false, audio: false })
+    expect(VIDEO_ANALYSIS_LLM_MODELS).not.toContain("gemini-3.7-flash")
+  })
 })
 
 describe("effectiveReasoningEffort", () => {
@@ -584,6 +654,7 @@ describe("buildLlmCreditIdentifier effort bump (xhigh/max only)", () => {
   })
   it("standard + xhigh → premium", () => {
     expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.6-terra", "xhigh")).toBe("llm-chat:premium")
+    expect(buildLlmCreditIdentifier("llm-chat", "grok-4.6", "xhigh")).toBe("llm-chat:premium")
   })
   it("premium + max stays premium", () => {
     expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.6-sol", "max")).toBe("llm-chat:premium")
@@ -767,3 +838,58 @@ describe("lane-aware reasoning efforts", () => {
     expect(bad).toEqual([])
   })
 })
+
+// ---------------------------------------------------------------------------
+// Vendor grouping — the ONE ordering every LLM model menu renders
+// ---------------------------------------------------------------------------
+describe("groupLlmModelsByVendor / orderedLlmModels", () => {
+  it("every vendor in the union has an order slot AND a label (totality)", () => {
+    // A new vendor added to LlmVendor without a menu decision would silently
+    // sort its models to the end of every picker unlabeled — fail here instead.
+    const vendorsInUse = new Set(LLM_MODELS.map((m) => m.vendor))
+    for (const v of vendorsInUse) {
+      expect(LLM_VENDOR_ORDER, `vendor "${v}" missing from LLM_VENDOR_ORDER`).toContain(v)
+      expect(LLM_VENDOR_LABELS[v], `vendor "${v}" missing from LLM_VENDOR_LABELS`).toBeTruthy()
+    }
+    for (const v of LLM_VENDOR_ORDER) {
+      expect(LLM_VENDOR_LABELS[v]).toBeTruthy()
+    }
+  })
+
+  it("covers every model exactly once, in vendor order", () => {
+    const groups = groupLlmModelsByVendor()
+    const flattened = groups.flatMap((g) => g.models.map((m) => m.id))
+    expect(flattened.sort()).toEqual(LLM_MODELS.map((m) => m.id).sort())
+    expect(new Set(flattened).size).toBe(flattened.length)
+    const groupVendors = groups.map((g) => g.vendor)
+    expect(groupVendors).toEqual(LLM_VENDOR_ORDER.filter((v) => groupVendors.includes(v)))
+  })
+
+  it("inside each group models are tier-ordered economy → standard → premium", () => {
+    const rank = { economy: 0, standard: 1, premium: 2 } as const
+    for (const g of groupLlmModelsByVendor()) {
+      const ranks = g.models.map((m) => rank[m.tier])
+      expect(ranks, g.vendor).toEqual([...ranks].sort((a, b) => a - b))
+    }
+  })
+
+  it("groups carry their display label and omit empty groups after a filter", () => {
+    const groups = groupLlmModelsByVendor(LLM_MODELS.filter((m) => m.vendor === "xai"))
+    expect(groups).toHaveLength(1)
+    expect(groups[0].label).toBe("xAI")
+    expect(groups[0].models.map((m) => m.id)).toEqual(["grok-4.6"])
+  })
+
+  it("does not mutate the registry (registry order is load-bearing for LLM_MODEL_IDS)", () => {
+    const before = LLM_MODELS.map((m) => m.id)
+    groupLlmModelsByVendor()
+    orderedLlmModels()
+    expect(LLM_MODELS.map((m) => m.id)).toEqual(before)
+  })
+
+  it("orderedLlmModels is the flattened grouping", () => {
+    expect(orderedLlmModels().map((m) => m.id)).toEqual(
+      groupLlmModelsByVendor().flatMap((g) => g.models.map((m) => m.id)),
+    )
+  })
+})

package/src/index.ts

@@ -281,6 +281,12 @@ export {
   LLM_MODELS,
   LLM_MODEL_IDS,
   STRUCTURED_VISION_MODELS,
+  LLM_VENDOR_ORDER,
+  LLM_VENDOR_LABELS,
+  groupLlmModelsByVendor,
+  orderedLlmModels,
+  type LlmVendor,
+  type LlmModelGroup,
   VIDEO_ANALYSIS_LLM_MODELS,
   VIDEO_ANALYSIS_TIERS,
   VIDEO_ANALYSIS_LEGACY_MODELS,

package/src/llm-models.ts

@@ -15,6 +15,7 @@
 
 export type LlmTier = "economy" | "standard" | "premium"
 export type KieApiFormat = "chat-completions" | "messages" | "responses"
+export type LlmVendor = "anthropic" | "google" | "openai" | "xai"
 
 export const LLM_REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"] as const
 export type LlmReasoningEffort = (typeof LLM_REASONING_EFFORTS)[number]
@@ -32,7 +33,7 @@ export interface LlmModelDef {
    *  For messages: the model id sent in the body (e.g. "claude-haiku-4-5-v1messages").
    *  For responses: the model id sent in the body (e.g. "gpt-5-4"). */
   kieSlugOrModel: string
-  vendor: "anthropic" | "google" | "openai"
+  vendor: LlmVendor
   supportsImages: boolean
   maxOutputTokens: number
   /**
@@ -159,6 +160,30 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // direct is the reliability fallback only.
     directGeminiModel: "gemini-3.6-flash",
   },
+  {
+    id: "gemini-3.7-flash",
+    displayName: "Gemini 3.7 Flash",
+    desc: "Newest fast Gemini, agentic-tuned",
+    tier: "economy",
+    kieFormat: "chat-completions",
+    // KIE serves it on the OpenAI-compatible dialect under this slug
+    // (docs.kie.ai/market/gemini/gemini-3-7-flash-openai.md) — same
+    // chat-completions path shape as gemini-3.6-flash.
+    kieSlugOrModel: "gemini-3-7-flash-openai",
+    vendor: "google",
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    // Google's own cap is 65,536, but the field feeds BOTH lanes and the KIE
+    // flash endpoints cap at 8192 (the measured 3.6 posture) — stay at the
+    // KIE-safe intersection, same reasoning as `reasoningEfforts` below.
+    maxOutputTokens: 8192,
+    // KIE's 3.7 endpoint enumerates reasoning_effort low | high (verified
+    // against its OpenAPI spec 2026-08-18), identical to 3.6.
+    reasoningEfforts: ["low", "high"],
+    // Assumed parity with 3.6 pending a live probe on the direct lane.
+    directReasoningEfforts: ["none", "low", "medium", "high"],
+    directGeminiModel: "gemini-3.7-flash",
+  },
   {
     id: "claude-haiku-4.5",
     displayName: "Claude Haiku 4.5",
@@ -321,7 +346,35 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
     supportsTemperature: false,
   },
-  // grok-4.5 deferred — KIE chat endpoint not yet live (2026-07-13); add entry + rate row + docs when it activates.
+  {
+    id: "grok-4.6",
+    displayName: "Grok 4.6",
+    desc: "xAI flagship, strong reasoning",
+    tier: "standard",
+    kieFormat: "responses",
+    // KIE serves Grok on the responses dialect under its own family path —
+    // grok/v1/responses, NOT codex/v1/responses (llm-client derives the path
+    // from `vendor`). Live-verified end-to-end 2026-08-18: array `input`,
+    // `developer` system role, `input_image` URL vision, `text.format`
+    // json_schema enforcement, SSE `response.output_text.delta` stream, and
+    // `credits_consumed` actual-cost capture. (grok-4.5 was deferred 2026-07-13
+    // because none of this was live; 4.6 is its activation.)
+    kieSlugOrModel: "grok-4-6",
+    vendor: "xai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    // KIE's documented enum, each level live-verified (echoed back) 2026-08-18.
+    // No `none`: the endpoint reasons unconditionally (see thinkingDefaultOn).
+    reasoningEfforts: ["low", "medium", "high", "xhigh"],
+    // Live-probed 2026-08-18: `temperature` is silently IGNORED (request echo
+    // stays at the 0.7 default), so never send it — same treatment as GPT-5.5+.
+    supportsTemperature: false,
+    // Reasons with NO reasoning param sent (effort defaults to "low" server-side
+    // — a trivial probe spent 169 of 170 output tokens on reasoning), so every
+    // call needs output headroom, not just xhigh.
+    thinkingDefaultOn: true,
+  },
   {
     id: "claude-sonnet-5",
     displayName: "Claude Sonnet 5",
@@ -407,6 +460,55 @@ export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
   (m) => m.supportsImages && m.structuredOutputMode != null,
 )
 
+/**
+ * Vendor presentation order + labels for model pickers. Every LlmVendor MUST
+ * appear in the order list (guarded by a registry test) so a new vendor can't
+ * ship with its models silently sorted to the end of every menu unlabeled.
+ * Alphabetical on purpose: stable, and no vendor-preference fights.
+ */
+export const LLM_VENDOR_ORDER: readonly LlmVendor[] = ["anthropic", "google", "openai", "xai"]
+export const LLM_VENDOR_LABELS: Record<LlmVendor, string> = {
+  anthropic: "Anthropic",
+  google: "Google",
+  openai: "OpenAI",
+  xai: "xAI",
+}
+
+const TIER_RANK: Record<LlmTier, number> = { economy: 0, standard: 1, premium: 2 }
+
+export interface LlmModelGroup {
+  vendor: LlmVendor
+  /** Display heading for the group (LLM_VENDOR_LABELS[vendor]). */
+  label: string
+  models: LlmModelDef[]
+}
+
+/**
+ * The ONE ordering every LLM model menu renders: grouped by vendor (in
+ * LLM_VENDOR_ORDER), and inside each group sorted economy → standard → premium
+ * (registry order breaks ties, which keeps family generations adjacent).
+ * A flat registry-order dump was genuinely hard to scan at 17 models — every
+ * picker (config panel, quick strips, quick toolbar) derives from this so the
+ * menus can't drift apart. Groups with no models (after `filter`) are omitted.
+ */
+export function groupLlmModelsByVendor(models: readonly LlmModelDef[] = LLM_MODELS): LlmModelGroup[] {
+  const groups: LlmModelGroup[] = []
+  for (const vendor of LLM_VENDOR_ORDER) {
+    const members = models
+      .filter((m) => m.vendor === vendor)
+      .sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier])
+    if (members.length > 0) groups.push({ vendor, label: LLM_VENDOR_LABELS[vendor], models: members })
+  }
+  return groups
+}
+
+/** {@link groupLlmModelsByVendor} flattened — for menus that can't render
+ *  group headers (e.g. the compact node quick strips) but should still read
+ *  vendor-clustered and tier-ordered. */
+export function orderedLlmModels(models: readonly LlmModelDef[] = LLM_MODELS): LlmModelDef[] {
+  return groupLlmModelsByVendor(models).flatMap((g) => g.models)
+}
+
 export type LlmFeature =
   | "ai-writer"
   | "llm-chat"
@@ -465,6 +567,12 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
 export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean; audio: boolean }> = {
   "gemini-3-flash":    { image: true,  video: true,  audio: true  },
   "gemini-3.6-flash":  { image: true,  video: true,  audio: true  },
+  // gemini-3.7-flash is IMAGE-ONLY by DECISION, not omission: full video+audio
+  // caps would auto-enroll it in VIDEO_ANALYSIS_LLM_MODELS (derived below) and
+  // force a video-analysis tier + pricing decision that is deliberately
+  // deferred while the smart-family A/B routes this model internally (#747).
+  // Flip these two flags ONLY together with that VA-side decision.
+  "gemini-3.7-flash":  { image: true,  video: false, audio: false },
   "gemini-3.1-pro":    { image: true,  video: true,  audio: true  },
   "claude-haiku-4.5":  { image: true,  video: false, audio: false },
   "claude-sonnet-4.6": { image: true,  video: false, audio: false },
@@ -475,6 +583,7 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "gpt-5.6-luna":      { image: true,  video: false, audio: false },
   "gpt-5.6-terra":     { image: true,  video: false, audio: false },
   "gpt-5.6-sol":       { image: true,  video: false, audio: false },
+  "grok-4.6":          { image: true,  video: false, audio: false },
   "claude-sonnet-5":   { image: true,  video: false, audio: false },
   "claude-opus-4.8":   { image: true,  video: false, audio: false },
   "claude-opus-5":     { image: true,  video: false, audio: false },