codecall 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# codecall
+
+`codecall` is an agent-backed skill for Codex and Claude Code that turns a
+completed implementation into a short, evidence-grounded, adaptive learning
+session. It uses the active coding agent that already understands the task and
+repository—there is no additional model call or external context upload.
+
+The MVP deliberately teaches and checks understanding one step at a time:
+
+```text
+collect minimal context → recommend → confidence → lesson → one check-in
+                                              ↑                 ↓
+                                              └── reinforce / advance
+```
+
+It does not throw a fixed quiz at the user. A normal session covers 2–4 related
+concepts, using two checks per concept: a real-world-to-technical mapping and a
+technical application or tradeoff question. A wrong answer produces targeted
+reinforcement and a fresh equivalent check-in; correct answers unlock the next
+prerequisite-ready learning step.
+
+## Install
+
+Install once from GitHub to add the same `codecall` skill to both your local Codex
+and Claude Code skills directories:
+
+```bash
+npm install -g https://github.com/GAURAV-1313/codecall/archive/refs/heads/main.tar.gz
+```
+
+Restart the relevant coding agent or open a new task so it reloads the installed
+skill. This package does not require an additional API key, and its install step
+does not upload your code.
+
+When the package is published to npm, the equivalent registry command will be:
+
+```bash
+npm install -g codecall
+```
+
+## Use it in Codex
+
+After Codex completes an implementation, invoke:
+
+```text
+$codecall
+```
+
+The skill uses the existing conversation and the coding agent's recent edits.
+It can optionally inspect a Git diff when that is useful, but Git is never a
+requirement.
+It first presents a Start/Skip recommendation. After Start, it teaches one
+implementation-specific concept and asks one reasoning question at a time.
+Your answer determines whether it reinforces, deepens, or advances. It finishes
+with concepts covered, weak areas, and an estimated session mastery. The final
+summary also gives implementation-grounded points to remember and only the
+relevant edge cases to check before applying the pattern in another project.
+
+The installable skill source is in [`skill/`](skill/SKILL.md).
+
+## Use it in Claude Code
+
+After Claude Code completes an implementation, invoke:
+
+```text
+/codecall
+```
+
+Claude Code discovers personal skills from `~/.claude/skills/<skill-name>/SKILL.md`.
+The installer creates `~/.claude/skills/codecall/SKILL.md`, using the same
+Agent-Skills-standard instruction file as Codex. It uses Claude Code's current
+conversation and edits—there is no extra learning-model API to configure.
+
+For a repository-level automatic, non-blocking recommendation, add the same
+rule below to `CLAUDE.md` rather than `AGENTS.md`.
+
+### Automatic recommendation
+
+Codex and Claude Code can select the skill implicitly, but skills are not
+background event listeners. `$codecall` (Codex) and `/codecall` (Claude Code) are the
+dependable triggers in any repository.
+
+The policy is intentionally selective: it recommends only when an implementation
+has one strong signal (for example a security boundary, integration, public
+contract, or architecture decision) or two moderate signals (such as a reusable
+pattern plus operational behavior). It skips cosmetic, documentation-only,
+mechanical, generated-only, dependency-only, and ordinary test-only work. The
+full policy is [installed with the skill](skill/references/trigger-policy.md).
+
+To enable it in a project, copy the [Codex template](skill/references/AGENTS.codecall.md)
+into `AGENTS.md` or the [Claude Code template](skill/references/CLAUDE.codecall.md)
+into `CLAUDE.md`:
+
+```md
+Before the normal final response for a completed implementation, read the
+codecall skill's references/trigger-policy.md and evaluate the change. Show Start
+Learning / Skip only for a `recommend` outcome; never teach without Start.
+```
+
+The policy retains only an in-memory concept fingerprint for the current agent
+session, preventing duplicate cards without tracking learning across sessions
+or projects.
+
+## Local demonstration runtime
+
+```bash
+codecall --from-git --task "Add OAuth protected routes"
+```
+
+The terminal command is a local, deterministic demonstration runtime. Use
+`$codecall` in Codex for the primary agent-backed product experience. Use
+`codecall --help` for command options.
+
+## Use it programmatically
+
+```ts
+import { codecall } from "codecall";
+
+const implementation = {
+  task: "Protect account routes using JWT authentication middleware.",
+  changedFiles: [{
+    path: "src/routes.ts",
+    summary: "Adds authentication middleware before account handlers."
+  }]
+};
+
+const runtime = codecall(implementation);
+const session = await runtime.start(implementation);
+
+runtime.decide(session, true);                 // developer chose Start Learning
+await runtime.setConfidence(session, "heard_of_it");
+
+// Render session.currentQuestion. On a user answer:
+await runtime.answer(session, "causal");
+```
+
+Providers render `runtime.history(session.id)` as their native UI: `/codecall`, a
+tool call, or a non-blocking post-task recommendation. Core workers never
+depend on a provider SDK.
+
+## What ships in v1.0.0
+
+- append-only, typed session events and an explicit state machine;
+- progressive minimal context represented as evidence references;
+- explainable opportunity scoring based on concepts and architecture signals,
+  not LOC;
+- separated concept categories, dependency-aware planning, and a bounded plan;
+- an adaptive teach → one MCQ → evaluate → reinforce/advance loop;
+- final transfer guidance: points to remember plus cross-project edge cases;
+- one shared skill installed for Codex and Claude Code;
+- an explainable strong/moderate auto-recommendation policy with session-local
+  duplicate suppression;
+- pluggable worker and documentation-provider contracts;
+- in-memory and caller-owned JSONL event stores;
+- deterministic default workers suitable for local demonstration and tests.
+
+The included deterministic workers support local tests and the terminal demo.
+The installed agent skill is the production path: its reasoning, concept
+selection, teaching, question generation, and evaluation are performed by the
+active coding agent in the existing conversation.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design, privacy posture,
+event model, state machine, and planned provider integrations.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { codecall } from "./public.js";
+function parseArguments(values) {
+    const parsed = { fromGit: false, help: false };
+    for (let index = 0; index < values.length; index += 1) {
+        if (values[index] === "--task")
+            parsed.task = values[++index];
+        else if (values[index] === "--from-git")
+            parsed.fromGit = true;
+        else if (values[index] === "--help" || values[index] === "-h")
+            parsed.help = true;
+        else
+            throw new Error(`Unknown argument: ${values[index]}`);
+    }
+    return parsed;
+}
+function help() {
+    console.log(`Usage: codecall --task "Describe the implementation" [--from-git]
+
+Starts an adaptive learning session. --from-git adds changed-file summaries and
+small excerpts from the current working tree. For the full agent-backed
+experience, invoke $codecall in Codex after completing an implementation.`);
+}
+function changedFilesFromGit() {
+    const options = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] };
+    try {
+        // Porcelain status includes staged, unstaged, and newly-created files, even
+        // in a repository that has not created its first commit yet.
+        const names = execFileSync("git", ["status", "--porcelain"], options)
+            .split("\n")
+            .map((line) => line.slice(3).trim())
+            .map((path) => path.includes(" -> ") ? path.split(" -> ").at(-1) : path)
+            .filter(Boolean);
+        return names.slice(0, 12).map((path) => {
+            let excerpt;
+            try {
+                excerpt = readFileSync(path, "utf8").slice(0, 1_500);
+            }
+            catch { /* deleted or binary file */ }
+            return { path, summary: "Changed in the current Git diff.", excerpt };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function latest(events, type) {
+    return [...events].reverse().find((event) => event.type === type)?.payload;
+}
+function printLesson(lesson) {
+    console.log(`\n${lesson.title}\n${lesson.what}\n\nWhy here: ${lesson.whyHere}\nWhat breaks: ${lesson.failureMode}\nMental model: ${lesson.mentalModel}`);
+}
+async function main() {
+    const args = parseArguments(process.argv.slice(2));
+    if (args.help)
+        return help();
+    const rl = createInterface({ input, output });
+    try {
+        const task = args.task ?? await rl.question("What implementation did you complete? ");
+        const implementation = { task, changedFiles: args.fromGit ? changedFilesFromGit() : [] };
+        const runtime = codecall(implementation);
+        const session = await runtime.start(implementation);
+        const opportunity = session.opportunity;
+        console.log(`\nLearning opportunity: ${opportunity.recommendation} · ${opportunity.estimatedMinutes} minutes\n${opportunity.reasoning.join(" ")}`);
+        const accepted = /^(y|yes)$/i.test(await rl.question("Start learning? [y/N] "));
+        runtime.decide(session, accepted);
+        if (!accepted) {
+            console.log("Learning skipped.");
+            return;
+        }
+        const confidence = (await rl.question("Confidence [expert / comfortable / heard_of_it / never_learned]: ")).trim();
+        if (!["expert", "comfortable", "heard_of_it", "never_learned"].includes(confidence)) {
+            throw new Error("Choose expert, comfortable, heard_of_it, or never_learned.");
+        }
+        await runtime.setConfidence(session, confidence);
+        let renderedLessonCount = 0;
+        while (session.state === "quiz" && session.currentQuestion) {
+            const events = runtime.history(session.id);
+            const lessons = events.filter((event) => event.type === "LESSON_READY");
+            if (lessons.length > renderedLessonCount) {
+                printLesson(latest(events, "LESSON_READY"));
+                renderedLessonCount = lessons.length;
+            }
+            const question = session.currentQuestion;
+            console.log(`\n${question.prompt}`);
+            question.choices.forEach((choice, index) => console.log(`  ${index + 1}. ${choice.text}`));
+            const selected = Number(await rl.question("Your answer: ")) - 1;
+            const choice = question.choices[selected];
+            if (!choice) {
+                console.log("Choose one of the displayed numbers.");
+                continue;
+            }
+            await runtime.answer(session, choice.id);
+            const feedback = latest(runtime.history(session.id), "ANSWER_EVALUATED");
+            if (feedback)
+                console.log(`\n${feedback.feedback}`);
+        }
+        if (session.summary)
+            console.log(`\nSession complete\nMastery: ${session.summary.estimatedSessionMastery}\nTakeaways:\n- ${session.summary.keyTakeaways.join("\n- ")}\nPoints to remember:\n- ${session.summary.pointsToRemember.join("\n- ")}\nEdge cases for other projects:\n- ${session.summary.edgeCasesForOtherProjects.join("\n- ")}`);
+    }
+    finally {
+        rl.close();
+    }
+}
+main().catch((error) => { console.error(error instanceof Error ? error.message : error); process.exitCode = 1; });

package/dist/install-skill.d.ts

@@ -0,0 +1,4 @@
+/** Copy the packaged skill into Codex's discoverable skill directory. */
+export declare function installSkill(destinationRoot?: string): string;
+/** Copy the same Agent Skills-standard skill into Claude Code's personal directory. */
+export declare function installClaudeSkill(destinationRoot?: string): string;

package/dist/install-skill.js

@@ -0,0 +1,40 @@
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function packagedSkillSource() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "..", "skill");
+}
+function copySkill(destinationRoot) {
+    const source = packagedSkillSource();
+    if (!existsSync(source))
+        throw new Error(`Packaged skill source was not found: ${source}`);
+    mkdirSync(destinationRoot, { recursive: true });
+    const destination = join(destinationRoot, "codecall");
+    cpSync(source, destination, { recursive: true, force: true });
+    const legacySkill = join(destinationRoot, "learn");
+    if (existsSync(legacySkill))
+        rmSync(legacySkill, { recursive: true, force: true });
+    return destination;
+}
+/** Copy the packaged skill into Codex's discoverable skill directory. */
+export function installSkill(destinationRoot = process.env.CODEX_HOME ? join(process.env.CODEX_HOME, "skills") : join(homedir(), ".codex", "skills")) {
+    return copySkill(destinationRoot);
+}
+/** Copy the same Agent Skills-standard skill into Claude Code's personal directory. */
+export function installClaudeSkill(destinationRoot = process.env.CLAUDE_CONFIG_DIR ? join(process.env.CLAUDE_CONFIG_DIR, "skills") : join(homedir(), ".claude", "skills")) {
+    return copySkill(destinationRoot);
+}
+const invokedAsScript = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (invokedAsScript) {
+    if (process.argv.includes("--global-only") && process.env.npm_config_global !== "true")
+        process.exit(0);
+    try {
+        console.log(`Installed Codex skill at ${installSkill()}`);
+        console.log(`Installed Claude Code skill at ${installClaudeSkill()}`);
+    }
+    catch (error) {
+        console.warn(`Could not install the codecall skill: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/policy/opportunity.d.ts

@@ -0,0 +1,12 @@
+import type { ImplementationContext, LearningOpportunity } from "../schemas/types.js";
+/**
+ * Deterministic parity policy for the agent-backed skill. It is deliberately
+ * evidence-based and selective; it is not the production authority on a
+ * conversation's technical meaning.
+ */
+export declare function evaluateLearningOpportunity(context: ImplementationContext): LearningOpportunity;
+/** Deduplicates concept clusters for the lifetime of one runtime/session only. */
+export declare class SessionOpportunityDeduper {
+    private readonly evaluatedFingerprints;
+    evaluate(context: ImplementationContext): LearningOpportunity;
+}

package/dist/policy/opportunity.js

@@ -0,0 +1,126 @@
+const strongRules = [
+    { id: "external_contract_or_integration", match: /\b(oauth|webhook|sdk|integration|third[- ]party|api endpoint|public api|protocol|schema|migration|openapi|graphql)\b/i },
+    { id: "architecture_or_cross_component_flow", match: /\b(middleware|pipeline|cross[- ]?(service|component)|event[- ]?driven|controller|service layer|handler|boundary)\b/i },
+    { id: "security_or_reliability_boundary", match: /\b(auth(?:entication|orization)?|jwt|token|permission|security|encrypt|concurrenc\w*|race condition|retry|backoff|timeout|idempoten\w*|transaction|consisten\w*|failure handling|error handling)\b/i },
+    { id: "consequential_tradeoff", match: /\b(trade[- ]?off|design decision|chose|choose|instead of|compatib(?:ility|le)|backward[- ]?compatible)\b/i }
+];
+const moderateRules = [
+    { id: "reusable_pattern_or_lifecycle", match: /\b(adapter|strategy|factory|observer|cache|queue|algorithm|state machine|lifecycle|framework)\b/i },
+    { id: "operational_behavior", match: /\b(config(?:uration)?|environment variable|feature flag|log(?:ging)?|metric|trace|observability|validat(?:e|ion)|test harness|fixture|mock|e2e|ci|deploy(?:ment)?)\b/i }
+];
+const excludedRules = [
+    { id: "formatting_or_copy", match: /\b(format(?:ting)?|prettier|lint(?:ing)?|whitespace|copy change|comment(?:s)?|typo)\b/i },
+    { id: "documentation_only", match: /\b(readme|documentation|docs?|changelog)\b/i },
+    { id: "mechanical_rename", match: /\b(rename|renaming|move(?:d)? files?)\b/i },
+    { id: "dependency_bump", match: /\b(dependency|package) (?:bump|update|upgrade)\b/i },
+    { id: "straightforward_local_fix", match: /\b(simple|straightforward|localized|local) (?:bug )?fix\b/i }
+];
+function implementationText(context) {
+    const { implementation } = context;
+    return `${implementation.task} ${implementation.conversationSummary ?? ""} ${implementation.changedFiles.map((file) => `${file.path} ${file.summary} ${file.excerpt ?? ""}`).join(" ")}`;
+}
+function isGenerated(file) {
+    return /(^|\/)(dist|build|coverage|generated)(\/|$)|\.(lock|snap)$/i.test(file.path) || /generated file/i.test(file.summary);
+}
+function isTestFile(file) {
+    return /(^|\/)(test|tests|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$/i.test(file.path);
+}
+function isDocumentationFile(file) {
+    return /(^|\/)(readme|changelog|docs?)(\/|\.|$)|\.(md|mdx|txt)$/i.test(file.path);
+}
+function isDependencyFile(file) {
+    return /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|composer\.lock|poetry\.lock)$/i.test(file.path);
+}
+function uniqueMatches(text, rules) {
+    return rules.filter((rule) => rule.match.test(text)).map((rule) => rule.id);
+}
+function sourceLabel(context) {
+    const file = context.implementation.changedFiles.find((candidate) => !isGenerated(candidate));
+    if (file)
+        return file.path;
+    const evidence = context.evidence.find((candidate) => candidate.path || candidate.label);
+    return evidence?.path ?? evidence?.label ?? "the completed implementation";
+}
+/**
+ * Deterministic parity policy for the agent-backed skill. It is deliberately
+ * evidence-based and selective; it is not the production authority on a
+ * conversation's technical meaning.
+ */
+export function evaluateLearningOpportunity(context) {
+    const { implementation } = context;
+    const text = implementationText(context);
+    const excludedChangeCategories = uniqueMatches(text, excludedRules);
+    if (implementation.changedFiles.some(isGenerated))
+        excludedChangeCategories.push("generated_or_lockfile_change");
+    const inspectable = Boolean(implementation.task.trim()) && (context.evidence.length > 0 || implementation.changedFiles.length > 0);
+    const strongSignals = uniqueMatches(text, strongRules);
+    const moderateSignals = uniqueMatches(text, moderateRules);
+    const changedSourceFiles = implementation.changedFiles.filter((file) => !isGenerated(file) && !isTestFile(file) && !isDocumentationFile(file) && !isDependencyFile(file));
+    const testFiles = implementation.changedFiles.filter(isTestFile);
+    const testStrategy = moderateSignals.includes("operational_behavior");
+    if (changedSourceFiles.length >= 2 && /\b(import|depend(?:s|ency|ent)|consumer|producer|route|service|handler)\b/i.test(text)) {
+        moderateSignals.push("cross_component_dependency");
+    }
+    if (testFiles.length > 0 && changedSourceFiles.length === 0 && !testStrategy)
+        excludedChangeCategories.push("test_only_without_strategy");
+    const uniqueStrong = [...new Set(strongSignals)];
+    const uniqueModerate = [...new Set(moderateSignals)];
+    const meaningfulEvidence = changedSourceFiles.length > 0 || (testFiles.length > 0 && testStrategy);
+    const onlyExcluded = implementation.changedFiles.length > 0 && !meaningfulEvidence;
+    const conceptFingerprint = `learning-policy/v1:${[...uniqueStrong, ...uniqueModerate].sort().join("+") || "no-meaningful-cluster"}`;
+    if (!inspectable || onlyExcluded) {
+        const reason = !inspectable
+            ? "Skipped automatic learning because the completed implementation lacks inspectable task or file evidence."
+            : `Skipped automatic learning because the change is limited to ${[...new Set(excludedChangeCategories)].join(", ")}.`;
+        return {
+            score: 0,
+            confidence: 0.9,
+            estimatedMinutes: 0,
+            recommendation: "skip",
+            signals: {},
+            strongSignals: uniqueStrong,
+            moderateSignals: uniqueModerate,
+            excludedChangeCategories: [...new Set(excludedChangeCategories)],
+            conceptFingerprint,
+            reasoning: [reason, "Manual /codecall or $codecall remains available."]
+        };
+    }
+    const recommendation = uniqueStrong.length >= 1 || uniqueModerate.length >= 2
+        ? "recommend"
+        : uniqueModerate.length === 1 ? "optional" : "skip";
+    const score = Number(Math.min(1, uniqueStrong.length * 0.65 + uniqueModerate.length * 0.3).toFixed(2));
+    const signalNames = [...uniqueStrong, ...uniqueModerate];
+    const reason = signalNames.length
+        ? `Implementation evidence in ${sourceLabel(context)} indicates ${signalNames.join(", ")}.`
+        : `No strong signal or pair of moderate signals was found in ${sourceLabel(context)}.`;
+    return {
+        score,
+        confidence: 0.8,
+        estimatedMinutes: recommendation === "recommend" ? Math.min(8, 3 + signalNames.length) : recommendation === "optional" ? 3 : 0,
+        recommendation,
+        signals: Object.fromEntries([...uniqueStrong.map((id) => [id, 1]), ...uniqueModerate.map((id) => [id, 0.5])]),
+        strongSignals: uniqueStrong,
+        moderateSignals: uniqueModerate,
+        excludedChangeCategories: [...new Set(excludedChangeCategories)],
+        conceptFingerprint,
+        reasoning: [reason, "Decision is based on implementation evidence and policy signals, never line count."]
+    };
+}
+/** Deduplicates concept clusters for the lifetime of one runtime/session only. */
+export class SessionOpportunityDeduper {
+    evaluatedFingerprints = new Set();
+    evaluate(context) {
+        const opportunity = evaluateLearningOpportunity(context);
+        if (this.evaluatedFingerprints.has(opportunity.conceptFingerprint)) {
+            return {
+                ...opportunity,
+                recommendation: "skip",
+                estimatedMinutes: 0,
+                excludedChangeCategories: [...opportunity.excludedChangeCategories, "already_evaluated_in_session"],
+                reasoning: [`Skipped automatic learning because ${opportunity.conceptFingerprint} was already evaluated in this session.`, "Manual /codecall or $codecall remains available."]
+            };
+        }
+        this.evaluatedFingerprints.add(opportunity.conceptFingerprint);
+        return opportunity;
+    }
+}

package/dist/public.d.ts

@@ -0,0 +1,12 @@
+import type { ImplementationLocator } from "./schemas/types.js";
+import { LearnRuntime } from "./runtime/orchestrator.js";
+/** Creates the provider-neutral MVP capability. Providers render its emitted events however they choose. */
+/**
+ * Local demonstration runtime. The production experience is the agent-backed
+ * Codex skill, which uses the active coding agent's reasoning directly.
+ */
+export declare function codecall(implementation: ImplementationLocator): LearnRuntime;
+export * from "./schemas/types.js";
+export * from "./policy/opportunity.js";
+export * from "./runtime/orchestrator.js";
+export * from "./runtime/event-store.js";

package/dist/public.js

@@ -0,0 +1,24 @@
+import { MemoryEventStore } from "./runtime/event-store.js";
+import { LearnRuntime, contextFromImplementation } from "./runtime/orchestrator.js";
+import { DefaultContextCollector, DependencyLearningPlanner, DeterministicEvaluationEngine, GroundedTeachingEngine, HeuristicConceptExtractor, HeuristicOpportunityDetector, NoopDocumentationResolver, ReasoningQuizEngine } from "./workers/default-workers.js";
+/** Creates the provider-neutral MVP capability. Providers render its emitted events however they choose. */
+/**
+ * Local demonstration runtime. The production experience is the agent-backed
+ * Codex skill, which uses the active coding agent's reasoning directly.
+ */
+export function codecall(implementation) {
+    return new LearnRuntime({
+        contextCollector: new DefaultContextCollector(contextFromImplementation(implementation)),
+        opportunityDetector: new HeuristicOpportunityDetector(),
+        conceptExtractor: new HeuristicConceptExtractor(),
+        learningPlanner: new DependencyLearningPlanner(),
+        documentationResolver: new NoopDocumentationResolver(),
+        teachingEngine: new GroundedTeachingEngine(),
+        quizEngine: new ReasoningQuizEngine(),
+        evaluationEngine: new DeterministicEvaluationEngine()
+    }, new MemoryEventStore());
+}
+export * from "./schemas/types.js";
+export * from "./policy/opportunity.js";
+export * from "./runtime/orchestrator.js";
+export * from "./runtime/event-store.js";

package/dist/runtime/event-store.d.ts

@@ -0,0 +1,20 @@
+import type { LearnEvent } from "../schemas/types.js";
+export interface EventStore {
+    append(event: LearnEvent): void;
+    read(sessionId: string): LearnEvent[];
+}
+export declare class MemoryEventStore implements EventStore {
+    private readonly events;
+    append(event: LearnEvent): void;
+    read(sessionId: string): LearnEvent[];
+}
+/**
+ * A deliberately small caller-owned persistence option. The runtime never
+ * chooses a storage location or sends events elsewhere; the adapter supplies it.
+ */
+export declare class JsonlEventStore implements EventStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    append(event: LearnEvent): void;
+    read(sessionId: string): LearnEvent[];
+}

package/dist/runtime/event-store.js

@@ -0,0 +1,32 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+export class MemoryEventStore {
+    events = [];
+    append(event) {
+        this.events.push(structuredClone(event));
+    }
+    read(sessionId) {
+        return this.events.filter((event) => event.sessionId === sessionId).map((event) => structuredClone(event));
+    }
+}
+/**
+ * A deliberately small caller-owned persistence option. The runtime never
+ * chooses a storage location or sends events elsewhere; the adapter supplies it.
+ */
+export class JsonlEventStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    append(event) {
+        appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf8");
+    }
+    read(sessionId) {
+        if (!existsSync(this.filePath))
+            return [];
+        return readFileSync(this.filePath, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line))
+            .filter((event) => event.sessionId === sessionId);
+    }
+}

package/dist/runtime/orchestrator.d.ts

@@ -0,0 +1,28 @@
+import type { ConfidenceLevel, ImplementationContext, ImplementationLocator, LearnEvent, Session } from "../schemas/types.js";
+import type { EventStore } from "./event-store.js";
+import type { ConceptExtractor, ContextCollector, DocumentationResolver, EvaluationEngine, LearningPlanner, OpportunityDetector, QuizEngine, TeachingEngine } from "../workers/contracts.js";
+export interface RuntimeWorkers {
+    contextCollector: ContextCollector;
+    opportunityDetector: OpportunityDetector;
+    conceptExtractor: ConceptExtractor;
+    learningPlanner: LearningPlanner;
+    documentationResolver: DocumentationResolver;
+    teachingEngine: TeachingEngine;
+    quizEngine: QuizEngine;
+    evaluationEngine: EvaluationEngine;
+}
+export declare class LearnRuntime {
+    private readonly workers;
+    private readonly events;
+    constructor(workers: RuntimeWorkers, events: EventStore);
+    start(implementation: ImplementationLocator): Promise<Session>;
+    decide(session: Session, accepted: boolean): Session;
+    setConfidence(session: Session, confidence: ConfidenceLevel): Promise<Session>;
+    answer(session: Session, choiceId: string): Promise<Session>;
+    cancel(session: Session, reason?: string): Session;
+    history(sessionId: string): LearnEvent[];
+    private presentCurrentLearningStep;
+    private summarize;
+    private emit;
+}
+export declare function contextFromImplementation(implementation: ImplementationLocator): ImplementationContext;