overcode 0.4.2__py3-none-any.whl → 0.5.2__py3-none-any.whl

overcode/__init__.py

@@ -1,5 +1,5 @@
 """
-Overcode - A supervisor for managing multiple Claude Code instances.
+Overcode - A supervisor for managing multiple coding agents (Claude Code, opencode).
 """
 
 from pathlib import Path

overcode/backends/__init__.py

@@ -0,0 +1,170 @@
+"""Agent backend registry.
+
+``get_backend(name)`` resolves a ``Session.backend`` discriminator to the
+adapter that owns that CLI's argv grammar and gestures.
+"""
+
+from typing import Any, Dict, List
+
+from .base import (
+    AgentBackend,
+    BackendCapability,
+    DialogRule,
+    KeyPress,
+    LaunchSpec,
+    supports,
+)
+from .claude_code import ClaudeCodeBackend
+from .codex import CodexBackend
+from .grok import GrokBackend
+from .opencode import OpencodeBackend
+
+DEFAULT_BACKEND = "claude-code"
+
+_BACKENDS: Dict[str, AgentBackend] = {
+    ClaudeCodeBackend.name: ClaudeCodeBackend(),
+    OpencodeBackend.name: OpencodeBackend(),
+    CodexBackend.name: CodexBackend(),
+    GrokBackend.name: GrokBackend(),
+}
+
+
+class UnknownBackendError(ValueError):
+    """Raised when a Session names a backend overcode doesn't have."""
+
+
+def get_backend(name: str = DEFAULT_BACKEND) -> AgentBackend:
+    """Resolve a backend by name.
+
+    Empty/None resolves to the default so pre-backend sessions and
+    partially-populated dicts keep working.
+    """
+    key = name or DEFAULT_BACKEND
+    try:
+        return _BACKENDS[key]
+    except KeyError:
+        known = ", ".join(sorted(_BACKENDS))
+        raise UnknownBackendError(
+            f"Unknown agent backend '{key}'. Known backends: {known}"
+        ) from None
+
+
+def list_backends() -> List[str]:
+    """Names of every registered backend."""
+    return sorted(_BACKENDS)
+
+
+def register_backend(backend: AgentBackend) -> None:
+    """Register (or replace) a backend. Used by tests to install doubles."""
+    _BACKENDS[backend.name] = backend
+    _invalidate_derived_caches()
+
+
+def unregister_backend(name: str) -> None:
+    """Remove a backend. Silent when it isn't registered."""
+    _BACKENDS.pop(name, None)
+    _invalidate_derived_caches()
+
+
+def _invalidate_derived_caches() -> None:
+    """Drop per-backend objects other modules cache by backend name."""
+    from ..stats_reader import clear_reader_cache
+    from ..status_patterns import clear_patterns_cache
+    clear_reader_cache()
+    clear_patterns_cache()
+
+
+def session_backend_name(session: Any) -> str:
+    """Backend name recorded on a session, defaulting for legacy sessions."""
+    name = getattr(session, "backend", None)
+    if isinstance(name, str) and name:
+        return name
+    return DEFAULT_BACKEND
+
+
+def capability_names(capabilities: BackendCapability) -> List[str]:
+    """Serialize a capability flag set to sorted member names.
+
+    This is the wire form: ``SessionDaemonState.backend_capabilities`` and
+    therefore the sister protocol carry these strings, so a newer sister can
+    tell an older TUI what its backends can do.
+    """
+    return sorted(
+        member.name
+        for member in BackendCapability
+        if member.name and member.value and (capabilities & member)
+    )
+
+
+def capabilities_from_names(names: Any) -> BackendCapability:
+    """Parse serialized capability names back into a flag set.
+
+    Unknown names are ignored: a sister running a newer overcode may report
+    capabilities this build has never heard of.
+    """
+    result = BackendCapability.NONE
+    if not isinstance(names, (list, tuple, set)):
+        return result
+    for name in names:
+        member = getattr(BackendCapability, name, None) if isinstance(name, str) else None
+        if isinstance(member, BackendCapability):
+            result |= member
+    return result
+
+
+def session_capabilities(session: Any) -> BackendCapability:
+    """Capabilities of the backend behind a session.
+
+    Remote (sister) agents are answered from the capability list their own
+    daemon published, so a sister can run a backend this host doesn't have.
+    Sisters predating Phase 6 report nothing; they are assumed to be
+    claude-code with the full capability set (design §3, consequence 5).
+    """
+    # Strict bool check: callers hand us duck-typed stand-ins whose every
+    # attribute is truthy, and misreading one as remote would silently swap
+    # in another host's capability answer.
+    is_remote = getattr(session, "is_remote", False)
+    if isinstance(is_remote, bool) and is_remote:
+        remote_state = getattr(session, "remote_daemon_state", None)
+        if isinstance(remote_state, dict) and remote_state.get("backend_capabilities"):
+            return capabilities_from_names(remote_state["backend_capabilities"])
+        return get_backend(DEFAULT_BACKEND).capabilities
+    try:
+        backend = get_backend(session_backend_name(session))
+    except UnknownBackendError:
+        return BackendCapability.NONE
+    return backend.capabilities
+
+
+def session_supports(session: Any, capability: BackendCapability) -> bool:
+    """True when the session's backend declares ``capability``.
+
+    An unknown backend name answers False — an adapter overcode doesn't
+    have can't be assumed to support anything.
+    """
+    return bool(session_capabilities(session) & capability)
+
+
+__all__ = [
+    "AgentBackend",
+    "BackendCapability",
+    "ClaudeCodeBackend",
+    "CodexBackend",
+    "GrokBackend",
+    "OpencodeBackend",
+    "DEFAULT_BACKEND",
+    "DialogRule",
+    "KeyPress",
+    "LaunchSpec",
+    "UnknownBackendError",
+    "capabilities_from_names",
+    "capability_names",
+    "get_backend",
+    "list_backends",
+    "register_backend",
+    "session_backend_name",
+    "session_capabilities",
+    "session_supports",
+    "unregister_backend",
+    "supports",
+]

