@deepblend/dsh-blender-tool 0.6.4 → 0.7.0

package/lib/attachment-image.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto'
+import { persistImage } from './shared.js'
+
+const MAX_IMAGE_BYTES = 32 * 1024 * 1024
+
+/** Persist one already verified PNG; validate any normalized durable reference. */
+export async function persistVerifiedPng(attachments, bytes, artifact, name, signal) {
+  const store = typeof attachments?.saveImage === 'function' ? {
+    async saveImage(input) {
+      const ref = await attachments.saveImage(input)
+      const exact = ref?.mediaType === 'image/png' && ref.bytes === artifact.bytes &&
+        ref.width === artifact.width && ref.height === artifact.height
+      const dimensionsMatch = ref?.width === artifact.width && ref?.height === artifact.height ||
+        ref?.originalDimensions?.width === artifact.width && ref?.originalDimensions?.height === artifact.height &&
+        ref.width <= artifact.width && ref.height <= artifact.height
+      if (typeof ref?.attachmentId !== 'string' || !ref.attachmentId.trim() ||
+          !['image/png', 'image/jpeg', 'image/webp'].includes(ref.mediaType) ||
+          !Number.isSafeInteger(ref.bytes) || ref.bytes <= 0 || ref.bytes > MAX_IMAGE_BYTES ||
+          !Number.isSafeInteger(ref.width) || ref.width <= 0 || !Number.isSafeInteger(ref.height) || ref.height <= 0 ||
+          !dimensionsMatch) {
+        throw new Error('attachment reference does not match the verified PNG')
+      }
+      // DSH may normalize the verified PNG into a smaller encoded image. Its
+      // read API verifies that durable image's digest, format and dimensions.
+      if (!exact) {
+        if (typeof attachments.readImage !== 'function') throw new Error('normalized attachment cannot be read back')
+        const stored = await attachments.readImage(ref, signal)
+        if (!(stored?.data instanceof Uint8Array) || stored.data.byteLength !== ref.bytes ||
+            ['attachmentId', 'mediaType', 'bytes', 'width', 'height'].some(key => stored.ref?.[key] !== ref[key]) ||
+            ref.attachmentId.startsWith('sha256:') &&
+            createHash('sha256').update(stored.data).digest('hex') !== ref.attachmentId.slice(7)) {
+          throw new Error('normalized attachment bytes do not match its durable reference')
+        }
+      }
+      return ref
+    },
+  } : attachments
+  const attached = await persistImage(store, bytes, name)
+  let { image, note } = attached
+  if (image && (image.mediaType !== 'image/png' || image.bytes !== artifact.bytes ||
+      image.width !== artifact.width || image.height !== artifact.height)) {
+    note = 'The attached image is the attachment service normalization of the verified source PNG. ' +
+      `Attached format: ${image.mediaType}; dimensions: ${image.width}x${image.height}. ` +
+      'The original PNG and its source digest remain at the project path in this result.'
+  }
+  return { image, note }
+}

