@oqura/wisdom 0.0.0-stage → 0.3.1-beta.0

package/dist/src/daemon.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { Captures } from './captures.js';
+import { SharedLibrary, readLedger, readView } from './shared.js';
+import { hookSchema, viewSchema } from './schema.js';
+import { writeJson } from './ledger.js';
+import { startDashboard } from './dashboard.js';
+/** Bumped when the daemon's contract changes (capture opening or reading). A daemon
+ * started from an older build keeps running old code in memory, so clients check this.
+ */
+// 11: hook events may carry a handoff, and the export view exists.
+// 12: /import, and the shared and transcript views.
+// 13: the markdown view.
+export const CAPTURE_API = 14;
+async function body(request) {
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of request) {
+        length += chunk.length;
+        if (length > 16 * 1024 * 1024)
+            throw new Error('Request exceeds 16 MiB');
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+}
+/** One local process owns SQLite and evidence files. No web framework is needed. */
+export async function startDaemon(dataDir, port = 7434, options = {}) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const lock = path.join(dataDir, 'daemon.lock');
+    if (fs.existsSync(lock)) {
+        const pid = Number(fs.readFileSync(lock, 'utf8'));
+        let alive = false;
+        if (Number.isInteger(pid) && pid > 0) {
+            try {
+                process.kill(pid, 0);
+                alive = true;
+            }
+            catch (error) {
+                if (error.code === 'EPERM')
+                    alive = true;
+            }
+        }
+        if (alive)
+            throw new Error(`Daemon already owns this data directory (PID ${pid}).`);
+        fs.unlinkSync(lock);
+    }
+    fs.writeFileSync(lock, String(process.pid), { flag: 'wx' });
+    let captures;
+    try {
+        captures = new Captures(dataDir);
+    }
+    catch (error) {
+        fs.unlinkSync(lock);
+        throw error;
+    }
+    const library = new SharedLibrary(path.join(dataDir, 'shared'));
+    const token = randomBytes(32).toString('hex');
+    let dashboard;
+    let closing = false;
+    let timer;
+    let finish;
+    const closed = new Promise(resolve => { finish = resolve; });
+    const server = http.createServer(async (request, response) => {
+        const send = (status, data) => {
+            response.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+            response.end(JSON.stringify(data));
+        };
+        if (request.headers.authorization !== `Bearer ${token}`) {
+            send(401, { error: 'Local daemon token required' });
+            return;
+        }
+        if (closing) {
+            send(503, { error: 'Daemon is stopping' });
+            return;
+        }
+        try {
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            if (request.method === 'GET' && url.pathname === '/health') {
+                send(200, { status: 'running', pid: process.pid, captures: captures.ledgers.size,
+                    storage: 'sqlite', captureApi: CAPTURE_API, readVersion: captures.database.revision,
+                    dashboard: dashboard?.state() ?? { status: 'unavailable', reason: 'Not started with this daemon.' } });
+                return;
+            }
+            if (request.method !== 'POST') {
+                send(404, { error: 'Unknown route' });
+                return;
+            }
+            const input = await body(request);
+            if (url.pathname === '/ledger') {
+                send(200, { text: readLedger(captures, library, input) });
+                return;
+            }
+            if (url.pathname === '/view') {
+                send(200, readView(captures, library, viewSchema.parse(input)));
+                return;
+            }
+            if (url.pathname === '/import') {
+                send(200, importShare(captures, library, input));
+                return;
+            }
+            // Every hook and the Pi extension: the session the event names picks its record.
+            if (url.pathname === '/observe') {
+                const record = captures.route(hookSchema.parse(input));
+                send(200, { recorded: !!record, id: record?.id, captureId: record?.captureId });
+                return;
+            }
+            if (url.pathname === '/resolve') {
+                // Resuming starts a harness, so it takes the exact session ID only: never a guess.
+                const { captureId, harness, workspaceRoot, source } = captures.get(String(input?.session ?? '')).manifest;
+                send(200, { captureId, harness, workspaceRoot, source });
+                return;
+            }
+            if (url.pathname === '/stop') {
+                send(200, { status: 'stopping' });
+                setImmediate(() => void close());
+                return;
+            }
+            send(404, { error: 'Unknown route' });
+        }
+        catch (error) {
+            send(400, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    server.requestTimeout = 30000;
+    server.headersTimeout = 10000;
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(port, '127.0.0.1', resolve);
+        });
+    }
+    catch (error) {
+        captures.shutdown();
+        captures.database.close();
+        fs.unlinkSync(lock);
+        throw error;
+    }
+    const address = server.address();
+    const connection = { url: `http://127.0.0.1:${address.port}`, token, pid: process.pid };
+    // Once the port is held, and before daemon.json says so: the hook that started this daemon
+    // waits for that file, so the file baseline of a kept tool start is taken before the tool runs.
+    captures.drainSpool();
+    writeJson(path.join(dataDir, 'daemon.json'), connection);
+    timer = setInterval(() => { captures.poll(); library.poll(); }, 500);
+    // Optional viewer. Started after daemon.json exists, since it reads it to connect.
+    if (options.dashboardPort)
+        dashboard = startDashboard(dataDir, options.dashboardPort);
+    async function close() {
+        if (closing)
+            return closed;
+        closing = true;
+        clearInterval(timer);
+        dashboard?.close();
+        captures.shutdown();
+        await new Promise(resolve => server.close(() => resolve()));
+        captures.database.close();
+        library.close();
+        fs.rmSync(path.join(dataDir, 'daemon.json'), { force: true });
+        fs.rmSync(lock, { force: true });
+        finish();
+    }
+    return { connection, captures, close, closed };
+}
+/** Import a share file named by an absolute path. Sessions also recorded here are named,
+ * because this project's own recording is the one every read shows.
+ */
+function importShare(captures, library, input) {
+    const file = input?.file;
+    if (typeof file !== 'string' || !path.isAbsolute(file))
+        throw new Error('Name the share file by its full path.');
+    const { store, added } = library.import(file);
+    const own = new Set(captures.database.manifests().map(manifest => manifest.captureId));
+    const sessions = library.sessions().filter(session => store.ids.includes(session.captureId));
+    return { added, shared: store.shared, sessions, alsoRecordedHere: sessions.map(s => s.captureId).filter(id => own.has(id)) };
+}
+//# sourceMappingURL=daemon.js.map

