Skip to content

Self-improving AI Employees for everyone

24.2 KB
Raw Blame
"""Anthropic Claude Code CLI provider — stream-json over stdio pipes.

Reference implementation for the `AICliProvider` Protocol. OpenCompany
spawns ``claude`` as a plain subprocess with piped stdin/stdout/stderr
(``ClaudeSessionPool``) and speaks the CLI's stream-json protocol: one
``{"type":"user","message":{...}}`` line per turn on stdin, one JSON
event per line on stdout, ending each turn with ``type == "result"``.
No PTY, no on-disk JSONL parsing. See
``docs-internal/claude_code_interactive_mode.md``.

Subprocess: ``claude --output-format stream-json --input-format
stream-json --verbose --ide [--mcp-config ...] [--strict-mcp-config]
--model <m> [--resume <UUID> | --continue | --session-id <UUID>]
[--allowedTools <list>] --permission-mode <mode>
[--append-system-prompt ...] [--effort ...] [--add-dir ...]
[--disallowedTools ...] [--agent ...]``

**Tools + skills are preserved**:
  - ``--mcp-config`` registers OpenCompany's FastMCP server; the spawned
    `claude` discovers `mcp__opencompany__*` tools via `tools/list`.
  - ``--allowedTools`` carries the explicit allowlist (every wired MCP
    tool + OpenCompany's MCP infrastructure tools; Claude built-ins only
    when a task opts them in, except ``Skill`` when a skill is wired).
  - Skills are materialised under ``<workspace_dir>/.claude/skills/``
    (discovered through ``--add-dir <workspace_dir>``) by the shared
    :func:`nodes.agent.claude_code_agent._skills.materialise_skills`
    helper, called from ``ClaudeSessionPool._spawn`` and
    ``ClaudeSessionPool._prepare_warm_reuse``; ``Skill`` enters
    ``--allowedTools`` iff at least one skill is wired.

**Permission mode**: ``dontAsk`` (the config default) never shows a
prompt: a call that would prompt is denied instead, unless it matches
``--allowedTools``. Per ``code.claude.com/docs/en/permission-modes``,
read-only Bash commands still run without a matching rule.
``--allowedTools`` pre-approves tools; it does not remove Claude's
other built-ins from the model's context (that is ``--tools`` /
``--disallowedTools``, neither emitted by default), so the model can
still call them and gets a denial.

Session identity: a cold spawn with no continuity flag gets a
host-minted ``--session-id <UUID>`` (``ClaudeSessionPool._spawn``) so the
UUID is known before the first event; memory-bound runs and crash
recovery pass ``--resume <UUID>``. ``--continue`` is kept on the spec
for callers that ask for it, but the CLI resolves it only against
interactive sessions, so the node never sets it.

Not emitted: ``-p`` / ``--print`` (the Agent SDK does not pass it
either), ``--include-partial-messages``, ``--include-hook-events``,
``--max-turns``, ``--max-budget-usd``, ``--fallback-model`` (print-mode
only; the spec keeps the fields for back-compat), and a positional
prompt (the prompt travels over stdin).

Binary + auth: shared with the auth surface via
``._oauth.claude_binary_path()`` — single managed install of the pinned
``package_version`` under ``<DATA_DIR>/packages/`` and
``CLAUDE_CONFIG_DIR`` set on the spawn env so the agent picks up the
same credentials the Login button wrote.

Final event: ``type == "result"`` on stdout carries ``total_cost_usd``,
``duration_ms``, ``num_turns``, ``session_id``, ``usage`` and the
assistant's ``result`` string. It is stdout-only — the on-disk session
JSONL never contains it — so completion is detected from the stream.
"""

from __future__ import annotations

import json
from pathlib import Path
from typing import Any, Dict, List, Optional

from core.logging import get_logger

from services.cli_agent.config import get_provider_config
from ._oauth import claude_binary_path, OPENCOMPANY_CLAUDE_DIR
from services.cli_agent.protocol import CanonicalUsage
from services.cli_agent.types import ClaudeTaskSpec

logger = get_logger(__name__)

NAME = "claude"