overcode/backends/base.py

@@ -0,0 +1,189 @@
+"""Backend seam: the protocol every agent CLI adapter implements.
+
+An ``AgentBackend`` owns everything that is specific to one agent CLI —
+argv grammar, env vars, startup-dialog handshake, key gestures — so the
+rest of overcode can stay backend-neutral. See
+``docs/design/agent-agnostic-backends-opencode.md`` §2.1.
+"""
+
+from dataclasses import dataclass, field
+from enum import Flag, auto
+from typing import (
+    TYPE_CHECKING,
+    Dict,
+    List,
+    Optional,
+    Protocol,
+    Sequence,
+    Set,
+    Tuple,
+    Type,
+)
+
+if TYPE_CHECKING:
+    from ..stats_reader import StatsReader
+    from ..status_patterns import StatusPatterns
+
+
+class BackendCapability(Flag):
+    """What an agent CLI can do. Used to gate UI actions and telemetry."""
+
+    NONE = 0
+    RESUME = auto()                   # relaunch continuing a prior conversation
+    FORK = auto()                     # branch a conversation into a new agent
+    SESSION_ID_PRESCRIPTION = auto()  # overcode chooses the session id up front
+    HOOK_EVENTS = auto()              # push telemetry (hook-state files) available
+    TRANSCRIPT_STATS = auto()         # tokens/cost/context readable from disk
+    PERMISSION_INJECTION = auto()     # per-launch permission allowlist
+    SKILLS = auto()                   # skills/persona file discovery
+    SANDBOX_PROBE = auto()
+    SUBSCRIPTION_USAGE = auto()
+    AGENT_TEAMS = auto()
+
+
+@dataclass(frozen=True)
+class KeyPress:
+    """One tmux send-keys gesture, with the pause that must follow it."""
+
+    keys: str
+    enter: bool = False
+    delay_after: float = 0.0
+
+
+@dataclass(frozen=True)
+class DialogRule:
+    """A startup dialog to dismiss while waiting for the input prompt.
+
+    ``marker`` is matched against captured pane content; ``presses`` are
+    sent in order, then the poller sleeps ``settle_seconds``.
+    """
+
+    marker: str
+    presses: Sequence[KeyPress]
+    settle_seconds: float = 1.0
+
+
+@dataclass
+class LaunchSpec:
+    """Everything a backend needs to render one launch invocation.
+
+    Carries the launch-time knobs recorded on a ``Session`` plus the
+    backend-neutral OVERCODE_* identity fields, so a backend can inject
+    them into its own env/config if it needs to.
+    """
+
+    # Session identity (exported into the child process env)
+    name: str = ""
+    session_id: str = ""
+    tmux_session: str = ""
+    parent_session_id: Optional[str] = None
+    parent_name: Optional[str] = None
+
+    # Conversation selection
+    resume_session_id: Optional[str] = None
+    fork: bool = False
+    prescribed_session_id: Optional[str] = None
+
+    # Permissions
+    permissiveness_mode: Optional[str] = None
+    skip_permissions: bool = False
+    dangerously_skip_permissions: bool = False
+    include_punchy_perms: bool = False
+
+    # Agent configuration
+    model: Optional[str] = None
+    agent: Optional[str] = None
+    allowed_tools: Optional[str] = None
+    extra_args: List[str] = field(default_factory=list)
+    agent_teams: bool = False
+    provider: str = "web"
+
+    # Execution environment
+    start_directory: Optional[str] = None
+    wrapper: Optional[str] = None
+    mock_scenario: Optional[str] = None
+
+
+class AgentBackend(Protocol):
+    """Adapter for one agent CLI."""
+
+    name: str                       # "claude-code" | "opencode" | "codex" | "grok"
+    display_name: str
+    binary: str                     # for dependency_check + doctor process matching
+    version_args: Sequence[str]
+    install_hint: str
+    process_basenames: Sequence[str]
+    not_found_error: Type[Exception]
+    capabilities: BackendCapability
+
+    # True when the backend's fork grammar takes an explicit new session id
+    # (--session-id alongside --fork-session) AND the prescribed id is
+    # authoritative for the forked session; False when the CLI mints its own
+    # fork id and discovery must fill it in. Only meaningful alongside
+    # SESSION_ID_PRESCRIPTION — launcher.py's fork branch mints a fresh uuid
+    # to bind eagerly only when both are true. Both grok (Phase 3) and Claude
+    # Code (#466, 2026-08-28) declare this True: Claude Code was originally
+    # assumed to mint its own, different fork id, but a live check of
+    # `claude --resume <id> --fork-session --session-id <new>` found the
+    # prescribed id IS honored — the CLI writes the fork's transcript under
+    # the prescribed uuid. That wrong assumption was #466's root cause:
+    # without eager binding, a fork's id was discovered via directory+time
+    # matching, which is ambiguous whenever another agent shares the same
+    # start_directory (the fork's record could bind to a sibling's id
+    # instead of its own). (The default backends don't literally inherit
+    # this Protocol, so launcher.py reads it via
+    # ``getattr(backend, "fork_prescribes_new_session_id", False)`` — this
+    # default documents the fallback, it isn't inherited automatically.)
+    fork_prescribes_new_session_id: bool = False
+
+    def build_command(self, spec: LaunchSpec) -> List[str]: ...
+
+    def prepare_launch(self, spec: LaunchSpec) -> None:
+        """Side effects the CLI needs in place before the process starts.
+
+        Called once per launch/restart/revive/fork, after the binary check and
+        before the shell line is sent. Claude Code needs nothing here — its
+        telemetry rides on ``--settings`` — but opencode installs its
+        telemetry plugin into the project directory. Must be idempotent and
+        must never raise: a failure costs telemetry, not the launch.
+        """
+        ...
+
+    def env_prefix(self, spec: LaunchSpec) -> Dict[str, str]: ...
+
+    def resume_args(self, session_id: str, fork: bool) -> List[str]: ...
+
+    def graceful_exit_keys(self) -> List[KeyPress]: ...
+
+    def clear_conversation_keys(self) -> List[KeyPress]: ...
+
+    def approve_keys(self) -> List[KeyPress]: ...
+
+    def reject_keys(self) -> List[KeyPress]: ...
+
+    def startup_dialog_rules(self) -> List[DialogRule]: ...
+
+    def prompt_ready_chars(self) -> Set[str]: ...
+
+    def status_patterns(self) -> "StatusPatterns": ...
+
+    def make_stats_reader(self) -> "StatsReader": ...
+
+    def health_verdict(self, argv: str) -> Optional[Tuple[str, str]]:
+        """Doctor's "is observability wired up?" answer for a live process.
+
+        Returns ``(verdict, details)`` from the ``doctor.VERDICT_*``
+        vocabulary, given the agent process's full argv.
+
+        A backend whose telemetry leaves no trace on the command line may
+        also define an *optional* ``refine_health_verdict(session, verdict,
+        details) -> (verdict, details)``. ``doctor`` calls it via ``getattr``
+        with the session in hand — opencode uses it to check for its
+        telemetry plugin in the project directory.
+        """
+        ...
+
+
+def supports(backend: AgentBackend, capability: BackendCapability) -> bool:
+    """True when ``backend`` declares ``capability``."""
+    return bool(backend.capabilities & capability)

