muse-code-sdk 1.4.13__tar.gz → 1.4.15__tar.gz

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muse-code-sdk
-Version: 1.4.13
+Version: 1.4.15
 Summary: Muse Code SDK for MSP: asyncio-first facade over the generated wire types (muse-code-msp), with a thin sync wrapper.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/meta-models/muse-code-sdk
@@ -15,7 +15,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic==2.13.5
-Requires-Dist: muse-code-msp==1.4.13
+Requires-Dist: muse-code-msp==1.4.15
 Dynamic: license-file
 
 # `muse-code-sdk`
@@ -61,29 +61,57 @@ path passed at spawn time.
 ```python
 import asyncio
 
-from muse_code import (
-    MuseClient, MuseClientSpawnOptions, SendUserTurnOptions, StartSessionOptions,
-)
+from muse_code import MuseClient, MuseClientSpawnOptions, StartSessionOptions
 
 async def main() -> None:
     client = await MuseClient.spawn(MuseClientSpawnOptions(
-        muse_bin="muse",
+        muse_bin=None,  # None finds `muse` on PATH; or pass a path
         args=["serve"],
         client_info={"name": "my-app", "version": "1.0.0"},
     ))
     session = await client.start_session(StartSessionOptions(workspace_root="."))
-    turn = await session.send_user_turn(SendUserTurnOptions(
-        input=[{"type": "text", "text": "Summarize this repository."}],
-        composer_input="Summarize this repository.",
-    ))
-    async for item in turn.items():
-        print(item)
-    await turn.completed
+    result = await session.run("Summarize this repository.")
+    print(result.final_text)
     await client.close()
 
 asyncio.run(main())
 ```
 
+`session.run` sends one turn and returns when the turn has ended, with the
+outcome, the final answer text, the turn's items, and its token usage. A turn
+that failed or was cancelled still returns; read `result.outcome` to tell. The
+final answer is the last completed agent message that is not commentary. Pass a
+list of input parts instead of a string, and turn options as keywords:
+`await session.run(parts, reasoning_effort="high")`.
+
+To stop it, cancel the task that awaits it, for example with
+`asyncio.timeout(60)` on Python 3.11 or newer. A turn still waiting in the
+queue is taken back, and a running turn is cancelled; `run` then waits for
+the turn to end and re-raises `CancelledError`. `SyncSession.run` is the
+blocking version, with no way to cancel.
+
+To follow a turn as it runs, send it yourself and read its items (paste
+inside `main()` above, before `await client.close()`; add
+`SendUserTurnOptions` to the import):
+
+```python
+turn = await session.send_user_turn(SendUserTurnOptions(
+    input=[{"type": "text", "text": "Summarize this repository."}],
+    composer_input="Summarize this repository.",
+))
+async for item in turn.items():
+    print(item)
+await turn.completed
+```
+
+To stop a running turn, `await turn.interrupt()` (the stop gesture; pass
+`retract=True` to also take the prompt back) or `await turn.cancel()`. Both are
+requests: the turn is over when `turn.completed` settles. `turn.steer(...)`
+adds input to the running turn, and `turn.unqueue()` takes back a queued one.
+The session itself can `fork`, `compact`, `rename`, and `leave`, and switch its
+model, reasoning effort, or approval mode (`set_model`, `set_reasoning_effort`,
+`set_approval_mode`); `client.list_models()` lists the models it accepts.
+
 To run a session and the child agents it starts without approval prompts,
 start it under the built-in `:unrestricted` permission profile. Current
 releases admit every child of such a session without prompts; a child admitted

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/README.md

@@ -41,29 +41,57 @@ path passed at spawn time.
 ```python
 import asyncio
 
-from muse_code import (
-    MuseClient, MuseClientSpawnOptions, SendUserTurnOptions, StartSessionOptions,
-)
+from muse_code import MuseClient, MuseClientSpawnOptions, StartSessionOptions
 
 async def main() -> None:
     client = await MuseClient.spawn(MuseClientSpawnOptions(
-        muse_bin="muse",
+        muse_bin=None,  # None finds `muse` on PATH; or pass a path
         args=["serve"],
         client_info={"name": "my-app", "version": "1.0.0"},
     ))
     session = await client.start_session(StartSessionOptions(workspace_root="."))
-    turn = await session.send_user_turn(SendUserTurnOptions(
-        input=[{"type": "text", "text": "Summarize this repository."}],
-        composer_input="Summarize this repository.",
-    ))
-    async for item in turn.items():
-        print(item)
-    await turn.completed
+    result = await session.run("Summarize this repository.")
+    print(result.final_text)
     await client.close()
 
 asyncio.run(main())
 ```
 
