wotann 0.5.0 → 0.5.39

package/dist/session/fork.js

@@ -0,0 +1,223 @@
+/**
+ * Session fork primitive — branch a SQLite-backed session at its last
+ * checkpoint to enable parallel-approach exploration ("try CQRS vs
+ * event-sourcing", "what if we rolled this back and tried a different
+ * tool order"). Ported from the opencode/cline session-fork pattern.
+ *
+ * WHAT: Given a source session id and a `wotannDir`, this module opens
+ *   `<wotannDir>/sessions.db`, materialises the schema if it's missing,
+ *   and atomically copies the source session row + its message thread
+ *   (up to and including its `last_checkpoint`) into a freshly minted
+ *   session id. The new session inherits the source's `last_checkpoint`
+ *   pointer so a follow-on resume/restore command sees the same head.
+ *
+ * WHY: WOTANN already has two checkpoint flavours — `storage/
+ *   checkpoint-supersede.ts` (pure-data rollback algorithm) and
+ *   `autopilot/checkpoint.ts` (JSON file dumps for long-running autopilot
+ *   loops). Neither offers a first-class "branch from here" primitive
+ *   for SQL-backed sessions. The opencode + cline ports both expose this
+ *   as a single transactional copy; we follow that shape so the future
+ *   CLI subcommand has a clean call site.
+ *
+ * WHERE: Imported by the CLI surface that the parent agent will wire up
+ *   sequentially. The DB file path is derived from `req.wotannDir` so
+ *   callers can sandbox it per test or per workspace without changing
+ *   the module's interface.
+ *
+ * HOW:
+ *   1. Lazy-construct (or open) `<wotannDir>/sessions.db` via
+ *      `better-sqlite3`. The schema (`sessions`, `messages`) is created
+ *      with `CREATE TABLE IF NOT EXISTS`, so multiple callers sharing
+ *      the same DB never collide.
+ *   2. Look up the source session row. Honest error envelope on miss:
+ *      `{ok:false, error:"session not found"}`.
+ *   3. Read the source's `last_checkpoint` pointer. If absent or empty,
+ *      `{ok:false, error:"no checkpoint to fork from"}`.
+ *   4. Generate a new session id with `crypto.randomUUID()`.
+ *   5. Inside `db.transaction(...)`, INSERT the new sessions row and
+ *      COPY every message in the source thread whose `seq` is at or
+ *      below the message that backs the checkpoint pointer. better-
+ *      sqlite3 transactions roll back atomically on any thrown error,
+ *      so a partial INSERT can never leave the database half-forked.
+ *   6. Return `{ok:true, newSessionId, sourceCheckpoint, messageCount}`.
+ *
+ * Schema (self-contained — no other module currently owns these tables):
+ *   sessions(id PK, label, last_checkpoint, created_at, source_session)
+ *   messages(session_id, seq, role, content, checkpoint_id,
+ *            PRIMARY KEY (session_id, seq))
+ *
+ *   The `messages.checkpoint_id` column records WHICH checkpoint each
+ *   message was the head for — required so a fork can compute "all
+ *   messages up to the checkpoint" without an external join table. A
+ *   row with `checkpoint_id = NULL` is a regular message; a row with
+ *   `checkpoint_id` non-null is the message that minted that checkpoint.
+ *
+ *   `sessions.last_checkpoint` is the pointer field the task calls out —
+ *   it stores the checkpoint id (a string) so we can locate the cut
+ *   point during fork.
+ *
+ * Honest-stub policy: every failure path returns a typed `ForkResult`
+ * with `ok:false` and a human-readable `error` string. The function
+ * never throws to the caller. Callers can branch on `result.ok` and
+ * surface the `error` in the CLI without try/catch noise.
+ */
+import Database from "better-sqlite3";
+import { mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+// Schema bootstrap ───────────────────────────────────────
+/**
+ * Materialise the session schema. Idempotent: existing tables are left
+ * untouched, missing tables/indexes are created. Called by `forkSession`
+ * on every invocation so a brand-new `wotannDir` works without a
+ * separate migration step.
+ *
+ * We DO NOT set `journal_mode = WAL` here. The parent CLI may share the
+ * DB across processes and WAL behaviour interacts with that decision —
+ * leave journal mode at SQLite's default until the caller wires the
+ * proper PRAGMA bundle from `utils/schema-drift.ts`.
+ */
+function ensureSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      label TEXT,
+      last_checkpoint TEXT,
+      created_at INTEGER NOT NULL,
+      source_session TEXT
+    );
+    CREATE TABLE IF NOT EXISTS messages (
+      session_id TEXT NOT NULL,
+      seq INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      content TEXT NOT NULL,
+      checkpoint_id TEXT,
+      PRIMARY KEY (session_id, seq)
+    );
+    CREATE INDEX IF NOT EXISTS idx_messages_checkpoint
+      ON messages(session_id, checkpoint_id);
+  `);
+}
+/**
+ * Open the sessions database at `<wotannDir>/sessions.db`. Creates
+ * `wotannDir` if it doesn't exist so the first call on a fresh
+ * workspace doesn't fail with ENOENT. Errors from `better-sqlite3` (e.g.
+ * file-system permission failures) propagate to the caller —
+ * `forkSession` catches them and translates to a typed `ForkResult`.
+ */
+function openSessionDb(wotannDir) {
+    if (!existsSync(wotannDir)) {
+        mkdirSync(wotannDir, { recursive: true });
+    }
+    const dbPath = join(wotannDir, "sessions.db");
+    return new Database(dbPath);
+}
+// Public API ─────────────────────────────────────────────
+/**
+ * Fork a session at its last checkpoint. See module docstring for the
+ * full contract. Never throws — every failure mode is a structured
+ * `ForkResult` with `ok:false` and a `error` string.
+ *
+ * Returns `Promise<ForkResult>` because the task contract specifies an
+ * async signature; the implementation is synchronous under the hood
+ * (better-sqlite3 is sync) but we honour the public shape for
+ * forward-compatibility with the node-sqlite3 / sql.js backends that
+ * `selectStorageAdapter()` may eventually route to.
+ */
+export async function forkSession(req) {
+    let db = null;
+    try {
+        db = openSessionDb(req.wotannDir);
+        ensureSchema(db);
+        // Look up the source session row ──────────────────────
+        const sourceRow = db
+            .prepare("SELECT id, label, last_checkpoint, created_at, source_session FROM sessions WHERE id = ?")
+            .get(req.sourceSessionId);
+        if (!sourceRow) {
+            return { ok: false, error: "session not found" };
+        }
+        const sourceCheckpoint = sourceRow.last_checkpoint;
+        if (sourceCheckpoint === null || sourceCheckpoint === undefined || sourceCheckpoint === "") {
+            return { ok: false, error: "no checkpoint to fork from" };
+        }
+        // Locate the message that minted the checkpoint ───────
+        // `messages.checkpoint_id` is set on the message at which the
+        // checkpoint was minted. We accept the FIRST match (lowest seq)
+        // so a misconfigured DB that double-tags rows still produces a
+        // deterministic cut.
+        const checkpointMessage = db
+            .prepare("SELECT session_id, seq, role, content, checkpoint_id " +
+            "FROM messages WHERE session_id = ? AND checkpoint_id = ? " +
+            "ORDER BY seq ASC LIMIT 1")
+            .get(req.sourceSessionId, sourceCheckpoint);
+        // Cut point: every message with seq <= checkpointMessage.seq. If
+        // the checkpoint pointer doesn't match any message (e.g. it was
+        // recorded before the message thread existed), we copy ALL
+        // messages — the checkpoint is the conceptual head even if no
+        // message backs it. This preserves the fork's "branch from here"
+        // semantics for thread-less sessions.
+        const cutSeq = checkpointMessage ? checkpointMessage.seq : Number.MAX_SAFE_INTEGER;
+        const newSessionId = randomUUID();
+        const createdAt = Date.now();
+        const newLabel = req.label ?? sourceRow.label ?? null;
+        // Atomic copy ────────────────────────────────────────
+        // better-sqlite3's `transaction()` wraps the callback in BEGIN /
+        // COMMIT and rolls back on any thrown error. If the new session
+        // INSERT collides or the message COPY fails partway, the DB is
+        // restored to its pre-fork state.
+        const handle = db;
+        const tx = handle.transaction(() => {
+            // Insert the new session row pointing at the SAME checkpoint id.
+            // The fork inherits the cut point — the next snapshot the user
+            // takes will supersede it via checkpoint-supersede semantics.
+            handle
+                .prepare("INSERT INTO sessions (id, label, last_checkpoint, created_at, source_session) " +
+                "VALUES (?, ?, ?, ?, ?)")
+                .run(newSessionId, newLabel, sourceCheckpoint, createdAt, sourceRow.id);
+            // Copy every message in the source thread up to and including
+            // the checkpoint cut point. We re-use the source's `seq` values
+            // because the new thread is a verbatim prefix; subsequent writes
+            // will append at seq = max(seq) + 1.
+            const sourceMessages = handle
+                .prepare("SELECT session_id, seq, role, content, checkpoint_id " +
+                "FROM messages WHERE session_id = ? AND seq <= ? " +
+                "ORDER BY seq ASC")
+                .all(req.sourceSessionId, cutSeq);
+            const insertMsg = handle.prepare("INSERT INTO messages (session_id, seq, role, content, checkpoint_id) " +
+                "VALUES (?, ?, ?, ?, ?)");
+            for (const m of sourceMessages) {
+                insertMsg.run(newSessionId, m.seq, m.role, m.content, m.checkpoint_id);
+            }
+            return sourceMessages.length;
+        });
+        const messageCount = tx();
+        return {
+            ok: true,
+            newSessionId,
+            sourceCheckpoint,
+            messageCount,
+        };
+    }
+    catch (err) {
+        // Translate every native exception into a typed envelope. Closed /
+        // read-only DBs surface here ("This database connection is busy"
+        // or "attempt to write a readonly database"), as do disk-full and
+        // permission errors. The CLI caller decides whether to surface
+        // the raw message; we expose it so debugging stays honest.
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `fork failed: ${message}` };
+    }
+    finally {
+        // Close the handle even on the error path so the test harness can
+        // remove the temp dir without "database is locked" noise on
+        // Windows. better-sqlite3's close() is idempotent.
+        try {
+            db?.close();
+        }
+        catch {
+            // Best-effort — if close itself throws, the caller already has
+            // the primary error to act on.
+        }
+    }
+}
+//# sourceMappingURL=fork.js.map

package/dist/session/fork.js.map

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

package/dist/skills/activation-telemetry.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Skill activation telemetry — closes the description-optimizer loop.
+ *
+ * The description-optimizer (skills/description-optimizer.ts) needs a
+ * labeled corpus of (prompt, expected-trigger) pairs to score a
+ * description's F1. Hand-curating that corpus is tedious. This module
+ * records, for every WOTANN session, *which* skill (if any) was
+ * actually activated for *which* user prompt, and persists the result
+ * to a JSONL log. The optimizer can then pull a real corpus directly
+ * from observed usage:
+ *
+ *   - positives for skill X = prompts where X was triggered
+ *   - negatives for skill X = prompts where X was NOT triggered
+ *
+ * The loop closes: real usage → telemetry → corpus → optimizer →
+ * better description → better future activation.
+ *
+ * Storage shape — JSONL with two event kinds:
+ *
+ *   activation:  { kind:"activation", ts, sessionId, prompt,
+ *                  triggered: {skill, kind} | null,
+ *                  candidates: [{skill, score}], outcome }
+ *
+ *   outcome-patch: { kind:"outcome-patch", ts, sessionId, outcome }
+ *
+ * The patch-event form is how `markOutcome` survives a process restart
+ * and a JSONL reload. `loadTelemetryLog` folds patches into the most-
+ * recent matching activation when reading, so disk-backed corpus
+ * mining sees regret signals exactly the same as in-memory does.
+ *
+ * Where:
+ *   - `triggered` is the skill that fired (null if no skill fired)
+ *   - `kind`      is "auto" | "user-named" — whether the harness chose
+ *     the skill itself or the user explicitly called it
+ *   - `candidates` is the top-N skills by the auto-detector's score
+ *     (so optimizer can mine near-misses for negatives)
+ *   - `outcome`   captures whether the activation was useful: "ok"
+ *     when a downstream success signal arrived, "regret" when the
+ *     user immediately re-invoked a different skill
+ *
+ * QUALITY BARS
+ *   - QB#1 No vendor bias — provider-agnostic; skills are name-only.
+ *   - QB#3 Honest stub — disk failures degrade to in-memory only and
+ *     surface a warn so the run never crashes.
+ *   - QB#7 Per-call state — each Telemetry instance is fresh; no
+ *     module-level singleton.
+ *   - QB#13 Env guard — telemetry is disabled by default (opt-in via
+ *     constructor flag); tests can pass `enabled:false` for full mocking.
+ */
+export type ActivationKind = "auto" | "user-named";
+export type ActivationOutcome = "ok" | "regret" | "unknown";
+export interface ActivationCandidate {
+    readonly skill: string;
+    readonly score: number;
+}
+export interface ActivationEvent {
+    /** ISO-8601 timestamp the event was recorded. */
+    readonly ts: string;
+    /** WOTANN session id the event belongs to. */
+    readonly sessionId: string;
+    /** The user's prompt text (exact, untrimmed) for corpus mining. */
+    readonly prompt: string;
+    /** The skill that fired, or null when no skill fired. */
+    readonly triggered: {
+        readonly skill: string;
+        readonly kind: ActivationKind;
+    } | null;
+    /** Top candidates from the activation scorer (regret + near-miss mining). */
+    readonly candidates: readonly ActivationCandidate[];
+    /** Optional outcome marker — set later by markOutcome(). */
+    readonly outcome: ActivationOutcome;
+}
+export interface TelemetryOptions {
+    /** When false, every method is a no-op. Default: true. */
+    readonly enabled?: boolean;
+    /** Path to the JSONL log. Required when enabled is true. */
+    readonly path?: string;
+    /** Optional clock override (tests). */
+    readonly now?: () => Date;
+    /** Cap on in-memory events when disk write fails. Default: 1000. */
+    readonly memoryCap?: number;
+}
+/**
+ * Append-only telemetry sink. Writes JSONL to disk; falls back to an
+ * in-memory ring when the disk write fails so the active run never
+ * loses events to filesystem hiccups.
+ */
+export declare class SkillActivationTelemetry {
+    private readonly enabled;
+    private readonly path;
+    private readonly now;
+    private readonly memoryCap;
+    private readonly memory;
+    /** Index from sessionId → most-recent event index in `memory` so
+     * markOutcome can patch retroactively without scanning the whole log. */
+    private readonly recentBySession;
+    constructor(opts?: TelemetryOptions);
+    /**
+     * Record one activation event. The event is added to the in-memory
+     * ring AND appended to disk (when a path is configured). Disk write
+     * failure is logged once; in-memory persists.
+     */
+    record(input: Omit<ActivationEvent, "ts" | "outcome"> & {
+        outcome?: ActivationOutcome;
+    }): Promise<ActivationEvent>;
+    /**
+     * Patch the outcome of the most-recent event for a given session.
+     * Used by the runtime to flag e.g. "user immediately switched to a
+     * different skill" → outcome:"regret".
+     *
+     * Persists the patch to disk as an `outcome-patch` JSONL event so a
+     * reload picks up the regret signal. Returns true when a matching
+     * in-memory event was patched (or telemetry is enabled); false when
+     * no recent event existed and telemetry is disabled.
+     */
+    markOutcome(sessionId: string, outcome: ActivationOutcome): Promise<boolean>;
+    /**
+     * In-memory snapshot of the recorded events (for tests / inspection).
+     * Returns a frozen copy so callers cannot mutate the ring.
+     */
+    snapshot(): readonly ActivationEvent[];
+    private pushMemory;
+}
+export interface ExtractedCorpus {
+    /** Prompts where the named skill triggered with outcome != "regret". */
+    readonly positives: readonly string[];
+    /** Prompts where another skill triggered while the named skill was
+     *  in the candidate set (true negatives — same domain, wrong skill). */
+    readonly negatives: readonly string[];
+    /** Total number of events scanned. */
+    readonly scanned: number;
+}
+/**
+ * Build a positive/negative corpus for the named skill from a
+ * read-only event stream. The negatives heuristic uses *near-miss*
+ * events (the named skill was a candidate but a different skill won)
+ * because pure non-trigger events are too easy and don't sharpen the
+ * description. Falls back to non-trigger events when the candidate
+ * stream isn't populated.
+ */
+export declare function extractCorpusForSkill(events: readonly ActivationEvent[], skill: string, opts?: {
+    readonly maxEach?: number;
+}): ExtractedCorpus;
+/**
+ * Read a JSONL telemetry log from disk and return the parsed events.
+ * Malformed lines are skipped (with a count returned for diagnostics).
+ */
+export interface LoadResult {
+    readonly events: readonly ActivationEvent[];
+    readonly skipped: number;
+    readonly path: string;
+}
+export declare function loadTelemetryLog(path: string): LoadResult;
+//# sourceMappingURL=activation-telemetry.d.ts.map

package/dist/skills/activation-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-telemetry.d.ts","sourceRoot":"","sources":["../../src/skills/activation-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAQH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,YAAY,CAAC;AACnD,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI,CAAC;IACrF,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAID,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD;6EACyE;IACzE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;gBAEtD,IAAI,GAAE,gBAAqB;IAoBvC;;;;OAIG;IACG,MAAM,CACV,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,SAAS,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAC/E,OAAO,CAAC,eAAe,CAAC;IAwB3B;;;;;;;;;OASG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BlF;;;OAGG;IACH,QAAQ,IAAI,SAAS,eAAe,EAAE;IAItC,OAAO,CAAC,UAAU;CAanB;AAID,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;4EACwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,eAAe,CAmCjB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAkDzD"}

package/dist/skills/activation-telemetry.js

@@ -0,0 +1,274 @@
+/**
+ * Skill activation telemetry — closes the description-optimizer loop.
+ *
+ * The description-optimizer (skills/description-optimizer.ts) needs a
+ * labeled corpus of (prompt, expected-trigger) pairs to score a
+ * description's F1. Hand-curating that corpus is tedious. This module
+ * records, for every WOTANN session, *which* skill (if any) was
+ * actually activated for *which* user prompt, and persists the result
+ * to a JSONL log. The optimizer can then pull a real corpus directly
+ * from observed usage:
+ *
+ *   - positives for skill X = prompts where X was triggered
+ *   - negatives for skill X = prompts where X was NOT triggered
+ *
+ * The loop closes: real usage → telemetry → corpus → optimizer →
+ * better description → better future activation.
+ *
+ * Storage shape — JSONL with two event kinds:
+ *
+ *   activation:  { kind:"activation", ts, sessionId, prompt,
+ *                  triggered: {skill, kind} | null,
+ *                  candidates: [{skill, score}], outcome }
+ *
+ *   outcome-patch: { kind:"outcome-patch", ts, sessionId, outcome }
+ *
+ * The patch-event form is how `markOutcome` survives a process restart
+ * and a JSONL reload. `loadTelemetryLog` folds patches into the most-
+ * recent matching activation when reading, so disk-backed corpus
+ * mining sees regret signals exactly the same as in-memory does.
+ *
+ * Where:
+ *   - `triggered` is the skill that fired (null if no skill fired)
+ *   - `kind`      is "auto" | "user-named" — whether the harness chose
+ *     the skill itself or the user explicitly called it
+ *   - `candidates` is the top-N skills by the auto-detector's score
+ *     (so optimizer can mine near-misses for negatives)
+ *   - `outcome`   captures whether the activation was useful: "ok"
+ *     when a downstream success signal arrived, "regret" when the
+ *     user immediately re-invoked a different skill
+ *
+ * QUALITY BARS
+ *   - QB#1 No vendor bias — provider-agnostic; skills are name-only.
+ *   - QB#3 Honest stub — disk failures degrade to in-memory only and
+ *     surface a warn so the run never crashes.
+ *   - QB#7 Per-call state — each Telemetry instance is fresh; no
+ *     module-level singleton.
+ *   - QB#13 Env guard — telemetry is disabled by default (opt-in via
+ *     constructor flag); tests can pass `enabled:false` for full mocking.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * Append-only telemetry sink. Writes JSONL to disk; falls back to an
+ * in-memory ring when the disk write fails so the active run never
+ * loses events to filesystem hiccups.
+ */
+export class SkillActivationTelemetry {
+    enabled;
+    path;
+    now;
+    memoryCap;
+    memory = [];
+    /** Index from sessionId → most-recent event index in `memory` so
+     * markOutcome can patch retroactively without scanning the whole log. */
+    recentBySession = new Map();
+    constructor(opts = {}) {
+        this.enabled = opts.enabled ?? true;
+        this.path = opts.path ?? null;
+        this.now = opts.now ?? (() => new Date());
+        this.memoryCap = opts.memoryCap ?? 1000;
+        if (this.enabled && this.path) {
+            try {
+                const dir = dirname(this.path);
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+            }
+            catch (e) {
+                // Non-fatal — record() will retry on first append; in-memory
+                // ring is the safety net.
+                console.warn(`[skill-telemetry] failed to ensure dir for ${this.path}: ${e.message}`);
+            }
+        }
+    }
+    /**
+     * Record one activation event. The event is added to the in-memory
+     * ring AND appended to disk (when a path is configured). Disk write
+     * failure is logged once; in-memory persists.
+     */
+    async record(input) {
+        const event = {
+            ts: this.now().toISOString(),
+            sessionId: input.sessionId,
+            prompt: input.prompt,
+            triggered: input.triggered,
+            candidates: input.candidates,
+            outcome: input.outcome ?? "unknown",
+        };
+        if (!this.enabled)
+            return event;
+        this.pushMemory(event);
+        if (this.path) {
+            try {
+                await appendFile(this.path, JSON.stringify(event) + "\n", "utf-8");
+            }
+            catch (e) {
+                console.warn(`[skill-telemetry] disk write failed (${e.message}); continuing with in-memory log`);
+            }
+        }
+        return event;
+    }
+    /**
+     * Patch the outcome of the most-recent event for a given session.
+     * Used by the runtime to flag e.g. "user immediately switched to a
+     * different skill" → outcome:"regret".
+     *
+     * Persists the patch to disk as an `outcome-patch` JSONL event so a
+     * reload picks up the regret signal. Returns true when a matching
+     * in-memory event was patched (or telemetry is enabled); false when
+     * no recent event existed and telemetry is disabled.
+     */
+    async markOutcome(sessionId, outcome) {
+        const idx = this.recentBySession.get(sessionId);
+        let patchedInMemory = false;
+        if (idx !== undefined) {
+            const event = this.memory[idx];
+            if (event) {
+                this.memory[idx] = { ...event, outcome };
+                patchedInMemory = true;
+            }
+        }
+        if (!this.enabled)
+            return patchedInMemory;
+        if (this.path) {
+            try {
+                const patch = {
+                    kind: "outcome-patch",
+                    ts: this.now().toISOString(),
+                    sessionId,
+                    outcome,
+                };
+                await appendFile(this.path, JSON.stringify(patch) + "\n", "utf-8");
+            }
+            catch (e) {
+                console.warn(`[skill-telemetry] outcome-patch disk write failed (${e.message})`);
+            }
+        }
+        // When telemetry is on but session never recorded, the disk patch
+        // can still be useful for offline analysis — return true.
+        return patchedInMemory || this.enabled;
+    }
+    /**
+     * In-memory snapshot of the recorded events (for tests / inspection).
+     * Returns a frozen copy so callers cannot mutate the ring.
+     */
+    snapshot() {
+        return Object.freeze([...this.memory]);
+    }
+    pushMemory(event) {
+        this.memory.push(event);
+        if (this.memory.length > this.memoryCap) {
+            // Drop the oldest. Re-index the recentBySession map so its
+            // pointers stay valid after the shift.
+            this.memory.shift();
+            for (const [k, v] of this.recentBySession) {
+                if (v <= 0)
+                    this.recentBySession.delete(k);
+                else
+                    this.recentBySession.set(k, v - 1);
+            }
+        }
+        this.recentBySession.set(event.sessionId, this.memory.length - 1);
+    }
+}
+/**
+ * Build a positive/negative corpus for the named skill from a
+ * read-only event stream. The negatives heuristic uses *near-miss*
+ * events (the named skill was a candidate but a different skill won)
+ * because pure non-trigger events are too easy and don't sharpen the
+ * description. Falls back to non-trigger events when the candidate
+ * stream isn't populated.
+ */
+export function extractCorpusForSkill(events, skill, opts = {}) {
+    const cap = typeof opts.maxEach === "number" && opts.maxEach > 0 ? opts.maxEach : Infinity;
+    const positives = [];
+    const negatives = [];
+    let scanned = 0;
+    for (const e of events) {
+        scanned++;
+        // Positive: the named skill fired with no regret marker.
+        if (e.triggered?.skill === skill && e.outcome !== "regret") {
+            if (positives.length < cap)
+                positives.push(e.prompt);
+            continue;
+        }
+        // Near-miss negative: a different skill fired AND the named skill
+        // was in the candidate set. Strong signal — same domain, wrong
+        // skill.
+        if (e.triggered?.skill &&
+            e.triggered.skill !== skill &&
+            e.candidates.some((c) => c.skill === skill)) {
+            if (negatives.length < cap)
+                negatives.push(e.prompt);
+            continue;
+        }
+        // Weak negative: no skill fired and the named skill wasn't a
+        // candidate at all. Only used to fill out the negative set when
+        // we don't have enough near-misses.
+        if (e.triggered === null && !e.candidates.some((c) => c.skill === skill)) {
+            if (negatives.length < cap)
+                negatives.push(e.prompt);
+        }
+    }
+    return {
+        positives: Object.freeze(positives),
+        negatives: Object.freeze(negatives),
+        scanned,
+    };
+}
+export function loadTelemetryLog(path) {
+    if (!existsSync(path)) {
+        return { events: Object.freeze([]), skipped: 0, path };
+    }
+    const raw = readFileSync(path, "utf-8");
+    const events = [];
+    // Track most-recent activation index per session so we can fold
+    // outcome-patch lines into the matching activation.
+    const recentBySession = new Map();
+    let skipped = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            skipped++;
+            continue;
+        }
+        const obj = parsed;
+        // outcome-patch: fold into the matching activation, then move on.
+        if (obj["kind"] === "outcome-patch") {
+            const sid = obj["sessionId"];
+            const oc = obj["outcome"];
+            if (typeof sid === "string" && typeof oc === "string") {
+                const idx = recentBySession.get(sid);
+                if (idx !== undefined) {
+                    const event = events[idx];
+                    if (event) {
+                        events[idx] = { ...event, outcome: oc };
+                    }
+                }
+            }
+            continue;
+        }
+        // Default: treat as activation event. Lightweight shape gate.
+        const event = obj;
+        if (typeof event.prompt === "string" && typeof event.sessionId === "string") {
+            events.push(event);
+            recentBySession.set(event.sessionId, events.length - 1);
+        }
+        else {
+            skipped++;
+        }
+    }
+    return { events: Object.freeze(events), skipped, path };
+}
+//# sourceMappingURL=activation-telemetry.js.map