auto-model-router 0.18.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.18.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.18.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
@@ -694,7 +762,9 @@ virtual profile it picked. Every routed response carries
 
 The ledger records every dispatch: model decided and served, tier, provider,
 tokens (including cached), reported cost, time to first token, total latency,
-escalation signal, error. Three views aggregate it, all from the same
+escalation signal, error, and the agentdox context scope the turn carried (the
+project it belongs to; NULL for a turn that carried none, and for every row
+written before v0.19.0). Three views aggregate it, all from the same
 `buildUsageReport` in `src/cost/report.ts`:
 
 - `/router report` in omp — a fullscreen hub with the `/models` look: views
@@ -706,10 +776,12 @@ escalation signal, error. Three views aggregate it, all from the same
   transcript. Falls back to reading the ledger directly if the router is
   unreachable.
 - `auto-model-router report --days 7 [--harness <id>] [--json]` on the terminal.
-- `auto-model-router export --days 30 [--harness a,b] [--json]`: one row per day, harness
-  and model (dispatches, tokens, spend, escalations, errors) as CSV. Also
-  `GET /v1/router/export?days=&harness=[&format=json]`; `GET /v1/router/spend?sinceMs=&harness=`
-  gives spend over a harness set since an instant, and `GET /v1/router/feedback?days=&harness=`
+- `auto-model-router export --days 30 [--harness a,b] [--json]`: one row per day, harness,
+  model and context scope (dispatches, tokens, spend, escalations, errors) as CSV — the
+  `scope` column is last, and is empty for a turn that carried none. Also
+  `GET /v1/router/export?days=&harness=[&format=json]`; `GET /v1/router/spend?sinceMs=&harness=[&scope=]`
+  gives spend over a harness set since an instant, narrowed to one context scope when `scope`
+  is given (a project's own bill), and `GET /v1/router/feedback?days=&harness=`
   lists verdicts by model and the recent ones with the harness that gave them, and
   `GET /v1/router/decisions?harness=&days=|since=&slug=&tier=&limit=` is the decision trail
   itself, newest first, each turn with its reasons, the classifier's view, forecast against
@@ -1309,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
@@ -1470,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 | — | — | — | — | — | — | — | — |
 
@@ -1555,6 +1641,20 @@ a team posts exactly what it always did, so its block is byte-identical; an olde
 agentdox ignores the keys it does not know. `context.layers: false` is the kill
 switch — the headers are still parsed but nothing new goes to agentdox.
 
+### Charging spend back to a project
+
+Every ledger row records the scope the bridge resolved for that turn — the
+request's `X-Agentdox-Scope`, or `context.defaultScope` behind it — so the money
+and the project are the same row. That is what a front door bills from: it names
+a project's scope on the turns it forwards, then reads its share back with
+`GET /v1/router/spend?sinceMs=&scope=<scope>` (composable with `harness=`, so one
+member's spend on one project is one call), or takes the whole split from
+`GET /v1/router/export`, whose rows now group by day, harness, model **and**
+scope and carry the scope as their last CSV column. `decisionEntries` (and
+`GET /v1/router/decisions`) carry it on each turn too. Rows written before
+v0.19.0, and turns that carried no scope at all, store NULL and export as `""` —
+old ledgers open and gain the column, they just have nothing to charge.
+
 ### The origin fingerprint
 
 The scope is the folder's name, and folder names collide: two unrelated repositories

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-model-router",
-  "version": "0.18.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}`);