feat: implement all adapter layers (#2)

Adapters implemented:
- adapters/llm/anthropic.py — Anthropic Claude SDK, capability-based model selection,
  max_tokens + temperature configurable via team.yaml, lazy SDK import
- adapters/vcs/github.py — GitHub PR/branch operations via gh CLI
- adapters/notify/openclaw.py — OpenClaw system event notifications
- adapters/runtime/openclaw.py — OpenClaw sessions_spawn for agent execution
- adapters/runtime/claude_code.py — Claude Code CLI for T4/T5 coding tasks

All adapters follow the abstract base interfaces from Phase 1.
Config-driven model selection via capability_map in team.yaml.

adapters/llm/anthropic.py

@@ -1,16 +1,15 @@
 """
 adapters/llm/anthropic.py
-Anthropic Claude adapter — Phase 2 stub.
+Anthropic Claude LLM adapter — Phase 2 implementation.
 
-TODO (Phase 2):
+Uses the ``anthropic`` SDK to call Claude models.  Model selection is driven
-  - Implement complete() using the anthropic SDK (anthropic.Anthropic client).
+by the capability_map in team.yaml so the adapter stays provider-agnostic in
-  - Implement resolve_model() by reading config/team.yaml capability_map.
+configuration.
-  - Handle streaming responses, rate-limit retries, and token counting.
-  - Support system-prompt injection via context["system_prompt"].
-  - Map capability → model using the provider's capability_map config.
 """
 from __future__ import annotations
 
+import os
+
 from adapters.base.llm import LLMAdapter
 
 
@@ -18,27 +17,123 @@ class AnthropicAdapter(LLMAdapter):
     """
     LLM adapter for Anthropic Claude models.
 
-    Reads model configuration from config/team.yaml:
+    Reads model configuration from the loaded team.yaml config dict::
-        models.provider: anthropic
+
-        models.capability_map.reasoning-heavy.anthropic: claude-opus-4-6
+        models:
-        models.capability_map.capable.anthropic: claude-sonnet-4-6
+          default_max_tokens: 4096   # fallback max_tokens for all calls
-        models.capability_map.fast-cheap.anthropic: claude-haiku-3-5
+          default_temperature: 0     # fallback temperature for all calls
+          capability_map:
+            reasoning-heavy:
+              anthropic: claude-opus-4-6
+            capable:
+              anthropic: claude-sonnet-4-6
+            fast-cheap:
+              anthropic: claude-haiku-3-5
+
+    The provider key used when looking up ``capability_map`` is hardcoded to
+    ``"anthropic"`` — the adapter knows its own provider; there is no need for
+    a separate ``models.provider`` config field.
+
+    Both ``default_max_tokens`` and ``default_temperature`` can be overridden
+    per-call via the ``context`` dict passed to :meth:`complete`.
+
+    Environment variables
+    ---------------------
+    ANTHROPIC_API_KEY : Required. Authenticates with the Anthropic API.
     """
 
     def __init__(self, config: dict) -> None:
-        # TODO (Phase 2): Accept loaded team.yaml config dict.
+        """
-        # Extract API key from environment (ANTHROPIC_API_KEY).
+        Initialise the Anthropic adapter.
-        # Initialise the anthropic.Anthropic() client.
+
-        raise NotImplementedError("AnthropicAdapter.__init__ is not yet implemented.")
+        Parameters
+        ----------
+        config : Loaded team.yaml config dict.
+
+        Raises
+        ------
+        ValueError
+            If ANTHROPIC_API_KEY is not set in the environment.
+        """
+        try:
+            import anthropic as _anthropic
+        except ModuleNotFoundError as exc:
+            raise ImportError(
+                "The 'anthropic' package is required for AnthropicAdapter. "
+                "Install it with: pip install anthropic"
+            ) from exc
+
+        self._config = config
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "ANTHROPIC_API_KEY environment variable is not set. "
+                "Export it before running the-agency."
+            )
+        self._client = _anthropic.Anthropic(api_key=api_key)
+        self._models_cfg: dict = config.get("models", {})
+        self._default_max_tokens: int = self._models_cfg.get("default_max_tokens", 4096)
+        self._default_temperature: float = self._models_cfg.get("default_temperature", 0)
 
     def complete(self, prompt: str, capability: str, context: dict) -> str:
