codee-agent 0.1.0__py3-none-any.whl

codee_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,69 @@
+codee/.gitignore,sha256=Fltsn5J90L9HwYTVg7Xlaoek3U0riZWmDTWmf0Ttfr8,15
+codee/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee/admin.py,sha256=nL_zv7XuO1gSND25AAVrBMRfDd042LLiM5MXgGp2-CY,71801
+codee/admin_api.py,sha256=q2S2H6neSXkcjrlhI3s190jJbOgenL0sqle5vnYmM5E,2503
+codee/admin_cli.py,sha256=V57mVyxDPPCW3IP715Fnejfp_o7H8XXiADTKLTAh-fY,2461
+codee/admin_service.py,sha256=hs8hNLBeNg5wjkIndTzYRnw2MEpKrBpHeUu-uK-_lFs,42135
+codee/executor.py,sha256=t30M0svaRfCP3CI1ES0FNEafu0H-Q70UR-_9tCgw71Q,14938
+codee/init_cli.py,sha256=0i_epmF5S2PeKNwHgRIvrjY-yn3V2sGiTsI3O5ha0tQ,2858
+codee/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee/lib/cron_describe.py,sha256=OTq58sKafyEz23WsZJdlxO0mOf944X4sXtNqY0pkNq4,960
+codee/lib/runs_db.py,sha256=YBL30GBucK6e5zHEDQYLdqCnuq0IX4A4ZJDpNdd_WwE,8350
+codee/lib/test_runs_db.py,sha256=ILZ_Dv3GW6HNNE7reKbZ8kW--nBbwfw2MpaPO_K_VU8,8225
+codee/lib/test_trigger_cron_skills.py,sha256=hLnJHETzO9vHP_dUws9i_abAUNOxv4eqOadaAQefJqk,18482
+codee/lib/test_trigger_issue_skills.py,sha256=1tHA-aP28HEQEKxsYKaKXn-c5dn_TJirg7_Y-wevIFI,3675
+codee/lib/trigger_aws_sqs_skills.py,sha256=n3r1zEgOiywPEsWtDiLpGZOpsQM49mfQREh6wJ7Myyo,7178
+codee/lib/trigger_cron_skills.py,sha256=GnkG4ED9doONDRGyjaMF9BgRO9dC2dhGRZ7IhsdZuRw,12722
+codee/lib/trigger_email_skills.py,sha256=1-eX__ZMCTzljzcTN34RCvU8-0Q4H67CFEW5_HlD_vM,8095
+codee/lib/trigger_issue_skills.py,sha256=MXQMR23L1HN-c4a9dFvqFbY9BtVeyFdVX8f9kzc8R-w,3630
+codee/mail_server.py,sha256=vqlObtIo59zjsTknWTdFhXJMOOG5bBbc5JMm4TDX1IU,1691
+codee/start_cli.py,sha256=-YHCM3VHb1leZhH9lYOiJnMshGOJOlq7sTxfOrtzTB0,2940
+codee/templates/AGENTS.md,sha256=NXJIXxo7_91jO47IdXxM-w5uSDjhPWeJryMy7_R6c1I,1815
+codee/templates/CLAUDE.md,sha256=kYsckFWTVe948z_fNWLysCHvi9_YpchBXl3s1Ek03lU,10
+codee/templates/skills/aws-sqs-alarm-response/SKILL.md,sha256=HGs1vAqIa2hxU94SS8lTmxaUnId3Wf9usAnqawtY8yE,904
+codee/templates/skills/cron-research-5xx-errors/SKILL.md,sha256=h131nDVkndvg9HUfWaUC1sTyynDp56IVLYH2yti41Ho,704
+codee/templates/skills/story-code-reviewer/SKILL.md,sha256=t8iADhFqrd5TvsZ849n1mPNSQT4ujwwtP7zF7uE9-oU,1311
+codee/templates/skills/story-developer/SKILL.md,sha256=pndrmcfMhM5ubtkW0lCxgoqMtYHvro8oBbFv0DlKtyk,1398
+codee/templates/skills/story-planner/SKILL.md,sha256=IKHvGuy9EUplYgkPuZts4edjTcmWwk6SptVA8C-n_5g,1871
+codee/templates/skills/story-planner/assets/readme-template.md,sha256=kIzyB8yk9zA5SWIhQb2XhuvXDBbG6vxmzOMQAgCkukw,793
+codee/templates/skills/story-qa/SKILL.md,sha256=-W7g8g4mePkCV5-mqt42_qwo6RPWrD_huQVHpadbcWs,1614
+codee/templates/skills/task-developer/SKILL.md,sha256=CKMLv-YDKmXhwZV8c6Ufjpy0QFJ0nEM4WI8yBdv7t4E,1488
+codee/templates/skills/task-qa/SKILL.md,sha256=ihdRKhSoZfupVXrclZIhILaAVMmGRIRaOuSmYwgg9sE,1395
+codee/test_admin_api.py,sha256=eT-ZCWw8giVU5V1xdqdctytVjuXV3wm3FKv4Nnp3gaU,2710
+codee/test_admin_cli.py,sha256=5AWSdeSgsY-RuFmP-ol5NDASvlelVhJXPZiQatSALrk,2350
+codee/test_admin_service.py,sha256=ESz89Tva0U9VzjUSrGZEowssLDSLFEL6QLqDf1Jwj-g,42706
+codee/test_executor.py,sha256=K5p_KWd9JC0uE0UXSge--rmSh7UjMGYtzBRfoQl-Tz4,7312
+codee/test_init_cli.py,sha256=1POSbxbmOFf1mRLBEMgXDrr7eWQ6k8S02_ahqLjQJm8,5606
+codee/test_memory_index.py,sha256=8Q2wq2l-L53QBDqzAeGaTQAaK4aCI4zo7WZND7byUZw,841
+codee/test_start_cli.py,sha256=04Bcr-WH2gAfptii-6NgjEs7xxEFDqoNB0CJP0U58DM,5942
+codee/workflow_graph.py,sha256=_R8TvXLQr0rtrELcPoNMMYTe4Wr9CRB_hRDw8imIl_4,2539
+codee_admin/__init__.py,sha256=kdPfIMlHX4kajFVw6XmC2jqsw1XKkkfEGWWC_3bdDZE,51
+codee_admin/codee_admin.py,sha256=MVzRzfRsMYWkcaD3zQG8bDmvs5FTrUSFz1Ij-_wU8e4,93
+codee_agent_abstract/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_agent_abstract/provider.py,sha256=lUYAuLTasdIwWc3Hw43ivYNTncTVRBq0xjMBVL19X2Y,1949
+codee_agent_claude_code/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_agent_claude_code/provider.py,sha256=ktD2idOc5cMb5h4yE-TQEc80L1iA7_bg3KPEzwefreU,3380
+codee_agent_github_copilot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_agent_github_copilot/provider.py,sha256=jJm0vOyj6VfoCUUqup0tsTtYHgUmov1Hef7Eh_H54qQ,9392
+codee_agent_github_copilot/test.py,sha256=VXMSmx-wl-pD2hh3bS3SyTjjxiUpuaYTOBkVt9uXJ_Y,7085
+codee_database/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_database/database.py,sha256=qoIemJhiOfZEaoN3AspFaLmfAXZkCm8bgctuUs9MKwE,358
+codee_database/oauth_tokens.py,sha256=x3UOhfcc3qr-qnedhI9eGyvkUx1MsagoIy70JH7wuWM,5971
+codee_main_context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_main_context/context.py,sha256=a4vl_upntRenMByuv8nr7VfQX_zLpeDFtSn2OGyRzhE,4583
+codee_main_context/logging.py,sha256=dZk3RnYrKh12TXpG_3G-4v1ky4KXLPA7oj-_hmjU190,3742
+codee_main_context/test_logging.py,sha256=5-GVjjmUNH320lc7_6YZBwIPav4--PfnSY1_QU_4c4Q,3543
+codee_tasks_abstract/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_tasks_abstract/provider.py,sha256=Jpv0FilAumNWDQkilJbrU5C88ddcD0LakYSvCWdxwk8,1923
+codee_tasks_azure_devops/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_tasks_azure_devops/oauth.py,sha256=gUaaFid32UxFYR9mULg3tDI4Pq1ij4pauLmxbF-6itE,13302
+codee_tasks_azure_devops/provider.py,sha256=m83Qx79KvL_m9AxAmDS1_hZIREpJLmsiXJrgvF5WvMs,8922
+codee_tasks_azure_devops/test.py,sha256=zvYi2dfILEENB6nMNfG1kMiskOACDaCCHFlDLlVXjkk,20355
+codee_tasks_jira/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codee_tasks_jira/provider.py,sha256=enIlKVsv50KDvAK37JFtQHiqh1dButKe4a9j0S837AU,6155
+codee_tasks_jira/test.py,sha256=S-k51HdQD4qnp6qeTi73QSLFzvObmYZLPEMTOCq5jpw,2425
+codee_agent-0.1.0.dist-info/licenses/LICENSE,sha256=kXz80_Kc5IXrxIiweSCMx9Dv_AUeOcfwnQqCk2IDTmY,1075
+codee_agent-0.1.0.dist-info/WHEEL,sha256=a0ta4TK7UKMB0EbDesmi2mn0Djkly7aj_7Tu2R7SseE,81
+codee_agent-0.1.0.dist-info/entry_points.txt,sha256=hTLMHLPAf2JRk3wwy-t3R5oqM4AlwQCJy2H7-MjA1xQ,159
+codee_agent-0.1.0.dist-info/METADATA,sha256=5sXrClMO-uf8culqG6266h_cFUBNTw6ckQLDJ-33_-k,2304
+codee_agent-0.1.0.dist-info/RECORD,,

