@kolisachint/hoocode-agent 0.5.18 → 0.5.19

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

@@ -12,30 +12,33 @@
  * 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.
+ * What the model does *not* do here is name or count. It used to emit a label
+ * per occurrence — its own canonical name for what was meant — and the reduce
+ * step grouped on exact label equality. That cannot work from inside one
+ * session: the model is asked to hit a shared vocabulary it has never seen, and
+ * on a real corpus it agreed with itself 3 times out of 188. Naming now happens
+ * once, globally, in `cluster.ts`, where every candidate is visible at the same
+ * time. Counting stays in `reduce.ts`, where it always belonged.
+ *
+ * Leaving labels out also makes the cache model-independent. A cached candidate
+ * used to carry a label frozen at mining time, so changing the `fast` tier
+ * forked the vocabulary permanently: old sessions and new ones named the same
+ * thing differently, and neither side reached the repeat threshold.
  */
 import type { AgentMessage } from "@kolisachint/hoocode-agent-core";
 import type { Model } from "@kolisachint/hoocode-ai";
 /** What kind of thing the model noticed. */
-export type CandidateKind = "directive" | "fix" | "workflow";
+export type CandidateKind = "directive" | "fix" | "request";
 /**
  * One occurrence, as reported by the model reading a single session.
  *
- * `label` is the load-bearing field. It is the model's canonical name for what
- * was meant — "use-bun-not-npm" for all of "we're on bun now", "stop using
- * npm", and "pnpm isn't what we use" — and it is what the reduce step groups
- * on. Getting a stable label out of the model is what buys semantic clustering
- * that `normalizeDirective`'s lowercase-and-strip-punctuation could never do.
+ * Deliberately unnamed. What was *meant* is only decidable against everything
+ * else that was said, and this stage sees one session, so it reports what it
+ * saw and leaves grouping to `cluster.ts`. This is also the shape that goes in
+ * the cache, which is why nothing model-specific may live on it.
  */
 export interface MinedCandidate {
     kind: CandidateKind;
-    /** Canonical slug for what was meant. The clustering key. */
-    label: string;
     /** Verbatim text from the transcript, so the digest can quote rather than paraphrase. */
     text: string;
     /** Why this is durable, in the model's words. Shown when a proposal is borderline. */
@@ -48,8 +51,11 @@ export interface MinedCandidate {
     interveningCommands?: string[];
     /** Files changed as part of the fix. */
     editedFiles?: string[];
-    /** Tool sequence, for `workflow` candidates. */
-    steps?: string[];
+}
+/** A candidate once the global naming pass has decided what to call it. */
+export interface LabelledCandidate extends MinedCandidate {
+    /** Canonical slug for what was meant. The clustering key. */
+    label: string;
 }
 /** A session reduced to what the miner needs: identity, time, and rendered text. */
 export interface MinableSession {
@@ -79,17 +85,60 @@ export declare function chunkCharsForModel(model: Pick<Model<any>, "contextWindo
  * every proposal would compound its own count.
  */
 export declare const LEARN_DIGEST_MARKER = "[learn-digest]";
+/**
+ * Literal runs from slash-command bodies, used to recognise a replayed expansion.
+ *
+ * A `user`-type slash command is persisted as an ordinary user message holding
+ * the whole template body, with nothing to mark it as machinery. Read back off
+ * disk it is indistinguishable from something the user typed — and it is the
+ * most repeated text in a real corpus, because running `/pr` thirty times
+ * writes the same two thousand characters thirty times. Mining it produces
+ * directives the user never stated, at counts that look exactly like organic
+ * repetition.
+ *
+ * Detection is retroactive on purpose. A provenance flag written at turn time
+ * would be exact, but it would only help sessions recorded after it shipped,
+ * leaving the existing corpus contaminated for months. Matching against the
+ * command bodies still on disk fixes the history that already exists. The gap
+ * is a template that has since been deleted; that case wants the flag, and is
+ * the reason to add one later.
+ */
+export declare function replayFingerprints(templates: Array<{
+    content: string;
+}>): string[];
+/** True when a user turn is the body of a slash command rather than something typed. */
+export declare function isReplayedTurn(text: string, fingerprints: string[]): boolean;
 /**
  * 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.
+ * User turns the user actually typed go in whole and unfiltered — any
+ * truncation there would quietly reintroduce the recall problem the old regex
+ * gate had. What does not go in is text the user's tooling replayed: its own
+ * past digests, and slash-command bodies.
+ *
+ * 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
+ * failure-then-pass is a fix. Successful tool output is dropped: it is a file
+ * or a command's stdout, not a statement by anyone, and feeding it to a miner
+ * looking for directives yields lines lifted out of plan files and configs
+ * attributed to the user.
+ */
+export declare function renderTranscript(session: MinableSession, fingerprints?: string[]): string;
+/** Everything the user actually said in a session, normalized, for checking quotes against. */
+export declare function spokenText(session: MinableSession, fingerprints?: string[]): string;
+/**
+ * Drop candidates whose quote cannot be found in what the user said.
+ *
+ * The miner is told to quote verbatim and the digest renders every quote inside
+ * quotation marks, but on a real corpus a third of them appear nowhere in the
+ * session: paraphrases, merged sentences, and lines lifted out of tool output.
+ * A quote that cannot be located is evidence that cannot be shown, and a
+ * proposal the reader cannot check is worse than one that was never made.
+ *
+ * Whitespace is normalized before comparing, because a directive written in a
+ * markdown file arrives wrapped across lines and the model unwraps it.
  */
-export declare function renderTranscript(session: MinableSession): string;
+export declare function verifyCandidates(candidates: MinedCandidate[], spoken: string): MinedCandidate[];
 /**
  * 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
@@ -110,6 +159,12 @@ export interface MinerDeps {
     model: Model<any>;
     apiKey?: string;
     headers?: Record<string, string>;
+    /**
+     * Literal runs from the slash-command bodies in force, from
+     * `replayFingerprints`. User turns matching one are machinery replaying
+     * itself, not the user speaking.
+     */
+    replayFingerprints?: string[];
 }
 /**
  * Build the real miner: one model call per chunk of one session.

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

@@ -1 +1 @@
-{"version":3,"file":"mine.d.ts","sourceRoot":"","sources":["../../../src/core/learn/mine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,yBAAyB,CAAC;AAG5E,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,KAAK,GAAG,UAAU,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AA4BjG;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,GAAG,MAAM,CAKnF;AAYD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAkCpD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAiChE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,SAAuB,GAAG,MAAM,EAAE,CAiBzF;AAiCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CA4ClE;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CA+BrD","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"]}
+{"version":3,"file":"mine.d.ts","sourceRoot":"","sources":["../../../src/core/learn/mine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,yBAAyB,CAAC;AAG5E,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACxD,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACd;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AA4BjG;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,GAAG,MAAM,CAKnF;AAmBD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AAOpD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,EAAE,CAclF;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAK5E;AAkCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,MAAM,CAgC7F;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,YAAY,GAAE,MAAM,EAAO,GAAG,MAAM,CAWvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAU/F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,SAAuB,GAAG,MAAM,EAAE,CAiBzF;AAgCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAwClE;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAmCrD","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 here is name or count. It used to emit a label\n * per occurrence — its own canonical name for what was meant — and the reduce\n * step grouped on exact label equality. That cannot work from inside one\n * session: the model is asked to hit a shared vocabulary it has never seen, and\n * on a real corpus it agreed with itself 3 times out of 188. Naming now happens\n * once, globally, in `cluster.ts`, where every candidate is visible at the same\n * time. Counting stays in `reduce.ts`, where it always belonged.\n *\n * Leaving labels out also makes the cache model-independent. A cached candidate\n * used to carry a label frozen at mining time, so changing the `fast` tier\n * forked the vocabulary permanently: old sessions and new ones named the same\n * thing differently, and neither side reached the repeat threshold.\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\" | \"request\";\n\n/**\n * One occurrence, as reported by the model reading a single session.\n *\n * Deliberately unnamed. What was *meant* is only decidable against everything\n * else that was said, and this stage sees one session, so it reports what it\n * saw and leaves grouping to `cluster.ts`. This is also the shape that goes in\n * the cache, which is why nothing model-specific may live on it.\n */\nexport interface MinedCandidate {\n\tkind: CandidateKind;\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}\n\n/** A candidate once the global naming pass has decided what to call it. */\nexport interface LabelledCandidate extends MinedCandidate {\n\t/** Canonical slug for what was meant. The clustering key. */\n\tlabel: 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/** Error output kept per call. Errors carry the signal; success output is dropped entirely. */\nconst TOOL_ERROR_CHARS = 1_500;\n\n/**\n * Shortest literal run of a slash-command body that identifies a replay.\n *\n * Long enough that a user cannot type it by accident, short enough to survive a\n * template whose placeholders are densely packed.\n */\nconst REPLAY_FINGERPRINT_CHARS = 40;\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\n/** Collapse whitespace so a quote survives the wrapping a markdown source imposes on it. */\nfunction normalizeForMatch(text: string): string {\n\treturn text.replace(/\\s+/g, \" \").trim().toLowerCase();\n}\n\n/**\n * Literal runs from slash-command bodies, used to recognise a replayed expansion.\n *\n * A `user`-type slash command is persisted as an ordinary user message holding\n * the whole template body, with nothing to mark it as machinery. Read back off\n * disk it is indistinguishable from something the user typed — and it is the\n * most repeated text in a real corpus, because running `/pr` thirty times\n * writes the same two thousand characters thirty times. Mining it produces\n * directives the user never stated, at counts that look exactly like organic\n * repetition.\n *\n * Detection is retroactive on purpose. A provenance flag written at turn time\n * would be exact, but it would only help sessions recorded after it shipped,\n * leaving the existing corpus contaminated for months. Matching against the\n * command bodies still on disk fixes the history that already exists. The gap\n * is a template that has since been deleted; that case wants the flag, and is\n * the reason to add one later.\n */\nexport function replayFingerprints(templates: Array<{ content: string }>): string[] {\n\tconst out: string[] = [];\n\tfor (const template of templates) {\n\t\t// Split on the placeholders that argument substitution rewrites, leaving the\n\t\t// literal text that survives every expansion.\n\t\tconst segments = template.content.split(/\\$(?:\\d+|ARGUMENTS|\\*)/);\n\t\tlet longest = \"\";\n\t\tfor (const segment of segments) {\n\t\t\tconst normalized = normalizeForMatch(segment);\n\t\t\tif (normalized.length > longest.length) longest = normalized;\n\t\t}\n\t\tif (longest.length >= REPLAY_FINGERPRINT_CHARS) out.push(longest);\n\t}\n\treturn out;\n}\n\n/** True when a user turn is the body of a slash command rather than something typed. */\nexport function isReplayedTurn(text: string, fingerprints: string[]): boolean {\n\tif (fingerprints.length === 0) return false;\n\tconst normalized = normalizeForMatch(text);\n\tif (normalized.length < REPLAY_FINGERPRINT_CHARS) return false;\n\treturn fingerprints.some((fingerprint) => normalized.includes(fingerprint));\n}\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 the user actually typed go in whole and unfiltered — any\n * truncation there would quietly reintroduce the recall problem the old regex\n * gate had. What does not go in is text the user's tooling replayed: its own\n * past digests, and slash-command bodies.\n *\n * Assistant prose is dropped: it is the bulk of a transcript and almost none of\n * it is evidence about what the *user* wants. Tool calls are kept, because a\n * failure-then-pass is a fix. Successful tool output is dropped: it is a file\n * or a command's stdout, not a statement by anyone, and feeding it to a miner\n * looking for directives yields lines lifted out of plan files and configs\n * attributed to the user.\n */\nexport function renderTranscript(session: MinableSession, fingerprints: string[] = []): 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\tif (isReplayedTurn(text, fingerprints)) 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\" && message.isError) {\n\t\t\tconst output = textOf(message.content);\n\t\t\tif (!output) continue;\n\t\t\tlines.push(`ERROR: ${output.length > TOOL_ERROR_CHARS ? `${output.slice(0, TOOL_ERROR_CHARS)}…` : output}`);\n\t\t}\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n/** Everything the user actually said in a session, normalized, for checking quotes against. */\nexport function spokenText(session: MinableSession, fingerprints: string[] = []): string {\n\tconst parts: string[] = [];\n\tfor (const entry of session.entries) {\n\t\tconst message = entry.type === \"message\" ? entry.message : undefined;\n\t\tif (!message || message.role !== \"user\") continue;\n\t\tconst text = textOf(message.content);\n\t\tif (!text || text.startsWith(LEARN_DIGEST_MARKER)) continue;\n\t\tif (isReplayedTurn(text, fingerprints)) continue;\n\t\tparts.push(text);\n\t}\n\treturn normalizeForMatch(parts.join(\"\\n\"));\n}\n\n/**\n * Drop candidates whose quote cannot be found in what the user said.\n *\n * The miner is told to quote verbatim and the digest renders every quote inside\n * quotation marks, but on a real corpus a third of them appear nowhere in the\n * session: paraphrases, merged sentences, and lines lifted out of tool output.\n * A quote that cannot be located is evidence that cannot be shown, and a\n * proposal the reader cannot check is worse than one that was never made.\n *\n * Whitespace is normalized before comparing, because a directive written in a\n * markdown file arrives wrapped across lines and the model unwraps it.\n */\nexport function verifyCandidates(candidates: MinedCandidate[], spoken: string): MinedCandidate[] {\n\t// Normalized again rather than trusting the caller: the check is a substring\n\t// test, and one un-normalized argument would silently reject everything.\n\tconst haystack = normalizeForMatch(spoken);\n\tif (!haystack) return [];\n\treturn candidates.filter((candidate) => {\n\t\t// A fix is evidenced by commands and errors, not by something the user said.\n\t\tif (candidate.kind === \"fix\") return true;\n\t\treturn haystack.includes(normalizeForMatch(candidate.text));\n\t});\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\"\nA directive is how things should be done in general. What to do right now is a **request** — see below — not a directive. When a message contains both, report the directive part here.\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**request** — the user asking for a piece of work by name: \"open a release PR\", \"run the full check and fix what it finds\", \"give me a demo of X\". Report the request as they phrased it. A request repeated across sessions is a slash command waiting to be written, which is why it is worth reporting even though it is not a rule.\n\nA message can contain both a request and a directive — \"open a release PR, and remember to stage only your own files\" is one of each. Report both, separately.\n\nQuote \"text\" VERBATIM from the transcript. Do not paraphrase, merge two sentences, or tidy the wording: a quote that cannot be found in the session is discarded, because the reader is shown it in quotation marks and has to be able to check it.\n\nDo not name or group anything. A later stage sees every session at once and decides what counts as the same point; from inside one session you cannot know.\n\nOutput STRICT JSON, no markdown fence, no prose:\n{\"candidates\":[{\"kind\":\"directive\",\"text\":\"<verbatim quote>\",\"rationale\":\"<one clause on why it is durable>\"}]}\n\nFor fix items add: \"command\", \"errorExcerpt\", \"interveningCommands\" (array), \"editedFiles\" (array).\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 !== \"request\") continue;\n\n\t\tconst text = typeof candidate.text === \"string\" ? candidate.text.trim() : \"\";\n\t\t// Nothing to quote back means nothing to show the reader.\n\t\tif (!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\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});\n\t}\n\treturn out;\n}\n\nexport interface MinerDeps {\n\tmodel: Model<any>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n\t/**\n\t * Literal runs from the slash-command bodies in force, from\n\t * `replayFingerprints`. User turns matching one are machinery replaying\n\t * itself, not the user speaking.\n\t */\n\treplayFingerprints?: 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\tconst fingerprints = deps.replayFingerprints ?? [];\n\treturn async (session, signal) => {\n\t\tconst chunks = chunkTranscript(renderTranscript(session, fingerprints), 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\t// Verify against the whole session rather than the chunk that produced the\n\t\t// candidate: a quote can legitimately straddle a chunk boundary, and a\n\t\t// dropped-for-being-unfindable verdict has to mean unfindable anywhere.\n\t\treturn verifyCandidates(candidates, spokenText(session, fingerprints));\n\t};\n}\n"]}

package/dist/core/learn/mine.js

@@ -12,12 +12,18 @@
  * 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.
+ * What the model does *not* do here is name or count. It used to emit a label
+ * per occurrence — its own canonical name for what was meant — and the reduce
+ * step grouped on exact label equality. That cannot work from inside one
+ * session: the model is asked to hit a shared vocabulary it has never seen, and
+ * on a real corpus it agreed with itself 3 times out of 188. Naming now happens
+ * once, globally, in `cluster.ts`, where every candidate is visible at the same
+ * time. Counting stays in `reduce.ts`, where it always belonged.
+ *
+ * Leaving labels out also makes the cache model-independent. A cached candidate
+ * used to carry a label frozen at mining time, so changing the `fast` tier
+ * forked the vocabulary permanently: old sessions and new ones named the same
+ * thing differently, and neither side reached the repeat threshold.
  */
 import { completeSimple } from "@kolisachint/hoocode-ai";
 /**
@@ -56,9 +62,15 @@ export function chunkCharsForModel(model) {
     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;
+/** Error output kept per call. Errors carry the signal; success output is dropped entirely. */
 const TOOL_ERROR_CHARS = 1_500;
+/**
+ * Shortest literal run of a slash-command body that identifies a replay.
+ *
+ * Long enough that a user cannot type it by accident, short enough to survive a
+ * template whose placeholders are densely packed.
+ */
+const REPLAY_FINGERPRINT_CHARS = 40;
 /** 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. */
@@ -69,6 +81,54 @@ const MAX_CANDIDATES_PER_CHUNK = 40;
  * every proposal would compound its own count.
  */
 export const LEARN_DIGEST_MARKER = "[learn-digest]";
+/** Collapse whitespace so a quote survives the wrapping a markdown source imposes on it. */
+function normalizeForMatch(text) {
+    return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * Literal runs from slash-command bodies, used to recognise a replayed expansion.
+ *
+ * A `user`-type slash command is persisted as an ordinary user message holding
+ * the whole template body, with nothing to mark it as machinery. Read back off
+ * disk it is indistinguishable from something the user typed — and it is the
+ * most repeated text in a real corpus, because running `/pr` thirty times
+ * writes the same two thousand characters thirty times. Mining it produces
+ * directives the user never stated, at counts that look exactly like organic
+ * repetition.
+ *
+ * Detection is retroactive on purpose. A provenance flag written at turn time
+ * would be exact, but it would only help sessions recorded after it shipped,
+ * leaving the existing corpus contaminated for months. Matching against the
+ * command bodies still on disk fixes the history that already exists. The gap
+ * is a template that has since been deleted; that case wants the flag, and is
+ * the reason to add one later.
+ */
+export function replayFingerprints(templates) {
+    const out = [];
+    for (const template of templates) {
+        // Split on the placeholders that argument substitution rewrites, leaving the
+        // literal text that survives every expansion.
+        const segments = template.content.split(/\$(?:\d+|ARGUMENTS|\*)/);
+        let longest = "";
+        for (const segment of segments) {
+            const normalized = normalizeForMatch(segment);
+            if (normalized.length > longest.length)
+                longest = normalized;
+        }
+        if (longest.length >= REPLAY_FINGERPRINT_CHARS)
+            out.push(longest);
+    }
+    return out;
+}
+/** True when a user turn is the body of a slash command rather than something typed. */
+export function isReplayedTurn(text, fingerprints) {
+    if (fingerprints.length === 0)
+        return false;
+    const normalized = normalizeForMatch(text);
+    if (normalized.length < REPLAY_FINGERPRINT_CHARS)
+        return false;
+    return fingerprints.some((fingerprint) => normalized.includes(fingerprint));
+}
 function textOf(content) {
     if (typeof content === "string")
         return content;
@@ -103,14 +163,19 @@ function renderArgs(args) {
 /**
  * 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.
+ * User turns the user actually typed go in whole and unfiltered — any
+ * truncation there would quietly reintroduce the recall problem the old regex
+ * gate had. What does not go in is text the user's tooling replayed: its own
+ * past digests, and slash-command bodies.
+ *
+ * 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
+ * failure-then-pass is a fix. Successful tool output is dropped: it is a file
+ * or a command's stdout, not a statement by anyone, and feeding it to a miner
+ * looking for directives yields lines lifted out of plan files and configs
+ * attributed to the user.
  */
-export function renderTranscript(session) {
+export function renderTranscript(session, fingerprints = []) {
     const lines = [];
     for (const entry of session.entries) {
         const message = entry.type === "message" ? entry.message : undefined;
@@ -121,6 +186,8 @@ export function renderTranscript(session) {
             // Skip the command's own past output, or proposals compound their counts.
             if (!text || text.startsWith(LEARN_DIGEST_MARKER))
                 continue;
+            if (isReplayedTurn(text, fingerprints))
+                continue;
             lines.push(`USER: ${text}`);
             continue;
         }
@@ -132,17 +199,56 @@ export function renderTranscript(session) {
             }
             continue;
         }
-        if (message.role === "toolResult") {
+        if (message.role === "toolResult" && message.isError) {
             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}`);
+            lines.push(`ERROR: ${output.length > TOOL_ERROR_CHARS ? `${output.slice(0, TOOL_ERROR_CHARS)}…` : output}`);
         }
     }
     return lines.join("\n");
 }
+/** Everything the user actually said in a session, normalized, for checking quotes against. */
+export function spokenText(session, fingerprints = []) {
+    const parts = [];
+    for (const entry of session.entries) {
+        const message = entry.type === "message" ? entry.message : undefined;
+        if (!message || message.role !== "user")
+            continue;
+        const text = textOf(message.content);
+        if (!text || text.startsWith(LEARN_DIGEST_MARKER))
+            continue;
+        if (isReplayedTurn(text, fingerprints))
+            continue;
+        parts.push(text);
+    }
+    return normalizeForMatch(parts.join("\n"));
+}
+/**
+ * Drop candidates whose quote cannot be found in what the user said.
+ *
+ * The miner is told to quote verbatim and the digest renders every quote inside
+ * quotation marks, but on a real corpus a third of them appear nowhere in the
+ * session: paraphrases, merged sentences, and lines lifted out of tool output.
+ * A quote that cannot be located is evidence that cannot be shown, and a
+ * proposal the reader cannot check is worse than one that was never made.
+ *
+ * Whitespace is normalized before comparing, because a directive written in a
+ * markdown file arrives wrapped across lines and the model unwraps it.
+ */
+export function verifyCandidates(candidates, spoken) {
+    // Normalized again rather than trusting the caller: the check is a substring
+    // test, and one un-normalized argument would silently reject everything.
+    const haystack = normalizeForMatch(spoken);
+    if (!haystack)
+        return [];
+    return candidates.filter((candidate) => {
+        // A fix is evidenced by commands and errors, not by something the user said.
+        if (candidate.kind === "fix")
+            return true;
+        return haystack.includes(normalizeForMatch(candidate.text));
+    });
+}
 /**
  * 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
@@ -179,23 +285,22 @@ Report three kinds of thing.
 - 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.
+A directive is how things should be done in general. What to do right now is a **request** — see below — not a directive. When a message contains both, report the directive part here.
 
 **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).
+**request** — the user asking for a piece of work by name: "open a release PR", "run the full check and fix what it finds", "give me a demo of X". Report the request as they phrased it. A request repeated across sessions is a slash command waiting to be written, which is why it is worth reporting even though it is not a rule.
+
+A message can contain both a request and a directive — "open a release PR, and remember to stage only your own files" is one of each. Report both, separately.
+
+Quote "text" VERBATIM from the transcript. Do not paraphrase, merge two sentences, or tidy the wording: a quote that cannot be found in the session is discarded, because the reader is shown it in quotation marks and has to be able to check 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.
+Do not name or group anything. A later stage sees every session at once and decides what counts as the same point; from inside one session you cannot know.
 
 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>"}]}
+{"candidates":[{"kind":"directive","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":[]}`;
 /**
@@ -227,25 +332,21 @@ export function parseCandidates(response) {
             continue;
         const candidate = item;
         const kind = candidate.kind;
-        if (kind !== "directive" && kind !== "fix" && kind !== "workflow")
+        if (kind !== "directive" && kind !== "fix" && kind !== "request")
             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)
+        // Nothing to quote back means nothing to show the reader.
+        if (!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;
@@ -260,8 +361,9 @@ export function parseCandidates(response) {
  */
 export function createLlmMiner(deps) {
     const chunkChars = chunkCharsForModel(deps.model);
+    const fingerprints = deps.replayFingerprints ?? [];
     return async (session, signal) => {
-        const chunks = chunkTranscript(renderTranscript(session), chunkChars);
+        const chunks = chunkTranscript(renderTranscript(session, fingerprints), chunkChars);
         const candidates = [];
         for (const chunk of chunks) {
             if (signal?.aborted)
@@ -279,7 +381,10 @@ export function createLlmMiner(deps) {
                 .join("\n");
             candidates.push(...parseCandidates(text));
         }
-        return candidates;
+        // Verify against the whole session rather than the chunk that produced the
+        // candidate: a quote can legitimately straddle a chunk boundary, and a
+        // dropped-for-being-unfindable verdict has to mean unfindable anywhere.
+        return verifyCandidates(candidates, spokenText(session, fingerprints));
     };
 }
 //# sourceMappingURL=mine.js.map