orkestra-runtime 0.1.2__py3-none-any.whl

orkestra/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

orkestra/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Agent adapter layer."""
+
+from orkestra.adapters.base import AdapterInfo, AgentAdapter, InvocationSpec
+from orkestra.adapters.registry import build_adapter, builtin_adapter_ids
+
+__all__ = [
+    "AdapterInfo",
+    "AgentAdapter",
+    "InvocationSpec",
+    "build_adapter",
+    "builtin_adapter_ids",
+]

orkestra/adapters/antigravity_cli.py

@@ -0,0 +1,231 @@
+"""Antigravity CLI adapter (`agy`) — first-party Google adapter.
+
+Surface verified live 2026-07-24 against agy 1.1.6 (samples/):
+
+- ``agy -p --output-format stream-json`` emits JSONL: ``init``
+  (conversation_id, tools, permission_mode), ``step_update``
+  (``step_type: agent_response`` carries ``text_delta`` + usage), and a
+  terminal ``result`` envelope (``conversation_id``, ``status``,
+  ``response``, ``usage``).
+- ``--output-format`` is accepted although undocumented in ``--help``;
+  the parser therefore also handles plain-text output as a fallback.
+- No schema-constrained output: structured requests use prompt-level
+  JSON plus :func:`extract_json_object` with kernel-side repair retries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from orkestra.adapters.base import AdapterInfo, AgentAdapter, InvocationSpec, StreamParser
+from orkestra.adapters.jsonl import extract_json_object, try_parse_json
+from orkestra.adapters.runner import run_capture
+from orkestra.schemas.agent import (
+    AgentEvent,
+    AgentResult,
+    AuthStatus,
+    ErrorKind,
+    EventKind,
+    ResultStatus,
+    SessionRef,
+    Usage,
+)
+from orkestra.schemas.task import TaskBrief
+
+
+class AntigravityParser(StreamParser):
+    def __init__(self, expect_structured: bool) -> None:
+        self.expect_structured = expect_structured
+        self.conversation_id = ""
+        self.final: dict[str, Any] | None = None
+        self.plain_lines: list[str] = []
+        self.stderr_tail: list[str] = []
+
+    def feed_line(self, line: str, *, is_stderr: bool) -> Iterable[AgentEvent]:
+        if is_stderr:
+            if line.strip():
+                self.stderr_tail = [*self.stderr_tail, line][-20:]
+            return
+        obj = try_parse_json(line)
+        if obj is None:
+            # Plain-text fallback (older versions / flag removed upstream).
+            self.plain_lines.append(line)
+            if line.strip():
+                yield AgentEvent(kind=EventKind.TEXT, text=line[:2000])
+            return
+        event = obj.get("event")
+        if event == "init":
+            init = obj.get("init") or {}
+            self.conversation_id = str(obj.get("conversation_id") or "")
+            yield AgentEvent(
+                kind=EventKind.STARTED,
+                text="antigravity session initialized",
+                data={
+                    "conversation_id": self.conversation_id,
+                    "permission_mode": init.get("permission_mode", ""),
+                },
+            )
+        elif event == "step_update":
+            step = obj.get("step_update") or {}
+            step_type = step.get("step_type")
+            if step_type == "agent_response" and step.get("text_delta"):
+                yield AgentEvent(kind=EventKind.TEXT, text=str(step["text_delta"])[:4000])
+            elif step_type not in (None, "user_input", "checkpoint", "unknown"):
+                yield AgentEvent(kind=EventKind.TOOL, text=str(step_type))
+        elif event == "result":
+            self.final = obj.get("result") or {}
+
+    def result(self, exit_code: int | None, duration_s: float, cwd: str) -> AgentResult:
+        stderr = "\n".join(self.stderr_tail)
+        if self.final is not None:
+            usage_raw = self.final.get("usage") or {}
+            usage = Usage(
+                input_tokens=int(usage_raw.get("input_tokens") or 0),
+                output_tokens=int(usage_raw.get("output_tokens") or 0),
+            )
+            conversation_id = str(self.final.get("conversation_id") or self.conversation_id)
+            status = str(self.final.get("status") or "")
+            text = str(self.final.get("response") or "")
+            ok = status.upper() == "SUCCESS" and (exit_code in (0, None))
+            structured = extract_json_object(text) if self.expect_structured else None
+            if ok and self.expect_structured and structured is None:
+                return AgentResult(
+                    status=ResultStatus.ERROR,
+                    error_kind=ErrorKind.INVALID_OUTPUT,
+                    error_detail="expected JSON in response, none found",
+                    final_text=text,
+                    exit_code=exit_code,
+                    duration_s=duration_s,
+                )
+            return AgentResult(
+                status=ResultStatus.OK if ok else ResultStatus.ERROR,
+                error_kind=ErrorKind.NONE if ok else ErrorKind.UNKNOWN,
+                error_detail="" if ok else f"status={status}",
+                final_text=text,
+                structured=structured,
+                session=(
+                    SessionRef(session_id=conversation_id, cwd=cwd) if conversation_id else None
+                ),
+                usage=usage,
+                exit_code=exit_code,
+                duration_s=duration_s,
+            )
+        # Plain-text fallback path.
+        text = "\n".join(self.plain_lines).strip()
+        lower = (stderr + text).lower()
+        if exit_code == 0 and text:
+            structured = extract_json_object(text) if self.expect_structured else None
+            if self.expect_structured and structured is None:
+                return AgentResult(
+                    status=ResultStatus.ERROR,
+                    error_kind=ErrorKind.INVALID_OUTPUT,
+                    error_detail="expected JSON in response, none found",
+                    final_text=text,
+                    exit_code=exit_code,
+                    duration_s=duration_s,
+                )
+            return AgentResult(
+                status=ResultStatus.OK,
+                final_text=text,
+                structured=structured,
+                exit_code=exit_code,
+                duration_s=duration_s,
+            )
+        if "auth" in lower or "sign in" in lower or "log in" in lower:
+            kind = ErrorKind.AUTH
+        elif "rate limit" in lower or "quota" in lower:
+            kind = ErrorKind.RATE_LIMIT
+        else:
+            kind = ErrorKind.CRASH if exit_code else ErrorKind.INVALID_OUTPUT
+        return AgentResult(
+            status=ResultStatus.ERROR,
+            error_kind=kind,
+            error_detail=(stderr or text or f"exit {exit_code}")[:2000],
+            exit_code=exit_code,
+            duration_s=duration_s,
+        )
+
+
+class AntigravityCliAdapter(AgentAdapter):
+    adapter_id = "antigravity-cli"
+    executable = "agy"
+
+    def __init__(self, model: str | None = None, autonomy: str = "safe") -> None:
+        self.model = model
+        self.autonomy = autonomy
+
+    async def detect(self) -> AdapterInfo:
+        path = self.which()
+        if not path:
+            return AdapterInfo(self.adapter_id, available=False, detail="`agy` not found on PATH")
+        code, out, err = await run_capture([path, "--version"])
+        if code != 0:
+            return AdapterInfo(
+                self.adapter_id,
+                available=False,
+                executable=path,
+                detail=f"--version failed: {err.strip()[:200]}",
+            )
+        return AdapterInfo(
+            self.adapter_id,
+            available=True,
+            version=out.strip(),
+            executable=path,
+            features=frozenset({"resume", "stream", "os_sandbox"}),
+            detail=(
+                "note: Antigravity ToS restricts third-party access to the "
+                "service; Orkestra only launches the official binary under "
+                "your own login — review antigravity.google/terms"
+            ),
+        )
+
+    async def check_auth(self) -> AuthStatus:
+        path = self.which()
+        if not path:
+            return AuthStatus(ready=False, detail="`agy` not found on PATH")
+        # `agy models` succeeds only when authenticated and consumes no
+        # model quota (verified locally 2026-07-24).
+        code, out, err = await run_capture([path, "models"], timeout_s=30)
+        if code == 0 and out.strip():
+            return AuthStatus(ready=True, detail="authenticated (models listed)")
+        return AuthStatus(
+            ready=False,
+            detail=(err or out).strip()[:200] or "run `agy` interactively to sign in",
+        )
+
+    def build_invocation(self, brief: TaskBrief) -> InvocationSpec:
+        timeout_arg = f"{max(brief.timeout_s, 60)}s"
+        instructions = brief.instructions
+        if brief.json_schema is not None:
+            # No native schema flag: embed the schema in the prompt and rely
+            # on extract_json_object + kernel-side validation/retries.
+            import json as _json
+
+            instructions += (
+                "\n\nRespond with ONLY one JSON object (no prose, no code "
+                "fences) conforming to this JSON Schema:\n" + _json.dumps(brief.json_schema)
+            )
+        argv = [
+            self.which() or self.executable,
+            "-p",
+            instructions,
+            "--output-format",
+            "stream-json",
+            "--print-timeout",
+            timeout_arg,
+        ]
+        if self.autonomy == "unsafe-full":
+            argv += ["--dangerously-skip-permissions"]
+        elif brief.kind.value in ("research", "plan", "review"):
+            argv += ["--mode", "plan"]
+        else:
+            argv += ["--mode", "accept-edits"]
+        if self.model:
+            argv += ["--model", self.model]
+        if brief.resume_session_id:
+            argv += ["--conversation", brief.resume_session_id]
+        return InvocationSpec(argv=argv, cwd=brief.cwd, timeout_s=brief.timeout_s + 30)
+
+    def make_parser(self, brief: TaskBrief) -> StreamParser:
+        return AntigravityParser(expect_structured=brief.json_schema is not None)

