leos-agent 7.0.0 → 10.2.0

package/scripts/render_adapters.py

@@ -1,508 +0,0 @@
-#!/usr/bin/env python3
-"""Render harness adapters from config/models.json and canonical role prompts."""
-
-import argparse
-import json
-from pathlib import Path
-import sys
-
-
-ROOT = Path(__file__).resolve().parents[1]
-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"
-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 _tier_identity(rows[t]) == _tier_identity(rows[tier])
-            ]
-            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):
-    lines = text.splitlines()
-    if not lines or lines[0] != "---":
-        raise ValueError("role prompt is missing YAML frontmatter")
-    try:
-        end = lines.index("---", 1)
-    except ValueError as exc:
-        raise ValueError("role prompt has unterminated YAML frontmatter") from exc
-    return lines[1:end], "\n".join(lines[end + 1 :]).strip() + "\n"
-
-
-def _tier_identity(row):
-    """A tier is a model *and* its requested reasoning effort.
-
-    Codex deliberately maps Fable and Opus to the same model at different
-    efforts. Treating a model id alone as identity falsely removes Fable.
-    """
-    return row["model"], row.get("effort")
-
-
-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, access, config):
-    source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
-    frontmatter, body = _split_role(source)
-
-    claude_frontmatter = _without(frontmatter, {"model", "effort"})
-    # Concrete model, never a plugin-config placeholder: Claude Code does not
-    # interpolate plugin options into agent frontmatter, so a placeholder here
-    # reaches the model selector verbatim and every spawn dies with "issue
-    # with the selected model". config/models.json stays the one source.
-    #
-    # And a *bare* alias, never an alias with a context suffix: the agent
-    # frontmatter `model` field documents exactly three accepted shapes — a
-    # bare alias, a full model id, or `inherit`. `opus[1m]` is valid for
-    # /model and for skill frontmatter, but it is not one of those three, so
-    # it is the same undocumented-assumption bet that the placeholder was.
-    # Skill frontmatter (skills-claude/*) keeps [1m]; agents do not.
-    claude_frontmatter.append(f"model: {config['harnesses']['claude'][tier]['model']}")
-    effort = config["harnesses"]["claude"][tier].get("effort")
-    if effort:
-        claude_frontmatter.append(f"effort: {effort}")
-    claude = (
-        "---\n"
-        + "\n".join(claude_frontmatter)
-        + "\n---\n\n"
-        + GENERATED
-        + "\n"
-        + body
-    )
-
-    cursor_frontmatter = _without(frontmatter, {"model", "effort", "tools"})
-    cursor_frontmatter.append("model: inherit")
-    if access == "read-only" and _cap(config, "readOnlyRoles", "cursor")["mode"] == "frontmatter":
-        cursor_frontmatter.append("readonly: true")
-    cursor = (
-        "---\n"
-        + "\n".join(cursor_frontmatter)
-        + "\n---\n\n"
-        + GENERATED
-        + "\n"
-        + body
-    )
-    return claude, cursor
-
-
-def _opencode_agents(config):
-    """Render adapters/opencode/agents.json: one entry per role, keyed by
-    role name, sourced from the same roles/*.md canonical prompts and the
-    same config/models.json tiers every other harness reads.
-
-    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"]
-    absent = set(opencode.get("absentTiers", ()))
-    adapter = opencode["adapter"]
-    agents = {}
-    for role, tier, access in _roles(config):
-        model = opencode[tier]["model"]
-        if tier in absent:
-            continue
-        source = (ROLE_ROOT / f"{role}.md").read_text(encoding="utf-8")
-        frontmatter, body = _split_role(source)
-        fm = {}
-        for line in frontmatter:
-            if ":" not in line:
-                continue
-            key, _, value = line.partition(":")
-            fm[key.strip()] = value.strip()
-        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": {cmd: "deny" for cmd in adapter["writeBashDeny"]}}
-        # `permission.edit: deny` prevents native edits, not destructive shell
-        # commands. Apply the narrow catastrophic Bash denial to every role,
-        # including shell-capable read-only agents.
-        permission.setdefault("bash", {}).update(
-            {cmd: "deny" for cmd in adapter["writeBashDeny"]}
-        )
-        agents[role] = {
-            "description": fm.get("description", ""),
-            "mode": "subagent",
-            "model": f"openrouter/{model}",
-            "prompt": body,
-            "permission": permission,
-        }
-    return json.dumps(agents, indent=2, sort_keys=True) + "\n"
-
-
-def _table(rows):
-    lines = ["| Tier | Model | Effort |", "|---|---|---|"]
-    for tier in ("fable", "opus", "sonnet", "haiku"):
-        item = rows[tier]
-        lines.append(f"| {tier.title()} | `{item['model']}` | {item.get('effort', 'native default')} |")
-    return "\n".join(lines)
-
-
-def _collapse_note(rows):
-    """Name tiers that share one model on this harness.
-
-    The policy treats the four tiers as distinct rungs, and its "no Fable
-    tier here, cap escalation at Opus" branch only fires if the harness says
-    so. A mapping that silently points two rungs at one model leaves that
-    branch unreachable while the expert rung is materially fake.
-    """
-    by_model = {}
-    for tier in ("fable", "opus", "sonnet", "haiku"):
-        by_model.setdefault(_tier_identity(rows[tier]), []).append(tier)
-    collapsed = [tiers for tiers in by_model.values() if len(tiers) > 1]
-    if not collapsed:
-        return ""
-    groups = ", ".join(
-        "≡".join(t.title() for t in tiers) + f" (`{rows[tiers[0]]['model']}`)"
-        for tiers in collapsed
-    )
-    note = f"\nTier collapse here: {groups} — routing between collapsed rungs buys role, not power. "
-    if any("fable" in tiers and "opus" in tiers for tiers in collapsed):
-        note += (
-            "Fable is not a real rung: `expert` cannot break a deadlock a "
-            "collapsed Opus already lost, so cap escalation at Opus and report. "
-        )
-    return note.rstrip() + "\n"
-
-
-def _skill_notes(config, harness):
-    """Name the leo:* skills this harness does not get, and why.
-
-    Silence here is worse than the exclusion: a policy Skill index that lists
-    skills the harness never registered reads as "available" until someone
-    invokes one. Reason strings describe placeholders in prose on purpose —
-    tests/test_harness_mappings.py fails the build if the literal Claude
-    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:
-        # 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, and so are the operational skills — "
-        + ", ".join(f"`leo:{name}`" for name in config["skills"].get("operational", ()))
-        + " 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):
-    """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))
-        if harness == "opencode":
-            parts.append("\n" + _absent_tier_sentence(config) + "\n")
-        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"]
-    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 operating policy with cost-tiered routing, "
-        "specialist roles, process skills, review discipline, and a narrow command guard. "
-        "This npm package is the **OpenCode** distribution; use the "
-        "[repository](https://github.com/foxhatleo/leos-agent) for Claude Code, Codex, Cursor, "
-        "and Hermes instructions.\n\n"
-        "Supported hosts are macOS, Linux, and WSL with Python 3.9+; native Windows is unsupported.\n\n"
-        "## Install and update\n\n"
-        "```sh\nopencode plugin leos-agent --global\n```\n\n"
-        "On builds without that subcommand, add `leos-agent` to the `plugin` array in "
-        "`~/.config/opencode/opencode.json` or `opencode.jsonc`:\n\n"
-        '```json\n{ "$schema": "https://opencode.ai/config.json", "plugin": ["leos-agent"] }\n```\n\n'
-        "Run `opencode auth login` and choose OpenRouter before using the mapped models; Leo "
-        "never writes provider credentials. Update with "
-        "`opencode plugin leos-agent --global --force`, then start a new session. OpenCode "
-        "currently has no plugin removal command; remove the `leos-agent` configuration entry "
-        "to uninstall.\n\n"
-        "The plugin registers generated shadow skills (`leo-<name>`) and namespaced "
-        f"`leo-<role>` agents ({len(json.loads(_opencode_agents(config)))} generated definitions) "
-        "from `adapters/opencode/agents.json`, "
-        "then injects the operating policy through OpenCode's configuration. Invoke its shadow "
-        "skill as `leo-using-leo`. If a skill is absent, "
-        "run `opencode debug skill`; its `location` should be an `opencode-skills-<hash>/leo-<name>/` "
-        "directory under machine-local state, not a hand-written package path.\n\n"
-        "## MCP and durable state\n\n"
-        "Use `leo-setup` to inspect or explicitly configure MCP services: `connectors` reports "
-        "without writing, while `connect` and `apply` make only reviewed, harness-owned changes. "
-        "Vendor connectors are never installed automatically and OAuth stays in OpenCode. "
-        "Slack, Gmail, Drive, and providers without dynamic registration remain manual-only.\n\n"
-        "Uninstall preserves `${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}`. Before a full "
-        "purge, export or copy that directory; only then explicitly remove it. For a 7.0 recovery, "
-        "move old `LEOS_AGENT_PATH/local/` data there, rename the variable, restart, and run "
-        "`leo-doctor`.\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, contributing, and security policy](https://github.com/foxhatleo/leos-agent)\n"
-        "- [GitHub Releases](https://github.com/foxhatleo/leos-agent/releases)\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, 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.
-        outputs[ROOT / "agents" / f"{role}.md"] = claude
-        outputs[ROOT / "adapters" / "cursor" / "agents" / f"{role}.md"] = cursor
-    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
-    # config/models.json and re-running this script, the flow README documents.
-    return outputs
-
-
-def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--check", action="store_true", help="fail if generated adapters drift")
-    args = parser.parse_args()
-    config = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
-    outputs = render(config)
-    drift = []
-    for path, expected in outputs.items():
-        if path.exists() and path.read_text(encoding="utf-8") == expected:
-            continue
-        if args.check:
-            drift.append(path.relative_to(ROOT).as_posix())
-        else:
-            path.parent.mkdir(parents=True, exist_ok=True)
-            path.write_text(expected, encoding="utf-8")
-
-    # Stale generated files are drift too. Comparing only what render() would
-    # produce is blind to a file that exists and *shouldn't* — a role dropped
-    # from models.json, a harness renamed — so the orphan survives every
-    # --check and ships. Sweep the generated trees and flag anything unclaimed.
-    for pattern in (
-        "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)):
-            if path in outputs:
-                continue
-            rel = path.relative_to(ROOT).as_posix()
-            if args.check:
-                drift.append(f"{rel} (stale: nothing in config/models.json generates it)")
-            else:
-                path.unlink()
-                print(f"removed stale generated file: {rel}", file=sys.stderr)
-    if drift:
-        print("generated adapter drift: " + ", ".join(drift), file=sys.stderr)
-        return 1
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())