@steerable/agent-shell 0.6.60 → 0.6.62

package/dist/image-attachment.js

@@ -3,9 +3,10 @@
  * actually see, replacing the old behavior of dropping only the file *path*
  * into the prompt text.
  *
- * Decoding / downscaling runs only when an {@link ImageDecoder} is supplied;
- * otherwise the original bytes pass through under the encoded cap. These caps
- * are enforced before the image ever reaches the model:
+ * PNG and JPEG are decoded by the built-in raster decoder so the host can
+ * crop and downscale without Electron. Pass `null` to skip that decoder and
+ * forward the original bytes under the encoded cap. These caps are enforced
+ * before the image ever reaches the model:
  *
  *   - source bytes  (`IMAGE_MAX_SOURCE_BYTES`) — refuse to read huge files;
  *   - long-edge px  (`IMAGE_MAX_DIMENSION`)    — downscale so the provider's
@@ -19,6 +20,7 @@
  */
 import { readFileSync, statSync } from 'fs';
 import { basename, extname } from 'path';
+import { builtinRasterSupports, createRasterImageDecoder } from './raster-image.js';
 /** Refuse to read source files larger than this (10 MB). */
 export const IMAGE_MAX_SOURCE_BYTES = 10 * 1024 * 1024;
 /** Downscale so the long edge is at most this many px (matches common vision limits). */
@@ -29,6 +31,20 @@ const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bm
 export function isImagePath(path) {
     return IMAGE_EXTENSIONS.has(extname(path).toLowerCase());
 }
+let builtinDecoder = null;
+/**
+ * `undefined` selects the built-in PNG/JPEG decoder. `null` keeps the
+ * original-bytes path. An explicit decoder (tests, or a host native image)
+ * replaces the built-in one.
+ */
+function resolveImageDecoder(filePath, decoder) {
+    if (decoder !== undefined)
+        return decoder;
+    if (!builtinRasterSupports(filePath))
+        return null;
+    builtinDecoder ??= createRasterImageDecoder();
+    return builtinDecoder;
+}
 /**
  * Validate the wire value (`metadata.images` from the renderer) into a clean
  * input list. Anything that isn't an object with a non-empty string `path`
@@ -73,7 +89,7 @@ export function computeTargetSize(width, height, maxDimension = IMAGE_MAX_DIMENS
  * tool result. `_image` is consumed by the CoreLoop as an image content part;
  * it is not a path or model-visible base64 string.
  */
