painapple-code 1.0.0__py3-none-any.whl

painapple_code/providers/claude/__init__.py

@@ -0,0 +1,74 @@
+"""
+Claude Code CLI provider.
+
+The reference implementation. Bodies here were moved (not rewritten) out of
+`services/agent_session.py` and `utils/agent_cli.py`, so behavior is
+identical — this is purely the relocation of Claude-specific logic behind the
+`Provider` seam.
+
+Claude's stream-json schema *is* the canonical internal event shape, so this
+adapter is a near-identity: it inherits the base `translate_events` and only
+normalizes cumulative cost to per-turn deltas. It's
+assembled from focused mixins (this file is the combiner — see session_store.py
+/ shadow_git.py for the same pattern):
+
+    capabilities.py  → _CapabilitiesMixin  binary, accounts, models, effort/perm
+                                            vocabularies, fetch_context,
+                                            skill/agent/plugin roots
+    launch.py        → _LaunchMixin         build_command (`claude -p …`)
+    translate.py     → _TranslateMixin      normalize_result (cumulative → delta)
+    summary.py       → _SummaryMixin         rich-commit summary fork (--fork-session)
+    errors.py        → _ErrorsMixin          stderr classification / retry policy
+"""
+
+from __future__ import annotations
+
+from painapple_code.providers.base import Provider, Capabilities
+from painapple_code.providers.claude.capabilities import _CapabilitiesMixin
+from painapple_code.providers.claude.launch import _LaunchMixin
+from painapple_code.providers.claude.translate import _TranslateMixin
+from painapple_code.providers.claude.summary import _SummaryMixin
+from painapple_code.providers.claude.errors import _ErrorsMixin
+
+
+class ClaudeProvider(
+    _CapabilitiesMixin,
+    _LaunchMixin,
+    _TranslateMixin,
+    _SummaryMixin,
+    _ErrorsMixin,
+    Provider,
+):
+    """Adapter for the Claude Code CLI (`claude -p ... --output-format stream-json`).
+
+    The behaviour lives in the mixins above; this class only carries the static
+    identity + capability flags and the MRO that composes them (mixins first, so
+    their overrides win over the `Provider` defaults).
+    """
+
+    name = "claude"
+    display_name = "Claude Code"
+    description = "Anthropic Claude Code CLI — line-protocol driver"
+    # Same engine as claude-sdk but the plainer driver (no live controls, no
+    # ask-mode cards) — kept out of the picker by default so Claude appears
+    # once. Flip it on in Settings → Engines.
+    default_enabled = False
+    capabilities = Capabilities(
+        resume=True,
+        fork=True,
+        permission_modes=True,
+        effort=True,
+        thinking_display=True,
+        context_command=True,
+        cumulative_cost=True,
+        rich_commit_summaries=True,
+        persistent_process=True,   # one `claude -p` process serves many turns
+        forward_plain_stderr=True,
+    )
+
+
+# Instances this module contributes to the registry. The package scanner
+# (providers/__init__.py) collects every module's PROVIDERS list, so adding a
+# provider is "drop a file that exports PROVIDERS" — no core edit. (A subpackage
+# is discovered exactly like a flat module.)
+PROVIDERS = [ClaudeProvider()]

painapple_code/providers/claude/capabilities.py