orkestra/adapters/base.py

@@ -0,0 +1,85 @@
+"""Adapter contract.
+
+An adapter is a pure translator between Orkestra's task brief and one
+agent CLI: it builds an argv (never a shell string), parses the CLI's
+output stream into normalized ``AgentEvent`` objects, and produces a
+structured ``AgentResult``. Process supervision (spawn, stream, timeout,
+cancel, kill) lives in :mod:`orkestra.adapters.runner`, shared by all
+adapters.
+"""
+
+from __future__ import annotations
+
+import shutil
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from orkestra.schemas.agent import AgentEvent, AgentResult, AuthStatus
+
+if TYPE_CHECKING:
+    from orkestra.schemas.task import TaskBrief
+
+
+@dataclass(frozen=True)
+class AdapterInfo:
+    """Detection result for one adapter."""
+
+    adapter_id: str
+    available: bool
+    version: str = ""
+    executable: str = ""
+    detail: str = ""
+    features: frozenset[str] = frozenset()
+    """Feature flags, e.g. {"structured_output", "resume", "structured_director"}."""
+
+
+@dataclass(frozen=True)
+class InvocationSpec:
+    """Everything the runner needs to launch one attempt."""
+
+    argv: list[str]
+    cwd: str
+    env_extra: dict[str, str] = field(default_factory=dict)
+    stdin_data: bytes | None = None
+    timeout_s: int = 1800
+
+
+class StreamParser(ABC):
+    """Incremental parser turning raw CLI output lines into events."""
+
+    @abstractmethod
+    def feed_line(self, line: str, *, is_stderr: bool) -> Iterable[AgentEvent]:
+        """Parse one output line into zero or more normalized events."""
+
+    @abstractmethod
+    def result(self, exit_code: int | None, duration_s: float, cwd: str) -> AgentResult:
+        """Produce the final structured result after process exit."""
+
+
+class AgentAdapter(ABC):
+    """Stable contract implemented by all adapters (first- and third-party)."""
+
+    adapter_id: str
+    executable: str
+
+    @abstractmethod
+    async def detect(self) -> AdapterInfo:
+        """Report availability, version, and feature flags. Never raises."""
+
+    @abstractmethod
+    async def check_auth(self) -> AuthStatus:
+        """Non-invasive auth readiness check (never reads credential stores)."""
+
+    @abstractmethod
+    def build_invocation(self, brief: TaskBrief) -> InvocationSpec:
+        """Translate a task brief into a concrete CLI invocation."""
+
+    @abstractmethod
+    def make_parser(self, brief: TaskBrief) -> StreamParser:
+        """Fresh parser for one attempt's output stream."""
+
+    def which(self) -> str | None:
+        """Locate the executable on PATH (helper for detect())."""
+        return shutil.which(self.executable)

