@kolisachint/hoocode-agent 0.5.16 → 0.5.18

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

@@ -1 +1 @@
-{"version":3,"file":"learn.d.ts","sourceRoot":"","sources":["../../../src/extensions/core/learn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,YAAY,EAA2B,MAAM,gCAAgC,CAAC;AAiO5F,wBAAgB,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAoGjD","sourcesContent":["/**\n * `/learn` — promote what recent sessions actually taught into durable rules\n * and skills.\n *\n * The command is a thin shell on purpose. It runs the deterministic extractor\n * over session transcripts on disk, renders the ranked result, and injects it\n * as a follow-up message; every judgement after that belongs to the model,\n * which can read the repo and phrase a rule far better than a heuristic can.\n *\n * Reading transcripts from disk rather than the live context is what makes this\n * work: the on-disk history survives compaction, and it spans past sessions, so\n * \"you have said this in five separate sessions\" is available as a number\n * instead of a guess. That number is the whole reason the command exists.\n *\n * Follows /grill in modes.ts: no session switch, no mode change, no config\n * write — just a follow-up message. Writes to AGENTS.md happen through ordinary\n * edit tools, so the existing permission prompt is the approval step and no\n * separate picker is needed.\n */\n\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { CONFIG_DIR_NAME, getHooCodeDir } from \"../../config.js\";\nimport { loadProjectContextFiles } from \"../../core/context-files.js\";\nimport type { ExtensionAPI, ExtensionCommandContext } from \"../../core/extensions/types.js\";\nimport { isEmptyDigest, renderLearnDigest } from \"../../core/learn/digest.js\";\nimport {\n\tbuildCoverageIndex,\n\textractLearnDigest,\n\ttype LearnDigest,\n\tmatchCoverage,\n\ttype SessionScanReport,\n\tscanSessions,\n} from \"../../core/learn/extract.js\";\nimport {\n\tgetLearnStatePath,\n\treadLearnState,\n\trecordSurfaced,\n\tsummarizeLearnState,\n\twriteLearnState,\n} from \"../../core/learn/state.js\";\nimport { getSessionDirPath } from \"../../core/session-manager.js\";\nimport { SettingsManager } from \"../../core/settings-manager.js\";\n\n/** Guards against double-registration when default extensions load more than once. */\nconst REGISTERED = Symbol.for(\"hoocode.learn.registered\");\n\n/** User-scope destination offered for personal rules that travel across repos. */\nconst USER_SCOPE_PATH = join(homedir(), \".agents\", \"AGENTS.md\");\n\n/** Render a home-relative path the way the user would type it. */\nfunction displayPath(path: string): string {\n\tconst home = homedir();\n\treturn path.startsWith(home) ? `~${path.slice(home.length)}` : path;\n}\n\nfunction shortDate(iso: string | undefined): string {\n\tif (!iso) return \"unknown\";\n\tconst date = new Date(iso);\n\treturn Number.isNaN(date.getTime()) ? \"unknown\" : date.toISOString().slice(0, 10);\n}\n\n/** The settings keys `/learn` reads, paired with the values in force right now. */\ntype LearnWindow = ReturnType<SettingsManager[\"getLearnSettings\"]>;\n\nconst SETTING_KEYS: Array<{ key: keyof LearnWindow; setting: string; note: string }> = [\n\t{ key: \"maxSessions\", setting: \"learnMaxSessions\", note: \"recent sessions scanned\" },\n\t{ key: \"maxAgeDays\", setting: \"learnMaxAgeDays\", note: \"ignore sessions older than this, in days\" },\n\t{ key: \"minRepeats\", setting: \"learnMinRepeats\", note: \"times a directive must recur to be proposed\" },\n\t{\n\t\tkey: \"minWorkflowRepeats\",\n\t\tsetting: \"learnMinWorkflowRepeats\",\n\t\tnote: \"repeats before a tool sequence is proposed\",\n\t},\n\t{ key: \"maxProposals\", setting: \"learnMaxProposals\", note: \"cap on each list in the digest\" },\n];\n\n/**\n * Where the knobs live, and what they are set to.\n *\n * `/learn` has five settings and no UI, so until this existed the only way to\n * find them was to already know they were in `settings.json`. Every message that\n * reports a disappointing result names a threshold, so every one of them ends\n * with these lines.\n */\nfunction settingsPathLines(ctx: ExtensionCommandContext, agentDir: string): string[] {\n\treturn [\n\t\t\"Settings — edit either file, no restart needed\",\n\t\t`  user     ${displayPath(join(agentDir, \"settings.json\"))}`,\n\t\t`  project  ${displayPath(join(ctx.cwd, CONFIG_DIR_NAME, \"settings.json\"))}  (wins where both set a key)`,\n\t];\n}\n\nfunction settingsLines(ctx: ExtensionCommandContext, agentDir: string, window: LearnWindow): string[] {\n\tconst lines = settingsPathLines(ctx, agentDir);\n\tfor (const { key, setting, note } of SETTING_KEYS) {\n\t\tlines.push(`  ${setting.padEnd(24)} ${String(window[key]).padStart(3)}   ${note}`);\n\t}\n\treturn lines;\n}\n\n/**\n * The directory whose name keys this cwd's bookmark.\n *\n * Derived from the cwd, never from the live session manager. An in-memory\n * session (`--no-session`) reports an empty session directory, which used to key\n * every such run to the same nameless state file, and a shared custom\n * `sessionDir` used to make two unrelated projects share one bookmark. The cwd\n * is what \"per directory\" means here, so the cwd is what it is keyed on.\n */\nfunction stateKeyDir(ctx: ExtensionCommandContext, agentDir: string): string {\n\treturn getSessionDirPath(ctx.cwd, agentDir);\n}\n\n/** Run the directory scan without ranking anything, for the reports that only need counts. */\nfunction sessionScanPreview(ctx: ExtensionCommandContext, agentDir: string, window: LearnWindow): SessionScanReport {\n\treturn scanSessions({\n\t\tcwd: ctx.cwd,\n\t\tagentDir,\n\t\tsessionDir: ctx.sessionManager.getSessionDir(),\n\t\tmaxSessions: window.maxSessions,\n\t\tmaxAgeDays: window.maxAgeDays,\n\t});\n}\n\n/** Where sessions were looked for, and what was passed over — the \"why nothing?\" answer. */\nfunction scanLines(scan: SessionScanReport, window: LearnWindow): string[] {\n\tconst lines: string[] = [\"Looked in\"];\n\tfor (const dir of scan.dirs) {\n\t\tconst missing = scan.missingDirs.includes(dir) ? \"  (does not exist)\" : \"\";\n\t\tlines.push(`  ${displayPath(dir)}${missing}`);\n\t}\n\tlines.push(`Found ${scan.files} session file(s)`);\n\n\tconst skips: string[] = [];\n\tif (scan.tooOld > 0) skips.push(`${scan.tooOld} older than ${window.maxAgeDays} days (learnMaxAgeDays)`);\n\tif (scan.otherCwd > 0) skips.push(`${scan.otherCwd} recorded a different working directory`);\n\tif (scan.overLimit > 0) skips.push(`${scan.overLimit} beyond the newest ${window.maxSessions} (learnMaxSessions)`);\n\tif (scan.unreadable > 0) skips.push(`${scan.unreadable} empty or unreadable`);\n\tfor (const skip of skips) lines.push(`  skipped: ${skip}`);\n\treturn lines;\n}\n\n/**\n * Explain an empty scan rather than asserting there is no history.\n *\n * The old single sentence was wrong as often as it was right: sessions existed,\n * they were simply all outside the window or recorded under another path. Naming\n * the directory searched and the reason each file was passed over turns a dead\n * end into something the reader can fix.\n */\nfunction reportNoSessions(ctx: ExtensionCommandContext, agentDir: string, digest: LearnDigest, window: LearnWindow) {\n\tconst lines: string[] = [];\n\tlines.push(\n\t\tdigest.scan.files === 0\n\t\t\t? \"/learn found no session transcripts for this directory.\"\n\t\t\t: \"/learn found session transcripts, but none inside the current window.\",\n\t);\n\tlines.push(\"\");\n\tlines.push(...scanLines(digest.scan, window));\n\tlines.push(\"\");\n\tlines.push(...settingsLines(ctx, agentDir, window));\n\tctx.ui.notify(lines.join(\"\\n\"), \"warning\");\n}\n\n/**\n * `/learn stats` — what became of past proposals.\n *\n * Reads the state file and recomputes coverage; it does not re-mine sessions,\n * so it is instant and answers a different question than a normal run: not\n * \"what should I write down\" but \"is this command earning its place\".\n */\nfunction reportStats(ctx: ExtensionCommandContext): void {\n\tconst agentDir = getHooCodeDir();\n\tconst window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();\n\tconst statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));\n\tconst state = readLearnState(statePath);\n\n\tif (Object.keys(state.surfaced).length === 0) {\n\t\t// Nothing on record means `/learn` has never proposed anything here — which\n\t\t// is as likely to be \"it never found any sessions\" as \"you never ran it\", so\n\t\t// point at both the sessions it can see and the knobs that gate them.\n\t\tconst lines = [\"No /learn history for this directory yet — nothing has been proposed here.\"];\n\t\tlines.push(`  State file  ${displayPath(statePath)}  (not created yet)`);\n\t\tlines.push(\"\");\n\t\tlines.push(...scanLines(sessionScanPreview(ctx, agentDir, window), window));\n\t\tlines.push(\"\");\n\t\tlines.push(...settingsPathLines(ctx, agentDir));\n\t\tlines.push(\"  Run /learn settings for the thresholds in force.\");\n\t\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n\t\treturn;\n\t}\n\n\tconst coverage = buildCoverageIndex({ cwd: ctx.cwd, agentDir });\n\tconst stats = summarizeLearnState(state, (normalized) => {\n\t\tconst match = matchCoverage(normalized, coverage);\n\t\treturn !!(match.rule || match.skill);\n\t});\n\n\tconst contextTokens = loadProjectContextFiles({ cwd: ctx.cwd, agentDir }).agentsFiles.reduce(\n\t\t(sum, file) => sum + (file.tokens ?? 0),\n\t\t0,\n\t);\n\n\tconst lines: string[] = [];\n\tlines.push(`/learn history for this directory — ${shortDate(stats.earliest)} to ${shortDate(stats.latest)}`);\n\tlines.push(\n\t\t`  Proposals shown   ${stats.total}  (${stats.directives} directive, ${stats.fixes} fix, ${stats.workflows} workflow)`,\n\t);\n\tif (stats.lastRun) lines.push(`  Last run          ${shortDate(stats.lastRun)}`);\n\tlines.push(\"\");\n\n\tif (stats.open === 0) {\n\t\tlines.push(\"No directive proposals yet, so there is nothing to measure adoption against.\");\n\t} else {\n\t\tconst rate = Math.round((stats.adopted / stats.open) * 100);\n\t\tlines.push(\"Directive adoption — the only category with a coverage signal\");\n\t\tlines.push(`  Written down      ${stats.adopted} of ${stats.open}  (${rate}%)`);\n\t\tlines.push(`  Passed over       ${stats.declined}`);\n\t\tlines.push(\"\");\n\t\t// Without this the number invites the wrong conclusion. Adoption is a proxy\n\t\t// for usefulness, and a proposal correctly rejected as not durable counts\n\t\t// against it exactly like a junk one — so near-100% means the bar is too\n\t\t// low, not that the extractor is perfect.\n\t\tlines.push(\"  A very high rate means the bar is too low, not that every proposal was good.\");\n\t\tlines.push(\"  Near zero means the extractor is proposing the wrong things.\");\n\t}\n\n\tlines.push(\"\");\n\tlines.push(`Context files       ~${contextTokens} tokens, re-sent every request`);\n\tlines.push(`State file          ${displayPath(statePath)}`);\n\tlines.push(\"\");\n\tlines.push(...settingsPathLines(ctx, agentDir));\n\tlines.push(\"  Run /learn settings for the thresholds in force.\");\n\n\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n}\n\n/** `/learn settings` — the knobs, their current values, and the files to set them in. */\nfunction reportSettings(ctx: ExtensionCommandContext): void {\n\tconst agentDir = getHooCodeDir();\n\tconst window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();\n\tconst lines = settingsLines(ctx, agentDir, window);\n\tlines.push(\"\");\n\tlines.push(...scanLines(sessionScanPreview(ctx, agentDir, window), window));\n\tlines.push(`State file  ${displayPath(getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir)))}`);\n\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n}\n\nexport function setupLearn(pi: ExtensionAPI): void {\n\tconst guarded = pi as unknown as Record<symbol, boolean>;\n\tif (guarded[REGISTERED]) return;\n\tguarded[REGISTERED] = true;\n\n\tpi.registerCommand(\"learn\", {\n\t\tdescription: \"Mine recent sessions for durable rules and skills. Usage: /learn [all|stats|settings]\",\n\t\tgetArgumentCompletions: (prefix: string) =>\n\t\t\t(\n\t\t\t\t[\n\t\t\t\t\t{ value: \"all\", label: \"re-propose everything\" },\n\t\t\t\t\t{ value: \"stats\", label: \"what happened to past proposals\" },\n\t\t\t\t\t{ value: \"settings\", label: \"where sessions are read from, and the knobs\" },\n\t\t\t\t] as const\n\t\t\t)\n\t\t\t\t.filter((option) => option.value.startsWith(prefix))\n\t\t\t\t.map((option) => ({ value: option.value, label: option.label })),\n\t\thandler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {\n\t\t\tconst argument = args.trim().toLowerCase();\n\t\t\tif (argument && argument !== \"all\" && argument !== \"stats\" && argument !== \"settings\") {\n\t\t\t\tctx.ui.notify(\"Usage: /learn [all|stats|settings]\", \"warning\");\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (argument === \"stats\") {\n\t\t\t\treportStats(ctx);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (argument === \"settings\") {\n\t\t\t\treportSettings(ctx);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst ignoreState = argument === \"all\";\n\n\t\t\t// Read per-invocation so a settings edit takes effect without a reload,\n\t\t\t// and so a project settings.json can narrow the window for one repo.\n\t\t\tconst agentDir = getHooCodeDir();\n\t\t\tconst window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();\n\t\t\tconst statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));\n\n\t\t\tlet digest: LearnDigest;\n\t\t\ttry {\n\t\t\t\tdigest = extractLearnDigest({\n\t\t\t\t\tcwd: ctx.cwd,\n\t\t\t\t\tagentDir,\n\t\t\t\t\t// Searched in addition to the per-cwd default directory, so a session\n\t\t\t\t\t// manager pointing elsewhere (`--session`, a custom `sessionDir`, or\n\t\t\t\t\t// an in-memory session reporting none at all) cannot hide the history.\n\t\t\t\t\tsessionDir: ctx.sessionManager.getSessionDir(),\n\t\t\t\t\tmaxSessions: window.maxSessions,\n\t\t\t\t\tmaxAgeDays: window.maxAgeDays,\n\t\t\t\t\tminRepeats: window.minRepeats,\n\t\t\t\t\tminWorkflowRepeats: window.minWorkflowRepeats,\n\t\t\t\t\tmaxProposals: window.maxProposals,\n\t\t\t\t\tstate: readLearnState(statePath),\n\t\t\t\t\tignoreState,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tctx.ui.notify(`/learn could not read session history: ${error}`, \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (digest.scannedSessions === 0) {\n\t\t\t\treportNoSessions(ctx, agentDir, digest, window);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (isEmptyDigest(digest)) {\n\t\t\t\tconst lines: string[] = [];\n\t\t\t\tlines.push(\n\t\t\t\t\tdigest.suppressed > 0\n\t\t\t\t\t\t? `Scanned ${digest.scannedSessions} session(s) — nothing new since last time (${digest.suppressed} already shown). Run /learn all to see them again.`\n\t\t\t\t\t\t: `Scanned ${digest.scannedSessions} session(s) — nothing repeated often enough to be worth a rule yet.`,\n\t\t\t\t);\n\t\t\t\tif (digest.suppressed === 0) {\n\t\t\t\t\t// The thresholds are the reason a scan with real sessions in it came\n\t\t\t\t\t// back empty, so this is the moment they are worth knowing about.\n\t\t\t\t\tlines.push(\"\");\n\t\t\t\t\tlines.push(...settingsLines(ctx, agentDir, window));\n\t\t\t\t}\n\t\t\t\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst counts = [\n\t\t\t\tdigest.directives.length > 0 ? `${digest.directives.length} directive(s)` : undefined,\n\t\t\t\tdigest.fixes.length > 0 ? `${digest.fixes.length} fix(es)` : undefined,\n\t\t\t\tdigest.workflows.length > 0 ? `${digest.workflows.length} workflow(s)` : undefined,\n\t\t\t].filter((part): part is string => !!part);\n\t\t\tconst held = digest.suppressed > 0 ? `, ${digest.suppressed} held back` : \"\";\n\t\t\tctx.ui.notify(`Mined ${digest.scannedSessions} session(s): ${counts.join(\", \")}${held}.`, \"info\");\n\n\t\t\t// Record before delivering: what matters is that these were put in front\n\t\t\t// of the user, which is true whether or not they act on the digest.\n\t\t\twriteLearnState(statePath, recordSurfaced(readLearnState(statePath), digest.surfaced));\n\n\t\t\tpi.sendUserMessage(renderLearnDigest(digest, { userScopePath: displayPath(USER_SCOPE_PATH) }), {\n\t\t\t\tdeliverAs: \"followUp\",\n\t\t\t});\n\t\t},\n\t});\n}\n"]}
+{"version":3,"file":"learn.d.ts","sourceRoot":"","sources":["../../../src/extensions/core/learn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,YAAY,EAA2B,MAAM,gCAAgC,CAAC;AA8W5F,wBAAgB,UAAU,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAiLjD","sourcesContent":["/**\n * `/learn` — promote what recent sessions actually taught into durable rules\n * and skills.\n *\n * The command is a thin shell on purpose. It runs the mining pipeline over\n * session transcripts on disk, renders the ranked result, and injects it as a\n * follow-up message; every judgement after that belongs to the model, which can\n * read the repo and phrase a rule far better than a heuristic can.\n *\n * Reading transcripts from disk rather than the live context is what makes this\n * work: the on-disk history survives compaction, and it spans past sessions, so\n * \"you have said this in five separate sessions\" is available as a number\n * instead of a guess. That number is the whole reason the command exists.\n *\n * The pipeline reads every transcript with a model rather than pre-filtering\n * with regexes, which costs real tokens on a cold cache. That price is stated\n * before it is paid, never inferred: a run with sessions to read asks first.\n *\n * Follows /grill in modes.ts: no session switch, no mode change, no config\n * write — just a follow-up message. Writes to AGENTS.md happen through ordinary\n * edit tools, so the existing permission prompt is the approval step and no\n * separate picker is needed.\n */\n\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Api, Model } from \"@kolisachint/hoocode-ai\";\nimport { CONFIG_DIR_NAME, getHooCodeDir } from \"../../config.js\";\nimport { loadProjectContextFiles } from \"../../core/context-files.js\";\nimport type { ExtensionAPI, ExtensionCommandContext } from \"../../core/extensions/types.js\";\nimport type { CoverageJudge } from \"../../core/learn/coverage.js\";\nimport { createLlmCoverageJudge } from \"../../core/learn/coverage.js\";\nimport { isEmptyDigest, renderLearnDigest } from \"../../core/learn/digest.js\";\nimport {\n\tbuildCoverageIndex,\n\ttype LearnDigest,\n\tmineLearnDigest,\n\tplanMining,\n\ttype SessionScanReport,\n\tscanSessions,\n} from \"../../core/learn/extract.js\";\nimport type { Miner } from \"../../core/learn/mine.js\";\nimport { chunkCharsForModel, createLlmMiner } from \"../../core/learn/mine.js\";\nimport {\n\tgetLearnStatePath,\n\treadLearnState,\n\trecordSurfaced,\n\tsummarizeLearnState,\n\twriteLearnState,\n} from \"../../core/learn/state.js\";\nimport { resolveModelCategory } from \"../../core/model-categories.js\";\nimport { getSessionDirPath } from \"../../core/session-manager.js\";\nimport { SettingsManager } from \"../../core/settings-manager.js\";\nimport { startupProgress } from \"../../core/startup-progress.js\";\n\n/** Guards against double-registration when default extensions load more than once. */\nconst REGISTERED = Symbol.for(\"hoocode.learn.registered\");\n\n/** User-scope destination offered for personal rules that travel across repos. */\nconst USER_SCOPE_PATH = join(homedir(), \".agents\", \"AGENTS.md\");\n\n/** Footer key for the mining progress bar. */\nconst PROGRESS_KEY = \"learn-mining\";\n\n/** Escape, the way a raw terminal delivers it. */\nconst ESCAPE = \"\\x1b\";\n\n/**\n * Sessions that can be read without asking first.\n *\n * A run that has one or two new transcripts to read is the normal daily case\n * and interrupting it to confirm a trivial cost is noise. Beyond this the run\n * is a backfill — onboarding to an existing repo, or a first run — and the\n * reader should get to decide before it starts.\n */\nconst CONFIRM_ABOVE_PENDING = 3;\n\n/** Render a home-relative path the way the user would type it. */\nfunction displayPath(path: string): string {\n\tconst home = homedir();\n\treturn path.startsWith(home) ? `~${path.slice(home.length)}` : path;\n}\n\nfunction shortDate(iso: string | undefined): string {\n\tif (!iso) return \"unknown\";\n\tconst date = new Date(iso);\n\treturn Number.isNaN(date.getTime()) ? \"unknown\" : date.toISOString().slice(0, 10);\n}\n\n/** The settings keys `/learn` reads, paired with the values in force right now. */\ntype LearnWindow = ReturnType<SettingsManager[\"getLearnSettings\"]>;\n\nconst SETTING_KEYS: Array<{ key: keyof LearnWindow; setting: string; note: string }> = [\n\t{ key: \"maxSessions\", setting: \"learnMaxSessions\", note: \"recent sessions scanned\" },\n\t{ key: \"maxAgeDays\", setting: \"learnMaxAgeDays\", note: \"ignore sessions older than this, in days\" },\n\t{ key: \"minRepeats\", setting: \"learnMinRepeats\", note: \"times a directive must recur to be proposed\" },\n\t{\n\t\tkey: \"minWorkflowRepeats\",\n\t\tsetting: \"learnMinWorkflowRepeats\",\n\t\tnote: \"repeats before a tool sequence is proposed\",\n\t},\n\t{ key: \"maxProposals\", setting: \"learnMaxProposals\", note: \"cap on each list in the digest\" },\n];\n\n/**\n * Where the knobs live, and what they are set to.\n *\n * `/learn` has its settings and no UI, so until this existed the only way to\n * find them was to already know they were in `settings.json`. Every message that\n * reports a disappointing result names a threshold, so every one of them ends\n * with these lines.\n */\nfunction settingsPathLines(ctx: ExtensionCommandContext, agentDir: string): string[] {\n\treturn [\n\t\t\"Settings — edit either file, no restart needed\",\n\t\t`  user     ${displayPath(join(agentDir, \"settings.json\"))}`,\n\t\t`  project  ${displayPath(join(ctx.cwd, CONFIG_DIR_NAME, \"settings.json\"))}  (wins where both set a key)`,\n\t];\n}\n\nfunction settingsLines(ctx: ExtensionCommandContext, agentDir: string, window: LearnWindow): string[] {\n\tconst lines = settingsPathLines(ctx, agentDir);\n\tfor (const { key, setting, note } of SETTING_KEYS) {\n\t\tlines.push(`  ${setting.padEnd(24)} ${String(window[key] ?? \"—\").padStart(3)}   ${note}`);\n\t}\n\treturn lines;\n}\n\n/**\n * The directory whose name keys this cwd's bookmark.\n *\n * Derived from the cwd, never from the live session manager. An in-memory\n * session (`--no-session`) reports an empty session directory, which used to key\n * every such run to the same nameless state file, and a shared custom\n * `sessionDir` used to make two unrelated projects share one bookmark. The cwd\n * is what \"per directory\" means here, so the cwd is what it is keyed on.\n */\nfunction stateKeyDir(ctx: ExtensionCommandContext, agentDir: string): string {\n\treturn getSessionDirPath(ctx.cwd, agentDir);\n}\n\n/** Run the directory scan without mining anything, for the reports that only need counts. */\nfunction sessionScanPreview(ctx: ExtensionCommandContext, agentDir: string, window: LearnWindow): SessionScanReport {\n\treturn scanSessions({\n\t\tcwd: ctx.cwd,\n\t\tagentDir,\n\t\tsessionDir: ctx.sessionManager.getSessionDir(),\n\t\tmaxSessions: window.maxSessions,\n\t\tmaxAgeDays: window.maxAgeDays,\n\t});\n}\n\n/** Where sessions were looked for, and what was passed over — the \"why nothing?\" answer. */\nfunction scanLines(scan: SessionScanReport, window: LearnWindow): string[] {\n\tconst lines: string[] = [\"Looked in\"];\n\tfor (const dir of scan.dirs) {\n\t\tconst missing = scan.missingDirs.includes(dir) ? \"  (does not exist)\" : \"\";\n\t\tlines.push(`  ${displayPath(dir)}${missing}`);\n\t}\n\tlines.push(`Found ${scan.files} session file(s)`);\n\n\tconst skips: string[] = [];\n\tif (scan.tooOld > 0) skips.push(`${scan.tooOld} older than ${window.maxAgeDays} days (learnMaxAgeDays)`);\n\tif (scan.otherCwd > 0) skips.push(`${scan.otherCwd} recorded a different working directory`);\n\tif (scan.overLimit > 0) skips.push(`${scan.overLimit} beyond the newest ${window.maxSessions} (learnMaxSessions)`);\n\tif (scan.unreadable > 0) skips.push(`${scan.unreadable} empty or unreadable`);\n\tfor (const skip of skips) lines.push(`  skipped: ${skip}`);\n\treturn lines;\n}\n\n/**\n * Explain an empty scan rather than asserting there is no history.\n *\n * The old single sentence was wrong as often as it was right: sessions existed,\n * they were simply all outside the window or recorded under another path. Naming\n * the directory searched and the reason each file was passed over turns a dead\n * end into something the reader can fix.\n */\nfunction reportNoSessions(ctx: ExtensionCommandContext, agentDir: string, digest: LearnDigest, window: LearnWindow) {\n\tconst lines: string[] = [];\n\tlines.push(\n\t\tdigest.scan.files === 0\n\t\t\t? \"/learn found no session transcripts for this directory.\"\n\t\t\t: \"/learn found session transcripts, but none inside the current window.\",\n\t);\n\tlines.push(\"\");\n\tlines.push(...scanLines(digest.scan, window));\n\tlines.push(\"\");\n\tlines.push(...settingsLines(ctx, agentDir, window));\n\tctx.ui.notify(lines.join(\"\\n\"), \"warning\");\n}\n\n/**\n * The model that reads transcripts.\n *\n * This is the one call in the pipeline that reads *everything*, so it wants the\n * cheapest capable model rather than the session's. That question already has an\n * answer in this codebase — the `fast` model category, which subagents use for\n * exactly this kind of bulk read — so it is reused rather than reinvented.\n * `settings.modelCategories.fast` wins when set; otherwise the tier is derived\n * from the user's available models, and nothing here is provider-specific.\n *\n * Falls back to the session model when the tier resolves to nothing or to a\n * model the registry cannot find, since a mis-set tier should not take the\n * command out entirely.\n */\nfunction resolveMinerModel(ctx: ExtensionCommandContext, settings: SettingsManager): Model<Api> | undefined {\n\tconst ref = resolveModelCategory(\n\t\t\"fast\",\n\t\t{\n\t\t\tmodelCategories: settings.getModelCategories(),\n\t\t\tdefaultProvider: settings.getDefaultProvider(),\n\t\t\tdefaultModel: settings.getDefaultModel(),\n\t\t},\n\t\tctx.modelRegistry.getAvailable(),\n\t);\n\tif (!ref) return ctx.model;\n\n\tconst slash = ref.indexOf(\"/\");\n\tconst found = slash > 0 ? ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1)) : undefined;\n\treturn found ?? ctx.model;\n}\n\n/** Build the two model-backed stages, or report why they cannot be built. */\nasync function buildPipeline(\n\tctx: ExtensionCommandContext,\n\tsettings: SettingsManager,\n): Promise<{ miner: Miner; coverageJudge: CoverageJudge; model: Model<Api> } | { error: string }> {\n\tconst model = resolveMinerModel(ctx, settings);\n\tif (!model) {\n\t\treturn {\n\t\t\terror: \"/learn reads session transcripts with a model, and no model is selected. Pick one with /model, then run /learn again.\",\n\t\t};\n\t}\n\n\tconst auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);\n\tif (!auth.ok) {\n\t\treturn { error: `/learn could not authenticate ${model.provider}/${model.id}: ${auth.error}` };\n\t}\n\n\tconst deps = { model, apiKey: auth.apiKey, headers: auth.headers };\n\treturn { miner: createLlmMiner(deps), coverageJudge: createLlmCoverageJudge(deps), model };\n}\n\n/**\n * What this run still owes the model.\n *\n * Delegated to `planMining` so the number quoted by the confirmation prompt\n * comes from the same session selection the run will use — same window, same\n * cwd check, same de-duplication.\n */\nfunction pendingWork(ctx: ExtensionCommandContext, agentDir: string, window: LearnWindow) {\n\treturn planMining({\n\t\tcwd: ctx.cwd,\n\t\tagentDir,\n\t\tsessionDir: ctx.sessionManager.getSessionDir(),\n\t\tmaxSessions: window.maxSessions,\n\t\tmaxAgeDays: window.maxAgeDays,\n\t});\n}\n\n/**\n * `/learn stats` — what became of past proposals.\n *\n * Reads the state file and recomputes coverage; it does not re-mine sessions,\n * so it costs one small model call and answers a different question than a\n * normal run: not \"what should I write down\" but \"is this command earning its\n * place\".\n */\nasync function reportStats(ctx: ExtensionCommandContext): Promise<void> {\n\tconst agentDir = getHooCodeDir();\n\tconst settings = SettingsManager.create(ctx.cwd, agentDir);\n\tconst window = settings.getLearnSettings();\n\tconst statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));\n\tconst state = readLearnState(statePath);\n\n\tif (Object.keys(state.surfaced).length === 0) {\n\t\t// Nothing on record means `/learn` has never proposed anything here — which\n\t\t// is as likely to be \"it never found any sessions\" as \"you never ran it\", so\n\t\t// point at both the sessions it can see and the knobs that gate them.\n\t\tconst lines = [\"No /learn history for this directory yet — nothing has been proposed here.\"];\n\t\tlines.push(`  State file  ${displayPath(statePath)}  (not created yet)`);\n\t\tlines.push(\"\");\n\t\tlines.push(...scanLines(sessionScanPreview(ctx, agentDir, window), window));\n\t\tlines.push(\"\");\n\t\tlines.push(...settingsPathLines(ctx, agentDir));\n\t\tlines.push(\"  Run /learn settings for the thresholds in force.\");\n\t\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n\t\treturn;\n\t}\n\n\tconst coverage = buildCoverageIndex({ cwd: ctx.cwd, agentDir });\n\n\t// Coverage is a model judgement now, so it is resolved once for every stored\n\t// label in a single batch and then answered from the resulting set. Asking\n\t// per item would be one call per proposal ever made in this directory.\n\tconst labels = Object.entries(state.surfaced)\n\t\t.filter(([key]) => key.startsWith(\"directive:\"))\n\t\t// Entries recorded before the wording was kept fall back to the slug, which\n\t\t// is a weaker question but still a answerable one.\n\t\t.map(([key, item]) => ({\n\t\t\tlabel: key.slice(\"directive:\".length),\n\t\t\ttext: item.text || key.slice(\"directive:\".length),\n\t\t}));\n\n\tconst covered = new Set<string>();\n\tif (labels.length > 0) {\n\t\tconst pipeline = await buildPipeline(ctx, settings);\n\t\tif (!(\"error\" in pipeline)) {\n\t\t\ttry {\n\t\t\t\tconst verdicts = await pipeline.coverageJudge(labels, coverage);\n\t\t\t\tfor (const [label, match] of verdicts) {\n\t\t\t\t\tif (match.rule || match.skill) covered.add(label);\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Adoption is reported as zero rather than failing the report; the\n\t\t\t\t// caveat below already tells the reader not to over-read the number.\n\t\t\t}\n\t\t}\n\t}\n\n\tconst stats = summarizeLearnState(state, (label) => covered.has(label));\n\n\tconst contextTokens = loadProjectContextFiles({ cwd: ctx.cwd, agentDir }).agentsFiles.reduce(\n\t\t(sum, file) => sum + (file.tokens ?? 0),\n\t\t0,\n\t);\n\n\tconst lines: string[] = [];\n\tlines.push(`/learn history for this directory — ${shortDate(stats.earliest)} to ${shortDate(stats.latest)}`);\n\tlines.push(\n\t\t`  Proposals shown   ${stats.total}  (${stats.directives} directive, ${stats.fixes} fix, ${stats.workflows} workflow)`,\n\t);\n\tif (stats.lastRun) lines.push(`  Last run          ${shortDate(stats.lastRun)}`);\n\tlines.push(\"\");\n\n\tif (stats.open === 0) {\n\t\tlines.push(\"No directive proposals yet, so there is nothing to measure adoption against.\");\n\t} else {\n\t\tconst rate = Math.round((stats.adopted / stats.open) * 100);\n\t\tlines.push(\"Directive adoption — the only category with a coverage signal\");\n\t\tlines.push(`  Written down      ${stats.adopted} of ${stats.open}  (${rate}%)`);\n\t\tlines.push(`  Passed over       ${stats.declined}`);\n\t\tlines.push(\"\");\n\t\t// Without this the number invites the wrong conclusion. Adoption is a proxy\n\t\t// for usefulness, and a proposal correctly rejected as not durable counts\n\t\t// against it exactly like a junk one — so near-100% means the bar is too\n\t\t// low, not that the extractor is perfect.\n\t\tlines.push(\"  A very high rate means the bar is too low, not that every proposal was good.\");\n\t\tlines.push(\"  Near zero means the miner is proposing the wrong things.\");\n\t}\n\n\tlines.push(\"\");\n\tlines.push(`Context files       ~${contextTokens} tokens, re-sent every request`);\n\tlines.push(`State file          ${displayPath(statePath)}`);\n\tlines.push(\"\");\n\tlines.push(...settingsPathLines(ctx, agentDir));\n\tlines.push(\"  Run /learn settings for the thresholds in force.\");\n\n\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n}\n\n/** `/learn settings` — the knobs, their current values, and the files to set them in. */\nfunction reportSettings(ctx: ExtensionCommandContext): void {\n\tconst agentDir = getHooCodeDir();\n\tconst settings = SettingsManager.create(ctx.cwd, agentDir);\n\tconst window = settings.getLearnSettings();\n\tconst lines = settingsLines(ctx, agentDir, window);\n\n\t// The reading model is not a `/learn` setting — it is the shared `fast` tier,\n\t// so name it here rather than leaving the reader to guess which model is\n\t// about to read their history, and point at the setting that changes it.\n\tconst model = resolveMinerModel(ctx, settings);\n\tlines.push(\n\t\t`  reads transcripts with  ${model ? `${model.provider}/${model.id}` : \"no model selected\"}` +\n\t\t\t`   (the \\`fast\\` tier — set modelCategories.fast to change it)`,\n\t);\n\tif (model) {\n\t\tlines.push(\n\t\t\t`  ${Math.round(chunkCharsForModel(model) / 1000)}k characters per call, from its ${model.contextWindow} token window`,\n\t\t);\n\t}\n\n\tlines.push(\"\");\n\tlines.push(...scanLines(sessionScanPreview(ctx, agentDir, window), window));\n\tlines.push(`State file  ${displayPath(getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir)))}`);\n\tconst { pending } = pendingWork(ctx, agentDir, window);\n\tlines.push(\n\t\tpending === 0\n\t\t\t? \"All sessions in the window are already mined; the next /learn costs one small coverage call.\"\n\t\t\t: `${pending} session(s) in the window still need reading, roughly one call each.`,\n\t);\n\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n}\n\nexport function setupLearn(pi: ExtensionAPI): void {\n\tconst guarded = pi as unknown as Record<symbol, boolean>;\n\tif (guarded[REGISTERED]) return;\n\tguarded[REGISTERED] = true;\n\n\tpi.registerCommand(\"learn\", {\n\t\tdescription: \"Mine recent sessions for durable rules and skills. Usage: /learn [all|stats|settings]\",\n\t\tgetArgumentCompletions: (prefix: string) =>\n\t\t\t(\n\t\t\t\t[\n\t\t\t\t\t{ value: \"all\", label: \"re-propose everything\" },\n\t\t\t\t\t{ value: \"stats\", label: \"what happened to past proposals\" },\n\t\t\t\t\t{ value: \"settings\", label: \"where sessions are read from, and the knobs\" },\n\t\t\t\t] as const\n\t\t\t)\n\t\t\t\t.filter((option) => option.value.startsWith(prefix))\n\t\t\t\t.map((option) => ({ value: option.value, label: option.label })),\n\t\thandler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {\n\t\t\tconst argument = args.trim().toLowerCase();\n\t\t\tif (argument && argument !== \"all\" && argument !== \"stats\" && argument !== \"settings\") {\n\t\t\t\tctx.ui.notify(\"Usage: /learn [all|stats|settings]\", \"warning\");\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (argument === \"stats\") {\n\t\t\t\tawait reportStats(ctx);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (argument === \"settings\") {\n\t\t\t\treportSettings(ctx);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst ignoreState = argument === \"all\";\n\n\t\t\t// Read per-invocation so a settings edit takes effect without a reload,\n\t\t\t// and so a project settings.json can narrow the window for one repo.\n\t\t\tconst agentDir = getHooCodeDir();\n\t\t\tconst settings = SettingsManager.create(ctx.cwd, agentDir);\n\t\t\tconst window = settings.getLearnSettings();\n\t\t\tconst statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));\n\n\t\t\tconst pipeline = await buildPipeline(ctx, settings);\n\t\t\tif (\"error\" in pipeline) {\n\t\t\t\tctx.ui.notify(pipeline.error, \"error\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// State the price before charging it. A first run in a busy repo reads\n\t\t\t// every transcript in the window, which is the expensive path by design\n\t\t\t// — but it should never be a surprise, and the cache means it is paid\n\t\t\t// once rather than on every run.\n\t\t\tconst { pending } = pendingWork(ctx, agentDir, window);\n\t\t\tif (pending > CONFIRM_ABOVE_PENDING) {\n\t\t\t\tconst proceed = await ctx.ui.confirm(\n\t\t\t\t\t\"Read session transcripts?\",\n\t\t\t\t\t`${pending} session(s) have not been read yet. /learn reads each one with a model ` +\n\t\t\t\t\t\t`(${pipeline.model.provider}/${pipeline.model.id}) and caches the result, so this cost is paid once ` +\n\t\t\t\t\t\t`per session. Later runs reuse it.`,\n\t\t\t\t);\n\t\t\t\tif (!proceed) {\n\t\t\t\t\tctx.ui.notify(\"/learn cancelled — nothing was read.\", \"info\");\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// A backfill can run for minutes across dozens of transcripts, and the\n\t\t\t// agent is idle throughout — so `ctx.signal` is undefined and there is no\n\t\t\t// ambient way out. Escape gets one.\n\t\t\tconst controller = new AbortController();\n\t\t\tconst unsubscribe = ctx.ui.onTerminalInput((data) => {\n\t\t\t\tif (data !== ESCAPE) return undefined;\n\t\t\t\tcontroller.abort();\n\t\t\t\treturn { consume: true };\n\t\t\t});\n\n\t\t\tlet digest: LearnDigest;\n\t\t\ttry {\n\t\t\t\tdigest = await mineLearnDigest({\n\t\t\t\t\tcwd: ctx.cwd,\n\t\t\t\t\tagentDir,\n\t\t\t\t\t// Searched in addition to the per-cwd default directory, so a session\n\t\t\t\t\t// manager pointing elsewhere (`--session`, a custom `sessionDir`, or\n\t\t\t\t\t// an in-memory session reporting none at all) cannot hide the history.\n\t\t\t\t\tsessionDir: ctx.sessionManager.getSessionDir(),\n\t\t\t\t\tmaxSessions: window.maxSessions,\n\t\t\t\t\tmaxAgeDays: window.maxAgeDays,\n\t\t\t\t\tminRepeats: window.minRepeats,\n\t\t\t\t\tminWorkflowRepeats: window.minWorkflowRepeats,\n\t\t\t\t\tmaxProposals: window.maxProposals,\n\t\t\t\t\tstate: readLearnState(statePath),\n\t\t\t\t\tignoreState,\n\t\t\t\t\tminer: pipeline.miner,\n\t\t\t\t\tcoverageJudge: pipeline.coverageJudge,\n\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t\tonProgress: ({ done, total, cached }) => {\n\t\t\t\t\t\t// The same footer bar the semantic index uses. Cached sessions are\n\t\t\t\t\t\t// counted as done because they are: the bar measures progress\n\t\t\t\t\t\t// through the window, not money spent, and a run that is mostly\n\t\t\t\t\t\t// cache should look nearly finished from the start.\n\t\t\t\t\t\tstartupProgress.set({\n\t\t\t\t\t\t\tkey: PROGRESS_KEY,\n\t\t\t\t\t\t\tkind: \"work\",\n\t\t\t\t\t\t\tlabel:\n\t\t\t\t\t\t\t\tcached > 0\n\t\t\t\t\t\t\t\t\t? `Reading sessions (${cached} cached) — esc to stop`\n\t\t\t\t\t\t\t\t\t: \"Reading sessions — esc to stop\",\n\t\t\t\t\t\t\tdone,\n\t\t\t\t\t\t\ttotal,\n\t\t\t\t\t\t\tunit: \"sessions\",\n\t\t\t\t\t\t});\n\t\t\t\t\t},\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tctx.ui.notify(`/learn could not read session history: ${error}`, \"error\");\n\t\t\t\treturn;\n\t\t\t} finally {\n\t\t\t\tunsubscribe();\n\t\t\t\tstartupProgress.remove(PROGRESS_KEY);\n\t\t\t}\n\n\t\t\t// A cancelled run counted only part of the window, so its numbers are not\n\t\t\t// merely incomplete — they are low. Showing them would be misleading and\n\t\t\t// bookmarking them would hide those items on the next, complete run.\n\t\t\t// Everything read so far is cached, so stopping costs nothing but time.\n\t\t\tif (digest.aborted) {\n\t\t\t\tctx.ui.notify(\n\t\t\t\t\t`/learn stopped — ${digest.mining.mined} session(s) were read and cached, so resuming picks up where this left off.`,\n\t\t\t\t\t\"info\",\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (digest.scannedSessions === 0) {\n\t\t\t\treportNoSessions(ctx, agentDir, digest, window);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tif (isEmptyDigest(digest)) {\n\t\t\t\tconst lines: string[] = [];\n\t\t\t\tlines.push(\n\t\t\t\t\tdigest.suppressed > 0\n\t\t\t\t\t\t? `Read ${digest.scannedSessions} session(s) — nothing new since last time (${digest.suppressed} already shown). Run /learn all to see them again.`\n\t\t\t\t\t\t: `Read ${digest.scannedSessions} session(s) — nothing repeated often enough to be worth a rule yet.`,\n\t\t\t\t);\n\t\t\t\tif (digest.suppressed === 0) {\n\t\t\t\t\t// The thresholds are the reason a scan with real sessions in it came\n\t\t\t\t\t// back empty, so this is the moment they are worth knowing about.\n\t\t\t\t\tlines.push(\"\");\n\t\t\t\t\tlines.push(...settingsLines(ctx, agentDir, window));\n\t\t\t\t}\n\t\t\t\tctx.ui.notify(lines.join(\"\\n\"), \"info\");\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst counts = [\n\t\t\t\tdigest.directives.length > 0 ? `${digest.directives.length} directive(s)` : undefined,\n\t\t\t\tdigest.fixes.length > 0 ? `${digest.fixes.length} fix(es)` : undefined,\n\t\t\t\tdigest.workflows.length > 0 ? `${digest.workflows.length} workflow(s)` : undefined,\n\t\t\t].filter((part): part is string => !!part);\n\t\t\tconst held = digest.suppressed > 0 ? `, ${digest.suppressed} held back` : \"\";\n\t\t\tctx.ui.notify(\n\t\t\t\t`Mined ${digest.scannedSessions} session(s) (${digest.mining.mined} read, ${digest.mining.cached} cached): ${counts.join(\", \")}${held}.`,\n\t\t\t\t\"info\",\n\t\t\t);\n\n\t\t\t// Record before delivering: what matters is that these were put in front\n\t\t\t// of the user, which is true whether or not they act on the digest.\n\t\t\twriteLearnState(statePath, recordSurfaced(readLearnState(statePath), digest.surfaced));\n\n\t\t\tpi.sendUserMessage(\n\t\t\t\trenderLearnDigest(digest, {\n\t\t\t\t\tuserScopePath: displayPath(USER_SCOPE_PATH),\n\t\t\t\t\tmode: ignoreState ? \"all\" : \"incremental\",\n\t\t\t\t}),\n\t\t\t\t{ deliverAs: \"followUp\" },\n\t\t\t);\n\t\t},\n\t});\n}\n"]}

package/dist/extensions/core/learn.js

@@ -2,16 +2,20 @@
  * `/learn` — promote what recent sessions actually taught into durable rules
  * and skills.
  *
- * The command is a thin shell on purpose. It runs the deterministic extractor
- * over session transcripts on disk, renders the ranked result, and injects it
- * as a follow-up message; every judgement after that belongs to the model,
- * which can read the repo and phrase a rule far better than a heuristic can.
+ * The command is a thin shell on purpose. It runs the mining pipeline over
+ * session transcripts on disk, renders the ranked result, and injects it as a
+ * follow-up message; every judgement after that belongs to the model, which can
+ * read the repo and phrase a rule far better than a heuristic can.
  *
  * Reading transcripts from disk rather than the live context is what makes this
  * work: the on-disk history survives compaction, and it spans past sessions, so
  * "you have said this in five separate sessions" is available as a number
  * instead of a guess. That number is the whole reason the command exists.
  *
+ * The pipeline reads every transcript with a model rather than pre-filtering
+ * with regexes, which costs real tokens on a cold cache. That price is stated
+ * before it is paid, never inferred: a run with sessions to read asks first.
+ *
  * Follows /grill in modes.ts: no session switch, no mode change, no config
  * write — just a follow-up message. Writes to AGENTS.md happen through ordinary
  * edit tools, so the existing permission prompt is the approval step and no
@@ -21,15 +25,32 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME, getHooCodeDir } from "../../config.js";
 import { loadProjectContextFiles } from "../../core/context-files.js";
+import { createLlmCoverageJudge } from "../../core/learn/coverage.js";
 import { isEmptyDigest, renderLearnDigest } from "../../core/learn/digest.js";
-import { buildCoverageIndex, extractLearnDigest, matchCoverage, scanSessions, } from "../../core/learn/extract.js";
+import { buildCoverageIndex, mineLearnDigest, planMining, scanSessions, } from "../../core/learn/extract.js";
+import { chunkCharsForModel, createLlmMiner } from "../../core/learn/mine.js";
 import { getLearnStatePath, readLearnState, recordSurfaced, summarizeLearnState, writeLearnState, } from "../../core/learn/state.js";
+import { resolveModelCategory } from "../../core/model-categories.js";
 import { getSessionDirPath } from "../../core/session-manager.js";
 import { SettingsManager } from "../../core/settings-manager.js";
+import { startupProgress } from "../../core/startup-progress.js";
 /** Guards against double-registration when default extensions load more than once. */
 const REGISTERED = Symbol.for("hoocode.learn.registered");
 /** User-scope destination offered for personal rules that travel across repos. */
 const USER_SCOPE_PATH = join(homedir(), ".agents", "AGENTS.md");
+/** Footer key for the mining progress bar. */
+const PROGRESS_KEY = "learn-mining";
+/** Escape, the way a raw terminal delivers it. */
+const ESCAPE = "\x1b";
+/**
+ * Sessions that can be read without asking first.
+ *
+ * A run that has one or two new transcripts to read is the normal daily case
+ * and interrupting it to confirm a trivial cost is noise. Beyond this the run
+ * is a backfill — onboarding to an existing repo, or a first run — and the
+ * reader should get to decide before it starts.
+ */
+const CONFIRM_ABOVE_PENDING = 3;
 /** Render a home-relative path the way the user would type it. */
 function displayPath(path) {
     const home = homedir();
@@ -55,7 +76,7 @@ const SETTING_KEYS = [
 /**
  * Where the knobs live, and what they are set to.
  *
- * `/learn` has five settings and no UI, so until this existed the only way to
+ * `/learn` has its settings and no UI, so until this existed the only way to
  * find them was to already know they were in `settings.json`. Every message that
  * reports a disappointing result names a threshold, so every one of them ends
  * with these lines.
@@ -70,7 +91,7 @@ function settingsPathLines(ctx, agentDir) {
 function settingsLines(ctx, agentDir, window) {
     const lines = settingsPathLines(ctx, agentDir);
     for (const { key, setting, note } of SETTING_KEYS) {
-        lines.push(`  ${setting.padEnd(24)} ${String(window[key]).padStart(3)}   ${note}`);
+        lines.push(`  ${setting.padEnd(24)} ${String(window[key] ?? "—").padStart(3)}   ${note}`);
     }
     return lines;
 }
@@ -86,7 +107,7 @@ function settingsLines(ctx, agentDir, window) {
 function stateKeyDir(ctx, agentDir) {
     return getSessionDirPath(ctx.cwd, agentDir);
 }
-/** Run the directory scan without ranking anything, for the reports that only need counts. */
+/** Run the directory scan without mining anything, for the reports that only need counts. */
 function sessionScanPreview(ctx, agentDir, window) {
     return scanSessions({
         cwd: ctx.cwd,
@@ -136,16 +157,75 @@ function reportNoSessions(ctx, agentDir, digest, window) {
     lines.push(...settingsLines(ctx, agentDir, window));
     ctx.ui.notify(lines.join("\n"), "warning");
 }
+/**
+ * The model that reads transcripts.
+ *
+ * This is the one call in the pipeline that reads *everything*, so it wants the
+ * cheapest capable model rather than the session's. That question already has an
+ * answer in this codebase — the `fast` model category, which subagents use for
+ * exactly this kind of bulk read — so it is reused rather than reinvented.
+ * `settings.modelCategories.fast` wins when set; otherwise the tier is derived
+ * from the user's available models, and nothing here is provider-specific.
+ *
+ * Falls back to the session model when the tier resolves to nothing or to a
+ * model the registry cannot find, since a mis-set tier should not take the
+ * command out entirely.
+ */
+function resolveMinerModel(ctx, settings) {
+    const ref = resolveModelCategory("fast", {
+        modelCategories: settings.getModelCategories(),
+        defaultProvider: settings.getDefaultProvider(),
+        defaultModel: settings.getDefaultModel(),
+    }, ctx.modelRegistry.getAvailable());
+    if (!ref)
+        return ctx.model;
+    const slash = ref.indexOf("/");
+    const found = slash > 0 ? ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1)) : undefined;
+    return found ?? ctx.model;
+}
+/** Build the two model-backed stages, or report why they cannot be built. */
+async function buildPipeline(ctx, settings) {
+    const model = resolveMinerModel(ctx, settings);
+    if (!model) {
+        return {
+            error: "/learn reads session transcripts with a model, and no model is selected. Pick one with /model, then run /learn again.",
+        };
+    }
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+        return { error: `/learn could not authenticate ${model.provider}/${model.id}: ${auth.error}` };
+    }
+    const deps = { model, apiKey: auth.apiKey, headers: auth.headers };
+    return { miner: createLlmMiner(deps), coverageJudge: createLlmCoverageJudge(deps), model };
+}
+/**
+ * What this run still owes the model.
+ *
+ * Delegated to `planMining` so the number quoted by the confirmation prompt
+ * comes from the same session selection the run will use — same window, same
+ * cwd check, same de-duplication.
+ */
+function pendingWork(ctx, agentDir, window) {
+    return planMining({
+        cwd: ctx.cwd,
+        agentDir,
+        sessionDir: ctx.sessionManager.getSessionDir(),
+        maxSessions: window.maxSessions,
+        maxAgeDays: window.maxAgeDays,
+    });
+}
 /**
  * `/learn stats` — what became of past proposals.
  *
  * Reads the state file and recomputes coverage; it does not re-mine sessions,
- * so it is instant and answers a different question than a normal run: not
- * "what should I write down" but "is this command earning its place".
+ * so it costs one small model call and answers a different question than a
+ * normal run: not "what should I write down" but "is this command earning its
+ * place".
  */
-function reportStats(ctx) {
+async function reportStats(ctx) {
     const agentDir = getHooCodeDir();
-    const window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();
+    const settings = SettingsManager.create(ctx.cwd, agentDir);
+    const window = settings.getLearnSettings();
     const statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));
     const state = readLearnState(statePath);
     if (Object.keys(state.surfaced).length === 0) {
@@ -163,10 +243,35 @@ function reportStats(ctx) {
         return;
     }
     const coverage = buildCoverageIndex({ cwd: ctx.cwd, agentDir });
-    const stats = summarizeLearnState(state, (normalized) => {
-        const match = matchCoverage(normalized, coverage);
-        return !!(match.rule || match.skill);
-    });
+    // Coverage is a model judgement now, so it is resolved once for every stored
+    // label in a single batch and then answered from the resulting set. Asking
+    // per item would be one call per proposal ever made in this directory.
+    const labels = Object.entries(state.surfaced)
+        .filter(([key]) => key.startsWith("directive:"))
+        // Entries recorded before the wording was kept fall back to the slug, which
+        // is a weaker question but still a answerable one.
+        .map(([key, item]) => ({
+        label: key.slice("directive:".length),
+        text: item.text || key.slice("directive:".length),
+    }));
+    const covered = new Set();
+    if (labels.length > 0) {
+        const pipeline = await buildPipeline(ctx, settings);
+        if (!("error" in pipeline)) {
+            try {
+                const verdicts = await pipeline.coverageJudge(labels, coverage);
+                for (const [label, match] of verdicts) {
+                    if (match.rule || match.skill)
+                        covered.add(label);
+                }
+            }
+            catch {
+                // Adoption is reported as zero rather than failing the report; the
+                // caveat below already tells the reader not to over-read the number.
+            }
+        }
+    }
+    const stats = summarizeLearnState(state, (label) => covered.has(label));
     const contextTokens = loadProjectContextFiles({ cwd: ctx.cwd, agentDir }).agentsFiles.reduce((sum, file) => sum + (file.tokens ?? 0), 0);
     const lines = [];
     lines.push(`/learn history for this directory — ${shortDate(stats.earliest)} to ${shortDate(stats.latest)}`);
@@ -188,7 +293,7 @@ function reportStats(ctx) {
         // against it exactly like a junk one — so near-100% means the bar is too
         // low, not that the extractor is perfect.
         lines.push("  A very high rate means the bar is too low, not that every proposal was good.");
-        lines.push("  Near zero means the extractor is proposing the wrong things.");
+        lines.push("  Near zero means the miner is proposing the wrong things.");
     }
     lines.push("");
     lines.push(`Context files       ~${contextTokens} tokens, re-sent every request`);
@@ -201,11 +306,25 @@ function reportStats(ctx) {
 /** `/learn settings` — the knobs, their current values, and the files to set them in. */
 function reportSettings(ctx) {
     const agentDir = getHooCodeDir();
-    const window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();
+    const settings = SettingsManager.create(ctx.cwd, agentDir);
+    const window = settings.getLearnSettings();
     const lines = settingsLines(ctx, agentDir, window);
+    // The reading model is not a `/learn` setting — it is the shared `fast` tier,
+    // so name it here rather than leaving the reader to guess which model is
+    // about to read their history, and point at the setting that changes it.
+    const model = resolveMinerModel(ctx, settings);
+    lines.push(`  reads transcripts with  ${model ? `${model.provider}/${model.id}` : "no model selected"}` +
+        `   (the \`fast\` tier — set modelCategories.fast to change it)`);
+    if (model) {
+        lines.push(`  ${Math.round(chunkCharsForModel(model) / 1000)}k characters per call, from its ${model.contextWindow} token window`);
+    }
     lines.push("");
     lines.push(...scanLines(sessionScanPreview(ctx, agentDir, window), window));
     lines.push(`State file  ${displayPath(getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir)))}`);
+    const { pending } = pendingWork(ctx, agentDir, window);
+    lines.push(pending === 0
+        ? "All sessions in the window are already mined; the next /learn costs one small coverage call."
+        : `${pending} session(s) in the window still need reading, roughly one call each.`);
     ctx.ui.notify(lines.join("\n"), "info");
 }
 export function setupLearn(pi) {
@@ -229,7 +348,7 @@ export function setupLearn(pi) {
                 return;
             }
             if (argument === "stats") {
-                reportStats(ctx);
+                await reportStats(ctx);
                 return;
             }
             if (argument === "settings") {
@@ -240,11 +359,41 @@ export function setupLearn(pi) {
             // Read per-invocation so a settings edit takes effect without a reload,
             // and so a project settings.json can narrow the window for one repo.
             const agentDir = getHooCodeDir();
-            const window = SettingsManager.create(ctx.cwd, agentDir).getLearnSettings();
+            const settings = SettingsManager.create(ctx.cwd, agentDir);
+            const window = settings.getLearnSettings();
             const statePath = getLearnStatePath(agentDir, stateKeyDir(ctx, agentDir));
+            const pipeline = await buildPipeline(ctx, settings);
+            if ("error" in pipeline) {
+                ctx.ui.notify(pipeline.error, "error");
+                return;
+            }
+            // State the price before charging it. A first run in a busy repo reads
+            // every transcript in the window, which is the expensive path by design
+            // — but it should never be a surprise, and the cache means it is paid
+            // once rather than on every run.
+            const { pending } = pendingWork(ctx, agentDir, window);
+            if (pending > CONFIRM_ABOVE_PENDING) {
+                const proceed = await ctx.ui.confirm("Read session transcripts?", `${pending} session(s) have not been read yet. /learn reads each one with a model ` +
+                    `(${pipeline.model.provider}/${pipeline.model.id}) and caches the result, so this cost is paid once ` +
+                    `per session. Later runs reuse it.`);
+                if (!proceed) {
+                    ctx.ui.notify("/learn cancelled — nothing was read.", "info");
+                    return;
+                }
+            }
+            // A backfill can run for minutes across dozens of transcripts, and the
+            // agent is idle throughout — so `ctx.signal` is undefined and there is no
+            // ambient way out. Escape gets one.
+            const controller = new AbortController();
+            const unsubscribe = ctx.ui.onTerminalInput((data) => {
+                if (data !== ESCAPE)
+                    return undefined;
+                controller.abort();
+                return { consume: true };
+            });
             let digest;
             try {
-                digest = extractLearnDigest({
+                digest = await mineLearnDigest({
                     cwd: ctx.cwd,
                     agentDir,
                     // Searched in addition to the per-cwd default directory, so a session
@@ -258,12 +407,43 @@ export function setupLearn(pi) {
                     maxProposals: window.maxProposals,
                     state: readLearnState(statePath),
                     ignoreState,
+                    miner: pipeline.miner,
+                    coverageJudge: pipeline.coverageJudge,
+                    signal: controller.signal,
+                    onProgress: ({ done, total, cached }) => {
+                        // The same footer bar the semantic index uses. Cached sessions are
+                        // counted as done because they are: the bar measures progress
+                        // through the window, not money spent, and a run that is mostly
+                        // cache should look nearly finished from the start.
+                        startupProgress.set({
+                            key: PROGRESS_KEY,
+                            kind: "work",
+                            label: cached > 0
+                                ? `Reading sessions (${cached} cached) — esc to stop`
+                                : "Reading sessions — esc to stop",
+                            done,
+                            total,
+                            unit: "sessions",
+                        });
+                    },
                 });
             }
             catch (error) {
                 ctx.ui.notify(`/learn could not read session history: ${error}`, "error");
                 return;
             }
+            finally {
+                unsubscribe();
+                startupProgress.remove(PROGRESS_KEY);
+            }
+            // A cancelled run counted only part of the window, so its numbers are not
+            // merely incomplete — they are low. Showing them would be misleading and
+            // bookmarking them would hide those items on the next, complete run.
+            // Everything read so far is cached, so stopping costs nothing but time.
+            if (digest.aborted) {
+                ctx.ui.notify(`/learn stopped — ${digest.mining.mined} session(s) were read and cached, so resuming picks up where this left off.`, "info");
+                return;
+            }
             if (digest.scannedSessions === 0) {
                 reportNoSessions(ctx, agentDir, digest, window);
                 return;
@@ -271,8 +451,8 @@ export function setupLearn(pi) {
             if (isEmptyDigest(digest)) {
                 const lines = [];
                 lines.push(digest.suppressed > 0
-                    ? `Scanned ${digest.scannedSessions} session(s) — nothing new since last time (${digest.suppressed} already shown). Run /learn all to see them again.`
-                    : `Scanned ${digest.scannedSessions} session(s) — nothing repeated often enough to be worth a rule yet.`);
+                    ? `Read ${digest.scannedSessions} session(s) — nothing new since last time (${digest.suppressed} already shown). Run /learn all to see them again.`
+                    : `Read ${digest.scannedSessions} session(s) — nothing repeated often enough to be worth a rule yet.`);
                 if (digest.suppressed === 0) {
                     // The thresholds are the reason a scan with real sessions in it came
                     // back empty, so this is the moment they are worth knowing about.
@@ -288,13 +468,14 @@ export function setupLearn(pi) {
                 digest.workflows.length > 0 ? `${digest.workflows.length} workflow(s)` : undefined,
             ].filter((part) => !!part);
             const held = digest.suppressed > 0 ? `, ${digest.suppressed} held back` : "";
-            ctx.ui.notify(`Mined ${digest.scannedSessions} session(s): ${counts.join(", ")}${held}.`, "info");
+            ctx.ui.notify(`Mined ${digest.scannedSessions} session(s) (${digest.mining.mined} read, ${digest.mining.cached} cached): ${counts.join(", ")}${held}.`, "info");
             // Record before delivering: what matters is that these were put in front
             // of the user, which is true whether or not they act on the digest.
             writeLearnState(statePath, recordSurfaced(readLearnState(statePath), digest.surfaced));
-            pi.sendUserMessage(renderLearnDigest(digest, { userScopePath: displayPath(USER_SCOPE_PATH) }), {
-                deliverAs: "followUp",
-            });
+            pi.sendUserMessage(renderLearnDigest(digest, {
+                userScopePath: displayPath(USER_SCOPE_PATH),
+                mode: ignoreState ? "all" : "incremental",
+            }), { deliverAs: "followUp" });
         },
     });
 }