Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| The image offload executor for deployments composing compaction: what happens when an image-capable route rejects a request as over its image budget. | package-reference |
@deepseek-ai/dsh-compaction-image-offload
English | 中文
Summary
Image-heavy conversations continue when older images exceed a model route's budget. The plugin permanently replaces those images with text naming each attachment and its available read-only path, then retries without spending the provider retry budget. Later requests retain that choice across route changes, resume, and replay. Token accounting follows the logged selections, and provider cache reuse ends at the first changed message.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount this plugin in every composition that runs the agent loop with an image-capable route. The shipped dsh base does. Without it, an IMAGE_OFFLOAD_REQUIRED failure reaches ordinary recovery and ends the turn as an error. The plugin has no configuration: the DeepSeek adapter enforces its file-mode and inline-fallback budgets, the pi-ai adapter its base64 bound, and each reports the count it needs offloaded.
Minimal configuration
- name: '@deepseek-ai/dsh-compaction-image-offload'
What you can observe
Each decision appends one image/offload event identifying the selected occurrences by current message-event sequence and depth-first image index. The message events and surface node identities remain unchanged. An agent retry follows a fresh request/header identifying a new message series. Summary retries remain inside the same compaction bracket.
Failures and recovery
The plugin acts only on IMAGE_OFFLOAD_REQUIRED failures that carry offloadImages. It walks the surface in model request order, skips assistant nodes and images already marked, and marks that many occurrences. When nothing remains to offload it delegates on the agent/request-error waterfall, so downstream recovery or the ordinary turn error applies. The retry spends no provider retry budget and logs no llm/retry event. Cancellation before recording a selection delegates without adding an image/offload event; cancellation after a committed selection stops retry but preserves the omission.
Understand the implementation
Implementation internals — click to expand
This package owns the event declaration, reference validation, immutable image projection, selection, and retry policy. It registers imageOffloadProjection with Session before accepting image-offload events. The same browser-safe definition is exported from ./projection for detached replay; the installed format catalog assembles it for offline readers. Missing registration rejects live restore, and unloading a used definition blocks further message derivation. Token measurement folds the same selections without replacement shadow prices.
Summary failures use the synchronous compaction/summary-error waterfall. The plugin selects only the supplied summary region and returns true after recording an omission. The compaction backend re-derives and re-prices that region before retrying; each retry omits additional retained occurrences, so recovery ends when none remain. Cancellation and unrelated selection changes reject the summary. Recorded omissions survive later failure or cancellation.
The pure projection rejects invalid or repeated image references before Session commits the event, and this executor retains no separate mutable offload state.
Further Exploration
- Dedicated image-offload events — durable selections, ownership, and rejected alternatives.
- compaction seam — the neighboring summary and text-pruning operations.
- compaction-tool-result-pruner — the sibling executor that trims tool outputs while preserving image selections.
- dsh-llm —
ImageBlock.offloaded,IMAGE_OFFLOAD_REQUIRED, and the placeholder projection. - llm-deepseek adapter and llm-pi-ai adapter — the route budgets that report offload counts.
Model Experience
Offloaded request images
What the model sees
Every selected image occurrence reaches the model as placeholder text (offloadedImageText) naming the attachment and its available read-only path; unselected occurrences stay images. Selections persist across requests. A new tool read may introduce a new occurrence of the same attachment without restoring the old one.
Token effect
An offloaded occurrence costs its placeholder text instead of visual tokens. The token meter applies the logged selections when pricing each node. Reference-only heuristic counts exclude offload metadata.
KV Cache effect
A selection turns earlier images into placeholder text, so provider cache reuse ends at the first changed image for that request. The selected occurrences remain omitted afterwards.
Known Limitations and Deferred Work
- Offloaded images never return automatically — a larger budget, a larger route, or compaction lowering the total leaves the marks in place; recovery is the read-only path in the placeholder.
- Every offload costs one failed attempt — nothing plans an offload before dispatch; the route's rejection is the signal, which matches the planned move to provider-reported uncacheable images.
- A temporary small budget offloads permanently — a Files outage that forces the inline fallback, or a temporary switch to a small-budget route, offloads images a later route would have sent.
Dev Note
Working context for maintainers — click to expand
This Dev Note is non-authoritative working context: notes for maintainers and open questions. Shipped behavior and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
- The route-local byte checks that produce
IMAGE_OFFLOAD_REQUIREDare provisional: once the provider reports uncacheable images itself, the adapters map that report to a count and this executor stays as it is.