session_contract.py 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. """Public session authority contract; live execution state never crosses this boundary."""
  2. from dataclasses import dataclass, field
  3. from typing import Literal, Mapping, Protocol
  4. JsonObject = Mapping[str, object]
  5. # Authenticated local WebSocket family, separate from the legacy Desktop API contract.
  6. CANONICAL_GATEWAY_PROTOCOL = 'hermes-gateway-v1'
  7. @dataclass(frozen=True)
  8. class SessionActor:
  9. subject: str
  10. profile_id: str
  11. capabilities: frozenset[str]
  12. transport_id: str
  13. @dataclass(frozen=True)
  14. class SessionRef:
  15. profile_id: str
  16. session_id: str
  17. @dataclass(frozen=True)
  18. class SessionHandle:
  19. ref: SessionRef
  20. instance_id: str
  21. authority_epoch: int
  22. revision: int
  23. execution_generation: int
  24. execution_state: Literal["idle", "running", "waiting", "unknown", "terminal"]
  25. @dataclass(frozen=True)
  26. class SessionCreate:
  27. request_id: str
  28. cwd: str
  29. source: str
  30. policy: JsonObject
  31. @dataclass(frozen=True)
  32. class Submission:
  33. request_id: str
  34. ref: SessionRef
  35. payload: JsonObject
  36. intent: Literal["queue", "steer", "redirect"]
  37. @dataclass(frozen=True)
  38. class AdmissionReceipt:
  39. admission_id: str
  40. ref: SessionRef
  41. sequence: int
  42. status: Literal["queued", "started", "unknown", "terminal"]
  43. outcome: str | None
  44. authority_epoch: int
  45. execution_generation: int | None
  46. @dataclass(frozen=True)
  47. class PendingAdmission(AdmissionReceipt):
  48. input_id: str
  49. text: str
  50. # The queued-row verbs this owner serves for the row (``steer`` / ``replace``); empty otherwise.
  51. controls: list[str] = field(default_factory=list)
  52. # A queued admission in transfer to the running turn (``prompt.steer_queued``): it reads ``started``
  53. # but goes back to its queue place if its text never reached that turn.
  54. steering: bool = False
  55. @dataclass(frozen=True)
  56. class SubscriptionSnapshot:
  57. subscription_id: str
  58. handle: SessionHandle
  59. replay_epoch: str
  60. last_sequence: int
  61. history: tuple[JsonObject, ...]
  62. pending: tuple[PendingAdmission, ...]
  63. prompts: tuple[JsonObject, ...]
  64. # The physical transcript a history-less attach resolved under the stream lock (``history=False``).
  65. transcript_target: str | None = None
  66. class SessionAuthority(Protocol):
  67. async def create(self, actor: SessionActor, request: SessionCreate) -> SessionHandle: ...
  68. async def resolve(self, actor: SessionActor, ref: SessionRef) -> SessionHandle: ...
  69. async def attach(self, actor: SessionActor, ref: SessionRef, *, history: bool = True,
  70. replay_from: tuple[str, int] | None = None) -> SubscriptionSnapshot: ...
  71. async def detach(self, actor: SessionActor, subscription_id: str, *, end_reason: str | None = None) -> None: ...
  72. async def submit(self, actor: SessionActor, request: Submission) -> AdmissionReceipt: ...
  73. async def receipt(self, actor: SessionActor, ref: SessionRef, admission_id: str) -> AdmissionReceipt: ...
  74. async def cancel_queued(self, actor: SessionActor, ref: SessionRef, admission_id: str) -> AdmissionReceipt: ...
  75. async def interrupt(self, actor: SessionActor, ref: SessionRef, generation: int) -> SessionHandle: ...
  76. async def respond(self, actor: SessionActor, ref: SessionRef, generation: int,
  77. prompt_id: str, response: JsonObject) -> JsonObject: ...
  78. async def mutate(self, actor: SessionActor, ref: SessionRef, revision: int,
  79. request_id: str, action: str, arguments: JsonObject) -> SessionHandle: ...