@deepblend/dsh-blender-host 0.2.0 → 0.2.2

package/lib/index.js

@@ -143,6 +143,84 @@ export function contentTypeForArtifact(path) {
  * "the host bundle is missing" error at runtime. */
 export const RUNTIME_SERVICE = 'blenderRuntime'
 
+/**
+ * The configuration a diagnostic bundle may carry.
+ *
+ * AN ALLOWLIST, AND IT LIVES HERE BECAUSE THIS IS WHERE THE KEYS ARE DECLARED. `config-surface.test.mjs`
+ * holds every `config.<key>` a package reads to that package's own schema, and it is right to: a value read
+ * where it cannot arrive is a knob that lies. The UI half projecting the Host's configuration would be
+ * exactly that — the UI's own schema declares none of these keys. So the Host names them, and the UI
+ * asks for the projection.
+ *
+ * The direction of the default matters: a key added to `StudioConfig` later is ABSENT from a bundle
+ * until somebody adds it here. A spread would publish it, and the bundle is the one artifact that
+ * leaves the machine.
+ *
+ * @param {Record<string, unknown>} config - the resolved `StudioConfig`
+ * @returns {Record<string, unknown>}
+ */
+export function diagnosticConfiguration(config) {
+  const source = config ?? {}
+  return {
+    projectsRoot: source.projectsRoot ?? null,
+    workspaceRoot: source.workspaceRoot ?? null,
+    maxPreviewSamples: source.maxPreviewSamples ?? null,
+    assetMaxBytes: source.assetMaxBytes ?? null,
+    maxMeshPolygons: source.maxMeshPolygons ?? null,
+    maxVisualIterations: source.maxVisualIterations ?? null,
+    minVisualConfidenceForAutoFix: source.minVisualConfidenceForAutoFix ?? null,
+    stopOnRepeatedIssueCount: source.stopOnRepeatedIssueCount ?? null,
+    visualReviewProvider: source.visualReviewProvider ?? null,
+    visualReviewModel: source.visualReviewModel ?? null,
+    visualReviewMaxTokens: source.visualReviewMaxTokens ?? null,
+    visualReviewViews: source.visualReviewViews ?? [],
+    finalRenderProfile: source.finalRenderProfile ?? null,
+    maxFinalSamples: source.maxFinalSamples ?? null,
+    ffmpegPath: source.ffmpegPath ?? null,
+    ffprobePath: source.ffprobePath ?? null,
+    encodeCrf: source.encodeCrf ?? null,
+    encodePreset: source.encodePreset ?? null,
+    requireApprovalAboveFrames: source.requireApprovalAboveFrames ?? null,
+    progressPollMs: source.progressPollMs ?? null,
+    reconcileOnStart: source.reconcileOnStart ?? null,
+    orphanGraceMs: source.orphanGraceMs ?? null,
+  }
+}
+
+/**
+ * The product's version, from this package's own manifest.
+ *
+ * NOT A CONSTANT, and not a second copy of the number: `deepblend/version.json` is the single source,
+ * `tools/release-version.mjs --check` holds all eight manifests to it, so reading any one of them
+ * answers for the product — and `contract/diagnostics.test.mjs` compares what this returns against
+ * the source, which is what makes it a reading rather than a third copy.
+ *
+ * It answers `null` rather than throwing: the diagnostic bundle is what a user produces when
+ * something is already wrong, and a version field that crashed the export would be the least useful
+ * failure in the product. Read once and remembered — a manifest does not change under a running
+ * process.
+ *
+ * AND IT IS HERE, not in the UI half, because that half is asserted to import no filesystem module
+ * at all (`composition/ui-plane.e2e.mjs`): it is the layer the browser talks to. The first version of
+ * the diagnostics bundle read this manifest in `ui/lib/index.js` and that suite went red, correctly.
+ *
+ * @returns {string|null}
+ */
+export function readProductVersion() {
+  if (cachedProductVersion === undefined) {
+    try {
+      const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      cachedProductVersion = typeof manifest.version === 'string' ? manifest.version : null
+    } catch {
+      cachedProductVersion = null
+    }
+  }
+  return cachedProductVersion
+}
+
+/** @type {string|null|undefined} */
+let cachedProductVersion
+
 /**
  * Host-level configuration. Mirrors SPEC §17.
  *
@@ -223,17 +301,20 @@ export const StudioConfig = z.object({
   /** Provider route used by the built-in vision reviewer. */
   visualReviewProvider: z.string().default('deepseek-official'),
   /** Model used by the built-in vision reviewer. */
-  visualReviewModel: z.string().default('deepseek-flash'),
+  visualReviewModel: z.string().default('deepseek-v4.1-flash'),
   /**
    * Token budget for one reviewer call.
    *
    * MEASURED, and the reason this is a config field rather than a constant: with the
-   * full reviewer prompt and a 2x2 sheet, `deepseek-flash` spent ~11 000 REASONING
-   * tokens before emitting any text. At 2048 — a budget that looks generous for a
-   * 600-character JSON answer — the stream ended with `max-tokens` and NO text, which
-   * downstream is indistinguishable from "the model reviewed the sheet and found
-   * nothing wrong". That silent approval is the failure mode this number exists to
-   * prevent, and the size of it is a property of the model, not of this code.
+   * full reviewer prompt and a 2x2 sheet, the model spends most of its output budget on
+   * REASONING before emitting any text. MEASURED twice, with the model the deployment
+   * actually serves (`deepseek-v4.1-flash`, via `visual-review-live-probe.mjs`): one
+   * review of a 640x360 sheet answered in 1049 tokens — 345 in, 704 out, of which 686
+   * were reasoning — and at the probe's own 400-token budget the same call ended with
+   * `max-tokens` and NO text at all. That empty answer is indistinguishable downstream
+   * from "the model reviewed the sheet and found nothing wrong", and that silent
+   * approval is the failure mode this number exists to prevent. The size of it is a
+   * property of the model, so this budget is sized for the reasoning, not the answer.
    */
   visualReviewMaxTokens: z.number().default(24_000),
   /** Views in the standard plan, in reading order (SPEC §12.3). */
@@ -400,6 +481,38 @@ export default class BlenderStudio extends Service {
     return HOST_API_VERSION
   }
 
+  /**
+   * The product's version, read from this package's own manifest.
+   *
+   * HERE RATHER THAN IN THE UI HALF, and that is a rule rather than a preference: the UI host is
+   * asserted to import no filesystem module at all (`composition/ui-plane.e2e.mjs`), because that
+   * layer is the one the browser talks to. The first version of the diagnostics bundle read this
+   * manifest in `ui/lib/index.js` and that suite went red, correctly.
+   *
+   * NOT A CONSTANT, and not a second copy of the number: `deepblend/version.json` is the single
+   * source, `tools/release-version.mjs --check` holds all eight manifests to it, so reading any one
+   * of them answers for the product — and `contract/diagnostics.test.mjs` compares what this returns
+   * against the source, which is what makes it a reading rather than a third copy.
+   *
+   * It answers `null` rather than throwing: the diagnostic bundle is what a user produces when
+   * something is already wrong, and a version field that crashed the export would be the least
+   * useful failure in the product.
+   *
+   * @returns {string|null}
+   */
+  productVersion() {
+    return readProductVersion()
+  }
+
+  /**
+   * The Host's own configuration, as a diagnostic bundle may carry it.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  describeConfiguration() {
+    return diagnosticConfiguration(this.config)
+  }
+
   // ---------------------------------------------------------------------------
   // Capabilities (M0)
   // ---------------------------------------------------------------------------
@@ -1720,6 +1833,75 @@ export default class BlenderStudio extends Service {
    *
    * @returns {(request: object) => Promise<{ findings: object[], operations: object[], note: string|null, model: string|null, provider: string|null, raw: string|null }>}
    */
+  /**
+   * Whether the configured vision route can actually review an image.
+   *
+   * Answers `{ problem: null }` when the route is usable, or a sentence naming what is wrong and
+   * what the catalog offers instead. Never throws: an absent catalog is "cannot check", not "bad
+   * route", and the model call downstream is still the authority on whether the call works.
+   *
+   * @param {string} provider
+   * @param {string} model
+   * @returns {Promise<{ problem: string|null, providers: string[], models: string[], imageCapable: string[] }>}
+   */
+  async _visionRoute(provider, model) {
+    const empty = { problem: null, providers: [], models: [], imageCapable: [] }
+    const llm = this.ctx.get('llm')
+    if (llm === undefined || typeof llm.listModels !== 'function') return empty
+
+    let providers = []
+    try {
+      providers = (llm.listProviders?.() ?? []).map(entry => entry.id).filter(id => typeof id === 'string')
+    } catch {
+      return empty
+    }
+    if (providers.length > 0 && !providers.includes(provider)) {
+      return {
+        problem: `The vision reviewer is configured for provider "${provider}", which this deployment does not offer. ` +
+          `Set \`visualReviewProvider\` to one of: ${providers.join(', ')}.`,
+        providers,
+        models: [],
+        imageCapable: [],
+      }
+    }
+
+    let catalog = []
+    try {
+      catalog = await llm.listModels(provider)
+    } catch {
+      return { ...empty, providers }
+    }
+    const models = catalog.map(entry => entry.id).filter(id => typeof id === 'string')
+    const imageCapable = catalog
+      .filter(entry => (entry.inputModalities ?? []).includes('image'))
+      .map(entry => entry.id)
+
+    const entry = catalog.find(candidate => candidate.id === model)
+    if (entry === undefined) {
+      return {
+        problem: `The vision reviewer is configured for model "${model}", which provider "${provider}" does not serve. ` +
+          `Set \`visualReviewModel\` to one of: ${models.join(', ') || '(the catalog is empty)'}.`,
+        providers,
+        models,
+        imageCapable,
+      }
+    }
+    if (!(entry.inputModalities ?? []).includes('image')) {
+      // THE QUIET HALF OF THIS FAILURE. A text-only model answers happily and never sees the sheet,
+      // so the review comes back with zero findings — which downstream is indistinguishable from
+      // "looked at it, found nothing wrong".
+      return {
+        problem: `The vision reviewer is configured for model "${model}", which does not accept images ` +
+          `(inputModalities: ${JSON.stringify(entry.inputModalities ?? [])}). A review would silently omit the ` +
+          `contact sheet. Set \`visualReviewModel\` to one of: ${imageCapable.join(', ') || '(none of the catalog accepts images)'}.`,
+        providers,
+        models,
+        imageCapable,
+      }
+    }
+    return { problem: null, providers, models, imageCapable }
+  }
+
   createVisualReviewer() {
     const provider = this.config.visualReviewProvider
     const model = this.config.visualReviewModel
@@ -1734,6 +1916,27 @@ export default class BlenderStudio extends Service {
         )
       }
 
+      // THE ROUTE IS CHECKED BEFORE ANYTHING IS SPENT. MEASURED: the shipped default named a model
+      // the provider had stopped serving, so every review ended in an HTTP 404 from inside the
+      // stream — after the sheet had been uploaded — and the loop recorded "no second opinion" in a
+      // note nobody read. A day of reviews ran that way with every suite green.
+      //
+      // Best-effort by design: a harness that does not expose a catalog (`listProviders`/
+      // `listModels` are optional) still gets the model call and its own error handling. What this
+      // adds is a refusal that NAMES the fix, at the one moment the caller can still do something.
+      const catalogue = await this._visionRoute(provider, model)
+      if (catalogue.problem !== null) {
+        throw new BlenderError(BlenderErrorCode.VISUAL_REVIEW_MODEL_UNAVAILABLE, catalogue.problem, {
+          detail: {
+            provider,
+            model,
+            providers: catalogue.providers,
+            models: catalogue.models,
+            imageCapable: catalogue.imageCapable,
+          },
+        })
+      }
+
       const ref = await attachments.saveImage({
         data: request.sheetPng,
         mediaType: 'image/png',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-host",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "DeepBlend Host service: the blenderStudio business facade over the BlenderRuntime seam.",
   "main": "lib/index.js",
@@ -20,7 +20,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.2.0"
+    "@deepblend/dsh-blender-contracts": "0.2.2"
   },
   "license": "MIT",
   "repository": {