chipgraph 0.1.0__py3-none-any.whl

chipgraph/adapters/runner/__init__.py

@@ -0,0 +1,7 @@
+"""Runner adapters: execute subprocess commands on behalf of `ToolAdapter`s."""
+
+from __future__ import annotations
+
+from chipgraph.adapters.runner.local import LocalRunner
+
+__all__ = ["LocalRunner"]

chipgraph/adapters/runner/local.py

@@ -0,0 +1,122 @@
+"""`LocalRunner`: runs commands as a direct subprocess on the local machine."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import signal
+import time
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from chipgraph.core.plugin_api.types import RunResult
+
+_MISSING_EXECUTABLE_RETURNCODE = 127
+_POSIX = os.name == "posix"
+_KILL_GRACE_S = 5.0
+"""How long, after a timeout's kill, the output pipes may stay open."""
+
+
+def _kill_tree(proc: asyncio.subprocess.Process) -> None:
+    """Kill `proc` and, on POSIX, every process of its process group (its children)."""
+    if _POSIX:
+        try:
+            os.killpg(proc.pid, signal.SIGKILL)
+            return
+        except (ProcessLookupError, PermissionError):
+            pass  # the group is gone: kill the child itself, if it is still there
+    with contextlib.suppress(ProcessLookupError):
+        proc.kill()
+
+
+class LocalRunner:
+    """Runs `cmd` as an argument list via `asyncio.create_subprocess_exec`.
+
+    Never invokes a shell: `cmd` is always an argument vector. `env` is merged on top
+    of the current process environment (`os.environ`). On POSIX the child starts in a
+    session (and process group) of its own, so a timeout, or the caller being cancelled,
+    kills the child and everything it started: a grandchild that keeps the output pipes
+    open cannot block the run after the kill. A timeout returns a `RunResult` with
+    `timed_out=True`, keeping whatever output was captured before the kill (if the pipes
+    are still open `_KILL_GRACE_S` after it, the output is dropped). A missing executable
+    is reported as `returncode=127` rather than raising.
+    """
+
+    name = "local"
+
+    async def run(
+        self,
+        cmd: Sequence[str],
+        *,
+        cwd: Path,
+        env: Mapping[str, str] | None = None,
+        timeout_s: float | None = None,
+    ) -> RunResult:
+        full_env = dict(os.environ)
+        if env is not None:
+            full_env.update(env)
+
+        start = time.monotonic()
+        extra: dict[str, Any] = {"start_new_session": True} if _POSIX else {}
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                cwd=str(cwd),
+                env=full_env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                **extra,
+            )
+        except FileNotFoundError as exc:
+            duration_s = time.monotonic() - start
+            return RunResult(
+                returncode=_MISSING_EXECUTABLE_RETURNCODE,
+                stdout="",
+                stderr=f"executable not found: {exc}",
+                duration_s=duration_s,
+            )
+        except OSError as exc:
+            duration_s = time.monotonic() - start
+            return RunResult(
+                returncode=_MISSING_EXECUTABLE_RETURNCODE,
+                stdout="",
+                stderr=f"failed to start command: {exc}",
+                duration_s=duration_s,
+            )
+
+        timed_out = False
+        try:
+            if timeout_s is None:
+                stdout_bytes, stderr_bytes = await proc.communicate()
+            else:
+                try:
+                    stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                        proc.communicate(), timeout=timeout_s
+                    )
+                except TimeoutError:
+                    timed_out = True
+                    _kill_tree(proc)
+                    try:
+                        stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                            proc.communicate(), timeout=_KILL_GRACE_S
+                        )
+                    except TimeoutError:
+                        await proc.wait()
+                        stdout_bytes = b""
+                        stderr_bytes = b"output dropped: its pipes stayed open after the kill"
+        except BaseException:
+            _kill_tree(proc)  # cancelled (e.g. Ctrl-C): leave nothing running
+            raise
+        finally:
+            duration_s = time.monotonic() - start
+
+        returncode = proc.returncode if proc.returncode is not None else -9
+        return RunResult(
+            returncode=returncode,
+            stdout=stdout_bytes.decode("utf-8", errors="replace"),
+            stderr=stderr_bytes.decode("utf-8", errors="replace"),
+            duration_s=duration_s,
+            timed_out=timed_out,
+        )

chipgraph/adapters/runtime/__init__.py

@@ -0,0 +1,5 @@
+"""Agent runtimes: where agent rules actually run (DESIGN.md 5.5, D35).
+
+- `claude_code`: the default. The user's own Claude Code runs each task as a role
+  subagent; the engine hands tasks out and checks them over MCP.
+"""