codee_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.33
+Root-Is-Purelib: true
+Tag: py3-none-any

codee_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+codee-admin = codee.admin_cli:main
+codee-executor = codee.executor:main
+codee-init = codee.init_cli:main
+codee-start = codee.start_cli:main
+

codee_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codee contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codee_agent_abstract/provider.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+from codee_main_context.context import Settings
+
+
+@dataclass(frozen=True)
+class AgentModel:
+    """One model a coding agent can run, as the admin UI shows and stores it.
+
+    ``id`` is what goes into the skill's ``model:`` frontmatter and onto the CLI;
+    ``name`` is the human-readable label ("Claude Opus 5" for ``claude-opus-5``).
+    """
+
+    id: str
+    name: str
+
+
+class AbstractCodingAgent(ABC):
+    """Base class every coding agent (e.g. Claude Code) inherits from.
+
+    A coding agent is constructed from the app ``Settings`` and the working
+    directory it should run in, and knows how to run one prompt under a session
+    id the caller hands it. The executor never has to know which agent it's
+    driving or what configuration that agent needs.
+    """
+
+    def __init__(self, settings: Settings, cwd: Path):
+        self._cwd = cwd
+
+    @abstractmethod
+    def run(self, user_message: str, session_id: str, model: str = "") -> str:
+        """Run the agent with the message in ``session_id`` and return its text.
+
+        ``model`` is the skill's ``model:`` frontmatter, or empty for the agent's
+        default. Agents that read the frontmatter themselves may ignore it.
+
+        Must raise on any failure so callers can retry (SQS keeps the message,
+        cron doesn't mark the slot done, email keeps the ``.eml``).
+        """
+        ...
+
+    @classmethod
+    def list_models(cls) -> list[AgentModel]:
+        """Models this agent offers, best-effort, for the admin UI's picker.
+
+        Returns an empty list when the agent can't be asked. Callers must still
+        accept a model id typed by hand, since the list is a convenience rather
+        than an allowlist.
+        """
+        return []
+
+    def describe(self) -> str:
+        """Human-readable one-liner about this agent, for logs."""
+        return type(self).__name__

