keating 0.3.6

package/dist/src/runtime/pi.js

@@ -0,0 +1,343 @@
+import { existsSync, statSync, readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { FALLBACK_PI_MODELS, loadKeatingConfig, mergePiDefaultsWithOverrides } from "../core/config.js";
+import { ensureProjectScaffold } from "../core/project.js";
+import { sessionsDir, configDir } from "../core/paths.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function resolvePackageRoot() {
+    const override = process.env.KEATING_PACKAGE_ROOT_OVERRIDE;
+    if (override)
+        return resolve(override);
+    const normalizedDir = __dirname.replace(/\\/g, "/");
+    return normalizedDir.includes("/dist/src/runtime")
+        ? join(__dirname, "..", "..", "..")
+        : join(__dirname, "..", "..");
+}
+function missingRuntimeMessage(report) {
+    if (report.preference === "standalone-only") {
+        return [
+            "Keating is configured for standalone-only but no `pi` AI agent binary was found on PATH.",
+            "",
+            "Recover with one of:",
+            "  npm install -g @mariozechner/pi-coding-agent",
+            "  keating setup",
+            "  edit keating.config.json and set pi.runtimePreference to prefer-standalone"
+        ].join("\n");
+    }
+    if (report.preference === "embedded-only") {
+        return [
+            "Keating is configured for embedded-only but no embedded AI agent was found.",
+            "",
+            "Recover with one of:",
+            "  npm install -g @mariozechner/pi-coding-agent",
+            "  keating setup",
+            "  npm install -g keating"
+        ].join("\n");
+    }
+    return [
+        "Could not find an AI runtime.",
+        "",
+        "Recover with one of:",
+        "  npm install -g @mariozechner/pi-coding-agent",
+        "  npm install -g keating",
+        "  curl -fsSL https://raw.githubusercontent.com/Diogenesoftoronto/keating/main/scripts/install/install.sh | bash"
+    ].join("\n");
+}
+function resolveStandaloneAgent() {
+    const result = spawnSync("which", ["pi"], { encoding: "utf8", env: process.env });
+    if (result.status === 0 && result.stdout.trim()) {
+        const command = result.stdout.trim();
+        const versionResult = spawnSync(command, ["--version"], { encoding: "utf8", env: process.env });
+        if (versionResult.status === 0 && /^\d+\.\d+\.\d+/.test(versionResult.stdout.trim())) {
+            return {
+                kind: "binary",
+                command
+            };
+        }
+    }
+    return null;
+}
+const CLI_AGENT_PACKAGES = [
+    ["@interleavelove", "keating-coding-agent"],
+    ["@mariozechner", "pi-coding-agent"],
+];
+async function syncPiSettings(cwd, config) {
+    const agentDir = configDir(cwd);
+    const settingsPath = join(agentDir, "settings.json");
+    let settings = {};
+    try {
+        const parsed = JSON.parse(await readFile(settingsPath, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            settings = parsed;
+        }
+    }
+    catch {
+        settings = {};
+    }
+    const quietStartup = !config.debug.consoleSummary;
+    if (settings.quietStartup === quietStartup)
+        return;
+    await mkdir(agentDir, { recursive: true });
+    await writeFile(settingsPath, `${JSON.stringify({ ...settings, quietStartup }, null, 2)}\n`, "utf8");
+}
+const PROVIDER_ENV_KEYS = {
+    google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    anthropic: ["ANTHROPIC_OAUTH_TOKEN", "ANTHROPIC_API_KEY"]
+};
+const PROVIDER_SETUP_HINTS = {
+    google: [
+        "export GEMINI_API_KEY=your_google_ai_studio_key",
+        "or run `keating setup` and choose another provider"
+    ],
+    openai: [
+        "export OPENAI_API_KEY=your_openai_key",
+        "or run `keating setup` and choose another provider"
+    ],
+    anthropic: [
+        "export ANTHROPIC_API_KEY=your_anthropic_key",
+        "or run `keating setup` and choose another provider"
+    ]
+};
+function hasFlag(args, flag) {
+    return args.includes(flag) || args.some((arg) => arg.startsWith(`${flag}=`));
+}
+function flagValue(args, flag) {
+    const equalsArg = args.find((arg) => arg.startsWith(`${flag}=`));
+    if (equalsArg)
+        return equalsArg.slice(flag.length + 1);
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function authJsonHasProvider(cwd, provider) {
+    const path = join(configDir(cwd), "auth.json");
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Boolean(parsed?.[provider]);
+    }
+    catch {
+        return false;
+    }
+}
+function envHasProvider(env, provider) {
+    return (PROVIDER_ENV_KEYS[provider] ?? []).some((key) => Boolean(env[key]));
+}
+function providerIsConfigured(cwd, env, provider) {
+    return envHasProvider(env, provider) || authJsonHasProvider(cwd, provider);
+}
+function envWithProviderAliases(env) {
+    if (!env.GEMINI_API_KEY && env.GOOGLE_API_KEY) {
+        return { ...env, GEMINI_API_KEY: env.GOOGLE_API_KEY };
+    }
+    return { ...env };
+}
+function providerSetupMessage(provider) {
+    const hints = PROVIDER_SETUP_HINTS[provider] ?? [
+        `set the API key expected by provider "${provider}"`,
+        "or run `keating setup` and choose a configured provider"
+    ];
+    return [
+        `No credentials found for provider "${provider}".`,
+        "",
+        "Recover with:",
+        ...hints.map((hint) => `  ${hint}`),
+        "  pi /login",
+        "",
+        "Then retry: keating shell"
+    ].join("\n");
+}
+function selectAuthenticatedProvider(cwd, config, args) {
+    const env = envWithProviderAliases(process.env);
+    if (hasFlag(args, "--list-models") || hasFlag(args, "--list-providers"))
+        return { env };
+    const hasExplicitProvider = hasFlag(args, "--provider");
+    const hasExplicitModel = hasFlag(args, "--model");
+    const hasExplicitApiKey = hasFlag(args, "--api-key");
+    const configuredProvider = config.pi.defaultProvider ?? "google";
+    if (hasExplicitProvider) {
+        const provider = flagValue(args, "--provider");
+        if (provider && !hasExplicitApiKey && PROVIDER_ENV_KEYS[provider] && !providerIsConfigured(cwd, env, provider)) {
+            throw new Error(providerSetupMessage(provider));
+        }
+        return { env };
+    }
+    const candidates = [configuredProvider, "google", "openai", "anthropic"].filter((provider, index, all) => provider && all.indexOf(provider) === index);
+    const selected = candidates.find((provider) => providerIsConfigured(cwd, env, provider));
+    if (!selected) {
+        throw new Error([
+            providerSetupMessage(configuredProvider),
+            "",
+            "Keating also checked for OpenAI and Anthropic credentials and did not find them.",
+            "Supported fallback env vars:",
+            "  GEMINI_API_KEY or GOOGLE_API_KEY",
+            "  OPENAI_API_KEY",
+            "  ANTHROPIC_API_KEY or ANTHROPIC_OAUTH_TOKEN"
+        ].join("\n"));
+    }
+    if (selected === configuredProvider)
+        return { env };
+    return {
+        provider: selected,
+        model: hasExplicitModel ? undefined : FALLBACK_PI_MODELS[selected],
+        env,
+        note: `No credentials found for "${configuredProvider}". Using configured ${selected} credentials instead.`
+    };
+}
+function resolveAgentInNodeModules(nodeModulesDir) {
+    for (const [scope, pkg] of CLI_AGENT_PACKAGES) {
+        const cliPath = join(nodeModulesDir, scope, pkg, "dist", "cli.js");
+        if (existsSync(cliPath)) {
+            return { kind: "embedded-keating", command: process.execPath, cliPath };
+        }
+    }
+    return null;
+}
+async function resolveEmbeddedAgent(packageRoot = resolvePackageRoot()) {
+    const local = resolveAgentInNodeModules(join(packageRoot, "node_modules"));
+    if (local)
+        return local;
+    const base = join(homedir(), ".local", "share", "keating");
+    const entries = await readdir(base, { withFileTypes: true }).catch(() => []);
+    const dirs = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .reverse();
+    for (const name of dirs) {
+        for (const root of [join(base, name), join(base, name, "app")]) {
+            const embedded = resolveAgentInNodeModules(join(root, "node_modules"));
+            if (embedded)
+                return embedded;
+        }
+    }
+    for (const [scope, pkg] of CLI_AGENT_PACKAGES) {
+        const globalPrefix = join(homedir(), ".local", "share", "mise", "installs", "node");
+        const versionEntries = await readdir(globalPrefix, { withFileTypes: true }).catch(() => []);
+        const versionDirs = versionEntries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+            .reverse();
+        for (const ver of versionDirs) {
+            const cliPath = join(globalPrefix, ver, "lib", "node_modules", scope, pkg, "dist", "cli.js");
+            if (existsSync(cliPath)) {
+                return { kind: "embedded-keating", command: process.execPath, cliPath };
+            }
+            const nmDir = join(globalPrefix, ver, "lib", "node_modules");
+            const nmEntries = await readdir(nmDir, { withFileTypes: true }).catch(() => []);
+            const nmDirs = nmEntries.filter((e) => e.isDirectory() || (e.isSymbolicLink() && statSync(join(nmDir, e.name)).isDirectory()));
+            for (const nmEntry of nmDirs) {
+                const nested = join(nmDir, nmEntry.name, "node_modules", scope, pkg, "dist", "cli.js");
+                if (existsSync(nested)) {
+                    return { kind: "embedded-keating", command: process.execPath, cliPath: nested };
+                }
+            }
+        }
+        const bunGlobal = join(homedir(), ".bun", "install", "global", "node_modules", scope, pkg, "dist", "cli.js");
+        if (existsSync(bunGlobal)) {
+            return { kind: "embedded-keating", command: process.execPath, cliPath: bunGlobal };
+        }
+    }
+    return null;
+}
+export async function detectAiRuntime(cwd) {
+    const config = await loadKeatingConfig(cwd);
+    const standalone = resolveStandaloneAgent();
+    const embedded = await resolveEmbeddedAgent();
+    let selected = null;
+    switch (config.pi.runtimePreference) {
+        case "embedded-only":
+            selected = embedded;
+            break;
+        case "prefer-standalone":
+            selected = standalone ?? embedded;
+            break;
+        case "standalone-only":
+        default:
+            selected = standalone;
+            break;
+    }
+    return {
+        selected,
+        standalone,
+        embedded,
+        preference: config.pi.runtimePreference
+    };
+}
+export async function launchShell(cwd, args) {
+    await ensureProjectScaffold(cwd);
+    const config = await loadKeatingConfig(cwd);
+    await syncPiSettings(cwd, config);
+    const report = await detectAiRuntime(cwd);
+    const runtime = report.selected;
+    if (!runtime) {
+        throw new Error(missingRuntimeMessage(report));
+    }
+    const packageRoot = resolvePackageRoot();
+    const isDist = __dirname.replace(/\\/g, "/").includes("/dist/src/runtime");
+    const extensionPath = isDist
+        ? join(__dirname, "..", "pi", "hyperteacher-extension.js")
+        : join(packageRoot, "dist", "src", "pi", "hyperteacher-extension.js");
+    if (!existsSync(extensionPath)) {
+        throw new Error([
+            `Missing built extension: ${extensionPath}.`,
+            "",
+            "Recover with:",
+            "  bun run build",
+            "  npm run build",
+            "",
+            "If this came from an installed package, reinstall Keating:",
+            "  npm install -g keating"
+        ].join("\n"));
+    }
+    const promptDir = join(packageRoot, "pi", "prompts");
+    const skillsDir = join(packageRoot, "pi", "skills");
+    const systemPromptPath = join(packageRoot, "SYSTEM.md");
+    const systemPrompt = readFileSync(systemPromptPath, "utf8");
+    const authSelection = selectAuthenticatedProvider(cwd, config, args);
+    if (authSelection.note) {
+        console.error(authSelection.note);
+    }
+    const sharedArgs = mergePiDefaultsWithOverrides(config, [
+        "--session-dir",
+        sessionsDir(cwd),
+        "--extension",
+        extensionPath,
+        "--prompt-template",
+        promptDir,
+        "--skill",
+        skillsDir,
+        "--append-system-prompt",
+        systemPrompt,
+        "--tools",
+        "read,bash,edit,write,grep,find,ls",
+        ...args
+    ], { provider: authSelection.provider, model: authSelection.model });
+    const child = runtime.kind === "binary"
+        ? spawn(runtime.command, sharedArgs, {
+            cwd,
+            stdio: "inherit",
+            env: {
+                ...authSelection.env,
+                PI_SKIP_VERSION_CHECK: process.env.PI_SKIP_VERSION_CHECK ?? "1",
+                PI_CODING_AGENT_DIR: configDir(cwd)
+            }
+        })
+        : spawn(runtime.command, [runtime.cliPath, ...sharedArgs], {
+            cwd,
+            stdio: "inherit",
+            env: {
+                ...authSelection.env,
+                PI_SKIP_VERSION_CHECK: process.env.PI_SKIP_VERSION_CHECK ?? "1",
+                PI_CODING_AGENT_DIR: configDir(cwd)
+            }
+        });
+    return await new Promise((resolvePromise, reject) => {
+        child.on("error", reject);
+        child.on("exit", (code) => resolvePromise(code ?? 0));
+    });
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "keating",
+  "version": "0.3.6",
+  "type": "module",
+  "description": "A Pi-powered hyperteacher package with self-improving teaching policies, lesson maps, and animated visual teaching artifacts.",
+  "keywords": [
+    "pi-package",
+    "hyperteacher",
+    "education",
+    "feynman-style",
+    "teaching-agent",
+    "ai-education",
+    "cognitive-empowerment"
+  ],
+  "author": "Diogenes of Toronto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Diogenesoftoronto/keating.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Diogenesoftoronto/keating/issues"
+  },
+  "homepage": "https://keating.help",
+  "bin": {
+    "keating": "bin/keating.js"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "files": [
+    "bin/keating.js",
+    "dist/",
+    "pi/",
+    "scripts/install/",
+    "SYSTEM.md",
+    "web/dist/"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/src/pi"
+    ],
+    "skills": [
+      "./pi/skills"
+    ],
+    "prompts": [
+      "./pi/prompts"
+    ]
+  },
+  "scripts": {
+    "build": "bun x tsc -p tsconfig.json && cd web && bun run build",
+    "test": "bun test ./test/*.test.ts",
+    "video:intro": "bun scripts/render-keating-intro.mjs",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@ax-llm/ax": "^19.0.43",
+    "@google/generative-ai": "^0.24.1",
+    "@mariozechner/pi-coding-agent": "^0.73.1",
+    "dotenv": "^17.4.0",
+    "h3": "^2.0.1-rc.20",
+    "ink": "^7.0.3",
+    "manim-web": "^0.3.16",
+    "nitro": "^3.0.260311-beta",
+    "react": "^19.2.5"
+  },
+  "devDependencies": {
+    "@remotion/cli": "^4.0.455",
+    "@remotion/media-utils": "^4.0.455",
+    "@remotion/renderer": "^4.0.455",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "fast-check": "^4.6.0",
+    "react-dom": "^19.2.5",
+    "remotion": "^4.0.455"
+  }
+}

