keating 0.3.6

package/dist/src/core/pi-agent.js

@@ -0,0 +1,82 @@
+import { spawnSync } from "node:child_process";
+import { loadKeatingConfig, mergePiDefaults } from "./config.js";
+import { configDir } from "./paths.js";
+import { detectAiRuntime } from "../runtime/pi.js";
+/**
+ * Programmatic interface to the AI agent via CLI.
+ * This ensures we use the same provider, model, and thinking settings as the user's agent install.
+ */
+export async function piComplete(cwd, prompt, options = {}) {
+    const config = await loadKeatingConfig(cwd);
+    const runtime = await detectAiRuntime(cwd);
+    if (!runtime.selected) {
+        throw new Error("No AI runtime found. Install `pi` with `npm install -g @mariozechner/pi-coding-agent`, or reinstall Keating so its embedded runtime dependency is present.");
+    }
+    const args = ["-p", "--no-session", "--no-tools", "--no-extensions", "--no-skills"];
+    if (options.systemPrompt) {
+        args.push("--system-prompt", options.systemPrompt);
+    }
+    if (options.json) {
+        args.push("--mode", "json");
+    }
+    if (options.thinking) {
+        args.push("--thinking", options.thinking);
+    }
+    const finalArgs = mergePiDefaults(config, [...args, prompt]);
+    let result;
+    try {
+        const isBinary = runtime.selected.kind === "binary";
+        const command = runtime.selected.command;
+        const spawnArgs = isBinary ? finalArgs : [runtime.selected.cliPath, ...finalArgs];
+        result = spawnSync(command, spawnArgs, {
+            cwd,
+            stdio: "pipe",
+            encoding: "utf8",
+            env: {
+                ...process.env,
+                PI_SKIP_VERSION_CHECK: "1",
+                PI_CODING_AGENT_DIR: configDir(cwd)
+            }
+        });
+    }
+    catch (e) {
+        throw new Error(`Agent command could not be spawned: ${e}`);
+    }
+    if (result.error) {
+        throw new Error(`Agent command failed to launch: ${result.error.message}`);
+    }
+    const signal = result.signal;
+    const exitStatus = result.status;
+    if (exitStatus === null || exitStatus !== 0) {
+        const errMsg = result.stderr?.trim() || result.stdout?.trim() || "unknown error";
+        const exitInfo = exitStatus !== null ? `exit ${exitStatus}` : `killed by signal ${signal ?? "unknown"}`;
+        throw new Error(`Agent completion failed (${exitInfo}): ${errMsg}`);
+    }
+    return result.stdout.trim();
+}
+/**
+ * Specialized helper for JSON completions.
+ */
+export async function piCompleteJson(cwd, prompt, options = {}) {
+    const response = await piComplete(cwd, prompt, { ...options, json: true });
+    try {
+        // Some models output reasoning BEFORE the JSON block.
+        // We try to find all JSON-like blocks and pick the one that parses successfully,
+        // prioritizing the last one.
+        const matches = response.match(/\{[\s\S]*?\}/g);
+        if (!matches)
+            return JSON.parse(response);
+        for (let i = matches.length - 1; i >= 0; i--) {
+            try {
+                return JSON.parse(matches[i]);
+            }
+            catch {
+                continue;
+            }
+        }
+        throw new Error("No valid JSON block found in response.");
+    }
+    catch (error) {
+        throw new Error(`Failed to parse agent JSON response: ${response}\nError: ${error}`);
+    }
+}

package/dist/src/core/policy.js