codee_agent_claude_code/provider.py

@@ -0,0 +1,90 @@
+import json
+import subprocess
+from pathlib import Path
+
+from codee_agent_abstract.provider import AbstractCodingAgent, AgentModel
+from codee_main_context.context import Settings
+from codee_main_context.logging import get_logger
+
+
+log = get_logger(__name__)
+
+# The `claude` CLI has no command that enumerates its models, so this catalog is
+# maintained by hand. It only feeds the admin UI's picker — the editor also takes
+# a model id typed by hand, so a model missing here is still usable.
+MODELS = [
+    AgentModel("claude-opus-5", "Claude Opus 5"),
+    AgentModel("claude-sonnet-5", "Claude Sonnet 5"),
+    AgentModel("claude-fable-5", "Claude Fable 5"),
+    AgentModel("claude-opus-4-8", "Claude Opus 4.8"),
+    AgentModel("claude-opus-4-7", "Claude Opus 4.7"),
+    AgentModel("claude-opus-4-6", "Claude Opus 4.6"),
+    AgentModel("claude-sonnet-4-6", "Claude Sonnet 4.6"),
+    AgentModel("claude-haiku-4-5", "Claude Haiku 4.5"),
+    AgentModel("opus", "Latest Opus (alias)"),
+    AgentModel("sonnet", "Latest Sonnet (alias)"),
+    AgentModel("haiku", "Latest Haiku (alias)"),
+]
+
+
+class ClaudeCodeAgent(AbstractCodingAgent):
+    """Runs the ``claude`` CLI in a fresh session, under the id the caller supplies."""
+
+    MAX_BUDGET_USD = "20.00"
+    TIMEOUT_SECONDS = 7200  # 2 hours
+
+    def __init__(self, settings: Settings, cwd: Path):
+        super().__init__(settings, cwd)
+
+    @classmethod
+    def list_models(cls) -> list[AgentModel]:
+        return list(MODELS)
+
+    def run(self, user_message: str, session_id: str, model: str = "") -> str:
+        # `model` is deliberately not forwarded as --model: Claude Code reads the
+        # skill's `model:` frontmatter itself.
+        cmd = [
+            "claude",
+            "-p", user_message,
+            "--session-id", session_id,
+            "--max-budget-usd", self.MAX_BUDGET_USD,
+            "--output-format", "json",
+            "--permission-mode", "bypassPermissions",
+        ]
+
+        log.info("Running claude with message: %s", user_message)
+        log.debug("cwd=%s cmd=%s", self._cwd, " ".join(cmd))
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self.TIMEOUT_SECONDS,
+                cwd=self._cwd,
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("Claude CLI timed out after 2 hours")
+
+        log.debug("claude exited %d (%d bytes stdout, %d bytes stderr)",
+                  result.returncode, len(result.stdout), len(result.stderr))
+
+        # Raise on any non-success so callers retry. Over-limit exits non-zero;
+        # a completed-but-errored run sets is_error in the JSON.
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"Claude CLI exited {result.returncode}: {result.stderr.strip()[:500]}"
+            )
+
+        try:
+            response = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return result.stdout
+        if isinstance(response, dict):
+            if response.get("is_error"):
+                raise RuntimeError(
+                    f"Claude run errored ({response.get('subtype', 'unknown')}): "
+                    f"{str(response.get('result', ''))[:500]}"
+                )
+            return response.get("result", result.stdout)
+        return result.stdout

