freeharness 0.4.1

package/dist/adapters/memory/doctor.d.ts

@@ -0,0 +1,480 @@
+import { spawnSync } from "node:child_process";
+export interface CacheVersion {
+    version: string;
+    dir: string;
+    ours: boolean;
+    skills: string[];
+    /** Found under the upstream (thedotmack/claude-mem) cache root: a previous FreeHarness
+     * build (pre-rename) or a genuine upstream install, never our current native path. */
+    legacy: boolean;
+}
+export interface WorkerProbe {
+    port: number;
+    reachable: boolean;
+    version?: string;
+    viewer?: boolean;
+    ours?: boolean;
+}
+/** Marker in the FreeHarness viewer page served on GET / (plugin/ui/viewer.html). */
+export declare const VIEWER_MARKER = "FreeHarness memory";
+/** Mirror of engine shared/observer-health.ts: warn only after this many consecutive failures. */
+export declare const OBSERVER_UNHEALTHY_FAILURE_THRESHOLD = 3;
+/** Mirror of engine shared/quota-cooldown.ts: how long requests are withheld after a quota refusal. */
+export declare const QUOTA_EXHAUSTED_RECHECK_COOLDOWN_MS: number;
+/** Ledger file names (engine shared/observer-health.ts, shared/quota-cooldown.ts), under the data dir. */
+export declare const OBSERVER_HEALTH_FILENAME = "observer-health.json";
+export declare const QUOTA_COOLDOWN_FILENAME = "quota-cooldown.json";
+/** The observer-health ledger as the engine writes it (all fields optional for older builds). */
+export interface ObserverHealth {
+    consecutiveFailures: number;
+    failingSinceAt: number | null;
+    lastErrorAt: number | null;
+    lastErrorMessage: string | null;
+    lastErrorProvider: string | null;
+    lastSuccessAt: number | null;
+    lastErrorKind?: string | null;
+    lastErrorCode?: string | null;
+    lastErrorAction?: string | null;
+}
+/** One armed quota breaker (the persisted half; probe claims are never on disk). */
+export interface QuotaCooldown {
+    provider: string;
+    message: string;
+    window?: string;
+    armedAtMs: number;
+    /** Milliseconds left in the cooldown (0 when it elapsed and the next observation re-probes). */
+    remainingMs: number;
+}
+/** Observer state derived from the ledgers. */
+export interface ObserverStatus {
+    health: ObserverHealth | null;
+    unhealthy: boolean;
+    cooldowns: QuotaCooldown[];
+}
+export interface MemoryDiagnosis {
+    configDir: string;
+    dataDir: string;
+    dbPath: string;
+    dbBytes: number;
+    chromaPresent: boolean;
+    cache: CacheVersion[];
+    activeInstallPath?: string;
+    activeVersion?: string;
+    activeIsOurs?: boolean;
+    worker: WorkerProbe;
+    observer: ObserverStatus;
+    verdict: "ours" | "upstream" | "mixed" | "none";
+    lines: string[];
+}
+/**
+ * Read the observer ledgers of the data dir.
+ *
+ * Args:
+ *   data: The claude-mem data dir.
+ *   now: Clock (ms), injectable for tests.
+ *
+ * Returns:
+ *   Health (null when no ledger), the unhealthy verdict (engine rule: >= threshold failures
+ *   and the last error newer than the last success) and every armed cooldown with its remaining time.
+ */
+export declare function readObserverStatus(data: string, now?: number): ObserverStatus;
+/**
+ * How long an unresolved observer verdict stays worth a fresh warning. Independent of the
+ * engine's own `isObserverUnhealthy` (that gate does not carry an age bound yet): this reads
+ * the same ledger file directly so `memory status` can down-rank a failure with no session in
+ * between from a live WARN to a dated INFO line.
+ */
+export declare const OBSERVER_STALE_AFTER_MS: number;
+/**
+ * True when the ledger's last failure is old enough that a fresh WARN would be noise: the
+ * same unhealthy condition (>= threshold consecutive failures, the last error newer than the
+ * last success) plus that last error being older than `OBSERVER_STALE_AFTER_MS`.
+ *
+ * Args:
+ *   ledger: The observer-health ledger (null when no ledger file exists yet).
+ *   nowMs: Clock (ms), injectable for tests.
+ *
+ * Returns:
+ *   Whether the verdict is stale.
+ */
+export declare function isObserverVerdictStale(ledger: ObserverHealth | null, nowMs?: number): boolean;
+/**
+ * Printable lines for the observer state (OK/WARN/INFO prefixed).
+ *
+ * Args:
+ *   s: The observer status.
+ *   now: Clock (ms).
+ *
+ * Returns:
+ *   Lines: one for the health ledger, one per cooldown (or "no quota cooldown").
+ */
+export declare function observerLines(s: ObserverStatus, now?: number): string[];
+/** Highest schema_versions row our vendored SessionStore applies (13.24.0 port; the upstream v50 observed_model/observed_billing migration is telemetry-only and not ported). */
+export declare const OUR_SCHEMA_VERSION = 49;
+/** One (window, model) group from the `observations` table. */
+export interface SpendRow {
+    window: "today" | "seven_day";
+    model: string;
+    observations: number;
+    tokens: number;
+}
+type SpawnSyncFn = typeof spawnSync;
+/**
+ * Why `observerSpend` could not read spend rows: the sqlite3 binary itself is missing
+ * (`missingBinary: true`, `spendLines` prints the fixed "unavailable without sqlite3" line),
+ * or a present binary reported a query/database error (`missingBinary: false`, `spendLines`
+ * prints `reason` — the first line of sqlite3's own stderr — so a real query failure is never
+ * mistaken for "install sqlite3").
+ */
+export interface SpendUnavailable {
+    reason: string;
+    missingBinary: boolean;
+}
+/**
+ * Reads observer spend (observation count and summed `discovery_tokens`) grouped by day
+ * window and `generated_by_model`, through `sqlite3 -readonly` (same invocation shape as
+ * `dbSchemaVersion`). The seven-day window includes today, matching the running total an
+ * owner reads off `memory status` (not "the other six days").
+ *
+ * Args:
+ *   dbPath: Path of claude-mem.db.
+ *   spawn: Injectable spawnSync, so the missing-binary path is deterministic in tests
+ *     regardless of whether sqlite3 happens to be on the test machine's PATH.
+ *
+ * Returns:
+ *   One row per (window, model) with a row, or the reason spend could not be read.
+ */
+export declare function observerSpend(dbPath: string, spawn?: SpawnSyncFn): SpendRow[] | SpendUnavailable;
+/**
+ * Model ids that name metered Claude spend: the `claude-*` families, a bare tier alias
+ * (`haiku`, `sonnet`, `opus`, alone or with a `-` suffix) and the `$TIER:` placeholder the
+ * engine writes before a tier is resolved. `generated_by_model` stores the id as configured,
+ * and the engine's own default simple-tier model is the bare alias `haiku`, so a plain
+ * `claude` prefix test would file the whole simple tier as free local spend.
+ *
+ * The same rule, with the same expression, lives in the cost-tracker hook
+ * (`canonical/hooks/freeharness-cost-tracker.mjs`): the two split the same rows and a
+ * divergence would make `memory status` and `cost report` disagree on one machine.
+ *
+ * Args:
+ *   model: A `generated_by_model` value.
+ *
+ * Returns:
+ *   True for a Claude id, false for a local one.
+ */
+export declare function isClaudeModelId(model: string): boolean;
+/**
+ * Renders `observerSpend`'s result as printable INFO lines: for each window (today, then the
+ * seven-day window) that has at least one row, the Claude model rows, then the local model
+ * rows, then a `subscription observer tokens` subtotal summing the Claude rows of that window
+ * only — the subscription is the metered resource, so a local row never inflates it and a
+ * local-only window still gets a printed (zero) subtotal, since the window itself had
+ * activity. A window with no rows at all (a fresh install, or a provider not yet run today)
+ * prints nothing, matching the pre-split behavior for an empty result. A single line instead
+ * when spend could not be read at all (the fixed sqlite3-missing wording, or the
+ * query/database error's own reason).
+ *
+ * Args:
+ *   spend: `observerSpend`'s return value.
+ *
+ * Returns:
+ *   Lines in today-rows/today-subtotal/seven-day-rows/seven-day-subtotal order; `[]` when
+ *   `spend` is an empty array (no observations in either window).
+ */
+export declare function spendLines(spend: SpendRow[] | SpendUnavailable): string[];
+/** The day's local-provider activity, read from `<data-dir>/local-provider.jsonl`. */
+export interface LocalProviderLogSummary {
+    /** Local-attempted batches today (`attempted === "local"`), served locally or falling back. */
+    batches: number;
+    /** Of `batches`, the ones the local server actually answered (`answered === "local"`). */
+    local: number;
+    /** `batches - local`, broken down by failure kind (`local_timeout`, `local_unparseable`, ...). */
+    fallbacks: Record<string, number>;
+    /** Lines that were not valid JSON, or lacked a parseable `ts` or a recognized `attempted`. */
+    skippedLines: number;
+    /** True when the file exceeded the read cap and only its tail was scanned (see `readLocalProviderLog`'s `maxBytes`). */
+    truncated: boolean;
+}
+/** A present but unreadable batch log (permissions, I/O), distinct from one that does not exist. */
+export interface LocalProviderLogUnavailable {
+    reason: string;
+}
+/**
+ * Reads today's local-provider activity from the append-only batch log, at most its last
+ * `maxBytes` (default 4 MB) so an unrotated, ever-growing log never makes `memory status`
+ * read the whole file.
+ *
+ * Args:
+ *   logPath: `<data-dir>/local-provider.jsonl`.
+ *   dayStartMs: Start of the UTC day being summarized. The engine writes `ts` as an ISO
+ *     instant and the only caller passes `startOfUtcDayMs`, so the window matches the UTC
+ *     boundary `observerSpend`'s `date('now')` already uses and the two lines describe one day.
+ *   nowMs: End of the window (the day so far).
+ *   maxBytes: Read cap, injectable so a test can exercise truncation without writing a
+ *     multi-megabyte fixture.
+ *
+ * Returns:
+ *   The day's batch/fallback counts and whether the read was truncated; null when the log file
+ *   does not exist yet (a fresh `CLAUDE_MEM_PROVIDER=claude` machine has never written one);
+ *   the reason when the file is there but could not be read, which is a different state from
+ *   an absent log and gets its own printed line.
+ */
+export declare function readLocalProviderLog(logPath: string, dayStartMs: number, nowMs: number, maxBytes?: number): LocalProviderLogSummary | LocalProviderLogUnavailable | null;
+/** One day's locally answered observation count and how many share a title within a session. */
+export interface DuplicateCounts {
+    observations: number;
+    duplicates: number;
+}
+/** The near-duplicate figures the eval plan compares: the day so far against the one before it. */
+export interface DuplicateStats {
+    today: DuplicateCounts;
+    yesterday: DuplicateCounts;
+}
+/**
+ * Reads the near-duplicate rate of the locally answered observations, for the UTC day so far
+ * and for the one before it: rows are grouped by `(generated_by_model, memory_session_id,
+ * title)` and every row past the first of a group counts as a near-duplicate. Only rows whose
+ * `generated_by_model` fails `isClaudeModelId` are counted — a stateless local batch has no
+ * prior context to avoid repeating itself, which is the cost the figure exists to measure, and
+ * a Claude row would dilute it. The previous day is read in the same pass so the rate has a
+ * local-to-local baseline: the day so far compared against the day before it, both counting
+ * only locally answered rows.
+ *
+ * Same unavailability shape as `observerSpend`.
+ *
+ * Args:
+ *   dbPath: Path of claude-mem.db.
+ *   spawn: Injectable spawnSync (see `observerSpend`).
+ *
+ * Returns:
+ *   Both days' observation and duplicate counts, or the reason the rate could not be read.
+ */
+export declare function observerDuplicateRate(dbPath: string, spawn?: SpawnSyncFn): DuplicateStats | SpendUnavailable;
+/**
+ * Renders the local-provider log summary and near-duplicate rate as printable INFO lines: the
+ * batch/fallback line, then the near-duplicate-rate line (omitted when the rate could not be
+ * read). Nothing at all when `summary` is null (no `local-provider.jsonl` yet); a single WARN
+ * naming the reason when the log is present but unreadable, so a permission or I/O failure
+ * never reads like a machine that has not run the local provider.
+ *
+ * Args:
+ *   summary: `readLocalProviderLog`'s return value.
+ *   duplicates: `observerDuplicateRate`'s return value.
+ *
+ * Returns:
+ *   Zero, one or two lines.
+ */
+export declare function localProviderLines(summary: LocalProviderLogSummary | LocalProviderLogUnavailable | null, duplicates: DuplicateStats | SpendUnavailable): string[];
+/** A `haiku` alias (bare or `claude-haiku-*`), the FreeHarness-recommended observer model kind. */
+export declare function isHaikuAlias(model: string): boolean;
+/** Effective observer model per tier, after merging engine defaults with the owner's file. */
+export interface EffectiveObserverModels {
+    base: string;
+    simple: string;
+    summary: string;
+}
+/**
+ * Effective observer model per tier: the engine defaults with the owner's settings.json layered
+ * on top, and the summary tier's empty-default resolved to the base model (the engine's own
+ * "empty = use default model for summaries" rule) so the printed value is what actually runs.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json (absent or malformed = engine defaults).
+ *
+ * Returns:
+ *   Base, simple and summary model ids.
+ */
+export declare function effectiveObserverModels(settingsPath: string): EffectiveObserverModels;
+/** Which provider the observer actually runs on, and its model when that provider is local. */
+export interface ObserverProvider {
+    provider: "claude" | "local";
+    /** `CLAUDE_MEM_LOCAL_MODEL` (or the engine's `local-model` default) when `provider` is
+     * `local`; null when `provider` is `claude` (no local model is in play). */
+    model: string | null;
+}
+/**
+ * Effective observer provider: `CLAUDE_MEM_PROVIDER` from settings.json (default `claude`; any
+ * value other than the literal `local` is treated as `claude`, mirroring the engine's own
+ * `SettingsDefaultsManager` fallback), and when local, the configured `CLAUDE_MEM_LOCAL_MODEL`
+ * or the engine's `local-model` default.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json (absent or malformed = claude).
+ *
+ * Returns:
+ *   The effective provider and, for local, its model id.
+ */
+export declare function effectiveObserverProvider(settingsPath: string): ObserverProvider;
+/**
+ * The FreeHarness-recommended observer settings: a haiku base and simple tier (the daily-spend
+ * gate), a sonnet summary tier (session summaries read by every future session, worth the
+ * larger model), the upstream skip list extended with the tools whose decisions matter for
+ * recall (Read, Glob, Grep and the multi-agent tools), and a concurrency cap of 2. Shared by
+ * `memory status`'s WARN check and the `memory settings` command.
+ */
+export declare const RECOMMENDED_OBSERVER_SETTINGS: Record<string, string>;
+/**
+ * `memory settings --no-local`: the two keys that return the observer to the Claude provider —
+ * `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS` restored to the recommended default, so the
+ * skip list follows the provider back.
+ */
+export declare const NO_LOCAL_OBSERVER_SETTINGS: Record<string, string>;
+/** `memory settings --local <base-url> <model>` / `--no-local` request, on top of the plain command. */
+export interface ObserverSettingsOptions {
+    local?: {
+        baseUrl: string;
+        model: string;
+    };
+    noLocal?: boolean;
+}
+/** One recommended key's current-vs-recommended state, for the `memory settings` preview. */
+export interface ObserverSettingsRow {
+    key: string;
+    current: string | undefined;
+    recommended: string;
+    changed: boolean;
+}
+export interface ObserverSettingsPreview {
+    rows: ObserverSettingsRow[];
+    /** Set when settingsPath exists but is not valid JSON; rows then compare against "absent". */
+    parseError?: string;
+}
+/**
+ * Previews `memory settings`: the selected key set against the current file, same or
+ * would-change, writing nothing. Plain (no options): the five recommended keys. `--local`:
+ * `CLAUDE_MEM_PROVIDER` plus the four `CLAUDE_MEM_LOCAL_*` keys plus the narrowed
+ * `CLAUDE_MEM_SKIP_TOOLS`. `--no-local`: `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS`
+ * restored to the recommended default.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   opts: The command's `--local`/`--no-local` request, if any.
+ *
+ * Returns:
+ *   One row per key in the selected set, and the parse error when the file is present but
+ *   invalid.
+ *
+ * Raises:
+ *   Error: `opts` fails validation (see `resolveObserverKeySet`); nothing is read or written.
+ */
+export declare function previewObserverSettings(settingsPath: string, opts?: ObserverSettingsOptions): ObserverSettingsPreview;
+export interface ApplyObserverSettingsResult {
+    /** True when settings.json did not exist and was created with exactly the five keys. */
+    created: boolean;
+    /** The timestamped backup path; absent when the file was created rather than updated. */
+    backupPath?: string;
+}
+/**
+ * Applies `memory settings`: adds or updates the selected key set (see `previewObserverSettings`
+ * for which set), preserving every other key, after backing up an existing file first. Refuses
+ * (throws) without writing anything when `opts` fails validation or the existing file is not
+ * valid JSON.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   opts: The command's `--local`/`--no-local` request, if any.
+ *
+ * Returns:
+ *   Whether the file was created, and the backup path when one was made.
+ *
+ * Raises:
+ *   Error: `opts` fails validation, or the existing file is not valid JSON (its message names
+ *   the parse error).
+ */
+export declare function applyObserverSettings(settingsPath: string, opts?: ObserverSettingsOptions): ApplyObserverSettingsResult;
+/** `probeMemoryProvider`'s outcome: reachable and serving the configured model, or not. */
+export interface MemoryProviderProbe {
+    ok: boolean;
+    /**
+     * One-line reason when `ok` is false: a connection error, `health <status>`,
+     * `model <id> not listed`, or `timeout after <n> ms` when the shared deadline elapses.
+     */
+    reason?: string;
+}
+/**
+ * Probes a local memory-provider server: `<root>/health` (200 expected), then `<base>/models`
+ * (the configured model id expected in `data[].id`), both requests bound by one
+ * `AbortController` armed once for `timeoutMs` — so a slow-but-live server cannot push the
+ * total probe time past the configured deadline by stacking a full timeout on each request.
+ * Down is a one-line reason, never a throw.
+ *
+ * Args:
+ *   baseUrl: `CLAUDE_MEM_LOCAL_BASE_URL`.
+ *   model: `CLAUDE_MEM_LOCAL_MODEL`.
+ *   timeoutMs: The whole probe's deadline (both requests together).
+ *
+ * Returns:
+ *   ok, or ok:false with a one-line reason.
+ */
+export declare function probeMemoryProvider(baseUrl: string, model: string, timeoutMs?: number): Promise<MemoryProviderProbe>;
+/**
+ * The `memory provider` doctor line: only when the data dir's settings.json sets
+ * `CLAUDE_MEM_PROVIDER=local`, a probe of the configured base URL and model, OK or WARN with
+ * the reason; absent or `claude` prints nothing.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   probe: Injectable probe function.
+ *
+ * Returns:
+ *   Zero or one printable line.
+ */
+export declare function memoryProviderLines(settingsPath: string, probe?: (baseUrl: string, model: string, timeoutMs?: number) => Promise<MemoryProviderProbe>): Promise<string[]>;
+/** Resolve $CLAUDE_CONFIG_DIR or ~/.claude. */
+export declare function configDir(): string;
+/** Mirror engine shared/paths.ts resolveDataDir (env, then settings.json, then default). */
+export declare function dataDir(): string;
+/**
+ * Diagnose which claude-mem is active.
+ *
+ * Returns:
+ *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN prefixed).
+ */
+export declare function diagnoseMemory(): Promise<MemoryDiagnosis>;
+/**
+ * Copy the claude-mem data dir to a timestamped sibling (never moves the original).
+ *
+ * Returns:
+ *   The backup directory path.
+ */
+export declare function backupMemoryData(): string;
+export interface RestartResult {
+    /** How the restart was performed. */
+    method: "worker-service restart" | "shutdown-only" | "nothing";
+    detail: string;
+}
+/**
+ * Restart the claude-mem worker of the registered FreeHarness build.
+ *
+ * Prefers the plugin's own launcher (`node <install>/scripts/bun-runner.js
+ * <install>/scripts/worker-service.cjs restart`, detached) so the new worker is the
+ * registered version; without a registered FreeHarness install it only asks a running
+ * worker to shut down (the next SessionStart hook respawns it). The observer ledgers are
+ * left alone: a restart does not clear an armed quota cooldown (that is by design in the
+ * engine; the breaker is persisted so restarts cannot reopen a request storm).
+ *
+ * Args:
+ *   dryRun: Report only.
+ *   diagnosis: A diagnosis already computed by the caller (a fresh one otherwise).
+ *
+ * Returns:
+ *   What was (or would be) done.
+ */
+export declare function restartWorker(dryRun: boolean, diagnosis?: MemoryDiagnosis): Promise<RestartResult>;
+export interface ActivateResult {
+    stoppedWorker: boolean;
+    disabled: string[];
+    registered: boolean;
+}
+/**
+ * Make the FreeHarness build the only active claude-mem: stop a running worker, move
+ * foreign cache versions aside (never deleted), point installed_plugins at ours.
+ *
+ * Args:
+ *   dryRun: Report only.
+ *
+ * Returns:
+ *   What was (or would be) done.
+ */
+export declare function activateOurs(dryRun: boolean): Promise<ActivateResult>;
+export {};