-export function processViewImage(input, decoder = null) {
+export function processViewImage(input, decoder) {
     if (!isImagePath(input.path)) {
         return {
             success: false,
@@ -103,10 +119,17 @@ export function processViewImage(input, decoder = null) {
             needsFollowup: true,
         };
     }
-    if (!decoder) {
+    const resolved = resolveImageDecoder(input.path, decoder);
+    if (!resolved) {
         return viewImageWithoutDecoder(input, sourceBytes, maxEdge);
     }
-    let rendered = decoder.createFromPath(input.path);
+    let rendered;
+    try {
+        rendered = resolved.createFromPath(input.path);
+    }
+    catch {
+        return { success: false, error: '不是可识别的图片', needsFollowup: true };
+    }
     if (rendered.isEmpty()) {
         return { success: false, error: '不是可识别的图片', needsFollowup: true };
     }
@@ -264,7 +287,7 @@ function formatMb(bytes) {
  * Process a batch of image attachments. Synchronous: decoder decode /
  * resize / encode are all synchronous, and the byte check uses `statSync`.
  */
-export function processImageAttachments(files, decoder = null) {
+export function processImageAttachments(files, decoder) {
     const images = [];
     const notes = [];
     for (const file of files) {
@@ -282,7 +305,8 @@ export function processImageAttachments(files, decoder = null) {
             notes.push(`- ${label}：源文件 ${formatMb(sourceBytes)}MB 超过 ${formatMb(IMAGE_MAX_SOURCE_BYTES)}MB 上限，未附加`);
             continue;
         }
-        if (!decoder) {
+        const fileDecoder = resolveImageDecoder(file.path, decoder);
+        if (!fileDecoder) {
             // The bytes are already an image the provider can read; pass them
             // through when they fit the encoded cap.
             if (sourceBytes > IMAGE_MAX_ENCODED_BYTES) {
@@ -302,7 +326,14 @@ export function processImageAttachments(files, decoder = null) {
             notes.push(`- ${label}（原图）`);
             continue;
         }
-        const image = decoder.createFromPath(file.path);
+        let image;
+        try {
+            image = fileDecoder.createFromPath(file.path);
+        }
+        catch {
+            notes.push(`- ${label}：不是可识别的图片，未附加`);
+            continue;
+        }
         if (image.isEmpty()) {
             notes.push(`- ${label}：不是可识别的图片，未附加`);
             continue;

package/dist/local-backend/history-edit.d.ts

@@ -0,0 +1,27 @@
+export interface StoredTurn {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    messageMetadata?: string | null;
+}
+export interface HistoryWrite {
+    role: StoredTurn['role'];
+    content: string;
+    messageMetadata: string | null;
+}
+/**
+ * Newest-first history. The newest two messages stay. Older ones become one summary,
+ * and the caller deletes from the oldest id (which removes the whole chat) before writing these back.
+ */
+export declare function compactHistory(messages: readonly StoredTurn[]): {
+    deleteFromId: string;
+    writes: HistoryWrite[];
+    compacted: number;
+} | null;
+/** Newest-first. Cut from the newest user message through the reply after it. */
+export declare function rewindFrom(messages: readonly StoredTurn[]): {
+    deleteFromId: string;
+    removed: number;
+} | null;
+/** Newest-first history copied in time order. */
+export declare function forkHistory(messages: readonly StoredTurn[]): HistoryWrite[];

package/dist/local-backend/history-edit.js

@@ -0,0 +1,46 @@
+/**
+ * Newest-first history. The newest two messages stay. Older ones become one summary,
+ * and the caller deletes from the oldest id (which removes the whole chat) before writing these back.
+ */
+export function compactHistory(messages) {
+    if (messages.length <= 2)
+        return null;
+    const kept = messages.slice(0, 2);
+    const older = messages.slice(2);
+    const oldest = older[older.length - 1];
+    if (!oldest)
+        return null;
+    const summary = older.slice().reverse().map((message) => {
+        const text = message.content.replace(/\s+/g, ' ').trim();
+        const clipped = text.length > 80 ? `${text.slice(0, 80)}…` : text;
+        return `${message.role}: ${clipped}`;
+    }).join('\n');
+    return {
+        deleteFromId: oldest.id,
+        compacted: older.length,
+        writes: [
+            { role: 'assistant', content: `已压缩 ${older.length} 条\n${summary}`, messageMetadata: null },
+            ...kept.slice().reverse().map((message) => ({
+                role: message.role,
+                content: message.content,
+                messageMetadata: message.messageMetadata ?? null,
+            })),
+        ],
+    };
+}
+/** Newest-first. Cut from the newest user message through the reply after it. */
+export function rewindFrom(messages) {
+    const index = messages.findIndex((message) => message.role === 'user');
+    const target = index >= 0 ? messages[index] : undefined;
+    if (!target)
+        return null;
+    return { deleteFromId: target.id, removed: index + 1 };
+}
+/** Newest-first history copied in time order. */
+export function forkHistory(messages) {
+    return messages.slice().reverse().map((message) => ({
+        role: message.role,
+        content: message.content,
+        messageMetadata: message.messageMetadata ?? null,
+    }));
+}

package/dist/local-backend/router.d.ts

@@ -192,6 +192,7 @@ export declare class LocalBackendRouter {
      * 用 parseSSEData 把 data 反序列化为 JSON 后用 type/content 字段路由。
      */
     private sseData;
+    private historyTurns;
     private toRecord;
     private safeJson;
     private notFound;

package/dist/local-backend/router.js

@@ -48,6 +48,7 @@ import { chatAttachmentsDirPath } from '../attachments.js';
 import { loadProjectRuleFiles } from '../project-rules.js';
 import { allocateProjectHome, ensureChatWorkspace, ensureProjectHome, expandUserPath, } from '../project-home.js';
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
+import { compactHistory, forkHistory, rewindFrom } from './history-edit.js';
 import { beginPackTurnObservers, collectPackExecWritableRoots, collectPackForcedSkillVars, collectPackWorldState, } from './pack-turn-hooks.js';
 import { matchPackBackendRoute } from './pack-backend-routes.js';
 import { invokePackHttpRoute } from '../host/http-routes.js';
@@ -870,6 +871,45 @@ export class LocalBackendRouter {
             await supervisor.cancelChat(streamId);
             return { status: 200, data: { success: true } };
         }
+        const compactMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/compact$/);
+        if (compactMatch && method === 'POST') {
+            const chatId = compactMatch[1];
+            const chat = await this.store.getChat(chatId);
+            if (!chat)
+                return { status: 404, data: { detail: 'chat not found' } };
+            const plan = compactHistory(await this.historyTurns(chatId));
+            if (!plan)
+                return { status: 200, data: { compacted: 0 } };
+            await this.store.deleteMessagesFrom(chatId, plan.deleteFromId);
+            for (const write of plan.writes) {
+                await this.store.addMessage(chatId, write.role, write.content, write.messageMetadata);
+            }
+            return { status: 200, data: { compacted: plan.compacted } };
+        }
+        const forkMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/fork$/);
+        if (forkMatch && method === 'POST') {
+            const chatId = forkMatch[1];
+            const chat = await this.store.getChat(chatId);
+            if (!chat)
+                return { status: 404, data: { detail: 'chat not found' } };
+            const created = await this.store.createChat(chat.title || '分叉', chat.agentId, chat.projectId);
+            for (const write of forkHistory(await this.historyTurns(chatId))) {
+                await this.store.addMessage(created.id, write.role, write.content, write.messageMetadata);
+            }
+            return { status: 200, data: { chatId: created.id } };
+        }
+        const rewindMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/rewind$/);
+        if (rewindMatch && method === 'POST') {
+            const chatId = rewindMatch[1];
+            const chat = await this.store.getChat(chatId);
+            if (!chat)
+                return { status: 404, data: { detail: 'chat not found' } };
+            const cut = rewindFrom(await this.historyTurns(chatId));
+            if (!cut)
+                return { status: 200, data: { removed: 0 } };
+            const removed = await this.store.deleteMessagesFrom(chatId, cut.deleteFromId);
+            return { status: 200, data: { removed } };
+        }
         if (method === 'GET' && pathname === '/api/v2/chat-agents') {
             const includeArchived = url.searchParams.get('include_archived') === 'true';
             const agents = await this.store.listChatAgents(includeArchived);
@@ -3407,6 +3447,7 @@ export class LocalBackendRouter {
                 sinceMs: turnStartedAtMs,
                 actions: executedActions,
                 projectRoot: workspaceRoot,
+                finalText: assistantText,
             });
         }
         catch (turnFilesErr) {
@@ -3556,6 +3597,15 @@ export class LocalBackendRouter {
     sseData(data) {
         return `data: ${JSON.stringify(data)}\n\n`;
     }
+    async historyTurns(chatId) {
+        const messages = await this.store.listMessages(chatId);
+        return messages.map((message) => ({
+            id: message.id,
+            role: message.role,
+            content: message.content,
+            messageMetadata: message.messageMetadata,
+        }));
+    }
     toRecord(body) {
         if (!body || typeof body !== 'object')
             return {};

package/dist/local-backend/skills/85-local-exec/SKILL.md

@@ -27,7 +27,7 @@ match: any
 - 命令可能改文件、装包、删数据时（destructive 类操作），**先**简单告诉用户你要执行什么，**再**发 tool_call；不要中间停手等用户确认（用户已经请求了）。
 - `local_exec_shell` 返回包含 `stdout` / `stderr` / `exitCode`。非 0 退出码视为失败：把 stderr 摘要给用户，并建议下一步。
 - 路径不存在 / 权限不足时，把 fs 错误原文告诉用户，**不要**反复重试同一个路径。
-- **交付文件要声明**：用户要的产出（表格、PPT、文档、报告、图片、导出包）写好后，在最终回复前调用 `present_files` 声明它们，脚本/命令生成的也一样。辅助脚本、临时文件、只为自查渲染效果导出的预览图、中间导出副本**不要**声明——它们会自动列在「已编辑文件」里。
+- **交付文件要声明**：用户要的产出（表格、幻灯片、文档、报告、图片、导出包）写好后，在最终回复前调用 `present_files`。每份独立交付文件都写 `purpose: "output"`；需要记录预览或中间文件时分别写 `purpose: "preview"` / `"intermediate"`，它们不会生成交付卡片。脚本、命令生成的文件也一样。最终回复用行内代码写出每份独立交付文件的完整路径。辅助脚本、临时文件、只为自查渲染效果导出的预览图和中间导出副本不要标为 output。
 
 
 - **超时 ≠ 失败，严禁原样重跑启动命令**：返回里出现 `timedOut: true` 时，只是 shell 等待被掐断——如果命令是启动 GUI / 长时间运行的程序（如 Qt 界面软件），该程序**很可能仍在运行**，用户可能正在里面操作。此时**不要**再次执行同一条启动命令（会把程序重复启动多次）。正确做法：先确认进程是否在运行（如 `Get-Process`）；确实需要长时间等待时传更大的 `timeout` 参数；启动 GUI 程序时优先用不阻塞的方式（PowerShell `Start-Process "app.exe"`），启动成功即视为完成，不要等它退出。

package/dist/local-backend/skills/86-proactive-coding/SKILL.md

@@ -47,5 +47,5 @@ match: any
 
 - **没跑过的代码不要说"运行结果如下"。** 只有看到 `local_run_snippet` 的真实返回（`exitCode: 0` + `stdout`）才能汇报结果；非 0 退出码就读 `stderr` 改代码重跑（最多迭代 2-3 次，还不行就如实说明卡点）。
 - 脚本里读写用户文件时，路径用用户提供的真实路径或项目内相对路径；不要编造路径。
-- 脚本产生的**交付物**（报表、转换后的文件）要落到用户能找到的地方（项目目录或用户指定路径），并在回复里给出完整路径，最终回复前用 `present_files` 声明——scratch 目录是临时区，不是交付位置。
+- 脚本产生的**交付物**（报表、转换后的文件）要落到用户能找到的地方（项目目录或用户指定路径），最终回复前用 `present_files` 以 `purpose: "output"` 声明，并在回复里用行内代码给出完整路径——scratch 目录是临时区，不是交付位置。
 - 代码保持简单直接：能 20 行解决就不要写 100 行；不要引入与任务无关的"工程化"。

package/dist/local-backend/turn-file-selection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 本轮哪些文件升成交付卡片。
+ *
+ * 证据优先级：生成流程结构化结果 > 最终回复引用 > present_files > 文件扫描。
+ * 启发式只纠正没有明确 purpose 的 present_files 和扫描结果；明确标为 output
+ * 的同名 PDF 与幻灯片会同时保留。
+ */
+export type ArtifactPurpose = 'output' | 'preview' | 'intermediate';
+export type DeliveryEvidenceSource = 'generation' | 'final-reference' | 'present-files';
+export interface DeliveryEvidence {
+    path: string;
+    source: DeliveryEvidenceSource;
+    /** present_files 的旧调用没有 purpose，此时才允许启发式纠错。 */
+    purpose?: ArtifactPurpose;
+}
+/**
+ * 选出本轮交付卡片的路径。结构化证据不会被文件名启发式覆盖。
+ */
+export declare function selectDeliverablePaths(files: readonly {
+    path: string;
+}[], evidence: readonly DeliveryEvidence[]): Set<string>;

package/dist/local-backend/turn-file-selection.js

@@ -0,0 +1,186 @@
+/**
+ * 本轮哪些文件升成交付卡片。
+ *
+ * 证据优先级：生成流程结构化结果 > 最终回复引用 > present_files > 文件扫描。
+ * 启发式只纠正没有明确 purpose 的 present_files 和扫描结果；明确标为 output
+ * 的同名 PDF 与幻灯片会同时保留。
+ */
+import path from 'node:path';
+const SOURCE_EXTENSIONS = new Set([
+    '.pptx', '.ppt', '.key', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+    '.docx', '.doc', '.pages',
+    '.xlsx', '.xls', '.xlsm', '.numbers',
+]);
+const PRESENTATION_EXTENSIONS = new Set([
+    '.pptx', '.ppt', '.key', // shell-neutral:allow — Office 幻灯片扩展名，不是产品品牌
+]);
+const IMAGE_OR_PDF_EXTENSIONS = new Set([
+    '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg',
+]);
+const RENDER_EXTENSIONS = new Set([
+    '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg',
+    '.html', '.htm', '.csv', '.tsv',
+    '.zip', '.tar', '.gz', '.7z',
+    '.mp4', '.mov', '.mp3', '.epub', '.rtf',
+]);
+const HELPER_EXTENSIONS = new Set([
+    '.mjs', '.js', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.sh', '.rb', '.go', '.rs',
+    '.java', '.css', '.json', '.yml', '.yaml', '.toml',
+]);
+const PREVIEW_NAME = /预览|截图|图像版|preview|screenshot|thumbnail/i;
+/** 没有办公文件时，自动升成卡片的渲染文件上限。再多就交给 present_files 点名。 */
+const AUTO_RENDER_MAX = 4;
+/**
+ * 选出本轮交付卡片的路径。结构化证据不会被文件名启发式覆盖。
+ */
+export function selectDeliverablePaths(files, evidence) {
+    const unique = [];
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.path))
+            continue;
+        seen.add(file.path);
+        unique.push(file);
+    }
+    const strongest = strongestEvidence(evidence, seen);
+    const explicitOutputs = new Set([...strongest.values()]
+        .filter((item) => item.purpose === 'output')
+        .map((item) => item.path));
+    const excluded = new Set([...strongest.values()]
+        .filter((item) => item.purpose === 'preview' || item.purpose === 'intermediate')
+        .map((item) => item.path));
+    const ambiguousReferences = new Set([...strongest.values()]
+        .filter((item) => item.purpose === undefined)
+        .map((item) => item.path));
+    const sources = unique.filter((file) => isSource(file.path)).map((file) => file.path);
+    const availableSources = sources.filter((item) => !excluded.has(item));
+    const outsideSources = availableSources.filter((item) => !inAgentScratch(item));
+    const sourcePool = outsideSources.length > 0 ? outsideSources : availableSources;
+    let inferred;
+    if (ambiguousReferences.size > 0) {
+        inferred = [...ambiguousReferences].filter((item) => !excluded.has(item) && !isShadow(item, availableSources));
+        const parents = availableSources.filter((source) => [...ambiguousReferences].some((item) => isShadowOf(item, source)));
+        const outsideParents = parents.filter((item) => !inAgentScratch(item));
+        for (const source of outsideParents.length > 0 ? outsideParents : parents) {
+            if (!inferred.includes(source))
+                inferred.push(source);
+        }
+        // 点名的全是脚本或预览、本轮又只有一份办公文件：卡片给那一份，不给脚本。
+        const onlySource = sourcePool.length === 1 ? sourcePool[0] : undefined;
+        if (onlySource &&
+            !inferred.some((item) => isSource(item)) &&
+            [...ambiguousReferences].every((item) => isHelper(item) || isShadow(item, availableSources))) {
+            inferred = [onlySource];
+        }
+        if (inferred.some((item) => isSource(item))) {
+            inferred = inferred.filter((item) => !isHelper(item));
+        }
+        if (inferred.length === 0) {
+            inferred = [...ambiguousReferences].filter((item) => !excluded.has(item));
+        }
+    }
+    else if (explicitOutputs.size > 0) {
+        inferred = [];
+    }
+    else if (sourcePool.length > 0) {
+        inferred = [...sourcePool];
+    }
+    else {
+        inferred = autoRenders(unique.filter((file) => !excluded.has(file.path)));
+    }
+    return new Set([...explicitOutputs, ...inferred]);
+}
+function strongestEvidence(evidence, knownPaths) {
+    const strongest = new Map();
+    for (const item of evidence) {
+        if (!knownPaths.has(item.path))
+            continue;
+        const previous = strongest.get(item.path);
+        if (!previous ||
+            evidenceRank(item.source) > evidenceRank(previous.source) ||
+            (item.source === previous.source &&
+                item.purpose !== undefined &&
+                previous.purpose === undefined)) {
+            strongest.set(item.path, item);
+        }
+    }
+    return strongest;
+}
+function evidenceRank(source) {
+    switch (source) {
+        case 'generation':
+            return 3;
+        case 'final-reference':
+            return 2;
+        case 'present-files':
+            return 1;
+    }
+}
+function autoRenders(files) {
+    const renders = files.filter((file) => isRender(file.path) && !inAgentScratch(file.path));
+    const plain = renders.filter((file) => !previewName(file.path));
+    const pool = plain.length > 0 ? plain : renders;
+    if (pool.length === 0 || pool.length > AUTO_RENDER_MAX)
+        return [];
+    return pool.map((file) => file.path);
+}
+function isShadow(filePath, sources) {
+    return sources.some((source) => isShadowOf(filePath, source));
+}
+/** 预览 PDF / 截图：和幻灯片同干名，或文件名像预览且跟办公文件在同一目录。 */
+function isShadowOf(filePath, sourcePath) {
+    if (filePath === sourcePath || !isSource(sourcePath) || !isRender(filePath))
+        return false;
+    if (stemsMatch(filePath, sourcePath) &&
+        isPresentation(sourcePath) &&
+        isImageOrPdf(filePath)) {
+        return true;
+    }
+    return previewName(filePath) && sameDir(filePath, sourcePath);
+}
+function isSource(filePath) {
+    return SOURCE_EXTENSIONS.has(extensionOf(filePath));
+}
+function isPresentation(filePath) {
+    return PRESENTATION_EXTENSIONS.has(extensionOf(filePath));
+}
+function isImageOrPdf(filePath) {
+    return IMAGE_OR_PDF_EXTENSIONS.has(extensionOf(filePath));
+}
+function isRender(filePath) {
+    return RENDER_EXTENSIONS.has(extensionOf(filePath));
+}
+function isHelper(filePath) {
+    return HELPER_EXTENSIONS.has(extensionOf(filePath));
+}
+function previewName(filePath) {
+    return PREVIEW_NAME.test(path.basename(filePath));
+}
+function extensionOf(filePath) {
+    return path.extname(filePath).toLowerCase();
+}
+function stemsMatch(left, right) {
+    const a = stemKey(left);
+    const b = stemKey(right);
+    return a.length > 0 && a === b;
+}
+function stemKey(filePath) {
+    const base = path.basename(filePath);
+    const ext = path.extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    return stem
+        .replace(/预览|截图|图像版/g, '')
+        .replace(/preview|screenshot|thumbnail/gi, '')
+        .replace(/[\s._\-—–()（）【】[\]]+/g, '')
+        .toLowerCase()
+        .normalize('NFC');
+}
+function sameDir(left, right) {
+    return directoryOf(left) === directoryOf(right);
+}
+function directoryOf(filePath) {
+    return path.dirname(filePath).replace(/\\/g, '/').replace(/\/+$/, '').normalize('NFC');
+}
+function inAgentScratch(filePath) {
+    return /(?:^|[/\\])(?:review_work|scripts)(?:[/\\]|$)/i.test(filePath);
+}

package/dist/local-backend/turn-files.d.ts

@@ -1,7 +1,7 @@
 /**
  * 回合产物文件收集（「本轮写了哪些文件」列表）。
  *
- * 四个来源取并集：
+ * 六个来源取并集：
  *
  *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
  *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
@@ -16,6 +16,10 @@
  *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
  *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
  *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *  5. 生成工具结果的结构化 artifacts：每项明确给出 path 与
+ *     output / preview / intermediate purpose，是交付选择的最高优先级。
+ *  6. 最终回复里的文件引用：Codex file citation、Markdown 本地链接和
+ *     行内代码路径，作为模型最终确认的交付文件。
  *
  * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
  * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
@@ -29,6 +33,7 @@
  * 扫描是有界 best-effort：忽略依赖/构建缓存目录，深度与遍历条目数有硬顶，
  * 超限直接截断返回已收集部分——产物列表是展示面，永远不该拖垮回合收尾。
  */
+import { type DeliveryEvidenceSource } from './turn-file-selection.js';
 export interface TurnFile {
     /** 绝对路径（点击打开直接用）。 */
     path: string;
@@ -40,8 +45,12 @@ export interface TurnFile {
     additions?: number;
     /** 删除行数（展示用，如 -0）。 */
     deletions?: number;
-    /** 类别：deliverable = present_files 声明的最终交付文件；intermediate = 其余本轮写过的文件。 */
+    /** 类别：deliverable = 本轮交付卡片；intermediate = 其余本轮写过的文件。 */
     category?: 'deliverable' | 'intermediate';
+    /** 新回合由后端完成分层证据选择；前端不再二次猜测。 */
+    selection?: 'resolved';
+    /** 成为交付卡片所依据的最高优先级证据。 */
+    deliverySource?: DeliveryEvidenceSource | 'inference';
     /** present_files 给出的一行说明（交付卡片副标题）。 */
     description?: string;
 }
@@ -56,7 +65,10 @@ export interface TurnFileAction {
 export declare const DELIVERABLE_EXTENSIONS: Set<string>;
 /** 是否为临时文件 / 办公软件锁定文件（如 ~$ 开头的文件名），产物列表中一律排除。 */
 export declare function isIgnoredFileName(name: string): boolean;
-/** 判定文件是最终交付文件还是中间修改文件。 */
+/**
+ * 按扩展名做的单文件猜测。回合级取舍在 `selectDeliverablePaths`：
+ * 同名预览不会因为扩展名就和正文一起升成卡片。
+ */
 export declare function classifyFileCategory(filePath: string): 'deliverable' | 'intermediate';
 /** 从统一 diff 文本中统计增删行数。 */
 export declare function parseDiffStats(diffText: string): {
@@ -74,4 +86,6 @@ export declare function collectTurnFiles(options: {
     actions?: readonly TurnFileAction[];
     projectRoot?: string | null;
     homeDir?: string;
+    /** 完整助手回复；其中明确的本地文件链接或行内代码路径属于最终引用。 */
+    finalText?: string;
 }): Promise<TurnFile[]>;

package/dist/local-backend/turn-files.js

@@ -1,7 +1,7 @@
 /**
  * 回合产物文件收集（「本轮写了哪些文件」列表）。
  *
- * 四个来源取并集：
+ * 六个来源取并集：
  *
  *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
  *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
@@ -16,6 +16,10 @@
  *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
  *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
  *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *  5. 生成工具结果的结构化 artifacts：每项明确给出 path 与
+ *     output / preview / intermediate purpose，是交付选择的最高优先级。
+ *  6. 最终回复里的文件引用：Codex file citation、Markdown 本地链接和
+ *     行内代码路径，作为模型最终确认的交付文件。
  *
  * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
  * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
@@ -32,7 +36,9 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { PRESENT_FILES_TOOL_NAME, readPresentedArgs, } from '../present-files.js';
+import { fileURLToPath } from 'node:url';
+import { PRESENT_FILES_TOOL_NAME, readPresentedArgs, resolvePresentedPath, } from '../present-files.js';
+import { selectDeliverablePaths, } from './turn-file-selection.js';
 /** 这些目录要么体量巨大（node_modules/target），要么是框架内部状态（.steerable），扫了只有噪音。 */
 const IGNORED_DIR_NAMES = new Set([
     'node_modules',
@@ -81,7 +87,10 @@ export function isIgnoredFileName(name) {
         return true;
     return false;
 }
-/** 判定文件是最终交付文件还是中间修改文件。 */
+/**
+ * 按扩展名做的单文件猜测。回合级取舍在 `selectDeliverablePaths`：
+ * 同名预览不会因为扩展名就和正文一起升成卡片。
+ */
 export function classifyFileCategory(filePath) {
     const normalized = filePath.replace(/\\/g, '/');
     const ext = path.extname(normalized).toLowerCase();
@@ -161,21 +170,55 @@ export async function collectTurnFiles(options) {
         await scanShallow(dir, sinceMs, byPath);
     }
     // present_files 声明的文件：本轮可能没动过（交付已有文件），不受时间水位线
-    // 约束，只要求仍是普通文件。
-    const presented = new Map();
+    // 约束，只要求仍是普通文件。路径按 realpath + NFC 并到扫描结果上，避免
+    // macOS 文件名归一化或 /var 与 /private/var 把同一文件收成两条。
+    const presentedByKey = new Map();
     for (const action of options.actions ?? []) {
         if (action.tool !== PRESENT_FILES_TOOL_NAME || action.success === false)
             continue;
         for (const file of readPresentedArgs(action.arguments, projectRoot, homeDir)) {
-            presented.set(file.path, file);
+            const key = await canonicalFileKey(file.path);
+            const prev = presentedByKey.get(key);
+            if (!prev || (!prev.description && file.description))
+                presentedByKey.set(key, file);
         }
     }
-    for (const file of presented.values()) {
-        if (byPath.has(file.path))
+    for (const [key, file] of presentedByKey) {
+        if (byPath.has(key))
             continue;
         const stat = await statPresentedFile(file.path);
         if (stat)
-            byPath.set(file.path, stat);
+            byPath.set(key, stat);
+    }
+    // 生成工具可在成功结果的 artifacts 数组里直接声明 path + purpose。
+    // 这是最高优先级来源，不用文件名猜主文件与预览文件。
+    const generatedByKey = new Map();
+    for (const action of options.actions ?? []) {
+        if (action.success === false)
+            continue;
+        for (const artifact of readStructuredArtifacts(action.result, projectRoot, homeDir)) {
+            const key = await canonicalFileKey(artifact.path);
+            generatedByKey.set(key, artifact);
+            if (byPath.has(key))
+                continue;
+            const stat = await statPresentedFile(artifact.path);
+            if (stat)
+                byPath.set(key, stat);
+        }
+    }
+    // 最终回复中的 Codex file citation、Markdown 本地链接和行内代码路径是次高
+    // 优先级。它们也可以引用本轮没改过但交付给用户的已有文件。
+    const finalReferencesByKey = new Map();
+    for (const reference of readFinalFileReferences(options.finalText ?? '', projectRoot, homeDir)) {
+        const key = await canonicalFileKey(reference.path);
+        const previous = finalReferencesByKey.get(key);
+        if (!previous || reference.explicitOutput)
+            finalReferencesByKey.set(key, reference);
+        if (byPath.has(key))
+            continue;
+        const stat = await statPresentedFile(reference.path);
+        if (stat)
+            byPath.set(key, stat);
     }
     // 从 actions 中提取增删行数统计（local_edit_file 的 diff 或 local_write_file 的 content）
     const statsByPath = new Map();
@@ -211,23 +254,58 @@ export async function collectTurnFiles(options) {
             }
         }
     }
-    const enriched = [];
-    for (const file of byPath.values()) {
-        const base = path.basename(file.path);
-        if (isIgnoredFileName(base))
+    const visible = [];
+    for (const [key, file] of byPath) {
+        if (isIgnoredFileName(path.basename(file.path)))
             continue;
+        visible.push({ key, file });
+    }
+    const evidence = [];
+    for (const { key, file } of visible) {
+        const generated = generatedByKey.get(key);
+        if (generated) {
+            evidence.push({
+                path: file.path,
+                source: 'generation',
+                purpose: generated.purpose,
+            });
+        }
+        const finalReference = finalReferencesByKey.get(key);
+        if (finalReference) {
+            evidence.push({
+                path: file.path,
+                source: 'final-reference',
+                ...(finalReference.explicitOutput ? { purpose: 'output' } : {}),
+            });
+        }
+        const presented = presentedByKey.get(key);
+        if (presented) {
+            evidence.push({
+                path: file.path,
+                source: 'present-files',
+                ...(presented.purpose ? { purpose: presented.purpose } : {}),
+            });
+        }
+    }
+    const deliverablePaths = selectDeliverablePaths(visible.map(({ file }) => file), evidence);
+    const enriched = [];
+    for (const { key, file } of visible) {
         const stats = statsByPath.get(file.path);
-        const declared = presented.get(file.path);
-        // 本轮有声明时以声明为准；没有声明（旧模型、未调用）才退回扩展名规则。
-        const category = presented.size > 0
-            ? declared
-                ? 'deliverable'
-                : 'intermediate'
-            : classifyFileCategory(file.path);
+        const declared = presentedByKey.get(key);
+        const generated = generatedByKey.get(key);
+        const category = deliverablePaths.has(file.path) ? 'deliverable' : 'intermediate';
+        const deliverySource = category === 'deliverable'
+            ? selectedDeliverySource(key, generatedByKey, finalReferencesByKey, presentedByKey)
+            : undefined;
         enriched.push({
             ...file,
             category,
-            ...(declared?.description ? { description: declared.description } : {}),
+            selection: 'resolved',
+            ...(deliverySource ? { deliverySource } : {}),
+            // 预览被拿掉之后，不把它的说明贴到推断出的可编辑文件上。
+            ...(category === 'deliverable' && (generated?.description || declared?.description)
+                ? { description: generated?.description ?? declared?.description }
+                : {}),
             ...(stats ? { additions: stats.additions, deletions: stats.deletions } : {}),
         });
     }
@@ -268,9 +346,23 @@ async function walk(dir, sinceMs, depth, state, out) {
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
+    }
+}
+/** 同一文件的扫描路径和模型声明路径收成一个键。 */
+async function canonicalFileKey(filePath) {
+    try {
+        return (await fs.realpath(filePath)).normalize('NFC');
+    }
+    catch {
+        return path.normalize(filePath).normalize('NFC');
     }
 }
+async function putTurnFile(out, file) {
+    const key = await canonicalFileKey(file.path);
+    if (!out.has(key))
+        out.set(key, file);
+}
 /** stat 一个文件，命中「本轮触碰过」则返回 TurnFile，否则 null。 */
 async function statTurnFile(full, sinceMs) {
     let stat;
@@ -304,6 +396,125 @@ async function statPresentedFile(full) {
         return null;
     return { path: full, kind: 'modified', size: stat.size };
 }
+/**
+ * 生成工具结果的标准产物字段：
+ * `{ artifacts: [{ path, purpose, description? }] }`，sidecar 包装结果也可放在
+ * `data.artifacts`。purpose 必填，避免把没有语义的路径数组冒充可靠证据。
+ */
+function readStructuredArtifacts(result, projectRoot, homeDir) {
+    if (!result || typeof result !== 'object')
+        return [];
+    const record = result;
+    const data = record.data && typeof record.data === 'object'
+        ? record.data
+        : null;
+    const raw = Array.isArray(record.artifacts)
+        ? record.artifacts
+        : Array.isArray(data?.artifacts)
+            ? data.artifacts
+            : [];
+    const artifacts = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const artifact = item;
+        if (typeof artifact.path !== 'string' || !isArtifactPurpose(artifact.purpose))
+            continue;
+        const resolved = resolvePresentedPath(artifact.path, projectRoot, homeDir);
+        if (!resolved)
+            continue;
+        const description = typeof artifact.description === 'string' ? artifact.description.trim() : '';
+        artifacts.push({
+            path: resolved,
+            purpose: artifact.purpose,
+            ...(description ? { description } : {}),
+        });
+    }
+    return artifacts;
+}
+function isArtifactPurpose(value) {
+    return value === 'output' || value === 'preview' || value === 'intermediate';
+}
+function readFinalFileReferences(text, projectRoot, homeDir) {
+    if (!text)
+        return [];
+    const rawPaths = new Map();
+    for (const match of text.matchAll(/:codex-file-citation\{([^}]*)\}/g)) {
+        const attributes = match[1] ?? '';
+        const purpose = directiveAttribute(attributes, 'purpose');
+        const filePath = directiveAttribute(attributes, 'path');
+        if (purpose === 'output' && filePath)
+            rawPaths.set(filePath, true);
+    }
+    for (const match of text.matchAll(/!?\[[^\]]*]\((?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"']*["'])?\)/g)) {
+        const target = match[1] ?? match[2];
+        if (target && !rawPaths.has(target))
+            rawPaths.set(target, false);
+    }
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        const candidate = match[1]?.trim();
+        if (candidate && looksLikeLocalFileReference(candidate) && !rawPaths.has(candidate)) {
+            rawPaths.set(candidate, false);
+        }
+    }
+    const resolved = new Map();
+    for (const [raw, explicitOutput] of rawPaths) {
+        const decoded = decodeFileReference(raw);
+        if (!decoded || /^(?:https?|data):/i.test(decoded))
+            continue;
+        const filePath = resolvePresentedPath(decoded, projectRoot, homeDir);
+        if (!filePath)
+            continue;
+        const previous = resolved.get(filePath);
+        if (!previous || explicitOutput) {
+            resolved.set(filePath, { path: filePath, explicitOutput });
+        }
+    }
+    return [...resolved.values()];
+}
+function directiveAttribute(attributes, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = new RegExp(`(?:^|\\s)${escaped}=(?:"([^"]*)"|'([^']*)'|([^\\s}]+))`).exec(attributes);
+    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+function decodeFileReference(raw) {
+    let value = raw.trim();
+    try {
+        value = decodeURIComponent(value);
+    }
+    catch {
+        // 非法百分号不是可靠的文件引用。
+        return null;
+    }
+    if (value.startsWith('file://')) {
+        try {
+            return fileURLToPath(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return value;
+}
+function looksLikeLocalFileReference(value) {
+    if (/^(?:~\/|\/|[A-Za-z]:[\\/])/.test(value))
+        return path.extname(value).length > 1;
+    return (!/^[a-z][a-z0-9+.-]*:/i.test(value) &&
+        /(?:^|[/\\])[^/\\]+\.[A-Za-z0-9]{1,10}$/.test(value));
+}
+function selectedDeliverySource(key, generatedByKey, finalReferencesByKey, presentedByKey) {
+    const generated = generatedByKey.get(key);
+    if (generated?.purpose === 'output')
+        return 'generation';
+    if (generated?.purpose === 'preview' || generated?.purpose === 'intermediate') {
+        return 'inference';
+    }
+    if (finalReferencesByKey.has(key))
+        return 'final-reference';
+    if (presentedByKey.has(key))
+        return 'present-files';
+    return 'inference';
+}
 /** local_edit_file 的 diff：直连结果在顶层，经 sidecar 回流的结果折进 `data`。 */
 function editDiffOf(result) {
     if (!result || typeof result !== 'object')
@@ -340,11 +551,11 @@ async function collectWriteToolPath(action, sinceMs, projectRoot, out) {
         : projectRoot
             ? path.resolve(projectRoot, raw)
             : null;
-    if (!full || out.has(full))
+    if (!full || out.has(await canonicalFileKey(full)))
         return;
     const file = await statTurnFile(full, sinceMs);
     if (file)
-        out.set(full, file);
+        await putTurnFile(out, file);
 }
 /**
  * exec 行动的实际工作目录（与 tool-router / local-executor 的解析规则对齐）：
@@ -394,11 +605,11 @@ async function scanShallow(dir, sinceMs, out) {
         if (entry.isSymbolicLink() || !entry.isFile())
             continue;
         const full = path.join(dir, entry.name);
-        if (out.has(full))
+        if (out.has(await canonicalFileKey(full)))
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
     }
 }
 /**
@@ -433,10 +644,10 @@ async function collectPathLiterals(action, sinceMs, homeDir, out) {
         }
     }
     for (const full of candidates) {
-        if (out.has(full))
+        if (out.has(await canonicalFileKey(full)))
             continue;
         const file = await statTurnFile(full, sinceMs);
         if (file)
-            out.set(full, file);
+            await putTurnFile(out, file);
     }
 }

package/dist/present-files.d.ts

@@ -6,6 +6,7 @@
  * 导出副本，所以由模型显式声明。工具只 stat 元数据、不读内容，也不复制
  * 文件——用户打开的是源文件当前版本。
  */
+import type { ArtifactPurpose } from './local-backend/turn-file-selection.js';
 export declare const PRESENT_FILES_TOOL_NAME = "present_files";
 export declare const PRESENT_FILES_SCHEMA: {
     name: string;
@@ -30,6 +31,11 @@ export declare const PRESENT_FILES_SCHEMA: {
                             type: string;
                             description: string;
                         };
+                        purpose: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
                     };
                     required: string[];
                     additionalProperties: boolean;
@@ -43,6 +49,7 @@ export declare const PRESENT_FILES_SCHEMA: {
 export interface PresentedFile {
     path: string;
     description?: string;
+    purpose?: ArtifactPurpose;
 }
 /**
  * 把参数里的路径解析成绝对路径：展开 `~/`，相对路径按项目根解析；

package/dist/present-files.js

@@ -18,8 +18,9 @@ export const PRESENT_FILES_SCHEMA = {
         'When a file you created or updated is an output the user asked to receive ' +
         '(spreadsheet, slide deck, document, report, image, exported archive), call this after writing it ' +
         'and before your final reply, including files produced by scripts or commands. ' +
-        'Do not present helper scripts, scratch files, render previews made only to check your work, ' +
-        'or intermediate exports. Files you write but do not present are still listed to the user as edited files.',
+        'Set purpose="output" for every independent deliverable. If you include a preview or intermediate ' +
+        'file for context, label it purpose="preview" or purpose="intermediate"; those files stay in the ' +
+        'edited-files list. Do not label helper scripts or layout-check screenshots as outputs.',
     mode: 'read',
     inputSchema: {
         type: 'object',
@@ -40,6 +41,11 @@ export const PRESENT_FILES_SCHEMA = {
                             type: 'string',
                             description: 'Optional one-line summary shown on the file card.',
                         },
+                        purpose: {
+                            type: 'string',
+                            enum: ['output', 'preview', 'intermediate'],
+                            description: 'Use output for an independent final deliverable; preview/intermediate never creates a deliverable card.',
+                        },
                     },
                     required: ['path'],
                     additionalProperties: false,
@@ -83,7 +89,16 @@ export function readPresentedArgs(args, projectRoot, homeDir) {
         if (!resolved)
             continue;
         const description = typeof record.description === 'string' ? record.description.trim() : '';
-        out.push({ path: resolved, ...(description ? { description } : {}) });
+        const purpose = record.purpose === 'output' ||
+            record.purpose === 'preview' ||
+            record.purpose === 'intermediate'
+            ? record.purpose
+            : undefined;
+        out.push({
+            path: resolved,
+            ...(description ? { description } : {}),
+            ...(purpose ? { purpose } : {}),
+        });
     }
     return out;
 }

package/dist/raster-image.d.ts

@@ -0,0 +1,8 @@
+import type { ImageDecoder } from './image-attachment.js';
+/** True when the built-in decoder can read this path's extension. */
+export declare function builtinRasterSupports(filePath: string): boolean;
+/**
+ * Decode a local PNG or JPEG into a crop/resize/encode surface.
+ * Unreadable or unsupported files yield an empty image.
+ */
+export declare function createRasterImageDecoder(): ImageDecoder;

package/dist/raster-image.js

@@ -0,0 +1,152 @@
+/**
+ * PNG/JPEG decode, crop, resize, and re-encode for the Node host.
+ *
+ * `view_image` used to require an injected {@link ImageDecoder} (Electron
+ * `nativeImage`). The headless host has none, so any image larger than
+ * `maxEdge` failed with "当前环境不能缩放". This decoder is the default.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+const require = createRequire(import.meta.url);
+const { PNG } = require('pngjs');
+const jpeg = require('jpeg-js');
+const RASTER_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
+/** True when the built-in decoder can read this path's extension. */
+export function builtinRasterSupports(filePath) {
+    return RASTER_EXTENSIONS.has(extname(filePath).toLowerCase());
+}
+/**
+ * Decode a local PNG or JPEG into a crop/resize/encode surface.
+ * Unreadable or unsupported files yield an empty image.
+ */
+export function createRasterImageDecoder() {
+    return {
+        createFromPath(filePath) {
+            const decoded = decodeRasterFile(filePath);
+            if (!decoded)
+                return EMPTY_IMAGE;
+            return new RasterImage(decoded.width, decoded.height, decoded.rgba);
+        },
+    };
+}
+function decodeRasterFile(filePath) {
+    if (!builtinRasterSupports(filePath))
+        return null;
+    let bytes;
+    try {
+        bytes = readFileSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const ext = extname(filePath).toLowerCase();
+        if (ext === '.png') {
+            const png = PNG.sync.read(bytes);
+            return { width: png.width, height: png.height, rgba: Buffer.from(png.data) };
+        }
+        const decoded = jpeg.decode(bytes, { useTArray: true, formatAsRGBA: true });
+        if (decoded.width < 1 || decoded.height < 1)
+            return null;
+        return {
+            width: decoded.width,
+            height: decoded.height,
+            rgba: Buffer.from(decoded.data),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+class RasterImage {
+    width;
+    height;
+    rgba;
+    constructor(width, height, rgba) {
+        this.width = width;
+        this.height = height;
+        this.rgba = rgba;
+    }
+    isEmpty() {
+        return this.width < 1 || this.height < 1 || this.rgba.length < this.width * this.height * 4;
+    }
+    getSize() {
+        return { width: this.width, height: this.height };
+    }
+    crop(rect) {
+        return new RasterImage(rect.width, rect.height, cropRgba(this.rgba, this.width, rect.x, rect.y, rect.width, rect.height));
+    }
+    resize(options) {
+        const width = options.width ?? this.width;
+        const height = options.height ?? this.height;
+        return new RasterImage(width, height, resizeRgba(this.rgba, this.width, this.height, width, height));
+    }
+    toPNG() {
+        const png = new PNG({ width: this.width, height: this.height });
+        this.rgba.copy(png.data);
+        return PNG.sync.write(png);
+    }
+    toJPEG(quality) {
+        const encoded = jpeg.encode({ data: this.rgba, width: this.width, height: this.height }, quality);
+        return Buffer.from(encoded.data);
+    }
+}
+const EMPTY_IMAGE = {
+    isEmpty: () => true,
+    getSize: () => ({ width: 0, height: 0 }),
+    crop: () => EMPTY_IMAGE,
+    resize: () => EMPTY_IMAGE,
+    toPNG: () => Buffer.alloc(0),
+    toJPEG: () => Buffer.alloc(0),
+};
+function cropRgba(src, srcWidth, x, y, width, height) {
+    const dst = Buffer.alloc(width * height * 4);
+    for (let row = 0; row < height; row++) {
+        const srcStart = ((y + row) * srcWidth + x) * 4;
+        src.copy(dst, row * width * 4, srcStart, srcStart + width * 4);
+    }
+    return dst;
+}
+/**
+ * Area-average downscale. Each output pixel is the mean of the source
+ * rectangle it covers, so a long screenshot can be sent under `maxEdge`
+ * without aliasing into a single row of samples.
+ */
+function resizeRgba(src, srcWidth, srcHeight, dstWidth, dstHeight) {
+    if (dstWidth === srcWidth && dstHeight === srcHeight)
+        return Buffer.from(src);
+    const dst = Buffer.alloc(Math.max(0, dstWidth * dstHeight * 4));
+    if (dstWidth < 1 || dstHeight < 1)
+        return dst;
+    for (let y = 0; y < dstHeight; y++) {
+        const y0 = Math.floor((y * srcHeight) / dstHeight);
+        const y1 = Math.min(srcHeight, Math.max(y0 + 1, Math.ceil(((y + 1) * srcHeight) / dstHeight)));
+        for (let x = 0; x < dstWidth; x++) {
+            const x0 = Math.floor((x * srcWidth) / dstWidth);
+            const x1 = Math.min(srcWidth, Math.max(x0 + 1, Math.ceil(((x + 1) * srcWidth) / dstWidth)));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            let count = 0;
+            for (let sy = y0; sy < y1; sy++) {
+                const row = sy * srcWidth;
+                for (let sx = x0; sx < x1; sx++) {
+                    const i = (row + sx) * 4;
+                    r += src[i];
+                    g += src[i + 1];
+                    b += src[i + 2];
+                    a += src[i + 3];
+                    count += 1;
+                }
+            }
+            const o = (y * dstWidth + x) * 4;
+            dst[o] = Math.round(r / count);
+            dst[o + 1] = Math.round(g / count);
+            dst[o + 2] = Math.round(b / count);
+            dst[o + 3] = Math.round(a / count);
+        }
+    }
+    return dst;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.60",
+  "version": "0.6.62",
   "description": "Steerable framework — product-neutral Node HostRuntime and headless HTTP server shared by Tauri desktop and browser deployments; scenario packs extend it through @steerable/pack-sdk.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -50,10 +50,12 @@
     "conf": "10.2.0",
     "dotenv": "^17.4.2",
     "he": "^1.2.0",
+    "jpeg-js": "^0.4.4",
     "node-pty": "^1.1.0",
-    "@steerable/agent-harness": "0.6.60",
-    "@steerable/agent-protocol": "0.6.60",
-    "@steerable/pack-sdk": "0.6.60"
+    "pngjs": "^7.0.0",
+    "@steerable/agent-harness": "0.6.62",
+    "@steerable/agent-protocol": "0.6.62",
+    "@steerable/pack-sdk": "0.6.62"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",