@sangyaahub/pi-marg 1.0.4 → 1.0.6

package/adapters/omp/extensions/provider-setup.ts

@@ -0,0 +1,177 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  probeModelIds,
+  validateCustomProvider,
+  writeCustomProvider,
+  type CustomProviderInput,
+} from "../../../core/provider-config";
+import {
+  numberedOptionLabel,
+  resolveSelectAnswer,
+  type ModelLike,
+} from "../../../core/model-routing";
+import { agentDirectory } from "../../../core/user-route";
+
+const SETUP_ITEMS = [
+  "Sign in to a provider",
+  "Add a custom OpenAI-compatible provider",
+  "Cancel",
+] as const;
+
+const DISTINCT_ITEMS = [
+  "Add another model",
+  "Continue and stop before the paired stage",
+] as const;
+
+export type CatalogSetup =
+  | { status: "ready"; models: ModelLike[] }
+  | { status: "cancelled" }
+  | { status: "restart" };
+
+async function askText(ctx: any, title: string, placeholder: string, masked = false): Promise<string | undefined> {
+  const value = await ctx.ui.input(title, placeholder, masked ? { masked: true } : undefined);
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed) {
+    ctx.ui.notify("Selection cancelled; no model was saved.", "warning");
+    return undefined;
+  }
+  return trimmed;
+}
+
+async function askItems<T extends string>(
+  ctx: any,
+  title: string,
+  items: readonly T[],
+): Promise<T | undefined> {
+  const answer = await ctx.ui.select(
+    title,
+    items.map((item, index) => numberedOptionLabel(index, item)),
+    { selectionMarker: "radio" },
+  );
+  const resolved = resolveSelectAnswer(answer, items, (item) => item);
+  switch (resolved.status) {
+    case "matched":
+      return resolved.item;
+    case "cancelled":
+      ctx.ui.notify("Selection cancelled; no model was saved.", "warning");
+      return undefined;
+    case "conflict":
+      ctx.ui.notify("That answer matches more than one option; no model was saved.", "error");
+      return undefined;
+    case "unrecognized":
+      ctx.ui.notify(`Unrecognized selection ${JSON.stringify(resolved.received)}; no model was saved.`, "error");
+      return undefined;
+    default: {
+      const unreachable: never = resolved;
+      return unreachable;
+    }
+  }
+}
+
+function envAlreadySet(home: string | undefined, name: string): boolean {
+  if (process.env[name]) return true;
+  const envPath = join(agentDirectory("OMP", home), ".env");
+  if (!existsSync(envPath)) return false;
+  return new RegExp(`^${name}=`, "m").test(readFileSync(envPath, "utf8"));
+}
+
+async function chooseProbedIds(ctx: any, typed: string[], probed: string[]): Promise<string[] | undefined> {
+  const items = ["Keep the model ids I typed", "Use every returned id", ...probed];
+  const choice = await askItems(ctx, "Models to register", items);
+  if (!choice) return undefined;
+  if (choice === "Keep the model ids I typed") return typed;
+  if (choice === "Use every returned id") return probed;
+  return [choice];
+}
+
+export async function addCustomProvider(ctx: any, home: string | undefined): Promise<CatalogSetup> {
+  const providerId = await askText(ctx, "Custom provider", "Provider id (lowercase)");
+  if (!providerId) return { status: "cancelled" };
+  const displayName = await askText(ctx, "Custom provider", "Display name");
+  if (!displayName) return { status: "cancelled" };
+  const baseUrl = await askText(ctx, "Custom provider", "Base URL");
+  if (!baseUrl) return { status: "cancelled" };
+  let allowLocalHttp = false;
+  try {
+    const url = new URL(baseUrl);
+    if (url.protocol === "http:" && url.hostname === "127.0.0.1") {
+      const confirm = await askItems(ctx, "Local endpoint", ["Use this local http endpoint", "Cancel"]);
+      if (confirm !== "Use this local http endpoint") return { status: "cancelled" };
+      allowLocalHttp = true;
+    }
+  } catch {
+    ctx.ui.notify("Base URL must be an https URL.", "error");
+    return { status: "cancelled" };
+  }
+  const envVar = await askText(ctx, "Custom provider", "Env var name");
+  if (!envVar) return { status: "cancelled" };
+  const modelText = await askText(ctx, "Custom provider", "Model ids, comma-separated");
+  if (!modelText) return { status: "cancelled" };
+  let modelIds = modelText.split(",").map((id) => id.trim()).filter(Boolean);
+  const secret = envAlreadySet(home, envVar) ? undefined : await askText(ctx, "Custom provider", `${envVar} value`, true);
+  if (!envAlreadySet(home, envVar) && !secret) return { status: "cancelled" };
+
+  const draft: CustomProviderInput = {
+    providerId,
+    displayName,
+    baseUrl,
+    envVar,
+    modelIds,
+    allowLocalHttp,
+  };
+  const problem = validateCustomProvider(draft);
+  if (problem) {
+    ctx.ui.notify(problem, "error");
+    return { status: "cancelled" };
+  }
+
+  const probeKey = secret ?? process.env[envVar];
+  if (probeKey) {
+    const probed = await probeModelIds(baseUrl, probeKey);
+    if (probed) {
+      const chosen = await chooseProbedIds(ctx, modelIds, probed);
+      if (!chosen) return { status: "cancelled" };
+      modelIds = chosen;
+      draft.modelIds = chosen;
+    }
+  }
+
+  try {
+    const directory = agentDirectory("OMP", home);
+    writeCustomProvider({
+      modelsPath: join(directory, "models.yml"),
+      envPath: join(directory, ".env"),
+    }, draft, secret);
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : "Could not write the provider.", "error");
+    return { status: "cancelled" };
+  }
+
+  if (typeof ctx.models?.reload === "function") {
+    await ctx.models.reload();
+  }
+  const models = (ctx.models.list() ?? []) as ModelLike[];
+  if (models.length === 0) return { status: "restart" };
+  return { status: "ready", models };
+}
+
+export async function configureEmptyCatalog(ctx: any, home: string | undefined): Promise<CatalogSetup> {
+  const choice = await askItems(ctx, "Model setup", SETUP_ITEMS);
+  if (!choice || choice === "Cancel") return { status: "cancelled" };
+  if (choice === "Sign in to a provider") {
+    if (typeof ctx.openLogin === "function") await ctx.openLogin();
+    else ctx.ui.notify("Sign in with /login, verify with `omp models`, then run /pi-marg again.", "warning");
+    const models = (ctx.models.list() ?? []) as ModelLike[];
+    return models.length > 0 ? { status: "ready", models } : { status: "cancelled" };
+  }
+  return addCustomProvider(ctx, home);
+}
+
+export async function resolveSingleModel(ctx: any, home: string | undefined): Promise<CatalogSetup | "defer"> {
+  const choice = await askItems(ctx, "Distinct models", DISTINCT_ITEMS);
+  if (!choice) return { status: "cancelled" };
+  if (choice === "Continue and stop before the paired stage") return "defer";
+  return addCustomProvider(ctx, home);
+}