package/dist/src/dashboard.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const bundled = fileURLToPath(new URL('../../dist-dashboard/', import.meta.url));
+/** The viewer, built ahead of time into dist-dashboard/. The daemon starts it, and it never
+ * affects recording: if it is missing or cannot start, capture continues.
+ */
+export function startDashboard(dataDir, port, root = bundled) {
+    const server = path.join(root, 'server.js');
+    if (!fs.existsSync(server))
+        return unavailable('The dashboard is missing from this copy of Wisdom. Reinstall the package; in a clone, run npm run dashboard:install, then npm run dashboard:build.');
+    const log = path.join(dataDir, 'dashboard.log');
+    const out = fs.openSync(log, 'a');
+    let status = 'starting';
+    // Loopback only; the dashboard serves unredacted evidence.
+    const child = spawn(process.execPath, [server], {
+        cwd: root, windowsHide: true, stdio: ['ignore', out, out],
+        env: { ...process.env, PORT: String(port), HOSTNAME: '127.0.0.1', WISDOM_DATA_DIR: dataDir, WISDOM_DAEMON_PID: String(process.pid), NEXT_TELEMETRY_DISABLED: '1' },
+    });
+    fs.closeSync(out);
+    child.once('spawn', () => { status = 'running'; });
+    child.once('exit', () => { status = 'exited'; });
+    child.once('error', error => { status = 'exited'; fs.appendFileSync(log, `spawn error: ${error.message}\n`); });
+    const url = `http://127.0.0.1:${port}`;
+    return { state: () => ({ url, status, log }), close: () => { if (status !== 'exited')
+            child.kill(); } };
+}
+function unavailable(reason) {
+    return { state: () => ({ status: 'unavailable', reason }), close: () => { } };
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/src/database.js

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+/** SQLite owns metadata. Large evidence stays in content-addressed payload files.
+ * There is one writer (the daemon), and every append is committed before ACK.
+ * JSON preserves optional evidence fields; indexed columns serve relationships.
+ */
+export class LedgerDatabase {
+    file;
+    sql;
+    constructor(file) {
+        this.file = file;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        this.sql = new DatabaseSync(file);
+        this.sql.exec('PRAGMA foreign_keys=ON; PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL;');
+        const version = Number(this.sql.prepare('PRAGMA user_version').get().user_version);
+        if (version > 1) {
+            this.sql.close();
+            throw new Error(`Unsupported database version ${version}`);
+        }
+        this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS captures (
+        id TEXT PRIMARY KEY, session_id TEXT NOT NULL, workspace_root TEXT NOT NULL,
+        manifest TEXT NOT NULL, recovery_gaps TEXT NOT NULL DEFAULT '[]'
+      );
+      CREATE INDEX IF NOT EXISTS captures_workspace ON captures(workspace_root, session_id);
+      CREATE TABLE IF NOT EXISTS records (
+        revision INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE, capture_id TEXT NOT NULL REFERENCES captures(id),
+        seq INTEGER NOT NULL, type TEXT NOT NULL, parent_id TEXT, request_id TEXT,
+        tool_call_id TEXT, tool_name TEXT, source_entry_id TEXT, path TEXT,
+        role TEXT, is_error INTEGER, observation_id TEXT, body TEXT NOT NULL,
+        UNIQUE(capture_id, seq), UNIQUE(capture_id, observation_id)
+      );
+      CREATE INDEX IF NOT EXISTS records_type ON records(capture_id, type, seq);
+      CREATE INDEX IF NOT EXISTS records_tool ON records(capture_id, tool_call_id, seq);
+      CREATE INDEX IF NOT EXISTS records_request ON records(capture_id, request_id, seq);
+      CREATE INDEX IF NOT EXISTS records_parent ON records(capture_id, parent_id, seq);
+      CREATE INDEX IF NOT EXISTS records_source ON records(capture_id, source_entry_id, seq);
+      CREATE INDEX IF NOT EXISTS records_path ON records(path, capture_id, seq);
+      PRAGMA user_version=1;
+    `);
+    }
+    manifests() {
+        return this.sql.prepare('SELECT manifest FROM captures').all().map(row => {
+            return JSON.parse(String(row.manifest));
+        });
+    }
+    saveManifest(manifest) {
+        this.sql.prepare(`INSERT INTO captures(id, session_id, workspace_root, manifest) VALUES(?,?,?,?)
+      ON CONFLICT(id) DO UPDATE SET manifest=excluded.manifest, session_id=excluded.session_id, workspace_root=excluded.workspace_root`).run(manifest.captureId, manifest.sessionId, workspaceKey(manifest.workspaceRoot), JSON.stringify(manifest));
+    }
+    recovery(id) {
+        return JSON.parse(String(this.sql.prepare('SELECT recovery_gaps FROM captures WHERE id=?').get(id)?.recovery_gaps ?? '[]'));
+    }
+    append(record) {
+        // Hook parentage is stronger than temporal association. Preserve that difference.
+        if (!record.requestId && record.parentId) {
+            const parent = this.records('id=? AND capture_id=?', [record.parentId, record.captureId])[0];
+            record.requestId = parent?.type === 'input' ? parent.id : parent?.requestId;
+            if (record.requestId)
+                record.linkBasis = 'recorded-parent';
+        }
+        // Transcript evidence and the usage it reports belong to the input window they arrived in.
+        if (record.requestId && record.type === 'usage' && !record.linkBasis)
+            record.linkBasis = 'observed-input-window';
+        if (!record.requestId && (record.type.startsWith('source_') || record.type === 'usage')) {
+            const input = record.turnId
+                ? this.sql.prepare("SELECT id FROM records WHERE capture_id=? AND type='input' AND json_extract(body,'$.turnId')=? AND json_extract(body,'$.agentId') IS ? ORDER BY seq DESC LIMIT 1")
+                    .get(record.captureId, record.turnId, record.agentId ?? null)
+                : this.sql.prepare("SELECT id FROM records WHERE capture_id=? AND type='input' ORDER BY seq DESC LIMIT 1").get(record.captureId);
+            if (input) {
+                record.requestId = String(input.id);
+                record.linkBasis = record.turnId ? 'recorded-turn' : 'observed-input-window';
+            }
+        }
+        this.insert(record);
+    }
+    /** A record exactly as another database stored it (a shared copy): links already made there are kept. */
+    insert(record) {
+        this.sql.prepare(`INSERT INTO records(id,capture_id,seq,type,parent_id,request_id,tool_call_id,
+      tool_name,source_entry_id,path,role,is_error,observation_id,body) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(record.id, record.captureId, record.seq, record.type, record.parentId ?? null, record.requestId ?? null, record.toolCallId ?? null, record.toolName ?? null, record.sourceEntryId ?? null, record.path ?? null, record.role ?? null, record.isError === undefined ? null : Number(record.isError), record.observationId ?? null, JSON.stringify(record));
+    }
+    /** The SQL fragment is internal code only. User values always use bindings. */
+    records(where, bindings = [], suffix = 'ORDER BY revision') {
+        return this.sql.prepare(`SELECT body FROM records WHERE ${where} ${suffix}`).all(...bindings)
+            .map(row => JSON.parse(String(row.body)));
+    }
+    get revision() { return Number(this.sql.prepare('SELECT coalesce(max(revision),0) AS n FROM records').get().n); }
+    lastSeq(id) {
+        return Number(this.sql.prepare('SELECT coalesce(max(seq),0) AS n FROM records WHERE capture_id=?').get(id).n);
+    }
+    close() { this.sql.close(); }
+}
+/** Windows path casing must not split one workspace into separate query scopes. */
+export function workspaceKey(root) {
+    const resolved = path.resolve(root);
+    const canonical = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+    return process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+}
+//# sourceMappingURL=database.js.map