dsh-image-size-guard
English | 中文
A DeepSeek Harness plugin. It
keeps model requests under a gateway's request-body ceiling by replacing the
oldest history images with placeholder text — in one batch that lands the body
on a low-water mark below the ceiling, so the following turns stay under it
without rewriting history again.
Written for the agent2api gateway, whose 16 MiB request-body limit rejects a
conversation once its accumulated images grow past it. At that point the session
can never complete another request, and nothing in the Harness recovers it: the
adapter's own image budget defaults to 20 MiB and never trips, the gateway's 413
arrives as a non-retryable INVALID_REQUEST, and the session is stuck.
What it does
Every model request carries the whole history, and every image in that history is
re-encoded into every request body. A long conversation therefore grows without
bound, and eventually no request fits.
When a request for a guarded provider would exceed the budget, this plugin:
- measures the request body, using the adapter's own cached request-image
versions so the image bytes are the ones actually sent;
- works out how many of the oldest image occurrences must go: it retires enough
of them to land on a target below the ceiling, sized from recent per-turn
growth, and leaves the newest turns' images alone;
- ends the attempt with a terminal failure, which the agent loop retries;
- the retry rebuilds the request from the session surface, which now carries the
omission — so the next measurement is of a genuinely smaller body.
Why a batch, not the minimum
Every omission rewrites an old message, and a provider's prefix cache matches the
longest common prefix — so each omission invalidates the cache from that image
onward. Retiring exactly one image per turn means hitting the ceiling again on
the very next turn and paying a full re-prefill every turn: the cheapest
possible deletion is the most expensive possible cache behaviour.
Retiring a batch pays that cost once every few turns instead, for the same total
number of images retired. Under a 10 MiB ceiling, eight turns of one 1 MiB
screenshot each now retire six images in one go, leaving ~2.7 MiB and about five
quiet turns; the minimal policy retired one image, landed on 9.3 MiB, and
triggered again immediately.
Three numbers shape the batch:
targetTurns (default 5) — how many turns of growth one deletion should buy.minFillPercent (default 40) — the floor: a batch never drops the body below
this share of the budget, however large the growth estimate looks.protectedTurns (default 2) — the newest turns keep their images; they are
only retired when the request would otherwise exceed the ceiling anyway.
A request that already fits is never trimmed, even when it sits above the
low-water mark.
Install
dsh plugin --profile web add dsh-image-size-guard
Not on npm yet, so install from a clone instead:
git clone https://github.com/qq744287383/dsh-image-size-guard
dsh plugin --profile web add ./dsh-image-size-guard
The bundle inserts its Host row and its Settings page. Restart the Harness once
after the first install so the browser picks up the new client module.
Usage
Open Settings → Image size guard. The page lists one row per guarded provider
and supports add, edit, remove, and enable/disable.
| Field | Meaning |
|---|
| Provider | The provider route name, such as agent2api. |
| Request limit (MiB) | The largest request body that provider accepts. Decimals are allowed (10.5). |
| Reserve (KiB) | Headroom kept free below the limit. |
| Placeholder size (bytes) | Bytes one omitted image is estimated to occupy. |
| Enabled | Whether the guard acts on this provider. |
Each row carries a switch on the right. Flipping it saves the row with only
enabled changed, so the limit never has to be retyped, and a disabled row stops
guarding immediately — its requests pass through untouched. The row also dims, so
a switched-off provider reads as off at a glance. The switch is a real
role="switch" button, so it answers to Enter and Space and reports its state to
screen readers.
Each size is edited in the unit its field names, so a value never has to be converted by hand: the default row reads 16 / 256 / 512. The stored values stay exact bytes; the panel converts on open and on save.
The page also offers the providers the LLM registry advertises that no row covers
yet, so a new provider is one click away instead of a typed guess.
Saving writes the profile patch layer through configEditor.edit, which validates
with this plugin's own Config and reconciles the Loader. The guard and the panel
therefore read one source of truth, and a save takes effect without restarting the
Harness. Removing the last row is allowed: it means no provider is guarded.
The panel talks to POST /image-size-guard/limits. The Host admits each request
through connection.admit, so it carries the same Host/Origin checks and browser
session as the rest of the API.
Configuration
The panel edits this row; the YAML below is the same value in file form.
- insert:
- id: image-size-guard
name: 'dsh-image-size-guard'
config:
providers:
- provider: agent2api
maxRequestBytes: 16777216
reserveBytes: 262144
placeholderBytes: 512
targetTurns: 5
minFillPercent: 40
protectedTurns: 2
growthWindow: 8
enabled: true
| Key | Default | Meaning |
|---|
providers | one agent2api row | Provider limit rows. Omit the field for that default; an explicit empty list guards nothing. |
providers[].provider | — | Provider route name. |
providers[].maxRequestBytes | 16777216 (16 MiB) | The gateway's request-body ceiling. |
providers[].reserveBytes | 262144 (256 KiB) | Headroom kept free below the ceiling. |
providers[].placeholderBytes | 512 | Bytes assumed for one placeholder block. |
providers[].targetTurns | 5 | Turns of growth one batch should buy below the ceiling. 0 disables batching and restores the minimal policy. |
providers[].minFillPercent | 40 | Lowest share of the budget, in percent, a batch may leave behind. |
providers[].protectedTurns | 2 | Newest turns whose images a batch leaves alone. 0 protects nothing. |
providers[].growthWindow | 8 | Turns sampled to estimate per-turn growth. |
providers[].enabled | true | Whether the guard acts on this provider. |
The budget a request is measured against is maxRequestBytes - reserveBytes. The
reserve exists because the estimate models the JSON body, not the provider
envelope or HTTP headers, which are invisible at this seam.
Two execution paths
The omission is a durable image/offload record. Two implementations can exist,
and the plugin picks one at startup:
| Mounted executor | Who writes the record | Signal the attempt ends with |
|---|
@deepseek-ai/dsh-compaction-image-offload | the shipped executor | IMAGE_OFFLOAD_REQUIRED |
| none | this plugin | REQUEST_TOO_LARGE |
The shipped executor already listens for IMAGE_OFFLOAD_REQUIRED, so when it is
present the plugin only asks: it yields a finish chunk carrying that code and a
positive offloadImages count, and the executor writes the record and returns the
retry action. That keeps one implementation of the selection and its projection,
and follows the harness when its format changes.
When the executor is absent, the plugin falls back to its own record writer and
its own REQUEST_TOO_LARGE retry, so a profile without that bundle still works.
The presence test is the registered image/offload projection, which the executor
contributes on mount.
The signal is yielded, not thrown. A thrown error from an llm/stream
listener propagates out of llm.stream() and the agent loop re-throws it before
the agent/request-error waterfall runs, so the executor would never see it. A
finish chunk with an error reason does reach that waterfall; the adapter
produces the same chunk by turning a thrown IMAGE_OFFLOAD_REQUIRED into it.
Why the omission is durable
The selection is recorded as the Session's own image/offload event, so it
survives resume, fork, and compaction, and it is visible to the token meter and
the GUI. The placeholder text the model sees is the adapter's standard "image
omitted" handle, which names the attachment and its recovery path.
The plugin contributes the image/offload projection only when the shipped bundle
has not already registered it; its definition is byte-compatible with that
package's, so the two can coexist and a session log written by either restores
under both.
Limits
- A request whose text alone exceeds the budget is sent unchanged, with a
warning. There is nothing left to omit, and blocking the turn would be worse
than letting the gateway decide.
- The estimate covers
system, messages, and tools. Adapter-specific fields
outside that set are covered by the reserve, not measured.
- Only images are omitted. Tool results, reasoning blocks, and text are never
altered.
- The guard acts before the request leaves the process. A gateway that rejects on
something this estimate cannot see — a compressed size, a header limit — is
outside what it can prevent.
Uninstall
dsh plugin --profile web remove dsh-image-size-guard
Session logs that already contain image/offload events keep replaying: the
shipped @deepseek-ai/dsh-compaction-image-offload bundle owns that projection,
and a profile without it falls back to this plugin only while the plugin is
installed. If you remove the plugin from a profile that has neither, restore the
bundle before resuming those sessions.
Develop
No build step and no dependencies: plain ESM on the Host, a plain browser module
on the Client.
for test in test/*.test.mjs; do node "$test"; done
estimate — request measurement, growth-based low-water sizing, and the batch decision.config — the limit schema, defaults, and every rejection.offload — the durable image/offload projection and selection order.plugin — the guard's wiring: pass-through, omission, retry, failure paths.deference — both execution paths: ask the shipped executor, or do it alone.rpc — the panel endpoint: admission, methods, list/save/remove, rejections.mount — the endpoint mounts even when its carrier services arrive late.save-path — that a saved row survives the Loader's own validation.client — the browser bundle's exports and slot registration.client.render — the panel's real element tree, text, and form behavior.switch — clicking a row's switch asks the Host for the inverted state.toggle — that toggle round-trips through the Host and persists.
Layout:
lib/index.js the guard: measurement, signal, retry wiring
lib/estimate.js request-body measurement, growth sizing, and the batch decision
lib/config.js limit schema, defaults, budget arithmetic
lib/offload.js the image/offload projection and selection (fallback path)
lib/rpc.js the Settings panel endpoint
client/client.js the Settings page
locale/{en,zh}.json
License
MIT
