@lawaty/lacode 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -9,8 +9,29 @@ commit as the changelog entry it describes.
 
 ## [Unreleased]
 
+## [0.6.0] — a client-only /pool command, and README corrections
+
+### Added
+
+- **`/pool <instruction>`** — a client-only command that rewrites this machine's
+  pool override, `~/.config/lacode/pool.txt`, from a short instruction. It
+  applies the loader's rules (at most 4 distinct slots, weight in (0, 100], line
+  order is the rotation), writes the WHOLE file rather than a patch, reports the
+  before → after table, and reminds you that nothing hot-reloads.
+
+### Fixed
+
+- README: the count of agent keys deliberately *not* injected was stated as
+  three, not the five `docs/CONFIGURATION.md` lists; and the `lacode` CLI section
+  was missing `version`, `update`, `receive` and `tunnel setup`.
+  `docs/INSTALL.md`'s CLI list gained `version` and `update`. A stale test title
+  ("three commands") was corrected to match what it asserts.
+
 ## [0.5.0] — a user-only /manager-directive, instant limit failover, and the longcat preset
 
+Released on the npm **`beta`** dist-tag (not `latest`) while the project is
+experimental; `latest` remains 0.4.2.
+
 ### Added
 
 - **`/manager-directive <text>`** — a client-only command that runs a hidden
@@ -193,7 +214,8 @@ commit as the changelog entry it describes.
 
 - First published release: pooled subagents over a shared set of models.
 
-[Unreleased]: https://github.com/lawaty/lacode/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/lawaty/lacode/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/lawaty/lacode/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/lawaty/lacode/compare/v0.4.2...v0.5.0
 [0.4.1]: https://github.com/lawaty/lacode/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/lawaty/lacode/compare/v0.3.0...v0.4.0

package/README.md

@@ -2,6 +2,11 @@
 
 > Ultimate opencode setup for Go users
 
+> **Beta — experimental, changing fast.** For the next month LaCode ships on the
+> npm **`beta`** dist-tag rather than `latest`, so nothing pulls it by accident:
+> install `@lawaty/lacode@beta`, or pin an exact version. Interfaces here can
+> change between releases without a major bump while the project stabilises.
+
 LaCode is an opencode plugin. It routes delegated work onto a weighted pool of
 cheap models instead of the expensive one, reaps subagents that hang without
 telling anyone, keeps a maintained map of your repository so agents stop
@@ -178,12 +183,12 @@ only thing that works: naming a variant lets the caller choose the provider
 directly, which is exactly what the rotation and the per-slot ceiling exist to
 prevent, so it is refused.
 
-Five commands: `/context-init`, `/context-update`, `/context-review`,
-`/lacode-doctor` and `/manager-directive`. Everything is added **only when your
-config does not already
+Six commands: `/context-init`, `/context-update`, `/context-review`,
+`/lacode-doctor`, `/manager-directive` and `/pool`. Everything is added **only
+when your config does not already
 define it** — an agent or command you wrote yourself is left byte-identical,
 never patched or partially merged. `{"enabled": false}` turns the whole thing off
