@lawaty/lacode 0.2.0 → 0.2.2

package/README.md

@@ -324,6 +324,29 @@ 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.
 
+**Setting it up on a client machine.** Four steps, in this order:
+
+1. Install OmniRoute, then make it stay up: run `omniroute autostart enable`
+   once. That writes a systemd user unit in a headless session, or an XDG
+   autostart entry in a graphical one, and OmniRoute supervises itself from
+   there on. Its gateway listens on `http://localhost:20128/v1`. The gateway's
+   lifecycle is **the client's responsibility**: LaCode never starts, supervises
+   or stops it, it only probes it. The gateway must therefore already be
+   running **before** you start opencode — one that is down at startup is
+   disabled for that run, and the integration is per-run.
+2. Add the plugin block to your opencode config:
+   `["@lawaty/lacode", { "omniroute": { "enabled": true, "apiKey": "<your omniroute key>", "combo": "auto", "models": [] } }]`
+3. Optionally, to route pooled work through it, make `omniroute/auto 3` the
+   **first** line of `~/.config/lacode/pool.txt`. `pool.txt` is optional user
+   config; the bundled default preset does **not** include OmniRoute.
+4. **Restart opencode.** Nothing here hot-reloads.
+
+With `models: []` and `combo: "auto"`, the plugin registers exactly one model,
+`omniroute/auto`, which then appears in the model picker for any agent — no
+hand-maintained model list.
+
+The full option set, for reference:
+
 ```jsonc
 {
   "plugin": [
@@ -352,12 +375,12 @@ as an opencode provider for you. It is **off by default**: if you do not set
 | `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 (or `auto`) used as the routing model. Always exposed first. |
+| `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. |
+| `timeoutMs` | `5000` | Budget for LaCode's own probe and model-cache calls to the gateway. It is not written into the provider options, so it does not bound real traffic — opencode's own default applies there. |
 
 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
@@ -372,25 +395,34 @@ 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.
-
-**OmniRoute becomes the pool's primary slot.** This is the point of the
-integration: when the gateway is healthy, LaCode replaces the pool's **first
-slot** — the one the pool takes first — with
-`omniroute/<combo | first allowlisted model | auto>`, inheriting that slot's
-weight, so pooled mechanical work (exploration, implementation, cartography)
-drains through OmniRoute before it reaches the bundled opencode/opencode-go
-("zen") models. On the default `pool.txt` shown below, gemini's slot becomes
-OmniRoute — same slot count, same weights — and bunny / step-5 / big-pickle keep
-their places behind it. The replacement is skipped, leaving the pool exactly as
-it was, if the gateway is disabled, unreachable, returns no usable models, or if
-your own pool already routes on the `omniroute` provider (LaCode never stacks a
-second slot on a provider you already chose). See
+**Combo vs. allowlist.** Set `combo` and OmniRoute does the fallback for you
+(let it route): the combo leads the exposed models, so opencode can hand a failed
+request to the gateway's own fallback chain. Without a combo, LaCode exposes the
+allowlist ordered by `tiers` (primary first). Candidate order is `filterModels`
+(combo first, then the hard allowlist) followed by `orderByTier`, and that is
+all — LaCode picks which model is exposed and in what order; it does not measure
+latency or error rate at runtime, and it does not skip a model because it
+failed.
+
+**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
@@ -408,12 +440,14 @@ local instance with `REQUIRE_API_KEY=false`, the literal placeholder
 
 | 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. |
+| `omniroute health check failed` at startup | Gateway not running, wrong `baseURL`, or a startup race | Start OmniRoute on `http://localhost:20128` and restart opencode; `omniroute autostart enable` makes that durable across restarts. The integration is disabled for that run only, not permanently. |
+| `omniroute health check failed` at startup, then a repeating `cooling omniroute/<id> (hang)` and `Model not found` churn on one slot | OmniRoute was started *after* opencode, and `pool.txt` names an `omniroute/<id>` slot | The integration is off for that run, but the pool still routes to the slot: the request hangs, the reaper cools it for 600s, and the cycle repeats. Start OmniRoute, then restart opencode. |
+| `ProviderModelNotFoundError: Model not found` on an id the gateway serves | The id is a valid OmniRoute route but is not in the plugin's `models` allowlist, so the plugin never exposed it | Add the id to `models`, or use `combo: "auto"` with `omniroute/auto`. A valid gateway route is not automatically an exposed model. |
 | `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 your own pool already routes on `omniroute` | Check the startup log for `omniroute health check failed` / `no usable models`; if you added your own `omniroute/…` pool slot, remove it to let LaCode place one. |
+| 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
 
@@ -524,6 +558,7 @@ are reading:
 /context-init      # build the map, or verify and refresh an existing one
 /context-update    # incremental refresh; accepts a focus, e.g. /context-update src/payments
 /context-review    # audit it for staleness, contradictions, duplication and bloat
+/lacode-doctor     # check the pool, model resolution and the OmniRoute gateway. Report only
 ```
 
 The map is local and untracked — it describes your checkout on your machine, so

