leos-agent 6.1.0 → 6.3.0

package/scripts/resolve_attach_target.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""Resolve an identifier (PR number/URL, branch name, or ticket id) to everything
+`/attach-pr` needs: the branch, its PR, and the working directory to attach from.
+
+Prints a single JSON object to stdout:
+
+  {"status": "ok", "branch": ..., "pr_number": ..., "pr_url": ..., "base_ref": ...,
+   "pr_state": ..., "pr_title": ..., "workdir": ... | null, "workdir_kind": ...,
+   "attach_command": ...}
+  {"status": "ambiguous", "message": ..., "candidates": [ {...}, ... ]}
+  {"status": "error", "message": ...}
+
+Exit code is 0 for "ok" and 1 otherwise, so callers can branch on it directly.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+PR_NUM_RE = re.compile(r"^#?(\d+)$")
+PR_URL_RE = re.compile(r"^https?://[^/]*github\.com/([^/]+)/([^/]+)/pull/(\d+)")
+TICKET_RE = re.compile(r"^([A-Za-z][A-Za-z0-9]*)-(\d+)$")
+
+PR_FIELDS = "number,url,headRefName,baseRefName,state,title"
+
+
+def run(cmd, cwd=None):
+    """Run a command, returning (returncode, stdout, stderr) with output stripped."""
+    try:
+        p = subprocess.run(
+            cmd, cwd=cwd, capture_output=True, text=True, timeout=60, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return 1, "", str(exc)
+    return p.returncode, p.stdout.strip(), p.stderr.strip()
+
+
+def die(message):
+    print(json.dumps({"status": "error", "message": message}, indent=2))
+    sys.exit(1)
+
+
+def emit(payload):
+    print(json.dumps(payload, indent=2))
+    sys.exit(0 if payload.get("status") == "ok" else 1)
+
+
+# --- environment checks ----------------------------------------------------
+
+
+def repo_root():
+    rc, out, _ = run(["git", "rev-parse", "--show-toplevel"])
+    if rc != 0:
+        die("not inside a git repository — cd into the repo before running /attach-pr")
+    return out
+
+
+def require_gh():
+    if not shutil.which("gh"):
+        die("`gh` is not installed or not on PATH; /attach-pr needs the GitHub CLI")
+    rc, _, err = run(["gh", "auth", "status"])
+    if rc != 0:
+        die(f"`gh` is not authenticated: {err or 'run `gh auth login`'}")
+
+
+def name_with_owner():
+    rc, out, err = run(["gh", "repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"])
+    if rc != 0:
+        die(f"could not determine the GitHub repo for this directory: {err}")
+    return out
+
+
+# --- git helpers -----------------------------------------------------------
+
+
+def worktrees():
+    """Map branch name -> worktree path, from `git worktree list --porcelain`."""
+    rc, out, _ = run(["git", "worktree", "list", "--porcelain"])
+    if rc != 0:
+        return {}
+    result, path = {}, None
+    for line in out.splitlines():
+        if line.startswith("worktree "):
+            path = line[len("worktree ") :]
+        elif line.startswith("branch ") and path:
+            branch = line[len("branch ") :]
+            if branch.startswith("refs/heads/"):
+                result[branch[len("refs/heads/") :]] = path
+    return result
+
+
+def branch_exists_local(branch):
+    rc, _, _ = run(["git", "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"])
+    return rc == 0
+
+
+def branch_exists_remote(branch):
+    rc, out, _ = run(["git", "ls-remote", "--heads", "origin", branch])
+    return rc == 0 and bool(out)
+
+
+def all_known_branches():
+    rc, out, _ = run(
+        [
+            "git",
+            "for-each-ref",
+            "--format=%(refname:short)",
+            "refs/heads",
+            "refs/remotes/origin",
+        ]
+    )
+    if rc != 0:
+        return []
+    names = []
+    for ref in out.splitlines():
+        name = ref[len("origin/") :] if ref.startswith("origin/") else ref
+        if name and name != "HEAD" and name not in names:
+            names.append(name)
+    return names
+
+
+# --- PR lookups ------------------------------------------------------------
+
+
+def pr_by_number(number):
+    rc, out, err = run(["gh", "pr", "view", str(number), "--json", PR_FIELDS])
+    if rc != 0:
+        if "Could not resolve to a PullRequest" in err:
+            return None, f"there is no pull request #{number} in this repo"
+        return None, err or f"no pull request #{number} in this repo"
+    try:
+        return json.loads(out), None
+    except json.JSONDecodeError as exc:
+        return None, f"could not parse `gh pr view` output: {exc}"
+
+
+def prs_for_branch(branch):
+    rc, out, err = run(
+        [
+            "gh", "pr", "list", "--head", branch, "--state", "all",
+            "--json", PR_FIELDS, "--limit", "20",
+        ]
+    )
+    if rc != 0:
+        return [], err or f"`gh pr list` failed for branch {branch}"
+    try:
+        return json.loads(out), None
+    except json.JSONDecodeError as exc:
+        return [], f"could not parse `gh pr list` output: {exc}"
+
+
+def prs_by_search(term):
+    rc, out, _ = run(
+        [
+            "gh", "pr", "list", "--search", term, "--state", "all",
+            "--json", PR_FIELDS, "--limit", "20",
+        ]
+    )
+    if rc != 0:
+        return []
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError:
+        return []
+
+
+def pick_one(prs):
+    """Prefer the single OPEN PR; otherwise the highest-numbered one."""
+    open_prs = [p for p in prs if p.get("state") == "OPEN"]
+    if len(open_prs) == 1:
+        return open_prs[0]
+    pool = open_prs or prs
+    return max(pool, key=lambda p: p.get("number", 0)) if pool else None
+
+
+def as_candidate(pr):
+    return {
+        "pr_number": pr.get("number"),
+        "url": pr.get("url"),
+        "branch": pr.get("headRefName"),
+        "base_ref": pr.get("baseRefName"),
+        "state": pr.get("state"),
+        "title": pr.get("title"),
+    }
+
+
+# --- resolution ------------------------------------------------------------
+
+
+def resolve(identifier, repo):
+    """Return (pr_dict, note) or emit an error/ambiguous payload and exit."""
+    ident = identifier.strip()
+
+    url_match = PR_URL_RE.match(ident)
+    if url_match:
+        owner, name, number = url_match.groups()
+        if f"{owner}/{name}".lower() != repo.lower():
+            die(
+                f"that PR URL belongs to {owner}/{name}, but this directory is {repo}. "
+                "cd into the right repo, or pass an identifier from this one."
+            )
+        pr, err = pr_by_number(number)
+        if not pr:
+            die(err)
+        return pr, f"resolved from PR URL #{number}"
+
+    num_match = PR_NUM_RE.match(ident)
+    if num_match:
+        number = num_match.group(1)
+        pr, err = pr_by_number(number)
+        if not pr:
+            die(err)
+        return pr, f"resolved from PR number #{number}"
+
+    # A ticket-shaped identifier may also be a literal branch name — colony's bare-ticket
+    # branches (`DOCS-5943`) and kebab variants (`docs-6171`) both look like ticket ids.
+    # An exact branch match is the more specific reading, so it wins; ticket search is the
+    # fallback for ids that name no branch directly.
+    if TICKET_RE.match(ident):
+        if branch_exists_local(ident) or branch_exists_remote(ident):
+            return resolve_branch(ident), f"resolved from branch {ident} (ticket-shaped name)"
+        return resolve_ticket(ident), f"resolved from ticket {ident.upper()}"
+
+    return resolve_branch(ident), f"resolved from branch {ident}"
+
+
+def resolve_branch(branch):
+    local = branch_exists_local(branch)
+    remote = branch_exists_remote(branch)
+    if not local and not remote:
+        die(
+            f"branch `{branch}` does not exist locally or on origin. "
+            "Check the name (`git branch -a`), or pass a PR number or ticket id instead."
+        )
+
+    prs, err = prs_for_branch(branch)
+    if err:
+        die(err)
+    if not prs:
+        where = "locally and on origin" if local and remote else ("locally" if local else "on origin")
+        die(
+            f"branch `{branch}` exists {where} but has no pull request "
+            "(any state). Open a PR for it first — /attach-pr only attaches to an existing PR."
+        )
+    if len(prs) > 1:
+        chosen = pick_one(prs)
+        if not (chosen and chosen.get("state") == "OPEN" and
+                sum(1 for p in prs if p.get("state") == "OPEN") == 1):
+            emit({
+                "status": "ambiguous",
+                "message": f"branch `{branch}` has {len(prs)} pull requests; ask which one to attach.",
+                "candidates": [as_candidate(p) for p in prs],
+            })
+        return chosen
+    return prs[0]
+
+
+def resolve_ticket(ticket):
+    """Ticket-tracker-agnostic: match the id against branch names and PR text."""
+    key = ticket.upper()
+    found = {}
+
+    for branch in all_known_branches():
+        if key in branch.upper():
+            prs, _ = prs_for_branch(branch)
+            for pr in prs:
+                found[pr["number"]] = pr
+
+    for pr in prs_by_search(key):
+        haystack = f"{pr.get('title', '')} {pr.get('headRefName', '')}".upper()
+        if key in haystack:
+            found.setdefault(pr["number"], pr)
+
+    prs = list(found.values())
+    if not prs:
+        die(
+            f"found no branch or pull request referencing `{key}` in this repo. "
+            "If the ticket exists but no PR does yet, there is nothing to attach; "
+            "otherwise pass the branch name or PR number directly."
+        )
+    if len(prs) > 1:
+        open_prs = [p for p in prs if p.get("state") == "OPEN"]
+        if len(open_prs) != 1:
+            emit({
+                "status": "ambiguous",
+                "message": f"`{key}` matches {len(prs)} pull requests; ask which one to attach.",
+                "candidates": [as_candidate(p) for p in prs],
+            })
+        return open_prs[0]
+    return prs[0]
+
+
+# --- working directory -----------------------------------------------------
+
+
+def resolve_workdir(branch, root):
+    """Where to attach from: an existing worktree, the base checkout, or nowhere."""
+    wts = worktrees()
+    if branch in wts:
+        path = wts[branch]
+        kind = "worktree" if os.path.realpath(path) != os.path.realpath(root) else "checkout"
+        return path, kind
+
+    rc, current, _ = run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=root)
+    if rc == 0 and current == branch:
+        return root, "checkout"
+
+    return None, "not_checked_out"
+
+
+def main():
+    if len(sys.argv) != 2 or not sys.argv[1].strip():
+        die("usage: resolve_attach_target.py <pr-number|pr-url|branch|TICKET-123>")
+
+    root = repo_root()
+    require_gh()
+    repo = name_with_owner()
+
+    pr, note = resolve(sys.argv[1], repo)
+    branch = pr.get("headRefName")
+    if not branch:
+        die(f"PR #{pr.get('number')} has no head branch recorded; cannot attach")
+
+    workdir, kind = resolve_workdir(branch, root)
+
+    payload = {
+        "status": "ok",
+        "note": note,
+        "repo": repo,
+        "branch": branch,
+        "pr_number": pr.get("number"),
+        "pr_url": pr.get("url"),
+        "base_ref": pr.get("baseRefName") or "main",
+        "pr_state": pr.get("state"),
+        "pr_title": pr.get("title"),
+        "workdir": workdir,
+        "workdir_kind": kind,
+        "repo_root": root,
+        "suggested_worktree": os.path.join(
+            root, ".claude", "worktrees", branch.replace("/", "-")
+        ),
+    }
+    if workdir:
+        payload["attach_command"] = (
+            'gh() { echo "$PR_URL"; }; '
+            f"cd {workdir}; "
+            f"PR_URL={pr.get('url')} gh pr create --draft "
+            f"--base {payload['base_ref']} --head {branch}"
+        )
+    emit(payload)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/setup.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""setup: turn on the wiring a plugin install cannot turn on for itself.
+
+Everything here is opt-in and idempotent. Nothing in this file runs at
+install or session start — the harnesses' own plugin systems have no
+install-time hook to hang it on (Hermes' register() only runs at session
+start), so consent is asked for once, explicitly, and recorded in
+machine-local state.
+
+The one thing it enables today is Hermes memory projection. The other four
+harnesses project into a file whose whole purpose is user instructions;
+Hermes' only user-owned global file is SOUL.md, its agent-identity prompt and
+the opening section of every system prompt on the machine. That is a blast
+radius worth a deliberate yes.
+
+  setup.py                     report what is on and what is available
+  setup.py --json              the same facts as JSON
+  setup.py enable <feature>    turn one on
+  setup.py disable <feature>   turn it off again
+
+Features: hermes-memory
+
+Exit code is 0 on success, 1 on an unknown feature or a failed write.
+"""
+import json
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+
+import memory  # noqa: E402  (path fix must precede the import)
+import state  # noqa: E402
+
+FEATURES = {
+    "hermes-memory": {
+        "state": ("hermes", "projectMemory"),
+        "summary": "project global memory facts into $HERMES_HOME/SOUL.md",
+    },
+}
+
+
+def _read():
+    return state.load(state.state_file(memory.SETUP_STATE))
+
+
+def _write(feature, value):
+    section, key = FEATURES[feature]["state"]
+    path = state.state_file(memory.SETUP_STATE)
+    # Same lock the state CLI takes, so a concurrent merge cannot lose this.
+    with state._locked(path):
+        data = state.deep_merge(state.load(path), {section: {key: value}})
+        state.atomic_write(path, data)
+
+
+def _enabled(data, feature):
+    section, key = FEATURES[feature]["state"]
+    return bool((data.get(section) or {}).get(key))
+
+
+def _hermes_facts():
+    """What projection would actually do right now, without doing it."""
+    home = memory.hermes_home()
+    soul = os.path.join(home, "SOUL.md")
+    return {
+        "home": home,
+        "soul": soul,
+        "home_exists": os.path.isdir(home),
+        "soul_exists": os.path.isfile(soul),
+        "projected": os.path.isfile(soul) and memory.BEGIN in _slurp(soul),
+    }
+
+
+def _slurp(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def collect():
+    data = _read()
+    return {
+        "state_file": state.state_file(memory.SETUP_STATE),
+        "features": {
+            name: {"enabled": _enabled(data, name), "summary": spec["summary"]}
+            for name, spec in FEATURES.items()
+        },
+        "hermes": _hermes_facts(),
+    }
+
+
+def _render(data):
+    lines = ["leo setup", ""]
+    for name, info in sorted(data["features"].items()):
+        lines.append(f"  {'on ' if info['enabled'] else 'off'}  {name}  —  {info['summary']}")
+    lines.append("")
+
+    hermes = data["hermes"]
+    if data["features"]["hermes-memory"]["enabled"]:
+        if not hermes["home_exists"]:
+            lines.append(f"  Hermes is enabled but {hermes['home']} does not exist, so nothing")
+            lines.append("  is written. That is the not-installed case, not a fault.")
+        elif not hermes["soul_exists"]:
+            lines.append(f"  Hermes is enabled but {hermes['soul']} does not exist.")
+            lines.append("  Leo never creates it: Hermes falls back to a built-in persona when")
+            lines.append("  the file is absent, so creating it would replace your agent's")
+            lines.append("  identity. Write the file yourself and Leo will splice into it.")
+        elif hermes["projected"]:
+            lines.append(f"  Hermes: projecting into {hermes['soul']}")
+        else:
+            lines.append(f"  Hermes: enabled, {hermes['soul']} present, not yet written")
+            lines.append("  (projection runs at the next session start).")
+    else:
+        lines.append("  Hermes memory projection is off. Turn it on with:")
+        lines.append("    setup.py enable hermes-memory")
+        lines.append("")
+        lines.append("  It splices a marked block into $HERMES_HOME/SOUL.md, which is the")
+        lines.append("  opening section of every Hermes system prompt. Everything outside")
+        lines.append("  Leo's markers is preserved byte for byte, one .leo-backup is taken")
+        lines.append("  before the first write, and the file is never created.")
+    lines.append("")
+    lines.append(f"  state: {data['state_file']}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv):
+    argv = list(argv)
+    if argv and argv[0] in ("enable", "disable"):
+        if len(argv) < 2:
+            print(f"setup: {argv[0]} needs a feature name: {', '.join(sorted(FEATURES))}",
+                  file=sys.stderr)
+            return 1
+        feature = argv[1]
+        if feature not in FEATURES:
+            print(f"setup: unknown feature {feature!r} "
+                  f"(known: {', '.join(sorted(FEATURES))})", file=sys.stderr)
+            return 1
+        want = argv[0] == "enable"
+        if _enabled(_read(), feature) == want:
+            print(f"{feature} is already {'on' if want else 'off'}; nothing to do")
+            return 0
+        try:
+            _write(feature, want)
+        except Exception as exc:
+            print(f"setup: could not record the change: {exc}", file=sys.stderr)
+            return 1
+        print(f"{feature} is now {'on' if want else 'off'}")
+        return 0
+
+    data = collect()
+    if "--json" in argv:
+        print(json.dumps(data, indent=2, sort_keys=True))
+    else:
+        sys.stdout.write(_render(data))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/skills/delegation/SKILL.md

@@ -53,7 +53,7 @@ a report that hedges across two of them.
 |---|---|---|
 | `done` | Work finished, matches the brief | Verify against artifacts — see leo:verification — never take the self-report at face value |
 | `concerns` | Finished, but flags something worth a second look | Read the concerns before accepting; they're often the real finding |
-| `needs-context` | Blocked on missing information you can supply | Send the missing piece to the same agent (SendMessage) so it keeps the context it already built; cold re-dispatch only if that agent is gone. Either way **once** — a second needs-context on the same gap means the brief itself is broken, escalate the tier |
+| `needs-context` | Blocked on missing information you can supply | Send the missing piece to the same agent (`SendMessage` on Claude Code — elsewhere see the *Follow-up to a live agent* row of your mapping, and where none is established, cold re-dispatch with the context restated is the whole mechanism) so it keeps the context it already built. Either way **once** — a second needs-context on the same gap means the brief itself is broken, escalate the tier |
 | `blocked` | Blocked on something you can't hand over inline | Resolve the blocker, or escalate per the ladder — never a silent same-tier retry |
 
 `needs-context` and `blocked` look similar; the test is whether the missing

package/skills/doctor/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: doctor
+description: >
+  Self-check for Leo's own wiring. Reports which harness this is, what each
+  tier name resolves to here, whether the bootstrap is installed, where
+  machine-local state and the memory store live, and which skills shipped
+  versus which this session can actually invoke. Disk facts come from a
+  helper script; the context facts only the running session can answer, and
+  a disagreement between the two columns is the diagnosis.
+when_to_use: >
+  Leo asks whether the policy loaded, why routing or a skill is misbehaving,
+  or invokes doctor by name after installing, updating, or switching harness.
+  Also the first move when a leo skill cannot be found. NOT a general
+  environment or project health check, NOT for debugging the project's own
+  code (that is leo:debugging), and never run unprompted — it reports on the
+  agent, not on the work.
+---
+
+# doctor
+
+Doctor answers two questions that look like one: what shipped to disk, and what
+reached this session. A skill the harness never registered is indistinguishable
+from a skill that does not exist, right up until the moment you invoke it.
+
+## Run the script
+
+```sh
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.py" --harness <name>
+```
+
+Pass `--harness` with the harness you are on — the mapping appendix in your
+context names it in its own heading (`# Hermes mapping` → `hermes`). Detection
+without it relies on a plugin-root variable that Hermes and OpenCode do not
+export, so on those two the script reports `unknown` rather than guessing.
+`unknown` on a harness whose mapping you can plainly read is a missing
+argument, not a fault.
+
+`${CLAUDE_PLUGIN_ROOT}` is the Claude Code spelling. Codex exports
+`$PLUGIN_ROOT` and Cursor `$CURSOR_PLUGIN_ROOT`. On Hermes and OpenCode no
+plugin-root variable exists at all — but the policy already in your context had
+its placeholders substituted before injection, so the absolute path appears in
+its machine-local state paragraph. Read it from there. Being unable to locate
+the payload at all is itself the first finding: the harness is not looking where
+the plugin was installed.
+
+Add `--json` when you want the same facts as data.
+
+## Then answer the three it cannot
+
+A script can prove the hook is installed and that the policy renders. It cannot
+prove the policy arrived. Only you can see your own context.
+
+1. **Did the policy load?** Look for the policy wrapper in your context, and
+   check that the mapping following it names *this* harness. A policy present
+   but carrying another harness's mapping is worse than none, because routing
+   then points at models that do not exist here.
+2. **Which skills are actually invocable?** Compare your own skill list against
+   the script's shipped roster. Mind the naming rule: most harnesses namespace
+   them as `leo:<name>`, while OpenCode registers the directory by path and
+   names each skill from its own frontmatter, so they appear bare there. A
+   skill that looks missing on OpenCode may simply be listed without a prefix.
+3. **Is memory present and delivered?** The script reports whether the store
+   exists and whether each native surface received its generated copy. Whether
+   those facts are in front of you right now is something only you can confirm.
+   Report the two separately; they disagree more often than expected.
+
+## Reading the report
+
+Every row carries its source — `env`, `disk`, `config`, or `context` — so a
+reader can tell a fact from an inference. Close with one verdict from exactly
+three: **healthy**, **degraded**, or **not loaded**. Never free prose. `not
+loaded` outranks everything else: if the policy did not arrive, nothing else in
+the report describes how this session will actually behave.
+
+**Breadcrumb logs are history, not a verdict.** They carry no timestamps, and
+the test suite drives the failure paths deliberately, so entries accumulate on
+any machine where the tests have ever run. Quote the newest line if it is
+useful, but never conclude "the hook failed this session" from it.
+
+## Failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Policy absent, bootstrap installed | the hook fired and failed open | read the newest breadcrumb, then confirm it describes this session before believing it |
+| Policy present, mapping names another harness | detection resolved wrong, usually a stray plugin-root variable exported in an unrelated shell | unset it, restart the session |
+| Harness reported as `unknown` | no `--harness`, and this harness exports no plugin-root variable | re-run with `--harness <name>` read off your mapping heading |
+| Shipped roster exceeds what you can invoke | the harness cached an older payload, or the skills directory is not registered | update the plugin; on OpenCode check `opencode debug skill` for each skill's `location` |
+| Skills listed without the `leo:` prefix | OpenCode, working as designed | invoke them bare; not a fault |
+| Tier names resolve to models this harness cannot run | mapping and harness disagree | same as row 2 |
+| Machine-local state not writable | the path override points somewhere unwritable | fix or unset it |
+| A skill is genuinely absent from disk | it was never added | see leo:writing-skills |
+
+## Doctor never repairs
+
+It reports, and it names the fix. It does not reinstall, rewrite configuration,
+or delete state — which is what keeps it safe to run at any tier and at any
+moment.
+
+## Works with
+
+- leo:writing-skills — for a skill that turned out to be missing because nobody
+  wrote it yet.
+- leo:memory — doctor reports whether the store exists and reached each surface.
+- leo:verification — this report is a claim like any other: the script ran this
+  turn and its output was read.