ags-sdk 0.1.0__py3-none-any.whl

ags_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: ags-sdk
+Version: 0.1.0
+Summary: SDK for building custom adapters for AgentS
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pywinpty>=2.0; sys_platform == "win32"

ags_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+harness_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+harness_sdk/base.py,sha256=MVmsZYjvIQBa4A8vJtYS8wTUy_TAgHTDdp6V-Zz2PNI,5593
+harness_sdk/cli_base.py,sha256=xedUZ4Xxi6pPC1NV2-AWUTfDV58TZDBWD39hQEewOX8,26525
+harness_sdk/events.py,sha256=Lw51hXCTa13ZZLxgyU-A_vHedg5HJs7IT7_zFmsYDFk,2491
+harness_sdk/types.py,sha256=BQP2LbLAkH7lQomqOSR4y_F525LiM8lURgoqNiLFIdU,181
+ags_sdk-0.1.0.dist-info/METADATA,sha256=K7PkWFOUS5DarfMJ5WTKhKxnlEJl-tou6eEgkY7oPBg,211
+ags_sdk-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+ags_sdk-0.1.0.dist-info/top_level.txt,sha256=Fmz5FUPlwHvRiywbi5Nqm7qQC3_Ziqj4-Mb0lYcbrRo,12
+ags_sdk-0.1.0.dist-info/RECORD,,

ags_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ags_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+harness_sdk

harness_sdk/base.py

