muse-code-sdk 1.4.9__tar.gz → 1.4.11__tar.gz

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muse-code-sdk
-Version: 1.4.9
+Version: 1.4.11
 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
@@ -27,7 +27,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.

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/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.

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muse-code-sdk"
-version = "1.4.9"
+version = "1.4.11"
 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"

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/src/muse_code/__init__.py

@@ -80,7 +80,7 @@ __all__ = [
 ]
 
 EXPECTED_SCHEMA_FINGERPRINT: Final[str] = (
-    "sha256:5d3b43e5ccdb7dc4f5a32c380f5f2cde0f10e3059b93610afb2e73f73b1d914c"
+    "sha256:f282ad16e21520d0cda68cb190149b86e2b062eef1dd282749360c05aa3d1082"
 )
 """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.9"
+__version__: Final[str] = "1.4.11"
 
 # 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.9 → muse_code_sdk-1.4.11}/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
@@ -112,6 +111,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 +146,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 +162,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 +211,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).
@@ -327,7 +345,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 +367,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.9 → muse_code_sdk-1.4.11}/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.9 → muse_code_sdk-1.4.11}/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

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/src/muse_code/facade/session.py

@@ -26,6 +26,7 @@ from typing import (
     Literal,
     Mapping,
     Protocol,
+    Sequence,
     TypeVar,
     Union,
     cast,
@@ -39,16 +40,21 @@ from muse_code_msp import (
     ItemDeltaParams,
     TurnCompletedParams,
     TurnUnqueuedParams,
+    UserInputAnswer,
+    UserInputAnswerResult,
 )
 
-from ..connection.connection import Connection
+from ..connection.connection import Connection, ProtocolError
 from ..fold.item_store import IgnoredStaleRevision
 from ..fold.session_fold import (
     ApprovalPending,
+    ApprovalResolvedFold,
     DeliveryGap,
     FoldItems,
     FoldOutcome,
     FoldSessionState,
+    IgnoredStaleFrame,
+    IgnoredUnrecognizedMethod,
     ItemFold,
     Params,
     PendingApproval,
@@ -101,6 +107,28 @@ _USER_MESSAGE = "userMessage"
 assert _USER_MESSAGE in ITEM_KIND_KNOWN_VALUES
 
 
+def _is_routable_approval_request(request: Mapping[str, Any]) -> bool:
+    """True when a routed ``approval/request`` carries every member the approval
+    router reads: its ``approvalId``, the requirement's ``approvalId`` and
+    ``sourceIndex``, and each offered choice's ``choiceId``."""
+    if not isinstance(request.get("approvalId"), str):
+        return False
+    requirement = request.get("currentRequirementId")
+    choices = request.get("availableChoices")
+    if not isinstance(requirement, dict) or not isinstance(choices, list):
+        return False
+    index = requirement.get("sourceIndex")
+    return (
+        isinstance(requirement.get("approvalId"), str)
+        and isinstance(index, int)
+        and not isinstance(index, bool)
+        and all(
+            isinstance(choice, dict) and isinstance(choice.get("choiceId"), str)
+            for choice in choices
+        )
+    )
+
+
 class SessionFoldView(Protocol):
     """The fold as a consumer may READ it — the TS ``SessionFoldView`` allowlist.
 
@@ -336,6 +364,10 @@ class SessionApplyOutcome(Generic[_I]):
             apply that started the fill, never on the buffered frame's own
             return. A second ``view/gap`` landing mid-fill rides the same
             channel: it extends the running walk, so its own ``io`` is empty.
+            A repeat of a ``next`` already named while the hole is open folds
+            as ``IgnoredStaleFrame`` and extends nothing; after a failed fill
+            it still restarts that fill, and the restarted walk's work
+            settles on this frame's ``io``.
         io: The client->server I/O this event triggered, settled — resolves to
             the retirements that I/O produced. A SEPARATE channel from
             ``retirements`` because ``apply`` is synchronous by contract: a
@@ -397,6 +429,11 @@ class Session(Generic[_I]):
         self._discarded = discarded
         self._connection = connection
         self._fold: SessionFold = SessionFold()
+        # Approvals the fold holds a durable terminal for. Read by a re-sent
+        # ``approval/request``, which skips the fold, so it authors nothing for
+        # an approval already resolved; mirrors the fold's own record, keyed
+        # for O(1).
+        self._resolved_approval_ids: set[str] = set()
         self._pending: PendingCommandSet[_I] = PendingCommandSet(
             discarded_command_ids=(
                 discarded.command_ids if discarded is not None else set()
@@ -545,7 +582,12 @@ class Session(Generic[_I]):
         # already reported synchronously) — appending an already-settled stub
         # instead would force ``_settled_io``'s gather arm, which needs a
         # running loop a fold-only ``apply`` may not have.
-        if isinstance(outcome, DeliveryGap):
+        # A stale repeat of an earlier gap still restarts a failed fill, as
+        # every folded ``view/gap`` (a ``DeliveryGap`` or a stale repeat)
+        # reaches ``start()`` (a no-op while a fill runs).
+        if isinstance(outcome, DeliveryGap) or (
+            isinstance(outcome, IgnoredStaleFrame) and outcome.method == "view/gap"
+        ):
             fill = self._gaps.start()
             if fill is not None:
                 sink.tasks.append(fill)
@@ -569,7 +611,32 @@ class Session(Generic[_I]):
         # everything downstream — the fold, the iterators, and the protocol
         # retirements.
         retirements: List[PendingRetirement[_I]] = []
+        # A re-sent ``approval/request`` server request skips the fold, which
+        # lists only the ``approval/requested`` notification, and reaches
+        # approval routing like that notification: the per-stage latch decides
+        # each stage once, and an approval already resolved authors nothing.
+        # Its handler task can land after the ``approval/resolved`` read with
+        # it, so in that case Python skips a request TypeScript would still
+        # route in arrival order. A request missing the members the router
+        # reads is dropped, never raised on, whichever path applies it: a held
+        # frame replayed inside ``resume_session`` included. A routed or
+        # dropped request reports ``IgnoredUnrecognizedMethod``, a sanctioned
+        # interim like ``session/started``'s (a dedicated outcome is tracked);
+        # one with no params dict falls through to the fold's
+        # ``IgnoredMissingParams``, like every other frame.
+        request = event.get("params")
+        if event.get("method") == "approval/request" and isinstance(request, dict):
+            if (
+                _is_routable_approval_request(request)
+                and request["approvalId"] not in self._resolved_approval_ids
+            ):
+                self._approval_requested(
+                    cast(ApprovalRequestParams, request), sink.tasks
+                )
+            return IgnoredUnrecognizedMethod("approval/request")
         outcome = self._fold.apply(event)
+        if isinstance(outcome, ApprovalResolvedFold):
+            self._resolved_approval_ids.add(outcome.approval_id)
         # The fold drops a params-less frame as IgnoredMissingParams;
         # the arms below read ``params`` on the turn/item arms, so return early.
         method = str(event.get("method"))
@@ -627,9 +694,9 @@ class Session(Generic[_I]):
                 )
         # ``view/gap`` deliberately routes to no turn: it names a hole in
         # DELIVERY, so what it moves is the fold's currency, and the recovery
-        # it triggers is started by ``apply`` off the ``DeliveryGap`` verdict
-        # rather than from here. Every other method is folded
-        # but routed to no turn.
+        # it triggers is started by ``apply`` off the ``DeliveryGap`` verdict,
+        # or off a stale ``view/gap``'s ``IgnoredStaleFrame``, rather than from
+        # here. Every other method is folded but routed to no turn.
 
         # The retired entries are gone from the set, so their replay memory
         # goes with them.
@@ -782,6 +849,62 @@ class Session(Generic[_I]):
         :data:`~muse_code.facade.approval.ApprovalFailure`."""
         self._approvals.on_approval_error(handler)
 