@@ -0,0 +1,218 @@
+"""Claude provider — declarative surface + customization roots.
+
+What the Claude adapter *declares about itself*: binary location, accounts,
+models, effort/permission vocabularies, context fetch, and where its
+skills/agents/plugins live. The `ClaudeProvider` combiner in this package's
+``__init__`` mixes this in.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from painapple_code.providers.base import PluginBackend
+from painapple_code.utils.agent_cli import get_claude_binary, fetch_context_tokens
+
+
+class _CapabilitiesMixin:
+    """Provider self-description: binary, accounts, vocabularies, roots, context."""
+
+    # --- binary -----------------------------------------------------------
+
+    # Settings "CLI path" row + generic engine-path endpoint (shared by both
+    # Claude drivers — same binary). The app also owns this engine's model
+    # catalog (models.yaml), so Settings renders it editable; per-model
+    # show/hide prefs are namespaced under the shared "claude" key so both
+    # drivers see the same curation.
+    path_config_key = "claude_path"
+    default_binary = "claude"
+    # "Continue in CLI" quick action → `claude -r <session-id>`.
+    cli_resume_template = "claude -r {id}"
+    models_editable = True
+    models_key = "claude"
+    # `claude auth status --json` → {loggedIn, authMethod, email,
+    # subscriptionType}; the interactive login flow prints an OAuth URL +
+    # paste-back code, which works fine inside a PTY terminal tab.
+    auth_status_args = ["auth", "status", "--json"]
+    auth_login_args = ["auth", "login"]
+
+    def binary(self) -> str:
+        return get_claude_binary()
+
+    def binary_not_found_hint(self) -> str:
+        return ("Make sure the Claude Code CLI is installed and 'claude' is on "
+                "the server's PATH, or set the full path in Settings → Engines. "
+                "Install with: curl -fsSL https://claude.ai/install.sh | bash")
+
+    def summary_model_editable(self) -> bool:
+        # Claude's journal model lives in models.yaml (`summary_model`), not
+        # a global-config key — override storage, keep the knob.
+        return True
+
+    def get_summary_model_override(self) -> Optional[str]:
+        from painapple_code.paths import get_summary_model
+        return get_summary_model()
+
+    def set_summary_model_override(self, value: Optional[str]) -> None:
+        # Empty resets to the shipped default — Claude's journal fork always
+        # needs a concrete model (`--model` is mandatory on the fork argv).
+        from painapple_code import paths
+        cleaned = (value or "").strip() or (
+            paths.get_default_models_config().get("summary_model")
+            or "claude-haiku-4-5")
+        paths.save_models_config({
+            "selectable": paths.get_selectable_models(),
+            "summary_model": cleaned,
+        })
+
+    def parse_auth_status(self, returncode: int, stdout: str, stderr: str) -> dict:
+        """Structured status: surface who's logged in and on which plan."""
+        try:
+            data = json.loads(stdout or "")
+        except (ValueError, TypeError):
+            data = None
+        if not isinstance(data, dict) or "loggedIn" not in data:
+            return super().parse_auth_status(returncode, stdout, stderr)
+        if not data.get("loggedIn"):
+            return {"logged_in": False, "detail": ""}
+        bits = [str(b) for b in (data.get("email"), data.get("subscriptionType")) if b]
+        return {"logged_in": True, "detail": " · ".join(bits)}
+
+    # --- accounts / models / effort / permissions -------------------------
+
+    def accounts(self) -> list[dict]:
+        """Claude accounts == token profiles (`CLAUDE_CODE_OAUTH_TOKEN`).
+
+        Empty id = the ambient login / global-default token. Each named profile
+        is a file under ~/.config/painapple-code/tokens/.
+        """
+        from painapple_code.utils.token_profiles import list_profiles
+        accounts = [{"id": "", "label": "Default"}]
+        accounts += [{"id": p["name"], "label": p["name"]} for p in list_profiles()]
+        return accounts
+
+    def models(self) -> list[dict]:
+        from painapple_code.paths import get_selectable_models
+        return get_selectable_models()
+
+    def effort_levels(self) -> list[str]:
+        # The Claude CLI's full --effort scale.
+        return ["low", "medium", "high", "xhigh", "max"]
+
+    def permission_modes(self) -> list[dict]:
+        # Claude's native permission modes, in display order — fully self-described
+        # here (value/label/desc/color), exactly like every other provider. No
+        # Claude permission vocabulary lives anywhere else (strings.yaml, a
+        # constant, the frontend); the engine picker and chip read this list.
+        return [
+            {"value": "plan", "label": "Plan",
+             "desc": "Read-only, explore & design", "color": "#8b5cf6"},
+            {"value": "dontAsk", "label": "Don't Ask",
+             "desc": "Auto-deny unless in allow rules", "color": "#facc15"},
+            {"value": "acceptEdits", "label": "Accept Edits",
+             "desc": "Auto-approve edits in workspace; deny others", "color": "#fb923c"},
+            {"value": "auto", "label": "Auto",
+             "desc": "AI classifier reviews each tool call", "color": "#60a5fa"},
+            {"value": "bypassPermissions", "label": "YOLO",
+             "desc": "Skip all permission checks", "color": "#4ade80"},
+        ]
+
+    def default_permission_mode(self) -> str:
+        return "dontAsk"
+
+    # --- context metering -------------------------------------------------
+
+    async def fetch_context(
+        self,
+        cwd: str,
+        session_id: Optional[str] = None,
+        token_profile: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> Optional[dict]:
+        return await fetch_context_tokens(
+            cwd,
+            provider_session_id=session_id,
+            token_profile=token_profile,
+            model=model,
+        )
+
+    # --- customization roots (skills / agents / plugins) ------------------
+
+    def skill_roots(self, cwd: str) -> list[dict]:
+        from pathlib import Path
+        return [
+            {"scope": "project", "dir": Path(cwd) / ".claude" / "skills"},
+            {"scope": "personal", "dir": Path.home() / ".claude" / "skills"},
+        ]
+
+    def agent_roots(self, cwd: str) -> list[dict]:
+        from pathlib import Path
+        return [
+            {"scope": "project", "dir": Path(cwd) / ".claude" / "agents",
+             "fmt": "markdown", "writable": True},
+            {"scope": "personal", "dir": Path.home() / ".claude" / "agents",
+             "fmt": "markdown", "writable": True},
+        ]
+
+    def plugin_backend(self) -> PluginBackend:
+        from pathlib import Path
+        return PluginBackend(
+            binary=self.binary(),
+            list_installed_args=["plugins", "list", "--json"],
+            list_all_args=["plugins", "list", "--available", "--json"],
+            install_verb=["plugins", "install"],
+            uninstall_verb=["plugins", "uninstall"],
+            enable_verb=["plugins", "enable"],
+            disable_verb=["plugins", "disable"],
+            marketplace_root=Path.home() / ".claude" / "plugins" / "marketplaces",
+        )
+
+    def plugin_skill_dirs(self) -> list[dict]:
+        """Skill roots from installed Claude plugins (read-only).
+
+        Claude Code caches every known marketplace under
+        ``~/.claude/plugins/marketplaces/`` but only a subset is installed;
+        ``installed_plugins.json`` is the authoritative list (keyed
+        ``<plugin>@<marketplace>``). We surface only installed plugins' skills.
+        """
+        from pathlib import Path
+        home = Path.home()
+        plugins_root = home / ".claude" / "plugins" / "marketplaces"
+        if not plugins_root.is_dir():
+            return []
+        installed = _load_installed_plugin_keys()
+        out: list[dict] = []
+        for marketplace in sorted(plugins_root.iterdir()):
+            plugins_dir = marketplace / "plugins"
+            if not plugins_dir.is_dir():
+                continue
+            for plugin in sorted(plugins_dir.iterdir()):
+                if f"{plugin.name}@{marketplace.name}" not in installed:
+                    continue
+                skills_root = plugin / "skills"
+                if skills_root.is_dir():
+                    out.append({
+                        "label": f"{plugin.name} ({marketplace.name})",
+                        "dir": skills_root,
+                    })
+        return out
+
+
+def _load_installed_plugin_keys() -> set:
+    """`{plugin@marketplace}` keys from ``~/.claude/plugins/installed_plugins.json``.
+
+    Empty set if missing/malformed (treat as "nothing installed" rather than
+    "show everything", so the picker reflects the user's /plugin install state).
+    """
+    from pathlib import Path
+    path = Path.home() / ".claude" / "plugins" / "installed_plugins.json"
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return set()
+    plugins = data.get("plugins")
+    if not isinstance(plugins, dict):
+        return set()
+    return set(plugins.keys())

painapple_code/providers/claude/errors.py

@@ -0,0 +1,79 @@
+"""Claude provider — stderr classification and retry/termination policy."""
+
+from __future__ import annotations
+
+import re
+
+from painapple_code.providers.base import StderrClass
+from painapple_code.utils.agent_cli import NORMAL_TERMINATION_CODES
+
+# Patterns that indicate retryable transient API errors (5xx, overloaded, etc.)
+_RETRYABLE_ERROR_PATTERNS = [
+    re.compile(r'API Error:\s*5\d{2}\b'),
+    re.compile(r'"type":\s*"api_error"'),
+    re.compile(r'overloaded', re.IGNORECASE),
+    re.compile(r'Internal server error', re.IGNORECASE),
+]
+
+# Usage/rate/session limit. The CLI wording varies by limit kind: "hit your
+# limit", "hit your session limit", "hit your weekly limit", … — one optional
+# word covers them all without matching unrelated "limit" mentions.
+_USAGE_LIMIT_RE = re.compile(r"hit your (?:\w+\s+)?limit", re.IGNORECASE)
+
+# Patterns that indicate NON-retryable errors (checked first to avoid retrying)
+_NON_RETRYABLE_PATTERNS = [
+    _USAGE_LIMIT_RE,
+    re.compile(r'authentication', re.IGNORECASE),
+    re.compile(r'invalid.*api.*key', re.IGNORECASE),
+    re.compile(r'credit', re.IGNORECASE),
+]
+
+# Patterns in a failed turn's result text that mean "re-login fixes this".
+# Narrower than _NON_RETRYABLE_PATTERNS (no `credit` — a billing problem, not
+# something `claude auth login` resolves).
+_AUTH_ERROR_PATTERNS = [
+    re.compile(r'failed to authenticate', re.IGNORECASE),
+    re.compile(r'authentication_error', re.IGNORECASE),
+    re.compile(r'invalid authentication', re.IGNORECASE),
+    re.compile(r'oauth token (?:has )?expired', re.IGNORECASE),
+    re.compile(r'invalid.*api.*key', re.IGNORECASE),
+]
+
+
+class _ErrorsMixin:
+    """Maps Claude stderr/result text to the canonical error classes."""
+
+    def classify_stderr(self, line: str) -> StderrClass:
+        if "No conversation found with session ID" in line:
+            return StderrClass.STALE_SESSION
+        if "compacting" in line.lower():
+            return StderrClass.COMPACTING
+        if self.is_retryable_api_error(line):
+            return StderrClass.RETRYABLE
+        return StderrClass.NONE
+
+    def is_retryable_api_error(self, text: str) -> bool:
+        for pattern in _NON_RETRYABLE_PATTERNS:
+            if pattern.search(text):
+                return False
+        for pattern in _RETRYABLE_ERROR_PATTERNS:
+            if pattern.search(text):
+                return True
+        return False
+
+    def is_auth_error(self, text: str, api_error_status=None) -> bool:
+        if api_error_status == 401:
+            return True
+        return any(p.search(text) for p in _AUTH_ERROR_PATTERNS)
+
+    def is_usage_limit(self, text: str) -> bool:
+        # Genuine limit messages are one-liners (~50-85 chars: "Error during
+        # compaction: You've hit your session limit · resets 4pm (…)"). The
+        # length cap keeps the substring match from misfiring on long text
+        # that merely QUOTES the phrase — an assistant reply discussing this
+        # very bug, pasted logs inside an error string, etc.
+        return bool(text) and len(text) <= 200 and bool(_USAGE_LIMIT_RE.search(text))
+
+    @property
+    def normal_termination_codes(self) -> frozenset:
+        return NORMAL_TERMINATION_CODES

painapple_code/providers/claude/launch.py

@@ -0,0 +1,50 @@
+"""Claude provider — command building.
+
+Turns a `LaunchOptions` into the persistent `claude -p … --output-format
+stream-json` argv (model, effort, permission mode, resume/fork). Mixed into
+`ClaudeProvider`.
+"""
+
+from __future__ import annotations
+
+from painapple_code.providers.base import LaunchOptions
+
+
+class _LaunchMixin:
+    """Builds the `claude -p` command line."""
+
+    def build_command(self, opts: LaunchOptions) -> list[str]:
+        cmd = [
+            self.binary(),
+            "-p",
+            "--input-format", "stream-json",
+            "--output-format", "stream-json",
+            "--verbose",
+            # Opus 4.7 changed the thinking-block default from "summarized"
+            # to "omitted" (empty text, signature only). Restore summaries
+            # on all models — the flag is a no-op where display was already
+            # "summarized". See anthropics/claude-code#8477 comment 4269024077.
+            "--thinking-display", "summarized",
+        ]
+
+        if opts.model:
+            cmd.extend(["--model", opts.model])
+
+        if opts.fallback_model:
+            cmd.extend(["--fallback-model", opts.fallback_model])
+
+        # "high" is the CLI default; skip to avoid noise.
+        if opts.effort and opts.effort != "high":
+            cmd.extend(["--effort", opts.effort])
+
+        # Fall back to this provider's own default when no mode was resolved.
+        cmd.extend(["--permission-mode", opts.permission_mode or self.default_permission_mode()])
+
+        # Fork from another session (new session with conversation history),
+        # else resume an existing one.
+        if opts.fork_from_session_id:
+            cmd.extend(["--resume", opts.fork_from_session_id, "--fork-session"])
+        elif opts.session_id:
+            cmd.extend(["--resume", opts.session_id])
+
+        return cmd

painapple_code/providers/claude/summary.py

@@ -0,0 +1,89 @@
+"""Claude provider — the rich-commit summary fork.
+
+Forks the live `claude -p` session with Haiku to write structured commit
+sections, then pulls `structured_output` + usage out of the wrapper JSON. Mixed
+into `ClaudeProvider`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from painapple_code.providers.base import SummaryForkPlan
+
+
+class _SummaryMixin:
+    """Fork the live session with Haiku and read back the structured sections."""
+
+    def build_summary_fork(
+        self,
+        *,
+        session_id: str,
+        fork_prompt: str,
+        schema_json: str,
+        cwd: str,
+        token_profile: Optional[str] = None,
+        session_model: Optional[str] = None,
+    ) -> Optional[SummaryForkPlan]:
+        """Fork the live session with Haiku to write structured commit sections.
+
+        `--fork-session` branches a throwaway session off the real one, so the
+        summary turn never touches the user's conversation; `--json-schema`
+        forces the structured shape and `--output-format json` wraps it with
+        cost/usage on stdout.
+
+        The prompt is fed over stdin (bare `-p`, no positional) rather than as an
+        argv element: the journey + tools prompt can be large, so this keeps it
+        clear of ARG_MAX and out of `ps`. The generic spawner writes
+        `stdin_input` before reading stdout.
+        """
+        from painapple_code.paths import get_summary_model
+        from painapple_code.utils.token_profiles import build_env as build_token_env
+
+        # Always plain haiku — the [1m] variant hangs with --fork-session from
+        # opus[1m] sessions (every fork times out at 300s even for 30k context).
+        summary_model = get_summary_model()
+        return SummaryForkPlan(
+            argv=[
+                self.binary(),
+                "--resume", session_id,
+                "--fork-session",
+                "--model", summary_model,
+                "--tools", "",                  # disable all tools
+                "--no-session-persistence",
+                "-p",                            # print mode; prompt arrives on stdin
+                "--output-format", "json",      # wrapper JSON carries cost/usage
+                "--json-schema", schema_json,   # force structured output
+            ],
+            env=build_token_env(token_profile),
+            model=summary_model,
+            output_file=None,                   # structured_output is on stdout
+            stdin_input=fork_prompt,            # feed the prompt via stdin (not argv)
+        )
+
+    def parse_summary_fork(
+        self,
+        *,
+        plan: SummaryForkPlan,
+        returncode: int,
+        stdout: bytes,
+        stderr: bytes,
+    ) -> tuple[Optional[dict], Optional[dict]]:
+        """Pull `structured_output` + usage out of the wrapper JSON on stdout."""
+        if returncode != 0:
+            return None, None
+        try:
+            result = json.loads(stdout.decode())
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return None, None
+        structured = result.get("structured_output")
+        if not isinstance(structured, dict):
+            return None, None
+        usage = result.get("usage") or {}
+        cost = {
+            "cost": result.get("total_cost_usd", 0.0) or 0.0,
+            "input_tokens": usage.get("input_tokens", 0),
+            "output_tokens": usage.get("output_tokens", 0),
+        }
+        return structured, cost

painapple_code/providers/claude/translate.py

@@ -0,0 +1,74 @@
+"""Claude provider — wire adaptation + output normalization.
+
+Claude's stream-json *is* the canonical internal event shape, so the wire
+methods here (`frame_input`, `session_id_from_event`) are the identity readings
+of that schema, and the base `translate_events` identity is inherited unchanged.
+The one real transform Claude needs is `normalize_result`: the CLI's `result`
+cost/usage fields are cumulative across the persistent `claude -p` process, and
+the server stores them per-turn. Mixed into `ClaudeProvider`.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from painapple_code.providers.base import CostState
+
+# Cumulative `modelUsage` fields tracked for the per-turn delta conversion.
+_CUM_USAGE_FIELDS = (
+    "costUSD", "inputTokens", "outputTokens",
+    "cacheReadInputTokens", "cacheCreationInputTokens",
+    "webSearchRequests",
+)
+
+
+class _TranslateMixin:
+    """Identity wire methods + per-turn delta conversion for the cumulative result."""
+
+    def frame_input(self, message: dict) -> dict:
+        # Identity: the canonical user-message envelope is exactly what the
+        # `claude -p --input-format stream-json` stdin protocol expects
+        # ({"type": "user", "message": {...}}).
+        return message
+
+    def session_id_from_event(self, event: dict) -> Optional[str]:
+        # Present on every stream-json line the CLI emits.
+        return event.get("session_id")
+
+    def normalize_result(self, msg: dict, state: CostState) -> None:
+        """Convert CLI `result` fields from per-process cumulative to per-turn delta.
+
+        The Claude CLI emits `result` messages whose `total_cost_usd` and
+        `modelUsage[*]` fields are running totals across the lifetime of the
+        subprocess (across multiple user prompts within one `claude -p`
+        invocation). Painapple stores these per-turn, so summing them
+        double-counts. This rewrites `msg` in place: cumulative values become
+        per-turn deltas (subtracting the previous cumulative seen on this
+        subprocess, tracked in `state`).
+
+        Resilient to out-of-order or negative deltas: if a value somehow drops
+        (shouldn't happen within a process, but defensive), treat it as a fresh
+        count from zero.
+        """
+        cum_cost = msg.get("total_cost_usd", 0) or 0.0
+        delta_cost = cum_cost - state.cum_cost
+        if delta_cost < 0:
+            delta_cost = cum_cost
+        msg["total_cost_usd"] = delta_cost
+        state.cum_cost = cum_cost
+
+        mu = msg.get("modelUsage") or {}
+        if not isinstance(mu, dict):
+            return
+        prev = state.cum_usage or {}
+        new_prev = {}
+        for model, info in list(mu.items()):
+            if not isinstance(info, dict):
+                continue
+            prev_info = prev.get(model, {})
+            new_prev[model] = {f: info.get(f, 0) or 0 for f in _CUM_USAGE_FIELDS}
+            for f in _CUM_USAGE_FIELDS:
+                cur = info.get(f, 0) or 0
+                d = cur - (prev_info.get(f, 0) or 0)
+                info[f] = d if d >= 0 else cur
+        state.cum_usage = new_prev