dsh-read-animation 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,8 +1,29 @@
 # Changelog
 
-## 0.1.0 — unreleased
+## 0.1.1 — 2026-10-14
 
-Initial version.
+Fixed after the first release, from what a live session reported back.
+
+- **`read_animation` follows the path it advertises.** Every image a model receives
+  is shown as a normalized copy at `attachments/v1/objects/<2>/<digest>`, and that
+  is the path a model reaches for when it wants to look at the picture again. For a
+  pasted animation that copy is a single frame, so the tool answered "this picture
+  has one frame": true of that file, and useless as an answer. The tool now resolves
+  that path to the animation this plugin kept, and reports the file the bytes
+  actually came from. A bare `sha256:<digest>` is accepted too.
+- **The sheet says where the animation lives.** Its header ends with the path the
+  store keeps the original at, so a model that wants more than the eight samples can
+  read that path with explicit frame indices instead of searching the attachment
+  store for the file behind the picture it was sent.
+
+## 0.1.0 — 2026-10-14
+
+First release.
+
+Note for anyone publishing a later version of this package: npm routes the first
+release of a brand-new package name through staged publishing, and the registry
+carries a public `0.0.0-stage` placeholder while the real version is processed. The
+real version appears on its own a couple of minutes later; nothing needs approving.
 
 ### Fixed after an adversarial audit
 

package/README.md

@@ -147,18 +147,19 @@ the gaps are gaps.
 dsh plugin --profile web add dsh-read-animation
 ```
 
-Replace `web` with your profile name. **Not on npm yet** — until it is, install
-straight from the repository:
+Replace `web` with your profile name. Both routes are verified in a real profile:
+the install lands, `dsh plugin add` registers the bundle, and the `sharp` native
+binary resolves from the package's own `node_modules`.
 
 ```sh
-dsh plugin --profile web add github:NeoHotaru/dsh-read-animation
+dsh plugin --profile web add dsh-read-animation                            # npm
+dsh plugin --profile web add github:NeoHotaru/dsh-read-animation#v0.1.0    # a tagged commit
 ```
 
-That route is verified end to end: it installs, `dsh plugin add` registers the
-bundle, and the `sharp` native binary resolves from the package's own
-`node_modules`. (A git spec copies the whole repository, tests and fixtures
-included, which is why the npm package above is the nicer install once it
-exists.)
+The git route copies the whole repository, tests and fixtures included, which is
+why npm is the nicer install. (A brand-new package name goes through npm's staged
+publishing on its first release, so the version you install may briefly not exist
+yet while the registry processes it.)
 
 Or from a checkout:
 

package/README.zh.md

@@ -121,15 +121,16 @@ frame 9 of 24 (sample 3) · starts at 450 ms · displayed for 50 ms
 dsh plugin --profile web add dsh-read-animation
 ```
 
-`web` 换成你自己的 profile 名。**目前还没发到 npm** —— 在那之前可以直接从仓库装：
+`web` 换成你自己的 profile 名。**两条路都在真实 profile 里验证过**：装得上、`dsh plugin add` 会把它
+注册成 bundle、`sharp` 的原生二进制也能从包自己的 `node_modules` 里解析出来。
 
 ```sh
-dsh plugin --profile web add github:NeoHotaru/dsh-read-animation
+dsh plugin --profile web add dsh-read-animation                            # npm
+dsh plugin --profile web add github:NeoHotaru/dsh-read-animation#v0.1.0    # 钉住某个 tag
 ```
 
-这条路是**实测过的**：能装上、`dsh plugin add` 会把它注册成 bundle、`sharp` 的原生二进制也能
-从包自己的 `node_modules` 里解析出来。（git spec 会把整个仓库连测试和 fixture 一起拷下来，
-所以等上面那个 npm 包存在之后，npm 那条路更干净。）
+git 那条会把整个仓库（含测试和 fixture）拷下来，所以 npm 更干净。（全新包名的**首次发布**会走
+npm 的 staged publishing，所以刚发完那一小段时间里，registry 上可能还查不到那个版本号。）
 
 或者从本地检出：
 

