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

package/dist/src/harnesses/pi/extension.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { deliver, handoffFromEnv } from '../../client.js';
+import { findDataDir, harnessHome } from '../../paths.js';
+/** Wisdom's data folder: the one Pi's agent folder is in, when Pi is tracked; otherwise the
+ * project's, since only a connected project's settings load this extension, and Pi loads them
+ * when it starts in the project's folder.
+ */
+function dataFolder() {
+    const agentDir = process.env.PI_CODING_AGENT_DIR;
+    if (agentDir) {
+        const data = path.resolve(agentDir, '..', '..', '..');
+        if (path.resolve(harnessHome(data, 'pi')) === path.resolve(agentDir))
+            return data;
+    }
+    return findDataDir(process.cwd());
+}
+/** A tracked session in a connected project loads this extension twice: from its home and from
+ * the project. One registration records it.
+ */
+const loaded = Symbol.for('wisdom.pi.extension');
+/** The version of the Pi that is running, from its own package. */
+function piVersion() {
+    try {
+        for (let dir = path.dirname(fs.realpathSync(process.argv[1]));; dir = path.dirname(dir)) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const { name, version } = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (/pi-coding-agent$/.test(name) && typeof version === 'string')
+                    return version;
+            }
+            if (path.dirname(dir) === dir)
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Loaded from the settings of Pi's home in Wisdom's folder, or of a connected project. Every event names its
+ * session, so /new, /fork, /clone and /resume reach the right record. It never blocks Pi:
+ * an event the daemon cannot take is kept in the spool.
+ */
+export default function wisdomTracking(pi) {
+    const dataDir = dataFolder();
+    if (!dataDir || globalThis[loaded])
+        return;
+    globalThis[loaded] = true;
+    let session;
+    let warning;
+    let queue = Promise.resolve();
+    const harnessVersion = piVersion();
+    const handoff = handoffFromEnv();
+    // Serial delivery preserves this extension's observation order. The tool_call
+    // handler awaits it, so the before-image exists before execution.
+    const send = (ctx, data) => {
+        const current = session;
+        const task = queue.then(async () => {
+            if (!current)
+                return;
+            const { spooled } = await deliver(dataDir, { harness: 'pi', harnessVersion, cwd: current.cwd, ...handoff,
+                observation: { observationId: randomUUID(), sessionId: current.sessionId, source: current.source, ...data } });
+            if (spooled && !warning) {
+                warning = `Wisdom is keeping events to record when its daemon is back (${spooled}).`;
+                ctx.ui?.setStatus('wisdom', 'Wisdom: keeping events');
+                ctx.ui?.notify(warning, 'warning');
+            }
+            else if (!spooled && warning) {
+                warning = undefined;
+                ctx.ui?.setStatus('wisdom', 'Wisdom recording');
+            }
+        });
+        queue = task.catch(error => { ctx.ui?.notify(`Wisdom could not record or keep an event: ${String(error)}`, 'error'); });
+        return queue;
+    };
+    pi.on('session_start', async (event, ctx) => {
+        session = { sessionId: ctx.sessionManager.getSessionId(), source: ctx.sessionManager.getSessionFile() ?? null, cwd: ctx.cwd };
+        ctx.ui?.setStatus('wisdom', 'Wisdom recording');
+        await send(ctx, { type: 'session_started', data: { sessionId: session.sessionId, source: session.source, origin: event?.reason } });
+    });
+    pi.on('input', async (event, ctx) => { await send(ctx, { type: 'input', data: event }); return { action: 'continue' }; });
+    pi.on('tool_call', async (event, ctx) => {
+        await send(ctx, { type: 'tool_started', toolCallId: event.toolCallId, toolName: event.toolName,
+            parentToolCallId: event.parentToolCallId, data: { input: event.input } });
+    });
+    const finished = new Set();
+    const result = async (event, ctx) => {
+        if (finished.has(event.toolCallId))
+            return;
+        finished.add(event.toolCallId);
+        await send(ctx, { type: 'tool_finished', toolCallId: event.toolCallId, toolName: event.toolName,
+            parentToolCallId: event.parentToolCallId, isError: event.isError,
+            data: event.result ?? { content: event.content, details: event.details, structuredContent: event.structuredContent } });
+    };
+    pi.on('tool_result', result);
+    // Blocked/validation-failed calls may skip tool_result. Preserve their execution
+    // outcome too, while avoiding duplicate normal completion records.
+    pi.on('tool_execution_end', result);
+    for (const eventName of ['agent_settled', 'session_tree', 'session_compact']) {
+        pi.on(eventName, async (event, ctx) => { await send(ctx, { type: eventName, data: eventName === 'agent_settled' ? undefined : event }); });
+    }
+    pi.on('message_end', async (event, ctx) => {
+        // Native session records supply persisted message bodies. Only keep fallback
+        // bodies when Pi persistence is disabled, rather than duplicating every message.
+        if (!ctx.sessionManager.getSessionFile())
+            await send(ctx, { type: 'message', data: event.message });
+    });
+    pi.on('session_shutdown', async (event, ctx) => {
+        await send(ctx, { type: 'session_ended', data: { reason: event?.reason } });
+        session = undefined;
+        finished.clear();
+    });
+    pi.registerCommand('wisdom-status', {
+        description: 'Show the session Wisdom is recording',
+        handler: async (_args, ctx) => ctx.ui.notify(warning ?? `Wisdom is recording session ${session?.sessionId ?? '(none yet)'}`, warning ? 'warning' : 'info')
+    });
+}
+//# sourceMappingURL=extension.js.map

package/dist/src/harnesses/pi/launch.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { home, installSkill, readSettings, resolveCommand, saveOrRemoveSettings, saveSettings, settingsFile } from '../launch.js';
+import { userHome } from '../index.js';
+/** Reuse the user's Pi installation; do not install another agent. An entry script named with
+ * --pi-entry, else the release Pi's own installer made current, else `pi` on PATH (npm).
+ */
+export function piCommand(entry) {
+    if (entry)
+        return { command: process.execPath, args: [path.resolve(entry)] };
+    const root = path.join(os.homedir(), '.pi', 'agent', 'install');
+    let version;
+    try {
+        version = fs.readFileSync(path.join(root, 'current-version'), 'utf8').trim();
+    }
+    catch {
+        return resolveCommand('pi');
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(version) || version === '..')
+        throw new Error('Invalid managed Pi version');
+    const pkg = path.join(root, 'releases', version, 'node_modules', '@earendil-works', 'pi-coding-agent');
+    const metadata = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8'));
+    return { command: process.execPath, args: [path.join(pkg, typeof metadata.bin === 'string' ? metadata.bin : metadata.bin.pi)] };
+}
+/** Pi's agent folder (PI_CODING_AGENT_DIR) in Wisdom's folder, with Wisdom's extension
+ * in its settings. Sessions, login and settings stay there; ~/.pi/agent is never touched.
+ */
+export function installPi(dataDir) {
+    const folder = home(dataDir, 'pi');
+    writeExtension(dataDir, 'home', true);
+    installSkill(folder);
+    return folder;
+}
+/** Wisdom's extension in the project's `.pi/settings.json` (verified on Pi 1.2.0: loaded once
+ * the project is trusted, when Pi starts in the project's folder). Pi uses the person's own
+ * agent folder and login. Returns the file.
+ */
+export function connectPi(dataDir) {
+    writeExtension(dataDir, 'project', true);
+    return settingsFile(dataDir, 'pi', 'project');
+}
+/** Take Wisdom's extension out of the project's `.pi/settings.json`, leaving everything else. */
+export function disconnectPi(dataDir) {
+    writeExtension(dataDir, 'project', false);
+}
+/** Add Wisdom's extension to one Pi settings file, replacing an earlier copy, or remove it. */
+function writeExtension(dataDir, place, add) {
+    const file = settingsFile(dataDir, 'pi', place);
+    const settings = readSettings(file);
+    const others = (Array.isArray(settings.extensions) ? settings.extensions : [])
+        .filter((item) => typeof item !== 'string' || !/harnesses[\\/]pi[\\/]extension\.js$/.test(item));
+    if (add) {
+        settings.extensions = [...others, fileURLToPath(new URL('./extension.js', import.meta.url))];
+        saveSettings(file, settings);
+        return;
+    }
+    if (others.length)
+        settings.extensions = others;
+    else
+        delete settings.extensions;
+    saveOrRemoveSettings(file, settings);
+}
+/** Pi with its agent folder in Wisdom's folder, or, in a connected project, with the person's
+ * own, where the project's settings load Wisdom's extension.
+ */
+export function launchPi(options) {
+    const own = options.place === 'project';
+    const folder = own ? userHome('pi') : installPi(options.dataDir);
+    options.args.forEach((arg, i) => {
+        if (/^--session-dir(?:=|$)/.test(arg))
+            throw new Error('Wisdom chooses where Pi stores sessions; remove --session-dir.');
+        const value = arg === '--session' ? options.args[i + 1] : arg.startsWith('--session=') ? arg.slice(10) : undefined;
+        if (value && /[\\/]/.test(value) && path.relative(folder, path.resolve(value)).startsWith('..')) {
+            throw new Error('Resume a Wisdom session by its ID; a session file outside Wisdom cannot be tracked.');
+        }
+    });
+    const program = piCommand(options.entry);
+    return { command: program.command, env: own ? {} : { PI_CODING_AGENT_DIR: folder }, args: [...program.args, ...options.args] };
+}
+//# sourceMappingURL=launch.js.map

package/dist/src/harnesses/types.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const count = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+/** A path inside `from` moved to the same place inside `to`; any other path unchanged.
+ * Windows paths compare without case.
+ */
+export function moveFolder(from, to) {
+    const key = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
+    return folder => {
+        if (key(folder) === key(from))
+            return to;
+        const inside = [from + '\\', from + '/'].some(prefix => key(folder).startsWith(key(prefix)));
+        return inside ? to + folder.slice(from.length) : folder;
+    };
+}
+/** `.jsonl` files `depth` folders below `dir` (0: in it), in name order. */
+export function jsonlFiles(dir, depth) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
+        const full = path.join(dir, entry.name);
+        if (depth > 0)
+            return entry.isDirectory() ? jsonlFiles(full, depth - 1) : [];
+        return entry.isFile() && entry.name.endsWith('.jsonl') ? [full] : [];
+    });
+}
+/** Text blocks of a message's content, joined; undefined when there are none. */
+export function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = content.filter((block) => ['text', 'input_text'].includes(block?.type) && typeof block.text === 'string')
+        .map((block) => block.text);
+    return parts.length ? parts.join('\n') : undefined;
+}
+//# sourceMappingURL=types.js.map