overcode/backends/claude_code.py

@@ -0,0 +1,270 @@
+"""Claude Code backend — the argv/env grammar overcode was built around."""
+
+import json
+import os
+import shlex
+import shutil
+import sys
+from typing import TYPE_CHECKING, Dict, List, Optional, Set, Tuple
+
+from ..exceptions import AgentCliNotFoundError
+from .base import (
+    AgentBackend,
+    BackendCapability,
+    DialogRule,
+    KeyPress,
+    LaunchSpec,
+)
+
+if TYPE_CHECKING:
+    from ..stats_reader import StatsReader
+    from ..status_patterns import StatusPatterns
+
+
+PROMPT_READY_CHARS = {">", "›", "❯"}
+
+
+def _resolve_overcode_bin() -> str:
+    """Resolve absolute path to the overcode binary.
+
+    Tries shutil.which first (covers global/pipx installs), then falls
+    back to invoking via the current Python interpreter (covers uv run,
+    venv-only installs, etc.).
+    """
+    which = shutil.which("overcode")
+    if which:
+        return which
+    return f"{sys.executable} -m overcode.cli"
+
+
+def _build_launch_settings(overcode_bin: str, include_punchy_perms: bool = False) -> dict:
+    """Build the --settings JSON for overcode-launched agents.
+
+    Includes all overcode hooks (with absolute-path commands) and
+    permissions so agents don't depend on user-level settings.json
+    containing these entries.
+    """
+    from ..hook_handler import OVERCODE_HOOKS
+    from ..cli.perms import OVERCODE_SAFE_PERMS, OVERCODE_PUNCHY_PERMS
+
+    # Build hooks dict: event -> [matcher group]
+    hooks: dict[str, list] = {}
+    for event, _bare_command in OVERCODE_HOOKS:
+        hooks.setdefault(event, []).append({
+            "matcher": "",
+            "hooks": [{"type": "command", "command": f"{overcode_bin} hook-handler"}],
+        })
+
+    perms = list(OVERCODE_SAFE_PERMS)
+    if include_punchy_perms:
+        perms.extend(OVERCODE_PUNCHY_PERMS)
+
+    return {
+        "hooks": hooks,
+        "permissions": {"allow": perms},
+    }
+
+
+class ClaudeCodeBackend:
+    """Claude Code CLI adapter."""
+
+    name = "claude-code"
+    display_name = "Claude Code"
+    binary = "claude"
+    version_args = ("--version",)
+    install_hint = (
+        "Claude Code CLI is required but not found. "
+        "Install it from: https://claude.ai/claude-code"
+    )
+    process_basenames = ("claude",)
+    not_found_error = AgentCliNotFoundError
+
+    # Live-verified 2026-08-28 (#466): `claude --resume <id> --fork-session
+    # --session-id <new-uuid>` honors the prescribed id — the fork's
+    # transcript is written to `~/.claude/projects/<enc>/<new-uuid>.jsonl`
+    # (a full replay of the parent conversation plus the new turn), not a
+    # CLI-minted id. This corrects the launcher's prior assumption (see
+    # `launcher.py::_send_launch_for_session`) that Claude mints its own,
+    # different fork id and must rely on directory+time discovery — that
+    # discovery was the root cause of #466 (forking in a shared
+    # start_directory bound the wrong sibling's session id). Prescribing
+    # and eagerly binding the fork's id, the same treatment grok already
+    # gets, sidesteps discovery entirely for Claude forks too.
+    fork_prescribes_new_session_id = True
+
+    capabilities = (
+        BackendCapability.RESUME
+        | BackendCapability.FORK
+        | BackendCapability.SESSION_ID_PRESCRIPTION
+        | BackendCapability.HOOK_EVENTS
+        | BackendCapability.TRANSCRIPT_STATS
+        | BackendCapability.PERMISSION_INJECTION
+        | BackendCapability.SKILLS
+        | BackendCapability.SANDBOX_PROBE
+        | BackendCapability.SUBSCRIPTION_USAGE
+        | BackendCapability.AGENT_TEAMS
+    )
+
+    def executable(self) -> str:
+        """The binary to invoke, honouring the CLAUDE_COMMAND override.
+
+        The override is how the e2e mock harness substitutes a fake TUI.
+        """
+        return os.environ.get("CLAUDE_COMMAND", "claude")
+
+    def resume_args(self, session_id: str, fork: bool) -> List[str]:
+        args = ["--resume", session_id]
+        if fork:
+            args.append("--fork-session")
+        return args
+
+    def build_command(self, spec: LaunchSpec) -> List[str]:
+        """Construct the claude CLI argument list.
+
+        For new launches, ``prescribed_session_id`` pins the Claude session
+        ID upfront. For resumes/forks, ``resume_session_id`` (plus ``fork``)
+        continues an existing conversation.
+        """
+        claude_command = self.executable()
+
+        if spec.resume_session_id:
+            cmd = (
+                ["claude"]
+                if claude_command == "claude"
+                else [claude_command]
+            )
+            cmd.extend(self.resume_args(spec.resume_session_id, spec.fork))
+        else:
+            cmd = [claude_command]
+
+        # Prescribe session ID so we know which session file belongs to
+        # this agent without needing PID-based discovery (#373). Forks are
+        # the one case where a prescribed id rides alongside --resume: the
+        # CLI honors --session-id together with --resume/--fork-session
+        # (live-verified #466), so a forking launch also gets eager binding
+        # instead of ambiguous directory+time discovery. A plain (non-fork)
+        # resume ignores any prescribed_session_id — you cannot rename an
+        # existing conversation, so build_command must not emit a spurious
+        # --session-id there even if the caller passed one (defense in
+        # depth; launcher.py never does in practice).
+        if spec.prescribed_session_id and (not spec.resume_session_id or spec.fork):
+            cmd.extend(["--session-id", spec.prescribed_session_id])
+
+        # Inject overcode hooks and permissions via --settings so launched
+        # agents don't depend on user-level settings.json (#435).
+        overcode_bin = _resolve_overcode_bin()
+        settings = _build_launch_settings(
+            overcode_bin, include_punchy_perms=spec.include_punchy_perms
+        )
+        cmd.extend(["--settings", json.dumps(settings)])
+
+        # Permission flags — from explicit args or inherited mode
+        if spec.dangerously_skip_permissions or spec.permissiveness_mode == "bypass":
+            cmd.append("--dangerously-skip-permissions")
+        elif spec.skip_permissions or spec.permissiveness_mode == "permissive":
+            cmd.extend(["--permission-mode", "dontAsk"])
+
+        if spec.model:
+            cmd.extend(["--model", spec.model])
+        if spec.agent:
+            cmd.extend(["--agent", spec.agent])
+        if spec.allowed_tools:
+            cmd.extend(["--allowedTools", spec.allowed_tools])
+        if spec.extra_args:
+            for arg in spec.extra_args:
+                cmd.extend(shlex.split(arg))
+
+        return cmd
+
+    def prepare_launch(self, spec: LaunchSpec) -> None:
+        """Nothing to stage — hooks and permissions ride on ``--settings``.
+
+        Claude Code is deliberately exempt from ``backend_telemetry`` config
+        (``config.get_backend_telemetry_enabled`` always returns True for
+        it): its hooks are per-launch ``--settings`` flags on the argv of
+        the process overcode itself starts, not a file written to disk, so
+        there is no on-disk footprint to opt out of.
+        """
+        return None
+
+    def env_prefix(self, spec: LaunchSpec) -> Dict[str, str]:
+        """Claude-specific env vars for the launch shell line."""
+        env: Dict[str, str] = {}
+        if spec.agent_teams:
+            env["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"] = "1"
+        if spec.provider == "bedrock":
+            env["CLAUDE_CODE_USE_BEDROCK"] = "1"
+            from ..config import get_bedrock_config
+            bedrock_cfg = get_bedrock_config()
+            env["AWS_REGION"] = bedrock_cfg["region"]
+        return env
+
+    def graceful_exit_keys(self) -> List[KeyPress]:
+        # Ctrl-C cancels any in-flight tool call, then /exit reliably
+        # terminates the claude process.
+        return [
+            KeyPress("C-c", enter=False, delay_after=0.5),
+            KeyPress("/exit", enter=True),
+        ]
+
+    def clear_conversation_keys(self) -> List[KeyPress]:
+        return [KeyPress("/clear", enter=True)]
+
+    def approve_keys(self) -> List[KeyPress]:
+        return [KeyPress("", enter=True)]
+
+    def reject_keys(self) -> List[KeyPress]:
+        return [KeyPress("Escape", enter=False)]
+
+    def startup_dialog_rules(self) -> List[DialogRule]:
+        return [
+            # Trust prompt: default is accept, just Enter
+            DialogRule(
+                marker="I trust this folder",
+                presses=[KeyPress("", enter=True)],
+                settle_seconds=1.5,
+            ),
+            # Permissions warning: navigate Down to "Yes, I accept", then Enter
+            DialogRule(
+                marker="Yes, I accept",
+                presses=[
+                    KeyPress("Down", enter=False, delay_after=0.3),
+                    KeyPress("", enter=True),
+                ],
+                settle_seconds=2.0,
+            ),
+        ]
+
+    def prompt_ready_chars(self) -> Set[str]:
+        return PROMPT_READY_CHARS
+
+    def status_patterns(self) -> "StatusPatterns":
+        """The pane-polling pattern set — overcode's defaults are Claude's."""
+        from ..status_patterns import DEFAULT_PATTERNS
+        return DEFAULT_PATTERNS
+
+    def make_stats_reader(self) -> "StatsReader":
+        from ..stats_reader import ClaudeStatsReader
+        return ClaudeStatsReader()
+
+    def health_verdict(self, argv: str) -> Tuple[str, str]:
+        """Hooks reach Claude Code only via the injected --settings payload."""
+        from ..doctor import VERDICT_MISSING_SETTINGS, VERDICT_OK
+
+        if "--settings" in argv:
+            return VERDICT_OK, "hooks injected via --settings"
+        return VERDICT_MISSING_SETTINGS, (
+            "claude running without --settings — hooks will not fire. "
+            "Relaunch via `overcode restart` to re-inject."
+        )
+
+
+_backend: Optional[AgentBackend] = None
+
+
+def get_claude_backend() -> "ClaudeCodeBackend":
+    """Module-level singleton — backends are stateless."""
+    global _backend
+    if _backend is None:
+        _backend = ClaudeCodeBackend()
+    return _backend