+    # ---- user-input answers ---------------------------------------------------
+
+    async def answer_user_input(
+        self, user_input_id: str, answers: Sequence[UserInputAnswer]
+    ) -> UserInputAnswerResult:
+        """Answer a question this session lists in ``fold.pending_user_inputs()``.
+
+        Sends ``userInput/answer`` with one answer per question and returns
+        the host's admission. The question leaves the pending list only when
+        the server's ``userInput/settled`` arrives.
+
+        Args:
+            user_input_id: The question to answer.
+            answers: One answer per question.
+
+        Returns:
+            The host's admission of the answer.
+
+        Raises:
+            MuseSessionDiscardedError: The session was discarded after an
+                ephemeral host death; nothing is sent.
+            RuntimeError: The session was constructed fold-only; nothing is sent.
+            ProtocolError: The acknowledgement has no command id or names
+                another question.
+        """
+        # Refused before anything is sent, as ``send_user_turn`` is: a
+        # discarded session cannot be reattached.
+        if self._discharge is not None and self._discharge.kind == "discharged":
+            from ..errors import MuseSessionDiscardedError
+
+            raise MuseSessionDiscardedError(
+                f"session {self.session_id} was discarded after an ephemeral host "
+                "death; it cannot answer a question"
+            )
+        connection = self._submit.require_connection("answer_user_input")
+        # No explicit ``commandId``: ``Connection.command`` mints and stamps it,
+        # and refuses an ack that echoes a different one. An ack with none is
+        # refused here, with one naming another question.
+        ack = await connection.command(
+            "userInput/answer",
+            {
+                "sessionId": self.session_id,
+                "userInputId": user_input_id,
+                "answers": list(answers),
+            },
+        )
+        if (
+            not isinstance(ack.get("commandId"), str)
+            or ack.get("userInputId") != user_input_id
+        ):
+            raise ProtocolError(
+                f"userInput/answer acknowledged command {ack.get('commandId')} for "
+                f"question {ack.get('userInputId')}, expected question {user_input_id}"
+            )
+        return cast(UserInputAnswerResult, ack)
+
     # ---- consumer-driven pending-retirement verbs ---------------------------------
 
     def stop_retrying(self, command_id: str) -> PendingRetirement[_I] | None:

{muse_code_sdk-1.4.9 → muse_code_sdk-1.4.11}/src/muse_code/fold/__init__.py

@@ -32,6 +32,7 @@ from .session_fold import (
     IgnoredUnrecognizedMethod,
     ItemDeltaFold,
     ItemFold,
+    MonitorInboxNotice,
     PendingApproval,
     SessionFold,
     SessionStateFold,
@@ -67,6 +68,7 @@ __all__ = [
     "ItemFold",
     "ItemLike",
     "ItemStore",
+    "MonitorInboxNotice",
     "PendingApproval",
     "Replaced",
     "SessionFold",