chipgraph/adapters/runtime/claude_code/__init__.py

@@ -0,0 +1,24 @@
+"""Runtime `claude-code` (DESIGN.md 5.5, D35, spike S7).
+
+- `runtime.ClaudeCodeRuntime`: the `AgentRuntime` a build uses; it queues agent tasks.
+  `runtime.ClaudeCodeExecutor` is the build's executor over it.
+- `loop`: the M2-02a agent rule loop applied to one submitted attempt (label, budget,
+  redo instruction, the dispatch bound).
+- `previous`: the outputs of a role without a read tool, moved aside at each dispatch
+  (so its `Write` creates a file), shown in its context, and put back if it fails.
+- `service`: what the MCP tools `next_task`, `get_context` and `submit` do.
+- The Claude Code plugin (`plugin/` in the repo) holds the loop command, one subagent
+  per role, and the write guard hook.
+
+`service` imports `chipgraph.app` (the build, the check runner), so it is not imported
+here: `chipgraph.app.build` imports this package for the runtime.
+"""
+
+from chipgraph.adapters.runtime.claude_code.runtime import (
+    PLUGIN_NAME,
+    RUN_COMMAND,
+    ClaudeCodeExecutor,
+    ClaudeCodeRuntime,
+)
+
+__all__ = ["PLUGIN_NAME", "RUN_COMMAND", "ClaudeCodeExecutor", "ClaudeCodeRuntime"]

chipgraph/adapters/runtime/claude_code/agents.py

