brindle 0.0.3__tar.gz → 0.0.4__tar.gz

{brindle-0.0.3 → brindle-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brindle
-Version: 0.0.3
+Version: 0.0.4
 Summary: Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges
 Project-URL: Homepage, https://pawdelta.com/brindle/
 Project-URL: Documentation, https://pawdelta.com/brindle/docs/recommended-use
@@ -89,7 +89,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.0.3`). A session started before an upgrade keeps
+session shows it too (`brindle 0.0.4`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -672,7 +672,7 @@ how to use them, and the next step to get the rest:
 | per-worktree services | Pro | `"services"` in `.brindle/config.json` |
 | several repos in one session | Pro | `brindle repo add <path>` |
 | org policies + audit feed | Team | `brindle account org policy` |
-| Brindle-CI | Team | back in a later release |
+| Brindle-CI | Team | `brindle ci init` |
 | audit log, air-gap | Enterprise | `brindle audit verify`, `"airgap": true` |
 
 ```sh
@@ -816,7 +816,11 @@ hosted control plane decides what each run does and what it reports. The
 workflows call these commands:
 
 - `brindle ci init`: set a repository up in one go (the GitHub App, the secrets,
-  the workflows as a pull request, then a doctor check).
+  the workflows as a pull request, then a doctor check). Run it inside a
+  checkout of the repository. For Claude it asks whether to use an API key
+  (the `ANTHROPIC_API_KEY` secret) or Anthropic
+  [workload identity federation](https://platform.claude.com/docs/en/manage-claude/wif-reference)
+  (`--credential key|federation` answers without asking).
 - `brindle ci doctor`: which provider CLIs and credential names a runner has, and
   which providers CI may use on this repository.
 - `brindle ci start`: start a run for an issue, a goal text or a dispatched run,
@@ -828,6 +832,36 @@ workflows call these commands:
 Credential names are reported, never values. On a repository owned by a GitHub
 organization, a provider signed in only with a personal subscription is not used.
 
+An Anthropic API key is either a workspace key (scoped to one workspace) or an
+organization-level key (not scoped to a workspace). An organization-level key
+needs the workspace in every request, so after the key `brindle ci init` asks for
+its workspace ID (`wrkspc_...`; leave it blank for a workspace key, or pass
+`--workspace-id`, default `$ANTHROPIC_WORKSPACE_ID`) and stores it as the Actions
+variable `ANTHROPIC_WORKSPACE_ID`. The workflow then sets
+`ANTHROPIC_CUSTOM_HEADERS="anthropic-workspace-id: <id>"`, which reaches every
+Claude Code process the run starts.
+
+With identity federation the repository stores no Anthropic key: the workflow
+exchanges GitHub's OIDC token once for a short-lived Anthropic token, as a
+Claude Console service account (billed as API, so it is allowed on
+organization repositories), and gives the job `ANTHROPIC_AUTH_TOKEN`. `brindle
+ci init` stores the rule, organization, service account and optional workspace
+IDs as the Actions variables `ANTHROPIC_FEDERATION_RULE_ID`,
+`ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` and
+`ANTHROPIC_WORKSPACE_ID`. Create the federation rule in the Claude Console with
+subject prefix `repo:<owner>/<name>:*`, the condition
+
+```text
+claims.repository == "<owner>/<name>" && claims.workflow_ref.startsWith("<owner>/<name>/.github/workflows/brindle-ci-")
+```
+
+audience `https://api.anthropic.com`, and a token lifetime of at least 7200
+seconds. The condition lets only brindle's workflows mint tokens. On pull
+requests the pull request's own copy of the validate workflow runs, so give
+write access only to people you trust (forks never get a token). Leave the `ANTHROPIC_API_KEY` secret
+unset: a key takes precedence (brindle drops an empty one before Claude Code
+starts).
+
 **Closing and cleaning up.** Press `x` on an agent in the sidebar (twice for one
 that's still running) or run `brindle close <id>` to stop it and hide it. Stopping means
 every process of the agent, not just its window: Claude Code can host a session in its

{brindle-0.0.3 → brindle-0.0.4}/README.md

@@ -59,7 +59,7 @@ uv tool install --editable ~/Projects/brindle   # or from a local checkout
 brindle drives Claude Code, so you need that too (`npm install -g @anthropic-ai/claude-code`).
 
 `brindle --version` prints the installed version; the tmux status bar of every brindle
-session shows it too (`brindle 0.0.3`). A session started before an upgrade keeps
+session shows it too (`brindle 0.0.4`). A session started before an upgrade keeps
 running the old code, and shows the old number, until you restart it.
 
 ## Quick start
@@ -642,7 +642,7 @@ how to use them, and the next step to get the rest:
 | per-worktree services | Pro | `"services"` in `.brindle/config.json` |
 | several repos in one session | Pro | `brindle repo add <path>` |
 | org policies + audit feed | Team | `brindle account org policy` |
-| Brindle-CI | Team | back in a later release |
+| Brindle-CI | Team | `brindle ci init` |
 | audit log, air-gap | Enterprise | `brindle audit verify`, `"airgap": true` |
 
 ```sh
@@ -786,7 +786,11 @@ hosted control plane decides what each run does and what it reports. The
 workflows call these commands:
 
 - `brindle ci init`: set a repository up in one go (the GitHub App, the secrets,
-  the workflows as a pull request, then a doctor check).
+  the workflows as a pull request, then a doctor check). Run it inside a
+  checkout of the repository. For Claude it asks whether to use an API key
+  (the `ANTHROPIC_API_KEY` secret) or Anthropic
+  [workload identity federation](https://platform.claude.com/docs/en/manage-claude/wif-reference)
+  (`--credential key|federation` answers without asking).
 - `brindle ci doctor`: which provider CLIs and credential names a runner has, and
   which providers CI may use on this repository.
 - `brindle ci start`: start a run for an issue, a goal text or a dispatched run,
@@ -798,6 +802,36 @@ workflows call these commands:
 Credential names are reported, never values. On a repository owned by a GitHub
 organization, a provider signed in only with a personal subscription is not used.
 
+An Anthropic API key is either a workspace key (scoped to one workspace) or an
+organization-level key (not scoped to a workspace). An organization-level key
+needs the workspace in every request, so after the key `brindle ci init` asks for
+its workspace ID (`wrkspc_...`; leave it blank for a workspace key, or pass
+`--workspace-id`, default `$ANTHROPIC_WORKSPACE_ID`) and stores it as the Actions
+variable `ANTHROPIC_WORKSPACE_ID`. The workflow then sets
+`ANTHROPIC_CUSTOM_HEADERS="anthropic-workspace-id: <id>"`, which reaches every
+Claude Code process the run starts.
+
+With identity federation the repository stores no Anthropic key: the workflow
+exchanges GitHub's OIDC token once for a short-lived Anthropic token, as a
+Claude Console service account (billed as API, so it is allowed on
+organization repositories), and gives the job `ANTHROPIC_AUTH_TOKEN`. `brindle
+ci init` stores the rule, organization, service account and optional workspace
+IDs as the Actions variables `ANTHROPIC_FEDERATION_RULE_ID`,
+`ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` and
+`ANTHROPIC_WORKSPACE_ID`. Create the federation rule in the Claude Console with
+subject prefix `repo:<owner>/<name>:*`, the condition
+
+```text
+claims.repository == "<owner>/<name>" && claims.workflow_ref.startsWith("<owner>/<name>/.github/workflows/brindle-ci-")
+```
+
+audience `https://api.anthropic.com`, and a token lifetime of at least 7200
+seconds. The condition lets only brindle's workflows mint tokens. On pull
+requests the pull request's own copy of the validate workflow runs, so give
+write access only to people you trust (forks never get a token). Leave the `ANTHROPIC_API_KEY` secret
+unset: a key takes precedence (brindle drops an empty one before Claude Code
+starts).
+
 **Closing and cleaning up.** Press `x` on an agent in the sidebar (twice for one
 that's still running) or run `brindle close <id>` to stop it and hide it. Stopping means
 every process of the agent, not just its window: Claude Code can host a session in its

{brindle-0.0.3 → brindle-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brindle"
-version = "0.0.3"
+version = "0.0.4"
 description = "Run coding agents in parallel, each on its own git branch, with a supervisor that delegates, reviews, and merges"
 readme = "README.md"
 requires-python = ">=3.11"

{brindle-0.0.3 → brindle-0.0.4}/src/brindle/ci_adapters.py

@@ -9,7 +9,9 @@ An adapter answers four questions and does three things:
 * ``credential(env)``: which credential *names* are present (never values) and
   what kind they are: an API key, a cloud sign-in (Bedrock, Vertex, ...), an
   endpoint without a key, or a personal subscription (``CLAUDE_CODE_OAUTH_TOKEN``;
-  a ChatGPT login for Codex).
+  a ChatGPT login for Codex). Anthropic workload identity federation reaches
+  here as an API key: the workflow exchanges GitHub's OIDC token once and
+  gives the job ``ANTHROPIC_AUTH_TOKEN``.
 * ``available(env)``: installed and holding some credential.
 * ``launch``: start a brindle autopilot supervisor with the plan's instructions.
 * ``review``: ask the model one question (the plan's instructions) and return
@@ -29,6 +31,7 @@ detection, no rendering. The server does that.
 from __future__ import annotations
 
 import json
+import logging
 import os
 import re
 import shutil
@@ -37,11 +40,13 @@ import tempfile
 import time
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Mapping
+from typing import Mapping, MutableMapping
 
 
 from brindle import providers
 
+log = logging.getLogger(__name__)
+
 API_KEY = "api_key"
 CLOUD = "cloud"
 ENDPOINT = "endpoint"
@@ -65,6 +70,12 @@ BASE_URL_RE = re.compile(r"^(?P<scheme>https?)://(?P<host>[A-Za-z0-9]([A-Za-z0-9
 PROVIDER_KEYS = frozenset((*CLAUDE_API_KEYS, *CLAUDE_SUBSCRIPTION, *CODEX_API_KEYS,
                            "GEMINI_API_KEY", "GOOGLE_API_KEY"))
 REVIEW_TIMEOUT = 1200.0
+FIRST_RUN_WAIT = 20.0    # how long a new claude supervisor's pane is watched for a first-run screen
+# An API error Claude Code retries itself (429, 5xx, overloaded) ends the run
+# only once a pane has shown it this long; one it won't retry, at once.
+TRANSIENT_API_ERROR_S = 120.0
+API_ERROR_MAX = 300
+SECRET_LIKE = re.compile(r"\bsk-[A-Za-z0-9_-]+|\b(?:Bearer|Basic)\s+\S+|[A-Za-z0-9_+/=-]{40,}", re.I)
 DEFAULT_PROFILE = "supervisor"
 
 
@@ -163,6 +174,11 @@ class Adapter:
 
         return agents.is_alive(root)
 
+    def stuck_screen(self, db, root) -> str | None:
+        """Why the supervisor can't make progress on its own (a screen only a
+        person answers), or None. Default: never."""
+        return None
+
     def review(self, instructions: str, cwd: str, env: Mapping[str, str], *,
                timeout: float = REVIEW_TIMEOUT, profile: str | None = None) -> Review:
         raise AdapterError(f"{self.name} can't review")
@@ -209,10 +225,41 @@ def _run(argv: list[str], cwd: str, env: Mapping[str, str], stdin: str, timeout:
     return Review(proc.stdout or "", exit=proc.returncode)
 
 
+def drop_empty_keys(env: MutableMapping[str, str]) -> list[str]:
+    """Remove Claude key variables set to an empty string from ``env`` in
+    place (a workflow's ``${{ secrets.ANTHROPIC_API_KEY }}`` when the secret
+    isn't set): an empty key still wins Claude Code's precedence, over the
+    ``ANTHROPIC_AUTH_TOKEN`` that identity federation gives the job.
+    Returns the names removed."""
+    gone = [k for k in CLAUDE_API_KEYS if k in env and not env[k]]
+    for k in gone:
+        del env[k]
+    return gone
+
+
+def claude_env(env: Mapping[str, str]) -> dict[str, str]:
+    """The environment the claude CLI runs in: ``env`` without empty key
+    variables."""
+    out = dict(env)
+    drop_empty_keys(out)
+    return out
+
+
+def api_error_line(error: str) -> str:
+    """An API error as a run's note may carry it: printable ASCII, anything
+    key- or token-like redacted, at most API_ERROR_MAX characters."""
+    text = SECRET_LIKE.sub("[redacted]", error)
+    return re.sub(r"[^\x20-\x7e]", "?", text)[:API_ERROR_MAX]
+
+
 class ClaudeAdapter(Adapter):
     name = "claude"
     cli = "claude"
 
+    def __init__(self, clock=time.monotonic) -> None:
+        self.clock = clock
+        self._api_errors: dict[str, tuple[str, float]] = {}   # agent id -> (error, first seen)
+
     def binary(self) -> str | None:
         return providers.claude_binary()
 
@@ -228,10 +275,91 @@ class ClaudeAdapter(Adapter):
             return Credential(SUBSCRIPTION, sub)
         return Credential(None, ())
 
+    @staticmethod
+    def prepare(cwd: str, env: Mapping[str, str]) -> None:
+        """Answer Claude Code's first-run screens ahead of time (a fresh
+        runner has no Claude Code state, and nobody is there to answer them),
+        trusting the checkout ``cwd``. brindle's own worktrees are trusted
+        when they're made (providers.trust_folder), now that the file exists.
+        Only on a CI runner (``GITHUB_ACTIONS`` or ``CI`` is ``"true"`` in
+        ``env``): anywhere else Claude Code's state is the person's own, and
+        is left alone."""
+        if "true" not in (env.get("GITHUB_ACTIONS"), env.get("CI")):
+            log.info("brindle ci: not on a CI runner, leaving Claude Code's state alone")
+            return
+        try:
+            providers.seed_ci_config([cwd], env.get("ANTHROPIC_API_KEY") or None)
+        except (OSError, ValueError) as e:
+            raise AdapterError(f"couldn't set up Claude Code's state: {e}") from None
+
+    def launch(self, db, ws, instructions: str, profile: str | None):
+        """Start the supervisor, then fail fast if it sits on a first-run
+        screen anyway (it would wait there for good, spending nothing)."""
+        self.prepare(ws.path, os.environ)
+        root = super().launch(db, ws, instructions, profile)
+        deadline = time.time() + FIRST_RUN_WAIT
+        while True:
+            screen = self._screen(root)
+            why = providers.ClaudeCode.first_run_screen(screen or "")
+            if why:
+                self.stop(db, root.id)
+                raise AdapterError(f"Claude Code stopped on {why}, which nobody in CI can answer")
+            if screen is None or providers.ClaudeCode.READY.search(screen) or time.time() >= deadline:
+                return root
+            time.sleep(1)
+
+    def stuck_screen(self, db, root) -> str | None:
+        """A first-run screen on the supervisor's pane, or an API error the
+        supervisor's or a reviewer's last reply ended on: at once when Claude
+        Code won't retry it, else once it has been there TRANSIENT_API_ERROR_S
+        (it would otherwise sit at its prompt, spending nothing, until the
+        server's stall timer)."""
+        from brindle import agents
+
+        screen = self._screen(root) or ""
+        why = providers.ClaudeCode.first_run_screen(screen)
+        if why:
+            return f"Claude Code is on {why}, which nobody in CI can answer"
+        panes = [("Claude Code", root, screen)]
+        if root is not None:
+            panes += [(f"reviewer {a.id}'s Claude Code", a, self._screen(a) or "")
+                      for a in agents.tree(db, root.id)
+                      if a.id != root.id and a.mode == "review" and a.provider == self.name]
+        now = self.clock()
+        for who, agent, text in panes:
+            if agent is None:
+                continue
+            error = providers.ClaudeCode.api_error(text)
+            if error is None:
+                self._api_errors.pop(agent.id, None)
+                continue
+            seen, since = self._api_errors.get(agent.id, (None, now))
+            if seen != error:
+                since = now
+            self._api_errors[agent.id] = (error, since)
+            line = api_error_line(error)
+            if providers.ClaudeCode.FATAL_API_ERROR.match(error):
+                return f"{who} stopped on an error it won't retry: {line}"
+            if now - since >= TRANSIENT_API_ERROR_S:
+                return f"{who} has been stopped on an API error for {int(now - since)}s: {line}"
+        return None
+
+    @staticmethod
+    def _screen(root) -> str | None:
+        from brindle import agents, tmux
+
+        if root is None or not getattr(root, "tmux_window", None):
+            return None
+        try:
+            return tmux.capture(root.tmux_window, lines=60, server=agents.server_of(root))
+        except tmux.TmuxError:
+            return None
+
     def review(self, instructions: str, cwd: str, env: Mapping[str, str], *,
                timeout: float = REVIEW_TIMEOUT, profile: str | None = None) -> Review:
+        self.prepare(cwd, env)
         argv = [self.binary() or "claude", "-p", "--output-format", "json"]
-        rev = _run(argv, cwd, env, instructions, timeout)
+        rev = _run(argv, cwd, claude_env(env), instructions, timeout)
         try:
             data = json.loads(rev.reply)
         except ValueError:
@@ -529,5 +657,6 @@ def format_doctor(rows: list[dict], repo: str | None, org: bool | None) -> str:
 
 __all__ = ["Adapter", "AdapterError", "ClaudeAdapter", "CodexAdapter", "Credential", "NativeAdapter",
            "Review", "default_adapters", "doctor", "format_doctor", "merge_usage", "providers_available",
-           "repo_is_org", "usable", "API_KEY", "CLOUD", "ENDPOINT", "SUBSCRIPTION"]
+           "repo_is_org", "usable", "claude_env", "drop_empty_keys", "API_KEY", "CLOUD", "ENDPOINT",
+           "SUBSCRIPTION"]