@nodaro/shared 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.17.0",
+  "version": "1.19.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

@@ -20,12 +20,36 @@ import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
 // the NON-monetary model registry (ids, capabilities, tiers, feature
 // defaults) that stays in the published package.
 
+/** The registry's expected membership, in order — the single list both the
+ *  count guard and the id-order guard below assert against, so a model
+ *  addition can never leave one of them stale. */
+const EXPECTED_MODEL_IDS = [
+  "gemini-3-flash",
+  "gemini-3.6-flash",
+  "claude-haiku-4.5",
+  "claude-sonnet-4.6",
+  "gpt-5.2",
+  "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",
+  "claude-opus-5",
+  "claude-fable-5",
+]
+
 // ---------------------------------------------------------------------------
 // LLM_MODELS data integrity
 // ---------------------------------------------------------------------------
 describe("LLM_MODELS data integrity", () => {
-  it("should have exactly 15 models", () => {
-    expect(LLM_MODELS).toHaveLength(15)
+  it("model count matches the enumerated id list", () => {
+    // Bound to the id list asserted below rather than a hand-typed number, so
+    // the count and the title can never disagree after a model addition.
+    expect(LLM_MODELS).toHaveLength(EXPECTED_MODEL_IDS.length)
   })
 
   it("each model has all required fields", () => {
@@ -60,14 +84,14 @@ describe("LLM_MODELS data integrity", () => {
     expect(new Set(ids).size).toBe(ids.length)
   })
 
-  it("has 4 economy, 4 standard, 7 premium models", () => {
+  it("has 4 economy, 4 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.premium).toBe(7)
+    expect(tierCounts.premium).toBe(8)
   })
 
   it("all three kieFormats are represented", () => {
@@ -106,24 +130,7 @@ describe("LLM_MODEL_IDS", () => {
   })
 
   it("contains all expected model ids", () => {
-    const expected = [
-      "gemini-3-flash",
-      "gemini-3.6-flash",
-      "claude-haiku-4.5",
-      "claude-sonnet-4.6",
-      "gpt-5.2",
-      "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",
-      "claude-fable-5",
-    ]
-    expect(LLM_MODEL_IDS).toEqual(expected)
+    expect(LLM_MODEL_IDS).toEqual(EXPECTED_MODEL_IDS)
   })
 })
 
@@ -399,11 +406,11 @@ describe("LLM_FEATURE_DEFAULTS", () => {
     expect(getLlmTier(LLM_FEATURE_DEFAULTS["ai-writer"])).toBe("standard")
   })
 
-  it('"describe-to-picker" defaults to "claude-opus-4.7" (premium vision)', () => {
-    expect(LLM_FEATURE_DEFAULTS["describe-to-picker"]).toBe("claude-opus-4.7")
+  it('"describe-to-picker" defaults to "claude-opus-5" (premium vision)', () => {
+    expect(LLM_FEATURE_DEFAULTS["describe-to-picker"]).toBe("claude-opus-5")
     expect(getLlmTier(LLM_FEATURE_DEFAULTS["describe-to-picker"])).toBe("premium")
     // The default MUST be an accepted analyzer model (vision + structured output).
-    expect(STRUCTURED_VISION_MODELS.map((m) => m.id)).toContain("claude-opus-4.7")
+    expect(STRUCTURED_VISION_MODELS.map((m) => m.id)).toContain("claude-opus-5")
   })
 
   it('"generate-script" defaults to "gemini-3.6-flash" (economy)', () => {
@@ -465,6 +472,7 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "gemini-3.1-pro",
         "claude-sonnet-5",
         "claude-opus-4.8",
+        "claude-opus-5",
         "claude-fable-5",
         // responses-format GPTs — KIE text.format json_schema live-verified
         // 2026-07-14 (text AND vision inputs).
@@ -520,6 +528,25 @@ describe("reasoning effort registry", () => {
     expect(getLlmTier("gpt-5.5")).toBe("premium")
     expect(getLlmTier("gemini-3.6-flash")).toBe("economy")
     expect(getLlmTier("claude-fable-5")).toBe("premium")
+    expect(getLlmTier("claude-opus-5")).toBe("premium")
+  })
+
+  it("claude-opus-5 carries the full ladder, its own direct fallback, and thinkingDefaultOn", () => {
+    const m = getLlmModel("claude-opus-5")
+    expect(m?.reasoningEfforts).toEqual(["low", "medium", "high", "xhigh", "max"])
+    expect(m?.directFallbackModel).toBe("claude-opus-5")
+    // Load-bearing: consumers floor max_tokens off this flag, because Opus 5
+    // reasons even with NO thinking param sent. Dropping it silently
+    // reintroduces truncated answers at Effort=Auto on a premium model.
+    expect(m?.thinkingDefaultOn).toBe(true)
+  })
+
+  it("thinkingDefaultOn is set only where the vendor default actually reasons", () => {
+    // Opus 4.8 / 4.7 and Sonnet 5 do NOT reason when `thinking` is omitted —
+    // flagging them would inflate every call's cap for no reason.
+    for (const id of ["claude-opus-4.8", "claude-opus-4.7", "claude-sonnet-5", "claude-sonnet-4.6"]) {
+      expect(getLlmModel(id)?.thinkingDefaultOn, id).toBeUndefined()
+    }
   })
 
   it("gemini-3.6-flash exposes the KIE low/high thinking levels; claude-fable-5 the full Claude ladder", () => {

package/src/__tests__/smart-cut-windows.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest"
+import {
+  clampSmartCutWindow,
+  SMART_CUT_WINDOW_MIN,
+  SMART_CUT_WINDOW_MAX,
+  SMART_CUT_WINDOW_DEFAULT,
+} from "../smart-cut-windows.js"
+
+describe("smart-cut search windows", () => {
+  it("keeps in-range integers untouched", () => {
+    for (const n of [1, 4, 8, 12, 24]) expect(clampSmartCutWindow(n)).toBe(n)
+  })
+
+  it("clamps to the product bounds instead of erroring", () => {
+    expect(clampSmartCutWindow(999)).toBe(SMART_CUT_WINDOW_MAX)
+    expect(clampSmartCutWindow(25)).toBe(SMART_CUT_WINDOW_MAX)
+    expect(clampSmartCutWindow(0)).toBe(SMART_CUT_WINDOW_MIN)
+    expect(clampSmartCutWindow(-5)).toBe(SMART_CUT_WINDOW_MIN)
+  })
+
+  it("rounds fractional input (a number <input> can emit one)", () => {
+    expect(clampSmartCutWindow(8.4)).toBe(8)
+    expect(clampSmartCutWindow(8.6)).toBe(9)
+  })
+
+  it('returns undefined — "use the engine default" — for anything non-numeric', () => {
+    // Load-bearing: undefined means the field is OMITTED from the request, so
+    // the engine applies its own 8/8. Coercing junk to a NUMBER instead would
+    // silently run a search width the user never chose.
+    for (const v of [undefined, null, NaN, Infinity, "8", "", {}, []]) {
+      expect(clampSmartCutWindow(v), String(v)).toBeUndefined()
+    }
+  })
+
+  it("bounds are coherent and the default sits inside them", () => {
+    expect(SMART_CUT_WINDOW_MIN).toBeLessThan(SMART_CUT_WINDOW_MAX)
+    expect(SMART_CUT_WINDOW_DEFAULT).toBeGreaterThanOrEqual(SMART_CUT_WINDOW_MIN)
+    expect(SMART_CUT_WINDOW_DEFAULT).toBeLessThanOrEqual(SMART_CUT_WINDOW_MAX)
+    // The engine route accepts up to 48; the product cap must stay within it
+    // or a clamped value would still 400 at the boundary we were protecting.
+    expect(SMART_CUT_WINDOW_MAX).toBeLessThanOrEqual(48)
+  })
+})

package/src/index.ts

@@ -889,5 +889,8 @@ export * from "./video-analysis.js"
 // --- Video-analysis pricing (duration buckets + structural credit formula) ---
 export * from "./video-analysis-pricing.js"
 
+// --- Smart-cut best-pair search windows (shared bound + clamp) ---
+export * from "./smart-cut-windows.js"
+
 export * from "./entity-asset-types.js"
 export * from "./hint-graph-types.js"

package/src/llm-models.ts

@@ -57,6 +57,20 @@ export interface LlmModelDef {
   supportsTemperature?: false
   /** Claude-only: KIE is the preferred routing, direct Anthropic the fallback. */
   preferKie?: true
+  /**
+   * true = the model reasons even when NO thinking parameter is sent, so its
+   * reasoning tokens share the `max_tokens` budget on EVERY call — not just
+   * effort-bearing ones. Claude Opus 5 flipped this default (on Opus 4.8/4.7
+   * and Sonnet 5, omitting `thinking` means no thinking at all).
+   *
+   * Consumers MUST give such a model output headroom regardless of the
+   * requested effort, or reasoning silently eats a small legacy cap and the
+   * answer truncates with `stop_reason: max_tokens` — a paid-for empty reply,
+   * not an error. `deriveParams` (llm-client.ts) and the film-pipeline's
+   * `callLLM` both floor on this flag; keep it in sync with the vendor's
+   * documented default rather than inferring it from the model name.
+   */
+  thinkingDefaultOn?: true
 }
 
 export const LLM_MODELS: readonly LlmModelDef[] = [
@@ -143,7 +157,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "claude-opus-4.7",
     displayName: "Claude Opus 4.7",
-    desc: "Highest quality, complex tasks",
+    // Superlatives belong to the CURRENT top model only — `desc` renders in every
+    // model picker, so leaving "highest quality" on an older Opus steers
+    // quality-critical work backwards (all three Opus entries bill premium, so
+    // the mis-steer is invisible on the invoice).
+    desc: "Older Opus, complex tasks",
     tier: "premium",
     kieFormat: "messages",
     kieSlugOrModel: "claude-opus-4-7",
@@ -245,7 +263,7 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "claude-opus-4.8",
     displayName: "Claude Opus 4.8",
-    desc: "Most capable Claude, long-horizon work",
+    desc: "Previous-gen Opus, long-horizon work",
     tier: "premium",
     kieFormat: "messages",
     kieSlugOrModel: "claude-opus-4-8",
@@ -258,6 +276,28 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     supportsTemperature: false,
     preferKie: true,
   },
+  {
+    id: "claude-opus-5",
+    displayName: "Claude Opus 5",
+    desc: "Latest Opus, deepest agentic reasoning",
+    tier: "premium",
+    kieFormat: "messages",
+    // KIE serves Opus 5 on the Claude-native messages dialect under the plain
+    // id (docs.kie.ai/market/claude/claude-opus-5.md) — same path shape as
+    // claude-opus-4-8 / claude-fable-5.
+    kieSlugOrModel: "claude-opus-5",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    directFallbackModel: "claude-opus-5",
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+    preferKie: true,
+    // Opus 5 reasons with NO thinking param sent (vendor default flipped from
+    // Opus 4.8/4.7) — so every call needs output headroom, not just xhigh/max.
+    thinkingDefaultOn: true,
+  },
   {
     id: "claude-fable-5",
     displayName: "Claude Fable 5",
@@ -323,7 +363,7 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "lottie-overlay": "claude-sonnet-4.6",
   "3d-title": "claude-sonnet-4.6",
   "image-to-text": "claude-sonnet-4.6",
-  "describe-to-picker": "claude-opus-4.7",
+  "describe-to-picker": "claude-opus-5",
   "qa-check": "gemini-3.6-flash",
   "generate-script": "gemini-3.6-flash",
   "translate": "gemini-3.6-flash",
@@ -354,6 +394,7 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "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 },
+  "claude-opus-5":     { image: true,  video: false, audio: false },
   "claude-fable-5":    { image: true,  video: false, audio: false },
 }
 

package/src/pipeline-types.ts

@@ -84,6 +84,7 @@ export const PIPELINE_PINNABLE_SCRIPT_LLMS = [
   "claude-haiku-4-5",
   "claude-sonnet-4-6",
   "claude-opus-4-7",
+  "claude-opus-5",
 ] as const
 export type PipelinePinnableScriptLlm = (typeof PIPELINE_PINNABLE_SCRIPT_LLMS)[number]
 

package/src/smart-cut-windows.ts

@@ -0,0 +1,50 @@
+/**
+ * Smart-cut best-pair SEARCH WINDOWS — the shared bound + clamp for
+ * generate-video-pro's `smartCutFramesPrev` / `smartCutFramesNext`.
+ *
+ * What they do: the best-pair matcher (the mode the node calls "legacy-8x8")
+ * PSNR-compares the last N frames of a segment against the first M of the
+ * next, ends the previous clip ON the best match and starts the next right
+ * AFTER its twin — so the duplicated frame plays once and motion stays
+ * continuous. N and M are those windows. Absent → the engine's own 8/8
+ * default, which is byte-identical to the behavior before they were
+ * exposed.
+ *
+ * Why wider helps: a continuation can re-enact a longer stretch of the
+ * previous tail than 8 frames covers, and a match outside the window is
+ * simply never found — the boundary silently falls back to the fixed
+ * freeze-trims. recast pins 24/24 for exactly this reason.
+ *
+ * Why a shared clamp: the canvas node (single-node Run) and the orchestrator
+ * (workflow Run) are two independent send paths into the same engine route,
+ * whose Zod schema rejects out-of-range values. Deriving both from this one
+ * function means a stale or hand-edited node value degrades to a legal
+ * request instead of 400-ing an entire multi-segment run at finalize time —
+ * and the two paths cannot drift apart.
+ */
+
+/** Widest window the UI offers. The engine route itself accepts up to 48;
+ *  24 is the product cap — it already covers a full second of re-enactment
+ *  at 24fps, and every frame added past the real overlap only costs match
+ *  time and invites a spurious pairing. */
+export const SMART_CUT_WINDOW_MAX = 24
+/** Narrowest meaningful window — one frame each side. */
+export const SMART_CUT_WINDOW_MIN = 1
+/** The engine's default when the field is absent. Documented here so the UI
+ *  can show it as the placeholder without hardcoding a second copy. */
+export const SMART_CUT_WINDOW_DEFAULT = 8
+
+/**
+ * Narrow an arbitrary node value to a legal window, or `undefined` to mean
+ * "let the engine use its default". Non-numbers, NaN, and non-integers all
+ * collapse to `undefined` rather than to a guessed number: a malformed value
+ * should fall back to the proven default, not silently pick a different
+ * search width than the user asked for.
+ */
+export function clampSmartCutWindow(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined
+  const n = Math.round(value)
+  if (n < SMART_CUT_WINDOW_MIN) return SMART_CUT_WINDOW_MIN
+  if (n > SMART_CUT_WINDOW_MAX) return SMART_CUT_WINDOW_MAX
+  return n
+}