@sanqianx/ai-coding-event-bridge-console 0.5.1 → 0.7.0

package/README.md

@@ -48,6 +48,15 @@ otherwise.
 | `GET /api/turns?project&date&cursor&limit` | Merged turns + `annotations` (commit shas per turn) |
 | `GET /api/sessions?project=` | Session index |
 | `GET /api/search?q&project&limit` | Substring search over conversation bodies |
+| `GET /api/journals` | Global and registered project journal identities |
+| `POST /api/internal/workbench-event` | Private native Workbench capture; runtime token, loopback, no browser Origin |
+
+The private capture route uses `KB_EVENT_BRIDGE_RUNTIME_TOKEN`. It resolves the
+Git identity and requires an already registered code directory. Stable event
+keys deduplicate retries; only original prompts, successful final answers and
+turn endings enter the same bridge journal used by hooks. Credentials and
+injected knowledge are not accepted as event metadata. Shell proxies must not
+expose this route to browser callers.
 
 Turn merging: for a registered project, the project journal and the global
 journal (legacy pre-import events) are both read, filtered by repo identity,
@@ -57,7 +66,9 @@ one journal's sequence space; `openTurnIdsAtCommit` binding works across both.
 ## Notes
 
 - Node >= 18, CommonJS, zero runtime dependencies beyond the core package.
-- The console never writes journals; it only reads them and mutates
-  `projects.json` on import/unregister.
-- Consumer-cursor compaction applies to the global journal only — project
-  journals are archival stores and are not auto-compacted.
+- Public query APIs read journals; project import/unregister changes registration.
+  The authenticated Workbench endpoint delegates capture to the core bridge,
+  not a second conversation database.
+- Consumer cursors and ACKs are journal-specific. Compaction may retire sealed
+  evidence only after every applicable consumer has acknowledged that journal;
+  creating a commit archive is not proof that the engine consumed it.

package/console/index.html