package/lib/committed-preview.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto'
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+import { persistVerifiedPng } from './attachment-image.js'
+import { imageForCallingModel } from './image-delivery.js'
+
+const MAX_IMAGE_BYTES = 32 * 1024 * 1024
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+
+/** Attach the receipt's existing preview, with no compile, render or output-time IO. */
+export async function attachCommittedPreview(ctx, exec, resolved, value, { projectId, summary }) {
+  const artifact = summary?.previews?.[0]
+  if (!artifact) return value
+  const cancelled = () => {
+    if (exec?.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED,
+      'Preview attachment cancelled; the saved revision may already exist.')
+  }
+  try {
+    cancelled()
+    const revision = summary.revision
+    if (typeof projectId !== 'string' || !projectId || !/^r[0-9]{4,}$/.test(revision) ||
+        !/^[a-f0-9]{64}$/.test(summary.digest) || artifact.kind !== 'preview' ||
+        artifact.sourceRevision !== revision || artifact.sourceDigest !== summary.digest ||
+        artifact.mime !== 'image/png' || typeof artifact.path !== 'string' ||
+        !artifact.path.startsWith(`revisions/${revision}/previews/`) ||
+        artifact.path.split('/').some(part => !part || part === '.' || part === '..') ||
+        !/^[a-f0-9]{64}$/.test(artifact.sha256) ||
+        !Number.isSafeInteger(artifact.bytes) || artifact.bytes <= 0 || artifact.bytes > MAX_IMAGE_BYTES ||
+        !Number.isSafeInteger(artifact.width) || artifact.width <= 0 || artifact.width > 2048 ||
+        !Number.isSafeInteger(artifact.height) || artifact.height <= 0 || artifact.height > 2048 ||
+        typeof artifact.cameraId !== 'string' || !artifact.cameraId || !Number.isSafeInteger(artifact.frame) ||
+        typeof resolved.studio.readArtifact !== 'function') throw new Error('Invalid saved preview receipt')
+    const read = await resolved.studio.readArtifact({ projectId, path: artifact.path })
+    cancelled()
+    if (read?.path !== artifact.path || read.contentType !== 'image/png' || !Buffer.isBuffer(read.bytes) ||
+        read.size !== artifact.bytes || read.bytes.length !== artifact.bytes || read.bytes.length < 24 ||
+        !read.bytes.subarray(0, 8).equals(PNG_SIGNATURE) ||
+        read.bytes.readUInt32BE(16) !== artifact.width || read.bytes.readUInt32BE(20) !== artifact.height ||
+        createHash('sha256').update(read.bytes).digest('hex') !== artifact.sha256) {
+      throw new Error('Saved PNG differs from its receipt')
+    }
+    const attached = await persistVerifiedPng(resolved.attachments, read.bytes, artifact,
+      `preview-${revision}-${artifact.cameraId}-${artifact.frame}.png`, exec?.signal)
+    cancelled()
+    return await imageForCallingModel(ctx, exec, {
+      ...value, image: attached.image,
+      imageSource: { ...artifact, projectId, revision, digest: summary.digest },
+      text: value.text + '\n\nThe image uses the preview already saved with this revision; no extra render was started.' +
+        (attached.note ? '\n' + attached.note : ''),
+    })
+  } catch (cause) {
+    cancelled()
+    if (cause?.code === BlenderErrorCode.ABORTED) throw cause
+    return { ...value, image: null,
+      text: value.text + '\n\nThe revision remains saved, but its preview could not be verified and attached here. ' +
+        'The model has not seen this image. Use the receipt to inspect the saved artifact; do not recreate the project or repeat the render to repair an attachment.' }
+  }
+}

package/lib/image-delivery.js