orkestra/adapters/claude_code.py

@@ -0,0 +1,211 @@
+"""Claude Code adapter (`claude`).
+
+Surface verified 2026-07-24 against claude 2.1.219 (see
+docs/research/AGENT_INTEGRATION_RESEARCH.md and samples/):
+
+- ``claude -p --output-format stream-json --verbose`` emits JSONL:
+  ``system/init``, ``assistant``/``user`` messages, ``system/api_retry``
+  (rate-limit/auth categories), and a terminal ``type:"result"`` object
+  with ``result``, ``session_id``, ``is_error``, ``usage``,
+  ``total_cost_usd``.
+- ``--json-schema`` yields ``structured_output`` in the result envelope.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any
+
+from orkestra.adapters.base import AdapterInfo, AgentAdapter, InvocationSpec, StreamParser
+from orkestra.adapters.jsonl import try_parse_json
+from orkestra.adapters.runner import run_capture
+from orkestra.schemas.agent import (
+    AgentEvent,
+    AgentResult,
+    AuthStatus,
+    ErrorKind,
+    EventKind,
+    ResultStatus,
+    SessionRef,
+    Usage,
+)
+from orkestra.schemas.task import TaskBrief
+
+_API_ERROR_TO_KIND = {
+    "authentication_failed": ErrorKind.AUTH,
+    "oauth_org_not_allowed": ErrorKind.AUTH,
+    "billing_error": ErrorKind.AUTH,
+    "rate_limit": ErrorKind.RATE_LIMIT,
+    "overloaded": ErrorKind.RATE_LIMIT,
+}
+
+
+class ClaudeParser(StreamParser):
+    def __init__(self) -> None:
+        self.final: dict[str, Any] | None = None
+        self.last_error_kind = ErrorKind.NONE
+        self.stderr_tail: list[str] = []
+
+    def feed_line(self, line: str, *, is_stderr: bool) -> Iterable[AgentEvent]:
+        if is_stderr:
+            if line.strip():
+                self.stderr_tail = [*self.stderr_tail, line][-20:]
+            return
+        obj = try_parse_json(line)
+        if obj is None:
+            if line.strip():
+                yield AgentEvent(kind=EventKind.RAW, text=line[:2000])
+            return
+        kind = obj.get("type")
+        if kind == "system":
+            subtype = obj.get("subtype")
+            if subtype == "init":
+                yield AgentEvent(
+                    kind=EventKind.STARTED,
+                    text="claude session initialized",
+                    data={"session_id": obj.get("session_id", "")},
+                )
+            elif subtype == "api_retry":
+                category = str(obj.get("error", "unknown"))
+                self.last_error_kind = _API_ERROR_TO_KIND.get(category, ErrorKind.UNKNOWN)
+                yield AgentEvent(
+                    kind=EventKind.WARNING,
+                    text=f"api retry ({category})",
+                    data={"category": category},
+                )
+        elif kind == "assistant":
+            message = obj.get("message") or {}
+            for block in message.get("content") or []:
+                if isinstance(block, dict):
+                    if block.get("type") == "text" and block.get("text"):
+                        yield AgentEvent(kind=EventKind.TEXT, text=str(block["text"])[:4000])
+                    elif block.get("type") == "tool_use":
+                        yield AgentEvent(
+                            kind=EventKind.TOOL,
+                            text=str(block.get("name", "tool")),
+                        )
+        elif kind == "result":
+            self.final = obj
+
+    def result(self, exit_code: int | None, duration_s: float, cwd: str) -> AgentResult:
+        if self.final is not None:
+            usage_raw = self.final.get("usage") or {}
+            usage = Usage(
+                input_tokens=int(usage_raw.get("input_tokens") or 0),
+                output_tokens=int(usage_raw.get("output_tokens") or 0),
+                cached_input_tokens=int(usage_raw.get("cache_read_input_tokens") or 0),
+                total_cost_usd=self.final.get("total_cost_usd"),
+            )
+            session_id = str(self.final.get("session_id") or "")
+            structured = self.final.get("structured_output")
+            is_error = bool(self.final.get("is_error"))
+            error_kind = ErrorKind.NONE
+            detail = ""
+            if is_error:
+                error_kind = (
+                    self.last_error_kind
+                    if self.last_error_kind is not ErrorKind.NONE
+                    else ErrorKind.UNKNOWN
+                )
+                detail = str(self.final.get("subtype") or "error")
+            return AgentResult(
+                status=ResultStatus.ERROR if is_error else ResultStatus.OK,
+                error_kind=error_kind,
+                error_detail=detail,
+                final_text=str(self.final.get("result") or ""),
+                structured=structured if isinstance(structured, dict) else None,
+                session=SessionRef(session_id=session_id, cwd=cwd) if session_id else None,
+                usage=usage,
+                exit_code=exit_code,
+                duration_s=duration_s,
+            )
+        stderr = "\n".join(self.stderr_tail)
+        lower = stderr.lower()
+        if "log in" in lower or "authentication" in lower or "api key" in lower:
+            kind = ErrorKind.AUTH
+        elif self.last_error_kind is not ErrorKind.NONE:
+            kind = self.last_error_kind
+        else:
+            kind = ErrorKind.CRASH if exit_code else ErrorKind.INVALID_OUTPUT
+        return AgentResult(
+            status=ResultStatus.ERROR,
+            error_kind=kind,
+            error_detail=(stderr or "no result envelope received")[:2000],
+            exit_code=exit_code,
+            duration_s=duration_s,
+        )
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    adapter_id = "claude-code"
+    executable = "claude"
+
+    def __init__(self, model: str | None = None, autonomy: str = "safe") -> None:
+        self.model = model
+        self.autonomy = autonomy
+
+    async def detect(self) -> AdapterInfo:
+        path = self.which()
+        if not path:
+            return AdapterInfo(
+                self.adapter_id, available=False, detail="`claude` not found on PATH"
+            )
+        code, out, err = await run_capture([path, "--version"])
+        if code != 0:
+            return AdapterInfo(
+                self.adapter_id,
+                available=False,
+                executable=path,
+                detail=f"--version failed: {err.strip()[:200]}",
+            )
+        return AdapterInfo(
+            self.adapter_id,
+            available=True,
+            version=out.strip().split()[0] if out.strip() else "",
+            executable=path,
+            features=frozenset({"structured_output", "resume", "structured_director", "stream"}),
+        )
+
+    async def check_auth(self) -> AuthStatus:
+        # `claude -p` with a trivial prompt would consume quota; instead rely
+        # on detection plus the documented failure envelope at run time. A
+        # cheap deterministic signal: `claude auth status` isn't universally
+        # available, so report ready-if-installed with a caveat.
+        info = await self.detect()
+        if not info.available:
+            return AuthStatus(ready=False, detail=info.detail)
+        return AuthStatus(
+            ready=True,
+            detail="installed; auth verified lazily on first invocation",
+        )
+
+    def build_invocation(self, brief: TaskBrief) -> InvocationSpec:
+        argv = [
+            self.which() or self.executable,
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--setting-sources",
+            "user",
+        ]
+        if self.autonomy == "unsafe-full":
+            argv += ["--permission-mode", "bypassPermissions"]
+        else:
+            argv += ["--permission-mode", "acceptEdits"]
+        if self.model:
+            argv += ["--model", self.model]
+        if brief.json_schema is not None:
+            # --json-schema requires --output-format json; the single result
+            # envelope is still parsed by ClaudeParser.
+            argv[argv.index("stream-json")] = "json"
+            argv.remove("--verbose")
+            argv += ["--json-schema", json.dumps(brief.json_schema)]
+        if brief.resume_session_id:
+            argv += ["--resume", brief.resume_session_id]
+        argv.append(brief.instructions)
+        return InvocationSpec(argv=argv, cwd=brief.cwd, timeout_s=brief.timeout_s)
+
+    def make_parser(self, brief: TaskBrief) -> StreamParser:
+        return ClaudeParser()