package/dist/src/ledger.js

@@ -0,0 +1,277 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { preview } from './schema.js';
+import { adapter } from './harnesses/index.js';
+export const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function writeJson(file, value) {
+    fs.writeFileSync(file + '.tmp', JSON.stringify(value, null, 2) + '\n');
+    fs.renameSync(file + '.tmp', file);
+}
+/** One capture's native mirror and payload files, backed by the shared database. */
+export class Ledger {
+    dir;
+    manifest;
+    database;
+    recoveryGaps = [];
+    sourceOffset = 0;
+    sourceStopped = false;
+    sourceChecked = false;
+    sourceTurnId;
+    sourceModel;
+    gaps = new Set();
+    constructor(dir, manifest, database, create = false) {
+        this.dir = dir;
+        this.manifest = manifest;
+        this.database = database;
+        if (create) {
+            fs.mkdirSync(path.join(dir, 'payloads'), { recursive: true });
+            fs.writeFileSync(this.mirror, '', { flag: 'wx' });
+            this.saveManifest();
+        }
+        this.recoveryGaps.splice(0, this.recoveryGaps.length, ...this.database.recovery(manifest.captureId));
+        const row = this.database.sql.prepare(`SELECT coalesce(max(
+      coalesce(json_extract(body,'$.sourceOffset'),0) + coalesce(json_extract(body,'$.sourceLength'),0)),0) AS n
+      FROM records WHERE capture_id=?`).get(manifest.captureId);
+        this.sourceOffset = Number(row.n);
+        const mirror = this.mirror;
+        if (fs.existsSync(mirror) && fs.statSync(mirror).size !== this.sourceOffset) {
+            this.recoveryGaps.push('Native mirror byte count differs from indexed references; further mirroring stopped.');
+            this.sourceStopped = true;
+        }
+    }
+    /** Byte copy of the harness's native transcript. */
+    get mirror() { return path.join(this.dir, 'native-session.jsonl'); }
+    saveManifest() { this.database.saveManifest(this.manifest); }
+    /** How far the native file has been read. Equals the copy's size until the harness
+     * rewrites its file; after that, copying goes on from the file's new end.
+     */
+    get sourcePosition() { return this.sourceOffset + (this.manifest.sourceShift ?? 0); }
+    /** A native file is copied only if it is this harness's file for this session: it
+     * starts with a JSON object, and none of its first lines names another session. A
+     * damaged line further in is not a different file; it becomes its own gap when copied.
+     */
+    checkSource(source) {
+        const fd = fs.openSync(source, 'r');
+        let text;
+        try {
+            const bytes = Buffer.alloc(Math.min(fs.fstatSync(fd).size, 1024 * 1024));
+            text = bytes.subarray(0, fs.readSync(fd, bytes, 0, bytes.length, 0)).toString('utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const harness = adapter(this.manifest.harness);
+        const lines = text.split('\n').slice(0, -1).slice(0, 200);
+        for (const [index, line] of lines.entries()) {
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                entry = undefined;
+            }
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                if (index === 0)
+                    return 'its first line is not a JSON object';
+                continue;
+            }
+            const session = harness.nativeSession(entry);
+            if (session && session !== this.manifest.sessionId)
+                return `line ${index + 1} belongs to session ${session}`;
+        }
+        return undefined;
+    }
+    listRecords() {
+        return this.database.records('capture_id=?', [this.manifest.captureId], 'ORDER BY seq');
+    }
+    findToolStart(toolCallId) {
+        return this.database.records("capture_id=? AND tool_call_id=? AND type='tool_started'", [this.manifest.captureId, toolCallId], 'ORDER BY seq LIMIT 1')[0];
+    }
+    hasObservation(id) {
+        return !!this.database.sql.prepare('SELECT 1 FROM records WHERE capture_id=? AND observation_id=?')
+            .get(this.manifest.captureId, id);
+    }
+    get lastSeq() { return this.database.lastSeq(this.manifest.captureId); }
+    append(fields) {
+        const record = { ...fields, schemaVersion: 1, captureId: this.manifest.captureId,
+            id: randomUUID(), seq: this.lastSeq + 1, observedAt: new Date().toISOString() };
+        this.database.append(record);
+        return record;
+    }
+    gap(kind, detail) {
+        const key = `${kind}:${detail}`;
+        if (this.gaps.has(key))
+            return;
+        this.gaps.add(key);
+        this.append({ type: 'gap', summary: key });
+    }
+    payload(value) {
+        const text = typeof value === 'string' ? value : JSON.stringify(value);
+        const name = hash(text);
+        const file = path.join(this.dir, 'payloads', name);
+        if (!fs.existsSync(file))
+            fs.writeFileSync(file, text);
+        return name;
+    }
+    readPayload(ref) {
+        if (!/^[a-f0-9]{64}$/.test(ref))
+            throw new Error('Invalid payload reference');
+        return fs.readFileSync(path.join(this.dir, 'payloads', ref), 'utf8');
+    }
+    readSource(record) {
+        if (record.sourceOffset === undefined || record.sourceLength === undefined)
+            return '';
+        const fd = fs.openSync(this.mirror, 'r');
+        try {
+            const bytes = Buffer.alloc(record.sourceLength);
+            fs.readSync(fd, bytes, 0, bytes.length, record.sourceOffset);
+            return bytes.toString('utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    /** Lines of a found session's file that an older session wrote: they keep their bytes
+     * here, but its prompts are that session's turns.
+     */
+    copiedEntries = new Set();
+    /** The harness moved this session's file (Claude Code does on entering a worktree).
+     * Copying goes on from the same position in the new file, after the usual check.
+     */
+    moveSource(source) {
+        const from = this.manifest.source;
+        this.manifest.source = source;
+        this.sourceChecked = false;
+        this.saveManifest();
+        this.append({ type: 'source_moved', summary: `Native file moved from ${from} to ${source}; copying continues at byte ${this.sourcePosition}.` });
+    }
+    /** Preserve native bytes. No line parser that treats Unicode separators as newlines. */
+    /** Mirror new native lines. `stopBefore` leaves the first matching line (and all
+     * after it) for a later sync, so it is linked to evidence recorded in between.
+     * `prompts` records each typed prompt as an input first: only for lines no hook saw.
+     */
+    syncSource(stopBefore, prompts = false) {
+        const source = this.manifest.source;
+        if (!source || !fs.existsSync(source) || this.sourceStopped)
+            return;
+        const size = fs.statSync(source).size;
+        const position = this.sourcePosition;
+        if (!size)
+            return;
+        if (!this.sourceChecked || size < position) {
+            const problem = this.checkSource(source);
+            if (problem) {
+                this.sourceStopped = true;
+                this.gap('source-incompatible', `Native file is not this ${this.manifest.harness} session (${problem}); copying stopped.`);
+                return;
+            }
+            this.sourceChecked = true;
+        }
+        if (size < position) {
+            // The harness rewrote its file. What it rewrote is not copied again; the copy keeps
+            // every byte read before, and lines added after the rewrite are copied as usual.
+            this.manifest.sourceShift = size - this.sourceOffset;
+            this.saveManifest();
+            this.gap('source-rewritten', `Native file shrank from ${position} to ${size} bytes; copying continues from its new end.`);
+            return;
+        }
+        if (size === position)
+            return;
+        const fd = fs.openSync(source, 'r');
+        try {
+            // Bound each poll; subsequent polls drain a large backlog. A native line
+            // larger than this bound is an explicit gap, not silent truncation.
+            const bytes = Buffer.alloc(Math.min(size - position, 32 * 1024 * 1024));
+            const count = fs.readSync(fd, bytes, 0, bytes.length, position);
+            let start = 0;
+            for (let end = bytes.subarray(0, count).indexOf(10); end >= 0; end = bytes.subarray(0, count).indexOf(10, start)) {
+                const line = bytes.subarray(start, end + 1);
+                if (stopBefore) {
+                    let entry;
+                    try {
+                        entry = adapter(this.manifest.harness).nativeEntry(JSON.parse(line.toString('utf8')));
+                    }
+                    catch { /* recorded as a gap below */ }
+                    if (entry && stopBefore(entry))
+                        break;
+                }
+                fs.appendFileSync(this.mirror, line);
+                this.recordSourceLine(line, this.sourceOffset + start, prompts);
+                start = end + 1;
+            }
+            this.sourceOffset += start;
+            if (!start && count === 32 * 1024 * 1024)
+                this.gap('source-line-oversize', 'Native record exceeds 32 MiB.');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    /** One usage record per model response the transcript reports. Counted once per key
+     * in stats; lines from before this capture (resumed history) are marked, not dropped.
+     */
+    recordUsage(entry, context) {
+        const { sourceModel, ...source } = context;
+        for (const usage of entry.usage ?? []) {
+            const model = usage.model ?? sourceModel;
+            const tokens = usage.input + usage.cacheRead + usage.cacheWrite + usage.output;
+            this.append({ type: 'usage', ...source, usageKey: usage.key, usageScope: usage.scope, model, provider: usage.provider,
+                beforeCapture: entry.timestamp && entry.timestamp < this.manifest.startedAt ? true : undefined,
+                usage: { input: usage.input, cacheRead: usage.cacheRead, cacheWrite: usage.cacheWrite, output: usage.output,
+                    reasoning: usage.reasoning, costUsd: usage.costUsd },
+                summary: usage.scope === 'session-total' ? `usage: session cost $${usage.costUsd?.toFixed(4)}`
+                    : `usage: ${model ?? 'model'} ${tokens} tokens (${usage.output} out)` });
+        }
+    }
+    recordSourceLine(line, offset, prompts = false) {
+        try {
+            const raw = JSON.parse(line.toString('utf8'));
+            const harness = adapter(this.manifest.harness);
+            const entry = harness.nativeEntry(raw);
+            if (entry.turnId)
+                this.sourceTurnId = entry.turnId;
+            if (entry.model)
+                this.sourceModel = entry.model;
+            const version = harness.nativeVersion(raw);
+            if (version && version !== this.manifest.harnessVersion) {
+                this.manifest.harnessVersion = version;
+                this.saveManifest();
+            }
+            const source = { sourceEntryId: entry.id ?? `byte:${offset}:${hash(line)}`, sourceParentId: entry.parentId, sourceTimestamp: entry.timestamp,
+                turnId: this.sourceTurnId, sourceOffset: offset, sourceLength: line.length };
+            // The prompt opens a turn before its own line is recorded, so that line belongs to it.
+            const prompt = prompts && !(entry.id && this.copiedEntries.has(entry.id)) ? harness.nativePrompt(raw) : undefined;
+            if (prompt)
+                this.append({ type: 'input', inputBasis: 'session-file', notice: harness.isNotice(prompt) || undefined, summary: preview(prompt), dataRef: this.payload({ text: prompt }),
+                    turnId: this.sourceTurnId, sourceEntryId: source.sourceEntryId, sourceTimestamp: entry.timestamp });
+            if (!entry.messages.length)
+                this.append({ type: 'source_record', summary: preview(entry.kind), ...source });
+            this.recordUsage(entry, { ...source, sourceModel: this.sourceModel });
+            // One native line can hold several messages, such as parallel tool results.
+            for (const message of entry.messages) {
+                const content = message.content;
+                const text = typeof content === 'string' ? content : Array.isArray(content)
+                    ? content.filter((block) => block?.type === 'text').map((block) => block.text).join(' ') : entry.kind;
+                this.append({ type: 'source_record', summary: preview(text), role: message.role,
+                    toolCallId: message.toolCallId, toolName: message.toolName, isError: message.isError, ...source });
+                // Assistant messages can contain several tool calls. Explicit IDs connect
+                // them to results; adjacency and parentId are not call/result correlation.
+                if (Array.isArray(content))
+                    for (const block of content) {
+                        if (block?.type === 'toolCall' && block.id)
+                            this.append({ type: 'source_tool_call',
+                                toolCallId: block.id, toolName: block.name, ...source,
+                                summary: `${block.name}: ${preview(block.arguments)}` });
+                    }
+            }
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                this.gap('malformed-native-record', `byte ${offset}`);
+            else
+                throw error;
+        }
+    }
+}
+//# sourceMappingURL=ledger.js.map