package/lib/bytes.js

@@ -0,0 +1,31 @@
+/**
+ * Collect a bounded byte stream into one array.
+ *
+ * `readFileStream` hands back an async iterable, and two callers here need the
+ * whole thing in one piece: the display path, which serves an original animation
+ * over the wire, and the tool, which decodes what the store kept verbatim.
+ *
+ * @module dsh-read-animation/bytes
+ */
+
+/**
+ * Drain an async iterable of chunks.
+ *
+ * @param stream - the chunks, in order.
+ * @returns one `Uint8Array` holding all of them.
+ */
+export async function collectBytes(stream) {
+  const chunks = []
+  let total = 0
+  for await (const chunk of stream) {
+    chunks.push(chunk)
+    total += chunk.byteLength
+  }
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const chunk of chunks) {
+    out.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return out
+}

package/lib/display.js

@@ -31,6 +31,7 @@
  * @module dsh-read-animation/display
  */
 
+import { collectBytes } from './bytes.js'
 import { describe, warn, wrapServiceMethod } from './patch.js'
 
 /**
@@ -64,7 +65,7 @@ export function installOriginalDisplay(ctx, pasted) {
       const entry = pasted.lookup(ref?.attachmentId)
       if (entry?.original === undefined) return base(ref, signal)
       try {
-        const data = await collect(attachments.readFileStream(entry.original.file, signal))
+        const data = await collectBytes(attachments.readFileStream(entry.original.file, signal))
         return { ref: displayedRef(ref, entry.original, data.byteLength), data }
       } catch (error) {
         // A missing or unreadable original must not cost the user their picture.
@@ -122,19 +123,3 @@ function displayedRef(ref, original, bytes) {
   }
 }
 
-/** Drain a bounded byte stream into one array. */
-async function collect(stream) {
-  const chunks = []
-  let total = 0
-  for await (const chunk of stream) {
-    chunks.push(chunk)
-    total += chunk.byteLength
-  }
-  const out = new Uint8Array(total)
-  let at = 0
-  for (const chunk of chunks) {
-    out.set(chunk, at)
-    at += chunk.byteLength
-  }
-  return out
-}

package/lib/index.js

@@ -62,15 +62,19 @@ const DEFAULT_MAX_INPUT_BYTES = 64 * 1024 * 1024
 export function apply(ctx, config = {}) {
   const settings = resolveConfig(config)
   ctx.inject(['attachments'], (imageCtx) => {
+    let pasted
     if (settings.expandPastedAnimations) {
       // Capture at admission (the last moment the animation's bytes exist) and
       // hand the frames to the model at request time. The message is not touched.
-      const pasted = createPastedStore(imageCtx)
+      pasted = createPastedStore(imageCtx)
       installAdmissionCapture(imageCtx, settings, pasted)
       const display = installOriginalDisplay(imageCtx, pasted)
       installModelFrames(imageCtx, pasted, display)
     }
-    registerTool(imageCtx, settings)
+    // The store is handed to the tool as well: a model shown a normalized copy of
+    // a pasted animation reaches for that path first, and the tool can answer with
+    // the animation instead of reporting that the picture has one frame.
+    registerTool(imageCtx, settings, pasted)
   })
 }
 
@@ -102,7 +106,7 @@ function resolveConfig(config) {
 }
 
 /** Build and register the `read_animation` tool definition. */