package/dist/commands.js

@@ -67,6 +67,36 @@ Audit the five context files for:
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
+  },
+  "lacode-doctor": {
+    description: "Check the LaCode setup \u2014 pool slots, model resolution, and the OmniRoute gateway. Report only; changes nothing.",
+    template: `Diagnose this machine's LaCode setup. Report only; change nothing.
+
+Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
+
+1. Pool status \u2014 call the \`pool_status\` tool. Report the slot list, each
+   slot's load against its weight ceiling, and which models are cooling.
+
+2. OmniRoute configured \u2014 inspect the \`@lawaty/lacode\` plugin options in the
+   user's opencode config for an \`omniroute\` block with \`enabled: true\`. If it
+   is absent or disabled, print the two OmniRoute checks below as "not
+   configured" and stop after the pool section.
+
+3. Gateway reachable \u2014 when omniroute is configured, request its model list
+   (\`GET <baseURL>/v1/models\`, default baseURL \`http://localhost:20128/v1\`)
+   and report reachable or not. On failure, say plainly: start OmniRoute BEFORE
+   opencode, then restart opencode \u2014 provider registration is per-run. To make
+   that durable, run \`omniroute autostart enable\` (OmniRoute's own autostart;
+   LaCode never starts the gateway itself).
+
+4. Slots resolve \u2014 for every pool slot whose provider is \`omniroute\`, confirm
+   the model id is one the gateway advertises AND is registered. The known
+   trap: an id that is a valid gateway route but is NOT in the plugin's
+   \`omniroute.models\` allowlist fails with
+   \`ProviderModelNotFoundError: Model not found\`; the fix is to add that id to
+   the \`models\` array, or use the always-registered \`auto\`.
+
+Change nothing. Print a final one-line summary of failures.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {

package/dist/index.js

@@ -250,51 +250,19 @@ function state(opts = {}) {
       dir,
       modelsFile,
       inlineModels: models,
-      primarySlot: null,
       origin: "unresolved",
       slots: []
     };
   }
   return g[key];
 }
-function replacePrimarySlot(base, primary) {
-  const problems = [];
-  const model = typeof primary?.model === "string" ? primary.model.trim() : "";
-  if (!model.includes("/")) {
-    problems.push(`primary slot: model must be written provider/model-id, got "${model}"`);
-    return { slots: base, problems };
-  }
-  const provider = providerOf(model);
-  if (base.some((slot) => providerOf(slot.model) === provider)) {
-    problems.push(`primary slot ${model}: provider ${provider} is already in the pool; the primary slot is skipped`);
-    return { slots: base, problems };
-  }
-  if (base.length === 0) return { slots: [{ index: 1, model, weight: Math.max(1, primary.weight ?? 1) }], problems };
-  let weight = primary.weight;
-  if (weight !== void 0 && (typeof weight !== "number" || !Number.isFinite(weight) || weight <= 0)) {
-    problems.push(`primary slot ${model}: weight must be a positive number; inheriting the replaced slot's weight`);
-    weight = void 0;
-  }
-  const slots = base.map((slot, i) => i === 0 ? { ...slot, model, weight: weight ?? slot.weight } : slot);
-  return { slots, problems };
-}
-function setPrimarySlot(s, primary) {
-  s.primarySlot = primary;
-  if (s.slots.length > 0) s.slots = [];
-}
 function ensureSlots(s, onWarn) {
   if (s.slots.length > 0) return s.slots;
   const { slots, problems, origin } = resolveModels({ models: s.inlineModels, modelsFile: s.modelsFile });
-  let resolved = slots;
-  if (s.primarySlot !== null) {
-    const replaced = replacePrimarySlot(slots, s.primarySlot);
-    resolved = replaced.slots;
-    problems.push(...replaced.problems);
-  }
-  s.slots = resolved;
+  s.slots = slots;
   s.origin = origin;
   for (const problem of problems) onWarn(problem);
-  return resolved;
+  return slots;
 }
 var claimKey = (sessionID, callID) => `${sessionID}:${callID}`;
 var selfFile = (id) => `claims.${id}.json`;