+`session.run` sends one turn and returns when the turn has ended, with the
+outcome, the final answer text, the turn's items, and its token usage. A turn
+that failed or was cancelled still returns; read `result.outcome` to tell. The
+final answer is the last completed agent message that is not commentary. Pass a
+list of input parts instead of a string, and turn options as keywords:
+`await session.run(parts, reasoning_effort="high")`.
+
+To stop it, cancel the task that awaits it, for example with
+`asyncio.timeout(60)` on Python 3.11 or newer. A turn still waiting in the
+queue is taken back, and a running turn is cancelled; `run` then waits for
+the turn to end and re-raises `CancelledError`. `SyncSession.run` is the
+blocking version, with no way to cancel.
+
+To follow a turn as it runs, send it yourself and read its items (paste
+inside `main()` above, before `await client.close()`; add
+`SendUserTurnOptions` to the import):
+
+```python
+turn = await session.send_user_turn(SendUserTurnOptions(
+    input=[{"type": "text", "text": "Summarize this repository."}],
+    composer_input="Summarize this repository.",
+))
+async for item in turn.items():
+    print(item)
+await turn.completed
+```
+
+To stop a running turn, `await turn.interrupt()` (the stop gesture; pass
+`retract=True` to also take the prompt back) or `await turn.cancel()`. Both are
+requests: the turn is over when `turn.completed` settles. `turn.steer(...)`
+adds input to the running turn, and `turn.unqueue()` takes back a queued one.
+The session itself can `fork`, `compact`, `rename`, and `leave`, and switch its
+model, reasoning effort, or approval mode (`set_model`, `set_reasoning_effort`,
+`set_approval_mode`); `client.list_models()` lists the models it accepts.
+
 To run a session and the child agents it starts without approval prompts,
 start it under the built-in `:unrestricted` permission profile. Current
 releases admit every child of such a session without prompts; a child admitted

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muse-code-sdk"
-version = "1.4.13"
+version = "1.4.15"
 description = "Muse Code SDK for MSP: asyncio-first facade over the generated wire types (muse-code-msp), with a thin sync wrapper."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -18,7 +18,7 @@ license-files = ["LICENSE"]
 # `pip install muse-code-sdk` must import, and the release bump moves this
 # package's version and its muse-code-msp pin together; pydantic bumps stay
 # reviewed PRs (test_publish_shape pins the pairing).
