opencode-python-sdk 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

opencode/lib/_session.py

@@ -0,0 +1,231 @@
+"""``client.session.run``: create or reuse a session, prompt it, wait until idle, and collect the result.
+
+The generated ``SessionResource`` / ``AsyncSessionResource`` inherit from the classes here (see
+``codegen/render.py``, ``HELPER_BASES``), so these methods sit next to the generated ones.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, cast
+
+import anyio
+
+from .._resource import AsyncAPIResource, SyncAPIResource
+from .._types import NOT_GIVEN, NotGiven, Timeout
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from ..resources.session import AsyncSessionResource, SessionResource
+    from ..types import (
+        AgentID,
+        ModelRef,
+        PromptInputFileAttachment,
+        SessionID,
+        SessionInfo,
+        SessionMessageAssistant,
+        SessionMessageInfo,
+        SessionStructuredError,
+        TokenUsageInfo,
+    )
+
+__all__ = ["AsyncSessionHelpers", "RunResult", "SessionHelpers"]
+
+
+@dataclass
+class RunResult:
+    """What :meth:`SessionHelpers.run` returns."""
+
+    session: SessionInfo
+    """The session as it was after the run. ``session.cost`` and ``session.tokens`` cover the whole session."""
+    messages: list[SessionMessageInfo] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    """Messages this run added, oldest first, starting with the prompt."""
+
+    @property
+    def assistant_messages(self) -> list[SessionMessageAssistant]:
+        """The assistant messages of this run, oldest first."""
+        from ..types import SessionMessageAssistant
+
+        return [message for message in self.messages if isinstance(message, SessionMessageAssistant)]
+
+    @property
+    def text(self) -> str:
+        """Text of the last assistant message, or ``""`` when the agent produced none."""
+        from ..types import SessionMessageAssistantText
+
+        for message in reversed(self.assistant_messages):
+            parts = [item.text for item in message.content if isinstance(item, SessionMessageAssistantText)]
+            if parts:
+                return "".join(parts)
+        return ""
+
+    @property
+    def outcome(self) -> str | None:
+        """``succeeded``, ``failed`` or ``interrupted``, from the run's idle marker or the session."""
+        from ..types import SessionMessageIdle
+
+        for message in reversed(self.messages):
+            if isinstance(message, SessionMessageIdle):
+                return message.outcome
+        return self.session.outcome
+
+    @property
+    def error(self) -> SessionStructuredError | None:
+        """Why the run failed, from its idle marker or last assistant message, or ``None``."""
+        from ..types import SessionMessageAssistant, SessionMessageIdle
+
+        for message in reversed(self.messages):
+            if isinstance(message, (SessionMessageIdle, SessionMessageAssistant)) and message.error is not None:
+                return message.error
+        return None
+
+    @property
+    def cost(self) -> float:
+        """Cost of this run in USD, summed over its assistant messages."""
+        return sum(message.cost or 0.0 for message in self.assistant_messages)
+
+    @property
+    def tokens(self) -> TokenUsageInfo:
+        """Token usage of this run, summed over its assistant messages."""
+        from ..types import TokenUsageInfo, TokenUsageInfoCache
+
+        total = TokenUsageInfo(input=0, output=0, reasoning=0, cache=TokenUsageInfoCache(read=0, write=0))
+        for message in self.assistant_messages:
+            usage = message.tokens
+            if usage is None:
+                continue
+            total.input += usage.input
+            total.output += usage.output
+            total.reasoning += usage.reasoning
+            total.cache.read += usage.cache.read
+            total.cache.write += usage.cache.write
+        return total
+
+
+def _new_messages(newest_first: list[SessionMessageInfo], marker: str | None) -> list[SessionMessageInfo]:
+    from ..types import SessionMessageUser
+
+    collected: list[SessionMessageInfo] = []
+    for message in newest_first:
+        if marker is not None and message.id == marker:
+            break
+        collected.append(message)
+    collected.reverse()
+    # Drop anything that was already queued before our prompt.
+    for index, message in enumerate(collected):
+        if isinstance(message, SessionMessageUser):
+            return collected[index:]
+    return collected
+
+
+class SessionHelpers(SyncAPIResource):
+    """Hand-written helpers on ``client.session``."""
+
+    def run(
+        self,
+        text: str,
+        *,
+        agent: AgentID | None = None,
+        model: ModelRef | None = None,
+        files: Sequence[PromptInputFileAttachment] | NotGiven = NOT_GIVEN,
+        session_id: SessionID | None = None,
+        timeout: Timeout = None,
+    ) -> RunResult:
+        """Runs one prompt to completion and returns what the agent produced.
+
+        Creates a session with ``agent`` and ``model`` (or reuses ``session_id``, switching its agent and model when
+        given), sends ``text``, blocks until the session is idle, and reads back the new messages and the session's
+        usage.
+
+        If the wait is interrupted (``KeyboardInterrupt``, a timeout, or any other error), the session is
+        interrupted on the server before the error propagates, so no agent keeps running unattended.
+
+        Args:
+          text: The prompt.
+          agent: Agent for a new session, or to switch an existing one to.
+          model: Model for a new session, or to switch an existing one to. Set it with ``agent`` so the session
+            does not start on another model.
+          files: File attachments; images can be ``data:`` URLs.
+          session_id: Continue this session instead of creating one.
+          timeout: Seconds to wait for the session to become idle. ``None`` waits forever.
+
+        Example::
+
+            result = client.session.run("Summarize README.md", agent="build")
+            print(result.text, result.cost)
+        """
+        resource = cast("SessionResource", self)
+        if session_id is None:
+            session = resource.create(agent=agent or NOT_GIVEN, model=model or NOT_GIVEN)
+            session_id = session.id
+            marker = None
+        else:
+            if agent is not None:
+                resource.switch_agent(session_id, agent=agent)
+            if model is not None:
+                resource.switch_model(session_id, model=model)
+            latest = self._client.message.list(session_id, order="desc", limit=1).data
+            marker = latest[0].id if latest else None
+
+        resource.prompt(session_id, text=text, files=files)
+        try:
+            resource.wait(session_id, timeout=timeout)
+        except BaseException:
+            with contextlib.suppress(Exception):
+                resource.interrupt(session_id)
+            raise
+
+        newest_first: list[SessionMessageInfo] = []
+        for message in self._client.message.list(session_id, order="desc"):
+            if marker is not None and message.id == marker:
+                break
+            newest_first.append(message)
+        return RunResult(session=resource.get(session_id), messages=_new_messages(newest_first, marker))
+
+
+class AsyncSessionHelpers(AsyncAPIResource):
+    """Hand-written helpers on ``client.session`` of :class:`opencode.AsyncOpencode`."""
+
+    async def run(
+        self,
+        text: str,
+        *,
+        agent: AgentID | None = None,
+        model: ModelRef | None = None,
+        files: Sequence[PromptInputFileAttachment] | NotGiven = NOT_GIVEN,
+        session_id: SessionID | None = None,
+        timeout: Timeout = None,
+    ) -> RunResult:
+        """Runs one prompt to completion. See :meth:`SessionHelpers.run`.
+
+        Cancelling the task interrupts the session on the server before the cancellation propagates.
+        """
+        resource = cast("AsyncSessionResource", self)
+        if session_id is None:
+            session = await resource.create(agent=agent or NOT_GIVEN, model=model or NOT_GIVEN)
+            session_id = session.id
+            marker = None
+        else:
+            if agent is not None:
+                await resource.switch_agent(session_id, agent=agent)
+            if model is not None:
+                await resource.switch_model(session_id, model=model)
+            latest = (await self._client.message.list(session_id, order="desc", limit=1)).data
+            marker = latest[0].id if latest else None
+
+        await resource.prompt(session_id, text=text, files=files)
+        try:
+            await resource.wait(session_id, timeout=timeout)
+        except BaseException:
+            with anyio.CancelScope(shield=True), contextlib.suppress(Exception):
+                await resource.interrupt(session_id)
+            raise
+
+        newest_first: list[SessionMessageInfo] = []
+        async for message in self._client.message.list(session_id, order="desc"):
+            if marker is not None and message.id == marker:
+                break
+            newest_first.append(message)
+        return RunResult(session=await resource.get(session_id), messages=_new_messages(newest_first, marker))

