loki-mode 7.7.24 → 7.7.26

package/tools/probe-model-catalog.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Probe provider documentation pages and report new models.
+
+Approach kept deliberately conservative: we fetch known docs URLs, look for
+model IDs that match well-defined regex patterns, and compare against the
+current `providers/model_catalog.json`. We do NOT auto-rewrite the catalog;
+we emit a report and a unified diff so a maintainer (or the cron-driven PR)
+can review.
+
+Run locally:
+    python3 tools/probe-model-catalog.py            # report only
+    python3 tools/probe-model-catalog.py --json     # machine-readable
+
+In CI: see .github/workflows/model-catalog-probe.yml
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CATALOG_PATH = REPO_ROOT / "providers" / "model_catalog.json"
+
+# Patterns that look like provider model IDs. Conservative -- only the well
+# defined Claude/Codex/Gemini families today.
+PATTERNS: dict[str, list[re.Pattern[str]]] = {
+    "claude": [
+        re.compile(r"\bclaude-(?:opus|sonnet|haiku)-\d+(?:-\d+)?(?:-\d{8})?\b"),
+    ],
+    "codex": [
+        re.compile(r"\bgpt-\d+(?:\.\d+)?-codex\b"),
+    ],
+    "gemini": [
+        re.compile(r"\bgemini-\d+(?:\.\d+)?-(?:pro|flash)(?:-(?:preview|exp|latest))?\b"),
+    ],
+}
+
+# Pages we read. These should be public documentation. Failure to fetch any
+# single one is non-fatal -- we report what we got.
+SOURCES: dict[str, list[str]] = {
+    "claude": [
+        "https://docs.claude.com/en/about-claude/models/overview",
+    ],
+    "codex": [
+        "https://platform.openai.com/docs/models",
+    ],
+    "gemini": [
+        "https://ai.google.dev/gemini-api/docs/models",
+    ],
+}
+
+USER_AGENT = (
+    "loki-mode-model-probe/1.0 "
+    "(+https://github.com/asklokesh/loki-mode)"
+)
+
+
+def fetch(url: str, timeout: int = 30) -> str:
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        body = resp.read().decode("utf-8", errors="ignore")
+    return body
+
+
+def load_catalog() -> dict:
+    with CATALOG_PATH.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def known_ids(catalog: dict, provider: str) -> set[str]:
+    p = catalog.get("providers", {}).get(provider, {})
+    ids: set[str] = set()
+    for m in p.get("models", []):
+        if isinstance(m, dict) and m.get("id"):
+            ids.add(m["id"])
+    for key in ("latest_planning", "latest_development", "latest_fast"):
+        if p.get(key):
+            ids.add(p[key])
+    aliases = p.get("cli_aliases", {})
+    if isinstance(aliases, dict):
+        for v in aliases.values():
+            if isinstance(v, str):
+                ids.add(v)
+    return ids
+
+
+def probe_provider(provider: str) -> tuple[set[str], list[str]]:
+    """Return (found_ids, errors)."""
+    seen: set[str] = set()
+    errors: list[str] = []
+    for url in SOURCES.get(provider, []):
+        try:
+            body = fetch(url)
+        except urllib.error.URLError as exc:
+            errors.append(f"{url}: {exc}")
+            continue
+        except Exception as exc:  # network / parse / etc.
+            errors.append(f"{url}: {type(exc).__name__}: {exc}")
+            continue
+        for pat in PATTERNS.get(provider, []):
+            for m in pat.findall(body):
+                seen.add(m)
+    return seen, errors
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    ap.add_argument("--strict", action="store_true", help="exit nonzero if new models are found")
+    args = ap.parse_args()
+
+    catalog = load_catalog()
+    report: dict[str, dict] = {}
+    any_new = False
+    for provider in PATTERNS:
+        found, errors = probe_provider(provider)
+        known = known_ids(catalog, provider)
+        new_only = sorted(found - known)
+        report[provider] = {
+            "known_count": len(known),
+            "found_count": len(found),
+            "new_candidates": new_only,
+            "errors": errors,
+        }
+        if new_only:
+            any_new = True
+
+    if args.json:
+        json.dump(report, sys.stdout, indent=2, sort_keys=True)
+        sys.stdout.write("\n")
+    else:
+        for provider, info in report.items():
+            new = info["new_candidates"]
+            errs = info["errors"]
+            print(f"== {provider} ==")
+            print(f"   known in catalog: {info['known_count']}")
+            print(f"   found in docs:    {info['found_count']}")
+            if new:
+                print(f"   NEW CANDIDATES:   {', '.join(new)}")
+            else:
+                print(f"   NEW CANDIDATES:   (none)")
+            for e in errs:
+                print(f"   ERROR: {e}")
+            print()
+        if any_new:
+            print("To adopt a new model: edit providers/model_catalog.json -> bump latest_<tier>")
+            print("and add to models[]. Then re-run this script to confirm it disappears from new_candidates.")
+
+    return 1 if (args.strict and any_new) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/regen-state-machine-refs.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Keep docs/architecture/STATE-MACHINES.md line-number references in sync.
+
+Many lines in STATE-MACHINES.md reference source locations like:
+    Source: `autonomy/run.sh:7380` (council_should_stop)
+    | running | ... | `run.sh:7380` |
+
+Whenever run.sh / loki / completion-council.sh / server.py grow, those line
+numbers drift and the doc lies. This script checks every reference that has
+an annotated function name `(func_name)` and verifies the line number in the
+referenced file matches the line where that function is defined.
+
+Usage:
+    python3 tools/regen-state-machine-refs.py            # report drift only
+    python3 tools/regen-state-machine-refs.py --fix      # rewrite stale numbers in place
+    python3 tools/regen-state-machine-refs.py --strict   # exit nonzero on drift (CI)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DOC_PATH = REPO_ROOT / "docs" / "architecture" / "STATE-MACHINES.md"
+
+# File path aliases used in the doc, mapped to repo-root-relative paths.
+FILE_ALIASES = {
+    "autonomy/run.sh": "autonomy/run.sh",
+    "run.sh": "autonomy/run.sh",
+    "autonomy/loki": "autonomy/loki",
+    "loki": "autonomy/loki",
+    "autonomy/completion-council.sh": "autonomy/completion-council.sh",
+    "completion-council.sh": "autonomy/completion-council.sh",
+    "dashboard/server.py": "dashboard/server.py",
+    "server.py": "dashboard/server.py",
+    "autonomy/openspec-adapter.py": "autonomy/openspec-adapter.py",
+    "openspec-adapter.py": "autonomy/openspec-adapter.py",
+    "memory/engine.py": "memory/engine.py",
+    "memory/storage.py": "memory/storage.py",
+    "memory/retrieval.py": "memory/retrieval.py",
+    "memory/consolidation.py": "memory/consolidation.py",
+    "providers/loader.sh": "providers/loader.sh",
+    "providers/claude.sh": "providers/claude.sh",
+    "providers/codex.sh": "providers/codex.sh",
+    "providers/gemini.sh": "providers/gemini.sh",
+    "events/bus.py": "events/bus.py",
+    "events/emit.sh": "events/emit.sh",
+    "mcp/server.py": "mcp/server.py",
+}
+
+# Pattern matches `<file>:<num>(-<num>)? (func_name)` where the parenthesised
+# function name is optional and may appear with surrounding text.
+# Examples it must catch:
+#   autonomy/run.sh:7380 (council_should_stop)
+#   `run.sh:7380` (council_should_stop)
+#   `completion-council.sh:1311` (council_should_stop), ...
+REF_RE = re.compile(
+    r"`?(?P<file>[\w./-]+\.(?:sh|py))"      # file
+    r":(?P<line>\d+)"                        # start line
+    r"(?:-(?P<line_end>\d+))?"               # optional range end
+    r"`?"
+    r"(?:\s*\((?P<func>[a-zA-Z_][a-zA-Z0-9_]*)(?:\s*\(\))?\))?"
+)
+
+
+def find_func_start(source: str, func_name: str) -> int | None:
+    """Return the 1-based line number where `func_name` is defined.
+
+    Supports bash (`func_name() {`) and Python (`def func_name(`) forms.
+    Returns None if not found uniquely.
+    """
+    bash_pat = re.compile(rf"^\s*{re.escape(func_name)}\s*\(\s*\)\s*\{{?\s*$")
+    py_pat = re.compile(rf"^\s*def\s+{re.escape(func_name)}\s*\(")
+    matches = []
+    for i, line in enumerate(source.splitlines(), start=1):
+        if bash_pat.match(line) or py_pat.match(line):
+            matches.append(i)
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        # Multiple definitions; we cannot disambiguate so return None.
+        return None
+    return None
+
+
+@dataclass
+class Drift:
+    line_no: int          # line in STATE-MACHINES.md
+    original: str         # exact substring to replace
+    file: str             # source file path
+    annotated_line: int   # line number written in the doc
+    actual_line: int      # line number where the function actually lives
+    func: str             # function name
+
+
+def scan(doc_text: str, source_cache: dict[str, str]) -> list[Drift]:
+    drifts: list[Drift] = []
+    for doc_line_no, line in enumerate(doc_text.splitlines(), start=1):
+        for m in REF_RE.finditer(line):
+            func = m.group("func")
+            if not func:
+                continue  # cannot verify without annotated function name
+            file_alias = m.group("file")
+            file_rel = FILE_ALIASES.get(file_alias)
+            if not file_rel:
+                continue
+            try:
+                annotated = int(m.group("line"))
+            except (TypeError, ValueError):
+                continue
+            src_path = REPO_ROOT / file_rel
+            if not src_path.exists():
+                continue
+            if file_rel not in source_cache:
+                source_cache[file_rel] = src_path.read_text(encoding="utf-8", errors="ignore")
+            actual = find_func_start(source_cache[file_rel], func)
+            if actual is None or actual == annotated:
+                continue
+            drifts.append(
+                Drift(
+                    line_no=doc_line_no,
+                    original=m.group(0),
+                    file=file_alias,
+                    annotated_line=annotated,
+                    actual_line=actual,
+                    func=func,
+                )
+            )
+    return drifts
+
+
+def apply_fixes(doc_text: str, drifts: list[Drift]) -> str:
+    """Rewrite each stale line number to its current value."""
+    if not drifts:
+        return doc_text
+    new_lines = doc_text.splitlines(keepends=True)
+    by_line: dict[int, list[Drift]] = {}
+    for d in drifts:
+        by_line.setdefault(d.line_no, []).append(d)
+    for ln, items in by_line.items():
+        idx = ln - 1
+        line = new_lines[idx]
+        for d in items:
+            old_seg = f"{d.file}:{d.annotated_line}"
+            new_seg = f"{d.file}:{d.actual_line}"
+            line = line.replace(old_seg, new_seg, 1)
+        new_lines[idx] = line
+    return "".join(new_lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--fix", action="store_true", help="rewrite stale line numbers in place")
+    ap.add_argument("--strict", action="store_true", help="exit nonzero if any drift is detected")
+    args = ap.parse_args()
+
+    if not DOC_PATH.exists():
+        print(f"missing: {DOC_PATH}", file=sys.stderr)
+        return 1
+
+    doc_text = DOC_PATH.read_text(encoding="utf-8")
+    cache: dict[str, str] = {}
+    drifts = scan(doc_text, cache)
+
+    if not drifts:
+        print(f"OK -- no drift in {DOC_PATH.relative_to(REPO_ROOT)}")
+        return 0
+
+    print(f"Drift detected in {DOC_PATH.relative_to(REPO_ROOT)}: {len(drifts)} reference(s)")
+    for d in drifts:
+        print(f"  doc L{d.line_no}: {d.file}:{d.annotated_line} ({d.func}) -> actual {d.file}:{d.actual_line}")
+
+    if args.fix:
+        DOC_PATH.write_text(apply_fixes(doc_text, drifts), encoding="utf-8")
+        print(f"Rewrote {len(drifts)} reference(s) in {DOC_PATH.relative_to(REPO_ROOT)}")
+        return 0
+
+    if args.strict:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())