myapikey 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "myapikey",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Personal LLM API gateway & proxy — one address + one API key for all your models. Forwards OpenAI & Anthropic calls to your backends with failover and a circuit breaker. Pure passthrough, no format translation. Self-hosted (CLI + web UI).",
   "keywords": [

package/packages/core/src/cli/index.ts

@@ -179,7 +179,7 @@ model.command("list").action(async () => {
     console.log(m.name);
     for (const f of fmts) {
       const fe = m[f];
-      const chain = fe.providers.map((p: any) => p.name).join(" → ") || "(none)";
+      const chain = fe.providers.map((p: any) => (p.model ? `${p.name}→${p.model}` : p.name)).join(" → ") || "(none)";
       console.log(`  ${f.padEnd(9)} ${fe.enabled ? "✓" : "·"} ${chain}`);
     }
   }
@@ -226,12 +226,29 @@ model
 
 model
   .command("prioritize <name> <refs...>")
-  .description("set provider priority order (left = primary)")
+  .description("reorder sources on a route (left = primary); list every source on the route, in order")
   .addOption(fmtOption())
   .action(async (name: string, refs: string[], opts: { format: "openai" | "anthropic" }) => {
-    const ids: string[] = [];
-    for (const ref of refs) ids.push(await resolveProviderId(ref));
-    await api(ctx(), "PUT", `/admin/models/${encodeURIComponent(name)}/priority`, { format: opts.format, providers: ids });
+    // The server reorders EXISTING slots (a duplicate id can occupy several), so
+    // each ref maps onto the chain left-to-right — a second ref with the same id
+    // consumes the next slot for that id. The refs must cover the whole route
+    // (the resulting indices are a permutation of [0..n-1]).
+    const wanted: string[] = [];
+    for (const ref of refs) wanted.push(await resolveProviderId(ref));
+    const r = (await api(ctx(), "GET", "/admin/models")) as { models: any[] };
+    const entry = (r.models as any[]).find((m) => m.name === name);
+    if (!entry) throw new Error(`No model '${name}'.`);
+    const chain: { id: string }[] = entry[opts.format]?.providers ?? [];
+    const used = new Set<number>();
+    const order: number[] = [];
+    for (const id of wanted) {
+      const idx = chain.findIndex((s, i) => s.id === id && !used.has(i));
+      if (idx === -1)
+        throw new Error(`'${name}' [${opts.format}] has no remaining slot for that source — list every source on the route exactly once.`);
+      used.add(idx);
+      order.push(idx);
+    }
+    await api(ctx(), "PUT", `/admin/models/${encodeURIComponent(name)}/priority`, { format: opts.format, order });
     console.log(`Priority for ${name} [${opts.format}]: ${refs.join(" → ")}`);
   });
 

package/packages/core/src/server/admin.ts

@@ -44,15 +44,11 @@ function providerSpeaks(p: Provider, key: RouteKey): boolean {
   return key === "responses" ? !!p.supportsResponses : p.formats.includes(key);
 }
 
-/** Drop a provider id from a routing slot: remove it from the chain AND from any
- *  modelMap (so a stale upstream-name override doesn't linger after the provider
- *  is gone or removed from this model's chain). */
+/** Drop every slot for a provider id from a routing slot — used when a provider
+ *  is deleted outright or removed from this model's chain. A provider may occupy
+ *  more than one slot (each mapped to a different upstream model); all go. */
 function purgeProvider(fe: FormatEntry, pid: string): void {
-  fe.providers = fe.providers.filter((x) => x !== pid);
-  if (fe.modelMap && pid in fe.modelMap) {
-    delete fe.modelMap[pid];
-    if (!Object.keys(fe.modelMap).length) delete fe.modelMap;
-  }
+  fe.providers = fe.providers.filter((s) => s.id !== pid);
 }
 
 /** Project provider for API responses: hide the full key. */
@@ -296,12 +292,13 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
     const byId = new Map(d.providers.map((p) => [p.id, p]));
     const proj = (fe: FormatEntry) => ({
       enabled: fe.enabled,
-      providers: fe.providers.map((pid) => ({
-        id: pid,
-        name: byId.get(pid)?.name ?? "?",
-        // Upstream model name this source is mapped to (undefined = send the
-        // public name verbatim). Flattened out of modelMap for the client.
-        model: fe.modelMap?.[pid],
+      providers: fe.providers.map((s) => ({
+        id: s.id,
+        name: byId.get(s.id)?.name ?? "?",
+        // Upstream model name this slot rewrites the request to (undefined =
+        // send the public model name verbatim). Carried inline on each slot so
+        // a provider can appear more than once with different upstream names.
+        model: s.model,
       })),
     });
     const models = Object.entries(d.models).map(([name, e]) => ({
@@ -337,7 +334,10 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
         responses: { enabled: false, providers: [] },
       });
       const fe = entry[key];
-      for (const pid of requested) if (!fe.providers.includes(pid)) fe.providers.push(pid);
+      // Enable/seed dedupes by provider id: re-enabling must not pile up
+      // duplicate slots. (Use POST /:name/providers to intentionally add a
+      // second occurrence of a provider for per-model failover.)
+      for (const pid of requested) if (!fe.providers.some((s) => s.id === pid)) fe.providers.push({ id: pid });
       fe.enabled = true;
     });
     return c.json({ ok: true }, 201);
@@ -345,7 +345,7 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
 
   app.post("/models/:name/providers", async (c) => {
     const name = c.req.param("name");
-    const body = await readJson<{ format?: RouteKey; providerId?: string }>(c.req.raw);
+    const body = await readJson<{ format?: RouteKey; providerId?: string; model?: string }>(c.req.raw);
     if (!body?.format) return c.json({ error: { message: "format is required" } }, 400);
     if (!body?.providerId) return c.json({ error: { message: "providerId is required" } }, 400);
     const cfg = store.get();
@@ -353,6 +353,11 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
     if (!p) return c.json({ error: { message: "provider not found" } }, 400);
     if (!providerSpeaks(p, body.format))
       return c.json({ error: { message: `provider ${p.name} does not serve ${body.format}` } }, 400);
+    // No dedupe guard: appending a SECOND occurrence of a provider is the whole
+    // point (failover across its models). An optional `model` sets the new
+    // slot's upstream name at attach time (add + map in one call).
+    const upstream = body.model?.trim();
+    const slot = upstream ? { id: body.providerId!, model: upstream } : { id: body.providerId! };
     let errStatus = 0;
     await store.update((d) => {
       const entry = d.models[name];
@@ -360,12 +365,39 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
         errStatus = 404;
         return;
       }
-      if (!entry[body.format!].providers.includes(body.providerId!)) entry[body.format!].providers.push(body.providerId!);
+      entry[body.format!].providers.push(slot);
     });
     if (errStatus === 404) return c.json({ error: { message: "model not found; enable it first" } }, 404);
     return c.json({ ok: true });
   });
 
+  // Remove a SINGLE chain slot at `index` (the web's per-row remove). Distinct
+  // from the id-based delete below, which removes every slot for a provider.
+  app.delete("/models/:name/providers", async (c) => {
+    const name = c.req.param("name");
+    const format = c.req.query("format") as RouteKey | undefined;
+    const index = Number(c.req.query("index"));
+    if (!format) return c.json({ error: { message: "?format=openai|anthropic|responses is required" } }, 400);
+    if (!Number.isInteger(index) || index < 0)
+      return c.json({ error: { message: "?index= (non-negative integer) is required" } }, 400);
+    let errStatus = 0;
+    await store.update((d) => {
+      const fe = d.models[name]?.[format];
+      if (!fe) {
+        errStatus = 404;
+        return;
+      }
+      if (index >= fe.providers.length) {
+        errStatus = 400;
+        return;
+      }
+      fe.providers.splice(index, 1);
+    });
+    if (errStatus === 404) return c.json({ error: { message: "model not found" } }, 404);
+    if (errStatus === 400) return c.json({ error: { message: "index out of range" } }, 400);
+    return c.json({ ok: true });
+  });
+
   app.delete("/models/:name/providers/:providerId", async (c) => {
     const name = c.req.param("name");
     const pid = c.req.param("providerId");
@@ -380,9 +412,10 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
 
   app.put("/models/:name/priority", async (c) => {
     const name = c.req.param("name");
-    const body = await readJson<{ format?: RouteKey; providers?: string[] }>(c.req.raw);
+    const body = await readJson<{ format?: RouteKey; order?: number[] }>(c.req.raw);
     if (!body?.format) return c.json({ error: { message: "format is required" } }, 400);
-    if (!Array.isArray(body?.providers)) return c.json({ error: { message: "providers[] required" } }, 400);
+    if (!Array.isArray(body?.order) || !body.order.every((n) => Number.isInteger(n)))
+      return c.json({ error: { message: "order[] (integers) required" } }, 400);
     const format = body.format;
     let errStatus = 0;
     let errMsg = "";
@@ -393,32 +426,38 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
         return;
       }
       const fe = entry[format];
-      // Reorder only: the submitted list must be a permutation of the current
-      // chain (use add-provider / remove-provider to change membership).
-      const cur = new Set(fe.providers);
-      if (body.providers!.length !== cur.size || body.providers!.some((pid) => !cur.has(pid))) {
+      const n = fe.providers.length;
+      // Reorder only: `order` must be a permutation of [0..n-1] (the current
+      // slot positions). Indices — not provider ids — because a provider may now
+      // occupy several slots. Use add-provider / remove-provider to change membership.
+      if (
+        body.order!.length !== n ||
+        new Set(body.order).size !== n ||
+        !body.order!.every((i) => i >= 0 && i < n)
+      ) {
         errStatus = 400;
-        errMsg = "providers must be a reordering of the current chain (no add/drop)";
+        errMsg = "order must be a reordering of the current chain (no add/drop)";
         return;
       }
-      fe.providers = body.providers!;
+      fe.providers = body.order!.map((i) => fe.providers[i]);
     });
     if (errStatus === 404) return c.json({ error: { message: "model not found" } }, 404);
     if (errStatus === 400) return c.json({ error: { message: errMsg } }, 400);
     return c.json({ ok: true });
   });
 
-  // Set (or clear) a model×source upstream-model mapping. `model` is the name
-  // sent upstream when forwarding this public model to this provider; an empty
-  // string clears it (back to identity — send the public name). The provider
-  // must already be in this slot's chain: you map a source already attached.
+  // Set (or clear) the upstream-model mapping for ONE chain slot (addressed by
+  // `index`). An empty `model` clears it (back to identity — send the public
+  // name). Index-addressed because a provider may occupy several slots, each
+  // with its own upstream model.
   app.put("/models/:name/map", async (c) => {
     const name = c.req.param("name");
-    const body = await readJson<{ format?: RouteKey; providerId?: string; model?: string }>(c.req.raw);
+    const body = await readJson<{ format?: RouteKey; index?: number; model?: string }>(c.req.raw);
     if (!body?.format) return c.json({ error: { message: "format is required" } }, 400);
-    if (!body?.providerId) return c.json({ error: { message: "providerId is required" } }, 400);
+    if (!Number.isInteger(body?.index) || (body?.index ?? -1) < 0)
+      return c.json({ error: { message: "index (non-negative integer) is required" } }, 400);
     const format = body.format;
-    const pid = body.providerId;
+    const index = body.index!;
     const upstream = (body.model ?? "").trim();
     let errStatus = 0;
     let errMsg = "";
@@ -430,17 +469,13 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
         return;
       }
       const fe = entry[format];
-      if (!fe.providers.includes(pid)) {
+      if (index >= fe.providers.length) {
         errStatus = 400;
-        errMsg = "provider is not in this model's chain for the given format";
+        errMsg = "index out of range for this model's chain";
         return;
       }
-      if (upstream) {
-        (fe.modelMap ??= {})[pid] = upstream;
-      } else if (fe.modelMap && pid in fe.modelMap) {
-        delete fe.modelMap[pid];
-        if (!Object.keys(fe.modelMap).length) delete fe.modelMap;
-      }
+      if (upstream) fe.providers[index].model = upstream;
+      else delete fe.providers[index].model;
     });
     if (errStatus === 404) return c.json({ error: { message: errMsg } }, 404);
     if (errStatus === 400) return c.json({ error: { message: errMsg } }, 400);
@@ -500,19 +535,20 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
     return c.json({ result: { ok: false, status: res.status, provider, format, error: shortError(txt) || `HTTP ${res.status}` } });
   });
 
-  // Probe a SINGLE source for a model+format: the same end-to-end loopback as the
-  // whole-model /test above, but dispatch is pinned to this one provider (via the
-  // x-myapikey-probe-provider header), so there is no failover and no
-  // circuit-breaker impact — a manual "is THIS source up?" check that reports the
-  // provider's real upstream status. Validation misses (source not on this route,
-  // wrong wire format) come back as a ProbeResult body, not an HTTP error, so the
-  // caller reads `result` uniformly.
-  app.post("/models/:name/providers/:providerId/test", async (c) => {
+  // Probe a SINGLE chain slot for a model+format: the same end-to-end loopback as
+  // the whole-model /test above, but dispatch is pinned to this one slot (via the
+  // x-myapikey-probe-slot header carrying the slot index), so there is no failover
+  // and no circuit-breaker impact — a manual "is THIS source up?" check that
+  // reports the slot's real upstream status (the slot's own mapped model name).
+  // Slot-indexed (not provider-id) because a provider may occupy several slots,
+  // each mapped to a different upstream model. Validation misses come back as a
+  // ProbeResult body, not an HTTP error, so the caller reads `result` uniformly.
+  app.post("/models/:name/providers/test", async (c) => {
     const name = c.req.param("name");
-    const pid = c.req.param("providerId");
     const cfg = store.get();
     const entry = cfg.models[name];
     if (!entry) return c.json({ error: { message: "model not found" } }, 404);
+    const index = Number(c.req.query("index"));
     let format = c.req.query("format") as RouteKey | undefined;
     if (!format) {
       // No slot requested: pick the first one the model is enabled on.
@@ -521,9 +557,10 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
     if (!format || !entry[format]?.enabled) {
       return c.json({ result: { ok: false, status: 0, format: format ?? "openai", error: "model not enabled on that routing slot" } });
     }
-    if (!entry[format].providers.includes(pid)) {
-      return c.json({ result: { ok: false, status: 0, format, error: "source is not on this route" } });
+    if (!Number.isInteger(index) || index < 0 || index >= entry[format].providers.length) {
+      return c.json({ result: { ok: false, status: 0, format, error: "slot index out of range for this route" } });
     }
+    const pid = entry[format].providers[index].id;
     const provider = cfg.providers.find((p) => p.id === pid);
     if (!provider || !providerSpeaks(provider, format)) {
       return c.json({ result: { ok: false, status: 0, format, error: "source does not speak this format" } });
@@ -538,7 +575,7 @@ export function adminApi(store: Store, auth: MiddlewareHandler, v1: Hono): Hono
     try {
       res = await v1.request(path, {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}`, "x-myapikey-probe": "1", "x-myapikey-probe-provider": pid },
+        headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}`, "x-myapikey-probe": "1", "x-myapikey-probe-slot": String(index) },
         body: JSON.stringify(body),
       });
     } catch (e) {

package/packages/core/src/server/proxy.ts

@@ -54,8 +54,17 @@ function parseResetFromBody(text: string): number | undefined {
   return ms > 0 ? ms : undefined;
 }
 
-/** Resolve the ordered, compatible provider list for a model on a routing slot. */
-function candidates(store: Store, model: string, key: RouteKey): Provider[] {
+/** One resolved routing slot: the provider to forward to plus THIS slot's
+ *  optional upstream model name (absent = send the public model name). The
+ *  same provider may occupy several slots in a chain — each is an independent
+ *  failover slot carrying its own upstream model. */
+interface CandidateSlot {
+  provider: Provider;
+  model?: string;
+}
+
+/** Resolve the ordered, compatible provider slots for a model on a routing slot. */
+function candidates(store: Store, model: string, key: RouteKey): CandidateSlot[] {
   const d = store.get();
   const entry = d.models[model];
   const fe = entry?.[key];
@@ -65,10 +74,13 @@ function candidates(store: Store, model: string, key: RouteKey): Provider[] {
   // requires supportsResponses. (Admin keeps chains pure, but a provider's
   // formats/flag can be edited afterwards.)
   return fe.providers
-    .map((id) => byId.get(id))
-    .filter((p): p is Provider => {
-      if (!p) return false;
-      return key === "responses" ? !!p.supportsResponses : p.formats.includes(key);
+    .map((s): CandidateSlot | null => {
+      const p = byId.get(s.id);
+      return p ? { provider: p, model: s.model } : null;
+    })
+    .filter((slot): slot is CandidateSlot => {
+      if (!slot) return false;
+      return key === "responses" ? !!slot.provider.supportsResponses : slot.provider.formats.includes(key);
     });
 }
 
@@ -295,15 +307,21 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
     // answered back to the test handler (x-myapikey-provider), without leaking
     // that header to real agent clients.
     const isProbe = c.req.header("x-myapikey-probe") === "1";
-    // The per-source "test this source" variant pins dispatch to ONE provider:
-    // the candidate chain is reduced to just it, and on failure we stop
-    // immediately (no failover) WITHOUT recording a circuit failure — a manual
-    // probe must not trip the breaker. Failure surfaces the real upstream status
+    // The per-source "test this source" variant pins dispatch to ONE slot (by
+    // chain index, since a provider may occupy several slots): the candidate
+    // chain is reduced to just that slot, and on failure we stop immediately
+    // (no failover) WITHOUT recording a circuit failure — a manual probe must
+    // not trip the breaker. Failure surfaces the real upstream status
     // (429/500/…), not a collapsed 502, so the badge shows what really happened.
-    const pinId = c.req.header("x-myapikey-probe-provider") || "";
+    const pinIndexRaw = c.req.header("x-myapikey-probe-slot");
+    const pinIndex = pinIndexRaw !== "" && Number.isInteger(Number(pinIndexRaw)) ? Number(pinIndexRaw) : null;
     // candidates() already restricts the responses chain to supportsResponses sources.
     let list = candidates(store, model, key);
-    if (pinId) list = list.filter((p) => p.id === pinId);
+    if (pinIndex != null) {
+      // An out-of-range index → empty list → 404, so a bad probe is reported as
+      // unreachable rather than accidentally hitting a different slot.
+      list = list[pinIndex] != null ? [list[pinIndex]] : [];
+    }
     if (!list.length) {
       if (key === "responses") {
         return c.json(
@@ -330,20 +348,22 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
     // (a skipped provider that now succeeds also resets its state). A pinned
     // (per-source) probe ignores both — the user is testing THIS source now,
     // whatever its breaker/pacing state.
-    const skipped = (p: Provider) => store.isCooling(p.id) || (!!p.rpm && store.rpmUsed(p.id) >= p.rpm);
-    const live = pinId ? list : list.filter((p) => !skipped(p));
+    const skipped = (slot: CandidateSlot) => {
+      const p = slot.provider;
+      return store.isCooling(p.id) || (!!p.rpm && store.rpmUsed(p.id) >= p.rpm);
+    };
+    const live = pinIndex != null ? list : list.filter((slot) => !skipped(slot));
     const order = live.length ? live : list;
 
-    for (const provider of order) {
-      // Model mapping (per model×source): rewrite the passthrough body's model
-      // to this provider's configured upstream name. Recomputed from the ORIGINAL
-      // `model` each iteration, so failover to the next provider never carries the
-      // previous provider's upstream name. Absent map/key → send the public name.
-      const mapped = store.get().models[model]?.[key]?.modelMap?.[provider.id];
-      body.model = mapped ?? model;
+    for (const slot of order) {
+      const provider = slot.provider;
+      // Per-slot upstream model name (absent = send the public name). Read from
+      // the slot each iteration, so failover never carries the previous slot's
+      // upstream name.
+      body.model = slot.model ?? model;
       // Count this attempt toward the source's RPM window — but not for a pinned
       // probe, which (like circuit state) takes no routing side-effects.
-      if (!pinId) store.recordDispatch(provider.id);
+      if (pinIndex == null) store.recordDispatch(provider.id);
       let upstream: Response;
       try {
         upstream = await fetch(upstreamTarget(provider, key).url, {
@@ -355,7 +375,7 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
         // Network error / DNS / timeout → try next provider.
         lastStatus = 502;
         lastErr = "network error";
-        if (pinId) break; // per-source probe: fail fast, no circuit impact.
+        if (pinIndex != null) break; // per-source probe: fail fast, no circuit impact.
         const r = store.recordCircuitFailure(provider.id, lastStatus, lastErr);
         if (r.entered) {
           store.pushLog({ ts: Date.now(), model, provider: provider.name, providerId: provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, kind: "cooldown", cooldownMs: r.cooldownMs, fails: r.fails, error: lastErr });
@@ -387,7 +407,7 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
             } else {
               // A pinned per-source probe takes no circuit side-effects (a manual
               // test must not trip the breaker) — mirrors the retryable branch.
-              if (!pinId) store.recordCircuitFailure(provider.id, info.status, info.error || "stream failed");
+              if (pinIndex == null) store.recordCircuitFailure(provider.id, info.status, info.error || "stream failed");
               store.pushLog({ ts: Date.now(), model, provider: provider.name, providerId: provider.id, format: wire, status: info.status, ms: ttfb, stream, error: info.error });
             }
           },
@@ -400,7 +420,7 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
         // reason for the log (this branch never streams back to the client).
         const txt = await upstream.text().catch(() => "");
         lastErr = shortError(txt) || `HTTP ${upstream.status}`;
-        if (pinId) break; // per-source probe: fail fast, no circuit impact.
+        if (pinIndex != null) break; // per-source probe: fail fast, no circuit impact.
         // A 429/overloaded upstream usually carries Retry-After; honoring it
         // cools for exactly as long as asked (clamped) instead of the escalating
         // guess. Absent (5xx often, OR a quota error that buried the reset time
@@ -422,13 +442,13 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
     }
 
     const last = order[order.length - 1];
-    store.pushLog({ ts: Date.now(), model, provider: last.name, providerId: last.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, error: lastErr || `all providers failed (last status ${lastStatus})` });
+    store.pushLog({ ts: Date.now(), model, provider: last.provider.name, providerId: last.provider.id, format: wire, status: lastStatus, ms: Date.now() - start, stream, error: lastErr || `all providers failed (last status ${lastStatus})` });
     // A pinned (per-source) probe failed: surface the REAL upstream status the
-    // one provider returned (429/500/…), not a collapsed 502, and tag it with
+    // one slot returned (429/500/…), not a collapsed 502, and tag it with
     // x-myapikey-provider so the source-row badge names the tested source.
-    if (pinId) {
+    if (pinIndex != null) {
       const h = new Headers({ "content-type": "application/json" });
-      if (isProbe) h.set("x-myapikey-provider", last.name);
+      if (isProbe) h.set("x-myapikey-provider", last.provider.name);
       return new Response(
         JSON.stringify({ error: { message: lastErr || `provider failed (status ${lastStatus})`, type: "upstream_error" } }),
         { status: lastStatus, headers: h },
@@ -458,7 +478,7 @@ export function proxyApi(store: Store, auth: MiddlewareHandler): Hono {
         id,
         object: "model",
         created: 0,
-        owned_by: byId.get(e.openai.providers[0] ?? "")?.name || "MyAPIKey",
+        owned_by: byId.get(e.openai.providers[0]?.id ?? "")?.name || "MyAPIKey",
       }));
     return c.json({ object: "list", data });
   });

package/packages/core/src/server/store.ts

@@ -248,11 +248,17 @@ export class Store {
       raw.apiKey = newApiKey();
       this.persist(raw);
     }
-    // Migration: model entries were { enabled, providers[] } (v1), then
-    // { openai, anthropic } (v2). Split into three routing slots
-    // { openai, anthropic, responses } so /responses routes independently.
-    // Idempotent; persisted immediately so the upgrade is stable across restarts.
-    if (migrateModels(raw) || migrateProviders(raw) || !raw.version || raw.version < CONFIG_VERSION) {
+    // Run every migrator unconditionally. Each is idempotent and returns
+    // whether it rewrote anything. We deliberately do NOT chain them with ||
+    // (which short-circuits): a v1 config makes migrateModels return true, which
+    // would skip migrateFormatEntries, yet the version still bumps to
+    // CONFIG_VERSION below — leaving v5-versioned data with unconverted string[]
+    // chains that crash candidates() on the very same boot. Calling all three
+    // every boot is cheap (they no-op once migrated) and closes that window.
+    const m1 = migrateModels(raw);
+    const m2 = migrateProviders(raw);
+    const m3 = migrateFormatEntries(raw);
+    if (m1 || m2 || m3 || !raw.version || raw.version < CONFIG_VERSION) {
       raw.version = CONFIG_VERSION;
       this.persist(raw);
     } else if (raw.version > CONFIG_VERSION) {
@@ -734,3 +740,38 @@ function migrateProviders(raw: GateConfig): boolean {
   }
   return changed;
 }
+
+/**
+ * FormatEntry migration to inline (provider, model) slots (v4 → v5).
+ *  - v4 stored each route's chain as `providers: string[]` (unique provider ids)
+ *    plus an optional side-channel `modelMap: { providerId → upstream model }`.
+ *  - v5 collapses both into `providers: { id, model? }[]`, so a provider id may
+ *    now REPEAT — each occurrence carries its own upstream model — enabling
+ *    failover across several models on one backend.
+ * Idempotent: slots already in the {id,model?} shape (no string elements and no
+ * modelMap) are skipped. Returns true if any entry was rewritten.
+ */
+function migrateFormatEntries(raw: GateConfig): boolean {
+  const models = raw.models as Record<string, unknown>;
+  if (!models || typeof models !== "object") return false;
+  let changed = false;
+  for (const entry of Object.values(models)) {
+    if (!entry || typeof entry !== "object") continue;
+    for (const f of ["openai", "anthropic", "responses"] as const) {
+      const fe = (entry as Record<string, unknown>)[f] as
+        | { providers?: unknown[]; modelMap?: Record<string, string> }
+        | undefined;
+      if (!fe || !Array.isArray(fe.providers)) continue;
+      const hasStrings = fe.providers.some((x) => typeof x === "string");
+      const hasMap = !!fe.modelMap && Object.keys(fe.modelMap).length > 0;
+      if (!hasStrings && !hasMap) continue; // already v5
+      const map = fe.modelMap ?? {};
+      fe.providers = (fe.providers as unknown[]).map((x) =>
+        typeof x === "string" ? (map[x] ? { id: x, model: map[x] } : { id: x }) : x,
+      );
+      delete fe.modelMap;
+      changed = true;
+    }
+  }
+  return changed;
+}

package/packages/core/src/shared/config.ts

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { GateConfig } from "./types";
 
-export const CONFIG_VERSION = 4;
+export const CONFIG_VERSION = 5;
 export const DEFAULT_PORT = 7800;
 /** Default on-disk home for the gateway's data: data.json + logs.jsonl live here. */
 export const DEFAULT_DATA_DIR = join(homedir(), ".myapikey");

package/packages/core/src/shared/types.ts

@@ -36,26 +36,38 @@ export interface Provider {
   createdAt: number;
 }
 
-/** One routing slot: an independent enable flag + a priority-ordered provider
- *  chain. Invariant (enforced by admin mutations, defended by proxy candidates()):
- *  every id in `providers` exists in `GateConfig.providers` and is compatible
- *  with the slot — openai/anthropic ids must carry that wire format; responses
- *  ids must additionally be supportsResponses sources (still OpenAI-format).
+/** One routing slot: an independent enable flag + a priority-ordered chain of
+ *  (provider, optional upstream model) pairs. Invariant (enforced by admin
+ *  mutations, defended by proxy candidates()): every id in `providers` exists in
+ *  `GateConfig.providers` and is compatible with the slot — openai/anthropic ids
+ *  must carry that wire format; responses ids must additionally be
+ *  supportsResponses sources (still OpenAI-format).
  *
- *  `modelMap` (optional): per-provider UPSTREAM model name. When forwarding to
- *  provider P, if `modelMap[P.id]` is set, the gateway rewrites the request's
- *  `model` field to that value before the passthrough POST; otherwise the
- *  public model name (the key in GateConfig.models) is sent verbatim. So this is
- *  a pure name rewrite on the passthrough body — still no OpenAI↔Anthropic
- *  translation. Lets you alias (claude-sonnet-4 → claude-sonnet-4-20250514) or
- *  swap the actual model (gpt-4 → gpt-4o) per source. Absent/empty = identity. */
+ *  A provider id may appear MORE THAN ONCE — each occurrence is an independent
+ *  failover slot that can carry its own upstream model name. When forwarding to
+ *  a slot, if its `model` is set the gateway rewrites the request's `model`
+ *  field to that value before the passthrough POST; otherwise the public model
+ *  name (the key in GateConfig.models) is sent verbatim. That is a pure name
+ *  rewrite on the passthrough body — still no OpenAI↔Anthropic translation. It
+ *  lets you alias (claude-sonnet-4 → claude-sonnet-4-20250514), swap the actual
+ *  model (gpt-4 → gpt-4o) per source, or fail over across several models on ONE
+ *  backend (Ark → doubao-pro primary, Ark → doubao-lite fallback). Absent model
+ *  = identity (send the public name). */
 export interface FormatEntry {
   enabled: boolean;
-  /** Provider ids in priority order. First = primary, rest = fallback. */
-  providers: string[];
-  /** providerId → upstream model name to send to that provider. Optional;
-   *  absent key (or absent map) = send the public model name unchanged. */
-  modelMap?: Record<string, string>;
+  /** Ordered chain of routing slots: first = primary, rest = fallback. The same
+   *  provider id may repeat — each occurrence can map a different upstream model. */
+  providers: ChainSlot[];
+}
+
+/** One slot in a format's provider chain: which provider to forward to, and the
+ *  optional upstream model name to rewrite the request's `model` field to.
+ *  Duplicates of `id` are legal (distinct failover slots). */
+export interface ChainSlot {
+  id: string;
+  /** Upstream model name to send to this provider. Absent = forward the public
+   *  model name (the key in GateConfig.models) unchanged. */
+  model?: string;
 }
 
 /** A model's routing dimensions — one per forwarding endpoint. /chat/completions