leos-agent 6.1.0 → 6.3.0

package/scripts/render_adapters.py

@@ -12,7 +12,72 @@ CONFIG_PATH = ROOT / "config" / "models.json"
 ROLE_ROOT = ROOT / "roles"
 CLAUDE_MANIFEST = ROOT / ".claude-plugin" / "plugin.json"
 GENERATED = "<!-- Generated by scripts/render_adapters.py; do not edit. -->\n"
-READ_ONLY = {"expert", "explore", "investigator", "planner", "reviewer"}
+TIERS = ("fable", "opus", "sonnet", "haiku")
+
+
+def _roles(config):
+    """(role, tier, access) triples, sorted.
+
+    `access` used to be a literal set here, duplicating a fact already stated
+    by each role prompt's own `tools:` line and duplicated a third time in the
+    OpenCode test, with nothing tying the three together.
+    """
+    for role, spec in sorted(config["roles"].items()):
+        yield role, spec["tier"], spec["access"]
+
+
+def _cap(config, key, harness):
+    for row in config["capabilities"]:
+        if row["key"] == key:
+            return row["values"][harness]
+    raise KeyError(f"no capability row {key!r}")
+
+
+def _validate(config):
+    """Refuse to render an incoherent matrix.
+
+    This is the only place a contradiction can be caught before --check ships
+    it: a mapping that renders cleanly is indistinguishable from a true one.
+    """
+    harnesses = set(config["harnesses"])
+    for harness, rows in config["harnesses"].items():
+        for tier in rows.get("absentTiers", ()):
+            # Two conditions, and collapse alone is not enough.
+            #
+            # Dropping a tier drops its roles. The ceiling tier is the only one
+            # whose role exists *solely* to be stronger than the rung below —
+            # `expert` cannot break a deadlock a collapsed Opus already lost, so
+            # when it collapses it has no remaining purpose. Every other role
+            # keeps its job through a collapse: "routing between collapsed rungs
+            # buys role, not power" is the policy's own line. Sonnet and Haiku
+            # share a model on two harnesses today, and declaring Sonnet absent
+            # there would silently delete `implementer` — a real rung with a
+            # real job — which is exactly the failure this whole rule replaced.
+            if tier != TIERS[0]:
+                raise ValueError(
+                    f"{harness}: tier {tier!r} is declared absent, but only the ceiling "
+                    f"tier ({TIERS[0]!r}) can be — every other rung's roles keep their "
+                    "job through a collapse"
+                )
+            twins = [t for t in TIERS if t != tier and rows[t]["model"] == rows[tier]["model"]]
+            if not twins:
+                raise ValueError(
+                    f"{harness}: tier {tier!r} is declared absent but has a model of its own — "
+                    "absence is only ever justified by tier collapse"
+                )
+    for row in config["capabilities"]:
+        unanswered = harnesses - set(row["values"])
+        if unanswered:
+            raise ValueError(
+                f"capability {row['key']!r} unanswered for {sorted(unanswered)} — every "
+                "harness answers every row, that is the whole point of the matrix"
+            )
+        for harness, value in row["values"].items():
+            if value["mode"] not in row["modes"]:
+                raise ValueError(
+                    f"capability {row['key']!r}/{harness}: mode {value['mode']!r} "
+                    f"is not one of {row['modes']}"
+                )
 
 
 def _split_role(text):
@@ -30,7 +95,7 @@ def _without(frontmatter, keys):
     return [line for line in frontmatter if not any(line.startswith(key + ":") for key in keys)]
 
 
-def _agent_docs(role, tier, config):
+def _agent_docs(role, tier, access, config):
     source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
     frontmatter, body = _split_role(source)
 
@@ -61,7 +126,7 @@ def _agent_docs(role, tier, config):
 
     cursor_frontmatter = _without(frontmatter, {"model", "effort", "tools"})
     cursor_frontmatter.append("model: inherit")