class AnthropicClaudeProvider:
    """`AICliProvider` for Anthropic's Claude Code CLI."""

    def __init__(self) -> None:
        cfg = get_provider_config(NAME)
        if cfg is None:
            raise RuntimeError(f"Provider config missing for {NAME!r}. Check ai_cli_providers.json.")
        self.name = NAME
        self.package_name = cfg.package_name
        self.binary_name = cfg.binary_name
        self.ide_lock_env_var = cfg.ide_lock_env_var
        # IDE lockfile dir: ``<CLAUDE_CONFIG_DIR>/ide/`` per claude's own
        # resolution rules — there is no separate "lockfile path" knob.
        # We set ``CLAUDE_CONFIG_DIR=OPENCOMPANY_CLAUDE_DIR`` on every
        # spawn (``AICliService._run_pooled_turn``, ``_oauth.py``), so
        # the dir is ``OPENCOMPANY_CLAUDE_DIR/ide``. The pool path writes
        # NO lockfile here (MCP connects through ``--mcp-config``); only
        # the generic ``AICliSession._pre_spawn``, which claude no longer
        # uses, writes one. The attribute stays for the Protocol and for
        # the startup stale-lockfile sweep in ``main.py``.
        # ``OPENCOMPANY_CLAUDE_DIR`` is imported at module top from
        # ``_oauth`` (the source of truth for this plugin's layout).
        self.ide_lockfile_dir = OPENCOMPANY_CLAUDE_DIR / "ide"
        self._defaults = cfg.defaults
        self._supports = cfg.supports
        self._login_argv = cfg.login_argv
        self._auth_status_argv = cfg.auth_status_argv

    # ---- spawn surface ---------------------------------------------------

    def binary_path(self) -> Path:
        """Resolve the project-local `claude` binary.

        Delegates to ``._oauth.claude_binary_path`` — same
        path used by the credentials Login button. Lazy-installs into
        ``<DATA_DIR>/packages/`` with ``bun add`` on first miss. Raises
        ``RuntimeError`` if bun is missing or the install fails, and
        ``FileNotFoundError`` if the binary is still absent afterwards.
        """
        return Path(claude_binary_path())

    def interactive_argv(
        self,
        task: Any,  # ClaudeTaskSpec
        *,
        defaults: Dict[str, Any],
        mcp_endpoint_url: Optional[str] = None,
        mcp_bearer_token: Optional[str] = None,
        connected_tool_names: Optional[List[str]] = None,
        connected_skill_names: Optional[List[str]] = None,
        include_prompt: bool = True,
    ) -> List[str]:
        """Build the full argv for one ``claude`` invocation, VSCode-style.

        Spawned as a regular subprocess with stdio pipes — NOT a PTY.
        Matches the invocation Anthropic's own VSCode extension uses
        (read from ``$VSCODE_EXT_DIR/anthropic.claude-code-2.1.140-<platform>/extension.js``
        line 156):

          ``claude --output-format stream-json --input-format stream-json
          --verbose --ide [task-flags...]``

        User prompts arrive over ``proc.stdin`` as newline-delimited JSON
        of shape ``{"type":"user","message":{"role":"user","content":...}}``,
        not as an argv positional. Events stream back on ``proc.stdout``
        and are parsed there by ``ClaudeSessionPool``; the on-disk
        session JSONL is not read at runtime (the ``result`` event is
        stdout-only).

        Critically NOT emitted:

          - ``-p`` / ``--print``: the VSCode extension drives the CLI
            without it. The expectation that this keeps usage in the
            interactive billing bucket (entrypoint ``claude-vscode``,
            not ``sdk-cli``) is unverified: nothing here checks the
            entrypoint the CLI reports.
          - The positional prompt (``-- "<prompt>"``): the prompt
            arrives via ``proc.stdin`` in stream-json input mode.
            ``include_prompt`` is kept for back-compat but ignored.

        ``mcp_endpoint_url`` + ``mcp_bearer_token`` (if both set) are
        emitted as ``--mcp-config <json>`` so the spawned claude
        registers OpenCompany's FastMCP server. Tools allowlist
        (``--allowedTools``) lists every wired ``mcp__opencompany__*``
        plus OpenCompany's MCP infrastructure tools, the built-in
        ``Skill`` only when a skill is wired, and any built-ins the task's
        ``allowed_tools`` opts in. Skills are materialised under
        ``<workspace_dir>/.claude/skills/`` by the pool before spawn.
        """
        if not isinstance(task, ClaudeTaskSpec):
            raise TypeError("AnthropicClaudeProvider.interactive_argv requires ClaudeTaskSpec, " f"got {type(task).__name__}")

        argv: List[str] = [str(self.binary_path())]

        # Stream-json I/O — the VSCode extension pattern. Prompts go via
        # ``proc.stdin``, events come back on ``proc.stdout``. Verified
        # against
        # ``$VSCODE_EXT_DIR/anthropic.claude-code-<ver>/extension.js:156``
        # which spawns claude with exactly these four flags. ``--verbose``
        # is required so the stream-json output includes the full event
        # detail (without it, only the final result line is emitted).
        # ``--ide`` is kept to match the extension's invocation, but the
        # pool path writes no IDE lockfile and sets no ``CLAUDE_IDE_LOCK``,
        # so there is nothing for it to discover: OpenCompany's MCP
        # server is registered only through ``--mcp-config`` below.
        argv += [
            "--output-format",
            "stream-json",
            "--input-format",
            "stream-json",
            "--verbose",
            "--ide",
        ]

        # MCP server registration — same shape as the prior headless
        # path; the Claude Code MCP doc's ``mcp.json`` example. Works
        # identically in interactive mode.
        if mcp_endpoint_url and mcp_bearer_token:
            # `alwaysLoad: true` opts this server out of MCP tool-search
            # deferral so all `mcp__opencompany__*` tools enter context at
            # session start instead of waiting for a `ToolSearch` call
            # the agent often doesn't make
            # (https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search).
            mcp_payload = json.dumps(
                {
                    "mcpServers": {
                        "opencompany": {
                            "type": "http",
                            "url": mcp_endpoint_url,
                            "headers": {
                                "Authorization": f"Bearer {mcp_bearer_token}",
                            },
                            "alwaysLoad": True,
                        }
                    }
                }
            )
            argv += ["--mcp-config", mcp_payload, "--strict-mcp-config"]

        # Model
        model = task.model or defaults.get("default_model") or self._defaults.get("default_model", "claude-sonnet-4-6")
        argv += ["--model", model]

        # Session continuity. Three flags, mutually exclusive, in this
        # precedence order:
        #   - ``resume_session_id`` set → ``--resume <UUID>``. Memory-bound
        #     runs set it from the memory node's ``last_session_id``
        #     (``ClaudeCodeAgentNode.execute_op``); the pool splices it in
        #     when respawning a crashed session (``ClaudeSessionPool.acquire``).
        #   - ``continue_session=True`` → ``--continue``. Kept only for
        #     explicit callers; the node never sets it, because the CLI
        #     resolves ``--continue`` only against interactively created
        #     sessions and so never finds the ones this pool creates.
        #   - ``session_id`` set → ``--session-id <UUID>`` (host-minted
        #     on cold spawn by ``ClaudeSessionPool._spawn`` so the UUID
        #     is known before the first event; the CLI requires a valid
        #     UUID and rejects one that is already in use).
        #   - None of the three → no flag; claude assigns its own UUID,
        #     reported on ``system/init``.
        if task.resume_session_id:
            argv += ["--resume", task.resume_session_id]
        elif task.continue_session:
            argv += ["--continue"]
        elif task.session_id:
            argv += ["--session-id", task.session_id]

        # Allowed tools — pre-approves what the operator wired through
        # ``input-tools`` plus OpenCompany's own MCP infrastructure
        # tools. Claude's built-in escape hatches (Read, Edit, Bash,
        # Glob, Grep, Write, Skill, WebSearch, WebFetch) are intentionally
        # NOT pre-approved (they stay in the model's context, since this
        # flag does not remove tools; under ``dontAsk`` calling them is
        # denied, except read-only Bash commands, which the CLI runs
        # anyway): they let the agent invoke
        # capabilities the workflow didn't explicitly grant — equivalent
        # filesystem / shell / search functionality is wired via the
        # ``fileRead`` / ``fileModify`` / ``fsSearch`` / ``shell`` /
        # ``browser`` / ``perplexitySearch`` workflow tools. The one
        # exception is ``Skill``, added below only when a skill is wired
        # (connected skills are also reachable through OpenCompany's
        # ``listSkills`` / ``getSkill`` MCP tools).
        #
        # Callers can opt specific claude built-ins back in per-task
        # via ``ClaudeTaskSpec.allowed_tools`` if they really need them
        # (the field is honored verbatim; no auto-merge with workflow
        # tools — explicit is better than implicit).
        allowed_extra = task.allowed_tools or defaults.get(
            "default_allowed_tools",
            self._defaults.get("default_allowed_tools", ""),
        )
        allowed_list: List[str] = [t.strip() for t in allowed_extra.split(",") if t.strip()] if allowed_extra else []
        if connected_tool_names:
            allowed_list += [f"mcp__opencompany__{name}" for name in connected_tool_names]
        # Conditionally enable claude's built-in ``Skill`` tool ONLY
        # when at least one skill is wired through ``input-skill``.
        # ``ClaudeSessionPool`` materialises connected SKILL.md files
        # under ``<workspace_dir>/.claude/skills/`` (reached through
        # ``--add-dir``) via the shared
        # :func:`nodes.agent.claude_code_agent._skills.materialise_skills`
        # helper, so the built-in skill loader has something to
        # discover. Skills accessed by name (`Skill <name>`) load
        # those materialised files. If no skill is wired, ``Skill``
        # stays disabled — strict allowlist invariant holds (see
        # ``test_no_claude_builtins_in_default_allowlist``).
        if connected_skill_names:
            allowed_list.append("Skill")
        # OpenCompany's own MCP infrastructure tools — needed for the
        # agent to discover connected skills, read its workspace, and
        # surface intermediate progress. These are OUR tools, not
        # claude's, so they stay regardless.
        allowed_list += [
            "mcp__opencompany__getWorkspaceFiles",
            "mcp__opencompany__listSkills",
            "mcp__opencompany__getSkill",
            "mcp__opencompany__readSkillResource",
            "mcp__opencompany__searchSkillResource",
            "mcp__opencompany__getCredential",
            "mcp__opencompany__broadcastLog",
        ]
        if allowed_list:
            argv += ["--allowedTools", ",".join(allowed_list)]

        # Permission mode — ``dontAsk`` is the documented mode for
        # "only pre-approved tools, no prompts"
        # (https://code.claude.com/docs/en/permission-modes): a call that
        # would prompt is denied instead, unless ``--allowedTools``
        # matches it; read-only Bash commands still run. The prior
        # ``bypassPermissions`` default "skips the permission layer
        # entirely" — meaning ``--allowedTools`` and
        # ``--disallowedTools`` become documentation-only and claude's
        # built-in Read / Edit / Bash / Glob / Grep / Write / Skill /
        # WebSearch / WebFetch remain invocable even when not in the
        # allowlist. ``acceptEdits`` would prompt for non-Edit tools,
        # hanging the headless agent. ``dontAsk`` is the middle: no
        # prompts, and a denial for anything not pre-approved (apart
        # from read-only Bash). Per-task override still honoured.
        perm = task.permission_mode or defaults.get(
            "default_permission_mode",
            self._defaults.get("default_permission_mode", "dontAsk"),
        )
        if perm:
            argv += ["--permission-mode", perm]

        # System prompt — appended to Claude Code's built-in system prompt
        if task.system_prompt:
            argv += ["--append-system-prompt", task.system_prompt]
            logger.info(
                "[CC-Agent argv] --append-system-prompt (task) " "length=%d preview=%r",
                len(task.system_prompt),
                task.system_prompt[:200],
            )

        # Optional per-task overrides (work in interactive mode per
        # code.claude.com/docs/en/cli-reference). ``--max-turns``,
        # ``--max-budget-usd``, ``--fallback-model`` are ``-p``-only and
        # not emitted; the task spec keeps the fields for back-compat
        # but they're silently dropped here.
        if task.effort:
            argv += ["--effort", task.effort]
        for path in task.add_dir:
            argv += ["--add-dir", path]
        if task.disallowed_tools:
            argv += ["--disallowedTools", task.disallowed_tools]
        if task.agent:
            argv += ["--agent", task.agent]

        # Prompt arrives via ``proc.stdin`` as stream-json — NOT as
        # an argv positional. ``include_prompt`` is kept on the signature
        # for back-compat (older callers pass ``include_prompt=False``)
        # but is ignored: stream-json input mode and a positional prompt
        # would double-send the first turn. Caller writes prompts to
        # ``ClaudeSessionPool.send_turn``'s ``proc.stdin`` instead.
        _ = include_prompt

        return argv

    # ---- native auth -----------------------------------------------------

    def login_argv(self) -> List[str]:
        return list(self._login_argv) or ["claude", "login"]

    def auth_status_argv(self) -> Optional[List[str]]:
        return list(self._auth_status_argv) if self._auth_status_argv else None

    def detect_auth_error(self, stderr: str, exit_code: int) -> bool:
        """True if stderr/exit_code indicate the user isn't logged in."""
        if not stderr and exit_code == 0:
            return False
        markers = (
            "Please run 'claude login'",
            "Please run `claude login`",
            "Not authenticated",
            "Authentication required",
            "401 Unauthorized",
            "Invalid API key",
        )
        return any(m in stderr for m in markers)

    # ---- streaming output parsing ---------------------------------------

    def parse_event(self, line: str) -> Optional[Dict[str, Any]]:
        line = line.strip()
        if not line:
            return None
        try:
            return json.loads(line)
        except json.JSONDecodeError:
            return None

    def is_final_event(self, event: Dict[str, Any]) -> bool:
        return event.get("type") == "result"

    def event_to_session_result(
        self,
        events: List[Dict[str, Any]],
        stderr: str,
        exit_code: int,
    ) -> Dict[str, Any]:
        """Reconstruct shared result fields from the event stream."""
        final = next(
            (e for e in reversed(events) if e.get("type") == "result"),
            None,
        )

        # Session ID can come from `system.init` or `result`
        session_id: Optional[str] = None
        for evt in events:
            sid = evt.get("session_id")
            if sid:
                session_id = sid
                break

        tool_calls = sum(
            1 for evt in events if evt.get("type") == "tool_use" or (evt.get("type") == "assistant" and self._has_tool_use(evt))
        )

        provider_data: Dict[str, Any] = {}
        for evt in events:
            if evt.get("type") == "assistant":
                msg = evt.get("message") or {}
                rd = msg.get("reasoning_details") or msg.get("thinking")
                if rd is not None:
                    provider_data.setdefault("reasoning_details", rd)
                    break

        success = exit_code == 0 and final is not None
        error: Optional[str] = None
        if exit_code != 0:
            error = stderr.strip()[-2000:] or f"claude exited with code {exit_code}"
        elif final is None:
            error = "no result event received"

        response = ""
        cost: Optional[float] = None
        duration_ms: Optional[int] = None
        num_turns: Optional[int] = None
        if final:
            response = str(final.get("result") or "")
            cost = final.get("total_cost_usd")
            duration_ms = final.get("duration_ms")
            num_turns = final.get("num_turns")
            if final.get("subtype") == "error":
                success = False
                error = error or response or "result event reports error"

            # Surface routable extras on ``provider_data`` so downstream
            # workflow nodes can read them off ``tasks[i].provider_data.*``.
            # ``canonical_usage`` flattens token counts across all models;
            # ``modelUsage`` preserves the per-model breakdown (with the
            # per-model ``costUSD`` + ``contextWindow`` + ``maxOutputTokens``
            # claude itself reports). The minor fields below either drive
            # FE diagnostics (``terminal_reason`` / ``api_error_status``)
            # or feed cost analytics (``service_tier`` / ``inference_geo``
            # land inside the usage block but aren't propagated by
            # ``canonical_usage`` because that struct is per-event, not
            # per-result).
            for key in (
                "modelUsage",
                "permission_denials",
                "terminal_reason",
                "fast_mode_state",
                "api_error_status",
            ):
                if key in final and final[key] is not None:
                    provider_data.setdefault(key, final[key])
            # Pull the service-tier / cache-creation / inference-geo bits
            # off the usage block so downstream consumers don't have to
            # re-iterate the events themselves.
            usage_block = final.get("usage") or {}
            for key in ("service_tier", "inference_geo"):
                v = usage_block.get(key)
                if v:
                    provider_data.setdefault(key, v)

        cu = self.canonical_usage(events)

        return {
            "session_id": session_id,
            "response": response,
            "cost_usd": cost,
            "duration_ms": duration_ms,
            "num_turns": num_turns,
            "tool_calls": tool_calls,
            "canonical_usage": cu,
            "provider_data": provider_data,
            "success": success,
            "error": error,
        }

    def canonical_usage(self, events: List[Dict[str, Any]]) -> CanonicalUsage:
        """Pull token counts from the `result` event's `usage` block.

        Anthropic shape:
          {
            "input_tokens": int,
            "output_tokens": int,
            "cache_creation_input_tokens": int,
            "cache_read_input_tokens": int,
          }
        """
        final = next(
            (e for e in reversed(events) if e.get("type") == "result"),
            None,
        )
        if not final:
            return CanonicalUsage()

        usage = final.get("usage") or {}
        request_count = int(final.get("num_turns") or 0) or sum(1 for e in events if e.get("type") == "assistant")
        return CanonicalUsage(
            input_tokens=int(usage.get("input_tokens", 0)),
            output_tokens=int(usage.get("output_tokens", 0)),
            cache_read=int(usage.get("cache_read_input_tokens", 0)),
            cache_write=int(usage.get("cache_creation_input_tokens", 0)),
            reasoning_tokens=0,  # Claude doesn't expose this separately
            request_count=request_count,
        )

    # ---- feature gating --------------------------------------------------

    def supports(self, feature: str) -> bool:
        return feature in self._supports

    # ---- internals -------------------------------------------------------

    @staticmethod
    def _has_tool_use(event: Dict[str, Any]) -> bool:
        msg = event.get("message") or {}
        content = msg.get("content")
        if isinstance(content, list):
            return any(isinstance(blk, dict) and blk.get("type") == "tool_use" for blk in content)
        return False