py-opencode-wrapper 0.3.0__tar.gz → 0.3.1__tar.gz

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-opencode-wrapper
-Version: 0.3.0
+Version: 0.3.1
 Summary: Async Python wrapper for OpenCode CLI (opencode run --format json)
 Project-URL: Homepage, https://github.com/idailylife/oc_py_wrapper
 Project-URL: Repository, https://github.com/idailylife/oc_py_wrapper
@@ -77,17 +77,21 @@ async def main():
 asyncio.run(main())
 ```
 
-Set `RunConfig(record_thinking=True)` when you want OpenCode reasoning/thinking
-parts included in `result.events` and `log_file` JSON lines. This only maps to
-OpenCode's display/output flag `--thinking`; it does not change model reasoning
-effort. Use `variant` separately if you intentionally want a provider-specific
-reasoning effort.
+Set `RunConfig(cli_kwargs={"thinking": True})` when you want OpenCode
+reasoning/thinking parts included in `result.events` and `log_file` JSON lines in
+**run mode**. This maps to OpenCode's display/output flag `--thinking`; it does
+not change model reasoning effort. In **server/session mode** there is no
+`--thinking` equivalent — reasoning parts are produced per the model's reasoning
+config and streamed onto the SSE bus unconditionally, so they already land in
+`result.events` / `log_file` with no opt-in.
 
 ### Multi-turn conversation (`OpenCodeSession`)
 
-For a stateful, multi-turn chat over a single opencode session, use
-`OpenCodeSession` as an async context manager. Each `send()` continues the same
-session, so the model retains context across turns:
+For a stateful, multi-turn chat, use `OpenCodeSession` as an async context
+manager. Unlike the one-shot `async_run`/`async_stream` (which spawn
+`opencode run` per call), a session owns a headless `opencode serve` process for
+the duration of the `async with` block and re-prompts one server-side session, so
+the model retains context **natively** across turns:
 
 ```python
 import asyncio
@@ -97,19 +101,65 @@ async def chat():
     client = AsyncOpenCodeClient()
     async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle")) as s:
         r1 = await s.send("My name is Bob.")