@@ -1304,6 +1272,36 @@ Audit the five context files for:
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
+  },
+  "lacode-doctor": {
+    description: "Check the LaCode setup \u2014 pool slots, model resolution, and the OmniRoute gateway. Report only; changes nothing.",
+    template: `Diagnose this machine's LaCode setup. Report only; change nothing.
+
+Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
+
+1. Pool status \u2014 call the \`pool_status\` tool. Report the slot list, each
+   slot's load against its weight ceiling, and which models are cooling.
+
+2. OmniRoute configured \u2014 inspect the \`@lawaty/lacode\` plugin options in the
+   user's opencode config for an \`omniroute\` block with \`enabled: true\`. If it
+   is absent or disabled, print the two OmniRoute checks below as "not
+   configured" and stop after the pool section.
+
+3. Gateway reachable \u2014 when omniroute is configured, request its model list
+   (\`GET <baseURL>/v1/models\`, default baseURL \`http://localhost:20128/v1\`)
+   and report reachable or not. On failure, say plainly: start OmniRoute BEFORE
+   opencode, then restart opencode \u2014 provider registration is per-run. To make
+   that durable, run \`omniroute autostart enable\` (OmniRoute's own autostart;
+   LaCode never starts the gateway itself).
+
+4. Slots resolve \u2014 for every pool slot whose provider is \`omniroute\`, confirm
+   the model id is one the gateway advertises AND is registered. The known
+   trap: an id that is a valid gateway route but is NOT in the plugin's
+   \`omniroute.models\` allowlist fails with
+   \`ProviderModelNotFoundError: Model not found\`; the fix is to add that id to
+   the \`models\` array, or use the always-registered \`auto\`.
+
+Change nothing. Print a final one-line summary of failures.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {
@@ -2639,7 +2637,6 @@ var omniRouteHooks = async (input, options, deps = {}) => {
   });
   const selector = createSelector(config, { now: deps.now });
   let disabled = false;
-  let poolModel = null;
   const probe = async () => {
     if (config.healthCheck) {
       const healthy = await checkHealth({
@@ -2650,7 +2647,7 @@ var omniRouteHooks = async (input, options, deps = {}) => {
       });
       if (!healthy) {
         disabled = true;
-        await warnOnce(`omniroute health check failed at ${config.baseURL}; falling back to lacode's normal behaviour for this run`);
+        await warnOnce(`omniroute health check failed at ${config.baseURL}; falling back to lacode's normal behaviour for this run; pool slots naming omniroute/<id> will fail until the gateway is up`);
         return;
       }
     }
@@ -2674,8 +2671,6 @@ var omniRouteHooks = async (input, options, deps = {}) => {
       return;
     }
     selector.setCandidates(candidates);
-    const chosen = config.combo ?? (config.models !== void 0 && config.models.length > 0 ? candidates[0] : "auto");
-    poolModel = `omniroute/${chosen}`;
     await log("info", `omniroute: ${candidates.length} model(s) from ${config.baseURL}: ${candidates.join(", ")}`);
   };
   let started = null;
@@ -2687,10 +2682,8 @@ var omniRouteHooks = async (input, options, deps = {}) => {
       return;
     }
     const exposed = selector.candidates();
-    const target = poolModel !== null ? poolModel.slice("omniroute/".length) : null;
-    const ids = target !== null && !exposed.includes(target) ? [target, ...exposed] : exposed;
     const models = {};
-    for (const id of ids) models[id] = { name: id };
+    for (const id of exposed) models[id] = { name: id };
     providers.omniroute = {
       name: "OmniRoute",
       // The documented opencode registration mechanism for a gateway speaking
@@ -2704,15 +2697,10 @@ var omniRouteHooks = async (input, options, deps = {}) => {
         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
+        ...config.apiKey ? { apiKey: config.apiKey } : {}
       },
       models
     };
