@lawaty/lacode 0.4.0 → 0.4.2

package/dist/lacode.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // bin/lacode
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { spawnSync as spawnSync3 } from "node:child_process";
 
 // src/tunnel/index.ts
 import { spawn, spawnSync } from "node:child_process";
@@ -279,9 +279,17 @@ function compareSemver(a, b) {
   }
   return 0;
 }
-function readInstalledVersion(packageRoot) {
+function readInstalledVersion(packageRoot, read = (path) => {
+  try {
+    return readFileSync2(path, "utf8");
+  } catch {
+    return void 0;
+  }
+}) {
   try {
-    const manifest = JSON.parse(readFileSync2(join3(packageRoot, "package.json"), "utf8"));
+    const raw = read(join3(packageRoot, "package.json"));
+    if (raw === void 0) return void 0;
+    const manifest = JSON.parse(raw);
     if (manifest.name !== PACKAGE_NAME) return void 0;
     return typeof manifest.version === "string" ? manifest.version : void 0;
   } catch {
@@ -395,16 +403,229 @@ async function refreshCache(opts) {
   };
 }
 
+// src/lib/version.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync, statSync as statSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { isAbsolute, join as join4, relative, sep } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/lib/jsonc.ts
+var stripJsonc = (raw) => {
+  let out = "";
+  let i = 0;
+  while (i < raw.length) {
+    const ch = raw[i];
+    if (ch === '"') {
+      out += ch;
+      i++;
+      while (i < raw.length) {
+        out += raw[i];
+        if (raw[i] === "\\") {
+          out += raw[i + 1] ?? "";
+          i += 2;
+          continue;
+        }
+        if (raw[i] === '"') {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && raw[i + 1] === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && raw[i + 1] === "*") {
+      i += 2;
+      while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+};
+var parseJsonc = (raw) => {
+  try {
+    return JSON.parse(stripJsonc(raw));
+  } catch {
+    return void 0;
+  }
+};
+
+// src/lib/version.ts
+var nodeStat = (path) => {
+  try {
+    return statSync2(path).mtimeMs;
+  } catch {
+    return void 0;
+  }
+};
+var nodeExists = (path) => existsSync2(path);
+var nodeRead = (path) => {
+  try {
+    return readFileSync3(path, "utf8");
+  } catch {
+    return void 0;
+  }
+};
+var realGit = (root) => (args) => {
+  try {
+    const result = spawnSync2("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5e3 });
+    if (result.status !== 0) return void 0;
+    return (result.stdout ?? "").trim();
+  } catch {
+    return void 0;
+  }
+};
+var walkSources = (root) => {
+  const found = [];
+  const stack = [join4(root, "src")];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let names;
+    try {
+      names = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const full = join4(dir, name);
+      if (name.endsWith(".ts")) found.push(full);
+      else if (name === "plugins" || name === "lib" || name === "tunnel") stack.push(full);
+    }
+  }
+  return found;
+};
+var checkDist = (root, deps) => {
+  if (!deps.exists(join4(root, "dist"))) return { dist: "unknown" };
+  const built = deps.stat(join4(root, "dist", "index.js"));
+  if (built === void 0) return { dist: "unknown" };
+  const sources = deps.listSources(root).map((file) => ({ file, mtime: deps.stat(file) }));
+  const newer = sources.filter((s) => s.mtime !== void 0 && s.mtime > built).map((s) => relative(root, s.file));
+  if (newer.length > 0) return { dist: "stale", stale: newer };
+  return { dist: "current" };
+};
+var readPluginEntries = (raw) => {
+  const parsed = parseJsonc(raw);
+  const list = parsed?.plugin;
+  if (!Array.isArray(list)) return void 0;
+  const entries = [];
+  for (const item of list) {
+    if (typeof item === "string") entries.push({ specifier: item });
+    else if (Array.isArray(item) && typeof item[0] === "string") {
+      entries.push({ specifier: item[0], options: item[1] ?? void 0 });
+    }
+  }
+  return entries;
+};
+var isInside = (child, parent) => {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
+var resolvesHere = (specifier, packageRoot) => {
+  if (specifier === PACKAGE_NAME) {
+    return packageRoot.split(sep).includes("node_modules");
+  }
+  if (specifier.startsWith("file://")) {
+    try {
+      const path = fileURLToPath2(specifier);
+      return isInside(path, packageRoot) || isInside(packageRoot, path);
+    } catch {
+      return false;
+    }
+  }
+  if (specifier.startsWith(".")) return resolvesHere(new URL(specifier, `file://${packageRoot}/`).href, packageRoot);
+  return false;
+};
+function readVersionReport(deps = {}) {
+  const packageRoot = deps.packageRoot ?? PACKAGE_ROOT;
+  const home = deps.home ?? homedir3();
+  const git = deps.git ?? realGit(packageRoot);
+  const readFile = deps.readFile ?? nodeRead;
+  const stat = deps.stat ?? nodeStat;
+  const exists = deps.exists ?? nodeExists;
+  const listSources = deps.listSources ?? walkSources;
+  const isCheckout = exists(join4(packageRoot, ".git"));
+  const report = {
+    version: readInstalledVersion(packageRoot, readFile),
+    root: packageRoot,
+    source: isCheckout ? "checkout" : "installed"
+  };
+  if (isCheckout) {
+    report.commit = git(["rev-parse", "--short", "HEAD"]) || "(unknown)";
+    report.dirty = (git(["status", "--porcelain"]) ?? "").length > 0;
+  }
+  const dist = checkDist(packageRoot, { stat, exists, listSources });
+  report.dist = dist.dist;
+  if (dist.stale) report.staleSources = dist.stale;
+  const configPath = [join4(home, ".config", "opencode", "opencode.jsonc"), join4(home, ".config", "opencode", "opencode.json")].find(
+    (candidate) => exists(candidate)
+  );
+  if (!configPath) {
+    report.note = `No opencode config found under ${join4(home, ".config", "opencode")}; nothing to compare this copy against.`;
+    return report;
+  }
+  report.configPath = configPath;
+  const entries = readPluginEntries(readFile(configPath) ?? "");
+  if (!entries) {
+    report.note = `${configPath} has no readable \`plugin\` array.`;
+    return report;
+  }
+  report.loaded = entries.map((e) => e.specifier);
+  const lacodeEntries = entries.filter((e) => e.specifier.includes("lacode"));
+  const ours = lacodeEntries.filter((e) => resolvesHere(e.specifier, packageRoot));
+  if (lacodeEntries.length === 0) {
+    report.servedByThisCopy = false;
+    report.note = `${configPath} loads no LaCode plugin entry.`;
+    return report;
+  }
+  if (ours.length > 0) {
+    report.servedByThisCopy = ours.length === lacodeEntries.length;
+    if (!report.servedByThisCopy) {
+      report.note = `${configPath} loads LaCode from more than one place; only some entries resolve to this copy.`;
+    }
+    return report;
+  }
+  report.servedByThisCopy = false;
+  report.note = `opencode loads LaCode from ${lacodeEntries.map((e) => e.specifier).join(", ")} \u2014 NOT this copy at ${packageRoot}. The version above is this CLI, not necessarily what opencode runs.`;
+  return report;
+}
+var formatVersion = (report) => {
+  const lines = [
+    ["version", report.version ?? "(unknown)"],
+    ["root", report.root],
+    ["source", report.source]
+  ];
+  if (report.commit) {
+    lines.push(["commit", `${report.commit}${report.dirty ? " (dirty)" : ""}`]);
+  }
+  if (report.dist) {
+    const stale = report.staleSources?.length ? ` \u2014 ${report.staleSources.length} source file(s) newer than dist/index.js` : "";
+    lines.push(["dist", `${report.dist}${stale}`]);
+  }
+  if (report.configPath) lines.push(["config", report.configPath]);
+  if (report.loaded?.length) lines.push(["plugin", report.loaded.join(", ")]);
+  if (report.servedByThisCopy !== void 0) {
+    lines.push(["this copy", report.servedByThisCopy ? "yes \u2014 opencode loads this copy" : "NO \u2014 see note"]);
+  }
+  return lines.map(([key, value]) => `${key.padEnd(10)} ${String(value)}`).join("\n");
+};
+
 // bin/lacode
 if (!process.features?.typescript) {
   if (process.env.LACODE_STRIP_TYPECHECKED === "1") {
     console.error("lacode: this node cannot load TypeScript sources; node >= 22.18 is required.");
     process.exit(1);
   }
-  const { spawnSync: spawnSync3 } = await import("node:child_process");
-  const result = spawnSync3(
+  const { spawnSync: spawnSync4 } = await import("node:child_process");
+  const result = spawnSync4(
     process.execPath,
-    ["--experimental-strip-types", "--no-warnings", fileURLToPath2(import.meta.url), ...process.argv.slice(2)],
+    ["--experimental-strip-types", "--no-warnings", fileURLToPath3(import.meta.url), ...process.argv.slice(2)],
     { stdio: "inherit", env: { ...process.env, LACODE_STRIP_TYPECHECKED: "1" } }
   );
   process.exit(result.status ?? 1);
@@ -425,6 +646,15 @@ var USAGE = `lacode \u2014 portable notifications and remote exec for LaCode
   lacode doctor
       Print what the environment resolves to. Diagnostics only.
 
+  lacode version
+      Report WHICH LaCode is speaking and WHICH one opencode actually loads.
+      Version, source (checkout or install), the commit it was built from,
+      and whether dist/ is behind src/ after a git pull. Compares itself
+      against the plugin array in your opencode config, because a config may
+      load the plugin by absolute path and report a version you did not ask
+      about. Never reaches the network; \`lacode update --check\` is what asks
+      npm whether something newer exists.
+
   lacode update [--check]
       Bring this machine's installed LaCode up to the latest published
       version. opencode's plugin cache never re-resolves on its own, so
@@ -485,6 +715,18 @@ switch (command) {
     process.exit(0);
     break;
   }
+  case "version": {
+    const report = readVersionReport();
+    console.log(formatVersion(report));
+    if (report.note) console.log(`
+${report.note}`);
+    if (report.dist === "stale") {
+      console.log("\nRebuild before trusting the rest of this report: npm run build");
+      for (const file of report.staleSources ?? []) console.log(`  newer than dist: ${file}`);
+    }
+    process.exit(0);
+    break;
+  }
   case "update": {
     const checkOnly = argv.includes("--check");
     const check = await checkForUpdate({ packageRoot: PACKAGE_ROOT });
@@ -534,15 +776,15 @@ switch (command) {
     }
     const { user, host, key } = resolveTunnel();
     const pub = `${key}.pub`;
-    if (!existsSync2(key)) {
-      const gen = spawnSync2("ssh-keygen", ["-t", "ed25519", "-N", "", "-C", "lacode-notify", "-f", key], { stdio: ["ignore", "ignore", "inherit"] });
+    if (!existsSync3(key)) {
+      const gen = spawnSync3("ssh-keygen", ["-t", "ed25519", "-N", "", "-C", "lacode-notify", "-f", key], { stdio: ["ignore", "ignore", "inherit"] });
       if (gen.status !== 0) {
         console.error("lacode tunnel setup: ssh-keygen failed; create the key by hand and re-run.");
         process.exit(1);
       }
       console.log(`Generated ${key}`);
     }
-    const pubkey = existsSync2(pub) ? readFileSync3(pub, "utf8").trim() : "(public key missing)";
+    const pubkey = existsSync3(pub) ? readFileSync4(pub, "utf8").trim() : "(public key missing)";
     const self = process.argv[1] ?? "lacode";
     console.log("\nOn the REMOTE host (where opencode runs), export:");
     console.log(`  OC_LOCAL_USER=${user || "<desktop-user>"}`);

package/dist/pool.js

@@ -30,6 +30,7 @@ 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;
@@ -203,6 +204,8 @@ var LIMIT_PATTERNS = [
 ];
 var isLimitText = (text) => LIMIT_PATTERNS.some((re) => re.test(text));
 var isUnavailableText = (text) => UNAVAILABLE_PATTERN.test(text);
+var TRANSIENT_GATEWAY_PATTERNS = [/queue budget/i, /exceeded queue/i, /aborted due to timeout/i, /timeout/i];
+var isTransientGatewayText = (text) => TRANSIENT_GATEWAY_PATTERNS.some((re) => re.test(text));
 var statedCooldown = (text) => {
   const hm = /resets?\s+in\s+(\d+)\s*(?:h|hr|hour)s?\s*(\d+)?\s*(?:m|min|minute)?s?/i.exec(text);
   if (hm) return (Number(hm[1]) * 60 + (hm[2] ? Number(hm[2]) : 0)) * 60 * 1e3;
@@ -291,7 +294,7 @@ function publish(s) {
   if (!s.dirReady) return;
   const now = Date.now();
   const payload = {};
-  for (const [key, claim] of s.own) if (now - claim.t <= CLAIM_TTL_MS) payload[key] = claim;
+  for (const [key, claim] of s.own) if (now - (claim.hb ?? claim.t) <= CLAIM_TTL_MS) payload[key] = claim;
   try {
     writeFileSync(join2(s.dir, `${selfFile(s.id)}.tmp`), JSON.stringify(payload));
     renameSync(join2(s.dir, `${selfFile(s.id)}.tmp`), join2(s.dir, selfFile(s.id)));
@@ -510,6 +513,11 @@ function pickSlot(s, snap, options) {
 function agentFor(base, slot) {
   return `${base}-${slot}`;
 }
+function manualVariant(name) {
+  const direct = /^(.*)-([1-9][0-9]*)$/.exec(name);
+  if (!direct) return void 0;
+  return BASES.includes(direct[1]) ? direct[1] : void 0;
+}
 function acquire(s, base, slot, ownerSession, key, target) {
   const now = Date.now();
   s.own.set(key, { v: base, k: slot.index, m: slot.model, t: now, hb: now, s: ownerSession, g: target });
@@ -567,12 +575,17 @@ function idleFor(s, claim, now) {
   const seen = s.activity.get(target);
   return seen ? now - seen : Infinity;
 }
+function condemnReason(s, claim, now = Date.now()) {
+  const age = now - claim.t;
+  if (age > MAX_CLAIM_AGE_MS) return "overran";
+  if (age > STUCK_MIN_AGE_MS && idleFor(s, claim, now) >= STUCK_IDLE_MS) return "hung";
+  return void 0;
+}
 function findStuck(s, now = Date.now()) {
   const stuck = [];
   for (const [key, claim] of s.own) {
-    if (now - claim.t <= STUCK_MIN_AGE_MS) continue;
-    if (idleFor(s, claim, now) < STUCK_IDLE_MS) continue;
-    stuck.push({ key, claim });
+    const reason = condemnReason(s, claim, now);
+    if (reason) stuck.push({ key, claim, reason });
   }
   return stuck;
 }
@@ -608,6 +621,7 @@ export {
   DEFAULT_PRESET,
   FALLBACK_SLOTS,
   HANG_COOLDOWN_MS,
+  MAX_CLAIM_AGE_MS,
   MAX_SLOTS,
   MAX_WEIGHT,
   ORPHAN_TMP_MS,
@@ -626,6 +640,7 @@ export {
   backfillChild,
   bindChild,
   claimKey,
+  condemnReason,
   coolProvider,
   coolUnavailable,
   ensureSlots,
@@ -636,7 +651,9 @@ export {
   isAvailable,
   isLimitText,
   isQuotaReason,
+  isTransientGatewayText,
   isUnavailableText,
+  manualVariant,
   noteActivity,
   parseSlotText,
   parseSlots,

package/docs/CONFIGURATION.md

@@ -0,0 +1,111 @@
+# Configuration reference
+
+The plugin options, where the model pool gets its slots, and exactly what LaCode writes into your config. The short version is in the [README](../README.md#configure).
+
+## Pool preset resolution
+
+The slot list is the first of these that yields usable slots:
+
+1. plugin options — `models` in the [tuple](../README.md#configure)
+2. `~/.config/lacode/pool.json` (its parent directory is created for you)
+3. the bundled `presets/free-tier.json`
+4. a built-in fallback, so routing always works
+
+A missing, unreadable or structurally broken source falls through to the next and
+logs one warning; nothing here throws into opencode. Nothing hot-reloads —
+change a preset, then restart every opencode process.
+
+**Any model list is accepted, including paid ones** (US-7). There is no free-tier
+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.
+
+
+## Which models run which agent
+
+Only the **pool** writes a model onto a pooled agent, from whichever source wins
+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.
+
+
+## ⚠️ 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 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`: 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`,
+`temperature`, `mode` and `hidden` are all read after the plugin hook runs.
+
+**So if you use a global `"tools"` block, declare the grants yourself:**
+
+```jsonc
+{
+  "tools": { "playwright_*": false },
+  "agent": {
+    "explore": { "tools": { "playwright_*": true } },
+    "implement": { "tools": { "playwright_*": true } }
+  }
+}
+```
+
+The hidden pool variants (`explore-1`, `implement-2`, …) inherit
+nothing here — add a line per variant, or drop the global
+deny and scope it to the agents that should not have browser access instead.
+Note that you cannot *spawn* a variant by name: the pool refuses
+`explore-1` and friends and points you at the bare base, so per-variant
+permissions only ever apply to a spawn the plugin routed itself.
+
+Nothing hot-reloads: after editing your config, restart every running opencode
+process.
+
+
+## What gets injected
+
+**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
+two keys are already taken and merge-without-clobber keeps the built-in — the
+LaCode definitions of `build` and `plan` are what you get if you remove the
+built-ins of those names first.
+
+**Five keys are deliberately not injected.** `basic` is a byte-for-byte
+duplicate of `plan` apart from a pinned model, and `plan` is injected instead.
+`expert` pins a specific model and carries a personal benchmark note in its
+description — a package cannot ship someone else's provider, quota or benchmark
+results — though its escalation ladder still resolves, because the two deep
+tiers it escalates to *are* injected. And `explore`, `general` and `implement`
+are only `{ "disable": true }` stubs in the author's own config: turning off
+opencode's built-in agents is a decision about one person's configuration, not
+a default a package should impose on a stranger.
+
+One **field** is deliberately not injected either: `tools`, for the
+load-time-folding reason explained above. Nothing else the plugin writes into
+an agent is subject to it.
+
+**Installation merges, it does not clobber** (US-16). An agent, command or
+instruction is added only when that key is absent from your config. A
+user-defined agent of the same name is left byte-identical — not patched, not
+partially merged. Skips are counted and logged once.
+
+**`enabled: false` turns all of it off** (US-17). No pool model rewriting, no
+agent injection, no command injection, no reaper timer armed, no
+`~/.config/lacode` directory created.
+
+These three are specified in [docs/USER-STORIES.md](USER-STORIES.md) as
+US-7, US-16 and US-17, and each has tests.