dsh-read-animation 0.1.0 → 0.1.2

package/lib/read.js

@@ -7,26 +7,59 @@
  */
 
 import { planFrames, probeAnimation, renderFrames } from './animation.js'
+import { collectBytes } from './bytes.js'
 import { loadSharp } from './sharp.js'
 
 /** Media types this tool accepts, independent of what the deployment accepts for storage. */
 const SUPPORTED_FORMATS = new Set(['gif', 'webp'])
 
+/**
+ * The stored attachment a path names, when it names one.
+ *
+ * Every image the harness stores has a normalized copy at
+ * `attachments/v1/objects/<2>/<digest>`, and that is the path a model is shown for
+ * an attachment it received. For an animation this plugin captured, that copy is
+ * the lossy single frame and the file the person actually sent is held verbatim
+ * beside it, so a model that reaches for the advertised path is asking about the
+ * animation through the wrong door.
+ *
+ * The digest alone is enough to identify the object, so this matches on the leaf
+ * name rather than on a directory layout, which also accepts a bare
+ * `sha256:<digest>` — how the same object is named everywhere else in the harness.
+ *
+ * @param pathLike - the requested path, as written.
+ * @returns `sha256:<digest>`, or undefined when this is an ordinary file.
+ */
+export function storedAttachmentId(pathLike) {
+  if (typeof pathLike !== 'string') return undefined
+  const leaf = basename(pathLike.trim())
+  const bare = /^sha256:([0-9a-f]{64})$/i.exec(leaf)
+  const digest = bare?.[1] ?? (/^[0-9a-f]{64}$/i.test(leaf) ? leaf : undefined)
+  return digest === undefined ? undefined : `sha256:${digest.toLowerCase()}`
+}
+
 /**
  * Read one animation and turn it into frames plus a description.
  * @param ctx - the plugin context carrying `fs`, `attachments`, and optionally `llm`.
  * @param settings - the resolved plugin configuration.
  * @param args - validated tool arguments.
  * @param exec - the tool execution context.
+ * @param pasted - the pasted-animation store, when that feature is enabled.
  * @returns the canonical output value.
  */