-    if role in READ_ONLY:
+    if access == "read-only" and _cap(config, "readOnlyRoles", "cursor")["mode"] == "frontmatter":
         cursor_frontmatter.append("readonly: true")
     cursor = (
         "---\n"
@@ -79,18 +144,22 @@ def _opencode_agents(config):
     role name, sourced from the same roles/*.md canonical prompts and the
     same config/models.json tiers every other harness reads.
 
-    A role whose tier resolves to the same model as `opus` on this harness
-    is skipped — that is `expert`/fable here, since opencode's tier table
-    collapses Fable onto Opus (see the opencode harnesses block). Dropping
-    it, rather than registering a fake rung, matches the removed v3.1
-    bridge's posture.
+    A role is dropped only when its tier is *declared absent* on this harness
+    (`absentTiers`), rather than registering a fake rung. That is `expert`
+    here, whose fable tier collapses onto opus.
+
+    The rule this replaced dropped any role whose tier resolved to the same
+    model as opus — model identity, not intent. The day `sonnet` collapsed
+    onto the opus model, `implementer` would have silently vanished from the
+    roster, and the only test that noticed would have said "6 != 5".
     """
     opencode = config["harnesses"]["opencode"]
-    opus_model = opencode["opus"]["model"]
+    absent = set(opencode.get("absentTiers", ()))
+    adapter = opencode["adapter"]
     agents = {}
-    for role, tier in sorted(config["roles"].items()):
+    for role, tier, access in _roles(config):
         model = opencode[tier]["model"]
-        if model == opus_model and tier != "opus":
+        if tier in absent:
             continue
         source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
         frontmatter, body = _split_role(source)
@@ -100,21 +169,14 @@ def _opencode_agents(config):
                 continue
             key, _, value = line.partition(":")
             fm[key.strip()] = value.strip()
-        if role in READ_ONLY:
-            permission = {"edit": "deny"}
+        if access == "read-only":
+            permission = dict(adapter["readOnlyPermission"])
         else:
             # Stopgap for opencode#5894 (unconfirmed whether
             # tool.execute.before intercepts subagent bash): coarse denies
             # on the catastrophic rm class for write-capable agents. The
             # precise tripwire stays hooks/bash-guard.py.
-            permission = {
-                "bash": {
-                    "rm -rf ~": "deny",
-                    "rm -rf ~/*": "deny",
-                    "rm -rf /": "deny",
-                    "rm -rf /*": "deny",
-                }
-            }
+            permission = {"bash": {cmd: "deny" for cmd in adapter["writeBashDeny"]}}
         agents[role] = {
             "description": fm.get("description", ""),
             "mode": "subagent",
@@ -170,102 +232,185 @@ def _skill_notes(config, harness):
     token appears in a non-Claude mapping.
     """
     skills = config.get("skills", {})
+    reasons = skills.get("reasons", {})
     missing = set(skills.get("exclude", {}).get(harness, ()))
     if harness != "claude":
         missing |= set(skills.get("claudeOnly", ()))
     if not missing:
-        return ""
-    reasons = skills.get("reasons", {})
+        # Claude's appendix used to end here, silent in both directions: it
+        # never listed what only it has, and the exclusion list renders only
+        # for the others. A Claude session could not tell from its own mapping
+        # which of its skills do not travel.
+        exclusive = sorted(set(skills.get("claudeOnly", ())))
+        if not exclusive:
+            return ""
+        lines = ["", "## Leo skills only available here", ""]
+        for name in exclusive:
+            lines.append(f"- `leo:{name}` — {reasons.get(name, 'not portable to other harnesses')}.")
+        lines.append("")
+        lines.append(
+            "Every other skill in the policy's Skill index is registered on every "
+            "harness and behaves the same. These are not, so a procedure that "
+            "leans on one of them does not transfer."
+        )
+        return "\n".join(lines) + "\n"
     lines = ["", "## Leo skills not available here", ""]
     for name in sorted(missing):
         lines.append(f"- `leo:{name}` — {reasons.get(name, 'not portable to this harness')}.")
     lines.append("")
     lines.append(
         "Every other skill in the policy's Skill index is registered here and "
-        "behaves the same. Reviewing a pull request on this harness means "
-        "running the canonical reviewer role prompt against the diff by hand."
+        "behaves the same, and so are the operational skills — `leo:review-pr`, "
+        "`leo:resolve-ticket` and `leo:watch-review` all run on this harness. "
+        "Where they name a capability the table above says is missing, take "
+        "the fallback each one documents."
     )
     return "\n".join(lines) + "\n"
 
 
+def _capability_table(config, harness):
+    """The declarative half of every appendix.
+
+    Every harness answers every row, so a *gap* is disclosed by exactly the
+    same mechanism as a capability. Hand-written prose is what let the
+    worktree tools and the workflow runner go unmentioned on three harnesses
+    each: nothing forces a paragraph that was never written, and nothing
+    notices when one goes stale.
+
+    The notes are still human-written English. The matrix does not make them
+    true; it makes them structurally complete and impossible to omit.
+    """
+    lines = ["", "## Capabilities here", "", "| Capability | Here |", "|---|---|"]
+    for row in config["capabilities"]:
+        lines.append(f"| {row['label']} | {row['values'][harness]['note']} |")
+    return "\n".join(lines) + "\n"
+
+
+def _capability_notes(config, harness):
+    """Per-harness visual-evidence rungs and memory projection target.
+
+    Both are things leo:visual-verification and leo:memory would otherwise have
+    to guess at from inside a session. Written as prose rather than a literal
+    plugin-root token: tests/test_harness_mappings.py fails the build if the
+    Claude placeholder leaks into another harness's mapping.
+    """
+    visual = config.get("visual", {}).get(harness)
+    target = config.get("memoryTarget", {}).get(harness)
+    if not visual and not target:
+        return ""
+    out = []
+    if visual:
+        out.append(
+            f"\nVisual evidence here: {visual}. When no rung answers, "
+            "leo:visual-verification requires the unverified-change warning in "
+            "place of a done report.\n"
+        )
+    if target:
+        out.append(
+            f"\nMemory projection here writes to {target}. Only global-scope "
+            "facts are projected — every per-user surface loads in every "
+            "repository, so repo facts would leak across projects; they reach "
+            "the model through the session context block instead. Leo's block "
+            "is marker-delimited; the rest of the file is untouched.\n"
+        )
+    return "".join(out)
+
+
 def _mapping_docs(config):
-    claude_rows = config["harnesses"]["claude"]
-    codex = config["harnesses"]["codex"]
-    cursor = config["harnesses"]["cursor"]
-    hermes = config["harnesses"]["hermes"]
-    hermes_rows = {tier: hermes[tier] for tier in ("fable", "opus", "sonnet", "haiku")}
+    """One loop, not five hand-written blocks.
+
+    Everything the per-harness prose used to say is now either a capability
+    note or a shared paragraph, so a new harness gets a complete appendix by
+    answering the matrix rather than by someone remembering to write one.
+    """
+    out = {}
+    for harness, rows in sorted(config["harnesses"].items()):
+        parts = [GENERATED, f"# {rows['title']} mapping\n\n"]
+        if rows.get("provider"):
+            parts.append(f"Provider: `{rows['provider']}`\n\n")
+        parts.append(_table(rows))
+        parts.append("\n")
+        parts.append(_capability_table(config, harness))
+        parts.append(_capability_notes(config, harness))
+        parts.append(_collapse_note(rows))
+        parts.append(_skill_notes(config, harness))
+        out[harness] = "".join(parts)
+    return out
+
+
+def _absent_tier_sentence(config):
+    """Derived, not asserted: the roles OpenCode does not register.
+
+    Hand-written, this sentence named `expert` and Fable directly and would
+    have gone quietly wrong the first time the tier table changed.
+    """
     opencode = config["harnesses"]["opencode"]
-    opencode_rows = {tier: opencode[tier] for tier in ("fable", "opus", "sonnet", "haiku")}
-    return {
-        "claude": GENERATED
-        + "# Claude Code mapping\n\n"
-        + _table(claude_rows)
-        + "\n\nSpawn the named native agent; its generated frontmatter selects the configured model.\n"
-        + _collapse_note(claude_rows)
-        + _skill_notes(config, "claude"),
-        "codex": GENERATED
-        + "# Codex mapping\n\n"
-        + _table(codex)
-        + "\n\nSpawn a generic subagent with the canonical `roles/<role>.md` prompt and pass both "
-        "`model` and `reasoning_effort` explicitly. A model override in the user's prompt or "
-        "native `AGENTS.md` wins over these defaults.\n"
-        "\nRead-only is prompt-enforced here, not harness-enforced: the judge roles "
-        "(planner, investigator, reviewer, explore) are pasted prompts, so nothing stops a "
-        "subagent that ignores them from editing. Treat their read-only contract as a "
-        "convention, and never route work here that depends on it being a guarantee.\n"
-        + _collapse_note(codex)
-        + _skill_notes(config, "codex"),
-        "cursor": GENERATED
-        + "# Cursor mapping\n\n"
-        + _table(cursor)
-        + "\n\nCursor plugin agents use `model: inherit`. Select the mapped model in Cursor before "
-        "starting a homogeneous tier batch; the plugin does not claim to enforce arbitrary "
-        "per-agent model names.\n"
-        + _collapse_note(cursor)
-        + _skill_notes(config, "cursor"),
-        "hermes": GENERATED
-        + "# Hermes mapping\n\n"
-        + f"Provider: `{hermes['provider']}`\n\n"
-        + _table(hermes_rows)
-        + "\n\nHermes native `delegate_task` has one configured delegation model. Group work into "
-        "homogeneous Kimi or GLM batches, switch the parent with `/model`, and set "
-        "`delegation.provider: openrouter` plus the matching `delegation.model` before spawning.\n"
-        "\nThis policy is NOT injected automatically here. Hermes accepts a `pre_llm_call` "
-        "hook but its runtime never invokes one, so the plugin registers `leo:using-leo` as "
-        "an ordinary skill instead — read it at the start of a session to load the policy. "
-        "Read-only is prompt-enforced only: the judge roles are pasted prompts, so their "
-        "read-only contract is a convention here, not a guarantee.\n"
-        + _collapse_note(hermes_rows)
-        + _skill_notes(config, "hermes"),
-        "opencode": GENERATED
-        + "# OpenCode mapping\n\n"
-        + f"Provider: `{opencode['provider']}`\n\n"
-        + _table(opencode_rows)
-        + "\n\nRoles register as native OpenCode agents (from `adapters/opencode/agents.json`, "
-        "generated from `config/models.json` and `roles/*.md`) and are spawned via the task tool "
-        "as subagents. There is no per-spawn model override on this harness: each agent always "
-        "runs its registered model, so `reviewer` always runs the full Opus-tier model — the "
-        "trivial-diff Sonnet-tier downscale does not apply here; every diff gets the full review.\n"
-        "\nRead-only is harness-enforced here, unlike Codex and Cursor: read-only roles carry a "
-        "generated `permission.edit: deny`, so an off-policy write attempt is refused by OpenCode "
-        "itself, not merely discouraged by the prompt. Write-capable agents additionally carry "
-        "coarse `rm -rf` bash denies as a stopgap for opencode#5894 (unconfirmed whether "
-        "`tool.execute.before` also intercepts subagent bash); the precise tripwire stays "
-        "`hooks/bash-guard.py` on the primary agent.\n"
-        "\nNo `EnterWorktree` tool exists here — use leo:worktrees' raw `git worktree` fallback for "
-        "isolated branch work. State reads and writes go through `python3 <plugin-root>/scripts/state.py` "
-        "(`get` / `merge` / `path`), same contract as every other harness. There is no Workflow tool "
-        "and no `cost-tiered-fix.js` here — a batch of independent tasks is fanned out as manual "
-        "parallel task-tool subagent spawns instead.\n"
-        + _collapse_note(opencode_rows)
-        + _skill_notes(config, "opencode"),
-    }
+    absent = list(opencode.get("absentTiers", ()))
+    if not absent:
+        return "Every tier is a distinct rung here."
+    roles = [r for r, tier, _ in _roles(config) if tier in absent]
+    tiers = " and ".join(t.title() for t in absent)
+    verb = "is" if len(absent) == 1 else "are"
+    listed = ", ".join(f"`{r}`" for r in roles)
+    return (
+        f"{tiers} {verb} not a real rung here, so {listed} "
+        f"{'is' if len(roles) == 1 else 'are'} not registered as an agent and "
+        "escalation caps at Opus."
+    )
+
+
+def _payload_readme(config):
+    """The npm landing page for `leos-agent`.
+
+    The root README cannot be symlinked in: every harness copies or caches
+    this payload on its own, so a link pointing outside it dangles, and the
+    packaging tests forbid symlinks here for exactly that reason. Generating
+    it instead keeps one source and lets --check catch drift.
+
+    Scoped to OpenCode deliberately — npm is only how OpenCode installs this.
+    Every other harness has a native marketplace, and its instructions would
+    be noise on this page.
+    """
+    opencode = config["harnesses"]["opencode"]
+    return (
+        GENERATED
+        + "\n# Leo's Agent\n\n"
+        "Leo's Agent is a portable agent operating policy: cost-tiered model routing, specialist "
+        "subagent roles, process skills, execute-then-review discipline, and a narrow "
+        "catastrophic-command guard.\n\n"
+        "This npm package is the **OpenCode** distribution. Claude Code, Codex, Cursor, and Hermes "
+        "each install it through their own plugin system — see "
+        "[the repository](https://github.com/foxhatleo/leos-agent) for those.\n\n"
+        "## Install\n\n"
+        "```sh\nopencode plugin leos-agent --global\n```\n\n"
+        "On builds without the `plugin` subcommand, add it to "
+        "`~/.config/opencode/opencode.json` (or `opencode.jsonc`) by hand:\n\n"
+        '```json\n{ "$schema": "https://opencode.ai/config.json", "plugin": ["leos-agent"] }\n```\n\n'
+        "Start a new OpenCode session. The plugin registers the skills directory, the "
+        f"{len(json.loads(_opencode_agents(config)))} subagent roles, and the operating policy, and installs the "
+        "bash deletion tripwire.\n\n"
+        "If the skills do not appear, run `opencode debug skill` — each one should list a "
+        "`location` inside this package. The plugin resolves its own install path and registers "
+        "it, so none needs to be written by hand.\n\n"
+        "## Model tiers\n\n"
+        "Tier names describe the kind of work, not a fixed provider model.\n\n"
+        + _table({tier: opencode[tier] for tier in TIERS})
+        + "\n\n"
+        + _absent_tier_sentence(config)
+        + " Retier by editing `config/models.json` and re-running "
+        "`scripts/render_adapters.py`.\n\n"
+        "## Links\n\n"
+        "- [Repository and full documentation](https://github.com/foxhatleo/leos-agent)\n"
+        "- [Operating policy](https://github.com/foxhatleo/leos-agent/blob/main/plugins/leo/skills/using-leo/SKILL.md)\n\n"
+        "MIT licensed.\n"
+    )
 
 
 def render(config):
+    _validate(config)
     outputs = {}
-    for role, tier in sorted(config["roles"].items()):
-        claude, cursor = _agent_docs(role, tier, config)
+    for role, tier, access in _roles(config):
+        claude, cursor = _agent_docs(role, tier, access, config)
         # Claude Code agents MUST live at the conventional agents/ path: a
         # manifest "agents" array of file paths validates but silently loads
         # zero agents, and the conventional directory auto-loads.
@@ -274,6 +419,7 @@ def render(config):
     for harness, content in _mapping_docs(config).items():
         outputs[ROOT / "skills" / "using-leo" / "references" / f"{harness}-mapping.md"] = content
     outputs[ROOT / "adapters" / "opencode" / "agents.json"] = _opencode_agents(config)
+    outputs[ROOT / "README.md"] = _payload_readme(config)
 
     # The manifest is no longer rewritten here: per-install model overrides
     # were retired along with the placeholder they fed. Retiering means editing
@@ -305,6 +451,7 @@ def main():
         "agents/*.md",
         "adapters/cursor/agents/*.md",
         "adapters/opencode/agents.json",
+        "README.md",
         "skills/using-leo/references/*-mapping.md",
     ):
         for path in sorted(ROOT.glob(pattern)):