@@ -0,0 +1,158 @@
+"""The one canonical adapter interface.
+
+Every backend (mock, local OpenAI-compatible, Claude Code, Google CLI) implements
+``BaseAdapter``. The orchestrator and workers depend ONLY on this contract, never
+on a concrete provider — this is the project's primary lever against vendor
+lock-in. New adapters in the extension SDK subclass this and register in the
+``registry``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+
+from pydantic import BaseModel, Field
+
+from harness_sdk.events import NormalizedEvent
+from harness_sdk.types import AdapterKind
+
+
+class Capabilities(BaseModel):
+    """What a provider can do — used for routing decisions and capability gating."""
+
+    streaming: bool = True
+    tool_calling: bool = False
+    max_context: int = 8192
+    reasoning: bool = False
+    cost_known: bool = False
+    vision: bool = False
+    notes: str = ""
+
+
+class HealthStatus(BaseModel):
+    ok: bool
+    latency_ms: float = 0.0
+    detail: dict = Field(default_factory=dict)
+
+
+class Cost(BaseModel):
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    usd: float | None = None
+
+
+class Usage(BaseModel):
+    """Raw usage numbers an adapter reports, fed to ``estimate_cost``."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+
+class SessionContext(BaseModel):
+    """Everything an adapter needs to start a provider session. The harness owns
+    canonical state; this is the compact, normalized projection passed to a
+    provider for a single run — including retrieved memory context."""
+
+    run_id: str
+    session_id: str
+    workspace_slug: str
+    objective: str
+    constraints: dict = Field(default_factory=dict)
+    system_prompt: str | None = None
+    memory_context: str = ""
+    tools: list[dict] = Field(default_factory=list)
+    workspace_dir: str | None = None
+    read_only: bool = True  # safe-by-default; the engine sets the workspace's mode
+    trust_policy: str = "restricted"  # workspace.trust_policy; gates risky tool calls
+    dry_run: bool = False
+    extra: dict = Field(default_factory=dict)
+
+
+class ProviderSession(BaseModel):
+    """Opaque handle returned by ``start_session``; carries provider-side ids."""
+
+    provider_session_id: str
+    adapter_kind: AdapterKind
+    meta: dict = Field(default_factory=dict)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+class AdapterConfig(BaseModel):
+    """Resolved configuration for one adapter instance (from ``provider_configs``
+    + resolved secret). The secret is held only in memory, never persisted back."""
+
+    name: str
+    kind: AdapterKind
+    base_url: str | None = None
+    model: str | None = None
+    api_key: str | None = None  # resolved from secret_ref at construction time
+    params: dict = Field(default_factory=dict)
+    capabilities: dict = Field(default_factory=dict)
+
+
+class BaseAdapter(ABC):
+    """Strict adapter contract. All methods that touch the network are async."""
+
+    kind: AdapterKind
+
+    def __init__(self, config: AdapterConfig) -> None:
+        self.config = config
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+    @abstractmethod
+    async def start_session(self, ctx: SessionContext) -> ProviderSession:
+        """Begin a provider session for a single run. Idempotent per run_id."""
+
+    @abstractmethod
+    def stream_events(
+        self,
+        session: ProviderSession,
+        message: str,
+        *,
+        tools: list[dict] | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[NormalizedEvent]:
+        """Send a message and yield normalized events. The single hot path used by
+        workers; ``send_message`` is a thin convenience wrapper over this."""
+
+    async def send_message(
+        self,
+        session: ProviderSession,
+        message: str,
+        *,
+        tools: list[dict] | None = None,
+        stream: bool = True,
+    ) -> AsyncIterator[NormalizedEvent]:
+        """Convenience alias — delegates to ``stream_events``."""
+        return self.stream_events(session, message, tools=tools, stream=stream)
+
+    @abstractmethod
+    async def cancel_run(self, run_id: str) -> None:
+        """Best-effort cancellation of in-flight work for a run."""
+
+    # ── introspection ─────────────────────────────────────────────────────────
+    @abstractmethod
+    def list_capabilities(self) -> Capabilities: ...
+
+    @abstractmethod
+    async def health_check(self) -> HealthStatus: ...
+
+    async def list_models(self) -> list[str]:
+        """Models the provider exposes. Default: the configured model (if any).
+        Overridden per adapter to enumerate the backend's catalogue (e.g. the
+        OpenAI ``/v1/models`` endpoint or a CLI's ``models`` subcommand)."""
+        return [self.config.model] if self.config.model else []
+
+    def normalize_response(self, raw: dict) -> NormalizedEvent:
+        """Map a single provider chunk to a NormalizedEvent. Overridden per
+        adapter; the default treats ``raw`` as adapter metadata."""
+        from harness_sdk.events import AdapterMetaEvent
+
+        return AdapterMetaEvent(seq=raw.get("seq", 0), data=raw)
+
+    def estimate_cost(self, usage: Usage) -> Cost | None:
+        """Return a cost estimate where the provider exposes pricing; else None."""
+        return None

harness_sdk/cli_base.py

@@ -0,0 +1,584 @@
+"""Shared base for adapters that drive an official CLI as a subprocess.
+
+Both ``ClaudeCodeAdapter`` and ``AntigravityCliAdapter`` subclass this. The base
+owns the hard parts — async process spawn, line streaming, sequence numbering,
+cooperative cancellation (process-group kill), env/secret injection, working-dir
+gating, and an optional **PTY** mode — so each concrete adapter only declares its
+argv and how to parse the CLI's output into ``NormalizedEvent``s.
+
+Why PTY: the Antigravity CLI (``agy``) suppresses stdout when it detects a non-TTY
+(pipe/subprocess) — verified empirically: a piped run emits 0 bytes and hangs.
+Allocating a pseudo-terminal is the supported workaround. ``claude`` streams fine
+on a plain pipe, so it leaves PTY off.
+
+No token hijacking: these adapters invoke the official binaries with their own
+supported auth. Any API key is injected into the child's environment from a
+``secret_ref`` and is never persisted.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import itertools
+import os
+import signal
+import sys
+from abc import abstractmethod
+from collections.abc import AsyncIterator, Iterable
+
+from harness.observability.logging import get_logger
+from harness_sdk.base import (
+    BaseAdapter,
+    Capabilities,
+    HealthStatus,
+    ProviderSession,
+    SessionContext,
+)
+from harness_sdk.events import (
+    ErrorEvent,
+    MessageEvent,
+    NormalizedEvent,
+    StatusEvent,
+)
+
+log = get_logger("cli-adapter")
+
+_IS_WINDOWS = sys.platform == "win32"
+
+# Per-run parser scratch space carried across chunks (e.g. accumulating text).
+ParserState = dict
+
+
+def _extra_bin_dirs() -> list[str]:
+    """Common locations agent CLIs get installed to but which are often missing from
+    a GUI-app's inherited PATH (Finder/launchd on macOS, a bare service env on Linux).
+    Returned in priority order, expanded, deduped — existence is checked by the caller.
+
+    Covers user-local installs (``~/.local/bin``, ``~/bin``), Homebrew (Intel + Apple
+    Silicon), npm global prefixes (``~/.npm-global``, the standard system prefixes), the
+    official Claude installer (``~/.claude/local``), and Windows npm/Programs dirs."""
+    home = os.path.expanduser("~")
+    if _IS_WINDOWS:
+        appdata = os.environ.get("APPDATA", "")
+        localappdata = os.environ.get("LOCALAPPDATA", "")
+        dirs = [
+            os.path.join(appdata, "npm") if appdata else "",
+            os.path.join(localappdata, "Programs") if localappdata else "",
+            os.path.join(home, "AppData", "Roaming", "npm"),
+        ]
+    else:
+        dirs = [
+            os.path.join(home, ".local", "bin"),
+            os.path.join(home, "bin"),
+            "/opt/homebrew/bin",          # Apple Silicon Homebrew
+            "/usr/local/bin",             # Intel Homebrew / common local installs
+            os.path.join(home, ".npm-global", "bin"),
+            "/usr/local/lib/node_modules/.bin",
+            os.path.join(home, ".claude", "local"),  # official Claude installer
+            "/usr/bin",
+            "/bin",
+        ]
+    return [d for d in dirs if d]
+
+
+def _augment_path(base_path: str) -> str:
+    """Append common install dirs to ``base_path`` (deduped, existing only) so a
+    minimal inherited PATH can still find the CLI and its own subprocesses. Appended,
+    never prepended, so the user's own PATH entries always win. Sync (filesystem
+    checks) so it stays off the async hot path."""
+    current = base_path.split(os.pathsep) if base_path else []
+    extra = [d for d in _extra_bin_dirs() if os.path.isdir(d) and d not in current]
+    if not extra:
+        return base_path
+    return os.pathsep.join([*current, *extra])
+
+
+def resolve_binary(name: str) -> str:
+    """Resolve a CLI name to a launchable path. Prefer PATH (``shutil.which``); when it
+    isn't on PATH, fall back to scanning common install dirs (see ``_extra_bin_dirs``).
+    Returns ``name`` unchanged when nothing is found, so a genuinely-missing binary
+    still surfaces a clear "not found" error rather than a fabricated path.
+
+    An absolute/relative path that already points at an existing file is returned as-is.
+    Shared by argv resolution, probing, and the doctor so all three agree."""
+    import shutil
+
+    # Already a usable path (absolute or contains a separator) — trust it if it exists.
+    if os.path.isfile(name) and os.access(name, os.X_OK):
+        return name
+    found = shutil.which(name)
+    if found:
+        return found
+    exts = ["", ".cmd", ".bat", ".exe"] if _IS_WINDOWS else [""]
+    for d in _extra_bin_dirs():
+        for ext in exts:
+            cand = os.path.join(d, name + ext)
+            if os.path.isfile(cand) and os.access(cand, os.X_OK):
+                return cand
+    return name
+
+
+def _resolve_argv(argv: list[str]) -> list[str]:
+    """Resolve argv[0] to a launchable executable, cross-platform.
+
+    ``asyncio.create_subprocess_exec`` maps to ``CreateProcess`` on Windows, which
+    only finds ``.exe`` on PATH — it does NOT honor ``PATHEXT`` the way a shell does,
+    and it cannot execute ``.cmd``/``.bat`` shims at all. The ``claude`` and ``agy``
+    CLIs are typically installed by npm as ``claude.cmd`` / ``agy.cmd`` on Windows,
+    so a bare ``["claude", "--version"]`` raises ``FileNotFoundError`` even when the
+    CLI is installed and works in the terminal — surfacing as "binary not found".
+
+    We resolve the name with ``resolve_binary`` (PATH + common install dirs, honoring
+    ``PATHEXT`` via ``shutil.which``) and, for a batch shim, route it through
+    ``cmd.exe /c`` so it actually launches. On POSIX this substitutes the absolute path
+    (or leaves the name untouched when nothing is found, so a genuinely-missing binary
+    still reports as not found)."""
+    if not argv:
+        return argv
+    resolved = resolve_binary(argv[0])
+    if resolved == argv[0] and not os.path.isabs(resolved):
+        return argv  # nothing found — keep bare name so a missing binary errors clearly
+    if _IS_WINDOWS and resolved.lower().endswith((".cmd", ".bat")):
+        comspec = os.environ.get("COMSPEC", "cmd.exe")
+        return [comspec, "/c", resolved, *argv[1:]]
+    return [resolved, *argv[1:]]
+
+
+class _WinPtyHandle:
+    """Adapts a ``pywinpty`` ``PtyProcess`` to the same ``.pid``/``.returncode``/
+    ``.terminate()``/``.kill()``/``.wait()`` surface ``_reap``/``cancel_run`` use for
+    an ``asyncio.subprocess.Process`` — so those two methods don't need to know
+    which backend actually launched the run."""
+
+    def __init__(self, pty_process) -> None:
+        self._p = pty_process
+
+    @property
+    def pid(self) -> int:
+        return self._p.pid
+
+    @property
+    def returncode(self) -> int | None:
+        return None if self._p.isalive() else self._p.exitstatus
+
+    def terminate(self) -> None:
+        self._p.terminate(force=False)
+
+    def kill(self) -> None:
+        self._p.terminate(force=True)
+
+    async def wait(self) -> int | None:
+        while self._p.isalive():
+            await asyncio.sleep(0.05)
+        return self._p.exitstatus
+
+
+class CliSubprocessAdapter(BaseAdapter):
+    """Base class for CLI-backed adapters. Concrete adapters implement
+    ``build_argv``, ``parse_chunk``, ``finalize``, ``env_overrides`` and
+    ``health_argv``; everything else is handled here."""
+
+    #: default PTY usage; subclasses/config may override via ``params.pty``
+    default_use_pty: bool = False
+    #: default seconds before the child is killed
+    default_timeout_s: float = 600.0
+
+    def __init__(self, config) -> None:  # noqa: ANN001 - AdapterConfig
+        super().__init__(config)
+        self._procs: dict[str, asyncio.subprocess.Process] = {}
+        self._cancelled: set[str] = set()
+
+    # ── hooks for subclasses ──────────────────────────────────────────────────
+    @abstractmethod
+    def build_argv(self, *, run_id: str, ctx: SessionContext, message: str) -> list[str]:
+        """Full argv for a single non-interactive run."""
+
+    @abstractmethod
+    def parse_chunk(self, line: str, state: ParserState) -> Iterable[NormalizedEvent]:
+        """Map one raw output line to zero or more events (seq assigned by base)."""
+
+    def finalize(self, state: ParserState) -> Iterable[NormalizedEvent]:
+        """Emit any end-of-stream events (e.g. a final MessageEvent from
+        accumulated plain-text output). Default: nothing."""
+        return ()
+
+    def env_overrides(self) -> dict[str, str]:
+        """Extra environment for the child (e.g. injected API key)."""
+        return {}
+
+    def stdin_payload(self, message: str, ctx: SessionContext | None = None) -> bytes | None:
+        """Bytes to write to the child's stdin, or None to use /dev/null. Adapters
+        that pass the prompt via stdin (e.g. claude, to avoid variadic-flag
+        ambiguity) return the encoded message here and omit it from argv. ``ctx``
+        (when available) lets an adapter enrich the payload — e.g. image
+        attachment content blocks."""
+        return None
+
+    @abstractmethod
+    def health_argv(self) -> list[str]:
+        """argv for a lightweight health probe (e.g. ``[bin, "--version"]``)."""
+
+    @property
+    def binary(self) -> str:
+        return self.config.params.get("bin") or self.config.params.get("cmd") or self.config.name
+
+    @property
+    def use_pty(self) -> bool:
+        return bool(self.config.params.get("pty", self.default_use_pty))
+
+    @property
+    def timeout_s(self) -> float:
+        return float(self.config.params.get("timeout_s", self.default_timeout_s))
+
+    def working_dir(self, ctx: SessionContext) -> str | None:
+        """Workspace directory passed to the CLI. Prefers the per-run project folder
+        from the session context (set from the workspace's runtime settings), then a
+        configured override, then cwd. Gate writes via the engine's permission layer."""
+        return ctx.workspace_dir or self.config.params.get("workspace_dir") or os.getcwd()
+
+    def _launch_cwd(self, ctx: SessionContext) -> str | None:
+        """The directory to spawn the CLI subprocess in — the project folder, if it
+        exists. Sync (filesystem check) so it stays off the async hot path."""
+        d = self.working_dir(ctx)
+        return d if d and os.path.isdir(d) else None
+
+    def remote_host(self, ctx: SessionContext) -> str | None:
+        """The ssh host this session's project lives on (set by the engine from the
+        workspace's ``project_host``), or None for a local project."""
+        return (ctx.extra or {}).get("ssh_host") or None
+
+    def _wrap_remote_argv(self, argv: list[str], ctx: SessionContext) -> list[str]:
+        """Wrap ``argv`` to run on the remote host via the system ``ssh`` client
+        (honors ~/.ssh/config; BatchMode = key/agent auth only, never prompts):
+        ``ssh -T|-tt <host> "cd <dir> && exec <argv…>"``, everything shlex-quoted.
+
+        Cancellation: PTY adapters use ``-tt``, so killing the local ssh client
+        makes sshd SIGHUP the remote process group — clean. Pipe adapters (``-T``)
+        rely on the remote CLI dying on EPIPE at its next stdout write; a silent
+        remote process can linger (accepted MVP tradeoff)."""
+        import shlex
+
+        host = self.remote_host(ctx)
+        # Run the binary by its BARE NAME on the remote so the remote login shell
+        # resolves it via the REMOTE PATH. argv[0] holds the locally-configured binary
+        # (``params.bin``), which may be a local absolute path (e.g. a workaround for a
+        # local off-PATH install like ``/Users/me/.local/bin/agy``). Shipping that local
+        # path verbatim fails on the remote with ``exec: <path>: not found`` (exit 127);
+        # the basename does not. A caller that truly needs a remote absolute path can set
+        # a bare ``bin`` and rely on the remote PATH, which is the common case.
+        remote_argv = [os.path.basename(argv[0]), *argv[1:]] if argv else argv
+        cmd = " ".join(shlex.quote(a) for a in remote_argv)
+        if (d := self.working_dir(ctx)):
+            cmd = f"cd {shlex.quote(d)} && exec {cmd}"
+        # Login shell: a bare ssh command runs non-login, so ~/.profile PATH
+        # additions (~/.local/bin — where agent CLIs usually live) are missing.
+        cmd = f"sh -lc {shlex.quote(cmd)}"
+        return [
+            os.environ.get("HARNESS_SSH_BIN", "ssh"),
+            "-tt" if self.use_pty else "-T",
+            "-o", "BatchMode=yes",
+            host,
+            cmd,
+        ]
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+    async def start_session(self, ctx: SessionContext) -> ProviderSession:
+        return ProviderSession(
+            provider_session_id=ctx.run_id,
+            adapter_kind=self.kind,
+            meta={
+                "binary": self.binary,
+                "session_id": ctx.session_id,
+                "workspace_slug": ctx.workspace_slug,
+                "system_prompt": ctx.system_prompt,
+                "memory_context": ctx.memory_context,
+                "workspace_dir": ctx.workspace_dir,
+                "read_only": ctx.read_only,
+                "extra": ctx.extra,
+            },
+        )
+
+    async def stream_events(
+        self, session: ProviderSession, message: str, *, tools=None, stream: bool = True
+    ) -> AsyncIterator[NormalizedEvent]:
+        run_id = session.provider_session_id
+        ctx = SessionContext(
+            run_id=run_id,
+            session_id=session.meta.get("session_id", run_id),
+            workspace_slug=session.meta.get("workspace_slug", "default"),
+            objective=message,
+            system_prompt=session.meta.get("system_prompt"),
+            memory_context=session.meta.get("memory_context", ""),
+            workspace_dir=session.meta.get("workspace_dir"),
+            read_only=session.meta.get("read_only", True),
+            extra=session.meta.get("extra", {}) or {},
+        )
+        argv = self.build_argv(run_id=run_id, ctx=ctx, message=message)
+        # Run the CLI *in* the project folder so the agent's cwd (where "current
+        # project" and relative paths resolve) is the one set via `project set` —
+        # --add-dir only grants access, it doesn't change the working directory.
+        # Remote projects: the cd happens on the remote host inside the ssh command,
+        # and the local isdir gate must not see the (remote-only) path.
+        if self.remote_host(ctx):
+            argv = self._wrap_remote_argv(argv, ctx)
+            cwd = None
+        else:
+            cwd = self._launch_cwd(ctx)
+        seq = itertools.count()
+        state: ParserState = {"text": []}
+
+        def _tag(ev: NormalizedEvent) -> NormalizedEvent:
+            ev.seq = next(seq)
+            return ev
+
+        yield _tag(StatusEvent(seq=0, status="running"))
+        try:
+            async for line in self._run_process(argv, run_id, message, state, cwd=cwd, ctx=ctx):
+                if run_id in self._cancelled:
+                    yield _tag(StatusEvent(seq=0, status="cancelled"))
+                    return
+                for ev in self.parse_chunk(line, state):
+                    yield _tag(ev)
+            for ev in self.finalize(state):
+                yield _tag(ev)
+        except FileNotFoundError:
+            yield _tag(ErrorEvent(
+                seq=0, message=f"CLI binary not found: {argv[0]!r}", retriable=False
+            ))
+            return
+        except TimeoutError:
+            yield _tag(ErrorEvent(seq=0, message="CLI run timed out", retriable=True))
+            return
+        except Exception as exc:  # contain any spawn/parse failure to this run
+            yield _tag(ErrorEvent(seq=0, message=f"{type(exc).__name__}: {exc}", retriable=True))
+            return
+
+        rc = state.get("returncode")
+        produced = bool(state.get("text")) or state.get("had_message")
+        stderr = (state.get("stderr") or "").strip()
+        if not produced:
+            # Nothing parseable — surface the failure cause (e.g. silent non-zero exit).
+            if rc not in (0, None):
+                msg = f"CLI exited with code {rc}" + (f": {stderr[-300:]}" if stderr else "")
+                yield _tag(ErrorEvent(seq=0, message=msg, retriable=rc in (124, 137)))
+            else:
+                yield _tag(ErrorEvent(
+                    seq=0,
+                    message="CLI produced no output" + (f": {stderr[-300:]}" if stderr else ""),
+                    retriable=False,
+                ))
+            return
+        # Output was produced; any error was already emitted by the parser. Reflect
+        # the true terminal status (a non-zero exit means the run failed).
+        yield _tag(StatusEvent(seq=0, status="succeeded" if rc in (0, None) else "failed"))
+
+    async def _run_process(
+        self, argv: list[str], run_id: str, message: str, state: ParserState,
+        *, cwd: str | None = None, ctx: SessionContext | None = None,
+    ) -> AsyncIterator[str]:
+        env = {**os.environ, **self.env_overrides()}
+        # Ensure the CLI (and the subprocesses it spawns, e.g. node) can be found even
+        # when this process inherited a minimal PATH (macOS GUI launch, bare service env).
+        # Skipped for remote runs — argv is an ``ssh …`` invocation and the remote PATH
+        # is set by the remote login shell, not by our local env.
+        if not (ctx and self.remote_host(ctx)):
+            env["PATH"] = _augment_path(env.get("PATH", ""))
+        if self.use_pty:
+            async for line in self._run_pty(argv, run_id, env, state, cwd=cwd):
+                yield line
+        else:
+            async for line in self._run_pipe(argv, run_id, env, message, state,
+                                             cwd=cwd, ctx=ctx):
+                yield line
+
+    async def _run_pipe(self, argv, run_id, env, message, state, *, cwd=None,
+                        ctx=None) -> AsyncIterator[str]:
+        payload = self.stdin_payload(message, ctx)
+        proc = await asyncio.create_subprocess_exec(
+            *_resolve_argv(argv),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            stdin=asyncio.subprocess.PIPE if payload is not None else asyncio.subprocess.DEVNULL,
+            env=env,
+            cwd=cwd,
+            # own process group for clean cancellation — POSIX only; Windows has no
+            # process-group session concept here, see _reap/cancel_run below.
+            **({} if _IS_WINDOWS else {"start_new_session": True}),
+        )
+        self._procs[run_id] = proc
+        if payload is not None and proc.stdin is not None:
+            proc.stdin.write(payload)
+            await proc.stdin.drain()
+            proc.stdin.close()
+        try:
+            assert proc.stdout is not None
+            async with asyncio.timeout(self.timeout_s):
+                async for raw in proc.stdout:
+                    yield raw.decode(errors="replace").rstrip("\r\n")
+                if proc.stderr is not None:
+                    state["stderr"] = (await proc.stderr.read()).decode(errors="replace")
+                await proc.wait()
+        finally:
+            state["returncode"] = proc.returncode
+            await self._reap(proc, run_id)
+
+    async def _run_pty(self, argv, run_id, env, state, *, cwd=None) -> AsyncIterator[str]:
+        """Run with a pseudo-terminal so TTY-gated CLIs (agy) emit output."""
+        if _IS_WINDOWS:
+            # POSIX's `pty` module (and the `termios`/`tty` modules it depends on)
+            # doesn't exist on Windows at all — there's no `import pty` fallback.
+            # Windows' equivalent is the native ConPTY API, wrapped by `pywinpty`.
+            async for line in self._run_pty_windows(argv, run_id, env, state, cwd=cwd):
+                yield line
+            return
+
+        import pty
+
+        master_fd, slave_fd = pty.openpty()
+        proc = await asyncio.create_subprocess_exec(
+            *_resolve_argv(argv),
+            stdout=slave_fd,
+            stderr=slave_fd,
+            stdin=slave_fd,
+            env=env,
+            cwd=cwd,
+            start_new_session=True,
+        )
+        os.close(slave_fd)
+        self._procs[run_id] = proc
+
+        loop = asyncio.get_running_loop()
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        master = os.fdopen(master_fd, "rb", buffering=0)
+        transport, _ = await loop.connect_read_pipe(lambda: protocol, master)
+        try:
+            async with asyncio.timeout(self.timeout_s):
+                while True:
+                    try:
+                        raw = await reader.readline()
+                    except OSError:  # PTY master raises EIO at child exit -> EOF
+                        break
+                    if not raw:
+                        break
+                    yield raw.decode(errors="replace").rstrip("\r\n")
+                await proc.wait()
+        finally:
+            transport.close()
+            with contextlib.suppress(Exception):
+                master.close()
+            state["returncode"] = proc.returncode
+            await self._reap(proc, run_id)
+
+    async def _run_pty_windows(self, argv, run_id, env, state, *, cwd=None) -> AsyncIterator[str]:
+        """Windows equivalent of ``_run_pty`` using ConPTY (via ``pywinpty``), since
+        POSIX's ``pty``/``termios``/``tty`` modules don't exist there at all."""
+        try:
+            from winpty import PtyProcess
+        except ImportError as exc:
+            raise RuntimeError(
+                "agy needs a console to produce output on Windows, which requires the "
+                "'pywinpty' package — it isn't installed in this build."
+            ) from exc
+
+        loop = asyncio.get_running_loop()
+        proc = await loop.run_in_executor(
+            None, lambda: PtyProcess.spawn(_resolve_argv(argv), cwd=cwd, env=env)
+        )
+        handle = _WinPtyHandle(proc)
+        self._procs[run_id] = handle
+        buf = b""
+        try:
+            async with asyncio.timeout(self.timeout_s):
+                while True:
+                    try:
+                        chunk = await loop.run_in_executor(None, proc.read, 1024)
+                    except EOFError:  # ConPTY signals child exit this way
+                        break
+                    if not chunk:
+                        break
+                    buf += chunk if isinstance(chunk, (bytes, bytearray)) else chunk.encode()
+                    while b"\n" in buf:
+                        line, buf = buf.split(b"\n", 1)
+                        yield line.decode(errors="replace").rstrip("\r")
+                if buf:
+                    yield buf.decode(errors="replace").rstrip("\r")
+                await handle.wait()
+        finally:
+            state["returncode"] = handle.returncode
+            await self._reap(handle, run_id)
+
+    async def _reap(self, proc, run_id: str) -> None:
+        if proc.returncode is None:
+            if _IS_WINDOWS:
+                with contextlib.suppress(Exception):
+                    proc.terminate()
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(proc.wait(), timeout=5)
+                if proc.returncode is None:
+                    with contextlib.suppress(Exception):
+                        proc.kill()
+            else:
+                with contextlib.suppress(ProcessLookupError):
+                    os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(proc.wait(), timeout=5)
+                if proc.returncode is None:
+                    with contextlib.suppress(ProcessLookupError):
+                        os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        self._procs.pop(run_id, None)
+
+    async def cancel_run(self, run_id: str) -> None:
+        self._cancelled.add(run_id)
+        proc = self._procs.get(run_id)
+        if proc is not None and proc.returncode is None:
+            if _IS_WINDOWS:
+                with contextlib.suppress(Exception):
+                    proc.terminate()
+            else:
+                with contextlib.suppress(ProcessLookupError):
+                    os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+
+    # ── introspection ─────────────────────────────────────────────────────────
+    @abstractmethod
+    def list_capabilities(self) -> Capabilities: ...
+
+    async def health_check(self) -> HealthStatus:
+        import time
+
+        start = time.perf_counter()
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *_resolve_argv(self.health_argv()),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                stdin=asyncio.subprocess.DEVNULL,
+                env={**os.environ, **self.env_overrides()},
+            )
+            out, err = await asyncio.wait_for(proc.communicate(), timeout=20)
+        except FileNotFoundError:
+            return HealthStatus(ok=False, detail={"error": f"binary not found: {self.binary!r}"})
+        except (TimeoutError, Exception) as exc:  # noqa: BLE001
+            return HealthStatus(ok=False, detail={"error": str(exc)})
+        detail: dict[str, object] = {
+            "version": out.decode(errors="replace").strip()[:120],
+            "returncode": proc.returncode,
+        }
+        # On failure, surface the process's stderr — otherwise a nonzero exit shows an
+        # empty version with no clue why (e.g. the `claude` CLI exiting on a deleted cwd
+        # writes its ENOENT to stderr). Only on failure, so success stays quiet.
+        if proc.returncode != 0 and (stderr := err.decode(errors="replace").strip()):
+            detail["stderr"] = stderr[:500]
+        return HealthStatus(
+            ok=proc.returncode == 0,
+            latency_ms=(time.perf_counter() - start) * 1000,
+            detail=detail,
+        )
+
+    @staticmethod
+    def _final_text_message(state: ParserState) -> Iterable[NormalizedEvent]:
+        text = "".join(state.get("text", [])).strip()
+        if text:
+            state["had_message"] = True
+            yield MessageEvent(seq=0, role="assistant", text=text)