@@ -0,0 +1,158 @@
+"""The plugin's role subagents, rendered from the role data (DESIGN.md 5.1, 5.5; D8, D35).
+
+Each built-in role's tool table (`chipgraph.core.runtime.roles`) becomes a Claude Code
+subagent file `plugin/agents/<role>.md`: its abstract capabilities mapped to Claude
+Code tools (`CAPABILITY_TOOLS`), its first tier mapped to a model alias, its prompt with
+the tool placeholders filled in. The files are generated; a test fails when a committed
+one differs from the render::
+
+    python -m chipgraph.adapters.runtime.claude_code.agents --write   # regenerate
+    python -m chipgraph.adapters.runtime.claude_code.agents --check   # exit 1 if stale
+
+`asker.md` and `decider.md` stay hand-written: `/chipgraph:ask` is not a role, and
+`decider` serves the `triage` role through `decide()` (its tools and tier are checked
+against that role by a test).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from chipgraph.adapters.runtime.claude_code.runtime import PLUGIN_NAME
+from chipgraph.core.contracts import ModelTier
+from chipgraph.core.runtime.roles import CAPABILITIES, Capability, RoleSpec, get_role
+
+MCP_TOOL_PREFIX = f"mcp__plugin_{PLUGIN_NAME}_{PLUGIN_NAME}__"
+"""How Claude Code names the plugin's MCP server tools: `mcp__plugin_<p>_<server>__<t>`."""
+
+CAPABILITY_TOOLS: dict[Capability, tuple[str, ...]] = {
+    "read_files": ("Read",),
+    "search_files": ("Glob", "Grep"),
+    "write_outputs": ("Write", "Edit", "MultiEdit"),
+    "engine_context": (f"{MCP_TOOL_PREFIX}get_context",),
+    "engine_decisions": (f"{MCP_TOOL_PREFIX}pending_decisions",),
+}
+"""The Claude Code tools for each abstract capability. Nothing maps to a shell or to web
+tools: roles get neither."""
+
+DEFAULT_TIER_MODELS: dict[ModelTier, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
+"""Claude Code model aliases per tier, when the profile's `models.tiers` names none. The
+agent file's `model` is its role's first tier; `next_task` passes the model per attempt."""
+
+RENDERED_ROLES = ("author", "tb-author", "rtl-author", "critic", "planner", "researcher")
+"""The roles with a generated subagent file."""
+
+HAND_WRITTEN_AGENTS = {"triage": "decider"}
+"""Roles served by a hand-written subagent, and its name."""
+
+_GENERATED_NOTE = (
+    "# Generated from src/chipgraph/core/runtime/roles/data/{role}.md by\n"
+    "# `python -m chipgraph.adapters.runtime.claude_code.agents --write`; do not edit.\n"
+)
+
+
+def agent_name(role_id: str) -> str:
+    """The subagent file name (without `.md`) for a role: its id, or the hand-written one."""
+    short = role_id.rsplit("/", 1)[-1]
+    return HAND_WRITTEN_AGENTS.get(short, short)
+
+
+def agent_type(role_id: str) -> str:
+    """The `subagent_type` for a role: `chipgraph:<agent name>`."""
+    return f"{PLUGIN_NAME}:{agent_name(role_id)}"
+
+
+def tools_for(role: RoleSpec) -> tuple[str, ...]:
+    """The Claude Code tools a role's subagent gets, in capability order."""
+    return tuple(
+        tool
+        for capability in CAPABILITIES
+        if capability in role.tools
+        for tool in CAPABILITY_TOOLS[capability]
+    )
+
+
+def _quoted(text: str) -> str:
+    """A single-quoted YAML scalar."""
+    return "'" + text.replace("'", "''") + "'"
+
+
+def render_agent(role: RoleSpec) -> str:
+    """The subagent file for `role`."""
+    names: dict[str, tuple[str, ...]] = {c: CAPABILITY_TOOLS[c] for c in role.tools}
+    head = (
+        "---\n"
+        + _GENERATED_NOTE.format(role=role.id)
+        + f"name: {agent_name(role.id)}\n"
+        + f"description: {_quoted(role.description)}\n"
+        + f"tools: {', '.join(tools_for(role))}\n"
+        + f"model: {DEFAULT_TIER_MODELS[role.default_tier]}\n"
+        + "---\n\n"
+    )
+    return head + role.render_prompt(names)
+
+
+def rendered_files() -> dict[str, str]:
+    """File name (`<role>.md`) to content, for every generated subagent file."""
+    return {f"{agent_name(r)}.md": render_agent(get_role(r)) for r in RENDERED_ROLES}
+
+
+def _default_agents_dir() -> Path:
+    here = Path(__file__).resolve()
+    for candidate in here.parents:
+        if (candidate / "pyproject.toml").is_file():
+            return candidate / "plugin" / "agents"
+    raise FileNotFoundError(f"no pyproject.toml found above {here}")
+
+
+def check(agents_dir: Path) -> list[str]:
+    """Generated files in `agents_dir` that are missing or differ from the render."""
+    problems = []
+    for name, content in rendered_files().items():
+        path = agents_dir / name
+        if not path.is_file():
+            problems.append(f"missing: {path}")
+        elif path.read_text(encoding="utf-8") != content:
+            problems.append(f"outdated: {path}")
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Render plugin/agents/ from the role data.")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--write", action="store_true", help="write the agent files")
+    mode.add_argument("--check", action="store_true", help="exit 1 if a file is out of date")
+    parser.add_argument("--dir", type=Path, default=None, help="default: plugin/agents/")
+    args = parser.parse_args(argv)
+    agents_dir: Path = args.dir if args.dir is not None else _default_agents_dir()
+    if args.check:
+        problems = check(agents_dir)
+        for problem in problems:
+            print(problem, file=sys.stderr)
+        return 1 if problems else 0
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    for name, content in rendered_files().items():
+        (agents_dir / name).write_text(content, encoding="utf-8")
+    print(f"wrote {len(RENDERED_ROLES)} agent files to {agents_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = [
+    "CAPABILITY_TOOLS",
+    "DEFAULT_TIER_MODELS",
+    "HAND_WRITTEN_AGENTS",
+    "MCP_TOOL_PREFIX",
+    "RENDERED_ROLES",
+    "agent_name",
+    "agent_type",
+    "check",
+    "render_agent",
+    "rendered_files",
+    "tools_for",
+]

chipgraph/adapters/runtime/claude_code/decisions.py