-function registerTool(ctx, settings) {
+function registerTool(ctx, settings, pasted) {
   ctx.tools.register({
     name: TOOL_NAME,
     description: describeTool(settings),
@@ -116,7 +120,7 @@ function registerTool(ctx, settings) {
     async execute(args, exec) {
       const violations = validateArguments(args)
       if (violations.length > 0) throw new Error(`invalid arguments: ${violations.join('; ')}`)
-      return readAnimation(ctx, settings, args, exec)
+      return readAnimation(ctx, settings, args, exec, pasted)
     },
     presentCall(args) {
       return {

package/lib/model.js

@@ -163,7 +163,7 @@ async function sheetFor(ctx, entry, ref, target, signal, display) {
 
   const sheet = await buildFilmstrip(sharp, {
     tiles,
-    header: headerFor(entry.note?.animation, tiles.length),
+    header: sheetHeader(entry.note?.animation, tiles.length, hostPathOf(ctx, entry)),
     // One tile may be as large as a single frame would have been for this caller:
     // the sheet costs N tiles, not one picture multiplied by N.
     tileMaxWidth: target?.width,
@@ -191,24 +191,52 @@ async function sheetFor(ctx, entry, ref, target, signal, display) {
   }
 }
 
+/**
+ * Where the animation itself is kept, when the store can say.
+ *
+ * The sheet names it so the model has a route to a denser read: eight samples is
+ * what fits in one image, and `read_animation(path, frames: […])` is how it asks
+ * for a specific moment afterwards. Without the path it has to go looking through
+ * the attachment store for the file behind the picture it was sent.
+ */
+function hostPathOf(ctx, entry) {
+  const attachments = ctx.get('attachments')
+  if (attachments === undefined || typeof attachments.fileHostPath !== 'function') return undefined
+  const path = attachments.fileHostPath(entry.original.file)
+  return typeof path === 'string' && path.length > 0 ? path : undefined
+}
+
 /**
  * The sheet's own header: what this animation is, and how it was sampled.
  *
- * Kept short and split in two on purpose. A single long line is not wrapped by
- * anything downstream — the sheet's own layout wraps each line to the canvas, and
- * that works better from meaningful breaks than from one 200-character sentence.
+ * Kept short and split on purpose. A single long line is not wrapped by anything
+ * downstream — the sheet's own layout wraps each line to the canvas, and that
+ * works better from meaningful breaks than from one 200-character sentence.
+ *
+ * Exported so the preview script renders the same text the model is handed,
+ * instead of a second copy that can drift from this one.
+ *
+ * @param animation - the captured animation's facts, when available.
+ * @param sampled - how many tiles the sheet holds.
+ * @param originalPath - where the animation itself is kept, when known.
+ * @returns the header, lines separated by newlines.
  */
-function headerFor(animation, sampled) {
+export function sheetHeader(animation, sampled, originalPath) {
   if (animation === undefined) return `${sampled} sampled frames of one animation, in reading order`
   const total = animation.frameCount
   const fps =
     total > 1 && animation.durationMs > 0 ? ` · ~${Math.round((total * 1000) / animation.durationMs)} fps` : ''
   const timing = animation.minDelayMs === animation.maxDelayMs ? '' : ' · uneven timing'
   const loops = animation.loopsForever === true ? ' · loops forever' : ''
+  const source =
+    originalPath === undefined
+      ? `All ${total} frames are in the file this was pasted from`
+      : `All ${total} frames are at ${originalPath}`
   return (
     `${animation.mediaType} · ${animation.width}x${animation.height} px · ${total} frames · ` +
     `${animation.durationMs} ms${fps}${timing}${loops}\n` +
     `The ${sampled} tiles below are evenly spaced samples in reading order; ` +
-    `each frame's index, duration and start time is printed under it.`
+    `each frame's index, duration and start time is printed under it.\n` +
+    `${source} — read_animation on that path with explicit frame indices looks closer at any moment.`
   )
 }

package/lib/read.js

@@ -7,20 +7,47 @@
  */
 
 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')
   }
@@ -40,7 +67,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 +85,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 +108,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 +116,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 +157,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.1",
   "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",
@@ -55,7 +55,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/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/preview-sheet.mjs

@@ -24,10 +24,24 @@ 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; the integration harness asserts the real accessor returns a real path.
+ */
+function keptFilePath(ref) {
+  return join(files, ref.name)
+}
 
 /** Where a content-addressed attachment object lives. */
 function objectPath(attachmentId) {
@@ -62,18 +76,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)