@seanhogg/builderforce-memory-mcp 2026.9.28 → 2026.9.30

package/src/experience/tools.ts

@@ -0,0 +1,363 @@
+/**
+ * Experience tools — what Evermind has DONE, over MCP.
+ *
+ * The same framework-neutral {@link MemoryTool}s as the memory tools, registered
+ * beside them when experience is on. Every result is JSON: Synapse drives these as a
+ * program (record → review → compile → run → audit), and a model reads JSON as well.
+ * The domain rules — Train Once, approval gates, routines, the corpus — are the
+ * engine's; these handlers only validate input and move data through the store.
+ */
+
+import { z } from "zod";
+import type { Episode, ReviewEdits, Run, RunStatus, SkillRoutine, StepOutcome } from "@seanhogg/builderforce-memory-engine";
+import { fail, okJson, type MemoryTool, type ToolResult } from "../tool-core.js";
+import { isSafeExperienceId } from "./file-store.js";
+import type { ExperienceHost } from "./host.js";
+import { experienceIndex, pendingDocuments, trainExperience } from "./train.js";
+
+const DEFAULT_RUNS = 50;
+const MAX_RUNS_RETURNED = 500;
+
+const editsShape = z
+    .object({
+        name: z.string().nullable().optional(),
+        removed: z.array(z.string()).optional(),
+        fixed: z.array(z.string()).optional(),
+        approvals: z.record(z.boolean()).optional(),
+        paramNames: z.record(z.string()).optional(),
+    })
+    .optional()
+    .describe("Review edits keyed by recorded step id.");
+
+const scheduleShape = z.union([
+    z.object({ every: z.literal("minutes"), minutes: z.number().int().min(1).max(10_080) }),
+    z.object({ every: z.literal("day"), hour: z.number().int().min(0).max(23), minute: z.number().int().min(0).max(59) }),
+]);
+
+const ACTION_KINDS = new Set(["click", "setValue", "keys"]);
+
+const isTarget = (t: unknown): boolean =>
+    !!t && typeof t === "object" && typeof (t as { name?: unknown }).name === "string";
+
+/**
+ * Why one recorded action is unusable, or null. Every field the corpus and replay read
+ * is checked here, so one malformed step is refused at save time instead of making
+ * every later `experience_train` throw.
+ */
+function actionProblem(a: Record<string, unknown>): string | null {
+    switch (a["kind"]) {
+        case "click":
+            return isTarget(a["target"]) ? null : "a click needs a target element";
+        case "setValue":
+            if (!isTarget(a["target"])) return "a setValue needs a target element";
+            return typeof a["value"] === "string" ? null : "a setValue needs a string value (empty for a secret)";
+        case "keys":
+            if (typeof a["keys"] !== "string" || !a["keys"]) return "a keys action needs its keys";
+            return a["target"] == null || isTarget(a["target"]) ? null : "a keys target must be an element";
+        default:
+            return "the action kind must be click, setValue or keys";
+    }
+}
+
+/** Accept a recorder's episode, or say what is wrong with it. */
+export function asEpisode(raw: unknown, newId: () => string): Episode | string {
+    const e = raw as Partial<Episode> | null;
+    if (!e || typeof e !== "object") return "episode must be an object.";
+    if (typeof e.name !== "string" || !e.name.trim()) return "episode.name is required.";
+    if (typeof e.program !== "string" || !e.program) return "episode.program is required.";
+    if (!Array.isArray(e.steps)) return "episode.steps must be an array.";
+    for (const [i, s] of e.steps.entries()) {
+        if (!s || typeof s.id !== "string" || !s.action || !ACTION_KINDS.has(s.action.kind)) {
+            return `episode.steps[${i}] needs an id and an action of kind click, setValue or keys.`;
+        }
+        const problem = actionProblem(s.action as unknown as Record<string, unknown>);
+        if (problem) return `episode.steps[${i}]: ${problem}.`;
+    }
+    // A secret field records THAT it was filled, never the value: whatever a recorder
+    // sent, a secret value is not stored (and so never returned by episode_get).
+    const steps = e.steps.map((s) =>
+        s.action.kind === "setValue" && s.action.secret ? { ...s, action: { ...s.action, value: "" } } : s,
+    );
+    const id = typeof e.id === "string" && e.id ? e.id : newId();
+    if (!isSafeExperienceId(id)) return "episode.id may use letters, digits, '-' and '_' only.";
+    return {
+        id,
+        name: e.name.trim(),
+        program: e.program,
+        args: Array.isArray(e.args) ? e.args.map(String) : [],
+        startedAt: typeof e.startedAt === "number" ? e.startedAt : Date.now(),
+        endedAt: typeof e.endedAt === "number" ? e.endedAt : null,
+        steps,
+    };
+}
+
+/** A tool whose thrown errors come back as tool errors named after it. */
+function tool(
+    name: string,
+    description: string,
+    inputSchema: z.ZodRawShape,
+    run: (args: Record<string, unknown>) => Promise<ToolResult>,
+): MemoryTool {
+    return {
+        name,
+        description,
+        inputSchema,
+        handler: async (args) => {
+            try {
+                return await run(args);
+            } catch (err) {
+                return fail(`${name} failed: ${String(err)}`);
+            }
+        },
+    };
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/** This machine's time zone as minutes east of UTC — what the engine's routines expect. */
+function localOffsetMinutes(): number {
+    return -new Date().getTimezoneOffset();
+}
+
+export function buildExperienceTools(host: ExperienceHost): MemoryTool[] {
+    const { store, engine } = host;
+
+    const episodeTools = [
+        tool(
+            "experience_info",
+            "Where experience is kept and how much there is: the memory and experience snapshot files, the screenshot folder, the private model it trains, and counts.",
+            {},
+            async () => {
+                const snap = await store.snapshot();
+                return okJson({
+                    memoryFile: host.memoryFile,
+                    file: host.file,
+                    episodesDir: host.episodesDir,
+                    modelFile: host.modelFile ?? null,
+                    episodes: snap.episodes.length,
+                    skills: snap.skills.length,
+                    runs: snap.runs.length,
+                    learned: Object.keys(snap.learned).length,
+                });
+            },
+        ),
+        tool(
+            "experience_overview",
+            "What experience says about the brain, for drawing it: counts per region (hippocampus = demonstrations, basalGanglia = skills, amygdala = approval decisions, hypothalamus = routines, neocortex = procedures the private model has learned), learned vs pending, run outcomes, every adaptation's measured loss, activity per local day, and the newest events.",
+            { days: z.number().int().min(1).max(365).optional() },
+            async (args) => {
+                const version = await host.modelVersion();
+                const overview = engine.experienceOverview(await store.snapshot(), {
+                    modelIndex: version ? experienceIndex(version) : 0,
+                    now: Date.now(),
+                    utcOffsetMinutes: localOffsetMinutes(),
+                    days: typeof args["days"] === "number" ? args["days"] : undefined,
+                });
+                return okJson({ modelVersion: version, ...overview });
+            },
+        ),
+        tool(
+            "episode_save",
+            "Save a recorded demonstration (an episode: a program, and the UI steps a person took in it). Returns its id. Screenshots belong in <episodesDir>/<id>/.",
+            { episode: z.record(z.unknown()).describe("The episode, in the engine's Episode shape.") },
+            async (args) => {
+                const episode = asEpisode(args["episode"], engine.newExperienceId);
+                if (typeof episode === "string") return fail(episode);
+                await store.putEpisode(episode);
+                return okJson({ id: episode.id });
+            },
+        ),
+        tool("episode_list", "List recorded demonstrations, newest first (summaries only).", {}, async () =>
+            okJson(await store.listEpisodes()),
+        ),
+        tool("episode_get", "Fetch one demonstration with all of its steps.", { id: z.string() }, async (args) => {
+            const e = await store.getEpisode(str(args["id"]));
+            return e ? okJson(e) : fail(`No episode "${str(args["id"])}".`);
+        }),
+        tool(
+            "episode_forget",
+            "Delete a demonstration and its screenshots. Skills compiled from it keep working.",
+            { id: z.string() },
+            async (args) => okJson({ forgotten: await store.deleteEpisode(str(args["id"])) }),
+        ),
+        tool(
+            "experience_forget_all",
+            "Delete every demonstration, screenshot, skill and run. Facts (memories) and the model are not touched. Requires confirm: true.",
+            { confirm: z.literal(true) },
+            async () => {
+                await store.clear();
+                return okJson({ forgotten: true });
+            },
+        ),
+    ];
+
+    /** Train Once over a stored episode — ONE path for preview (no save) and compile (save). */
+    async function compile(args: Record<string, unknown>, save: boolean): Promise<ToolResult> {
+        const episode = await store.getEpisode(str(args["episodeId"]));
+        if (!episode) return fail(`No episode "${str(args["episodeId"])}".`);
+        const skill = engine.trainOnce(episode, (args["edits"] as ReviewEdits | undefined) ?? {});
+        if (save) await store.putSkill(skill);
+        return okJson(skill);
+    }
+
+    const skillTools = [
+        tool(
+            "skill_preview",
+            "Show the skill Train Once would compile from a demonstration with these review edits, without saving it.",
+            { episodeId: z.string(), edits: editsShape },
+            (a) => compile(a, false),
+        ),
+        tool(
+            "skill_compile",
+            "Compile a demonstration into a runnable skill (Train Once) and save it.",
+            { episodeId: z.string(), edits: editsShape },
+            (a) => compile(a, true),
+        ),
+        tool("skill_list", "List skills, newest first.", {}, async () => okJson(await store.listSkills())),
+        tool("skill_get", "Fetch one skill.", { id: z.string() }, async (args) => {
+            const s = await store.getSkill(str(args["id"]));
+            return s ? okJson(s) : fail(`No skill "${str(args["id"])}".`);
+        }),
+        tool("skill_forget", "Delete a skill (its run history stays).", { id: z.string() }, async (args) =>
+            okJson({ forgotten: await store.deleteSkill(str(args["id"])) }),
+        ),
+        tool(
+            "skill_schedule",
+            "Give a skill a routine (every N minutes, or daily at a local time, with values for its non-secret parameters), or pass null to remove it.",
+            {
+                id: z.string(),
+                routine: z
+                    .object({
+                        schedule: scheduleShape,
+                        values: z.record(z.string()).default({}),
+                        enabled: z.boolean().default(true),
+                    })
+                    .nullable(),
+            },
+            async (args) => {
+                const skill = await store.getSkill(str(args["id"]));
+                if (!skill) return fail(`No skill "${str(args["id"])}".`);
+                const r = args["routine"] as Omit<SkillRoutine, "lastRunAt"> | null;
+                // Routine values are stored in plain JSON, so a secret parameter's value is
+                // never kept here — secrets come from the host's vault at run time.
+                const secret = new Set(skill.params.filter((p) => p.secret).map((p) => p.name));
+                const values = r ? Object.fromEntries(Object.entries(r.values).filter(([k]) => !secret.has(k))) : {};
+                skill.routine = r ? { ...r, values, lastRunAt: skill.routine?.lastRunAt ?? null } : null;
+                await store.putSkill(skill);
+                return okJson(skill);
+            },
+        ),
+        tool(
+            "skills_due",
+            "Skills whose routine is due now, least recently run first.",
+            {
+                tzOffsetMinutes: z
+                    .number()
+                    .int()
+                    .min(-840)
+                    .max(840)
+                    .optional()
+                    .describe("Local offset east of UTC; defaults to this machine's."),
+            },
+            async (args) => {
+                const tz = args["tzOffsetMinutes"];
+                const offset = typeof tz === "number" ? tz : localOffsetMinutes();
+                return okJson(engine.dueSkills(await store.listSkills(), Date.now(), offset));
+            },
+        ),
+    ];
+
+    const runTools = [
+        tool(
+            "run_start",
+            "Start a run of a skill. A routine run also marks the routine as run, so it is not due again until its next slot.",
+            { skillId: z.string(), trigger: z.enum(["manual", "routine"]) },
+            async (args) => {
+                const skill = await store.getSkill(str(args["skillId"]));
+                if (!skill) return fail(`No skill "${str(args["skillId"])}".`);
+                const now = Date.now();
+                const run: Run = {
+                    id: engine.newExperienceId(),
+                    skillId: skill.id,
+                    skillName: skill.name,
+                    trigger: str(args["trigger"]),
+                    status: "running",
+                    startedAt: now,
+                    steps: [],
+                };
+                await store.putRun(run);
+                if (run.trigger === "routine" && skill.routine) {
+                    skill.routine.lastRunAt = now;
+                    await store.putSkill(skill);
+                }
+                return okJson(run);
+            },
+        ),
+        tool(
+            "run_step",
+            "Append one line to a run's audit trail.",
+            {
+                runId: z.string(),
+                idx: z.number().int().min(0),
+                stepId: z.string(),
+                outcome: z.enum(["ok", "fallback", "failed", "approved", "denied"]),
+                detail: z.string().nullable().optional(),
+            },
+            async (args) => {
+                const logged = await store.appendRunStep(str(args["runId"]), {
+                    idx: Number(args["idx"]),
+                    stepId: str(args["stepId"]),
+                    outcome: args["outcome"] as StepOutcome,
+                    detail: typeof args["detail"] === "string" ? args["detail"] : null,
+                    at: Date.now(),
+                });
+                return logged ? okJson({ logged }) : fail(`No run "${str(args["runId"])}".`);
+            },
+        ),
+        tool(
+            "run_finish",
+            "Close a run with its final status.",
+            { runId: z.string(), status: z.enum(["succeeded", "failed", "stopped", "denied"]), error: z.string().nullable().optional() },
+            async (args) => {
+                const run = await store.getRun(str(args["runId"]));
+                if (!run) return fail(`No run "${str(args["runId"])}".`);
+                run.status = args["status"] as RunStatus;
+                run.endedAt = Date.now();
+                run.error = typeof args["error"] === "string" ? args["error"] : null;
+                await store.putRun(run);
+                return okJson(run);
+            },
+        ),
+        tool(
+            "run_list",
+            "Recent runs, newest first.",
+            { limit: z.number().int().min(1).max(MAX_RUNS_RETURNED).optional() },
+            async (args) => okJson(await store.listRuns(Number(args["limit"] ?? DEFAULT_RUNS))),
+        ),
+        tool("run_get", "Fetch one run with its audit trail.", { id: z.string() }, async (args) => {
+            const r = await store.getRun(str(args["id"]));
+            return r ? okJson(r) : fail(`No run "${str(args["id"])}".`);
+        }),
+    ];
+
+    const learnTools = [
+        tool(
+            "experience_train",
+            "Teach the private Evermind model the procedures it has not learned yet (each skill, and each demonstration not yet compiled into one). Pass dryRun to only count them. The previous model is kept beside the new one.",
+            { dryRun: z.boolean().optional() },
+            async (args) => {
+                if (!host.modelFile) return fail("No private Evermind model is configured (set BUILDERFORCE_MEMORY_MODEL).");
+                const model = await host.loadModel();
+                if (!model) return fail(`Could not load an evermind-lm package and its tokenizer from ${host.modelFile}.`);
+                if (args["dryRun"] === true) {
+                    const version = model.pkg.manifest.version ?? "0";
+                    const pending = (await pendingDocuments(store, engine, version)).length;
+                    return okJson({ status: "dry_run", pending, version });
+                }
+                return okJson(await trainExperience(store, engine, model, host.modelFile));
+            },
+        ),
+    ];
+
+    return [...episodeTools, ...skillTools, ...runTools, ...learnTools];
+}

package/src/experience/train.ts

@@ -0,0 +1,96 @@
+/**
+ * Teach the person's private Evermind what they have done.
+ *
+ * Experience becomes text through the engine (`experienceDocuments`: each skill or
+ * uncompiled demonstration as a written procedure), and the text becomes weights
+ * through the engine's ONE adaptation recipe (`adaptPackage`). This module only
+ * decides what is new, runs the passes over the local model file and writes the
+ * result back, keeping the previous model beside it.
+ *
+ * "What is new" is the store's learned ledger. Every adaptation writes `<base>+expN`
+ * and records N against each procedure it learned, so a loaded model trusts exactly
+ * the entries at or below its own N: rolling back to `<model>.prev` (+exp N-1)
+ * re-teaches what the discarded version had learned, and a fresh base (no suffix,
+ * N = 0) — a newly downloaded Evermind — gets every procedure again.
+ */
+
+import type { adaptPackage, experienceDocuments, packDocuments, ExperienceStore } from "@seanhogg/builderforce-memory-engine";
+import type { LoadedEvermind } from "../model/evermind-package.js";
+
+/** The engine functions training needs, passed in so the peer stays optional. */
+export interface TrainEngine {
+    experienceDocuments: typeof experienceDocuments;
+    packDocuments: typeof packDocuments;
+    adaptPackage: typeof adaptPackage;
+    EVERMIND_ADAPT_MAX_CHARS: number;
+}
+
+export type TrainOutcome =
+    | { status: "nothing_new"; pending: 0; version: string }
+    | { status: "no_window"; pending: number; version: string }
+    | { status: "trained"; learned: number; passes: number; loss: number; version: string; previousModel: string };
+
+const EXP_SUFFIX = /\+exp(\d+)$/;
+
+/** The version an adaptation writes: `<base>+exp1`, then `+exp2`, … */
+export function nextExperienceVersion(version: string): string {
+    const m = EXP_SUFFIX.exec(version);
+    return m ? version.replace(EXP_SUFFIX, `+exp${Number(m[1]) + 1}`) : `${version}+exp1`;
+}
+
+/** Which adaptation produced this model: N for `+expN`, 0 for a base that has none. */
+export function experienceIndex(version: string): number {
+    const m = EXP_SUFFIX.exec(version);
+    return m ? Number(m[1]) : 0;
+}
+
+/** Procedures the model has not learned yet. */
+export async function pendingDocuments(store: ExperienceStore, engine: TrainEngine, modelVersion: string) {
+    const snap = await store.snapshot();
+    const current = experienceIndex(modelVersion);
+    const known = (id: string) => {
+        const n = snap.learned[id];
+        return typeof n === "number" && n >= 1 && n <= current;
+    };
+    return engine.experienceDocuments(snap.episodes, snap.skills).filter((d) => !known(d.id));
+}
+
+export async function trainExperience(
+    store: ExperienceStore,
+    engine: TrainEngine,
+    model: LoadedEvermind,
+    modelFile: string,
+): Promise<TrainOutcome> {
+    const version = model.pkg.manifest.version ?? "0";
+    const docs = await pendingDocuments(store, engine, version);
+    if (docs.length === 0) return { status: "nothing_new", pending: 0, version };
+
+    const next = nextExperienceVersion(version);
+    // The engine's package type; the structural view is what was loaded from disk.
+    let pkg = model.pkg as unknown as Parameters<typeof adaptPackage>[0];
+    const learned: string[] = [];
+    let lossSum = 0;
+    let passes = 0;
+    for (const pass of engine.packDocuments(docs, engine.EVERMIND_ADAPT_MAX_CHARS)) {
+        const r = engine.adaptPackage(pkg, model.codec, pass.map((d) => d.text).join("\n\n"), next);
+        if (!r) continue;
+        pkg = r.pkg;
+        lossSum += r.loss;
+        passes++;
+        learned.push(...pass.map((d) => d.id));
+    }
+    if (passes === 0) return { status: "no_window", pending: docs.length, version };
+
+    const loss = lossSum / passes;
+    // Keep the model this pass started from, so one bad adaptation is one rename away
+    // from undone. The new model is written beside the old one and renamed into place,
+    // so a crash mid-write never leaves a truncated model. The ledger is written only
+    // after the new model is on disk.
+    const previousModel = `${modelFile}.prev`;
+    model.fs.copyFileSync(modelFile, previousModel);
+    const staged = `${modelFile}.next`;
+    model.fs.writeFileSync(staged, new Uint8Array(pkg.toBlob()));
+    model.fs.renameSync(staged, modelFile);
+    await store.recordAdaptation({ index: experienceIndex(next), version: next, learned, passes, loss, at: Date.now() });
+    return { status: "trained", learned: learned.length, passes, loss, version: next, previousModel };
+}

package/src/gateway-tools.ts

@@ -0,0 +1,97 @@
+/**
+ * Gateway-backed cost tools (token_usage, model_efficiency). Registered only when a
+ * gateway URL and a `bfk_*` key are both configured, so memory-only deployments
+ * never see them.
+ */
+
+import { fail, ok, type MemoryTool } from "./tool-core.js";
+
+/** Snapshot shape returned by GET /llm/v1/builder-insights. */
+interface BuilderInsightsSnapshot {
+    windowLabel?: string;
+    todayTokens?: number;
+    todayCostUsd?: number;
+    dailyCapTokens?: number | null;
+    pctOfDailyCap?: number | null;
+    topModel?: { model: string; tokens: number } | null;
+    costPerMergedPrUsd?: number | null;
+    tip?: string | null;
+}
+
+/** Ranking shape returned by GET /llm/v1/model-analytics. */
+interface ModelAnalytics {
+    byAction?: Array<{
+        actionType?: string;
+        label?: string;
+        models?: Array<{
+            model: string;
+            samples?: number;
+            avgScore?: number;
+            mergeRate?: number;
+            avgCostMillicents?: number;
+        }>;
+    }>;
+}
+
+async function gatewayGet<T>(gatewayUrl: string, path: string, apiKey: string): Promise<T> {
+    const res = await fetch(`${gatewayUrl}${path}`, {
+        headers: { authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) throw new Error(`gateway ${path} → HTTP ${res.status}`);
+    return (await res.json()) as T;
+}
+
+export function appendGatewayCostTools(tools: MemoryTool[], gatewayUrl: string, apiKey: string): void {
+    tools.push({
+        name: "token_usage",
+        description: "Current token spend + budget for the workspace (today).",
+        inputSchema: {},
+        handler: async () => {
+            try {
+                const s = await gatewayGet<BuilderInsightsSnapshot>(gatewayUrl, "/llm/v1/builder-insights", apiKey);
+                const lines = [
+                    `Token usage (${s.windowLabel ?? "today"}):`,
+                    `• Tokens: ${(s.todayTokens ?? 0).toLocaleString()}`,
+                    `• Cost: $${(s.todayCostUsd ?? 0).toFixed(2)}`,
+                    `• % of daily cap: ${
+                        s.pctOfDailyCap == null
+                            ? "no cap"
+                            : `${s.pctOfDailyCap}%${s.dailyCapTokens ? ` of ${s.dailyCapTokens.toLocaleString()}` : ""}`
+                    }`,
+                    `• Top model: ${s.topModel ? `${s.topModel.model} (${s.topModel.tokens.toLocaleString()} tok)` : "—"}`,
+                ];
+                if (s.costPerMergedPrUsd != null) lines.push(`• Cost / merged PR: $${s.costPerMergedPrUsd.toFixed(2)}`);
+                if (s.tip) lines.push(`• Tip: ${s.tip}`);
+                return ok(lines.join("\n"));
+            } catch (err) {
+                return fail(`token_usage failed: ${String(err)}`);
+            }
+        },
+    });
+
+    tools.push({
+        name: "model_efficiency",
+        description: "Which models performed best/cheapest for this workspace's recent work.",
+        inputSchema: {},
+        handler: async () => {
+            try {
+                const a = await gatewayGet<ModelAnalytics>(gatewayUrl, "/llm/v1/model-analytics", apiKey);
+                const groups = a.byAction ?? [];
+                if (groups.length === 0) return ok("No model efficiency data yet for this workspace.");
+                const out: string[] = ["Model efficiency by action type (best first):"];
+                for (const g of groups) {
+                    out.push(`\n${g.label ?? g.actionType ?? "action"}:`);
+                    for (const m of (g.models ?? []).slice(0, 3)) {
+                        const cost = m.avgCostMillicents != null ? ` $${(m.avgCostMillicents / 100_000).toFixed(4)}/call` : "";
+                        const merge = m.mergeRate != null ? ` merge=${Math.round(m.mergeRate * 100)}%` : "";
+                        const score = m.avgScore != null ? ` score=${m.avgScore}` : "";
+                        out.push(`  • ${m.model}${score}${merge}${cost} (n=${m.samples ?? 0})`);
+                    }
+                }
+                return ok(out.join("\n"));
+            } catch (err) {
+                return fail(`model_efficiency failed: ${String(err)}`);
+            }
+        },
+    });
+}

package/src/index.ts

@@ -23,7 +23,14 @@ export type { LocalBackendOptions } from "./backends/memory-store.js";
 
 // ── Tool core ─────────────────────────────────────────────────────────────────
 export { buildMemoryTools } from "./tools.js";
-export type { MemoryTool, MemoryToolsOptions, ToolResult } from "./tools.js";
+export type { MemoryToolsOptions } from "./tools.js";
+export type { MemoryTool, ToolResult } from "./tool-core.js";
+
+// ── Experience (demonstrations → Train Once skills → runs → the private model) ─
+// The domain is the engine's; this is its durable host and its tools.
+export { createExperienceHost, EXPERIENCE_ENV } from "./experience/host.js";
+export type { ExperienceHost, ExperienceHostOptions, ExperienceEngine } from "./experience/host.js";
+export { nextExperienceVersion } from "./experience/train.js";
 
 // ── Compaction (absorbed fact → one-line pointer stub) ───────────────────────
 // Exported so an EXTERNAL compactor (the BuilderForce VS Code extension rewrites

package/src/install/install.ts

@@ -10,7 +10,7 @@
 import nodeFs from "node:fs";
 import nodeOs from "node:os";
 import nodePath from "node:path";
-import { HOSTS, SERVER_KEY, type HostAdapter, type HostEnv } from "./hosts.js";
+import { HOSTS, SERVER_KEY, findHost, type HostAdapter, type HostEnv } from "./hosts.js";
 import { buildServerSpec, type ServerSpecOptions, type StdioServerSpec } from "./server-spec.js";
 
 export interface FsLike {
@@ -132,7 +132,7 @@ function installToml(fs: FsLike, file: string, spec: StdioServerSpec): InstallSt
 function resolveHosts(selector: HostSelector, fs: FsLike, hostEnv: HostEnv): HostAdapter[] {
     if (Array.isArray(selector)) {
         return selector.map((id) => {
-            const h = HOSTS.find((x) => x.id === id);
+            const h = findHost(id);
             if (!h) throw new Error(`unknown host "${id}" (known: ${HOSTS.map((x) => x.id).join(", ")})`);
             return h;
         });