@@ -0,0 +1,79 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { clamp } from "./util.js";
+export const DEFAULT_POLICY = {
+    name: "keating-default",
+    analogyDensity: 0.72,
+    socraticRatio: 0.66,
+    formalism: 0.64,
+    retrievalPractice: 0.74,
+    exerciseCount: 3,
+    diagramBias: 0.7,
+    reflectionBias: 0.68,
+    interdisciplinaryBias: 0.62,
+    challengeRate: 0.58
+};
+export const DEFAULT_WEIGHTS = {
+    masteryGain: 0.34,
+    retention: 0.20,
+    engagement: 0.16,
+    transfer: 0.18,
+    confusion: 0.18
+};
+export function clampWeights(weights) {
+    const clamped = {
+        masteryGain: clamp(weights.masteryGain, 0.01, 1),
+        retention: clamp(weights.retention, 0.01, 1),
+        engagement: clamp(weights.engagement, 0.01, 1),
+        transfer: clamp(weights.transfer, 0.01, 1),
+        confusion: clamp(weights.confusion, 0.01, 1)
+    };
+    const sum = clamped.masteryGain + clamped.retention + clamped.engagement + clamped.transfer + clamped.confusion;
+    if (sum === 0)
+        return DEFAULT_WEIGHTS;
+    return {
+        masteryGain: clamped.masteryGain / sum,
+        retention: clamped.retention / sum,
+        engagement: clamped.engagement / sum,
+        transfer: clamped.transfer / sum,
+        confusion: clamped.confusion / sum
+    };
+}
+export function clampPolicy(policy) {
+    return {
+        ...policy,
+        analogyDensity: clamp(policy.analogyDensity),
+        socraticRatio: clamp(policy.socraticRatio),
+        formalism: clamp(policy.formalism),
+        retrievalPractice: clamp(policy.retrievalPractice),
+        exerciseCount: Math.min(5, Math.max(1, Math.round(policy.exerciseCount))),
+        diagramBias: clamp(policy.diagramBias),
+        reflectionBias: clamp(policy.reflectionBias),
+        interdisciplinaryBias: clamp(policy.interdisciplinaryBias),
+        challengeRate: clamp(policy.challengeRate)
+    };
+}
+export function policySignature(policy) {
+    return [
+        policy.analogyDensity.toFixed(2),
+        policy.socraticRatio.toFixed(2),
+        policy.formalism.toFixed(2),
+        policy.retrievalPractice.toFixed(2),
+        String(policy.exerciseCount),
+        policy.diagramBias.toFixed(2),
+        policy.reflectionBias.toFixed(2),
+        policy.interdisciplinaryBias.toFixed(2),
+        policy.challengeRate.toFixed(2)
+    ].join("|");
+}
+export async function loadPolicy(filePath) {
+    try {
+        const content = await readFile(filePath, "utf8");
+        return clampPolicy(JSON.parse(content));
+    }
+    catch {
+        return DEFAULT_POLICY;
+    }
+}
+export async function savePolicy(filePath, policy) {
+    await writeFile(filePath, `${JSON.stringify(clampPolicy(policy), null, 2)}\n`, "utf8");
+}

package/dist/src/core/project.js

