muse-code-sdk 1.3.0__py3-none-any.whl

muse_code/facade/turn_submit.py

@@ -0,0 +1,289 @@
+"""``turn/start`` submission and same-``commandId`` replay (spec 638
+FR-638-019a carrying spec 14990 FR-018 obligations (a) and (d); tdd SS3.1.1,
+SS3.2, SS4.13). Port of ``clients/sdk-ts/src/facade/turn-submit.ts``.
+
+It holds the ONE piece of state :class:`~muse_code.pending.PendingCommandSet`
+deliberately cannot: the ``turn/start`` params per ``commandId``. The set
+stores the COMPOSER input and is wire-blind by design (INV-638-01), so a
+replay — which must re-send the SAME logical command to be the sanctioned
+retry rather than a double execution — needs the params on this side of that
+boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Generic, List, Sequence, TypeVar, cast
+
+from muse_code_msp import (
+    IfBusy,
+    ReasoningEffort,
+    TurnInputPart,
+    TurnStartParams,
+    TurnStartResult,
+)
+
+from ..connection.connection import Connection, MspError, Params
+from ..pending.pending_command_set import (
+    CommandErrorResponse,
+    PendingCommandAck,
+    PendingCommandSet,
+    PendingRetirement,
+    ReplayAck,
+    ReplayAnswer,
+    ReplayError,
+)
+
+_I = TypeVar("_I")
+
+
+@dataclass
+class SendUserTurnOptions(Generic[_I]):
+    """What :meth:`Session.send_user_turn` sends, composed from the generated
+    ``turn/start`` params rather than restated (INV-638-02).
+
+    ``commandId`` is excluded because ``Connection`` is the single minter
+    (INV-638-04 carrying INV-013); ``sessionId`` because the session already
+    knows its own and a caller-supplied one could only disagree.
+
+    Attributes:
+        input: The turn's input parts (the wire ``input`` member).
+        display_text: Optional composer display text (wire ``displayText``).
+        if_busy: How to treat a submit while a turn runs (wire ``ifBusy``).
+        reasoning_effort: The turn's reasoning effort (wire
+            ``reasoningEffort``).
+        composer_input: What to hand back to the composer if this submit is
+            ever retired — SS4.13 restores the INPUT, not the wire parts.
+            Optional: a consumer rendering nothing optimistically has nothing
+            to restore.
+    """
+
+    input: List[TurnInputPart]
+    display_text: str | None = None
+    if_busy: IfBusy | None = None
+    reasoning_effort: ReasoningEffort | None = None
+    composer_input: _I | None = None
+
+
+def _camel(field_name: str) -> str:
+    """snake_case → camelCase, the C-638-1 facade→wire member mapping.
+
+    The single copy: ``client.py`` imports this for its own drift pins rather
+    than restating it (that direction has no import cycle — this module reaches
+    neither ``client`` nor ``session``).
+    """
+    head, *rest = field_name.split("_")
+    return head + "".join(part.capitalize() for part in rest)
+
+
+# Drift pin — the Python twin of the TS `AssertNever` on TURN_START_FORWARDED
+# (turn-submit.ts). A schema regen that adds a member to TurnStartParams but not
+# to SendUserTurnOptions reds THIS import, so a regenerated member cannot
+# silently fail to reach the wire (INV-638-02). `composer_input` is the SDK's
+# own field (the SS4.13 restore payload), never a wire member, so it is dropped
+# before the compare; `commandId`/`sessionId` are excluded because the
+# connection mints the first and the session owns the second.
+_TURN_WIRE_FIELDS = {"input", "display_text", "if_busy", "reasoning_effort"}
+_TURN_EXCLUDED = {"commandId", "sessionId"}
+assert {
+    _camel(f.name) for f in fields(SendUserTurnOptions) if f.name in _TURN_WIRE_FIELDS
+} | _TURN_EXCLUDED == set(
+    TurnStartParams.__annotations__
+), "SendUserTurnOptions drifted from TurnStartParams — forward the new member"
+
+
+def command_error_response(error: BaseException) -> CommandErrorResponse | None:
+    """An :class:`MspError` as the pending set reads it (SS4.13's settlement
+    test).
+
+    ``None`` for anything that is NOT a server-authored MSP error — a
+    :class:`ProtocolError`, a dead transport — because those admit nothing AND
+    prove nothing about the intake, so the entry must HOLD rather than be
+    judged.
+
+    Args:
+        error: The exception a submit or replay raised.
+
+    Returns:
+        The typed response, or ``None`` for a non-MSP failure.
+    """
+    if not isinstance(error, MspError):
+        return None
+    reason = error.data.get("reason")
+    return CommandErrorResponse(
+        code=error.code,
+        kind=error.kind,
+        reason=reason if isinstance(reason, str) else None,
+    )
+
+
+class TurnSubmitter(Generic[_I]):
+    """Shapes ``turn/start`` frames, records the optimistic SS4.13 entry, and
+    replays a remembered command under its original ``commandId``."""
+
+    def __init__(
+        self,
+        session_id: str,
+        connection: Connection | None,
+        pending: PendingCommandSet[_I],
+    ) -> None:
+        """Binds the submitter; ``connection`` is ``None`` on a fold-only
+        session."""
+        self._session_id = session_id
+        self._connection = connection
+        self._pending = pending
+        # See the module doc. Pruned on retirement, so it tracks the set.
+        self._memory: dict[str, Params] = {}
+
+    @property
+    def wired(self) -> bool:
+        """Whether a connection is present to author through."""
+        return self._connection is not None
+
+    def require_connection(self, verb: str) -> Connection:
+        """The connection, or a plain error naming the fold-only misuse.
+
+        A plain :class:`Exception`: calling a submit verb on a fold-only
+        session is API misuse, not the foreign-frame STATE
+        :class:`MuseForeignSessionError` names.
+
+        Args:
+            verb: The verb name, for the error message.
+
+        Returns:
+            The live connection.
+
+        Raises:
+            RuntimeError: This session was constructed fold-only.
+        """
+        if self._connection is None:
+            raise RuntimeError(
+                f"{verb} needs a connection; this Session was constructed fold-only"
+            )
+        return self._connection
+
+    async def submit(
+        self, options: SendUserTurnOptions[_I], anchor_after_item_id: str | None
+    ) -> PendingCommandAck:
+        """Records the optimistic SS4.13 entry, then sends ``turn/start``.
+
+        The ORDER is the point. An entry created only on the ack is invisible
+        for exactly the window it exists to cover — between the user pressing
+        enter and the host answering — and ``anchor_after_item_id`` is fixed
+        here, at submission time, because SS4.13's insertion point may never
+        be relocated by events that fold in afterwards.
+
+        Args:
+            options: The caller's turn options.
+            anchor_after_item_id: The last item the session holds now.
+
+        Returns:
+            The admission ack (``turnId`` + ``disposition``).
+        """
+        connection = self.require_connection("send_user_turn")
+        # Delegated, not re-implemented: the connection owns the single mint,
+        # so INV-013's single-minter property survives this verb needing the
+        # id early.
+        command_id = connection.mint_command_id()
+        params = self._params(command_id, options)
+        self._pending.submitted(
+            command_id,
+            # ``composer_input`` is optional on the options object; a consumer
+            # rendering nothing optimistically has nothing to restore, and the
+            # set stores whatever it is handed for restoration. ``None`` is a
+            # valid stored input, so the cast preserves it rather than
+            # inventing a value.
+            cast(_I, options.composer_input),
+            display_text=params.get("displayText"),
+            anchor_after_item_id=anchor_after_item_id,
+        )
+        self._memory[command_id] = params
+        try:
+            ack = await self._send(connection, params, command_id)
+            self._pending.acked(command_id, ack)
+            return ack
+        except MspError as error:
+            response = command_error_response(error)
+            # Only a durable -32030 settles; every other error admitted
+            # nothing and the entry HOLDS for the caller's same-commandId
+            # retry (SS4.13).
+            if response is not None:
+                settled = self._pending.ack_errored(command_id, response)
+                if settled != "held":
+                    self.forget_retired([settled])
+            # Re-raised, deliberately: the caller who submitted still holds its
+            # own input, so this path needs no second retirement channel.
+            raise
+
+    async def replay(self, command_id: str) -> ReplayAnswer[_I] | None:
+        """Re-sends one remembered ``turn/start`` under its ORIGINAL
+        ``commandId`` (SS3.1.1 — always safe, the only re-send that is not a
+        double execution).
+
+        Args:
+            command_id: The command to replay.
+
+        Returns:
+            The answer, or ``None`` for "no answer this set can act on" —
+            either this session never authored the command, or the failure was
+            transport/protocol, which proves nothing about the intake.
+        """
+        params = self._memory.get(command_id)
+        if params is None:
+            return None
+        connection = self.require_connection("turn/start replay")
+        try:
+            ack = await self._send(connection, params, command_id)
+            return ReplayAck(ack=ack)
+        except MspError as error:
+            response = command_error_response(error)
+            if response is None:
+                return None
+            return ReplayError(error=response)
+
+    async def drive_replay(
+        self, command_id: str, into: List[PendingRetirement[_I]]
+    ) -> None:
+        """Replay one entry and feed the answer back through the live SS4.13
+        rules."""
+        answer = await self.replay(command_id)
+        if answer is None:
+            return
+        settled = self._pending.replay_answered(command_id, answer)
+        if settled != "held":
+            into.append(settled)
+
+    def forget_retired(
+        self, retirements: Sequence[PendingRetirement[_I]]
+    ) -> None:
+        """Drop the replay memory for retired entries so it tracks the set."""
+        for retirement in retirements:
+            self._memory.pop(retirement.command_id, None)
+
+    async def _send(
+        self, connection: Connection, params: Params, command_id: str
+    ) -> PendingCommandAck:
+        raw = await connection.command("turn/start", params, command_id=command_id)
+        result: TurnStartResult = raw  # type: ignore[assignment]
+        # ``turnId`` comes from the ACK, never from the ``commandId``: SS3.2
+        # makes the ack authoritative, and a queued submit's turn may already
+        # exist.
+        return PendingCommandAck(
+            turnId=result["turnId"], disposition=result["disposition"]
+        )
+
+    def _params(self, command_id: str, options: SendUserTurnOptions[_I]) -> Params:
+        # OPTIONAL MEANS OMITTED, NEVER null (tdd SS1.2): an unset member is
+        # dropped from the frame rather than nulled.
+        params: Params = {
+            "commandId": command_id,
+            "input": options.input,
+            "sessionId": self._session_id,
+        }
+        if options.display_text is not None:
+            params["displayText"] = options.display_text
+        if options.if_busy is not None:
+            params["ifBusy"] = options.if_busy
+        if options.reasoning_effort is not None:
+            params["reasoningEffort"] = options.reasoning_effort
+        return params

muse_code/fold/__init__.py

@@ -0,0 +1,82 @@
+"""The SS4 client fold: item store, session-state store, and their
+composition ``SessionFold`` (spec 638 FR-638-007; port of
+``clients/sdk-ts/src/fold``)."""
+
+from __future__ import annotations
+
+from .item_store import (
+    Appended,
+    BufferedForAbsentItem,
+    DeltaApplyOutcome,
+    IgnoredStaleRevision,
+    Inserted,
+    ItemApplyOutcome,
+    ItemLike,
+    ItemStore,
+    Replaced,
+    TerminalUnknownItemAnnotation,
+)
+from .session_fold import (
+    SESSION_STATE_METHODS,
+    LIVE_HOST_STATE_PROJECTIONS,
+    LIVE_HOST_STATE_PROJECTIONS,
+    VIEW_EVENT_METHODS,
+    ApprovalPending,
+    ApprovalResolvedFold,
+    DeliveryGap,
+    FoldItems,
+    FoldOutcome,
+    FoldSessionState,
+    IgnoredMissingParams,
+    IgnoredStaleFrame,
+    IgnoredUnrecognizedMethod,
+    ItemDeltaFold,
+    ItemFold,
+    PendingApproval,
+    SessionFold,
+    SessionStateFold,
+    TurnEntry,
+    TurnFold,
+    TurnState,
+    UserInputPending,
+    UserInputSettledFold,
+)
+from .state_store import SessionStateStore, StateApplyOutcome, StateValue
+
+__all__ = [
+    "SESSION_STATE_METHODS",
+    "LIVE_HOST_STATE_PROJECTIONS",
+    "VIEW_EVENT_METHODS",
+    "Appended",
+    "ApprovalPending",
+    "ApprovalResolvedFold",
+    "BufferedForAbsentItem",
+    "DeliveryGap",
+    "DeltaApplyOutcome",
+    "FoldItems",
+    "FoldOutcome",
+    "FoldSessionState",
+    "IgnoredMissingParams",
+    "IgnoredStaleFrame",
+    "IgnoredStaleRevision",
+    "IgnoredUnrecognizedMethod",
+    "Inserted",
+    "ItemApplyOutcome",
+    "ItemDeltaFold",
+    "ItemFold",
+    "ItemLike",
+    "ItemStore",
+    "PendingApproval",
+    "Replaced",
+    "SessionFold",
+    "SessionStateFold",
+    "SessionStateStore",
+    "StateApplyOutcome",
+    "StateValue",
+    "TerminalUnknownItemAnnotation",
+    "TurnEntry",
+    "TurnFold",
+    "TurnState",
+    "UserInputPending",
+    "UserInputSettledFold",
+]

muse_code/fold/item_store.py

@@ -0,0 +1,268 @@
+"""The item half of the SS4 client fold: upsert-by-revision plus delta
+accumulation (spec 638 FR-638-007 carrying spec 14990 FR-007,
+INV-003/INV-004).
+
+Items are the generated ``muse_code_msp`` shapes at runtime — plain dicts
+carrying at least ``itemId`` and ``revision`` (the algebraic precondition the
+rules need). The store reads only those two members, so it stays
+wire-shape-blind exactly as the TS ``ItemStore`` is (INV-638-01/02); the
+``SessionFold`` binding supplies wire-aware probes where a rule needs one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, List, Mapping
+
+from ..errors import MuseSessionDiscardedError
+
+# The store's item view: a wire item is a dict at runtime. Reading only
+# `itemId`/`revision` here keeps the store wire-shape-blind (INV-638-01).
+ItemLike = Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class Inserted:
+    """A first sighting: the item was inserted."""
+
+    item_id: str
+
+
+@dataclass(frozen=True)
+class Replaced:
+    """A strictly higher revision replaced the held item (INV-003)."""
+
+    item_id: str
+    from_revision: int
+    to_revision: int
+
+
+@dataclass(frozen=True)
+class IgnoredStaleRevision:
+    """A stale or replayed re-emission. The store did not change (INV-003)."""
+
+    item_id: str
+    held: int
+    offered: int
+
+
+ItemApplyOutcome = Inserted | Replaced | IgnoredStaleRevision
+"""What an apply did — enough for a consumer to render without re-diffing."""
+
+
+@dataclass(frozen=True)
+class Appended:
+    """A delta appended to a held item's field accumulator."""
+
+    item_id: str
+    field: str
+    length: int
+
+
+@dataclass(frozen=True)
+class BufferedForAbsentItem:
+    """A delta for an item the store does not hold.
+
+    Deltas are a streaming optimization and are never a fold's only source
+    of a fact (tdd SS4.7.3), so this is buffered against the item's arrival
+    rather than dropped or treated as an error.
+    """
+
+    item_id: str
+    field: str
+
+
+DeltaApplyOutcome = Appended | BufferedForAbsentItem
+"""What a delta did. Deltas bump no revision (tdd SS4.4.1)."""
+
+
+@dataclass(frozen=True)
+class TerminalUnknownItemAnnotation:
+    """Client-only annotation required when an ephemeral host dies abnormally."""
+
+    item_id: str
+
+
+def _item_id(item: ItemLike) -> str:
+    return str(item["itemId"])
+
+
+def _revision(item: ItemLike) -> int:
+    revision = item["revision"]
+    if not isinstance(revision, int):
+        raise TypeError(f"item revision is not an integer: {revision!r}")
+    return revision
+
+
+class ItemStore:
+    """Items in first-opened order (tdd SS4.9.1), each at its latest revision.
+
+    Holds per-field delta accumulators beside the items, and the
+    terminal-unknown annotation set an ephemeral host death produces.
+    """
+
+    def __init__(self) -> None:
+        """Create an empty store."""
+        self._items: dict[str, ItemLike] = {}
+        # item id -> field path -> accumulated text.
+        self._deltas: dict[str, dict[str, str]] = {}
+        # First-opened order; an item id appears exactly once.
+        self._order: list[str] = []
+        self._terminal_unknown: set[str] = set()
+        self._ephemeral_session_discarded = False
+
+    def apply(self, item: ItemLike) -> ItemApplyOutcome:
+        """Apply an ``item/started`` | ``item/updated`` | ``item/completed`` payload.
+
+        Replace iff the incoming revision is strictly higher (INV-003).
+
+        Args:
+            item: The wire item object, verbatim.
+
+        Returns:
+            What the apply did.
+
+        Raises:
+            MuseSessionDiscardedError: The ephemeral session was discarded.
+        """
+        self._assert_session_active()
+        item_id = _item_id(item)
+        held = self._items.get(item_id)
+        if held is None:
+            self._items[item_id] = item
+            self._order.append(item_id)
+            return Inserted(item_id)
+        held_revision = _revision(held)
+        offered = _revision(item)
+        if offered <= held_revision:
+            return IgnoredStaleRevision(item_id, held=held_revision, offered=offered)
+        self._items[item_id] = item
+        return Replaced(item_id, from_revision=held_revision, to_revision=offered)
+
+    def apply_delta(
+        self, item_id: str, delta: str, field: str = "text"
+    ) -> DeltaApplyOutcome:
+        """Apply an ``item/delta``: a lossless append to a field accumulator.
+
+        The concatenation of all deltas for a field path equals that field's
+        value on the final ``item/completed`` object (INV-004, tdd SS4.3.1).
+
+        Args:
+            item_id: The delta's item.
+            delta: The appended text, verbatim.
+            field: The streamed field path (wire default ``"text"``).
+
+        Returns:
+            ``Appended`` for a held item, ``BufferedForAbsentItem`` otherwise.
+
+        Raises:
+            MuseSessionDiscardedError: The ephemeral session was discarded.
+        """
+        self._assert_session_active()
+        fields = self._deltas.setdefault(item_id, {})
+        fields[field] = fields.get(field, "") + delta
+        if item_id not in self._items:
+            return BufferedForAbsentItem(item_id, field)
+        return Appended(item_id, field, length=len(fields[field]))
+
+    def accumulated(self, item_id: str, field: str = "text") -> str | None:
+        """The accumulated delta text for a field path, or ``None`` if none."""
+        fields = self._deltas.get(item_id)
+        return None if fields is None else fields.get(field)
+
+    def accumulated_fields(self, item_id: str) -> List[str]:
+        """Every field path that has accumulated deltas for this item, sorted."""
+        fields = self._deltas.get(item_id)
+        return [] if fields is None else sorted(fields)
+
+    def get(self, item_id: str) -> ItemLike | None:
+        """The held item at its latest revision, or ``None``."""
+        return self._items.get(item_id)
+
+    def has(self, item_id: str) -> bool:
+        """Whether the store holds this item."""
+        return item_id in self._items
+
+    def list(self) -> List[ItemLike]:
+        """Items in first-opened order (tdd SS4.9.1)."""
+        return [self._items[item_id] for item_id in self._order if item_id in self._items]
+
+    def last_opened_item_id(self) -> str | None:
+        """The id of the most recently opened item, or ``None`` when empty."""
+        return self._order[-1] if self._order else None
+
+    @property
+    def size(self) -> int:
+        """How many items the store holds."""
+        return len(self._items)
+
+    def seed(self, items: Iterable[ItemLike]) -> None:
+        """Seed from a snapshot's ``state.items`` (tdd SS4.9.1).
+
+        Seeding REPLACES the store — a snapshot is authoritative (tdd SS4.9),
+        never merged into stale local state. Delta accumulators are
+        intentionally NOT seeded: a snapshot carries streamed fields at their
+        accumulated-so-far values on the item itself, and ``view/page`` never
+        replays ephemeral-sourced deltas (tdd SS4.7.3).
+
+        Args:
+            items: Every item at its latest revision, in first-opened order.
+
+        Raises:
+            MuseSessionDiscardedError: The ephemeral session was discarded.
+        """
+        self._assert_session_active()
+        self._items.clear()
+        self._deltas.clear()
+        self._terminal_unknown.clear()
+        self._order.clear()
+        for item in items:
+            item_id = _item_id(item)
+            if item_id not in self._items:
+                self._order.append(item_id)
+            self._items[item_id] = item
+
+    def mark_ephemeral_host_death(
+        self, is_in_progress: Callable[[ItemLike], bool]
+    ) -> List[TerminalUnknownItemAnnotation]:
+        """Permanently discard an ephemeral session after abnormal host death.
+
+        The last wire item remains byte-for-byte intact: terminal-unknown is a
+        client display annotation, never a fabricated ``item/completed`` or
+        wire status (SS2.13.3b / SS4.4.3). Further events and snapshot seeding
+        are refused because this session has no resume surface.
+
+        Args:
+            is_in_progress: The wire-aware probe (the store never knows wire
+                shapes, INV-638-01); the ``SessionFold`` binding passes
+                ``item["status"] == "inProgress"`` against the generated
+                ``Item``.
+
+        Returns:
+            The terminal-unknown annotations, in first-opened item order.
+        """
+        if not self._ephemeral_session_discarded:
+            for item in self._items.values():
+                if is_in_progress(item):
+                    self._terminal_unknown.add(_item_id(item))
+            self._ephemeral_session_discarded = True
+        return [
+            TerminalUnknownItemAnnotation(item_id)
+            for item_id in self._order
+            if item_id in self._terminal_unknown
+        ]
+
+    def is_terminal_unknown(self, item_id: str) -> bool:
+        """Whether this item carries the terminal-unknown annotation."""
+        return item_id in self._terminal_unknown
+
+    @property
+    def ephemeral_session_discarded(self) -> bool:
+        """Whether an ephemeral host death discarded this session."""
+        return self._ephemeral_session_discarded
+
+    def _assert_session_active(self) -> None:
+        if self._ephemeral_session_discarded:
+            raise MuseSessionDiscardedError(
+                "ephemeral session was discarded after abnormal host death"
+            )