@kolisachint/hoocode-agent 0.5.16 → 0.5.18

package/dist/core/learn/mine.js

@@ -0,0 +1,285 @@
+/**
+ * The map half of `/learn`: a model reads one session transcript and says what
+ * it saw.
+ *
+ * This replaces the regex gate that used to decide which user turns were worth
+ * looking at. That gate was a whitelist of imperative words, so a directive
+ * phrased any other way — "we're on bun now", "that's not how our error
+ * handling works" — was not ranked low, it was invisible. Recall was traded for
+ * a token budget, silently and unrecoverably.
+ *
+ * The trade here is explicit instead. Every user turn goes to the model
+ * verbatim; the budget is enforced by chunking and by a session cap the reader
+ * can see, not by a filter they cannot.
+ *
+ * What the model does *not* do is count. It reports occurrences one session at
+ * a time, and each one carries a `label` — its own normalization of what was
+ * meant. Counting identical labels across sessions is arithmetic, and it stays
+ * in code (see `reduce.ts`), for two reasons: models do not count reliably over
+ * long contexts, and a session mined in isolation cannot see recurrence anyway.
+ * Semantic grouping is the model's job; the number is not.
+ */
+import { completeSimple } from "@kolisachint/hoocode-ai";
+/**
+ * Chunking exists to fit a session into a context window, so it is sized from
+ * the window rather than from a fixed guess.
+ *
+ * The guess was costing calls. Rendering already strips assistant prose and
+ * truncates tool output, which compresses the two real transcripts in this repo
+ * from 0.93 MB and 2.26 MB down to 183 KB and 266 KB — about 47k and 68k
+ * tokens. A fixed 120k-character chunk cut those into two and three pieces for
+ * no reason: on any model with a 200k window each is comfortably one call.
+ *
+ * One call per session is also better than a cheaper-looking alternative. A
+ * chunk boundary is a blind spot — a failure and the fix that resolved it can
+ * land on opposite sides of one — so the fewer boundaries inside a session, the
+ * more the model can actually see.
+ */
+const CHUNK_CONTEXT_FRACTION = 0.6;
+/** Rough bytes per token. Deliberately conservative; a wrong guess here costs a wasted call. */
+const CHARS_PER_TOKEN = 4;
+/** Used when a model does not report a usable window. */
+const FALLBACK_CHUNK_CHARS = 120_000;
+/** Never chunk below this, or a small window would shred a transcript into noise. */
+const MIN_CHUNK_CHARS = 40_000;
+/**
+ * How much rendered transcript to send per call, given the reading model.
+ *
+ * Only a fraction of the window is used: the instructions, the response, and
+ * tokenizer variance all have to fit alongside, and overshooting costs a
+ * context-overflow error rather than a slightly worse answer.
+ */
+export function chunkCharsForModel(model) {
+    const window = model.contextWindow;
+    if (!Number.isFinite(window) || window <= 0)
+        return FALLBACK_CHUNK_CHARS;
+    const budgetTokens = window * CHUNK_CONTEXT_FRACTION - MAX_RESPONSE_TOKENS;
+    return Math.max(MIN_CHUNK_CHARS, Math.floor(budgetTokens * CHARS_PER_TOKEN));
+}
+/** Tool output kept per call. Errors carry the signal; success output is mostly noise. */
+const TOOL_OUTPUT_CHARS = 600;
+const TOOL_ERROR_CHARS = 1_500;
+/** Response ceiling per chunk. A chunk yielding more than this is noise, not signal. */
+const MAX_RESPONSE_TOKENS = 4_000;
+/** Candidates accepted from a single chunk, as a guard against a runaway response. */
+const MAX_CANDIDATES_PER_CHUNK = 40;
+/**
+ * Prefix on the message `/learn` injects. Its own digest is persisted like any
+ * other user turn, so without this the next run would mine its own output and
+ * every proposal would compound its own count.
+ */
+export const LEARN_DIGEST_MARKER = "[learn-digest]";
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => block && typeof block === "object" && block.type === "text"
+        ? (block.text ?? "")
+        : "")
+        .join("\n")
+        .trim();
+}
+function isToolCall(block) {
+    return !!block && typeof block === "object" && block.type === "toolCall";
+}
+/** Compact one tool call's arguments — enough to recognise it, not enough to flood the window. */
+function renderArgs(args) {
+    if (!args)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === "string") {
+            parts.push(`${key}=${value.length > 200 ? `${value.slice(0, 200)}…` : value}`);
+        }
+        else if (typeof value === "number" || typeof value === "boolean") {
+            parts.push(`${key}=${value}`);
+        }
+        // Objects and arrays are structural detail the miner does not need.
+    }
+    return parts.join(" ");
+}
+/**
+ * Render a session as plain text for the model.
+ *
+ * User turns go in whole and unfiltered — that is the entire point of this
+ * rewrite, and any truncation here would quietly reintroduce the recall problem
+ * the regex gate had. Assistant prose is dropped: it is the bulk of a
+ * transcript and almost none of it is evidence about what the *user* wants.
+ * Tool calls are kept because a repeated sequence is a workflow and a
+ * failure-then-pass is a fix, and both are things worth proposing.
+ */
+export function renderTranscript(session) {
+    const lines = [];
+    for (const entry of session.entries) {
+        const message = entry.type === "message" ? entry.message : undefined;
+        if (!message)
+            continue;
+        if (message.role === "user") {
+            const text = textOf(message.content);
+            // Skip the command's own past output, or proposals compound their counts.
+            if (!text || text.startsWith(LEARN_DIGEST_MARKER))
+                continue;
+            lines.push(`USER: ${text}`);
+            continue;
+        }
+        if (message.role === "assistant") {
+            for (const block of (message.content ?? [])) {
+                if (!isToolCall(block))
+                    continue;
+                lines.push(`TOOL: ${block.name}(${renderArgs(block.arguments)})`);
+            }
+            continue;
+        }
+        if (message.role === "toolResult") {
+            const output = textOf(message.content);
+            if (!output)
+                continue;
+            const limit = message.isError ? TOOL_ERROR_CHARS : TOOL_OUTPUT_CHARS;
+            const label = message.isError ? "ERROR" : "RESULT";
+            lines.push(`${label}: ${output.length > limit ? `${output.slice(0, limit)}…` : output}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Split rendered text on line boundaries, so a chunk never cuts a user turn in
+ * half. A single turn longer than the budget gets its own oversized chunk
+ * rather than being split — losing the second half of a long directive is
+ * exactly the failure this rewrite exists to remove.
+ */
+export function chunkTranscript(text, chunkChars = FALLBACK_CHUNK_CHARS) {
+    if (text.length <= chunkChars)
+        return text.length > 0 ? [text] : [];
+    const chunks = [];
+    let current = [];
+    let size = 0;
+    for (const line of text.split("\n")) {
+        if (size > 0 && size + line.length + 1 > chunkChars) {
+            chunks.push(current.join("\n"));
+            current = [];
+            size = 0;
+        }
+        current.push(line);
+        size += line.length + 1;
+    }
+    if (current.length > 0)
+        chunks.push(current.join("\n"));
+    return chunks;
+}
+const MINER_SYSTEM_PROMPT = `You read one coding-session transcript and report durable signals in it.
+
+You are the recall stage of a two-stage pipeline. A later stage counts how often each signal recurs ACROSS sessions and decides what is worth writing down. Your job is to notice and name, not to judge importance and not to count — you are seeing one session and cannot know what repeats.
+
+Report three kinds of thing.
+
+**directive** — the user stating a preference, correction, constraint, or fact about how they want work done. Include these regardless of phrasing. All of these are directives:
+- imperative: "always run the tests before pushing"
+- corrective: "no, that's not how our error handling works"
+- declarative: "we're on bun now", "the API returns snake_case"
+- preference stated once, in passing: "I'd rather see this as a table"
+Do NOT report task requests ("add a button to the header", "fix the login bug"). A task is what to do now; a directive is how things should be done in general. When a message contains both, report only the directive part.
+
+**fix** — a command that failed and later succeeded, where something in between was the cause. Report the failing command, a short error excerpt, and what changed in between.
+
+**workflow** — a sequence of three or more tool calls that recurs within this session, or that clearly represents a routine procedure (scaffold a file, then register it, then test it).
+
+For every item, produce a "label": a short kebab-case slug naming what was MEANT, not what was said. The label is how occurrences are grouped across sessions, so two different phrasings of the same underlying point MUST get the same label.
+- "we're on bun now" → use-bun-not-npm
+- "stop using npm install" → use-bun-not-npm
+- "pnpm isn't what we use here" → use-bun-not-npm
+Keep labels general enough to collide when they mean the same thing, specific enough not to collide when they do not. Prefer 2-5 words.
+
+Output STRICT JSON, no markdown fence, no prose:
+{"candidates":[{"kind":"directive","label":"use-bun-not-npm","text":"<verbatim quote>","rationale":"<one clause on why it is durable>"}]}
+
+For fix items add: "command", "errorExcerpt", "interveningCommands" (array), "editedFiles" (array).
+For workflow items add: "steps" (array of tool names in order).
+
+Report nothing rather than padding. An empty list is a correct answer for a session that taught nothing: {"candidates":[]}`;
+/**
+ * Pull the JSON object out of a model response.
+ *
+ * Models fence JSON even when told not to, and occasionally prepend a sentence.
+ * Scanning for the outermost braces is more forgiving than trusting the format
+ * and cheaper than a repair pass — and a chunk whose response cannot be parsed
+ * is skipped, never fatal, because one bad chunk should not lose a whole run.
+ */
+export function parseCandidates(response) {
+    const start = response.indexOf("{");
+    const end = response.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(response.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    const raw = parsed?.candidates;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw.slice(0, MAX_CANDIDATES_PER_CHUNK)) {
+        if (!item || typeof item !== "object")
+            continue;
+        const candidate = item;
+        const kind = candidate.kind;
+        if (kind !== "directive" && kind !== "fix" && kind !== "workflow")
+            continue;
+        const label = typeof candidate.label === "string" ? candidate.label.trim().toLowerCase() : "";
+        const text = typeof candidate.text === "string" ? candidate.text.trim() : "";
+        // A candidate with no label cannot be grouped, and one with no text cannot
+        // be quoted back — either way there is nothing to show the reader.
+        if (!label || !text)
+            continue;
+        const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string").slice(0, 12) : undefined;
+        out.push({
+            kind,
+            label,
+            text,
+            rationale: typeof candidate.rationale === "string" ? candidate.rationale.trim() : undefined,
+            command: typeof candidate.command === "string" ? candidate.command : undefined,
+            errorExcerpt: typeof candidate.errorExcerpt === "string" ? candidate.errorExcerpt.slice(0, 400) : undefined,
+            interveningCommands: strings(candidate.interveningCommands),
+            editedFiles: strings(candidate.editedFiles),
+            steps: strings(candidate.steps),
+        });
+    }
+    return out;
+}
+/**
+ * Build the real miner: one model call per chunk of one session.
+ *
+ * Chunks are mined sequentially rather than in parallel. A cold-cache run is
+ * already the expensive path, and firing every chunk of every session at once
+ * is how you trip a provider rate limit on exactly the run that has the most to
+ * do.
+ */
+export function createLlmMiner(deps) {
+    const chunkChars = chunkCharsForModel(deps.model);
+    return async (session, signal) => {
+        const chunks = chunkTranscript(renderTranscript(session), chunkChars);
+        const candidates = [];
+        for (const chunk of chunks) {
+            if (signal?.aborted)
+                break;
+            const response = await completeSimple(deps.model, {
+                systemPrompt: MINER_SYSTEM_PROMPT,
+                messages: [{ role: "user", content: [{ type: "text", text: chunk }], timestamp: Date.now() }],
+            }, { maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers });
+            if (response.stopReason === "error") {
+                throw new Error(response.errorMessage || "miner call failed");
+            }
+            const text = response.content
+                .filter((c) => c.type === "text")
+                .map((c) => c.text)
+                .join("\n");
+            candidates.push(...parseCandidates(text));
+        }
+        return candidates;
+    };
+}
+//# sourceMappingURL=mine.js.map

package/dist/core/learn/mine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mine.js","sourceRoot":"","sources":["../../../src/core/learn/mine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The map half of `/learn`: a model reads one session transcript and says what\n * it saw.\n *\n * This replaces the regex gate that used to decide which user turns were worth\n * looking at. That gate was a whitelist of imperative words, so a directive\n * phrased any other way — \"we're on bun now\", \"that's not how our error\n * handling works\" — was not ranked low, it was invisible. Recall was traded for\n * a token budget, silently and unrecoverably.\n *\n * The trade here is explicit instead. Every user turn goes to the model\n * verbatim; the budget is enforced by chunking and by a session cap the reader\n * can see, not by a filter they cannot.\n *\n * What the model does *not* do is count. It reports occurrences one session at\n * a time, and each one carries a `label` — its own normalization of what was\n * meant. Counting identical labels across sessions is arithmetic, and it stays\n * in code (see `reduce.ts`), for two reasons: models do not count reliably over\n * long contexts, and a session mined in isolation cannot see recurrence anyway.\n * Semantic grouping is the model's job; the number is not.\n */\n\nimport type { AgentMessage } from \"@kolisachint/hoocode-agent-core\";\nimport type { Model, TextContent, ToolCall } from \"@kolisachint/hoocode-ai\";\nimport { completeSimple } from \"@kolisachint/hoocode-ai\";\n\n/** What kind of thing the model noticed. */\nexport type CandidateKind = \"directive\" | \"fix\" | \"workflow\";\n\n/**\n * One occurrence, as reported by the model reading a single session.\n *\n * `label` is the load-bearing field. It is the model's canonical name for what\n * was meant — \"use-bun-not-npm\" for all of \"we're on bun now\", \"stop using\n * npm\", and \"pnpm isn't what we use\" — and it is what the reduce step groups\n * on. Getting a stable label out of the model is what buys semantic clustering\n * that `normalizeDirective`'s lowercase-and-strip-punctuation could never do.\n */\nexport interface MinedCandidate {\n\tkind: CandidateKind;\n\t/** Canonical slug for what was meant. The clustering key. */\n\tlabel: string;\n\t/** Verbatim text from the transcript, so the digest can quote rather than paraphrase. */\n\ttext: string;\n\t/** Why this is durable, in the model's words. Shown when a proposal is borderline. */\n\trationale?: string;\n\t/** The failing command, for `fix` candidates. */\n\tcommand?: string;\n\t/** Short error excerpt, for `fix` candidates. */\n\terrorExcerpt?: string;\n\t/** What was done in between, for `fix` candidates. */\n\tinterveningCommands?: string[];\n\t/** Files changed as part of the fix. */\n\teditedFiles?: string[];\n\t/** Tool sequence, for `workflow` candidates. */\n\tsteps?: string[];\n}\n\n/** A session reduced to what the miner needs: identity, time, and rendered text. */\nexport interface MinableSession {\n\tid: string;\n\ttimestamp: string;\n\tentries: Array<{ type: string; message?: AgentMessage }>;\n}\n\n/**\n * Mines one session. Injectable so the reduce path can be tested without a\n * model, and so a cached result can stand in for a live call.\n */\nexport type Miner = (session: MinableSession, signal?: AbortSignal) => Promise<MinedCandidate[]>;\n\n/**\n * Chunking exists to fit a session into a context window, so it is sized from\n * the window rather than from a fixed guess.\n *\n * The guess was costing calls. Rendering already strips assistant prose and\n * truncates tool output, which compresses the two real transcripts in this repo\n * from 0.93 MB and 2.26 MB down to 183 KB and 266 KB — about 47k and 68k\n * tokens. A fixed 120k-character chunk cut those into two and three pieces for\n * no reason: on any model with a 200k window each is comfortably one call.\n *\n * One call per session is also better than a cheaper-looking alternative. A\n * chunk boundary is a blind spot — a failure and the fix that resolved it can\n * land on opposite sides of one — so the fewer boundaries inside a session, the\n * more the model can actually see.\n */\nconst CHUNK_CONTEXT_FRACTION = 0.6;\n\n/** Rough bytes per token. Deliberately conservative; a wrong guess here costs a wasted call. */\nconst CHARS_PER_TOKEN = 4;\n\n/** Used when a model does not report a usable window. */\nconst FALLBACK_CHUNK_CHARS = 120_000;\n\n/** Never chunk below this, or a small window would shred a transcript into noise. */\nconst MIN_CHUNK_CHARS = 40_000;\n\n/**\n * How much rendered transcript to send per call, given the reading model.\n *\n * Only a fraction of the window is used: the instructions, the response, and\n * tokenizer variance all have to fit alongside, and overshooting costs a\n * context-overflow error rather than a slightly worse answer.\n */\nexport function chunkCharsForModel(model: Pick<Model<any>, \"contextWindow\">): number {\n\tconst window = model.contextWindow;\n\tif (!Number.isFinite(window) || window <= 0) return FALLBACK_CHUNK_CHARS;\n\tconst budgetTokens = window * CHUNK_CONTEXT_FRACTION - MAX_RESPONSE_TOKENS;\n\treturn Math.max(MIN_CHUNK_CHARS, Math.floor(budgetTokens * CHARS_PER_TOKEN));\n}\n\n/** Tool output kept per call. Errors carry the signal; success output is mostly noise. */\nconst TOOL_OUTPUT_CHARS = 600;\nconst TOOL_ERROR_CHARS = 1_500;\n\n/** Response ceiling per chunk. A chunk yielding more than this is noise, not signal. */\nconst MAX_RESPONSE_TOKENS = 4_000;\n\n/** Candidates accepted from a single chunk, as a guard against a runaway response. */\nconst MAX_CANDIDATES_PER_CHUNK = 40;\n\n/**\n * Prefix on the message `/learn` injects. Its own digest is persisted like any\n * other user turn, so without this the next run would mine its own output and\n * every proposal would compound its own count.\n */\nexport const LEARN_DIGEST_MARKER = \"[learn-digest]\";\n\nfunction textOf(content: unknown): string {\n\tif (typeof content === \"string\") return content;\n\tif (!Array.isArray(content)) return \"\";\n\treturn content\n\t\t.map((block) =>\n\t\t\tblock && typeof block === \"object\" && (block as TextContent).type === \"text\"\n\t\t\t\t? ((block as TextContent).text ?? \"\")\n\t\t\t\t: \"\",\n\t\t)\n\t\t.join(\"\\n\")\n\t\t.trim();\n}\n\nfunction isToolCall(block: unknown): block is ToolCall {\n\treturn !!block && typeof block === \"object\" && (block as ToolCall).type === \"toolCall\";\n}\n\n/** Compact one tool call's arguments — enough to recognise it, not enough to flood the window. */\nfunction renderArgs(args: Record<string, unknown> | undefined): string {\n\tif (!args) return \"\";\n\tconst parts: string[] = [];\n\tfor (const [key, value] of Object.entries(args)) {\n\t\tif (typeof value === \"string\") {\n\t\t\tparts.push(`${key}=${value.length > 200 ? `${value.slice(0, 200)}…` : value}`);\n\t\t} else if (typeof value === \"number\" || typeof value === \"boolean\") {\n\t\t\tparts.push(`${key}=${value}`);\n\t\t}\n\t\t// Objects and arrays are structural detail the miner does not need.\n\t}\n\treturn parts.join(\" \");\n}\n\n/**\n * Render a session as plain text for the model.\n *\n * User turns go in whole and unfiltered — that is the entire point of this\n * rewrite, and any truncation here would quietly reintroduce the recall problem\n * the regex gate had. Assistant prose is dropped: it is the bulk of a\n * transcript and almost none of it is evidence about what the *user* wants.\n * Tool calls are kept because a repeated sequence is a workflow and a\n * failure-then-pass is a fix, and both are things worth proposing.\n */\nexport function renderTranscript(session: MinableSession): string {\n\tconst lines: string[] = [];\n\n\tfor (const entry of session.entries) {\n\t\tconst message = entry.type === \"message\" ? entry.message : undefined;\n\t\tif (!message) continue;\n\n\t\tif (message.role === \"user\") {\n\t\t\tconst text = textOf(message.content);\n\t\t\t// Skip the command's own past output, or proposals compound their counts.\n\t\t\tif (!text || text.startsWith(LEARN_DIGEST_MARKER)) continue;\n\t\t\tlines.push(`USER: ${text}`);\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (message.role === \"assistant\") {\n\t\t\tfor (const block of (message.content ?? []) as unknown[]) {\n\t\t\t\tif (!isToolCall(block)) continue;\n\t\t\t\tlines.push(`TOOL: ${block.name}(${renderArgs(block.arguments as Record<string, unknown>)})`);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (message.role === \"toolResult\") {\n\t\t\tconst output = textOf(message.content);\n\t\t\tif (!output) continue;\n\t\t\tconst limit = message.isError ? TOOL_ERROR_CHARS : TOOL_OUTPUT_CHARS;\n\t\t\tconst label = message.isError ? \"ERROR\" : \"RESULT\";\n\t\t\tlines.push(`${label}: ${output.length > limit ? `${output.slice(0, limit)}…` : output}`);\n\t\t}\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Split rendered text on line boundaries, so a chunk never cuts a user turn in\n * half. A single turn longer than the budget gets its own oversized chunk\n * rather than being split — losing the second half of a long directive is\n * exactly the failure this rewrite exists to remove.\n */\nexport function chunkTranscript(text: string, chunkChars = FALLBACK_CHUNK_CHARS): string[] {\n\tif (text.length <= chunkChars) return text.length > 0 ? [text] : [];\n\n\tconst chunks: string[] = [];\n\tlet current: string[] = [];\n\tlet size = 0;\n\tfor (const line of text.split(\"\\n\")) {\n\t\tif (size > 0 && size + line.length + 1 > chunkChars) {\n\t\t\tchunks.push(current.join(\"\\n\"));\n\t\t\tcurrent = [];\n\t\t\tsize = 0;\n\t\t}\n\t\tcurrent.push(line);\n\t\tsize += line.length + 1;\n\t}\n\tif (current.length > 0) chunks.push(current.join(\"\\n\"));\n\treturn chunks;\n}\n\nconst MINER_SYSTEM_PROMPT = `You read one coding-session transcript and report durable signals in it.\n\nYou are the recall stage of a two-stage pipeline. A later stage counts how often each signal recurs ACROSS sessions and decides what is worth writing down. Your job is to notice and name, not to judge importance and not to count — you are seeing one session and cannot know what repeats.\n\nReport three kinds of thing.\n\n**directive** — the user stating a preference, correction, constraint, or fact about how they want work done. Include these regardless of phrasing. All of these are directives:\n- imperative: \"always run the tests before pushing\"\n- corrective: \"no, that's not how our error handling works\"\n- declarative: \"we're on bun now\", \"the API returns snake_case\"\n- preference stated once, in passing: \"I'd rather see this as a table\"\nDo NOT report task requests (\"add a button to the header\", \"fix the login bug\"). A task is what to do now; a directive is how things should be done in general. When a message contains both, report only the directive part.\n\n**fix** — a command that failed and later succeeded, where something in between was the cause. Report the failing command, a short error excerpt, and what changed in between.\n\n**workflow** — a sequence of three or more tool calls that recurs within this session, or that clearly represents a routine procedure (scaffold a file, then register it, then test it).\n\nFor every item, produce a \"label\": a short kebab-case slug naming what was MEANT, not what was said. The label is how occurrences are grouped across sessions, so two different phrasings of the same underlying point MUST get the same label.\n- \"we're on bun now\" → use-bun-not-npm\n- \"stop using npm install\" → use-bun-not-npm\n- \"pnpm isn't what we use here\" → use-bun-not-npm\nKeep labels general enough to collide when they mean the same thing, specific enough not to collide when they do not. Prefer 2-5 words.\n\nOutput STRICT JSON, no markdown fence, no prose:\n{\"candidates\":[{\"kind\":\"directive\",\"label\":\"use-bun-not-npm\",\"text\":\"<verbatim quote>\",\"rationale\":\"<one clause on why it is durable>\"}]}\n\nFor fix items add: \"command\", \"errorExcerpt\", \"interveningCommands\" (array), \"editedFiles\" (array).\nFor workflow items add: \"steps\" (array of tool names in order).\n\nReport nothing rather than padding. An empty list is a correct answer for a session that taught nothing: {\"candidates\":[]}`;\n\n/**\n * Pull the JSON object out of a model response.\n *\n * Models fence JSON even when told not to, and occasionally prepend a sentence.\n * Scanning for the outermost braces is more forgiving than trusting the format\n * and cheaper than a repair pass — and a chunk whose response cannot be parsed\n * is skipped, never fatal, because one bad chunk should not lose a whole run.\n */\nexport function parseCandidates(response: string): MinedCandidate[] {\n\tconst start = response.indexOf(\"{\");\n\tconst end = response.lastIndexOf(\"}\");\n\tif (start < 0 || end <= start) return [];\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(response.slice(start, end + 1));\n\t} catch {\n\t\treturn [];\n\t}\n\n\tconst raw = (parsed as { candidates?: unknown })?.candidates;\n\tif (!Array.isArray(raw)) return [];\n\n\tconst out: MinedCandidate[] = [];\n\tfor (const item of raw.slice(0, MAX_CANDIDATES_PER_CHUNK)) {\n\t\tif (!item || typeof item !== \"object\") continue;\n\t\tconst candidate = item as Record<string, unknown>;\n\t\tconst kind = candidate.kind;\n\t\tif (kind !== \"directive\" && kind !== \"fix\" && kind !== \"workflow\") continue;\n\n\t\tconst label = typeof candidate.label === \"string\" ? candidate.label.trim().toLowerCase() : \"\";\n\t\tconst text = typeof candidate.text === \"string\" ? candidate.text.trim() : \"\";\n\t\t// A candidate with no label cannot be grouped, and one with no text cannot\n\t\t// be quoted back — either way there is nothing to show the reader.\n\t\tif (!label || !text) continue;\n\n\t\tconst strings = (value: unknown): string[] | undefined =>\n\t\t\tArray.isArray(value) ? value.filter((v): v is string => typeof v === \"string\").slice(0, 12) : undefined;\n\n\t\tout.push({\n\t\t\tkind,\n\t\t\tlabel,\n\t\t\ttext,\n\t\t\trationale: typeof candidate.rationale === \"string\" ? candidate.rationale.trim() : undefined,\n\t\t\tcommand: typeof candidate.command === \"string\" ? candidate.command : undefined,\n\t\t\terrorExcerpt: typeof candidate.errorExcerpt === \"string\" ? candidate.errorExcerpt.slice(0, 400) : undefined,\n\t\t\tinterveningCommands: strings(candidate.interveningCommands),\n\t\t\teditedFiles: strings(candidate.editedFiles),\n\t\t\tsteps: strings(candidate.steps),\n\t\t});\n\t}\n\treturn out;\n}\n\nexport interface MinerDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n}\n\n/**\n * Build the real miner: one model call per chunk of one session.\n *\n * Chunks are mined sequentially rather than in parallel. A cold-cache run is\n * already the expensive path, and firing every chunk of every session at once\n * is how you trip a provider rate limit on exactly the run that has the most to\n * do.\n */\nexport function createLlmMiner(deps: MinerDeps): Miner {\n\tconst chunkChars = chunkCharsForModel(deps.model);\n\treturn async (session, signal) => {\n\t\tconst chunks = chunkTranscript(renderTranscript(session), chunkChars);\n\t\tconst candidates: MinedCandidate[] = [];\n\n\t\tfor (const chunk of chunks) {\n\t\t\tif (signal?.aborted) break;\n\n\t\t\tconst response = await completeSimple(\n\t\t\t\tdeps.model,\n\t\t\t\t{\n\t\t\t\t\tsystemPrompt: MINER_SYSTEM_PROMPT,\n\t\t\t\t\tmessages: [{ role: \"user\", content: [{ type: \"text\", text: chunk }], timestamp: Date.now() }],\n\t\t\t\t},\n\t\t\t\t{ maxTokens: MAX_RESPONSE_TOKENS, signal, apiKey: deps.apiKey, headers: deps.headers },\n\t\t\t);\n\n\t\t\tif (response.stopReason === \"error\") {\n\t\t\t\tthrow new Error(response.errorMessage || \"miner call failed\");\n\t\t\t}\n\n\t\t\tconst text = response.content\n\t\t\t\t.filter((c): c is { type: \"text\"; text: string } => c.type === \"text\")\n\t\t\t\t.map((c) => c.text)\n\t\t\t\t.join(\"\\n\");\n\t\t\tcandidates.push(...parseCandidates(text));\n\t\t}\n\n\t\treturn candidates;\n\t};\n}\n"]}

package/dist/core/learn/reduce.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The reduce half of `/learn`: turn per-session observations into counts.
+ *
+ * The split with `mine.ts` is the whole design. Deciding that "we're on bun
+ * now" and "stop using npm" mean the same thing is semantics, and the model is
+ * better at it than any normalizer — so the model does it, by emitting a shared
+ * `label`. Deciding that the shared label occurred nine times across five
+ * sessions is arithmetic, and arithmetic stays here, because a model asked to
+ * count over a long context will be approximately right, and an approximately
+ * right number is worse than none when the number is the thing the reader acts
+ * on.
+ *
+ * Nothing in this file filters on content. The only gate is the repeat
+ * threshold, which is a dial the user sets and the digest reports, not a
+ * whitelist they cannot see.
+ */
+import type { MinedCandidate } from "./mine.js";
+/** Where a repeated directive already lives, if anywhere. */
+export type DirectiveStatus = "new" | "restated" | "has-skill";
+/** Fields every proposable item shares, so suppression can be applied uniformly. */
+export interface Proposable {
+    /** Stable identity across runs — what the state file remembers. */
+    key: string;
+    /** Newest occurrence in the window, ISO. */
+    lastSeen: string;
+}
+export interface DirectiveCluster extends Proposable {
+    /** The model's canonical name for what was meant. The clustering key. */
+    label: string;
+    /** Representative verbatim quote, the longest seen in the cluster. */
+    text: string;
+    /** Why it is durable, in the model's words. */
+    rationale?: string;
+    /** Total times said. */
+    count: number;
+    /** Distinct sessions it was said in — the stronger of the two counts. */
+    sessions: number;
+    status: DirectiveStatus;
+    /** The existing rule line matched, when status is `restated`. */
+    existingRule?: string;
+    /** The skill that already covers this, when status is `has-skill`. */
+    existingSkill?: string;
+    /**
+     * Shown before and still not written down anywhere — neither as a rule nor as
+     * a skill — so the reader saw this proposal and passed on it.
+     */
+    previouslyDeclined: boolean;
+}
+export interface FixCandidate extends Proposable {
+    label: string;
+    /** The failing command. */
+    command: string;
+    /** Short excerpt of the real error text. */
+    errorExcerpt: string;
+    /** Commands run between the failure and the pass. */
+    interveningCommands: string[];
+    /** Files edited between the failure and the pass. */
+    editedFiles: string[];
+    count: number;
+    sessions: number;
+}
+export interface WorkflowCandidate extends Proposable {
+    label: string;
+    /** Tool names in order. */
+    steps: string[];
+    count: number;
+    sessions: number;
+}
+/** One session's mining output, tagged with the identity the counts need. */
+export interface MinedSession {
+    sessionId: string;
+    timestamp: string;
+    candidates: MinedCandidate[];
+}
+export declare function reduceDirectives(sessions: MinedSession[], minRepeats: number): DirectiveCluster[];
+export declare function reduceFixes(sessions: MinedSession[], minRepeats: number): FixCandidate[];
+export declare function reduceWorkflows(sessions: MinedSession[], minRepeats: number): WorkflowCandidate[];
+//# sourceMappingURL=reduce.d.ts.map

package/dist/core/learn/reduce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reduce.d.ts","sourceRoot":"","sources":["../../../src/core/learn/reduce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,CAAC;AAE/D,oFAAoF;AACpF,MAAM,WAAW,UAAU;IAC1B,qEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IACnD,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,2EAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC7B;AAuED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAiBjG;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,EAAE,CAexF;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAYjG","sourcesContent":["/**\n * The reduce half of `/learn`: turn per-session observations into counts.\n *\n * The split with `mine.ts` is the whole design. Deciding that \"we're on bun\n * now\" and \"stop using npm\" mean the same thing is semantics, and the model is\n * better at it than any normalizer — so the model does it, by emitting a shared\n * `label`. Deciding that the shared label occurred nine times across five\n * sessions is arithmetic, and arithmetic stays here, because a model asked to\n * count over a long context will be approximately right, and an approximately\n * right number is worse than none when the number is the thing the reader acts\n * on.\n *\n * Nothing in this file filters on content. The only gate is the repeat\n * threshold, which is a dial the user sets and the digest reports, not a\n * whitelist they cannot see.\n */\n\nimport type { MinedCandidate } from \"./mine.js\";\n\n/** Where a repeated directive already lives, if anywhere. */\nexport type DirectiveStatus = \"new\" | \"restated\" | \"has-skill\";\n\n/** Fields every proposable item shares, so suppression can be applied uniformly. */\nexport interface Proposable {\n\t/** Stable identity across runs — what the state file remembers. */\n\tkey: string;\n\t/** Newest occurrence in the window, ISO. */\n\tlastSeen: string;\n}\n\nexport interface DirectiveCluster extends Proposable {\n\t/** The model's canonical name for what was meant. The clustering key. */\n\tlabel: string;\n\t/** Representative verbatim quote, the longest seen in the cluster. */\n\ttext: string;\n\t/** Why it is durable, in the model's words. */\n\trationale?: string;\n\t/** Total times said. */\n\tcount: number;\n\t/** Distinct sessions it was said in — the stronger of the two counts. */\n\tsessions: number;\n\tstatus: DirectiveStatus;\n\t/** The existing rule line matched, when status is `restated`. */\n\texistingRule?: string;\n\t/** The skill that already covers this, when status is `has-skill`. */\n\texistingSkill?: string;\n\t/**\n\t * Shown before and still not written down anywhere — neither as a rule nor as\n\t * a skill — so the reader saw this proposal and passed on it.\n\t */\n\tpreviouslyDeclined: boolean;\n}\n\nexport interface FixCandidate extends Proposable {\n\tlabel: string;\n\t/** The failing command. */\n\tcommand: string;\n\t/** Short excerpt of the real error text. */\n\terrorExcerpt: string;\n\t/** Commands run between the failure and the pass. */\n\tinterveningCommands: string[];\n\t/** Files edited between the failure and the pass. */\n\teditedFiles: string[];\n\tcount: number;\n\tsessions: number;\n}\n\nexport interface WorkflowCandidate extends Proposable {\n\tlabel: string;\n\t/** Tool names in order. */\n\tsteps: string[];\n\tcount: number;\n\tsessions: number;\n}\n\n/** One session's mining output, tagged with the identity the counts need. */\nexport interface MinedSession {\n\tsessionId: string;\n\ttimestamp: string;\n\tcandidates: MinedCandidate[];\n}\n\ninterface Acc {\n\tlabel: string;\n\ttext: string;\n\trationale?: string;\n\tcount: number;\n\tsessions: Set<string>;\n\tlastSeen: string;\n\tsamples: MinedCandidate[];\n}\n\n/**\n * Group every candidate of one kind by its label.\n *\n * `lastSeen` takes the session timestamp rather than anything the model\n * reports: the model is reading a transcript and has no reliable clock, and\n * `lastSeen` drives suppression, where a wrong value silently hides a live\n * signal or resurfaces a dead one.\n */\nfunction groupByLabel(sessions: MinedSession[], kind: MinedCandidate[\"kind\"]): Acc[] {\n\tconst acc = new Map<string, Acc>();\n\n\tfor (const session of sessions) {\n\t\tfor (const candidate of session.candidates) {\n\t\t\tif (candidate.kind !== kind) continue;\n\t\t\tconst existing = acc.get(candidate.label);\n\t\t\tif (existing) {\n\t\t\t\texisting.count++;\n\t\t\t\texisting.sessions.add(session.sessionId);\n\t\t\t\tif (session.timestamp > existing.lastSeen) existing.lastSeen = session.timestamp;\n\t\t\t\t// Keep the fullest quote: a longer one carries more of the reasoning.\n\t\t\t\tif (candidate.text.length > existing.text.length) existing.text = candidate.text;\n\t\t\t\texisting.rationale ??= candidate.rationale;\n\t\t\t\texisting.samples.push(candidate);\n\t\t\t} else {\n\t\t\t\tacc.set(candidate.label, {\n\t\t\t\t\tlabel: candidate.label,\n\t\t\t\t\ttext: candidate.text,\n\t\t\t\t\trationale: candidate.rationale,\n\t\t\t\t\tcount: 1,\n\t\t\t\t\tsessions: new Set([session.sessionId]),\n\t\t\t\t\tlastSeen: session.timestamp,\n\t\t\t\t\tsamples: [candidate],\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\treturn [...acc.values()];\n}\n\n/** Distinct sessions first, then raw count: five sessions beats nine times in one. */\nfunction byEvidence(a: { sessions: number; count: number; label: string }, b: typeof a): number {\n\treturn b.sessions - a.sessions || b.count - a.count || a.label.localeCompare(b.label);\n}\n\n/** Merge repeated string fields across a cluster's samples, preserving order and dropping dupes. */\nfunction mergeStrings(samples: MinedCandidate[], pick: (c: MinedCandidate) => string[] | undefined): string[] {\n\tconst out: string[] = [];\n\tconst seen = new Set<string>();\n\tfor (const sample of samples) {\n\t\tfor (const value of pick(sample) ?? []) {\n\t\t\tif (seen.has(value)) continue;\n\t\t\tseen.add(value);\n\t\t\tout.push(value);\n\t\t}\n\t}\n\treturn out.slice(0, 12);\n}\n\nexport function reduceDirectives(sessions: MinedSession[], minRepeats: number): DirectiveCluster[] {\n\treturn groupByLabel(sessions, \"directive\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `directive:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\ttext: entry.text,\n\t\t\trationale: entry.rationale,\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t\t// Coverage is decided later, by a model that can tell a paraphrase from a\n\t\t\t// coincidence. Everything starts `new` and is corrected in place.\n\t\t\tstatus: \"new\" as DirectiveStatus,\n\t\t\tpreviouslyDeclined: false,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n\nexport function reduceFixes(sessions: MinedSession[], minRepeats: number): FixCandidate[] {\n\treturn groupByLabel(sessions, \"fix\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `fix:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\tcommand: entry.samples.find((s) => s.command)?.command ?? entry.text,\n\t\t\terrorExcerpt: entry.samples.find((s) => s.errorExcerpt)?.errorExcerpt ?? \"\",\n\t\t\tinterveningCommands: mergeStrings(entry.samples, (s) => s.interveningCommands),\n\t\t\teditedFiles: mergeStrings(entry.samples, (s) => s.editedFiles),\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n\nexport function reduceWorkflows(sessions: MinedSession[], minRepeats: number): WorkflowCandidate[] {\n\treturn groupByLabel(sessions, \"workflow\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `workflow:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\tsteps: entry.samples.find((s) => s.steps && s.steps.length > 0)?.steps ?? [],\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n"]}

