agentbridge-core 0.1.0__py3-none-any.whl

agentbridge/__init__.py

@@ -0,0 +1,5 @@
+"""AgentBridge: provider-agnostic orchestration for AI coding agents."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

agentbridge/__main__.py

@@ -0,0 +1,3 @@
+from agentbridge.main import main
+
+main()

agentbridge/agents/antigravity/adapter.py

@@ -0,0 +1,211 @@
+"""Google Antigravity remote agent: human-in-the-loop handoff.
+
+No documented, verified headless task API was available when this adapter was
+written, so AgentBridge does **not** start remote executions. ``execute``
+generates a task packet and instructions; a developer launches the remote
+session with Antigravity's own supported workflow, and the resulting branch is
+imported with ``agentbridge remote import``. The adapter never reports that a
+remote task ran.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from agentbridge.agents.base import (
+    AgentAdapter,
+    AvailabilityReport,
+    ExecutionRequest,
+    ExecutionResult,
+    ExecutionState,
+)
+from agentbridge.agents.capabilities import Capability, OperationSupport, ProviderCapabilities
+from agentbridge.config.settings import ProviderSettings
+from agentbridge.execution.process import resolve_executable
+from agentbridge.workspace.git import Git
+
+DOCS_URL = "https://antigravity.google/docs/remote-agents"
+_USERINFO = re.compile(r"(?<=://)[^/@\s]+@")
+
+
+def sanitize_remote_url(url: str) -> str:
+    """Strip any embedded credentials from a git remote URL."""
+    return _USERINFO.sub("", url)
+
+
+def remote_branch_name(task_id: str) -> str:
+    return f"agentbridge-remote/{task_id}"
+
+
+class AntigravityRemoteAdapter(AgentAdapter):
+    provider_type = "antigravity_remote"
+
+    def __init__(self, name: str, settings: ProviderSettings) -> None:
+        super().__init__(name, settings)
+        self.command = settings.command or "agy"
+
+    async def check_availability(self) -> AvailabilityReport:
+        executable = resolve_executable(self.command)
+        details = [
+            "Execution mode: remote_handoff (manual). AgentBridge generates a task packet; "
+            "you launch the remote agent yourself.",
+            f"Documentation: {DOCS_URL}",
+        ]
+        if executable:
+            details.append(f"Antigravity CLI found at {executable} (commands not auto-invoked)")
+        else:
+            details.append(
+                f"Antigravity CLI '{self.command}' not found; packets can still be generated, "
+                "but you need Antigravity installed to launch the remote session."
+            )
+        # Packet generation is local and always possible. Remote work also needs the
+        # repository to be reachable from the remote environment (a git remote).
+        return AvailabilityReport(
+            available=True, executable=executable, auth="unknown", details=details
+        )
+
+    async def get_capabilities(self) -> ProviderCapabilities:
+        return ProviderCapabilities(
+            provider_type=self.provider_type,
+            capabilities=frozenset(
+                {
+                    Capability.EDIT_CODE,
+                    Capability.ANALYZE,
+                    Capability.REMOTE_WORKSPACE,
+                    Capability.HUMAN_IN_THE_LOOP,
+                }
+            ),
+            execution=OperationSupport.MANUAL,
+            cancellation=OperationSupport.UNSUPPORTED,
+            status_query=OperationSupport.UNSUPPORTED,
+            notes=[
+                "No verified headless API: execution is a manual handoff.",
+                "Remote agents cannot see local worktrees; results return via git.",
+                "Token and cost data are not available to AgentBridge.",
+            ],
+        )
+
+    async def execute(self, request: ExecutionRequest) -> ExecutionResult:
+        repo_root = Path(request.repository_info.get("root", "."))
+        packet = build_packet(request, repo_root, self.settings.git_remote)
+        request.output_dir.mkdir(parents=True, exist_ok=True)
+        json_path = request.output_dir / "remote_packet.json"
+        md_path = request.output_dir / "remote_packet.md"
+        json_path.write_text(json.dumps(packet, indent=2), encoding="utf-8")
+        md_path.write_text(render_packet_markdown(packet), encoding="utf-8")
+        return ExecutionResult(
+            execution_id=request.execution_id,
+            provider=self.name,
+            state=ExecutionState.HANDOFF_PREPARED,
+            summary=(
+                "Remote handoff packet prepared. No remote execution was started by "
+                f"AgentBridge. Follow {md_path} to launch it."
+            ),
+            output_path=str(md_path),
+            artifacts={"packet_json": str(json_path), "packet_markdown": str(md_path)},
+            metadata={"warnings": packet["warnings"]},
+        )
+
+
+def build_packet(request: ExecutionRequest, repo_root: Path, git_remote: str) -> dict[str, Any]:
+    git = Git(repo_root)
+    warnings: list[str] = []
+    remote_url: str | None = None
+    result = git.run("remote", "get-url", git_remote, check=False)
+    if result.returncode == 0:
+        remote_url = sanitize_remote_url(result.stdout.strip())
+    else:
+        warnings.append(
+            f"Git remote '{git_remote}' is not configured. The remote agent needs the "
+            "repository on a hosted remote (e.g. GitHub)."
+        )
+    base_commit = request.repository_info.get("base_commit")
+    base_branch = request.repository_info.get("base_branch")
+    if remote_url and base_commit:
+        contains = git.run("branch", "-r", "--contains", str(base_commit), check=False)
+        if contains.returncode != 0 or not contains.stdout.strip():
+            warnings.append(
+                f"Base commit {str(base_commit)[:12]} is not on any remote-tracking branch; "
+                f"push it ('git push {git_remote} {base_branch}') before launching."
+            )
+    result_branch = remote_branch_name(request.task_id)
+    return {
+        "packet_version": 1,
+        "task_id": request.task_id,
+        "title": request.title,
+        "description": request.description,
+        "role": request.role,
+        "acceptance_criteria": request.acceptance_criteria,
+        "expected_files": request.expected_files,
+        "repository": {
+            "remote": git_remote,
+            "url": remote_url,
+            "base_branch": base_branch,
+            "base_commit": base_commit,
+        },
+        "deliverables": {
+            "result_branch": result_branch,
+            "instructions": (
+                f"Create branch '{result_branch}' from the base commit, implement the task, "
+                "commit, and push the branch (or open a pull request from it). Do not push "
+                "to the base branch."
+            ),
+        },
+        "prompt": request.prompt,
+        "import_command": (
+            f"agentbridge remote import {request.task_id} --branch {result_branch} "
+            f"--remote {git_remote}"
+        ),
+        "warnings": warnings,
+        "documentation": DOCS_URL,
+        "status_note": "This packet does not mean the task ran. It is a handoff.",
+    }
+
+
+def render_packet_markdown(packet: dict[str, Any]) -> str:
+    repo = packet["repository"]
+    lines = [
+        f"# Remote handoff: {packet['task_id']}",
+        "",
+        "> AgentBridge has **not** executed this task. Launch it yourself using a",
+        f"> supported Antigravity workflow ({packet['documentation']}).",
+        "",
+        f"**Title:** {packet['title']}",
+        "",
+        "## Repository",
+        "",
+        f"- Remote: `{repo['remote']}` {repo['url'] or '(not configured)'}",
+        f"- Base branch: `{repo['base_branch']}`",
+        f"- Base commit: `{repo['base_commit']}`",
+        "",
+        "## Acceptance criteria",
+        "",
+        *[f"- {item}" for item in packet["acceptance_criteria"] or ["(none specified)"]],
+        "",
+        "## Steps",
+        "",
+        "1. Make sure the base commit is pushed to the remote.",
+        "2. Start a remote agent session attached to this repository using Antigravity.",
+        "3. Give it the prompt below.",
+        f"4. Ask it to push its work to branch `{packet['deliverables']['result_branch']}`.",
+        "5. When it finishes, import and validate the result locally:",
+        "",
+        "```bash",
+        packet["import_command"],
+        "```",
+        "",
+        "6. Review the validation report, then approve or reject with",
+        f"   `agentbridge tasks approve {packet['task_id']}` / `agentbridge tasks reject ...`.",
+        "",
+        "## Prompt",
+        "",
+        "```text",
+        packet["prompt"],
+        "```",
+    ]
+    if packet["warnings"]:
+        lines += ["", "## Warnings", "", *[f"- {w}" for w in packet["warnings"]]]
+    return "\n".join(lines) + "\n"