@@ -0,0 +1,23 @@
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+
+/** Keep rendered artifacts available without sending images to a known text-only route. */
+export async function imageForCallingModel(ctx, exec, value) {
+  if (!value.image) return value
+  const route = exec?.agent?.session?.requestHeader?.()?.config
+  const llm = ctx.get('llm')
+  if (!route?.provider || !route.model || typeof llm?.listModels !== 'function') return value
+  let catalog
+  try { catalog = await llm.listModels(route.provider) } catch {
+    if (exec?.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Image delivery cancelled.')
+    return value
+  }
+  if (exec?.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Image delivery cancelled.')
+  const model = catalog?.find(entry => entry.id === route.model)
+  if (!Array.isArray(model?.inputModalities) || model.inputModalities.includes('image')) return value
+  return { ...value, image: null,
+    imageDelivery: { provider: route.provider, model: route.model, deliveredToModel: false,
+      reason: 'The active request model declares no image input.' },
+    text: value.text + '\n\nThe rendered image remains saved at the path in this result. ' +
+      `It was not attached to the ${route.provider}/${route.model} conversation because this model does not accept images. ` +
+      'The model has not seen these pixels; report measurements separately from appearance and artistic approval.' }
+}

package/lib/inspection.js

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto'
 import { BlenderError, BlenderErrorCode, warning } from '@deepblend/dsh-blender-contracts'
-import { canonicalCall, definedFields, persistImage, renderSuccess } from './shared.js'
+import { canonicalCall, definedFields, renderSuccess } from './shared.js'
+
+import { persistVerifiedPng } from './attachment-image.js'
 
 const REQUIRED_HOST_API = 6
 const MAX_IMAGE_BYTES = 32 * 1024 * 1024
@@ -66,17 +68,7 @@ export async function renderInspection(resolved, request) {
   let image = null
   let note = null
   try {
-    const store = typeof attachments?.saveImage === 'function' ? {
-      async saveImage(input) {
-        const ref = await attachments.saveImage(input)
-        if (typeof ref?.attachmentId !== 'string' || !ref.attachmentId.trim() || ref.mediaType !== 'image/png' ||
-            ref.bytes !== artifact.bytes || ref.width !== artifact.width || ref.height !== artifact.height) {
-          throw new Error('attachment reference does not match the verified PNG')
-        }
-        return ref
-      },
-    } : attachments
-    const attached = await persistImage(store, read.bytes, `${mode}-${revision}-${cameraId}-${frame}.png`)
+    const attached = await persistVerifiedPng(attachments, read.bytes, artifact, `${mode}-${revision}-${cameraId}-${frame}.png`, signal)
     aborted(signal)
     image = attached.image
     note = attached.note

package/lib/shared.js

@@ -99,6 +99,9 @@ export async function persistImage(attachments, bytes, name) {
       width: Number(ref.width),
       height: Number(ref.height),
       name: typeof ref.name === 'string' ? ref.name : name,
+      ...(ref.originalDimensions ? { originalDimensions: {
+        width: Number(ref.originalDimensions.width), height: Number(ref.originalDimensions.height),
+      } } : {}),
     },
     note: null,
   }

package/lib/tools.js

@@ -28,6 +28,8 @@
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { renderInspection } from './inspection.js'
+import { imageForCallingModel } from './image-delivery.js'
+import { attachCommittedPreview } from './committed-preview.js'
 
 import {
   SCENE_OPERATION_NAMES,
@@ -116,7 +118,7 @@ function recipeParameters(ctx) {
       'Saving needs that exact baseRevision and numeric parameters. It updates the same project, preserves independent ' +
       'materials, bevels, photography and history, and refuses manually conflicting controlled geometry. ' +
       'A scene without declared assembly controls returns available:false; do not invent parameters or replace the project. ' +
-      'Saving compiles a checkpoint and preview by default; explicit false flags can request a data-only revision. ' +
+      'Saving compiles a checkpoint and preview by default and can attach that existing preview for inspection; explicit false flags can request a data-only revision. ' +
       'Use a unique idempotencyKey per user save and reuse it only when retrying the same intent.',
     parameters: {
       action: { type: 'string', enum: ['read', 'save'], description: 'read (default) is read-only; save creates one atomic revision.' },
@@ -128,7 +130,7 @@ function recipeParameters(ctx) {
       saveCheckpoint: { type: 'boolean', description: 'Save a Blender checkpoint (default true).' },
       renderPreview: { type: 'boolean', description: 'Render an actual new preview (default true).' },
     },
-    output: TOOL_OUTPUT,
+    output: TOOL_OUTPUT_WITH_IMAGE,
     async execute(args, exec) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
@@ -143,7 +145,9 @@ function recipeParameters(ctx) {
             saveCheckpoint: args.saveCheckpoint !== false, renderPreview: args.renderPreview !== false,
             signal: exec?.signal })
         const { data, canonicalWarnings } = await canonicalCall(result, warning)
-        return { ok: true, text: renderSuccess(action === 'read' ? 'Saved assembly controls.' : 'Assembly dimensions saved.', data, { warnings: canonicalWarnings }), data }
+        const value = { ok: true, text: renderSuccess(action === 'read' ? 'Saved assembly controls.' : 'Assembly dimensions saved.', data, { warnings: canonicalWarnings }), data }
+        return action === 'save' && args.renderPreview !== false
+          ? await attachCommittedPreview(ctx, exec, resolved, value, { projectId: args.projectId, summary: data }) : value
       } catch (cause) { return { ok: false, ...renderFailure(cause, 'RECIPE_PARAMETER_FAILED') } }
     },
     presentCall: args => ({ card: 'generic', title: args?.action === 'save' ? 'Save assembly dimensions' : 'Read assembly dimensions',
@@ -194,6 +198,9 @@ function projectCreate(ctx) {
       'Give it the operator\'s brief as `goal`: it is stored with the project and never parsed, so write it ' +
       'in full. For an existing product design, call blender_recipe_list and pass its id/version/digest ' +
       'as recipe, with only its declared parameter overrides. recipe and sceneSpec are mutually exclusive. ' +
+      'When the brief asks for an editable Blender file and a preview, set saveCheckpoint:true and ' +
+      'renderPreview:true together to save both in this creation. The saved preview can be attached in this result; inspect it before rendering that view again. Inspect those returned receipts before ' +
+      'reading a full scene or starting another render. ' +
       'Omit both to start from a minimal renderable scaffold and build up with ' +
       'blender_scene_patch; pass one only when you already know the whole scene. ' +
       'Set saveCheckpoint:false to skip the Blender compile and store the SceneSpec alone. The revision then ' +
@@ -246,7 +253,7 @@ function projectCreate(ctx) {
         description: 'Optional stable key for this creation intent (1–128 characters, no control characters). Reuse it with the same inputs when retrying an uncertain result. A completed request opens the same project without another compile or render; a new project needs a new key. Recovery returns its current saved revision.',
       },
     },
-    output: TOOL_OUTPUT,
+    output: TOOL_OUTPUT_WITH_IMAGE,
     async execute(args, exec) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
@@ -282,7 +289,7 @@ function projectCreate(ctx) {
           notes.push('Compiler notes (these describe decisions made on your behalf):')
           for (const entry of data.warnings) notes.push(`  - ${entry.message}`)
         }
-        return {
+        const value = {
           ok: true,
           text: renderSuccess(`Created project "${data.projectId}" at revision ${data.revision.revision}.`, data, {
             notes,
@@ -290,6 +297,8 @@ function projectCreate(ctx) {
           }),
           data,
         }
+        return args.renderPreview === true
+          ? await attachCommittedPreview(ctx, exec, resolved, value, { projectId: data.projectId, summary: data.revision }) : value
       } catch (cause) {
         const failure = renderFailure(cause, 'PROJECT_CREATE_FAILED')
         return { ok: false, ...failure }
@@ -563,7 +572,7 @@ function scenePatch(ctx) {
         description: 'Also render the preview profile as part of this commit, so the revision arrives with an image. Default false.',
       },
     },
-    output: TOOL_OUTPUT,
+    output: TOOL_OUTPUT_WITH_IMAGE,
     async execute(args, exec) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
@@ -619,7 +628,7 @@ function scenePatch(ctx) {
         }
         const scene = data.scene ?? {}
         if (scene.counts) notes.push(`Scene now: ${JSON.stringify(scene.counts)}`)
-        return {
+        const value = {
           ok: true,
           text: renderSuccess(
             `${data.idempotentReplay === true ? 'Reused' : 'Committed'} revision ${data.revision}.`,
@@ -628,6 +637,8 @@ function scenePatch(ctx) {
           ),
           data,
         }
+        return args.renderPreview === true
+          ? await attachCommittedPreview(ctx, exec, resolved, value, { projectId: args.projectId, summary: data }) : value
       } catch (cause) {
         const failure = renderFailure(cause, 'SCENE_PATCH_FAILED')
         return { ok: false, ...failure }
@@ -688,11 +699,11 @@ function previewRender(ctx) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
       try {
-        if (args.mode !== undefined) return await renderInspection(resolved, {
+        if (args.mode !== undefined) return await imageForCallingModel(ctx, exec, await renderInspection(resolved, {
           projectId: args.projectId, revision: args.revision, mode: args.mode,
           cameraId: args.cameraId, frame: args.frame, width: args.width, height: args.height,
           samples: args.samples, signal: exec.signal,
-        })
+        }))
         const { data, canonicalWarnings } = await canonicalCall(resolved.studio.renderPreview({
           ...definedFields({
             projectId: args.projectId,

package/lib/visual-tools.js

@@ -40,6 +40,7 @@
  */
 
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { imageForCallingModel } from './image-delivery.js'
 
 import { BlenderWarningCode, warning } from '@deepblend/dsh-blender-contracts'
 
@@ -229,12 +230,12 @@ function visualReview(ctx) {
         )
         if (persisted.note !== null) notes.push(persisted.note)
 
-        return {
+        return await imageForCallingModel(ctx, exec, {
           ok: true,
           text: renderSuccess(`Visual review of ${data.revision}: ${data.score}/100.`, data, { notes, warnings: [...(data.warnings ?? []), ...canonicalWarnings] }),
           data,
           image: persisted.image,
-        }
+        })
       } catch (cause) {
         const failure = renderFailure(cause, 'VISUAL_REVIEW_FAILED')
         return { ok: false, ...failure, image: null }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "type": "module",
   "description": "Agent-preset tool consumer: registers the model-visible DeepBlend Blender tools. Publishes no service.",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.6.4"
+    "@deepblend/dsh-blender-contracts": "0.7.0"
   },
   "license": "MIT",
   "repository": {