codee_agent_github_copilot/provider.py

@@ -0,0 +1,253 @@
+import json
+import queue
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+from codee_agent_abstract.provider import AbstractCodingAgent, AgentModel
+from codee_main_context.context import Settings
+from codee_main_context.logging import get_logger
+
+
+log = get_logger(__name__)
+
+# Events the CLI streams that carry the pieces we care about. Everything else in
+# the JSONL stream (tool calls, MCP chatter, usage checkpoints) is skipped.
+ASSISTANT_MESSAGE = "assistant.message"
+SESSION_ERROR = "session.error"
+RESULT = "result"
+
+# `copilot` has no "list models" command, but its Agent Client Protocol mode
+# answers session/new with the account's live catalog — ids and display names
+# both. That's the only way to ask the CLI what it can run.
+ACP_TIMEOUT_SECONDS = 60
+_INITIALIZE_ID = 1
+_SESSION_NEW_ID = 2
+
+
+class GitHubCopilotAgent(AbstractCodingAgent):
+    """Runs the ``copilot`` CLI in a fresh session, under the id the caller supplies."""
+
+    # Ceiling on what one run may spend. AI credits bill at $0.04 each, so this
+    # is the same $20 cap the Claude Code agent puts on a run. Minimum is 30.
+    MAX_AI_CREDITS = "500"
+    TIMEOUT_SECONDS = 7200  # 2 hours
+
+    def __init__(self, settings: Settings, cwd: Path):
+        super().__init__(settings, cwd)
+
+    @classmethod
+    def list_models(cls) -> list[AgentModel]:
+        try:
+            return _fetch_acp_models()
+        except Exception as exc:
+            # The picker falls back to free text, so a CLI that isn't installed
+            # or isn't logged in must not break the admin UI.
+            log.warning("Could not read the copilot model catalog: %s", exc)
+            return []
+
+    def run(self, user_message: str, session_id: str, model: str = "") -> str:
+        cmd = [
+            "copilot",
+            "-p", user_message,
+            "--session-id", session_id,
+            "--max-ai-credits", self.MAX_AI_CREDITS,
+            "--output-format", "json",
+            # Tools, paths and URLs: the equivalent of claude's bypassPermissions.
+            "--allow-all",
+            # Nothing is around to answer questions in a headless run.
+            "--no-ask-user",
+            "--no-color",
+        ]
+        # Copilot never sees the skill's frontmatter — the triggers hand it the
+        # body alone — so a skill's model only takes effect via this flag.
+        if model:
+            cmd += ["--model", model]
+
+        log.info("Running copilot with message: %s", user_message)
+        log.debug("cwd=%s cmd=%s", self._cwd, " ".join(cmd))
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self.TIMEOUT_SECONDS,
+                cwd=self._cwd,
+            )
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("Copilot CLI timed out after 2 hours")
+
+        log.debug("copilot exited %d (%d bytes stdout, %d bytes stderr)",
+                  result.returncode, len(result.stdout), len(result.stderr))
+
+        reply, outcome, errors = _parse_events(result.stdout)
+
+        # Raise on any non-success so callers retry. A run that fails before the
+        # session starts (bad model, no auth) exits non-zero with nothing on
+        # stdout; one that fails mid-run reports it in the trailing result event.
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"Copilot CLI exited {result.returncode}: "
+                f"{_detail(errors, result.stderr)}"
+            )
+        if outcome is None:
+            # Not the JSONL we know how to read — hand back whatever it printed
+            # rather than failing a run that the CLI itself called successful.
+            log.warning("copilot produced no result event; returning raw output")
+            return result.stdout
+        if outcome.get("exitCode"):
+            raise RuntimeError(
+                f"Copilot run errored (exit code {outcome['exitCode']}): "
+                f"{_detail(errors, result.stderr)}"
+            )
+        if not reply:
+            raise RuntimeError(
+                f"Copilot run produced no response: {_detail(errors, result.stderr)}"
+            )
+        return reply
+
+
+def _fetch_acp_models() -> list[AgentModel]:
+    """Ask ``copilot --acp`` for the account's model catalog.
+
+    Speaks just enough of the Agent Client Protocol to get a session: initialize,
+    then session/new, whose result carries ``models.availableModels``. The session
+    it opens is a throwaway that no prompt is ever sent to.
+    """
+    process = subprocess.Popen(
+        ["copilot", "--acp"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+        cwd=Path.cwd(),
+    )
+    try:
+        lines: queue.Queue[str] = queue.Queue()
+        reader = threading.Thread(
+            target=_drain, args=(process.stdout, lines), daemon=True)
+        reader.start()
+
+        _send(process, _INITIALIZE_ID, "initialize", {
+            "protocolVersion": 1,
+            "clientCapabilities": {
+                "fs": {"readTextFile": False, "writeTextFile": False},
+            },
+        })
+        _send(process, _SESSION_NEW_ID, "session/new", {
+            "cwd": str(Path.cwd()),
+            "mcpServers": [],
+        })
+
+        result = _await_result(process, lines, _SESSION_NEW_ID)
+    finally:
+        process.kill()
+
+    available = (result.get("models") or {}).get("availableModels") or []
+    models = []
+    for entry in available:
+        if not isinstance(entry, dict):
+            continue
+        model_id = str(entry.get("modelId", "")).strip()
+        if not model_id:
+            continue
+        name = str(entry.get("name", "")).strip() or model_id
+        models.append(AgentModel(model_id, name))
+    log.debug("copilot reported %d model(s)", len(models))
+    return models
+
+
+def _send(process: subprocess.Popen, request_id: int, method: str, params: dict) -> None:
+    request = {"jsonrpc": "2.0", "id": request_id,
+               "method": method, "params": params}
+    process.stdin.write(json.dumps(request) + "\n")
+    process.stdin.flush()
+
+
+def _drain(stream, lines: "queue.Queue[str]") -> None:
+    """Pump the CLI's stdout into a queue so the read can be given a deadline."""
+    for line in stream:
+        lines.put(line)
+
+
+def _await_result(
+    process: subprocess.Popen, lines: "queue.Queue[str]", request_id: int
+) -> dict:
+    """Read until the response to ``request_id`` arrives, or the deadline passes.
+
+    Everything else on the wire — the initialize reply, the session/update
+    notifications the CLI starts emitting straight away — is skipped.
+    """
+    deadline = time.monotonic() + ACP_TIMEOUT_SECONDS
+    while True:
+        if time.monotonic() >= deadline:
+            raise RuntimeError(
+                f"copilot --acp did not answer within {ACP_TIMEOUT_SECONDS}s")
+        try:
+            line = lines.get(timeout=0.5)
+        except queue.Empty:
+            # An immediate exit means the CLI is missing, unauthenticated, or
+            # too old for --acp; no point waiting out the whole deadline.
+            if process.poll() is not None:
+                raise RuntimeError(
+                    f"copilot --acp exited {process.returncode}: "
+                    f"{(process.stderr.read() or '').strip()[:300] or 'no output'}"
+                )
+            continue
+
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(message, dict) or message.get("id") != request_id:
+            continue
+        if "error" in message:
+            raise RuntimeError(f"copilot --acp errored: {message['error']}")
+        result = message.get("result")
+        return result if isinstance(result, dict) else {}
+
+
+def _parse_events(stdout: str) -> tuple[str, dict | None, list[str]]:
+    """Pull the reply, the trailing result event and any errors out of the JSONL.
+
+    Returns ``("", None, [])`` for output that isn't the JSONL stream at all, so
+    the caller can tell "no result event" from "the run failed".
+    """
+    reply = ""
+    outcome: dict | None = None
+    errors: list[str] = []
+
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+
+        kind = event.get("type")
+        if kind == ASSISTANT_MESSAGE:
+            # Keep the last message that actually said something: the ones in
+            # between carry only tool requests, and reasoning is a separate field.
+            content = (event.get("data") or {}).get("content") or ""
+            if content.strip():
+                reply = content.strip()
+        elif kind == SESSION_ERROR:
+            data = event.get("data") or {}
+            message = data.get("message") or data.get("errorType") or "unknown error"
+            errors.append(str(message))
+        elif kind == RESULT:
+            outcome = event
+
+    return reply, outcome, errors
+
+
+def _detail(errors: list[str], stderr: str) -> str:
+    """Best available explanation of a failure, trimmed for the log line."""
+    return ("; ".join(errors) or stderr.strip() or "no error detail")[:500]