code-coordinator 0.5.46__py3-none-any.whl

coord/providers/base.py

@@ -0,0 +1,218 @@
+"""Provider abstraction layer: base ABC and Capabilities descriptor.
+
+Every worker-command backend (claude -p, hypothetical alternatives) implements
+:class:`Provider`.  Downstream code calls ``provider.build_command(spec)`` and
+``provider.initial_input(spec)`` rather than importing concrete helpers from
+``coord.agent`` directly.
+
+Re-exports :class:`~coord.worker_events.WorkerSummary` for convenience so
+callers can do ``from coord.providers.base import WorkerSummary`` without
+knowing which module originates it.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+# Re-export WorkerSummary so callers can import it from here.
+from coord.worker_events import WorkerSummary  # noqa: F401
+
+if TYPE_CHECKING:
+    from coord.agent import AssignmentSpec
+
+__all__ = ["Capabilities", "Provider", "WorkerSummary"]
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    """What a provider can actually do.
+
+    Downstream code gates features on these flags instead of silently
+    degrading when a provider doesn't support them.
+
+    Attributes:
+        resume: Supports session resume (``--resume``) → gates chat-continue
+            (#315).
+        inject: Supports mid-session stdin message injection → gates
+            ``inject_message``.
+        cost_reporting: Emits per-run cost in the log → TUI shows a dollar
+            figure rather than "n/a".
+        true_system_prompt: Honours a real ``--system-prompt`` flag rather
+            than prepending the prompt text to the first user message.
+        enforces_deny_list: SAFETY — honours the worker deny-list and tool
+            restrictions.  Providers that ignore ``--allowedTools`` / deny
+            prompts must set this to ``False`` so the coordinator can warn.
+        billing_mode: How runs of this provider are billed.  One of
+            ``"subscription"`` (covered by a fixed-price plan, e.g.
+            interactive Claude Code on Max/Pro), ``"metered"`` (billed
+            per-token at API rates, e.g. ``claude -p`` after the
+            2026-06-15 metering change), ``"byo_key"`` (uses the
+            operator's own API key — cost is theirs), or ``"unknown"``
+            for backends whose billing the coordinator can't infer.  This
+            is the Track-3 routing signal for the June-15 metering
+            mitigation (#322): the coordinator and TUI prefer a
+            non-metered backend when one is available.
+        human_attended_only: STRUCTURAL TOS-COMPLIANCE GATE (#437).  When
+            ``True``, this provider may NEVER be selected for unattended
+            dispatch — the coordinator refuses to route ``coord plan`` /
+            ``coord approve`` / auto-review / auto-reassign /
+            reconciliation through it.  Used for subscription-billed
+            interactive backends (e.g. :class:`ClaudePtyProvider`) where
+            running unsupervised would violate Anthropic ToS §3.7
+            (no headless / agentic use of subscription Claude Code).
+            The default is ``False`` — a new provider is automatable
+            unless it explicitly opts out (fail-safe: a metered backend
+            is safe to gate behind nothing; an interactive subscription
+            backend must opt out).  Workers run via this provider must
+            be launched into a human-attended terminal by ``coord assign
+            --interactive`` and HUMAN-CLOSED; no coordinator-side
+            completion-sentinel watching, no auto-termination on output,
+            no parsing of the TTY to advance pipeline state.
+    """
+
+    resume: bool
+    inject: bool
+    cost_reporting: bool
+    true_system_prompt: bool
+    enforces_deny_list: bool
+    billing_mode: str
+    human_attended_only: bool = False
+
+
+class Provider(ABC):
+    """Abstract base class for worker-command providers.
+
+    A provider knows how to:
+    * Build the argv for spawning the worker subprocess (``build_command``).
+    * Produce the initial stdin payload (``initial_input``).
+    * Report what capabilities it actually has (``capabilities``).
+    * Identify a successful run in the log (``result_marker``).
+    * Declare extra environment variables (``env``).
+    * Parse a completed log file (``parse_log``).
+
+    The concrete ``supports_inject()`` method is derived from
+    ``capabilities().inject`` to keep them in sync — subclasses should
+    *not* override it.
+    """
+
+    @abstractmethod
+    def build_command(
+        self,
+        spec: "AssignmentSpec",
+        *,
+        resolved_model: str | None = None,
+        system_prompt: str | None = None,
+        allowed_tools: str | None = None,
+        permission_mode: str = "acceptEdits",
+    ) -> list[str]:
+        """Build the worker subprocess argv for *spec*.
+
+        Args:
+            spec: The assignment spec being dispatched.
+            resolved_model: The resolved model identifier to pass (e.g.
+                ``"claude-sonnet-4-6"`` after alias expansion).  ``None``
+                falls back to provider-internal defaults (``spec.model`` for
+                :class:`ClaudeProvider`).
+            system_prompt: Override the system prompt.  ``None`` means the
+                provider computes one from ``spec.type``.
+            allowed_tools: Override the ``--allowedTools`` value.  ``None``
+                means the provider computes one from ``spec.type``.
+            permission_mode: Override the ``--permission-mode`` value.
+                Defaults to ``"acceptEdits"``.
+        """
+        ...
+
+    @abstractmethod
+    def initial_input(self, spec: "AssignmentSpec") -> bytes:
+        """Return the first stdin payload written to the worker process.
+
+        For stream-json workers this is the JSON-encoded user message
+        containing the briefing text.
+        """
+        ...
+
+    def supports_inject(self) -> bool:
+        """Whether this provider supports mid-session message injection.
+
+        Derived from ``capabilities().inject`` — never let the two disagree.
+        Override ``capabilities()`` to change this; do not override
+        ``supports_inject()`` directly.
+        """
+        return self.capabilities().inject
+
+    @abstractmethod
+    def result_marker(self) -> str:
+        """Return a string whose presence in the log signals job completion.
+
+        The coordinator reads the log in binary mode so callers are
+        responsible for encoding this value when comparing against raw bytes.
+        """
+        ...
+
+    @abstractmethod
+    def env(self) -> dict[str, str]:
+        """Extra environment variables to set for the worker subprocess.
+
+        Merged on top of the base environment in the spawn path.  Return an
+        empty dict when no extra variables are needed.
+        """
+        ...
+
+    @abstractmethod
+    def parse_log(
+        self, log_path: str | Path, tail_bytes: int = 65536
+    ) -> WorkerSummary:
+        """Parse a worker log file and return a rolling summary.
+
+        Args:
+            log_path: Path to the worker's log file.
+            tail_bytes: When > 0, only the last *tail_bytes* of the file is
+                read (cheap live-polling).  Pass ``0`` for a full parse.
+        """
+        ...
+
+    @abstractmethod
+    def capabilities(self) -> Capabilities:
+        """Return a descriptor of what this provider can actually do."""
+        ...
+
+    @abstractmethod
+    def oneshot_command(
+        self,
+        *,
+        system_prompt: str,
+        output_format: str | None = "json",
+    ) -> list[str]:
+        """Return the argv for a non-looping, one-shot prompt call.
+
+        This is distinct from :meth:`build_command`, which produces the
+        streaming worker command (``--input-format stream-json``, etc.).
+        One-shot calls are used by coordinator-side code — brain planning
+        and the dashboard assistant — that needs a single prompt/response
+        round, not a full streaming worker session.
+
+        The caller is responsible for piping the user message via *stdin*
+        (for :class:`~.claude.ClaudeProvider`).  Providers where stdin
+        delivery is not applicable (e.g.
+        :class:`~.opencode.OpenCodeProvider`) silently ignore the user
+        message and the *output_format* kwarg; callers should document
+        that the one-shot path is best-effort for those backends.
+
+        Args:
+            system_prompt: The system prompt for the call.
+            output_format: Requested output format.  ``"json"`` asks for a
+                structured JSON response (as the brain expects);
+                ``None`` omits any output-format flag so the backend
+                streams plain text (used by the dashboard assistant).
+                Providers that do not support the requested format
+                silently ignore this kwarg.
+
+        Returns:
+            A list of strings suitable for passing to
+            :func:`subprocess.run` or
+            :func:`asyncio.create_subprocess_exec`.
+        """
+        ...

coord/providers/claude.py

@@ -0,0 +1,284 @@
+"""ClaudeProvider: the ``claude -p`` concrete provider.
+
+Parity requirement: ``ClaudeProvider().build_command(spec)`` produces the
+**same argv** as ``coord.agent.default_worker_command(spec)`` for the same
+inputs.  The logic is a direct transcription of that function's body with
+the ``resolved_model`` / ``system_prompt`` / ``allowed_tools`` /
+``permission_mode`` kwargs spliced in; the parity tests in
+``tests/test_providers.py`` enforce this mechanically.
+
+Imports from ``coord.agent`` are **deferred** (inside method bodies) to keep
+the import cycle latent until the wiring issue lands.  At that point
+``AgentServer`` will consume ``ClaudeProvider``, creating a two-way link;
+until then the one-way ``claude → agent`` direction is safe because
+``coord.agent`` does not import from ``coord.providers``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from coord.providers.base import Capabilities, Provider, WorkerSummary
+
+if TYPE_CHECKING:
+    from coord.agent import AssignmentSpec
+
+
+class ClaudeProvider(Provider):
+    """Concrete provider for ``claude -p`` (Anthropic Claude Code workers).
+
+    This is the **reference backend** — all :class:`~.base.Capabilities`
+    flags are ``True`` because ``claude -p`` supports every feature the
+    coordinator relies on.
+
+    Args:
+        binary: Override the worker binary name/path.  ``None`` falls back to
+            :data:`coord.agent.DEFAULT_WORKER_BINARY` (``"claude"``).
+        model: Fallback model id/alias from the provider definition
+            (``ProviderDef.model``).  Used only when neither an explicit
+            ``resolved_model`` nor ``spec.model`` is set — see
+            :meth:`build_command`.
+        env: Extra environment variables from the provider definition
+            (``ProviderDef.env``, already ``${VAR}``-expanded by config
+            parsing).  Returned verbatim by :meth:`env`.
+        extra_args: Additional argv entries from the provider definition
+            (``ProviderDef.extra_args``).  Appended to the end of the argv
+            built by :meth:`build_command`.
+    """
+
+    def __init__(
+        self,
+        binary: str | None = None,
+        *,
+        model: str | None = None,
+        env: dict[str, str] | None = None,
+        extra_args: list[str] | None = None,
+    ) -> None:
+        self._binary = binary
+        self._model = model
+        self._env = dict(env) if env else {}
+        self._extra_args = list(extra_args) if extra_args else []
+
+    # ── Capabilities ──────────────────────────────────────────────────────────
+
+    def capabilities(self) -> Capabilities:
+        """All capabilities enabled — claude -p is the reference backend.
+
+        ``billing_mode="metered"`` reflects the 2026-06-15 Anthropic
+        change: ``claude -p`` (and Agent SDK) sessions are billed at full
+        API rates against a small non-rolling credit pool, not against
+        the Max/Pro subscription.  Downstream code uses this flag to
+        prefer a non-metered backend when one is available (#322).
+        """
+        return Capabilities(
+            resume=True,
+            inject=True,
+            cost_reporting=True,
+            true_system_prompt=True,
+            enforces_deny_list=True,
+            billing_mode="metered",
+            # #437: claude -p is an unattended/headless backend — billed
+            # per-token and intended for autonomous dispatch.  This is the
+            # COMPLIANT automatable path and must NOT be flagged as
+            # human-attended.  Set explicitly (not by default) to make the
+            # intent visible in code.
+            human_attended_only=False,
+        )
+
+    # ── Core methods ──────────────────────────────────────────────────────────
+
+    def build_command(  # noqa: PLR0912  (many spec.type branches, matches legacy)
+        self,
+        spec: "AssignmentSpec",
+        *,
+        resolved_model: str | None = None,
+        system_prompt: str | None = None,
+        allowed_tools: str | None = None,
+        permission_mode: str = "acceptEdits",
+    ) -> list[str]:
+        """Build the ``claude -p`` argv for *spec*.
+
+        Produces the **same argv** as ``default_worker_command(spec)`` when
+        called with ``resolved_model=spec.model`` and without overriding
+        ``system_prompt`` / ``allowed_tools`` / ``permission_mode``.
+        """
+        # Deferred import — keeps the cycle latent until wiring is done.
+        from coord.agent import (  # noqa: PLC0415
+            DEFAULT_WORKER_BINARY,
+            MILESTONE_CHAT_DENY_COMMANDS,
+            MILESTONE_CHAT_SYSTEM_PROMPT,
+            MOCK_AUTHOR_DENY_COMMANDS,
+            MOCK_AUTHOR_SYSTEM_PROMPT,
+            NEW_ISSUE_CHAT_DENY_COMMANDS,
+            NEW_ISSUE_CHAT_SYSTEM_PROMPT,
+            REFINEMENT_SYSTEM_PROMPT,
+            TEST_CHAT_SYSTEM_PROMPT,
+            WORKER_PLAN_PROMPT,
+            WORKER_SYSTEM_PROMPT,
+            _base_checkout_write_guard_tools,
+            _sealed_write_guard_tools,
+            build_deny_prompt,
+        )
+
+        binary = self._binary if self._binary is not None else DEFAULT_WORKER_BINARY
+
+        # Precedence: explicit resolved_model > spec.model > provider-
+        # definition model (ProviderDef.model, threaded in via __init__).
+        # A plain ClaudeProvider().build_command(spec) with no definition
+        # model still matches default_worker_command (self._model is None).
+        if resolved_model is not None:
+            effective_model = resolved_model
+        elif spec.model is not None:
+            effective_model = spec.model
+        else:
+            effective_model = self._model
+
+        # Compute system_prompt / allowed_tools from spec.type when not
+        # provided — direct transcription of default_worker_command's logic.
+        if system_prompt is None or allowed_tools is None:
+            if spec.type == "plan":
+                _sp = spec.system_prompt if spec.system_prompt else WORKER_PLAN_PROMPT
+                _at = "Read,Bash"
+            elif spec.type == "refinement":
+                _sp = spec.system_prompt if spec.system_prompt else REFINEMENT_SYSTEM_PROMPT
+                _at = "Read"
+            elif spec.type == "test-chat":
+                _sp = spec.system_prompt if spec.system_prompt else TEST_CHAT_SYSTEM_PROMPT
+                _sp += build_deny_prompt(spec.deny_commands)
+                _at = "Read,Bash"
+            elif spec.type == "new-issue-chat":
+                _sp = spec.system_prompt if spec.system_prompt else NEW_ISSUE_CHAT_SYSTEM_PROMPT
+                _sp += build_deny_prompt(NEW_ISSUE_CHAT_DENY_COMMANDS)
+                if spec.new_issue_guidance:
+                    _sp += (
+                        "\n\nThe user's repo has the following guidance for "
+                        "new-issue drafts. Follow it: ask focused questions "
+                        "matched to the required sections, then produce a "
+                        "finalised issue body using the same structure. Do not "
+                        "invent sections that aren't there; do not omit required "
+                        "sections (mark them `(TBD)` if the conversation hasn't "
+                        "covered them yet).\n\n"
+                        + spec.new_issue_guidance
+                    )
+                _at = "Read,Bash"
+            elif spec.type == "milestone-chat":
+                _sp = spec.system_prompt if spec.system_prompt else MILESTONE_CHAT_SYSTEM_PROMPT
+                _sp += build_deny_prompt(MILESTONE_CHAT_DENY_COMMANDS)
+                _at = "Read,Bash"
+            elif spec.type == "mock-author":
+                _sp = spec.system_prompt if spec.system_prompt else MOCK_AUTHOR_SYSTEM_PROMPT
+                _sp += build_deny_prompt(MOCK_AUTHOR_DENY_COMMANDS)
+                _at = "Read,Edit,Write,Bash"
+            else:
+                _sp = spec.system_prompt if spec.system_prompt else WORKER_SYSTEM_PROMPT
+                _sp += build_deny_prompt(spec.deny_commands)
+                _at = "Read,Edit,Write,Bash"
+
+            if system_prompt is None:
+                system_prompt = _sp
+            if allowed_tools is None:
+                allowed_tools = _at
+
+        argv: list[str] = [
+            binary, "-p",
+            "--input-format", "stream-json",
+            "--output-format", "stream-json",
+            "--verbose",
+            "--system-prompt", system_prompt,
+            "--allowedTools", allowed_tools,
+            "--permission-mode", permission_mode,
+            # #1445: see the matching comment in default_worker_command —
+            # workers must not inherit the host checkout's project/local
+            # Claude Code settings.
+            "--setting-sources", "user",
+        ]
+        if effective_model:
+            argv.extend(["--model", effective_model])
+        # #1315 / #1642: same structural write guards as
+        # default_worker_command — sealed-oracle prefix plus (for any type
+        # with Edit in --allowedTools) the shared base checkout.
+        disallowed_tools = _sealed_write_guard_tools(spec.files_forbidden)
+        if "Edit" in allowed_tools:
+            for pattern in _base_checkout_write_guard_tools(spec.repo_path):
+                if pattern not in disallowed_tools:
+                    disallowed_tools.append(pattern)
+        if disallowed_tools:
+            argv.extend(["--disallowedTools", ",".join(disallowed_tools)])
+        if spec.resume_session_id:
+            argv.extend(["--resume", spec.resume_session_id])
+        # #1706: provider-definition extra_args go last, after every flag
+        # this method itself constructs.
+        if self._extra_args:
+            argv.extend(self._extra_args)
+        return argv
+
+    def oneshot_command(
+        self,
+        *,
+        system_prompt: str,
+        output_format: str | None = "json",
+    ) -> list[str]:
+        """Build the argv for a one-shot ``claude -p`` call.
+
+        Returns ``[binary, "-p", "--system-prompt", system_prompt]`` plus
+        ``["--output-format", output_format]`` when *output_format* is
+        non-``None``.
+
+        Unlike :meth:`build_command`, this does **not** add
+        ``--input-format stream-json``, ``--verbose``,
+        ``--allowedTools``, or ``--permission-mode`` — those flags are
+        only meaningful for streaming worker sessions.
+
+        The user message is expected to arrive via *stdin* (the caller
+        passes ``input=`` to :func:`subprocess.run` or writes to
+        ``proc.stdin`` in the async path).
+
+        Note: unlike :meth:`build_command`, this does **not** thread in
+        ``self._model`` / ``self._extra_args`` / ``self._env`` (#1706) —
+        oneshot calls (brain planning, dashboard assistant) don't take an
+        ``AssignmentSpec`` and sit outside the assignment spawn path that
+        #1706 wires provider-definition config into. A future reader
+        should not assume oneshot calls honour ``providers.definitions.
+        <name>.{model,extra_args,env}``.
+
+        Args:
+            system_prompt: The system prompt for the one-shot call.
+            output_format: Output format flag value.  ``"json"`` produces
+                ``--output-format json`` (brain planning expects this so
+                it can extract the ``result`` field from the outer JSON
+                object).  ``None`` omits the flag (dashboard assistant
+                streams the raw text response line-by-line).
+        """
+        from coord.agent import DEFAULT_WORKER_BINARY  # noqa: PLC0415
+        binary = self._binary if self._binary is not None else DEFAULT_WORKER_BINARY
+        cmd = [binary, "-p", "--system-prompt", system_prompt]
+        if output_format is not None:
+            cmd.extend(["--output-format", output_format])
+        return cmd
+
+    def initial_input(self, spec: "AssignmentSpec") -> bytes:
+        """Return the briefing encoded as a stream-json user message."""
+        from coord.agent import _user_message_line  # noqa: PLC0415
+        return _user_message_line(spec.briefing)
+
+    def result_marker(self) -> str:
+        """String whose presence in the log signals logical completion."""
+        return '"type":"result"'
+
+    def env(self) -> dict[str, str]:
+        """Extra environment variables from the provider definition (#1706).
+
+        Returns a copy of ``ProviderDef.env`` (already ``${VAR}``-expanded
+        by config parsing) threaded in via ``__init__``.  Empty dict when
+        the provider was constructed with no ``env`` (matches pre-#1706
+        behaviour for no-config deployments).
+        """
+        return dict(self._env)
+
+    def parse_log(
+        self, log_path: str | Path, tail_bytes: int = 65536
+    ) -> WorkerSummary:
+        """Delegate to :func:`coord.worker_events.parse_log`."""
+        from coord.worker_events import parse_log  # noqa: PLC0415
+        return parse_log(log_path, tail_bytes=tail_bytes)