@mxalbert/context-mode 2.0.0

package/build/session/pricing.js

@@ -0,0 +1,151 @@
+/**
+ * Pricing catalog — single source of truth for per-model USD cost.
+ *
+ * Deep module, tiny interface. At load it reads one curated multi-vendor JSON
+ * (src/session/model-prices.json) into a Map<modelId, Price> in per-Mtok units,
+ * then exposes three pure-ish functions:
+ *
+ *   lookupPrice(modelId)            → Price | null
+ *   computeCostUsd(modelId, tokens) → number  | null
+ *   nativeOrComputed(id, t, native) → number  | null
+ *
+ * WHY THIS EXISTS — the bug it kills:
+ * The old table in src/session/extract.ts hardcoded ~5 Claude rows plus a
+ * `default` row, and any unmatched id (every OpenAI / Gemini / Qwen / DeepSeek
+ * / Grok model) silently inherited Claude-Sonnet pricing. Non-Claude turns were
+ * therefore mispriced. Here each model is priced from ITS OWN curated row, and
+ * an unknown id resolves to `null` (no price) instead of a wrong Claude rate.
+ *
+ * The large litellm catalog (~1.5MB, ~2900 models) is NOT bundled — it lives at
+ * tools/pricing/litellm-catalog.json as the dev-only refresh base for this
+ * curated JSON.
+ *
+ * The curated JSON is small (~13KB, 61 models) and esbuild inlines it into the
+ * hook/server bundles at build time (no runtime fs read, no external file).
+ */
+import catalog from "./model-prices.json" with { type: "json" };
+/**
+ * Read the curated JSON into one Map. A row with a null *input* price is
+ * unusable for cost (the primary bucket has no rate) and is dropped at load so
+ * lookupPrice returns null for it — matching "null-priced entries → no price".
+ * (The two null-input ids are already pruned from the JSON itself; this guard
+ * keeps the loader robust if one is ever re-added.)
+ */
+function buildCatalog() {
+    const map = new Map();
+    const src = catalog;
+    for (const id of Object.keys(src)) {
+        const row = src[id];
+        if (row == null || typeof row !== "object")
+            continue;
+        // No input rate ⇒ no usable price for this model.
+        if (typeof row.input_per_mtok !== "number")
+            continue;
+        map.set(id, {
+            input_per_mtok: row.input_per_mtok,
+            output_per_mtok: typeof row.output_per_mtok === "number" ? row.output_per_mtok : null,
+            cache_read_per_mtok: typeof row.cache_read_per_mtok === "number" ? row.cache_read_per_mtok : null,
+            cache_write_per_mtok: typeof row.cache_write_per_mtok === "number" ? row.cache_write_per_mtok : null,
+        });
+    }
+    return map;
+}
+const CATALOG = buildCatalog();
+/**
+ * Strip a single leading `provider/` segment, char-algorithmically (NO regex).
+ * Walks to the first '/'; everything after it is the bare model id. Only the
+ * FIRST segment is stripped — `openai/gpt-5` → `gpt-5`, `a/b/c` → `b/c` — so a
+ * model id that legitimately contains a slash keeps its remaining segments.
+ * Returns null when there is no '/' (caller already tried the raw form).
+ */
+function stripProviderPrefix(id) {
+    for (let i = 0; i < id.length; i++) {
+        if (id.charCodeAt(i) === 47 /* '/' */) {
+            // Guard against a leading or trailing slash producing an empty segment.
+            if (i === 0 || i === id.length - 1)
+                return null;
+            return id.slice(i + 1);
+        }
+    }
+    return null;
+}
+/** trim + lowercase, char-safe (String.prototype.trim/toLowerCase, no regex). */
+function normalize(id) {
+    return id.trim().toLowerCase();
+}
+/**
+ * Resolve a model id to its curated Price, or null on miss.
+ * Strategy: exact, then normalized (trim+lowercase), then provider-stripped
+ * normalized. Misses return null so the caller can decide (warn / fall back).
+ */
+export function lookupPrice(modelId) {
+    if (typeof modelId !== "string" || modelId.length === 0)
+        return null;
+    // 1. Exact — fastest path, covers ids already in canonical form.
+    const exact = CATALOG.get(modelId);
+    if (exact)
+        return exact;
+    // 2. Normalized — trimmed + lowercased.
+    const norm = normalize(modelId);
+    const byNorm = CATALOG.get(norm);
+    if (byNorm)
+        return byNorm;
+    // 3. Provider-stripped (pi / openclaw / opencode report `provider/model`).
+    const bare = stripProviderPrefix(norm);
+    if (bare) {
+        const byBare = CATALOG.get(bare);
+        if (byBare)
+            return byBare;
+    }
+    return null;
+}
+/** Price one token bucket. A null bucket rate falls back to the input rate. */
+function bucketCost(tokens, rate, inputRate) {
+    if (tokens <= 0)
+        return 0;
+    const effective = typeof rate === "number" ? rate : inputRate;
+    return tokens * effective;
+}
+/**
+ * Σ tokens × per-Mtok price / 1e6 over the four buckets. Returns null when no
+ * price is found OR every token count is zero/absent (so dashboards never show
+ * a misleading "$0.00 for nothing" row). On a price miss, warns exactly once
+ * with the unmatched id so the curated catalog can be extended.
+ *
+ * Bucket → price mapping:
+ *   input_tokens          → input_per_mtok
+ *   output_tokens         → output_per_mtok  (null ⇒ input rate)
+ *   cache_read_tokens     → cache_read_per_mtok  (null ⇒ input rate)
+ *   cache_creation_tokens → cache_write_per_mtok (null ⇒ input rate)
+ */
+export function computeCostUsd(modelId, t) {
+    const input = typeof t.input_tokens === "number" ? t.input_tokens : 0;
+    const output = typeof t.output_tokens === "number" ? t.output_tokens : 0;
+    const cacheRead = typeof t.cache_read_tokens === "number" ? t.cache_read_tokens : 0;
+    const cacheCreate = typeof t.cache_creation_tokens === "number" ? t.cache_creation_tokens : 0;
+    // All buckets empty ⇒ nothing to price, regardless of model.
+    if (input <= 0 && output <= 0 && cacheRead <= 0 && cacheCreate <= 0)
+        return null;
+    const price = lookupPrice(modelId);
+    if (!price || typeof price.input_per_mtok !== "number") {
+        // Unknown model — emit one line so the id can be added to the catalog.
+        console.warn(`[pricing] no curated price for model id: ${modelId}`);
+        return null;
+    }
+    const inputRate = price.input_per_mtok;
+    const microDollars = bucketCost(input, inputRate, inputRate) +
+        bucketCost(output, price.output_per_mtok, inputRate) +
+        bucketCost(cacheRead, price.cache_read_per_mtok, inputRate) +
+        bucketCost(cacheCreate, price.cache_write_per_mtok, inputRate);
+    return microDollars / 1_000_000;
+}
+/**
+ * Prefer a provider-supplied native cost when present, else compute from the
+ * catalog. A native cost of exactly 0 is a real value (free tier) and passes
+ * through — only null/undefined defers to computeCostUsd.
+ */
+export function nativeOrComputed(modelId, t, nativeCostUsd) {
+    if (typeof nativeCostUsd === "number")
+        return nativeCostUsd;
+    return computeCostUsd(modelId, t);
+}

