auto-model-router 0.19.0 → 0.20.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.19.0",
+    "version": "0.20.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.19.0",
+      "version": "0.20.0",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/README.md

@@ -472,8 +472,17 @@ cline -P openai -m auto "your task"
 Verified live with cline 3.0 (captured request:
 `test/fixtures/harness/cline-cli.json`). The CLI sends native tool calls
 (`read_files`, `search_codebase`, `run_commands`, `fetch_web_content`, …),
-all in `digest.toolAliases`, and no custom headers, so its rows carry no
-harness id. No session id or hooks.
+all in `digest.toolAliases`. No session id or hooks.
+
+`auto-model-router connect` writes this itself, and writes one thing the
+`auth` command cannot: Cline's provider store
+(`~/.cline/data/settings/providers.json`) has a `settings.headers` map with no
+CLI flag behind it, so a file written by hand is what finally gives Cline a
+harness id. Verified live on cline 3.0.61 by pointing it at a recording
+server — `test/fixtures/harness/cline-cli-connected.json` is that capture, with
+`X-Omp-Harness: cline` on it. That one file also serves the **VS Code
+extension**, which reads the same store since its settings migration, so the
+extension needs no separate recipe (and neither does any editor that hosts it).
 
 ### Kilo Code CLI
 
@@ -534,10 +543,11 @@ id or hooks: the digest applies only through summarising compaction.
 
 ### Cline (VS Code)
 
-Choose the *OpenAI Compatible* provider in the extension's settings, set the
-base URL to `http://127.0.0.1:8788/v1`, any API key, and the model id `auto`
-(or `auto-cheap` / `auto-max`); add `X-Omp-Harness` under custom headers if
-offered. Not verified live here (the CLI above was); its tool names are in
+Nothing extra: the extension reads the same provider store as the CLI
+(`~/.cline/data/settings/providers.json`), so `connect` has already configured
+it — pick the *OpenAI Compatible* provider and the `auto` model. By hand, set
+the base URL to `http://127.0.0.1:8788/v1`, any API key, and the model id
+`auto` (or `auto-cheap` / `auto-max`). Its tool names are in
 `digest.toolAliases`, and the digest applies only through summarising
 compaction.
 
@@ -564,9 +574,16 @@ SSE frame, which is why the router's final summary frame is shaped as a
 chunk with no choices. Its tool names (`read`, `grep`, `glob`, `bash`,
 `webfetch`) match the router's canonical list.
 
+`auto-model-router connect` writes both halves of this: the provider block
+(other providers, MCP servers and `$schema` untouched) and the plugin below.
+The config directory is `~/.config/opencode` on **every** platform, Windows
+included — OpenCode uses the XDG layout there rather than `%APPDATA%`.
+
 **Native features (OpenCode plugin API).** Copy
 `opencode-plugin/auto-model-router.ts` to `~/.config/opencode/plugin/` (or a
-project's `.opencode/plugin/`); OpenCode loads it on start. It adds:
+project's `.opencode/plugin/`); OpenCode loads it on start (`plugins/`, the
+name current docs use, is loaded too — both were confirmed on opencode 1.18).
+It adds:
 
 - **Session identity** — `X-Omp-Session`, `X-Omp-Harness` (`opencode`, or
   `OMP_HARNESS_ID`) and `X-Omp-Subagent` for sessions with a parent, through
@@ -581,6 +598,57 @@ No `/router` command (OpenCode commands are markdown files, not plugin
 hooks): use `auto-model-router report` on the terminal, or the router's
 HTTP endpoints.
 
