auto-model-router 0.1.0

package/docs/claude-anthropic-wire.md

@@ -0,0 +1,116 @@
+# Claude Code support: Anthropic wire front end
+
+Claude Code speaks the **Anthropic Messages API** (`POST /v1/messages`, SSE
+with `message_start`/`content_block_delta`/`message_delta`/`message_stop`).
+The router currently serves only the OpenAI wire (`/v1/chat/completions`), so
+Claude cannot use it yet. This is the plan to add an `anthropic-messages`
+front end so Claude Code gets the router's per-turn cost/complexity routing.
+
+The router core is already wire-agnostic (`src/wire/types.ts` defines
+`NormRequest`/`UpstreamChunk`/`ResponseSink`; `WireProtocol` already lists
+`"pi-native"` as a future front end). Adding Anthropic is a bounded new front
+end, not a core change.
+
+## What Claude Code sends
+
+- `POST /v1/messages` with `{ model, max_tokens, system, messages, tools, stream, thinking }`.
+- Messages: `user`/`assistant` roles with `content` as a string or a
+  content-block array (`text`, `image`, `tool_use`, `tool_result`).
+- Tools: `{ name, description, input_schema }`.
+- SSE response: `message_start`, `content_block_start`, `content_block_delta`
+  (`text_delta`, `input_json_delta`, `thinking_delta`), `content_block_stop`,
+  `message_delta`, `message_stop`.
+
+## Work items
+
+### 1. `src/wire/anthropic/request.ts` — parse `/v1/messages` → `NormRequest`
+
+Mirror `src/wire/openai/request.ts`:
+
+- `parseMessagesRequest(body, headers)` → `NormRequest`.
+- Map Anthropic roles → `NormRole`: `user`/`assistant`/`system` → the router's
+  `system`/`user`/`assistant`; `tool_result`/`tool_use` content blocks → the
+  router's `tool` role with `toolCallId`/`name`/`args`.
+- Flatten `content` blocks (text + image + tool blocks) into `NormMessage`
+  for feature extraction.
+- Parse `tools[].input_schema` → `NormTool` (the router sizes tools for
+  prompt-cost accounting).
+- Parse `thinking` → `ReasoningLevel`.
+- `conversationKeyOf` from the same hash util.
+
+### 2. `src/wire/anthropic/sink.ts` — render `UpstreamChunk` → Anthropic SSE
+
+Mirror `src/wire/openai/sink.ts`:
+
+- `createAnthropicStreamingSink(requestedModel)` → `ResponseSink` that emits
+  Anthropic SSE frames from `StreamEvent`s:
+  - `start` → `message_start` + `content_block_start` (text or tool_use).
+  - `text` → `content_block_delta` with `text_delta`.
+  - `reasoning` → `content_block_delta` with `thinking_delta`.
+  - `tool_call` → `content_block_delta` with `input_json_delta` (partial JSON).
+  - `finish` → `content_block_stop` + `message_delta` (stop_reason) +
+    `message_stop`.
+  - `usage` → `message_delta` with `usage` (input_tokens/output_tokens).
+- `createAnthropicBufferedSink` for non-streaming clients (re-buffer the SSE).
+- Reuse `encodeSseData` from `src/util/sse.ts`.
+
+### 3. `src/wire/anthropic/errors.ts` — map `WireError` → Anthropic error envelope
+
+Anthropic errors are `{ type: "error", error: { type, message } }` with
+`type` ∈ `invalid_request_error` | `authentication_error` | `rate_limit_error`
+| `api_error`. Map the router's `WireError.status`/`code` accordingly.
+
+### 4. `src/server/http.ts` — add `POST /v1/messages` route
+
+- In the `fetch` handler, add `if (req.method === "POST" && url.pathname === "/v1/messages")`.
+- Parse with `parseMessagesRequest`, build the Anthropic sink, call the same
+  `runTurn(normReq, sink, turnDeps, req.signal)` core.
+- Reuse the existing Host validation, auth check, and concurrency cap.
+
+### 5. Upstream dispatch — the key decision
+
+The router dispatches to OpenRouter. OpenRouter accepts **both** Anthropic and
+OpenAI formats. Two options:
+
+- **A (recommended): dispatch to OpenRouter in Anthropic format** for
+  Claude-originated turns. Add an `anthropic-messages` renderer to
+  `src/upstream/openrouter.ts` that builds the `/v1/messages` body from
+  `NormRequest` + `UpstreamMutations`. This preserves Anthropic-native
+  features (thinking blocks, tool_use framing) end to end.
+- **B: dispatch in OpenAI format** and let OpenRouter translate. Simpler, but
+  loses Anthropic-native thinking/tool framing and may degrade Claude's
+  tool-call fidelity.
+
+Recommend **A** — the router's `renderUpstreamBody` is already per-wire, so
+adding an Anthropic variant is consistent.
+
+### 6. `/v1/models` for Claude
+
+Claude Code may probe `/v1/models`. The router already returns the profiles in
+OpenAI shape. If Claude needs Anthropic shape, add a small renderer; otherwise
+reuse the existing list (verify during implementation).
+
+### 7. Tests
+
+- `test/wire-anthropic-request.test.ts` — parse `/v1/messages` bodies
+  (roles, content blocks, tools, thinking) into `NormRequest`.
+- `test/wire-anthropic-sink.test.ts` — render `StreamEvent`s into Anthropic
+  SSE frames (message_start, deltas, tool_use, finish, usage).
+- `test/wire-anthropic-errors.test.ts` — `WireError` → Anthropic envelope.
+- Extend `tools/smoke.ts` with an Anthropic-wire turn against the mock
+  OpenRouter.
+
+## Day-1 support
+
+- **Hermes**: already works (OpenAI wire) — config snippet added to README.
+- **Claude**: requires this front end. Not day-1; a deliberate follow-up.
+
+## Open questions
+
+1. **Upstream dispatch format** — confirm A (Anthropic-native) vs B (OpenAI +
+   OpenRouter translation). Recommend A.
+2. **`/v1/models` shape** — does Claude Code need Anthropic-shaped model
+   metadata, or is the OpenAI list sufficient?
+3. **Thinking blocks** — how faithfully to round-trip Claude's `thinking`
+   through the router's `reasoning` `StreamEvent` (the router already models
+   `reasoning` deltas).