opencode/resources/agent.py

@@ -5,18 +5,20 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._qs import encode_path_segment
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    AgentGetResponse,
-    AgentID,
-    AgentListResponse,
-    Location,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        AgentGetResponse,
+        AgentID,
+        AgentListResponse,
+        Location,
+    )
 
 __all__ = ["AgentResource", "AsyncAgentResource"]
 
@@ -56,7 +58,7 @@ class AgentResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentListResponse,
+                response_type="AgentListResponse",
             ),
         )
 
@@ -94,7 +96,7 @@ class AgentResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentGetResponse,
+                response_type="AgentGetResponse",
             ),
         )
 
@@ -134,7 +136,7 @@ class AsyncAgentResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentListResponse,
+                response_type="AgentListResponse",
             ),
         )
 
@@ -172,6 +174,6 @@ class AsyncAgentResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentGetResponse,
+                response_type="AgentGetResponse",
             ),
         )

opencode/resources/command.py

@@ -5,15 +5,17 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    CommandListResponse,
-    Location,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        CommandListResponse,
+        Location,
+    )
 
 __all__ = ["CommandResource", "AsyncCommandResource"]
 
@@ -53,7 +55,7 @@ class CommandResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CommandListResponse,
+                response_type="CommandListResponse",
             ),
         )
 