+### Continue
+
+```yaml
+# ~/.continue/config.yaml
+name: auto-model-router
+version: 0.0.1
+schema: v1
+models:
+  - name: auto-model-router
+    provider: openai
+    model: auto
+    apiBase: http://127.0.0.1:8788/v1
+    apiKey: local
+    roles: [chat, edit, apply, summarize]
+    capabilities: [tool_use, image_input]
+    requestOptions:
+      headers:
+        X-Omp-Harness: continue
+```
+
+`connect` writes all three profiles as entries like this one, editing the YAML
+*document* rather than re-serialising it, so a hand-written config keeps its
+comments, key order and other models; entries are matched by `name`, so a later
+connect replaces them in place. Pick `auto-model-router` in the model dropdown.
+This is Continue's documented assistant schema rather than a shape captured
+here — Continue was not run against the router — and `config.yaml` takes
+precedence over the older `config.json` if you still have one.
+
+### Cursor
+
+Cursor has no provider file to write: the OpenAI override is an application
+setting in the editor's own state. `connect` prints the values instead —
+Cursor Settings → Models → OpenAI API Key, enable the base-URL override, then
+the base URL, the key and `auto` as a custom model.
+
+Two limits worth knowing before you try. Cursor proxies chat through **its own
+servers** with your key attached, so the base URL has to be reachable from the
+internet — a `127.0.0.1` router or a LAN team edition will never be called. And
+the override carries no custom header, so those turns arrive with no
+`X-Omp-Harness` id and share the unnamed budget.
+
+### Windsurf
+
+Windsurf has no custom base-URL field at all: its bring-your-own-key page takes
+first-party provider keys, and the files under `~/.codeium/<channel>` are MCP
+servers, rules and skills. So the route in is an extension. Windsurf is a VS
+Code fork, and **Cline** reads the provider store `connect` already wrote
+(`~/.cline/data/settings/providers.json`) — installing the extension is the
+whole configuration. Continue works the same way against `~/.continue/config.yaml`.
+`connect` says exactly this when it finds a Windsurf install.
+
 ### The OpenRouter key
 
 **omp does not need to be authenticated to OpenRouter.** On a routed turn omp
@@ -1313,9 +1381,21 @@ embed extension registers the remote router as omp's provider with that key inst
 binding a local one, and the toast, `/router` hub and digest extensions talk to it. Nothing
 is classified or selected locally; the remote router is the router. The same command adds
 the extensions to omp's config, installs the Hermes plugins and points them at the remote,
-adds the Codex provider and the Aider settings, and prints (or with `--profile` persists)
-the environment lines for Claude Code. `--harness omp,hermes` restricts it; `--dry-run`
-shows the changes. Delete `remote.json` to go back to a local router. (`join` is an alias.)
+adds the Codex provider and the Aider settings, writes Claude Code's settings file, merges
+the provider into OpenCode's `opencode.json` (and copies its plugin), Cline's
+`providers.json` and Continue's `config.yaml`, and prints what to set by hand for Cursor
+and Windsurf. `--harness omp,hermes` restricts it (`omp`, `hermes`, `codex`, `aider`,
+`claude`, `opencode`, `cline`, `continue`, `cursor`, `windsurf`); `--dry-run` shows the
+changes. Delete `remote.json` to go back to a local router. (`join` is an alias.)
+
+**What gets written and what gets printed.** A harness is configured only where its file
+format is documented and, wherever the harness could be run here, seen to be read: omp,
+Hermes, Codex, Aider, Claude Code, OpenCode, Cline and Continue. Cursor and Windsurf keep
+their provider settings in application state — an editor's own database, a vendor's
+account page — so `connect` reports them as `manual` and prints the base URL, key and
+model to paste. That is deliberate: a config key invented for them would write a file that
+silently does nothing while the run reported success. Every write is idempotent, backs the
+previous file up, and touches only its own keys.
 
 `connect` also writes omp's `models.yml` (a managed block, other providers untouched, the
 previous file backed up). That entry is what makes `auto-model-router/auto` resolvable at
@@ -1474,10 +1554,12 @@ plus a harness header; the rest needs the harness's own hook API.
 | Hermes | provider plugin | yes | yes (native plugin) | yes (native plugin) | no | text | yes (native plugin) | on demand | no |
 | Codex CLI | Responses API wire | yes | yes (from body) | yes (from body) | no | no | compaction only | no | no |
 | Aider | config only | via model settings | no | no | no | no | no tools | no | no |
-| Cline CLI | config only | no | no | no | no | no | compaction only | no | no |
+| Cline (CLI + VS Code) | config only | yes | no | no | no | no | compaction only | no | no |
 | Kilo Code CLI | config only | yes | no | no | no | no | compaction only | no | no |
 | Roo Code (VS Code) | config only | yes | no | no | no | no | compaction only | no | no |
