@wrongstack/core 0.9.19 → 0.10.0

package/dist/storage/index.d.ts

@@ -1,17 +1,401 @@
-export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, M as MemoryStoreOptions, j as MigrationContext, k as MigrationResult, P as PersistedQueueItem, l as PlanFile, m as PlanItem, n as PlanTemplate, Q as QueueStore, R as RecoveryLock, o as RecoveryLockOptions, S as SessionAnalyzer, p as SessionStoreOptions, T as TodosCheckpointFile, q as addPlanItem, r as attachPlanCheckpoint, s as attachTodosCheckpoint, t as clearPlan, u as deriveTodosFromPlanItem, v as emptyPlan, w as formatPlan, x as formatPlanTemplates, y as getPlanTemplate, z as listPlanTemplates, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from '../plan-templates-fkQTyz3U.js';
-export { D as DefaultSessionReader } from '../session-reader-CSWcb5Ga.js';
+export { A as AbandonedSession, a as AttachmentStoreOptions, C as ConfigLoaderOptions, b as ConfigMigration, c as ConfigMigrationError, d as ConfigSource, D as DEFAULT_CONFIG_MIGRATIONS, e as DefaultAttachmentStore, f as DefaultConfigLoader, g as DefaultConfigStore, h as DefaultMemoryStore, i as DefaultSessionStore, M as MemoryStoreOptions, j as MigrationContext, k as MigrationResult, P as PersistedQueueItem, l as PlanFile, m as PlanItem, n as PlanTemplate, Q as QueueStore, R as RecoveryLock, o as RecoveryLockOptions, S as SessionAnalyzer, p as SessionStoreOptions, T as TodosCheckpointFile, q as addPlanItem, r as attachPlanCheckpoint, s as attachTodosCheckpoint, t as clearPlan, u as deriveTodosFromPlanItem, v as emptyPlan, w as formatPlan, x as formatPlanTemplates, y as getPlanTemplate, z as listPlanTemplates, B as loadPlan, E as loadTodosCheckpoint, F as removePlanItem, G as runConfigMigrations, H as savePlan, I as saveTodosCheckpoint, J as setPlanItemStatus } from '../plan-templates-BWs6Je7j.js';
+export { D as DefaultSessionReader, f as DefaultSessionReaderOptions, S as SessionReader } from '../session-reader-CCSBfQmd.js';
+import { p as Request, q as Response, w as SessionEvent } from '../context-7u93AcGD.js';
 import { S as SessionRewinder, C as CheckpointInfo, a as RewindResultExtended } from '../session-rewinder-C9HnMkhP.js';
 export { D as DirectorStateCheckpoint, a as DirectorStateSnapshot, b as DirectorSubagentState, c as DirectorTaskState, l as loadDirectorState } from '../director-state-BmYi3DGA.js';
-export { G as GoalFile, J as JournalEntry, M as MAX_JOURNAL_ENTRIES, a as appendJournal, e as emptyGoal, f as formatGoal, g as goalFilePath, l as loadGoal, s as saveGoal, b as summarizeUsage } from '../goal-store-C7jcumEh.js';
-import { a as WstackPaths } from '../wstack-paths-BCgmTNlG.js';
-import { S as SyncCategory, m as SyncConfig } from '../config-CWva0qoL.js';
-import '../events-CiG9qUM_.js';
-import '../context-BRNbHmRM.js';
+export { A as AuditLevel, C as CORE_RECONSTRUCT_EVENTS, G as GoalFile, J as JournalEntry, M as MAX_JOURNAL_ENTRIES, S as STANDARD_AUDIT_EVENTS, a as SessionEventBridge, b as SessionEventBridgeOptions, c as SessionSamplingOptions, T as ToolProgressSamplingOptions, d as appendJournal, e as createSessionEventBridge, f as emptyGoal, g as formatGoal, h as goalFilePath, l as loadGoal, r as resolveAuditLevel, i as resolveSessionLoggingConfig, s as saveGoal, j as summarizeUsage } from '../goal-store-BeRsj7YX.js';
+import { a as WstackPaths } from '../wstack-paths-eMXnY1_X.js';
+import { m as SyncCategory, n as SyncConfig } from '../config-CJXBka2r.js';
+import '../events-Bw1K5E6K.js';
 import '../secret-scrubber-3MHDDAtm.js';
 import '../memory-CEXuo7sz.js';
 import '../secret-vault-DoISxaKO.js';
 import '../models-registry-BcYJDKLm.js';
 
