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

{muse_code_sdk-1.4.15/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.15
+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.15
+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.
@@ -112,6 +117,29 @@ 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
@@ -153,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.15 → muse_code_sdk-1.4.20}/README.md

@@ -8,6 +8,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.
@@ -17,6 +19,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.
@@ -92,6 +97,29 @@ 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
@@ -133,6 +161,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.15 → 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.15"
+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.15"]
+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.15 → muse_code_sdk-1.4.20}/src/muse_code/__init__.py

@@ -58,15 +58,19 @@ __all__ = [
     "MuseHostDiscoveryError",
     "MuseHostStartError",
     "MuseSessionDiscardedError",
+    "NotificationFailureHandler",
+    "NotificationObserver",
     "PendingCommandSet",
     "PendingCommandView",
     "PermissionProfileNotApplied",
+    "ProtocolErrorObserver",
     "ResumeSessionOptions",
     "RunResult",
     "SendUserTurnOptions",
     "Session",
     "SessionApplyOutcome",
     "SessionDurabilityProfile",
+    "SessionEvent",
     "SessionFold",
     "SessionFoldView",
     "SessionGapBuffered",
@@ -82,6 +86,7 @@ __all__ = [
     "Turn",
     "TurnOutcome",
     "TurnUnqueueOutcome",
+    "ViewFrame",
     "is_abnormal_host_death",
     "is_launch_failure",
     "load_transcript",
@@ -103,7 +108,7 @@ 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.15"
+__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
@@ -123,13 +128,17 @@ from .facade import (  # noqa: E402
     MuseClientSpawnOptions,
     MuseHostDiedError,
     MuseHostStartError,
+    NotificationFailureHandler,
+    NotificationObserver,
     PendingCommandView,
+    ProtocolErrorObserver,
     ResumeSessionOptions,
     RunResult,
     SendUserTurnOptions,
     Session,
     SessionApplyOutcome,
     SessionDurabilityProfile,
+    SessionEvent,
     SessionFoldView,
     SessionGapBuffered,
     SessionGapOverlap,
@@ -139,6 +148,7 @@ from .facade import (  # noqa: E402
     Turn,
     TurnOutcome,
     TurnUnqueueOutcome,
+    ViewFrame,
     is_abnormal_host_death,
     is_launch_failure,
     read_session_durability,

{muse_code_sdk-1.4.15 → 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.15 → 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]
 
 

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

@@ -117,9 +117,10 @@ class PermissionProfileNotApplied(Exception):
 
 
 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.
+    """``MuseClient.command`` or ``MuseClient.request`` 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.
@@ -133,7 +134,8 @@ class MuseFacadeOwnedMethodError(Exception):
         """
         super().__init__(
             f"{method} is sent by the facade itself and cannot go through "
-            "MuseClient.command; use the facade verb that owns it"
+            "MuseClient.command or MuseClient.request; use the facade verb that "
+            "owns it"
         )
         self.method: str = method
 
@@ -205,7 +207,7 @@ class MuseValidationError(ValueError):
         self.__cause__ = cause
 
 
-COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/compatibility/"
+COMPATIBILITY_PAGE_URL = "https://meta-models.github.io/muse-code-sdk/latest/compatibility/"
 """The developer-docs compatibility page the discovery errors cite.
 
 The Python row there is the customer-facing statement of the supported

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

@@ -24,6 +24,9 @@ from .client import (
     MuseClient,
     MuseClientOptions,
     MuseClientSpawnOptions,
+    NotificationFailureHandler,
+    NotificationObserver,
+    ProtocolErrorObserver,
     ResumeSessionOptions,
     StartSessionOptions,
 )
@@ -45,10 +48,12 @@ from .session import (
     Session,
     SessionApplyOutcome,
     SessionApplyRefusal,
+    SessionEvent,
     SessionFoldView,
     SessionGapBuffered,
     SessionGapOverlap,
     SessionOpening,
+    ViewFrame,
 )
 from .run import RunResult
 from .turn_handle import FoldedItem, Turn, TurnOutcome, TurnUnqueueOutcome, is_launch_failure
@@ -70,7 +75,10 @@ __all__ = [
     "MuseClientSpawnOptions",
     "MuseHostDiedError",
     "MuseHostStartError",
+    "NotificationFailureHandler",
+    "NotificationObserver",
     "PendingCommandView",
+    "ProtocolErrorObserver",
     "ResumeSessionOptions",
     "RunResult",
     "SendUserTurnOptions",
@@ -78,6 +86,7 @@ __all__ = [
     "SessionApplyOutcome",
     "SessionApplyRefusal",
     "SessionDurabilityProfile",
+    "SessionEvent",
     "SessionFoldView",
     "SessionGapBuffered",
     "SessionGapOverlap",
@@ -88,6 +97,7 @@ __all__ = [
     "Turn",
     "TurnOutcome",
     "TurnUnqueueOutcome",
+    "ViewFrame",
     "is_abnormal_host_death",
     "is_launch_failure",
     "read_session_durability",