package/adapters/pi/extensions/model-router.ts

@@ -12,10 +12,10 @@ import {
   hasConfiguredFallback,
   modelFailureKey,
   modelToolUsageLimitFailure,
-  restoreModelRouteState,
   type ModelLike,
   type ModelRouteParams,
 } from "../../../core/model-routing";
+import { loadRuntimeRoute, rememberRuntimeRoute } from "../../../core/user-route";
 
 function toolNames(pi: any): string[] {
   return (pi.getAllTools?.() ?? [])
@@ -38,12 +38,21 @@ export default function modelRouter(pi: any) {
   let sessionGeneration = 0;
   let pendingModelFailure: { selector: string; key: string } | undefined;
   let pendingToolFailure: { selector: string; key: string } | undefined;
+  const routeHome = (ctx: any) => typeof ctx?.agentHome === "string" ? ctx.agentHome : undefined;
+  const persistRoute = (nextState: Parameters<typeof rememberRuntimeRoute>[1], ctx?: any) => {
+    pi.appendEntry(MODEL_STATE_TYPE, nextState);
+    try {
+      rememberRuntimeRoute("Pi", nextState, routeHome(ctx));
+    } catch {
+      ctx?.ui?.notify?.("PiMarg saved the route in this session, but could not update the user route file.", "warning");
+    }
+  };
   const restore = (_event: unknown, ctx: any) => {
     sessionGeneration += 1;
     recoveryToken = undefined;
     pendingModelFailure = undefined;
     pendingToolFailure = undefined;
-    state = restoreModelRouteState(ctx.sessionManager.getBranch());
+    state = loadRuntimeRoute("Pi", ctx.sessionManager.getBranch(), routeHome(ctx));
   };
 
   pi.on("session_start", restore);
@@ -63,7 +72,7 @@ export default function modelRouter(pi: any) {
         activate: (model) => pi.setModel(model),
         persist: (nextState) => {
           if (sessionGeneration !== generation) throw new Error("session changed during automatic recovery");
-          pi.appendEntry(MODEL_STATE_TYPE, nextState);
+          persistRoute(nextState, ctx);
         },
       }, failure.key);
       if (sessionGeneration !== generation) {
@@ -162,7 +171,7 @@ export default function modelRouter(pi: any) {
         models,
         hasExternalDevin: hasExternalDevin(pi),
         activate: (model) => pi.setModel(model),
-        persist: (nextState) => pi.appendEntry(MODEL_STATE_TYPE, nextState),
+        persist: (nextState) => persistRoute(nextState, ctx),
       });
       state = execution.state;
       return execution.response;

package/adapters/pi/prompts/auto-models.md

@@ -5,8 +5,8 @@ argument-hint: [status | choose]
 
 Load `auto-mode-router` and read its model-routing reference.
 
-- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover.
-- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
+- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover. Show a saved selector as `missing` when status says it is no longer in the live catalog. Do not remap it to a similarly named model.
+- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Show the saved selectors first and pass each one as the initially selected choice before asking for a replacement. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
 - Do not type or persist a model ID that the live catalog did not return.
 - Treat any model returned by Pi's registry as a normal in-session route. Treat Devin or another external coding-agent session as a capability-gated external route; creating one requires `post-web` approval.
 - C/D are the authoritative independent review selectors. Any detected advisor or watcher is supplemental and must not weaken the A≠C or B≠D checks.

package/commands/auto-models.md

@@ -5,8 +5,8 @@ argument-hint: [status | choose]
 
 Load `auto-mode-router` and read its model-routing reference.
 
-- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover.
-- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
+- With no argument or `status`, call `auto_model_route` with `action: status`, then show the saved A/B/C/D selectors, separation checks, high/low backups, active fallback, and last failover. Show a saved selector as `missing` when status says it is no longer in the live catalog. Do not remap it to a similarly named model.
+- With `choose`, call `auto_model_route` with `action: catalog` and the active work type. Show the saved selectors first and pass each one as the initially selected choice before asking for a replacement. Present required stages and exact available selectors. Save each stage with `action: select`, then save two distinct runtime models with `action: select_fallback`, first `fallback: high`, then `fallback: low`.
 - Do not type or persist a model ID that the live catalog did not return.
 - Distinguish native `devin/swe-*` OMP models from the optional external `devin/mcp-session` route. Only creating the external session requires `post-web` approval.
 - C/D are the authoritative independent review selectors. A configured OMP advisor is supplemental and must not weaken the A≠C or B≠D checks.

package/core/model-routing.ts

@@ -36,9 +36,13 @@ export interface ModelSelection extends ModelCandidate {
   selectedAt: string;
 }
 
+export type WorkBoundary = "Job/client" | "Personal";
+
 export interface ModelRouteState {
   version: 2;
   workType?: number;
+  boundary?: WorkBoundary;
+  skillMode?: string;
   selections: Partial<Record<AutoStage, ModelSelection>>;
   fallbacks: Partial<Record<FallbackLevel, ModelSelection>>;
   activeStage?: AutoStage;
@@ -370,6 +374,38 @@ export function buildFallbackCatalog(catalog: Record<AutoStage, ModelCandidate[]
   } satisfies Record<FallbackLevel, ModelCandidate[]>;
 }
 
+export interface SavedChoiceAvailability {
+  status: "present" | "missing";
+  selection: ModelSelection;
+}
+
+export function revalidateSavedRoute(
+  state: ModelRouteState,
+  models: readonly ModelLike[],
+  hasExternalDevin: boolean,
+): {
+  selections: Partial<Record<AutoStage, SavedChoiceAvailability>>;
+  fallbacks: Partial<Record<FallbackLevel, SavedChoiceAvailability>>;
+} {
+  const catalog = buildModelCatalog([...models], hasExternalDevin);
+  const fallbackCatalog = buildFallbackCatalog(catalog);
+  const selections: Partial<Record<AutoStage, SavedChoiceAvailability>> = {};
+  for (const stage of STAGES) {
+    const selection = state.selections[stage];
+    if (!selection) continue;
+    const live = catalog[stage].some((item) => item.selector === selection.selector);
+    selections[stage] = { status: live ? "present" : "missing", selection };
+  }
+  const fallbacks: Partial<Record<FallbackLevel, SavedChoiceAvailability>> = {};
+  for (const level of FALLBACK_LEVELS) {
+    const selection = state.fallbacks[level];
+    if (!selection) continue;
+    const live = fallbackCatalog[level].some((item) => item.selector === selection.selector);
+    fallbacks[level] = { status: live ? "present" : "missing", selection };
+  }
+  return { selections, fallbacks };
+}
+
 export function numberedOptionLabel(index: number, text: string): string {
   return `${index + 1}. ${text}`;
 }
@@ -383,6 +419,42 @@ export function matchNumberedOption<T>(
   return items.find((item, index) => numberedOptionLabel(index, labelOf(item)) === answer);
 }
 
+export type SelectAnswerResolution<T> =
+  | { status: "cancelled" }
+  | { status: "matched"; item: T }
+  | { status: "conflict" }
+  | { status: "unrecognized"; received: string };
+
+const DISAMBIGUATION_SUFFIX = /^(?: \(\d+\)| · .+)$/;
+
+export function resolveSelectAnswer<T>(
+  answer: string | undefined,
+  items: readonly T[],
+  labelOf: (item: T) => string,
+): SelectAnswerResolution<T> {
+  if (answer === undefined) return { status: "cancelled" };
+  const received = answer.trim();
+  if (!received) return { status: "cancelled" };
+
+  const numbered = items.filter((item, index) => numberedOptionLabel(index, labelOf(item)) === received);
+  if (numbered.length > 1) return { status: "conflict" };
+  if (numbered.length === 1) return { status: "matched", item: numbered[0]! };
+
+  const exact = items.filter((item) => labelOf(item) === received);
+  if (exact.length > 1) return { status: "conflict" };
+  if (exact.length === 1) return { status: "matched", item: exact[0]! };
+
+  const suffixed = items.filter((item) => {
+    const label = labelOf(item);
+    if (!received.startsWith(label) || received.length === label.length) return false;
+    return DISAMBIGUATION_SUFFIX.test(received.slice(label.length));
+  });
+  if (suffixed.length > 1) return { status: "conflict" };
+  if (suffixed.length === 1) return { status: "matched", item: suffixed[0]! };
+
+  return { status: "unrecognized", received };
+}
+
 export function uniqueProviders(candidates: readonly ModelCandidate[]): string[] {
   return [...new Set(candidates.map((candidate) => candidate.provider))].sort((left, right) => left.localeCompare(right));
 }
@@ -621,6 +693,59 @@ export async function executeAutomaticFailover(
   };
 }
 
