pairling 0.0.1 → 0.1.0

package/payload/mac/companiond/providers/__init__.py

@@ -0,0 +1 @@
+"""Provider runtime adapters for Pairling companiond."""

package/payload/mac/companiond/providers/base.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+from typing import Iterable, Protocol
+
+
+ProviderCapability = str
+
+
+@dataclass(frozen=True)
+class ProviderDescriptor:
+    provider_id: str
+    display_name: str
+    kind: str
+    builtin: bool = True
+    docs_url: str | None = None
+
+
+@dataclass(frozen=True)
+class ProviderAvailability:
+    provider_id: str
+    display_name: str
+    kind: str
+    installed: bool
+    usable: bool
+    launchable: bool
+    auth_state: str
+    config_state: str
+    readable_sessions: int
+    live_sessions: int
+    controllable_sessions: int
+    capabilities: tuple[ProviderCapability, ...]
+    setup_actions: tuple[str, ...] = ()
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ProviderDiagnostics:
+    cli_path: str | None = None
+    cli_path_source: str | None = None
+    version: str | None = None
+    config_path: str | None = None
+    config_exists: bool | None = None
+    hook_count: int | None = None
+    hooks_configured: bool | None = None
+    mcp_count: int | None = None
+    plugin_count: int | None = None
+    registry_count: int | None = None
+    registry_live_count: int | None = None
+
+
+@dataclass(frozen=True)
+class ProviderProbeResult:
+    descriptor: ProviderDescriptor
+    availability: ProviderAvailability
+    diagnostics: ProviderDiagnostics
+    observed_at: float
+
+    def with_availability(self, **changes) -> "ProviderProbeResult":
+        return replace(self, availability=replace(self.availability, **changes))
+
+    def with_diagnostics(self, **changes) -> "ProviderProbeResult":
+        return replace(self, diagnostics=replace(self.diagnostics, **changes))
+
+
+class ProviderAdapter(Protocol):
+    descriptor: ProviderDescriptor
+
+    def probe(self) -> ProviderProbeResult:
+        ...
+
+    def supports(self, capability: ProviderCapability) -> bool:
+        ...
+
+
+@dataclass(frozen=True)
+class ResolvedExecutable:
+    path: Path
+    source: str
+
+
+def normalize_provider_id(raw: str) -> str:
+    return (raw or "").strip().lower()
+
+
+def is_valid_provider_id(raw: str) -> bool:
+    provider_id = normalize_provider_id(raw)
+    return bool(provider_id) and len(provider_id) <= 48 and re.fullmatch(r"[a-z0-9_]+", provider_id) is not None
+
+
+def executable_candidates(name: str, known: Iterable[Path | str], env_var: str | None = None) -> list[tuple[Path, str]]:
+    candidates: list[tuple[Path, str]] = []
+    if env_var:
+        configured = os.environ.get(env_var)
+        if configured:
+            candidates.append((Path(configured).expanduser(), f"env:{env_var}"))
+    for candidate in known:
+        candidates.append((Path(candidate).expanduser(), "known"))
+    for prefix in os.environ.get("PATH", "").split(":"):
+        if prefix:
+            candidates.append((Path(prefix).expanduser() / name, "path"))
+    return candidates
+
+
+def resolve_executable(name: str, known: Iterable[Path | str], env_var: str | None = None) -> ResolvedExecutable | None:
+    seen: set[str] = set()
+    for candidate, source in executable_candidates(name, known, env_var=env_var):
+        key = str(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        if candidate.exists() and os.access(candidate, os.X_OK):
+            return ResolvedExecutable(candidate, source)
+    return None
+
+
+def cli_version(bin_path: Path | str | None, args: list[str] | None = None, timeout: int = 3) -> str | None:
+    if not bin_path:
+        return None
+    try:
+        proc = subprocess.run([str(bin_path), *(args or ["--version"])], capture_output=True, text=True, timeout=timeout)
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    return (proc.stdout or proc.stderr or "").strip()[:160] or None
+
+
+def count_dirs(root: Path, excluded: set[str] | None = None) -> int:
+    excluded = excluded or set()
+    if not root.is_dir():
+        return 0
+    try:
+        return sum(1 for p in root.iterdir() if p.is_dir() and not p.name.startswith(".") and p.name not in excluded)
+    except OSError:
+        return 0
+
+
+def command_line_count(bin_path: Path | str | None, args: list[str], timeout: int = 5) -> int | None:
+    if not bin_path:
+        return None
+    try:
+        proc = subprocess.run([str(bin_path), *args], capture_output=True, text=True, timeout=timeout)
+    except Exception:
+        return None
+    text = (proc.stdout or proc.stderr or "").strip()
+    if not text:
+        return 0 if proc.returncode == 0 else None
+    lines: list[str] = []
+    for line in text.splitlines():
+        s = line.strip()
+        low = s.lower()
+        if not s:
+            continue
+        if low.startswith("no ") or "no mcp" in low:
+            continue
+        if low.startswith("name ") or set(s) <= {"-", " "}:
+            continue
+        lines.append(s)
+    return len(lines)
+
+
+def hook_command_count(obj) -> int:
+    if isinstance(obj, dict):
+        own = 1 if isinstance(obj.get("command"), str) and obj.get("command") else 0
+        return own + sum(hook_command_count(v) for k, v in obj.items() if k != "command")
+    if isinstance(obj, list):
+        return sum(hook_command_count(v) for v in obj)
+    return 0
+
+
+def json_hook_count(path: Path) -> int:
+    if not path.is_file():
+        return 0
+    try:
+        obj = json.loads(path.read_text(errors="replace"))
+    except Exception:
+        return 0
+    return hook_command_count(obj.get("hooks") if isinstance(obj, dict) and "hooks" in obj else obj)
+
+
+def availability_dict(availability: ProviderAvailability) -> dict:
+    data = asdict(availability)
+    data["capabilities"] = list(availability.capabilities)
+    data["setup_actions"] = list(availability.setup_actions)
+    data["notes"] = list(availability.notes)
+    return data
+
+
+def diagnostics_dict(diagnostics: ProviderDiagnostics) -> dict:
+    return asdict(diagnostics)
+
+
+def provider_detail_payload(result: ProviderProbeResult) -> dict:
+    payload = availability_dict(result.availability)
+    payload.update(diagnostics_dict(result.diagnostics))
+    payload["provider"] = result.availability.provider_id
+    payload["ok"] = result.availability.usable
+    payload["session_count"] = result.availability.readable_sessions
+    payload["controllable_count"] = result.availability.controllable_sessions
+    return payload
+
+
+def provider_snapshot_payload(results: list[ProviderProbeResult], source: str = "live_probe", observed_at: float | None = None) -> dict:
+    usable = [r.availability for r in results if r.availability.usable]
+    default_provider_id: str | None = None
+    default_filter = "all"
+    if len(usable) == 1:
+        default_provider_id = usable[0].provider_id
+        default_filter = usable[0].provider_id
+    elif len(usable) > 1:
+        launchable = [p for p in usable if p.launchable]
+        default_provider_id = launchable[0].provider_id if launchable else usable[0].provider_id
+
+    ts = observed_at if observed_at is not None else time.time()
+    return {
+        "schema_version": 1,
+        "providers": [availability_dict(r.availability) for r in results],
+        "default_provider_id": default_provider_id,
+        "default_filter": default_filter,
+        "observed_at": ts,
+        "source": source,
+    }
+
+
+def failed_probe(descriptor: ProviderDescriptor, exc: Exception) -> ProviderProbeResult:
+    note = f"{type(exc).__name__}: {str(exc)[:160]}"
+    availability = ProviderAvailability(
+        provider_id=descriptor.provider_id,
+        display_name=descriptor.display_name,
+        kind=descriptor.kind,
+        installed=False,
+        usable=False,
+        launchable=False,
+        auth_state="unknown",
+        config_state="unknown",
+        readable_sessions=0,
+        live_sessions=0,
+        controllable_sessions=0,
+        capabilities=("detect",),
+        setup_actions=("repair_provider_probe",),
+        notes=(note,),
+    )
+    return ProviderProbeResult(
+        descriptor=descriptor,
+        availability=availability,
+        diagnostics=ProviderDiagnostics(),
+        observed_at=time.time(),
+    )

package/payload/mac/companiond/providers/claude.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from .base import (
+    ProviderAdapter,
+    ProviderAvailability,
+    ProviderDescriptor,
+    ProviderDiagnostics,
+    ProviderProbeResult,
+    cli_version,
+    command_line_count,
+    count_dirs,
+    json_hook_count,
+    resolve_executable,
+)
+
+
+class ClaudeProviderAdapter(ProviderAdapter):
+    descriptor = ProviderDescriptor(
+        provider_id="claude",
+        display_name="Claude",
+        kind="terminal_cli",
+        builtin=True,
+        docs_url="https://docs.anthropic.com/en/docs/claude-code",
+    )
+
+    def __init__(self, home: Path | None = None):
+        self.home = home or Path.home()
+
+    @property
+    def candidates(self) -> list[Path]:
+        return [
+            self.home / ".local" / "bin" / "claude",
+            Path("/opt/homebrew/bin/claude"),
+            Path("/usr/local/bin/claude"),
+        ]
+
+    def supports(self, capability: str) -> bool:
+        return capability in {
+            "detect",
+            "status",
+            "list_sessions",
+            "read_transcript",
+            "spawn",
+            "live_state",
+            "send_text",
+            "interrupt",
+            "terminate",
+            "commands",
+            "search",
+            "mcp",
+            "export",
+            "resume",
+            "orchestration_launch",
+            "worker_telemetry",
+            "worker_control",
+            "semantic_index",
+        }
+
+    def probe(self) -> ProviderProbeResult:
+        resolved = resolve_executable("claude", self.candidates, env_var="PAIRLING_CLAUDE_BIN")
+        config_path = self.home / ".claude" / "settings.json"
+        hook_count = json_hook_count(config_path)
+        installed = resolved is not None
+        notes: list[str] = []
+        setup_actions: list[str] = []
+        if not installed:
+            notes.append("Claude CLI not found in configured, known, or daemon PATH locations")
+            setup_actions.append("install_cli")
+        if not config_path.is_file():
+            notes.append("Claude settings.json not found")
+            setup_actions.append("configure_provider")
+        capabilities = (
+            "detect",
+            "status",
+            "list_sessions",
+            "read_transcript",
+            "spawn",
+            "live_state",
+            "send_text",
+            "interrupt",
+            "terminate",
+            "commands",
+            "search",
+            "mcp",
+            "export",
+            "resume",
+            "orchestration_launch",
+            "worker_telemetry",
+            "worker_control",
+            "semantic_index",
+        ) if installed else ("detect", "status")
+        availability = ProviderAvailability(
+            provider_id=self.descriptor.provider_id,
+            display_name=self.descriptor.display_name,
+            kind=self.descriptor.kind,
+            installed=installed,
+            usable=installed,
+            launchable=installed,
+            auth_state="ready" if installed else "missing_cli",
+            config_state="ready" if config_path.is_file() else "missing",
+            readable_sessions=0,
+            live_sessions=0,
+            controllable_sessions=0,
+            capabilities=capabilities,
+            setup_actions=tuple(dict.fromkeys(setup_actions)),
+            notes=tuple(notes),
+        )
+        diagnostics = ProviderDiagnostics(
+            cli_path=str(resolved.path) if resolved else None,
+            cli_path_source=resolved.source if resolved else None,
+            version=cli_version(resolved.path) if resolved else None,
+            config_path=str(config_path),
+            config_exists=config_path.is_file(),
+            hook_count=hook_count,
+            hooks_configured=hook_count > 0,
+            mcp_count=command_line_count(resolved.path, ["mcp", "list"], timeout=0.75) if resolved else None,
+            plugin_count=count_dirs(self.home / ".claude" / "plugins", excluded={"cache"}),
+        )
+        return ProviderProbeResult(
+            descriptor=self.descriptor,
+            availability=availability,
+            diagnostics=diagnostics,
+            observed_at=time.time(),
+        )

package/payload/mac/companiond/providers/codex.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from .base import (
+    ProviderAdapter,
+    ProviderAvailability,
+    ProviderDescriptor,
+    ProviderDiagnostics,
+    ProviderProbeResult,
+    cli_version,
+    command_line_count,
+    count_dirs,
+    json_hook_count,
+    resolve_executable,
+)
+
+
+class CodexProviderAdapter(ProviderAdapter):
+    descriptor = ProviderDescriptor(
+        provider_id="codex",
+        display_name="Codex",
+        kind="terminal_cli",
+        builtin=True,
+        docs_url="https://developers.openai.com/codex",
+    )
+
+    def __init__(self, home: Path | None = None):
+        self.home = home or Path.home()
+
+    @property
+    def candidates(self) -> list[Path]:
+        return [
+            self.home / ".local" / "bin" / "codex",
+            Path("/opt/homebrew/bin/codex"),
+            Path("/usr/local/bin/codex"),
+        ]
+
+    def supports(self, capability: str) -> bool:
+        return capability in {
+            "detect",
+            "status",
+            "list_sessions",
+            "read_transcript",
+            "spawn",
+            "live_state",
+            "send_text",
+            "interrupt",
+            "terminate",
+            "commands",
+            "search",
+            "terminal_output",
+            "mcp",
+            "export",
+            "orchestration_launch",
+            "worker_telemetry",
+        }
+
+    def probe(self) -> ProviderProbeResult:
+        resolved = resolve_executable("codex", self.candidates, env_var="PAIRLING_CODEX_BIN")
+        config_path = self.home / ".codex" / "config.toml"
+        hooks_path = self.home / ".codex" / "hooks.json"
+        hook_count = json_hook_count(hooks_path)
+        installed = resolved is not None
+        notes: list[str] = []
+        setup_actions: list[str] = []
+        if not installed:
+            notes.append("Codex CLI not found in configured, known, or daemon PATH locations")
+            setup_actions.append("install_cli")
+        if not config_path.is_file():
+            notes.append("Codex config.toml not found")
+            setup_actions.append("configure_provider")
+        capabilities = (
+            "detect",
+            "status",
+            "list_sessions",
+            "read_transcript",
+            "spawn",
+            "live_state",
+            "send_text",
+            "interrupt",
+            "terminate",
+            "commands",
+            "search",
+            "terminal_output",
+            "mcp",
+            "export",
+            "orchestration_launch",
+            "worker_telemetry",
+        ) if installed else ("detect", "status")
+        availability = ProviderAvailability(
+            provider_id=self.descriptor.provider_id,
+            display_name=self.descriptor.display_name,
+            kind=self.descriptor.kind,
+            installed=installed,
+            usable=installed,
+            launchable=installed,
+            auth_state="ready" if installed else "missing_cli",
+            config_state="ready" if config_path.is_file() else "missing",
+            readable_sessions=0,
+            live_sessions=0,
+            controllable_sessions=0,
+            capabilities=capabilities,
+            setup_actions=tuple(dict.fromkeys(setup_actions)),
+            notes=tuple(notes),
+        )
+        diagnostics = ProviderDiagnostics(
+            cli_path=str(resolved.path) if resolved else None,
+            cli_path_source=resolved.source if resolved else None,
+            version=cli_version(resolved.path) if resolved else None,
+            config_path=str(config_path),
+            config_exists=config_path.is_file(),
+            hook_count=hook_count,
+            hooks_configured=hook_count > 0,
+            mcp_count=command_line_count(resolved.path, ["mcp", "list"], timeout=0.75) if resolved else None,
+            plugin_count=count_dirs(self.home / ".codex" / "plugins"),
+        )
+        return ProviderProbeResult(
+            descriptor=self.descriptor,
+            availability=availability,
+            diagnostics=diagnostics,
+            observed_at=time.time(),
+        )

package/payload/mac/companiond/providers/external.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import time
+
+from .base import ProviderAdapter, ProviderAvailability, ProviderDescriptor, ProviderDiagnostics, ProviderProbeResult
+
+
+EXTERNAL_DESCRIPTORS = [
+    ProviderDescriptor("aider", "Aider", "terminal_cli", builtin=False, docs_url="https://aider.chat/docs/"),
+    ProviderDescriptor("opencode", "OpenCode", "terminal_cli", builtin=False, docs_url="https://opencode.ai/docs"),
+    ProviderDescriptor("hermes_agent", "Hermes Agent", "terminal_cli", builtin=False, docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/cli"),
+    ProviderDescriptor("grok_build", "Grok Build", "terminal_cli", builtin=False, docs_url="https://x.ai/cli"),
+    ProviderDescriptor("antigravity", "Antigravity", "agent_platform", builtin=False, docs_url="https://developers.googleblog.com/en/build-with-google-antigravity-our-new-agentic-development-platform/"),
+]
+
+
+class DisabledExternalProviderAdapter(ProviderAdapter):
+    def __init__(self, descriptor: ProviderDescriptor):
+        self.descriptor = descriptor
+
+    def supports(self, capability: str) -> bool:
+        return capability == "detect"
+
+    def probe(self) -> ProviderProbeResult:
+        availability = ProviderAvailability(
+            provider_id=self.descriptor.provider_id,
+            display_name=self.descriptor.display_name,
+            kind=self.descriptor.kind,
+            installed=False,
+            usable=False,
+            launchable=False,
+            auth_state="unsupported",
+            config_state="unsupported",
+            readable_sessions=0,
+            live_sessions=0,
+            controllable_sessions=0,
+            capabilities=("detect",),
+            setup_actions=("provider_sprint_required",),
+            notes=("Provider descriptor is present for future integration; adapter is disabled.",),
+        )
+        return ProviderProbeResult(
+            descriptor=self.descriptor,
+            availability=availability,
+            diagnostics=ProviderDiagnostics(),
+            observed_at=time.time(),
+        )

package/payload/mac/companiond/providers/registry.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .base import ProviderAdapter, ProviderDescriptor, failed_probe, is_valid_provider_id, normalize_provider_id
+from .claude import ClaudeProviderAdapter
+from .codex import CodexProviderAdapter
+from .external import DisabledExternalProviderAdapter, EXTERNAL_DESCRIPTORS
+
+
+def _external_enabled_ids() -> set[str]:
+    raw = os.environ.get("PAIRLING_EXPERIMENTAL_PROVIDERS", "")
+    if raw.strip().lower() in {"1", "true", "yes", "all", "*"}:
+        return {d.provider_id for d in EXTERNAL_DESCRIPTORS}
+    return {
+        normalize_provider_id(item)
+        for item in raw.split(",")
+        if is_valid_provider_id(item)
+    }
+
+
+def provider_adapters(home: Path | None = None, include_external: bool | None = None) -> list[ProviderAdapter]:
+    adapters: list[ProviderAdapter] = [
+        ClaudeProviderAdapter(home=home),
+        CodexProviderAdapter(home=home),
+    ]
+    enabled = _external_enabled_ids() if include_external is None else ({d.provider_id for d in EXTERNAL_DESCRIPTORS} if include_external else set())
+    for descriptor in EXTERNAL_DESCRIPTORS:
+        if descriptor.provider_id in enabled:
+            adapters.append(DisabledExternalProviderAdapter(descriptor))
+    return adapters
+
+
+def provider_ids(include_external: bool | None = None) -> set[str]:
+    return {adapter.descriptor.provider_id for adapter in provider_adapters(include_external=include_external)}
+
+
+def provider_descriptors(include_external: bool | None = None) -> list[ProviderDescriptor]:
+    return [adapter.descriptor for adapter in provider_adapters(include_external=include_external)]
+
+
+def known_provider_ids() -> set[str]:
+    return {"claude", "codex", *(d.provider_id for d in EXTERNAL_DESCRIPTORS)}
+
+
+def get_provider(provider_id: str, home: Path | None = None, include_external: bool | None = None) -> ProviderAdapter | None:
+    wanted = normalize_provider_id(provider_id)
+    for adapter in provider_adapters(home=home, include_external=include_external):
+        if adapter.descriptor.provider_id == wanted:
+            return adapter
+    return None
+
+
+def iter_providers(provider_filter: str = "all", home: Path | None = None, include_external: bool | None = None) -> list[ProviderAdapter]:
+    provider_filter = normalize_provider_id(provider_filter or "all")
+    adapters = provider_adapters(home=home, include_external=include_external)
+    if provider_filter == "all":
+        return adapters
+    return [adapter for adapter in adapters if adapter.descriptor.provider_id == provider_filter]
+
+
+def probe_all(provider_filter: str = "all", home: Path | None = None, include_external: bool | None = None):
+    results = []
+    for adapter in iter_providers(provider_filter=provider_filter, home=home, include_external=include_external):
+        try:
+            results.append(adapter.probe())
+        except Exception as exc:
+            results.append(failed_probe(adapter.descriptor, exc))
+    return results