deepclause-sdk 0.0.88 → 0.1.0

package/dist/repl/history.js

@@ -0,0 +1,661 @@
+/**
+ * Persistent session / trace / harness history.
+ *
+ * See `docs/DML_REPL_SESSION_HISTORY.md`. Storage lives under a
+ * workspace-relative directory (default `.deepclause/repl/`):
+ *
+ *   history.dml                       append-only harness_* facts, consulted at
+ *                                     session start and queryable from DML
+ *   harness/HEAD.json                 current version pointer
+ *   harness/changes.jsonl             one line per harness change
+ *   harness/versions/NNNN_<ts>.json   full module snapshot per version
+ *   sessions/<id>/session.json        session metadata
+ *   sessions/<id>/turns.jsonl         one summary per turn
+ *   sessions/<id>/events.jsonl        runtime event trace
+ *
+ * The recorder is best-effort: callers swallow its errors so a turn never fails
+ * because history could not be written.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const DEFAULT_DIR = '.deepclause/repl';
+/** Stable hash of a harness module plus its linked scripts. */
+export function harnessHash(module, scripts) {
+    return createHash('sha256')
+        .update(module)
+        .update('\n')
+        .update(JSON.stringify(scripts))
+        .digest('hex');
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Single-quoted Prolog atom. */
+export function prologAtom(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
+}
+export class HistoryStore {
+    sessionId;
+    harnessName;
+    rootRel;
+    sessionDirRel;
+    rootAbs;
+    sessionDirAbs;
+    trace;
+    maxEventBytes;
+    maxSessions;
+    maxVersions;
+    redactions;
+    eventBuffer = [];
+    /** Current HEAD version (0 = empty harness) and the highest ever issued. */
+    headVersion = 0;
+    maxVersion = 0;
+    /** Hash recorded for the current HEAD (for session-snapshot consistency). */
+    headHash;
+    constructor(workspacePath, sessionId, options = {}, 
+    /** Harness this session edits (a project can hold several). */
+    harnessName = 'main') {
+        this.sessionId = sessionId;
+        this.harnessName = harnessName;
+        this.rootRel = (options.dir ?? DEFAULT_DIR).replace(/\\/g, '/').replace(/\/+$/, '');
+        this.rootAbs = path.resolve(workspacePath, this.rootRel);
+        this.sessionDirRel = `${this.rootRel}/sessions/${sessionId}`;
+        this.sessionDirAbs = path.resolve(workspacePath, this.sessionDirRel);
+        this.trace = options.trace ?? 'summary';
+        this.maxEventBytes = options.maxEventBytes ?? 8192;
+        this.maxSessions = options.maxSessions ?? 50;
+        this.maxVersions = options.maxVersions ?? 200;
+        this.redactions = (options.redact ?? []).map((source) => new RegExp(source, 'g'));
+    }
+    get currentVersion() {
+        return this.headVersion;
+    }
+    get currentHash() {
+        return this.headHash;
+    }
+    get tracePath() {
+        return `${this.sessionDirRel}/events.jsonl`;
+    }
+    get historyFile() {
+        return path.join(this.rootAbs, 'history.dml');
+    }
+    /** Per-harness store: `.deepclause/repl/harnesses/<name>/`. */
+    get harnessDir() {
+        return path.join(this.rootAbs, 'harnesses', this.harnessName);
+    }
+    /** The single pre-harnesses store, migrated to `harnesses/main` once. */
+    get legacyHarnessDir() {
+        return path.join(this.rootAbs, 'harness');
+    }
+    /** The current content (source of truth; portable as a `.dml`). */
+    get harnessFile() {
+        return path.join(this.harnessDir, 'harness.dml');
+    }
+    /** The module the harness started from (version 0 / rollback floor). */
+    get baselineFile() {
+        return path.join(this.harnessDir, 'baseline.dml');
+    }
+    get headFile() {
+        return path.join(this.harnessDir, 'HEAD.json');
+    }
+    get changesFile() {
+        return path.join(this.harnessDir, 'changes.jsonl');
+    }
+    /** Whether the harness has any committed versions (HEAD > baseline). */
+    get hasCommits() {
+        return this.headVersion > 0;
+    }
+    /** Facts for this harness only (`harness_change`/`changed`/`head`/`rollback`). */
+    get harnessFactsFile() {
+        return path.join(this.harnessDir, 'history.dml');
+    }
+    /** Create directories, read the current version, and prune old entries. */
+    async init() {
+        await fs.mkdir(this.sessionDirAbs, { recursive: true });
+        await this.migrateLegacyHarness();
+        await fs.mkdir(path.join(this.harnessDir, 'versions'), { recursive: true });
+        try {
+            const head = JSON.parse(await fs.readFile(this.headFile, 'utf8'));
+            if (typeof head.version === 'number')
+                this.headVersion = head.version;
+            if (typeof head.hash === 'string')
+                this.headHash = head.hash;
+            this.maxVersion = typeof head.maxVersion === 'number' ? head.maxVersion : this.headVersion;
+        }
+        catch {
+            // no HEAD yet
+        }
+        // A harness always has a baseline (empty for a fresh one) and a current file.
+        await this.ensureHarnessFiles();
+        await this.prune();
+    }
+    /** Move the legacy single `harness/` store into `harnesses/main/` (once). */
+    async migrateLegacyHarness() {
+        if (this.harnessName !== 'main')
+            return;
+        try {
+            await fs.access(path.join(this.legacyHarnessDir, 'HEAD.json'));
+        }
+        catch {
+            return; // nothing to migrate
+        }
+        try {
+            await fs.access(this.harnessDir);
+            return; // the per-harness dir already exists
+        }
+        catch {
+            // proceed
+        }
+        await fs.mkdir(path.dirname(this.harnessDir), { recursive: true });
+        await fs.rename(this.legacyHarnessDir, this.harnessDir);
+    }
+    /** Ensure `baseline.dml` and `harness.dml` exist (materializing from HEAD). */
+    async ensureHarnessFiles() {
+        let baseline = '';
+        try {
+            baseline = await fs.readFile(this.baselineFile, 'utf8');
+        }
+        catch {
+            await fs.writeFile(this.baselineFile, '', 'utf8');
+        }
+        try {
+            const current = await fs.readFile(this.harnessFile, 'utf8');
+            if (current.trim() || this.headVersion <= 0)
+                return;
+        }
+        catch {
+            // write below
+        }
+        const head = this.headVersion > 0 ? await this.readVersion(this.headVersion) : null;
+        await fs.writeFile(this.harnessFile, head?.module ?? baseline, 'utf8');
+    }
+    /** The module at HEAD: the live `harness.dml`, or the HEAD version snapshot. */
+    async readHeadModule() {
+        let module = '';
+        try {
+            module = await fs.readFile(this.harnessFile, 'utf8');
+        }
+        catch {
+            module = '';
+        }
+        if (module.trim())
+            return { version: this.headVersion, module };
+        if (this.headVersion > 0) {
+            const current = await this.readVersion(this.headVersion);
+            if (current?.module.trim())
+                return { version: this.headVersion, module: current.module };
+        }
+        return null;
+    }
+    /** The module this harness started from (version 0). */
+    async readBaseline() {
+        try {
+            return await fs.readFile(this.baselineFile, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Establish the baseline of a fresh harness from its first content (e.g. a
+     * harness file loaded with `-l`). No-op once the harness has a baseline or
+     * any committed version.
+     */
+    async setInitialBaseline(module) {
+        if (this.headVersion > 0)
+            return;
+        if ((await this.readBaseline()).trim())
+            return;
+        await fs.mkdir(this.harnessDir, { recursive: true });
+        await fs.writeFile(this.baselineFile, module, 'utf8');
+        await fs.writeFile(this.harnessFile, module, 'utf8');
+    }
+    /** The persisted facts, to be loaded into the module at session start. */
+    async readFacts() {
+        const read = async (file) => {
+            try {
+                return await fs.readFile(file, 'utf8');
+            }
+            catch {
+                return '';
+            }
+        };
+        const [workspace, harness] = await Promise.all([
+            read(this.historyFile),
+            read(this.harnessFactsFile),
+        ]);
+        return `${workspace}${harness}`;
+    }
+    /** The turns recorded for a session, oldest first (used for input history). */
+    async readTurns(sessionId = this.sessionId) {
+        const file = path.join(this.sessionsDir(), sessionId, 'turns.jsonl');
+        let text;
+        try {
+            text = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const turns = [];
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.request === 'string')
+                    turns.push(parsed);
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return turns;
+    }
+    async startSession(info, options = {}) {
+        const sessionFile = path.join(this.sessionDirAbs, 'session.json');
+        if (options.resume) {
+            const resumedAt = nowIso();
+            const facts = [
+                `harness_session_resume(${prologAtom(this.sessionId)}, ${prologAtom(resumedAt)}).`,
+            ];
+            await this.appendFacts(facts);
+            let existing = {};
+            try {
+                existing = JSON.parse(await fs.readFile(sessionFile, 'utf8'));
+            }
+            catch {
+                // first resume of a session that never wrote session.json
+            }
+            const previous = Array.isArray(existing.resumedAt) ? existing.resumedAt : [];
+            await this.writeJson(sessionFile, {
+                ...existing,
+                sessionId: this.sessionId,
+                model: info.model,
+                backend: info.backend,
+                traceDir: this.sessionDirRel,
+                endedAt: null,
+                exit: null,
+                resumedAt: [...previous, resumedAt],
+            });
+            return facts;
+        }
+        const startedAt = nowIso();
+        const facts = [
+            `harness_session(${prologAtom(this.sessionId)}, ${prologAtom(startedAt)}, `
+                + `${prologAtom(info.model)}, ${prologAtom(info.backend)}, ${prologAtom(this.sessionDirRel)}).`,
+        ];
+        await this.appendFacts(facts);
+        await this.writeJson(sessionFile, {
+            sessionId: this.sessionId,
+            startedAt,
+            endedAt: null,
+            exit: null,
+            model: info.model,
+            backend: info.backend,
+            traceDir: this.sessionDirRel,
+        });
+        return facts;
+    }
+    async endSession(reason) {
+        await this.flushEvents();
+        const endedAt = nowIso();
+        const facts = [`harness_session_end(${prologAtom(this.sessionId)}, ${prologAtom(endedAt)}).`];
+        await this.appendFacts(facts);
+        const sessionFile = path.join(this.sessionDirAbs, 'session.json');
+        try {
+            const existing = JSON.parse(await fs.readFile(sessionFile, 'utf8'));
+            await this.writeJson(sessionFile, { ...existing, endedAt, exit: reason });
+        }
+        catch {
+            // best effort
+        }
+        return facts;
+    }
+    async recordTurn(record) {
+        const ts = nowIso();
+        const facts = [
+            `harness_turn(${prologAtom(this.sessionId)}, ${record.turn}, ${prologAtom(ts)}, `
+                + `${prologAtom(record.mode)}, ${prologAtom(record.outcome)}).`,
+            `harness_trace(${prologAtom(this.sessionId)}, ${record.turn}, ${prologAtom(this.tracePath)}).`,
+        ];
+        await this.appendFacts(facts);
+        await this.appendJsonl(path.join(this.sessionDirAbs, 'turns.jsonl'), { ts, ...record });
+        return facts;
+    }
+    /**
+     * Record a harness version. Returns the facts to assert and the new version.
+     */
+    async recordChange(record) {
+        const ts = nowIso();
+        const hash = harnessHash(record.module, record.scripts);
+        // Committing content identical to HEAD is a no-op: do not burn a version.
+        if (hash === this.headHash && this.headVersion > 0) {
+            return { facts: [], version: this.headVersion };
+        }
+        const version = this.maxVersion + 1;
+        this.maxVersion = version;
+        const parentVersion = this.headVersion;
+        const facts = [
+            `harness_change(${version}, ${prologAtom(ts)}, ${prologAtom(record.kind)}, `
+                + `${prologAtom(record.sessionId)}, ${record.turn}).`,
+            ...record.changed.map((change) => {
+                const [name, arity] = splitPredicate(change.predicate);
+                return `harness_changed(${version}, ${prologAtom(name)}, ${arity}, ${prologAtom(change.action)}).`;
+            }),
+            `harness_head(${version}, ${prologAtom(ts)}, ${prologAtom(record.sessionId)}, ${record.turn}).`,
+        ];
+        await this.appendHarnessFacts(facts);
+        await this.appendJsonl(this.changesFile, {
+            version,
+            ts,
+            sessionId: record.sessionId,
+            turn: record.turn,
+            kind: record.kind,
+            hash,
+            changed: record.changed,
+            scripts: record.scripts,
+        });
+        await this.writeJson(path.join(this.harnessDir, 'versions', `${String(version).padStart(4, '0')}_${fileStamp(ts)}.json`), {
+            version,
+            ts,
+            parentVersion: parentVersion > 0 ? parentVersion : null,
+            kind: record.kind,
+            sessionId: record.sessionId,
+            turn: record.turn,
+            hash,
+            changed: record.changed,
+            scripts: record.scripts,
+            module: record.module,
+            manifest: record.manifest,
+        });
+        await this.writeJson(this.headFile, {
+            version,
+            maxVersion: this.maxVersion,
+            ts,
+            sessionId: record.sessionId,
+            turn: record.turn,
+            hash,
+        });
+        // Keep the live harness file in step with HEAD (it is the source of truth).
+        await fs.writeFile(this.harnessFile, record.module, 'utf8');
+        this.headVersion = version;
+        this.headHash = hash;
+        return { facts, version };
+    }
+    /**
+     * Plan a rollback to the parent of HEAD. Returns null when there is nothing
+     * to undo, otherwise the module source to restore (floored at the baseline).
+     */
+    async prepareRollback() {
+        if (this.headVersion <= 0)
+            return null;
+        const current = await this.readVersion(this.headVersion);
+        const to = current?.parentVersion ?? Math.max(this.headVersion - 1, 0);
+        const module = to > 0 ? (await this.readVersion(to))?.module ?? '' : await this.readBaseline();
+        return { from: this.headVersion, to, module };
+    }
+    /** Persist a rollback (facts + HEAD + change log + harness file). */
+    async recordRollback(from, to, turn, sessionId, module) {
+        const ts = nowIso();
+        const facts = [
+            `harness_rollback(${from}, ${to}, ${prologAtom(ts)}, ${prologAtom(sessionId)}, ${turn}).`,
+            `harness_head(${to}, ${prologAtom(ts)}, ${prologAtom(sessionId)}, ${turn}).`,
+        ];
+        await this.appendHarnessFacts(facts);
+        await this.appendJsonl(this.changesFile, { ts, sessionId, turn, kind: 'rollback', from, to });
+        await this.writeJson(this.headFile, {
+            version: to,
+            maxVersion: this.maxVersion,
+            ts,
+            sessionId,
+            turn,
+            rollback: true,
+        });
+        if (module !== undefined) {
+            await fs.writeFile(this.harnessFile, module, 'utf8');
+        }
+        this.headVersion = to;
+        // The hash no longer matches HEAD's content until the next commit.
+        this.headHash = undefined;
+        return facts;
+    }
+    async readVersion(version) {
+        const dir = path.join(this.harnessDir, 'versions');
+        try {
+            const prefix = `${String(version).padStart(4, '0')}_`;
+            const name = (await fs.readdir(dir)).find((entry) => entry.startsWith(prefix));
+            if (!name)
+                return null;
+            const data = JSON.parse(await fs.readFile(path.join(dir, name), 'utf8'));
+            return { module: data.module ?? '', parentVersion: data.parentVersion ?? null };
+        }
+        catch {
+            return null;
+        }
+    }
+    // ---- Session lookup & durable harness snapshots (resume) ----
+    sessionsDir() {
+        return path.join(this.rootAbs, 'sessions');
+    }
+    sessionHarnessFile(sessionId) {
+        return path.join(this.sessionsDir(), sessionId, 'harness.json');
+    }
+    /** True when a session directory exists for `sessionId`. */
+    async sessionExists(sessionId) {
+        try {
+            return (await fs.stat(path.join(this.sessionsDir(), sessionId))).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /** All recorded sessions, oldest first. */
+    async sessionSummaries() {
+        let ids;
+        try {
+            ids = await fs.readdir(this.sessionsDir());
+        }
+        catch {
+            return [];
+        }
+        const summaries = [];
+        for (const id of ids) {
+            let meta = {};
+            try {
+                meta = JSON.parse(await fs.readFile(path.join(this.sessionsDir(), id, 'session.json'), 'utf8'));
+            }
+            catch {
+                // session without metadata (e.g. history disabled mid-way)
+            }
+            summaries.push({
+                id,
+                startedAt: typeof meta.startedAt === 'string' ? meta.startedAt : undefined,
+                endedAt: typeof meta.endedAt === 'string' ? meta.endedAt : null,
+                resumedAt: Array.isArray(meta.resumedAt) ? meta.resumedAt : undefined,
+                lastTurn: await this.lastTurn(id),
+            });
+        }
+        summaries.sort((a, b) => (a.startedAt ?? '').localeCompare(b.startedAt ?? ''));
+        return summaries;
+    }
+    /** The most recently started session, or null when there is none. */
+    async latestSessionId() {
+        const summaries = await this.sessionSummaries();
+        return summaries.length > 0 ? summaries[summaries.length - 1].id : null;
+    }
+    /** The highest turn number recorded for a session (0 when none). */
+    async lastTurn(sessionId = this.sessionId) {
+        const file = path.join(this.sessionsDir(), sessionId, 'turns.jsonl');
+        let text;
+        try {
+            text = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            return 0;
+        }
+        const lines = text.split('\n').filter((line) => line.trim());
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+            try {
+                const record = JSON.parse(lines[index]);
+                if (typeof record.turn === 'number')
+                    return record.turn;
+            }
+            catch {
+                // skip a malformed line
+            }
+        }
+        return 0;
+    }
+    /** Persist the durable harness snapshot beside a session (best effort). */
+    async writeSessionHarness(snapshot, sessionId = this.sessionId) {
+        await this.writeJson(this.sessionHarnessFile(sessionId), snapshot);
+    }
+    /** Read a session's durable harness snapshot, or null when absent. */
+    async readSessionHarness(sessionId = this.sessionId) {
+        try {
+            const data = JSON.parse(await fs.readFile(this.sessionHarnessFile(sessionId), 'utf8'));
+            return typeof data?.module === 'string' ? data : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Buffer one event line (flushed at turn end / dispose). */
+    recordEvent(context, event) {
+        if (this.trace === 'off')
+            return;
+        try {
+            const line = this.serializeEvent(context, event);
+            if (!line)
+                return;
+            this.eventBuffer.push(line);
+            if (this.eventBuffer.length >= 200)
+                void this.flushEvents();
+        }
+        catch {
+            // never let tracing break the turn
+        }
+    }
+    async flushEvents() {
+        if (this.eventBuffer.length === 0)
+            return;
+        const payload = `${this.eventBuffer.join('\n')}\n`;
+        this.eventBuffer = [];
+        await this.appendRaw(path.join(this.sessionDirAbs, 'events.jsonl'), payload);
+    }
+    serializeEvent(context, event) {
+        const base = {
+            ts: nowIso(),
+            sessionId: this.sessionId,
+            turn: context.turn,
+            frame: context.frame,
+            type: event.type,
+        };
+        const put = (key, value) => {
+            if (value !== undefined && value !== null)
+                base[key] = this.scrub(value);
+        };
+        switch (event.type) {
+            case 'stream':
+                if (this.trace === 'full')
+                    put('content', event.content);
+                break;
+            case 'output':
+            case 'answer':
+            case 'error':
+            case 'log':
+                put('content', event.content);
+                break;
+            case 'tool_call':
+                put('toolName', event.toolName);
+                put('toolState', event.toolState);
+                put('toolSummary', event.toolSummary);
+                put('toolArgs', event.toolArgs);
+                break;
+            case 'solution':
+                put('bindings', event.solution?.bindings);
+                break;
+            case 'usage':
+                put('usage', event.usage);
+                break;
+            case 'task_activity':
+                put('taskState', event.taskState);
+                put('taskDescription', event.taskDescription);
+                break;
+            default:
+                break;
+        }
+        return JSON.stringify(base);
+    }
+    /** Redact and truncate strings recursively. */
+    scrub(value) {
+        if (typeof value === 'string') {
+            let text = value;
+            for (const pattern of this.redactions)
+                text = text.replace(pattern, '[redacted]');
+            if (Buffer.byteLength(text, 'utf8') > this.maxEventBytes) {
+                text = `${text.slice(0, this.maxEventBytes)}…[truncated]`;
+            }
+            return text;
+        }
+        if (Array.isArray(value))
+            return value.map((entry) => this.scrub(entry));
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, this.scrub(entry)]));
+        }
+        return value;
+    }
+    async appendFacts(facts) {
+        if (facts.length === 0)
+            return;
+        await this.appendRaw(this.historyFile, `${facts.join('\n')}\n`);
+    }
+    async appendHarnessFacts(facts) {
+        if (facts.length === 0)
+            return;
+        await this.appendRaw(this.harnessFactsFile, `${facts.join('\n')}\n`);
+    }
+    async appendJsonl(file, record) {
+        if (this.trace === 'off' && file.endsWith('events.jsonl'))
+            return;
+        await this.appendRaw(file, `${JSON.stringify(record)}\n`);
+    }
+    async appendRaw(file, text) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.appendFile(file, text, 'utf8');
+    }
+    async writeJson(file, value) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    }
+    /** Keep only the newest sessions and versions. */
+    async prune() {
+        await this.pruneDir(path.join(this.rootAbs, 'sessions'), this.maxSessions);
+        await this.pruneDir(path.join(this.harnessDir, 'versions'), this.maxVersions);
+    }
+    async pruneDir(dir, keep) {
+        try {
+            const entries = await fs.readdir(dir);
+            if (entries.length <= keep)
+                return;
+            const sorted = entries.sort();
+            for (const entry of sorted.slice(0, entries.length - keep)) {
+                await fs.rm(path.join(dir, entry), { recursive: true, force: true });
+            }
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+function splitPredicate(predicate) {
+    const slash = predicate.lastIndexOf('/');
+    if (slash === -1)
+        return [predicate, 0];
+    return [predicate.slice(0, slash), Number(predicate.slice(slash + 1)) || 0];
+}
+function fileStamp(iso) {
+    return iso.replace(/[:.]/g, '-');
+}
+//# sourceMappingURL=history.js.map