@@ -0,0 +1,280 @@
+"""`decide()` in runtime `claude-code`: questions answered by a small-model subagent.
+
+chipgraph never calls a model in this runtime (D35), so `ClaudeCodeDecideBackend.ask`
+does not answer: it records the question under the state backend and returns
+`Deferred`. The plugin then runs the question in the user's Claude Code session::
+
+    pending_decisions()         the MCP tool lists the queued questions, each with the
+                                tier's model and a prompt, for a `chipgraph:decider`
+                                subagent started with that model
+    answer_decision(id, ...)    the MCP tool records the subagent's JSON answer, after
+                                checking the value is one of the question's choices
+    decide(question) again      the recorded answer comes back from `ask`; if it is
+                                under the small threshold, `decide()` asks the large
+                                tier, which queues the question again with its model
+
+State, one file per question (never in the repo tree)::
+
+    <state>/runtime/decisions/<sha256(question_id)>.json      PendingDecision
+
+A recorded answer is reused only for the very same question (same fingerprint): a
+question id asked with a new prompt, context or choices starts afresh. A question
+labeled 'nda' is refused (`NdaBlocked`): every model of this runtime is a cloud model.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+from chipgraph.adapters.llm._errors import NdaBlocked
+from chipgraph.adapters.llm.decide_backend import question_prompt
+from chipgraph.adapters.runtime.claude_code.runtime import PLUGIN_NAME
+from chipgraph.core.config.models import DecideTier, ModelsCfg
+from chipgraph.core.engine.decide import Deferred, ModelAnswer, Question
+from chipgraph.core.runtime import state_key
+from chipgraph.core.state.layout import StateLayout
+
+DECIDER_AGENT = f"{PLUGIN_NAME}:decider"
+"""The plugin subagent that answers one question (`plugin/agents/decider.md`)."""
+
+DEFAULT_TIER_MODELS: dict[DecideTier, str] = {"small": "haiku", "large": "opus"}
+"""Claude Code model aliases per decide tier, when the profile's `models.tiers` names none
+(the same aliases the task loop uses for these tiers)."""
+
+
+class DecisionStateError(Exception):
+    """An unknown question, one not waiting for an answer, or an answer it cannot take."""
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class RecordedAnswer(BaseModel):
+    """What the decider subagent answered for one tier."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    value: str = Field(description="The answer: one of the question's choices.")
+    confidence: float = Field(ge=0, le=1, description="The subagent's confidence.")
+    reason: str = Field(default="", description="Its short justification.")
+    model: str = Field(description="The model the subagent was asked to run on.")
+    answered_at: AwareDatetime = Field(default_factory=_now, description="When it answered.")
+
+
+class PendingDecision(BaseModel):
+    """One question `decide()` handed to the Claude Code session, and its answers."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    schema_version: Literal[1] = Field(default=1, description="Schema version of this model.")
+    question: Question = Field(description="The question.")
+    fingerprint: str = Field(description="`question.fingerprint()` when it was queued.")
+    tier: DecideTier = Field(description="The tier last asked: the one pending, if any.")
+    model: str = Field(description="The model for `tier`.")
+    status: Literal["pending", "answered"] = Field(description="Whether `tier` has answered.")
+    answers: dict[DecideTier, RecordedAnswer] = Field(
+        default_factory=dict, description="Recorded answers, per tier."
+    )
+    updated_at: AwareDatetime = Field(default_factory=_now, description="Last change.")
+
+
+def _write_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)
+
+
+class DecisionQueue:
+    """Reads and writes the queued questions under a project's state directory."""
+
+    def __init__(self, layout: StateLayout) -> None:
+        self.layout = layout
+        self.dir = layout.state_dir / "runtime" / "decisions"
+
+    def _path(self, question_id: str) -> Path:
+        return self.dir / f"{state_key(question_id)}.json"
+
+    def get(self, question_id: str) -> PendingDecision | None:
+        """The record for `question_id`, or `None` if it was never queued."""
+        path = self._path(question_id)
+        if not path.is_file():
+            return None
+        return PendingDecision.model_validate_json(path.read_text(encoding="utf-8"))
+
+    def all(self) -> list[PendingDecision]:
+        """Every record, sorted by question id."""
+        if not self.dir.is_dir():
+            return []
+        records = [
+            PendingDecision.model_validate_json(p.read_text(encoding="utf-8"))
+            for p in self.dir.glob("*.json")
+        ]
+        return sorted(records, key=lambda r: r.question.id)
+
+    def pending(self) -> list[PendingDecision]:
+        """The records waiting for an answer."""
+        return [r for r in self.all() if r.status == "pending"]
+
+    def _put(self, record: PendingDecision) -> PendingDecision:
+        record = record.model_copy(update={"updated_at": _now()})
+        _write_atomic(self._path(record.question.id), record.model_dump_json(indent=2))
+        return record
+
+    def request(self, question: Question, tier: DecideTier, model: str) -> PendingDecision:
+        """Queue `question` for `tier` (idempotent); a changed question starts afresh."""
+        fingerprint = question.fingerprint()
+        existing = self.get(question.id)
+        answers = existing.answers if existing and existing.fingerprint == fingerprint else {}
+        if (
+            existing is not None
+            and existing.fingerprint == fingerprint
+            and existing.status == "pending"
+            and existing.tier == tier
+            and existing.model == model
+        ):
+            return existing
+        return self._put(
+            PendingDecision(
+                question=question,
+                fingerprint=fingerprint,
+                tier=tier,
+                model=model,
+                status="pending",
+                answers={t: a for t, a in answers.items() if t != tier},
+            )
+        )
+
+    def answer(
+        self, question_id: str, value: str, confidence: float, reason: str = ""
+    ) -> PendingDecision:
+        """Record the answer to the pending tier of `question_id`.
+
+        Raises `DecisionStateError` for an unknown question, one not pending, a value
+        that is not one of its choices, or a confidence outside 0..1.
+        """
+        record = self.get(question_id)
+        if record is None:
+            raise DecisionStateError(
+                f"no queued question {question_id!r}; pending_decisions lists them"
+            )
+        if record.status != "pending":
+            raise DecisionStateError(
+                f"question {question_id!r} is not waiting for an answer (its {record.tier} "
+                "tier already answered)"
+            )
+        choice = record.question.match(value)
+        if choice is None:
+            raise DecisionStateError(
+                f"{value!r} is not a choice of question {question_id!r}; answer one of "
+                f"{list(record.question.choices)}"
+            )
+        if not 0 <= confidence <= 1:
+            raise DecisionStateError(f"confidence must be between 0 and 1, got {confidence}")
+        answers = dict(record.answers)
+        answers[record.tier] = RecordedAnswer(
+            value=choice, confidence=confidence, reason=reason, model=record.model
+        )
+        return self._put(record.model_copy(update={"status": "answered", "answers": answers}))
+
+
+class ClaudeCodeDecideBackend:
+    """A `ModelBackend` for `decide()` that defers each question to the Claude Code session.
+
+    `models.tiers` (the profile's) may name the model per tier; otherwise `haiku` for
+    `small` and `opus` for `large`.
+    """
+
+    name = "claude-code"
+
+    def __init__(self, layout: StateLayout, models: ModelsCfg | None = None) -> None:
+        self.queue = DecisionQueue(layout)
+        self.models = models if models is not None else ModelsCfg()
+
+    def model_for(self, tier: DecideTier) -> str:
+        """The subagent model for `tier`."""
+        return self.models.tiers.get(tier) or DEFAULT_TIER_MODELS[tier]
+
+    async def ask(self, question: Question, tier: DecideTier) -> ModelAnswer | Deferred:
+        if "nda" in question.labels:
+            raise NdaBlocked(
+                f"question {question.id!r} is labeled 'nda' and runtime claude-code only "
+                "has cloud models; 'nda' data only goes to a self-hosted model"
+            )
+        record = self.queue.get(question.id)
+        if record is not None and record.fingerprint == question.fingerprint():
+            answered = record.answers.get(tier)
+            if answered is not None:
+                return ModelAnswer(
+                    value=answered.value,
+                    confidence=answered.confidence,
+                    model=answered.model,
+                    reason=answered.reason,
+                )
+        model = self.model_for(tier)
+        self.queue.request(question, tier, model)
+        return Deferred(
+            question_id=question.id,
+            tier=tier,
+            model=model,
+            message=(
+                f"queued for the {DECIDER_AGENT} subagent (model {model}): the plugin "
+                "reads it with pending_decisions and records the answer with "
+                "answer_decision; then ask again"
+            ),
+        )
+
+
+# --- what the MCP tools do ---------------------------------------------------------------
+
+
+def _entry(record: PendingDecision) -> dict[str, Any]:
+    question = record.question
+    return {
+        "question_id": question.id,
+        "tier": record.tier,
+        "model": record.model,
+        "agent": DECIDER_AGENT,
+        "description": f"chipgraph decide {question.id}",
+        "choices": list(question.choices),
+        "prompt": question_prompt(question),
+    }
+
+
+def pending_decisions(layout: StateLayout) -> dict[str, Any]:
+    """The `pending_decisions` MCP tool: every question waiting for the decider."""
+    return {"decisions": [_entry(r) for r in DecisionQueue(layout).pending()]}
+
+
+def answer_decision(
+    layout: StateLayout, question_id: str, value: str, confidence: float, reason: str = ""
+) -> dict[str, Any]:
+    """The `answer_decision` MCP tool: record the decider's answer for a pending question."""
+    record = DecisionQueue(layout).answer(question_id, value, confidence, reason)
+    answer = record.answers[record.tier]
+    return {
+        "question_id": question_id,
+        "tier": record.tier,
+        "value": answer.value,
+        "confidence": answer.confidence,
+        "status": record.status,
+    }
+
+
+__all__ = [
+    "DECIDER_AGENT",
+    "DEFAULT_TIER_MODELS",
+    "ClaudeCodeDecideBackend",
+    "DecisionQueue",
+    "DecisionStateError",
+    "PendingDecision",
+    "RecordedAnswer",
+    "answer_decision",
+    "pending_decisions",
+]