@wrongstack/core 0.1.9 → 0.2.0

package/dist/storage/index.d.ts

@@ -0,0 +1,540 @@
+import { E as EventBus } from '../events-B6Q03pTu.js';
+import { o as SessionStore, n as SessionMetadata, q as SessionWriter, k as ResumedSession, S as SessionData, p as SessionSummary, b as ContentBlock, m as SessionEvent, aa as TodoItem, a4 as ConversationState } from '../context-u0bryklF.js';
+import { e as AttachmentStore, A as AddAttachmentInput, d as AttachmentRef, a as Attachment } from '../session-reader-C3x96CDR.js';
+export { D as DefaultSessionReader } from '../session-reader-C3x96CDR.js';
+import { b as MemoryStore, a as MemoryScope } from '../memory-CEXuo7sz.js';
+import { a as WstackPaths } from '../wstack-paths-BGu2INTm.js';
+import { b as ConfigStore, C as Config, a as ConfigLoader } from '../config-DXrqb41m.js';
+import { S as SecretVault } from '../secret-vault-DoISxaKO.js';
+import '../models-registry-Y2xbog0E.js';
+
+interface SessionStoreOptions {
+    dir: string;
+    /** Optional EventBus for emitting session diagnostics. */
+    events?: EventBus;
+}
+declare class DefaultSessionStore implements SessionStore {
+    private readonly dir;
+    private readonly events?;
+    constructor(opts: SessionStoreOptions);
+    create(meta: Omit<SessionMetadata, 'startedAt'>): Promise<SessionWriter>;
+    resume(id: string): Promise<ResumedSession>;
+    load(id: string): Promise<SessionData>;
+    list(limit?: number): Promise<SessionSummary[]>;
+    private summaryFor;
+    delete(id: string): Promise<void>;
+    private summarize;
+    private metaFromEvents;
+    private replay;
+}
+
+/**
+ * The persisted form of a single queued user message. The TUI's
+ * in-memory QueueItem has a render id; that's pure UI bookkeeping, so
+ * we drop it when serializing — fresh ids are assigned on rehydrate.
+ */
+interface PersistedQueueItem {
+    displayText: string;
+    blocks: ContentBlock[];
+}
+/**
+ * Side-file storage for a session's pending input queue. Lives at
+ * `<sessionDir>/queue.json` next to the attachment spool. Reads are
+ * tolerant (missing/malformed file → empty array); writes are atomic
+ * (tmp + rename) so a crash mid-write can never leave a partial file
+ * the next launch would choke on.
+ *
+ * The contract is "snapshot replacement": every mutation hands the
+ * full queue and we rewrite the file. The queue is small (rarely more
+ * than a handful of messages), so this is cheaper than delta logging
+ * and avoids the replay complexity.
+ */
+declare class QueueStore {
+    private readonly file;
+    constructor(opts: {
+        dir: string;
+    });
+    write(items: PersistedQueueItem[]): Promise<void>;
+    read(): Promise<PersistedQueueItem[]>;
+    clear(): Promise<void>;
+}
+
+interface AttachmentStoreOptions {
+    /**
+     * Directory for spooling payloads larger than `spoolThresholdBytes`.
+     * When omitted, all payloads stay in memory.
+     */
+    spoolDir?: string;
+    spoolThresholdBytes?: number;
+}
+/**
+ * In-memory attachment store with optional disk spool. Placeholder syntax
+ * is `[<kind> #<seq>]` where kind is `pasted` / `image` / `file`. Unknown
+ * placeholders are passed through as-is so users can write that literal
+ * text without losing it.
+ */
+declare class DefaultAttachmentStore implements AttachmentStore {
+    private readonly items;
+    private readonly refs;
+    private nextSeq;
+    private readonly spoolDir;
+    private readonly spoolThreshold;
+    constructor(opts?: AttachmentStoreOptions);
+    add(input: AddAttachmentInput): Promise<AttachmentRef>;
+    get(id: string): Promise<Attachment | undefined>;
+    list(): AttachmentRef[];
+    expand(text: string): Promise<ContentBlock[]>;
+    clear(): Promise<void>;
+    private toBlock;
+}
+
+interface MemoryStoreOptions {
+    paths: WstackPaths;
+}
+/**
+ * Three scopes:
+ *   project-agents → <project>/.wrongstack/AGENTS.md     (committed)
+ *   project-memory → ~/.wrongstack/projects/<hash>/memory.md   (per-project agent notes)
+ *   user-memory    → ~/.wrongstack/memory.md             (global personal memory)
+ */
+declare class DefaultMemoryStore implements MemoryStore {
+    private readonly files;
+    /**
+     * Per-scope serialization queue. `remember` / `forget` / `consolidate` /
+     * `clear` are read-modify-write against a single file; without a lock,
+     * two concurrent calls on the same scope can read the same baseline and
+     * the later write silently drops the earlier entry. We chain each
+     * mutation onto the prior promise for the same scope so they run in
+     * issue order. Different scopes still proceed in parallel.
+     *
+     * The chain tracks only the last pending write. If a write fails, its
+     * error is caught and swallowed (line 43) so the chain stays alive for
+     * subsequent calls. A crash between atomicWrite() and backup copy leaves
+     * the file at its new content with no backup — acceptable for an optional
+     * backup whose worst case is losing a memory consolidation pass.
+     */
+    private readonly writeChain;
+    constructor(opts: MemoryStoreOptions);
+    private runSerialized;
+    readAll(): Promise<string>;
+    read(scope: MemoryScope): Promise<string>;
+    remember(text: string, scope?: MemoryScope): Promise<void>;
+    forget(query: string, scope?: MemoryScope): Promise<number>;
+    private forgetUnsafe;
+    consolidate(scope: MemoryScope): Promise<void>;
+    private consolidateUnsafe;
+    clear(scope?: MemoryScope): Promise<void>;
+}
+
+/**
+ * Reference implementation of `ConfigStore`. Stores a single frozen Config
+ * and notifies watchers synchronously on every update. Updates use a deep
+ * clone so callers can mutate their `partial` argument freely without
+ * tainting state.
+ *
+ * For the CLI: instantiate once at boot, pass the store (not the Config)
+ * to subsystems that care about runtime changes (provider switching,
+ * extension reload).
+ */
+declare class DefaultConfigStore implements ConfigStore {
+    private current;
+    private watchers;
+    constructor(initial: Config);
+    get(): Readonly<Config>;
+    getSection<K extends keyof Config>(key: K): Readonly<Config[K]>;
+    getExtension(pluginName: string): Readonly<Record<string, unknown>>;
+    update(partial: Partial<Config>): Readonly<Config>;
+    watch(cb: (next: Readonly<Config>, prev: Readonly<Config>) => void): () => void;
+}
+
+/**
+ * A single config source. Higher priority wins in merges.
+ * Sources are applied in priority order (lowest first), so a source
+ * with priority=10 overrides one with priority=1.
+ */
+interface ConfigSource {
+    /** Unique name for debugging and error messages. */
+    name: string;
+    /** Lower numbers merge first, higher numbers override lower. Default: 50. */
+    priority?: number;
+    /**
+     * Read the raw config patch. Return an empty object if unavailable.
+     * Errors are surfaced but do not abort loading — the source is skipped.
+     */
+    read(): Promise<Partial<Config>>;
+}
+interface ConfigLoaderOptions {
+    paths: WstackPaths;
+    strict?: boolean;
+    vault?: SecretVault;
+    /** Extra sources merged after the built-in layers. */
+    sources?: ConfigSource[];
+}
+declare class DefaultConfigLoader implements ConfigLoader {
+    private readonly paths;
+    private readonly strict;
+    private readonly vault;
+    private readonly extraSources;
+    constructor(opts: ConfigLoaderOptions);
+    load(opts?: {
+        cliFlags?: Partial<Config>;
+        cwd?: string;
+    }): Promise<Config>;
+    private readJson;
+    private validateBehavior;
+    private validateIdentity;
+}
+
+/**
+ * L2-D: Config version migration framework. Pure functions, decoupled
+ * from disk/CLI — caller passes a parsed JSON object and gets back the
+ * up-to-date `Config` shape (or a structured error explaining why
+ * migration failed).
+ *
+ * Migrations are registered as `{ from, to, migrate }` triples and run
+ * sequentially. Each migration is independently testable. Adding a new
+ * version means appending one migration; existing user configs are
+ * upgraded in place at load time.
+ */
+interface MigrationContext {
+    /**
+     * Original on-disk version of the input. Migrations may use this to
+     * decide between in-place patches and rewrites.
+     */
+    fromVersion: number;
+    /**
+     * Set when the migration writes back to disk. Callers persist the
+     * migrated config when this is true so the user doesn't see the same
+     * migration banner on every boot.
+     */
+    shouldPersist: boolean;
+}
+interface ConfigMigration {
+    /** Version of the input this migration accepts. */
+    from: number;
+    /** Version of the output it produces. */
+    to: number;
+    /** Pure transform — no I/O. */
+    migrate(input: Record<string, unknown>, ctx: MigrationContext): Record<string, unknown>;
+    /** Optional human-readable description for migration logs / banners. */
+    describe?: string;
+}
+interface MigrationResult {
+    /** Final config (still typed as `unknown`-keyed — caller validates). */
+    config: Record<string, unknown>;
+    /** Ordered list of `from→to` versions that ran. */
+    applied: string[];
+    /** True when at least one migration produced changes worth persisting. */
+    shouldPersist: boolean;
+}
+declare class ConfigMigrationError extends Error {
+    readonly fromVersion: number;
+    readonly targetVersion: number;
+    readonly missingStep: number | null;
+    constructor(opts: {
+        message: string;
+        fromVersion: number;
+        targetVersion: number;
+        missingStep: number | null;
+    });
+}
+/**
+ * Run registered migrations until the input reaches `targetVersion`.
+ *
+ * Resolution rules:
+ * 1. If `input.version === targetVersion`, no migrations run; `shouldPersist`
+ *    is false.
+ * 2. Otherwise walk the migration chain from `input.version` upward,
+ *    picking the migration whose `from` matches the current version.
+ * 3. Stop when `current.version === targetVersion`.
+ * 4. If no migration matches at some point, throw `ConfigMigrationError`
+ *    with the missing step recorded for diagnostics.
+ *
+ * Migrations may be downward (e.g. for staged rollouts), but `targetVersion`
+ * must be reachable strictly via the registered chain — there's no implicit
+ * "skip" or transitive resolution.
+ */
+declare function runConfigMigrations(input: Record<string, unknown>, targetVersion: number, migrations: readonly ConfigMigration[]): MigrationResult;
+/**
+ * Default empty migration registry. Real migrations are appended as new
+ * Config versions are introduced. Example (when v2 lands):
+ *
+ *   export const CONFIG_MIGRATIONS: readonly ConfigMigration[] = [
+ *     {
+ *       from: 1, to: 2, describe: 'rename `apiKey` → `auth.apiKey`',
+ *       migrate(cfg) {
+ *         const apiKey = cfg.apiKey;
+ *         delete cfg.apiKey;
+ *         return { ...cfg, auth: { ...(cfg.auth ?? {}), apiKey } };
+ *       },
+ *     },
+ *   ];
+ */
+declare const DEFAULT_CONFIG_MIGRATIONS: readonly ConfigMigration[];
+
+/**
+ * Per-project lockfile used for crash detection. The CLI writes one of
+ * these alongside the session JSONLs (`<projectSessions>/active.json`)
+ * when an interactive run starts, and deletes it on clean exit. If we
+ * find one on the next launch whose owning PID is dead (or whose host
+ * doesn't match), we know the previous run was killed mid-flight and
+ * the session it was writing to is a recovery candidate.
+ *
+ * The lockfile is intentionally per-project (already isolated by
+ * `wpaths.projectSessions`), so two TUIs in two different repos do not
+ * fight each other.
+ */
+interface RecoveryLockOptions {
+    /** Directory the lockfile lives in. Usually `wpaths.projectSessions`. */
+    dir: string;
+    /** This process's PID. Default: `process.pid`. */
+    pid?: number;
+    /** Hostname recorded for the lock. Default: `os.hostname()`. */
+    hostname?: string;
+    /** Locks older than this are considered orphaned (disk wiped, etc.). Default 24h. */
+    maxAgeMs?: number;
+    /** Used to check whether the abandoned session was actually closed cleanly. */
+    sessionStore?: SessionStore;
+    /**
+     * Override the PID-liveness probe. Default: `process.kill(pid, 0)` —
+     * succeeds (or throws EPERM) when the PID is alive, throws ESRCH when
+     * it is gone. Tests inject a deterministic stub.
+     */
+    isPidAlive?: (pid: number) => boolean;
+}
+interface AbandonedSession {
+    sessionId: string;
+    pid: number;
+    startedAt: string;
+    /** Lockfile age in ms at the time of the check. */
+    ageMs: number;
+    /** Number of messages already on disk for this session. */
+    messageCount: number;
+}
+declare class RecoveryLock {
+    private readonly file;
+    private readonly pid;
+    private readonly hostname;
+    private readonly maxAgeMs;
+    private readonly sessionStore?;
+    private readonly probe;
+    constructor(opts: RecoveryLockOptions);
+    /**
+     * Examine the lockfile and decide whether it represents an abandoned
+     * session. Returns `null` if the file is missing, points to a live
+     * instance, references a clean-closed session, is too old, or is
+     * malformed. Otherwise returns enough detail to prompt the user.
+     *
+     * Important: this is a read-only check. We never delete an active
+     * lock from here — if another wstack instance is alive, the caller
+     * should bail or run with a fresh session instead.
+     */
+    checkAbandoned(): Promise<AbandonedSession | null>;
+    /**
+     * Claim the lock for the given session. Overwrites any existing lock
+     * — the caller should have already handled abandonment (via
+     * `checkAbandoned`) before calling this.
+     */
+    write(sessionId: string): Promise<void>;
+    /**
+     * Release the lock. Idempotent — silently succeeds if the file is
+     * already gone (e.g. someone else cleared it, or the directory was
+     * wiped).
+     */
+    clear(): Promise<void>;
+    private readLock;
+}
+
+interface QueryFilter {
+    eventTypes?: string[];
+    toolNames?: string[];
+    timeRange?: {
+        start: string;
+        end: string;
+    };
+}
+interface ModeChange {
+    ts: string;
+    from: string;
+    to: string;
+}
+interface TaskSummary {
+    taskId: string;
+    title: string;
+    status: string;
+    createdAt: string;
+    completedAt?: string;
+}
+interface SessionAnalysis {
+    sessionId: string;
+    totalDuration: number;
+    toolUsageCount: Record<string, number>;
+    errorCount: number;
+    modeChanges: ModeChange[];
+    tasks: TaskSummary[];
+}
+declare class SessionAnalyzer {
+    analyze(events: SessionEvent[]): SessionAnalysis;
+    query(events: SessionEvent[], filter: QueryFilter): SessionEvent[];
+    private calcDuration;
+}
+
+/**
+ * On-disk checkpoint for `ctx.todos`. Written atomically every time the
+ * todo list changes, read once on session resume. This is the missing
+ * piece that lets `wstack resume <id>` rehydrate where the previous run
+ * stopped instead of starting with an empty board.
+ *
+ * Schema is intentionally small — a single JSON object so a future
+ * format bump is easy. The `version` field is the only contract; the
+ * shape under `todos` mirrors `TodoItem` so reading is a straight assign.
+ */
+interface TodosCheckpointFile {
+    version: 1;
+    sessionId: string;
+    updatedAt: string;
+    todos: TodoItem[];
+}
+/** Read a checkpoint from disk. Returns null when the file doesn't
+ *  exist or is corrupt — callers treat both cases as "no prior state".
+ */
+declare function loadTodosCheckpoint(filePath: string): Promise<TodoItem[] | null>;
+/** Write the checkpoint atomically. Best-effort: a write failure is
+ *  logged but does not throw — losing one checkpoint shouldn't bring
+ *  down the agent run.
+ */
+declare function saveTodosCheckpoint(filePath: string, sessionId: string, todos: readonly TodoItem[]): Promise<void>;
+/**
+ * Subscribe a `ConversationState` so every `todos_replaced` mutation
+ * triggers an atomic write to disk. Returns the unsubscribe function.
+ *
+ * Writes are debounced by 150ms so a flurry of edits (e.g. the LLM
+ * marking three items done in the same tool call) coalesces into one
+ * disk hit.
+ */
+declare function attachTodosCheckpoint(state: ConversationState, filePath: string, sessionId: string): () => void;
+
+/**
+ * Plan items are the strategic counterpart to todos. Where `ctx.todos`
+ * is the moment-to-moment task board the LLM mutates per-turn, a plan
+ * captures the higher-level approach — the steps the user (or LLM)
+ * laid out before any work began.
+ *
+ * Plans persist by default (per session) so a resumed session can show
+ * "you were on step 3 of 5". Todos are derived/transient. Both can
+ * coexist: think roadmap (plan) vs. sprint board (todos).
+ */
+interface PlanItem {
+    id: string;
+    title: string;
+    /** Optional longer-form context or rationale. */
+    details?: string;
+    status: 'open' | 'in_progress' | 'done';
+    createdAt: string;
+    updatedAt: string;
+}
+interface PlanFile {
+    version: 1;
+    sessionId: string;
+    title?: string;
+    updatedAt: string;
+    items: PlanItem[];
+}
+declare function loadPlan(filePath: string): Promise<PlanFile | null>;
+declare function savePlan(filePath: string, plan: PlanFile): Promise<void>;
+/** Create a new PlanFile when none exists on disk. */
+declare function emptyPlan(sessionId: string, title?: string): PlanFile;
+declare function addPlanItem(plan: PlanFile, title: string, details?: string): {
+    plan: PlanFile;
+    item: PlanItem;
+};
+declare function removePlanItem(plan: PlanFile, idOrIndex: string): PlanFile;
+declare function setPlanItemStatus(plan: PlanFile, idOrIndex: string, status: PlanItem['status']): PlanFile;
+declare function clearPlan(plan: PlanFile): PlanFile;
+/** Render the plan as a short markdown-ish string suitable for slash output. */
+declare function formatPlan(plan: PlanFile): string;
+/**
+ * Optional: attach a state-listener so meta operations (storing a plan
+ * id on ctx.meta) trigger a save. Currently a stub — plans don't live
+ * on Context, but this keeps the API surface symmetric with the todos
+ * checkpoint so future refactors can flip plans into Context if needed.
+ */
+declare function attachPlanCheckpoint(_state: ConversationState, _filePath: string, _sessionId: string): () => void;
+
+/**
+ * Director state checkpoint — written incrementally throughout a fleet
+ * run so a crashed director can be inspected (and eventually resumed)
+ * instead of leaving only a final `fleet.json` manifest after `shutdown()`.
+ *
+ * Schema is JSON-friendly and deliberately denormalized. Each mutation
+ * triggers an atomic-write of the whole file — small payloads (typically
+ * < 10 KB even with dozens of subagents) make this cheap.
+ */
+interface DirectorSubagentState {
+    id: string;
+    name?: string;
+    role?: string;
+    provider?: string;
+    model?: string;
+    spawnedAt: string;
+}
+interface DirectorTaskState {
+    taskId: string;
+    subagentId?: string;
+    description?: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped' | 'timeout';
+    assignedAt?: string;
+    completedAt?: string;
+    iterations?: number;
+    toolCalls?: number;
+    durationMs?: number;
+    error?: string;
+}
+interface DirectorStateSnapshot {
+    version: 1;
+    directorRunId: string;
+    updatedAt: string;
+    spawnCount: number;
+    maxSpawns?: number;
+    spawnDepth: number;
+    maxSpawnDepth: number;
+    subagents: DirectorSubagentState[];
+    tasks: DirectorTaskState[];
+    /** Aggregated usage snapshot. Optional — populated by the Director on save when available. */
+    usage?: unknown;
+}
+declare function loadDirectorState(filePath: string): Promise<DirectorStateSnapshot | null>;
+/**
+ * In-memory accumulator with atomic-write checkpoint. The Director keeps
+ * an instance, mutates it on every spawn/assign/complete/fail event, and
+ * the instance debounces writes so a burst of activity collapses into a
+ * single disk hit.
+ */
+declare class DirectorStateCheckpoint {
+    private snapshot;
+    private readonly filePath;
+    private timer;
+    private readonly debounceMs;
+    private writing;
+    private rewriteRequested;
+    constructor(filePath: string, init: {
+        directorRunId: string;
+        maxSpawns?: number;
+        spawnDepth: number;
+        maxSpawnDepth: number;
+    }, debounceMs?: number);
+    current(): DirectorStateSnapshot;
+    recordSpawn(sub: DirectorSubagentState, spawnCount: number): void;
+    recordTaskAssigned(task: DirectorTaskState): void;
+    recordTaskStatus(taskId: string, patch: Partial<DirectorTaskState> & {
+        status: DirectorTaskState['status'];
+    }): void;
+    setUsage(usage: unknown): void;
+    /** Force a synchronous flush — used by Director.shutdown(). */
+    flush(): Promise<void>;
+    private bumpUpdatedAt;
+    private schedule;
+    private persist;
+}
+
+export { type AbandonedSession, type AttachmentStoreOptions, type ConfigLoaderOptions, type ConfigMigration, ConfigMigrationError, type ConfigSource, DEFAULT_CONFIG_MIGRATIONS, DefaultAttachmentStore, DefaultConfigLoader, DefaultConfigStore, DefaultMemoryStore, DefaultSessionStore, DirectorStateCheckpoint, type DirectorStateSnapshot, type DirectorSubagentState, type DirectorTaskState, type MemoryStoreOptions, type MigrationContext, type MigrationResult, type PersistedQueueItem, type PlanFile, type PlanItem, QueueStore, RecoveryLock, type RecoveryLockOptions, SessionAnalyzer, type SessionStoreOptions, type TodosCheckpointFile, addPlanItem, attachPlanCheckpoint, attachTodosCheckpoint, clearPlan, emptyPlan, formatPlan, loadDirectorState, loadPlan, loadTodosCheckpoint, removePlanItem, runConfigMigrations, savePlan, saveTodosCheckpoint, setPlanItemStatus };