devvy 0.1.0__py3-none-any.whl

cli/models.py

@@ -0,0 +1,83 @@
+"""ORM models for the CLI's local SQLite database.
+
+These are intentionally separate from the server-side app/models/ so the CLI
+package has no dependency on app/.  The schema is a simplified subset —
+no MSSQL-specific types, no alembic migrations needed (tables are created
+automatically via create_tables() on startup).
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from cli.db import Base
+from cli.fsm import TicketState
+
+
+class Ticket(Base):
+    """A coding task submitted to the local agent."""
+
+    __tablename__ = "tickets"
+
+    id: Mapped[str] = mapped_column(
+        String(36), primary_key=True, default=lambda: str(uuid.uuid4())
+    )
+    title: Mapped[str] = mapped_column(String(500), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    repo_url: Mapped[str] = mapped_column(String(1000), nullable=False)
+    branch_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    state: Mapped[str] = mapped_column(
+        String(50), nullable=False, default=TicketState.RECEIVED.value
+    )
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=lambda: datetime.now(UTC)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=lambda: datetime.now(UTC)
+    )
+
+
+class GraphContext(Base):
+    """Persists orchestrator state so it survives between runs."""
+
+    __tablename__ = "graph_contexts"
+    __table_args__ = (
+        UniqueConstraint("ticket_id", name="uq_graph_contexts_ticket_id"),
+    )
+
+    id: Mapped[str] = mapped_column(
+        String(36), primary_key=True, default=lambda: str(uuid.uuid4())
+    )
+    ticket_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("tickets.id"), nullable=False, index=True
+    )
+    current_state: Mapped[str] = mapped_column(String(50), nullable=False)
+    retry_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    container_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    pr_number: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    plan_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    opencode_session_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    logs: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    workspace_path: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    # Comma-separated thread IDs that have already been responded to, so the
+    # agent does not re-address comments it has already handled.
+    seen_thread_ids: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    default_branch: Mapped[str] = mapped_column(
+        String(255), nullable=False, default="main"
+    )
+    # JSON-serialised RepoContainerConfig — set during PREPARE_ENV and used
+    # by VALIDATE to build and run the repo's own container for checks.
+    repo_container_config_json: Mapped[str | None] = mapped_column(Text, nullable=True)
+    # PID of the background process running the orchestrator for this ticket.
+    # Set to os.getpid() at startup; cleared to NULL on terminal state.
+    # Used by `devvy status` and `devvy ps` to determine if a ticket is actively
+    # being processed or has crashed mid-run.
+    worker_pid: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=lambda: datetime.now(UTC)
+    )

cli/orchestrator.py

@@ -0,0 +1,530 @@
+"""Local orchestrator — drives a ticket through its full lifecycle without a server.
+
+All code execution happens inside an ephemeral Docker container (devvy-worker:latest).
+The orchestrator itself only manages state, persistence, and ADO API calls.
+
+Flow:
+  RECEIVED → PREPARE_ENV (clone repo, start container)
+           → PLAN        (opencode: explore + plan, no code changes)
+           → IMPLEMENT   (opencode: implement the plan, same session)
+           → VALIDATE    (pytest / ruff / mypy inside container)
+           → CREATE_PR   (git push + ADO REST API)
+           → WAIT_FOR_REVIEW (poll ADO every 30s)
+           → RESPOND_TO_REVIEW (opencode: address comments)
+           → MERGED / FAILED (stop + remove container)
+
+The FSM logic is copied here to avoid importing from app/ (CLI wheel has no
+dependency on the server package).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from collections.abc import Callable
+from datetime import UTC, datetime
+
+from cli import ado_client, local_runner
+from cli.config import Config
+from cli.db import SessionManager
+from cli.fsm import (
+    VALID_TRANSITIONS,
+    InvalidTransitionError,
+    TicketState,
+    transition as _transition,
+)
+from cli.models import GraphContext, Ticket
+from cli.prompts import parse_replies
+
+
+_PR_POLL_INTERVAL = 30  # seconds between ADO status polls
+_MAX_VALIDATE_RETRIES = 3
+
+
+class Orchestrator:
+    """Drives a single ticket through its lifecycle inside a Docker container."""
+
+    def __init__(self, ticket: Ticket, context: GraphContext, config: Config) -> None:
+        self._ticket = ticket
+        self._ctx = context
+        self._cfg = config
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def run(self, status_callback: Callable[[str], None] | None = None) -> None:
+        """Run the FSM from the current state to a terminal state."""
+        self._ctx.worker_pid = os.getpid()
+        await self._persist()
+        try:
+            while not TicketState(self._ctx.current_state).is_terminal:
+                await self._dispatch(
+                    TicketState(self._ctx.current_state), status_callback
+                )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            await self._fail(str(exc))
+        finally:
+            # Clear the PID so status/ps can distinguish "done" from "crashed".
+            self._ctx.worker_pid = None
+            await self._persist()
+
+    # ------------------------------------------------------------------
+    # Dispatch
+    # ------------------------------------------------------------------
+
+    # Handler map is a class-level constant — it never varies per call or
+    # per instance, so there is no reason to rebuild it on every _dispatch().
+    _HANDLERS: dict[TicketState, str] = {
+        TicketState.RECEIVED: "_handle_received",
+        TicketState.PREPARE_ENV: "_handle_prepare_env",
+        TicketState.PLAN: "_handle_plan",
+        TicketState.IMPLEMENT: "_handle_implement",
+        TicketState.VALIDATE: "_handle_validate",
+        TicketState.CREATE_PR: "_handle_create_pr",
+        TicketState.WAIT_FOR_REVIEW: "_handle_wait_for_review",
+        TicketState.RESPOND_TO_REVIEW: "_handle_respond_to_review",
+        TicketState.MERGED: "_handle_merged",
+        TicketState.FAILED: "_handle_failed",
+    }
+
+    async def _dispatch(
+        self, state: TicketState, cb: Callable[[str], None] | None
+    ) -> None:
+        handler_name = self._HANDLERS[state]
+        if state == TicketState.WAIT_FOR_REVIEW:
+            # _poll_for_review calls cb itself on state transitions, so we
+            # pass cb through rather than calling it once after the handler.
+            await self._poll_for_review(cb)
+        else:
+            await getattr(self, handler_name)()
+            if cb:
+                cb(self._ctx.current_state)
+
+    async def _handle_wait_for_review(self) -> None:
+        """Placeholder — actual work is done by _poll_for_review via _dispatch."""
+        pass  # _dispatch routes WAIT_FOR_REVIEW directly to _poll_for_review
+
+    # ------------------------------------------------------------------
+    # State handlers
+    # ------------------------------------------------------------------
+
+    async def _handle_received(self) -> None:
+        if not self._ticket.repo_url:
+            await self._fail("Ticket has no repo_url")
+            return
+        await self._set_state(TicketState.PREPARE_ENV)
+
+    async def _handle_prepare_env(self) -> None:
+        setup = await local_runner.prepare_workspace(
+            ticket_id=self._ticket.id,
+            repo_url=self._ticket.repo_url,
+            ado_pat=self._cfg.ado_pat,
+            env_file=self._cfg.env_file,
+        )
+        self._ticket.branch_name = setup.branch_name
+        self._ctx.workspace_path = str(setup.workspace)
+        self._ctx.container_id = setup.container_id
+        self._ctx.default_branch = setup.default_branch
+        self._ctx.repo_container_config_json = setup.repo_cfg.to_json()
+        self._append_log(
+            f"Workspace: {setup.workspace}\nBranch: {setup.branch_name}\n"
+            f"Default branch: {setup.default_branch}\nContainer: {setup.container_id[:12]}"
+        )
+        await self._persist()
+        await self._set_state(TicketState.PLAN)
+
+    async def _handle_plan(self) -> None:
+        """Ask opencode to explore the repo and produce a plan. No code changes yet."""
+        container_id = self._require_container()
+        prompt = (
+            f"You are an autonomous coding agent.\n\n"
+            f"Ticket title: {self._ticket.title}\n\n"
+            f"Ticket description:\n{self._ticket.description}\n\n"
+            f"Explore the repository at {local_runner.CONTAINER_WORKSPACE}, understand "
+            f"the existing codebase, and produce a detailed implementation plan. "
+            f"List the files you will create or modify and the exact changes needed. "
+            f"Do NOT make any code changes yet — planning only."
+        )
+        plan_text, session_id = await local_runner.run_opencode(
+            container_id=container_id,
+            prompt=prompt,
+            model=self._cfg.opencode_model,
+        )
+        self._ctx.plan_json = plan_text
+        self._ctx.opencode_session_id = session_id
+        self._append_log(f"Plan (session {session_id}):\n{plan_text}")
+        await self._persist()
+        await self._set_state(TicketState.IMPLEMENT)
+
+    async def _handle_implement(self) -> None:
+        """Continue the opencode session and implement the plan."""
+        container_id = self._require_container()
+        prompt = (
+            "Now implement the plan you just described. "
+            "Make all necessary code changes, create new files where required, "
+            "and ensure the implementation is complete and correct.\n\n"
+            "IMPORTANT: After making your changes, verify them by running the "
+            "repo's validation scripts inside the workspace in this order:\n\n"
+            f"  1. Format:       bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/format.sh\n"
+            f"  2. Code checks:  bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/code-checks.sh\n"
+            f"  3. Tests:        bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/run-tests.sh\n\n"
+            "Fix any failures before finishing. "
+            "You MAY create, update, or delete tests to keep the suite consistent with your changes."
+        )
+        output, session_id = await local_runner.run_opencode(
+            container_id=container_id,
+            prompt=prompt,
+            model=self._cfg.opencode_model,
+            session_id=self._ctx.opencode_session_id or None,
+        )
+        self._ctx.opencode_session_id = session_id
+        self._append_log(f"Implementation:\n{output}")
+        await local_runner.commit_if_changed(
+            container_id, f"agent: implement ticket {self._ticket.id[:8]}"
+        )
+        await self._set_state(TicketState.VALIDATE)
+
+    async def _handle_validate(self) -> None:
+        container_id = self._require_container()
+        if not self._ctx.repo_container_config_json:
+            await self._fail("No repo container config — PREPARE_ENV may have failed")
+            return
+        repo_cfg = local_runner.RepoContainerConfig.from_json(
+            self._ctx.repo_container_config_json
+        )
+        result = await local_runner.run_validation(repo_cfg)
+        self._append_log(f"Validation:\n{result.output}")
+
+        if result.passed:
+            self._ctx.retry_count = 0
+            if self._ctx.pr_number:
+                # PR already exists (post-review validation) — push the updated
+                # branch so the PR reflects the new commits, then go back to polling.
+                branch = self._branch_name
+                await local_runner.push_branch(container_id, branch)
+                await self._set_state(TicketState.WAIT_FOR_REVIEW)
+            else:
+                await self._set_state(TicketState.CREATE_PR)
+            return
+
+        self._ctx.retry_count += 1
+        if self._ctx.retry_count > _MAX_VALIDATE_RETRIES:
+            await self._fail(f"Validation failed after {_MAX_VALIDATE_RETRIES} retries")
+            return
+
+        fix_prompt = (
+            f"The validation checks failed. Fix ALL of the following issues:\n\n"
+            f"{result.output}\n\n"
+            f"Once fixed, verify by re-running the repo's validation scripts in order:\n\n"
+            f"  1. Format:       bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/format.sh\n"
+            f"  2. Code checks:  bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/code-checks.sh\n"
+            f"  3. Tests:        bash {local_runner.CONTAINER_WORKSPACE}/src/scripts/run-tests.sh\n\n"
+            f"Fix everything — do not stop after fixing just one category. "
+            f"All scripts must exit 0 before you finish."
+        )
+        fix_output, session_id = await local_runner.run_opencode(
+            container_id=container_id,
+            prompt=fix_prompt,
+            model=self._cfg.opencode_model,
+            session_id=self._ctx.opencode_session_id or None,
+        )
+        self._ctx.opencode_session_id = session_id
+        self._append_log(f"Self-fix:\n{fix_output}")
+        await local_runner.commit_if_changed(
+            container_id,
+            f"agent: fix validation failures (attempt {self._ctx.retry_count})",
+        )
+        await self._persist()
+        # Stay in VALIDATE — the while loop re-dispatches
+
+    async def _generate_pr_description(self, template: str) -> str:
+        """
+        Ask opencode (continuing the existing session) to fill in *template*
+        based on the changes it just made.
+
+        Returns the filled-in description text.  Falls back to the raw plan
+        text if opencode produces no output.
+        """
+        container_id = self._require_container()
+        prompt = (
+            "Fill in the following pull request template based on the changes "
+            "you just made to this repository. Return ONLY the filled-in "
+            "template text — no preamble, no extra commentary.\n\n"
+            f"Template:\n{template}"
+        )
+        description, session_id = await local_runner.run_opencode(
+            container_id=container_id,
+            prompt=prompt,
+            model=self._cfg.opencode_model,
+            session_id=self._ctx.opencode_session_id or None,
+        )
+        self._ctx.opencode_session_id = session_id
+        return description.strip() or (
+            self._ctx.plan_json or self._ticket.description or ""
+        )
+
+    async def _handle_create_pr(self) -> None:
+        container_id = self._require_container()
+        branch = self._branch_name
+        await local_runner.push_branch(container_id, branch)
+
+        template = local_runner.read_pr_template(self._ticket.id)
+        if template:
+            description = await self._generate_pr_description(template)
+            self._append_log(f"PR description generated from template:\n{description}")
+        else:
+            description = self._ctx.plan_json or self._ticket.description or ""
+
+        pr_number, pr_url = await ado_client.create_pr(
+            repo_url=self._ticket.repo_url,
+            branch=branch,
+            title=f"[Agent] {self._ticket.title}",
+            description=description,
+            ado_org_url=self._cfg.ado_org_url,
+            ado_project=self._cfg.ado_project,
+            ado_pat=self._cfg.ado_pat,
+            target_branch=self._ctx.default_branch or "main",
+        )
+        self._ctx.pr_number = pr_number
+        self._append_log(f"PR #{pr_number} created: {pr_url}")
+        await self._set_state(TicketState.WAIT_FOR_REVIEW)
+
+    async def _poll_for_review(self, cb: Callable[[str], None] | None) -> None:
+        """Poll ADO every 30s until the PR is merged, abandoned, or has new comments."""
+        pr_number = self._ctx.pr_number
+        if not pr_number:
+            await self._fail("No PR number in WAIT_FOR_REVIEW")
+            return
+
+        self._append_log("Waiting for PR review (polling ADO every 30s)...")
+        await self._persist()
+
+        while True:
+            await asyncio.sleep(_PR_POLL_INTERVAL)
+            try:
+                status = await ado_client.get_pr_status(
+                    self._ticket.repo_url,
+                    pr_number,
+                    self._cfg.ado_org_url,
+                    self._cfg.ado_project,
+                    self._cfg.ado_pat,
+                )
+            except Exception as exc:
+                self._append_log(f"ADO poll error: {exc}")
+                continue
+
+            if status == "completed":
+                await self._set_state(TicketState.MERGED)
+                if cb:
+                    cb(self._ctx.current_state)
+                return
+            elif status == "abandoned":
+                await self._fail("PR was abandoned")
+                return
+            else:
+                try:
+                    comments = await ado_client.get_pr_comments(
+                        self._ticket.repo_url,
+                        pr_number,
+                        self._cfg.ado_org_url,
+                        self._cfg.ado_project,
+                        self._cfg.ado_pat,
+                    )
+                except Exception:
+                    comments = []
+
+                seen_map = self._seen_thread_map()
+                new_threads = [
+                    t
+                    for t in comments
+                    if max(c["comment_id"] for c in t["comments"])
+                    > seen_map.get(t["thread_id"], 0)
+                ]
+                if new_threads:
+                    await self._set_state(TicketState.RESPOND_TO_REVIEW)
+                    if cb:
+                        cb(self._ctx.current_state)
+                    return
+
+    async def _handle_respond_to_review(self) -> None:
+        pr_number = self._ctx.pr_number
+        if not pr_number:
+            await self._fail("No PR number in RESPOND_TO_REVIEW")
+            return
+
+        container_id = self._require_container()
+        threads = await ado_client.get_pr_comments(
+            self._ticket.repo_url,
+            pr_number,
+            self._cfg.ado_org_url,
+            self._cfg.ado_project,
+            self._cfg.ado_pat,
+        )
+
+        seen_map = self._seen_thread_map()
+        new_threads = [
+            t
+            for t in threads
+            if max(c["comment_id"] for c in t["comments"])
+            > seen_map.get(t["thread_id"], 0)
+        ]
+
+        if not new_threads:
+            await self._set_state(TicketState.WAIT_FOR_REVIEW)
+            return
+
+        # Build a full thread history block for each new thread so OpenCode
+        # has full context (prior conversation + new reply).
+        thread_blocks = []
+        for t in new_threads:
+            header = f"thread_id={t['thread_id']}, file={t['file_path'] or 'general'}:"
+            lines = [header]
+            for c in t["comments"]:
+                lines.append(f"  [{c['author']}] {c['body']}")
+            thread_blocks.append("\n".join(lines))
+        thread_section = "\n\n".join(thread_blocks)
+
+        prompt = (
+            "You have the following PR review threads to address. Each thread "
+            "shows the full conversation history — the last message in each "
+            "thread is the newest comment requiring your attention.\n\n"
+            f"{thread_section}\n\n"
+            "For each thread:\n"
+            "1. If you agree it requires a code change, make the change.\n"
+            "2. If you disagree, do NOT make the change — instead explain "
+            "   your reasoning clearly and respectfully in your reply.\n"
+            "3. You MUST write a reply for every thread, whether you made a "
+            "   change or not (e.g. 'Good catch, fixed.' or 'I disagree "
+            "   because ...').\n\n"
+            "At the end of your response, output your replies in EXACTLY "
+            "this format (no extra blank lines between entries):\n\n"
+            "REPLIES:\n"
+            "thread_id=<id>: <your reply text>\n"
+            "thread_id=<id>: <your reply text>\n"
+        )
+
+        output, session_id = await local_runner.run_opencode(
+            container_id=container_id,
+            prompt=prompt,
+            model=self._cfg.opencode_model,
+            session_id=self._ctx.opencode_session_id or None,
+        )
+        self._ctx.opencode_session_id = session_id
+        self._append_log(f"Review response:\n{output}")
+
+        # Post a reply to each thread in ADO, then advance the high-water mark
+        # to include devvy's own reply comment ID so we don't re-process it.
+        replies = parse_replies(output)
+        for t in new_threads:
+            tid = t["thread_id"]
+            # High-water mark: max comment ID seen in this thread so far.
+            max_seen = max(c["comment_id"] for c in t["comments"])
+            message = replies.get(tid, "Reviewed and addressed.")
+            try:
+                new_comment_id = await ado_client.post_thread_reply(
+                    repo_url=self._ticket.repo_url,
+                    pr_number=pr_number,
+                    thread_id=tid,
+                    message=message,
+                    ado_org_url=self._cfg.ado_org_url,
+                    ado_project=self._cfg.ado_project,
+                    ado_pat=self._cfg.ado_pat,
+                )
+                # Advance mark to include devvy's own reply so it isn't re-processed.
+                max_seen = max(max_seen, new_comment_id)
+                self._append_log(f"Posted reply to thread {tid}: {message}")
+            except Exception as exc:
+                self._append_log(f"Failed to post reply to thread {tid}: {exc}")
+            self._mark_comments_seen(tid, max_seen)
+
+        # Commit any code changes OpenCode made.
+        committed = await local_runner.commit_if_changed(
+            container_id, "agent: address PR review comments"
+        )
+
+        self._ctx.retry_count = 0
+        await self._persist()
+
+        if committed:
+            # Code changed — run validation before re-entering the review loop.
+            await self._set_state(TicketState.VALIDATE)
+        else:
+            # Pure discussion (replies only, no code changes) — skip CI and
+            # go straight back to waiting for the next reviewer action.
+            await self._set_state(TicketState.WAIT_FOR_REVIEW)
+
+    async def _handle_merged(self) -> None:
+        await local_runner.cleanup_workspace(self._ticket.id, self._ctx.container_id)
+        self._append_log("Ticket complete — PR merged.")
+        await self._persist()
+
+    async def _handle_failed(self) -> None:
+        await local_runner.cleanup_workspace(self._ticket.id, self._ctx.container_id)
+        await self._persist()
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    async def _set_state(self, target: TicketState) -> None:
+        current = TicketState(self._ctx.current_state)
+        new_state = _transition(current, target)
+        self._ctx.current_state = new_state.value
+        self._ticket.state = new_state.value
+        self._ticket.updated_at = datetime.now(UTC)
+        await self._persist()
+
+    async def _fail(self, reason: str) -> None:
+        self._ticket.error_message = reason
+        try:
+            await self._set_state(TicketState.FAILED)
+        except Exception:
+            self._ctx.current_state = TicketState.FAILED.value
+            self._ticket.state = TicketState.FAILED.value
+            await self._persist()
+        await self._handle_failed()
+
+    async def _persist(self) -> None:
+        self._ctx.updated_at = datetime.now(UTC)
+        async with SessionManager.session() as session:
+            session.add(self._ticket)
+            session.add(self._ctx)
+
+    def _require_container(self) -> str:
+        if not self._ctx.container_id:
+            raise RuntimeError("No container_id — PREPARE_ENV may have failed")
+        return self._ctx.container_id
+
+    @property
+    def _branch_name(self) -> str:
+        return self._ticket.branch_name or f"agent/{self._ticket.id[:8]}"
+
+    def _seen_thread_map(self) -> dict[str, int]:
+        """Return a mapping of thread_id → max comment_id seen.
+
+        Stored as a JSON object in ``seen_thread_ids``, e.g.::
+
+            {"64": 3, "65": 1, "66": 2}
+        """
+        raw = self._ctx.seen_thread_ids or ""
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            # Graceful fallback for any stale data from a previous format.
+            return {}
+
+    def _mark_comments_seen(self, thread_id: str, max_comment_id: int) -> None:
+        """Record that we have seen up to *max_comment_id* in *thread_id*."""
+        seen_map = self._seen_thread_map()
+        seen_map[thread_id] = max(seen_map.get(thread_id, 0), max_comment_id)
+        self._ctx.seen_thread_ids = json.dumps(seen_map)
+
+    def _append_log(self, message: str) -> None:
+        timestamp = datetime.now(UTC).isoformat()
+        self._ctx.logs = f"{self._ctx.logs}\n[{timestamp}] {message}".strip()

