@nodaro/shared 1.7.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.7.0",
+  "version": "1.10.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__/credit-identifiers.test.ts

@@ -17,6 +17,8 @@ describe("buildCreditModelIdentifier", () => {
       "seedream-edit",
       "seedream-5-lite",
       "seedream-5-lite-i2i",
+      "seedream-5-pro",
+      "seedream-5-pro-i2i",
     ]
 
     it.each(highQualityProviders)(

package/src/__tests__/image-ref-limit.test.ts

@@ -16,7 +16,9 @@ describe("imageReferenceLimit", () => {
     "flux-2-max": 8,
     "gpt-image-2": 16, // → gpt-image-2-i2i
     "seedream-5-lite": 16, // → seedream-5-lite-i2i
+    "seedream-5-pro": 16, // → seedream-5-pro-i2i
     "nano-banana-2": 4,
+    "nano-banana-2-lite": 10, // schema maxItems (image_urls)
     flux: 4, // → flux-pro-i2i
     "flux-2-klein": 1, // product cap (schema array slices at 5)
     "flux-2-pro": 4, // product cap (BFL schema accepts 8)

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

@@ -3,11 +3,13 @@ import {
   LLM_MODEL_IDS,
   LLM_FEATURE_DEFAULTS,
   STRUCTURED_VISION_MODELS,
+  LLM_REASONING_EFFORTS,
   getLlmModel,
   getLlmTier,
   buildLlmCreditIdentifier,
   resolveLlmCreditId,
   motionGraphicsFeature,
+  effectiveReasoningEffort,
 } from "../llm-models.js"
 import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
 
@@ -21,8 +23,8 @@ import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
 // LLM_MODELS data integrity
 // ---------------------------------------------------------------------------
 describe("LLM_MODELS data integrity", () => {
-  it("should have exactly 7 models", () => {
-    expect(LLM_MODELS).toHaveLength(7)
+  it("should have exactly 13 models", () => {
+    expect(LLM_MODELS).toHaveLength(13)
   })
 
   it("each model has all required fields", () => {
@@ -57,14 +59,14 @@ describe("LLM_MODELS data integrity", () => {
     expect(new Set(ids).size).toBe(ids.length)
   })
 
-  it("has 2 economy, 2 standard, 3 premium models", () => {
+  it("has 3 economy, 4 standard, 6 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(2)
-    expect(tierCounts.standard).toBe(2)
-    expect(tierCounts.premium).toBe(3)
+    expect(tierCounts.economy).toBe(3)
+    expect(tierCounts.standard).toBe(4)
+    expect(tierCounts.premium).toBe(6)
   })
 
   it("all three kieFormats are represented", () => {
@@ -111,6 +113,12 @@ describe("LLM_MODEL_IDS", () => {
       "gemini-3.1-pro",
       "claude-opus-4.7",
       "gpt-5.4",
+      "gpt-5.5",
+      "gpt-5.6-luna",
+      "gpt-5.6-terra",
+      "gpt-5.6-sol",
+      "claude-sonnet-5",
+      "claude-opus-4.8",
     ]
     expect(LLM_MODEL_IDS).toEqual(expected)
   })
@@ -420,20 +428,29 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "claude-sonnet-4.6",
         "gemini-3-flash",
         "gemini-3.1-pro",
+        "claude-sonnet-5",
+        "claude-opus-4.8",
+        // responses-format GPTs — KIE text.format json_schema live-verified
+        // 2026-07-14 (text AND vision inputs).
+        "gpt-5.4",
+        "gpt-5.5",
+        "gpt-5.6-luna",
+        "gpt-5.6-terra",
+        "gpt-5.6-sol",
       ].sort(),
     )
   })
 
-  it("includes Anthropic (forced-tool) AND Gemini (response_format) vendors", () => {
+  it("includes Anthropic (forced-tool), Gemini (response_format), and OpenAI (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")
   })
 
-  it("excludes GPT models — no native structured mode (parse+retry only)", () => {
+  it("excludes chat-completions GPT models — no native structured mode there (parse+retry only)", () => {
     const ids = STRUCTURED_VISION_MODELS.map((m) => m.id)
     expect(ids).not.toContain("gpt-5.2")
-    expect(ids).not.toContain("gpt-5.4")
   })
 
   it("every member is vision-capable and has a structuredOutputMode", () => {
@@ -443,3 +460,78 @@ 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.
+// ---------------------------------------------------------------------------
+describe("reasoning effort registry", () => {
+  it("every reasoningEfforts list is a subset of the superset, in ascending order", () => {
+    const rank = Object.fromEntries(LLM_REASONING_EFFORTS.map((e, i) => [e, i]))
+    for (const m of LLM_MODELS) {
+      for (const e of m.reasoningEfforts ?? []) expect(LLM_REASONING_EFFORTS).toContain(e)
+      const ranks = (m.reasoningEfforts ?? []).map((e) => rank[e])
+      expect([...ranks].sort((a, b) => a - b)).toEqual(ranks)
+    }
+  })
+  it("new models exist with expected tiers", () => {
+    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("claude-sonnet-5")).toBe("standard")
+    expect(getLlmTier("claude-opus-4.8")).toBe("premium")
+    expect(getLlmTier("gpt-5.5")).toBe("premium")
+  })
+})
+
+describe("effectiveReasoningEffort", () => {
+  it("passes through a supported level", () => {
+    expect(effectiveReasoningEffort("claude-sonnet-5", "max")).toBe("max")
+  })
+  it("clamps down to the highest supported level ≤ requested", () => {
+    expect(effectiveReasoningEffort("gpt-5.4", "xhigh")).toBe("high")
+  })
+  it("returns undefined when the model has no levels", () => {
+    expect(effectiveReasoningEffort("gemini-3-flash", "high")).toBeUndefined()
+  })
+  it("returns undefined for none on Claude (below its lowest level)", () => {
+    expect(effectiveReasoningEffort("claude-sonnet-5", "none")).toBeUndefined()
+  })
+  it("returns undefined for undefined/garbage input", () => {
+    expect(effectiveReasoningEffort("claude-sonnet-5", undefined)).toBeUndefined()
+    expect(effectiveReasoningEffort("claude-sonnet-5", "turbo")).toBeUndefined()
+  })
+})
+
+describe("buildLlmCreditIdentifier effort bump (xhigh/max only)", () => {
+  it("economy + max → standard (bare feature)", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.6-luna", "max")).toBe("llm-chat")
+  })
+  it("standard + xhigh → premium", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.6-terra", "xhigh")).toBe("llm-chat:premium")
+  })
+  it("premium + max stays premium", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.6-sol", "max")).toBe("llm-chat:premium")
+  })
+  it("high never bumps", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "claude-sonnet-5", "high")).toBe("llm-chat")
+  })
+  it("clamp on a partial-list standard model never bumps (sonnet-4.6 @ xhigh → high)", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "claude-sonnet-4.6", "xhigh")).toBe("llm-chat")
+  })
+  it("bump uses the CLAMPED effort (xhigh on a low/medium/high model clamps to high → no bump)", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.4", "xhigh")).toBe("llm-chat:premium")
+    // gpt-5.4 is premium anyway; the real clamp case:
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash", "max")).toBe("llm-chat:economy")
+  })
+  it("back-compat: no effort arg → identical to today for every model", () => {
+    for (const m of LLM_MODELS) {
+      const before = m.tier === "standard" ? "x" : `x:${m.tier}`
+      expect(buildLlmCreditIdentifier("x", m.id)).toBe(before)
+    }
+  })
+  it("resolveLlmCreditId reads reasoningEffort from the raw body", () => {
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gpt-5.6-terra", reasoningEffort: "max" })).toBe("llm-chat:premium")
+  })
+})

package/src/__tests__/prompt-length-limits.test.ts

@@ -28,6 +28,7 @@ describe("per-model prompt length limits", () => {
   describe("getMaxImagePromptChars", () => {
     it("returns the verified higher caps (provider supports more than 5000)", () => {
       expect(getMaxImagePromptChars("nano-banana-2")).toBe(20000)
+      expect(getMaxImagePromptChars("nano-banana-2-lite")).toBe(20000)
       expect(getMaxImagePromptChars("nano-banana-pro")).toBe(20000)
       expect(getMaxImagePromptChars("gpt-image-2-i2i")).toBe(20000)
     })
@@ -44,6 +45,8 @@ describe("per-model prompt length limits", () => {
     it("falls back to IMAGE_PROMPT_MAX for verified-default + unknown providers", () => {
       expect(getMaxImagePromptChars("flux")).toBe(IMAGE_PROMPT_MAX)
       expect(getMaxImagePromptChars("imagen4")).toBe(IMAGE_PROMPT_MAX)
+      expect(getMaxImagePromptChars("seedream-5-pro")).toBe(IMAGE_PROMPT_MAX) // verified 5000 in KIE schema
+      expect(getMaxImagePromptChars("seedream-5-pro-i2i")).toBe(IMAGE_PROMPT_MAX) // verified 5000 in KIE schema
       expect(getMaxImagePromptChars("grok-i2i")).toBe(IMAGE_PROMPT_MAX) // 390000 doc = sanity-capped
       expect(getMaxImagePromptChars("flux-kontext")).toBe(IMAGE_PROMPT_MAX) // UNVERIFIED
       expect(getMaxImagePromptChars(undefined)).toBe(IMAGE_PROMPT_MAX)

package/src/__tests__/seedance2-continuation-ref.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest"
+import {
+  SEEDANCE_2_CONTINUATION_REF_SEC,
+  SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC,
+  SEEDANCE_2_EXTEND_STITCH,
+} from "../model-constants.js"
+
+/** KIE hard-rejects r2v reference videos below the floor: "the parameter
+ *  video duration (seconds) specified in the request must be greater than or
+ *  equal to 1.8 for model dreamina-seedance-2-0-fast in r2v" (2026-07-13,
+ *  job dbf95612 — the original 1.0s tails made every generate-video-pro
+ *  continuation segment fail deterministically). Everything this platform
+ *  sends as a Seedance-2 video reference cuts SEEDANCE_2_CONTINUATION_REF_SEC
+ *  seconds; do NOT "optimize" it back below the floor. The private-plugin
+ *  twin constants (nodaro-cloud-plugins chain.ts TAIL_SEC / bridge-math.ts
+ *  MIN_REF) are guarded by that repo's r2v-ref-floor.test.ts — keep in sync. */
+describe("seedance-2 continuation-reference floor (do not regress)", () => {
+  it("the platform's continuation-ref length clears KIE's r2v minimum", () => {
+    expect(SEEDANCE_2_CONTINUATION_REF_SEC).toBeGreaterThanOrEqual(SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC)
+  })
+  it("the extend node's tail IS the shared continuation-ref length (single source)", () => {
+    expect(SEEDANCE_2_EXTEND_STITCH.referenceTailSeconds).toBe(SEEDANCE_2_CONTINUATION_REF_SEC)
+  })
+})

package/src/__tests__/video-analysis-pricing.test.ts

@@ -5,13 +5,16 @@ import {
   pickVideoAnalysisBucket, buildVideoAnalysisCreditId, bucketSecondsFromCreditId,
   videoAnalysisNumWindows,
 } from "../video-analysis-pricing.js"
-import { VIDEO_ANALYSIS_LLM_MODELS } from "../llm-models.js"
+import {
+  VIDEO_ANALYSIS_LLM_MODELS, VIDEO_ANALYSIS_TIERS, VIDEO_ANALYSIS_TIER_ORDER,
+  DEFAULT_VIDEO_ANALYSIS_TIER, DEFAULT_VIDEO_ANALYSIS_MODEL, resolveVideoAnalysisModel,
+} from "../llm-models.js"
 
 // The measured-rate constants and the $-derived `videoAnalysisBucketCredits`
-// formula moved to backend/src/lib/pricing/video-analysis-cost.ts (S5) — its
-// tests (including the worked-example bucket-credit values and the
-// cross-check against VIDEO_ANALYSIS_BUCKET_CREDITS below) live in
-// backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts. This file
+// formula are PRIVATE, in @nodaroai/cloud-plugins
+// (src/plugins/video-analysis/cost.ts) — its tests (the worked-example
+// bucket-credit values and the cross-check against VIDEO_ANALYSIS_BUCKET_CREDITS
+// below) live in that private package's __tests__/cost.test.ts. This file
 // covers only the NON-monetary duration-bucketing, window-batching, and
 // credit-id-construction logic that stays in the published package.
 
@@ -40,6 +43,26 @@ describe("video-analysis-pricing", () => {
     expect(VIDEO_ANALYSIS_LLM_MODELS).toEqual(["gemini-3-flash", "gemini-3.1-pro"])
   })
 
+  it("tier layer: every tier maps to a real model AND every model is tier-reachable (no vendor leak)", () => {
+    // Adding a video-analysis model without a tier would silently leave it
+    // unreachable / unnamed — this fails until a tier decision is made.
+    const tierTargets = Object.values(VIDEO_ANALYSIS_TIERS)
+    for (const m of tierTargets) expect(VIDEO_ANALYSIS_LLM_MODELS).toContain(m)
+    for (const m of VIDEO_ANALYSIS_LLM_MODELS) expect(tierTargets).toContain(m)
+    expect(new Set(VIDEO_ANALYSIS_TIER_ORDER)).toEqual(new Set(Object.keys(VIDEO_ANALYSIS_TIERS)))
+  })
+
+  it("resolveVideoAnalysisModel: tier → model, raw model passthrough, default pro on empty/unknown", () => {
+    expect(DEFAULT_VIDEO_ANALYSIS_TIER).toBe("pro")
+    expect(DEFAULT_VIDEO_ANALYSIS_MODEL).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("pro")).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("fast")).toBe("gemini-3-flash")
+    expect(resolveVideoAnalysisModel("gemini-3-flash")).toBe("gemini-3-flash") // raw passthrough
+    expect(resolveVideoAnalysisModel(undefined)).toBe("gemini-3.1-pro") // default → pro
+    expect(resolveVideoAnalysisModel("")).toBe("gemini-3.1-pro")
+    expect(resolveVideoAnalysisModel("nonsense")).toBe("gemini-3.1-pro") // unknown → default, never throws
+  })
+
   // Full drift-detection against the live $-formula lives in
   // backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts (this
   // package cannot see the formula post-S5). This is a lightweight shape

package/src/__tests__/video-analysis.test.ts

@@ -7,7 +7,7 @@ import {
 } from "../video-analysis.js"
 
 const slot: EntitySlot = { slotId: "hero", label: "Protagonist", source: "wired-character", role: "person", description: "tan man, mustache, black tee" }
-const baseScene = { startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} juggles a ball", audio: { mode: "speech" as const, content: "As a kid…", voice: "male, warm" } }
+const baseScene = { startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} juggles a ball", audio: [{ mode: "speech" as const, content: "As a kid…", voice: "male, warm" }] }
 
 describe("windowAnalysisSchema", () => {
   it("accepts a zero-scene window (quiet footage is a VALID result)", () => {

package/src/index.ts

@@ -19,6 +19,7 @@ export {
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   getMaxImagePromptChars,
   PROMPT_HARD_CEILING,
+  LLM_TEXT_INPUT_MAX,
   MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER,
   getMaxVideoPromptChars,
   NEGATIVE_PROMPT_MAX,
@@ -92,8 +93,11 @@ export {
   SEED_SUPPORT,
   RENDERING_SPEED_SUPPORT,
   GUIDANCE_SCALE_SUPPORT,
+  SEEDANCE_2_PROVIDERS,
   SEEDANCE_2_REF_LIMITS,
   SEEDANCE_2_EXTEND_STITCH,
+  SEEDANCE_2_R2V_MIN_REF_VIDEO_SEC,
+  SEEDANCE_2_CONTINUATION_REF_SEC,
   NATIVE_ADAPTIVE_ASPECT,
   VIDEO_REF_LIMITS_BY_PROVIDER,
   VIDEO_PROVIDERS_REQUIRING_IMAGE,
@@ -249,18 +253,30 @@ export {
   LLM_MODEL_IDS,
   STRUCTURED_VISION_MODELS,
   VIDEO_ANALYSIS_LLM_MODELS,
+  VIDEO_ANALYSIS_TIERS,
+  type VideoAnalysisTier,
+  VIDEO_ANALYSIS_TIER_ORDER,
+  DEFAULT_VIDEO_ANALYSIS_TIER,
+  DEFAULT_VIDEO_ANALYSIS_MODEL,
+  VIDEO_ANALYSIS_TIER_LABELS,
+  isVideoAnalysisTier,
+  resolveVideoAnalysisModel,
   LLM_FEATURE_DEFAULTS,
   LLM_MODALITY_CAPS,
+  LLM_REASONING_EFFORTS,
+  EFFORT_TIER_BUMP,
   getLlmModel,
   getLlmTier,
   getLlmModalityCaps,
   buildLlmCreditIdentifier,
   resolveLlmCreditId,
   motionGraphicsFeature,
+  effectiveReasoningEffort,
   type LlmTier,
   type LlmFeature,
   type KieApiFormat,
   type LlmModelDef,
+  type LlmReasoningEffort,
 } from "./llm-models.js"
 
 export {

package/src/llm-models.ts

@@ -16,6 +16,12 @@
 export type LlmTier = "economy" | "standard" | "premium"
 export type KieApiFormat = "chat-completions" | "messages" | "responses"
 
+export const LLM_REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"] as const
+export type LlmReasoningEffort = (typeof LLM_REASONING_EFFORTS)[number]
+/** Levels that bill one tier up. `high` is the Claude-family server default — it never bumps. */
+export const EFFORT_TIER_BUMP: ReadonlySet<LlmReasoningEffort> = new Set(["xhigh", "max"])
+const EFFORT_RANK: Record<LlmReasoningEffort, number> = { none: 0, low: 1, medium: 2, high: 3, xhigh: 4, max: 5 }
+
 export interface LlmModelDef {
   id: string
   displayName: string
@@ -31,16 +37,26 @@ export interface LlmModelDef {
   maxOutputTokens: number
   /**
    * How this model can be forced into schema-valid structured output.
-   * - "anthropic-tool"       → direct Anthropic SDK forced tool_choice (guaranteed).
-   * - "kie-response-format"  → KIE chat-completions `response_format: json_schema`
-   *                            (verified enforced for Gemini via KIE).
-   * - undefined              → no native structured mode (GPT-via-KIE doesn't honor
-   *                            response_format); callers fall back to parse + retry.
+   * - "anthropic-tool"          → forced tool_choice on the Claude wire (direct SDK
+   *                               guaranteed; KIE's proxy re-serializes the tool call
+   *                               as a `<tool_calls>` text tag — decoded in llm-client).
+   * - "kie-response-format"     → KIE chat-completions `response_format: json_schema`
+   *                               (verified enforced for Gemini via KIE).
+   * - "responses-json-schema"   → KIE codex/v1/responses `text.format: json_schema`
+   *                               (live-verified 2026-07-14 for gpt-5.4/5.5 and the
+   *                               whole GPT-5.6 family, text AND vision inputs).
+   * - undefined                 → no native mode; callers fall back to parse + retry.
    * Capability-driven so `llmCompleteStructured` never hardcodes provider ids.
    */
-  structuredOutputMode?: "anthropic-tool" | "kie-response-format"
+  structuredOutputMode?: "anthropic-tool" | "kie-response-format" | "responses-json-schema"
   /** If set, fallback to direct Anthropic SDK with this model ID when KIE.ai fails */
   directFallbackModel?: string
+  /** Effort levels this model accepts (ascending). Absent/empty = no effort lever, picker hidden. */
+  reasoningEfforts?: readonly LlmReasoningEffort[]
+  /** false = model rejects `temperature` (Claude 5-era, GPT-5.6). Absent = accepts. */
+  supportsTemperature?: false
+  /** Claude-only: KIE is the preferred routing, direct Anthropic the fallback. */
+  preferKie?: true
 }
 
 export const LLM_MODELS: readonly LlmModelDef[] = [
@@ -81,6 +97,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     supportsImages: true,
     maxOutputTokens: 16384,
     directFallbackModel: "claude-sonnet-4-6",
+    reasoningEfforts: ["low", "medium", "high", "max"],
   },
   {
     id: "gpt-5.2",
@@ -117,6 +134,9 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     supportsImages: true,
     maxOutputTokens: 16384,
     directFallbackModel: "claude-opus-4-7",
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+    preferKie: true,
   },
   {
     id: "gpt-5.4",
@@ -126,8 +146,99 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-4",
     vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    reasoningEfforts: ["low", "medium", "high"],
+  },
+  {
+    id: "gpt-5.5",
+    displayName: "GPT-5.5",
+    desc: "Previous flagship GPT, deep reasoning",
+    tier: "premium",
+    kieFormat: "responses",
+    kieSlugOrModel: "gpt-5-5",
+    vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+  },
+  {
+    id: "gpt-5.6-luna",
+    displayName: "GPT-5.6 Luna",
+    desc: "Fastest GPT-5.6, high-volume workloads",
+    tier: "economy",
+    kieFormat: "responses",
+    kieSlugOrModel: "gpt-5-6-luna",
+    vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+  },
+  {
+    id: "gpt-5.6-terra",
+    displayName: "GPT-5.6 Terra",
+    desc: "Balanced GPT-5.6 for production work",
+    tier: "standard",
+    kieFormat: "responses",
+    kieSlugOrModel: "gpt-5-6-terra",
+    vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+  },
+  {
+    id: "gpt-5.6-sol",
+    displayName: "GPT-5.6 Sol",
+    desc: "Flagship GPT-5.6, deepest reasoning",
+    tier: "premium",
+    kieFormat: "responses",
+    kieSlugOrModel: "gpt-5-6-sol",
+    vendor: "openai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    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: "claude-sonnet-5",
+    displayName: "Claude Sonnet 5",
+    desc: "Near-Opus quality at Sonnet cost",
+    tier: "standard",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-sonnet-5",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    directFallbackModel: "claude-sonnet-5",
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+    preferKie: true,
+  },
+  {
+    id: "claude-opus-4.8",
+    displayName: "Claude Opus 4.8",
+    desc: "Most capable Claude, long-horizon work",
+    tier: "premium",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-opus-4-8",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
     supportsImages: true,
     maxOutputTokens: 16384,
+    directFallbackModel: "claude-opus-4-8",
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+    preferKie: true,
   },
 ] as const
 
@@ -136,9 +247,10 @@ export const LLM_MODEL_IDS = LLM_MODELS.map((m) => m.id)
 /** Vision models that can return GUARANTEED structured output — the
  *  describe-to-picker analyzer forces a schema over an image, so its model
  *  pickers AND the backend route gate offer exactly these: Anthropic (forced
- *  tool) + Gemini (KIE `response_format`). GPT-via-KIE has no native structured
- *  mode (parse+retry only), so it's excluded. Single source of truth so the
- *  picker, the config panel, and the route gate can't drift. */
+ *  tool), Gemini (KIE `response_format`), and GPT responses-format models
+ *  (KIE `text.format` json_schema — vision+schema live-verified 2026-07-14).
+ *  Single source of truth so the picker, the config panel, and the route gate
+ *  can't drift. */
 export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
   (m) => m.supportsImages && m.structuredOutputMode != null,
 )
@@ -201,6 +313,12 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "claude-opus-4.7":   { image: true,  video: false, audio: false },
   "gpt-5.2":           { image: true,  video: false, audio: false },
   "gpt-5.4":           { image: true,  video: false, audio: false },
+  "gpt-5.5":           { image: true,  video: false, audio: false },
+  "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 },
+  "claude-sonnet-5":   { image: true,  video: false, audio: false },
+  "claude-opus-4.8":   { image: true,  video: false, audio: false },
 }
 
 /** Capability lookup with safe default — unknown models get image-only. */
@@ -217,29 +335,87 @@ export function getLlmTier(id: string): LlmTier {
   return getLlmModel(id)?.tier ?? "standard"
 }
 
+/** Highest level the model supports that is ≤ the requested level; undefined = treat as Auto. */
+export function effectiveReasoningEffort(
+  modelId: string | undefined,
+  requested?: string,
+): LlmReasoningEffort | undefined {
+  if (!requested || !(requested in EFFORT_RANK)) return undefined
+  const levels = getLlmModel(modelId ?? "")?.reasoningEfforts
+  if (!levels || levels.length === 0) return undefined
+  const req = requested as LlmReasoningEffort
+  let best: LlmReasoningEffort | undefined
+  for (const l of levels) {
+    if (EFFORT_RANK[l] <= EFFORT_RANK[req] && (best === undefined || EFFORT_RANK[l] > EFFORT_RANK[best])) best = l
+  }
+  return best
+}
+
 /**
  * Build a composite credit identifier for an LLM feature.
  * - economy tier → "ai-writer:economy"
  * - standard tier → "ai-writer" (no suffix — backward compatible)
  * - premium tier → "ai-writer:premium"
+ * A reasoning effort of "xhigh" or "max" (after clamping to what the model
+ * actually supports) bills one tier up (economy→standard, standard→premium;
+ * premium stays premium). `high` is the Claude-family server default and
+ * never bumps.
  */
-export function buildLlmCreditIdentifier(feature: string, modelId?: string): string {
+export function buildLlmCreditIdentifier(feature: string, modelId?: string, reasoningEffort?: string): string {
   if (!modelId) return feature
-  const tier = getLlmTier(modelId)
+  let tier = getLlmTier(modelId)
+  const eff = effectiveReasoningEffort(modelId, reasoningEffort)
+  if (eff !== undefined && EFFORT_TIER_BUMP.has(eff)) {
+    if (tier === "economy") tier = "standard"
+    else if (tier === "standard") tier = "premium"
+  }
   if (tier === "standard") return feature
   return `${feature}:${tier}`
 }
 
 /**
- * Resolve llmModel from raw body for creditGuard preHandler (before Zod parsing).
- * Returns the credit identifier for the given feature + optional model.
+ * Resolve llmModel (+ reasoningEffort) from raw body for creditGuard preHandler
+ * (before Zod parsing). Returns the credit identifier for the given feature.
  */
 export function resolveLlmCreditId(feature: string, body: unknown): string {
-  const llmModel = (body as Record<string, unknown>)?.llmModel as string | undefined
-  return buildLlmCreditIdentifier(feature, llmModel)
+  const b = body as Record<string, unknown> | undefined
+  return buildLlmCreditIdentifier(feature, b?.llmModel as string | undefined, b?.reasoningEffort as string | undefined)
 }
 
 /** Models capable of video-analysis: capability-derived, never hand-listed (route-enum-sync convention). */
 export const VIDEO_ANALYSIS_LLM_MODELS: string[] = LLM_MODELS
   .filter((m) => getLlmModalityCaps(m.id).video && getLlmModalityCaps(m.id).audio)
   .map((m) => m.id)
+
+/**
+ * Video-analysis quality TIERS — the ONLY analyzer identifiers exposed to users
+ * (API, UI, docs). Each maps to an internal analysis model; the underlying
+ * vendor/model name is never surfaced. Default is `pro`. The guard test
+ * (video-analysis-pricing.test.ts) asserts every tier target is a real
+ * VIDEO_ANALYSIS_LLM_MODELS member AND every such model is reachable by a tier,
+ * so adding a video model forces a tier decision instead of silently leaking.
+ */
+export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3-flash", pro: "gemini-3.1-pro" } as const
+export type VideoAnalysisTier = keyof typeof VIDEO_ANALYSIS_TIERS
+/** UI/listing order — recommended (pro) first. */
+export const VIDEO_ANALYSIS_TIER_ORDER = ["pro", "fast"] as const
+export const DEFAULT_VIDEO_ANALYSIS_TIER: VideoAnalysisTier = "pro"
+export const DEFAULT_VIDEO_ANALYSIS_MODEL: string = VIDEO_ANALYSIS_TIERS[DEFAULT_VIDEO_ANALYSIS_TIER]
+/** Neutral, vendor-free display labels for the UI. */
+export const VIDEO_ANALYSIS_TIER_LABELS: Record<VideoAnalysisTier, string> = { fast: "Fast", pro: "Pro" }
+
+export function isVideoAnalysisTier(v: string): v is VideoAnalysisTier {
+  return Object.prototype.hasOwnProperty.call(VIDEO_ANALYSIS_TIERS, v)
+}
+
+/**
+ * Resolve a user-supplied tier (`"fast"`/`"pro"`) OR a raw internal model id to
+ * the internal analysis model id. Empty/unknown → the default tier's model.
+ * Real model ids pass through (back-compat for existing stored `llmModel`
+ * values); anything else falls back to the default rather than erroring.
+ */
+export function resolveVideoAnalysisModel(input?: string | null): string {
+  if (input && isVideoAnalysisTier(input)) return VIDEO_ANALYSIS_TIERS[input]
+  if (input && VIDEO_ANALYSIS_LLM_MODELS.includes(input)) return input
+  return DEFAULT_VIDEO_ANALYSIS_MODEL
+}