@@ -185,6 +185,10 @@
   .btn-upg { height: 26px; padding: 0 12px; border-radius: 7px; background: var(--text); color: #16171a; font-size: 12px; font-weight: 600; flex-shrink: 0; }
   .btn-upg:hover { background: #fff; }
   .btn-upg:disabled { opacity: .45; cursor: not-allowed; }
+  body.kb-embedded[data-kb-theme="light"] { --bg-side:#f8f9fb; --bg-main:#fff; --bg-card:#f8f9fb; --bg-input:#edf1f4; --bg-hover:#edf1f4; --bg-active:#e6edf3; --line:#dce2e8; --line-soft:#dce2e8; --text:#202733; --text-2:#687587; --text-3:#8e99a7; --label:#687587; --blue:#516f89; --green:#397761; --red:#a05252; color-scheme:light; }
+  body.kb-embedded[data-kb-theme="dark"] { --bg-side:#1b2028; --bg-main:#20252d; --bg-card:#252b34; --bg-input:#2c333e; --bg-hover:#2c333e; --bg-active:#293748; --line:#39424f; --line-soft:#39424f; --text:#e6ebf0; --text-2:#a0aaba; --text-3:#788393; --label:#a0aaba; --blue:#8aa8cf; --green:#81b29a; --red:#d88b8b; color-scheme:dark; }
+  body.kb-embedded .topbar h1 { display:none; }
+  body.kb-embedded .topbar { padding:8px 24px; }
 </style>
 </head>
 <body>
@@ -226,7 +230,7 @@
         <span class="svg-i" data-i="gear"></span>
       </button>
       <div class="hist-wrap">
-        <button class="hist-btn" id="hist-btn">🕘 历史</button>
+        <button class="hist-btn" id="hist-btn">历史</button>
         <div class="hist-pop" id="hist-pop">
           <div class="ph">历史对话</div>
           <div id="hist-list"></div>
@@ -333,8 +337,14 @@ function toast(ok, text) {
   }, 3200);
 }
 
+var embedQuery = new URLSearchParams(location.search);
+var embedded = embedQuery.get('embed') === '1';
+var moduleApiBase = /^\/api\/[a-z0-9/-]+$/i.test(embedQuery.get('apiBase') || '') ? embedQuery.get('apiBase').replace(/\/$/, '') : '/api';
+var projectEpoch = 0;
+var selectionEpoch = 0;
+var embedVisible = true;
 function api(path, options) {
-  return fetch(path, options).then(function (res) {
+  return fetch(path.replace(/^\/api(?=\/|$)/, moduleApiBase), options).then(function (res) {
     return res.text().then(function (body) {
       var payload = null;
       try { payload = body ? JSON.parse(body) : null; } catch (_) { payload = null; }
@@ -376,7 +386,7 @@ function timeOf(iso) {
   return String(d.getHours()).padStart(2, '0') + ':' + String(d.getMinutes()).padStart(2, '0');
 }
 
-var SOURCE_LABELS = { 'claude-code': 'Claude', claude: 'Claude', codex: 'Codex', opencode: 'OpenCode' };
+var SOURCE_LABELS = { 'claude-code': 'Claude', claude: 'Claude', codex: 'Codex', opencode: 'OpenCode', zcode: 'ZCode' };
 
 /* ---------- 状态 ---------- */
 
@@ -490,6 +500,7 @@ function loadMoreTurns() {
 
 function fetchTurns(options) {
   if (!state.project) return Promise.resolve();
+  var epoch = projectEpoch;
   var append = options && options.append;
   state.loadingTurns = true;
   if (!append) { state.turns = []; state.cursor = null; }
@@ -498,13 +509,14 @@ function fetchTurns(options) {
     + '&order=desc'
     + (state.cursor ? '&cursor=' + encodeURIComponent(state.cursor) : '');
   return api(query).then(function (payload) {
-    if (!state.project || payload.project !== state.project.id) return; // 切换已发生，丢弃过期响应
+    if (epoch !== projectEpoch || !state.project || payload.project !== state.project.id) return;
     state.turns = state.turns.concat(payload.turns || []);
     state.cursor = payload.nextCursor || null;
     state.totalTurns = payload.totalTurns || state.turns.length;
     state.loadingTurns = false;
     renderLive();
   }).catch(function (err) {
+    if (epoch !== projectEpoch) return;
     state.loadingTurns = false;
     renderLive();
     toast(false, '加载对话失败：' + err.message);
@@ -514,6 +526,7 @@ function fetchTurns(options) {
 function selectProject(id, options) {
   var project = state.projects.find(function (p) { return p.id === id; });
   if (!project) return;
+  projectEpoch++;
   state.project = project;
   state.turns = [];
   state.cursor = null;
@@ -688,13 +701,14 @@ document.getElementById('hist-list').addEventListener('click', function (ev) {
   document.getElementById('back-btn').classList.add('show');
   showDocLoading(true);
   // 懒加载：此刻才请求这一份文档，其余历史永不加载
-  fetch('/api/commits/' + encodeURIComponent(file) + '?project=' + encodeURIComponent(state.project.id))
+  var epoch = projectEpoch;
+  fetch(moduleApiBase + '/commits/' + encodeURIComponent(file) + '?project=' + encodeURIComponent(state.project.id))
     .then(function (res) {
       if (!res.ok) throw new Error('HTTP ' + res.status);
       return res.text();
     })
     .then(function (text) {
-      if (state.currentDocFile !== file) return; // 已切换到别的文档/项目
+      if (epoch !== projectEpoch || state.currentDocFile !== file) return;
       var parsed = parseSealedDoc(text);
       var title = doc.subject || parsed.fm.subject || (parsed.fm.commitSha || file).slice(0, 12);
       var subParts = [];
@@ -901,20 +915,32 @@ setInterval(loadHealth, 30000);
  * URL 参数：?embed=1 进入嵌入态（默认折叠，sidebar=1 保持展开）。
  * 就绪后回发 {type:'kb:ready', app:'event-bridge'}；独立打开时不受控、侧栏恒显。 */
 function embedAllowedOrigin(origin) {
-  if (origin === 'null') return true; // file:// 壳
-  try { const u = new URL(origin); return u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]'; }
+  try { return origin === (document.referrer ? new URL(document.referrer).origin : location.origin); }
   catch { return false; }
 }
 function setEmbedSideVisible(visible) { document.body.classList.toggle('embed-collapse', !visible); }
-window.addEventListener('message', function (ev) {
-  if (!embedAllowedOrigin(ev.origin)) return;
+window.addEventListener('message', async function (ev) {
+  if (ev.source !== window.parent || !embedAllowedOrigin(ev.origin)) return;
   const d = ev.data;
   if (!d || typeof d !== 'object') return;
+  if (d.type === 'kb:theme') { document.body.dataset.kbTheme = d.theme === 'dark' ? 'dark' : 'light'; return; }
+  if (d.type === 'kb:visibility') { embedVisible = d.visible === true; return; }
+  if (d.type === 'kb:refresh' && embedVisible && state.project) { fetchTurns(); refreshHist(); return; }
+  if (d.type === 'kb:select-project') {
+    var requestEpoch = ++selectionEpoch;
+    var find = function () { return state.projects.find(function (p) { return p.id === d.project || p.path === d.project; }); };
+    if (!find()) await loadProjects();
+    if (requestEpoch !== selectionEpoch) return;
+    var p = find();
+    if (p) selectProject(p.id);
+    ev.source.postMessage({ type: 'kb:projects', app: 'event-bridge', ok: !!p, projectId: p && p.id, requestId: d.requestId }, ev.origin);
+    return;
+  }
   if (d.type === 'kb:sidebar') setEmbedSideVisible(!!d.visible);
 });
 (function () {
   const q = new URLSearchParams(location.search);
-  if (q.get('embed') === '1') setEmbedSideVisible(q.get('sidebar') !== '1');
+  if (q.get('embed') === '1') { document.body.classList.add('kb-embedded'); document.body.dataset.kbTheme = q.get('theme') === 'dark' ? 'dark' : 'light'; setEmbedSideVisible(q.get('sidebar') === '1'); }
   if (window.parent !== window) window.parent.postMessage({ type: 'kb:ready', app: 'event-bridge' }, '*');
 })();
 </script>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanqianx/ai-coding-event-bridge-console",
-  "version": "0.5.1",
-  "description": "Local console for the AI coding event bridge: project import with per-project journal storage, REST query API and a built-in conversation explorer page.",
+  "version": "0.7.0",
+  "description": "Durable AI coding event bridge, all in one: capture connectors and installers (Claude Code, Codex, OpenCode, ZCode), journal with commit boundaries and per-commit conversation sealing, headless query, and a local conversation explorer console.",
   "license": "MIT",
   "private": false,
   "repository": {
@@ -22,8 +22,5 @@
   ],
   "scripts": {
     "test": "node ../../test/run-all.js"
-  },
-  "dependencies": {
-    "@sanqianx/ai-coding-event-bridge": "0.5.0"
   }
 }

package/src/agent-detect.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
-const core = require('@sanqianx/ai-coding-event-bridge');
+const core = require('./bridge');
 
 /**
  * Detection of AI coding agent tools on this machine. "Installed" means the

package/src/bin.js

@@ -2,17 +2,21 @@
 'use strict';
 
 const http = require('http');
-const { bridgeHome } = require('@sanqianx/ai-coding-event-bridge');
+const { bridgeHome } = require('./bridge');
 const { createConsoleServer } = require('./server');
 const { warmFolderPicker } = require('./pick-folder');
 
 /**
- * ai-coding-event-bridge-console CLI (also reachable as
- * `ai-coding-event-bridge serve` via the core package's dispatcher).
+ * ai-coding-event-bridge-console CLI — the single package of this project.
  *
  *   serve [--port 8790] [--host 127.0.0.1] [--home DIR]
  *         Start the local console (explorer page + JSON API).
  *
+ *   commit-boundary [--cwd <repo>] [--home DIR] [--sha] [--branch]
+ *                   [--committed-at ISO] [--subject TEXT]
+ *       Append one commit boundary event — the call a managed git
+ *       post-commit hook makes.
+ *
  * The server binds to localhost by default: journals contain full
  * conversation bodies, so they stay on this machine unless --host says
  * otherwise.
@@ -24,8 +28,23 @@ async function main(argv = process.argv.slice(2)) {
     return i >= 0 ? argv[i + 1] : undefined;
   };
 
+  if (command === 'commit-boundary') {
+    // The boundary entry reads its own flags from process.argv; the extra
+    // positional is ignored by its --flag lookup. The contract is one JSON
+    // line (ok:true/false) on stdout, preserved even when required from here.
+    await require('./bridge/bin/commit-boundary').main().catch((err) => {
+      process.stderr.write(`${JSON.stringify({ ok: false, error: err && err.message ? err.message : String(err) })}\n`);
+      process.exitCode = 1;
+    });
+    return;
+  }
+
   if (command !== 'serve') {
-    console.log('Usage: ai-coding-event-bridge-console serve [--port 8790] [--host 127.0.0.1] [--home DIR]');
+    console.log('Usage: ai-coding-event-bridge-console <command> [options]');
+    console.log('  serve            Start the local console (explorer page + JSON API)');
+    console.log('                     --port 8790  --host 127.0.0.1  --home DIR');
+    console.log('  commit-boundary  Append one commit boundary event (git post-commit hooks)');
+    console.log('                     --cwd <repo>  --home DIR  --sha  --branch');
     process.exitCode = command ? 1 : 0;
     return;
   }
@@ -33,8 +52,12 @@ async function main(argv = process.argv.slice(2)) {
   const home = bridgeHome(get('home'));
   const port = Number(get('port') || 8790);
   const host = get('host') || '127.0.0.1';
-  const server = http.createServer(createConsoleServer({ home }));
+  const server = http.createServer(createConsoleServer({ home, runtimeToken: process.env.KB_EVENT_BRIDGE_RUNTIME_TOKEN }));
   await new Promise((resolve) => server.listen(port, host, resolve));
+  let stopping = false;
+  const stop = () => { if (stopping) return; stopping = true; server.closeAllConnections?.(); server.close(() => process.exit(0)); };
+  for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, stop);
+  process.on('message', message => { if (message?.type === 'kb:shutdown') stop(); });
   console.log(`ai-coding-event-bridge console serving on http://${host}:${port}`);
   console.log(`  home: ${home}`);
   console.log(`  import projects from the sidebar; conversations of imported`);

package/src/bridge/bin/commit-boundary.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Bridge commit-boundary injection point. Any git hook (or a human, or a
+ * test) can signal "this repo just committed" by running:
+ *
+ *   node commit-boundary.js --cwd <repo> [--home <bridge home>]
+ *                           [--sha <sha>] [--branch <name>] [--committed-at <iso>]
+ *
+ * The repo identity is resolved from the working tree (that is how the bridge
+ * knows which registered project — and therefore which store — the commit
+ * belongs to). Facts not provided are read from the repo's git. Output is a
+ * single JSON line on stdout; errors exit non-zero so callers can distinguish
+ * a failed injection from a skip.
+ */
+
+const { execFileSync } = require('child_process');
+const { resolveRepoContext } = require('../core/repo-context');
+const { createBridge } = require('../core/bridge');
+
+function arg(name, fallback = '') {
+  const prefix = `--${name}`;
+  const argv = process.argv.slice(2);
+  const index = argv.indexOf(prefix);
+  if (index === -1) return fallback;
+  const value = argv[index + 1];
+  return value === undefined || value.startsWith('--') ? fallback : value;
+}
+
+function git(cwd, args) {
+  return String(execFileSync('git', args, { cwd, windowsHide: true, encoding: 'utf8' })).trim();
+}
+
+async function main() {
+  const cwd = arg('cwd', process.cwd());
+  const repo = await resolveRepoContext(cwd);
+  if (!repo || !repo.repoIdentity) {
+    throw new Error(`not a Git work tree (no repo identity): ${cwd}`);
+  }
+  const commitSha = arg('sha') || git(cwd, ['rev-parse', 'HEAD']);
+  const branch = arg('branch') || git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const committedAt = arg('committed-at') || git(cwd, ['log', '-1', '--format=%cI']);
+  const subject = arg('subject') || git(cwd, ['log', '-1', '--format=%s']);
+  const homeDir = arg('home') || undefined;
+  const bridge = createBridge(homeDir ? { homeDir } : {});
+  const result = await bridge.appendCommitBoundary({
+    repoIdentity: repo.repoIdentity,
+    commitSha,
+    branch,
+    subject,
+    committedAt: committedAt || undefined
+  });
+  process.stdout.write(`${JSON.stringify({ ok: true, projectPath: repo.projectPath, ...result })}\n`);
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`${JSON.stringify({ ok: false, error: err && err.message ? err.message : String(err) })}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/bridge/connectors/capture-guard.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Capture-disable guard. Project-Knowledge (or any host) marks its internal
+ * AI SDK sessions with AI_CODING_EVENT_BRIDGE_CAPTURE=0 and
+ * AI_CODING_EVENT_ORIGIN. Every connector checks this FIRST — before
+ * normalization, repo Git resolution, or any journal write — so internal
+ * Workbench/Analyzer conversations never reach the durable journal.
+ */
+function isCaptureDisabled(env = process.env, payload = null) {
+  if (env && env.AI_CODING_EVENT_BRIDGE_CAPTURE === '0') {
+    return true;
+  }
+  if (payload && typeof payload === 'object' && payload.meta && typeof payload.meta === 'object') {
+    return String(payload.meta.bridgeCapture) === '0';
+  }
+  return false;
+}
+
+function captureDisabledResult() {
+  return { status: 'ignored', reason: 'capture-disabled' };
+}
+
+module.exports = { isCaptureDisabled, captureDisabledResult };

package/src/bridge/connectors/claude-code/hook-entry.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { normalizeClaudeCode } = require('../../core/normalizer');
+const { resolveRepoContext } = require('../../core/repo-context');
+const { journalFor } = require('../../core/journal-router');
+const { isCaptureDisabled, captureDisabledResult } = require('../capture-guard');
+const { notifyConsumers } = require('./notify');
+
+/**
+ * Durable-first Claude Code hook processing. The event is appended and fsynced
+ * to the Bridge journal before any consumer notification is attempted, and the
+ * whole entry fails open: a broken Bridge must never block the AI client.
+ * Internal host SDK sessions (AI_CODING_EVENT_BRIDGE_CAPTURE=0) are ignored
+ * before any Git/journal work happens.
+ */
+async function main({ home, payload }) {
+  if (isCaptureDisabled(process.env, payload)) {
+    return captureDisabledResult();
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { status: 'ignored' };
+  }
+  const event = normalizeClaudeCode(payload);
+  if (!event) {
+    return { status: 'ignored' };
+  }
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+  const repo = await resolveRepoContext(cwd);
+  const journal = journalFor(home, event.repoIdentity || repo.repoIdentity);
+  const appended = await journal.appendConversationEvent({
+    ...event,
+    repoIdentity: event.repoIdentity || repo.repoIdentity,
+    projectPath: event.projectPath || repo.projectPath,
+    branch: event.branch || repo.branch,
+    headAtCapture: event.headAtCapture || repo.headAtCapture
+  });
+  await notifyConsumers(home, { sequence: appended.sequence, eventId: appended.eventId });
+  return { status: 'captured', sequence: appended.sequence, turnId: appended.turnId };
+}
+
+function mainFailOpen({ home, payload }) {
+  return main({ home, payload }).catch(() => ({ status: 'fail-open' }));
+}
+
+module.exports = { main, mainFailOpen };

package/src/bridge/connectors/claude-code/notify.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { ConsumerRegistry } = require('../../core/consumer-registry');
+
+function postJson(url, body, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    try {
+      const target = new URL(url);
+      const mod = target.protocol === 'https:' ? https : http;
+      const data = JSON.stringify(body);
+      const req = mod.request(
+        {
+          hostname: target.hostname,
+          port: target.port || (target.protocol === 'https:' ? 443 : 80),
+          path: `${target.pathname}${target.search}`,
+          method: 'POST',
+          headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(data) },
+          timeout: timeoutMs
+        },
+        (res) => {
+          res.resume();
+          res.on('end', () => resolve({ ok: res.statusCode && res.statusCode < 500 }));
+        }
+      );
+      req.on('timeout', () => {
+        req.destroy();
+        resolve({ ok: false });
+      });
+      req.on('error', () => resolve({ ok: false }));
+      req.end(data);
+    } catch (_) {
+      resolve({ ok: false });
+    }
+  });
+}
+
+/**
+ * Best-effort wake-up for consumers that registered a notifyUrl. Always runs
+ * after the durable append; failures never propagate to the AI client.
+ */
+async function notifyConsumers(home, info) {
+  try {
+    const registry = new ConsumerRegistry(home);
+    const consumers = await registry.getConsumers();
+    const urls = consumers
+      .map((consumer) => consumer.meta && consumer.meta.notifyUrl)
+      .filter((url) => typeof url === 'string' && url);
+    await Promise.all(urls.map((url) => postJson(url, info)));
+    return { notified: urls.length };
+  } catch (_) {
+    return { notified: 0 };
+  }
+}
+
+module.exports = { notifyConsumers, postJson };

package/src/bridge/connectors/codex/cursor-store.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { writeJsonAtomicSync, readJsonIfExists, ensureDirSync } = require('../../core/fs-utils');
+
+/**
+ * Atomic per-session cursor state. One JSON file per Codex session under
+ * <home>/cursors/codex/, written via rename so a crash never corrupts it.
+ * Cursor v2 stores an independent offset and workspace context for every
+ * rollout file. A v1 cursor is upgraded in memory without resetting its
+ * consumed offset, so discovering a continuation file never replays history.
+ */
+const CURSOR_SCHEMA = 'codex-cursor/v2';
+
+function fileState(state = {}) {
+  return {
+    filePath: state.filePath,
+    byteOffset: Number.isInteger(state.byteOffset) && state.byteOffset >= 0 ? state.byteOffset : 0,
+    lastRecordKey: state.lastRecordKey || null,
+    activeCwd: state.activeCwd || null,
+    repoIdentity: state.repoIdentity || null,
+    projectPath: state.projectPath || null,
+    branch: state.branch || null,
+    headAtCapture: state.headAtCapture || null
+  };
+}
+
+function normalizeCursor(sessionId, state) {
+  const normalized = { schema: CURSOR_SCHEMA, sessionId: String(sessionId), files: {} };
+  if (!state || typeof state !== 'object') return normalized;
+
+  if (state.schema === CURSOR_SCHEMA && state.files && typeof state.files === 'object') {
+    for (const [key, value] of Object.entries(state.files)) {
+      if (!value || typeof value !== 'object' || typeof value.filePath !== 'string') continue;
+      normalized.files[key] = fileState(value);
+    }
+    return normalized;
+  }
+
+  // v1 compatibility: preserve the exact consumed offset and context. The
+  // caller supplies the canonical key after resolving the legacy file path.
+  if (typeof state.filePath === 'string' && state.filePath) {
+    normalized.legacyFile = fileState(state);
+  }
+  return normalized;
+}
+
+class CodexCursorStore {
+  constructor(homeDir) {
+    this.dir = path.join(homeDir, 'cursors', 'codex');
+    ensureDirSync(this.dir);
+  }
+
+  _fileFor(sessionId) {
+    const safe = String(sessionId).replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(this.dir, `${safe}.json`);
+  }
+
+  read(sessionId) {
+    return normalizeCursor(sessionId, readJsonIfExists(this._fileFor(sessionId)));
+  }
+
+  write(sessionId, state) {
+    const normalized = normalizeCursor(sessionId, state);
+    writeJsonAtomicSync(this._fileFor(sessionId), {
+      schema: CURSOR_SCHEMA,
+      sessionId: normalized.sessionId,
+      files: normalized.files,
+      updatedAt: new Date().toISOString()
+    });
+  }
+
+  clear(sessionId) {
+    try {
+      fs.rmSync(this._fileFor(sessionId), { force: true });
+    } catch (_) {
+      // Already gone.
+    }
+  }
+}
+
+module.exports = { CodexCursorStore, CURSOR_SCHEMA, normalizeCursor };