approval_transport.py 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. """Host-owned contract for plugin-provided human approval transports.
  2. Transports only present an immutable, redacted request and return a correlated human decision. They
  3. do not participate in command detection or authorization policy. The host validates scope, request
  4. binding, and timeout fail-closed.
  5. """
  6. from __future__ import annotations
  7. import asyncio
  8. import hashlib
  9. import inspect
  10. import json
  11. import logging
  12. import queue
  13. import threading
  14. import time
  15. import uuid
  16. from dataclasses import dataclass
  17. from typing import Awaitable, Callable, Literal
  18. logger = logging.getLogger(__name__)
  19. _MAX_ACTIVE_TRANSPORT_WORKERS = 8
  20. _transport_worker_slots = threading.BoundedSemaphore(_MAX_ACTIVE_TRANSPORT_WORKERS)
  21. ApprovalChoice = Literal["once", "session", "always", "deny"]
  22. ApprovalPresentFn = Callable[["ApprovalRequest"], "ApprovalDecision | Awaitable[ApprovalDecision]"]
  23. @dataclass(frozen=True)
  24. class ApprovalDecision:
  25. """A transport response bound to one exact host-created request."""
  26. request_id: str
  27. request_digest: str
  28. choice: str
  29. @dataclass(frozen=True)
  30. class ApprovalRequest:
  31. """Immutable, display-only approval request passed to a transport plugin."""
  32. schema_version: int
  33. request_id: str
  34. digest: str
  35. command: str
  36. description: str
  37. pattern_key: str
  38. pattern_keys: tuple[str, ...]
  39. surface: str
  40. timeout_seconds: float
  41. allowed_choices: tuple[ApprovalChoice, ...]
  42. @classmethod
  43. def create(
  44. cls, *, command: str, description: str, pattern_key: str, pattern_keys: tuple[str, ...],
  45. session_key: str, surface: str, allow_session: bool, allow_permanent: bool,
  46. timeout_seconds: float = 300,
  47. ) -> ApprovalRequest:
  48. choices: list[ApprovalChoice] = ["once"]
  49. if allow_session:
  50. choices.append("session")
  51. if allow_permanent:
  52. choices.append("always")
  53. choices.append("deny")
  54. fields = dict(
  55. schema_version=1, request_id=uuid.uuid4().hex, command=command,
  56. description=description, pattern_key=pattern_key, pattern_keys=list(pattern_keys),
  57. surface=surface, timeout_seconds=timeout_seconds, allowed_choices=choices,
  58. )
  59. canonical = json.dumps({**fields, "session_key": session_key}, sort_keys=True, separators=(",", ":"))
  60. digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
  61. return cls(**{**fields, "pattern_keys": pattern_keys, "allowed_choices": tuple(choices)}, digest=digest)
  62. def respond(self, choice: ApprovalChoice | str) -> ApprovalDecision:
  63. """Build the correlated response a transport should return."""
  64. return ApprovalDecision(self.request_id, self.digest, choice)
  65. @dataclass(frozen=True)
  66. class ApprovalTransportResult:
  67. """Normalized host result. Any failure is represented as a denial."""
  68. choice: ApprovalChoice
  69. failure: str | None = None
  70. @dataclass(frozen=True)
  71. class RegisteredApprovalTransport:
  72. """Plugin-owned registration retained by one profile's PluginManager."""
  73. name: str
  74. present: ApprovalPresentFn
  75. plugin_id: str
  76. profile_home: str
  77. def _deny(failure: str) -> ApprovalTransportResult:
  78. return ApprovalTransportResult("deny", failure)
  79. def invoke_approval_transport(
  80. present: ApprovalPresentFn, request: ApprovalRequest, *, timeout_seconds: float,
  81. poll_interval: float = 1.0, on_poll: Callable[[], None] | None = None,
  82. is_interrupted: Callable[[], bool] | None = None,
  83. ) -> ApprovalTransportResult:
  84. """Run a sync or async transport on a bounded daemon worker.
  85. Async callbacks are awaited with ``asyncio.run`` on that worker, never on a gateway or TUI event
  86. loop. A callback must return before the host timeout; late results are discarded and cannot
  87. authorize another request.
  88. """
  89. if not _transport_worker_slots.acquire(blocking=False):
  90. logger.warning("Approval transport worker capacity exhausted")
  91. return _deny("busy")
  92. results: queue.Queue[tuple[str, object, float]] = queue.Queue(maxsize=1)
  93. deadline = time.monotonic() + max(float(timeout_seconds), 0.0)
  94. async def _await_value(value):
  95. return await value
  96. def _run() -> None:
  97. try:
  98. value = present(request)
  99. if inspect.isawaitable(value):
  100. value = asyncio.run(_await_value(value))
  101. results.put_nowait(("result", value, time.monotonic()))
  102. except BaseException as exc: # fail closed even for unusual callback exits
  103. try:
  104. results.put_nowait(("error", exc, time.monotonic()))
  105. except queue.Full:
  106. pass
  107. finally:
  108. _transport_worker_slots.release()
  109. worker = threading.Thread(target=_run, name=f"approval-transport-{request.request_id[:8]}", daemon=True)
  110. try:
  111. worker.start()
  112. except BaseException:
  113. _transport_worker_slots.release()
  114. logger.warning("Could not start approval transport worker")
  115. return _deny("error")
  116. while True:
  117. if is_interrupted is not None and is_interrupted():
  118. logger.info("Approval transport wait interrupted for %s", request.request_id)
  119. return _deny("interrupted")
  120. remaining = deadline - time.monotonic()
  121. if remaining <= 0:
  122. logger.warning("Approval transport timed out for request %s", request.request_id)
  123. return _deny("timeout")
  124. try:
  125. kind, value, completed_at = results.get(timeout=min(max(float(poll_interval), 0.001), remaining))
  126. break
  127. except queue.Empty:
  128. if on_poll is not None:
  129. try:
  130. on_poll()
  131. except Exception:
  132. logger.debug("Approval transport poll callback failed", exc_info=True)
  133. failure = _validate_decision(kind, value, completed_at, deadline, request)
  134. return _deny(failure) if failure is not None else ApprovalTransportResult(value.choice)
  135. def _validate_decision(kind, value, completed_at, deadline, request) -> str | None:
  136. """Return the failure code for a worker result, or ``None`` when the decision is valid."""
  137. rid = request.request_id
  138. if completed_at > deadline:
  139. logger.warning("Approval transport timed out for request %s", rid)
  140. return "timeout"
  141. if kind == "error":
  142. logger.warning("Approval transport failed for request %s", rid)
  143. return "error"
  144. if not isinstance(value, ApprovalDecision):
  145. logger.warning("Approval transport returned an invalid decision type")
  146. return "invalid"
  147. if value.request_id != rid or value.request_digest != request.digest:
  148. logger.warning("Approval transport returned a stale or mismatched decision")
  149. return "stale"
  150. if value.choice not in request.allowed_choices:
  151. logger.warning("Approval transport returned a disallowed choice")
  152. return "invalid"
  153. return None