@qilin-agent/compaction-image-offload 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,55 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/compaction/compaction-image-offload/README.md
+/:
+  en: b599a8ee08c48558
+  zh: 4534254e1fd4cdcf
+/qilin-compaction-image-offload:
+  en: 677cc41173025d5b
+  zh: 8ee4a356d326571d
+/qilin-compaction-image-offload/summary:
+  en: 8881f7155e7f99c7
+  zh: 1e01354c7a7b1e68
+/qilin-compaction-image-offload/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-compaction-image-offload/use-this-package:
+  en: 100dfe44db6bcc2c
+  zh: 6e9665cd10c75d7a
+/qilin-compaction-image-offload/use-this-package/minimal-configuration:
+  en: 7e32fdf2571d190c
+  zh: 6b455c98d3afa3e0
+/qilin-compaction-image-offload/use-this-package/what-you-can-observe:
+  en: 6a156ba4e44b520a
+  zh: a61fc63697f85095
+/qilin-compaction-image-offload/use-this-package/failures-and-recovery:
+  en: 5e4ac1980eec905a
+  zh: 0284e597c82cb179
+/qilin-compaction-image-offload/understand-the-implementation:
+  en: 560e73eece24a4de
+  zh: 4e99c02296be59c8
+/qilin-compaction-image-offload/further-exploration:
+  en: 4fdfd5f29d376592
+  zh: cad39487903af5c0
+/qilin-compaction-image-offload/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-compaction-image-offload/model-experience/offloaded-request-images:
+  en: e57e89ce994680bd
+  zh: b31ac5142af08695
+/qilin-compaction-image-offload/model-experience/offloaded-request-images/what-the-model-sees:
+  en: 54a927e19008dd58
+  zh: 45ec6d988b73e2fb
+/qilin-compaction-image-offload/model-experience/offloaded-request-images/token-effect:
+  en: a1a6386bbdad684e
+  zh: 09a1f02f013390cd
+/qilin-compaction-image-offload/model-experience/offloaded-request-images/kv-cache-effect:
+  en: 1ddf05ccd042aa85
+  zh: 0f2984a2e6b8c5c7
+/qilin-compaction-image-offload/known-limitations-and-deferred-work:
+  en: 56e34b1ca548fa07
+  zh: 8ad247f5251a5461
+/qilin-compaction-image-offload/known-limitations-and-deferred-work/dev-note:
+  en: 699a8ae4642c8f5a
+  zh: 19a4edd00e473c8a

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+---
+description: "The image offload executor for deployments composing compaction: what happens when an image-capable route rejects a request as over its image budget."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/compaction-image-offload
+
+English | [中文](README.zh.md)
+
+## 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](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this plugin in every composition that runs the agent loop with an image-capable route. The shipped `qilin` 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
+
+```yaml
+- name: '@qilin-agent/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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+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.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Dedicated image-offload events](../../../.agents/notes/implemented/architecture/2026-09-10-image-offload-events.md) — durable selections, ownership, and rejected alternatives.
+- [compaction seam](../compaction/README.md) — the neighboring summary and text-pruning operations.
+- [compaction-tool-result-pruner](../compaction-tool-result-pruner/README.md) — the sibling executor that trims tool outputs while preserving image selections.
+- [qilin-llm](../../llm/llm/README.md) — `ImageBlock.offloaded`, `IMAGE_OFFLOAD_REQUIRED`, and the placeholder projection.
+- [llm-deepseek adapter](../../llm/llm-deepseek/README.md) and [llm-pi-ai adapter](../../llm/llm-pi-ai/README.md) — the route budgets that report offload counts.
+
+-----
+
+<a id="model-experience"></a>
+## 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+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_REQUIRED` are provisional: once the provider reports uncacheable images itself, the adapters map that report to a count and this executor stays as it is.
+
+</details>

package/README.zh.md

