@withgateway/sdk 0.3.3 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -0,0 +1,174 @@
1
+ """``Admission``: how many requests run on one version at once, and how many wait.
2
+
3
+ Every session of a version is served by one process (its version worker, or the
4
+ host itself for a world with no code of its own), so a burst on a version is a
5
+ burst on that process. The host admits a version's requests a few at a time and
6
+ one per session (a session's store answers one request at a time anyway); the
7
+ rest wait their turn in the order they came, up to a bound. A request past the
8
+ bound, or one whose turn did not come in time, is refused ``busy`` with when to
9
+ come back, so a burst queues or is told to retry and the process never holds
10
+ more requests than it has room for. A request held outside the queue (its session moving to
11
+ another host) is counted against the same bounds (:meth:`Admission.waiting`).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import threading
17
+ import time
18
+ from collections import Counter, deque
19
+ from collections.abc import Iterator
20
+ from contextlib import contextmanager
21
+ from dataclasses import dataclass
22
+
23
+ from .validation import fail
24
+
25
+ VERSION_SLOTS = 8
26
+ SESSION_SLOTS = 1
27
+ QUEUE_DEPTH = 256
28
+ #: A session's own share of the waiting, so one session's burst cannot fill its version's queue.
29
+ SESSION_QUEUE_DEPTH = 32
30
+ #: With a call's own budget it stays under the platform's 60 s (``conformance/world-sessions.json``).
31
+ QUEUE_WAIT_S = 10.0
32
+ RETRY_AFTER_S = 1
33
+ BUSY = "busy"
34
+
35
+
36
+ def _less(counter: Counter, key: object) -> None:
37
+ counter[key] -= 1
38
+ if counter[key] <= 0:
39
+ del counter[key]
40
+
41
+
42
+ @dataclass(eq=False)
43
+ class _Turn:
44
+ version: str
45
+ session: str
46
+ started: float | None = None
47
+
48
+
49
+ class Admission:
50
+ """Turns on each version, first come first served within the version's and
51
+ each session's slots; another version never waits."""
52
+
53
+ def __init__(
54
+ self,
55
+ *,
56
+ slots: int = VERSION_SLOTS,
57
+ per_session: int = SESSION_SLOTS,
58
+ queue: int = QUEUE_DEPTH,
59
+ session_queue: int = SESSION_QUEUE_DEPTH,
60
+ wait_s: float = QUEUE_WAIT_S,
61
+ retry_after_s: int = RETRY_AFTER_S,
62
+ ) -> None:
63
+ self.slots = slots
64
+ self.per_session = per_session
65
+ self.queue = queue
66
+ self.session_queue = session_queue
67
+ self.wait_s = wait_s
68
+ self.retry_after_s = retry_after_s
69
+ self._lock = threading.Lock()
70
+ self._changed = threading.Condition(self._lock)
71
+ self._running: Counter[str] = Counter()
72
+ self._holding: dict[tuple[str, str], list[_Turn]] = {}
73
+ self._waiting: dict[str, deque[_Turn]] = {}
74
+ self._outside: Counter[str] = Counter()
75
+ self._outside_by: Counter[tuple[str, str]] = Counter()
76
+
77
+ @contextmanager
78
+ def turn(self, version: str, session: str) -> Iterator[None]:
79
+ """Hold one of ``version``'s slots for ``session`` while the block runs; refused
80
+ ``busy`` (a :class:`ContractError` carrying ``retryAfter``) when none comes."""
81
+ turn = self._enter(_Turn(version, session))
82
+ try:
83
+ yield
84
+ finally:
85
+ self._leave(turn)
86
+
87
+ @contextmanager
88
+ def waiting(self, version: str, session: str) -> Iterator[None]:
89
+ """Count a request waiting outside the queue against ``version``'s and ``session``'s waiting
90
+ bounds while the block runs; refused ``busy`` past them, as a queued request would be."""
91
+ with self._lock:
92
+ self._outside[version] += 1
93
+ self._outside_by[(version, session)] += 1
94
+ if self._overfull(version, session):
95
+ self._unwait(version, session)
96
+ self._refuse(version, "too many requests are waiting")
97
+ try:
98
+ yield
99
+ finally:
100
+ with self._lock:
101
+ self._unwait(version, session)
102
+
103
+ def _unwait(self, version: str, session: str) -> None:
104
+ _less(self._outside, version)
105
+ _less(self._outside_by, (version, session))
106
+
107
+ def held_ages(self) -> dict[str, float]:
108
+ """Each session holding a turn now, with how long its oldest has run, in seconds."""
109
+ now = time.monotonic()
110
+ with self._lock:
111
+ return {
112
+ session: now - min(turn.started for turn in turns if turn.started is not None)
113
+ for (_, session), turns in self._holding.items()
114
+ if turns
115
+ }
116
+
117
+ def _enter(self, turn: _Turn) -> _Turn:
118
+ with self._lock:
119
+ queue = self._waiting.setdefault(turn.version, deque())
120
+ queue.append(turn)
121
+ self._admit(turn.version)
122
+ if turn.started is None and self._overfull(turn.version, turn.session):
123
+ queue.remove(turn)
124
+ self._refuse(turn.version, f"{len(queue)} requests are waiting")
125
+ deadline = time.monotonic() + self.wait_s
126
+ while turn.started is None:
127
+ left = deadline - time.monotonic()
128
+ if left <= 0:
129
+ queue.remove(turn)
130
+ self._refuse(turn.version, f"no turn came within {self.wait_s:g} s")
131
+ self._changed.wait(left)
132
+ return turn
133
+
134
+ def _overfull(self, version: str, session: str) -> bool:
135
+ queue = self._waiting.get(version, deque())
136
+ mine = sum(waiting.session == session for waiting in queue) + self._outside_by[(version, session)]
137
+ return len(queue) + self._outside[version] > self.queue or mine > self.session_queue
138
+
139
+ def _leave(self, turn: _Turn) -> None:
140
+ with self._lock:
141
+ key = (turn.version, turn.session)
142
+ self._holding[key].remove(turn)
143
+ if not self._holding[key]:
144
+ del self._holding[key]
145
+ self._running[turn.version] -= 1
146
+ if self._running[turn.version] <= 0:
147
+ del self._running[turn.version]
148
+ self._admit(turn.version)
149
+ self._forget(turn.version)
150
+
151
+ def _admit(self, version: str) -> None:
152
+ """Under the lock: give free slots to the earliest waiters whose session has room."""
153
+ queue = self._waiting.get(version, deque())
154
+ for waiting in list(queue):
155
+ if self._running[version] >= self.slots:
156
+ break
157
+ if len(self._holding.get((version, waiting.session), ())) < self.per_session:
158
+ queue.remove(waiting)
159
+ waiting.started = time.monotonic()
160
+ self._running[version] += 1
161
+ self._holding.setdefault((version, waiting.session), []).append(waiting)
162
+ self._changed.notify_all()
163
+
164
+ def _forget(self, version: str) -> None:
165
+ if not self._waiting.get(version) and not self._running[version]:
166
+ self._waiting.pop(version, None)
167
+
168
+ def _refuse(self, version: str, why: str) -> None:
169
+ self._forget(version)
170
+ fail(
171
+ BUSY,
172
+ f"this world's version is busy ({why}); retry after {self.retry_after_s} s",
173
+ retryAfter=self.retry_after_s,
174
+ )