@@ -0,0 +1,337 @@
+import { readdir, stat, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { loadKeatingConfig } from "./config.js";
+import { writeLessonAnimation } from "./animation.js";
+import { benchmarkToMarkdown, runBenchmarkSuite } from "./benchmark.js";
+import { buildEngagementTimeline, dueTopics, dueTopicsToMarkdown, engagementTimelineToMarkdown, loadEngagementPolicy } from "./engagement.js";
+import { mapElitesEvolve, mapElitesToMarkdown, mapElitesToEvolutionRun } from "./map-elites.js";
+import { buildLessonPlan, lessonPlanToMarkdown } from "./lesson-plan.js";
+import { writeLessonMap } from "./map.js";
+import { evaluatePromptContent, writePromptEvolutionArtifacts } from "./prompt-evolution.js";
+import { animationsDir, benchmarksDir, currentPolicyPath, ensureKeatingDirs, engagementPolicyPath, evolutionDir, mapsDir, plansDir, promptEvolutionDir, timelineDir, tracesDir, verificationsDir, verificationCachePath, learnerStatePath, quizDir, flashcardsDir, projectsDir, workbooksDir, masteryDir } from "./paths.js";
+import { ensureConfig } from "./config.js";
+import { DEFAULT_POLICY, loadPolicy, savePolicy } from "./policy.js";
+import { resolveTopic } from "./topics.js";
+import { slugify } from "./util.js";
+import { buildPendingVerificationResult, buildVerificationChecklist, loadVerificationCache, runCoveVerification, saveVerificationCache, verificationStatus } from "./verification.js";
+import { loadLearnerState } from "./learner-state.js";
+import { generateImprovementArtifact, loadImprovementArchive, improvementHistoryToMarkdown, evaluateImprovement, acceptImprovement, rejectImprovement } from "./self-improve.js";
+import { generateQuiz, quizToMarkdown, quizAnswerKeyToMarkdown, generateWorkbook, workbookToMarkdown } from "./quiz.js";
+import { generateFlashCards, flashcardsToMarkdown } from "./flashcards.js";
+import { generateProject, generateAssignment, projectToMarkdown, assignmentToMarkdown } from "./projects.js";
+import { generateDiagnosticQuestions } from "./mastery.js";
+export async function ensureProjectScaffold(cwd) {
+    await ensureKeatingDirs(cwd);
+    await ensureConfig(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    await savePolicy(currentPolicyPath(cwd), policy ?? DEFAULT_POLICY);
+}
+export async function planTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    const plan = buildLessonPlan(topicName, policy);
+    const planPath = join(plansDir(cwd), `${slugify(topicName)}.md`);
+    await writeFile(planPath, lessonPlanToMarkdown(plan), "utf8");
+    return { planPath };
+}
+export async function mapTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    return writeLessonMap(cwd, topicName, policy);
+}
+export async function animateTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    return writeLessonAnimation(cwd, topicName, policy);
+}
+export async function benchPolicyArtifact(cwd, focusTopic) {
+    await ensureProjectScaffold(cwd);
+    const config = await loadKeatingConfig(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    const result = await runBenchmarkSuite(cwd, policy, focusTopic, 20260401, config.debug.traceTopLearners);
+    const fileName = focusTopic ? `${slugify(focusTopic)}.md` : "core-suite.md";
+    const reportPath = join(benchmarksDir(cwd), fileName);
+    await writeFile(reportPath, benchmarkToMarkdown(result), "utf8");
+    const tracePath = config.debug.persistTraces
+        ? join(tracesDir(cwd), `${focusTopic ? slugify(focusTopic) : "core-suite"}-benchmark.json`)
+        : null;
+    if (tracePath) {
+        await writeFile(tracePath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+    }
+    return { reportPath, tracePath, overallScore: result.overallScore };
+}
+export async function evolvePolicyArtifact(cwd, focusTopic) {
+    await ensureProjectScaffold(cwd);
+    const config = await loadKeatingConfig(cwd);
+    const policyPath = currentPolicyPath(cwd);
+    const basePolicy = await loadPolicy(policyPath);
+    const meRun = await mapElitesEvolve(cwd, basePolicy, { focusTopic });
+    const run = mapElitesToEvolutionRun(meRun);
+    await savePolicy(policyPath, run.best.policy);
+    const fileName = focusTopic ? `${slugify(focusTopic)}.md` : "latest.md";
+    const reportPath = join(evolutionDir(cwd), fileName);
+    await writeFile(reportPath, mapElitesToMarkdown(meRun), "utf8");
+    const tracePath = config.debug.persistTraces
+        ? join(tracesDir(cwd), `${focusTopic ? slugify(focusTopic) : "latest"}-evolution.json`)
+        : null;
+    if (tracePath) {
+        await writeFile(tracePath, `${JSON.stringify(run, null, 2)}\n`, "utf8");
+    }
+    return { reportPath, tracePath, bestScore: run.best.overallScore, policyPath };
+}
+export async function evolvePromptArtifact(cwd, promptName = "learn") {
+    await ensureProjectScaffold(cwd);
+    return writePromptEvolutionArtifacts(cwd, promptName);
+}
+export async function verifyTopicArtifact(cwd, topicName, useLLM = true) {
+    await ensureProjectScaffold(cwd);
+    const topic = resolveTopic(topicName);
+    const cachePath = verificationCachePath(cwd);
+    const cache = await loadVerificationCache(cachePath);
+    const existing = verificationStatus(topic, cache);
+    if (existing && existing.claims.every((c) => c.status !== "unconfirmed")) {
+        return {
+            checklistPath: join(verificationsDir(cwd), `${topic.slug}.md`),
+            alreadyVerified: true,
+            result: existing
+        };
+    }
+    let result;
+    if (useLLM) {
+        try {
+            result = await runCoveVerification(cwd, topic);
+            cache[topic.slug] = result;
+            await saveVerificationCache(cachePath, cache);
+        }
+        catch (error) {
+            console.warn(`CoVe verification failed for ${topic.slug}, falling back to manual checklist:`, error);
+            result = buildPendingVerificationResult(topic);
+        }
+    }
+    else {
+        result = buildPendingVerificationResult(topic);
+    }
+    const checklist = buildVerificationChecklist(topic, result);
+    const checklistPath = join(verificationsDir(cwd), `${topic.slug}.md`);
+    await writeFile(checklistPath, checklist, "utf8");
+    return { checklistPath, alreadyVerified: false, result };
+}
+export async function improveArtifact(cwd) {
+    await ensureProjectScaffold(cwd);
+    return generateImprovementArtifact(cwd);
+}
+export async function improveAccept(cwd, proposalId) {
+    await ensureProjectScaffold(cwd);
+    const evaluation = await evaluateImprovement(cwd, 0);
+    await acceptImprovement(cwd, proposalId, evaluation.afterScore);
+    return { afterScore: evaluation.afterScore, delta: evaluation.delta };
+}
+export async function improveReject(cwd, proposalId, snapshots) {
+    await ensureProjectScaffold(cwd);
+    await rejectImprovement(cwd, proposalId, snapshots);
+}
+export async function improveHistory(cwd) {
+    await ensureProjectScaffold(cwd);
+    const archive = await loadImprovementArchive(cwd);
+    return improvementHistoryToMarkdown(archive);
+}
+export async function autoImproveArtifact(cwd, focusTopic) {
+    await ensureProjectScaffold(cwd);
+    const baseline = await benchPolicyArtifact(cwd, focusTopic);
+    const evolved = await evolvePolicyArtifact(cwd, focusTopic);
+    const promptEvo = await evolvePromptArtifact(cwd, "learn");
+    const after = await benchPolicyArtifact(cwd, focusTopic);
+    const delta = after.overallScore - baseline.overallScore;
+    const report = [
+        `# Auto-Improve Report`,
+        ``,
+        `**Baseline:** ${baseline.overallScore.toFixed(2)}/100`,
+        `**After:** ${after.overallScore.toFixed(2)}/100`,
+        `**Delta:** ${delta >= 0 ? "+" : ""}${delta.toFixed(2)}`,
+        `**Verdict:** ${delta > 0 ? "IMPROVED" : delta < -0.5 ? "REGRESSED" : "NO SIGNIFICANT CHANGE"}`,
+        ``,
+        `## Benchmark`,
+        `- Report: ${relative(cwd, baseline.reportPath)}`,
+        ``,
+        `## Policy Evolution`,
+        `- Best: ${evolved.bestScore.toFixed(2)}/100`,
+        `- Report: ${relative(cwd, evolved.reportPath)}`,
+        ``,
+        `## Prompt Evolution`,
+        `- Best: ${promptEvo.bestScore.toFixed(2)}/100`,
+        `- Report: ${relative(cwd, promptEvo.reportPath)}`,
+        ``,
+    ].join("\n");
+    const reportPath = join(benchmarksDir(cwd), focusTopic ? `${slugify(focusTopic)}-auto-improve.md` : "auto-improve.md");
+    await writeFile(reportPath, report, "utf8");
+    return { baselineScore: baseline.overallScore, afterScore: after.overallScore, delta, reportPath };
+}
+export async function promptEvalArtifact(cwd, promptContent) {
+    await ensureProjectScaffold(cwd);
+    const slug = `eval-${Date.now().toString(36)}`;
+    const tmpPath = join(promptEvolutionDir(cwd), `${slug}.md`);
+    await writeFile(tmpPath, promptContent, "utf8");
+    const result = await evaluatePromptContent(cwd, tmpPath, promptContent);
+    const lines = [
+        `# Prompt Evaluation`,
+        ``,
+        `**Score:** ${result.score.toFixed(2)}/100`,
+        ``,
+        `## Objectives`,
+        ...Object.entries(result.objectives).map(([k, v]) => `- ${k}: ${v.toFixed(2)}`),
+        ``,
+        `## Feedback`,
+        ...(result.feedback.length > 0 ? result.feedback.map((f) => `- ${f}`) : ["- No major issues detected."]),
+    ];
+    const reportPath = join(promptEvolutionDir(cwd), `${slug}-eval.md`);
+    await writeFile(reportPath, lines.join("\n"), "utf8");
+    return { reportPath, score: result.score, objectives: result.objectives, feedback: result.feedback };
+}
+export async function timelineArtifact(cwd) {
+    await ensureProjectScaffold(cwd);
+    const state = await loadLearnerState(learnerStatePath(cwd));
+    const policy = await loadEngagementPolicy(engagementPolicyPath(cwd));
+    const timeline = buildEngagementTimeline(state, policy);
+    const markdown = engagementTimelineToMarkdown(timeline);
+    const reportPath = join(timelineDir(cwd), "latest.md");
+    await writeFile(reportPath, markdown, "utf8");
+    return { reportPath, markdown };
+}
+export async function dueTopicsArtifact(cwd) {
+    await ensureProjectScaffold(cwd);
+    const state = await loadLearnerState(learnerStatePath(cwd));
+    const policy = await loadEngagementPolicy(engagementPolicyPath(cwd));
+    const due = dueTopics(state, policy);
+    const markdown = dueTopicsToMarkdown(due);
+    const reportPath = join(timelineDir(cwd), "due.md");
+    await writeFile(reportPath, markdown, "utf8");
+    return { reportPath, markdown, count: due.length };
+}
+export async function currentPolicySummary(cwd) {
+    await ensureProjectScaffold(cwd);
+    const policy = await loadPolicy(currentPolicyPath(cwd));
+    return [
+        `Policy: ${policy.name}`,
+        `analogyDensity=${policy.analogyDensity.toFixed(2)}`,
+        `socraticRatio=${policy.socraticRatio.toFixed(2)}`,
+        `formalism=${policy.formalism.toFixed(2)}`,
+        `retrievalPractice=${policy.retrievalPractice.toFixed(2)}`,
+        `exerciseCount=${policy.exerciseCount}`,
+        `diagramBias=${policy.diagramBias.toFixed(2)}`,
+        `reflectionBias=${policy.reflectionBias.toFixed(2)}`,
+        `interdisciplinaryBias=${policy.interdisciplinaryBias.toFixed(2)}`,
+        `challengeRate=${policy.challengeRate.toFixed(2)}`
+    ].join("\n");
+}
+export async function quizTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const quiz = generateQuiz(topicName);
+    const slug = quiz.slug;
+    const base = join(quizDir(cwd), slug);
+    await writeFile(`${base}.md`, quizToMarkdown(quiz), "utf8");
+    await writeFile(`${base}-answers.md`, quizAnswerKeyToMarkdown(quiz), "utf8");
+    return { quizPath: `${base}.md`, answersPath: `${base}-answers.md` };
+}
+export async function workbookTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const wb = generateWorkbook(topicName);
+    const wbPath = join(workbooksDir(cwd), `${wb.slug}.md`);
+    await writeFile(wbPath, workbookToMarkdown(wb), "utf8");
+    return { workbookPath: wbPath };
+}
+export async function flashcardsTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const deck = generateFlashCards(topicName);
+    const deckPath = join(flashcardsDir(cwd), `${deck.slug}.md`);
+    await writeFile(deckPath, flashcardsToMarkdown(deck), "utf8");
+    return { flashcardsPath: deckPath };
+}
+export async function projectTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const project = generateProject(topicName);
+    const projectPath = join(projectsDir(cwd), `${project.slug}.md`);
+    await writeFile(projectPath, projectToMarkdown(project), "utf8");
+    return { projectPath };
+}
+export async function assignmentTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const assignment = generateAssignment(topicName);
+    const assignmentPath = join(projectsDir(cwd), `${assignment.slug}-assignment.md`);
+    await writeFile(assignmentPath, assignmentToMarkdown(assignment), "utf8");
+    return { assignmentPath };
+}
+export async function masteryTopicArtifact(cwd, topicName) {
+    await ensureProjectScaffold(cwd);
+    const topic = resolveTopic(topicName);
+    const questions = generateDiagnosticQuestions(topic);
+    const slug = topic.slug;
+    const diagPath = join(masteryDir(cwd), `${slug}-diagnostic.md`);
+    const lines = [
+        `# Diagnostic Questions: ${topic.title}`,
+        "",
+        `> Answer each question in your own words. Self-score using the rubric, or run \`keating assess ${topicName}\` after answering.`,
+        "",
+    ];
+    for (const q of questions) {
+        lines.push(`## ${q.id} [${q.level}]`);
+        lines.push(q.question);
+        lines.push("");
+        lines.push(`**Rubric:** ${q.rubric}`);
+        lines.push("");
+        lines.push(`**Your answer:**`);
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+    }
+    await writeFile(diagPath, lines.join("\n"), "utf8");
+    return { diagPath };
+}
+export async function listArtifacts(cwd) {
+    await ensureProjectScaffold(cwd);
+    const roots = [
+        plansDir(cwd),
+        mapsDir(cwd),
+        animationsDir(cwd),
+        benchmarksDir(cwd),
+        evolutionDir(cwd),
+        promptEvolutionDir(cwd),
+        tracesDir(cwd),
+        verificationsDir(cwd),
+        timelineDir(cwd),
+        quizDir(cwd),
+        flashcardsDir(cwd),
+        projectsDir(cwd),
+        workbooksDir(cwd),
+        masteryDir(cwd)
+    ];
+    const artifacts = [];
+    async function collectFiles(root) {
+        const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name === "_vendor")
+                continue;
+            const fullPath = join(root, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await collectFiles(fullPath)));
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files;
+    }
+    for (const root of roots) {
+        for (const fullPath of await collectFiles(root)) {
+            const info = await stat(fullPath);
+            artifacts.push({
+                label: `${relative(cwd, fullPath)} (${Math.round(info.size / 1024) || 1}KB)`,
+                path: relative(cwd, fullPath),
+                mtime: info.mtimeMs
+            });
+        }
+    }
+    return artifacts
+        .sort((left, right) => right.mtime - left.mtime)
+        .map((artifact) => ({ label: artifact.label, path: artifact.path }));
+}