slipwai 1.3.0.dev5__tar.gz → 1.3.0.dev8__tar.gz

{slipwai-1.3.0.dev5 → slipwai-1.3.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: slipwai
-Version: 1.3.0.dev5
+Version: 1.3.0.dev8
 Summary: One-shot scaffolder for product monorepos: a walking skeleton, a verify gate, a path to production, and a repository set up for coding agents.
 Project-URL: Homepage, https://github.com/ROBCOATVG/slipwai
 Project-URL: Repository, https://git.treyco.dev/ROBCOATVG/slipwai

slipwai-1.3.0.dev8/VERSION

@@ -0,0 +1 @@
+1.3.0.dev8

{slipwai-1.3.0.dev5 → slipwai-1.3.0.dev8}/assets/toolkit/docs/agent-harnesses.md

@@ -86,8 +86,10 @@ project with no index. Both lists name the route back (`mcp_*` on Gemini, one `<
 this project's extensions install on Copilot), which costs nothing that was being held, because both already
 carry the whole shell. The other four reach the session's servers whatever the file says — Claude Code and
 Codex inherit them, Cursor inherits every tool, opencode's `permission` map is a denylist — and on Claude Code
-the tool arrives *deferred*, a bare name the delegate has to load through the harness's own tool-search step
-before it can call it. `registry.json` records all of that under `agentFile.mcp`, with the source and the date
+an MCP tool arrives *deferred*, a bare name the delegate has to load through the harness's own tool-search step
+before it can call it — unless the server's `.mcp.json` entry carries `alwaysLoad: true`, which the registry's
+`projectMcp.serverFields` has the CodeGraph extension write, so its tool is loaded at session start. Every
+harness also has `scripts/codegraph`, the pinned CLI, through the shell. `registry.json` records all of that under `agentFile.mcp`, with the source and the date
 it was read, and every projection's stamp carries it, so a route a harness withholds is one somebody can read.
 
 Because the model lives in these files on five of the six harnesses, `/model-delegation-settings` rewrites them as part of the

slipwai-1.3.0.dev8/assets/toolkit/scripts/agents/code_index.py

@@ -0,0 +1,481 @@
+#!/usr/bin/env python3
+"""The code index kept healthy, kept current and asked first — by the harness and the runner, not by a brief.
+
+A `/cruise` iteration met all four ways an adopted index fails to be used, with nobody making a mistake. The
+database was corrupt when the iteration started, and CodeGraph's own commands did not say so: on a malformed
+`codegraph.db`, `codegraph status` reports the index up to date and `codegraph sync` exits 0, and only a query
+fails. The watcher that keeps it current was off, which CodeGraph decides for itself in a sandbox. Delegates
+reached the index as a deferred tool they had to load by name first, and grepped instead. And nothing counted
+which delegate asked it. Each of those is a place a sentence in a brief was the only control.
+
+So this script holds the index at the points the harness and the runner already own:
+
+    python3 scripts/agents/code_index.py health   # open it, integrity-check it, rebuild a corrupt one, sync a stale one
+    python3 scripts/agents/code_index.py session  # Claude Code's SessionStart hook: `health`, said only when it acted
+    python3 scripts/agents/code_index.py sync     # Claude Code's PostToolUse hook: a delegate came back; sync
+    python3 scripts/agents/code_index.py guard    # Claude Code's PreToolUse hook: a symbol search before the index
+
+`health` is what `scripts/agents/cruise.py` runs before every iteration, what `make check-codegraph` runs on a corrupt
+database before it judges one, and what a person runs to repair an index by hand. `session` is the same step at the
+start of a Claude Code session — a person's `/drive` has no runner in front of it — and prints only what it did or
+could not do, since a hook's output lands in the session's context. The database is ignored by Git and derived from the source, so a corrupt one loses nothing by being moved
+aside (to `.codegraph/corrupt/`, the latest only) and rebuilt. `sync` keeps the index current while an iteration is
+still editing: after each delegate returns rather than on CodeGraph's watcher, because the watcher is what was off.
+`guard` refuses a search of the source for a symbol — the Grep tool, or `grep`, `rg`, `ag`, `ack`, `git grep` or a
+`sed -n '/pattern/p'` through the shell — from a session or a delegate that has not asked the index yet, and names
+the route that answers instead. A symbol is a name the index holds a definition for, or a name shaped like one
+(camelCase, PascalCase with a second hump, snake_case). Words and phrases are prose, and a search confined to
+documents is text search, which is right for them: `spec.md`, `decisions.md`, the PRD, `model.yaml`, a test's string.
+Once the agent has asked the index, its greps are its own business.
+
+Every route here runs the version the MCP server runs (`CODEGRAPH`), so two versions never write one database.
+Standard library only, like every script the toolkit ships. Nothing here fails a command it hooks: a hook that
+cannot decide allows the call.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import shutil
+import sqlite3
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+def project_root(script: Path, depth: int) -> Path:
+    """The repository root: the nearest directory above this script holding `project.json` (see models.py)."""
+    for candidate in script.parents:
+        if (candidate / "project.json").is_file():
+            return candidate
+    return script.parents[depth]
+
+
+SCRIPT = Path(__file__).resolve()
+ROOT = project_root(SCRIPT, 2)
+# The one pin: the MCP server `./init --extension codegraph` writes, the repo-local `scripts/codegraph`, and every
+# command below all run this release. `codegraph help` in it lists the query verbs INDEX_QUERY names.
+CODEGRAPH = "@colbymchenry/codegraph@1.6.0"
+DIRECTORY = ROOT / ".codegraph"
+DATABASE = DIRECTORY / "codegraph.db"
+ASIDE = DIRECTORY / "corrupt"
+# Which session and delegate has asked the index, for `guard`: inside the index's own ignored directory.
+ASKED = DIRECTORY / "asked.json"
+EXTENSIONS = ROOT / ".slipwai/extensions.json"
+# The gate beside this script's directory, whose reading of index against tree `health` shares.
+GATE = SCRIPT.parents[1] / "check-codegraph.py"
+# A command that asks the index something, as against one that maintains it (`sync`, `init`, `index`, `serve`).
+INDEX_QUERY = re.compile(
+    r"\bcodegraph(?:@[\w.-]+)?\s+(query|explore|context|node|files|callers|callees|impact|affected)\b")
+# How long a sync or a rebuild may take before the step gives up and says so.
+SYNC_SECONDS, BUILD_SECONDS = 120, 900
+# The words a refusal starts with, which is how the stream shows where `guard` refused a call.
+REFUSED = "code-index: refused"
+SEARCHERS = {"grep", "egrep", "fgrep", "rg", "ag", "ack"}
+# Documents, whose words a text search is right for: a search confined to these is never a symbol search.
+DOCUMENT = re.compile(r"(^|/)(docs|specs|\.specify)(/|$)|\.(md|mdx|txt|ya?ml|json|feature|csv|drawio|html)$")
+IDENTIFIER = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+SHAPED = re.compile(r"[a-z0-9][A-Z]|[A-Za-z0-9]_[A-Za-z0-9]")
+
+
+def adopted() -> bool:
+    """An index is here, or the extension was elected and the index is due."""
+    if DIRECTORY.is_dir():
+        return True
+    try:
+        return "codegraph" in (json.loads(EXTENSIONS.read_text()).get("extensions") or [])
+    except (OSError, ValueError, AttributeError):
+        return False
+
+
+def route() -> list[str] | None:
+    """How to run the pinned CLI: through `npx` where Node is, or an installed `codegraph` where it is not."""
+    if shutil.which("npx"):
+        return ["npx", "-y", CODEGRAPH]
+    if shutil.which("codegraph"):
+        return ["codegraph"]
+    return None
+
+
+def cli(*arguments: str, seconds: int = SYNC_SECONDS) -> tuple[bool, str]:
+    command = route()
+    if command is None:
+        return False, "neither `npx` nor `codegraph` is on PATH"
+    try:
+        done = subprocess.run([*command, *arguments], cwd=ROOT, text=True, capture_output=True, timeout=seconds,
+                              stdin=subprocess.DEVNULL, env={**os.environ, "CODEGRAPH_NO_UPDATE_CHECK": "1"})
+    except subprocess.TimeoutExpired:
+        return False, f"`codegraph {' '.join(arguments)}` took longer than {seconds}s"
+    except OSError as error:
+        return False, str(error)
+    said = (done.stdout + done.stderr).strip().splitlines()
+    return done.returncode == 0, said[-1].strip("│└● ").strip() if said else ""
+
+
+def damage() -> str | None:
+    """Why the database cannot be trusted — it does not open, or SQLite's integrity check fails — or None."""
+    try:
+        with sqlite3.connect(f"{DATABASE.as_uri()}?mode=ro", uri=True) as connection:
+            verdict = connection.execute("PRAGMA integrity_check").fetchone()
+    except sqlite3.Error as error:
+        return str(error)
+    if verdict and verdict[0] == "ok":
+        return None
+    # SQLite reports every damaged cell on its own line; the first says what kind of damage, the count how much.
+    lines = [line for line in str(verdict[0] if verdict else "no verdict").splitlines() if line.strip()
+             and "in database main" not in line]
+    return lines[0] + (f", and {len(lines) - 1} more" if len(lines) > 1 else "") if lines else "no verdict"
+
+
+def gate() -> Any:
+    """`check-codegraph.py`, loaded, for its reading of which tracked files the index is behind on."""
+    import importlib.util
+    sys.dont_write_bytecode = True  # no `__pycache__/` beside the gate in the project
+    specification = importlib.util.spec_from_file_location("check_codegraph", GATE)
+    assert specification is not None and specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+def behind() -> int | None:
+    """How many tracked files the index has never seen or read before they changed; None where it cannot say."""
+    found = gate().drift()
+    return None if found is None else len(found[1]) + len(found[2])
+
+
+def set_aside() -> str:
+    """Move the database and its journal files under `.codegraph/corrupt/`, keeping only this latest copy."""
+    shutil.rmtree(ASIDE, ignore_errors=True)
+    ASIDE.mkdir(parents=True)
+    stamp = time.strftime("%Y%m%dT%H%M%S")
+    for suffix in ("", "-wal", "-shm", "-journal"):
+        source = DATABASE.with_name(DATABASE.name + suffix)
+        if source.exists():
+            source.rename(ASIDE / f"{stamp}-{source.name}")
+    return (ASIDE.relative_to(ROOT)).as_posix()
+
+
+def health() -> dict[str, Any]:
+    """Make the index one an iteration can query, and say what that took: `current`, `synced`, `built`, `rebuilt`,
+    `unreachable` (no route to the CLI) or `failed` (the step ran and the index is still not right). Nothing where
+    no index was adopted."""
+    if not adopted():
+        return {}
+    began = time.monotonic()
+    result: dict[str, Any] = {}
+    if route() is None:
+        result = {"state": "unreachable", "detail": "neither `npx` nor `codegraph` is on PATH, so nothing can "
+                                                    "maintain or query the index"}
+    elif not DATABASE.is_file():
+        done, said = cli("init", "-y", ".", seconds=BUILD_SECONDS)
+        result = {"state": "built", "detail": "there was no database; built it with `codegraph init`"}
+        if not done:
+            result = {"state": "failed", "detail": f"no database, and `codegraph init` failed: {said}"}
+    elif (problem := damage()) is not None:
+        where = set_aside()
+        done, said = cli("init", "-y", ".", seconds=BUILD_SECONDS)
+        result = {"state": "rebuilt", "detail": f"the database failed its integrity check ({problem}); moved it "
+                                               f"to {where}/ and rebuilt it with `codegraph init`"}
+        if not done:
+            result = {"state": "failed", "detail": f"the database failed its integrity check ({problem}), was moved "
+                                                   f"to {where}/, and `codegraph init` failed: {said}"}
+    else:
+        stale = behind()
+        if stale:
+            done, said = cli("sync", ".")
+            result = {"state": "synced", "detail": f"{stale} tracked file(s) were ahead of the index; synced it"}
+            if not done:
+                result = {"state": "failed", "detail": f"{stale} tracked file(s) ahead of the index, and `codegraph "
+                                                       f"sync` failed: {said}"}
+        else:
+            result = {"state": "current", "detail": "opens, passes its integrity check, and describes the tree"}
+    if result["state"] in ("built", "rebuilt", "synced"):
+        problem, stale = (damage() if DATABASE.is_file() else "no database was written"), None
+        if problem is None:
+            stale = behind()
+        if problem is not None or stale:
+            result = {"state": "failed", "detail": f"{result['detail']}, and it is still "
+                      + (f"not sound ({problem})" if problem else f"behind on {stale} file(s)")}
+    result["seconds"] = round(time.monotonic() - began, 1)
+    return result
+
+
+# --- which calls search the source for a symbol ---------------------------------------------------------------------
+
+
+def symbols(names: list[str]) -> set[str]:
+    """Which of these names the index holds a definition of."""
+    if not names or not DATABASE.is_file():
+        return set()
+    try:
+        with sqlite3.connect(f"{DATABASE.as_uri()}?mode=ro", uri=True) as connection:
+            marks = ",".join("?" * len(names))
+            return {row[0] for row in connection.execute(
+                f"SELECT DISTINCT name FROM nodes WHERE kind NOT IN ('file', 'import') AND name IN ({marks})", names)}
+    except sqlite3.Error:
+        return set()
+
+
+def symbol_of(pattern: str) -> str | None:
+    """The pattern as the symbol(s) it names, or None where it is words: every alternative must be one identifier,
+    and each must be shaped like a symbol or be a name the index defines."""
+    stripped = re.sub(r"\\[bB<>]|[\^$()]|\\\(|\\\)", "", pattern)
+    parts = [part for part in re.split(r"\\?\|", stripped) if part]
+    if not parts or not all(IDENTIFIER.fullmatch(part) for part in parts):
+        return None
+    known = symbols(parts)
+    if all(SHAPED.search(part) or part in known for part in parts):
+        return "|".join(parts)
+    return None
+
+
+def documents_only(paths: list[str], globs: list[str]) -> bool:
+    """A search confined to documents: every path and every include pattern names one, and at least one was given."""
+    named = [item for item in [*paths, *globs] if item]
+    return bool(named) and all(DOCUMENT.search(item.rstrip("/*").replace("**", "")) or DOCUMENT.search(item)
+                               for item in named)
+
+
+def commands_of(command: str) -> list[list[list[str]]]:
+    """The command's pipelines, each a list of the words of its stages, split where the shell splits them: on `;`,
+    `&&`, `||` and newlines between pipelines and on `|` between stages — never inside a quoted pattern."""
+    lexer = shlex.shlex(command.replace("\n", " ; "), posix=True, punctuation_chars=";&|")
+    lexer.whitespace_split = True
+    pipelines: list[list[list[str]]] = [[[]]]
+    try:
+        for token in lexer:
+            if token in (";", "&&", "||", "&", ";;"):
+                pipelines.append([[]])
+            elif token == "|":
+                pipelines[-1].append([])
+            else:
+                pipelines[-1][-1].append(token)
+    except ValueError:
+        return []
+    return [[words for words in pipeline if words] for pipeline in pipelines if any(pipeline)]
+
+
+def shell_searches(command: str) -> list[tuple[str, list[str], list[str]]]:
+    """Each search the command runs over files: its pattern, the paths it names and its include patterns. A search
+    reading another command's output — `git ls-files | grep Cue` — is over names, not source, and is not one."""
+    found = []
+    for pipeline in commands_of(command):
+        for position, words in enumerate(pipeline):
+            while words and "=" in words[0] and not words[0].startswith("-"):
+                words = words[1:]
+            if not words:
+                continue
+            program = Path(words[0]).name
+            if program == "git" and len(words) > 1 and words[1] == "grep":
+                program, words = "grep", words[1:]
+            if program == "sed":
+                scripts = [word for word in words[1:] if not word.startswith("-")]
+                address = re.match(r"^/((?:\\.|[^/])+)/", scripts[0]) if scripts else None
+                if address:
+                    found.append((address.group(1), scripts[1:], []))
+                continue
+            if program not in SEARCHERS:
+                continue
+            pattern, paths, globs, rest = None, [], [], words[1:]
+            index = 0
+            while index < len(rest):
+                word = rest[index]
+                if word in ("-e", "--regexp") and index + 1 < len(rest):
+                    pattern, index = rest[index + 1], index + 2
+                    continue
+                if word.startswith("--include=") or word.startswith("--glob="):
+                    globs.append(word.split("=", 1)[1])
+                elif word in ("-g", "--glob", "--include", "-t", "--type") and index + 1 < len(rest):
+                    globs.append(rest[index + 1] if word not in ("-t", "--type") else f"*.{rest[index + 1]}")
+                    index += 1
+                elif word.startswith("-"):
+                    pass
+                elif pattern is None:
+                    pattern = word
+                else:
+                    paths.append(word)
+                index += 1
+            if pattern is not None and (paths or position == 0):
+                found.append((pattern, paths, globs))
+    return found
+
+
+def symbol_search(tool: str, given: dict[str, Any]) -> str | None:
+    """The symbol a tool call searches the source for, or None where it searches documents, words, or nothing."""
+    if tool == "Grep":
+        glob = given.get("glob") or (f"*.{given['type']}" if given.get("type") else "")
+        if documents_only([str(given.get("path") or "")], [str(glob)]):
+            return None
+        return symbol_of(str(given.get("pattern", "")))
+    if tool == "Bash":
+        for pattern, paths, globs in shell_searches(str(given.get("command", ""))):
+            if not documents_only(paths, globs) and (symbol := symbol_of(pattern)):
+                return symbol
+    return None
+
+
+def index_query(tool: str, given: dict[str, Any]) -> bool:
+    return tool.startswith("mcp__codegraph__") or (tool == "Bash" and bool(INDEX_QUERY.search(str(given.get("command", "")))))
+
+
+# --- the hooks ------------------------------------------------------------------------------------------------------
+
+
+def event() -> dict[str, Any]:
+    try:
+        read = json.loads(sys.stdin.read() or "{}")
+    except ValueError:
+        return {}
+    return read if isinstance(read, dict) else {}
+
+
+def asker(happened: dict[str, Any]) -> str:
+    """Whose call this is: the session, and the delegate inside it where there is one."""
+    return f"{happened.get('session_id', '?')}:{happened.get('agent_id') or 'host'}"
+
+
+def load_asked() -> dict[str, float]:
+    try:
+        read = json.loads(ASKED.read_text())
+    except (OSError, ValueError):
+        return {}
+    return read if isinstance(read, dict) else {}
+
+
+def guard() -> int:
+    """Refuse a symbol search of the source from whoever has not asked the index yet; record who has."""
+    happened = event()
+    tool = str(happened.get("tool_name", ""))
+    given = happened.get("tool_input") if isinstance(happened.get("tool_input"), dict) else {}
+    if not DATABASE.is_file() or route() is None:
+        return 0
+    asked = load_asked()
+    who = asker(happened)
+    if index_query(tool, given):
+        asked[who] = time.time()
+        try:
+            ASKED.write_text(json.dumps(dict(sorted(asked.items(), key=lambda pair: pair[1])[-200:])) + "\n")
+        except OSError:
+            pass
+        return 0
+    if who in asked:
+        return 0
+    symbol = symbol_search(tool, given)
+    if symbol is None:
+        return 0
+    first = symbol.split("|")[0]
+    print(f"{REFUSED}: `{symbol}` is a symbol, and this repository's code index answers who calls it, what it calls "
+          f"and what a change to it reaches. Ask it first: `scripts/codegraph callers {first}`, `scripts/codegraph "
+          f"impact {first}` or `scripts/codegraph explore {first}` through the shell, or the codegraph_explore tool. "
+          "A text search is for words in documents — spec.md, decisions.md, model.yaml, a test's string — and once "
+          "the index has been asked in this context a search for a symbol is allowed too.", file=sys.stderr)
+    return 2
+
+
+def sync() -> int:
+    """A delegate came back, having edited what it edited: bring the index up to it. Never fails the call."""
+    if DATABASE.is_file() and route() is not None:
+        cli("sync", ".")
+    return 0
+
+
+# --- what the stream says each delegate did --------------------------------------------------------------------------
+
+
+def delegate_use(stream: Path, only: int | None = None) -> dict[int, list[dict[str, Any]]]:
+    """Per iteration of a runner's stream, per agent — the host session, then each delegate in the order it was sent —
+    how often it asked the index, which symbols it searched the source for before it had, and how often `guard`
+    refused it. Claude Code marks a delegate's events with `parent_tool_use_id`; a harness whose stream does not
+    is counted as the host alone."""
+    found: dict[int, list[dict[str, Any]]] = {}
+    if not stream.is_file():
+        return found
+    iteration, agents = 0, {}
+    for line in stream.read_text(errors="replace").splitlines():
+        if line.startswith("# iteration "):
+            iteration = int(line.split()[2])
+            if only is not None and iteration != only:
+                continue
+            agents = {"": {"agent": "host", "queries": 0, "searched_first": [], "refused": 0}}
+            found[iteration] = list(agents.values())
+            continue
+        if only is not None and iteration != only:
+            continue
+        try:
+            happened = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(happened, dict) or iteration not in found:
+            continue
+        owner = agents.get(str(happened.get("parent_tool_use_id") or ""), agents[""])
+        message = happened.get("message") if isinstance(happened.get("message"), dict) else {}
+        for block in message.get("content") if isinstance(message.get("content"), list) else []:
+            if not isinstance(block, dict):
+                continue
+            given = block.get("input") if isinstance(block.get("input"), dict) else {}
+            if block.get("type") == "tool_use":
+                name = str(block.get("name", ""))
+                if name in ("Agent", "Task"):
+                    agents[str(block.get("id", ""))] = {"agent": str(given.get("subagent_type") or "delegate"),
+                                                        "queries": 0, "searched_first": [], "refused": 0}
+                    found[iteration].append(agents[str(block.get("id", ""))])
+                elif index_query(name, given):
+                    owner["queries"] += 1
+                elif not owner["queries"] and (symbol := symbol_search(name, given)):
+                    owner["searched_first"].append(symbol)
+            # An error result carrying the hook's words: an index answer quoting this file is not a refusal.
+            elif block.get("type") == "tool_result" and block.get("is_error") and REFUSED in json.dumps(block.get("content")):
+                owner["refused"] += 1
+        item = happened.get("item") if isinstance(happened.get("item"), dict) else {}
+        if happened.get("type") == "item.started":
+            if (item.get("type") == "mcp_tool_call" and item.get("server") == "codegraph") or (
+                    item.get("type") == "command_execution" and INDEX_QUERY.search(str(item.get("command", "")))):
+                owner["queries"] += 1
+            elif item.get("type") == "command_execution" and not owner["queries"]:
+                symbol = symbol_search("Bash", {"command": item.get("command", "")})
+                if symbol:
+                    owner["searched_first"].append(symbol)
+    return found
+
+
+def use_lines(iteration: int, agents: list[dict[str, Any]]) -> list[str]:
+    """The feed's and `status`'s account of one iteration: the queries per agent, then each agent that searched the
+    source for a symbol before asking the index."""
+    counts = ", ".join(f"{agent['agent']} {agent['queries']}" for agent in agents)
+    lines = [f"cruise: iteration {iteration} asked the code index {sum(agent['queries'] for agent in agents)} time(s) — "
+             f"{counts}"]
+    for agent in agents:
+        if agent["searched_first"]:
+            shown = ", ".join(f"`{each}`" for each in dict.fromkeys(agent["searched_first"]))
+            lines.append(f"cruise:   {agent['agent']} searched the source for {shown} before asking the index")
+        if agent["refused"]:
+            lines.append(f"cruise:   {agent['agent']} was refused {agent['refused']} symbol search(es) until it asked")
+    return lines
+
+
+def main(argv: list[str]) -> int:
+    verb = argv[0] if argv else ""
+    if verb == "health":
+        said = health()
+        print(f"code-index: {said['state']} — {said['detail']}" if said else "code-index: no index adopted here")
+        return 1 if said.get("state") in ("failed", "unreachable") else 0
+    if verb == "session":
+        said = health()
+        if said and said["state"] != "current":
+            print(f"code-index: at session start the index was {said['state']} — {said['detail']}")
+        return 0
+    if verb == "guard":
+        return guard()
+    if verb == "sync":
+        return sync()
+    print(__doc__, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

{slipwai-1.3.0.dev5 → slipwai-1.3.0.dev8}/assets/toolkit/scripts/agents/cruise.py

@@ -76,6 +76,12 @@ def project_root(script: Path, depth: int) -> Path:
 
 SCRIPT = Path(__file__).resolve()
 ROOT = project_root(SCRIPT, 2)
+# The code index's health, freshness and per-delegate use live beside this script, shared with the hooks. No bytecode:
+# a `__pycache__/` written beside the scripts is an untracked directory in the project, which `add-service` refuses
+# to start over and the run's fingerprint would read as progress.
+sys.dont_write_bytecode = True
+sys.path.insert(0, str(SCRIPT.parent))
+import code_index  # noqa: E402
 # The delivery toolkit this script is part of: `commands/`, `scripts/`, `skills/` beside each other, at the root
 # or under the delivery directory of an adopted repository.
 DELIVERY = SCRIPT.parents[2]
@@ -91,10 +97,6 @@ STREAM = ROOT / ".specify/cruise-stream.jsonl"
 # The code index `./init --extension codegraph` leaves, and the project MCP file that carries its server: what the
 # runner says it can expect of them before the first iteration, rather than a feed that fell back to grep without saying.
 CODE_INDEX = ROOT / ".codegraph/codegraph.db"
-# A shell command that asks the index something, as against one that maintains it: `codegraph sync` keeps the gate
-# green and answers nothing, and counting it once let a run claim the index was asked when every answer was grep
-# (the CLI's query subcommands, `codegraph help` in the 1.6.0 bundle, read 2026-09-22).
-INDEX_QUERY = re.compile(r"\bcodegraph\s+(query|explore|node|files|callers|callees|impact|affected)\b")
 MCP_CONFIG = ROOT / ".mcp.json"
 # How far into the run log the watching session has read.
 WATCH_CURSOR = ROOT / ".specify/cruise-watch.cursor"
@@ -1224,6 +1226,12 @@ def drive(table: dict[str, Any], harness: dict[str, Any] | None, template: str,
                 feature, kickoff if attempt == "kick-off" else None, told_argument(messages)) if part))
             print(f"cruise: iteration {len(entries()) + 1} carries {len(messages)} message(s) from a person", flush=True)
         iteration = len(entries()) + 1