package/pi/prompts/bridge.md

@@ -0,0 +1,14 @@
+---
+description: Bridge a concept across domains including science, math, philosophy, code, law, history, psychology, medicine, arts, and politics so the learner sees what transfers and what does not.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Bridge the following concept across domains: $@
+
+Structure:
+
+1. Define the core invariant idea.
+2. Show how that idea appears in at least two domains.
+3. Point out where the analogy stops working.
+4. End with a transfer question for the learner.

package/pi/prompts/diagnose.md

@@ -0,0 +1,15 @@
+---
+description: Diagnose what a learner already understands, where they are confused, and what to teach next.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Diagnose the learner's current state on: $@
+
+Requirements:
+
+0. If `.keating/state/learner.json` exists, read the learner's identified misconceptions and mastery estimates before asking diagnostic questions. Use prior state to focus your questions.
+1. Ask at most three high-information questions before explaining.
+2. Infer likely misconceptions from the answers.
+3. Separate "missing prerequisite", "partial intuition", and "formal gap".
+4. End with a proposed next teaching step, not a full lecture.

package/pi/prompts/improve.md

@@ -0,0 +1,39 @@
+---
+description: Run the self-improvement loop — diagnose benchmark weaknesses and propose code changes.
+args: [history]
+section: Meta-Evolution
+topLevelCli: true
+---
+Run the Keating self-improvement pipeline.
+
+If the argument is "history", show the improvement attempt archive:
+- Run `/improve history` and display the result.
+
+Otherwise, generate a new improvement proposal:
+
+1. Run `/improve` to diagnose benchmark weaknesses and generate a proposal.
+2. Read the proposal file under `.keating/outputs/improvements/`.
+3. The proposal contains:
+   - A ranked list of diagnosed weaknesses (from benchmark traces).
+   - Specific target files that may be modified.
+   - Structured instructions for what to change and why.
+   - Safety rules: which files are mutable vs immutable.
+
+4. Execute the proposed changes:
+   - Only modify files listed in the proposal's `targets`.
+   - Never modify: `self-improve.ts`, `types.ts`, `config.ts`, `paths.ts`, `random.ts`.
+   - Before each edit, explain what you are changing and why.
+   - Keep changes minimal and focused on the diagnosed weakness.
+
+5. After making changes, run the benchmark to evaluate:
+   - `keating bench` to get the new score.
+   - Compare against the before-score in the proposal.
+   - If the score improved or held steady, the change is accepted.
+   - If the score dropped, revert your changes.
+
+6. Report the outcome: what changed, before/after scores, and whether the change was kept or rolled back.
+
+Safety contract:
+- The self-improvement loop modifies teaching logic (lesson plans, benchmark weights, animations, topic definitions, maps, policy defaults).
+- It never modifies the improvement engine itself, type definitions, configuration, or the random seed system.
+- Every attempt is archived with snapshots so changes can always be rolled back.