-        r2 = await s.send("What is my name?")   # auto-continues → "Bob"
+        r2 = await s.send("What is my name?")   # continues natively → "Bob"
         print(s.session_id, r2.final_text)
 
 asyncio.run(chat())
 ```
 
-On enter, the session allocates a private, persistent `XDG_DATA_HOME` tmpdir that
-every turn reuses, so opencode's SQLite session DB survives across turns. The
-first `send()` creates the session (its id is captured on `RunResult.session_id`);
-later turns continue it via `--session <id>`. Each session is an isolated island —
-no shared global DB, so no cross-session lock contention — and the tmpdir is
-removed when the `async with` block exits. `send()` accepts per-turn `run_cfg` and
-`timeout_s` overrides.
+On enter, the session spawns `opencode serve` (with the same hermetic isolation
+run mode uses) and creates one session pinned to the workspace; on exit the
+session is deleted and the server torn down. `send()` accepts per-turn `run_cfg`
+and `timeout_s` overrides, but only **prompt-body knobs** (`model` / `agent` /
+`tools`) vary per turn — `permission` / `mcp` / `instructions` are fixed at enter
+(they are server-global).
+
+#### Human-in-the-loop permissions
+
+Because the server can pause on a permission request, sessions support an
+`on_permission` async callback that run mode cannot. Set `permission={"bash":
+"ask"}` and answer each prompt with `"once"` / `"always"` / `"reject"`:
+
+```python
+async def approve(props):    # props: {"id", "sessionID", "permission", ...}
+    return "once"
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(permission={"bash": "ask"}),
+                           on_permission=approve) as s:
+    r = await s.send("Run `echo hi` and tell me the output.")
+```
+
+When `on_permission` is `None` (the default), any `permission.asked` is
+auto-rejected so a turn never blocks. File attachments are run-mode only — pass
+`RunConfig(cli_kwargs={"f": ["a.txt", "b.png"]})` to `async_run`. Server-mode
+sessions ignore `cli_kwargs`, so embed file content in the prompt instead.
+
+#### Answering the model's questions
+
+opencode's built-in `question` tool lets the model ask the user multiple-choice
+questions mid-run (gather preferences, clarify, offer choices). Pass an
+`on_question` async callback to answer it. The callback receives the question
+props (`{"id", "sessionID", "questions": [{"question", "header", "options":
+[{"label", "description"}], "multiple"?, "custom"?}], ...}`) and returns a list
+with one entry per question — each a list of selected option labels. Returning
+`None` rejects (dismisses) the question.
+
+```python
+async def answer(props):
+    out = []
+    for q in props["questions"]:
+        out.append([q["options"][0]["label"]])   # pick the first option
+    return out
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle"),
+                           on_question=answer) as s:
+    r = await s.send("Ask me which database to use, then scaffold it.")
+```
+
+When `on_question` is `None` (the default), any `question.asked` is auto-rejected
+so a turn never blocks. The `question` tool is enabled by default under
+`opencode serve`; set `RunConfig(extra_env={"OPENCODE_ENABLE_QUESTION_TOOL": "1"})`
+to force-enable it regardless of the server's client identity.
 
 ### Stream structured JSON events
 
@@ -175,7 +225,23 @@ host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
 
 ## CLI arguments
 
-`RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.
+In run mode, `model` and `agent` map to `-m` and `--agent`. Every other
+`opencode run` flag is passed through `RunConfig.cli_kwargs`, a raw dict expanded
+by `build_argv`:
+
+- bool `True` → `--flag` (e.g. `{"fork": True}` → `--fork`)
+- a value → `--flag=value` (e.g. `{"title": "demo"}` → `--title=demo`)
+- a single-char key → `-k value` (e.g. `{"f": "a.txt"}` → `-f a.txt`)
+- a list/tuple → repeated (e.g. `{"f": ["a.txt", "b.txt"]}` → `-f a.txt -f b.txt`)
+- `False` / `None` → skipped
+
+```python
+RunConfig(model="anthropic/claude", cli_kwargs={"fork": True, "title": "demo", "f": ["a.txt"]})
+# -> opencode run --format json -m anthropic/claude --fork --title=demo -f a.txt <prompt>
+```
+
+Prompt text is appended as the final `opencode run` message argument.
+`cli_kwargs` is ignored by `OpenCodeSession` (server mode has no CLI surface).
 
 ## Tests
 
@@ -220,7 +286,7 @@ The defaults already handle the common pitfalls when running many `async_run` ca
 
 To opt out: pass `startup_delay_s=0` (and a large `startup_concurrency`) to drop the startup pacing, `isolate_db=False` to share session history across runs, and `max_retries=0` to disable retries.
 
-> For **multi-turn conversations** you don't need `isolate_db=False`. Use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it keeps one session's DB alive across turns in a private dir, so context is preserved without sharing the global DB.
+> These notes apply to `async_run` / `async_stream` (run mode). For **multi-turn conversations** use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it runs `opencode serve` and re-prompts one server-side session, so context is preserved natively with no shared-DB contention.
 
 ## Notes
 

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/README.md

@@ -62,17 +62,21 @@ async def main():
 asyncio.run(main())
 ```
 
-Set `RunConfig(record_thinking=True)` when you want OpenCode reasoning/thinking
-parts included in `result.events` and `log_file` JSON lines. This only maps to
-OpenCode's display/output flag `--thinking`; it does not change model reasoning
-effort. Use `variant` separately if you intentionally want a provider-specific
-reasoning effort.
+Set `RunConfig(cli_kwargs={"thinking": True})` when you want OpenCode
+reasoning/thinking parts included in `result.events` and `log_file` JSON lines in
+**run mode**. This maps to OpenCode's display/output flag `--thinking`; it does
+not change model reasoning effort. In **server/session mode** there is no
+`--thinking` equivalent — reasoning parts are produced per the model's reasoning
+config and streamed onto the SSE bus unconditionally, so they already land in
+`result.events` / `log_file` with no opt-in.
 
 ### Multi-turn conversation (`OpenCodeSession`)
 
-For a stateful, multi-turn chat over a single opencode session, use
-`OpenCodeSession` as an async context manager. Each `send()` continues the same
-session, so the model retains context across turns:
+For a stateful, multi-turn chat, use `OpenCodeSession` as an async context
+manager. Unlike the one-shot `async_run`/`async_stream` (which spawn
+`opencode run` per call), a session owns a headless `opencode serve` process for
+the duration of the `async with` block and re-prompts one server-side session, so
+the model retains context **natively** across turns:
 
 ```python
 import asyncio
