feat(images) I4: store pasted images locally, and make the meter tell the truth

Local, session-attached. Nothing is uploaded. A screenshot of someone's proprietary code
never leaves their machine — which is also the only shape that works for BYOK, where the
editor talks to the provider directly and a detour through our infrastructure would add a
failure mode and contradict the promise that we are not in the middle.

WHY A SIBLING media/ DIRECTORY RATHER THAN INLINE BASE64. Claude Code inlines image bytes
in its own JSONL and that works fine there — I measured it: 24 images, all base64, in a
34MB transcript. It does not work here, for a reason specific to this codebase.
sessionStore.scanProject does readFileSync + JSON.parse on EVERY session file in a project
whenever index.json is missing, malformed, or on an older schema — first run, and after any
schema bump. Inlined bytes would make drawing a list of session titles parse every
screenshot in every session. Refs keep that scan cheap, keep the transcript greppable, and
dedupe the re-paste that follows a failed send.

Content-addressed by sha256, so the same screenshot twice is one file. Written tmp+rename,
because a crash mid-write must never leave a truncated file under a hash claiming to
describe its full contents. Capped at 5MB of bytes — the Claude API allows 10MB of base64,
Bedrock and Vertex 5MB, and base64 inflates by 4/3, so 5MB of bytes is what is safe
everywhere.

REFS ARE NOT PATHS. A ref is read straight out of a session file, which is data on disk a
user can edit. isRef pins the shape to 64 hex characters plus a known extension, and read()
returns null rather than touching anything else — `../../etc/passwd` is not a ref.

THE METER. estimateMsgTokens now counts an image by its real visual cost and excludes its
JSON entirely. chars/4 is sound for text and wrong for an image in EITHER shape: inline
base64 books about a third of its byte count (a 1MB screenshot read as ~350,000 tokens),
while a stored ref is 64 hex characters and reads as ~18 — for the same ~4,800. A test pins
that the storage shape does not move the number, which is the point of the design.

Bypass-verified, each by reverting the fix:
  - path traversal accepted as a ref
  - not content-addressed, so duplicate pastes duplicate files
  - oversize and unsupported media types accepted
  - a missing file silently becoming empty text instead of throwing
  - tmp file left behind by a non-atomic write
  - the meter counting images by JSON length again; and costing them nothing at all

11 tests in imageStore, 36 suites green.

Author: ndemianc

extensions/levelcode-ai/agentMemory.js

@@ -6,6 +6,8 @@
  *--------------------------------------------------------------------------------------------*/
 'use strict';
 
+
+const { imageBlockTokens } = require('./imageCost');
 /** A "goal boundary": a user message with plain STRING content (a fresh user turn, never a tool_result).
  *  It is the only splice point that cannot orphan a tool_use/tool_result pair — tool results always sit
  *  in the message immediately after their tool_use, so any pair is wholly on one side of such a cut. */
@@ -34,10 +36,32 @@ function findCompactionCut(msgs, keepRecent) {
 	return cut;
 }
 