package/build/session/project-attribution.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Project attribution heuristics for session events.
+ *
+ * Goal: avoid pinning all activity to the startup directory when work shifts
+ * across projects mid-session. This module resolves a best-effort project
+ * directory per event and attaches a confidence score + source signal.
+ */
+import type { SessionEvent } from "../types.js";
+/**
+ * Confidence scores for project attribution sources.
+ *
+ * Higher = more reliable signal. The hierarchy reflects how directly
+ * the signal indicates the user's intended project:
+ * - Explicit config (workspace roots) > explicit navigation (cd) > implicit context
+ * - Path-bearing events score higher than fallbacks without path signals
+ */
+export declare const ATTRIBUTION_CONFIDENCE: {
+    /** Explicit workspace root from IDE/editor config */
+    readonly WORKSPACE_ROOT: 0.98;
+    /** User explicitly navigated here (cd command) */
+    readonly CWD_EVENT: 0.9;
+    /** Hook payload cwd — reliable but implicit */
+    readonly INPUT_CWD: 0.88;
+    /** Session startup directory */
+    readonly SESSION_ORIGIN: 0.82;
+    /** Carry-forward from previous high-confidence event */
+    readonly LAST_SEEN: 0.76;
+    /** Inferred from file path prefix matching */
+    readonly EVENT_PATH: 0.7;
+    /** Minimum confidence to carry forward as lastKnownProjectDir */
+    readonly CARRY_FORWARD_THRESHOLD: 0.55;
+    /** Fallback: input_cwd without path signal */
+    readonly FALLBACK_INPUT_CWD: 0.45;
+    /** Fallback: last_seen without path signal */
+    readonly FALLBACK_LAST_SEEN: 0.4;
+    /** Fallback: session_origin without path signal */
+    readonly FALLBACK_SESSION_ORIGIN: 0.35;
+};
+export type AttributionSource = "event_path" | "cwd_event" | "input_cwd" | "workspace_root" | "last_seen" | "session_origin" | "env" | "test" | "unknown";
+export interface ProjectAttribution {
+    projectDir: string;
+    source: AttributionSource;
+    confidence: number;
+}
+export interface AttributionContext {
+    sessionOriginDir?: string | null;
+    inputProjectDir?: string | null;
+    workspaceRoots?: string[] | null;
+    lastKnownProjectDir?: string | null;
+}
+/**
+ * Resolve the most likely project directory for one event.
+ */
+export declare function resolveProjectAttribution(event: SessionEvent, context: AttributionContext): ProjectAttribution;
+/**
+ * Convenience helper: resolve attributions for a stream of events while
+ * carrying forward the latest confident project as context.
+ */
+export declare function resolveProjectAttributions(events: SessionEvent[], context: AttributionContext): ProjectAttribution[];
+/**
+ * 0..100 score for UI display.
+ */
+export declare function confidenceToPercent(confidence: number): number;
+/**
+ * True when attribution is strong enough for project-level spending claims.
+ */
+export declare function isHighConfidenceAttribution(confidence: number): boolean;
+/**
+ * Lightweight utility used by some hooks to normalize path separators
+ * before writing attribution metadata.
+ */
+export declare function normalizeProjectDir(projectDir: string): string;
+export declare const PROJECT_ATTRIBUTION_VERSION = 1;

