leos-agent 6.1.1 → 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,15 +16,22 @@
 // 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 { 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';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 
@@ -30,6 +43,29 @@ 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
+// per-directory state in a bare module variable. The directory arrives on
+// PluginInput and is threaded through every consumer instead.
+function directoryKey(directory) {
+  return createHash('sha256').update(directory).digest('hex').slice(0, 12);
+}
+
 // A 6-line strip, not a YAML parser: the body starts after the second
 // leading '---' fence line. Anything malformed just returns the raw text.
 function stripFrontmatter(raw) {
@@ -43,7 +79,241 @@ function stripFrontmatter(raw) {
   return raw;
 }
 
-async function assemblePolicy() {
+// --- 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 {
     skillRaw = await readFile(path.join(ROOT, 'skills', 'using-leo', 'SKILL.md'), 'utf8');
@@ -71,33 +341,82 @@ async function assemblePolicy() {
   return LEO_POLICY_MARKER + '\n' + combined + '</leo-policy>';
 }
 
-async function writePolicyFile(policy) {
+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>';
+  }
+  return policy;
+}
+
+// Hard-kills after 4s: OpenCode session start must not hang on a memory store
+// living on a slow or unreachable filesystem. Any failure yields '' and the
+// session proceeds with policy only.
+//
+// `memory.py session` renders the block for the repo it is run in, so the
+// directory has to be the session's, not the server's: process.cwd() here
+// would serve one project's repo-scoped memories to every other project the
+// same OpenCode process is hosting.
+function memoryBlock(directory) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (value) => { if (!done) { done = true; resolve(value); } };
+    try {
+      const child = spawn('python3', [path.join(ROOT, 'scripts', 'memory.py'), 'session'], {
+        cwd: directory,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} finish(''); }, 4000);
+      let out = '';
+      child.stdout.on('data', (chunk) => { out += chunk.toString(); });
+      child.on('error', () => { clearTimeout(timer); finish(''); });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        finish(code === 0 ? out.trim() : '');
+      });
+    } catch {
+      finish('');
+    }
+  });
+}
+
+// Named per directory: the memory envelope inside is repo-scoped, so a single
+// shared filename would have each project's instance overwriting the file the
+// other projects' config.instructions already point at.
+async function writePolicyFile(policy, directory) {
   const dir = localStateRoot();
-  const dest = path.join(dir, 'opencode-policy.md');
+  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;
   }
 }
 
-let policyCache;
-async function getPolicy() {
-  if (policyCache === undefined) {
-    policyCache = await assemblePolicy();
-  }
-  return policyCache;
-}
-
-let policyPathCache;
-async function getPolicyPath() {
-  if (policyPathCache === undefined) {
-    const policy = await getPolicy();
-    policyPathCache = policy ? await writePolicyFile(policy) : null;
-  }
-  return policyPathCache;
+// 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.
+let policyInputsCache = null;
+const policyPathCache = new Map();
+async function getPolicyPath(directory) {
+  const policy = await getPolicy(directory);
+  return policy ? await writePolicyFile(policy, directory) : null;
 }
 
 async function loadAgents() {
@@ -109,23 +428,74 @@ async function loadAgents() {
   }
 }
 
-let guardWarnedOnce = false;
+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
+// one-shot warning latch meant the second and every later unguarded command
+// passed with nothing said anywhere. Breadcrumb every one of them, to the
+// same local log the other bootstraps write to.
+function guardBreadcrumb(err) {
+  const reason = (err && err.message) || String(err);
+  try {
+    const dir = ensureLocalStateRootSync();
+    appendFileSync(
+      path.join(dir, 'opencode-guard.log'),
+      `${new Date().toISOString()} guard did not run, command allowed: ${reason}\n`,
+    );
+  } catch {
+    // A breadcrumb that cannot be written must not itself break the session.
+  }
+  console.error('[leo guard] guard did not run, allowing command:', reason);
+}
+
+export default async function leoPlugin(ctx) {
+  // The only place the session's directory is available. tool.execute.before
+  // receives just {tool, sessionID, callID} (@opencode-ai/plugin's own types),
+  // so reading a directory off that input yields undefined every time and
+  // falls through to the server's cwd — a different tree whenever one process
+  // hosts more than one project.
+  const directory = (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+
+  // OpenCode runs no session-start hook and exports no plugin-root variable,
+  // so scripts/doctor.py cannot tell this harness apart from a bare shell and
+  // used to inherit the bootstrap's "claude" default. Declare it, and do it
+  // here so the guard and memory subprocesses inherit it too.
+  process.env.LEOS_AGENT_HARNESS = 'opencode';
 
-export default async function leoPlugin(_ctx) {
   return {
     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();
+      const policyPath = await getPolicyPath(directory);
       if (policyPath) {
         config.instructions ||= [];
         if (!config.instructions.includes(policyPath)) {
@@ -143,7 +513,7 @@ export default async function leoPlugin(_ctx) {
       if (!Array.isArray(system)) return;
       if (system.some((s) => typeof s === 'string' && s.includes(LEO_POLICY_MARKER))) return;
 
-      const policy = await getPolicy();
+      const policy = await getPolicy(directory);
       if (policy) system.push(policy);
     },
 
@@ -152,32 +522,50 @@ export default async function leoPlugin(_ctx) {
       const command = output && output.args && output.args.command;
       if (typeof command !== 'string' || !command) return;
 
-      const cwd = (input && (input.directory || input.worktree || input.cwd)) || process.cwd();
-      const payload = JSON.stringify({ tool_name: 'Bash', tool_input: { command }, cwd });
+      // bash-guard expands relative targets against this cwd, so the wrong
+      // one misjudges in both directions: a home-level delete read as safe,
+      // a project-local delete read as critical.
+      const payload = JSON.stringify({
+        tool_name: 'Bash',
+        tool_input: { command },
+        cwd: directory,
+      });
       const guardPath = path.join(ROOT, 'hooks', 'bash-guard.py');
 
       let exitCode;
       let stderr = '';
+      let timer;
       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 {}
+            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) {
-        if (!guardWarnedOnce) {
-          guardWarnedOnce = true;
-          console.error(
-            '[leo guard] infra failure spawning bash-guard.py, allowing command:',
-            err && err.message ? err.message : err,
-          );
-        }
+        guardBreadcrumb(err);
         return; // infra fail-open
+      } finally {
+        clearTimeout(timer);
       }
 
       if (exitCode === 2) {

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.