@@ -0,0 +1,106 @@
+---
+description: "面向组合 compaction 的部署的图片省略执行器说明：支持图片的路由以请求超出图片预算拒绝时会发生什么。"
+kind: "package-reference"
+---
+
+# @qilin-agent/compaction-image-offload
+
+[English](README.md) | 中文
+
+## 概述
+
+当较早的图片超出模型路由的预算时，图片密集的会话仍可继续。本插件永久将这些图片替换为注明附件及其可用只读路径的文本，然后重试，不消耗提供方重试预算。后续请求在切换路由、恢复和回放时都保留这一选择。token 计量随日志记录的选择更新，提供方缓存只能复用到第一条被修改的消息之前。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+凡是运行 agent loop（智能体循环）并带有支持图片的路由的组合，都应挂载本插件，随附的 `qilin` 基础配置已经挂载。没有它，`IMAGE_OFFLOAD_REQUIRED` 失败会进入普通恢复并以错误结束该轮次。本插件没有配置：DeepSeek 适配器执行其 file 模式和内联回退预算，pi-ai 适配器执行其 base64 上限，各自上报需要省略的数量。
+
+### 最小可用组合
+
+```yaml
+- name: '@qilin-agent/compaction-image-offload'
+```
+
+### 你可以观察到什么
+
+每次决定追加一条 `image/offload` 事件，通过当前消息事件的序号和消息内深度优先的图片序号指定省略位置。消息事件和表层节点标识保持不变。agent 重试前会追加新的 `request/header`，标明新的消息序列。摘要重试保留在同一对压缩标记内。
+
+### 失败与恢复
+
+本插件只处理带 `offloadImages` 的 `IMAGE_OFFLOAD_REQUIRED` 失败。它按模型请求顺序遍历表层，跳过 assistant 节点和已经标记的图片，给指定数量的出现位置打标记。没有可省略的图片时在 `agent/request-error` waterfall 上委派下游，由下游恢复或普通的轮次错误处理。这次重试不占提供方重试预算，也不追加 `llm/retry` 事件。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部——点击展开</summary>
+
+本包拥有事件声明、引用校验、不可变图片投影、选图和重试策略。它在接受图片省略事件前向 Session 注册 `imageOffloadProjection`。相同的浏览器安全处理器通过 `./projection` 导出，供独立回放使用，当前格式目录为离线读取器装配该处理器。缺少注册时拒绝实时恢复，卸载已经使用的处理器后拒绝继续派生消息。token 测量应用同一份选择，不依赖替换影子价格。
+
+摘要失败使用同步的 `compaction/summary-error` waterfall。插件只在传入的摘要选区内选图，记录省略后返回 true。压缩后端重新派生该选区并计价，然后重试。每次重试都会继续省略保留的图片，没有可省略的位置时结束恢复。取消或无关的选区变更会使摘要失败。已经记录的省略在后续失败或取消后仍然有效。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [独立的图片省略事件](../../../.agents/notes/implemented/architecture/2026-09-10-image-offload-events.zh.md)，记录持久选择、职责和被否决的方案。
+- [compaction seam](../compaction/README.zh.md)，相邻的摘要和文本剪枝操作。
+- [compaction-tool-result-pruner](../compaction-tool-result-pruner/README.zh.md)，保留图片选择并修剪工具输出的兄弟执行器。
+- [qilin-llm](../../llm/llm/README.zh.md)——`ImageBlock.offloaded`、`IMAGE_OFFLOAD_REQUIRED` 与占位投影。
+- [llm-deepseek 适配器](../../llm/llm-deepseek/README.zh.md)与 [llm-pi-ai 适配器](../../llm/llm-pi-ai/README.zh.md)——上报省略数量的路由预算。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 已省略的请求图片
+
+#### 模型看到的内容
+
+每个选中的图片出现位置以占位文本（`offloadedImageText`）到达模型，文本注明附件及其可用只读路径，未选中的位置仍是图片。选择在后续请求中持续生效。新的工具读取可以引入同一附件的新出现位置，不会恢复旧位置。
+
+#### Token 影响
+
+被省略的出现位置只花费占位文本，不再花费视觉 token。token meter 为每个节点定价时应用日志记录的选择。仅针对引用的启发式计数不计入省略元数据。
+
+#### KV Cache 影响
+
+一次选择把较早的图片换成占位文本，该请求的提供方缓存复用因此止于第一张被修改的图片。所选位置之后仍保持省略。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **被省略的图片不会自动回归**——更大的预算、更大的路由或 compaction 降低总量都不会移除标记；恢复手段是占位文本中的只读路径。
+- **每次省略都要先失败一次**——发送前没有任何规划，路由的拒绝就是信号，这和计划中改由 provider 报告无法缓存图片的方向一致。
+- **临时的小预算会永久省略**——迫使内联回退的 Files 故障，或临时切到小预算路由，会省略后来的路由本可以发送的图片。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作背景——点击展开</summary>
+
+本开发备注是非权威的工作背景：给维护者的备注和未决问题。已交付的行为与被接受的理由见上文各节、包代码和链接的 Agent Note。
+
+- 产生 `IMAGE_OFFLOAD_REQUIRED` 的路由本地字节检查是过渡实现：provider 自己报告无法缓存的图片之后，adapter 把该报告换算成数量，本执行器保持不变。
+
+</details>