-dependencies = ["pydantic==2.13.5", "muse-code-msp==1.4.13"]
+dependencies = ["pydantic==2.13.5", "muse-code-msp==1.4.15"]
 classifiers = [
     # Alpha states the withheld promise: publication is permitted, but the
     # stability promise and conformance claim stay withheld — experimental

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/src/muse_code/__init__.py

@@ -19,10 +19,15 @@ from __future__ import annotations
 
 from typing import Final
 
+import muse_code_msp
+
 from .errors import (
     GapFillFailureReason,
+    MuseCapabilityNotGrantedError,
+    MuseFacadeOwnedMethodError,
     MuseForeignSessionError,
     MuseGapFillError,
+    MuseHostDiscoveryError,
     MuseSessionDiscardedError,
     PermissionProfileNotApplied,
 )
@@ -42,18 +47,22 @@ __all__ = [
     "HostDeathDischarge",
     "HostDeathNotification",
     "ItemStore",
+    "MuseCapabilityNotGrantedError",
     "MuseClient",
     "MuseClientOptions",
     "MuseClientSpawnOptions",
+    "MuseFacadeOwnedMethodError",
     "MuseForeignSessionError",
     "MuseGapFillError",
     "MuseHostDiedError",
+    "MuseHostDiscoveryError",
     "MuseHostStartError",
     "MuseSessionDiscardedError",
     "PendingCommandSet",
     "PendingCommandView",
     "PermissionProfileNotApplied",
     "ResumeSessionOptions",
+    "RunResult",
     "SendUserTurnOptions",
     "Session",
     "SessionApplyOutcome",
@@ -64,6 +73,7 @@ __all__ = [
     "SessionGapOverlap",
     "SessionStateStore",
     "StartSessionOptions",
+    "SteerTurnOptions",
     "SyncMuseClient",
     "SyncSession",
     "SyncTurn",
@@ -71,6 +81,7 @@ __all__ = [
     "TransportEof",
     "Turn",
     "TurnOutcome",
+    "TurnUnqueueOutcome",
     "is_abnormal_host_death",
     "is_launch_failure",
     "load_transcript",
@@ -79,20 +90,20 @@ __all__ = [
     "transcript_dirs",
 ]
 
-EXPECTED_SCHEMA_FINGERPRINT: Final[str] = (
-    "sha256:7fddaf646dbc317e5fcac0785e135eb04df14fbb0db1863089dfd6da21730e5b"
-)
+EXPECTED_SCHEMA_FINGERPRINT: Final[str] = muse_code_msp.SCHEMA_FINGERPRINT
 """The stable schema-bundle fingerprint this SDK was built against.
 
-The one deliberately duplicated fact: ``clients/sdk-py/tests/test_manifests.py`` binds it to
-``schema/msp/stable/manifest.json``, so a schema advance that forgets the
-Python SDK reds this lane instead of drifting silently.
+No second port and no second copy: this is the generated package's stable
+``SCHEMA_FINGERPRINT``, derived at import from the schema bytes. The
+manifests suite binds it to the value derived from the stable bundle, so a
+drift between the port the package vendors and the shared derivation reds
+that lane instead of passing silently.
 """
 
 # The lockstep rule: the release train bumps pyproject.toml, the
 # distribution-metadata authority; this constant is aligned at publication
 # time.
-__version__: Final[str] = "1.4.13"
+__version__: Final[str] = "1.4.15"
 
 # The facade is imported last so the constants above are already bound: the
 # spawn path reads ``EXPECTED_SCHEMA_FINGERPRINT`` (lazily, at initialize
@@ -114,6 +125,7 @@ from .facade import (  # noqa: E402
     MuseHostStartError,
     PendingCommandView,
     ResumeSessionOptions,
+    RunResult,
     SendUserTurnOptions,
     Session,
     SessionApplyOutcome,
@@ -122,9 +134,11 @@ from .facade import (  # noqa: E402
     SessionGapBuffered,
     SessionGapOverlap,
     StartSessionOptions,
+    SteerTurnOptions,
     TransportEof,
     Turn,
     TurnOutcome,
+    TurnUnqueueOutcome,
     is_abnormal_host_death,
     is_launch_failure,
     read_session_durability,

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/src/muse_code/connection/discovery.py

@@ -2,10 +2,11 @@
 
 The wheel carries no host binary and no code path assumes one. Exactly the
 two ruled tiers, first hit wins: an explicit ``muse_bin`` argument, then a
-``muse`` on ``PATH``. The LIBRARY reads no environment variable (TS parity:
-the TS spawn module takes a required command; ``MUSE_BIN`` is a knob of the
-quickstart/cookbook HARNESSES, which read it themselves and pass the
-explicit parameter down). No discoverable host fails BEFORE any process is
+``muse`` on ``PATH`` (the same two tiers as the TS and Rust SDKs, and what
+``MuseClient.spawn`` applies when ``muse_bin`` is ``None``). The LIBRARY reads
+no other environment variable: ``MUSE_BIN`` is a knob of the
+quickstart/cookbook HARNESSES, which read it themselves and pass the explicit
+parameter down. No discoverable host fails BEFORE any process is
 spawned, with an exact error naming the parameter and the compatibility
 page.
 """

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/src/muse_code/errors.py

@@ -115,6 +115,53 @@ class PermissionProfileNotApplied(Exception):
         self.session_id: str = session_id
 
 
+
+class MuseFacadeOwnedMethodError(Exception):
+    """``MuseClient.command`` was asked to send a method whose state the
+    facade owns. Sending it raw would bypass that state, so it is refused
+    before anything is written; use the facade verb instead.
+
+    Attributes:
+        method: The refused wire method.
+    """
+
+    def __init__(self, method: str) -> None:
+        """Builds the refusal.
+
+        Args:
+            method: The refused wire method.
+        """
+        super().__init__(
+            f"{method} is sent by the facade itself and cannot go through "
+            "MuseClient.command; use the facade verb that owns it"
+        )
+        self.method: str = method
+
+
+class MuseCapabilityNotGrantedError(Exception):
+    """A session open asked for something the host did not grant on this
+    connection: today, per-session MCP servers (``config["mcpServers"]``)
+    without the ``sessionMcp`` capability. Refused before anything is sent;
+    the client stays usable, and an open without that request still goes
+    through.
+
+    Attributes:
+        capability: The capability the request needs.
+        method: The wire method that was refused.
+    """
+
+    def __init__(self, capability: str, method: str, reason: str) -> None:
+        """Builds the refusal.
+
+        Args:
+            capability: The capability the request needs.
+            method: The wire method that was refused.
+            reason: Why the grant is missing.
+        """
+        super().__init__(f"{method} was not sent: {reason}")
+        self.capability: str = capability
+        self.method: str = method
+
 ValidationSeam = Literal["initializeResult", "spawnOptions"]
 """Which validating pydantic seam refused its input.
 
@@ -207,9 +254,9 @@ class MuseHostMismatchError(Exception):
             pinned: ``muse_code.EXPECTED_SCHEMA_FINGERPRINT``.
             host_version: ``serverInfo.version`` from the handshake result.
             required_host_version: The generated
-                ``muse_code_msp.REQUIRED_HOST_VERSION`` — tree-derived by the
-                renderer from the host crate's manifest and kept honest by
-                the regen gate, never hand-typed.
+                ``muse_code_msp.REQUIRED_HOST_VERSION`` — derived at import
+                through the vendored resolver and kept honest by the regen
+                gate, never hand-typed.
                 Required, not defaulted: the contract names the exact version, so
                 a version-less message is not a state this error can carry.
         """

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/src/muse_code/facade/__init__.py

@@ -50,8 +50,9 @@ from .session import (
     SessionGapOverlap,
     SessionOpening,
 )
-from .turn_handle import FoldedItem, Turn, TurnOutcome, is_launch_failure
-from .turn_submit import SendUserTurnOptions
+from .run import RunResult
+from .turn_handle import FoldedItem, Turn, TurnOutcome, TurnUnqueueOutcome, is_launch_failure
+from .turn_submit import SendUserTurnOptions, SteerTurnOptions
 
 __all__ = [
     "AbnormalExit",
@@ -71,6 +72,7 @@ __all__ = [
     "MuseHostStartError",
     "PendingCommandView",
     "ResumeSessionOptions",
+    "RunResult",
     "SendUserTurnOptions",
     "Session",
     "SessionApplyOutcome",
@@ -81,9 +83,11 @@ __all__ = [
     "SessionGapOverlap",
     "SessionOpening",
     "StartSessionOptions",
+    "SteerTurnOptions",
     "TransportEof",
     "Turn",
     "TurnOutcome",
+    "TurnUnqueueOutcome",
     "is_abnormal_host_death",
     "is_launch_failure",
     "read_session_durability",

{muse_code_sdk-1.4.13 → muse_code_sdk-1.4.15}/src/muse_code/facade/approval.py

@@ -66,6 +66,7 @@ _REFRESH_FROM_REQUEST = frozenset(
         "judgeEscalated",
         "protectedWrite",
         "rawArgs",
+        "reviewerReason",
         "taskId",
         "toolCallId",
         "toolName",
@@ -302,6 +303,10 @@ class ApprovalRouter:
         # the retained request across stages.
         if "cuaCardFacts" in requested:
             refreshed["cuaCardFacts"] = requested["cuaCardFacts"]
+        # The escalation reason belongs to the call, so it stays with the
+        # retained request across stages.
+        if "reviewerReason" in requested:
+            refreshed["reviewerReason"] = requested["reviewerReason"]
         acked = self._in_flight.get(requested["approvalId"])
         if acked is not None:
             return self._after_ack(acked, refreshed)