package/dist/core/learn/reduce.js

@@ -0,0 +1,123 @@
+/**
+ * The reduce half of `/learn`: turn per-session observations into counts.
+ *
+ * The split with `mine.ts` is the whole design. Deciding that "we're on bun
+ * now" and "stop using npm" mean the same thing is semantics, and the model is
+ * better at it than any normalizer — so the model does it, by emitting a shared
+ * `label`. Deciding that the shared label occurred nine times across five
+ * sessions is arithmetic, and arithmetic stays here, because a model asked to
+ * count over a long context will be approximately right, and an approximately
+ * right number is worse than none when the number is the thing the reader acts
+ * on.
+ *
+ * Nothing in this file filters on content. The only gate is the repeat
+ * threshold, which is a dial the user sets and the digest reports, not a
+ * whitelist they cannot see.
+ */
+/**
+ * Group every candidate of one kind by its label.
+ *
+ * `lastSeen` takes the session timestamp rather than anything the model
+ * reports: the model is reading a transcript and has no reliable clock, and
+ * `lastSeen` drives suppression, where a wrong value silently hides a live
+ * signal or resurfaces a dead one.
+ */
+function groupByLabel(sessions, kind) {
+    const acc = new Map();
+    for (const session of sessions) {
+        for (const candidate of session.candidates) {
+            if (candidate.kind !== kind)
+                continue;
+            const existing = acc.get(candidate.label);
+            if (existing) {
+                existing.count++;
+                existing.sessions.add(session.sessionId);
+                if (session.timestamp > existing.lastSeen)
+                    existing.lastSeen = session.timestamp;
+                // Keep the fullest quote: a longer one carries more of the reasoning.
+                if (candidate.text.length > existing.text.length)
+                    existing.text = candidate.text;
+                existing.rationale ??= candidate.rationale;
+                existing.samples.push(candidate);
+            }
+            else {
+                acc.set(candidate.label, {
+                    label: candidate.label,
+                    text: candidate.text,
+                    rationale: candidate.rationale,
+                    count: 1,
+                    sessions: new Set([session.sessionId]),
+                    lastSeen: session.timestamp,
+                    samples: [candidate],
+                });
+            }
+        }
+    }
+    return [...acc.values()];
+}
+/** Distinct sessions first, then raw count: five sessions beats nine times in one. */
+function byEvidence(a, b) {
+    return b.sessions - a.sessions || b.count - a.count || a.label.localeCompare(b.label);
+}
+/** Merge repeated string fields across a cluster's samples, preserving order and dropping dupes. */
+function mergeStrings(samples, pick) {
+    const out = [];
+    const seen = new Set();
+    for (const sample of samples) {
+        for (const value of pick(sample) ?? []) {
+            if (seen.has(value))
+                continue;
+            seen.add(value);
+            out.push(value);
+        }
+    }
+    return out.slice(0, 12);
+}
+export function reduceDirectives(sessions, minRepeats) {
+    return groupByLabel(sessions, "directive")
+        .filter((entry) => entry.count >= minRepeats)
+        .map((entry) => ({
+        key: `directive:${entry.label}`,
+        label: entry.label,
+        text: entry.text,
+        rationale: entry.rationale,
+        count: entry.count,
+        sessions: entry.sessions.size,
+        lastSeen: entry.lastSeen,
+        // Coverage is decided later, by a model that can tell a paraphrase from a
+        // coincidence. Everything starts `new` and is corrected in place.
+        status: "new",
+        previouslyDeclined: false,
+    }))
+        .sort(byEvidence);
+}
+export function reduceFixes(sessions, minRepeats) {
+    return groupByLabel(sessions, "fix")
+        .filter((entry) => entry.count >= minRepeats)
+        .map((entry) => ({
+        key: `fix:${entry.label}`,
+        label: entry.label,
+        command: entry.samples.find((s) => s.command)?.command ?? entry.text,
+        errorExcerpt: entry.samples.find((s) => s.errorExcerpt)?.errorExcerpt ?? "",
+        interveningCommands: mergeStrings(entry.samples, (s) => s.interveningCommands),
+        editedFiles: mergeStrings(entry.samples, (s) => s.editedFiles),
+        count: entry.count,
+        sessions: entry.sessions.size,
+        lastSeen: entry.lastSeen,
+    }))
+        .sort(byEvidence);
+}
+export function reduceWorkflows(sessions, minRepeats) {
+    return groupByLabel(sessions, "workflow")
+        .filter((entry) => entry.count >= minRepeats)
+        .map((entry) => ({
+        key: `workflow:${entry.label}`,
+        label: entry.label,
+        steps: entry.samples.find((s) => s.steps && s.steps.length > 0)?.steps ?? [],
+        count: entry.count,
+        sessions: entry.sessions.size,
+        lastSeen: entry.lastSeen,
+    }))
+        .sort(byEvidence);
+}
+//# sourceMappingURL=reduce.js.map