-without leaving a trace. The exact injection list, and the three keys that are
+without leaving a trace. The exact injection list, and the five keys that are
 deliberately *not* injected, are in
 [docs/CONFIGURATION.md](docs/CONFIGURATION.md#what-gets-injected).
 
@@ -214,6 +219,7 @@ are reading:
 /context-review    # audit it for staleness, contradictions, duplication and bloat
 /lacode-doctor     # check the pool, model resolution and the OmniRoute gateway. Report only
 /manager-directive # record a managerial direction in manager.md — client-only, see below
+/pool              # rewrite the pool slot table in ~/.config/lacode/pool.txt; restart to apply
 ```
 
 The map is local and untracked — it describes your checkout on your machine, so
@@ -333,6 +339,13 @@ must never be able to fail the process that tried to notify you. `lacode forward
 HOST -- COMMAND` runs a command on another host over ssh and exits with its
 status.
 
+The full CLI is `notify`, `forward`, `doctor`, `version`, `update`, `receive`
+and `tunnel setup`. `version` reports which copy of LaCode is running — and
+whether opencode is loading that same copy — and `update [--check]` refreshes an
+installed one. `receive` is the desktop end of the tunnel (the forced command a
+remote key is restricted to) and `tunnel setup` provisions the key and the
+forward.
+
 Configuration, the payload format, the receiver contract and holding the forward
 open are in [docs/TUNNEL.md](docs/TUNNEL.md).
 

package/dist/commands.js

@@ -1,6 +1,55 @@
 // src/lib/manager-directive.ts
 var MANAGER_AGENT_NAME = "manager";
 
+// src/lib/pool.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/lib/package-root.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "@lawaty/lacode";
+var findPackageRoot = (start) => {
+  let dir = start;
+  for (let up = 0; up < 6; up++) {
+    try {
+      if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name === PACKAGE_NAME) return dir;
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(start, "..", "..");
+};
+var PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+
+// src/lib/pool.ts
+var CLAIM_TTL_MS = 10 * 60 * 1e3;
+var DEAD_FILE_MS = 2 * CLAIM_TTL_MS;
+var ORPHAN_TMP_MS = 60 * 1e3;
+var CATALOG_TTL_MS = 10 * 60 * 1e3;
+var STUCK_MIN_AGE_MS = 5 * 60 * 1e3;
+var STUCK_IDLE_MS = 3 * 60 * 1e3;
+var MAX_CLAIM_AGE_MS = 30 * 60 * 1e3;
+var HANG_COOLDOWN_MS = 10 * 60 * 1e3;
+var UNAVAILABLE_COOLDOWN_MS = 60 * 1e3;
+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 PRESETS_DIR = join2(PACKAGE_ROOT, "presets");
+var DEFAULT_PRESET = join2(PRESETS_DIR, "free-tier.json");
+var USER_CONFIG_DIR = join2(homedir(), ".config", "lacode");
+var USER_MODELS_PATH = join2(USER_CONFIG_DIR, "pool.json");
+var USER_MODELS_TXT = join2(USER_CONFIG_DIR, "pool.txt");
+var CHILD_MEMORY_MS = 30 * 6e4;
+
 // src/commands.ts
 var COMMANDS = {
   "context-init": {
@@ -121,6 +170,36 @@ Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
    whether or not the gateway advertises it, so it needs no allowlist entry.
 
 Change nothing. Print a final one-line summary of failures.`
+  },
+  "pool": {
+    description: "Modify this machine's LaCode pool from a short instruction \u2014 the shared free-model slot table in ~/.config/lacode/pool.txt. Restarts opencode afterwards.",
+    template: `Apply this change to the LaCode pool on this machine:
+
+$ARGUMENTS
+
+The pool is ONE global slot table shared by every pooled base (explore, implement, context) \u2014 there are no per-base model lists, so "put X on explore" means "give X a slot", not a per-base override.
+
+1. Establish the baseline. Read \`${USER_MODELS_TXT}\`. If it is absent, the pool is resolving from the bundled preset \`presets/free-tier.json\`; read that file to learn what is in effect. Call the \`pool_status\` tool only if you need live load or cooldown state.
+
+2. Resolve the instruction above into a target slot table. These are the rules the loader enforces \u2014 never write a file that breaks one:
+   - one slot per line: \`<provider>/<model-id>  [weight]\`
+   - at most ${MAX_SLOTS} slots, and a model may appear only once
+   - weight is optional (default 1) and must be a number in (0, ${MAX_WEIGHT}]. It is the soft ceiling on concurrent claims and the slot's share of the rotation \u2014 NOT a priority; pick order follows line order.
+   - \`#\` starts a comment (whole-line or trailing); blank lines are ignored.
+   If the instruction names a model ambiguously, or would need more than ${MAX_SLOTS} slots, stop and ask rather than guessing.
+
+3. Write the WHOLE file, not a patch. This file is an override, not an edit target: any slot you drop disappears, and slot numbers are line positions, so a partial write silently renumbers the rotation. Keep the existing comment header. If the write fails on a missing directory, create \`~/.config/lacode\` first and retry.
+
+4. Report the before \u2192 after slot table, the resolved path, and this reminder in substance: nothing hot-reloads, so every running opencode process must be restarted before the new pool takes effect.
+
+Two traps that fail silently, so check and state them explicitly:
+- A slot's provider must already exist in the user's opencode config, or that slot cannot resolve at all. If the instruction adds a model on a provider that is not configured, say so.
+- If a slot model is \`omniroute/<id>\`, that id must also appear in the plugin's \`omniroute.models\` allowlist (or be the \`combo\` id, which needs no entry) \u2014 otherwise the pool resolves and every spawn fails with \`ProviderModelNotFoundError\`.
+- A provider \`whitelist\` is an allowlist, and the plugin appends your model to it at config time. Nothing for you to do there.
+
+If the instruction is to RESET or REVERT rather than to change models, delete \`${USER_MODELS_TXT}\` instead, and report that the pool falls back to the bundled preset \u2014 with the same restart reminder.
+
+Change nothing else. In particular do not touch \`presets/free-tier.json\`, \`~/.config/lacode/pool.json\`, \`FALLBACK_SLOTS\` in \`src/lib/pool.ts\`, or \`tests/models-snapshot.json\`: this command owns the per-machine override and nothing else.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {

package/dist/index.js

@@ -1506,6 +1506,36 @@ Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
    whether or not the gateway advertises it, so it needs no allowlist entry.
 
 Change nothing. Print a final one-line summary of failures.`
+  },
+  "pool": {
+    description: "Modify this machine's LaCode pool from a short instruction \u2014 the shared free-model slot table in ~/.config/lacode/pool.txt. Restarts opencode afterwards.",
+    template: `Apply this change to the LaCode pool on this machine:
+
+$ARGUMENTS
+
+The pool is ONE global slot table shared by every pooled base (explore, implement, context) \u2014 there are no per-base model lists, so "put X on explore" means "give X a slot", not a per-base override.
+
+1. Establish the baseline. Read \`${USER_MODELS_TXT}\`. If it is absent, the pool is resolving from the bundled preset \`presets/free-tier.json\`; read that file to learn what is in effect. Call the \`pool_status\` tool only if you need live load or cooldown state.
+
+2. Resolve the instruction above into a target slot table. These are the rules the loader enforces \u2014 never write a file that breaks one:
+   - one slot per line: \`<provider>/<model-id>  [weight]\`
+   - at most ${MAX_SLOTS} slots, and a model may appear only once
+   - weight is optional (default 1) and must be a number in (0, ${MAX_WEIGHT}]. It is the soft ceiling on concurrent claims and the slot's share of the rotation \u2014 NOT a priority; pick order follows line order.
+   - \`#\` starts a comment (whole-line or trailing); blank lines are ignored.
+   If the instruction names a model ambiguously, or would need more than ${MAX_SLOTS} slots, stop and ask rather than guessing.
+
+3. Write the WHOLE file, not a patch. This file is an override, not an edit target: any slot you drop disappears, and slot numbers are line positions, so a partial write silently renumbers the rotation. Keep the existing comment header. If the write fails on a missing directory, create \`~/.config/lacode\` first and retry.
+
+4. Report the before \u2192 after slot table, the resolved path, and this reminder in substance: nothing hot-reloads, so every running opencode process must be restarted before the new pool takes effect.
+
+Two traps that fail silently, so check and state them explicitly:
+- A slot's provider must already exist in the user's opencode config, or that slot cannot resolve at all. If the instruction adds a model on a provider that is not configured, say so.
+- If a slot model is \`omniroute/<id>\`, that id must also appear in the plugin's \`omniroute.models\` allowlist (or be the \`combo\` id, which needs no entry) \u2014 otherwise the pool resolves and every spawn fails with \`ProviderModelNotFoundError\`.
+- A provider \`whitelist\` is an allowlist, and the plugin appends your model to it at config time. Nothing for you to do there.
+
+If the instruction is to RESET or REVERT rather than to change models, delete \`${USER_MODELS_TXT}\` instead, and report that the pool falls back to the bundled preset \u2014 with the same restart reminder.
+
+Change nothing else. In particular do not touch \`presets/free-tier.json\`, \`~/.config/lacode/pool.json\`, \`FALLBACK_SLOTS\` in \`src/lib/pool.ts\`, or \`tests/models-snapshot.json\`: this command owns the per-machine override and nothing else.`
   }
 };
 function applyCommands(cfg, commands = COMMANDS) {

package/docs/INSTALL.md

@@ -182,7 +182,8 @@ 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
+The package also ships the `lacode` CLI (`notify`, `forward`, `doctor`, `version`,
+`update`, `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -60,5 +60,8 @@
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "1.18.34"
+  },
+  "publishConfig": {
+    "tag": "beta"
   }
 }