muse-code-sdk 1.4.10__tar.gz → 1.4.12__tar.gz

{muse_code_sdk-1.4.10/src/muse_code_sdk.egg-info → muse_code_sdk-1.4.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muse-code-sdk
-Version: 1.4.10
+Version: 1.4.12
 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,6 +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.12
 Dynamic: license-file
 
 # `muse-code-sdk`
@@ -27,7 +28,12 @@ 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.
-- Answer tool-approval requests with a handler you register.
+- 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.
@@ -37,13 +43,14 @@ 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. One runtime dependency: `pydantic`, exact-pinned.
+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 muse-code-msp
+pip install muse-code-sdk
 ```
 
 You also need the Muse Code CLI: a `muse` binary on `PATH`, or an explicit

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/README.md

@@ -8,7 +8,12 @@ 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.
-- Answer tool-approval requests with a handler you register.
+- 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.
@@ -18,13 +23,14 @@ 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. One runtime dependency: `pydantic`, exact-pinned.
+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 muse-code-msp
+pip install muse-code-sdk
 ```
 
 You also need the Muse Code CLI: a `muse` binary on `PATH`, or an explicit

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/pyproject.toml

@@ -5,19 +5,20 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muse-code-sdk"
-version = "1.4.10"
+version = "1.4.12"
 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"
 license = "MIT"
 license-files = ["LICENSE"]
-# Exactly ONE runtime dependency, exact-pinned: a deliberate, ruled
-# supply-chain exception. Any second dependency is an owner escalation;
-# bumps are deliberate reviewed PRs.
-# muse-code-msp is deliberately NOT declared: it is not on the registry yet,
-# and promoting it is the owner escalation decided with the first publish
-# (the @muse-code/msp devDependency precedent; test_publish_shape pins this).
-dependencies = ["pydantic==2.13.5"]
+# Two runtime dependencies, both exact-pinned. pydantic is the deliberate,
+# ruled supply-chain exception; bumps are deliberate reviewed PRs.
+# muse-code-msp is the companion wire-types package generated and released
+# from the same tree, so its pin is this package's own version: a plain
+# `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.12"]
 classifiers = [
     # Alpha states the withheld promise: publication is permitted, but the
     # stability promise and conformance claim stay withheld — experimental

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/src/muse_code/__init__.py

@@ -80,7 +80,7 @@ __all__ = [
 ]
 
 EXPECTED_SCHEMA_FINGERPRINT: Final[str] = (
-    "sha256:5d3b43e5ccdb7dc4f5a32c380f5f2cde0f10e3059b93610afb2e73f73b1d914c"
+    "sha256:cfdb6d2525601b9bac76584ccb0610ab3a5539b5e4f51141f079b99b39fcb4e0"
 )
 """The stable schema-bundle fingerprint this SDK was built against.
 
@@ -92,7 +92,7 @@ Python SDK reds this lane instead of drifting 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.10"
+__version__: Final[str] = "1.4.12"
 
 # The facade is imported last so the constants above are already bound: the
 # spawn path reads ``EXPECTED_SCHEMA_FINGERPRINT`` (lazily, at initialize

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/src/muse_code/facade/approval.py

@@ -1,18 +1,17 @@
-"""The approval round trip: inbound ``approval/requested`` → the consumer's
-handler → outbound ``approval/decide``. Port of the TypeScript SDK's
-approval router.
+"""The approval round trip: inbound ``approval/requested`` or
+``approval/request`` → the consumer's handler → outbound ``approval/decide``.
+Port of the TypeScript SDK's approval router.
 
 Split out of ``session.py`` rather than added to it: the router owns a
 handler, a per-stage latch, and a decision-shaping guard chain that have
 nothing to do with folding a view, and ``Session`` was already the package's
 largest module.
 
-SHAPE NOTE, established from the bundle rather than assumed. ``approval/request``
-as a SERVER REQUEST is not enrolled for the view stream this router rides —
-the schema carries ``approval/requested`` as a NOTIFICATION — so the round
-trip is notification-in / command-out, which is exactly the pair the
-protocol names. The server-request form would be a protocol enrollment
-request upstream, never a local interface.
+Two frames carry a request in: the ``approval/requested`` notification and
+the ``approval/request`` server request, which the host sends beside it and
+re-sends after a resume. A client-owned connection routes both here, and the
+per-stage latch decides each stage once, whichever arrives first. The
+decision goes out as the ``approval/decide`` command.
 """
 
 from __future__ import annotations
@@ -62,6 +61,7 @@ _REFRESH_FROM_UPDATE = frozenset(
 _REFRESH_FROM_REQUEST = frozenset(
     {
         "approvalId",
+        "cuaCardFacts",
         "itemId",
         "judgeEscalated",
         "protectedWrite",
@@ -112,6 +112,22 @@ class UnofferedChoice:
     kind: Literal["unofferedChoice"] = "unofferedChoice"
 
 
+@dataclass(frozen=True)
+class FeedbackNotAccepted:
+    """The handler attached ``feedback`` to a choice whose ``acceptsFeedback``
+    is not true. The host would refuse that decision, so it is not sent; the
+    offered reject (the ``denied`` choice, else the ``abort`` one) is sent
+    next, so the approval closes. With neither offered, nothing is sent and the
+    approval stays open; a failure to send the reject is reported as
+    ``SubmitFailed``. Next time, answer without feedback, or pick one of
+    ``feedback_choice_ids``, the offered choices that accept it."""
+
+    approval_id: str
+    choice_id: str
+    feedback_choice_ids: tuple[str, ...]
+    kind: Literal["feedbackNotAccepted"] = "feedbackNotAccepted"
+
+
 @dataclass(frozen=True)
 class HandlerRaised:
     """The consumer's decision handler raised; nothing reached the wire."""
@@ -131,14 +147,15 @@ class SubmitFailed:
     kind: Literal["submitFailed"] = "submitFailed"
 
 
-ApprovalFailure = Union[UnofferedChoice, HandlerRaised, SubmitFailed]
+ApprovalFailure = Union[UnofferedChoice, FeedbackNotAccepted, HandlerRaised, SubmitFailed]
 """Why one approval round trip did not complete.
 
 REPORTED, not raised: the trip is driven from a notification, so an exception
 would escape into the consumer's pump with nothing to catch it — the same
-hazard ``Session.apply`` already refuses a malformed frame for. Each arm names
-a DIFFERENT owner (the consumer's handler, the consumer's choice, the host),
-because the repair differs.
+hazard ``Session.apply`` already refuses a malformed frame for. Each kind names
+whose repair it is (the consumer's handler; the consumer's choice, for
+``unofferedChoice`` and ``feedbackNotAccepted``; the host), because the repair
+differs.
 """
 
 ApprovalFailureHandler = Callable[[ApprovalFailure], None]
@@ -146,9 +163,10 @@ ApprovalFailureHandler = Callable[[ApprovalFailure], None]
 
 
 class ApprovalRouter:
-    """Routes folded ``approval/requested`` frames, and ``approval/updated``
-    frames that advance a pending approval's stage, to the consumer's handler
-    and authors the ``approval/decide`` command."""
+    """Routes folded ``approval/requested`` frames, routed ``approval/request``
+    frames, and ``approval/updated`` frames that advance a pending approval's
+    stage, to the consumer's handler and authors the ``approval/decide``
+    command."""
 
     def __init__(self, session_id: str, connection: Connection | None) -> None:
         """Builds the router; ``connection`` is absent on a fold-only session.
@@ -194,7 +212,8 @@ class ApprovalRouter:
         self._on_failure = handler
 
     def requested(self, params: ApprovalRequestParams) -> Awaitable[None] | None:
-        """An ``approval/requested`` folded. Returns the decision round trip to
+        """An ``approval/requested`` the fold kept pending, or a routed
+        ``approval/request``. Returns the decision round trip to
         await, or ``None`` when this call schedules nothing — no handler, an
         already-decided stage, or a fold-only session (whose ``SubmitFailed``
         is reported synchronously before returning).
@@ -279,6 +298,10 @@ class ApprovalRouter:
         # Omitted rather than nulled when absent, like ``feedback`` below.
         if "subagentOrigin" in params:
             refreshed["subagentOrigin"] = params["subagentOrigin"]
+        # A Computer Use card's facts belong to the call, so they stay with
+        # the retained request across stages.
+        if "cuaCardFacts" in requested:
+            refreshed["cuaCardFacts"] = requested["cuaCardFacts"]
         acked = self._in_flight.get(requested["approvalId"])
         if acked is not None:
             return self._after_ack(acked, refreshed)
@@ -327,7 +350,15 @@ class ApprovalRouter:
         available_choice_ids = tuple(
             choice["choiceId"] for choice in params["availableChoices"]
         )
-        if choice_id not in available_choice_ids:
+        chosen = next(
+            (
+                choice
+                for choice in params["availableChoices"]
+                if choice["choiceId"] == choice_id
+            ),
+            None,
+        )
+        if chosen is None:
             # Select-never-create, enforced on THIS side of the
             # transport. An invented choice bounces -32052 a round trip later,
             # by which time the stage may have advanced — so the diagnosis a
@@ -341,6 +372,36 @@ class ApprovalRouter:
                 )
             )
             return
+        if feedback is not None and chosen.get("acceptsFeedback") is not True:
+            # The host refuses feedback on any other choice (-32052) and
+            # keeps its approval open, so refuse it here and answer with the
+            # offered reject instead, the choice the Rust SDK sends too: the
+            # approval closes and the host's turn goes on. With neither a
+            # ``denied`` nor an ``abort`` choice, nothing is sent.
+            self._report(
+                FeedbackNotAccepted(
+                    approval_id=params["approvalId"],
+                    choice_id=choice_id,
+                    feedback_choice_ids=tuple(
+                        choice["choiceId"]
+                        for choice in params["availableChoices"]
+                        if choice.get("acceptsFeedback") is True
+                    ),
+                )
+            )
+            reject = next(
+                (
+                    choice
+                    for decision in ("denied", "abort")
+                    for choice in params["availableChoices"]
+                    if choice.get("decision") == decision
+                ),
+                None,
+            )
+            if reject is None:
+                return
+            choice_id = reject["choiceId"]
+            feedback = None
 
         decide_params: dict[str, Any] = {
             "approvalId": params["approvalId"],

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/src/muse_code/facade/client.py

@@ -40,11 +40,12 @@ from muse_code_msp import (
     ClientInfo,
     InitializeParams,
     InitializeResult,
+    RecoveryMode,
     SessionResumeParams,
     SessionStartParams,
 )
 
-from ..connection.connection import Connection
+from ..connection.connection import Connection, MspError
 from ..connection.spawn import (
     DEFAULT_SHUTDOWN_TIMEOUT_MS,
     ExitClassification,
@@ -63,6 +64,7 @@ from .host_death import (
     read_session_durability,
     survives_host_death,
 )
+from .approval import ApprovalFailureHandler, ApprovalHandler
 from .session import Session, SessionOpening, _ResumeOpening, _StartOpening
 from .turn_submit import _camel
 
@@ -105,6 +107,8 @@ class StartSessionOptions:
             of proceeding on the host default. Client-local: never sent on
             the wire. Setting it without ``permission_profile`` is a usage
             error.
+        recovery_mode: Optional recovery selection (wire ``recoveryMode``);
+            omitted means no selection is sent.
     """
 
     approval_mode: str | None = None
@@ -115,6 +119,7 @@ class StartSessionOptions:
     model_id: str | None = None
     permission_profile: str | None = None
     require_permission_profile: bool = False
+    recovery_mode: RecoveryMode | None = None
 
 
 @dataclass
@@ -134,6 +139,18 @@ class ResumeSessionOptions:
             wire's ``permissionProfile`` member: the host restores the
             retained authority first, then applies the pick. Omitted means
             no override.
+        recovery_mode: Optional recovery selection (wire ``recoveryMode``);
+            omitted means no selection is sent.
+        on_approval: Answers this session's approvals from its first frame,
+            so an approval the host re-sends right after the resume reply
+            reaches it. The same contract as ``Session.on_approval``,
+            installed before the frames that arrived with the reply are
+            applied. Never sent on the wire.
+        on_approval_error: Hears this session's approval failures from its
+            first frame, as ``Session.on_approval_error`` does later, so a
+            failure for an approval that arrived with the resume reply is
+            heard whatever task the caller registers from. Never sent on the
+            wire.
     """
 
     session_id: str
@@ -141,6 +158,9 @@ class ResumeSessionOptions:
     exclude_items: bool | None = None
     history: Mapping[str, Any] | None = None
     permission_profile: str | None = None
+    recovery_mode: RecoveryMode | None = None
+    on_approval: ApprovalHandler | None = None
+    on_approval_error: ApprovalFailureHandler | None = None
 
 
 # Drift pins — the Python twin of the TS `AssertNever` on START_FORWARDED /
@@ -162,7 +182,10 @@ assert (
 ), "StartSessionOptions drifted from SessionStartParams — forward the new member"
 
 _RESUME_EXCLUDED = {"commandId", "config"}
-assert {_camel(f.name) for f in fields(ResumeSessionOptions)} | _RESUME_EXCLUDED == set(
+_RESUME_OWNED = {"onApproval", "onApprovalError"}
+assert (
+    {_camel(f.name) for f in fields(ResumeSessionOptions)} - _RESUME_OWNED
+) | _RESUME_EXCLUDED == set(
     SessionResumeParams.__annotations__
 ), "ResumeSessionOptions drifted from SessionResumeParams — forward the new member"
 
@@ -279,6 +302,14 @@ class MuseClient(Generic[_I]):
         # spawn-built consumer hears no view frame. ``Connection`` holds ONE
         # notification handler — this client claims it.
         connection.on_notification(self._route)
+        # A question or approval still open when a session is resumed is
+        # re-sent as a ``userInput/request`` or ``approval/request`` server
+        # request. Each is routed and answered with the empty receipt ``{}``:
+        # a question as the ``userInput/requested`` twin it shares params with,
+        # so its session lists it, and an approval as itself, which the session
+        # routes to its approval handler. Every other server-request method
+        # keeps the ``-32601`` a bare ``Connection`` answers.
+        connection.on_server_request(self._serve_request)
         # Registered at construction, not at the first session: an EOF can land
         # before any session exists, and the flag has to be read at that moment.
         self._closed_watch = asyncio.ensure_future(self._watch_closed())
@@ -417,6 +448,8 @@ class MuseClient(Generic[_I]):
             params["workspaceRoots"] = options.workspace_roots
         if options.model_id is not None:
             params["modelId"] = options.model_id
+        if options.recovery_mode is not None:
+            params["recoveryMode"] = options.recovery_mode
         # The initial permission-profile selection, forwarded verbatim like the
         # other start members (None stays omitted).
         if options.permission_profile is not None:
@@ -488,9 +521,17 @@ class MuseClient(Generic[_I]):
             params["excludeItems"] = options.exclude_items
         if options.history is not None:
             params["history"] = options.history
+        if options.recovery_mode is not None:
+            params["recoveryMode"] = options.recovery_mode
         if options.permission_profile is not None:
             params["permissionProfile"] = options.permission_profile
-        return await self._open("session/resume", params, _ResumeOpening)
+        return await self._open(
+            "session/resume",
+            params,
+            _ResumeOpening,
+            options.on_approval,
+            options.on_approval_error,
+        )
 
     async def close(self) -> None:
         """Shut the host down in an orderly way.
@@ -519,6 +560,8 @@ class MuseClient(Generic[_I]):
         verb: str,
         params: dict[str, Any],
         opening: Callable[[Mapping[str, Any]], SessionOpening],
+        on_approval: ApprovalHandler | None = None,
+        on_approval_error: ApprovalFailureHandler | None = None,
     ) -> Session[_I]:
         # The window ``_route`` holds unknown-session frames for: from the
         # request to the Session's registration. Counted, not flagged, so two
@@ -530,7 +573,10 @@ class MuseClient(Generic[_I]):
             raw = await self._connection.command(verb, params)
             result: Mapping[str, Any] = raw
             return self._open_session(
-                str(result["session"]["sessionId"]), opening(result)
+                str(result["session"]["sessionId"]),
+                opening(result),
+                on_approval,
+                on_approval_error,
             )
         finally:
             self._opening -= 1
@@ -538,7 +584,11 @@ class MuseClient(Generic[_I]):
                 self._held.clear()
 
     def _open_session(
-        self, session_id: str, opening: SessionOpening
+        self,
+        session_id: str,
+        opening: SessionOpening,
+        on_approval: ApprovalHandler | None = None,
+        on_approval_error: ApprovalFailureHandler | None = None,
     ) -> Session[_I]:
         session: Session[_I] = Session(
             session_id,
@@ -547,6 +597,12 @@ class MuseClient(Generic[_I]):
             discarded=self._discarded,
             opening=opening,
         )
+        # Before the held frames below: an approval re-sent with the resume
+        # reply must find the handler, and its failure the observer.
+        if on_approval_error is not None:
+            session.on_approval_error(on_approval_error)
+        if on_approval is not None:
+            session.on_approval(on_approval)
         self._sessions.add(session)
         # The frames that named this session while its verb was in flight
         # fold NOW, in arrival order — synchronously, so nothing the pump
@@ -570,6 +626,37 @@ class MuseClient(Generic[_I]):
                 "reattaching to it"
             )
 
+    async def _serve_request(self, request: Mapping[str, Any]) -> dict[str, Any]:
+        # The connection runs this as its own task, so the twin can land after
+        # frames read in the same chunk. The same questions are listed, since
+        # the list is keyed by question id and a settled question stays
+        # settled; their order can differ when another question arrives in
+        # that chunk. The receipt does not depend on ``_route`` finding the
+        # session: a request read during an open is held before that session
+        # exists.
+        method = request.get("method")
+        if method == "userInput/request":
+            self._route(
+                {
+                    "jsonrpc": "2.0",
+                    "method": "userInput/requested",
+                    "params": request.get("params"),
+                }
+            )
+            return {}
+        if method == "approval/request":
+            self._route(
+                {"jsonrpc": "2.0", "method": method, "params": request.get("params")}
+            )
+            return {}
+        raise MspError(
+            {
+                "code": -32601,
+                "message": f"method not found: {method}",
+                "data": {"kind": "methodNotFound", "retryable": False},
+            }
+        )
+
     def _route(self, notification: Mapping[str, Any]) -> None:
         # Deliver one view notification to the session(s) it names. A frame
         # naming NO session is dropped here rather than fed to every session

{muse_code_sdk-1.4.10 → muse_code_sdk-1.4.12}/src/muse_code/facade/gap_fill.py

@@ -206,7 +206,8 @@ class GapFiller(Generic[_I]):
         """
         gap = self._options.fold.pending_gap
         # Only reachable if a caller invokes this with nothing outstanding; the
-        # one production caller folds the marker first, which always sets it.
+        # one production caller folds the marker first, which sets it or, for
+        # a stale repeat, finds it already set.
         if gap is None:
             return None
         if self._filling:
@@ -489,6 +490,10 @@ class GapFiller(Generic[_I]):
 
 
 def _view_cursor_of(frame: WireFrame) -> str | None:
+    # A routed ``approval/request`` carries its notification's cursor but is
+    # not that event: matching it would spend the twin's overlap slot.
+    if frame.get("method") == "approval/request":
+        return None
     params = frame.get("params")
     cursor = params.get("viewCursor") if isinstance(params, dict) else None
     return cursor if isinstance(cursor, str) else None