Skip to content

A local plugin for image-heavy chats in Codex, Claude Code and other agents: earlier images stop going out with every message, and the model fetches the one it needs by its ID, also after compaction.

feat(spike): 阶段 0 的 T0–T3 与请求大小校准

chipfighterc5a887117427
diff --git a/docs/tasks.md b/docs/tasks.md
index 469fbc6..21532fe 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -12,26 +12,26 @@
## 任务
-- [ ] **T0 准备**
+- [x] **T0 准备**(证据:`spike/package.json`、`spike/tsconfig.json`、`local/phase0-report-draft.md`、`local/protocol-types/`)
- 在 `spike/` 下初始化 TypeScript/Node 工程。
- 记录桌面版版本,以及桌面版自带的 `codex.exe` 的路径和版本。路径写成 `%LOCALAPPDATA%\…` 这样的通用形式。
- 确认样本任务(原任务和 fork)的线程 ID,以及它们的历史存在 JSONL 里还是 SQLite 里。
- 用 `codex app-server generate-ts` 生成本机的协议类型。
- 完成标准:以上信息都写进报告草稿。
-- [ ] **T1 只读导入**(关卡 1)
+- [x] **T1 只读导入**(关卡 1;证据:`local/assets.json`、`local/assets.md`、`local/phase0-report-draft.md`)
- 读取样本的记录,输出一份素材清单,同时给出 JSON 和便于阅读的表格。每条出现记录包括:轮次、时间、来源类型、字节数、字节哈希、像素哈希、尺寸、已知的本地路径。
- 标出重复关系,无法识别的项单独列出。
- 操作前后,对样本的记录文件分别计算哈希并对比。
- 完成标准:满足 spec 关卡 1。
-- [ ] **T2 找到磁盘上的原件**
+- [x] **T2 找到磁盘上的原件**(证据:`local/matches.json`、`local/matches.md`、`local/cache/`)
- 在样本任务所用的项目素材文件夹(包括子目录;位置执行者已知,不写进仓库)和 `generated_images/` 里,按哈希找每份素材的原件。
- 如果 Codex 发送前缩放过图片,导致哈希对不上,记下有多少张。然后把图片缩放到相同尺寸再比较相似度,给出候选匹配,标为“待确认”。
- 统计“找到原件”和“只存在于记录里”各有多少。后者解码后缓存到 `local/`。
- 完成标准:每份素材都有一个可以当附件用的本地文件。
-- [ ] **T3 连上 app-server**
+- [x] **T3 连上 app-server**(证据:`local/t3-connect.json`、`local/sqlite-backup/`;由 Claude 执行)
- 按 plan“安全措施”备份 SQLite 状态库。
- 用桌面版自带的 `codex.exe` 启动一个独立的 app-server(stdio),完成 `initialize`,再调用只读的 `thread/list`。
- 如果被沙箱拦下,请用户批准提权,或者请用户在普通终端里运行。
diff --git a/spike/package.json b/spike/package.json
new file mode 100644
index 0000000..94a16d6
--- /dev/null
+++ b/spike/package.json
@@ -0,0 +1,13 @@
+{
+ "name": "codex-attachment-manager-phase0",
+ "private": true,
+ "type": "module",
+ "engines": {
+ "node": ">=24"
+ },
+ "scripts": {
+ "test": "node --test",
+ "index": "node src/index.ts",
+ "match": "node src/match.ts"
+ }
+}
diff --git a/spike/src/appserver.ts b/spike/src/appserver.ts
new file mode 100644
index 0000000..c8699b7
--- /dev/null
+++ b/spike/src/appserver.ts
@@ -0,0 +1,139 @@
+// Purpose: minimal JSON-RPC client for `codex app-server` over stdio, used by the phase 0 scripts.
+// Input: the desktop-bundled codex.exe (auto-detected) plus optional CLI args and env.
+// Output: request/notification API; the server's stderr is appended to a log file under local/.
+
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createWriteStream, existsSync, readdirSync, statSync, type WriteStream } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+
+type Json = Record<string, any>;
+export type Notification = { method: string; params: Json };
+type Pending = { resolve: (value: any) => void; reject: (error: Error) => void; method: string; timer: NodeJS.Timeout };
+type ServerRequestHandler = (method: string, params: Json) => Json | undefined;
+
+// Approval-style server requests are declined so a test turn can never change files or permissions.
+const DECLINE: Record<string, Json> = {
+ "item/commandExecution/requestApproval": { decision: "decline" },
+ "item/fileChange/requestApproval": { decision: "decline" },
+ execCommandApproval: { decision: "denied" },
+ applyPatchApproval: { decision: "denied" },
+};
+
+export function findBundledCodex(): string {
+ const bin = join(process.env.LOCALAPPDATA ?? "", "OpenAI", "Codex", "bin");
+ if (!existsSync(bin)) throw new Error("desktop-bundled codex not found under %LOCALAPPDATA%\\OpenAI\\Codex\\bin");
+ const candidates = readdirSync(bin)
+ .map((name) => join(bin, name, "codex.exe"))
+ .filter((file) => existsSync(file))
+ .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+ if (!candidates.length) throw new Error("no codex.exe in the desktop bin directory");
+ return candidates[0];
+}
+
+export class AppServer {
+ readonly notifications: Notification[] = [];
+ #child: ChildProcessWithoutNullStreams;
+ #log: WriteStream;
+ #nextId = 1;
+ #pending = new Map<number, Pending>();
+ #listeners = new Set<(notification: Notification) => void>();
+ #onServerRequest: ServerRequestHandler | undefined;
+ #exited: Promise<number | null>;
+
+ constructor(codexPath: string, args: string[], env: Record<string, string>, stderrLog: string, onServerRequest?: ServerRequestHandler) {
+ this.#log = createWriteStream(stderrLog, { flags: "a" });
+ this.#onServerRequest = onServerRequest;
+ this.#child = spawn(codexPath, ["app-server", ...args], { env: { ...process.env, ...env }, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+ this.#child.stderr.pipe(this.#log);
+ this.#exited = new Promise((resolve) => this.#child.on("exit", (code) => resolve(code)));
+ this.#child.on("exit", (code) => {
+ for (const pending of this.#pending.values()) {
+ clearTimeout(pending.timer);
+ pending.reject(new Error(`app-server exited (${code}) while waiting for ${pending.method}`));
+ }
+ this.#pending.clear();
+ });
+ createInterface({ input: this.#child.stdout, crlfDelay: Infinity }).on("line", (line) => this.#dispatch(line));
+ }
+
+ #write(message: Json): void {
+ this.#child.stdin.write(`${JSON.stringify(message)}\n`);
+ }
+
+ #dispatch(line: string): void {
+ if (!line.trim()) return;
+ let message: Json;
+ try { message = JSON.parse(line); }
+ catch { this.#log.write(`[client] unparsable stdout line (${line.length} chars)\n`); return; }
+ if (message.id !== undefined && message.method === undefined) {
+ const pending = this.#pending.get(message.id);
+ if (!pending) return;
+ this.#pending.delete(message.id);
+ clearTimeout(pending.timer);
+ if (message.error) pending.reject(new Error(`${pending.method}: ${message.error.message ?? JSON.stringify(message.error)}`));
+ else pending.resolve(message.result);
+ return;
+ }
+ if (message.id !== undefined) {
+ const custom = this.#onServerRequest?.(message.method, message.params ?? {});
+ const result = custom ?? DECLINE[message.method];
+ this.#log.write(`[client] server request ${message.method} -> ${result ? "answered" : "rejected"}\n`);
+ if (result) this.#write({ id: message.id, result });
+ else this.#write({ id: message.id, error: { code: -32601, message: `phase 0 client does not handle ${message.method}` } });
+ return;
+ }
+ const notification: Notification = { method: message.method, params: message.params ?? {} };
+ this.notifications.push(notification);
+ for (const listener of this.#listeners) listener(notification);
+ }
+
+ request<T = Json>(method: string, params: unknown, timeoutMs = 120_000): Promise<T> {
+ const id = this.#nextId++;
+ return new Promise<T>((resolve, reject) => {
+ const timer = setTimeout(() => {
+ this.#pending.delete(id);
+ reject(new Error(`${method} timed out after ${timeoutMs} ms`));
+ }, timeoutMs);
+ this.#pending.set(id, { resolve, reject, method, timer });
+ this.#write({ id, method, params });
+ });
+ }
+
+ notify(method: string, params?: unknown): void {
+ this.#write(params === undefined ? { method } : { method, params });
+ }
+
+ waitFor(predicate: (notification: Notification) => boolean, timeoutMs: number): Promise<Notification> {
+ const already = this.notifications.find(predicate);
+ if (already) return Promise.resolve(already);
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => { this.#listeners.delete(listener); reject(new Error(`notification wait timed out after ${timeoutMs} ms`)); }, timeoutMs);
+ const listener = (notification: Notification) => {
+ if (!predicate(notification)) return;
+ clearTimeout(timer);
+ this.#listeners.delete(listener);
+ resolve(notification);
+ };
+ this.#listeners.add(listener);
+ });
+ }
+
+ async initialize(): Promise<Json> {
+ const result = await this.request("initialize", {
+ clientInfo: { name: "codex-attachment-manager-phase0", title: "Codex Attachment Manager (phase 0)", version: "0.0.0" },
+ capabilities: null,
+ });
+ this.notify("initialized");
+ return result;
+ }
+
+ async stop(timeoutMs = 10_000): Promise<number | null> {
+ this.#child.stdin.end();
+ const timer = setTimeout(() => this.#child.kill(), timeoutMs);
+ const code = await this.#exited;
+ clearTimeout(timer);
+ await new Promise<void>((resolve) => this.#log.end(() => resolve()));
+ return code;
+ }
+}
diff --git a/spike/src/history.ts b/spike/src/history.ts
new file mode 100644
index 0000000..7a34596
--- /dev/null
+++ b/spike/src/history.ts
@@ -0,0 +1,102 @@
+// Purpose: read a thread's effective model-visible history from paginated rollout segments (read-only)
+// and estimate how many bytes of history a model request carries.
+// Input: the sessions directory and a thread or segment id. Output: records and byte estimates (in memory).
+
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+type Json = Record<string, any>;
+export type RolloutRecord = { file: string; line: number; offset: number; ordinal: number | null; type: string; payload: Json };
+
+function walk(directory: string): string[] {
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const full = join(directory, entry.name);
+ return entry.isDirectory() ? walk(full) : entry.isFile() ? [full] : [];
+ });
+}
+
+// A segment id is the UUID suffix after the thread id in the file name; the first segment uses the thread id itself.
+export function indexSegments(sessionsDir: string): Map<string, string> {
+ const segments = new Map<string, string>();
+ for (const file of walk(sessionsDir)) {
+ const match = /rollout-[0-9T:-]+-([0-9a-f-]{36})(?:_([0-9a-f-]{36}))?\.jsonl$/.exec(basename(file));
+ if (match) segments.set(match[2] ?? match[1], file);
+ }
+ return segments;
+}
+
+function ownRecords(file: string, endOffset: number): { meta: Json; records: RolloutRecord[] } {
+ const buffer = readFileSync(file);
+ const records: RolloutRecord[] = [];
+ let meta: Json = {};
+ let offset = 0;
+ let line = 0;
+ while (offset < buffer.length && offset < endOffset) {
+ let end = buffer.indexOf(0x0a, offset);
+ if (end < 0) end = buffer.length;
+ line++;
+ const text = buffer.toString("utf8", offset, end).replace(/\r$/, "");
+ if (text.trim()) {
+ const record = JSON.parse(text);
+ if (record.type === "session_meta" && line === 1) meta = record.payload ?? {};
+ records.push({ file, line, offset, ordinal: record.ordinal ?? null, type: record.type, payload: record.payload ?? {} });
+ }
+ offset = end + 1;
+ }
+ return { meta, records };
+}
+
+// Effective history = the base segment's records before history_base.end_byte_offset (recursively) + this segment's records.
+export function effectiveRecords(segments: Map<string, string>, segmentId: string, endOffset = Number.POSITIVE_INFINITY): RolloutRecord[] {
+ const file = segments.get(segmentId);
+ if (!file) throw new Error(`rollout segment not found: ${segmentId}`);
+ const { meta, records } = ownRecords(file, endOffset);
+ const base = meta.history_base;
+ const inherited = base ? effectiveRecords(segments, base.thread_id, base.end_byte_offset) : [];
+ return [...inherited, ...records];
+}
+
+// The newest segment of a thread is the one no other segment of that thread uses as its base.
+export function latestSegment(segments: Map<string, string>, threadId: string): string {
+ const own = [...segments.entries()].filter(([, file]) => basename(file).includes(threadId));
+ const bases = new Set<string>();
+ for (const [, file] of own) {
+ const first = readFileSync(file, "utf8").split("\n", 1)[0];
+ const base = JSON.parse(first).payload?.history_base?.thread_id;
+ if (base) bases.add(base);
+ }
+ const heads = own.filter(([id]) => !bases.has(id)).map(([id]) => id);
+ if (heads.length !== 1) throw new Error(`expected one latest segment for ${threadId}, found ${heads.length}`);
+ return heads[0];
+}
+
+export type InlineImage = { sha256: string; bytes: number; dataUrlChars: number; record: RolloutRecord };
+
+export function inlineImages(records: RolloutRecord[]): InlineImage[] {
+ const images: InlineImage[] = [];
+ for (const record of records) {
+ if (record.type !== "response_item") continue;
+ const parts = Array.isArray(record.payload.content) ? record.payload.content : Array.isArray(record.payload.output) ? record.payload.output : [];
+ for (const part of parts) {
+ const url = part?.image_url;
+ const match = typeof url === "string" ? /^data:[^;,]+;base64,(.+)$/s.exec(url) : null;
+ if (!match) continue;
+ const bytes = Buffer.from(match[1], "base64");
+ images.push({ sha256: createHash("sha256").update(bytes).digest("hex"), bytes: bytes.length, dataUrlChars: url.length, record });
+ }
+ }
+ return images;
+}
+
+// Bytes of the history items a request would carry: every response_item payload serialized as UTF-8 JSON.
+export function historyBytes(records: RolloutRecord[]): { items: number; bytes: number } {
+ let bytes = 0;
+ let items = 0;
+ for (const record of records) {
+ if (record.type !== "response_item") continue;
+ items++;
+ bytes += Buffer.byteLength(JSON.stringify(record.payload), "utf8");
+ }
+ return { items, bytes };
+}
diff --git a/spike/src/index.ts b/spike/src/index.ts
new file mode 100644
index 0000000..b1b53ad
--- /dev/null
+++ b/spike/src/index.ts
@@ -0,0 +1,243 @@
+// Purpose: read sample Codex rollout JSONL files and build a local-only image timeline.
+// Input: --sessions <directory> --threads <id,id>; output: local/assets.json and local/assets.md.
+
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, mkdirSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { decodePng } from "./png.ts";
+import { fileSha256, pathForViewedImage } from "./viewpaths.ts";
+
+type Json = Record<string, any>;
+type Occurrence = {
+ threadId: string;
+ turnId: string | null;
+ turnNumber: number | null;
+ timestamp: string;
+ source: "user_upload" | "view_image" | "tool_output";
+ byteLength: number;
+ byteSha256: string;
+ pixelSha256: string | null;
+ width: number | null;
+ height: number | null;
+ mime: string;
+ knownLocalPath: string | null;
+ rolloutFile: string;
+ line: number;
+ contentIndex: number;
+ assetId: string;
+};
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const localRoot = join(repoRoot, "local");
+
+function argument(name: string): string {
+ const index = process.argv.indexOf(name);
+ const value = process.argv[index + 1];
+ if (index < 0 || !value || value.startsWith("--")) throw new Error(`missing ${name}`);
+ return value;
+}
+
+function walk(directory: string): string[] {
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const full = join(directory, entry.name);
+ return entry.isDirectory() ? walk(full) : entry.isFile() ? [full] : [];
+ });
+}
+
+function localPathFromText(text: unknown): string | null {
+ if (typeof text !== "string") return null;
+ const found = text.match(/\bpath\s*=\s*["']([^"']+)["']/i)?.[1];
+ if (!found) return null;
+ if (found.startsWith("file://")) {
+ try { return fileURLToPath(found); } catch { return null; }
+ }
+ return isAbsolute(found) ? found : null;
+}
+
+function pathBefore(content: Json[], index: number): string | null {
+ for (let i = index - 1; i >= 0; i--) {
+ const found = localPathFromText(content[i]?.text);
+ if (found) return found;
+ }
+ return null;
+}
+
+function imageParts(item: Json): Array<{ image: Json; index: number; path: string | null }> {
+ const content: Json[] = Array.isArray(item.content) ? item.content : Array.isArray(item.output) ? item.output : [];
+ return content.flatMap((part, index) =>
+ part?.type === "input_image" || part?.type === "output_image"
+ ? [{ image: part, index, path: pathBefore(content, index) }]
+ : [],
+ );
+}
+
+function pathFromImageView(uri: unknown): string | null {
+ if (typeof uri !== "string") return null;
+ if (uri.startsWith("file://")) {
+ try { return fileURLToPath(uri); } catch { return null; }
+ }
+ return isAbsolute(uri) ? uri : null;
+}
+
+function markdownCell(value: unknown): string {
+ return String(value ?? "—").replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+async function main(): Promise<void> {
+ const sessions = resolve(argument("--sessions"));
+ const threadIds = argument("--threads").split(",").filter(Boolean);
+ if (!threadIds.length || !existsSync(sessions)) throw new Error("sessions directory or thread ids unavailable");
+ mkdirSync(localRoot, { recursive: true });
+ const actualLocal = realpathSync(localRoot);
+ if (relative(repoRoot, actualLocal).startsWith("..")) throw new Error("local output points outside the repository");
+
+ const files = walk(sessions)
+ .filter((file) => file.endsWith(".jsonl") && threadIds.some((id) => basename(file).includes(id)))
+ .sort();
+ if (!files.length) throw new Error("no sample rollout files found");
+ const before = new Map<string, string>();
+ for (const file of files) before.set(file, await fileSha256(file));
+
+ const occurrences: Occurrence[] = [];
+ const unrecognized: Json[] = [];
+ const turns: Array<{ threadId: string; turnId: string; timestamp: string }> = [];
+ const decoded = new Map<string, { pixelSha256: string; width: number; height: number }>();
+ const viewedFileHashes = new Map<string, string | null>();
+ for (const file of files) {
+ let lineNumber = 0;
+ let threadId: string | null = null;
+ let activeTurn: string | null = null;
+ const calls = new Map<string, Json>();
+ let pendingViews: string[] = [];
+ const input = createInterface({ input: createReadStream(file, { encoding: "utf8" }), crlfDelay: Infinity });
+ for await (const line of input) {
+ lineNumber++;
+ let record: Json;
+ try { record = JSON.parse(line); }
+ catch {
+ unrecognized.push({ rolloutFile: basename(file), line: lineNumber, reason: "invalid_json" });
+ continue;
+ }
+ const payload: Json = record.payload ?? {};
+ if (record.type === "session_meta") {
+ threadId = payload.id ?? null;
+ continue;
+ }
+ if (!threadId || !threadIds.includes(threadId)) continue;
+ if (record.type === "event_msg" && payload.type === "task_started") {
+ activeTurn = payload.turn_id ?? null;
+ if (activeTurn) turns.push({ threadId, turnId: activeTurn, timestamp: record.timestamp });
+ }
+ if (record.type === "event_msg" && payload.type === "item_completed" && payload.item?.type === "ImageView") {
+ const viewedPath = pathFromImageView(payload.item.path);
+ if (viewedPath) pendingViews.push(viewedPath);
+ else unrecognized.push({ rolloutFile: basename(file), line: lineNumber, reason: "image_view_path_unreadable" });
+ }
+ if (record.type !== "response_item") continue;
+ if (payload.type === "custom_tool_call") {
+ calls.set(payload.call_id, { name: payload.name, input: payload.input });
+ continue;
+ }
+ const parts = imageParts(payload);
+ if (!parts.length) continue;
+ const call = calls.get(payload.call_id);
+ const source: Occurrence["source"] = payload.type === "message" && payload.role === "user"
+ ? "user_upload"
+ : String(call?.input ?? "").includes("view_image") ? "view_image" : "tool_output";
+ const viewCandidates = source === "view_image" ? pendingViews.splice(0, parts.length) : [];
+ for (const { image, index, path } of parts) {
+ const url = image.image_url ?? image.url;
+ const match = typeof url === "string" ? /^data:([^;,]+);base64,(.+)$/s.exec(url) : null;
+ if (!match) {
+ unrecognized.push({ rolloutFile: basename(file), line: lineNumber, contentIndex: index, reason: "image_without_inline_data" });
+ continue;
+ }
+ const bytes = Buffer.from(match[2], "base64");
+ const byteSha256 = createHash("sha256").update(bytes).digest("hex");
+ let info = decoded.get(byteSha256);
+ if (!info && match[1] === "image/png") {
+ try {
+ const png = decodePng(bytes);
+ info = { pixelSha256: png.pixelSha256, width: png.width, height: png.height };
+ decoded.set(byteSha256, info);
+ } catch (error) {
+ unrecognized.push({ rolloutFile: basename(file), line: lineNumber, contentIndex: index, reason: "pixel_decode_failed", detail: String(error) });
+ }
+ }
+ if (match[1] !== "image/png") {
+ unrecognized.push({ rolloutFile: basename(file), line: lineNumber, contentIndex: index, reason: "unsupported_image_mime", mime: match[1] });
+ }
+ occurrences.push({
+ threadId,
+ turnId: payload.internal_chat_message_metadata_passthrough?.turn_id ?? activeTurn,
+ turnNumber: null,
+ timestamp: record.timestamp,
+ source,
+ byteLength: bytes.length,
+ byteSha256,
+ pixelSha256: info?.pixelSha256 ?? null,
+ width: info?.width ?? null,
+ height: info?.height ?? null,
+ mime: match[1],
+ knownLocalPath: source === "view_image" ? await pathForViewedImage(viewCandidates, byteSha256, viewedFileHashes) : path,
+ rolloutFile: basename(file),
+ line: lineNumber,
+ contentIndex: index,
+ assetId: "",
+ });
+ }
+ }
+ for (const viewedPath of pendingViews) {
+ unrecognized.push({ rolloutFile: basename(file), reason: "image_view_without_inline_result", knownLocalPath: viewedPath });
+ }
+ }
+
+ const turnNumbers = new Map<string, number>();
+ for (const id of threadIds) {
+ const sorted = turns.filter((turn) => turn.threadId === id).sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+ for (const turn of sorted) {
+ const key = `${id}:${turn.turnId}`;
+ if (!turnNumbers.has(key)) turnNumbers.set(key, [...turnNumbers.keys()].filter((value) => value.startsWith(`${id}:`)).length + 1);
+ }
+ }
+ occurrences.sort((a, b) => a.timestamp.localeCompare(b.timestamp) || a.rolloutFile.localeCompare(b.rolloutFile) || a.line - b.line || a.contentIndex - b.contentIndex);
+ const assets: Array<Json> = [];
+ const groups = new Map<string, Json>();
+ for (const occurrence of occurrences) {
+ occurrence.turnNumber = occurrence.turnId ? turnNumbers.get(`${occurrence.threadId}:${occurrence.turnId}`) ?? null : null;
+ const groupKey = occurrence.pixelSha256 ? `pixel:${occurrence.pixelSha256}` : `byte:${occurrence.byteSha256}`;
+ let asset = groups.get(groupKey);
+ if (!asset) {
+ asset = { assetId: `IMG-${String(assets.length + 1).padStart(3, "0")}`, pixelSha256: occurrence.pixelSha256, width: occurrence.width, height: occurrence.height, byteHashes: [], occurrenceCount: 0, threadIds: [] };
+ groups.set(groupKey, asset);
+ assets.push(asset);
+ }
+ occurrence.assetId = asset.assetId;
+ asset.occurrenceCount++;
+ if (!asset.byteHashes.includes(occurrence.byteSha256)) asset.byteHashes.push(occurrence.byteSha256);
+ if (!asset.threadIds.includes(occurrence.threadId)) asset.threadIds.push(occurrence.threadId);
+ }
+
+ const sourceFiles = [];
+ for (const file of files) {
+ const afterSha256 = await fileSha256(file);
+ sourceFiles.push({ path: file, bytes: statSync(file).size, beforeSha256: before.get(file), afterSha256, unchanged: before.get(file) === afterSha256 });
+ }
+ const manifest = { createdAt: new Date().toISOString(), threadIds, sourceFiles, originalFilesUnchanged: sourceFiles.every((source) => source.unchanged), assets, occurrences, unrecognized };
+ writeFileSync(join(localRoot, "assets.json"), JSON.stringify(manifest, null, 2));
+
+ const rows = occurrences.map((o) => `| ${markdownCell(o.threadId.slice(0, 8))} | ${markdownCell(o.turnNumber)} | ${markdownCell(o.timestamp)} | ${markdownCell(o.source)} | ${o.assetId} | ${o.byteLength} | ${o.byteSha256.slice(0, 12)} | ${markdownCell(o.pixelSha256?.slice(0, 12))} | ${markdownCell(o.width && o.height ? `${o.width}×${o.height}` : null)} | ${markdownCell(o.knownLocalPath)} | ${markdownCell(`${o.rolloutFile}:${o.line}:${o.contentIndex}`)} |`);
+ const report = [
+ "# 阶段 0 素材清单(仅本机)", "",
+ `记录文件:${files.length};图片出现记录:${occurrences.length};素材:${assets.length};无法识别:${unrecognized.length};原文件哈希不变:${manifest.originalFilesUnchanged}`, "",
+ "| 任务 | 轮次 | 时间 UTC | 来源 | 素材 | 图片字节 | 字节 SHA 前缀 | 像素 SHA 前缀 | 尺寸 | 已知本地路径 | 记录位置 |",
+ "| --- | ---: | --- | --- | --- | ---: | --- | --- | --- | --- | --- |",
+ ...rows, "", "## 无法识别的项目", "", "```json", JSON.stringify(unrecognized, null, 2), "```", "",
+ ].join("\n");
+ writeFileSync(join(localRoot, "assets.md"), report);
+ console.log(JSON.stringify({ files: files.length, occurrences: occurrences.length, assets: assets.length, unrecognized: unrecognized.length, originalFilesUnchanged: manifest.originalFilesUnchanged, byThread: Object.fromEntries(threadIds.map((id) => [id, { occurrences: occurrences.filter((o) => o.threadId === id).length, assets: new Set(occurrences.filter((o) => o.threadId === id).map((o) => o.assetId)).size }])) }));
+}
+
+await main();
diff --git a/spike/src/match.ts b/spike/src/match.ts
new file mode 100644
index 0000000..a5f486d
--- /dev/null
+++ b/spike/src/match.ts
@@ -0,0 +1,175 @@
+// Purpose: match indexed images to read-only local originals and cache inline-only copies.
+// Input: local/assets.json plus --project and --generated image directories.
+// Output: local/matches.json, local/matches.md, and exact inline copies under local/cache/.
+
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { decodePng, type DecodedPng } from "./png.ts";
+
+type Json = Record<string, any>;
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const localRoot = join(repoRoot, "local");
+
+function argument(name: string): string {
+ const i = process.argv.indexOf(name);
+ if (i < 0 || !process.argv[i + 1]) throw new Error(`missing ${name}`);
+ return resolve(process.argv[i + 1]);
+}
+
+function walk(directory: string): string[] {
+ if (!existsSync(directory)) return [];
+ return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+ const full = join(directory, entry.name);
+ return entry.isDirectory() ? walk(full) : entry.isFile() ? [full] : [];
+ });
+}
+
+async function sha256File(file: string): Promise<string> {
+ const hash = createHash("sha256");
+ for await (const chunk of createReadStream(file)) hash.update(chunk);
+ return hash.digest("hex");
+}
+
+async function inlineImage(occurrence: Json, sourceFiles: Json[]): Promise<Buffer> {
+ const source = sourceFiles.find((entry) => basename(entry.path) === occurrence.rolloutFile);
+ if (!source) throw new Error(`missing rollout source for ${occurrence.assetId}`);
+ let number = 0;
+ const lines = createInterface({ input: createReadStream(source.path, { encoding: "utf8" }), crlfDelay: Infinity });
+ for await (const line of lines) {
+ if (++number !== occurrence.line) continue;
+ const item = JSON.parse(line).payload;
+ const parts = Array.isArray(item.content) ? item.content : item.output;
+ const image = parts?.[occurrence.contentIndex];
+ const match = /^data:[^;,]+;base64,(.+)$/s.exec(image?.image_url ?? image?.url ?? "");
+ if (!match) throw new Error(`inline image missing for ${occurrence.assetId}`);
+ const bytes = Buffer.from(match[1], "base64");
+ if (createHash("sha256").update(bytes).digest("hex") !== occurrence.byteSha256) {
+ throw new Error(`inline image hash changed for ${occurrence.assetId}`);
+ }
+ lines.close();
+ return bytes;
+ }
+ throw new Error(`rollout line missing for ${occurrence.assetId}`);
+}
+
+function resizedSimilarity(source: DecodedPng, target: DecodedPng): number {
+ let difference = 0;
+ const sourcePixels = source.pixels;
+ const targetPixels = target.pixels;
+ for (let y = 0; y < target.height; y++) {
+ const sy = Math.max(0, Math.min(source.height - 1, (y + 0.5) * source.height / target.height - 0.5));
+ const y0 = Math.floor(sy), y1 = Math.min(source.height - 1, y0 + 1), fy = sy - y0;
+ for (let x = 0; x < target.width; x++) {
+ const sx = Math.max(0, Math.min(source.width - 1, (x + 0.5) * source.width / target.width - 0.5));
+ const x0 = Math.floor(sx), x1 = Math.min(source.width - 1, x0 + 1), fx = sx - x0;
+ const dest = (y * target.width + x) * 4;
+ for (let channel = 0; channel < 3; channel++) {
+ const a = sourcePixels[(y0 * source.width + x0) * 4 + channel];
+ const b = sourcePixels[(y0 * source.width + x1) * 4 + channel];
+ const c = sourcePixels[(y1 * source.width + x0) * 4 + channel];
+ const d = sourcePixels[(y1 * source.width + x1) * 4 + channel];
+ const interpolated = (a * (1 - fx) + b * fx) * (1 - fy) + (c * (1 - fx) + d * fx) * fy;
+ difference += Math.abs(interpolated - targetPixels[dest + channel]);
+ }
+ }
+ }
+ return 1 - difference / (target.width * target.height * 3 * 255);
+}
+
+async function main(): Promise<void> {
+ const project = argument("--project");
+ const generated = argument("--generated");
+ const inventory: Json = JSON.parse(readFileSync(join(localRoot, "assets.json"), "utf8"));
+ const candidateMap = new Map<string, { path: string; sources: string[] }>();
+ for (const [source, files] of [
+ ["project", walk(project)],
+ ["generated_images", walk(generated)],
+ ["known_path", inventory.occurrences.map((item: Json) => item.knownLocalPath).filter(Boolean)],
+ ] as Array<[string, string[]]>) {
+ for (const file of files) {
+ if (!existsSync(file) || !/\.(png|jpg|jpeg|webp)$/i.test(extname(file))) continue;
+ const key = resolve(file).toLowerCase();
+ let candidate = candidateMap.get(key);
+ if (!candidate) {
+ candidate = { path: resolve(file), sources: [] };
+ candidateMap.set(key, candidate);
+ }
+ if (!candidate.sources.includes(source)) candidate.sources.push(source);
+ }
+ }
+
+ const candidates = [];
+ for (const candidate of candidateMap.values()) {
+ candidates.push({ ...candidate, bytes: statSync(candidate.path).size, byteSha256: await sha256File(candidate.path) });
+ }
+ const matches = [];
+ const realFileHashesBefore = new Map<string, string>();
+ mkdirSync(join(localRoot, "cache"), { recursive: true });
+ for (const asset of inventory.assets) {
+ const first: Json = inventory.occurrences.find((item: Json) => item.assetId === asset.assetId);
+ const exact = candidates.filter((candidate) => asset.byteHashes.includes(candidate.byteSha256));
+ const preferred = exact.find((candidate) => candidate.sources.includes("project"))
+ ?? exact.find((candidate) => candidate.sources.includes("generated_images"))
+ ?? exact[0];
+ const record: Json = { assetId: asset.assetId, exactMatches: exact, attachmentPath: null, attachmentKind: null, resizedCandidate: null };
+ if (preferred) {
+ record.attachmentPath = preferred.path;
+ record.attachmentKind = "exact_local_file";
+ realFileHashesBefore.set(preferred.path, preferred.byteSha256);
+ } else {
+ const inline = await inlineImage(first, inventory.sourceFiles);
+ const cachePath = join(localRoot, "cache", `${asset.assetId}.png`);
+ if (existsSync(cachePath)) {
+ if (await sha256File(cachePath) !== first.byteSha256) throw new Error(`existing cache differs for ${asset.assetId}`);
+ } else {
+ writeFileSync(cachePath, inline, { flag: "wx" });
+ }
+ record.attachmentPath = cachePath;
+ record.attachmentKind = "exact_inline_cache";
+ const known = candidates.find((candidate) => candidate.path.toLowerCase() === resolve(first.knownLocalPath ?? "").toLowerCase());
+ if (known?.path.toLowerCase().endsWith(".png")) {
+ const source = decodePng(readFileSync(known.path));
+ const target = decodePng(inline);
+ const similarity = resizedSimilarity(source, target);
+ record.resizedCandidate = {
+ path: known.path,
+ sourceDimensions: [source.width, source.height],
+ targetDimensions: [target.width, target.height],
+ similarity: Number(similarity.toFixed(6)),
+ status: "待确认",
+ };
+ realFileHashesBefore.set(known.path, known.byteSha256);
+ }
+ }
+ matches.push(record);
+ }
+ const realFilesUnchanged = [];
+ for (const [file, beforeSha256] of realFileHashesBefore) {
+ const afterSha256 = await sha256File(file);
+ realFilesUnchanged.push({ path: file, beforeSha256, afterSha256, unchanged: beforeSha256 === afterSha256 });
+ }
+ const report = {
+ createdAt: new Date().toISOString(),
+ candidateFilesScanned: candidates.length,
+ exactLocalFiles: matches.filter((item) => item.attachmentKind === "exact_local_file").length,
+ exactInlineCaches: matches.filter((item) => item.attachmentKind === "exact_inline_cache").length,
+ resizedCandidatesPending: matches.filter((item) => item.resizedCandidate).length,
+ realFilesUnchanged,
+ allRealFilesUnchanged: realFilesUnchanged.every((item) => item.unchanged),
+ matches,
+ };
+ writeFileSync(join(localRoot, "matches.json"), JSON.stringify(report, null, 2));
+ const rows = matches.map((item) => `| ${item.assetId} | ${item.attachmentKind} | ${item.attachmentPath} | ${item.exactMatches.length} | ${item.resizedCandidate ? `${item.resizedCandidate.similarity}(待确认)` : "—"} |`);
+ writeFileSync(join(localRoot, "matches.md"), [
+ "# 阶段 0 磁盘素材匹配(仅本机)", "",
+ `候选文件:${candidates.length};精确原件:${report.exactLocalFiles};内联缓存:${report.exactInlineCaches};缩放候选:${report.resizedCandidatesPending};真实文件哈希不变:${report.allRealFilesUnchanged}`, "",
+ "| 素材 | 可用附件来源 | 路径 | 精确副本数 | 缩放相似度 |",
+ "| --- | --- | --- | ---: | --- |", ...rows, "",
+ ].join("\n"));
+ console.log(JSON.stringify({ candidateFilesScanned: report.candidateFilesScanned, exactLocalFiles: report.exactLocalFiles, exactInlineCaches: report.exactInlineCaches, resizedCandidatesPending: report.resizedCandidatesPending, allRealFilesUnchanged: report.allRealFilesUnchanged }));
+}
+
+await main();
diff --git a/spike/src/png.test.ts b/spike/src/png.test.ts
new file mode 100644
index 0000000..850a32d
--- /dev/null
+++ b/spike/src/png.test.ts
@@ -0,0 +1,42 @@
+// Purpose: verify pixel identity across differently encoded PNG files.
+// Input: synthetic 1×1 PNG buffers; output: Node test assertions only.
+
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import test from "node:test";
+import { deflateSync } from "node:zlib";
+import { decodePng } from "./png.ts";
+
+function chunk(type: string, data: Buffer): Buffer {
+ const length = Buffer.alloc(4);
+ length.writeUInt32BE(data.length);
+ return Buffer.concat([length, Buffer.from(type), data, Buffer.alloc(4)]);
+}
+
+function onePixelPng(colorType: 2 | 6, color: number[], compressionLevel: number): Buffer {
+ const header = Buffer.alloc(13);
+ header.writeUInt32BE(1, 0);
+ header.writeUInt32BE(1, 4);
+ header[8] = 8;
+ header[9] = colorType;
+ return Buffer.concat([
+ Buffer.from("89504e470d0a1a0a", "hex"),
+ chunk("IHDR", header),
+ chunk("IDAT", deflateSync(Buffer.from([0, ...color]), { level: compressionLevel })),
+ chunk("IEND", Buffer.alloc(0)),
+ ]);
+}
+
+test("RGB and RGBA encodings of the same picture share a pixel hash", () => {
+ const rgb = onePixelPng(2, [255, 0, 0], 1);
+ const rgba = onePixelPng(6, [255, 0, 0, 255], 9);
+ const expectedPixels = Buffer.alloc(8 + 4);
+ expectedPixels.writeUInt32BE(1, 0);
+ expectedPixels.writeUInt32BE(1, 4);
+ Buffer.from([255, 0, 0, 255]).copy(expectedPixels, 8);
+ const expectedHash = createHash("sha256").update(expectedPixels).digest("hex");
+
+ assert.notDeepEqual(rgb, rgba);
+ assert.equal(decodePng(rgb).pixelSha256, expectedHash);
+ assert.equal(decodePng(rgba).pixelSha256, expectedHash);
+});
diff --git a/spike/src/png.ts b/spike/src/png.ts
new file mode 100644
index 0000000..64a0baa
--- /dev/null
+++ b/spike/src/png.ts
@@ -0,0 +1,106 @@
+// Purpose: decode the PNG variants in the phase 0 sample into canonical RGBA pixels.
+// Input: PNG bytes; output: dimensions, RGBA pixels, and a dimension-aware pixel SHA-256.
+
+import { createHash } from "node:crypto";
+import { inflateSync } from "node:zlib";
+
+export type DecodedPng = {
+ width: number;
+ height: number;
+ pixels: Buffer;
+ pixelSha256: string;
+};
+
+const PNG_SIGNATURE = Buffer.from("89504e470d0a1a0a", "hex");
+
+function paeth(left: number, above: number, upperLeft: number): number {
+ const predicted = left + above - upperLeft;
+ const leftDistance = Math.abs(predicted - left);
+ const aboveDistance = Math.abs(predicted - above);
+ const upperLeftDistance = Math.abs(predicted - upperLeft);
+ if (leftDistance <= aboveDistance && leftDistance <= upperLeftDistance) return left;
+ if (aboveDistance <= upperLeftDistance) return above;
+ return upperLeft;
+}
+
+export function decodePng(bytes: Buffer): DecodedPng {
+ if (bytes.length < 33 || !bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+ throw new Error("invalid PNG signature");
+ }
+
+ let offset = 8;
+ let width = 0;
+ let height = 0;
+ let channels = 0;
+ const imageData: Buffer[] = [];
+ while (offset + 12 <= bytes.length) {
+ const length = bytes.readUInt32BE(offset);
+ const end = offset + 12 + length;
+ if (end > bytes.length) throw new Error("truncated PNG chunk");
+ const type = bytes.toString("ascii", offset + 4, offset + 8);
+ const data = bytes.subarray(offset + 8, offset + 8 + length);
+ if (type === "IHDR") {
+ if (length !== 13) throw new Error("invalid PNG header");
+ width = data.readUInt32BE(0);
+ height = data.readUInt32BE(4);
+ if (data[8] !== 8 || (data[9] !== 2 && data[9] !== 6) || data[12] !== 0) {
+ throw new Error(`unsupported PNG encoding: depth=${data[8]}, color=${data[9]}, interlace=${data[12]}`);
+ }
+ channels = data[9] === 2 ? 3 : 4;
+ } else if (type === "IDAT") {
+ imageData.push(data);
+ } else if (type === "IEND") {
+ break;
+ }
+ offset = end;
+ }
+
+ if (!width || !height || !channels || !imageData.length || width * height > 100_000_000) {
+ throw new Error("invalid or oversized PNG image");
+ }
+ const rowBytes = width * channels;
+ const inflated = inflateSync(Buffer.concat(imageData));
+ if (inflated.length !== height * (rowBytes + 1)) throw new Error("invalid PNG scanline size");
+
+ const pixels = Buffer.allocUnsafe(width * height * 4);
+ let previous = Buffer.alloc(rowBytes);
+ for (let y = 0; y < height; y++) {
+ const rowStart = y * (rowBytes + 1);
+ const filter = inflated[rowStart];
+ const row = Buffer.allocUnsafe(rowBytes);
+ for (let i = 0; i < rowBytes; i++) {
+ const left = i >= channels ? row[i - channels] : 0;
+ const above = previous[i];
+ const upperLeft = i >= channels ? previous[i - channels] : 0;
+ let predictor: number;
+ switch (filter) {
+ case 0: predictor = 0; break;
+ case 1: predictor = left; break;
+ case 2: predictor = above; break;
+ case 3: predictor = Math.floor((left + above) / 2); break;
+ case 4: predictor = paeth(left, above, upperLeft); break;
+ default: throw new Error(`unsupported PNG filter: ${filter}`);
+ }
+ row[i] = (inflated[rowStart + 1 + i] + predictor) & 0xff;
+ }
+ for (let x = 0; x < width; x++) {
+ const source = x * channels;
+ const target = (y * width + x) * 4;
+ pixels[target] = row[source];
+ pixels[target + 1] = row[source + 1];
+ pixels[target + 2] = row[source + 2];
+ pixels[target + 3] = channels === 4 ? row[source + 3] : 255;
+ }
+ previous = row;
+ }
+
+ const dimensions = Buffer.alloc(8);
+ dimensions.writeUInt32BE(width, 0);
+ dimensions.writeUInt32BE(height, 4);
+ return {
+ width,
+ height,
+ pixels,
+ pixelSha256: createHash("sha256").update(dimensions).update(pixels).digest("hex"),
+ };
+}
diff --git a/spike/src/t3-connect.ts b/spike/src/t3-connect.ts
new file mode 100644
index 0000000..d9a34d5
--- /dev/null
+++ b/spike/src/t3-connect.ts
@@ -0,0 +1,63 @@
+// Purpose: T3 — start an independent app-server with the desktop-bundled codex.exe and make read-only calls.
+// Input: --threads <id,id>; output: local/t3-connect.json (thread metadata only, no conversation content).
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AppServer, findBundledCodex } from "./appserver.ts";
+
+const localRoot = join(resolve(dirname(fileURLToPath(import.meta.url)), "../.."), "local");
+
+function argument(name: string): string {
+ const index = process.argv.indexOf(name);
+ const value = process.argv[index + 1];
+ if (index < 0 || !value) throw new Error(`missing ${name}`);
+ return value;
+}
+
+function summary(thread: Record<string, any>): Record<string, unknown> {
+ const { id, name, forkedFromId, historyMode, modelProvider, model, reasoningEffort, status, cliVersion, source, originator, createdAt, updatedAt, ephemeral, cwd } = thread;
+ return { id, name, preview: String(thread.preview ?? "").slice(0, 40), forkedFromId, historyMode, modelProvider, model, reasoningEffort, status, cliVersion, source, originator, createdAt, updatedAt, ephemeral, cwd };
+}
+
+async function main(): Promise<void> {
+ const threadIds = argument("--threads").split(",").filter(Boolean);
+ const codex = findBundledCodex();
+ const codexVersion = execFileSync(codex, ["--version"]).toString().trim();
+ mkdirSync(join(localRoot, "logs"), { recursive: true });
+ const stamp = new Date().toISOString().replaceAll(":", "-");
+ const server = new AppServer(codex, [], {}, join(localRoot, "logs", `t3-appserver-${stamp}.log`));
+ try {
+ const init = await server.initialize();
+ const threads = [];
+ for (const threadId of threadIds) {
+ const response = await server.request<{ thread: Record<string, any> }>("thread/read", { threadId, includeTurns: false });
+ threads.push(summary(response.thread));
+ }
+ const listedIds: string[] = [];
+ let cursor: string | null = null;
+ let pages = 0;
+ do {
+ const page: { data: Array<{ id: string }>; nextCursor: string | null } = await server.request("thread/list", { cursor, limit: 100 });
+ listedIds.push(...page.data.map((thread) => thread.id));
+ cursor = page.nextCursor;
+ pages++;
+ } while (cursor && pages < 20 && !threadIds.every((id) => listedIds.includes(id)));
+ const result = {
+ createdAt: new Date().toISOString(),
+ codexVersion,
+ platformFamily: init.platformFamily,
+ threads,
+ listed: Object.fromEntries(threadIds.map((id) => [id, listedIds.includes(id)])),
+ listPagesScanned: pages,
+ notificationsSeen: [...new Set(server.notifications.map((n) => n.method))],
+ };
+ writeFileSync(join(localRoot, "t3-connect.json"), JSON.stringify(result, null, 2));
+ console.log(JSON.stringify({ ...result, threads: threads.map(({ cwd, ...rest }) => rest) }, null, 2));
+ } finally {
+ console.log(`app-server exit code: ${await server.stop()}`);
+ }
+}
+
+await main();
diff --git a/spike/src/t7-calibrate.ts b/spike/src/t7-calibrate.ts
new file mode 100644
index 0000000..2a02c21
--- /dev/null
+++ b/spike/src/t7-calibrate.ts
@@ -0,0 +1,51 @@
+// Purpose: T7 prerequisite — check that the rollout-based request estimate matches real request sizes
+// that Codex logged (pre_compression_bytes) for the sample threads.
+// Input: --sessions <dir>; sample thread ids and logged sizes come from local/sample.json (never committed).
+// Output: local/t7-calibration.json and a console table.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { effectiveRecords, historyBytes, indexSegments, inlineImages, latestSegment, type RolloutRecord } from "./history.ts";
+
+type CalibrationCase = { name: string; thread: "original" | "fork"; segment: "fork" | "latest"; lastLine: number | null; logged: number };
+const localRoot = join(resolve(dirname(fileURLToPath(import.meta.url)), "../.."), "local");
+
+function argument(name: string): string {
+ const index = process.argv.indexOf(name);
+ if (index < 0 || !process.argv[index + 1]) throw new Error(`missing ${name}`);
+ return process.argv[index + 1];
+}
+
+// Keep inherited records plus the named segment's records up to and including `lastLine`.
+function upTo(records: RolloutRecord[], segmentFileSuffix: string, lastLine: number): RolloutRecord[] {
+ return records.filter((record) => !record.file.endsWith(segmentFileSuffix) || record.line <= lastLine);
+}
+
+function main(): void {
+ const sample = JSON.parse(readFileSync(join(localRoot, "sample.json"), "utf8"));
+ const threads: Record<string, string> = { original: sample.originalThreadId, fork: sample.forkThreadId };
+ const segments = indexSegments(argument("--sessions"));
+ const rows = (sample.calibration as CalibrationCase[]).map(({ name, thread, segment, lastLine, logged }) => {
+ const threadId = threads[thread];
+ const segmentId = segment === "latest" ? latestSegment(segments, threadId) : threadId;
+ const all = effectiveRecords(segments, segmentId);
+ const records = lastLine === null ? all : upTo(all, `${threadId}.jsonl`, lastLine);
+ const { items, bytes } = historyBytes(records);
+ const images = inlineImages(records);
+ return {
+ name,
+ logged,
+ historyItems: items,
+ historyBytes: bytes,
+ overheadBytes: logged - bytes,
+ ratio: Number((bytes / logged).toFixed(4)),
+ inlineImages: images.length,
+ inlineImageDataUrlBytes: images.reduce((sum, image) => sum + image.dataUrlChars, 0),
+ };
+ });
+ writeFileSync(join(localRoot, "t7-calibration.json"), JSON.stringify({ createdAt: new Date().toISOString(), rows }, null, 2));
+ console.table(rows);
+}
+
+main();
diff --git a/spike/src/viewpaths.test.ts b/spike/src/viewpaths.test.ts
new file mode 100644
index 0000000..135176f
--- /dev/null
+++ b/spike/src/viewpaths.test.ts
@@ -0,0 +1,40 @@
+// Purpose: regression test for view_image path attribution when parallel calls finish out of order.
+// Input: temporary synthetic files; output: Node test assertions only.
+
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { pathForViewedImage } from "./viewpaths.ts";
+
+const sha256 = (data: string) => createHash("sha256").update(data).digest("hex");
+
+test("each output image gets the path whose bytes match, whatever the event order", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "cam-viewpaths-"));
+ try {
+ const bridge = join(dir, "bridge.png");
+ const timelapse = join(dir, "timelapse.png");
+ writeFileSync(bridge, "bridge-bytes");
+ writeFileSync(timelapse, "timelapse-bytes");
+ // Events arrived as [bridge, timelapse] while the tool output listed timelapse first.
+ const candidates = [bridge, timelapse];
+ const cache = new Map<string, string | null>();
+ assert.equal(await pathForViewedImage(candidates, sha256("timelapse-bytes"), cache), timelapse);
+ assert.equal(await pathForViewedImage(candidates, sha256("bridge-bytes"), cache), bridge);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("an image whose bytes match no candidate gets no path", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "cam-viewpaths-"));
+ try {
+ const only = join(dir, "only.png");
+ writeFileSync(only, "only-bytes");
+ assert.equal(await pathForViewedImage([only, join(dir, "missing.png")], sha256("resized-bytes"), new Map()), null);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/spike/src/viewpaths.ts b/spike/src/viewpaths.ts
new file mode 100644
index 0000000..cab3b8d
--- /dev/null
+++ b/spike/src/viewpaths.ts
@@ -0,0 +1,21 @@
+// Purpose: attribute a view_image output image to the file it came from.
+// Input: candidate paths from the same call's ImageView events and the image's byte SHA-256.
+// Output: the matching path, or null when no candidate file has the same bytes.
+
+import { createHash } from "node:crypto";
+import { createReadStream, existsSync } from "node:fs";
+
+export async function fileSha256(file: string): Promise<string> {
+ const hash = createHash("sha256");
+ for await (const chunk of createReadStream(file)) hash.update(chunk);
+ return hash.digest("hex");
+}
+
+// Parallel view_image calls complete out of order, so event order cannot be trusted for pairing.
+export async function pathForViewedImage(candidates: string[], byteSha256: string, fileHashes: Map<string, string | null>): Promise<string | null> {
+ for (const candidate of candidates) {
+ if (!fileHashes.has(candidate)) fileHashes.set(candidate, existsSync(candidate) ? await fileSha256(candidate) : null);
+ if (fileHashes.get(candidate) === byteSha256) return candidate;
+ }
+ return null;
+}
diff --git a/spike/tsconfig.json b/spike/tsconfig.json
new file mode 100644
index 0000000..0bc6c8b
--- /dev/null
+++ b/spike/tsconfig.json
@@ -0,0 +1,11 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "strict": true,
+ "noEmit": true,
+ "allowImportingTsExtensions": true
+ },
+ "include": ["src/**/*.ts"]
+}