agentbridge/agents/base.py

@@ -0,0 +1,138 @@
+"""Provider-independent agent adapter contract."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentbridge.agents.capabilities import ProviderCapabilities
+from agentbridge.config.settings import ProviderSettings
+
+
+class ExecutionState(StrEnum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+    TIMED_OUT = "timed_out"
+    CANCELLED = "cancelled"
+    INTERRUPTED = "interrupted"
+    INVALID_OUTPUT = "invalid_output"
+    UNAVAILABLE = "unavailable"
+    HANDOFF_PREPARED = "handoff_prepared"  # nothing executed; a human must act
+    RUNNING = "running"
+    UNKNOWN = "unknown"
+
+
+class UnsupportedOperationError(Exception):
+    """Raised when an adapter is asked for an operation it does not support."""
+
+
+class AvailabilityReport(BaseModel):
+    available: bool
+    version: str | None = None
+    executable: str | None = None
+    auth: Literal["ok", "missing", "unknown", "not_required"] = "unknown"
+    details: list[str] = Field(default_factory=list)
+
+
+class UsageMetrics(BaseModel):
+    """Usage data. ``None`` means *unavailable*, never zero."""
+
+    model: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cost_usd: float | None = None
+    # "measured" (billing data) vs "estimated" (e.g. CLI-computed figure).
+    cost_kind: Literal["measured", "estimated"] | None = None
+    cost_source: str | None = None
+
+
+class ExecutionRequest(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    task_id: str
+    execution_id: str
+    attempt: int = 1
+    title: str
+    description: str = ""
+    role: str
+    prompt: str
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    expected_files: list[str] = Field(default_factory=list)
+    workdir: Path | None = None
+    output_dir: Path
+    timeout_seconds: int
+    agents_may_edit: bool = True
+    permission_mode: str | None = None
+    repository_info: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExecutionResult(BaseModel):
+    execution_id: str
+    provider: str
+    state: ExecutionState
+    summary: str = ""
+    exit_code: int | None = None
+    duration_seconds: float | None = None
+    output_path: str | None = None
+    error: str | None = None
+    retryable: bool = False
+    usage: UsageMetrics = Field(default_factory=UsageMetrics)
+    structured_output: dict[str, Any] | None = None
+    artifacts: dict[str, str] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentAdapter(ABC):
+    """Contract every provider adapter implements.
+
+    Unsupported operations raise ``UnsupportedOperationError`` (and are declared
+    as such in ``get_capabilities``); adapters must never fake support.
+    """
+
+    provider_type: str = "abstract"
+
+    def __init__(self, name: str, settings: ProviderSettings) -> None:
+        self.name = name
+        self.settings = settings
+        self._cancel_events: dict[str, asyncio.Event] = {}
+
+    @abstractmethod
+    async def check_availability(self) -> AvailabilityReport: ...
+
+    @abstractmethod
+    async def get_capabilities(self) -> ProviderCapabilities: ...
+
+    @abstractmethod
+    async def execute(self, request: ExecutionRequest) -> ExecutionResult: ...
+
+    async def get_status(self, execution_id: str) -> ExecutionState:
+        """Status of an execution, possibly from a previous process.
+
+        The default is honest: without provider support the state is UNKNOWN.
+        """
+        return ExecutionState.UNKNOWN
+
+    async def cancel(self, execution_id: str) -> bool:
+        """Request cancellation. Returns True if a running execution was signalled."""
+        event = self._cancel_events.get(execution_id)
+        if event is None:
+            return False
+        event.set()
+        return True
+
+    # Helpers for subclasses ------------------------------------------------
+    def _cancel_event(self, execution_id: str) -> asyncio.Event:
+        event = self._cancel_events.get(execution_id)
+        if event is None:
+            event = asyncio.Event()
+            self._cancel_events[execution_id] = event
+        return event
+
+    def _forget(self, execution_id: str) -> None:
+        self._cancel_events.pop(execution_id, None)

agentbridge/agents/capabilities.py

@@ -0,0 +1,48 @@
+"""Provider capability model.
+
+Capabilities are *declared* by adapters. The router only assigns a task to a
+provider that declares every capability the task requires; nothing is assumed.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class Capability(StrEnum):
+    PLAN = "plan"  # can return a structured task plan
+    EDIT_CODE = "edit_code"  # can modify files in an assigned workspace
+    ANALYZE = "analyze"  # can read a repository and produce analysis text
+    REVIEW = "review"  # can review a diff and report findings
+    LOCAL_WORKSPACE = "local_workspace"  # operates on a local directory
+    REMOTE_WORKSPACE = "remote_workspace"  # operates in a provider-managed environment
+    STRUCTURED_OUTPUT = "structured_output"  # machine-readable output format
+    CANCEL = "cancel"  # execution can be cancelled
+    STATUS = "status"  # execution status can be queried after a restart
+    COST_REPORTING = "cost_reporting"  # reports cost figures
+    TOKEN_REPORTING = "token_reporting"  # reports token usage
+    HUMAN_IN_THE_LOOP = "human_in_the_loop"  # requires a person to complete execution
+
+
+class OperationSupport(StrEnum):
+    SUPPORTED = "supported"
+    UNSUPPORTED = "unsupported"
+    EXPERIMENTAL = "experimental"
+    MANUAL = "manual"  # performed by a human following generated instructions
+
+
+class ProviderCapabilities(BaseModel):
+    provider_type: str
+    capabilities: frozenset[Capability] = Field(default_factory=frozenset)
+    execution: OperationSupport = OperationSupport.SUPPORTED
+    cancellation: OperationSupport = OperationSupport.UNSUPPORTED
+    status_query: OperationSupport = OperationSupport.UNSUPPORTED
+    notes: list[str] = Field(default_factory=list)
+
+    def supports(self, required: set[Capability] | frozenset[Capability]) -> bool:
+        return set(required).issubset(self.capabilities)
+
+    def missing(self, required: set[Capability] | frozenset[Capability]) -> set[Capability]:
+        return set(required) - set(self.capabilities)