deepclause-sdk 0.0.89 → 0.1.1

package/dist/repl/history.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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.
+ */
+export type HistoryTrace = 'off' | 'summary' | 'full';
+export interface HistoryOptions {
+    /** Workspace-relative root (default `.deepclause/repl`). */
+    dir?: string;
+    /** `off`, `summary` (event metadata), or `full` (include streamed text). */
+    trace?: HistoryTrace;
+    maxEventBytes?: number;
+    maxSessions?: number;
+    maxVersions?: number;
+    includeInExport?: boolean;
+    /** Regex sources applied to recorded text before writing. */
+    redact?: string[];
+}
+export interface HistoryEventContext {
+    turn: number;
+    frame?: string;
+}
+export interface HistoryTurnRecord {
+    turn: number;
+    mode: 'goal' | 'prompt';
+    request: string;
+    outcome: 'committed' | 'answered' | 'failed' | 'aborted' | 'query';
+    commitVersion?: number;
+    durationMs: number;
+    modelCalls: number;
+    error?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+export interface HistoryChangedPredicate {
+    predicate: string;
+    action: 'added' | 'removed' | 'replaced';
+}
+export interface HistoryChangeRecord {
+    kind: 'commit' | 'load' | 'reset';
+    sessionId: string;
+    turn: number;
+    changed: HistoryChangedPredicate[];
+    scripts: Array<{
+        path: string;
+        sha256: string;
+    }>;
+    module: string;
+    manifest: string;
+}
+/** A linked script file and its content hash. */
+export interface HistoryScriptRef {
+    path: string;
+    sha256: string;
+}
+/**
+ * Durable snapshot of a session's harness, written beside the session so the
+ * harness can be restored by `--session` even after the process exits or the
+ * scratch bundle is gone. See `docs/DML_REPL_SESSION_HISTORY.md`.
+ */
+export interface SessionHarnessSnapshot {
+    sessionId: string;
+    /** Last recorded harness version for the session (0 = none). */
+    version: number;
+    /** sha256 of `module` + `scripts` (see `harnessHash`). */
+    hash: string;
+    /** True when `module` still matches the recorded version's snapshot. */
+    clean: boolean;
+    savedAt: string;
+    scripts: HistoryScriptRef[];
+    /** Serialized conversation memory, when captured. */
+    memory?: {
+        harness: string;
+        meta: string;
+        /** Authoring-agent conversation (TS agent mode), for resume. */
+        agent?: Array<{
+            role: 'system' | 'user' | 'assistant';
+            content: string;
+        }>;
+    };
+    module: string;
+}
+/** Metadata about a past REPL session, for `--session` resolution. */
+export interface SessionSummary {
+    id: string;
+    startedAt?: string;
+    endedAt?: string | null;
+    resumedAt?: string[];
+    lastTurn?: number;
+}
+/** Stable hash of a harness module plus its linked scripts. */
+export declare function harnessHash(module: string, scripts: Array<{
+    path: string;
+    sha256: string;
+}>): string;
+/** Single-quoted Prolog atom. */
+export declare function prologAtom(value: string): string;
+export declare class HistoryStore {
+    private readonly sessionId;
+    /** Harness this session edits (a project can hold several). */
+    readonly harnessName: string;
+    readonly rootRel: string;
+    readonly sessionDirRel: string;
+    private readonly rootAbs;
+    private readonly sessionDirAbs;
+    private readonly trace;
+    private readonly maxEventBytes;
+    private readonly maxSessions;
+    private readonly maxVersions;
+    private readonly redactions;
+    private eventBuffer;
+    /** Current HEAD version (0 = empty harness) and the highest ever issued. */
+    private headVersion;
+    private maxVersion;
+    /** Hash recorded for the current HEAD (for session-snapshot consistency). */
+    private headHash?;
+    constructor(workspacePath: string, sessionId: string, options?: HistoryOptions, 
+    /** Harness this session edits (a project can hold several). */
+    harnessName?: string);
+    get currentVersion(): number;
+    get currentHash(): string | undefined;
+    get tracePath(): string;
+    private get historyFile();
+    /** Per-harness store: `.deepclause/repl/harnesses/<name>/`. */
+    private get harnessDir();
+    /** The single pre-harnesses store, migrated to `harnesses/main` once. */
+    private get legacyHarnessDir();
+    /** The current content (source of truth; portable as a `.dml`). */
+    private get harnessFile();
+    /** The module the harness started from (version 0 / rollback floor). */
+    private get baselineFile();
+    private get headFile();
+    private get changesFile();
+    /** Whether the harness has any committed versions (HEAD > baseline). */
+    get hasCommits(): boolean;
+    /** Facts for this harness only (`harness_change`/`changed`/`head`/`rollback`). */
+    private get harnessFactsFile();
+    /** Create directories, read the current version, and prune old entries. */
+    init(): Promise<void>;
+    /** Move the legacy single `harness/` store into `harnesses/main/` (once). */
+    private migrateLegacyHarness;
+    /** Ensure `baseline.dml` and `harness.dml` exist (materializing from HEAD). */
+    private ensureHarnessFiles;
+    /** The module at HEAD: the live `harness.dml`, or the HEAD version snapshot. */
+    readHeadModule(): Promise<{
+        version: number;
+        module: string;
+    } | null>;
+    /** The module this harness started from (version 0). */
+    readBaseline(): Promise<string>;
+    /**
+     * 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.
+     */
+    setInitialBaseline(module: string): Promise<void>;
+    /** The persisted facts, to be loaded into the module at session start. */
+    readFacts(): Promise<string>;
+    /** The turns recorded for a session, oldest first (used for input history). */
+    readTurns(sessionId?: string): Promise<HistoryTurnRecord[]>;
+    startSession(info: {
+        model: string;
+        backend: string;
+    }, options?: {
+        resume?: boolean;
+    }): Promise<string[]>;
+    endSession(reason: string): Promise<string[]>;
+    recordTurn(record: HistoryTurnRecord): Promise<string[]>;
+    /**
+     * Record a harness version. Returns the facts to assert and the new version.
+     */
+    recordChange(record: HistoryChangeRecord): Promise<{
+        facts: string[];
+        version: number;
+    }>;
+    /**
+     * 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).
+     */
+    prepareRollback(): Promise<{
+        from: number;
+        to: number;
+        module: string;
+    } | null>;
+    /** Persist a rollback (facts + HEAD + change log + harness file). */
+    recordRollback(from: number, to: number, turn: number, sessionId: string, module?: string): Promise<string[]>;
+    private readVersion;
+    private sessionsDir;
+    private sessionHarnessFile;
+    /** True when a session directory exists for `sessionId`. */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /** All recorded sessions, oldest first. */
+    sessionSummaries(): Promise<SessionSummary[]>;
+    /** The most recently started session, or null when there is none. */
+    latestSessionId(): Promise<string | null>;
+    /** The highest turn number recorded for a session (0 when none). */
+    lastTurn(sessionId?: string): Promise<number>;
+    /** Persist the durable harness snapshot beside a session (best effort). */
+    writeSessionHarness(snapshot: SessionHarnessSnapshot, sessionId?: string): Promise<void>;
+    /** Read a session's durable harness snapshot, or null when absent. */
+    readSessionHarness(sessionId?: string): Promise<SessionHarnessSnapshot | null>;
+    /** Buffer one event line (flushed at turn end / dispose). */
+    recordEvent(context: HistoryEventContext, event: {
+        type: string;
+    } & Record<string, unknown>): void;
+    flushEvents(): Promise<void>;
+    private serializeEvent;
+    /** Redact and truncate strings recursively. */
+    private scrub;
+    private appendFacts;
+    private appendHarnessFacts;
+    private appendJsonl;
+    private appendRaw;
+    private writeJson;
+    /** Keep only the newest sessions and versions. */
+    private prune;
+    private pruneDir;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/repl/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/repl/history.ts"],"names":[],"mappings":"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"}