package/omp-extension/configure-logic.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure configuration-driving logic for the `/router configure` slash command.
+ *
+ * Reuses the router's existing wizard field definitions and validation
+ * (`src/cli/config-wizard.ts`) so the in-omp UI edits exactly the same set of
+ * settings as `auto-model-router config`, and persists them through the same
+ * validated merge (`writeRouterConfig`). The only thing this module adds is a
+ * UI-adapter seam so the command can drive omp's native dialogs (`ctx.ui`)
+ * while remaining unit-testable with a fake UI.
+ */
+
+import type { FieldSpec, SectionSpec } from "../src/cli/config-wizard.ts";
+import { CLEAR_TOKEN, formatValue, validateField } from "../src/cli/config-wizard.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+
+export interface ConfigUi {
+	/** Show a selector, return the chosen option label, or undefined on cancel. */
+	select(title: string, options: string[], selected?: number): Promise<string | undefined>;
+	/** Show a text input with a placeholder, or undefined on cancel. */
+	input(title: string, placeholder?: string, initial?: string): Promise<string | undefined>;
+	/** Yes/no confirmation. */
+	confirm(title: string, message: string): Promise<boolean>;
+	/** Surface a status/result line. */
+	notify(text: string, level?: "info" | "warn" | "error"): void;
+}
+
+
+/**
+ * Prompts for one field, returning the parsed value or null when the user kept
+ * the current value. An empty answer keeps the current; CLEAR_TOKEN clears an
+ * optional field. Returns `undefined` when the user cancelled the dialog.
+ */
+export async function promptField(
+	ui: ConfigUi,
+	field: FieldSpec,
+	current: unknown,
+): Promise<{ value: unknown; changed: boolean } | undefined> {
+	const label = field.hint !== undefined ? `${field.label} (${field.hint})` : field.label;
+
+	if (field.kind === "boolean") {
+		const chosen = await ui.select(label, ["true", "false"], current === true ? 0 : 1);
+		if (chosen === undefined) return undefined;
+		const value = chosen === "true";
+		return { value, changed: value !== current };
+	}
+
+	if (field.kind === "enum") {
+		const options = field.options ?? [];
+		const idx = options.indexOf(String(current));
+		const chosen = await ui.select(label, [...options], idx >= 0 ? idx : 0);
+		if (chosen === undefined) return undefined;
+		return { value: chosen, changed: chosen !== current };
+	}
+
+	// string | number | stringArray: free-text input.
+	const placeholder = formatValue(current);
+	const answer = await ui.input(label, placeholder, "");
+	if (answer === undefined) return undefined;
+	if (answer.trim() === "") return { value: current, changed: false }; // keep
+	if (answer.trim() === CLEAR_TOKEN) {
+		if (field.optional !== true) return { value: current, changed: false };
+		return { value: null, changed: true };
+	}
+
+	const result = validateField(field, answer);
+	if (!result.ok) {
+		ui.notify(`invalid: ${result.error}`, "warn");
+		return { value: current, changed: false };
+	}
+	return { value: result.value, changed: result.value !== current };
+}
+
+/**
+ * Walks a section's fields, prompting the user for each and collecting edits
+ * into `answers`. Returns true if any field changed, false if the walk was
+ * cancelled (a dialog returned undefined).
+ */
+export async function walkSection(
+	ui: ConfigUi,
+	section: SectionSpec,
+	cfg: RouterConfig,
+	answers: Record<string, unknown>,
+): Promise<boolean> {
+	let any = false;
+	for (const field of section.fields) {
+		const current = field.path in answers ? answers[field.path] : getPathValue(cfg, field.path);
+		const result = await promptField(ui, field, current);
+		if (result === undefined) return false;
+		if (result.changed) {
+			answers[field.path] = result.value;
+			any = true;
+		}
+	}
+	return any;
+}
+
+/** Reads a dotted path from the config, with `undefined` for missing keys. */
+function getPathValue(obj: unknown, path: string): unknown {
+	let cur: unknown = obj;
+	for (const part of path.split(".")) {
+		if (typeof cur !== "object" || cur === null) return undefined;
+		cur = (cur as Record<string, unknown>)[part];
+	}
+	return cur;
+}
+
+/** Section titles in menu order, mirroring `omp config`'s menu. */
+export function sectionTitles(sections: readonly SectionSpec[]): string[] {
+	return sections.map((s) => s.title);
+}
+
+/**
+ * Edits one virtual profile (a whole array element) through the UI. Returns
+ * the updated profile record, or null when cancelled.
+ */
+export async function editProfile(
+	ui: ConfigUi,
+	profile: Record<string, unknown>,
+	fields: readonly FieldSpec[],
+): Promise<Record<string, unknown> | null> {
+	const next: Record<string, unknown> = { ...profile };
+	for (const field of fields) {
+		const result = await promptField(ui, field, next[field.path]);
+		if (result === undefined) return null;
+		if (result.changed) next[field.path] = result.value;
+	}
+	return next;
+}