package/dist/core/learn/reduce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reduce.js","sourceRoot":"","sources":["../../../src/core/learn/reduce.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The reduce half of `/learn`: turn per-session observations into counts.\n *\n * The split with `mine.ts` is the whole design. Deciding that \"we're on bun\n * now\" and \"stop using npm\" mean the same thing is semantics, and the model is\n * better at it than any normalizer — so the model does it, by emitting a shared\n * `label`. Deciding that the shared label occurred nine times across five\n * sessions is arithmetic, and arithmetic stays here, because a model asked to\n * count over a long context will be approximately right, and an approximately\n * right number is worse than none when the number is the thing the reader acts\n * on.\n *\n * Nothing in this file filters on content. The only gate is the repeat\n * threshold, which is a dial the user sets and the digest reports, not a\n * whitelist they cannot see.\n */\n\nimport type { MinedCandidate } from \"./mine.js\";\n\n/** Where a repeated directive already lives, if anywhere. */\nexport type DirectiveStatus = \"new\" | \"restated\" | \"has-skill\";\n\n/** Fields every proposable item shares, so suppression can be applied uniformly. */\nexport interface Proposable {\n\t/** Stable identity across runs — what the state file remembers. */\n\tkey: string;\n\t/** Newest occurrence in the window, ISO. */\n\tlastSeen: string;\n}\n\nexport interface DirectiveCluster extends Proposable {\n\t/** The model's canonical name for what was meant. The clustering key. */\n\tlabel: string;\n\t/** Representative verbatim quote, the longest seen in the cluster. */\n\ttext: string;\n\t/** Why it is durable, in the model's words. */\n\trationale?: string;\n\t/** Total times said. */\n\tcount: number;\n\t/** Distinct sessions it was said in — the stronger of the two counts. */\n\tsessions: number;\n\tstatus: DirectiveStatus;\n\t/** The existing rule line matched, when status is `restated`. */\n\texistingRule?: string;\n\t/** The skill that already covers this, when status is `has-skill`. */\n\texistingSkill?: string;\n\t/**\n\t * Shown before and still not written down anywhere — neither as a rule nor as\n\t * a skill — so the reader saw this proposal and passed on it.\n\t */\n\tpreviouslyDeclined: boolean;\n}\n\nexport interface FixCandidate extends Proposable {\n\tlabel: string;\n\t/** The failing command. */\n\tcommand: string;\n\t/** Short excerpt of the real error text. */\n\terrorExcerpt: string;\n\t/** Commands run between the failure and the pass. */\n\tinterveningCommands: string[];\n\t/** Files edited between the failure and the pass. */\n\teditedFiles: string[];\n\tcount: number;\n\tsessions: number;\n}\n\nexport interface WorkflowCandidate extends Proposable {\n\tlabel: string;\n\t/** Tool names in order. */\n\tsteps: string[];\n\tcount: number;\n\tsessions: number;\n}\n\n/** One session's mining output, tagged with the identity the counts need. */\nexport interface MinedSession {\n\tsessionId: string;\n\ttimestamp: string;\n\tcandidates: MinedCandidate[];\n}\n\ninterface Acc {\n\tlabel: string;\n\ttext: string;\n\trationale?: string;\n\tcount: number;\n\tsessions: Set<string>;\n\tlastSeen: string;\n\tsamples: MinedCandidate[];\n}\n\n/**\n * Group every candidate of one kind by its label.\n *\n * `lastSeen` takes the session timestamp rather than anything the model\n * reports: the model is reading a transcript and has no reliable clock, and\n * `lastSeen` drives suppression, where a wrong value silently hides a live\n * signal or resurfaces a dead one.\n */\nfunction groupByLabel(sessions: MinedSession[], kind: MinedCandidate[\"kind\"]): Acc[] {\n\tconst acc = new Map<string, Acc>();\n\n\tfor (const session of sessions) {\n\t\tfor (const candidate of session.candidates) {\n\t\t\tif (candidate.kind !== kind) continue;\n\t\t\tconst existing = acc.get(candidate.label);\n\t\t\tif (existing) {\n\t\t\t\texisting.count++;\n\t\t\t\texisting.sessions.add(session.sessionId);\n\t\t\t\tif (session.timestamp > existing.lastSeen) existing.lastSeen = session.timestamp;\n\t\t\t\t// Keep the fullest quote: a longer one carries more of the reasoning.\n\t\t\t\tif (candidate.text.length > existing.text.length) existing.text = candidate.text;\n\t\t\t\texisting.rationale ??= candidate.rationale;\n\t\t\t\texisting.samples.push(candidate);\n\t\t\t} else {\n\t\t\t\tacc.set(candidate.label, {\n\t\t\t\t\tlabel: candidate.label,\n\t\t\t\t\ttext: candidate.text,\n\t\t\t\t\trationale: candidate.rationale,\n\t\t\t\t\tcount: 1,\n\t\t\t\t\tsessions: new Set([session.sessionId]),\n\t\t\t\t\tlastSeen: session.timestamp,\n\t\t\t\t\tsamples: [candidate],\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\treturn [...acc.values()];\n}\n\n/** Distinct sessions first, then raw count: five sessions beats nine times in one. */\nfunction byEvidence(a: { sessions: number; count: number; label: string }, b: typeof a): number {\n\treturn b.sessions - a.sessions || b.count - a.count || a.label.localeCompare(b.label);\n}\n\n/** Merge repeated string fields across a cluster's samples, preserving order and dropping dupes. */\nfunction mergeStrings(samples: MinedCandidate[], pick: (c: MinedCandidate) => string[] | undefined): string[] {\n\tconst out: string[] = [];\n\tconst seen = new Set<string>();\n\tfor (const sample of samples) {\n\t\tfor (const value of pick(sample) ?? []) {\n\t\t\tif (seen.has(value)) continue;\n\t\t\tseen.add(value);\n\t\t\tout.push(value);\n\t\t}\n\t}\n\treturn out.slice(0, 12);\n}\n\nexport function reduceDirectives(sessions: MinedSession[], minRepeats: number): DirectiveCluster[] {\n\treturn groupByLabel(sessions, \"directive\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `directive:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\ttext: entry.text,\n\t\t\trationale: entry.rationale,\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t\t// Coverage is decided later, by a model that can tell a paraphrase from a\n\t\t\t// coincidence. Everything starts `new` and is corrected in place.\n\t\t\tstatus: \"new\" as DirectiveStatus,\n\t\t\tpreviouslyDeclined: false,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n\nexport function reduceFixes(sessions: MinedSession[], minRepeats: number): FixCandidate[] {\n\treturn groupByLabel(sessions, \"fix\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `fix:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\tcommand: entry.samples.find((s) => s.command)?.command ?? entry.text,\n\t\t\terrorExcerpt: entry.samples.find((s) => s.errorExcerpt)?.errorExcerpt ?? \"\",\n\t\t\tinterveningCommands: mergeStrings(entry.samples, (s) => s.interveningCommands),\n\t\t\teditedFiles: mergeStrings(entry.samples, (s) => s.editedFiles),\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n\nexport function reduceWorkflows(sessions: MinedSession[], minRepeats: number): WorkflowCandidate[] {\n\treturn groupByLabel(sessions, \"workflow\")\n\t\t.filter((entry) => entry.count >= minRepeats)\n\t\t.map((entry) => ({\n\t\t\tkey: `workflow:${entry.label}`,\n\t\t\tlabel: entry.label,\n\t\t\tsteps: entry.samples.find((s) => s.steps && s.steps.length > 0)?.steps ?? [],\n\t\t\tcount: entry.count,\n\t\t\tsessions: entry.sessions.size,\n\t\t\tlastSeen: entry.lastSeen,\n\t\t}))\n\t\t.sort(byEvidence);\n}\n"]}

package/dist/core/learn/state.d.ts

@@ -31,6 +31,13 @@ export interface SurfacedItem {
      * told from a declined one, without asking.
      */
     coveredWhenSurfaced: boolean;
+    /**
+     * Representative wording, kept so `/learn stats` can ask about coverage using
+     * what was actually said. The key alone is a slug, and judging "is this
+     * written down?" from a slug is a much weaker question than judging it from
+     * the sentence the slug stands for.
+     */
+    text?: string;
 }
 export interface LearnState {
     version: number;
@@ -114,5 +121,6 @@ export declare function recordSurfaced(state: LearnState, items: Array<{
     key: string;
     lastSeen: string;
     covered: boolean;
+    text?: string;
 }>, now?: Date): LearnState;
 //# sourceMappingURL=state.d.ts.map