package/lib/index.js

@@ -0,0 +1,154 @@
+import { IMAGE_OFFLOAD_REQUIRED_CODE, LlmError } from "@qilin-agent/llm";
+import { deepFreeze } from "@qilin-agent/util-values";
+//#region lib/types/image-offload.js
+/** Select and log permanent image omissions in current model-request order. */
+/**
+* Record one decision omitting the oldest retained input-image occurrences.
+* Assistant nodes carry model output and are excluded. Image indexes count
+* every occurrence, including previously offloaded ones, within each message.
+* @param session - session whose next request applies the decision.
+* @param sourceEventSeqs - input message events in the failed request's order.
+* @param count - additional retained occurrences the adapter needs omitted.
+* @returns whether any occurrence remained to offload.
+*/
+function offloadOldestImages(session, sourceEventSeqs, count) {
+	const targets = [];
+	for (const seq of sourceEventSeqs) {
+		if (count === 0) break;
+		const event = session.eventAt(seq);
+		if (event.type !== "user/message" && event.type !== "tool/result") continue;
+		const message = session.deriveEventMessage(event);
+		const imageIndexes = [];
+		let imageIndex = 0;
+		const visit = (blocks) => {
+			for (const block of blocks) {
+				if (count === 0) break;
+				if (block.type === "image") {
+					if (block.offloaded !== true) {
+						imageIndexes.push(imageIndex);
+						count -= 1;
+					}
+					imageIndex += 1;
+				}
+			}
+		};
+		visit(message.content);
+		if (imageIndexes.length > 0) targets.push({
+			seq,
+			imageIndexes
+		});
+	}
+	if (targets.length === 0) return false;
+	session.append("image/offload", { targets });
+	return true;
+}
+//#endregion
+//#region lib/types/project-message.js
+/** Immutable application of the image occurrences recorded by image/offload. */
+/**
+* Project selected image occurrences to immutable offloaded blocks.
+* @param message - message projected before this decision.
+* @param indexes - nonempty, strictly increasing depth-first image indexes.
+* @returns an immutable message with the same identity and selected images marked.
+* @throws when a selected occurrence is missing or already offloaded.
+*/
+function offloadMessageImages(message, indexes) {
+	let imageIndex = 0;
+	let selected = 0;
+	const visit = (blocks) => {
+		let next;
+		for (const [index, block] of blocks.entries()) {
+			let projected = block;
+			if (block.type === "image") {
+				if (imageIndex === indexes[selected]) {
+					if (block.offloaded === true) throw new Error(`image/offload: image index ${imageIndex} is already offloaded`);
+					projected = {
+						...block,
+						offloaded: true
+					};
+					selected += 1;
+				}
+				imageIndex += 1;
+			}
+			if (projected !== block) next ??= blocks.slice(0, index);
+			next?.push(projected);
+		}
+		return next ?? blocks;
+	};
+	const content = visit(message.content);
+	if (selected !== indexes.length) throw new Error(`image/offload: image index ${indexes[selected]} does not exist`);
+	return deepFreeze({
+		...message,
+		content
+	});
+}
+//#endregion
+//#region lib/types/projection.js
+/** Browser-safe durable image selection declaration and pure replay definition. */
+/** Whether a durable value is a JSON object. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Whether a durable occurrence index or sequence is canonical. */
+function isIndex(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);
+}
+/** Atomic validation and reconstruction shared by live sessions and detached replay. */
+const imageOffloadProjection = {
+	type: "image/offload",
+	project(event, context) {
+		const data = event.data;
+		if (!isRecord(data) || Object.keys(data).length !== 1 || !Array.isArray(data["targets"]) || data["targets"].length === 0) throw new Error("image/offload: data must contain a nonempty targets array");
+		const messages = /* @__PURE__ */ new Map();
+		const nodes = new Set(context.nodes);
+		for (const target of data["targets"]) {
+			if (!isRecord(target) || Object.keys(target).length !== 2 || !isIndex(target["seq"]) || !Array.isArray(target["imageIndexes"]) || target["imageIndexes"].length === 0) throw new Error("image/offload: each target must contain a seq and nonempty imageIndexes");
+			const seq = target["seq"];
+			if (messages.has(seq)) throw new Error(`image/offload: duplicate target seq ${seq}`);
+			if (!nodes.has(seq)) throw new Error(`image/offload: target seq ${seq} is not a current surface node`);
+			const source = context.events[seq - context.baseSeq];
+			if (source?.type !== "user/message" && source?.type !== "tool/result") throw new Error(`image/offload: target seq ${seq} must be user/message or tool/result`);
+			let previous = -1;
+			for (const index of target["imageIndexes"]) {
+				if (!isIndex(index) || index <= previous) throw new Error("image/offload: imageIndexes must be strictly increasing non-negative safe integers");
+				previous = index;
+			}
+			const message = context.messages.get(seq) ?? (source.type === "user/message" ? source.data : source.data.message);
+			messages.set(seq, offloadMessageImages(message, target["imageIndexes"]));
+		}
+		return messages;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Image offload executor for the compaction seam. When an image-capable route
+* fails a request with `IMAGE_OFFLOAD_REQUIRED`, the plugin records one
+* `image/offload` decision selecting the oldest retained input occurrences
+* and retries through the agent or compaction summary error waterfall. Every route
+* sends placeholder text for those occurrences in subsequent requests.
+*
+* @module @qilin-agent/compaction-image-offload
+*/
+const name = "compaction-image-offload";
+const inject = ["agents", "sessions"];
+/**
+* Mount agent and summary recovery listeners without configuration.
+* @param ctx - the plugin context.
+*/
+function apply(ctx) {
+	ctx.sessions.registerMessageProjection(imageOffloadProjection);
+	ctx.on("agent/request-error", ({ agent, failure }, next) => {
+		if (failure.code !== IMAGE_OFFLOAD_REQUIRED_CODE || failure.offloadImages === void 0) return next();
+		if (!offloadOldestImages(agent.session, agent.session.surface.nodes, failure.offloadImages)) return next();
+		return Promise.resolve({ kind: "retry" });
+	});
+	ctx.on("compaction/summary-error", ({ session, sourceEventSeqs, error, signal }, next) => {
+		if (!(error instanceof LlmError) || error.code !== IMAGE_OFFLOAD_REQUIRED_CODE || error.failure.offloadImages === void 0) return next();
+		signal?.throwIfAborted();
+		if (!offloadOldestImages(session, sourceEventSeqs, error.failure.offloadImages)) return next();
+		return true;
+	});
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/image-offload.d.ts

@@ -0,0 +1,13 @@
+/** Select and log permanent image omissions in current model-request order. */
+import type { Session, SessionSeq } from '@qilin-agent/session';
+/**
+ * Record one decision omitting the oldest retained input-image occurrences.
+ * Assistant nodes carry model output and are excluded. Image indexes count
+ * every occurrence, including previously offloaded ones, within each message.
+ * @param session - session whose next request applies the decision.
+ * @param sourceEventSeqs - input message events in the failed request's order.
+ * @param count - additional retained occurrences the adapter needs omitted.
+ * @returns whether any occurrence remained to offload.
+ */
+export declare function offloadOldestImages(session: Session, sourceEventSeqs: readonly SessionSeq[], count: number): boolean;
+//# sourceMappingURL=image-offload.d.ts.map

package/lib/types/image-offload.js

@@ -0,0 +1,47 @@
+/** Select and log permanent image omissions in current model-request order. */
+/**
+ * Record one decision omitting the oldest retained input-image occurrences.
+ * Assistant nodes carry model output and are excluded. Image indexes count
+ * every occurrence, including previously offloaded ones, within each message.
+ * @param session - session whose next request applies the decision.
+ * @param sourceEventSeqs - input message events in the failed request's order.
+ * @param count - additional retained occurrences the adapter needs omitted.
+ * @returns whether any occurrence remained to offload.
+ */
+export function offloadOldestImages(session, sourceEventSeqs, count) {
+    const targets = [];
+    for (const seq of sourceEventSeqs) {
+        if (count === 0)
+            break;
+        // Existing Session history read; migration deferred. Current surface nodes index the durable log.
+        // oxlint-disable-next-line typescript/no-non-null-assertion, typescript/no-deprecated
+        const event = session.eventAt(seq);
+        if (event.type !== 'user/message' && event.type !== 'tool/result')
+            continue;
+        // oxlint-disable-next-line typescript/no-non-null-assertion -- both input node types produce a message
+        const message = session.deriveEventMessage(event);
+        const imageIndexes = [];
+        let imageIndex = 0;
+        const visit = (blocks) => {
+            for (const block of blocks) {
+                if (count === 0)
+                    break;
+                if (block.type === 'image') {
+                    if (block.offloaded !== true) {
+                        imageIndexes.push(imageIndex);
+                        count -= 1;
+                    }
+                    imageIndex += 1;
+                }
+            }
+        };
+        visit(message.content);
+        if (imageIndexes.length > 0)
+            targets.push({ seq, imageIndexes });
+    }
+    if (targets.length === 0)
+        return false;
+    session.append('image/offload', { targets });
+    return true;
+}
+//# sourceMappingURL=image-offload.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Image offload executor for the compaction seam. When an image-capable route
+ * fails a request with `IMAGE_OFFLOAD_REQUIRED`, the plugin records one
+ * `image/offload` decision selecting the oldest retained input occurrences
+ * and retries through the agent or compaction summary error waterfall. Every route
+ * sends placeholder text for those occurrences in subsequent requests.
+ *
+ * @module @qilin-agent/compaction-image-offload
+ */
+import type { Context } from '@qilin-agent/kylin';
+export declare const name = "compaction-image-offload";
+export declare const inject: string[];
+/**
+ * Mount agent and summary recovery listeners without configuration.
+ * @param ctx - the plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,40 @@
+/**
+ * Image offload executor for the compaction seam. When an image-capable route
+ * fails a request with `IMAGE_OFFLOAD_REQUIRED`, the plugin records one
+ * `image/offload` decision selecting the oldest retained input occurrences
+ * and retries through the agent or compaction summary error waterfall. Every route
+ * sends placeholder text for those occurrences in subsequent requests.
+ *
+ * @module @qilin-agent/compaction-image-offload
+ */
+import { IMAGE_OFFLOAD_REQUIRED_CODE, LlmError } from '@qilin-agent/llm';
+import { offloadOldestImages } from "./image-offload.js";
+import { imageOffloadProjection } from "./projection.js";
+export const name = 'compaction-image-offload';
+export const inject = ['agents', 'sessions'];
+/**
+ * Mount agent and summary recovery listeners without configuration.
+ * @param ctx - the plugin context.
+ */
+export function apply(ctx) {
+    ctx.sessions.registerMessageProjection(imageOffloadProjection);
+    ctx.on('agent/request-error', ({ agent, failure }, next) => {
+        if (failure.code !== IMAGE_OFFLOAD_REQUIRED_CODE || failure.offloadImages === undefined)
+            return next();
+        // A durable surface repair, not a provider retry: it spends no retry budget and logs no retry event.
+        if (!offloadOldestImages(agent.session, agent.session.surface.nodes, failure.offloadImages))
+            return next();
+        return Promise.resolve({ kind: 'retry' });
+    });
+    ctx.on('compaction/summary-error', ({ session, sourceEventSeqs, error, signal }, next) => {
+        if (!(error instanceof LlmError)
+            || error.code !== IMAGE_OFFLOAD_REQUIRED_CODE
+            || error.failure.offloadImages === undefined)
+            return next();
+        signal?.throwIfAborted();
+        if (!offloadOldestImages(session, sourceEventSeqs, error.failure.offloadImages))
+            return next();
+        return true;
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/types/project-message.d.ts

@@ -0,0 +1,11 @@
+/** Immutable application of the image occurrences recorded by image/offload. */
+import type { Message } from '@qilin-agent/llm';
+/**
+ * Project selected image occurrences to immutable offloaded blocks.
+ * @param message - message projected before this decision.
+ * @param indexes - nonempty, strictly increasing depth-first image indexes.
+ * @returns an immutable message with the same identity and selected images marked.
+ * @throws when a selected occurrence is missing or already offloaded.
+ */
+export declare function offloadMessageImages(message: Message, indexes: readonly number[]): Message;
+//# sourceMappingURL=project-message.d.ts.map

package/lib/types/project-message.js

@@ -0,0 +1,37 @@
+/** Immutable application of the image occurrences recorded by image/offload. */
+import { deepFreeze } from '@qilin-agent/util-values';
+/**
+ * Project selected image occurrences to immutable offloaded blocks.
+ * @param message - message projected before this decision.
+ * @param indexes - nonempty, strictly increasing depth-first image indexes.
+ * @returns an immutable message with the same identity and selected images marked.
+ * @throws when a selected occurrence is missing or already offloaded.
+ */
+export function offloadMessageImages(message, indexes) {
+    let imageIndex = 0;
+    let selected = 0;
+    const visit = (blocks) => {
+        let next;
+        for (const [index, block] of blocks.entries()) {
+            let projected = block;
+            if (block.type === 'image') {
+                if (imageIndex === indexes[selected]) {
+                    if (block.offloaded === true)
+                        throw new Error(`image/offload: image index ${imageIndex} is already offloaded`);
+                    projected = { ...block, offloaded: true };
+                    selected += 1;
+                }
+                imageIndex += 1;
+            }
+            if (projected !== block)
+                next ??= blocks.slice(0, index);
+            next?.push(projected);
+        }
+        return next ?? blocks;
+    };
+    const content = visit(message.content);
+    if (selected !== indexes.length)
+        throw new Error(`image/offload: image index ${indexes[selected]} does not exist`);
+    return deepFreeze({ ...message, content });
+}
+//# sourceMappingURL=project-message.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,27 @@
+/** Browser-safe durable image selection declaration and pure replay definition. */
+import type { SessionSeq } from '@qilin-agent/session/types';
+import type { SessionMessageProjection } from '@qilin-agent/session/surface';
+/** Exact input-image occurrences selected by one durable offload decision. */
+export interface ImageOffloadTarget {
+    /** Current message-producing event containing these occurrences. */
+    seq: SessionSeq;
+    /** Zero-based depth-first image indexes within the immutable message. */
+    imageIndexes: number[];
+}
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /**
+         * Permanently omit selected input-image occurrences from subsequent model requests.
+         * Targets name unique current user/message or tool/result nodes. Nonempty, strictly
+         * increasing indexes count all images in depth-first order, including nested tool
+         * results and already omitted images. Message nodes and identities remain unchanged.
+         * @messageProjection
+         */
+        'image/offload': {
+            targets: ImageOffloadTarget[];
+        };
+    }
+}
+/** Atomic validation and reconstruction shared by live sessions and detached replay. */
+export declare const imageOffloadProjection: SessionMessageProjection<'image/offload'>;
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,49 @@
+/** Browser-safe durable image selection declaration and pure replay definition. */
+import { offloadMessageImages } from "./project-message.js";
+/** Whether a durable value is a JSON object. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether a durable occurrence index or sequence is canonical. */
+function isIndex(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);
+}
+/** Atomic validation and reconstruction shared by live sessions and detached replay. */
+export const imageOffloadProjection = {
+    type: 'image/offload',
+    project(event, context) {
+        const data = event.data;
+        if (!isRecord(data) || Object.keys(data).length !== 1 || !Array.isArray(data['targets']) || data['targets'].length === 0) {
+            throw new Error('image/offload: data must contain a nonempty targets array');
+        }
+        const messages = new Map();
+        const nodes = new Set(context.nodes);
+        for (const target of data['targets']) {
+            if (!isRecord(target) || Object.keys(target).length !== 2 || !isIndex(target['seq'])
+                || !Array.isArray(target['imageIndexes']) || target['imageIndexes'].length === 0) {
+                throw new Error('image/offload: each target must contain a seq and nonempty imageIndexes');
+            }
+            const seq = target['seq'];
+            if (messages.has(seq))
+                throw new Error(`image/offload: duplicate target seq ${seq}`);
+            if (!nodes.has(seq))
+                throw new Error(`image/offload: target seq ${seq} is not a current surface node`);
+            const source = context.events[seq - context.baseSeq];
+            if (source?.type !== 'user/message' && source?.type !== 'tool/result') {
+                throw new Error(`image/offload: target seq ${seq} must be user/message or tool/result`);
+            }
+            let previous = -1;
+            for (const index of target['imageIndexes']) {
+                if (!isIndex(index) || index <= previous) {
+                    throw new Error('image/offload: imageIndexes must be strictly increasing non-negative safe integers');
+                }
+                previous = index;
+            }
+            const message = context.messages.get(seq)
+                ?? (source.type === 'user/message' ? source.data : source.data.message);
+            messages.set(seq, offloadMessageImages(message, target['imageIndexes']));
+        }
+        return messages;
+    },
+};
+//# sourceMappingURL=projection.js.map

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@qilin-agent/compaction-image-offload",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Durable image offload for image-capable routes: replace over-budget request images with placeholders and retry",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/compaction/compaction-image-offload"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./projection": {
+      "types": "./lib/types/projection.d.ts",
+      "default": "./lib/types/projection.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/compaction": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/llm": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/agent-loop-testkit": "3.1.3",
+    "@qilin-agent/agent-loop": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/attachment": "3.1.3",
+    "@qilin-agent/compaction-basic": "3.1.3",
+    "@qilin-agent/compaction": "3.1.3",
+    "@qilin-agent/llm-deepseek": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/session-projection": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/token-meter": "3.1.3"
+  },
+  "dependencies": {
+    "@qilin-agent/util-values": "3.1.3"
+  }
 }