cli/prompts.py

@@ -0,0 +1,42 @@
+"""Prompt parsing helpers for the devvy CLI.
+
+Contains pure-Python parsers for structured output produced by opencode,
+kept separate from ADO API calls (ado_client.py) and orchestration logic.
+"""
+
+from __future__ import annotations
+
+
+def parse_replies(output: str) -> dict[str, str]:
+    """Extract per-thread replies from OpenCode's structured output.
+
+    Looks for a block of the form::
+
+        REPLIES:
+        thread_id=abc123: Great suggestion, fixed.
+        thread_id=def456: I disagree because X.
+
+    Returns a dict mapping thread_id → reply text.  Lines that don't match
+    the expected format are silently skipped.
+    """
+    replies: dict[str, str] = {}
+    in_block = False
+    for line in output.splitlines():
+        stripped = line.strip()
+        if stripped == "REPLIES:":
+            in_block = True
+            continue
+        if in_block:
+            # Stop at the next blank line or a line that looks like a new section
+            if not stripped:
+                break
+            if stripped.startswith("thread_id="):
+                # thread_id=<id>: <message>
+                rest = stripped[len("thread_id=") :]
+                if ":" in rest:
+                    tid, _, msg = rest.partition(":")
+                    tid = tid.strip()
+                    msg = msg.strip()
+                    if tid and msg:
+                        replies[tid] = msg
+    return replies