leos-agent 6.3.0 → 7.0.0

package/adapters/opencode/plugin.js

@@ -1,6 +1,12 @@
-// Leo's OpenCode bridge: registers the skills dir by path (OpenCode names
-// each skill from its own frontmatter, so there is no leo: prefix here as
-// there is on Claude Code and Hermes), injects the
+// Leo's OpenCode bridge: registers a generated shadow copy of the skills
+// tree, with every skill renamed leo-<name>, in place of the source tree
+// (OpenCode's config schema gives skills only `paths` and `urls` — no
+// namespace or prefix knob — verified against
+// https://opencode.ai/config.json, and OpenCode requires a skill's
+// frontmatter `name:` to equal its containing directory name, so the only
+// way to get a leo-<name> identity here is a generated copy living under
+// that name; there is no such constraint on Claude Code or Hermes, which
+// read leo: off their own namespace instead), injects the
 // generated subagent roster from adapters/opencode/agents.json, assembles
 // the using-leo policy plus the OpenCode mapping appendix and hands it to
 // OpenCode through config.instructions (belt) and the
@@ -10,14 +16,19 @@
 // Node builtins only, ESM. No external dependencies. No runtime frontmatter
 // parsing and no env-var tier overrides: agents.json and this policy are
 // both generated by scripts/render_adapters.py from config/models.json, the
-// single source of truth every other harness also reads.
+// single source of truth every other harness also reads. (The shadow-skills
+// frontmatter rewrite below is not an exception to that: it edits one
+// generated-at-runtime `name:` line, not the policy or the roster.)
 //
 // Every read below is wrapped so a missing file degrades to "no
 // skills/agents/policy" rather than breaking session start — same fail-open
