contract.py 3.2 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374
  1. """Connection contract: the states a target moves through, who may cause each move, and the
  2. reasons an operation settles. ``operation.py`` enforces it; the desktop reads a generated copy.
  3. A `str` enum so payloads serialise to the bare value and the TypeScript side sees literal unions."""
  4. from __future__ import annotations
  5. from enum import Enum
  6. from typing import Dict, Optional, Tuple
  7. class TargetState(str, Enum):
  8. pending = "pending"
  9. initiated = "initiated"
  10. connected = "connected"
  11. skipped = "skipped"
  12. failed = "failed"
  13. expired = "expired"
  14. # Stamped by settle() on every unresolved target; never a transition target.
  15. not_connected = "not_connected"
  16. class Actor(str, Enum):
  17. user = "user"
  18. backend_watcher = "backend_watcher"
  19. clock = "clock"
  20. class SettleReason(str, Enum):
  21. all_resolved = "all_resolved"
  22. continue_ = "continue"
  23. deadline = "deadline"
  24. interrupt = "interrupt"
  25. KINDS: tuple[str, ...] = ("connector", "mcp", "plugin", "skill")
  26. RESOLVED_STATES = frozenset({TargetState.connected, TargetState.skipped})
  27. # A failed catalog row is done as well: the host already ran the install and the row carries the
  28. # reason. Counting it as open held the model's turn until the deadline while nobody clicked. Try
  29. # again still works while another row keeps the operation open, and the failed row keeps its state
  30. # and reason when the operation settles.
  31. _RESOLVED_BY_KIND = {kind: RESOLVED_STATES | {TargetState.failed} for kind in ("plugin", "skill")}
  32. def resolves(kind: str, state: TargetState) -> bool:
  33. return state in _RESOLVED_BY_KIND.get(kind, RESOLVED_STATES)
  34. _S, _A = TargetState, Actor
  35. # (kind, from) -> {to: the only actor allowed to cause it}. Every `connected` is witnessed by the
  36. # backend: the gateway's account list for a managed target, the install / enable / OAuth worker for
  37. # an MCP one. The card can only skip a target, or ask for a failed one to be run again.
  38. TRANSITIONS: dict[tuple[str, TargetState], dict[TargetState, Actor]] = {
  39. ("connector", _S.pending): {_S.initiated: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
  40. ("connector", _S.initiated): {
  41. _S.connected: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.expired: _A.clock, _S.skipped: _A.user,
  42. },
  43. ("connector", _S.failed): {_S.initiated: _A.user, _S.skipped: _A.user},
  44. ("connector", _S.expired): {_S.initiated: _A.user, _S.skipped: _A.user},
  45. ("mcp", _S.pending): {_S.initiated: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
  46. ("mcp", _S.initiated): {_S.connected: _A.backend_watcher, _S.failed: _A.backend_watcher, _S.skipped: _A.user},
  47. ("mcp", _S.failed): {_S.initiated: _A.user, _S.skipped: _A.user},
  48. }
  49. # ``manage_catalog`` rows install like an MCP entry: approve starts the host's install, the install
  50. # worker witnesses ``connected``, Try again re-runs a failed row.
  51. for _kind in ("plugin", "skill"):
  52. for (_k, _from), _edges in list(TRANSITIONS.items()):
  53. if _k == "mcp":
  54. TRANSITIONS[(_kind, _from)] = dict(_edges)
  55. def allowed(kind: str, current: TargetState, to: TargetState) -> Optional[Actor]:
  56. return TRANSITIONS.get((kind, current), {}).get(to)