package/pi/prompts/learn.md

@@ -0,0 +1,21 @@
+---
+description: Teach a concept adaptively with a mastery-first lesson loop.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Teach the learner the following topic: $@
+
+Workflow:
+
+0. Before teaching, check `.keating/outputs/verifications/` for this topic. If no verification checklist exists, run `/verify <topic>` yourself — do not ask the user to do it. Do not present unverified factual claims as settled truth.
+0b. Check `.keating/state/learner.json` for prior coverage of this topic. If the learner has seen it before, skip orientation and go straight to retrieval practice or misconception repair.
+1. Start with a short diagnostic question or assumption check.
+2. Move through intuition before formal structure.
+3. Repair the likeliest misconception explicitly.
+4. Give at least one worked example.
+5. Ask for retrieval or reconstruction, not just agreement.
+6. End by bridging the topic to another domain or a practical consequence.
+
+If a matching Keating artifact already exists under `.keating/outputs/plans/` or `.keating/outputs/maps/`, read it and use it.
+If it does not exist and a structured lesson would help, run `/plan <topic>` or `/map <topic>` yourself. Never ask the user to run commands for you.

package/pi/prompts/quiz.md

@@ -0,0 +1,14 @@
+---
+description: Quiz a learner on a topic with feedback that reveals misconceptions instead of just scoring answers.
+args: <topic>
+section: Teaching Workflows
+topLevelCli: true
+---
+Run a short mastery quiz on: $@
+
+Rules:
+
+1. Ask one question at a time.
+2. Mix recall, transfer, and misconception-revealing prompts.
+3. After each answer, say what the answer shows about understanding.
+4. If the learner misses something, teach the minimum needed correction before continuing.

