@lawaty/lacode 0.1.0 → 0.1.2

package/README.md

@@ -39,6 +39,12 @@ directory to create. Do not run `npm i -g @lawaty/lacode`: a global npm install
 is never consulted by opencode, so it changes nothing about whether the plugin
 loads.
 
+It is also the form to keep as your default: if your opencode does not load the
+bare specifier, add to this line rather than replacing it. The
+[procedure below](#if-the-agents-are-missing) says when that is, and
+[which versions this is known on](#which-opencode-versions-this-is-known-on)
+says what is actually verified.
+
 To install it explicitly instead — or to install it once for every project on
 the machine rather than per config — use the CLI, which does the same thing:
 
@@ -53,37 +59,177 @@ agent set will look stale for no visible reason.
 
 ### 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:
+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:
 
 ```
-$XDG_CACHE_HOME/opencode/packages/<specifier>/node_modules/
-# ~/.cache/opencode/packages/@lawaty/lacode@latest/node_modules/ by default
+~/.cache/opencode/packages/@lawaty/lacode@latest/node_modules/
 ```
 
-`$XDG_CACHE_HOME` defaults to `~/.cache`; set it if you keep a cache elsewhere.
-To inspect what a specifier actually resolved to, list its directory under
-`~/.cache/opencode/packages/`. 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.
+**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.
 
-### Verifying the install
+### If the agents are missing
 
-A plugin that fails to install is silent: there is no error, opencode starts,
-and it simply does not have the agents. Check for them:
+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-fast|implement-fast|explore-deep|implement-deep)'
+opencode agent list | grep -E '^(explore|implement|context)'
 ```
 
-A working install prints `explore-fast`, `implement-fast`, `explore-deep` and
-`implement-deep`, each with the hidden `-1`..`-4` pool variants alongside. If the
-grep returns nothing but opencode's built-ins, the plugin did not load: check the
-cache directory above, and check that `plugin` is in the config file opencode
-actually reads. Run this in the same shell environment opencode runs in — an
+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.
+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:
+
+  | Script | Runs on | Why it is Linux-only |
+  | --- | --- | --- |
+  | `bin/oc`, `bin/oc-notify` | the **remote host** that runs opencode | Server-side. They are pushed to `~/bin/` on each host by `bin/oc-sync` and notify *your desktop* over the tunnel. |
+  | `bin/oc-notify-receiver` | your **desktop** | Delivers through `notify-send` (libnotify), and the persistent forward that reaches it is a systemd user unit. |
+  | `bin/oc-sync` | your **desktop** | Installs those systemd user units and runs `loginctl enable-linger`. |
+
+  None of this is a limitation of the package: a macOS client installs the plugin
+  and uses the `lacode` CLI, and both are portable. The scripts above are the
+  author's personal remote-tunnel tooling. `bin/oc-sync` refuses to run where it
+  cannot work and says which `lacode` subcommand to use instead, rather than
+  failing somewhere less obvious.
+
+**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
 
@@ -138,7 +284,6 @@ option is optional:
 | `enabled` | `true` | The single off switch. `false` injects nothing at all and does no writes. |
 | `models` | — | An inline slot list. Highest-priority source. |
 | `modelsFile` | — | An explicit slot file; short-circuits the chain below. |
-| `deepModel` | — | A `provider/model-id` pinned onto `explore-deep` and `implement-deep`. |
 | `reapMs` | `30000` | Hang-reaper interval. |
 
 ### Pool preset resolution
@@ -162,46 +307,26 @@ that is a sensible default, not because the pool requires it.
 ### Which models run which agent
 
 Only the **pool** writes a model onto a pooled agent, from whichever source wins
-above. The pooled bases (`explore-fast`, `implement-fast`, `context-manager`)
+above. The pooled bases (`explore`, `implement`, `context`)
 and their hidden `-1`..`-4` variants therefore carry no model of their own: a
 model written next to an agent would be a second source of truth that silently
 wins whenever routing falls through. Spawn a base and let the pool route it.
 
-`explore-deep` and `implement-deep` are **not** pooled — they are the deliberate
-escalation above a pooled tier — so nothing routes them and nothing writes their
-model. Left alone they fall through to your default model, which turns "I am
-stuck, escalate" into an unannounced jump to the most expensive model in your
-setup. Set `deepModel` to pin them:
-
-```jsonc
-"plugin": [["@lawaty/lacode", { "deepModel": "your-provider/your-deep-model" }]]
-```
-
-It is an option and not a literal in the package because which model to escalate
-onto is a property of your providers, not of LaCode. If you keep a `whitelist`
-on that provider, LaCode appends the pinned model to it for you: the whitelist is
-an allowlist, so opencode drops any model a provider offers that it does not
-name, and an unlisted pin would resolve to nothing at all. If you have no
-whitelist there, none is written — an absent one already allows every model. With
-`deepModel` unset, no model is written and the deep tiers use your
-default model — the behaviour of earlier versions.
-
 ### ⚠️ Per-agent tool grants must be in your own config
 
 **LaCode cannot grant tools to its agents, and this is not an oversight you can
 work around by configuring it.** If you keep a global `"tools"` block in your
-config — for example `"tools": { "playwright_*": false }` — then the four
-exploration and implementation tiers (`explore-fast`, `explore-deep`,
-`implement-fast`, `implement-deep`, plus their hidden `-1`..`-4` pool variants)
-lose browser access, and **nothing tells them why**: the tool call is simply
-refused mid-task. `context-manager` gets no grant either, which is correct — it
+config — for example `"tools": { "playwright_*": false }` — then the pooled
+exploration and implementation bases (`explore` and `implement`, plus their
+hidden `-1`..`-4` pool variants) lose browser access, and **nothing tells them why**: the tool call is simply
+refused mid-task. `context` gets no grant either, which is correct — it
 writes the context map and has no business in a browser.
 
 opencode folds an agent's `tools` into its permission list **at config-load
 time**, while decoding the config — before any plugin runs. A plugin's `config`
 hook mutates the already-decoded config, so the fold never re-runs and anything
 it puts in `agent.tools` is inert. (Verified on opencode 1.18.34/1.18.35 with
-`opencode debug agent explore-fast`: a grant written in your own config shows two
+`opencode debug agent explore`: a grant written in your own config shows two
 `playwright_*` entries — `deny` then `allow`, last one winning — while the same
 grant injected by the plugin shows only the `deny`.) LaCode's other injected
 fields are not affected; `permission`, `prompt`, `model`, `description`,
@@ -213,15 +338,13 @@ fields are not affected; `permission`, `prompt`, `model`, `description`,
 {
   "tools": { "playwright_*": false },
   "agent": {
-    "explore-fast": { "tools": { "playwright_*": true } },
-    "explore-deep": { "tools": { "playwright_*": true } },
-    "implement-fast": { "tools": { "playwright_*": true } },
-    "implement-deep": { "tools": { "playwright_*": true } }
+    "explore": { "tools": { "playwright_*": true } },
+    "implement": { "tools": { "playwright_*": true } }
   }
 }
 ```
 
-The hidden pool variants (`explore-fast-1`, `implement-fast-2`, …) inherit
+The hidden pool variants (`explore-1`, `implement-2`, …) inherit
 nothing here — add a line per variant you actually spawn, or drop the global
 deny and scope it to the agents that should not have browser access instead.
 
@@ -230,8 +353,8 @@ process.
 
 ### What gets injected
 
-**19 agent keys**: the 7 bases `build`, `plan`, `explore-fast`, `explore-deep`,
-`implement-fast`, `implement-deep`, `context-manager`, plus one hidden
+**17 agent keys**: the 5 bases `build`, `plan`, `explore`, `implement`,
+`context`, plus one hidden
 `<base>-1`..`-4` pool variant for each of the 3 pooled bases.
 
 `build` and `plan` exist in opencode as built-ins, so on a stock config those
@@ -278,7 +401,7 @@ inventories: it answers "what should I look at first?" and nothing else, which
 is what makes reading it cheaper than the exploration it replaces.
 
 It keeps itself current. When a session that edited code goes idle, LaCode
-starts a `context-manager` run that borrows a slot from the same pool every
+starts a `context` run that borrows a slot from the same pool every
 other subagent uses and updates the map from the changed paths and their
 architectural neighbourhood — defaulting to *no edit*, since a changed file is
 not a changed fact. Only that one agent ever writes the map; everything else
@@ -407,7 +530,8 @@ they call the same `scripts/build.mjs` the tarball does.
 is the guard: it reads the `### US-N:` headings out of `docs/USER-STORIES.md`
 and the `[US-N]` markers out of the test names and fails if they disagree, in
 either direction. **A test that covers a story must have the id at the start of
-its name** — `test("[US-7] a paid model is accepted")` — or CI's guard fails it.
+its name** — `test("[US-7] a paid model is accepted")` — or the coverage guard
+fails it.
 A story with no test is as much a failure as a test naming a story that does not
 exist.