-export async function readAnimation(ctx, settings, args, exec) {
+export async function readAnimation(ctx, settings, args, exec, pasted) {
   if (typeof args.file_path !== 'string' || args.file_path.trim().length === 0) {
     throw new Error('file_path must be a non-empty string')
   }
 
   const attachments = ctx.get('attachments')
   if (attachments === undefined) throw new Error('read_animation requires a mounted attachment store')
+  if (typeof attachments.saveImages !== 'function') {
+    throw new Error(
+      'read_animation needs attachments.saveImages() to store the frames it decodes, and this DSH build does not ' +
+        'provide it; read_animation supports DSH 0.1.3-alpha.2 and later',
+    )
+  }
   await assertImageCapableRoute(ctx, exec, args.file_path)
 
   const target = await ctx.fs.resolve(args.file_path, resolveOptions(exec))
@@ -40,7 +73,13 @@ export async function readAnimation(ctx, settings, args, exec) {
   }
 
   const byteCap = Math.min(settings.maxInputBytes, attachments.imageLimits.maxMessageImageBytes)
-  const data = await ctx.fs.readBytes(target, exec.signal, byteCap)
+
+  // Follow an advertised normalized copy back to the animation this plugin kept.
+  // Without this, reading the path the model was shown reports that the picture
+  // has one frame, which is true of that file and useless as an answer.
+  const kept = await keptOriginal(ctx, attachments, pasted, target)
+  const data = kept === undefined ? await ctx.fs.readBytes(target, exec.signal, byteCap) : kept.data
+  const path = kept === undefined ? target.displayPath : kept.path
 
   // The deployment's own decoded-pixel ceiling, applied to both the probe and the
   // frame extraction. Bounding the encoded bytes does not bound decoding: a 60 KB
@@ -52,7 +91,7 @@ export async function readAnimation(ctx, settings, args, exec) {
 
   if (!SUPPORTED_FORMATS.has(animation.format)) {
     throw new Error(
-      `cannot read "${target.displayPath}" as an animation: it is ${animation.format}, and ` +
+      `cannot read "${path}" as an animation: it is ${animation.format}, and ` +
         'read_animation only handles GIF and animated WebP. Use read_image for this file.',
     )
   }
@@ -75,7 +114,7 @@ export async function readAnimation(ctx, settings, args, exec) {
     rendered.map((frame) => ({
       data: frame.data,
       mediaType: 'image/png',
-      name: `${basename(target.displayPath)}#frame${frame.index}`,
+      name: `${basename(path)}#frame${frame.index}`,
     })),
   )
 
@@ -83,7 +122,7 @@ export async function readAnimation(ctx, settings, args, exec) {
 
   const delays = animation.delaysMs
   return {
-    path: target.displayPath,
+    path,
     animation: {
       mediaType: animation.mediaType,
       width: animation.width,
@@ -124,6 +163,38 @@ export async function readAnimation(ctx, settings, args, exec) {
   }
 }
 
+/**
+ * The animation this plugin kept, for a path that names its normalized copy.
+ *
+ * Returns the original bytes and the path they actually came from, so the caller
+ * can report which file was read rather than which one was asked for. The returned
+ * path is the model's route back to the same file for a denser read.
+ *
+ * @param ctx - the plugin context.
+ * @param attachments - the mounted attachment service.
+ * @param pasted - the pasted-animation store, or undefined when disabled.
+ * @param target - the resolved requested path.
+ * @returns `{ data, path }`, or undefined when this is not a captured animation.
+ */
+async function keptOriginal(ctx, attachments, pasted, target) {
+  if (pasted === undefined) return undefined
+  const id = storedAttachmentId(target.displayPath)
+  if (id === undefined) return undefined
+  const entry = pasted.lookup(id)
+  if (entry?.original === undefined) return undefined
+
+  try {
+    const data = await collectBytes(attachments.readFileStream(entry.original.file))
+    const host =
+      typeof attachments.fileHostPath === 'function' ? attachments.fileHostPath(entry.original.file) : undefined
+    return { data, path: typeof host === 'string' && host.length > 0 ? host : target.displayPath }
+  } catch {
+    // An unreadable original is not a reason to fail: the requested path may still
+    // be a usable file in its own right.
+    return undefined
+  }
+}
+
 /**
  * Refuse the call when the resolved model route does not declare image input.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-read-animation",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Let a DeepSeek Harness agent actually see an animated GIF or animated WebP: decode every frame, sample the animation across time, and hand the model a labelled sequence of real frames instead of the single first frame the harness otherwise delivers.",
   "type": "module",
   "main": "lib/index.js",
@@ -13,13 +13,16 @@
   "files": [
     "lib",
     "scripts",
+    "assets",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",
     "CHANGELOG.md",
+    "COMPATIBILITY.md",
     "THIRD_PARTY.md",
     "LICENSE"
   ],
+  "icon": "assets/icon.svg",
   "license": "MIT",
   "author": "NeoHotaru (https://github.com/NeoHotaru)",
   "repository": {
@@ -35,7 +38,7 @@
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.7-alpha.1"
+    "dsh": ">=0.1.3-alpha.2"
   },
   "keywords": [
     "dsh",
@@ -55,7 +58,7 @@
     }
   },
   "scripts": {
-    "test": "node --test test/animation.test.js test/decode.test.js test/envelope.test.js test/filmstrip.test.js test/model.test.js test/pasted.test.js test/patch.test.js test/shipped.test.js test/tool.test.js",
+    "test": "node --test test/animation.test.js test/decode.test.js test/envelope.test.js test/filmstrip.test.js test/model.test.js test/pacing.test.js test/pasted.test.js test/patch.test.js test/read.test.js test/shipped.test.js test/tool.test.js",
     "test:integration": "node test/integration/harness.mjs",
     "test:all": "npm test && npm run test:integration",
     "prepublishOnly": "npm test",

package/scripts/check-dsh-compat.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Which DSH versions expose every attachment-store member this plugin uses.
+
+DSH publishes its whole monorepo at one version, so dsh@X pins
+dsh-attachment-local@X. That makes the probe a straight walk over DSH versions:
+download the two packages that declare the attachment service, concatenate their
+type declarations, and ask which of the members this plugin calls are present.
+
+A version whose declarations could not be fetched is reported as NO DATA, never as
+a pass. The first version of this probe returned "OK" for every release because it
+looked in the wrong place and treated an empty haystack as an empty list of
+missing needles.
+"""
+import io
+import json
+import sys
+import tarfile
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+REG = 'https://registry.npmjs.org'
+CACHE = {}
+
+REQUIRED = [
+    'saveImages',
+    'saveFile',
+    'readImage',
+    'readImageRequest',
+    'readFileStream',
+    'fileHostPath',
+    'imageLimits',
+    'maxImagePixels',
+    'root',
+]
+
+PACKAGES = ['@deepseek-ai/dsh-attachment', '@deepseek-ai/dsh-attachment-local']
+
+
+def fetch(url, binary=False):
+    req = urllib.request.Request(url, headers={'cache-control': 'no-cache',
+                                               'user-agent': 'dsh-compat-probe'})
+    with urllib.request.urlopen(req, timeout=90) as r:
+        return r.read() if binary else r.read().decode('utf-8', 'replace')
+
+
+def packument(name):
+    key = 'meta:' + name
+    if key not in CACHE:
+        CACHE[key] = json.loads(fetch('%s/%s' % (REG, name.replace('/', '%2F'))))
+    return CACHE[key]
+
+
+def declarations(name, version):
+    """Every .d.ts in one published package, or None when there is nothing to read."""
+    key = '%s@%s' % (name, version)
+    if key in CACHE:
+        return CACHE[key]
+    CACHE[key] = None
+    try:
+        entry = packument(name)['versions'].get(version)
+        if entry is None:
+            return None
+        blob = fetch(entry['dist']['tarball'], binary=True)
+        text = []
+        with tarfile.open(fileobj=io.BytesIO(blob), mode='r:gz') as tar:
+            for member in tar.getmembers():
+                if member.name.endswith('.d.ts') and member.isfile():
+                    text.append(tar.extractfile(member).read().decode('utf-8', 'replace'))
+        CACHE[key] = '\n'.join(text) if text else None
+    except Exception as error:
+        print('  ! %s: %s' % (key, error), file=sys.stderr)
+    return CACHE[key]
+
+
+def main():
+    meta = packument('@deepseek-ai/dsh')
+    versions = sorted(meta['versions'], key=lambda v: meta['time'][v])
+
+    def probe(version):
+        texts = []
+        sources = []
+        for name in PACKAGES:
+            text = declarations(name, version)
+            if text:
+                texts.append(text)
+                sources.append(name.rsplit('/', 1)[-1])
+        if not texts:
+            return version, None, None
+        joined = '\n'.join(texts)
+        missing = [member for member in REQUIRED if member not in joined]
+        return version, missing, '+'.join(sources)
+
+    with ThreadPoolExecutor(max_workers=6) as pool:
+        results = list(pool.map(probe, versions))
+
+    print('%-18s %-9s %s' % ('dsh', 'read from', 'missing members'))
+    print('-' * 84)
+    state = {}
+    for version, missing, sources in results:
+        if missing is None:
+            label = 'NO DATA'
+        elif missing:
+            label = ', '.join(missing)
+        else:
+            label = 'OK'
+        state[version] = label
+        print('%-18s %-9s %s' % (version, sources or '-', label))
+
+    ok = [v for v in versions if state[v] == 'OK']
+    nodata = [v for v in versions if state[v] == 'NO DATA']
+    print('\nevery member present : %s' % (', '.join(ok) if ok else 'none'))
+    print('no data              : %s' % (', '.join(nodata) if nodata else 'none'))
+    if ok:
+        print('\n=> continuous support from %s through %s' % (ok[0], ok[-1]))
+        first_bad = [v for v in versions[:versions.index(ok[0])]]
+        if first_bad:
+            print('   versions before it that lack something: %s' % ', '.join(first_bad))
+
+
+if __name__ == '__main__':
+    main()

package/scripts/preview-sheet.mjs

@@ -24,10 +24,28 @@ import { fileURLToPath } from 'node:url'
 const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const { loadSharp } = await import(pathToFileURL(join(REPO, 'lib', 'sharp.js')).href)
 const { buildFilmstrip } = await import(pathToFileURL(join(REPO, 'lib', 'filmstrip.js')).href)
+// The same header text the model is handed, so this preview cannot drift from it.
+const { sheetHeader } = await import(pathToFileURL(join(REPO, 'lib', 'model.js')).href)
 
 const dshHome = process.env.DSH_HOME ?? resolve(REPO, '..')
 const stateFile = join(dshHome, 'read-animation', 'v1', 'pasted.jsonl')
 const objects = join(dshHome, 'attachments', 'v1', 'objects')
+const files = join(dshHome, 'attachments', 'v1', 'files')
+
+/**
+ * Where the store keeps a file's verbatim bytes.
+ *
+ * Mirrors `ctx.attachments.fileHostPath`, which the plugin uses for the header's
+ * last line. This script has no mounted service, so the layout is spelled out
+ * here — and the first version of it spelled the layout wrong, printing
+ * `files/<name>` where the store uses `files/<2>/<digest>/<name>`, which put a
+ * path that does not exist onto the preview. The integration harness asserts the
+ * real accessor returns a real file, so only this script could drift.
+ */
+function keptFilePath(ref) {
+  const digest = String(ref.attachmentId).replace(/^sha256:/, '')
+  return join(files, digest.slice(0, 2), digest, ref.name)
+}
 
 /** Where a content-addressed attachment object lives. */
 function objectPath(attachmentId) {
@@ -62,18 +80,8 @@ for (const [position, frame] of frames.entries()) {
 }
 
 const animation = note?.animation
-const total = animation?.frameCount ?? tiles.length
-const fps =
-  animation && total > 1 && animation.durationMs > 0
-    ? ` · ~${Math.round((total * 1000) / animation.durationMs)} fps`
-    : ''
-const header = animation === undefined
-  ? `${tiles.length} sampled frames of one animation, in reading order`
-  : `${animation.mediaType} · ${animation.width}x${animation.height} px · ${total} frames · ` +
-    `${animation.durationMs} ms${fps}${animation.minDelayMs === animation.maxDelayMs ? '' : ' · uneven timing'}` +
-    `${animation.loopsForever ? ' · loops forever' : ''}\n` +
-    `The ${tiles.length} tiles below are evenly spaced samples in reading order; ` +
-    `each frame's index, duration and start time is printed under it.`
+const kept = record.entry.original?.file
+const header = sheetHeader(animation, tiles.length, kept?.name === undefined ? undefined : keptFilePath(kept))
 
 const sheet = await buildFilmstrip(sharp, { tiles, header, maxBytes: 4 * 1024 * 1024, maxDimension: 4096 })
 await writeFile(out, sheet.data)