-/** Rough token estimate for a message list — the house chars/4 heuristic, used only for the UI meter. */
-function estimateMsgTokens(msgs) {
+/**
+ * Rough token estimate for a message list — the house chars/4 heuristic, used only for the UI meter.
+ *
+ * Images are counted by their real visual cost, not by their JSON. chars/4 is sound for text and
+ * wrong for an image in whichever shape it takes: inline base64 books about a third of its byte
+ * count (a 1MB screenshot reads as ~333,000 tokens, more than most context windows, for something
+ * that really costs ~4,800), and a stored ref swings the other way — 64 hex characters read as ~18
+ * tokens for the same ~4,800. Both would make the meter lie about how much room is left.
+ *
+ * `modelId` picks the resolution tier; omitting it costs the standard tier, which over-counts
+ * rather than under-counts. See imageCost.js.
+ */
+function estimateMsgTokens(msgs, modelId) {
 	if (!Array.isArray(msgs)) { return 0; }
-	return Math.round(msgs.reduce((n, m) => n + JSON.stringify(m).length, 0) / 4);
+	let chars = 0;
+	let imageTokens = 0;
+	for (const m of msgs) {
+		if (!m) { continue; }
+		if (!Array.isArray(m.content)) { chars += JSON.stringify(m).length; continue; }
+		chars += 24;   // role + envelope, roughly what the object costs around its blocks
+		for (const b of m.content) {
+			if (b && b.type === 'image') { imageTokens += imageBlockTokens(b, modelId); }
+			else { chars += JSON.stringify(b).length; }
+		}
+	}
+	return Math.round(chars / 4) + imageTokens;
 }
 
 module.exports = { isGoalBoundary, findCompactionCut, estimateMsgTokens };

extensions/levelcode-ai/imageStore.js

@@ -0,0 +1,116 @@
+/*---------------------------------------------------------------------------------------------
+ *  Pasted images on disk — content-addressed, beside the session that used them.
+ *
+ *  LOCAL, SESSION-ATTACHED. Nothing is uploaded. A screenshot of someone's proprietary code
+ *  never leaves their machine, which is also the only shape that works for BYOK, where the
+ *  editor talks to the provider directly and a detour through our infrastructure would both add
+ *  a failure mode and contradict the promise that we are not in the middle.
+ *
+ *  WHY A SIBLING DIRECTORY RATHER THAN INLINE BASE64. Claude Code inlines image bytes in its
+ *  own JSONL transcript and that works fine there. It does not work here, and the reason is
+ *  specific to this codebase: sessionStore.scanProject readFileSync + JSON.parses EVERY session
+ *  file in a project whenever index.json is missing, malformed, or on an older schema — which
+ *  happens on first run and after any schema bump. Inlined bytes would make drawing a list of
+ *  session titles parse every screenshot in every session. Refs keep that scan cheap, keep the
+ *  transcript greppable, and dedupe the re-paste that follows a failed send.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/** Claude accepts exactly these. Anything else is refused before it reaches a provider. */
+const MEDIA_EXT = {
+	'image/png': 'png',
+	'image/jpeg': 'jpg',
+	'image/gif': 'gif',
+	'image/webp': 'webp'
+};
+
+/**
+ * Per-image ceiling. The Claude API's own limit is 10MB of base64 (5MB on Bedrock and Vertex),
+ * and base64 inflates by 4/3 — so 5MB of BYTES is the largest thing that is safe everywhere.
+ * Normalization should keep real pastes far under this; the cap is for the pathological file.
+ */
+const MAX_BYTES = 5 * 1024 * 1024;
+
+function mediaDir(root, slug) { return path.join(root, slug, 'media'); }
+function refPath(root, slug, ref) { return path.join(mediaDir(root, slug), ref); }
+
+/** true for a ref this module could have produced — 64 hex chars, a known extension, no path parts. */
+function isRef(ref) {
+	return typeof ref === 'string' && /^[0-9a-f]{64}\.(png|jpg|gif|webp)$/.test(ref);
+}
+
+/**
+ * Store bytes and return the ref that identifies them.
+ *
+ * Content-addressed: the same screenshot pasted twice is one file, which is exactly what happens
+ * when someone re-pastes after a send fails. Writing is skipped when the file already exists, so
+ * a duplicate paste costs a hash and a stat.
+ */
+function put(root, slug, base64, mediaType) {
+	const ext = MEDIA_EXT[mediaType];
+	if (!ext) { throw new Error('imageStore: unsupported media type: ' + String(mediaType)); }
+	const buf = Buffer.from(String(base64 || ''), 'base64');
+	if (!buf.length) { throw new Error('imageStore: empty image'); }
+	if (buf.length > MAX_BYTES) {
+		throw new Error('imageStore: image is ' + Math.round(buf.length / 1024) + 'KB, over the '
+			+ Math.round(MAX_BYTES / 1024) + 'KB limit');
+	}
+	const ref = crypto.createHash('sha256').update(buf).digest('hex') + '.' + ext;
+	const dest = refPath(root, slug, ref);
+	if (!fs.existsSync(dest)) {
+		fs.mkdirSync(mediaDir(root, slug), { recursive: true });
+		// tmp + rename: a crash mid-write must never leave a truncated file under a hash that
+		// claims to describe its full contents.
+		const tmp = dest + '.' + process.pid + '.tmp';
+		fs.writeFileSync(tmp, buf);
+		fs.renameSync(tmp, dest);
+	}
+	return { ref, bytes: buf.length };
+}
+
+/** Read bytes back as base64 for a provider request. Returns null when the file is gone. */
+function read(root, slug, ref) {
+	if (!isRef(ref)) { return null; }
+	try { return fs.readFileSync(refPath(root, slug, ref)).toString('base64'); }
+	catch { return null; }
+}
+
+/** The media type a ref implies, from its extension. */
+function mediaTypeOf(ref) {
+	if (!isRef(ref)) { return null; }
+	const ext = ref.slice(ref.lastIndexOf('.') + 1);
+	return Object.keys(MEDIA_EXT).find((k) => MEDIA_EXT[k] === ext) || null;
+}
+
+/**
+ * A stored `{type:'image', ref, …}` block → the Anthropic wire block, bytes and all.
+ *
+ * Called only when a request is being built, and the result is never retained: the conversation,
+ * the session log and the token meter all keep the ref. Throws when the file is missing, because
+ * a request that silently drops its subject is the failure this whole feature exists to avoid.
+ */
+function materialize(root, slug, block) {
+	if (!block || block.type !== 'image') { return block; }
+	if (block.source) { return block; }   // already materialized (or an inline block from elsewhere)
+	const data = read(root, slug, block.ref);
+	if (!data) { throw new Error('imageStore: attached image is missing from disk: ' + String(block.ref)); }
+	return { type: 'image', source: { type: 'base64', media_type: mediaTypeOf(block.ref), data } };
+}
+
+/** Refs still referenced by these messages — the keep-set for a sweep. */
+function refsIn(msgs) {
+	const out = new Set();
+	for (const m of (Array.isArray(msgs) ? msgs : [])) {
+		for (const b of (Array.isArray(m && m.content) ? m.content : [])) {
+			if (b && b.type === 'image' && isRef(b.ref)) { out.add(b.ref); }
+		}
+	}
+	return out;
+}
+
+module.exports = { MEDIA_EXT, MAX_BYTES, mediaDir, refPath, isRef, put, read, mediaTypeOf, materialize, refsIn };

extensions/levelcode-ai/test/imageStore.test.js

@@ -0,0 +1,122 @@
+/*---------------------------------------------------------------------------------------------
+ *  Local image store + the meter that counts what it holds — run: node test/imageStore.test.js
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const S = require('../imageStore');
+const { estimateMsgTokens } = require('../agentMemory');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'lc-img-'));
+const slug = 'proj';
+const png = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex').toString('base64');
+
+test('ROUND TRIP: bytes go in, the same bytes come back', () => {
+	const { ref, bytes } = S.put(root, slug, png, 'image/png');
+	assert.ok(S.isRef(ref), 'ref should be sha256 + extension: ' + ref);
+	assert.strictEqual(bytes, Buffer.from(png, 'base64').length);
+	assert.strictEqual(S.read(root, slug, ref), png);
+	assert.strictEqual(S.mediaTypeOf(ref), 'image/png');
+});
+
+test('CONTENT ADDRESSED: the same screenshot twice is one file', () => {
+	// Exactly what happens when someone re-pastes after a send fails.
+	const a = S.put(root, slug, png, 'image/png');
+	const b = S.put(root, slug, png, 'image/png');
+	assert.strictEqual(a.ref, b.ref);
+	const files = fs.readdirSync(S.mediaDir(root, slug)).filter((f) => f.endsWith('.png'));
+	assert.strictEqual(files.length, 1, 'a duplicate paste must not write a second file');
+});
+
+test('CONTENT ADDRESSED: different bytes get different refs', () => {
+	const other = Buffer.from('ffd8ffe000104a464946', 'hex').toString('base64');
+	assert.notStrictEqual(S.put(root, slug, png, 'image/png').ref,
+		S.put(root, slug, other, 'image/jpeg').ref);
+});
+
+test('NO TMP LEFT BEHIND: a completed write leaves only the final file', () => {
+	assert.ok(!fs.readdirSync(S.mediaDir(root, slug)).some((f) => f.includes('.tmp')),
+		'tmp+rename must not leave a .tmp file behind');
+});
+
+test('REFUSED: unsupported media type, empty bytes, and oversize', () => {
+	assert.throws(() => S.put(root, slug, png, 'image/tiff'), /unsupported media type/);
+	assert.throws(() => S.put(root, slug, png, 'image/svg+xml'), /unsupported media type/);
+	assert.throws(() => S.put(root, slug, '', 'image/png'), /empty image/);
+	const huge = Buffer.alloc(S.MAX_BYTES + 1).toString('base64');
+	assert.throws(() => S.put(root, slug, huge, 'image/png'), /over the/);
+});
+
+test('REFS ARE NOT PATHS: traversal and junk are rejected, not read', () => {
+	// read() takes a ref straight from a session file, which is data on disk that a user could edit.
+	for (const bad of ['../../etc/passwd', '../secrets.png', 'a/b.png', 'notahash.png',
+		'a'.repeat(64) + '.exe', 'a'.repeat(63) + '.png', '', null, undefined]) {
+		assert.strictEqual(S.isRef(bad), false, 'should not look like a ref: ' + String(bad));
+		assert.strictEqual(S.read(root, slug, bad), null, 'must not read: ' + String(bad));
+		assert.strictEqual(S.mediaTypeOf(bad), null);
+	}
+});
+
+test('MATERIALIZE: a ref becomes a wire block only when a request is built', () => {
+	const { ref } = S.put(root, slug, png, 'image/png');
+	const out = S.materialize(root, slug, { type: 'image', ref, w: 100, h: 50 });
+	assert.deepStrictEqual(out, { type: 'image', source: { type: 'base64', media_type: 'image/png', data: png } });
+	// already-materialized blocks pass through untouched
+	const inline = { type: 'image', source: { type: 'url', url: 'https://x.test/a.png' } };
+	assert.strictEqual(S.materialize(root, slug, inline), inline);
+	assert.deepStrictEqual(S.materialize(root, slug, { type: 'text', text: 'hi' }), { type: 'text', text: 'hi' });
+});
+
+test('MATERIALIZE: a missing file throws rather than sending a request without its subject', () => {
+	assert.throws(
+		() => S.materialize(root, slug, { type: 'image', ref: 'b'.repeat(64) + '.png' }),
+		/missing from disk/,
+		'a silently dropped image is the exact failure this feature exists to avoid'
+	);
+});
+
+test('REFS IN: the keep-set sees every attached image and nothing else', () => {
+	const r1 = 'a'.repeat(64) + '.png', r2 = 'c'.repeat(64) + '.webp';
+	const got = S.refsIn([
+		{ role: 'user', content: [{ type: 'image', ref: r1 }, { type: 'text', text: 'x' }] },
+		{ role: 'user', content: 'a plain string turn' },
+		{ role: 'user', content: [{ type: 'image', ref: r2 }, { type: 'image', ref: '../evil' }] }
+	]);
+	assert.deepStrictEqual([...got].sort(), [r1, r2].sort());
+});
+
+test('METER: the storage shape does not change the number', () => {
+	// This is the point of the whole design. An image costs what it costs; whether the bytes are
+	// inline or on disk behind a ref must not move the meter.
+	const big = 'A'.repeat(1_400_000);
+	const inline = [{ role: 'user', content: [
+		{ type: 'image', source: { type: 'base64', media_type: 'image/png', data: big } },
+		{ type: 'text', text: 'why?' }] }];
+	const ref = [{ role: 'user', content: [
+		{ type: 'image', ref: 'a'.repeat(64) + '.png', w: 3840, h: 2160 },
+		{ type: 'text', text: 'why?' }] }];
+
+	const a = estimateMsgTokens(inline, 'claude-opus-5');
+	const b = estimateMsgTokens(ref, 'claude-opus-5');
+	assert.strictEqual(a, b, 'inline and ref must cost the same');
+	assert.ok(a < 6000, 'a 1MB image must not book six figures of tokens — got ' + a);
+	assert.ok(a > 4000, 'nor may it be under-counted as a short string — got ' + a);
+	assert.ok(estimateMsgTokens(ref, 'gpt-4o') < b, 'the standard tier costs less than high-res');
+});
+
+test('METER: text-only messages are unchanged by any of this', () => {
+	const msgs = [{ role: 'user', content: 'hello there' }, { role: 'assistant', content: 'hi' }];
+	assert.strictEqual(estimateMsgTokens(msgs), Math.round(
+		msgs.reduce((n2, m) => n2 + JSON.stringify(m).length, 0) / 4),
+		'the old heuristic must still hold exactly for text');
+});
+
+try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+console.log('\nimageStore: ' + n + ' tests passed.');