package/pi/skills/adaptive-teaching/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: adaptive-teaching
+description: Use when the user wants to learn, be taught, be quizzed, or understand an idea across any domain — science, math, philosophy, code, law, politics, psychology, medicine, arts, or history — with active scaffolding.
+---
+
+# Adaptive Teaching
+
+Use this skill when the user asks to learn a concept rather than merely receive a summary.
+
+## Teaching Contract
+
+1. Diagnose first if the learner state is unknown. Check `.keating/state/learner.json` for prior coverage.
+2. Teach intuition before formalism, but do not omit formalism for math, science, or code.
+3. Surface one misconception early.
+4. Use retrieval and reconstruction prompts, not just exposition.
+5. End with transfer, reflection, or a next challenge.
+6. Verify factual claims before teaching. If `.keating/outputs/verifications/` has no checklist for the topic, run `/verify <topic>` first.
+
+## Keating Artifacts
+
+- Run `/plan <topic>` yourself when a lesson plan would help — do not ask the user to do it.
+- Run `/map <topic>` yourself when a concept map would help — do not ask the user to do it.
+- Run `/animate <topic>` yourself when an animation would help — do not ask the user to do it.
+- Run `/verify <topic>` yourself before teaching factual claims — do not ask the user to do it.
+- Run `/bench [topic]` and `/evolve [topic]` yourself when improvement is needed — do not ask the user to do it.
+- Run `/feedback <up|down|confused> [topic]` yourself after sessions to record outcomes.
+
+## Red Flags
+
+- Do not drown the learner in formal language before a concrete hook exists.
+- Do not act as though the synthetic benchmark proves pedagogical truth.
+- Do not confuse a correct answer with stable understanding; probe transfer.
+- Do not present unverified factual claims as settled truth. If verification artifacts exist, consult them. If claims are flagged as unconfirmed, hedge appropriately.