package/build/session/project-attribution.js

@@ -0,0 +1,245 @@
+/**
+ * Project attribution heuristics for session events.
+ *
+ * Goal: avoid pinning all activity to the startup directory when work shifts
+ * across projects mid-session. This module resolves a best-effort project
+ * directory per event and attaches a confidence score + source signal.
+ */
+import { dirname, isAbsolute, normalize, resolve, sep } from "node:path";
+/**
+ * Confidence scores for project attribution sources.
+ *
+ * Higher = more reliable signal. The hierarchy reflects how directly
+ * the signal indicates the user's intended project:
+ * - Explicit config (workspace roots) > explicit navigation (cd) > implicit context
+ * - Path-bearing events score higher than fallbacks without path signals
+ */
+export const ATTRIBUTION_CONFIDENCE = {
+    /** Explicit workspace root from IDE/editor config */
+    WORKSPACE_ROOT: 0.98,
+    /** User explicitly navigated here (cd command) */
+    CWD_EVENT: 0.9,
+    /** Hook payload cwd — reliable but implicit */
+    INPUT_CWD: 0.88,
+    /** Session startup directory */
+    SESSION_ORIGIN: 0.82,
+    /** Carry-forward from previous high-confidence event */
+    LAST_SEEN: 0.76,
+    /** Inferred from file path prefix matching */
+    EVENT_PATH: 0.7,
+    /** Minimum confidence to carry forward as lastKnownProjectDir */
+    CARRY_FORWARD_THRESHOLD: 0.55,
+    /** Fallback: input_cwd without path signal */
+    FALLBACK_INPUT_CWD: 0.45,
+    /** Fallback: last_seen without path signal */
+    FALLBACK_LAST_SEEN: 0.4,
+    /** Fallback: session_origin without path signal */
+    FALLBACK_SESSION_ORIGIN: 0.35,
+};
+function normalizePath(path) {
+    const norm = normalize(path).replace(/\\/g, "/");
+    if (norm.length <= 1)
+        return norm;
+    return norm.replace(/\/+$/, "");
+}
+function isPrefixPath(path, prefix) {
+    if (!path || !prefix)
+        return false;
+    if (path === prefix)
+        return true;
+    return path.startsWith(`${prefix}/`);
+}
+function normalizeRoots(roots) {
+    if (!roots || roots.length === 0)
+        return [];
+    const normalized = roots
+        .filter((r) => typeof r === "string" && r.trim().length > 0)
+        .map((r) => normalizePath(r));
+    // dedupe + longest-first for stable best match
+    const unique = Array.from(new Set(normalized));
+    return unique.sort((a, b) => b.length - a.length);
+}
+function parseFileSearchPath(data) {
+    const marker = " in ";
+    const idx = data.lastIndexOf(marker);
+    if (idx < 0)
+        return null;
+    const path = data.slice(idx + marker.length).trim();
+    return path.length > 0 ? path : null;
+}
+function looksLikePath(value) {
+    if (!value)
+        return false;
+    // Fast path-like checks: separators, dot segments, drive roots.
+    return value.includes("/")
+        || value.includes("\\")
+        || value.startsWith(".")
+        || /^[A-Za-z]:[\\/]/.test(value);
+}
+function extractPathSignal(event) {
+    if (event.type === "cwd") {
+        return { rawPath: event.data, fromCwdEvent: true };
+    }
+    if (event.type === "file_search") {
+        const path = parseFileSearchPath(event.data);
+        if (path)
+            return { rawPath: path, fromCwdEvent: false };
+    }
+    const fileTypes = new Set([
+        "file_read",
+        "file_write",
+        "file_edit",
+        "file_glob",
+        "rule",
+    ]);
+    if (fileTypes.has(event.type) && looksLikePath(event.data)) {
+        return { rawPath: event.data, fromCwdEvent: false };
+    }
+    return null;
+}
+function absolutizePath(rawPath, context) {
+    if (!rawPath)
+        return null;
+    // Ignore broad glob-only patterns that aren't useful for attribution.
+    if (rawPath.includes("*") && !isAbsolute(rawPath) && !/^[A-Za-z]:[\\/]/.test(rawPath)) {
+        return null;
+    }
+    if (isAbsolute(rawPath) || /^[A-Za-z]:[\\/]/.test(rawPath)) {
+        return normalizePath(rawPath);
+    }
+    // For relative paths, anchor to the most recent known project first.
+    const anchor = context.lastKnownProjectDir
+        || context.inputProjectDir
+        || context.sessionOriginDir
+        || null;
+    if (!anchor)
+        return null;
+    return normalizePath(resolve(anchor, rawPath));
+}
+function inferProjectFromAbsolutePath(absPath, event, context) {
+    const normalizedRoots = normalizeRoots(context.workspaceRoots);
+    const normalizedOrigin = context.sessionOriginDir ? normalizePath(context.sessionOriginDir) : "";
+    const normalizedInput = context.inputProjectDir ? normalizePath(context.inputProjectDir) : "";
+    const normalizedLast = context.lastKnownProjectDir ? normalizePath(context.lastKnownProjectDir) : "";
+    // 1) Prefer explicit workspace roots (highest confidence).
+    const workspaceRoot = normalizedRoots.find((root) => isPrefixPath(absPath, root));
+    if (workspaceRoot) {
+        return { projectDir: workspaceRoot, source: "workspace_root", confidence: ATTRIBUTION_CONFIDENCE.WORKSPACE_ROOT };
+    }
+    // 2) Prefer stable known roots from session context.
+    if (normalizedInput && isPrefixPath(absPath, normalizedInput)) {
+        return { projectDir: normalizedInput, source: "input_cwd", confidence: ATTRIBUTION_CONFIDENCE.INPUT_CWD };
+    }
+    if (normalizedOrigin && isPrefixPath(absPath, normalizedOrigin)) {
+        return { projectDir: normalizedOrigin, source: "session_origin", confidence: ATTRIBUTION_CONFIDENCE.SESSION_ORIGIN };
+    }
+    if (normalizedLast && isPrefixPath(absPath, normalizedLast)) {
+        return { projectDir: normalizedLast, source: "last_seen", confidence: ATTRIBUTION_CONFIDENCE.LAST_SEEN };
+    }
+    // 3) Direct cwd events indicate explicit operator intent to shift project.
+    if (event.type === "cwd") {
+        return { projectDir: absPath, source: "cwd_event", confidence: ATTRIBUTION_CONFIDENCE.CWD_EVENT };
+    }
+    // 4) Fallback for out-of-root absolute paths.
+    // For known file events, use parent directory to avoid attributing to a file path.
+    const fileLike = new Set(["file_read", "file_write", "file_edit", "rule"]);
+    const projectDir = fileLike.has(event.type) ? normalizePath(dirname(absPath)) : absPath;
+    return { projectDir, source: "event_path", confidence: ATTRIBUTION_CONFIDENCE.EVENT_PATH };
+}
+function fallbackAttribution(context) {
+    if (context.inputProjectDir) {
+        return {
+            projectDir: normalizePath(context.inputProjectDir),
+            source: "input_cwd",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_INPUT_CWD,
+        };
+    }
+    if (context.lastKnownProjectDir) {
+        return {
+            projectDir: normalizePath(context.lastKnownProjectDir),
+            source: "last_seen",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_LAST_SEEN,
+        };
+    }
+    if (context.sessionOriginDir) {
+        return {
+            projectDir: normalizePath(context.sessionOriginDir),
+            source: "session_origin",
+            confidence: ATTRIBUTION_CONFIDENCE.FALLBACK_SESSION_ORIGIN,
+        };
+    }
+    return { projectDir: "", source: "unknown", confidence: 0 };
+}
+/**
+ * Resolve the most likely project directory for one event.
+ */
+export function resolveProjectAttribution(event, context) {
+    try {
+        const pathSignal = extractPathSignal(event);
+        if (!pathSignal)
+            return fallbackAttribution(context);
+        const absPath = absolutizePath(pathSignal.rawPath, context);
+        if (!absPath)
+            return fallbackAttribution(context);
+        return inferProjectFromAbsolutePath(absPath, event, context);
+    }
+    catch {
+        return fallbackAttribution(context);
+    }
+}
+/**
+ * Convenience helper: resolve attributions for a stream of events while
+ * carrying forward the latest confident project as context.
+ */
+export function resolveProjectAttributions(events, context) {
+    const out = [];
+    let lastKnown = context.lastKnownProjectDir ? normalizePath(context.lastKnownProjectDir) : "";
+    // v1.0.162 Bug 8 — track whether an in-batch CWD-level event has explicitly
+    // re-scoped the project. When extract.ts emits a cwd event for `cd /projB`
+    // or `git -C /projB ...`, subsequent path-less events in the same batch
+    // (e.g. the git operation event itself) currently fall back to the hook's
+    // inputProjectDir, which still points at the session startup cwd. The
+    // user's INTENTIONAL scoping should win over the hook's startup cwd —
+    // shadow inputProjectDir with the carried-forward lastKnown once a high-
+    // confidence cwd event has fired in this batch.
+    let inBatchCwdScope = false;
+    for (const ev of events) {
+        const effectiveInputCwd = inBatchCwdScope ? lastKnown : context.inputProjectDir;
+        const attribution = resolveProjectAttribution(ev, {
+            ...context,
+            inputProjectDir: effectiveInputCwd,
+            lastKnownProjectDir: lastKnown || context.lastKnownProjectDir || null,
+        });
+        out.push(attribution);
+        if (attribution.projectDir && attribution.confidence >= ATTRIBUTION_CONFIDENCE.CARRY_FORWARD_THRESHOLD) {
+            lastKnown = attribution.projectDir;
+            if (attribution.confidence >= ATTRIBUTION_CONFIDENCE.CWD_EVENT) {
+                inBatchCwdScope = true;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * 0..100 score for UI display.
+ */
+export function confidenceToPercent(confidence) {
+    const clamped = Math.max(0, Math.min(1, confidence));
+    return Math.round(clamped * 100);
+}
+/**
+ * True when attribution is strong enough for project-level spending claims.
+ */
+export function isHighConfidenceAttribution(confidence) {
+    return confidence >= 0.8;
+}
+/**
+ * Lightweight utility used by some hooks to normalize path separators
+ * before writing attribution metadata.
+ */
+export function normalizeProjectDir(projectDir) {
+    return normalizePath(projectDir);
+}
+export const PROJECT_ATTRIBUTION_VERSION = 1;
+// Keep explicit references to path separator for bundlers that tree-shake too aggressively.
+void sep;

package/build/session/purge.d.ts

@@ -0,0 +1,138 @@
+/**
+ * purgeSession — deep module that wipes ALL session-related on-disk artifacts
+ * for a single project directory.
+ *
+ * Why a deep module instead of an inline handler:
+ *   - The previous inline ctx_purge handler was 100+ lines split across three
+ *     try/catch blocks. Only ONE of those blocks knew about the case-fold
+ *     migration's dual-hash legacy filenames, so a partial upgrade could
+ *     leak orphaned events.md / .cleanup files on macOS / Windows.
+ *   - Centralizing the logic here means: one canonical sidecar list, one
+ *     uniform dual-hash sweep, one place to add new file kinds.
+ *
+ * Worktree separation guarantee (carried over from the case-fold migration):
+ *   Every path this module touches is derived deterministically from the input
+ *   `projectDir`. There is NO `readdirSync` + glob-filter loop. Different
+ *   worktrees → different physical paths → different canonical hashes →
+ *   different file names → cannot collapse worktrees on disk.
+ *
+ * SQLite sidecar handling:
+ *   Each `.db` file may be accompanied by `-wal` (write-ahead log) and `-shm`
+ *   (shared memory index) sidecars. We unlink the triple unconditionally —
+ *   missing sidecars are not an error. This matches the canonical SQLite
+ *   sidecar naming used elsewhere (see refs/platforms/zed/crates/sqlez:
+ *   `[main, "{main}-wal", "{main}-shm"]`).
+ *
+ * Cross-platform notes:
+ *   - All paths are joined via `node:path.join` so Windows backslash
+ *     separators and POSIX forward slashes both work.
+ *   - On macOS / Windows (case-insensitive FS) we sweep BOTH the canonical
+ *     (lowercased) and legacy (raw-cased) project-dir hash variants for the
+ *     session-related kinds. On Linux the two hashes coincide, so the dual
+ *     sweep collapses into a single unique-path pass.
+ */
+export interface PurgeOpts {
+    /**
+     * Absolute path to the project root. Drives every other path the module
+     * touches via the project-dir hash. MUST be the same string the rest of
+     * the system uses (e.g. `getProjectDir()`); otherwise the wrong DB is
+     * targeted. Worktree separation is preserved — only files matching
+     * THIS projectDir's hash are unlinked.
+     */
+    projectDir: string;
+    /**
+     * Adapter-specific session directory (e.g. `~/.claude/context-mode/sessions`).
+     * Holds: `<hash><suffix>.db`, `<hash><suffix>-events.md`,
+     * `<hash><suffix>.cleanup`.
+     */
+    sessionsDir: string;
+    /**
+     * Absolute path to the per-project FTS5 knowledge-base DB
+     * (e.g. `~/.claude/context-mode/content/<hash>.db`). When omitted no
+     * FTS5 wipe runs. Caller is responsible for closing any open handle
+     * BEFORE invoking purgeSession (Windows file locks).
+     *
+     * Use `contentDir` instead for new code — it dual-sweeps the canonical
+     * AND legacy raw-casing variants, mirroring the session events pattern.
+     * `storePath` remains for callers that have already pre-resolved a single
+     * absolute path and only want to wipe that exact file.
+     */
+    storePath?: string;
+    /**
+     * Per-platform FTS5 content directory (e.g.
+     * `~/.claude/context-mode/content`). When provided, purgeSession sweeps
+     * BOTH the canonical and legacy raw-casing hash variants of the FTS5
+     * store inside this directory plus their `-wal` / `-shm` sidecars. This
+     * is the recommended input — covers a partial upgrade where the user
+     * had been writing to a legacy raw-casing FTS5 file before the case-fold
+     * migration landed.
+     *
+     * Mutually-additive with `storePath`: if both are passed, both are swept
+     * (de-duped on path). Closing FTS5 handles before invoking is still the
+     * caller's responsibility.
+     */
+    contentDir?: string;
+    /**
+     * Legacy shared content directory at `~/.context-mode/content`. When
+     * omitted, the legacy content sweep is skipped.
+     */
+    legacyContentDir?: string;
+    /**
+     * Hash used to locate the legacy shared content DB. Required when
+     * `legacyContentDir` is provided. Computed by the caller because the
+     * legacy code-path uses a different hash function than the canonical
+     * session DB hash.
+     */
+    contentHash?: string;
+    /**
+     * Issue #520 — scoped purge.
+     *
+     *  - `"project"` (default when omitted for back-compat callers that
+     *    only pass `confirm:true` at the MCP layer): wipe ALL session
+     *    artifacts for `projectDir`. This is the legacy destructive
+     *    behavior preserved verbatim.
+     *  - `"session"`: wipe ONLY the rows for `sessionId` inside the
+     *    project's SessionDB plus FTS5 chunks tagged with that
+     *    `session_id`. Project-wide files (events.md, content store
+     *    file, stats file) are left intact. Requires `sessionId`.
+     *
+     * When `scope` is omitted but `sessionId` is set, behavior implies
+     * `scope:"session"` (a sessionId-only call cannot mean "wipe the
+     * whole project"). When neither is set, behavior implies
+     * `scope:"project"` for back-compat with the original handler.
+     */
+    scope?: "session" | "project";
+    /**
+     * Session identifier whose rows should be wiped from the project's
+     * SessionDB and tagged FTS5 chunks. Only consulted when `scope ===
+     * "session"`. The `session_events`, `session_meta`, and
+     * `session_resume` rows for this id are removed; rows for other
+     * sessions in the same DB are preserved. Match SessionDB.deleteSession
+     * semantics (see src/session/db.ts).
+     */
+    sessionId?: string;
+}
+export interface PurgeResult {
+    /**
+     * Human-readable labels rendered to the user by the ctx_purge handler.
+     * MUST stay backward-compatible with the existing UI strings:
+     *   "knowledge base (FTS5)", "session events DB", "session events markdown".
+     * Each label appears at most once, and only when at least one matching
+     * file was actually unlinked.
+     */
+    deleted: string[];
+    /**
+     * Every full path that was successfully `unlink`ed. Surfaced for tests
+     * and for diagnostic logging — NEVER shown to end users (the labels
+     * above carry the human story).
+     */
+    wipedPaths: string[];
+}
+/**
+ * Wipe every session-related on-disk artifact for `projectDir`.
+ *
+ * This function never throws on missing files (a fresh install is a no-op).
+ * It throws only when given an invalid argument (e.g. `legacyContentDir`
+ * without `contentHash`), which is a programmer bug not a runtime concern.
+ */
+export declare function purgeSession(opts: PurgeOpts): PurgeResult;