package/omp-extension/embed-logic.ts

@@ -0,0 +1,141 @@
+/**
+ * Pure embed configuration logic, extracted from the omp extension so it can
+ * be unit-tested without omp's runtime or a live Bun.serve.
+ *
+ * The embedded router runs IN the main omp process and binds a free
+ * OS-assigned port (`port: 0`). Subagents do NOT bind their own router — they
+ * route to the main session's router, whose bound port is published in a
+ * single shared file. This avoids the PID-reuse race: subagents are ephemeral
+ * worker processes whose PIDs get recycled, so keying a port file by PID means
+ * a subagent can read a stale file written by a dead worker that reused its
+ * PID. One shared file, written only by the main session, has exactly one
+ * authoritative writer.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * The provider id registered into omp. Kept stable so a `models.yml` that
+ * already pins `baseUrl`/`auth` for the same id is overridden by the
+ * extension (extension registration wins at runtime).
+ */
+export const EMBED_PROVIDER_ID = "auto-model-router";
+
+/**
+ * A dummy bearer the extension registers so omp treats the provider as
+ * authenticated. The router's `server.apiKey` is unset by default, so it does
+ * not enforce auth; the value only needs to satisfy omp's "has credentials"
+ * gate.
+ */
+export const EMBED_DUMMY_API_KEY = "embedded";
+
+/**
+ * Filename (in `$AUTO_MODEL_ROUTER_HOME` / `~/.auto-model-router`) of the shared embed port
+ * file. Written only by the main session's router; read by every subagent and
+ * the toast. A single writer and single file means there is never a stale
+ * per-PID file pointing at a recycled process's dead port.
+ */
+export const EMBED_PORT_FILE = "embed.port";
+
+export interface EmbedModelSpec {
+	id: string;
+	name: string;
+	contextWindow: number;
+	maxTokens: number;
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+}
+
+export interface EmbedConfig {
+	port: number;
+	host: string;
+	baseUrl: string;
+	models: EmbedModelSpec[];
+	harnessId?: string;
+}
+
+/**
+ * Resolves the desired bind port: an explicit `AUTO_MODEL_ROUTER_PORT` when set and
+ * valid, else `0` so Bun assigns a free ephemeral port (the "random port" that
+ * lets multiple local omp sessions coexist without colliding). Returning 0
+ * means "let the OS pick"; the caller must read the actual port back off the
+ * started server.
+ */
+export function resolveEmbedPort(envPort: string | undefined): number {
+	if (envPort !== undefined && envPort !== "") {
+		const port = Number.parseInt(envPort, 10);
+		if (Number.isInteger(port) && port >= 0 && port <= 65_535) return port;
+	}
+	return 0;
+}
+
+/**
+ * Absolute path of the shared embed port file under a router home directory.
+ */
+export function embedPortPath(homeDir: string): string {
+	return join(homeDir, EMBED_PORT_FILE);
+}
+
+/**
+ * Persists the embedded router's actual bound port so subagents and the toast
+ * can follow it. Creates the parent directory when absent.
+ */
+export function writeEmbedPort(path: string, port: number): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, String(port), "utf8");
+}
+
+/**
+ * Reads the embedded router's last-known port from the port file, or null when
+ * the file is absent/unreadable/malformed.
+ */
+export function readEmbedPort(path: string): number | null {
+	try {
+		const raw = readFileSync(path, "utf8").trim();
+		const port = Number.parseInt(raw, 10);
+		if (Number.isInteger(port) && port > 0 && port <= 65_535) return port;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Builds the provider config for `pi.registerProvider(EMBED_PROVIDER_ID, …)`
+ * given the shared bound port. `models` are the router's own `profiles`, mapped
+ * into omp's provider-model shape (cost is USD per million tokens, same unit
+ * `renderProviderBlock` uses for `config --write`). A wildcard listen address
+ * maps to loopback, since a wildcard is not a connectable target.
+ */
+export function buildProviderConfig(
+	port: number,
+	cfg: {
+		server: { host: string; harnessId?: string };
+		profiles: Array<{ id: string; name: string; contextWindow: number; maxTokens: number }>;
+		ledger: { fallbackBlend: { inputPerMtok: number; outputPerMtok: number } };
+	},
+): EmbedConfig {
+	const host = cfg.server.host === "0.0.0.0" || cfg.server.host === "::" ? "127.0.0.1" : cfg.server.host;
+	const round = (v: number): number => Math.round(v * 1e4) / 1e4;
+	const input = cfg.ledger.fallbackBlend.inputPerMtok;
+	const output = cfg.ledger.fallbackBlend.outputPerMtok;
+	const cacheRead = input * 0.1;
+	const cacheWrite = input * 1.25;
+	const models = cfg.profiles.map((p) => ({
+		id: p.id,
+		name: p.name,
+		contextWindow: p.contextWindow,
+		maxTokens: p.maxTokens,
+		cost: { input: round(input), output: round(output), cacheRead: round(cacheRead), cacheWrite: round(cacheWrite) },
+	}));
+	const out: EmbedConfig = {
+		port,
+		host,
+		baseUrl: `http://${host}:${port}/v1`,
+		models,
+	};
+	if (cfg.server.harnessId !== undefined && cfg.server.harnessId !== "") {
+		out.harnessId = cfg.server.harnessId;
+	}
+	return out;
+}

package/omp-extension/router-configure.ts

@@ -0,0 +1,111 @@
+/**
+ * omp extension: `/router` — edit auto-model-router's settings through
+ * omp's native UI dialogs.
+ *
+ * The command walks the same sections and fields as `auto-model-router config`
+ * (reusing `WIZARD_SECTIONS` / `PROFILE_FIELDS` from the router's CLI) but
+ * prompts through `ctx.ui` select/input/confirm dialogs instead of stdin.
+ * Edits are persisted through the router's own validated merge
+ * (`writeRouterConfig`), so the on-disk config.yml is schema-checked and
+ * backed up exactly as the CLI wizard does.
+ *
+ * Install alongside router-embed.ts:
+ *
+ *   # ~/.omp/agent/config.yml
+ *   extensions:
+ *     - /path/to/auto-model-router/omp-extension/router-embed.ts
+ *     - /path/to/auto-model-router/omp-extension/router-configure.ts
+ *
+ * Run `/router` in an omp session to pick a section, edit its
+ * fields, and save.
+ */
+
+import { loadConfig } from "../src/config/load.ts";
+import { applyAnswers, PROFILE_FIELDS, WIZARD_SECTIONS } from "../src/cli/config-wizard.ts";
+import { writeRouterConfig, routerConfigPath } from "../src/cli/config-cmd.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+import { editProfile, sectionTitles, walkSection, type ConfigUi } from "./configure-logic.ts";
+
+export default function (pi: ExtensionAPI): void {
+	pi.setLabel("auto-model-router configure");
+
+	pi.registerCommand("router", {
+		description: "Configure auto-model-router settings through the native UI",
+		handler: async (_args, ctx) => {
+			const ui = ctx.ui;
+			const cfg = loadConfig();
+			const answers: Record<string, unknown> = {};
+
+			for (;;) {
+				const options = [...sectionTitles(WIZARD_SECTIONS), "Profiles", "Save and exit", "Quit without saving"];
+				const chosen = await ui.select("auto-model-router configure", options);
+				if (chosen === undefined) return;
+				if (chosen === "Quit without saving") return;
+				if (chosen === "Save and exit") break;
+
+				if (chosen === "Profiles") {
+					await editProfiles(ui, cfg, answers);
+					continue;
+				}
+
+				const section = WIZARD_SECTIONS.find((s) => s.title === chosen);
+				if (section === undefined) continue;
+				await walkSection(ui, section, cfg, answers);
+			}
+
+			if (Object.keys(answers).length === 0) {
+				ui.notify("no changes made", "info");
+				return;
+			}
+
+			try {
+				const target = routerConfigPath();
+				const partial = applyAnswers(answers);
+				const backup = writeRouterConfig(target, partial);
+				ui.notify(`wrote ${target}${backup ? ` (backup: ${backup})` : ""}`, "info");
+			} catch (err) {
+				ui.notify(err instanceof Error ? err.message : String(err), "error");
+			}
+		},
+	});
+}
+
+/** Edits the profiles array as whole elements, mirroring the CLI wizard. */
+async function editProfiles(
+	ui: ConfigUi,
+	cfg: RouterConfig,
+	answers: Record<string, unknown>,
+): Promise<void> {
+	// Work over the profiles as plain records (the shape the wizard's merge
+	// expects), converting at the boundary to/from ProfileConfig.
+	const list: Record<string, unknown>[] = cfg.profiles.map((p) => ({ ...p }));
+	const names = list.map((p, i) => `${i + 1}) ${p.id} (${p.name})`);
+	const choice = await ui.select("Profiles", [...names, "+ Add profile", "Back"]);
+	if (choice === undefined || choice === "Back") return;
+
+	if (choice === "+ Add profile") {
+		const blank: Record<string, unknown> = {
+			id: "",
+			name: "",
+			minTier: "trivial",
+			maxTier: "hard",
+			contextWindow: 400000,
+			maxTokens: 32000,
+		};
+		const updated = await editProfile(ui, blank, PROFILE_FIELDS);
+		if (updated === null || updated.id === "" || updated.name === "") return;
+		answers.profiles = [...list, updated];
+		return;
+	}
+
+	const idx = names.indexOf(choice);
+	if (idx < 0) return;
+	const updated = await editProfile(ui, list[idx] ?? {}, PROFILE_FIELDS);
+	if (updated === null) return;
+	const next = list.slice();
+	next[idx] = updated;
+	answers.profiles = next;
+}

package/omp-extension/router-embed.ts

@@ -0,0 +1,118 @@
+/**
+ * omp extension: run auto-model-router IN the omp process.
+ *
+ * The MAIN omp session embeds the router: it binds a free OS-assigned port,
+ * publishes it to the shared `$AUTO_MODEL_ROUTER_HOME/embed.port`, and registers the
+ * auto-model-router provider. Subagents do NOT bind their own router — they are
+ * ephemeral worker processes whose PIDs get recycled, so a per-PID port file
+ * is a race. Instead every subagent registers the same shared provider and
+ * routes to the main session's single router.
+ *
+ * The discriminator is `ctx.hasUI`: the main interactive session has a UI,
+ * subagents do not.
+ *
+ * Install by adding this file's absolute path to omp's `extensions:` list:
+ *
+ *   # ~/.omp/agent/config.yml
+ *   extensions:
+ *     - /path/to/auto-model-router/omp-extension/router-embed.ts
+ *     - /path/to/auto-model-router/omp-extension/router-toast.ts
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { loadConfig } from "../src/config/load.ts";
+import { startServer } from "../src/server/http.ts";
+import type { StartedServer } from "../src/server/http.ts";
+import type { RouterConfig } from "../src/config/types.ts";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+import {
+	buildProviderConfig,
+	EMBED_DUMMY_API_KEY,
+	EMBED_PROVIDER_ID,
+	embedPortPath,
+	readEmbedPort,
+	resolveEmbedPort,
+	writeEmbedPort,
+} from "./embed-logic.ts";
+
+/**
+ * Registers the auto-model-router provider (and its virtual models) into omp's model
+ * registry at a specific bound port.
+ */
+function registerRouterProvider(pi: ExtensionAPI, port: number, cfg: RouterConfig): void {
+	const providerConfig = buildProviderConfig(port, cfg);
+	pi.registerProvider(EMBED_PROVIDER_ID, {
+		baseUrl: providerConfig.baseUrl,
+		api: "openai-completions",
+		apiKey: EMBED_DUMMY_API_KEY,
+		...(providerConfig.harnessId !== undefined && providerConfig.harnessId !== ""
+			? { headers: { "X-Omp-Harness": providerConfig.harnessId } }
+			: {}),
+		models: providerConfig.models.map((m) => ({
+			id: m.id,
+			name: m.name,
+			api: "openai-completions",
+			reasoning: false,
+			input: ["text", "image"],
+			contextWindow: m.contextWindow,
+			maxTokens: m.maxTokens,
+			cost: {
+				input: m.cost.input,
+				output: m.cost.output,
+				cacheRead: m.cost.cacheRead,
+				cacheWrite: m.cost.cacheWrite,
+			},
+		})),
+	});
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.setLabel("auto-model-router embed");
+
+	const requestedPort = resolveEmbedPort(process.env.AUTO_MODEL_ROUTER_PORT);
+
+	// Shared port file, written only by the main session's router.
+	const homeRaw = process.env.AUTO_MODEL_ROUTER_HOME ?? join(homedir(), ".auto-model-router");
+	const home =
+		homeRaw === "~" || homeRaw.startsWith("~/") || homeRaw.startsWith("~\\")
+			? join(homedir(), homeRaw.slice(1))
+			: homeRaw;
+	const portFile = embedPortPath(home);
+	const cfg = loadConfig({ overrides: { server: { host: "127.0.0.1", port: requestedPort } } });
+
+	let app: StartedServer | null = null;
+
+	pi.on("session_start", (_event, ctx) => {
+		// Subagents and headless sessions do not bind their own router; they
+		// route to the main's router via the shared port file. The main writes
+		// the file before spawning subagents, so the port is available here.
+		if (!ctx.hasUI) {
+			const port = readEmbedPort(portFile);
+			if (port !== null) registerRouterProvider(pi, port, cfg);
+			return;
+		}
+
+		// Main interactive session: bind the router once, then register the
+		// provider against the exact bound port. Registration happens only
+		// here — never at factory load, where a stale shared port would be
+		// captured into omp's model registry and defeat the correct bound URL.
+		if (app) return;
+		const started = startServer(cfg);
+		const actualPort = started.server.port;
+		if (actualPort === undefined) return;
+		app = started;
+
+		// Publish the shared port; subagents and the toast read it from here.
+		writeEmbedPort(portFile, actualPort);
+		registerRouterProvider(pi, actualPort, cfg);
+
+		pi.on("session_shutdown", () => {
+			void app?.stop().catch(() => {});
+			app = null;
+		});
+	});
+}