muse-code-sdk 1.4.14__tar.gz → 1.4.20__tar.gz

{muse_code_sdk-1.4.14/src/muse_code_sdk.egg-info → muse_code_sdk-1.4.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muse-code-sdk
-Version: 1.4.14
+Version: 1.4.20
 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.14
+Requires-Dist: muse-code-msp==1.4.20
 Dynamic: license-file
 
 # `muse-code-sdk`
@@ -28,6 +28,8 @@ wrapper for scripts and notebooks.
   one you already run.
 - Stream a turn's items and text deltas as async iterators; await the turn's
   server-authored outcome.
+- Stream what each incoming event changed in a session with
+  `session.events()`, to update a view incrementally.
 - Answer tool-approval requests with a handler you register, or pass it as
   `ResumeSessionOptions(on_approval=...)`, with `on_approval_error=...` for
   its failures, so approvals still pending at resume reach it.
@@ -37,6 +39,9 @@ wrapper for scripts and notebooks.
 - A client-side fold keeps a live, typed view of the session — items, session
   state, pending commands — with gap recovery after reconnects, and safe
   same-command retry that can never double-submit.
+- Observe the connection itself: every notification the host sends (including
+  ones that name no session, such as `usage/changed`), messages the SDK
+  rejects as malformed, and the connection closing.
 - `SyncMuseClient` mirrors the same surface with blocking verbs.
 
 Status: developer preview. Experimental protocol surfaces may change.
@@ -61,29 +66,80 @@ 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 render incrementally, read `session.events()`: every event the session
+folds from then on, with what it changed. Read the current state first, then
+subscribe before the next `await`, and nothing is missed, including the events
+that arrived before `start_session` or `resume_session` returned:
+
+```python
+import contextlib
+
+render_all(session.fold)  # the state so far
+async with contextlib.aclosing(session.events()) as events:
+    async for event in events:
+        # `event.item` is the item as of this event; `session.fold` may be ahead.
+        render(event.frame["method"], event.outcome.fold, event.item)
+```
+
+Each event arrives once, in order, including events the SDK fetches to fill a
+gap in delivery. `aclosing` stops listening when the loop ends or breaks (or
+call `aclose()`). The stream ends when an ephemeral host dies and raises
+`MuseHostDiedError` when a durable one does, as `turn.items()` does. Reading
+it changes nothing else: `turn.unqueue()` still returns the queued input it
+takes back, and that input is not repeated on an event. `SyncSession.events()`
+is the blocking version: `for event in session.events(): ...`.
+
 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
@@ -125,6 +181,30 @@ mode, but its child agents are capped by the session's permission profile.
 Under a prompting profile (such as `:ask-me`, whose approval is `on_request`),
 the children still ask.
 
+## Observe the connection
+
+The client routes each event to its session, and also lets you listen to the
+raw feed. Each `on_*` call returns a function that removes that one listener:
+
+```python
+unsubscribe = client.on_notification(
+    lambda notification: print(notification["method"], notification.get("params"))
+)
+client.on_notification_error(lambda error, notification: print("listener failed:", error))
+client.on_protocol_error(lambda error: print("rejected frame:", error.line))
+await client.closed  # resolves when the connection closes, for any reason
+unsubscribe()
+```
+
+A notification for a session you opened reaches your listener after the
+session has applied it, except during a gap fill (the event is folded when
+the fill completes) or while `start_session`/`resume_session` is still running
+(it is folded before the call returns). Listeners run as frames are read, so keep them quick;
+an `async def` listener runs as a task. An exception from a listener goes to
+`on_notification_error` and never disconnects the client. `SyncMuseClient`
+has the same three `on_*` methods (listeners run while a blocking call is in
+progress) and `wait_closed()` in place of `closed`.
+
 ## Documentation
 
 - Guides, cookbook recipes, and the protocol reference:

muse_code_sdk-1.4.20/README.md

@@ -0,0 +1,194 @@
+# `muse-code-sdk`
+
+The Python SDK for Muse Code: an asyncio-first client for driving a Muse
+Code agent over the Muse Session Protocol (MSP), with a thin synchronous
+wrapper for scripts and notebooks.
+
+- Open and resume sessions against a spawned `muse serve` host, or attach to
+  one you already run.
+- Stream a turn's items and text deltas as async iterators; await the turn's
+  server-authored outcome.
+- Stream what each incoming event changed in a session with
+  `session.events()`, to update a view incrementally.
+- Answer tool-approval requests with a handler you register, or pass it as
+  `ResumeSessionOptions(on_approval=...)`, with `on_approval_error=...` for
+  its failures, so approvals still pending at resume reach it.
+- Answer the agent's questions: list them with
+  `session.fold.pending_user_inputs()` and answer with
+  `session.answer_user_input`.
+- A client-side fold keeps a live, typed view of the session — items, session
+  state, pending commands — with gap recovery after reconnects, and safe
+  same-command retry that can never double-submit.
+- Observe the connection itself: every notification the host sends (including
+  ones that name no session, such as `usage/changed`), messages the SDK
+  rejects as malformed, and the connection closing.
+- `SyncMuseClient` mirrors the same surface with blocking verbs.
+
+Status: developer preview. Experimental protocol surfaces may change.
+
+The generated MSP wire types live in the companion package
+[`muse-code-msp`](https://pypi.org/project/muse-code-msp/) and are never
+restated here; it is installed with this package, pinned to the same version.
+One further runtime dependency: `pydantic`, exact-pinned.
+Python 3.10+. Fully typed (`py.typed`).
+
+## Install
+
+```sh
+pip install muse-code-sdk
+```
+
+You also need the Muse Code CLI: a `muse` binary on `PATH`, or an explicit
+path passed at spawn time.
+
+## Use
+
+```python
+import asyncio
+
+from muse_code import MuseClient, MuseClientSpawnOptions, StartSessionOptions
+
+async def main() -> None:
+    client = await MuseClient.spawn(MuseClientSpawnOptions(
+        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="."))
+    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 render incrementally, read `session.events()`: every event the session
+folds from then on, with what it changed. Read the current state first, then
+subscribe before the next `await`, and nothing is missed, including the events
+that arrived before `start_session` or `resume_session` returned:
+
+```python
+import contextlib
+
+render_all(session.fold)  # the state so far
+async with contextlib.aclosing(session.events()) as events:
+    async for event in events:
+        # `event.item` is the item as of this event; `session.fold` may be ahead.
+        render(event.frame["method"], event.outcome.fold, event.item)
+```
+
+Each event arrives once, in order, including events the SDK fetches to fill a
+gap in delivery. `aclosing` stops listening when the loop ends or breaks (or
+call `aclose()`). The stream ends when an ephemeral host dies and raises
+`MuseHostDiedError` when a durable one does, as `turn.items()` does. Reading
+it changes nothing else: `turn.unqueue()` still returns the queued input it
+takes back, and that input is not repeated on an event. `SyncSession.events()`
+is the blocking version: `for event in session.events(): ...`.
+
+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
+with a narrower authority would stay gated at it.
+
+That profile is described, verbatim, as "No filesystem sandbox or approval
+prompts; local commands have direct network access; project trust is
+unchanged." It also sets the approval reviewer to none. Use it only for a
+trusted workspace and trusted prompts. Never use it where the prompts or the
+sandbox are what protects you.
+
+Start it with that profile, and pass the same profile when you resume it.
+Paste inside `main()` above, indented, before `await client.close()`, with the same client:
+
+```python
+from muse_code import ResumeSessionOptions, StartSessionOptions
+
+session = await client.start_session(StartSessionOptions(
+    workspace_root="/path/to/repo",  # an absolute path
+    permission_profile=":unrestricted",
+))
+saved_session_id = session.session_id
+# ... later, in the same client:
+session = await client.resume_session(ResumeSessionOptions(
+    session_id=saved_session_id,
+    permission_profile=":unrestricted",
+))
+```
+
+On start, `require_permission_profile=True` makes the client prove that the
+pick was applied, and raise `PermissionProfileNotApplied` if it cannot (a
+failed `session/read` read-back raises its own error). A host
+that does not report the committed selection fails that proof even when the
+pick was applied (seen with Muse Code 1.4.12). Resume has no
+`require_permission_profile`, so the client never verifies the pick there.
+
+`approval_mode` alone is not enough: it changes the session's own approval
+mode, but its child agents are capped by the session's permission profile.
+Under a prompting profile (such as `:ask-me`, whose approval is `on_request`),
+the children still ask.
+
+## Observe the connection
+
+The client routes each event to its session, and also lets you listen to the
+raw feed. Each `on_*` call returns a function that removes that one listener:
+
+```python
+unsubscribe = client.on_notification(
+    lambda notification: print(notification["method"], notification.get("params"))
+)
+client.on_notification_error(lambda error, notification: print("listener failed:", error))
+client.on_protocol_error(lambda error: print("rejected frame:", error.line))
+await client.closed  # resolves when the connection closes, for any reason
+unsubscribe()
+```
+
+A notification for a session you opened reaches your listener after the
+session has applied it, except during a gap fill (the event is folded when
+the fill completes) or while `start_session`/`resume_session` is still running
+(it is folded before the call returns). Listeners run as frames are read, so keep them quick;
+an `async def` listener runs as a task. An exception from a listener goes to
+`on_notification_error` and never disconnects the client. `SyncMuseClient`
+has the same three `on_*` methods (listeners run while a blocking call is in
+progress) and `wait_closed()` in place of `closed`.
+
+## Documentation
+
+- Guides, cookbook recipes, and the protocol reference:
+  <https://meta-models.github.io/muse-code-sdk/>
+- Python API reference:
+  <https://meta-models.github.io/muse-code-sdk/next/generated/python/>
+- Source and issues: <https://github.com/meta-models/muse-code-sdk>

{muse_code_sdk-1.4.14 → muse_code_sdk-1.4.20}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muse-code-sdk"
-version = "1.4.14"
+version = "1.4.20"
 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.14"]
+dependencies = ["pydantic==2.13.5", "muse-code-msp==1.4.20"]
 classifiers = [
     # Alpha states the withheld promise: publication is permitted, but the
     # stability promise and conformance claim stay withheld — experimental

{muse_code_sdk-1.4.14 → muse_code_sdk-1.4.20}/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,28 +47,37 @@ __all__ = [
     "HostDeathDischarge",
     "HostDeathNotification",
     "ItemStore",
+    "MuseCapabilityNotGrantedError",
     "MuseClient",
     "MuseClientOptions",
     "MuseClientSpawnOptions",
+    "MuseFacadeOwnedMethodError",
     "MuseForeignSessionError",
     "MuseGapFillError",
     "MuseHostDiedError",
+    "MuseHostDiscoveryError",
     "MuseHostStartError",
     "MuseSessionDiscardedError",
+    "NotificationFailureHandler",
+    "NotificationObserver",
     "PendingCommandSet",
     "PendingCommandView",
     "PermissionProfileNotApplied",
+    "ProtocolErrorObserver",
     "ResumeSessionOptions",
+    "RunResult",
     "SendUserTurnOptions",
     "Session",
     "SessionApplyOutcome",
     "SessionDurabilityProfile",
+    "SessionEvent",
     "SessionFold",
     "SessionFoldView",
     "SessionGapBuffered",
     "SessionGapOverlap",
     "SessionStateStore",
     "StartSessionOptions",
+    "SteerTurnOptions",
     "SyncMuseClient",
     "SyncSession",
     "SyncTurn",
@@ -71,6 +85,8 @@ __all__ = [
     "TransportEof",
     "Turn",
     "TurnOutcome",
+    "TurnUnqueueOutcome",
+    "ViewFrame",
     "is_abnormal_host_death",
     "is_launch_failure",
     "load_transcript",
@@ -79,20 +95,20 @@ __all__ = [
     "transcript_dirs",
 ]
 
-EXPECTED_SCHEMA_FINGERPRINT: Final[str] = (
-    "sha256:c94c3d1f2f51e6424074b9ec43eac3eedcf532d3dcd77351ec1383a87d3049c6"
-)
+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.14"
+__version__: Final[str] = "1.4.20"
 
 # The facade is imported last so the constants above are already bound: the
 # spawn path reads ``EXPECTED_SCHEMA_FINGERPRINT`` (lazily, at initialize
@@ -112,19 +128,27 @@ from .facade import (  # noqa: E402
     MuseClientSpawnOptions,
     MuseHostDiedError,
     MuseHostStartError,
+    NotificationFailureHandler,
+    NotificationObserver,
     PendingCommandView,
+    ProtocolErrorObserver,
     ResumeSessionOptions,
+    RunResult,
     SendUserTurnOptions,
     Session,
     SessionApplyOutcome,
     SessionDurabilityProfile,
+    SessionEvent,
     SessionFoldView,
     SessionGapBuffered,
     SessionGapOverlap,
     StartSessionOptions,
+    SteerTurnOptions,
     TransportEof,
     Turn,
     TurnOutcome,
+    TurnUnqueueOutcome,
+    ViewFrame,
     is_abnormal_host_death,
     is_launch_failure,
     read_session_durability,

{muse_code_sdk-1.4.14 → muse_code_sdk-1.4.20}/src/muse_code/connection/connection.py

@@ -101,6 +101,11 @@ class MspError(Exception):
 class ProtocolError(Exception):
     """A local framing/correlation violation, never a server-authored error.
 
+    When a call fails because a host ``MuseClient.spawn`` started died, the
+    error it raises (usually this class; the transport's own error when a
+    write failed) has a ``MuseHostDiedError`` ``__cause__`` saying how the
+    host ended, so check ``__cause__`` alone.
+
     Attributes:
         line: The offending inbound line, preserved as evidence and bounded
             in UTF-8 bytes, when one exists.
@@ -296,6 +301,10 @@ class Connection:
         self._buffer_bytes = 0
         self._dropping_oversized = False
         self._finished = False
+        self._read_peer_end_cause: (
+            Callable[[], asyncio.Future[BaseException | None] | None] | None
+        ) = None
+        self._end_cause: asyncio.Future[BaseException | None] | None = None
         self._closed: asyncio.Future[None] = self._loop.create_future()
         self._read_task = self._loop.create_task(self._read_loop())
 
@@ -324,6 +333,22 @@ class Connection:
         """
         return self._submit_tail
 
+    def _peer_end_cause(
+        self, read: Callable[[], asyncio.Future[BaseException | None] | None]
+    ) -> None:
+        """Friend seam: lets the owner of the peer process say, once when the
+        connection finishes, why the peer is gone.
+
+        Module-private, like the TS twin's Symbol fence. A future ``read``
+        returns settles (never with an exception) with the ``__cause__`` given
+        to every call the connection then fails; ``None`` keeps the bare error
+        and its timing.
+        """
+        self._read_peer_end_cause = read
+        # The host can die between the handshake and this registration.
+        if self._finished and self._end_cause is None:
+            self._end_cause = read()
+
     def mint_command_id(self) -> str:
         """Takes one id from THIS connection's single command-id minter.
 
@@ -352,7 +377,7 @@ class Connection:
         """
         outcome: asyncio.Future[Params] = self._loop.create_future()
         if self._finished:
-            outcome.set_exception(ProtocolError("connection is closed"))
+            self._fail_with_end_cause(outcome, ProtocolError("connection is closed"))
             return outcome
         request_id = self._mint_request_id()
         if not _valid_request_id(request_id):
@@ -376,8 +401,7 @@ class Connection:
             error = done.exception()
             if error is not None:
                 self._pending.pop(key, None)
-                if not outcome.done():
-                    outcome.set_exception(error)
+                self._fail_with_end_cause(outcome, error)
 
         write_outcome.add_done_callback(on_write_done)
         return outcome
@@ -440,7 +464,8 @@ class Connection:
         """Sends one logical command with the same-``commandId`` retry contract.
 
         Same-id retries on the retryable pair (``backpressured`` /
-        ``overloaded``) with the bounded full-jitter budget; a value-identical
+        ``overloaded``) with the bounded full-jitter budget, unless the error
+        carries an explicit ``retryable: false``; a value-identical
         ack settles a replay; ``inputTooLarge`` (and every other error) is
         never auto-retried.
 
@@ -529,9 +554,12 @@ class Connection:
                 remembered.ack = dict(ack)
                 return ack
             except MspError as error:
-                retryable_nothing_admitted = (
-                    error.code == -32001 and error.kind == "overloaded"
-                ) or (error.code == -32031 and error.kind == "backpressured")
+                # A present data.retryable overrides the code's table default,
+                # so an explicit False stops the retry; absent keeps it.
+                retryable_nothing_admitted = error.retryable is not False and (
+                    (error.code == -32001 and error.kind == "overloaded")
+                    or (error.code == -32031 and error.kind == "backpressured")
+                )
                 if not retryable_nothing_admitted or attempt == attempts:
                     raise
                 await delay(attempt, error)
@@ -878,6 +906,27 @@ class Connection:
         if error is not None:
             self._finish(error)
 
+    def _fail_with_end_cause(
+        self, outcome: asyncio.Future[Any], error: BaseException
+    ) -> None:
+        """Fails ``outcome`` with ``error``, first giving it the peer's end
+        cause when the owner reported one."""
+        end_cause = self._end_cause
+        if end_cause is None or error.__cause__ is not None:
+            if not outcome.done():
+                outcome.set_exception(error)
+            return
+
+        def settle(done: asyncio.Future[BaseException | None]) -> None:
+            if not done.cancelled():
+                cause = done.result()
+                if cause is not None:
+                    error.__cause__ = cause
+            if not outcome.done():
+                outcome.set_exception(error)
+
+        end_cause.add_done_callback(settle)
+
     def _protocol_error(self, error: ProtocolError) -> None:
         if self._protocol_error_handler is not None:
             self._protocol_error_handler(error)
@@ -891,9 +940,10 @@ class Connection:
             if isinstance(reason, BaseException)
             else ProtocolError(str(reason))
         )
+        if self._read_peer_end_cause is not None:
+            self._end_cause = self._read_peer_end_cause()
         for pending in self._pending.values():
-            if not pending.future.done():
-                pending.future.set_exception(error)
+            self._fail_with_end_cause(pending.future, error)
         self._pending.clear()
         if not self._closed.done():
             self._closed.set_result(None)

{muse_code_sdk-1.4.14 → muse_code_sdk-1.4.20}/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.14 → muse_code_sdk-1.4.20}/src/muse_code/connection/spawn.py

@@ -55,7 +55,8 @@ SIGTERM_GRACE_MS = 2_000
 its whole drain window, so this covers only a signal handler's final flush.
 Also bounds ``_classified``'s post-exit stderr-drain wait (py3.10 settles
 ``wait()`` at the reap, before pipe EOF), so tuning it down also shrinks the
-window for capturing a host's final stderr evidence."""
+window for capturing a host's final stderr evidence. And it bounds how long a
+call failed by a host death waits for the exit."""
 OnStderr = Callable[[str], None]