harness_sdk/events.py

@@ -0,0 +1,94 @@
+"""Normalized, vendor-neutral event model.
+
+Every adapter maps its provider-specific stream onto this discriminated union so
+the orchestrator and the ``run_events`` ledger stay provider-agnostic. The
+``type`` discriminator matches ``harness.models.enums.RunEventType``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+class _BaseEvent(BaseModel):
+    seq: int = Field(description="Monotonic per-run sequence number.")
+
+
+class TokenEvent(_BaseEvent):
+    type: Literal["token"] = "token"
+    text: str
+    # True for a reasoning/"thinking" delta (models that stream chain-of-thought
+    # separately from the answer). Surfaced live but kept out of the final answer.
+    reasoning: bool = False
+
+
+class MessageEvent(_BaseEvent):
+    type: Literal["message"] = "message"
+    role: Literal["assistant", "user", "system", "tool"] = "assistant"
+    text: str
+    # User-message attachments (GUI uploads): [{id, name, media_type, size, image}].
+    # Carried on the event so the transcript can re-render chips/thumbnails.
+    attachments: list[dict] = Field(default_factory=list)
+
+
+class ToolCallEvent(_BaseEvent):
+    type: Literal["tool_call"] = "tool_call"
+    name: str
+    arguments: dict = Field(default_factory=dict)
+    call_id: str | None = None
+
+
+class ToolResultEvent(_BaseEvent):
+    type: Literal["tool_result"] = "tool_result"
+    call_id: str | None = None
+    output: str = ""
+    is_error: bool = False
+
+
+class ArtifactEvent(_BaseEvent):
+    type: Literal["artifact"] = "artifact"
+    kind: Literal["file", "patch", "plan", "doc"] = "doc"
+    uri: str
+    sha256: str | None = None
+    meta: dict = Field(default_factory=dict)
+
+
+class StatusEvent(_BaseEvent):
+    type: Literal["status"] = "status"
+    status: str
+    detail: str | None = None
+
+
+class CostEvent(_BaseEvent):
+    type: Literal["cost"] = "cost"
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    usd: float | None = None
+
+
+class AdapterMetaEvent(_BaseEvent):
+    type: Literal["adapter_meta"] = "adapter_meta"
+    data: dict = Field(default_factory=dict)
+
+
+class ErrorEvent(_BaseEvent):
+    type: Literal["error"] = "error"
+    message: str
+    retriable: bool = False
+
+
+NormalizedEvent = Annotated[
+    TokenEvent
+    | MessageEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | ArtifactEvent
+    | StatusEvent
+    | CostEvent
+    | AdapterMetaEvent
+    | ErrorEvent,
+    Field(discriminator="type"),
+]

harness_sdk/types.py

@@ -0,0 +1,5 @@
+"""Types shared across the SDK."""
+
+# Instead of an enum, we use a simple string type alias in the SDK 
+# so third-parties can define custom adapter names easily.
+AdapterKind = str