-| Cline (VS Code) | config only, unverified | if headers supported | no | no | no | no | compaction only | no | no |
+| Continue | config only | yes | no | no | no | no | compaction only | no | no |
+| Cursor | manual (no config file; needs a public URL) | no | no | no | no | no | compaction only | no | no |
+| Windsurf | via the Cline or Continue extension | as that extension | no | no | no | no | compaction only | no | no |
 | OpenCode | config + plugin | yes | yes (plugin) | yes (plugin) | yes (plugin) | no | yes (plugin) | no | no |
 | Claude Code | needs an Anthropic Messages wire module | — | — | — | — | — | — | — | — |
 

package/package.json

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

package/src/cli/connect.ts

@@ -17,6 +17,15 @@
  *   Claude Code ~/.claude/settings.json gains the base URL (its `env` block) and
  *               `apiKeyHelper` running `auto-model-router token`, so no key
  *               sits in its environment or on disk for it
+ *   OpenCode    ~/.config/opencode/opencode.json gains the provider block, and
+ *               plugin/ the native plugin
+ *   Cline       ~/.cline/data/settings/providers.json gains the
+ *               openai-compatible provider — the CLI and the extension share it
+ *   Continue    ~/.continue/config.yaml gains the three profiles as models
+ *
+ * Cursor and Windsurf keep their provider settings in application state rather
+ * than in a file, so they are PRINTED, not written; see configureExtraHarnesses
+ * for where that line is drawn and why.
  *
  * Every write is idempotent and announced. `--profile` persists the
  * environment lines (shell rc on POSIX, user environment on Windows).
@@ -34,6 +43,7 @@ import { executablePath, materializePackage, readEmbeddedPackage } from "./embed
 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";
