feat(sessions): sessionEvents.js — verbatim message<->event translation (pure)

Third slice, completing the pure sessions engine. The seam between the live
agent's provider messages and the stored session events, so extension.js stays
thin glue:
- toolStatsFromMessages derives the sparkline (tool-calls/turn) and files-edited
  straight from a turn's messages — one source of truth, the transcript.
- userTurnEvent/agentTurnEvent/end/title/label build the append-only events.
- eventsToMessages rebuilds the messages array BYTE-IDENTICALLY (verbatim,
  lossless resume — design §4); tailFrom appends only the per-turn delta.

Tested incl. a cross-module check that events built here derive the right card
in sessionStore. sessionEvents: 6 tests. Full suite: 30 suites, 0 failures.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ndemianc

extensions/levelcode-ai/sessionEvents.js

@@ -0,0 +1,99 @@
+// @ts-check
+'use strict';
+
+/*
+ * sessionEvents.js — the pure translation between the live agent's provider MESSAGES and the stored
+ * session EVENTS. It is the seam that lets extension.js stay thin glue: the agent loop hands us the
+ * messages it already has; we hand back event objects to append (sessionStore.appendEvent) and, on
+ * resume, rebuild the exact messages array back.
+ *
+ * Two guarantees, both tested:
+ *   • VERBATIM & LOSSLESS. Events store provider message shapes as-is, so `eventsToMessages(...)` rebuilds
+ *     a byte-identical array — verbatim resume sees precisely the conversation it left (design §4 rules).
+ *   • The card data is DERIVED, not hand-passed. `toolStatsFromMessages` reads the sparkline (tool-calls
+ *     per turn) and files-edited straight out of the turn's messages, so the extension never computes or
+ *     duplicates them — one source of truth (the transcript).
+ */
+
+/** Tool names that MUTATE files → count as "edited" for the files-touched chip (not read/list/run). */
+const EDIT_TOOLS = new Set(['edit_file', 'write_file']);
+
+// ── read stats out of a turn's messages (pure) ───────────────────────────────────────────────────
+
+/**
+ * Walk a messages array and pull { tools, edits } from its assistant `tool_use` blocks:
+ *   tools — total tool calls (the sparkline height for the turn);
+ *   edits — one `{ path }` per edit_file/write_file call (repeats kept, so "most-edited" ordering survives).
+ * Tolerant of any shape — a message without array content, a tool_use without input, etc.
+ */
+function toolStatsFromMessages(messages) {
+	let tools = 0;
+	const edits = [];
+	for (const m of (Array.isArray(messages) ? messages : [])) {
+		if (!m || m.role !== 'assistant' || !Array.isArray(m.content)) { continue; }
+		for (const b of m.content) {
+			if (!b || b.type !== 'tool_use') { continue; }
+			tools++;
+			if (EDIT_TOOLS.has(b.name) && b.input && typeof b.input.path === 'string') { edits.push({ path: b.input.path }); }
+		}
+	}
+	return { tools, edits };
+}
+
+// ── build events to append (pure) ────────────────────────────────────────────────────────────────
+
+/** The user turn: `content` for preview/title/turn-count, `messages` (verbatim) for the rebuild. */
+function userTurnEvent(userMessage, t) {
+	const content = userMessage && typeof userMessage.content === 'string' ? userMessage.content
+		: (userMessage && userMessage.content != null ? userMessage.content : '');
+	return { kind: 'user', t: t || null, content, messages: userMessage ? [userMessage] : [] };
+}
+
+/**
+ * The agent turn: the NEW messages the loop produced this turn (assistant + tool_result messages),
+ * stored verbatim, plus the model and the derived tool/edit stats the card reads.
+ */
+function agentTurnEvent(newMessages, model, t) {
+	const msgs = Array.isArray(newMessages) ? newMessages : [];
+	const { tools, edits } = toolStatsFromMessages(msgs);
+	return { kind: 'agent', t: t || null, model: model || null, messages: msgs, tools, edits };
+}
+
+function endEvent(state, t) { return { kind: 'end', t: t || null, state: state || 'done' }; }
+function titleEvent(title, t) { return { kind: 'title', t: t || null, title: String(title == null ? '' : title) }; }
+/** A lifecycle/pin change — append-only, so archiving/pinning never rewrites the file (experience §4.9). */
+function labelEvent(fields, t) {
+	const e = { kind: 'label', t: t || null };
+	if (fields && fields.lifecycle) { e.lifecycle = String(fields.lifecycle); }
+	if (fields && typeof fields.pinned === 'boolean') { e.pinned = fields.pinned; }
+	return e;
+}
+
+// ── rebuild messages on resume (pure — the verbatim guarantee) ───────────────────────────────────
+
+/**
+ * Concatenate the stored `messages` from every transcript event, in order, into the provider messages
+ * array the agent loop resumes from. Non-transcript events (title/label/end/compact) carry no messages
+ * and are skipped, so the rebuild is exactly the conversation — nothing more, nothing lost.
+ */
+function eventsToMessages(events) {
+	const out = [];
+	for (const e of (Array.isArray(events) ? events : [])) {
+		if (e && Array.isArray(e.messages)) { for (const m of e.messages) { out.push(m); } }
+	}
+	return out;
+}
+
+/** How many messages are already persisted — so a per-turn append stores only the new tail, not the lot. */
+function tailFrom(messages, storedCount) {
+	const msgs = Array.isArray(messages) ? messages : [];
+	const from = Number.isFinite(storedCount) && storedCount > 0 ? storedCount : 0;
+	return msgs.slice(from);
+}
+
+module.exports = {
+	EDIT_TOOLS,
+	toolStatsFromMessages,
+	userTurnEvent, agentTurnEvent, endEvent, titleEvent, labelEvent,
+	eventsToMessages, tailFrom
+};

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

