@lawaty/lacode 0.4.0 → 0.4.2

package/docs/INSTALL.md

@@ -0,0 +1,209 @@
+# Install and troubleshooting
+
+Everything about getting LaCode loaded, and what to do when it silently is not. The one-line install is in the [README](../README.md#getting-started); this page is for the rest of it.
+
+A plugin that fails to load is silent — opencode starts normally, prints nothing, logs nothing, and the agents are simply not there. Start at [If the agents are missing](#if-the-agents-are-missing).
+
+## Where it is installed
+
+opencode installs npm plugins itself, into one directory per specifier under its
+cache — not into your project's `node_modules`, and not from anywhere a global
+npm install put them. Ask opencode where that cache is instead of assuming,
+because where it lives differs by platform:
+
+```bash
+opencode debug paths
+```
+
+It prints the directories opencode is using on this machine — config, data, log
+and the rest. Find the **cache** line and append
+`/packages/<specifier>/node_modules/` to the path it reports. On Linux with no
+`XDG_CACHE_HOME` set, that comes out as, for example:
+
+```
+~/.cache/opencode/packages/@lawaty/lacode@latest/node_modules/
+```
+
+**That last line is an illustration of one platform's layout, not a path to
+copy.** Where the same cache root sits on another operating system is not
+something this document should guess at — read it from `opencode debug paths`
+and use what it prints.
+
+To inspect what a specifier actually resolved to, list its directory under that
+cache root. An **empty** directory with no `node_modules` inside it means the
+install failed — almost always an unpublished or misspelled package — and
+opencode starts normally **without** the plugin. A **populated** directory there
+means the install succeeded and tells you nothing at all about whether the
+plugin was loaded; that is the next section, and telling those two apart is the
+whole reason for reading it.
+
+
+## If the agents are missing
+
+A plugin that fails to load is silent: opencode starts normally, prints nothing,
+logs nothing, and the agents are simply not there. Work down this. Every step
+below is written to hold whichever opencode version you are running — none of
+them depends on knowing the answer in advance.
+
+**1 — Write the bare specifier and restart.**
+
+```json
+{ "plugin": ["@lawaty/lacode"] }
+```
+
+Nothing here hot-reloads, so the restart is part of the step, not a footnote.
+
+**2 — Check whether the plugin loaded.**
+
+```bash
+opencode agent list | grep -E '^(explore|implement|context)'
+```
+
+A working install prints `explore`, `implement` and `context`, each with the
+hidden `-1`..`-4` pool variants alongside. If the
+grep returns nothing and the list holds only opencode's own built-ins, the plugin
+did not load. Run it in the same shell environment opencode runs in — an
+`agent list` under a different `HOME` or `XDG_CONFIG_HOME` tests a different
+machine. **If the agents are listed, stop here: the one line above is the whole
+install**, and nothing further in this section applies to you.
+
+**3 — Decide which failure you are looking at.** Inspect the package directory
+under the cache root from
+[Where it is installed](#where-it-is-installed), and also check that `plugin`
+really is in the config file opencode reads.
+
+- **Empty** (no `node_modules` inside): the install failed — check the package
+  name, and that it is published. There is nothing to load yet.
+- **Populated**: the install worked and the loader dropped the plugin. Go to
+  step 4. These two look identical from the outside, which is why this step
+  exists.
+
+**4 — If the install worked and the agents are still missing, point the loader
+at the built file.** Add a second entry; leave the bare name in place:
+
+```json
+{
+  "plugin": [
+    "@lawaty/lacode",
+    "file:///ABSOLUTE-PATH-FROM-debug-paths/packages/@lawaty/lacode@latest/node_modules/@lawaty/lacode/dist/index.js"
+  ]
+}
+```
+
+`ABSOLUTE-PATH-FROM-debug-paths` is a placeholder to be replaced, not a
+directory: take the cache path `opencode debug paths` reports for **your**
+machine and put it in front of `/packages/…`. It must be an absolute path with
+`$HOME` already expanded and no `~` left in it. Re-derive it after a cache wipe
+or a reinstall — the directory is keyed by specifier, so it moves when the
+version does.
+
+Why keep both entries instead of swapping the bare name out:
+
+- The bare name is what makes opencode install the package into its cache, and
+  therefore what creates the path the `file://` entry points at.
+- The `file://` entry is what actually loads the plugin.
+- They **cannot double-inject** on opencode 1.18.35, where the bare name
+  contributes nothing at all: the pair loads the plugin exactly once. On any
+  other version this is untested, which is precisely why step 4 is something you
+  take *because* step 2 showed the agents missing, and never on the expectation
+  that it would help.
+
+**5 — Restart, and expect two restarts after a cache wipe.** The first start
+installs the package and creates the path the `file://` entry points at, but a
+path that does not exist at startup is a path that cannot be loaded in that same
+run. The second start finds it and loads the plugin. After that it is steady
+state.
+
+This package also publishes `main` and an `exports["./server"]` entry pointing at
+the same built file, because those are two of the shapes a plugin loader
+resolving an entry point consults. They are forward-compatibility metadata and
+they cost nothing — but they do **not** fix this on 1.18.35: adding either one to
+the *installed* cache copy was tested there and the bare specifier still loaded
+nothing. No other version has been observed where they help either. Use the
+`file://` entry.
+
+
+## Which opencode versions this is known on
+
+Exactly one version has been measured, and the procedure above is deliberately
+not built around that fact. Treat this table as the evidence it is, which is one
+row wide.
+
+| opencode version | bare spec loads? | `file://` needed? | evidence |
+| --- | --- | --- | --- |
+| 1.18.35 | No — installs the package, then silently drops it | Yes | **Verified** on 1.18.35: a populated cache directory, zero agents injected, no error and no log line; the `file://` entry loads the full agent set. |
+| Any other version | **Unknown** | **Unknown** | **Untested.** No other opencode version has been run against this package in either direction. |
+
+Every command quoted on this page was run against 1.18.35. **If your version is
+not the one measured here, follow the procedure above rather than reading this
+table as coverage of your build**: each step stands on its own, and step 2 tells
+you which situation you are in before any version-specific advice is relevant.
+
+
+## macOS
+
+The plugin runs on macOS. It is plain JavaScript with no native dependency, and
+what the package publishes is the built JavaScript rather than TypeScript
+sources, so nothing about loading it is Linux-only. Use the procedure above
+unchanged.
+
+Three things differ, and all three are worth reading rather than assuming:
+
+- **Paths.** Do not copy a cache path out of this document — the example under
+  [Where it is installed](#where-it-is-installed) is one platform's layout. Run
+  `opencode debug paths` and build the `file://` entry from what it reports.
+  This page deliberately does not name a macOS cache root: where opencode keeps
+  it on a Mac has not been established here, and a plausible-looking guess is
+  worse than an instruction to look.
+- **Notifications** are delivered through `osascript`, or through
+  `terminal-notifier` when `osascript` is not installed, rather than through the
+  Linux `notify-send` (US-26). `lacode doctor` reports which channel your machine
+  would actually use.
+- **The repository's shell scripts are Linux-only by design**, and are not in the
+  published package. They drive one person's SSH topology, so each is on the side
+  it belongs to:
+
+- **Remote hosts are plain npm clients.** A remote host installs the plugin the
+  same way (`opencode plugin @lawaty/lacode -g`); there is nothing to rsync. The
+  notification hop is a direct ssh (`ControlMaster` + `ControlPersist`) set up
+  once with `lacode tunnel setup` — no reverse forward, no listening port, no
+  systemd unit. See [Remote hosts](../README.md#remote-hosts) and docs/TUNNEL.md.
+- The repo still carries the author's personal, Linux-only tooling from the older
+  reverse-forward setup (`bin/oc`, `bin/oc-notify`, `bin/oc-notify-receiver`,
+  `bin/oc-sync`). None of it is in the published package, and none of it is needed
+  for the npm-client path above.
+
+**The test suite runs on macOS.** It is written to pass on a Mac as well as on
+Linux, so "it works on a Mac" is a supported claim rather than an intention. The
+few checks that exercise the Linux-only shell scripts above skip themselves on a
+machine that cannot run them, naming the reason — a bash 3.2 with no `mapfile`,
+or no GNU `timeout` — rather than passing silently or failing confusingly.
+
+
+## The `lacode` CLI
+
+The package also ships the `lacode` CLI (`notify`, `forward`, `doctor`, `receive`, `tunnel setup`) — see
+[Remote hosts](../README.md#remote-hosts). The plugin install does **not** put it on your
+`PATH`; run it from the package's `node_modules/.bin`, or install just the CLI
+globally with `npm i -g @lawaty/lacode` if you want the bare command. (That
+global install is for the command only — it is still never what makes the plugin
+load.)
+
+
+## What the install gives you
+
+Two things are worth knowing about what npm actually hands you:
+
+- **`@opencode-ai/plugin` is a peer dependency.** It is not vendored into this
+  package and never will be: a second copy of the SDK inside the tarball would
+  mean opencode and the plugin holding two different module instances, and
+  instance identity is what plugin state hangs on. npm installs the peer for you;
+  if you install with a tool that does not, install `@opencode-ai/plugin` at the
+  same version yourself.
+- **You get compiled JavaScript, not TypeScript sources.** The tarball ships
+  `dist/`, built from `src/` at pack time (`prepack` runs the build, so a stale
+  `dist/` cannot be published). This is not a preference: node strips types
+  natively from 22.18 but **refuses to for files under `node_modules`**, so a
+  package that shipped `.ts` worked fine in a checkout and failed on install —
+  `lacode --help` died with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. A
+  published package cannot depend on its consumer's loader being lenient.

package/docs/OMNIROUTE.md

@@ -0,0 +1,232 @@
+# OmniRoute gateway integration
+
+[OmniRoute](https://github.com/diegosouzapw/OmniRoute) is a local OpenAI-compatible gateway that routes a request across many providers with fallback and "combos". LaCode can register it as an opencode provider. It is **off by default**. The summary is in the [README](../README.md#configure); this page is the full reference, including a latency-measured combo that is worth applying on a new client.
+
+## 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.
+
+**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": [] } }]`
+   `auto` is the zero-config default, but on a free tier it often resolves to a
+   slow chain. [A tested fast combo](#a-tested-fast-combo-free-mix) below is
+   ordered for latency and is worth applying on a new client.
+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": [
+    ["@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 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
+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): 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](USER-STORIES.md) US-28.
+
+
+## A tested fast combo: `free-mix`
+
+`combo: "auto"` is the zero-configuration default, but `auto` inherits whatever
+the gateway chooses, and on a busy free tier that is frequently the slowest
+chain available. The combo below was **measured** against a live free-tier
+gateway and is ordered for latency rather than for breadth. Apply it during the
+"Setting it up on a client machine" steps above and pooled work is usable
+straight away, instead of starting from a gateway that queues for half a minute
+per call.
+
+```jsonc
+{
+  "name": "free-mix",
+  // Order decides. Do NOT use "weighted" here — weights let the gateway
+  // re-shuffle a model that is returning 429 into first position again.
+  "strategy": "priority",
+  "models": [
+    { "model": "gemini/gemini-3.1-flash-lite",                      "providerId": "gemini" },
+    { "model": "gemini/gemini-3.8-flash",                           "providerId": "gemini" },
+    { "model": "gemini/gemini-3.7-flash",                           "providerId": "gemini" },
+    { "model": "gemini/gemini-3-flash-preview",                     "providerId": "gemini" },
+    { "model": "openrouter/nvidia/nemotron-3-super-120b-a12b:free",  "providerId": "openrouter" },
+    { "model": "openrouter/nvidia/nemotron-3-ultra-550b-a55b:free",  "providerId": "openrouter" },
+    { "model": "openrouter/nvidia/nemotron-3.5-lightning:free",     "providerId": "openrouter" },
+    { "model": "openrouter/cohere/north-mini-code:free",            "providerId": "openrouter" },
+    { "model": "openrouter/poolside/laguna-s-2.1:free",             "providerId": "openrouter" },
+    { "model": "openrouter/dots-studio/dots-3-note-preview:free",   "providerId": "openrouter" }
+  ]
+}
+```
+
+Why this order, from 859 calls over a single day against that gateway:
+
+| Model | Observed behaviour | Position |
+| --- | --- | --- |
+| `gemini/gemini-3.1-flash-lite` | **165/172 succeeded (96%)**, ~4.5s median | **first** |
+| `gemini-3.8-flash` / `3.7-flash` / `3-flash-preview` | succeed intermittently, but **burn exactly 30.0s** on a `503` queue-budget timeout when they do not | next |
+| `openrouter/*:free` | **~90% `429`**, but fails *fast* (~1.8s) and occasionally succeeds | last, as a cheap final fallback |
+| `gemini-2.5-flash`, `gemini-2.5-flash-lite` | **`404` on every attempt** — dead ids | **omitted entirely** |
+
+The ordering matters because a combo pays for *every* step it walks past. Put the
+96%-success model first and the common case is a single hop; the 30s models sit
+behind it where they cost nothing, and the 429s sit last where they give up in
+under two seconds.
+
+Measured on the same gateway, same day, `max_tokens: 10`:
+
+| | Before | After |
+| --- | --- | --- |
+| `free-mix` response | 42.7s / 41.8s / 34.7s | 4.1s / 3.1s / 3.2s / 4.0s / 3.2s |
+| Median | **~41.8s** | **~3.2s** |
+| Provider time burned on calls >25s | **56.9 of 102.4 min (56%)** | — |
+
+Before the change, the real call sequence was a `429` after 2.7s, then a `503`
+after 30.0s, then the actual work in 5.7s — roughly **33 seconds of dead time in
+front of every successful request**, and a p90 of 100s when three 30s steps
+chained.
+
+These free-tier endpoints change availability constantly, so treat the ordering
+as a **starting point to re-measure, not a permanent truth**. Re-check it with
+OmniRoute's own call logs before assuming it still holds:
+
+```bash
+# one timed request through the gateway
+curl -o /dev/null -w '%{http_code} %{time_starttransfer}s\n' \
+  -X POST http://localhost:20128/v1/chat/completions \
+  -H "Authorization: Bearer $OMNIROUTE_API_KEY" -H 'Content-Type: application/json' \
+  -d '{"model":"free-mix","messages":[{"role":"user","content":"Say OK"}],"max_tokens":10}'
+
+# per-model status + duration, straight from OmniRoute's logs
+python3 - <<'PY'
+import json, glob, collections
+d = "/home/<user>/.omniroute/call_logs/<YYYY-MM-DD>"
+g = collections.defaultdict(collections.Counter)
+for f in glob.glob(d + "/*.json"):
+    try: s = json.load(open(f))["summary"]
+    except Exception: continue
+    g[s.get("comboStepId")][s.get("status")] += 1
+for k, v in sorted(g.items(), key=lambda x: str(x[0])):
+    print(f"{str(k)[:44]:44} {dict(v)}")
+PY
+```
+
+Apply it with the bundled CLI (`PUT /api/combos/<id>` updates in place, so the
+combo is never briefly missing):
+
+```bash
+omniroute api combos get-api-combos-id- --id <combo-id> --json > free-mix.json
+# edit name/strategy/models in free-mix.json, then:
+omniroute api combos put-api-combos-id- --id <combo-id> --body @free-mix.json
+```
+
+**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; `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 set it as `combo` — `combo` is registered whether or not the gateway advertises it, so a valid gateway route works there too. 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 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,7 @@
     "presets",
     "sounds",
     "LICENSE",
+    "CHANGELOG.md",
     "README.md",
     "docs"
   ],