@@ -93,6 +95,6 @@ class AsyncCommandResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CommandListResponse,
+                response_type="CommandListResponse",
             ),
         )

opencode/resources/config.py

@@ -6,16 +6,18 @@
 from __future__ import annotations
 
 import builtins
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    ConfigEntry,
-    ConfigShellOption,
-    Location,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        ConfigEntry,
+        ConfigShellOption,
+        Location,
+    )
 
 __all__ = ["ConfigResource", "AsyncConfigResource"]
 
@@ -55,7 +57,7 @@ class ConfigResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[ConfigEntry],
+                response_type="builtins.list[ConfigEntry]",
             ),
         )
 
@@ -89,7 +91,7 @@ class ConfigResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[ConfigShellOption],
+                response_type="builtins.list[ConfigShellOption]",
             ),
         )
 
@@ -164,7 +166,7 @@ class AsyncConfigResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[ConfigEntry],
+                response_type="builtins.list[ConfigEntry]",
             ),
         )
 
@@ -198,7 +200,7 @@ class AsyncConfigResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[ConfigShellOption],
+                response_type="builtins.list[ConfigShellOption]",
             ),
         )
 

opencode/resources/credential.py

@@ -6,18 +6,20 @@
 from __future__ import annotations
 
 import builtins
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._qs import encode_path_segment
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    CredentialEntry,
-    CredentialID,
-    CredentialValue,
-    IntegrationID,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        CredentialEntry,
+        CredentialID,
+        CredentialValue,
+        IntegrationID,
+    )
 
 __all__ = ["CredentialResource", "AsyncCredentialResource"]
 
@@ -54,7 +56,7 @@ class CredentialResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[CredentialEntry],
+                response_type="builtins.list[CredentialEntry]",
                 unwrap=True,
             ),
         )
@@ -101,7 +103,7 @@ class CredentialResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CredentialEntry,
+                response_type="CredentialEntry",
                 unwrap=True,
             ),
         )
@@ -234,7 +236,7 @@ class AsyncCredentialResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[CredentialEntry],
+                response_type="builtins.list[CredentialEntry]",
                 unwrap=True,
             ),
         )
@@ -281,7 +283,7 @@ class AsyncCredentialResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CredentialEntry,
+                response_type="CredentialEntry",
                 unwrap=True,
             ),
         )

opencode/resources/debug.py

@@ -7,15 +7,17 @@ from __future__ import annotations
 
 import builtins
 from functools import cached_property
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    Location,
-    LocationPublicRef,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        Location,
+        LocationPublicRef,
+    )
 
 __all__ = ["DebugResource", "AsyncDebugResource"]
 
@@ -52,7 +54,7 @@ class DebugLocationResource(SyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[LocationPublicRef],
+                response_type="builtins.list[LocationPublicRef]",
             ),
         )
 
@@ -130,7 +132,7 @@ class AsyncDebugLocationResource(AsyncAPIResource):
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=builtins.list[LocationPublicRef],
+                response_type="builtins.list[LocationPublicRef]",
             ),
         )
 

opencode/resources/event.py

@@ -5,13 +5,17 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from .._base_client import RequestOptions
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._streaming import AsyncStream, Stream
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    Event,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        Event,
+    )
 
 __all__ = ["EventResource", "AsyncEventResource"]
 
@@ -46,7 +50,7 @@ class EventResource(SyncAPIResource):
                 extra_body=extra_body,
                 timeout=timeout,
             ),
-            item_type=Event,
+            item_type="Event",
         )
 
 
@@ -80,5 +84,5 @@ class AsyncEventResource(AsyncAPIResource):
                 extra_body=extra_body,
                 timeout=timeout,
             ),
-            item_type=Event,
+            item_type="Event",
         )