auto-model-router 0.11.0 → 0.12.0

package/.omp-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "auto-model-router: a local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
-    "version": "0.11.0",
+    "version": "0.12.0",
     "pluginRoot": "."
   },
   "plugins": [
     {
       "name": "auto-model-router",
       "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter. Runs in-process, routes per turn by price and task complexity, with budget caps, mid-stream escalation, and cache-aware hysteresis.",
-      "version": "0.11.0",
+      "version": "0.12.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -1355,6 +1355,16 @@ becomes Claude Code's key helper and, with `--profile`, goes on PATH. `connect
 `remote.json` records the executable, and a refresh from inside omp keeps the helper
 pointed at it.
 
+### The remote's skills come along
+
+A remote that serves a skills bundle (`GET <url>/setup/skills` with the member key: a
+version and a list of `{ name, files }`, each with a `SKILL.md`) has it installed by
+`connect`, and by every refresh, into the harnesses it configured that read user-level
+skills: Claude Code's `~/.claude/skills/<name>/` and omp's `~/.omp/agent/skills/<name>/`.
+`<router home>/skills-installed.json` records what was placed, so an update removes what
+the bundle no longer carries, and a skill of the same name the member wrote themselves is
+left alone with a note. A remote without skills answers 404 and nothing happens.
+
 ## Multiple coding harnesses, one router
 
 **One router process for everything.** omp's embed extension binds a private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Local cost/complexity-aware model router for Oh My Pi, backed by OpenRouter",
   "type": "module",

package/src/cli/connect.ts

@@ -31,6 +31,7 @@ import { fileURLToPath } from "node:url";
 import { refreshAccountOf, remoteFilePath } from "../../omp-extension/remote-logic.ts";
 import { SCOPE_ENV } from "../context/scope.ts";
 import { executablePath, materializePackage, readEmbeddedPackage } from "./embedded.ts";
+import { fetchSkills, installSkills, type SkillsBundle, type SkillsInstallReport, type SkillsTarget } from "./skills.ts";
 import { pickStore, saveRefreshToken, type StoreDeps, type StoreKind } from "./credential-store.ts";
 import { flagString, type CliArgs } from "./args.ts";
 
@@ -65,6 +66,8 @@ export interface ConnectOptions {
 	 * remote.json records it so a refresh from omp keeps pointing at it.
 	 */
 	exePath?: string;
+	/** The remote's skills bundle, installed into every configured harness that reads user-level skills. */
+	skills?: SkillsBundle;
 	platform: string;
 	pathHas: (bin: string) => boolean;
 }
@@ -75,6 +78,8 @@ export interface ConnectReport {
 	skipped: string[];
 	envLines: string[];
 	notes: string[];
+	/** What the remote's skills bundle did, when there was one. */
+	skills?: SkillsInstallReport;
 }
 
 const expand = (raw: string, home: string): string => (raw === "~" || raw.startsWith("~/") || raw.startsWith("~\\") ? join(home, raw.slice(1)) : raw);
@@ -360,6 +365,17 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	report.envLines.unshift(`AUTO_MODEL_ROUTER_URL=${o.url}`, `AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
 	report.envLines = [...new Set(report.envLines)];
 
+	// 6b. The remote's skills, into the harnesses configured above that read a
+	// user-level skills directory. Hermes, Codex and Aider have none we know of.
+	if (o.skills !== undefined) {
+		const targets: SkillsTarget[] = [];
+		if (report.configured.some((c) => c.startsWith("omp ("))) targets.push({ harness: "omp", dir: join(agentDir, "skills") });
+		if (report.configured.some((c) => c.startsWith("Claude Code ("))) targets.push({ harness: "Claude Code", dir: join(claudeDir, "skills") });
+		report.skills = installSkills(o.skills, targets, rh, o.dryRun);
+		if (report.skills.placed.length > 0) report.configured.push(`skills ${o.skills.version} (${report.skills.placed.join(", ")})`);
+		for (const s of report.skills.skipped) report.notes.push(`skill ${s}`);
+	}
+
 	// 7. Persist the environment.
 	if (o.profile && !o.dryRun) {
 		if (o.platform === "win32") {
@@ -445,6 +461,7 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	const pathHas = (bin: string): boolean => Bun.which(bin) !== null;
 	const packageDir = await resolvePackageDir();
 	const exePath = executablePath();
+	const fetchImpl = fetch;
 	let name = flagString(args, "name") ?? "";
 	let userId = flagString(args, "user-id") ?? "";
 	let device = flagString(args, "device") ?? "";
@@ -476,6 +493,8 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	// A single-project machine can label every request; a machine with several
 	// repos should leave it off and let the extensions send the workspace's own.
 	const scopeFlag = flagString(args, "scope");
+	// The remote's skills for the agents on this machine; a remote without any serves 404.
+	const skills = await fetchSkills(url, key, fetchImpl);
 	const report = connectRemote({
 		url,
 		key,
@@ -495,7 +514,9 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 		...(Number.isFinite(refreshExpires) ? { refreshExpiresAtMs: refreshExpires } : {}),
 		...(device === "" ? {} : { device }),
 		...(exePath === null ? {} : { exePath }),
+		...(skills.bundle === null ? {} : { skills: skills.bundle }),
 	});
+	if (skills.note !== undefined) report.notes.push(skills.note);
 	if (exePath !== null) console.log(`executable ${exePath}; package files under ${packageDir}`);
 	console.log(`${args.flags.has("dry-run") ? "would write" : "wrote"} ${report.remoteFile}${name === "" ? "" : ` for ${name}`}`);
 	for (const c of report.configured) console.log(`  configured ${c}`);

package/src/cli/refresh.ts

@@ -14,6 +14,7 @@
  */
 
 import { executablePath, materializePackage, readEmbeddedPackage } from "./embedded.ts";
+import { fetchSkills } from "./skills.ts";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -96,6 +97,8 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 	const embedded = opts.packageDir === undefined ? await readEmbeddedPackage() : null;
 	const packageDir = opts.packageDir ?? (embedded === null ? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..") : materializePackage(rh, embedded));
 	const exePath = opts.remote.executable ?? executablePath() ?? undefined;
+	// A refresh is when the team's skills reach a machine that has not re-run connect.
+	const skills = await fetchSkills(opts.remote.url, fresh.key, opts.fetchImpl ?? fetch);
 	connectRemote({
 		url: opts.remote.url,
 		key: fresh.key,
@@ -117,6 +120,7 @@ export async function refreshAndRewrite(opts: { remote: RemoteRouter; fetchImpl?
 		...(opts.remote.refreshTokenStore !== undefined ? { store: opts.remote.refreshTokenStore } : {}),
 		...(opts.storeDeps !== undefined ? { storeDeps: opts.storeDeps } : {}),
 		...(exePath !== undefined ? { exePath } : {}),
+		...(skills.bundle === null ? {} : { skills: skills.bundle }),
 		// undefined keeps whatever scope the managed models.yml block already carries.
 	});
 	return fresh;

package/src/cli/skills.ts

@@ -0,0 +1,145 @@
+/**
+ * Skills served by a remote router, installed by `connect`.
+ *
+ * A coding agent is only as good as the instructions it carries, and a team
+ * has instructions it wants every member's agent to have: how its shared
+ * context works, how to use the router well. The remote serves them as one
+ * versioned bundle (`GET <url>/setup/skills`, with the member key), and
+ * `connect` writes them into every harness it configures that reads a
+ * user-level skills directory — Claude Code's `~/.claude/skills`, omp's
+ * `~/.omp/agent/skills`. A manifest under the router home records what was
+ * placed, so an update removes what the bundle no longer carries and a skill
+ * the member wrote themselves under the same name is never touched.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface SkillsBundle {
+	/** Changes whenever any file changes; what `connect` reports and remembers. */
+	version: string;
+	skills: { name: string; files: Record<string, string> }[];
+}
+
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const REL = /^(?!\.)(?!.*\/\.)[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+
+/** Parses a bundle defensively: a malformed one installs nothing rather than something odd. */
+export function parseSkillsBundle(value: unknown): SkillsBundle | null {
+	if (typeof value !== "object" || value === null) return null;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.version !== "string" || raw.version === "" || !Array.isArray(raw.skills)) return null;
+	const skills: SkillsBundle["skills"] = [];
+	for (const s of raw.skills) {
+		if (typeof s !== "object" || s === null) return null;
+		const r = s as Record<string, unknown>;
+		if (typeof r.name !== "string" || !NAME.test(r.name) || typeof r.files !== "object" || r.files === null) return null;
+		const files: Record<string, string> = {};
+		for (const [rel, content] of Object.entries(r.files as Record<string, unknown>)) {
+			if (!REL.test(rel) || typeof content !== "string") return null;
+			files[rel] = content;
+		}
+		if (files["SKILL.md"] === undefined) return null;
+		skills.push({ name: r.name, files });
+	}
+	return { version: raw.version, skills };
+}
+
+/** The remote's bundle, or null when it serves none (404) or cannot be reached; never throws. */
+export async function fetchSkills(url: string, key: string, fetchImpl: typeof fetch = fetch): Promise<{ bundle: SkillsBundle | null; note?: string }> {
+	try {
+		const res = await fetchImpl(`${url}/setup/skills`, { headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(15_000) });
+		if (res.status === 404) return { bundle: null };
+		if (!res.ok) return { bundle: null, note: `skills: ${url}/setup/skills answered ${res.status}; nothing installed` };
+		const bundle = parseSkillsBundle(await res.json());
+		return bundle === null ? { bundle: null, note: "skills: the remote's bundle was not understood; nothing installed" } : { bundle };
+	} catch (err) {
+		return { bundle: null, note: `skills: could not fetch ${url}/setup/skills (${err instanceof Error ? err.message : String(err)}); nothing installed` };
+	}
+}
+
+export interface SkillsTarget {
+	/** Shown in the report: "Claude Code", "omp". */
+	harness: string;
+	/** The harness's user-level skills directory; each skill goes in `<dir>/<name>/`. */
+	dir: string;
+}
+
+export interface SkillsInstallReport {
+	version: string;
+	/** "<harness>: <name>" per skill written. */
+	placed: string[];
+	/** Files from an earlier install the bundle no longer carries. */
+	removed: string[];
+	/** Skills left alone because the member has their own of that name there. */
+	skipped: string[];
+}
+
+interface Manifest {
+	version: string;
+	files: string[];
+}
+
+export function skillsManifestPath(routerHome: string): string {
+	return join(routerHome, "skills-installed.json");
+}
+
+export function readSkillsManifest(routerHome: string): Manifest | null {
+	try {
+		const raw = JSON.parse(readFileSync(skillsManifestPath(routerHome), "utf8")) as Record<string, unknown>;
+		return typeof raw.version === "string" && Array.isArray(raw.files) ? { version: raw.version, files: raw.files.filter((f): f is string => typeof f === "string") } : null;
+	} catch {
+		return null;
+	}
+}
+
+const norm = (p: string): string => p.replaceAll("\\", "/");
+
+/**
+ * Writes the bundle into each target, records what it placed, removes what a
+ * previous install placed that is gone now, and skips a skill directory it did
+ * not create. Pure over the file system: no network, so a test can drive it.
+ */
+export function installSkills(bundle: SkillsBundle, targets: readonly SkillsTarget[], routerHome: string, dryRun = false): SkillsInstallReport {
+	const previous = readSkillsManifest(routerHome);
+	const ours = new Set((previous?.files ?? []).map(norm));
+	const report: SkillsInstallReport = { version: bundle.version, placed: [], removed: [], skipped: [] };
+	const placedFiles: string[] = [];
+	for (const t of targets) {
+		for (const skill of bundle.skills) {
+			const dir = join(t.dir, skill.name);
+			const foreign = existsSync(dir) && !readdirSync(dir).some((f) => ours.has(norm(join(dir, f))));
+			if (foreign) {
+				report.skipped.push(`${t.harness}: ${skill.name} (a skill of that name is already there and was not placed by connect; left alone)`);
+				continue;
+			}
+			for (const [rel, content] of Object.entries(skill.files)) {
+				const path = join(dir, ...rel.split("/"));
+				placedFiles.push(norm(path));
+				if (dryRun) continue;
+				mkdirSync(dirname(path), { recursive: true });
+				writeFileSync(path, content, "utf8");
+			}
+			report.placed.push(`${t.harness}: ${skill.name}`);
+		}
+	}
+	const keep = new Set(placedFiles);
+	for (const old of ours) {
+		if (keep.has(old)) continue;
+		report.removed.push(old);
+		if (dryRun) continue;
+		rmSync(old, { force: true });
+		// An emptied skill directory goes too, so the harness does not list a hollow skill.
+		const parent = dirname(old);
+		try {
+			if (readdirSync(parent).length === 0) rmSync(parent, { recursive: true, force: true });
+		} catch {
+			/* already gone */
+		}
+	}
+	if (!dryRun) {
+		mkdirSync(routerHome, { recursive: true });
+		writeFileSync(skillsManifestPath(routerHome), `${JSON.stringify({ version: bundle.version, files: placedFiles } satisfies Manifest, null, 2)}\n`, "utf8");
+	}
+	return report;
+}

package/src/index.ts

@@ -28,7 +28,7 @@ Usage: auto-model-router <command> [options]
   stats      Show routed spend, per-model share, and escalation rates
   report     Usage analytics: providers, models, tiers, cost, speed, cache hit rate
   export     One row per day, harness and model as CSV (--json for rows)
-  connect    Point this machine at a remote router (--url with --key[, --refresh-token] or --setup-token <one-time token from a team>; --scope pins one project for the whole machine (default: each workspace's own); --profile persists the environment and, from the compiled executable, PATH)
+  connect    Point this machine at a remote router (--url with --key[, --refresh-token] or --setup-token <one-time token from a team>; --scope pins one project for the whole machine (default: each workspace's own); --profile persists the environment and, from the compiled executable, PATH; the remote's skills are installed for Claude Code and omp)
   refresh    Trade the refresh token for a new access key and re-write every harness config (--force: even when not near expiry)
   token      Print an access key that is good right now, refreshing first if needed (for a harness key-helper)
   models     Show what each complexity tier would consider, and why

package/src/lib.ts

@@ -24,5 +24,6 @@ export { spendUsdSince, feedbackView, exportRows, exportCsv, harnessScopeParam,
 export { createLedger } from "./cost/ledger.ts";
 export { createFeedbackStore, type FeedbackStore, type FeedbackRecord } from "./cost/feedback.ts";
 export { buildExecutable, collectPackageFiles, executableFileName, hostTarget, isExecutableTarget, EXECUTABLE_TARGETS, type ExecutableTarget, type BuildExecutableResult } from "./cli/build-executable.ts";
+export { parseSkillsBundle, type SkillsBundle } from "./cli/skills.ts";
 export type { RequestPolicy } from "./wire/types.ts";
 export type { Ledger, LedgerEntry } from "./cost/types.ts";

package/test/skills.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { connectRemote } from "../src/cli/connect.ts";
+import { fetchSkills, installSkills, parseSkillsBundle, readSkillsManifest, type SkillsBundle } from "../src/cli/skills.ts";
+
+const NL = String.fromCharCode(10);
+const bundle = (version: string, skills: Record<string, Record<string, string>>): SkillsBundle => ({ version, skills: Object.entries(skills).map(([name, files]) => ({ name, files })) });
+
+describe("skills served by the remote, installed by connect", () => {
+	test("a bundle is parsed defensively", () => {
+		expect(parseSkillsBundle({ version: "v1", skills: [{ name: "team-context", files: { "SKILL.md": "# x" } }] })?.skills[0]?.name).toBe("team-context");
+		expect(parseSkillsBundle({ version: "v1", skills: [{ name: "Bad Name", files: { "SKILL.md": "# x" } }] })).toBeNull();
+		expect(parseSkillsBundle({ version: "v1", skills: [{ name: "ok", files: { "notes.md": "x" } }] })).toBeNull(); // no SKILL.md
+		expect(parseSkillsBundle({ version: "v1", skills: [{ name: "ok", files: { "../escape.md": "x", "SKILL.md": "y" } }] })).toBeNull();
+		expect(parseSkillsBundle({ version: "", skills: [] })).toBeNull();
+		expect(parseSkillsBundle("nope")).toBeNull();
+	});
+
+	test("install writes each skill into each target, updates in place, removes what is gone, and leaves a member's own skill alone", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-skills-"));
+		const rh = join(home, ".auto-model-router");
+		const claude = join(home, ".claude", "skills");
+		const omp = join(home, ".omp", "agent", "skills");
+		try {
+			const targets = [
+				{ harness: "Claude Code", dir: claude },
+				{ harness: "omp", dir: omp },
+			];
+			// The member already has their own "router" skill in Claude Code.
+			mkdirSync(join(claude, "router"), { recursive: true });
+			writeFileSync(join(claude, "router", "SKILL.md"), "mine", "utf8");
+			const v1 = bundle("v1", { "team-context": { "SKILL.md": `# ctx v1${NL}`, "notes/extra.md": "extra" }, router: { "SKILL.md": "# router v1" } });
+			const r1 = installSkills(v1, targets, rh);
+			expect(r1.placed).toEqual(["Claude Code: team-context", "omp: team-context", "omp: router"]);
+			expect(r1.skipped).toHaveLength(1);
+			expect(r1.skipped[0]).toContain("Claude Code: router");
+			expect(readFileSync(join(claude, "router", "SKILL.md"), "utf8")).toBe("mine");
+			expect(readFileSync(join(omp, "router", "SKILL.md"), "utf8")).toBe("# router v1");
+			expect(readFileSync(join(claude, "team-context", "notes", "extra.md"), "utf8")).toBe("extra");
+			expect(readSkillsManifest(rh)?.version).toBe("v1");
+			expect(readSkillsManifest(rh)?.files).toHaveLength(5);
+
+			// v2 drops the extra file and the router skill; team-context changes.
+			const v2 = bundle("v2", { "team-context": { "SKILL.md": `# ctx v2${NL}` } });
+			const r2 = installSkills(v2, targets, rh);
+			expect(r2.placed).toEqual(["Claude Code: team-context", "omp: team-context"]);
+			expect(readFileSync(join(omp, "team-context", "SKILL.md"), "utf8")).toBe(`# ctx v2${NL}`);
+			expect(existsSync(join(claude, "team-context", "notes", "extra.md"))).toBe(false);
+			expect(existsSync(join(omp, "router"))).toBe(false); // ours, now gone, directory and all
+			expect(readFileSync(join(claude, "router", "SKILL.md"), "utf8")).toBe("mine"); // theirs, untouched
+			expect(r2.removed).toHaveLength(3);
+			expect(readSkillsManifest(rh)?.files).toHaveLength(2);
+
+			// Dry run touches nothing.
+			const r3 = installSkills(bundle("v3", { fresh: { "SKILL.md": "x" } }), targets, rh, true);
+			expect(r3.placed).toHaveLength(2);
+			expect(existsSync(join(omp, "fresh"))).toBe(false);
+			expect(readSkillsManifest(rh)?.version).toBe("v2");
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+
+	test("fetchSkills: a remote without skills is silent, an unreachable one is a note, never an error", async () => {
+		const gone = (async () => new Response("", { status: 404 })) as unknown as typeof fetch;
+		expect(await fetchSkills("https://t", "k", gone)).toEqual({ bundle: null });
+		const seen: string[] = [];
+		const ok = (async (url: string | URL | Request, init?: RequestInit) => {
+			seen.push(`${String(url)} ${(init?.headers as Record<string, string>).authorization}`);
+			return Response.json({ version: "v9", skills: [{ name: "team-context", files: { "SKILL.md": "# hi" } }] });
+		}) as unknown as typeof fetch;
+		expect((await fetchSkills("https://t", "amrt_k", ok)).bundle?.version).toBe("v9");
+		expect(seen[0]).toBe("https://t/setup/skills Bearer amrt_k");
+		const down = (async () => {
+			throw new Error("connect ECONNREFUSED");
+		}) as unknown as typeof fetch;
+		const r = await fetchSkills("https://t", "k", down);
+		expect(r.bundle).toBeNull();
+		expect(r.note).toContain("ECONNREFUSED");
+		const odd = (async () => Response.json({ version: "v1", skills: "?" })) as unknown as typeof fetch;
+		expect((await fetchSkills("https://t", "k", odd)).note).toContain("not understood");
+	});
+
+	test("connect installs the bundle only into the harnesses it configured", () => {
+		const home = mkdtempSync(join(tmpdir(), "amr-skills-connect-"));
+		mkdirSync(join(home, ".claude"), { recursive: true });
+		const agent = join(home, ".omp", "agent");
+		mkdirSync(agent, { recursive: true });
+		writeFileSync(join(agent, "config.yml"), `extensions: []${NL}`, "utf8");
+		const rh = join(home, ".auto-model-router");
+		const env = { HOME: home, PI_CODING_AGENT_DIR: agent, AUTO_MODEL_ROUTER_HOME: rh, HERMES_HOME: join(home, "no-hermes") };
+		try {
+			const skills = bundle("s1", { "team-context": { "SKILL.md": "# team" } });
+			const r = connectRemote({ url: "https://team.example", key: "amrt_k", userId: "u", name: "Ada", profile: false, dryRun: false, only: ["omp", "claude"], env, home, packageDir: "/pkg", skills, platform: "linux", pathHas: () => false });
+			expect(r.skills?.placed).toEqual(["omp: team-context", "Claude Code: team-context"]);
+			expect(readFileSync(join(agent, "skills", "team-context", "SKILL.md"), "utf8")).toBe("# team");
+			expect(readFileSync(join(home, ".claude", "skills", "team-context", "SKILL.md"), "utf8")).toBe("# team");
+			expect(r.configured.some((c) => c.startsWith("skills s1 ("))).toBe(true);
+			// Only Claude Code asked for: omp's directory is not created.
+			rmSync(join(agent, "skills"), { recursive: true, force: true });
+			const r2 = connectRemote({ url: "https://team.example", key: "amrt_k", userId: "u", name: "Ada", profile: false, dryRun: false, only: ["claude"], env, home, packageDir: "/pkg", skills, platform: "linux", pathHas: () => false });
+			expect(r2.skills?.placed).toEqual(["Claude Code: team-context"]);
+			expect(existsSync(join(agent, "skills"))).toBe(false);
+		} finally {
+			rmSync(home, { recursive: true, force: true });
+		}
+	});
+});