+import { cursorSnippet, mergeClineProviders, mergeContinueConfig, mergeOpenCodeConfig, windsurfSnippet, type ManualSnippet } from "./harnesses.ts";
 
 export interface ConnectOptions {
 	url: string;
@@ -42,7 +52,7 @@ export interface ConnectOptions {
 	name: string;
 	profile: boolean;
 	dryRun: boolean;
-	/** Restrict to these harnesses (omp, hermes, codex, aider, claude); empty ⇒ every one detected. */
+	/** Restrict to these harnesses (omp, hermes, codex, aider, claude, opencode, cline, continue, cursor, windsurf); empty ⇒ every one detected. */
 	only: string[];
 	env: Record<string, string | undefined>;
 	home: string;
@@ -84,6 +94,12 @@ export interface ConnectReport {
 	skipped: string[];
 	envLines: string[];
 	notes: string[];
+	/**
+	 * Harnesses whose provider settings live in application state rather than a
+	 * documented file: what to paste into their settings UI. Never a guess at a
+	 * file — see harnesses.ts for why the line is drawn on confidence.
+	 */
+	manual: ManualSnippet[];
 	/** What the remote's skills bundle did, when there was one. */
 	skills?: SkillsInstallReport;
 	/** Files that gained (or lost) the team-context MCP server. */
@@ -278,7 +294,7 @@ export function hasForeignRouterProvider(text: string): boolean {
 }
 
 export function connectRemote(o: ConnectOptions): ConnectReport {
-	const report: ConnectReport = { remoteFile: "", configured: [], skipped: [], envLines: [], notes: [] };
+	const report: ConnectReport = { remoteFile: "", configured: [], skipped: [], envLines: [], notes: [], manual: [] };
 	const write = (path: string, content: string): void => {
 		if (o.dryRun) return;
 		mkdirSync(dirname(path), { recursive: true });
@@ -405,6 +421,8 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 		}
 		report.configured.push(`Claude Code (${settingsPath}: env.ANTHROPIC_BASE_URL + apiKeyHelper; open a new session)`);
 	} else report.skipped.push("Claude Code (not on PATH and no ~/.claude)");
+
+	configureExtraHarnesses(o, report, write);
 	report.envLines.unshift(`AUTO_MODEL_ROUTER_URL=${o.url}`, `AUTO_MODEL_ROUTER_API_KEY=${o.key}`);
 	report.envLines = [...new Set(report.envLines)];
 
@@ -463,6 +481,112 @@ export function connectRemote(o: ConnectOptions): ConnectReport {
 	return report;
 }
 
+/**
+ * The harnesses added in 0.20.0, kept out of `connectRemote` only for its
+ * length: same contract, same report, same idempotence.
+ *
+ * Two shapes appear here. The automated ones own a documented config file, and
+ * `connect` merges its own keys into it (harnesses.ts holds those merges, and
+ * says why each format is trusted). The manual ones keep their provider
+ * settings in application state — a VS Code `globalState` blob, an IDE's own
+ * database — where there is no file to edit, so `connect` prints the values to
+ * paste and says so in the report rather than writing something that would look
+ * like success and do nothing.
+ *
+ * A manual harness is announced when it is INSTALLED, or when `--harness` named
+ * it outright; a user without Cursor should not be read a Cursor recipe.
+ */
+function configureExtraHarnesses(o: ConnectOptions, report: ConnectReport, write: (path: string, content: string) => void): void {
+	const scope = o.agentdoxScope ?? "";
+	const named = (h: string): boolean => o.only.includes(h);
+
+	// OpenCode: the provider block the README documents, plus the plugin that
+	// gives it session identity, the toast and the digest — the same two-part
+	// install Hermes gets, since OpenCode is the other harness with a real hook API.
+	const ocDir = openCodeDir(o);
+	if (wants(o, "opencode") && (existsSync(ocDir) || o.pathHas("opencode"))) {
+		const p = join(ocDir, "opencode.json");
+		const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+		const after = mergeOpenCodeConfig(before, o.url, o.key, scope);
+		if (after === null && before.trim() !== "" && !isJsonObject(before)) {
+			report.notes.push(`${p} is not a JSON object; left alone — add the auto-model-router provider by hand`);
+		} else if (after !== null) {
+			if (before !== "" && !o.dryRun) writeFileSync(`${p}.${backupStamp()}.bak`, before, "utf8");
+			write(p, after);
+		}
+		if (!o.dryRun) cpSync(join(o.packageDir, "opencode-plugin", "auto-model-router.ts"), join(ocDir, "plugin", "auto-model-router.ts"));
+		report.configured.push(`OpenCode (${p} + ${join(ocDir, "plugin")}; model auto-model-router/auto)`);
+	} else report.skipped.push("OpenCode (not on PATH and no ~/.config/opencode)");
+
+	// Cline: one provider store for the CLI and, since its settings migration, the
+	// VS Code extension — so this single write serves both, and every editor that
+	// hosts the extension (see the Windsurf snippet below).
+	const clineDataDir = clineDir(o);
+	let clineConfigured = false;
+	if (wants(o, "cline") && (existsSync(clineDataDir) || o.pathHas("cline"))) {
+		const p = join(clineDataDir, "settings", "providers.json");
+		const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+		const after = mergeClineProviders(before, o.url, o.key, new Date().toISOString(), scope);
+		if (after === null && before.trim() !== "" && !isJsonObject(before)) {
+			report.notes.push(`${p} is not a JSON object; left alone — run \`cline auth -p openai -b ${o.url}/v1 -k <key> -m auto\` instead`);
+		} else if (after !== null) {
+			if (before !== "" && !o.dryRun) writeFileSync(`${p}.${backupStamp()}.bak`, before, "utf8");
+			write(p, after);
+		}
+		clineConfigured = true;
+		report.configured.push(`Cline (${p}; \`cline -m auto\`, or the VS Code extension)`);
+	} else report.skipped.push("Cline (not on PATH and no ~/.cline)");
+
+	// Continue: one assistant file holds the models, so the three profiles go in as
+	// three entries and the user picks between them in the model dropdown.
+	const continueDir = join(o.home, ".continue");
+	if (wants(o, "continue") && (existsSync(continueDir) || o.pathHas("cn"))) {
+		const p = join(continueDir, "config.yaml");
+		const before = existsSync(p) ? readFileSync(p, "utf8") : "";
+		const after = mergeContinueConfig(before, o.url, o.key, scope);
+		if (after === null && before.trim() !== "") {
+			report.notes.push(`${p} is not an assistant file we can edit; left alone — add the models entry by hand`);
+		} else if (after !== null) {
+			if (before !== "" && !o.dryRun) writeFileSync(`${p}.${backupStamp()}.bak`, before, "utf8");
+			write(p, after);
+			// config.yaml wins over the older config.json, so say so rather than let a
+			// user wonder why the settings they had stopped applying.
+			if (before === "" && existsSync(join(continueDir, "config.json"))) report.notes.push(`${join(continueDir, "config.json")} is Continue's older format and config.yaml now takes precedence over it`);
+		}
+		report.configured.push(`Continue (${p}; pick auto-model-router in the model dropdown)`);
+	} else report.skipped.push("Continue (no ~/.continue)");
+
+	// Cursor and Windsurf keep provider settings where no file can reach them.
+	if (wants(o, "cursor") && (named("cursor") || existsSync(join(o.home, ".cursor")) || o.pathHas("cursor"))) report.manual.push(cursorSnippet(o.url, o.key));
+	else report.skipped.push("Cursor (no ~/.cursor)");
+	if (wants(o, "windsurf") && (named("windsurf") || existsSync(join(o.home, ".codeium")) || o.pathHas("windsurf"))) report.manual.push(windsurfSnippet(clineConfigured));
+	else report.skipped.push("Windsurf (no ~/.codeium)");
+}
+
+/** Cline's state directory: `--data-dir`'s default, `~/.cline/data`, or `CLINE_DATA_DIR` when the user moved it. */
+function clineDir(o: ConnectOptions): string {
+	const d = o.env.CLINE_DATA_DIR;
+	return d !== undefined && d !== "" ? expand(d, o.home) : join(o.home, ".cline", "data");
+}
+
+/** OpenCode's config home: `XDG_CONFIG_HOME`, else `~/.config` — the same on Windows, where it does not use APPDATA. */
+function openCodeDir(o: ConnectOptions): string {
+	const xdg = o.env.XDG_CONFIG_HOME;
+	return join(xdg !== undefined && xdg !== "" ? expand(xdg, o.home) : join(o.home, ".config"), "opencode");
+}
+
+/** A filename-safe timestamp for the `.bak` beside a file we are about to replace. */
+const backupStamp = (): string => new Date().toISOString().replaceAll(":", "-");
+
+const isJsonObject = (text: string): boolean => {
+	try {
+		const v = JSON.parse(text) as unknown;
+		return typeof v === "object" && v !== null && !Array.isArray(v);
+	} catch {
+		return false;
+	}
+};
+
 /** What a team's one-time setup token is traded for. */
 export interface IssuedCredential {
 	key: string;
@@ -597,6 +721,11 @@ export async function connectCommand(args: CliArgs): Promise<void> {
 	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}`);
 	for (const s of report.skipped) console.log(`  skipped    ${s}`);
+	// A manual harness gets the values printed rather than a file written; see configureExtraHarnesses.
+	for (const m of report.manual) {
+		console.log(`  manual     ${m.harness} — ${m.reason}`);
+		for (const l of m.lines) console.log(`               ${l}`);
+	}
 	console.log("environment:");
 	for (const l of report.envLines) console.log(`  ${process.platform === "win32" ? "$env:" : "export "}${process.platform === "win32" ? l.replace("=", '="') + '"' : l}`);
 	for (const n of report.notes) console.log(`note: ${n}`);

package/src/cli/harnesses.ts

@@ -0,0 +1,277 @@
+/**
+ * The harness configurations `connect` writes beyond the five it has always
+ * written (omp, Hermes, Codex, Aider, Claude Code), and the snippets it prints
+ * for the ones it deliberately does not write.
+ *
+ * The line between the two is confidence, not effort. A harness whose config
+ * FILE and keys are documented — and, where the harness could be run here, seen
+ * to read them — gets an automated path: a pure merge over the file's text, so
+ * `connect` edits its own keys and leaves every other one alone. A harness
+ * whose provider settings live in application state (an editor's `globalState`
+ * database, a vendor's web account page) has no file to edit honestly, so it
+ * gets a snippet the user pastes into its settings UI instead. An invented key
+ * writes a file that silently does nothing and then reports success, which is
+ * worse for the user than a printed instruction that works.
+ *
+ * Every merge returns `null` when nothing changes — so a second `connect` is a
+ * no-op — and also when the file cannot be parsed: a file we do not understand
+ * is not ours to rewrite, and the caller says so rather than guessing.
+ */
+
+import { isMap, isScalar, isSeq, parseDocument, type Document, type YAMLSeq } from "yaml";
+
+import { SCOPE_ENV } from "../context/scope.ts";
+
+/** The provider id every automated harness registers the router under. */
+export const PROVIDER_ID = "auto-model-router";
+
+/** The virtual models a router serves; `auto` is the one each harness is pointed at. */
+export const PROFILE_IDS = ["auto", "auto-cheap", "auto-max"] as const;
+
+/**
+ * The headers a harness's provider entry sends on every turn.
+ *
+ * `X-Omp-Harness` is what splits budgets, reports and toasts per harness, so it
+ * is always here. The agentdox scope is not: these files hold LITERAL header
+ * values — unlike omp's models.yml, none of these harnesses resolves a value
+ * that names an environment variable — so a machine-wide file could only pin one
+ * project onto every workspace. It is written only when `connect --scope` asked
+ * for exactly that; otherwise the scope is left to the remote's own default.
+ */
+export function harnessHeaders(harness: string, scope: string): Record<string, string> {
+	return { "X-Omp-Harness": harness, ...(scope !== "" && scope !== SCOPE_ENV ? { "X-Agentdox-Scope": scope } : {}) };
+}
+
+/** A harness `connect` will not write a file for: what to set, and where. */
+export interface ManualSnippet {
+	/** The harness's display name, as it appears in the report. */
+	harness: string;
+	/** Why there is no file to write — one line, shown beside the name. */
+	reason: string;
+	/** The instruction lines, already formatted for a terminal. */
+	lines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// OpenCode — automated
+// ---------------------------------------------------------------------------
+
+/**
+ * Merges the router into OpenCode's `opencode.json`.
+ *
+ * OpenCode reaches any OpenAI-compatible endpoint through a `provider` entry
+ * backed by the `@ai-sdk/openai-compatible` npm package, which it installs
+ * itself; `options` is handed to that package verbatim, which is where the base
+ * URL, the key and the per-request headers go. This is the shape the README
+ * documents, verified live against opencode 1.18 — the captured request,
+ * `test/fixtures/harness/opencode.json`, carries the `X-Omp-Harness` header
+ * that `options.headers` put there.
+ *
+ * `model` is pointed at our `auto` so the harness comes up on the router rather
+ * than leaving the user to find it in the picker; every other key in the file —
+ * `$schema`, the theme, MCP servers, other providers — is carried through.
+ */
+export function mergeOpenCodeConfig(before: string, url: string, key: string, scope = ""): string | null {
+	const root = parseJsonObject(before);
+	if (root === null) return null;
+	const providers = { ...((root.provider as Record<string, unknown> | undefined) ?? {}) };
+	providers[PROVIDER_ID] = {
+		npm: "@ai-sdk/openai-compatible",
+		name: "auto-model-router",
+		options: { baseURL: `${url}/v1`, apiKey: key, headers: harnessHeaders("opencode", scope) },
+		models: Object.fromEntries(PROFILE_IDS.map((id) => [id, { name: id }])),
+	};
+	const next = { ...root, provider: providers, model: `${PROVIDER_ID}/auto` };
+	const after = `${JSON.stringify(next, null, 2)}\n`;
+	return after === before ? null : after;
+}
+
+// ---------------------------------------------------------------------------
+// Cline — automated
+// ---------------------------------------------------------------------------
+
+/** The provider id Cline files an OpenAI-compatible endpoint under; `cline auth -p openai` resolves to it. */
+const CLINE_PROVIDER = "openai-compatible";
+
+/**
+ * Merges the router into Cline's `~/.cline/data/settings/providers.json`.
+ *
+ * The shape was captured by running `cline auth -p openai -b <base> -k <key> -m
+ * auto` — the command the README documents — against an isolated `--data-dir`
+ * on cline 3.0.61: a `version`, the `lastUsedProvider`, and one entry per
+ * provider holding `settings`, an `updatedAt` stamp and a `tokenSource`. One
+ * file serves the CLI and, since the extension's settings migration, the VS
+ * Code extension too, which is also how Cline reaches the router inside an
+ * editor that has no provider settings of its own (see windsurfSnippet).
+ *
+ * Writing the keys rather than shelling out to `cline auth` buys two things
+ * the command cannot give: `--dry-run` can show the change, and `settings.headers`
+ * gets written. That map is in the on-disk schema but has no CLI flag, and it is
+ * what finally gives Cline a harness id — verified live by pointing cline 3.0.61
+ * at a recording server, whose capture is `test/fixtures/harness/cline-cli-connected.json`.
+ *
+ * `updatedAt` is deliberately NOT refreshed when the settings already match: a
+ * stamp that moved on every run would make `connect` write a different file each
+ * time, which is the one thing every path here promises not to do.
+ */
+export function mergeClineProviders(before: string, url: string, key: string, nowIso: string, scope = ""): string | null {
+	const root = parseJsonObject(before);
+	if (root === null) return null;
+	const providers = { ...((root.providers as Record<string, unknown> | undefined) ?? {}) };
+	const entry = (providers[CLINE_PROVIDER] as Record<string, unknown> | undefined) ?? {};
+	const settings = { provider: CLINE_PROVIDER, apiKey: key, model: "auto", baseUrl: `${url}/v1`, headers: harnessHeaders("cline", scope) };
+	if (JSON.stringify(entry.settings) === JSON.stringify(settings) && root.lastUsedProvider === CLINE_PROVIDER) return null;
+	providers[CLINE_PROVIDER] = { ...entry, settings, updatedAt: nowIso, tokenSource: entry.tokenSource ?? "manual" };
+	// `version` leads the file cline writes; spreading root after it keeps that order on a file that has one.
+	const next = { version: 1, ...root, lastUsedProvider: CLINE_PROVIDER, modes: root.modes ?? {}, providers };
+	return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Continue — automated
+// ---------------------------------------------------------------------------
+
+/** The `name:` our model entries carry in Continue's config, and how they are found again on a re-run. */
+const CONTINUE_PREFIX = PROVIDER_ID;
+
+/**
+ * Merges the router's three profiles into Continue's `~/.continue/config.yaml`.
+ *
+ * Continue's documented assistant file is a YAML map with `name`, `version` and
+ * `schema` at the top and a `models:` list under it; an OpenAI-compatible
+ * endpoint is a model entry with `provider: openai` and `apiBase`, `apiKey`,
+ * `roles` and `requestOptions.headers` — the last is what carries the harness
+ * id. Continue was not run here, so this is the documented shape rather than an
+ * observed one; it is automated because the file, its location and its keys are
+ * all published, which is the bar (nothing about it is inferred).
+ *
+ * The edit goes through the YAML *document*, not a re-serialisation of parsed
+ * data, so a hand-written config keeps its comments, key order and quoting and
+ * only our own entries move. Entries are matched by `name`, so a re-run with a
+ * new key replaces them in place instead of appending a second copy.
+ */
+export function mergeContinueConfig(before: string, url: string, key: string, scope = ""): string | null {
+	let doc: Document.Parsed;
+	try {
+		doc = parseDocument(before);
+	} catch {
+		return null;
+	}
+	if (doc.errors.length > 0) return null;
+	// A new file is seeded in the schema's own order rather than assembled key by
+	// key, which would leave the three required fields trailing the model list.
+	if (before.trim() === "") doc = parseDocument(`name: ${PROVIDER_ID}\nversion: 0.0.1\nschema: v1\nmodels:\n`);
+	if (!isMap(doc.contents)) return null;
+	// Required by the schema, and only supplied when the file does not already say otherwise.
+	if (doc.get("name") === undefined) doc.set("name", PROVIDER_ID);
+	if (doc.get("version") === undefined) doc.set("version", "0.0.1");
+	if (doc.get("schema") === undefined) doc.set("schema", "v1");
+	const models = doc.get("models", true);
+	// `models:` with nothing under it parses to a null SCALAR node, not to null itself.
+	if (models === undefined || models === null || (isScalar(models) && models.value === null)) doc.set("models", doc.createNode([]));
+	else if (!isSeq(models)) return null;
+	const seq = doc.get("models", true) as YAMLSeq<unknown>;
+	seq.flow = false; // an empty seq is created in flow style, which would drag every entry onto one line
+	const wanted = PROFILE_IDS.map((id) =>
+		doc.createNode({
+			name: id === "auto" ? CONTINUE_PREFIX : `${CONTINUE_PREFIX}-${id.replace("auto-", "")}`,
+			provider: "openai",
+			model: id,
+			apiBase: `${url}/v1`,
+			apiKey: key,
+			roles: ["chat", "edit", "apply", "summarize"],
+			capabilities: ["tool_use", "image_input"],
+			requestOptions: { headers: harnessHeaders("continue", scope) },
+		}),
+	);
+	const nameOf = (item: unknown): string => (isMap(item) ? String(item.get("name") ?? "") : "");
+	for (const node of wanted) {
+		const name = nameOf(node);
+		const at = seq.items.findIndex((item) => nameOf(item) === name);
+		if (at >= 0) seq.items[at] = node;
+		else seq.items.push(node);
+	}
+	const after = doc.toString();
+	return after === before ? null : after;
+}
+
+// ---------------------------------------------------------------------------
+// Manual paths
+// ---------------------------------------------------------------------------
+
+/**
+ * The values every OpenAI-compatible settings form asks for, as lines.
+ *
+ * Shared by the manual harnesses because the substance is identical in each —
+ * a base URL, a key and a model id — and only the form differs. One renderer
+ * means the three recipes cannot drift apart from each other or from what the
+ * automated paths write.
+ */
+function providerFields(url: string, key: string): string[] {
+	return [`base URL: ${url}/v1`, `API key:  ${key}`, `model:    auto  (also auto-cheap, auto-max)`];
+}
+
+/**
+ * Cursor.
+ *
+ * Cursor's OpenAI override is an application setting in the editor's own state
+ * database, not a documented file: what lives under `~/.cursor` is MCP servers
+ * and rules, and the official key documentation describes only the settings
+ * pane. So the values are printed instead of written.
+ *
+ * The second line is the one that saves an afternoon: Cursor routes chat
+ * through its own servers with the key attached, so the override only works
+ * against a router the internet can reach. A loopback or LAN router cannot
+ * serve Cursor however it is configured — which is worth saying plainly, since
+ * every other harness here is happy with `127.0.0.1`.
+ */
+export function cursorSnippet(url: string, key: string): ManualSnippet {
+	const reachable = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\]|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(url);
+	return {
+		harness: "Cursor",
+		reason: "its OpenAI override lives in the editor's settings, not a file",
+		lines: [
+			"Cursor Settings → Models → OpenAI API Key: enable the base-URL override, then",
+			...providerFields(url, key),
+			"Add `auto` as a custom model and select it. Cursor sends no custom header,",
+			"so its turns carry no X-Omp-Harness id and share the unnamed budget.",
+			...(reachable ? ["WARNING: Cursor proxies chat through its own servers, so this URL must be", "reachable from the internet — a loopback or LAN router will never answer it."] : []),
+		],
+	};
+}
+
+/**
+ * Windsurf.
+ *
+ * Windsurf's own files under `~/.codeium/<channel>` cover MCP servers, rules
+ * and skills; the model provider is not among them, and its bring-your-own-key
+ * page takes first-party provider keys rather than an arbitrary base URL —
+ * there is no field for one to write. So the useful answer is not a snippet of
+ * Windsurf settings at all but the extension route: Windsurf is a VS Code fork,
+ * and the Cline extension reads the same `providers.json` `connect` has already
+ * written, so installing it is the whole configuration.
+ */
+export function windsurfSnippet(clineConfigured: boolean): ManualSnippet {
+	return {
+		harness: "Windsurf",
+		reason: "it has no custom base-URL field; reach the router through an extension",
+		lines: [
+			"Windsurf's own provider settings take first-party keys, not a base URL.",
+			"Install the Cline extension in Windsurf: it reads the same providers.json",
+			clineConfigured ? "this connect just wrote, so it needs no further setup." : "connect writes — re-run `connect --harness cline` once Cline is installed.",
+			"The Continue extension works the same way against ~/.continue/config.yaml.",
+		],
+	};
+}
+
+/** Parses a JSON object file, treating an empty file as `{}` and anything else as not ours. */
+function parseJsonObject(before: string): Record<string, unknown> | null {
+	if (before.trim() === "") return {};
+	try {
+		const parsed = JSON.parse(before) as unknown;
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		return parsed as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}

package/src/index.ts

@@ -29,6 +29,7 @@ Usage: auto-model-router <command> [options]
   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; the remote's skills and its MCP endpoint are installed for Claude Code and omp)
+             --harness omp,hermes,codex,aider,claude,opencode,cline,continue,cursor,windsurf restricts it; cursor and windsurf are printed, not written
   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