| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374 |
- """Connection contract: the states a target moves through, who may cause each move, and the
- reasons an operation settles. ``operation.py`` enforces it; the desktop reads a generated copy.
- A `str` enum so payloads serialise to the bare value and the TypeScript side sees literal unions."""
- from __future__ import annotations
- from enum import Enum
- from typing import Dict, Optional, Tuple
- class TargetState(str, Enum):
- pending = "pending"
- initiated = "initiated"
- connected = "connected"
- skipped = "skipped"
- failed = "failed"
- expired = "expired"
- # Stamped by settle() on every unresolved target; never a transition target.
- not_connected = "not_connected"
- class Actor(str, Enum):
- user = "user"
- backend_watcher = "backend_watcher"
- clock = "clock"
- class SettleReason(str, Enum):
- all_resolved = "all_resolved"
- continue_ = "continue"
- deadline = "deadline"
- interrupt = "interrupt"
- KINDS: tuple[str, ...] = ("connector", "mcp", "plugin", "skill")
- RESOLVED_STATES = frozenset({TargetState.connected, TargetState.skipped})
- # A failed catalog row is done as well: the host already ran the install and the row carries the
- # reason. Counting it as open held the model's turn until the deadline while nobody clicked. Try
- # again still works while another row keeps the operation open, and the failed row keeps its state
- # and reason when the operation settles.
- _RESOLVED_BY_KIND = {kind: RESOLVED_STATES | {TargetState.failed} for kind in ("plugin", "skill")}
- def resolves(kind: str, state: TargetState) -> bool:
- return state in _RESOLVED_BY_KIND.get(kind, RESOLVED_STATES)
- _S, _A = TargetState, Actor
- # (kind, from) -> {to: the only actor allowed to cause it}. Every `connected` is witnessed by the
- # backend: the gateway's account list for a managed target, the install / enable / OAuth worker for
- # an MCP one. The card can only skip a target, or ask for a failed one to be run again.
- TRANSITIONS: dict[tuple[str, TargetState], dict[TargetState, Actor]] = {
- ("connector", _S.pending): {_S.initiated: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
- ("connector", _S.initiated): {
- _S.connected: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.expired: _A.clock, _S.skipped: _A.user,
- },
- ("connector", _S.failed): {_S.initiated: _A.user, _S.skipped: _A.user},
- ("connector", _S.expired): {_S.initiated: _A.user, _S.skipped: _A.user},
- ("mcp", _S.pending): {_S.initiated: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
- ("mcp", _S.initiated): {_S.connected: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
- ("mcp", _S.failed): {_S.initiated: _A.user, _S.skipped: _A.user},
- }
- # ``manage_catalog`` rows install like an MCP entry: approve starts the host's install, the install
- # worker witnesses ``connected``, Try again re-runs a failed row.
- for _kind in ("plugin", "skill"):
- for (_k, _from), _edges in list(TRANSITIONS.items()):
- if _k == "mcp":
- TRANSITIONS[(_kind, _from)] = dict(_edges)
- def allowed(kind: str, current: TargetState, to: TargetState) -> Optional[Actor]:
- return TRANSITIONS.get((kind, current), {}).get(to)
|