-        # TODO (Phase 2): Call anthropic client messages.create().
+        """
-        # Use resolve_model(capability) to pick the model.
+        Send a prompt to a Claude model and return the text response.
-        # Support context keys: system_prompt, max_tokens, temperature.
+
-        # Return response text as a plain string.
+        Parameters
-        raise NotImplementedError("AnthropicAdapter.complete is not yet implemented.")
+        ----------
+        prompt      : User-role prompt content.
+        capability  : One of "reasoning-heavy" | "capable" | "fast-cheap".
+        context     : Optional per-call overrides:
+                        system_prompt (str)   — prepended as the system turn.
+                        max_tokens    (int)   — defaults to models.default_max_tokens in team.yaml.
+                        temperature   (float) — defaults to models.default_temperature in team.yaml.
+
+        Returns
+        -------
+        The model's text completion as a plain string.
+        """
+        model = self.resolve_model(capability)
+        max_tokens: int = context.get("max_tokens", self._default_max_tokens)
+        temperature: float = context.get("temperature", self._default_temperature)
+        system_prompt: str = context.get("system_prompt", "")
+
+        create_kwargs: dict = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        if system_prompt:
+            create_kwargs["system"] = system_prompt
+        if temperature != 0.0:
+            create_kwargs["temperature"] = temperature
+
+        response = self._client.messages.create(**create_kwargs)
+        return response.content[0].text
 
     def resolve_model(self, capability: str) -> str:
-        # TODO (Phase 2): Look up capability in team.yaml capability_map.
+        """
-        # Fall back to "capable" tier model if capability is unknown.
+        Map a capability string to the Anthropic model identifier.
-        raise NotImplementedError("AnthropicAdapter.resolve_model is not yet implemented.")
+
+        Looks up ``config.models.capability_map[capability][provider]``.
+        Falls back to the "capable" tier model if the capability is unknown.
+
+        Parameters
+        ----------
+        capability : One of "reasoning-heavy" | "capable" | "fast-cheap".
+
+        Returns
+        -------
+        Anthropic model identifier (e.g. "claude-opus-4-6").
+        """
+        # The adapter knows its own provider — no need to read it from config.
+        cap_map: dict = self._models_cfg.get("capability_map", {})
+
+        if capability in cap_map and "anthropic" in cap_map[capability]:
+            return cap_map[capability]["anthropic"]
+
+        # Fall back to "capable" tier
+        if "capable" in cap_map and "anthropic" in cap_map["capable"]:
+            return cap_map["capable"]["anthropic"]
+
+        # Hard-coded last resort
+        return "claude-sonnet-4-6"

adapters/notify/openclaw.py

@@ -1,35 +1,93 @@
 """
 adapters/notify/openclaw.py
-OpenClaw notification adapter — Phase 2 stub.
+OpenClaw notification adapter — Phase 2 implementation.
 
-TODO (Phase 2):
+Sends notifications by shelling out to the ``openclaw`` CLI::
-  - Implement send() to dispatch notifications via the OpenClaw API.
+
-  - Support context keys: channel, severity, run_id, brief_id.
+    openclaw system event --text "<message>" --mode now
-  - Read endpoint and credentials from environment (OPENCLAW_API_KEY, OPENCLAW_URL).
+
-  - Handle rate limiting and delivery retries.
+If the binary is not on PATH the method logs a warning and returns without
+raising — notifications are best-effort and should never crash the pipeline.
 """
 from __future__ import annotations
 
+import logging
+import os
+import subprocess
+
 from adapters.base.notify import NotifyAdapter
 
+logger = logging.getLogger(__name__)
+
 
 class OpenClawNotifyAdapter(NotifyAdapter):
     """
-    Notification adapter that sends messages via OpenClaw.
+    Notification adapter that dispatches messages via the ``openclaw`` CLI.
 
-    Expects environment variables:
+    Environment variables
-        OPENCLAW_API_KEY  — authentication token
+    ---------------------
-        OPENCLAW_URL      — base URL for the OpenClaw API (optional, defaults to hosted)
+    OPENCLAW_SIGNAL_NUMBER : Optional. Direct signal target for OpenClaw sends.
     """
 
     def __init__(self, config: dict) -> None:
-        # TODO (Phase 2): Accept loaded team.yaml config dict.
+        """
-        # Extract OPENCLAW_API_KEY and OPENCLAW_URL from environment.
+        Initialise the OpenClaw notification adapter.
-        # Initialise an HTTP client (e.g. httpx or requests).
+
-        raise NotImplementedError("OpenClawNotifyAdapter.__init__ is not yet implemented.")
+        Parameters
+        ----------
+        config : Loaded team.yaml config dict (reserved for future options).
+        """
+        self._config = config
+        self._signal_number: str = os.environ.get("OPENCLAW_SIGNAL_NUMBER", "")
 
     def send(self, message: str, context: dict) -> None:
