overcode 0.4.2__py3-none-any.whl → 0.5.3__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,176 @@
+"""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 .hermes import HermesBackend
+from .opencode import OpencodeBackend
+from .opencode2 import Opencode2Backend
+
+DEFAULT_BACKEND = "claude-code"
+
+_BACKENDS: Dict[str, AgentBackend] = {
+    ClaudeCodeBackend.name: ClaudeCodeBackend(),
+    OpencodeBackend.name: OpencodeBackend(),
+    Opencode2Backend.name: Opencode2Backend(),
+    CodexBackend.name: CodexBackend(),
+    GrokBackend.name: GrokBackend(),
+    HermesBackend.name: HermesBackend(),
+}
+
+
+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",
+    "HermesBackend",
+    "OpencodeBackend",
+    "Opencode2Backend",
+    "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,231 @@
+"""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
+    AGENT_INJECTION = auto()           # launch-time persona/agent flag (--agent) is honored
+    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" | "opencode2" | "codex" | "grok" | "hermes"
+    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
+
+    # Optional. Substrings that identify the agent's live process by argv when
+    # its basename is not distinctive — hermes runs as Hermes's own venv
+    # python (`.../venv/bin/python .../hermes-agent/hermes --cli`), so
+    # matching ``process_basenames`` alone would have to match "python".
+    # ``doctor.find_agent_process`` reads this via ``getattr`` and accepts a
+    # process whose basename is in ``process_basenames`` OR whose argv
+    # contains any marker. Same "not inherited from the Protocol" caveat as
+    # fork_prescribes_new_session_id above.
+    process_argv_markers: Sequence[str] = ()
+
+    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 prompt_ready_line(self, line: str) -> bool:
+        """Optional. Is this (ANSI-stripped, whitespace-trimmed) pane line the
+        live, empty input prompt?
+
+        ``launcher._wait_for_prompt`` consults this via ``getattr`` before
+        falling back to an exact match against ``prompt_ready_chars()``. The
+        exact-set form can't express a prompt that is never drawn bare —
+        hermes always follows its glyph with a rotating placeholder hint —
+        so a backend with that shape implements this instead.
+        """
+        ...
+
+    def uninstall_telemetry(self, project_dir: Optional[str] = None) -> Tuple[bool, str]:
+        """Optional. Remove this backend's on-disk telemetry footprint.
+
+        Backs ``overcode hooks uninstall-backend <name>``. Returns ``(ok,
+        message)``: ``ok`` False means the footprint was found but *not*
+        removed (not overcode-managed, or ``project_dir`` was needed and
+        missing) and the CLI exits non-zero. A backend whose telemetry
+        leaves nothing on disk (Claude Code's ``--settings``, codex's ``-c``
+        overrides) returns ``(True, "nothing installed on disk …")``.
+        """
+        ...
+
+    def doctor_findings(self) -> List[str]:
+        """Optional. Fleet-level warnings for ``overcode doctor`` — version
+        outside the tested range, missing auth, stats-store schema drift.
+        Only called when the fleet actually has an agent on this backend.
+        """
+        ...
+
+    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)