+export interface IntakeRouteDraft {
+  workType: number;
+  boundary?: WorkBoundary;
+  skillMode?: string;
+  selections: Partial<Record<AutoStage, ModelCandidate>>;
+  fallbacks: Record<FallbackLevel, ModelCandidate>;
+  activateStage: AutoStage;
+}
+
+export async function commitIntakeRoute(
+  currentState: ModelRouteState,
+  intake: IntakeRouteDraft,
+  port: ModelRoutePort,
+): Promise<{ state: ModelRouteState; error?: string }> {
+  const selected = intake.selections[intake.activateStage];
+  if (!selected) {
+    return { state: currentState, error: `Stage ${intake.activateStage} has no model to activate.` };
+  }
+  if (selected.access === "runtime-model") {
+    const model = port.models.find((item) => `${item.provider}/${item.id}` === selected.selector);
+    const failure = `Could not activate ${selected.selector}; verify ${selected.provider} authentication.`;
+    if (!model) return { state: currentState, error: failure };
+    try {
+      const activated = await port.activate(model);
+      if (activated === false) return { state: currentState, error: failure };
+    } catch {
+      return { state: currentState, error: failure };
+    }
+  }
+
+  const selectedAt = port.now?.() ?? new Date().toISOString();
+  const selections = Object.fromEntries(
+    Object.entries(intake.selections).map(([stage, candidate]) => [stage, { ...candidate, selectedAt }]),
+  ) as ModelRouteState["selections"];
+  const fallbacks = Object.fromEntries(
+    Object.entries(intake.fallbacks).map(([level, candidate]) => [level, { ...candidate, selectedAt }]),
+  ) as ModelRouteState["fallbacks"];
+  const nextState: ModelRouteState = {
+    version: 2,
+    workType: intake.workType,
+    boundary: intake.boundary,
+    skillMode: intake.skillMode,
+    selections,
+    fallbacks,
+    activeStage: intake.activateStage,
+    activeFallback: undefined,
+    exhaustedSelectors: [],
+    handledFailureKeys: [],
+  };
+  port.persist(nextState);
+  return { state: nextState };
+}
+
 export async function executeModelRoute(
   currentState: ModelRouteState,
   params: ModelRouteParams,
@@ -670,7 +795,14 @@ export async function executeModelRoute(
   }
 
   if (params.action === "status") {
-    return { state: currentState, response: toolResult(JSON.stringify(currentState, null, 2), { state: currentState }) };
+    const availability = revalidateSavedRoute(currentState, port.models, port.hasExternalDevin);
+    return {
+      state: currentState,
+      response: toolResult(
+        JSON.stringify({ ...currentState, availability }, null, 2),
+        { state: currentState, availability },
+      ),
+    };
   }
 
   if (params.action === "select_fallback") {

package/core/provider-config.ts

@@ -0,0 +1,142 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface CustomProviderInput {
+  providerId: string;
+  displayName: string;
+  baseUrl: string;
+  envVar: string;
+  modelIds: string[];
+  allowLocalHttp: boolean;
+}
+
+export interface ProviderFiles {
+  modelsPath: string;
+  envPath: string;
+}
+
+const PROVIDER_ID = /^[a-z0-9_-]+$/;
+const ENV_VAR = /^[A-Z][A-Z0-9_]*$/;
+const MODEL_ID = /^[A-Za-z0-9._:-]+$/;
+
+export function validateCustomProvider(input: CustomProviderInput): string | undefined {
+  if (!PROVIDER_ID.test(input.providerId)) {
+    return "Provider id must be lowercase letters, numbers, underscores, or hyphens.";
+  }
+  if (!input.displayName.trim()) return "Display name is required.";
+  let url: URL;
+  try {
+    url = new URL(input.baseUrl);
+  } catch {
+    return "Base URL must be an https URL.";
+  }
+  const local = url.protocol === "http:" && url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(local && input.allowLocalHttp)) {
+    return "Base URL must use https unless you confirm a local http://127.0.0.1 endpoint.";
+  }
+  if (!ENV_VAR.test(input.envVar)) {
+    return "Env var name must match the runtime convention, such as EXAMPLE_GATEWAY_API_KEY.";
+  }
+  if (input.modelIds.length === 0) return "At least one model id is required.";
+  const unique = new Set(input.modelIds);
+  if (unique.size !== input.modelIds.length) return "Model ids must be unique.";
+  if (input.modelIds.some((id) => !MODEL_ID.test(id))) return "Model ids must be non-empty and contain no spaces.";
+  return undefined;
+}
+
+function yamlString(value: string): string {
+  if (/^[A-Za-z0-9_./:-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+export function renderProviderBlock(input: CustomProviderInput): string {
+  const models = input.modelIds.map((id, index) => {
+    const name = index === 0 && input.displayName.trim() ? input.displayName.trim() : id;
+    return `      - id: ${yamlString(id)}\n        name: ${yamlString(name)}`;
+  }).join("\n");
+  return [
+    `  ${input.providerId}:`,
+    `    baseUrl: ${yamlString(input.baseUrl)}`,
+    "    api: openai-completions",
+    `    apiKey: ${input.envVar}`,
+    "    authHeader: true",
+    "    models:",
+    models,
+  ].join("\n");
+}
+
+export function insertProvider(existing: string, providerId: string, block: string): string {
+  if (new RegExp(`^  ${providerId}:\\s*$`, "m").test(existing)) {
+    throw new Error(`Provider ${providerId} already exists in models.yml.`);
+  }
+  const trimmedBlock = block.replace(/\s+$/, "");
+  if (!existing.trim()) return `providers:\n${trimmedBlock}\n`;
+  const lines = existing.split("\n");
+  const providersIndex = lines.findIndex((line) => /^providers:\s*$/.test(line));
+  if (providersIndex === -1) {
+    const suffix = existing.endsWith("\n") ? "" : "\n";
+    return `${existing}${suffix}providers:\n${trimmedBlock}\n`;
+  }
+  lines.splice(providersIndex + 1, 0, ...trimmedBlock.split("\n"));
+  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}
+
+export function upsertEnvAssignment(existing: string, name: string, value: string): string {
+  if (new RegExp(`^${name}=`, "m").test(existing)) return existing;
+  const suffix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${suffix}${name}=${value}\n`;
+}
+
+function atomicWrite(path: string, contents: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const backup = `${path}.bak`;
+  const temporary = `${path}.${process.pid}.tmp`;
+  const hadOriginal = existsSync(path);
+  if (hadOriginal) copyFileSync(path, backup);
+  try {
+    writeFileSync(temporary, contents, { mode: 0o600 });
+    renameSync(temporary, path);
+  } catch (error) {
+    if (hadOriginal && existsSync(backup)) copyFileSync(backup, path);
+    throw error;
+  }
+}
+
+export function writeCustomProvider(files: ProviderFiles, input: CustomProviderInput, secret?: string): void {
+  const problem = validateCustomProvider(input);
+  if (problem) throw new Error(problem);
+  if (secret && (secret.includes("\n") || secret.includes("\r"))) {
+    throw new Error("The API key must be a single line.");
+  }
+  const existing = existsSync(files.modelsPath) ? readFileSync(files.modelsPath, "utf8") : "";
+  const next = insertProvider(existing, input.providerId, renderProviderBlock(input));
+  if (secret && next.includes(secret)) {
+    throw new Error("Refusing to write the API key into models.yml.");
+  }
+  atomicWrite(files.modelsPath, next);
+  if (!secret) return;
+  const currentEnv = existsSync(files.envPath) ? readFileSync(files.envPath, "utf8") : "";
+  atomicWrite(files.envPath, upsertEnvAssignment(currentEnv, input.envVar, secret));
+}
+
+export async function probeModelIds(
+  baseUrl: string,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string[] | undefined> {
+  const url = `${baseUrl.replace(/\/$/, "")}/models`;
+  try {
+    const response = await fetchImpl(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) return undefined;
+    const body = await response.json() as { data?: Array<{ id?: unknown }> };
+    const ids = (body.data ?? [])
+      .map((item) => item.id)
+      .filter((id): id is string => typeof id === "string" && id.length > 0);
+    return ids.length > 0 ? ids : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/core/user-route.ts

@@ -0,0 +1,100 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  emptyModelRouteState,
+  isFallbackLevel,
+  isStage,
+  restoreModelRouteState,
+  type ModelRouteState,
+  type RuntimeName,
+  type WorkBoundary,
+} from "./model-routing";
+
+const ROUTE_FILE = "pi-marg-route.json";
+
+export function agentDirectory(runtime: RuntimeName, home = process.env.PI_MARG_AGENT_HOME || homedir()): string {
+  return join(home, runtime === "OMP" ? ".omp" : ".pi", "agent");
+}
+
+export function userRoutePath(runtime: RuntimeName, home?: string): string {
+  return join(home ? agentDirectory(runtime, home) : agentDirectory(runtime), ROUTE_FILE);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBoundary(value: unknown): value is WorkBoundary {
+  return value === "Job/client" || value === "Personal";
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+export function parseUserRoute(raw: string): ModelRouteState | undefined {
+  try {
+    const data = JSON.parse(raw) as unknown;
+    if (!isRecord(data) || data.version !== 2) return undefined;
+    const activeStage = isStage(data.activeStage) ? data.activeStage : undefined;
+    const activeFallback = isFallbackLevel(data.activeFallback) ? data.activeFallback : undefined;
+    return {
+      version: 2,
+      workType: typeof data.workType === "number" ? data.workType : undefined,
+      boundary: isBoundary(data.boundary) ? data.boundary : undefined,
+      skillMode: typeof data.skillMode === "string" ? data.skillMode : undefined,
+      selections: isRecord(data.selections) ? data.selections as ModelRouteState["selections"] : {},
+      fallbacks: isRecord(data.fallbacks) ? data.fallbacks as ModelRouteState["fallbacks"] : {},
+      ...(activeStage ? { activeStage } : {}),
+      ...(activeFallback ? { activeFallback } : {}),
+      ...(stringList(data.exhaustedSelectors) ? { exhaustedSelectors: stringList(data.exhaustedSelectors) } : {}),
+      ...(stringList(data.handledFailureKeys) ? { handledFailureKeys: stringList(data.handledFailureKeys) } : {}),
+      ...(isRecord(data.lastFailover) ? { lastFailover: data.lastFailover as ModelRouteState["lastFailover"] } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function readUserRoute(path: string): ModelRouteState | undefined {
+  try {
+    return parseUserRoute(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeUserRoute(path: string, state: ModelRouteState): void {
+  const payload = parseUserRoute(JSON.stringify({ ...state, version: 2 })) ?? emptyModelRouteState();
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function routeHasChoices(state: ModelRouteState): boolean {
+  return Boolean(
+    state.workType
+    || state.boundary
+    || state.skillMode
+    || Object.keys(state.selections).length > 0
+    || Object.keys(state.fallbacks).length > 0,
+  );
+}
+
+export function loadSavedRoute(entries: readonly unknown[], file: ModelRouteState | undefined): ModelRouteState {
+  const branch = restoreModelRouteState(entries);
+  if (routeHasChoices(branch)) return branch;
+  return file ?? branch;
+}
+
+export function loadRuntimeRoute(runtime: RuntimeName, entries: readonly unknown[], home?: string): ModelRouteState {
+  return loadSavedRoute(entries, readUserRoute(userRoutePath(runtime, home)));
+}
+
+export function rememberRuntimeRoute(runtime: RuntimeName, state: ModelRouteState, home?: string): void {
+  writeUserRoute(userRoutePath(runtime, home), state);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sangyaahub/pi-marg",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A governed, model-routed development path for Pi Agent and Oh My Pi.",
   "type": "module",
   "license": "MIT",