@@ -82,19 +86,65 @@ async def chat():
     client = AsyncOpenCodeClient()
     async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle")) as s:
         r1 = await s.send("My name is Bob.")
-        r2 = await s.send("What is my name?")   # auto-continues → "Bob"
+        r2 = await s.send("What is my name?")   # continues natively → "Bob"
         print(s.session_id, r2.final_text)
 
 asyncio.run(chat())
 ```
 
-On enter, the session allocates a private, persistent `XDG_DATA_HOME` tmpdir that
-every turn reuses, so opencode's SQLite session DB survives across turns. The
-first `send()` creates the session (its id is captured on `RunResult.session_id`);
-later turns continue it via `--session <id>`. Each session is an isolated island —
-no shared global DB, so no cross-session lock contention — and the tmpdir is
-removed when the `async with` block exits. `send()` accepts per-turn `run_cfg` and
-`timeout_s` overrides.
+On enter, the session spawns `opencode serve` (with the same hermetic isolation
+run mode uses) and creates one session pinned to the workspace; on exit the
+session is deleted and the server torn down. `send()` accepts per-turn `run_cfg`
+and `timeout_s` overrides, but only **prompt-body knobs** (`model` / `agent` /
+`tools`) vary per turn — `permission` / `mcp` / `instructions` are fixed at enter
+(they are server-global).
+
+#### Human-in-the-loop permissions
+
+Because the server can pause on a permission request, sessions support an
+`on_permission` async callback that run mode cannot. Set `permission={"bash":
+"ask"}` and answer each prompt with `"once"` / `"always"` / `"reject"`:
+
+```python
+async def approve(props):    # props: {"id", "sessionID", "permission", ...}
+    return "once"
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(permission={"bash": "ask"}),
+                           on_permission=approve) as s:
+    r = await s.send("Run `echo hi` and tell me the output.")
+```
+
+When `on_permission` is `None` (the default), any `permission.asked` is
+auto-rejected so a turn never blocks. File attachments are run-mode only — pass
+`RunConfig(cli_kwargs={"f": ["a.txt", "b.png"]})` to `async_run`. Server-mode
+sessions ignore `cli_kwargs`, so embed file content in the prompt instead.
+
+#### Answering the model's questions
+
+opencode's built-in `question` tool lets the model ask the user multiple-choice
+questions mid-run (gather preferences, clarify, offer choices). Pass an
+`on_question` async callback to answer it. The callback receives the question
+props (`{"id", "sessionID", "questions": [{"question", "header", "options":
+[{"label", "description"}], "multiple"?, "custom"?}], ...}`) and returns a list
+with one entry per question — each a list of selected option labels. Returning
+`None` rejects (dismisses) the question.
+
+```python
+async def answer(props):
+    out = []
+    for q in props["questions"]:
+        out.append([q["options"][0]["label"]])   # pick the first option
+    return out
+
+async with OpenCodeSession(client, ".", run_cfg=RunConfig(model="opencode/big-pickle"),
+                           on_question=answer) as s:
+    r = await s.send("Ask me which database to use, then scaffold it.")
+```
+
+When `on_question` is `None` (the default), any `question.asked` is auto-rejected
+so a turn never blocks. The `question` tool is enabled by default under
+`opencode serve`; set `RunConfig(extra_env={"OPENCODE_ENABLE_QUESTION_TOOL": "1"})`
+to force-enable it regardless of the server's client identity.
 
 ### Stream structured JSON events
 
@@ -160,7 +210,23 @@ host OpenCode config as-is. For reproducible runs, pass `model`, `permission`,
 
 ## CLI arguments
 
-`RunConfig` maps to flags such as `--agent`, `-m`, `-f`, `--attach`, `--title`, etc. Prompt text is appended as the final `opencode run` message argument.
+In run mode, `model` and `agent` map to `-m` and `--agent`. Every other
+`opencode run` flag is passed through `RunConfig.cli_kwargs`, a raw dict expanded
+by `build_argv`:
+
+- bool `True` → `--flag` (e.g. `{"fork": True}` → `--fork`)
+- a value → `--flag=value` (e.g. `{"title": "demo"}` → `--title=demo`)
+- a single-char key → `-k value` (e.g. `{"f": "a.txt"}` → `-f a.txt`)
+- a list/tuple → repeated (e.g. `{"f": ["a.txt", "b.txt"]}` → `-f a.txt -f b.txt`)
+- `False` / `None` → skipped
+
+```python
+RunConfig(model="anthropic/claude", cli_kwargs={"fork": True, "title": "demo", "f": ["a.txt"]})
+# -> opencode run --format json -m anthropic/claude --fork --title=demo -f a.txt <prompt>
+```
+
+Prompt text is appended as the final `opencode run` message argument.
+`cli_kwargs` is ignored by `OpenCodeSession` (server mode has no CLI surface).
 
 ## Tests
 
@@ -205,7 +271,7 @@ The defaults already handle the common pitfalls when running many `async_run` ca
 
 To opt out: pass `startup_delay_s=0` (and a large `startup_concurrency`) to drop the startup pacing, `isolate_db=False` to share session history across runs, and `max_retries=0` to disable retries.
 
-> For **multi-turn conversations** you don't need `isolate_db=False`. Use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it keeps one session's DB alive across turns in a private dir, so context is preserved without sharing the global DB.
+> These notes apply to `async_run` / `async_stream` (run mode). For **multi-turn conversations** use [`OpenCodeSession`](#multi-turn-conversation-opencodesession) instead — it runs `opencode serve` and re-prompts one server-side session, so context is preserved natively with no shared-DB contention.
 
 ## Notes
 

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/opencode_wrapper/__init__.py

@@ -1,7 +1,12 @@
 """OpenCode CLI async wrapper for Python orchestration."""
 
 from opencode_wrapper.client import AsyncOpenCodeClient, build_argv, build_env, resolve_binary
-from opencode_wrapper.config import RunConfig, validate_config_for_run, validate_permission_actions
+from opencode_wrapper.config import (
+    RunConfig,
+    split_model,
+    validate_config_for_run,
+    validate_permission_actions,
+)
 from opencode_wrapper.errors import (
     OpenCodeBinaryNotFoundError,
     OpenCodeCancelledError,
@@ -13,23 +18,28 @@ from opencode_wrapper.events import (
     RunResult,
     TokenUsage,
     aggregate_run_result,
+    aggregate_server_result,
     parse_event_line,
     run_result_fuzzy_text,
 )
-from opencode_wrapper.session import OpenCodeSession
+from opencode_wrapper.session import OpenCodeSession, PermissionCallback, QuestionCallback
 
 __all__ = [
     "AsyncOpenCodeClient",
     "OpenCodeSession",
+    "PermissionCallback",
+    "QuestionCallback",
     "RunConfig",
     "RunResult",
     "TokenUsage",
     "aggregate_run_result",
+    "aggregate_server_result",
     "build_argv",
     "build_env",
     "parse_event_line",
     "run_result_fuzzy_text",
     "resolve_binary",
+    "split_model",
     "validate_config_for_run",
     "validate_permission_actions",
     "OpenCodeError",

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/opencode_wrapper/client.py

@@ -38,43 +38,34 @@ def build_argv(
     prompt: str,
     run_cfg: RunConfig,
 ) -> list[str]:
-    """Build ``opencode run`` argument list."""
+    """Build ``opencode run`` argument list.
+
+    ``model`` / ``agent`` are structured fields shared with server mode and map
+    to ``-m`` / ``--agent``.  Every other ``opencode run`` flag is passed through
+    ``run_cfg.cli_kwargs``: each entry expands to ``--flag`` (bool ``True``),
+    ``--flag=value`` (multi-char key) / ``-f value`` (single-char key), or a
+    repetition per element (list/tuple value).  ``False`` / ``None`` are skipped.
+    The argv list is handed to ``create_subprocess_exec`` (no shell), so values
+    are not subject to shell injection.
+    """
     cmd: list[str] = [binary_resolved, "run", "--format", "json"]
-
-    if run_cfg.print_logs:
-        cmd.append("--print-logs")
-    if run_cfg.log_level:
-        cmd.extend(["--log-level", run_cfg.log_level])
-    if run_cfg.command:
-        cmd.extend(["--command", run_cfg.command])
-    if run_cfg.continue_session:
-        cmd.append("--continue")
-    if run_cfg.session_id:
-        cmd.extend(["--session", run_cfg.session_id])
-    if run_cfg.fork:
-        cmd.append("--fork")
-    if run_cfg.share is True:
-        cmd.append("--share")
     if run_cfg.model:
         cmd.extend(["-m", run_cfg.model])
     if run_cfg.agent:
         cmd.extend(["--agent", run_cfg.agent])
-    for f in run_cfg.files:
-        cmd.extend(["-f", str(f)])
-    if run_cfg.title:
-        cmd.extend(["--title", run_cfg.title])
-    if run_cfg.attach:
-        cmd.extend(["--attach", run_cfg.attach])
-    if run_cfg.password:
-        cmd.extend(["-p", run_cfg.password])
-    if run_cfg.remote_dir:
-        cmd.extend(["--dir", run_cfg.remote_dir])
-    if run_cfg.port is not None:
-        cmd.extend(["--port", str(run_cfg.port)])
-    if run_cfg.variant:
-        cmd.extend(["--variant", run_cfg.variant])
-    if run_cfg.record_thinking is True or run_cfg.thinking is True:
-        cmd.append("--thinking")
+
+    for key, val in (run_cfg.cli_kwargs or {}).items():
+        flag = f"-{key}" if len(key) == 1 else f"--{key}"
+        vals = val if isinstance(val, (list, tuple)) else [val]
+        for v in vals:
+            if v is True:
+                cmd.append(flag)
+            elif v is False or v is None:
+                continue
+            elif len(key) == 1:
+                cmd.extend([flag, str(v)])
+            else:
+                cmd.append(f"{flag}={v}")
 
     if prompt:
         cmd.append(prompt)

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/opencode_wrapper/config.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Any, Dict, Mapping
 
 # Permission values accepted by OpenCode
@@ -131,29 +130,17 @@ def _deep_merge(base: dict[str, Any], override: Mapping[str, Any]) -> dict[str,
 
 @dataclass
 class RunConfig:
-    """Per-invocation settings merged into env and CLI."""
+    """Per-invocation settings merged into env and CLI.
 
+    Most fields are honored by both modes (run mode via CLI/env, server/session
+    mode via the prompt body/env).  ``cli_kwargs`` is the exception: it is a
+    raw passthrough of ``opencode run`` CLI flags and is **ignored by server/
+    session mode**, which has no CLI surface.
+    """
+
+    # --- honored by both modes ---
     agent: str | None = None
     model: str | None = None
-    files: tuple[str | Path, ...] = ()
-    title: str | None = None
-    command: str | None = None
-    continue_session: bool = False
-    session_id: str | None = None
-    fork: bool = False
-    share: bool | None = None
-    attach: str | None = None
-    password: str | None = None
-    remote_dir: str | None = None
-    port: int | None = None
-    variant: str | None = None
-    # Include OpenCode reasoning/thinking parts in the JSON event stream.
-    # This maps to `opencode run --thinking`; it does not set model reasoning effort.
-    record_thinking: bool | None = None
-    # Backward-compatible alias for record_thinking.
-    thinking: bool | None = None
-    print_logs: bool | None = None
-    log_level: str | None = None
     disable_autoupdate: bool = True
     inherit_user_config: bool = False
     extra_env: Mapping[str, str] | None = None
@@ -163,6 +150,16 @@ class RunConfig:
     tools: dict[str, Any] | None = None
     instructions: list[str] | None = None
     config_overrides: dict[str, Any] | None = None
+    # --- run mode only: passed through verbatim to `opencode run` as CLI flags;
+    # server/session mode ignores this entirely.
+    # e.g. {"title": "x", "continue": True, "session": "ses_1", "fork": True,
+    #       "thinking": True, "f": ["a.txt"]}
+    # build_argv expands each entry: bool True -> "--flag", a value -> "--flag=value"
+    # (long) or "-f value" (single-char), a list -> repeated, False/None -> skipped.
+    # Note: server mode has no --thinking equivalent; reasoning parts are produced
+    # per the model's reasoning config and published to the SSE bus unconditionally,
+    # so they already land in result.events / log_file with no opt-in.
+    cli_kwargs: dict[str, Any] | None = None
 
     def build_opencode_config_dict(self) -> dict[str, Any]:
         """Build the dict serialized to ``OPENCODE_CONFIG_CONTENT``."""
@@ -186,15 +183,32 @@ class RunConfig:
         return json.dumps(cfg, ensure_ascii=False)
 
 
-def validate_permission_actions(obj: Any, *, _path: str = "") -> None:
-    """Ensure string leaves are non-interactive OpenCode permission actions.
+def split_model(model: str) -> dict[str, str]:
+    """Split a ``"providerID/modelID"`` string into the server prompt-body shape.
+
+    opencode's server API wants ``{"providerID": ..., "modelID": ...}`` whereas
+    ``opencode run -m`` takes the ``provider/model`` string.  Only the first ``/``
+    separates provider from model (model ids may themselves contain ``/``).  A
+    string with no ``/`` is treated as a bare model id with an empty provider,
+    letting the server fall back to its default provider resolution.
+    """
+    provider, sep, rest = model.partition("/")
+    if not sep:
+        return {"providerID": "", "modelID": model}
+    return {"providerID": provider, "modelID": rest}
+
+
+def validate_permission_actions(obj: Any, *, _path: str = "", allow_ask: bool = False) -> None:
+    """Ensure string leaves are valid OpenCode permission actions.
 
-    ``"ask"`` is rejected because the subprocess has no terminal to prompt —
-    it would block forever.
+    ``"ask"`` is rejected by default because the run-mode subprocess has no
+    terminal to prompt — it would block forever.  The server/session path passes
+    ``allow_ask=True`` because there a ``permission.asked`` event is answerable via
+    the ``on_permission`` callback.
     """
-    allowed = frozenset({"allow", "deny"})
+    allowed = frozenset({"allow", "deny", "ask"} if allow_ask else {"allow", "deny"})
     if isinstance(obj, str):
-        if obj == "ask":
+        if obj == "ask" and not allow_ask:
             loc = f" at {_path!r}" if _path else ""
             raise ValueError(
                 f"Permission action 'ask' is not supported in non-interactive "
@@ -209,7 +223,7 @@ def validate_permission_actions(obj: Any, *, _path: str = "") -> None:
     if isinstance(obj, dict):
         for k, v in obj.items():
             child_path = f"{_path}.{k}" if _path else k
-            validate_permission_actions(v, _path=child_path)
+            validate_permission_actions(v, _path=child_path, allow_ask=allow_ask)
 
 
 def validate_config_for_run(cfg: RunConfig) -> None:

{py_opencode_wrapper-0.3.0 → py_opencode_wrapper-0.3.1}/opencode_wrapper/events.py

@@ -203,3 +203,121 @@ def aggregate_run_result(
     for ev in events:
         r.append_event(ev)
     return r
+
+
+# ---------------------------------------------------------------------------
+# Server-mode (opencode serve / SSE) aggregation
+#
+# Server event shapes differ from `opencode run --format json`:
+#   {"type": "message.part.updated",
+#    "properties": {"sessionID": "...", "part": {"type": "text"|"tool"|"reasoning",
+#                                                 "text": "...", "id": "prt_...", ...}}}
+#   {"type": "message.updated", "properties": {"info": {"role": "assistant",
+#                                                       "tokens": {...}, "cost": ...}}}
+# Run-mode parsing above is intentionally left untouched.
+# ---------------------------------------------------------------------------
+
+
+def _server_assistant_text_from_messages(messages: list[dict[str, Any]]) -> str:
+    """Extract the last assistant message's concatenated text parts.
+
+    ``GET /session/{id}/message`` returns ``[{info:{role,...}, parts:[...]}, ...]``.
+    The authoritative final answer is the text parts of the final assistant turn.
+    """
+    last = ""
+    for m in messages:
+        info = m.get("info") if isinstance(m, dict) else None
+        if not isinstance(info, dict) or info.get("role") != "assistant":
+            continue
+        parts = m.get("parts")
+        if not isinstance(parts, list):
+            continue
+        texts = [
+            p["text"]
+            for p in parts
+            if isinstance(p, dict) and p.get("type") == "text" and isinstance(p.get("text"), str)
+        ]
+        joined = "".join(texts).strip()
+        if joined:
+            last = joined
+    return last
+
+
+def _accumulate_token_usage(usage: TokenUsage, tokens: Any, cost_acc: list[float], info: dict) -> None:
+    cost = info.get("cost")
+    if isinstance(cost, (int, float)):
+        cost_acc[0] += float(cost)
+    if isinstance(tokens, dict):
+        for attr, key in (("total", "total"), ("input", "input"), ("output", "output"), ("reasoning", "reasoning")):
+            val = tokens.get(key)
+            if isinstance(val, (int, float)):
+                setattr(usage, attr, getattr(usage, attr) + int(val))
+        cache = tokens.get("cache")
+        if isinstance(cache, dict):
+            for attr, key in (("cache_read", "read"), ("cache_write", "write")):
+                val = cache.get(key)
+                if isinstance(val, (int, float)):
+                    setattr(usage, attr, getattr(usage, attr) + int(val))
+
+
+def aggregate_server_result(
+    *,
+    events: list[dict[str, Any]],
+    session_id: str | None,
+    final_messages: list[dict[str, Any]] | None = None,
+    exit_code: int | None = 0,
+    stderr: str = "",
+) -> RunResult:
+    """Build a :class:`RunResult` from a server-mode turn's SSE events.
+
+    ``events`` are the raw SSE event dicts collected during the turn.  When
+    ``final_messages`` (the ``GET /session/{id}/message`` payload) is supplied it
+    is treated as the authoritative source for final text and token/cost totals;
+    otherwise those are reconstructed from the streamed events.
+    """
+    r = RunResult(events=list(events), exit_code=exit_code, stderr=stderr, session_id=session_id)
+
+    # tool_calls + streamed text snapshots keyed by part id (parts are replaced,
+    # not appended, as they stream — keep the latest snapshot per id).
+    text_by_part: dict[str, str] = {}
+    text_order: list[str] = []
+    cost_acc = [0.0]
+    seen_assistant_msgs: set[str] = set()
+
+    for ev in events:
+        etype = ev.get("type")
+        props = ev.get("properties", {}) if isinstance(ev.get("properties"), dict) else {}
+        if etype in ("message.part.updated", "message.part.delta"):
+            part = props.get("part")
+            if not isinstance(part, dict):
+                continue
+            ptype = part.get("type")
+            pid = part.get("id") or ""
+            if ptype == "text" and isinstance(part.get("text"), str):
+                if pid not in text_by_part:
+                    text_order.append(pid)
+                text_by_part[pid] = part["text"]
+            elif ptype == "tool":
+                r.tool_calls.append({
+                    "type": "tool",
+                    "tool": part.get("tool"),
+                    "callID": part.get("callID"),
+                    "state": part.get("state"),
+                    "id": pid,
+                })
+        elif etype == "message.updated":
+            info = props.get("info")
+            if isinstance(info, dict) and info.get("role") == "assistant":
+                mid = info.get("id") or ""
+                if mid not in seen_assistant_msgs:
+                    seen_assistant_msgs.add(mid)
+                    r.turns += 1
+                _accumulate_token_usage(r.token_usage, info.get("tokens"), cost_acc, info)
+
+    r.total_cost = cost_acc[0]
+
+    if final_messages is not None:
+        r.final_text = _server_assistant_text_from_messages(final_messages)
+    if not r.final_text:
+        r.final_text = "".join(text_by_part[pid] for pid in text_order).strip()
+    return r