@@ -0,0 +1,96 @@
+/*---------------------------------------------------------------------------------------------
+ *  sessionEvents — message ⇄ event translation — run: node test/sessionEvents.test.js
+ *
+ *  Two guarantees: (1) VERBATIM — messages → events → messages is byte-identical, so a verbatim resume
+ *  sees exactly what it left; (2) the card stats (sparkline, files-edited) are DERIVED from the turn's
+ *  own messages, not hand-passed — so they can't drift from the transcript. The last test wires this to
+ *  sessionStore.deriveEntry to prove the two modules agree end-to-end.
+ *--------------------------------------------------------------------------------------------*/
+// @ts-check
+'use strict';
+
+const assert = require('assert');
+const E = require('../sessionEvents');
+const S = require('../sessionStore');
+
+let n = 0;
+function test(name, fn) { fn(); n++; console.log('  ok - ' + name); }
+
+// A realistic agent turn: read one file, then edit two, then answer.
+function conversation() {
+	return [
+		{ role: 'user', content: 'add idempotency to refunds' },
+		{ role: 'assistant', content: [{ type: 'text', text: 'reading' }, { type: 'tool_use', id: 'a', name: 'read_file', input: { path: 'refund.rb' } }] },
+		{ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'a', content: '…' }] },
+		{ role: 'assistant', content: [
+			{ type: 'tool_use', id: 'b', name: 'edit_file', input: { path: 'refund.rb' } },
+			{ type: 'tool_use', id: 'c', name: 'write_file', input: { path: 'redis_lock.rb' } }
+		] },
+		{ role: 'user', content: [{ type: 'tool_result', tool_use_id: 'b' }, { type: 'tool_result', tool_use_id: 'c' }] },
+		{ role: 'assistant', content: 'Done: idempotent refunds via Redis keys' }
+	];
+}
+
+test('STATS: tool count is the sparkline; only edit_file/write_file count as files edited', () => {
+	const { tools, edits } = E.toolStatsFromMessages(conversation());
+	assert.strictEqual(tools, 3, 'read_file + edit_file + write_file = 3 tool calls');
+	assert.deepStrictEqual(edits, [{ path: 'refund.rb' }, { path: 'redis_lock.rb' }], 'the read is not an edit');
+	assert.deepStrictEqual(E.toolStatsFromMessages(null), { tools: 0, edits: [] }, 'never throws on junk');
+});
+
+test('BUILD: user/agent events carry content + verbatim messages + derived stats', () => {
+	const msgs = conversation();
+	const u = E.userTurnEvent(msgs[0], 't1');
+	assert.strictEqual(u.kind, 'user');
+	assert.strictEqual(u.content, 'add idempotency to refunds');
+	assert.deepStrictEqual(u.messages, [msgs[0]]);
+
+	const a = E.agentTurnEvent(msgs.slice(1), 'anthropic/claude-opus-5', 't2');
+	assert.strictEqual(a.kind, 'agent');
+	assert.strictEqual(a.model, 'anthropic/claude-opus-5');
+	assert.strictEqual(a.tools, 3);
+	assert.deepStrictEqual(a.messages, msgs.slice(1), 'the turn is stored verbatim');
+});
+
+test('VERBATIM: messages → events → eventsToMessages is byte-identical (lossless resume)', () => {
+	const msgs = conversation();
+	const events = [E.userTurnEvent(msgs[0], 't1'), E.agentTurnEvent(msgs.slice(1), 'm', 't2')];
+	assert.deepStrictEqual(E.eventsToMessages(events), msgs, 'rebuild == original, exactly');
+	// non-transcript events contribute nothing to the rebuild
+	const withMeta = events.concat([E.titleEvent('T', 't3'), E.labelEvent({ pinned: true }, 't4'), E.endEvent('done', 't5')]);
+	assert.deepStrictEqual(E.eventsToMessages(withMeta), msgs, 'title/label/end carry no messages');
+});
+
+test('TAIL: only the new messages since the stored count are appended (incremental, not the whole lot)', () => {
+	const msgs = conversation();
+	assert.deepStrictEqual(E.tailFrom(msgs, 3), msgs.slice(3));
+	assert.deepStrictEqual(E.tailFrom(msgs, 0), msgs);
+	assert.deepStrictEqual(E.tailFrom(msgs, msgs.length), []);
+});
+
+test('LABEL: archiving/pinning is an append-only event, never a rewrite', () => {
+	assert.deepStrictEqual(E.labelEvent({ lifecycle: 'archived' }, 't'), { kind: 'label', t: 't', lifecycle: 'archived' });
+	assert.deepStrictEqual(E.labelEvent({ pinned: true }, 't'), { kind: 'label', t: 't', pinned: true });
+});
+
+// ── cross-module: sessionEvents output feeds sessionStore.deriveEntry correctly ───────────────────
+
+test('END-TO-END: events built here derive the right card in sessionStore (one source of truth)', () => {
+	const msgs = conversation();
+	const meta = { kind: 'meta', v: 1, id: 's1', project: '/p', createdAt: 'c0', title: null };
+	const events = [
+		E.userTurnEvent(msgs[0], 't1'),
+		E.agentTurnEvent(msgs.slice(1), 'anthropic/claude-opus-5', 't2'),
+		E.titleEvent('Idempotent refunds via Redis keys', 't3'),
+		E.endEvent('done', 't4')
+	];
+	const card = S.deriveEntry(meta, events);
+	assert.strictEqual(card.title, 'Idempotent refunds via Redis keys');
+	assert.strictEqual(card.turns, 1);
+	assert.strictEqual(card.model, 'anthropic/claude-opus-5');
+	assert.strictEqual(card.state, 'done');
+	assert.deepStrictEqual(card.spark, [3], 'the sparkline came from the turn messages via the agent event');
+	assert.deepStrictEqual(card.filesEdited, ['refund.rb', 'redis_lock.rb'], 'and so did the files-edited chips');
+});
+
+console.log('sessionEvents: ' + n + ' tests passed');