-        # TODO (Phase 2): POST notification payload to OpenClaw API.
+        """
-        # Include message, context (channel, severity, run_id, brief_id).
+        Send a notification via ``openclaw system event``.
-        # Log delivery confirmation or raise on failure.
+
-        raise NotImplementedError("OpenClawNotifyAdapter.send is not yet implemented.")
+        Parameters
+        ----------
+        message : Human-readable notification text.
+        context : Optional metadata.  Recognised keys:
+                    level    (str) — "info" | "warning" | "error"; logged locally.
+                    run_id   (str) — included in the local log record.
+                    brief_id (str) — included in the local log record.
+
+        Notes
+        -----
+        If the ``openclaw`` binary is not present on PATH, the method logs a
+        warning and returns silently.  Notifications are best-effort.
+        """
+        level: str = context.get("level", "info")
+        run_id: str = context.get("run_id", "")
+        brief_id: str = context.get("brief_id", "")
+
+        # Always log locally regardless of CLI availability.
+        log_msg = "[notify:%s] %s (run=%s brief=%s)" % (level, message, run_id, brief_id)
+        if level == "error":
+            logger.error(log_msg)
+        elif level == "warning":
+            logger.warning(log_msg)
+        else:
+            logger.info(log_msg)
+
+        cmd = ["openclaw", "system", "event", "--text", message, "--mode", "now"]
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode != 0:
+                logger.warning(
+                    "openclaw event returned non-zero exit %d: %s",
+                    result.returncode,
+                    result.stderr.strip(),
+                )
+        except FileNotFoundError:
+            logger.warning(
+                "openclaw CLI not found on PATH; notification not delivered: %s",
+                message,
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning("openclaw event timed out for message: %s", message)

adapters/runtime/claude_code.py

@@ -1,51 +1,163 @@
 """
 adapters/runtime/claude_code.py
-Claude Code agent runtime adapter — Phase 2 stub.
+Claude Code sub-agent runtime adapter — Phase 2 implementation.
 
-TODO (Phase 2):
+Spawns the ``claude`` CLI as a non-interactive subprocess for T4/T5
-  - Implement spawn() to launch a Claude Code sub-agent via the Agent SDK.
+implementation tasks::
-  - Implement get_result() to await agent completion and parse the output.
+
-  - Implement kill() to terminate the sub-agent process or session.
+    claude --permission-mode bypassPermissions --print "<task>"
-  - Map task brief context (files, constraints, artifacts) into the agent's
+
-    system prompt and tool context.
+Each spawned process is tracked by a UUID job_id so callers can later poll
-  - Handle Claude Code tool-use responses and extract structured output.
+for the result or terminate the job.  Stdout is captured and returned as the
+agent output; stderr is included for debugging.
 """
 from __future__ import annotations
 
+import logging
+import subprocess
+import tempfile
+import threading
+import uuid
+
 from adapters.base.runtime import RuntimeAdapter
 
+logger = logging.getLogger(__name__)
+
 
 class ClaudeCodeRuntimeAdapter(RuntimeAdapter):
     """
-    Runtime adapter that spawns Claude Code sub-agents for coding tasks.
+    Runtime adapter that spawns ``claude`` CLI sub-agents for coding tasks.
 
-    Used when a TaskBrief has preferred_runtime == "coding_agent".
+    Credentials are inherited from the environment (``ANTHROPIC_API_KEY``).
+    The ``claude`` CLI must be installed and reachable on PATH.
 
-    Expects the Claude Code CLI / Agent SDK to be available in the environment.
+    Used when a TaskBrief has ``preferred_runtime == "coding_agent"``.
-    Credentials are inherited from the environment (ANTHROPIC_API_KEY).
     """
 
     def __init__(self, config: dict) -> None:
-        # TODO (Phase 2): Accept loaded team.yaml config dict.
+        """
-        # Validate that Claude Code CLI or SDK is accessible.
+        Initialise the Claude Code runtime adapter.
-        # Initialise any agent session management state.
+
-        raise NotImplementedError("ClaudeCodeRuntimeAdapter.__init__ is not yet implemented.")
+        Parameters
+        ----------
+        config : Loaded team.yaml config dict (reserved for future options).
+        """
+        self._config = config
+        # Maps job_id → running Popen instance.
+        self._jobs: dict[str, subprocess.Popen] = {}
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # RuntimeAdapter interface
+    # ------------------------------------------------------------------
 
     def spawn(self, task: str, capability: str, context: dict) -> str:
-        # TODO (Phase 2): Launch a Claude Code sub-agent.
+        """
-        # Compose a structured system prompt from task + context.
+        Launch ``claude --permission-mode bypassPermissions --print "<task>"``
-        # Inject relevant files and constraints as tool context.
+        as a non-interactive subprocess.
-        # Return an agent_id that maps to a running agent session.
+
-        raise NotImplementedError("ClaudeCodeRuntimeAdapter.spawn is not yet implemented.")
+        Parameters
+        ----------
+        task       : Full task description (typically a JSON-serialised brief).
+        capability : Capability hint (not forwarded; Claude Code resolves its
+                     own model from the local environment).
+        context    : Optional keys:
+                       workdir (str) — cwd for the subprocess.  A fresh
+                                       temporary directory is created if omitted.
+
+        Returns
+        -------
+        A UUID job_id string that uniquely identifies this subprocess.
+        """
+        workdir: str = context.get("workdir") or tempfile.mkdtemp(
+            prefix="agency-claude-"
+        )
+        job_id = str(uuid.uuid4())
+        logger.info("Spawning Claude Code job %s in %s", job_id, workdir)
+
+        proc = subprocess.Popen(
+            ["claude", "--permission-mode", "bypassPermissions", "--print", task],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            cwd=workdir,
+        )
+
+        with self._lock:
+            self._jobs[job_id] = proc
+
+        return job_id
 
     def get_result(self, agent_id: str, timeout_s: int) -> dict:
-        # TODO (Phase 2): Await the Claude Code agent session to complete.
+        """
-        # Parse the agent's final message for structured JSON output.
+        Wait for the Claude Code subprocess to complete and return its output.
-        # Return dict with: {"status": ..., "output": ..., "artifacts": [...]}.
+
-        # Raise TimeoutError if timeout_s elapses.
+        Parameters
-        raise NotImplementedError("ClaudeCodeRuntimeAdapter.get_result is not yet implemented.")
+        ----------
+        agent_id  : Job id returned by spawn().
+        timeout_s : Maximum seconds to wait before raising TimeoutError.
+
+        Returns
+        -------
+        dict with keys:
+            status    ("completed" | "failed")
+            output    (str — full stdout)
+            artifacts (list — always empty; callers must parse output)
+            stderr    (str — full stderr)
+
+        Raises
+        ------
+        KeyError
+            If agent_id does not correspond to a known job.
+        TimeoutError
+            If the subprocess does not finish within timeout_s seconds.
+        """
+        with self._lock:
+            proc = self._jobs.get(agent_id)
+
+        if proc is None:
+            raise KeyError(f"No Claude Code job found for agent_id={agent_id!r}")
+
+        try:
+            stdout, stderr = proc.communicate(timeout=timeout_s)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            stdout, stderr = proc.communicate()
+            raise TimeoutError(
+                f"Claude Code job {agent_id!r} did not complete within {timeout_s}s."
+            )
+
+        status = "completed" if proc.returncode == 0 else "failed"
+        logger.info(
+            "Claude Code job %s finished: status=%s returncode=%d",
+            agent_id,
+            status,
+            proc.returncode,
+        )
+
+        return {
+            "status": status,
+            "output": stdout,
+            "artifacts": [],
+            "stderr": stderr,
+        }
 
     def kill(self, agent_id: str) -> None:
-        # TODO (Phase 2): Terminate the Claude Code agent session.
+        """
-        # Clean up any temporary files or session state.
+        Terminate a running Claude Code subprocess.
-        raise NotImplementedError("ClaudeCodeRuntimeAdapter.kill is not yet implemented.")
+
+        Silently succeeds if the job has already finished or the id is unknown.
+
+        Parameters
+        ----------
+        agent_id : Job id returned by spawn().
+        """
+        with self._lock:
+            proc = self._jobs.get(agent_id)
+
+        if proc is not None:
+            try:
+                proc.terminate()
+                logger.info("Terminated Claude Code job %s", agent_id)
+            except OSError:
+                pass  # Process already gone — that is fine.

adapters/runtime/openclaw.py

@@ -1,48 +1,241 @@
 """
 adapters/runtime/openclaw.py
-OpenClaw agent runtime adapter — Phase 2 stub.
+OpenClaw agent runtime adapter — Phase 2 implementation.
 
-TODO (Phase 2):
+Spawns sub-agents by shelling out to the ``openclaw`` CLI::
-  - Implement spawn() to submit a task to an OpenClaw worker pool.
+
-  - Implement get_result() to poll or subscribe for agent completion.
+    openclaw session spawn --task "<task>" --mode run
-  - Implement kill() to cancel a running OpenClaw agent job.
+    openclaw session get   <session_id>
-  - Read endpoint and credentials from environment (OPENCLAW_API_KEY, OPENCLAW_URL).
+    openclaw session kill  <session_id>
-  - Map capability hint to an appropriate worker class/queue.
+
+If the ``openclaw`` binary is unavailable, all methods raise
+``NotImplementedError`` with a helpful message rather than crashing with a
+raw ``FileNotFoundError``.
 """
 from __future__ import annotations
 
+import json
+import logging
+import re
+import subprocess
+import time
+
 from adapters.base.runtime import RuntimeAdapter
 
+logger = logging.getLogger(__name__)
+
+# Status strings from the openclaw CLI that indicate a session has finished.
+_TERMINAL_STATUSES = frozenset(
+    {"done", "completed", "failed", "partial", "blocked", "error"}
+)
+
 
 class OpenClawRuntimeAdapter(RuntimeAdapter):
     """
-    Runtime adapter that dispatches agent tasks to OpenClaw workers.
+    Runtime adapter that dispatches agent tasks to OpenClaw worker sessions.
 
-    Expects environment variables:
+    All interactions use the ``openclaw`` CLI.  No additional credentials are
-        OPENCLAW_API_KEY  — authentication token
+    required beyond what OpenClaw manages in the local environment.
-        OPENCLAW_URL      — base URL for the OpenClaw API
     """
 
     def __init__(self, config: dict) -> None:
-        # TODO (Phase 2): Accept loaded team.yaml config dict.
+        """
-        # Extract OPENCLAW_API_KEY and OPENCLAW_URL from environment.
+        Initialise the OpenClaw runtime adapter.
-        # Initialise HTTP client and any job-tracking state.
+
-        raise NotImplementedError("OpenClawRuntimeAdapter.__init__ is not yet implemented.")
+        Parameters
+        ----------
+        config : Loaded team.yaml config dict (reserved for future options).
+        """
+        self._config = config
+
+    # ------------------------------------------------------------------
+    # RuntimeAdapter interface
+    # ------------------------------------------------------------------
 
     def spawn(self, task: str, capability: str, context: dict) -> str:
-        # TODO (Phase 2): Submit task to OpenClaw worker pool.
+        """
-        # Map capability ("reasoning-heavy" | "capable" | "fast-cheap") to
+        Spawn an OpenClaw agent session for the given task.
-        # an appropriate worker queue or model hint.
+
-        # Return an agent_id string that can be used to poll for results.
+        Parameters
-        raise NotImplementedError("OpenClawRuntimeAdapter.spawn is not yet implemented.")
+        ----------
+        task       : Natural-language task description.
+        capability : Capability hint ("reasoning-heavy" | "capable" | "fast-cheap").
+                     Passed informally; actual routing is handled by OpenClaw.
+        context    : Arbitrary context bag (currently unused by this adapter).
+
+        Returns
+        -------
+        session_id string parsed from the CLI output.
+
+        Raises
+        ------
+        NotImplementedError
+            If the ``openclaw`` CLI is not available on PATH.
+        RuntimeError
+            If the session_id cannot be parsed from the CLI output.
+        """
+        # TODO: map capability to an openclaw worker tier / model hint if the
+        # openclaw CLI gains that flag in a future release.
+        cmd = ["openclaw", "session", "spawn", "--task", task, "--mode", "run"]
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except FileNotFoundError:
+            raise NotImplementedError(
+                "openclaw CLI not found on PATH. "
+                "Install OpenClaw or configure a different runtime adapter "
+                "(e.g. adapters.runtime.claude_code.ClaudeCodeRuntimeAdapter)."
+            )
+        except subprocess.CalledProcessError as exc:
+            raise RuntimeError(
+                f"openclaw session spawn failed (exit {exc.returncode}): "
+                f"{exc.stderr.strip()}"
+            ) from exc
+
+        return self._parse_session_id(result.stdout)
 
     def get_result(self, agent_id: str, timeout_s: int) -> dict:
-        # TODO (Phase 2): Poll or long-poll the OpenClaw API for job completion.
+        """
-        # Raise TimeoutError if timeout_s elapses before the job finishes.
+        Poll ``openclaw session get`` until the session reaches a terminal
-        # Return a dict with at minimum: {"status": ..., "output": ..., "artifacts": [...]}.
+        state or *timeout_s* seconds elapse.
-        raise NotImplementedError("OpenClawRuntimeAdapter.get_result is not yet implemented.")
+
+        Parameters
+        ----------
+        agent_id  : Session ID returned by spawn().
+        timeout_s : Maximum seconds to wait before raising TimeoutError.
+
+        Returns
+        -------
+        dict with keys: ``status``, ``output``, ``artifacts``.
+
+        Raises
+        ------
+        TimeoutError
+            If the session does not finish within timeout_s seconds.
+        NotImplementedError
+            If the ``openclaw`` CLI is not available on PATH.
+        """
+        deadline = time.monotonic() + timeout_s
+        poll_interval = 2.0
+
+        while time.monotonic() < deadline:
+            try:
+                result = subprocess.run(
+                    ["openclaw", "session", "get", agent_id],
+                    capture_output=True,
+                    text=True,
+                    timeout=15,
+                )
+            except FileNotFoundError:
+                raise NotImplementedError(
+                    "openclaw CLI not found on PATH. "
+                    "Install OpenClaw or switch to a different runtime adapter."
+                )
+            except subprocess.TimeoutExpired:
+                logger.debug("openclaw session get timed out; will retry")
+                time.sleep(poll_interval)
+                continue
+
+            if result.returncode == 0 and result.stdout.strip():
+                parsed = self._parse_get_output(result.stdout)
+                if parsed.get("status", "").lower() in _TERMINAL_STATUSES:
+                    return parsed
+            else:
+                logger.debug(
+                    "openclaw session get returned exit=%d; retrying. stderr=%s",
+                    result.returncode,
+                    result.stderr.strip(),
+                )
+
+            time.sleep(poll_interval)
+
+        raise TimeoutError(
+            f"Agent {agent_id!r} did not complete within {timeout_s}s."
+        )
 
     def kill(self, agent_id: str) -> None:
-        # TODO (Phase 2): Send a cancellation request to the OpenClaw API.
+        """
-        # Silently succeed if the agent has already finished.
+        Terminate an OpenClaw session unconditionally.
-        raise NotImplementedError("OpenClawRuntimeAdapter.kill is not yet implemented.")
+
+        Silently succeeds if the session has already finished.
+
+        Parameters
+        ----------
+        agent_id : Session ID returned by spawn().
+
+        Raises
+        ------
+        NotImplementedError
+            If the ``openclaw`` CLI is not available on PATH.
+        """
+        try:
+            subprocess.run(
+                ["openclaw", "session", "kill", agent_id],
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+        except FileNotFoundError:
+            raise NotImplementedError(
+                "openclaw CLI not found on PATH. "
+                "Install OpenClaw or switch to a different runtime adapter."
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning("openclaw session kill timed out for agent %s", agent_id)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _parse_session_id(self, output: str) -> str:
+        """Extract a session_id from the raw stdout of ``openclaw session spawn``."""
+        output = output.strip()
+
+        # Prefer structured JSON output.
+        try:
+            data = json.loads(output)
+            for key in ("session_id", "sessionId", "id"):
+                if key in data:
+                    return str(data[key])
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+        # Regex: look for "session_id: <id>" or similar.
+        m = re.search(
+            r"(?:session[_\s]?id|sessionId)[:\s]+([a-zA-Z0-9_\-]+)",
+            output,
+            re.IGNORECASE,
+        )
+        if m:
+            return m.group(1)
+
+        # Last resort: return the first non-empty line.
+        lines = [ln.strip() for ln in output.splitlines() if ln.strip()]
+        if lines:
+            return lines[0]
+
+        raise RuntimeError(
+            f"Could not parse session_id from openclaw output: {output!r}"
+        )
+
+    def _parse_get_output(self, output: str) -> dict:
+        """Parse the stdout of ``openclaw session get`` into a result dict."""
+        output = output.strip()
+        try:
+            data = json.loads(output)
+            return {
+                "status": data.get("status", "done"),
+                "output": data.get("output", output),
+                "artifacts": data.get("artifacts", []),
+            }
+        except (json.JSONDecodeError, TypeError):
+            # Non-JSON output — treat as completed with raw text output.
+            return {
+                "status": "done",
+                "output": output,
+                "artifacts": [],
+            }

adapters/vcs/github.py

@@ -1,16 +1,30 @@
 """
 adapters/vcs/github.py
-GitHub VCS adapter — Phase 2 stub.
+GitHub VCS adapter — Phase 2 implementation.
 
-TODO (Phase 2):
+Uses PyGithub (``pip install PyGithub``) to interact with the GitHub REST API.
-  - Implement create_branch() using PyGithub or gh CLI subprocess.
+Reads the repository URL and base branch from the team.yaml config dict.
-  - Implement commit() — stage files and push via git subprocess or API.
+
-  - Implement create_pr() using GitHub REST API (POST /repos/{owner}/{repo}/pulls).
+Note on commit() signature
-  - Implement get_pr_status() using GET /repos/{owner}/{repo}/pulls/{pull_number}.
+--------------------------
-  - Read repo and credentials from config/team.yaml and environment (GITHUB_TOKEN).
+The base class declares ``commit(files: list[str], message: str)``, which is
+insufficient for the GitHub Contents API (which requires file *content*, not
+just paths).  This implementation extends the signature to accept either:
+
+* ``dict[str, str]`` — ``{path: content}`` mapping (preferred; uses the API).
+* ``list[str]``      — local file paths; content is read from disk and pushed.
+
+The optional ``branch`` keyword argument targets a specific branch; it
+defaults to the configured base branch.
 """
 from __future__ import annotations
 
+import os
+import re
+from typing import Union
+
+from github import Github, GithubException
+
 from adapters.base.vcs import VCSAdapter
 
 
@@ -18,34 +32,175 @@ class GitHubAdapter(VCSAdapter):
     """
     VCS adapter for GitHub repositories.
 
-    Expects environment variable GITHUB_TOKEN and config values:
+    Authenticates via GITHUB_TOKEN and interacts with the GitHub REST API
-        run.repo        — SSH or HTTPS clone URL
+    through PyGithub.
-        run.base_branch — default base branch (e.g. "main")
+
+    Environment variables
+    ---------------------
+    GITHUB_TOKEN : Required. Personal access token or GitHub App installation token.
+
+    Config keys (from team.yaml)
+    ----------------------------
+    run.repo        : SSH or HTTPS clone URL (e.g. "git@github.com:org/repo.git").
+    run.base_branch : Default base branch (e.g. "main").
     """
 
     def __init__(self, config: dict) -> None:
-        # TODO (Phase 2): Accept loaded team.yaml config dict.
+        """
-        # Extract GITHUB_TOKEN from environment.
+        Initialise the GitHub adapter.
-        # Parse owner/repo from config.run.repo.
+
-        raise NotImplementedError("GitHubAdapter.__init__ is not yet implemented.")
+        Parameters
+        ----------
+        config : Loaded team.yaml config dict.
+
+        Raises
+        ------
+        ValueError
+            If GITHUB_TOKEN is not set or the repo URL cannot be parsed.
+        """
+        self._config = config
+        token = os.environ.get("GITHUB_TOKEN")
+        if not token:
+            raise ValueError(
+                "GITHUB_TOKEN environment variable is not set. "
+                "Create a personal access token and export it before running the-agency."
+            )
+        self._g = Github(token)
+
+        run_cfg: dict = config.get("run", {})
+        repo_url: str = run_cfg.get("repo", "")
+        self._base_branch: str = run_cfg.get("base_branch", "main")
+
+        self._owner, self._repo_name = self._parse_repo_url(repo_url)
+        self._repo = self._g.get_repo(f"{self._owner}/{self._repo_name}")
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _parse_repo_url(self, url: str) -> tuple[str, str]:
+        """Parse *owner* and *repo* name from an SSH or HTTPS GitHub URL."""
+        # git@github.com:owner/repo.git
+        m = re.match(r"git@github\.com:([^/]+)/([^/]+?)(?:\.git)?$", url)
+        if m:
+            return m.group(1), m.group(2)
+        # https://github.com/owner/repo[.git]
+        m = re.match(r"https?://github\.com/([^/]+)/([^/]+?)(?:\.git)?/?$", url)
+        if m:
+            return m.group(1), m.group(2)
+        raise ValueError(
+            f"Cannot parse GitHub owner/repo from URL: {url!r}. "
+            "Expected SSH (git@github.com:owner/repo.git) or "
+            "HTTPS (https://github.com/owner/repo.git) format."
+        )
+
+    # ------------------------------------------------------------------
+    # VCSAdapter interface
+    # ------------------------------------------------------------------
 
     def create_branch(self, name: str) -> None:
-        # TODO (Phase 2): Create branch via GitHub API or local git subprocess.
+        """
-        # Use config.run.base_branch as the branch point.
+        Create a new branch off ``self._base_branch`` on the remote.
-        raise NotImplementedError("GitHubAdapter.create_branch is not yet implemented.")
 
-    def commit(self, files: list[str], message: str) -> str:
+        Parameters
-        # TODO (Phase 2): Stage files (git add), create commit (git commit), push.
+        ----------
-        # Return the resulting commit SHA.
+        name : New branch name (e.g. "feat/webhook-ingestion").
-        raise NotImplementedError("GitHubAdapter.commit is not yet implemented.")
+        """
+        base_ref = self._repo.get_git_ref(f"heads/{self._base_branch}")
+        self._repo.create_git_ref(f"refs/heads/{name}", base_ref.object.sha)
+
+    def commit(
+        self,
+        files: Union[dict[str, str], list[str]],
+        message: str,
+        branch: str | None = None,
+    ) -> str:
+        """
+        Commit files to the repository via the GitHub Contents API.
+
+        Parameters
+        ----------
+        files   : Either a ``dict[path, content]`` mapping (preferred), or a
+                  ``list[path]`` of local file paths whose content is read from
+                  disk.
+        message : Commit message.
+        branch  : Target branch.  Defaults to ``self._base_branch``.
+
+        Returns
+        -------
+        SHA of the last created/updated commit, or empty string if no files
+        were committed.
+        """
+        target_branch = branch or self._base_branch
+
+        # Normalise to {path: content}
+        if isinstance(files, list):
+            files_dict: dict[str, str] = {}
+            for path in files:
+                with open(path, "r", encoding="utf-8") as fh:
+                    files_dict[path] = fh.read()
+        else:
+            files_dict = files
+
+        last_sha: str = ""
+        for path, content in files_dict.items():
+            try:
+                existing = self._repo.get_contents(path, ref=target_branch)
+                result = self._repo.update_file(
+                    path=path,
+                    message=message,
+                    content=content,
+                    sha=existing.sha,  # type: ignore[union-attr]
+                    branch=target_branch,
+                )
+            except GithubException:
+                # File does not exist yet — create it
+                result = self._repo.create_file(
+                    path=path,
+                    message=message,
+                    content=content,
+                    branch=target_branch,
+                )
+            last_sha = result["commit"].sha
+
+        return last_sha
 
     def create_pr(self, title: str, body: str, head: str, base: str) -> str:
-        # TODO (Phase 2): POST to GitHub API /repos/{owner}/{repo}/pulls.
+        """
-        # Return the HTML URL of the created PR.
+        Open a pull request on GitHub.
-        raise NotImplementedError("GitHubAdapter.create_pr is not yet implemented.")
+
+        Parameters
+        ----------
+        title : PR title.
+        body  : PR description / body markdown.
+        head  : Head branch name (the branch with changes).
+        base  : Base branch name (e.g. "main").
+
+        Returns
+        -------
+        HTML URL of the created pull request.
+        """
+        pr = self._repo.create_pull(
+            title=title,
+            body=body,
+            head=head,
+            base=base,
+        )
+        return pr.html_url
 
     def get_pr_status(self, pr_id: str) -> str:
-        # TODO (Phase 2): GET /repos/{owner}/{repo}/pulls/{number}.
+        """
-        # Map GitHub PR state ("open", "closed") + merged flag to
+        Fetch the current status of a pull request.
-        # our schema: "open" | "merged" | "closed".
+
-        raise NotImplementedError("GitHubAdapter.get_pr_status is not yet implemented.")
+        Parameters
+        ----------
+        pr_id : Pull request number as a string (e.g. "42").
+
+        Returns
+        -------
+        One of: "open" | "merged" | "closed".
+        """
+        pr = self._repo.get_pull(int(pr_id))
+        if pr.merged:
+            return "merged"
+        return pr.state  # "open" or "closed"

requirements.txt

@@ -10,6 +10,9 @@ pyyaml
 # Environment variable management
 python-dotenv
 
+# GitHub VCS adapter
+PyGithub
+
 # --- stdlib-only (no pip install needed) ---
 # sqlite3   — blackboard persistence
 # dataclasses — task_brief schema