-// posture as hooks/session-start.py.
+// posture as hooks/session-start.py. Shadow-skills generation follows suit,
+// but does not register the source tree on failure: bare skills would falsely
+// advertise identities OpenCode cannot provide. It leaves a doctor breadcrumb
+// and starts without Leo skills instead.
 
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { readFile, writeFile, mkdir, readdir, stat, rm, utimes, chmod } from 'node:fs/promises';
+import { appendFileSync, mkdirSync, chmodSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
@@ -32,6 +43,20 @@ function localStateRoot() {
   return process.env.LEOS_AGENT_LOCAL_PATH || path.join(os.homedir(), '.leos-agent-local');
 }
 
+async function ensureLocalStateRoot() {
+  const dir = localStateRoot();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  return dir;
+}
+
+function ensureLocalStateRootSync() {
+  const dir = localStateRoot();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  return dir;
+}
+
 // One OpenCode process serves several project directories at once (its own log
 // shows one run= creating an instance per directory), and ESM caches this
 // module once per process, so nothing below may key off process.cwd() or hold
@@ -54,6 +79,240 @@ function stripFrontmatter(raw) {
   return raw;
 }
 
+// --- Shadow skills tree ----------------------------------------------------
+//
+// OpenCode requires a skill's frontmatter `name:` to equal its directory
+// name and offers no separate namespace, so `leo-<name>` identities can only
+// come from an actual directory called `leo-<name>`. This section builds one
+// generated copy of skills/ per content hash under localStateRoot() and
+// hands its path to config() in place of the source tree.
+//
+// The directory name is the cache key, the same shape as
+// opencode-policy-<sha256[:12]>.md below: a hash over every file's relative
+// path and content, so any change anywhere under skills/ (a new skill, an
+// edited SKILL.md, an edited reference file) yields a new directory rather
+// than silently reusing a stale one — the failure mode that matters most
+// here, since a stale shadow tree fails quietly rather than loudly.
+
+const SHADOW_SKILLS_PREFIX = 'opencode-skills';
+const SHADOW_COMPLETE_MARKER = '.leo-shadow-complete';
+// How long a shadow tree must go untouched before a sweep may delete it.
+// Generous on purpose: the cost of keeping one too long is a few hundred KB
+// of disk, the cost of deleting one too early is pulling the skills directory
+// out from under a running session.
+const STALE_TREE_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Recursively lists every file under `dir`, as paths relative to `dir`, in a
+// sorted, deterministic order — both the hash and the copy below depend on
+// walking every run in the same order regardless of the filesystem's own
+// directory-entry ordering.
+async function walkFiles(dir) {
+  const out = [];
+  async function recurse(sub) {
+    let entries;
+    try {
+      entries = await readdir(path.join(dir, sub), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const rel = sub ? path.join(sub, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        await recurse(rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  }
+  await recurse('');
+  return out.sort();
+}
+
+// A sha256 over every file's relative path and content under skills/ — not
+// mtimes, which lie across a git checkout/clone and would leave the shadow
+// tree pinned to whatever happened to be on disk the first time this ran.
+async function hashSkillsTree(skillsDir, files) {
+  const hash = createHash('sha256');
+  for (const rel of files) {
+    hash.update(rel.split(path.sep).join('/') + '\0');
+    hash.update(await readFile(path.join(skillsDir, rel)));
+  }
+  return hash.digest('hex').slice(0, 12);
+}
+
+// Same 6-line strip as stripFrontmatter, but rewriting rather than removing:
+// finds the `name:` line inside the frontmatter fence and replaces it. Every
+// other line — including the rest of the frontmatter and the whole body —
+// is copied through untouched.
+function rewriteSkillName(raw, newName) {
+  const lines = raw.split('\n');
+  if (!lines.length || lines[0].trim() !== '---') return raw;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') break;
+    if (/^name:\s*/.test(lines[i])) {
+      lines[i] = `name: ${newName}`;
+      return lines.join('\n');
+    }
+  }
+  return raw;
+}
+
+// Copies every file under skills/ into <shadowRoot>/leo-<skill>/..., which
+// preserves subdirectories (skills/using-leo/references/) and sibling files
+// for free since it walks the real tree rather than special-casing SKILL.md.
+// Only each skill's own SKILL.md is rewritten; everything else is copied
+// verbatim, byte for byte.
+async function buildShadowSkillsTree(shadowRoot, skillsDir, files) {
+  for (const rel of files) {
+    const parts = rel.split(path.sep);
+    // A file directly under skills/ (e.g. .gitkeep) belongs to no skill
+    // directory and is not part of what OpenCode reads, so it is hashed
+    // (any change there still invalidates the cache) but not copied.
+    if (parts.length < 2) continue;
+    const skillName = parts[0];
+    const destFile = path.join(shadowRoot, `leo-${skillName}`, ...parts.slice(1));
+    await mkdir(path.dirname(destFile), { recursive: true });
+    if (parts.length === 2 && parts[1] === 'SKILL.md') {
+      const raw = await readFile(path.join(skillsDir, rel), 'utf8');
+      await writeFile(destFile, rewriteSkillName(raw, `leo-${skillName}`), 'utf8');
+    } else {
+      await writeFile(destFile, await readFile(path.join(skillsDir, rel)));
+    }
+  }
+}
+
+// Deletes opencode-skills-* directories that nothing has claimed recently.
+//
+// Never deletes on hash mismatch alone. Two Leo payloads can legitimately
+// share one state root — the repo's own documented dev setup points `plugin`
+// at a working tree beside the installed npm package — and each returns its
+// own tree from config(). An eager sweep would delete the *other* live
+// instance's skills directory out from under it, and an upgrade would do the
+// same to any session already open. Every call touches its own marker, so a
+// tree in use stays young; only one untouched for STALE_TREE_MS is garbage.
+async function cleanupStaleShadowTrees(root, currentHash) {
+  const currentName = `${SHADOW_SKILLS_PREFIX}-${currentHash}`;
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - STALE_TREE_MS;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith(`${SHADOW_SKILLS_PREFIX}-`)) continue;
+    if (entry.name === currentName) continue;
+    const dir = path.join(root, entry.name);
+    try {
+      // The marker is the liveness signal; a tree without one never finished
+      // building, and its own directory mtime is the best evidence available.
+      let seen;
+      try {
+        seen = (await stat(path.join(dir, SHADOW_COMPLETE_MARKER))).mtimeMs;
+      } catch {
+        seen = (await stat(dir)).mtimeMs;
+      }
+      if (seen >= cutoff) continue;
+      await rm(dir, { recursive: true, force: true });
+    } catch {
+      // A stale tree left behind costs disk, not correctness.
+    }
+  }
+}
+
+// breadcrumb + fail-open sibling of guardBreadcrumb below, for the one other
+// place in this file where "cannot do the real thing" must still be loud
+// somewhere rather than just silently degrading.
+function shadowSkillsBreadcrumb(err) {
+  const reason = (err && err.message) || String(err);
+  try {
+    const dir = ensureLocalStateRootSync();
+    appendFileSync(
+      path.join(dir, 'opencode-skills.log'),
+      `${new Date().toISOString()} shadow skills tree generation failed, ` +
+        `registering no Leo skills: ${reason}\n`,
+    );
+  } catch {
+    // A breadcrumb that cannot be written must not itself break the session.
+  }
+  console.error('[leo skills] shadow tree generation failed; registering no Leo skills:', reason);
+}
+
+// Builds (or reuses, keyed by content hash) the shadow tree and returns its
+// path. A failed build returns null rather than the source skills/ directory:
+// registering bare names would be a misleading partial success.
+async function getShadowSkillsDir() {
+  const skillsDir = path.resolve(ROOT, 'skills');
+  let files;
+  try {
+    files = await walkFiles(skillsDir);
+    if (!files.length) throw new Error('no files found under skills/');
+  } catch (err) {
+    shadowSkillsBreadcrumb(err);
+    return null;
+  }
+
+  let hash;
+  try {
+    hash = await hashSkillsTree(skillsDir, files);
+  } catch (err) {
+    shadowSkillsBreadcrumb(err);
+    return null;
+  }
+
+  let stateRoot;
+  try {
+    stateRoot = await ensureLocalStateRoot();
+  } catch (err) {
+    shadowSkillsBreadcrumb(err);
+    return null;
+  }
+  const shadowRoot = path.join(stateRoot, `${SHADOW_SKILLS_PREFIX}-${hash}`);
+  const marker = path.join(shadowRoot, SHADOW_COMPLETE_MARKER);
+
+  let alreadyBuilt = false;
+  try {
+    await stat(marker);
+    alreadyBuilt = true;
+  } catch {
+    // No marker: either never built, or a previous build crashed mid-way.
+    // Either way, (re)build below.
+  }
+
+  if (!alreadyBuilt) {
+    try {
+      await mkdir(shadowRoot, { recursive: true });
+      await buildShadowSkillsTree(shadowRoot, skillsDir, files);
+      // Written last: its presence is the only thing that means "complete",
+      // so a build killed partway through never looks done on the next call.
+      await writeFile(marker, hash + '\n', 'utf8');
+    } catch (err) {
+      shadowSkillsBreadcrumb(err);
+      return null;
+    }
+  }
+
+  // Mark this tree as in use *now*, so a concurrently live instance's tree
+  // never looks abandoned to whoever sweeps next.
+  try {
+    const now = new Date();
+    await utimes(marker, now, now);
+  } catch {
+    // Losing the touch only risks an early sweep of this tree; the next
+    // config() call rebuilds it.
+  }
+
+  try {
+    await cleanupStaleShadowTrees(stateRoot, hash);
+  } catch {
+    // Best-effort; see cleanupStaleShadowTrees.
+  }
+
+  return shadowRoot;
+}
+
 async function assemblePolicy(directory) {
   let skillRaw;
   try {
@@ -79,11 +338,16 @@ async function assemblePolicy(directory) {
   // hooks/session-start.py:97 uses.
   combined = combined.split('${CLAUDE_PLUGIN_ROOT}').join(ROOT);
 
-  let policy = LEO_POLICY_MARKER + '\n' + combined + '</leo-policy>';
+  return LEO_POLICY_MARKER + '\n' + combined + '</leo-policy>';
+}
 
-  // Memory rides in its own envelope after the policy. Spawned rather than
-  // reimplemented in JS: memory.py already owns the store, the projection and
-  // the marker engine, and a fourth copy of that renderer would drift.
+async function getPolicy(directory) {
+  // Policy source and mapping are immutable package inputs, so cache only
+  // those. Memory is repo-local mutable state and must be projected anew on
+  // every config() call in this long-lived OpenCode process.
+  if (!policyInputsCache) policyInputsCache = await assemblePolicy();
+  let policy = policyInputsCache;
+  if (!policy) return null;
   const memory = await memoryBlock(directory);
   if (memory) {
     policy += '\n\n<leo-memory>\n' + memory + '\n</leo-memory>';
@@ -128,9 +392,17 @@ function memoryBlock(directory) {
 async function writePolicyFile(policy, directory) {
   const dir = localStateRoot();
   const dest = path.join(dir, `opencode-policy-${directoryKey(directory)}.md`);
+  const digest = createHash('sha256').update(policy).digest('hex');
+  const cached = policyPathCache.get(directory);
   try {
-    await mkdir(dir, { recursive: true });
-    await writeFile(dest, policy, 'utf8');
+    await ensureLocalStateRoot();
+    if (cached && cached.digest === digest) {
+      await chmod(cached.path, 0o600);
+      return cached.path;
+    }
+    await writeFile(dest, policy, { encoding: 'utf8', mode: 0o600 });
+    await chmod(dest, 0o600);
+    policyPathCache.set(directory, { digest, path: dest });
     return dest;
   } catch {
     return null;
@@ -140,21 +412,11 @@ async function writePolicyFile(policy, directory) {
 // Keyed by directory for the same reason. A bare module variable is shared by
 // every instance in the process, which would pin whichever project started
 // first and serve its memories to the rest.
-const policyCache = new Map();
-async function getPolicy(directory) {
-  if (!policyCache.has(directory)) {
-    policyCache.set(directory, await assemblePolicy(directory));
-  }
-  return policyCache.get(directory);
-}
-
+let policyInputsCache = null;
 const policyPathCache = new Map();
 async function getPolicyPath(directory) {
-  if (!policyPathCache.has(directory)) {
-    const policy = await getPolicy(directory);
-    policyPathCache.set(directory, policy ? await writePolicyFile(policy, directory) : null);
-  }
-  return policyPathCache.get(directory);
+  const policy = await getPolicy(directory);
+  return policy ? await writePolicyFile(policy, directory) : null;
 }
 
 async function loadAgents() {
@@ -166,6 +428,27 @@ async function loadAgents() {
   }
 }
 
+function agentCollisionBreadcrumb(name) {
+  const message = `preserving user OpenCode agent definition for ${name}`;
+  try {
+    const dir = ensureLocalStateRootSync();
+    appendFileSync(path.join(dir, 'opencode-agents.log'), `${new Date().toISOString()} ${message}\n`);
+  } catch {}
+  console.warn(`[leo agents] ${message}`);
+}
+
+function registerAgents(config, agents) {
+  config.agent ||= {};
+  for (const [role, definition] of Object.entries(agents)) {
+    const name = `leo-${role}`;
+    if (Object.prototype.hasOwnProperty.call(config.agent, name)) {
+      agentCollisionBreadcrumb(name);
+      continue;
+    }
+    config.agent[name] = definition;
+  }
+}
+
 // A guard that cannot run allows the command — the same posture as Claude
 // Code and Codex, where PreToolUse blocks only on exit 2 and any other
 // outcome is non-blocking. What must not happen is that it goes quiet: a
@@ -175,8 +458,7 @@ async function loadAgents() {
 function guardBreadcrumb(err) {
   const reason = (err && err.message) || String(err);
   try {
-    const dir = localStateRoot();
-    mkdirSync(dir, { recursive: true });
+    const dir = ensureLocalStateRootSync();
     appendFileSync(
       path.join(dir, 'opencode-guard.log'),
       `${new Date().toISOString()} guard did not run, command allowed: ${reason}\n`,
@@ -205,14 +487,13 @@ export default async function leoPlugin(ctx) {
     async config(config) {
       config.skills ||= {};
       config.skills.paths ||= [];
-      const skillsDir = path.resolve(ROOT, 'skills');
-      if (!config.skills.paths.includes(skillsDir)) {
+      const skillsDir = await getShadowSkillsDir();
+      if (skillsDir && !config.skills.paths.includes(skillsDir)) {
         config.skills.paths.push(skillsDir);
       }
 
       const agents = await loadAgents();
-      config.agent ||= {};
-      Object.assign(config.agent, agents);
+      registerAgents(config, agents);
 
       const policyPath = await getPolicyPath(directory);
       if (policyPath) {
@@ -257,21 +538,28 @@ export default async function leoPlugin(ctx) {
       try {
         exitCode = await new Promise((resolve, reject) => {
           const proc = spawn('python3', [guardPath], { stdio: ['pipe', 'ignore', 'pipe'] });
+          let settled = false;
+          const succeed = (value) => { if (!settled) { settled = true; resolve(value); } };
+          const fail = (err) => { if (!settled) { settled = true; reject(err); } };
           // Every other guard channel is bounded — Claude Code, Codex and
           // Cursor all set timeout 10 in their hook manifests, and Hermes
           // runs in-process so it cannot hang on its own. Unbounded, a wedged
           // python3 hangs the tool call forever with nothing shown to anyone.
           timer = setTimeout(() => {
             try { proc.kill('SIGKILL'); } catch {}
-            reject(new Error('bash-guard.py timed out after 10s'));
+            fail(new Error('bash-guard.py timed out after 10s'));
           }, 10000);
           proc.stderr.on('data', (d) => {
             stderr += d.toString();
           });
-          proc.on('error', reject);
-          proc.on('close', (code) => resolve(code));
-          proc.stdin.write(payload);
-          proc.stdin.end();
+          proc.on('error', fail);
+          proc.on('close', (code) => succeed(code));
+          // An early child exit can turn either write or end into EPIPE. Keep
+          // handlers on both paths so it follows the existing breadcrumbed
+          // fail-open route instead of becoming an unhandled Node error.
+          proc.stdin.on('error', fail);
+          proc.stdin.write(payload, (err) => { if (err) fail(err); });
+          proc.stdin.end((err) => { if (err) fail(err); });
         });
       } catch (err) {
         guardBreadcrumb(err);

package/config/MCP_PINS.md

@@ -0,0 +1,17 @@
+# MCP executable pins
+
+Leo setup executes only the exact core package versions declared together in
+`models.json`'s `command` and `exactVersion` fields:
+
+- `@upstash/context7-mcp@3.2.5`
+- `@playwright/mcp@0.0.78`
+- `chrome-devtools-mcp@1.6.0`
+- `duckduckgo-mcp-server==0.5.0`
+
+To update a pin, review the upstream release and its vendor-owned package
+record, confirm that its command-line and MCP transport contract still match
+setup's rendered shape, then change the command argument and `exactVersion`
+in the same commit. Never use an unqualified package name, range, tag, or
+`@latest`. Run both Python 3.9 and 3.14 setup suites, render adapters with
+`--check`, and inspect a dry-run for every affected harness. The final diff
+must receive the normal Opus-tier review before release.