@lawaty/lacode 0.1.10 → 0.2.1

package/README.md

@@ -284,6 +284,7 @@ option is optional:
 | `modelsFile` | — | An explicit slot file; short-circuits the chain below. |
 | `reapMs` | `30000` | Hang-reaper interval. |
 | `selfUpdate` | `true` | Check for a newer release at most once per ~6h and install it in the background; it applies on the next opencode start. `false` — or `LACODE_NO_SELFUPDATE=1` — turns the check off. |
+| `omniroute` | — | Optional [OmniRoute](#configuring-omniroute) gateway integration. Absent or `{ enabled: false }` changes nothing. |
 
 ### Staying up to date
 
@@ -315,6 +316,112 @@ allowlist anywhere in the package, and no cost check of any kind: only the
 structure is validated. The bundled preset is built from free models because
 that is a sensible default, not because the pool requires it.
 
+### Configuring OmniRoute
+
+[OmniRoute](https://github.com/diegosouzapw/OmniRoute) is a local
+OpenAI-compatible AI gateway (default `http://localhost:20128/v1`) that routes a
+request across many providers with fallback and "combos". LaCode can register it
+as an opencode provider for you. It is **off by default**: if you do not set
+`omniroute.enabled: true`, nothing below happens and LaCode makes no request.
+
+```jsonc
+{
+  "plugin": [
+    ["@lawaty/lacode", {
+      "omniroute": {
+        "enabled": true,
+        "baseURL": "http://localhost:20128/v1",
+        "apiKey": "sk_omniroute",          // optional; OMNIROUTE_API_KEY overrides it
+        "combo": "static-best-free",        // optional: let OmniRoute do the routing
+        "models": ["cc/claude-sonnet-4-6", "gemini-3-flash"], // hard allowlist
+        "tiers": {
+          "primary": ["cc/claude-sonnet-4-6"],
+          "backup": ["gemini-3-flash"]
+        },
+        "stickyPerSession": true,
+        "healthCheck": true,
+        "timeoutMs": 5000
+      }
+    }]
+  ]
+}
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Turns the integration on. |
+| `baseURL` | `http://localhost:20128/v1` | Gateway base URL, normalised to exactly one `/v1`. |
+| `apiKey` | — | Bearer key. **`OMNIROUTE_API_KEY` overrides this value.** The key is never logged. |
+| `combo` | — | An OmniRoute combo id (or `auto`) to expose as a selectable model even though the gateway does not list it. Exposed first. |
+| `models` | — | A **hard allowlist**: only these ids are ever exposed, even if the gateway lists more. |
+| `tiers` | — | `{ "primary": [...], "backup": [...] }` preference order over models the allowlist already permits. |
+| `stickyPerSession` | `true` | Keep a session on one model while that model is healthy. |
+| `healthCheck` | `true` | Probe `GET /models` at startup; a failed check disables the integration for that run only. |
+| `timeoutMs` | `5000` | Budget for LaCode's own calls to the gateway. |
+
+An enabled but invalid block (bad `baseURL`, a non-array `models`, …) is rejected
+as a whole: LaCode logs one warning naming the problem and continues exactly as
+if the integration were off. It never crashes opencode.
+
+**What it registers.** On the first `config` pass LaCode health-checks the
+gateway, reads `GET /models`, filters it through your `models` allowlist (or
+exposes everything the gateway lists when no allowlist is set), and writes a
+`provider.omniroute` entry — `npm: "@ai-sdk/openai-compatible"` with your
+`baseURL` / `apiKey` — so `omniroute/<model-id>` becomes selectable. If you
+already have a `provider.omniroute` block, LaCode leaves it completely untouched
+and warns; it also never adds a `whitelist`. Because opencode loads
+`@ai-sdk/openai-compatible` itself, no extra dependency is installed.
+
+**Combo vs. allowlist.** Set `combo` and OmniRoute does the fallback for you (let
+it route). Without a combo, LaCode exposes the allowlist ordered by `tiers`
+(primary first), tracks a rolling latency and error rate per model, and skips a
+model while it is cooling after a transient failure — 429, 408 and 5xx, honouring
+`Retry-After` and otherwise using capped exponential backoff. Non-transient
+errors (400, 401, 403, 404) are surfaced to you, never failed over.
+
+**Using OmniRoute in the pool.** The integration only *registers* the provider —
+it never touches your pool, and it does not place a slot for you. To route pooled
+work (exploration, implementation, cartography) through the gateway, list it in
+your pool like any other model:
+
+```
+# ~/.config/lacode/pool.txt
+omniroute/auto             3
+opencode/space-bunny-free  2
+opencode-go/step-5-preview-free 1
+opencode/big-pickle        1
+```
+
+`omniroute/auto` then takes slot 1 (weight 3) and drains pooled mechanical work
+before it reaches the bundled opencode/opencode-go ("zen") models. Any
+`omniroute/<id>` works, provided the id is exposed — by `combo`/`models`, or the
+whole catalog when neither is set. Because the plugin writes the pool nothing,
+the only thing that changes when the gateway is down is that `omniroute/<id>`
+fails; every other slot keeps working. See
+[docs/USER-STORIES.md](docs/USER-STORIES.md) US-28.
+
+**A note on mid-session switching.** opencode 1.18.34 exposes no hook to change
+an agent's main model mid-request, so LaCode cannot swap models inside a running
+session; use an OmniRoute `combo` (or `auto`) if you want per-request fallback.
+LaCode's selection engine decides which models are exposed and in what order, and
+its cooldown/backoff rules are unit-tested.
+
+**Getting a key.** Open the OmniRoute dashboard, go to API Manager / API Keys and
+copy a key into `OMNIROUTE_API_KEY` (recommended) or `omniroute.apiKey`. On a
+local instance with `REQUIRE_API_KEY=false`, the literal placeholder
+`sk_omniroute` is accepted.
+
+**Troubleshooting**
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `omniroute health check failed` at startup | Gateway not running, wrong `baseURL`, or a startup race | Start OmniRoute on `http://localhost:20128` and restart opencode. The integration is disabled for that run only, not permanently. |
+| `no usable models` | The gateway returned an empty list, or every id was filtered out by `models` | `curl -H "Authorization: Bearer $OMNIROUTE_API_KEY" http://localhost:20128/v1/models` and check `models`/`combo` against the returned ids. |
+| `401` / `Invalid API key` | `REQUIRE_API_KEY=true` and the key is missing or wrong | Create a key in the dashboard, export `OMNIROUTE_API_KEY`, or set `REQUIRE_API_KEY=false` locally and use `sk_omniroute`. |
+| `404` on a URL containing `/v1/v1/` | A `baseURL` that already carried `/v1` was given twice | LaCode normalises this, so it should not come from LaCode; check a hand-written `provider.omniroute` block, which LaCode leaves untouched. |
+| Provider registered but models are missing | You already had `provider.omniroute` | Remove it and let LaCode write it, or add the models yourself — LaCode never modifies an existing provider. |
+| Pooled work still runs on the bundled models | The gateway was unhealthy/disabled at startup, or you have no `omniroute/…` slot in your pool | Check the startup log for `omniroute health check failed` / `no usable models`, then add `omniroute/<model>` to `pool.txt` (or `pool.json`) to route pooled work through the gateway. |
+
 ### Which models run which agent
 
 Only the **pool** writes a model onto a pooled agent, from whichever source wins

package/dist/agents.js

@@ -35,6 +35,8 @@ var UNAVAILABLE_COOLDOWN_MS = 60 * 1e3;
 var MAX_SLOTS = 4;
 var COOLDOWN_BASE_MS = 60 * 1e3;
 var COOLDOWN_MAX_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_BASE_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1e3;
 var STRIKE_DECAY_MS = 30 * 60 * 1e3;
 var PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
 var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
@@ -70,8 +72,31 @@ Every question of the form "what does this file do", "where is X handled", or
   that proves it. Never one whole refactor handed over in a single piece \u2014
   see \`# Task size\` below.
 
-The agents you spawn are the pooled \`explore\` / \`implement\` bases \u2014
-spawn the bare name and let the pool route, never a \`-1\`/\`-2\` slot variant.
+The agents you spawn are the pooled \`explore\` / \`implement\` / \`context\`
+bases. **Always spawn the BARE base name and let the plugin choose the slot;
+never name a \`-N\` variant** (\`explore-1\`..\`explore-4\`, \`implement-1\`..,
+\`context-1\`..). The plugin owns which model every pooled spawn runs on: it
+picks the next slot from the pool's weights, current load and cooldowns, and
+rewrites your spawn to that variant for you. Naming a variant bypasses that
+decision, defeats failover, and can pin work to a cooling or unhealthy model.
+If you catch yourself choosing a slot number, you are doing the plugin's job \u2014
+spawn \`explore\` and let it decide.
+
+# When the pool is unavailable
+
+The pooled agents are the ONLY route to investigation and implementation. If the
+pool cannot serve a spawn \u2014 every slot cooling or exhausted, spawns repeatedly
+failing, or a runtime message saying no slot is available \u2014 that is a STOP
+condition, not a reason to do the work yourself.
+
+**Never fall back to reading, grepping, exploring or implementing on your own.**
+Do not "just quickly" inspect a file because a spawn failed. Stop, say what
+failed (slot, model, error), and ASK the user how to proceed: wait for a slot to
+recover, change the pool, or obtain explicit permission to work without
+subagents. A failed spawn is never permission, and silence is not consent.
+
+\`edit\`/\`write\`/\`bash\` stay yours for applying and verifying what a subagent
+returned \u2014 never as a substitute for a spawn that could not run.
 
 # Task size
 
@@ -175,6 +200,16 @@ When you need to understand the codebase:
 2. Invoke @explore with specific, focused instructions (e.g. "read src/auth.ts", "grep for 'migration' in *.py files", "list the src/ directory")
 3. @explore will return its findings \u2014 you process them and plan accordingly
 
+Always spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`) and let
+the plugin choose the slot. Never name a \`-N\` variant (\`explore-1\`..\`explore-4\`);
+doing so bypasses the pool's weights, load and cooldowns, which is the one thing
+the plugin exists to decide.
+
+If the pool cannot serve a spawn \u2014 every slot cooling or exhausted, or repeated
+failures \u2014 do NOT fall back to reading or planning from your own inspection.
+Stop and ASK the user how to proceed; a failed spawn is not permission to
+investigate yourself.
+
 Repository context: before delegating investigation for a non-trivial task,
 tell the exploration agent to first check \`.opencode/context/\` in this project
 (using \`ls\`, never \`glob\` \u2014 it skips hidden directories)

package/dist/index.js

@@ -36,7 +36,10 @@ var MAX_WEIGHT = 100;
 var MAX_SLOTS = 4;
 var COOLDOWN_BASE_MS = 60 * 1e3;
 var COOLDOWN_MAX_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_BASE_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1e3;
 var STRIKE_DECAY_MS = 30 * 60 * 1e3;
+var isQuotaReason = (reason) => /quota|limit|rate|too-many|overloaded|429/i.test(reason);
 var BASES = ["explore", "implement", "context"];
 var PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
 var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
@@ -238,6 +241,7 @@ function state(opts = {}) {
       catalog: /* @__PURE__ */ new Map(),
       catalogAt: 0,
       cooling: /* @__PURE__ */ new Map(),
+      strikes: /* @__PURE__ */ new Map(),
       activity: /* @__PURE__ */ new Map(),
       reaped: 0,
       reaping: false,
@@ -294,6 +298,14 @@ function publish(s) {
     s.dirReady = false;
   }
 }
+var isPidAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
 function readSiblings(s) {
   const siblings = [];
   let entries;
@@ -327,6 +339,13 @@ function readSiblings(s) {
       }
       continue;
     }
+    if (/^\d+$/.test(match[1]) && !isPidAlive(Number(match[1]))) {
+      try {
+        unlinkSync(path4);
+      } catch {
+      }
+      continue;
+    }
     try {
       const parsed = JSON.parse(readFileSync2(path4, "utf8"));
       const claims = Object.values(parsed).filter(
@@ -340,10 +359,13 @@ function readSiblings(s) {
 }
 function readLimits(s) {
   const cooling = /* @__PURE__ */ new Map();
+  const memory = /* @__PURE__ */ new Map();
   let entries;
   try {
     entries = readdirSync(s.dir);
   } catch {
+    s.cooling = cooling;
+    s.strikes = memory;
     return cooling;
   }
   const now = Date.now();
@@ -353,8 +375,14 @@ function readLimits(s) {
     try {
       const strike = JSON.parse(readFileSync2(path4, "utf8"));
       if (typeof strike.until !== "number" || typeof strike.model !== "string") continue;
-      if (strike.until > now) cooling.set(strike.model, strike);
-      else unlinkSync(path4);
+      if (strike.until > now) {
+        cooling.set(strike.model, strike);
+        memory.set(strike.model, strike);
+      } else if (typeof strike.last === "number" && now - strike.last < STRIKE_DECAY_MS) {
+        memory.set(strike.model, strike);
+      } else {
+        unlinkSync(path4);
+      }
     } catch {
       try {
         unlinkSync(path4);
@@ -363,16 +391,21 @@ function readLimits(s) {
     }
   }
   s.cooling = cooling;
+  s.strikes = memory;
   return cooling;
 }
 function recordStrike(s, model, reason, stated) {
   if (!s.dirReady) return;
   const now = Date.now();
-  const prior = s.cooling.get(model);
+  const prior = s.strikes.get(model);
   const strikes = prior && now - prior.last < STRIKE_DECAY_MS ? prior.strikes + 1 : 1;
-  const backoff = Math.min(COOLDOWN_MAX_MS, COOLDOWN_BASE_MS * 2 ** (strikes - 1));
+  const quota = isQuotaReason(reason);
+  const base = quota ? QUOTA_COOLDOWN_BASE_MS : COOLDOWN_BASE_MS;
+  const cap = quota ? QUOTA_COOLDOWN_MAX_MS : COOLDOWN_MAX_MS;
+  const backoff = Math.min(cap, base * 2 ** (strikes - 1));
   const strike = { model, until: now + (stated ?? backoff), strikes, reason, last: now };
   s.cooling.set(model, strike);
+  s.strikes.set(model, strike);
   const path4 = join2(s.dir, limitFile(model));
   try {
     writeFileSync(`${path4}.tmp`, JSON.stringify(strike));
@@ -389,6 +422,7 @@ function coolUnavailable(s, model) {
   if (prior && prior.until > until) return prior;
   const strike = { model, until, strikes: 1, reason: "endpoint-unavailable", last: now };
   s.cooling.set(model, strike);
+  s.strikes.set(model, strike);
   const path4 = join2(s.dir, limitFile(model));
   try {
     writeFileSync(`${path4}.tmp`, JSON.stringify(strike));
@@ -524,8 +558,31 @@ Every question of the form "what does this file do", "where is X handled", or
   that proves it. Never one whole refactor handed over in a single piece \u2014
   see \`# Task size\` below.
 
-The agents you spawn are the pooled \`explore\` / \`implement\` bases \u2014
-spawn the bare name and let the pool route, never a \`-1\`/\`-2\` slot variant.
+The agents you spawn are the pooled \`explore\` / \`implement\` / \`context\`
+bases. **Always spawn the BARE base name and let the plugin choose the slot;
+never name a \`-N\` variant** (\`explore-1\`..\`explore-4\`, \`implement-1\`..,
+\`context-1\`..). The plugin owns which model every pooled spawn runs on: it
+picks the next slot from the pool's weights, current load and cooldowns, and
+rewrites your spawn to that variant for you. Naming a variant bypasses that
+decision, defeats failover, and can pin work to a cooling or unhealthy model.
+If you catch yourself choosing a slot number, you are doing the plugin's job \u2014
+spawn \`explore\` and let it decide.
+
+# When the pool is unavailable
+
+The pooled agents are the ONLY route to investigation and implementation. If the
+pool cannot serve a spawn \u2014 every slot cooling or exhausted, spawns repeatedly
+failing, or a runtime message saying no slot is available \u2014 that is a STOP
+condition, not a reason to do the work yourself.
+
+**Never fall back to reading, grepping, exploring or implementing on your own.**
+Do not "just quickly" inspect a file because a spawn failed. Stop, say what
+failed (slot, model, error), and ASK the user how to proceed: wait for a slot to
+recover, change the pool, or obtain explicit permission to work without
+subagents. A failed spawn is never permission, and silence is not consent.
+
+\`edit\`/\`write\`/\`bash\` stay yours for applying and verifying what a subagent
+returned \u2014 never as a substitute for a spawn that could not run.
 
 # Task size
 
@@ -629,6 +686,16 @@ When you need to understand the codebase:
 2. Invoke @explore with specific, focused instructions (e.g. "read src/auth.ts", "grep for 'migration' in *.py files", "list the src/ directory")
 3. @explore will return its findings \u2014 you process them and plan accordingly
 
+Always spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`) and let
+the plugin choose the slot. Never name a \`-N\` variant (\`explore-1\`..\`explore-4\`);
+doing so bypasses the pool's weights, load and cooldowns, which is the one thing
+the plugin exists to decide.
+
+If the pool cannot serve a spawn \u2014 every slot cooling or exhausted, or repeated
+failures \u2014 do NOT fall back to reading or planning from your own inspection.
+Stop and ASK the user how to proceed; a failed spawn is not permission to
+investigate yourself.
+
 Repository context: before delegating investigation for a non-trivial task,
 tell the exploration agent to first check \`.opencode/context/\` in this project
 (using \`ls\`, never \`glob\` \u2014 it skips hidden directories)
@@ -1282,9 +1349,10 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
           `hung ${claim.v} on ${claim.m} after ${Math.round((Date.now() - claim.t) / 1e3)}s with ${Math.round(idleFor(s, claim, Date.now()) / 1e3)}s of silence; ${killed ? `aborted session ${claim.g}` : "no session to abort"}`,
           { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: killed }
         );
-        const prior = s.cooling.get(claim.m);
         const now = Date.now();
-        const strike = recordStrike(s, claim.m, "hang", prior && prior.until > now ? prior.until - now : HANG_FALLBACK_MS);
+        const prior = s.cooling.get(claim.m);
+        if (prior && prior.until > now) continue;
+        const strike = recordStrike(s, claim.m, "hang", HANG_FALLBACK_MS);
         if (strike) await log("warn", `cooling ${claim.m} for ${Math.round((strike.until - now) / 1e3)}s (hang)`);
       }
     } catch (error) {
@@ -1492,6 +1560,7 @@ priority is weight: the heaviest slot under its ceiling takes the next spawn (FU
     dispose: async () => {
       clearInterval(timer);
       s.own.clear();
+      publish(s);
     }
   };
 });
@@ -2151,6 +2220,477 @@ var notifyHooks = (async ({ client, directory }, _options, deps = {}) => {
   };
 });
 
+// src/lib/omniroute.ts
+var DEFAULT_BASE_URL = "http://localhost:20128/v1";
+var ENV_API_KEY = "OMNIROUTE_API_KEY";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var DEFAULT_CACHE_TTL_MS = 6e4;
+var COOLDOWN_BASE_MS2 = 1e3;
+var COOLDOWN_MAX_MS2 = 15 * 60 * 1e3;
+var MODELS_PATH = "/models";
+var dedupe = (ids) => {
+  const out = [];
+  for (const id of ids) if (!out.includes(id)) out.push(id);
+  return out;
+};
+var isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+var isStringArray = (value) => Array.isArray(value) && value.every((entry) => isNonEmptyString(entry));
+function normalizeBaseURL(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (trimmed === "") return null;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  let path4 = url.pathname.replace(/\/+$/, "");
+  while (path4.endsWith("/v1")) path4 = path4.slice(0, -"/v1".length);
+  return `${url.origin}${path4}/v1`;
+}
+function parseConfig(raw, env = process.env) {
+  if (typeof raw !== "object" || raw === null) return { enabled: false, config: null, problems: [] };
+  const block = raw;
+  if (block.enabled !== true) return { enabled: false, config: null, problems: [] };
+  const problems = [];
+  let baseURL = DEFAULT_BASE_URL;
+  if (block.baseURL !== void 0) {
+    const normalized = normalizeBaseURL(block.baseURL);
+    if (normalized === null) problems.push("omniroute.baseURL is not a valid http(s) URL");
+    else baseURL = normalized;
+  }
+  let timeoutMs = DEFAULT_TIMEOUT_MS;
+  if (block.timeoutMs !== void 0) {
+    const value = block.timeoutMs;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      problems.push("omniroute.timeoutMs must be a positive number");
+    } else {
+      timeoutMs = value;
+    }
+  }
+  let stickyPerSession = true;
+  if (block.stickyPerSession !== void 0) {
+    if (typeof block.stickyPerSession !== "boolean") problems.push("omniroute.stickyPerSession must be a boolean");
+    else stickyPerSession = block.stickyPerSession;
+  }
+  let healthCheck = true;
+  if (block.healthCheck !== void 0) {
+    if (typeof block.healthCheck !== "boolean") problems.push("omniroute.healthCheck must be a boolean");
+    else healthCheck = block.healthCheck;
+  }
+  let combo;
+  if (block.combo !== void 0) {
+    if (!isNonEmptyString(block.combo)) problems.push("omniroute.combo must be a non-empty string");
+    else combo = block.combo.trim();
+  }
+  let models;
+  if (block.models !== void 0) {
+    if (!isStringArray(block.models)) problems.push("omniroute.models must be an array of non-empty strings");
+    else models = dedupe(block.models.map((id) => id.trim()));
+  }
+  let tiers = { primary: [], backup: [] };
+  if (block.tiers !== void 0) {
+    const value = block.tiers;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      problems.push("omniroute.tiers must be an object with primary/backup string arrays");
+    } else {
+      const read = (list) => {
+        if (list === void 0) return [];
+        if (!isStringArray(list)) return null;
+        return dedupe(list.map((id) => id.trim()));
+      };
+      const group = value;
+      const primary = read(group.primary);
+      const backup = read(group.backup);
+      if (primary === null || backup === null) {
+        problems.push("omniroute.tiers must be an object with primary/backup string arrays");
+      } else {
+        tiers = { primary, backup };
+      }
+    }
+  }
+  if (models !== void 0) {
+    const allowed = new Set(models);
+    tiers = {
+      primary: tiers.primary.filter((id) => allowed.has(id)),
+      backup: tiers.backup.filter((id) => allowed.has(id))
+    };
+  }
+  let apiKey;
+  if (block.apiKey !== void 0 && typeof block.apiKey !== "string") {
+    problems.push("omniroute.apiKey must be a string when set");
+  }
+  const fromEnv = env[ENV_API_KEY];
+  if (typeof fromEnv === "string" && fromEnv.trim() !== "") apiKey = fromEnv.trim();
+  else if (typeof block.apiKey === "string" && block.apiKey.trim() !== "") apiKey = block.apiKey.trim();
+  if (problems.length > 0) return { enabled: true, config: null, problems };
+  const config = {
+    baseURL,
+    tiers,
+    stickyPerSession,
+    healthCheck,
+    timeoutMs
+  };
+  if (apiKey !== void 0) config.apiKey = apiKey;
+  if (combo !== void 0) config.combo = combo;
+  if (models !== void 0) config.models = models;
+  return { enabled: true, config, problems: [] };
+}
+function filterModels(ids, config) {
+  const out = [];
+  const push = (id) => {
+    if (id.trim() === "") return;
+    if (!out.includes(id)) out.push(id);
+  };
+  if (config.combo !== void 0) push(config.combo);
+  if (config.models !== void 0) {
+    for (const id of config.models) if (ids.includes(id)) push(id);
+  } else {
+    for (const id of ids) push(id);
+  }
+  return out;
+}
+function orderByTier(ids, tiers) {
+  const present = new Set(ids);
+  const out = [];
+  const push = (id) => {
+    if (!out.includes(id)) out.push(id);
+  };
+  for (const id of tiers.primary) if (present.has(id)) push(id);
+  for (const id of tiers.backup) if (present.has(id)) push(id);
+  for (const id of ids) push(id);
+  return out;
+}
+function isTransientStatus(status) {
+  if (status === 429 || status === 408) return true;
+  return status >= 500 && status <= 599;
+}
+function backoffMs(strikes, capMs = COOLDOWN_MAX_MS2) {
+  const count = Number.isFinite(strikes) ? strikes : 1;
+  return Math.min(COOLDOWN_BASE_MS2 * 2 ** (count - 1), capMs);
+}
+function cooldownUntil(opts) {
+  const cap = opts.capMs ?? COOLDOWN_MAX_MS2;
+  const now = opts.now ?? Date.now();
+  const retryAfterMs2 = opts.retryAfterMs;
+  if (typeof retryAfterMs2 === "number" && Number.isFinite(retryAfterMs2) && retryAfterMs2 > 0) {
+    return now + Math.min(retryAfterMs2, cap);
+  }
+  const strikes = opts.strikes ?? 1;
+  return now + backoffMs(Math.max(1, strikes), cap);
+}
+var rateOf = (stat) => {
+  const attempts = stat.requests + stat.errors;
+  return attempts > 0 ? stat.errors / attempts : 0;
+};
+var ttftOf = (stat) => stat.ttftEwma ?? Number.POSITIVE_INFINITY;
+function createSelector(config, deps = {}) {
+  const now = deps.now ?? Date.now;
+  const stats = /* @__PURE__ */ new Map();
+  const sticky = /* @__PURE__ */ new Map();
+  let cands = [];
+  const ensure = (modelID) => {
+    let stat = stats.get(modelID);
+    if (stat === void 0) {
+      stat = { requests: 0, errors: 0, strikes: 0, cooldownUntil: 0 };
+      stats.set(modelID, stat);
+    }
+    return stat;
+  };
+  const cooling = (modelID) => {
+    const stat = stats.get(modelID);
+    return stat !== void 0 && stat.cooldownUntil > now();
+  };
+  const better = (challenger, challengerIndex, best, bestIndex) => {
+    const challengerRate = rateOf(challenger);
+    const bestRate = rateOf(best);
+    if (challengerRate !== bestRate) return challengerRate < bestRate;
+    const challengerTtft = ttftOf(challenger);
+    const bestTtft = ttftOf(best);
+    if (challengerTtft !== bestTtft) return challengerTtft < bestTtft;
+    return challengerIndex < bestIndex;
+  };
+  return {
+    setCandidates(ids) {
+      const next = dedupe(ids.filter((id) => typeof id === "string" && id.trim() !== ""));
+      cands = next;
+      for (const id of next) ensure(id);
+    },
+    candidates() {
+      return [...cands];
+    },
+    select(sessionID) {
+      const list = cands;
+      if (list.length === 0) return null;
+      if (config.stickyPerSession) {
+        const held = sticky.get(sessionID);
+        if (held !== void 0 && list.includes(held) && !cooling(held)) return held;
+      }
+      let bestID = null;
+      let bestStat = null;
+      let bestIndex = -1;
+      for (const [index, id] of list.entries()) {
+        const stat = ensure(id);
+        if (stat.cooldownUntil > now()) continue;
+        if (bestStat === null || bestID === null || better(stat, index, bestStat, bestIndex)) {
+          bestID = id;
+          bestStat = stat;
+          bestIndex = index;
+        }
+      }
+      if (bestID === null) return null;
+      if (config.stickyPerSession) sticky.set(sessionID, bestID);
+      return bestID;
+    },
+    stickyFor(sessionID) {
+      return sticky.get(sessionID) ?? null;
+    },
+    recordSuccess(sessionID, modelID, ttftMs) {
+      void sessionID;
+      const stat = ensure(modelID);
+      stat.requests += 1;
+      if (typeof ttftMs === "number" && Number.isFinite(ttftMs) && ttftMs >= 0) {
+        stat.ttftEwma = stat.ttftEwma === void 0 ? ttftMs : stat.ttftEwma * 0.6 + ttftMs * 0.4;
+      }
+    },
+    recordFailure(sessionID, modelID, opts = {}) {
+      const stat = ensure(modelID);
+      stat.errors += 1;
+      if (opts.message !== void 0) stat.lastFailure = opts.message;
+      const transient = opts.transient ?? (opts.status === void 0 ? true : isTransientStatus(opts.status));
+      if (!transient) return;
+      stat.strikes += 1;
+      const until = cooldownUntil({ retryAfterMs: opts.retryAfterMs, strikes: stat.strikes, now: now() });
+      if (until > stat.cooldownUntil) stat.cooldownUntil = until;
+      if (sticky.get(sessionID) === modelID) sticky.delete(sessionID);
+    },
+    isCooling(modelID) {
+      return cooling(modelID);
+    },
+    stats() {
+      const out = {};
+      for (const [id, stat] of stats) out[id] = { ...stat };
+      return out;
+    }
+  };
+}
+var statusReason = (status) => {
+  const reasons = {
+    400: "bad request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not found",
+    408: "request timeout",
+    429: "rate limited",
+    500: "server error",
+    502: "bad gateway",
+    503: "unavailable",
+    504: "gateway timeout"
+  };
+  if (Number.isFinite(status) && reasons[status] !== void 0) return reasons[status];
+  return status >= 500 ? "server error" : "http error";
+};
+var entryID = (entry) => {
+  if (typeof entry === "string") return entry.trim() === "" ? null : entry.trim();
+  if (entry !== null && typeof entry === "object") {
+    const id = entry.id;
+    if (typeof id === "string") return id.trim() === "" ? null : id.trim();
+  }
+  return null;
+};
+var listEntries = (body) => {
+  if (Array.isArray(body)) return body;
+  if (body === null || typeof body !== "object") return null;
+  const obj = body;
+  if (Array.isArray(obj.data)) return obj.data;
+  if (Array.isArray(obj.models)) return obj.models;
+  return null;
+};
+async function fetchModels(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const url = `${opts.baseURL}${MODELS_PATH}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = {};
+    if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
+    const response = await fetchImpl(url, { headers, signal: controller.signal });
+    const status = typeof response?.status === "number" ? response.status : Number.NaN;
+    const ok = typeof response?.ok === "boolean" ? response.ok : Number.isFinite(status) ? status >= 200 && status < 300 : true;
+    if (!ok) throw new Error(`omniroute GET ${url} failed: HTTP ${status} ${statusReason(status)}`);
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new Error(`omniroute GET ${url} returned a non-JSON body`);
+    }
+    const entries = listEntries(body);
+    if (entries === null) throw new Error(`omniroute GET ${url} returned an unsupported body shape`);
+    const out = [];
+    for (const entry of entries) {
+      const id = entryID(entry);
+      if (id !== null && !out.includes(id)) out.push(id);
+    }
+    return out;
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error(`omniroute GET ${url} timed out after ${timeoutMs}ms`);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function checkHealth(opts) {
+  try {
+    await fetchModels(opts);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createModelCache(opts) {
+  const ttlMs = opts.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  const now = opts.now ?? Date.now;
+  let cached = null;
+  let cachedAt = 0;
+  return {
+    async get(force) {
+      if (!force && cached !== null && now() - cachedAt < ttlMs) return [...cached];
+      try {
+        const ids = await fetchModels(opts);
+        cached = ids;
+        cachedAt = now();
+        return [...ids];
+      } catch (error) {
+        if (cached !== null) return [...cached];
+        throw error;
+      }
+    },
+    invalidate() {
+      cached = null;
+      cachedAt = 0;
+    }
+  };
+}
+function redactApiKey(text, apiKey) {
+  if (typeof apiKey !== "string" || apiKey === "") return text;
+  return text.split(apiKey).join("[redacted]");
+}
+
+// src/plugins/omniroute.ts
+var SERVICE4 = "omniroute";
+var omniRouteHooks = async (input, options, deps = {}) => {
+  const opts = options ?? {};
+  const parsed = parseConfig(opts.omniroute, deps.env ?? process.env);
+  const log = (level, message) => input.client.app.log({ body: { service: SERVICE4, level, message } }).catch(() => {
+  });
+  const warned = /* @__PURE__ */ new Set();
+  const warnOnce = async (message) => {
+    if (warned.has(message)) return;
+    warned.add(message);
+    await log("warn", message);
+  };
+  if (!parsed.enabled) return {};
+  if (parsed.config === null) {
+    await warnOnce(`omniroute is enabled but unusable: ${parsed.problems.join("; ")}`);
+    return {};
+  }
+  const config = parsed.config;
+  const cache = createModelCache({
+    baseURL: config.baseURL,
+    apiKey: config.apiKey,
+    timeoutMs: config.timeoutMs,
+    fetchImpl: deps.fetchImpl,
+    now: deps.now
+  });
+  const selector = createSelector(config, { now: deps.now });
+  let disabled = false;
+  const probe = async () => {
+    if (config.healthCheck) {
+      const healthy = await checkHealth({
+        baseURL: config.baseURL,
+        apiKey: config.apiKey,
+        timeoutMs: config.timeoutMs,
+        fetchImpl: deps.fetchImpl
+      });
+      if (!healthy) {
+        disabled = true;
+        await warnOnce(`omniroute health check failed at ${config.baseURL}; falling back to lacode's normal behaviour for this run`);
+        return;
+      }
+    }
+    let ids;
+    try {
+      ids = await cache.get();
+    } catch (error) {
+      disabled = true;
+      await warnOnce(
+        redactApiKey(
+          `omniroute is unreachable at ${config.baseURL}: ${error instanceof Error ? error.message : String(error)}; falling back for this run`,
+          config.apiKey
+        )
+      );
+      return;
+    }
+    const candidates = orderByTier(filterModels(ids, config), config.tiers);
+    if (candidates.length === 0) {
+      disabled = true;
+      await warnOnce(`omniroute returned no usable models at ${config.baseURL}; falling back for this run`);
+      return;
+    }
+    selector.setCandidates(candidates);
+    await log("info", `omniroute: ${candidates.length} model(s) from ${config.baseURL}: ${candidates.join(", ")}`);
+  };
+  let started = null;
+  const initialize = () => started ??= probe();
+  const injectProvider = async (cfg, warn) => {
+    const providers = cfg.provider ??= {};
+    if (providers.omniroute !== void 0) {
+      await warn("omniroute provider is already defined in your config; lacode left it untouched");
+      return;
+    }
+    const exposed = selector.candidates();
+    const models = {};
+    for (const id of exposed) models[id] = { name: id };
+    providers.omniroute = {
+      name: "OmniRoute",
+      // The documented opencode registration mechanism for a gateway speaking
+      // the OpenAI `/v1` API: opencode loads this package itself from the user's
+      // own install, so lacode needs no dependency to expose OmniRoute. No
+      // `capabilities` are declared on purpose -- opencode ignores custom
+      // capabilities for openai-compatible providers, so writing one would be
+      // decoration that reads like a promise.
+      npm: "@ai-sdk/openai-compatible",
+      options: {
+        baseURL: config.baseURL,
+        // Absent rather than blank: an empty bearer on a keyless gateway is a
+        // 401 that looks like a configuration error.
+        ...config.apiKey ? { apiKey: config.apiKey } : {},
+        timeout: config.timeoutMs
+      },
+      models
+    };
+  };
+  return {
+    config: async (cfg) => {
+      try {
+        await initialize();
+        if (disabled) return;
+        await injectProvider(cfg, warnOnce);
+      } catch (error) {
+        await warnOnce(
+          redactApiKey(
+            `omniroute config injection failed: ${error instanceof Error ? error.message : String(error)}`,
+            config.apiKey
+          )
+        );
+      }
+    }
+  };
+};
+
 // src/lib/selfupdate.ts
 import { spawn as spawn2 } from "node:child_process";
 import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, statSync as statSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, writeSync } from "node:fs";
@@ -2443,6 +2983,7 @@ var LaCode = (async (input, options) => {
   const autoupdate = await settled("context-autoupdate", () => contextAutoUpdateHooks(input, options)) ?? inertHooks;
   const notifier = await settled("notify", () => notifyHooks(input, options)) ?? inertHooks;
   const selfupdate = await settled("self-update", () => selfUpdateHooks(input, options)) ?? inertHooks;
+  const omniroute = await settled("omniroute", () => omniRouteHooks(input, options)) ?? inertHooks;
   const config = async (cfg) => {
     try {
       const injected = applyAgents(cfg, agentSet);
@@ -2456,6 +2997,7 @@ var LaCode = (async (input, options) => {
       if (applyInstructions(cfg).added) {
         await log("info", "instructions: added the standing context-map rule (no user instructions were present)");
       }
+      await omniroute.config?.(cfg);
       await pool.config?.(cfg);
     } catch (error) {
       await log("error", `config hook failed: ${String(error)}`);
@@ -2484,6 +3026,7 @@ var LaCode = (async (input, options) => {
       await autoupdate.dispose?.();
       await notifier.dispose?.();
       await selfupdate.dispose?.();
+      await omniroute.dispose?.();
     }
   };
 });

package/dist/pool.js

@@ -36,7 +36,10 @@ var MAX_WEIGHT = 100;
 var MAX_SLOTS = 4;
 var COOLDOWN_BASE_MS = 60 * 1e3;
 var COOLDOWN_MAX_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_BASE_MS = 15 * 60 * 1e3;
+var QUOTA_COOLDOWN_MAX_MS = 6 * 60 * 60 * 1e3;
 var STRIKE_DECAY_MS = 30 * 60 * 1e3;
+var isQuotaReason = (reason) => /quota|limit|rate|too-many|overloaded|429/i.test(reason);
 var BASES = ["explore", "implement", "context"];
 var PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
 var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
@@ -238,6 +241,7 @@ function state(opts = {}) {
       catalog: /* @__PURE__ */ new Map(),
       catalogAt: 0,
       cooling: /* @__PURE__ */ new Map(),
+      strikes: /* @__PURE__ */ new Map(),
       activity: /* @__PURE__ */ new Map(),
       reaped: 0,
       reaping: false,
@@ -294,6 +298,14 @@ function publish(s) {
     s.dirReady = false;
   }
 }
+var isPidAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+};
 function readSiblings(s) {
   const siblings = [];
   let entries;
@@ -327,6 +339,13 @@ function readSiblings(s) {
       }
       continue;
     }
+    if (/^\d+$/.test(match[1]) && !isPidAlive(Number(match[1]))) {
+      try {
+        unlinkSync(path);
+      } catch {
+      }
+      continue;
+    }
     try {
       const parsed = JSON.parse(readFileSync2(path, "utf8"));
       const claims = Object.values(parsed).filter(
@@ -340,10 +359,13 @@ function readSiblings(s) {
 }
 function readLimits(s) {
   const cooling = /* @__PURE__ */ new Map();
+  const memory = /* @__PURE__ */ new Map();
   let entries;
   try {
     entries = readdirSync(s.dir);
   } catch {
+    s.cooling = cooling;
+    s.strikes = memory;
     return cooling;
   }
   const now = Date.now();
@@ -353,8 +375,14 @@ function readLimits(s) {
     try {
       const strike = JSON.parse(readFileSync2(path, "utf8"));
       if (typeof strike.until !== "number" || typeof strike.model !== "string") continue;
-      if (strike.until > now) cooling.set(strike.model, strike);
-      else unlinkSync(path);
+      if (strike.until > now) {
+        cooling.set(strike.model, strike);
+        memory.set(strike.model, strike);
+      } else if (typeof strike.last === "number" && now - strike.last < STRIKE_DECAY_MS) {
+        memory.set(strike.model, strike);
+      } else {
+        unlinkSync(path);
+      }
     } catch {
       try {
         unlinkSync(path);
@@ -363,16 +391,21 @@ function readLimits(s) {
     }
   }
   s.cooling = cooling;
+  s.strikes = memory;
   return cooling;
 }
 function recordStrike(s, model, reason, stated) {
   if (!s.dirReady) return;
   const now = Date.now();
-  const prior = s.cooling.get(model);
+  const prior = s.strikes.get(model);
   const strikes = prior && now - prior.last < STRIKE_DECAY_MS ? prior.strikes + 1 : 1;
-  const backoff = Math.min(COOLDOWN_MAX_MS, COOLDOWN_BASE_MS * 2 ** (strikes - 1));
+  const quota = isQuotaReason(reason);
+  const base = quota ? QUOTA_COOLDOWN_BASE_MS : COOLDOWN_BASE_MS;
+  const cap = quota ? QUOTA_COOLDOWN_MAX_MS : COOLDOWN_MAX_MS;
+  const backoff = Math.min(cap, base * 2 ** (strikes - 1));
   const strike = { model, until: now + (stated ?? backoff), strikes, reason, last: now };
   s.cooling.set(model, strike);
+  s.strikes.set(model, strike);
   const path = join2(s.dir, limitFile(model));
   try {
     writeFileSync(`${path}.tmp`, JSON.stringify(strike));
@@ -389,6 +422,7 @@ function coolUnavailable(s, model) {
   if (prior && prior.until > until) return prior;
   const strike = { model, until, strikes: 1, reason: "endpoint-unavailable", last: now };
   s.cooling.set(model, strike);
+  s.strikes.set(model, strike);
   const path = join2(s.dir, limitFile(model));
   try {
     writeFileSync(`${path}.tmp`, JSON.stringify(strike));
@@ -511,6 +545,8 @@ export {
   ORPHAN_TMP_MS,
   PACKAGE_ROOT,
   PRESETS_DIR,
+  QUOTA_COOLDOWN_BASE_MS,
+  QUOTA_COOLDOWN_MAX_MS,
   STUCK_IDLE_MS,
   STUCK_MIN_AGE_MS,
   UNAVAILABLE_COOLDOWN_MS,
@@ -530,6 +566,7 @@ export {
   init,
   isAvailable,
   isLimitText,
+  isQuotaReason,
   isUnavailableText,
   noteActivity,
   parseSlotText,

package/docs/USER-STORIES.md

@@ -140,6 +140,17 @@ correct exactly when a whitelist exists (it is a real restriction, and the pool
 models would otherwise resolve to nothing) and is not merely unnecessary when one
 does not.
 
+### US-28: A local gateway (OmniRoute) is registered as an ordinary provider
+**As a** user running a local OpenAI-compatible gateway, **I want** LaCode to register it so its models are selectable and I can name one in my pool, **so that** *I* decide whether pooled work drains through it instead of the bundled models.
+
+**Story ID(s) for tests:** US-28
+**Acceptance criteria:**
+- [ ] Given `omniroute.enabled` with a reachable gateway, When the config hook runs, Then LaCode registers a `provider.omniroute` entry exposing the gateway's models (everything it lists, or filtered by `models`/`combo`), and writes NOTHING into the pool.
+- [ ] Given any pool source (bundled preset, `pool.json`, `pool.txt`, or `options.models`), When OmniRoute is enabled and healthy, Then every slot resolves exactly as it would without the integration — the slot list is unchanged, so opting in means the user lists `omniroute/<model>` themselves.
+- [ ] Given a pool slot naming an `omniroute/<model>`, When the pool resolves and binds, Then that slot routes as an ordinary slot, and the pool does not warn the provider is missing, because OmniRoute registers the provider before the pool's config hook runs.
+- [ ] Given OmniRoute is disabled, enabled with an invalid block, unhealthy, or returns no usable models, When the config hook runs, Then no provider is registered, no pool slot changes, and a failure is warned about once.
+- [ ] Given the gateway is unreachable, When pooled work runs, Then the only thing affected is a slot that names `omniroute/<model>`; every other slot keeps working, because the plugin never put an `omniroute` slot in the pool.
+
 ---
 
 ## Epic C — Hang detection and auto-recovery
@@ -413,6 +424,7 @@ table was filled in.
 | US-5 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-test.mjs`, `tests/pool-models-test.mjs` |
 | US-6 | B | `tests/stories/b-provider-resilience.test.mjs` |
 | US-7 | B | `tests/stories/b-provider-resilience.test.mjs`, `tests/pool-models-test.mjs` |
+| US-28 | B | `tests/stories/i-omniroute.test.mjs` |
 | US-8 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs` |
 | US-9 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-shared-test.mjs` |
 | US-10 | C | `tests/stories/c-hang-recovery.test.mjs`, `tests/pool-hang-test.mjs`, `tests/pool-timer-test.mjs` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",