-    if (poolModel !== null) {
-      const ps = state(options ?? {});
-      setPrimarySlot(ps, { model: poolModel });
-    }
   };
   return {
     config: async (cfg) => {

package/dist/pool.js

@@ -250,51 +250,19 @@ function state(opts = {}) {
       dir,
       modelsFile,
       inlineModels: models,
-      primarySlot: null,
       origin: "unresolved",
       slots: []
     };
   }
   return g[key];
 }
-function replacePrimarySlot(base, primary) {
-  const problems = [];
-  const model = typeof primary?.model === "string" ? primary.model.trim() : "";
-  if (!model.includes("/")) {
-    problems.push(`primary slot: model must be written provider/model-id, got "${model}"`);
-    return { slots: base, problems };
-  }
-  const provider = providerOf(model);
-  if (base.some((slot) => providerOf(slot.model) === provider)) {
-    problems.push(`primary slot ${model}: provider ${provider} is already in the pool; the primary slot is skipped`);
-    return { slots: base, problems };
-  }
-  if (base.length === 0) return { slots: [{ index: 1, model, weight: Math.max(1, primary.weight ?? 1) }], problems };
-  let weight = primary.weight;
-  if (weight !== void 0 && (typeof weight !== "number" || !Number.isFinite(weight) || weight <= 0)) {
-    problems.push(`primary slot ${model}: weight must be a positive number; inheriting the replaced slot's weight`);
-    weight = void 0;
-  }
-  const slots = base.map((slot, i) => i === 0 ? { ...slot, model, weight: weight ?? slot.weight } : slot);
-  return { slots, problems };
-}
-function setPrimarySlot(s, primary) {
-  s.primarySlot = primary;
-  if (s.slots.length > 0) s.slots = [];
-}
 function ensureSlots(s, onWarn) {
   if (s.slots.length > 0) return s.slots;
   const { slots, problems, origin } = resolveModels({ models: s.inlineModels, modelsFile: s.modelsFile });
-  let resolved = slots;
-  if (s.primarySlot !== null) {
-    const replaced = replacePrimarySlot(slots, s.primarySlot);
-    resolved = replaced.slots;
-    problems.push(...replaced.problems);
-  }
-  s.slots = resolved;
+  s.slots = slots;
   s.origin = origin;
   for (const problem of problems) onWarn(problem);
-  return resolved;
+  return slots;
 }
 var claimKey = (sessionID, callID) => `${sessionID}:${callID}`;
 var selfFile = (id) => `claims.${id}.json`;
@@ -615,11 +583,9 @@ export {
   refreshCatalog,
   release,
   releaseStuck,
-  replacePrimarySlot,
   resolveModels,
   retryAfterMs,
   selfFile,
-  setPrimarySlot,
   slotFor,
   snapshot,
   splitModel,

package/docs/USER-STORIES.md

@@ -140,16 +140,16 @@ 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) becomes the pool's primary slot
-**As a** user running a local OpenAI-compatible gateway, **I want** LaCode to drain the pool's mechanical work through it first, **so that** the bundled opencode/opencode-go ("zen") models stop carrying that load.
+### 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 and a `combo` or `models` choice, When the config hook runs, Then slot 1 of the pool is `omniroute/<combo | first allowlisted model>` — replacing the first slot's model IN PLACE and inheriting that slot's weight — so it is the model the pool takes first.
-- [ ] Given OmniRoute is disabled, enabled with an invalid block, unhealthy, or returns no usable models, When the pool resolves, Then no slot is changed and the resolved slots are exactly what the chain produced — the behaviour before the integration existed.
-- [ ] Given the user's own pool already routes on the `omniroute` provider, When the integration is healthy, Then the first slot is left exactly as written and no second slot is stacked on that provider.
-- [ ] Given the primary slot is injected, When the pool resolves, Then the number of slots is unchanged and every slot after the first is byte-identical to what the chain produced — nothing is dropped or renumbered, because the replacement creates no extra slot.
-- [ ] Given an `omniroute` slot is injected, When the pool binds its variants, Then it does not warn that the provider is missing, because OmniRoute registers the provider before the pool's config hook runs.
+- [ ] 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.
 
 ---
 

package/package.json

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