+/**
+ * L2-B: AnnotationsStore — sidecar storage for collaboration annotations
+ * (Phase 2 of idea #13 from IDEAS.md).
+ *
+ * Why a sidecar file, not the session JSONL?
+ *
+ *   The session log is an event-sourced append-only journal
+ *   (`packages/core/src/types/session.ts` invariant: events are
+ *   append-only, with `truncateToCheckpoint` only as an explicit
+ *   rewind). Mixing in human-typed annotations would break that
+ *   invariant — the user's note about "this rm looks dangerous"
+ *   is not part of the agent's event history; it is meta-commentary
+ *   on the history.
+ *
+ *   So we keep annotations in a sibling file: one JSON document per
+ *   session, at `<sessionDir>/<sessionId>.annotations.json`. The
+ *   shape is a simple versioned array, written atomically.
+ *
+ * Concurrency model:
+ *
+ *   The store uses a per-session Promise chain to serialize writes.
+ *   Multiple annotators adding notes at the same time will queue,
+ *   not race. The atomic write itself is the second line of
+ *   defense (in case the chain is bypassed — e.g. two processes
+ *   pointing at the same dir).
+ */
+/** Wire/storage shape for one annotation. */
+interface Annotation {
+    /** Stable id (UUIDv4-ish). Referenced by resolve/delete. */
+    id: string;
+    /** Session this annotation belongs to. */
+    sessionId: string;
+    /** Index into the session event log the annotation refers to. */
+    atEventIndex: number;
+    /** Participant id of the annotator (matches WSCollabParticipantJoined.participantId). */
+    authorId: string;
+    /** Human-readable role label snapshot for display (e.g. "annotator"). */
+    authorRole: 'annotator';
+    /** The note itself. Trimmed, capped at `MAX_TEXT_LENGTH` on add. */
+    text: string;
+    /** ISO timestamp of creation. */
+    createdAt: string;
+    /** Resolved state. Annotations start unresolved. */
+    resolved: boolean;
+    /** ISO timestamp when resolved (if resolved). */
+    resolvedAt?: string;
+    /** Participant id of the resolver (if resolved). */
+    resolvedBy?: string;
+}
+interface AnnotationsStoreOptions {
+    /** Directory where `<sessionId>.annotations.json` files live. */
+    dir: string;
+}
+declare class AnnotationsStore {
+    private readonly dir;
+    /** Per-session write queue. Created lazily on first add. */
+    private readonly writeChains;
+    constructor(opts: AnnotationsStoreOptions);
+    /**
+     * Return all annotations for `sessionId` in insertion order
+     * (oldest first). Returns an empty array when no file exists
+     * yet (the normal case for a fresh session).
+     */
+    list(sessionId: string): Promise<Annotation[]>;
+    /**
+     * Convenience: only unresolved annotations, newest first — the
+     * common UI rendering for "what still needs attention?".
+     */
+    listOpen(sessionId: string): Promise<Annotation[]>;
+    /**
+     * Add a new annotation. Returns the persisted record (with id
+     * and timestamps filled in). Throws when `text` is empty or
+     * exceeds `MAX_TEXT_LENGTH`.
+     */
+    add(input: {
+        sessionId: string;
+        atEventIndex: number;
+        authorId: string;
+        text: string;
+    }): Promise<Annotation>;
+    /**
+     * Mark an annotation as resolved. Returns the updated record, or
+     * `null` if no annotation with that id exists in this session.
+     * Idempotent: resolving an already-resolved annotation refreshes
+     * `resolvedAt` / `resolvedBy` to the latest call.
+     */
+    resolve(input: {
+        sessionId: string;
+        annotationId: string;
+        resolvedBy: string;
+    }): Promise<Annotation | null>;
+    private filePath;
+    private readFile;
+    private writeFile;
+    /**
+     * Serialize writes per-sessionId. We chain promises instead of
+     * using a Mutex class so the contract is obvious from the
+     * call-site: `enqueue(sid, fn)` runs `fn` after every prior
+     * enqueue for `sid` has settled.
+     */
+    private enqueue;
+}
+
+/**
+ * ReplayLogStore — sidecar store for deterministic-replay support
+ * (idea #2 from IDEAS.md). One JSONL file per session, recording
+ * every provider request/response pair so the same agent loop can
+ * be re-run later with frozen API responses.
+ *
+ * Why a sidecar (not the session JSONL)?
+ *
+ *   Same reason as `AnnotationsStore` — the session log is
+ *   event-sourced and append-only; a provider request payload can be
+ *   tens of kilobytes (especially with long conversation history),
+ *   and we want replay to be opt-in (recorded only when the user
+ *   runs with `--replay` or a future equivalent). Mixing it into
+ *   the event log would inflate every read for replay-irrelevant
+ *   paths.
+ *
+ * File layout: `<dir>/<sessionId>.replay.jsonl`, one entry per line.
+ * Each entry: `{ hash, ts, request, response }`. The `hash` is
+ * computed via `hashRequest` so lookups are O(1) by hash.
+ *
+ * Concurrency: per-session write queue (same pattern as
+ * `AnnotationsStore`). Reads are lock-free; the write chain makes
+ * the append + rehash sequence atomic.
+ */
+interface ReplayEntry {
+    hash: string;
+    ts: string;
+    request: Request;
+    response: Response;
+}
+interface ReplayLogStoreOptions {
+    /** Directory where `<sessionId>.replay.jsonl` files live. */
+    dir: string;
+    /**
+     * Cap on the number of entries per session. When a `record` would
+     * push the file beyond this, the oldest entries are evicted (LRU
+     * by insertion order). Set to `Infinity` to disable rotation.
+     * Defaults to 1000 — a single LLM call averages ~5KB serialized
+     * (messages + tools + response), so 1000 entries is ~5MB per
+     * session which is a reasonable upper bound.
+     */
+    maxEntries?: number;
+}
+declare class ReplayLogStore {
+    private readonly dir;
+    private readonly writeChains;
+    /** Per-session hash → entry index, kept in memory after the first load. */
+    private readonly cache;
+    private readonly maxEntries;
+    constructor(opts: ReplayLogStoreOptions);
+    /**
+     * Record a request/response pair. Idempotent on hash: a second
+     * `record` for the same hash is a no-op (the existing entry wins).
+     * Returns the hash.
+     */
+    record(input: {
+        sessionId: string;
+        request: Request;
+        response: Response;
+    }): Promise<string>;
+    /**
+     * Look up an entry by hash. Returns `null` when the request has
+     * not been recorded for this session. O(1) after the first call
+     * per session (in-memory cache).
+     */
+    lookup(sessionId: string, hash: string): Promise<ReplayEntry | null>;
+    /** All recorded entries for a session, in insertion order. */
+    load(sessionId: string): Promise<ReplayEntry[]>;
+    /**
+     * List every session id that has a replay log in the store dir.
+     * Returns an array of `{ sessionId, entryCount, path }` sorted
+     * by sessionId for stable output. Used by `wstack replay --list`.
+     */
+    list(): Promise<Array<{
+        sessionId: string;
+        entryCount: number;
+        path: string;
+    }>>;
+    private filePath;
+    private readAll;
+    private writeAll;
+    private ensureCache;
+    private enqueue;
+}
+
+/**
+ * Idea #1 from IDEAS.md — Stateful Session Recovery.
+ *
+ * `SessionRecovery` is the read-side companion to the in-flight
+ * marker mechanism. When the agent loop is running, it writes an
+ * `in_flight_start` event at the current point in the log. On
+ * clean shutdown, a matching `in_flight_end` follows. If the
+ * process dies (crash, OOM, machine sleep, SIGKILL) the marker
+ * is the last event in the file — and `detectStale` flags the
+ * session as "incomplete, can be resumed".
+ *
+ * Phase 1 of this feature is **detection only**. The actual
+ * re-execution of incomplete work is a follow-up: it requires
+ * tracking pending tool calls, mid-stream LLM responses, and
+ * uncommitted file changes — and re-running the agent loop from
+ * the last `checkpoint` event. The detection layer is independent
+ * and ships first because (a) it gives the user immediate
+ * visibility into what died, and (b) it's the foundation for the
+ * resume command and the CLI's "Incomplete sessions" surface.
+ *
+ * Concurrency: pure read; no writes. Safe to call from multiple
+ * processes simultaneously.
+ */
+interface StaleSession {
+    sessionId: string;
+    /** Path to the JSONL log. */
+    path: string;
+    /** Last event ts (the in_flight_start timestamp). */
+    lastEventTs: string;
+    /** Context the agent was working on when it died. */
+    context: string;
+    /** Total events in the log. */
+    eventCount: number;
+}
+interface RecoveryPlan {
+    sessionId: string;
+    /** True if the session is stale (has a dangling in_flight_start). */
+    stale: boolean;
+    /** The last `checkpoint` event before the un-replayed work, or null. */
+    lastCheckpoint: SessionEvent | null;
+    /** All events after the last checkpoint (i.e. the work that needs re-execution). */
+    pendingEvents: SessionEvent[];
+    /** The dangling in_flight_start event, if any. */
+    inFlightStart: SessionEvent | null;
+    /** Free-form context the agent was working on, if any. */
+    context: string | null;
+}
+/**
+ * Result of `SessionRecovery.recover(sessionId)`. Distinct from
+ * `StaleSession`: a session is "stale" if the last event is an
+ * open marker, but a "recovery plan" can also be generated for
+ * clean sessions whose last checkpoint is older than the
+ * conversation history (e.g. a user-initiated "rewind to last
+ * good state" flow). Phase 2 of idea #1: this returns the plan;
+ * the actual kernel re-execution is a follow-up.
+ */
+declare class SessionRecovery {
+    private readonly dir;
+    /**
+     * Scan a session log and return a `StaleSession` if and only
+     * if the last event is an `in_flight_start` without a matching
+     * `in_flight_end`. Returns `null` when:
+     *   - the log does not exist;
+     *   - the log is empty;
+     *   - the last event is `in_flight_end` (clean shutdown);
+     *   - the last event is something else (e.g. an unannotated
+     *     legacy log without in-flight markers).
+     */
+    detectStale(sessionId: string): Promise<StaleSession | null>;
+    /**
+     * Generate a recovery plan for a session. The plan describes
+     * "what would be re-executed" if the user chose to resume —
+     * everything after the last `checkpoint` event, plus the
+     * dangling in-flight marker if present.
+     *
+     * Returns a non-null plan for ANY session that has at least
+     * one event after a checkpoint (or, for legacy sessions, at
+     * least one event). Pure read; no mutation.
+     */
+    recover(sessionId: string): Promise<RecoveryPlan | null>;
+    /**
+     * List every stale session in a directory. Returns an array
+     * (possibly empty) sorted by `lastEventTs` descending — most
+     * recent crash first.
+     */
+    listResumable(): Promise<StaleSession[]>;
+    private filePath;
+    /**
+     * Stream-parse the last few lines of a JSONL log. We do NOT load
+     * the whole file into memory — for long-running sessions the log
+     * can be megabytes. Instead we read tail-ward and find the last
+     * `in_flight_start` / `in_flight_end` pair.
+     */
+    private parseForStale;
+    constructor(dir: string);
+}
+
+/**
+ * ToolAuditLog — idea #9 from IDEAS.md.
+ *
+ * Tamper-evident audit trail for tool calls. Every tool_use /
+ * tool_result pair is appended to a sidecar JSONL with a chained
+ * SHA-256 — each entry's `prevHash` is the prior entry's `hash`,
+ * so any post-hoc modification of a single line breaks the chain
+ * from that point forward.
+ *
+ * Why a sidecar (not the session JSONL)?
+ *   Same reason as `AnnotationsStore` and `ReplayLogStore`: the
+ *   session log is an event-sourced journal. Mixing in a hash
+ *   chain would inflate every read and tightly couple the
+ *   integrity check to the event format. Sidecar keeps both
+ *   concerns orthogonal.
+ *
+ * What "tamper-evident" means here:
+ *   - The hash covers the full serialized entry: tool name, id,
+ *     input, output, timestamp, author. Changing any byte
+ *     changes the hash.
+ *   - The chain is sequential — a verifier walks the file in
+ *     order, recomputing each hash, and checks `prevHash`
+ *     matches the previous entry's `hash`.
+ *   - Any insertion, deletion, or modification of a single
+ *     entry surfaces as a "chain broken at entry N" verdict.
+ *
+ * What it does NOT defend against:
+ *   - An attacker who rewrites the whole file consistently.
+ *     For that you'd need an external anchor (signing key,
+ *     transparency log, etc.) — out of scope for Phase 1.
+ *   - The agent itself misbehaving; this is post-hoc audit, not
+ *     real-time enforcement. Use `PermissionPolicy` for that.
+ *
+ * File layout: `<dir>/<sessionId>.audit.jsonl`, one entry per
+ * line. The chain starts with a `genesis` entry whose
+ * `prevHash` is all zeros.
+ */
+interface AuditEntry {
+    /** Monotonic index (0-based). */
+    index: number;
+    /** UUID for cross-referencing with logs. */
+    id: string;
+    /** ISO timestamp. */
+    ts: string;
+    /** Hash of the previous entry (or all-zeros for the genesis entry). */
+    prevHash: string;
+    /** Hash of this entry's content (sha256 over the canonical JSON). */
+    hash: string;
+    toolName: string;
+    toolUseId: string;
+    input: unknown;
+    output: unknown;
+    isError: boolean;
+}
+type VerifyResult = {
+    ok: true;
+    entries: number;
+} | {
+    ok: false;
+    brokenAt: number;
+    reason: string;
+};
+interface ToolAuditLogOptions {
+    /** Directory where `<sessionId>.audit.jsonl` files live. */
+    dir: string;
+}
+declare class ToolAuditLog {
+    private readonly dir;
+    /** In-memory cache of the last entry's hash (per session), to compute chains efficiently. */
+    private readonly tailHash;
+    private readonly writeChains;
+    constructor(opts: ToolAuditLogOptions);
+    /**
+     * Append a tool call/result pair to the chain. Returns the
+     * resulting entry. Idempotency is not guaranteed — if you
+     * record the same tool_use twice you get two entries. That's
+     * intentional: the audit log is a record, not a cache.
+     */
+    record(input: {
+        sessionId: string;
+        toolName: string;
+        toolUseId: string;
+        input: unknown;
+        output: unknown;
+        isError: boolean;
+    }): Promise<AuditEntry>;
+    /**
+     * Walk the chain and verify every entry's hash and prevHash.
+     * Returns a structured verdict — never throws.
+     */
+    verify(sessionId: string): Promise<VerifyResult>;
+    /** All entries for a session, in insertion order. */
+    load(sessionId: string): Promise<AuditEntry[]>;
+    private filePath;
+    private readAll;
+    private appendLine;
+    private enqueue;
+}
+
 interface SessionRewinderOptions {
     sessionsDir: string;
     /** The project root directory; used to validate rewind targets stay inside it. */
@@ -100,4 +484,4 @@ declare class CloudSync {
     private walkDir;
 }
 
-export { ALL_SYNC_CATEGORIES, CloudSync, DefaultPromptStore, DefaultSessionRewinder, type PromptEntry, type PromptStore, type SessionRewinderOptions, SyncCategory, SyncConfig, type SyncResult };
+export { ALL_SYNC_CATEGORIES, type Annotation, AnnotationsStore, type AnnotationsStoreOptions, type AuditEntry, CloudSync, DefaultPromptStore, DefaultSessionRewinder, type PromptEntry, type PromptStore, type RecoveryPlan, type ReplayEntry, ReplayLogStore, type ReplayLogStoreOptions, SessionRecovery, type SessionRewinderOptions, type StaleSession, SyncCategory, SyncConfig, type SyncResult, ToolAuditLog, type ToolAuditLogOptions, type VerifyResult };