@volter/supercode-interchange 0.1.22 → 0.1.24

package/sqlite-reader.mjs

@@ -1,49 +1,165 @@
 import { DatabaseSync } from 'node:sqlite';
-import { fileFingerprint } from './file-io.mjs';
+import { mkdtemp, open, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileFingerprint, sameFingerprint, withSessionFile } from './file-io.mjs';
 import { sourceStat } from './store-registry.mjs';
 import { verifySources } from './source-files.mjs';
 import { parseNativeJson } from './native-json.mjs';
+import { SESSION_UNREADABLE } from './session-file.mjs';
 
-/** Only DB and WAL mutations affect the stored read mark. SHM is SQLite's
- * reader coordination file and never schedules transcript/index work. */
-export async function storeFingerprints(path) {
+const SNAPSHOT_ROW_BYTES = 256 * 1024 * 1024;
+const snapshots = new WeakMap();
+function chargeRow(snapshot, row) {
+  if (row == null) return row;
+  let bytes = 64;
+  for (const [name, value] of Object.entries(row)) {
+    bytes += 32 + name.length * 2;
+    if (typeof value === 'string') bytes += value.length * 2;
+    else if (ArrayBuffer.isView(value)) bytes += value.byteLength;
+    else if (value instanceof ArrayBuffer) bytes += value.byteLength;
+    else bytes += 8;
+  }
+  if (bytes > SNAPSHOT_ROW_BYTES - snapshot.bytes) throw Object.assign(new Error(`${snapshot.path} exceeds the foreign-store snapshot row budget (${SNAPSHOT_ROW_BYTES} charged bytes); no partial session is returned`), { code: 'EFBIG', rpcCode: SESSION_UNREADABLE });
+  snapshot.bytes += bytes;
+  return row;
+}
+function admittedStatement(prepared, snapshot) {
+  const iterate = function* (...args) { for (const row of prepared.iterate(...args)) yield chargeRow(snapshot, row); };
+  return new Proxy(prepared, { get(target, name) {
+    if (name === 'iterate') return iterate;
+    if (name === 'all') return (...args) => Array.from(iterate(...args));
+    if (name === 'get') return (...args) => chargeRow(snapshot, target.get(...args));
+    const value = Reflect.get(target, name, target);
+    return typeof value === 'function' ? value.bind(target) : value;
+  } });
+}
+
+const missing = (error) => error.code === 'ENOENT' || error.code === 'ENOTDIR';
+const changed = (path) => Object.assign(new Error(`${path} changed during its foreign-store snapshot; previous index rows are retained`), { code: 'ESTALE' });
+
+/** Native aliases follow their database target, including its adjacent WAL
+ * and rollback journal. SHM is coordination, not transcript source content. */
+async function storeSources(path) {
+  let target;
+  try { target = await realpath(path); }
+  catch (error) { if (!missing(error)) throw error; target = resolve(path); }
   const sources = [];
-  for (const file of [path, `${path}-wal`]) {
+  for (const file of [path, `${target}-wal`, `${target}-journal`]) {
     const info = await sourceStat(file);
+    if (info && !info.isFile()) throw Object.assign(new Error(`${file} is not a regular foreign-store file`), { code: 'EINVAL' });
     sources.push(info ? { path: file, fingerprint: fileFingerprint(info) } : { path: file, missing: true });
   }
-  return sources;
+  return { target, sources };
+}
+
+export async function storeFingerprints(path) {
+  return (await storeSources(path)).sources;
+}
+
+async function verifyStoreSources(path, target, sources) {
+  await verifySources(sources);
+  let current;
+  try { current = await realpath(path); } catch (error) { if (!missing(error)) throw error; }
+  if (current !== target) throw changed(path);
+}
+
+async function copySource(source, destination, metrics, snapshot) {
+  await withSessionFile(source.path, async (reader) => {
+    if (!sameFingerprint(source.fingerprint, reader.fingerprint)) throw changed(source.path);
+    const output = await open(destination, 'wx', 0o600);
+    snapshot.outputs.add(output);
+    let copyError;
+    try {
+      for (let offset = 0; offset < reader.size; offset += 64 * 1024)
+        await output.writeFile(await reader.read(offset, Math.min(64 * 1024, reader.size - offset)));
+    } catch (error) { copyError = error; throw error; }
+    finally {
+      try { await output.close(); snapshot.outputs.delete(output); }
+      catch (error) {
+        if (copyError) throw new AggregateError([copyError, error], `${source.path} snapshot copy and close failed`);
+        throw error;
+      }
+    }
+  }, metrics);
+}
+
+// A failed close/removal keeps its exact owner and private path. A later read
+// settles retained cleanup before admitting another snapshot, rather than
+// forgetting a connection or treating uncertain cleanup as successful.
+const retainedCleanup = new Map();
+let cleanupDrain;
+async function cleanupSnapshot(snapshot) {
+  for (const output of snapshot.outputs) {
+    if (output.fd !== -1) await output.close();
+    snapshot.outputs.delete(output);
+  }
+  if (snapshot.db) {
+    if (snapshot.db.isOpen !== false) snapshot.db.close();
+    snapshots.delete(snapshot.db);
+    snapshot.db = null;
+  }
+  await rm(snapshot.directory, { recursive: true, force: true });
+}
+
+async function settleCleanup() {
+  if (!retainedCleanup.size) return;
+  cleanupDrain ??= (async () => {
+    for (const [directory, snapshot] of retainedCleanup) {
+      try { await cleanupSnapshot(snapshot); retainedCleanup.delete(directory); }
+      catch (error) { throw Object.assign(new Error(`foreign-store snapshot cleanup remains incomplete at ${directory}`, { cause: error }), { code: 'FOREIGN_STORE_CLEANUP' }); }
+    }
+  })().finally(() => { cleanupDrain = null; });
+  await cleanupDrain;
 }
 
-/** One read-only connection and one synchronous snapshot. A changed DB/WAL
- * refuses the commit unit, leaving the owner's prior rows and retry visible.
+/** SQLite opens only owned private copies, never a mutable foreign pathname.
+ * Source descriptors use nonblocking admission and exact initial/final stamps;
+ * copies stream in 64 KiB ranges. A changed DB/WAL/journal refuses the whole
+ * unit. Private SHM/locks belong to this snapshot, with no foreign writes.
  * No foreign writer, journal-mode setter or extension loading is permitted. */
 export async function readStore(path, work, metrics = {}) {
-  const sources = await storeFingerprints(path);
+  await settleCleanup();
+  const { target, sources } = await storeSources(path);
   if (sources[0].missing) throw Object.assign(new Error(`${path} is not present`), { code: 'ENOENT' });
-  const db = new DatabaseSync(path, { readOnly: true, allowExtension: false });
-  metrics.stores_read = (metrics.stores_read ?? 0) + 1;
-  let result;
+  const snapshot = { directory: await mkdtemp(join(tmpdir(), 'supercode-store-')), db: null, outputs: new Set() };
+  let readError;
   try {
+    const privatePath = join(snapshot.directory, 'source.db');
+    for (const [index, suffix] of ['', '-wal', '-journal'].entries())
+      if (!sources[index].missing) await copySource(sources[index], `${privatePath}${suffix}`, metrics, snapshot);
+    await verifyStoreSources(path, target, sources);
+    const db = snapshot.db = new DatabaseSync(privatePath, { readOnly: true, allowExtension: false });
+    snapshots.set(db, { path, bytes: 0 });
+    metrics.stores_read = (metrics.stores_read ?? 0) + 1;
     db.exec('PRAGMA busy_timeout=0; BEGIN');
-    result = work(db);
+    const result = work(db);
     if (result != null && typeof result.then === 'function') throw new Error('a foreign-store snapshot must be synchronous');
     db.exec('COMMIT');
-  } finally { db.close(); }
-  await verifySources(sources);
-  return { result, sources };
+    await verifyStoreSources(path, target, sources);
+    return { result, sources };
+  } catch (error) { readError = error; throw error; }
+  finally {
+    try { await cleanupSnapshot(snapshot); }
+    catch (error) {
+      retainedCleanup.set(snapshot.directory, snapshot);
+      const failures = readError ? [readError, error] : [error];
+      throw Object.assign(new AggregateError(failures, `foreign-store snapshot cleanup incomplete at ${snapshot.directory}`), { code: 'FOREIGN_STORE_CLEANUP' });
+    }
+  }
 }
 
 export function statement(db, sql) {
   const prepared = db.prepare(sql);
   prepared.setReadBigInts(true);
-  return prepared;
+  const snapshot = snapshots.get(db);
+  return snapshot ? admittedStatement(prepared, snapshot) : prepared;
 }
 
 export function tableColumns(db, table) {
   // Callers provide only these fixed native schema identifiers.
   if (!['session', 'sessions', 'messages'].includes(table)) throw new Error('unknown catalog schema table');
-  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+  return new Set(statement(db, `PRAGMA table_info(${table})`).all().map((row) => row.name));
 }
 
 export function text(value, nullable = false) {

package/support-registry.json

@@ -0,0 +1,402 @@
+{
+  "schema": "supercode.support-registry.v1",
+  "harnesses": [
+    {
+      "id": "claude-code",
+      "display_name": "Claude Code",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "built_in",
+        "protocol": "claude-stream-json",
+        "default_launch": {
+          "program": "claude",
+          "arguments": [
+            "--print",
+            "--input-format",
+            "stream-json",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--permission-prompt-tool",
+            "stdio"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": true,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "codex",
+      "display_name": "Codex",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "built_in",
+        "protocol": "codex-app-server-jsonl",
+        "default_launch": {
+          "program": "codex",
+          "arguments": [
+            "app-server"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": true,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "opencode",
+      "display_name": "OpenCode",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "built_in",
+        "protocol": "opencode-http-sse",
+        "default_launch": {
+          "program": "opencode",
+          "arguments": [
+            "serve"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "pi",
+      "display_name": "Pi",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "built_in",
+        "protocol": "pi-rpc-jsonl",
+        "default_launch": {
+          "program": "pi",
+          "arguments": [
+            "--mode",
+            "rpc"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "runhuman",
+      "display_name": "Runhuman",
+      "native": {
+        "discover": "absent",
+        "load": "absent",
+        "follow": "absent",
+        "import": "absent",
+        "export": "absent"
+      },
+      "runtime": {
+        "implementation": "built_in",
+        "protocol": "rhh-rpc-jsonl",
+        "default_launch": {
+          "program": "rhh",
+          "arguments": [
+            "--mode",
+            "rpc"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "grok",
+      "display_name": "Grok",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "grok",
+          "arguments": [
+            "--sandbox",
+            "workspace",
+            "agent",
+            "--no-leader",
+            "stdio"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "gemini",
+      "display_name": "Gemini CLI",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "gemini",
+          "arguments": [
+            "--experimental-acp"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "goose",
+      "display_name": "Goose",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "goose",
+          "arguments": [
+            "acp"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "hermes",
+      "display_name": "Hermes Agent",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "absent",
+        "import": "absent",
+        "export": "generic_protocol"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "hermes-acp",
+          "arguments": [],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "openclaw",
+      "display_name": "OpenClaw",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "absent",
+        "import": "absent",
+        "export": "absent"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "openclaw",
+          "arguments": [
+            "acp"
+          ],
+          "env": {}
+        },
+        "connect_launch": {
+          "config_path": "~/.openclaw/openclaw.json",
+          "address_pointer": "/gateway/remote/url",
+          "port_pointer": "/gateway/port",
+          "default_address": "ws://127.0.0.1:18789",
+          "auth_pointer": "/gateway/auth/token",
+          "protocol": "acp-v1-jsonrpc"
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    },
+    {
+      "id": "orchestrator",
+      "display_name": "Orchestrator",
+      "native": {
+        "discover": "absent",
+        "load": "absent",
+        "follow": "absent",
+        "import": "absent",
+        "export": "absent"
+      },
+      "runtime": {
+        "implementation": "absent",
+        "protocol": "none",
+        "default_launch": null,
+        "capabilities": {
+          "start_session": false,
+          "resume_session": false,
+          "attach_existing_process": false,
+          "send_input": false,
+          "stream_events": false,
+          "interrupt": false,
+          "steer": false,
+          "respond_to_requests": false
+        }
+      }
+    },
+    {
+      "id": "supercode",
+      "display_name": "Volter Harness",
+      "native": {
+        "discover": "built_in",
+        "load": "built_in",
+        "follow": "built_in",
+        "import": "built_in",
+        "export": "built_in"
+      },
+      "runtime": {
+        "implementation": "generic_protocol",
+        "protocol": "acp-v1-jsonrpc",
+        "default_launch": {
+          "program": "supercode",
+          "arguments": [
+            "acp"
+          ],
+          "env": {}
+        },
+        "capabilities": {
+          "start_session": true,
+          "resume_session": true,
+          "attach_existing_process": false,
+          "send_input": true,
+          "stream_events": true,
+          "interrupt": true,
+          "steer": false,
+          "respond_to_requests": true
+        }
+      }
+    }
+  ]
+}

package/support-report.mjs

@@ -0,0 +1,69 @@
+// Implementation facts, not a verdict that a vendor works or is installed.
+import { readFileSync } from 'node:fs';
+import { isAbsolute, toNamespacedPath } from 'node:path';
+import { grokHomeEnvironment } from './session-resume-instructions.mjs';
+
+const table = JSON.parse(readFileSync(new URL('./support-registry.json', import.meta.url), 'utf8'));
+const concepts = ['scheduled_job', 'run', 'conversation', 'pending_request', 'profile', 'skills', 'memory', 'delivery_target', 'channel', 'routing', 'inbound_trigger', 'gateway_health'];
+const gateways = ['hermes', 'openclaw', 'orchestrator'];
+const lifecycle = { codex: ['archive', 'delete'], opencode: ['archive', 'delete'], hermes: ['reset', 'delete'], openclaw: ['new', 'reset'], orchestrator: ['new', 'reset'], supercode: ['archive', 'delete'] };
+const methods = (noun, verbs) => verbs.map(verb => `harness.v1.${noun}.${verb}`);
+
+export function supportOrchestration(descriptor) {
+  const id = descriptor.id, gateway = gateways.includes(id), jobs = gateway || id === 'claude-code';
+  return { concepts: concepts.map(concept => {
+    let observed = 'absent', controlled = 'absent', backing = [];
+    const read = list => { observed = 'built_in'; backing = list; };
+    const control = list => { read(list); controlled = 'built_in'; };
+    switch (concept) {
+      case 'scheduled_job':
+        if (gateway) control(methods('jobs', ['list', 'get', 'create', 'update', 'pause', 'resume', 'run', 'delete']));
+        else if (jobs) read(methods('jobs', ['list', 'get']));
+        break;
+      case 'run': if (gateway) read(methods('runs', ['list', 'get'])); break;
+      case 'conversation':
+        if (descriptor.native.load === 'built_in') {
+          const verbs = lifecycle[id] ?? [];
+          read(methods('sessions', ['discover', 'load', ...verbs]));
+          if (verbs.length) controlled = 'built_in';
+        } else if (id === 'orchestrator') control(methods('sessions', ['discover', ...lifecycle[id]]));
+        break;
+      case 'pending_request': if (descriptor.runtime.capabilities.respond_to_requests) control(['harness.v1.approvals.list', 'harness.v1.approvals.resolve', 'harness.v1.runtimes.respond']); break;
+      case 'profile':
+        if (gateway) control(methods('profiles', ['list', 'get', 'create', 'delete']));
+        else if (['codex', 'supercode'].includes(id)) read(methods('profiles', ['list', 'get']));
+        break;
+      case 'skills': if (['claude-code', 'codex', 'opencode', 'pi', 'hermes', 'openclaw'].includes(id)) control(methods('skills', ['list', 'install', 'remove'])); break;
+      case 'memory': if (['claude-code', 'hermes', 'openclaw'].includes(id)) read(methods('memory', ['show', 'search'])); break;
+      case 'delivery_target': if (jobs) read([...methods('jobs', ['list', 'get']), ...(gateway ? methods('runs', ['list', 'get']) : [])]); break;
+      case 'channel': if (gateway) read(methods('channels', ['list', 'status'])); break;
+      case 'routing': if (gateway) read(methods('routes', ['list'])); break;
+      case 'inbound_trigger': if (gateway) read(methods('triggers', ['list'])); break;
+      case 'gateway_health': if (gateway) read(['harness.v1.harnesses.list']); break;
+    }
+    return { concept, observed, controlled, ...(backing.length ? { methods: backing } : {}) };
+  }) };
+}
+
+export function supportRegistryReport({ env = process.env, cwd = process.cwd() } = {}) {
+  const report = structuredClone(table);
+  for (const descriptor of report.harnesses) {
+    if (descriptor.id === 'codex') {
+      const program = env.SUPERCODE_CODEX_BIN;
+      // The native registry does not trim, stat or substitute a configured
+      // executable. An invalid relative override means no default launch.
+      const absolute = typeof program === 'string' && isAbsolute(program)
+        && (process.platform !== 'win32' || /^(?:[A-Za-z]:[\\/]|[\\/]{2})/.test(program));
+      descriptor.runtime.default_launch = program ? absolute ? { program, arguments: ['app-server'], env: {} } : null
+        : { program: 'codex', arguments: ['app-server'], env: {} };
+    } else if (descriptor.id === 'grok') {
+      const home = grokHomeEnvironment(env, cwd);
+      // Rust canonicalize keeps the Windows extended path prefix in this
+      // inventory's environment value, including an owned junction target.
+      if (process.platform === 'win32' && home.GROK_HOME != null) home.GROK_HOME = toNamespacedPath(home.GROK_HOME);
+      descriptor.runtime.default_launch.env = { GROK_AGENT_DASHBOARD: '0', ...home };
+    }
+    descriptor.orchestration = supportOrchestration(descriptor);
+  }
+  return report;
+}