onadit 0.0.1 → 1.0.0

package/dist/src/observability/onboarding-metric.js

@@ -0,0 +1,352 @@
+// rename:keep-tool-labels The tool names in this file are usage-log labels: stored data, kept as first written.
+/**
+ * `time_to_first_useful_recall` v1 instrumentation.
+ *
+ * Persists exactly four fields under `<data_dir>/metrics/onboarding.json`:
+ *   - install_id                  (random UUID, minted on first read)
+ *   - useful_state_reached_at     (ISO timestamp or null)
+ *   - first_useful_recall_at      (ISO timestamp or null)
+ *   - first_useful_recall_tool    (one of the three retrieval tools)
+ *
+ * Privacy contract: query text, response text, hit IDs, source paths and
+ * client identifiers MUST NEVER land in this file. Writes go through a
+ * fixed-key sanitizer so an upstream caller that hands in extra fields
+ * cannot leak them by accident. Tests assert the persisted shape.
+ *
+ * Write-once: once a field is set, it is never overwritten. End
+ * stamping (`first_useful_recall_*`) requires `useful_state_reached_at`
+ * to have already been observed by a real readiness check — the metric's
+ * definition is "first MCP retrieval *after start*", so a recorded end
+ * without a prior recorded start would lie about the latency. If start
+ * is null when end fires, the end is dropped. To avoid losing the first
+ * real recall, callers should evaluate readiness via
+ * `stampOnboardingStartIfReady` (the shared helper used by
+ * `/status/friend`) before invoking the end-event recorder.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+/** MCP retrieval tools that can satisfy the end-event condition. */
+export const RETRIEVAL_TOOLS = new Set([
+    "rift_search",
+    "rift_conversations_search",
+    "rift_context_pack",
+]);
+export function onboardingMetricPath(dataDir) {
+    return path.join(dataDir, "metrics", "onboarding.json");
+}
+function isRetrievalTool(v) {
+    return typeof v === "string" && RETRIEVAL_TOOLS.has(v);
+}
+/**
+ * Read-or-bootstrap. A missing/corrupt file is replaced with a fresh
+ * record whose `install_id` is a new UUID. Unknown fields in an existing
+ * file are dropped on the next write (sanitizer drops everything outside
+ * the fixed key set).
+ */
+export function readOnboardingMetric(dataDir) {
+    const file = onboardingMetricPath(dataDir);
+    let parsed;
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        const obj = JSON.parse(raw);
+        if (obj && typeof obj === "object") {
+            parsed = obj;
+        }
+    }
+    catch {
+        // missing or unreadable — fall through to bootstrap
+    }
+    if (!parsed ||
+        typeof parsed["install_id"] !== "string" ||
+        parsed["install_id"].length === 0) {
+        const fresh = {
+            install_id: randomUUID(),
+            useful_state_reached_at: null,
+            first_useful_recall_at: null,
+            first_useful_recall_tool: null,
+        };
+        writeOnboardingMetric(dataDir, fresh);
+        return fresh;
+    }
+    return {
+        install_id: parsed["install_id"],
+        useful_state_reached_at: typeof parsed["useful_state_reached_at"] === "string"
+            ? parsed["useful_state_reached_at"]
+            : null,
+        first_useful_recall_at: typeof parsed["first_useful_recall_at"] === "string"
+            ? parsed["first_useful_recall_at"]
+            : null,
+        first_useful_recall_tool: isRetrievalTool(parsed["first_useful_recall_tool"])
+            ? parsed["first_useful_recall_tool"]
+            : null,
+    };
+}
+/**
+ * Persist the metric. The sanitizer copies exactly four named fields —
+ * anything else a caller might have spliced onto the object is discarded
+ * before it touches disk. This is the privacy guard that the schema
+ * test pins.
+ */
+function writeOnboardingMetric(dataDir, metric) {
+    const file = onboardingMetricPath(dataDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const sanitized = {
+        install_id: metric.install_id,
+        useful_state_reached_at: metric.useful_state_reached_at,
+        first_useful_recall_at: metric.first_useful_recall_at,
+        first_useful_recall_tool: metric.first_useful_recall_tool,
+    };
+    fs.writeFileSync(file, JSON.stringify(sanitized, null, 2));
+}
+/**
+ * Useful state = the product delivered first value: the daemon is healthy,
+ * there is indexed content to retrieve, AND at least one working retrieval
+ * surface — semantic (valid Voyage embeddings) OR keyword (intentional no-key
+ * lexical mode). Gating on Voyage alone would make the shipped no-key path
+ * never count as activated, skewing beta telemetry.
+ */
+export function isUsefulStateReached(signals) {
+    return (signals.daemonHealthy &&
+        (signals.voyageKeyValid || signals.lexicalModeAvailable) &&
+        signals.indexedCount >= 1);
+}
+/**
+ * Stamp `useful_state_reached_at` if (a) readiness is observed and
+ * (b) the field is still null. No-op otherwise. Returns the (possibly
+ * updated) record.
+ */
+export function stampUsefulStateIfReady(dataDir, opts) {
+    const current = readOnboardingMetric(dataDir);
+    if (current.useful_state_reached_at !== null)
+        return current;
+    if (!opts.ready)
+        return current;
+    const next = {
+        ...current,
+        useful_state_reached_at: opts.now,
+    };
+    writeOnboardingMetric(dataDir, next);
+    return next;
+}
+/**
+ * Stamp `first_useful_recall_*` if eligible. Eligibility:
+ *   1. tool is one of `RETRIEVAL_TOOLS`
+ *   2. response was not degraded
+ *   3. response had at least one hit
+ *   4. `first_useful_recall_at` is still null (write-once)
+ *   5. `useful_state_reached_at` was already observed (non-null)
+ *
+ * The metric measures "first MCP retrieval *after* start." If start
+ * has not been observed yet, end stamping is skipped — recording an
+ * end alongside a synthesised start would report a near-zero duration
+ * that doesn't reflect a real "from readiness to first useful recall"
+ * measurement. Callers that want to avoid dropping the first real
+ * recall should evaluate readiness via the shared helper
+ * (`stampOnboardingStartIfReady` on the daemon, exposed through
+ * `/status/friend`) before invoking this function.
+ */
+export function stampFirstUsefulRecallIfEligible(dataDir, opts) {
+    const current = readOnboardingMetric(dataDir);
+    if (!RETRIEVAL_TOOLS.has(opts.tool))
+        return current;
+    if (opts.isDegraded)
+        return current;
+    if (opts.hitCount < 1)
+        return current;
+    if (current.first_useful_recall_at !== null)
+        return current;
+    if (current.useful_state_reached_at === null)
+        return current;
+    const next = {
+        ...current,
+        first_useful_recall_at: opts.now,
+        first_useful_recall_tool: opts.tool,
+    };
+    writeOnboardingMetric(dataDir, next);
+    return next;
+}
+/**
+ * Project the persisted metric to the three rendering states the
+ * status surface needs. Hidden = no start yet (don't show the line at
+ * all). Pending = start, no end. Completed = both, with a derived
+ * `duration_seconds`.
+ */
+export function computeOnboardingState(metric) {
+    if (!metric.useful_state_reached_at)
+        return { state: "hidden" };
+    if (!metric.first_useful_recall_at ||
+        !metric.first_useful_recall_tool) {
+        return {
+            state: "pending",
+            useful_state_reached_at: metric.useful_state_reached_at,
+        };
+    }
+    const startMs = Date.parse(metric.useful_state_reached_at);
+    const endMs = Date.parse(metric.first_useful_recall_at);
+    const duration_seconds = Number.isNaN(startMs) || Number.isNaN(endMs)
+        ? 0
+        : Math.max(0, Math.round((endMs - startMs) / 1000));
+    return {
+        state: "completed",
+        useful_state_reached_at: metric.useful_state_reached_at,
+        first_useful_recall_at: metric.first_useful_recall_at,
+        first_useful_recall_tool: metric.first_useful_recall_tool,
+        duration_seconds,
+    };
+}
+/**
+ * MCP-side bridge between a finished retrieval-tool call and the
+ * end-event stamper. Mirrors the extractor logic in
+ * `observability/tool-usage.ts` for `result_count` and `degraded`, but
+ * stays self-contained so this module has no dependency on the logger.
+ *
+ * Readiness handshake: end stamping requires `useful_state_reached_at`
+ * to already be set (the metric is "first MCP retrieval *after*
+ * start", per the v1 spec). When the recorder finds start still null
+ * but the response is otherwise eligible, it invokes the optional
+ * `pingReadiness` callback (the MCP wrapper passes one that GETs
+ * `/status/friend` on the daemon, which evaluates readiness signals
+ * and stamps start lazily). After the ping returns, the metric is
+ * re-read and end is stamped only if start has now landed. When no
+ * callback is provided, or readiness still cannot be observed, the
+ * end event is silently dropped — that matches the contract that
+ * end-without-start would otherwise misreport as a near-zero duration.
+ *
+ * Never throws: persistence errors and ping errors are swallowed so
+ * onboarding telemetry can never break a tool call. CLI callers do not
+ * invoke this helper (it lives behind the MCP server's tool
+ * registration), so the "MCP-only end" constraint is enforced by
+ * construction.
+ */
+export async function recordMcpRetrievalForOnboarding(dataDir, tool, mcpResult, opts = {}) {
+    if (!RETRIEVAL_TOOLS.has(tool))
+        return;
+    if (mcpResult.isError)
+        return;
+    const initialNow = opts.now ?? new Date().toISOString();
+    try {
+        const signal = extractRetrievalSignal(tool, mcpResult);
+        if (signal.count === undefined)
+            return;
+        if (signal.degraded === true)
+            return;
+        if (signal.count < 1)
+            return;
+        // Cheap pre-check: if end is already stamped, skip everything
+        // (write-once means stampFirstUsefulRecallIfEligible would no-op
+        // anyway, but bailing here avoids a needless readiness ping).
+        let current = readOnboardingMetric(dataDir);
+        if (current.first_useful_recall_at !== null)
+            return;
+        // Readiness handshake: only when start is missing AND a ping is
+        // available. The end-condition (non-degraded, ≥ 1 hit) strictly
+        // implies the start-conditions hold in the wider system, but we
+        // still want the daemon to do the formal readiness observation
+        // (env present + last_embed_at + capability counts) before
+        // recording an end timestamp — otherwise the metric would lie
+        // about its own definition.
+        if (current.useful_state_reached_at === null && opts.pingReadiness) {
+            try {
+                await opts.pingReadiness();
+            }
+            catch {
+                // Ping failures degrade to "skip end this time" rather than
+                // breaking the tool call. The next eligible retrieval will
+                // re-attempt the ping.
+            }
+            // Re-read so the ordering clamp below sees the freshly stamped
+            // start (if any) before we record end.
+            current = readOnboardingMetric(dataDir);
+        }
+        // Ordering clamp: the metric measures "first MCP retrieval *after*
+        // start", so `first_useful_recall_at` must never be earlier than
+        // `useful_state_reached_at`. When the readiness ping above lazily
+        // stamps start during this same call, the retrieval `now` captured
+        // before the ping can be older than the freshly written start —
+        // recording the older `now` as end would produce an inverted pair
+        // that the duration projection then silently clamps to 0s, hiding
+        // the bug. Take the max so the persisted end is always >= start.
+        let now = initialNow;
+        if (current.useful_state_reached_at !== null &&
+            now < current.useful_state_reached_at) {
+            now = current.useful_state_reached_at;
+        }
+        stampFirstUsefulRecallIfEligible(dataDir, {
+            tool,
+            isDegraded: false,
+            hitCount: signal.count,
+            now,
+        });
+    }
+    catch {
+        // Telemetry must never break tool execution.
+    }
+}
+/**
+ * Per-tool `(count, degraded)` extraction. Duplicated from
+ * `tool-usage.ts` rather than imported to avoid circular dependency
+ * risk and to keep this module's contract narrow.
+ */
+function extractRetrievalSignal(tool, mcpResult) {
+    const sc = mcpResult.structuredContent;
+    if (tool === "rift_context_pack") {
+        if (!sc)
+            return {};
+        const sum = (key) => {
+            const v = sc[key];
+            return Array.isArray(v) ? v.length : 0;
+        };
+        const count = sum("decisions") + sum("constraints") + sum("examples") + sum("rules");
+        const out = { count };
+        if (typeof sc["degraded"] === "boolean")
+            out.degraded = sc["degraded"];
+        return out;
+    }
+    // search-style tools: prefer structuredContent.results, fall back to JSON-in-text.
+    const fromStructured = sc?.["results"];
+    if (Array.isArray(fromStructured)) {
+        const out = {
+            count: fromStructured.length,
+        };
+        if (typeof sc?.["degraded"] === "boolean") {
+            out.degraded = sc["degraded"];
+        }
+        return out;
+    }
+    try {
+        const text = mcpResult.content?.[0]?.text;
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        const out = {};
+        if (Array.isArray(parsed["results"])) {
+            out.count = parsed["results"].length;
+        }
+        if (typeof parsed["degraded"] === "boolean") {
+            out.degraded = parsed["degraded"];
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Render a duration like `7m 42s` / `1h 03m 17s` / `12s`. Used by the
+ * friend-status header so the value reads in human time, not seconds.
+ */
+export function formatOnboardingDuration(totalSeconds) {
+    const s = Math.max(0, Math.floor(totalSeconds));
+    const hours = Math.floor(s / 3600);
+    const minutes = Math.floor((s % 3600) / 60);
+    const seconds = s % 60;
+    if (hours > 0) {
+        return `${hours}h ${String(minutes).padStart(2, "0")}m ${String(seconds).padStart(2, "0")}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+    }
+    return `${seconds}s`;
+}
+//# sourceMappingURL=onboarding-metric.js.map

package/dist/src/observability/onboarding-metric.js.map

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

package/dist/src/observability/retrieval-feedback.d.ts

@@ -0,0 +1,82 @@
+import type { StableEvidenceIdentity } from "../retrieval/evidence-key.js";
+export declare const RETRIEVAL_FEEDBACK_FILE = "retrieval-feedback.jsonl";
+export declare const B_FEED_NEUTRAL = 1;
+export declare const B_FEED_MAX = 1.25;
+export type RetrievalFeedbackEventType = "evidence_opened" | "evidence_cited" | "feedback_reset";
+export interface RetrievalFeedbackEvent {
+    timestamp: string;
+    type: RetrievalFeedbackEventType;
+    stable_evidence_key: string;
+    evidence_kind?: string;
+    source_table?: string;
+    source_id?: string;
+    source_path?: string;
+    parent_id?: string;
+    digest_id?: string;
+    session_id?: string;
+    tool_call_id?: string;
+    outcome_id?: string;
+    project?: string;
+    intent?: string;
+    query?: string;
+    task?: string;
+    rank_at_retrieval?: number;
+    result_count?: number;
+    context_pack_bucket?: string;
+    position_in_bucket?: number;
+    reason?: string;
+    dedupe_key?: string;
+}
+export interface AppendRetrievalFeedbackInput {
+    type: RetrievalFeedbackEventType;
+    identity: StableEvidenceIdentity;
+    session_id?: string;
+    tool_call_id?: string;
+    outcome_id?: string;
+    project?: string;
+    intent?: string;
+    query?: string;
+    task?: string;
+    rank_at_retrieval?: number;
+    result_count?: number;
+    context_pack_bucket?: string;
+    position_in_bucket?: number;
+    reason?: string;
+    dedupe_key?: string;
+    now?: Date;
+}
+export interface AppendRetrievalFeedbackResult {
+    event: RetrievalFeedbackEvent;
+    written: boolean;
+    duplicate: boolean;
+}
+export interface FeedbackBoost {
+    stable_evidence_key: string;
+    B_feed: number;
+    weighted_credit: number;
+    positive_event_count: number;
+    reset_count: number;
+    applied: false;
+}
+export interface FeedbackScope {
+    project?: string;
+    intent?: string;
+    now?: Date;
+}
+export declare function retrievalFeedbackPath(dataDir: string): string;
+export declare function appendRetrievalFeedbackEvent(dataDir: string, input: AppendRetrievalFeedbackInput): AppendRetrievalFeedbackResult;
+export declare function appendFeedbackReset(dataDir: string, input: {
+    identity: StableEvidenceIdentity;
+    session_id?: string;
+    project?: string;
+    intent?: string;
+    reason?: string;
+    now?: Date;
+}): AppendRetrievalFeedbackResult;
+export declare function readRetrievalFeedbackEvents(dataDir: string): RetrievalFeedbackEvent[];
+export declare function computeFeedbackBoosts(events: readonly RetrievalFeedbackEvent[], stableEvidenceKeys: readonly string[], scope?: FeedbackScope): Map<string, FeedbackBoost>;
+export declare function explainFeedback(dataDir: string, stableEvidenceKey: string, scope?: FeedbackScope): FeedbackBoost & {
+    events: RetrievalFeedbackEvent[];
+};
+export declare function positionBiasWeight(event: RetrievalFeedbackEvent): number;
+//# sourceMappingURL=retrieval-feedback.d.ts.map

package/dist/src/observability/retrieval-feedback.d.ts.map

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