+        # The index an iteration starts against is the runner's to make sound, not the iteration's: a corrupt one is
+        # moved aside and rebuilt, a stale one synced, and the entry says which — before the clock starts.
+        index = code_index.health()
+        if index:
+            print(f"cruise: code index before iteration {iteration} — {index['state']}: {index['detail']} "
+                  f"({index['seconds']}s)", flush=True)
         started = now()
         LAST_RESPONSE.unlink(missing_ok=True)
         INTERRUPTED = False
@@ -1246,6 +1254,13 @@ def drive(table: dict[str, Any], harness: dict[str, Any] | None, template: str,
                                  "last_line": last or "no last line", "fingerprint": seen}
         if attempt is not None:
             entry["attempt"] = attempt
+        if index:
+            entry["index"] = index
+        use = code_index.delegate_use(STREAM, iteration).get(iteration) if index and stream else None
+        if use:
+            entry["index_use"] = use
+            for line in code_index.use_lines(iteration, use):
+                print(line, flush=True)
         changed = controls_changed(controls_before, controls_signature())
         if changed:
             entry["controls_changed"] = changed
@@ -1531,36 +1546,9 @@ def refusals() -> dict[tuple[str, str], list[int]]:
 def index_queries() -> dict[int, int]:
     """How many times each iteration in the stream asked the code index — an MCP tool of the codegraph server, or a
     query subcommand of the CLI through the shell; never `sync`, `init` or `serve`, which maintain it — so `status`
-    can say whether the index was used rather than only kept fresh."""
-    asked: dict[int, int] = {}
-    if not STREAM.is_file():
-        return asked
-    iteration = 0
-    for line in STREAM.read_text(errors="replace").splitlines():
-        if line.startswith("# iteration "):
-            iteration = int(line.split()[2])
-            asked.setdefault(iteration, 0)
-            continue
-        try:
-            event = json.loads(line)
-        except ValueError:
-            continue
-        if not isinstance(event, dict):
-            continue
-        message = event.get("message") if isinstance(event.get("message"), dict) else {}
-        for block in message.get("content") if isinstance(message.get("content"), list) else []:
-            if not isinstance(block, dict) or block.get("type") != "tool_use":
-                continue
-            given = block.get("input") if isinstance(block.get("input"), dict) else {}
-            if str(block.get("name", "")).startswith("mcp__codegraph__") or (
-                    block.get("name") == "Bash" and INDEX_QUERY.search(str(given.get("command", "")))):
-                asked[iteration] = asked.get(iteration, 0) + 1
-        item = event.get("item") if isinstance(event.get("item"), dict) else {}
-        if event.get("type") == "item.started" and (
-                (item.get("type") == "mcp_tool_call" and item.get("server") == "codegraph")
-                or (item.get("type") == "command_execution" and INDEX_QUERY.search(str(item.get("command", ""))))):
-            asked[iteration] = asked.get(iteration, 0) + 1
-    return asked
+    can say whether the index was used rather than only kept fresh. Summed over the host and every delegate."""
+    return {iteration: sum(agent["queries"] for agent in agents)
+            for iteration, agents in code_index.delegate_use(STREAM).items()}
 
 
 def index_use_lines() -> list[str]:
@@ -1580,6 +1568,18 @@ def index_use_lines() -> list[str]:
             "it was refused, and `start` says whether it can be reached at all"]
 
 
+def delegate_lines(last: int = 5) -> list[str]:
+    """`status`'s per-delegate account of the last few iterations the stream holds: each agent's queries, and each
+    that searched the source for a symbol before asking the index."""
+    if not CODE_INDEX.is_file():
+        return []
+    used = code_index.delegate_use(STREAM)
+    lines: list[str] = []
+    for iteration in sorted(used)[-last:]:
+        lines += code_index.use_lines(iteration, used[iteration])
+    return lines
+
+
 def denials() -> None:
     """What a run needed that its permissions did not allow — the list to read after a run, before widening
     anything, because the tools a build needs are measured from a build and not guessed at."""
@@ -1637,7 +1637,7 @@ def status() -> None:
     if found:
         print(f"cruise: {sum(len(its) for its in found.values())} permission refusal(s) in the stream; "
               "`python3 scripts/agents/cruise.py denials` lists them")
-    for line in index_use_lines():
+    for line in index_use_lines() + delegate_lines():
         print(line)
 
 

{slipwai-1.3.0.dev5 → slipwai-1.3.0.dev8}/assets/toolkit/scripts/agents/registry.json

@@ -224,8 +224,11 @@
         "file": ".mcp.json",
         "format": "json-mcpServers",
         "headlessFlags": "--mcp-config .mcp.json",
-        "how": "the project-scoped MCP file Claude Code reads (code.claude.com/docs/en/mcp, the scope table): `{\"mcpServers\": {\"<name>\": {\"type\": \"stdio\", \"command\", \"args\"}}}`. A print session loads it only once the workspace is trusted and the file's servers approved (`enabledMcpjsonServers` in the project's settings, which an untrusted workspace ignores), so the runner passes the file by name",
-        "source": "a 2.1.280 print session in an untrusted scratch checkout: `--mcp-config .mcp.json` listed the file's server as connected on its init event and the allowed tool answered; the same file without the flag, in the same checkout, was not loaded — read 2026-09-22; the file's shape also from CodeGraph 1.6.0's installer targets (`lib/dist/installer/targets/*.js` in the @colbymchenry/codegraph-linux-x64 bundle), which write the same file for `--location=local`, read 2026-09-22"
+        "serverFields": {
+          "alwaysLoad": true
+        },
+        "how": "the project-scoped MCP file Claude Code reads (code.claude.com/docs/en/mcp, the scope table): `{\"mcpServers\": {\"<name>\": {\"type\": \"stdio\", \"command\", \"args\"}}}`. A print session loads it only once the workspace is trusted and the file's servers approved (`enabledMcpjsonServers` in the project's settings, which an untrusted workspace ignores), so the runner passes the file by name; `alwaysLoad: true` on the entry loads the server's tools at session start, delegates' included, rather than behind the tool-search step a delegate otherwise has to take by name before its first call",
+        "source": "a 2.1.280 print session in an untrusted scratch checkout: `--mcp-config .mcp.json` listed the file's server as connected on its init event and the allowed tool answered; the same file without the flag, in the same checkout, was not loaded — read 2026-09-22; the file's shape also from CodeGraph 1.6.0's installer targets (`lib/dist/installer/targets/*.js` in the @colbymchenry/codegraph-linux-x64 bundle), which write the same file for `--location=local`, read 2026-09-22; `alwaysLoad`: three 2.1.281 print sessions in a scratch checkout, each sending a delegate to find a function's callers — without the key the delegate's first call was the tool-search step selecting `codegraph_explore`, with it (two sessions) its first call was `codegraph_explore` itself — read 2026-09-25"
       }
     },
     {