@lmmslab/harness 0.0.0-stage → 0.81.1

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 (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1356 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +232 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. package/python/harness/tui/views.py +434 -0
@@ -0,0 +1,909 @@
1
+ """Observe, decide and deliver one worker command per control period.
2
+
3
+ Single-resource executions take turns and receive the receipts for their own commands. With channels,
4
+ executions advance concurrently, merging their inputs with holds and reflexes before local
5
+ admission. Delayed actions retain their admission and attribution until delivery. The
6
+ worker shield judges every delivered command.
7
+ """
8
+
9
+ import collections
10
+ import contextlib
11
+ import math
12
+ import sys
13
+ import threading
14
+ import time
15
+ import uuid
16
+
17
+ from harness.core import spans
18
+ from harness.runtime.safety.approval import WORKER_APPROVAL_SECONDS
19
+ from harness.runtime.execution import control
20
+ from harness.runtime import events as ev
21
+ from harness.runtime.reactive import rules as reactive
22
+
23
+
24
+ # The clocks a worker profile may name (`clock`).
25
+ CLOCKS = ("steps", "wall", "events")
26
+
27
+
28
+ def delay_ticks(reaction_delay_ms, hz) -> int:
29
+ """The control periods a decision waits before it is sent: `reaction_delay_ms`
30
+ rounded up to whole periods of `hz`."""
31
+ delay = float(reaction_delay_ms or 0.0)
32
+ if not math.isfinite(delay) or delay < 0:
33
+ raise ValueError(f"reaction_delay_ms must be a number of milliseconds >= 0, got {reaction_delay_ms!r}")
34
+ return math.ceil(delay * float(hz) / 1000.0 - 1e-9) if delay else 0
35
+
36
+
37
+ # How often the code waiting for its execution looks for a reason to stop waiting.
38
+ POLL = 0.05
39
+ # How often a wall clock tells the host how its periods went (a tick_periods note).
40
+ PERIODS_NOTE_SECONDS = 10.0
41
+
42
+
43
+ class _Periods:
44
+ """A wall clock's periods since the last tick_periods note: their lengths and parts
45
+ (observe, decide, send), in ms."""
46
+
47
+ PARTS = ("observe", "decide", "send")
48
+
49
+ def __init__(self, period):
50
+ self.period = period
51
+ self.since = time.monotonic()
52
+ self.last = None
53
+ self.lengths, self.parts = [], {name: [] for name in self.PARTS}
54
+
55
+ def begin(self):
56
+ now = time.monotonic()
57
+ if self.last is not None:
58
+ self.lengths.append(now - self.last)
59
+ self.last = self.marked = now
60
+
61
+ def mark(self, name):
62
+ now = time.monotonic()
63
+ self.parts[name].append(now - self.marked)
64
+ self.marked = now
65
+
66
+ def flush(self):
67
+ """The note, when PERIODS_NOTE_SECONDS passed since the last one."""
68
+ if time.monotonic() - self.since < PERIODS_NOTE_SECONDS or not self.lengths:
69
+ return
70
+ lengths = sorted(self.lengths)
71
+
72
+ def ms(values, q=0.5):
73
+ values = sorted(values)
74
+ return round(1000 * values[min(len(values) - 1, int(len(values) * q))], 1) if values else None
75
+ spans.note("tick_periods", periods=len(lengths), target_ms=round(1000 * self.period, 1),
76
+ period_ms={"p50": ms(lengths), "p90": ms(lengths, 0.9), "max": round(1000 * lengths[-1], 1)},
77
+ late=sum(length > 1.5 * self.period for length in lengths),
78
+ **{f"{name}_ms": {"p50": ms(values), "p90": ms(values, 0.9)} for name, values in self.parts.items()})
79
+ self.since = time.monotonic()
80
+ self.lengths, self.parts = [], {name: [] for name in self.PARTS}
81
+
82
+
83
+ class _Entry:
84
+ def __init__(self, steps, parent, owner=None):
85
+ self.steps = steps
86
+ self.parent = parent
87
+ self.owner = owner
88
+ self.picked = False
89
+ self.started = False
90
+ self.trace = None
91
+ self.error = None
92
+ self.cancelled = False
93
+ self.done = threading.Event()
94
+ self.queued = 0
95
+ self.generation = 0
96
+ self.suspended = None
97
+ self.execution_id = uuid.uuid4().hex
98
+ self.plan = []
99
+ self.uses = frozenset()
100
+ self.cameras = self.check = None
101
+ self.fresh = None
102
+ self.change = None
103
+
104
+
105
+ class Tick:
106
+ """The tick of one kernel session (see the module docstring): `run(steps)` runs a
107
+ program entry on it, `start()` begins holding a wall-clock embodiment, `stop()` ends
108
+ it. `ticks` counts the steps it sent."""
109
+
110
+ def __init__(self, session):
111
+ self.session = session
112
+ self.period = POLL if session.profile.get("clock") == "events" else 1.0 / float(session.hz)
113
+ self.clock = str((getattr(session, "profile", None) or {}).get("clock") or "steps")
114
+ if self.clock not in CLOCKS:
115
+ raise ValueError(f"A worker's clock is one of {list(CLOCKS)}, got {self.clock!r}")
116
+ self.delay_ticks = delay_ticks(session.__dict__.get("reaction_delay_ms", 0.0), session.hz)
117
+ self.ticks = self._period = 0
118
+ self._line = collections.deque()
119
+ self._entries = []
120
+ self._changed = threading.Condition()
121
+ self._thread = None
122
+ self._holding = False
123
+ self._stopped = False
124
+ self._due = None
125
+ # Channels (see the module docstring): {name: channel}, empty when the embodiment
126
+ # is one resource; who claims each, the execution that drives each, what each
127
+ # entry holds down, and whether that changed since the last command went out.
128
+ self.channels = dict(getattr(session, "channels", None) or {})
129
+ self._claimed = {}
130
+ self._driving = {}
131
+ self._held = {}
132
+ self._dirty = False
133
+ self._sent_held = None
134
+ self._periods = _Periods(self.period) if self.clock == "wall" else None
135
+
136
+ # What the session calls.
137
+
138
+ def start(self):
139
+ """Run from now on: a wall-clock embodiment is held every period while no entry
140
+ runs (a steps clock only ticks for entries)."""
141
+ with self._changed:
142
+ self._holding = self.clock == "wall"
143
+ if self._holding or self._observes():
144
+ self._wake()
145
+
146
+ def _wake(self):
147
+ """Wake the tick when an observation rule is registered."""
148
+ with self._changed:
149
+ if not self._stopped:
150
+ self._ensure_thread()
151
+ self._changed.notify_all()
152
+
153
+ def stop(self, timeout=5.0):
154
+ """Stop ticking; a program entry still running ends with an error."""
155
+ with self._changed:
156
+ self._stopped = True
157
+ self._changed.notify_all()
158
+ thread = self._thread
159
+ if thread is not None and thread is not threading.current_thread():
160
+ thread.join(timeout)
161
+ for entry in list(self._entries):
162
+ entry.error = RuntimeError("the session closed while the execution ran")
163
+ self._end(entry)
164
+
165
+ def on_thread(self) -> bool:
166
+ """Whether the caller runs on the tick (a controller, a guard)."""
167
+ return self._thread is not None and threading.current_thread() is self._thread
168
+
169
+ def run(self, steps):
170
+ """Run the execution on the tick and return its trace, or raise its error."""
171
+ sys.audit("harness.execution")
172
+ tree = self._tree()
173
+ entry = _Entry(steps, spans.current(), tree.current() if tree is not None else None)
174
+ inline = self.on_thread()
175
+ with self._changed:
176
+ if self._stopped:
177
+ raise RuntimeError("the session's tick has stopped")
178
+ self._entries.append(entry)
179
+ if not inline:
180
+ self._ensure_thread()
181
+ self._changed.notify_all()
182
+ if inline:
183
+ entry.picked = True
184
+ while not entry.done.is_set() and not self._stopped:
185
+ self._wait_turn(idle=entry.suspended is not None)
186
+ self._step([entry])
187
+ if not entry.done.is_set():
188
+ self._fail(entry, RuntimeError("the session closed while the execution ran"))
189
+ else:
190
+ self._wait_entry(entry, tree)
191
+ if entry.error is not None:
192
+ raise entry.error
193
+ return entry.trace
194
+
195
+ def _wait_entry(self, entry, tree):
196
+ try:
197
+ while not entry.done.wait(POLL):
198
+ if tree is None:
199
+ continue
200
+ with self._changed:
201
+ if entry.picked or tree.interruption(entry.owner, take=False) is None:
202
+ continue
203
+ self._entries.remove(entry)
204
+ entry.done.set()
205
+ entry.steps.close()
206
+ tree.check(entry.owner)
207
+ except BaseException:
208
+ entry.cancelled = True
209
+ raise
210
+
211
+ # The loop.
212
+
213
+ def _tree(self):
214
+ """The session's tree of entries (runtime/execution/entries.py), if it has one."""
215
+ return self.session.__dict__.get("_entry_tree")
216
+
217
+ def _ensure_thread(self):
218
+ if self._thread is None:
219
+ self._thread = threading.Thread(target=self._loop, name="harness-tick", daemon=True)
220
+ self._thread.start()
221
+
222
+ def _observes(self, *, stopping=False):
223
+ layer = getattr(self.session, "reactive", None)
224
+ return (layer is not None
225
+ and layer._observes(stopping, getattr(self.session, "observation_event_kinds", ()))
226
+ and not self.session.state.get("ended"))
227
+
228
+ def _loop(self):
229
+ while True:
230
+ with self._changed:
231
+ while not (self._stopped or self._entries or self._holding or self._dirty
232
+ or self._line or self._observes()):
233
+ self._changed.wait()
234
+ if self._stopped:
235
+ return
236
+ entries = list(self._entries)
237
+ if not self.channels:
238
+ suspended = next((entry for entry in entries if entry.suspended is not None), None)
239
+ entries = [suspended] if suspended is not None else entries[:1]
240
+ for entry in entries:
241
+ entry.picked = True
242
+ idle = all(entry.suspended for entry in entries) and (bool(entries) or not self._line)
243
+ self._wait_turn(idle=idle)
244
+ self._step(entries)
245
+
246
+ def _wait_turn(self, idle=False):
247
+ if self.clock != "wall" and not idle:
248
+ return
249
+ now = time.monotonic()
250
+ if self._due is not None and now < self._due:
251
+ time.sleep(self._due - now)
252
+ now = time.monotonic()
253
+ self._due = self._due + self.period if self._due is not None and self._due + self.period > now \
254
+ else now + self.period
255
+
256
+ def _end(self, entry):
257
+ with self._changed:
258
+ self._undrive(entry)
259
+ if entry in self._entries:
260
+ self._entries.remove(entry)
261
+ self._cancel_receipt(entry, "execution ended")
262
+ entry.done.set()
263
+ self._changed.notify_all()
264
+
265
+ def _cancel_receipt(self, entry, reason):
266
+ action, entry.suspended = entry.suspended, None
267
+ if action is None:
268
+ return
269
+ if action.refusal is None:
270
+ action.pending.cancel(reason)
271
+ else:
272
+ identifier = action.refusal["approval"]["id"]
273
+ with control._answered:
274
+ control._physical.discard(identifier)
275
+ control._answers.pop(identifier, None)
276
+ spans.note("physical_cancel", id=identifier, reason=reason)
277
+
278
+ # Channels (see the module docstring).
279
+
280
+ def known(self, names) -> list:
281
+ """`names` (a name or a list) as channel names of the embodiment (ValueError for
282
+ one it does not declare)."""
283
+ names = [names] if isinstance(names, str) else list(names or [])
284
+ unknown = [name for name in names if name not in self.channels]
285
+ if unknown:
286
+ raise ValueError(f"no channel {unknown[0]!r}: the channels are {sorted(self.channels)}")
287
+ return names
288
+
289
+ def conflicts(self, entry, names, *, claiming=False) -> dict:
290
+ """{channel: id of the entry that has it} for the channels of `names` that `entry`
291
+ cannot use now: another entry drives or holds it, or claimed it (a claim of an
292
+ entry above `entry` leaves it to the entries below)."""
293
+ above = set(entry.lineage()) if entry is not None and not claiming else set()
294
+ found = {}
295
+ with self._changed:
296
+ for name in names:
297
+ claimed = self._claimed.get(name)
298
+ if claimed is not None and claimed is not entry and claimed not in above:
299
+ found[name] = claimed.id
300
+ continue
301
+ driving = self._driving.get(name)
302
+ if driving is not None and driving.owner is not entry:
303
+ found[name] = getattr(driving.owner, "id", None)
304
+ continue
305
+ for owner, held in self._held.items():
306
+ if owner is not entry and name in self.session._channels_of(held):
307
+ found[name] = owner.id
308
+ break
309
+ return found
310
+
311
+ def claim(self, entry, names) -> dict:
312
+ """`entry` claims the channels `names` until it releases them or ends: {channel:
313
+ holder id} of those it cannot have (then it claims none), else {}."""
314
+ names = self.known(names)
315
+ with self._changed:
316
+ found = self.conflicts(entry, names, claiming=True)
317
+ if not found:
318
+ self._claimed.update({name: entry for name in names})
319
+ return found
320
+
321
+ def release(self, entry, names=None) -> None:
322
+ """`entry` lets go of the channels `names` (None: all it has): its claims, and the
323
+ keys and buttons it holds down on them, which go up at the next period."""
324
+ with self._changed:
325
+ names = set(self.channels if names is None else self.known(names))
326
+ for name in names:
327
+ if self._claimed.get(name) is entry:
328
+ del self._claimed[name]
329
+ self._let_go(entry, names)
330
+ self._changed.notify_all()
331
+
332
+ def let_go(self, entries) -> None:
333
+ """The keys and buttons `entries` hold down go up at the next period; their claims
334
+ stay (a guard stopped what they do, runtime/execution/session.py)."""
335
+ with self._changed:
336
+ for entry in entries:
337
+ self._let_go(entry, set(self.channels))
338
+ self._changed.notify_all()
339
+
340
+ def _let_go(self, entry, names) -> None:
341
+ """The keys and buttons `entry` holds on the channels `names` go up."""
342
+ held = self._held.get(entry, {})
343
+ self._invalidate_release(entry, lambda fragment: self.session._mask(fragment, names))
344
+ if (kept := self.session._mask(held, names)) != held:
345
+ self._set_held(entry, kept)
346
+
347
+ def board(self) -> dict:
348
+ """Who has each channel now: {channel: {"entry", "how": claimed, driving or
349
+ holding}}, None where nobody does (it is at its default)."""
350
+ with self._changed:
351
+ board = {name: None for name in self.channels}
352
+ for owner, held in self._held.items():
353
+ for name in self.session._channels_of(held):
354
+ board[name] = {"entry": owner.id, "how": "holding"}
355
+ for name, execution in self._driving.items():
356
+ board[name] = {"entry": getattr(execution.owner, "id", None), "how": "driving"}
357
+ for name, owner in self._claimed.items():
358
+ board[name] = {"entry": owner.id, "how": "claimed"}
359
+ return board
360
+
361
+ def _undrive(self, execution):
362
+ for name in [name for name, driving in self._driving.items() if driving is execution]:
363
+ del self._driving[name]
364
+
365
+ def _step(self, entries):
366
+ tree, session = self._tree(), self.session
367
+ layer = getattr(session, "reactive", None)
368
+ due = None
369
+ deliver = False
370
+ try:
371
+ if self._periods is not None:
372
+ self._periods.begin()
373
+ waiting = any(entry.suspended for entry in entries)
374
+ if (self.clock == "wall" or waiting or (not entries and self._observes())
375
+ or (self._line and self._observes(stopping=True))):
376
+ session._observe()
377
+ if session.state.get("ended"):
378
+ self._holding = False
379
+ self._line.clear()
380
+ with self._changed:
381
+ for entry in self._entries:
382
+ entry.queued = 0
383
+ entry.plan.clear()
384
+ self._cancel_receipt(entry, "episode ended")
385
+ budget = reactive.period(layer.budget_seconds) if layer is not None else contextlib.nullcontext()
386
+ with budget:
387
+ if tree is not None and getattr(session, "observation_event_kinds", ()):
388
+ owner = getattr(entries[0].owner, "id", None) if entries else None
389
+ for observed in session._take_observation_events(session.state):
390
+ reactive.emit(tree, owner, "observe", observed, notice=True)
391
+ stopping = self.clock == "wall" and not entries
392
+ if tree is not None and self._observes(stopping=stopping):
393
+ reactive.apply(session, tree, busy=not stopping)
394
+ self._mark("observe")
395
+ parts = []
396
+ for entry in entries:
397
+ try:
398
+ if self._advance(entry, tree):
399
+ break
400
+ except BaseException as error:
401
+ self._fail(entry, error)
402
+ if entry.plan:
403
+ parts.append(_Part(entry, entry.plan.pop(0), last=not entry.plan))
404
+ else:
405
+ action = self._decide(parts, entries, tree)
406
+ if action is not None:
407
+ self._line.append(action)
408
+ for part in action.parts:
409
+ if part.execution is not None:
410
+ part.execution.queued += 1
411
+ if self._line and not any(entry.suspended for entry in entries):
412
+ due = self._line[0] if self._line[0].due <= self._period else None
413
+ if due is not None and self.delay_ticks:
414
+ self._check_delayed(due, tree)
415
+ self._period += 1
416
+ deliver = True
417
+ if deliver:
418
+ if due is not None:
419
+ self._line.popleft()
420
+ self._deliver(due)
421
+ except BaseException as error:
422
+ self._failed_period(entries, error)
423
+ return
424
+ for entry in entries:
425
+ if entry.trace is not None and not entry.queued and entry.suspended is None:
426
+ self._end(entry)
427
+ elif not entry.plan:
428
+ with self._changed:
429
+ self._undrive(entry)
430
+ if self._periods is not None:
431
+ self._periods.flush()
432
+
433
+ def _decide(self, parts, entries, tree):
434
+ if self.session.state.get("ended"):
435
+ self._dirty = False
436
+ return None
437
+ if self.channels:
438
+ command, parts, idle = self._admit(parts, entries, tree)
439
+ else:
440
+ command, idle = (parts[0].part if parts else None), None
441
+ with self._changed:
442
+ dirty, self._dirty = self._dirty, False
443
+ holding = self._holding and not any(entry.suspended is not None for entry in entries)
444
+ if not (dirty or holding or any(part.execution or part.reflex for part in parts)):
445
+ return None
446
+ cameras = self._cameras(parts) if self.channels else parts[0].cameras if parts else None
447
+ return _Action(command, parts, cameras, self._period + self.delay_ticks, idle)
448
+
449
+ @staticmethod
450
+ def _cameras(parts):
451
+ return sorted({camera for part in parts if part.last for camera in (part.cameras or ())}) or None
452
+
453
+ def _admit(self, parts, entries, tree):
454
+ session = self.session
455
+ acts, taken = self._acts(parts + self._holds(), entries, tree)
456
+ while True:
457
+ held = self._holds()
458
+ used = set(taken)
459
+ for act in acts:
460
+ used |= session._channels_of(act.part)
461
+ for part in parts + held:
462
+ part.sent = self.session._mask(part.part, taken)
463
+ idle = self._idle() - used
464
+ command = session._merge([part.sent for part in parts + held + acts], idle)
465
+ verdict = session._admit(command, commit=False)
466
+ if verdict.command is not None:
467
+ command = verdict.command
468
+ break
469
+ blamed = self._blame(parts, held, verdict.reasons[0], acts)
470
+ if blamed is None:
471
+ break
472
+ if blamed.reflex is not None:
473
+ # A reflex's act the shield would reject is left out of this period.
474
+ acts.remove(blamed)
475
+ continue
476
+ reply = {"executed": False, "shield": verdict.to_dict(), "state": dict(session.state)}
477
+ self._settle(blamed, reply, tree)
478
+ if blamed.execution is not None:
479
+ parts.remove(blamed)
480
+ with self._changed:
481
+ self._undrive(blamed.execution)
482
+ return command, parts + held + acts, idle
483
+
484
+ def _check_delayed(self, action, tree):
485
+ for part in action.parts:
486
+ entry = part.execution
487
+ if entry is None or part.generation != entry.generation or entry.check is None:
488
+ continue
489
+ if not self._execution_live(entry):
490
+ continue
491
+ try:
492
+ with spans.under(entry.parent), _acting(tree, entry.owner):
493
+ stop = entry.check()
494
+ if stop is not None:
495
+ self._discard_plan(entry)
496
+ entry.fresh = (stop, self.session.state)
497
+ except BaseException as error:
498
+ self._fail(entry, error)
499
+
500
+ def _deliver(self, due):
501
+ session = self.session
502
+ if self._stopped:
503
+ return
504
+ parts = due.parts if due is not None else []
505
+ with self._changed:
506
+ live, inputs = self._delivery_inputs(parts)
507
+ if parts and not live and not self._holding and not self.channels:
508
+ return
509
+ command = due.command if due is not None else None
510
+ cameras = due.cameras if due is not None else None
511
+ if self.channels:
512
+ if due is None:
513
+ command = session._still(self._sent_held or None)
514
+ elif inputs != [part.sent for part in parts if part.sent]:
515
+ command = session._merge(inputs, due.idle)
516
+ if live != parts:
517
+ cameras = self._cameras(live)
518
+ elif not live or command is None:
519
+ command = session._base_command(session.state)
520
+ self._mark("decide")
521
+ source = live[0].execution if len(parts) == len(live) == 1 and not self.channels else None
522
+ attributable = source is not None and source.check is not None
523
+ if self.channels and due is not None and session.profile.get("action_ids"):
524
+ attributable = bool(live)
525
+ action = due if attributable else None
526
+ try:
527
+ with spans.under(source.parent if source is not None else None), _acting(
528
+ self._tree(), source.owner if source is not None else None):
529
+ reply = self._send(action, command, cameras)
530
+ if isinstance(reply, dict):
531
+ reply = self._receipt(action, reply)
532
+ except BaseException as error:
533
+ self._failed_period([part.execution for part in live if part.execution is not None], error)
534
+ return
535
+ self.ticks += 1
536
+ self._mark("send")
537
+ if (action is not None and source is not None and isinstance(reply, dict)
538
+ and not reply["executed"] and (request := reply.get("approval"))
539
+ and (request.get("retry") is None or request.get("retry") == "host_tick"
540
+ and "sensitive_approval" in getattr(session.env, "host_controls", ())) and spans.connected()):
541
+ with control._answered:
542
+ control._physical.add(request["id"])
543
+ action.refusal = reply
544
+ action.deadline = time.monotonic() + WORKER_APPROVAL_SECONDS
545
+ source.suspended = action
546
+ spans.note("physical_request", request=request)
547
+ return
548
+ if not isinstance(reply, dict):
549
+ if action is None or source is None:
550
+ reply.cancel("the action has no attributable source")
551
+ raise RuntimeError("Only an attributable action may wait for a receipt")
552
+ action.pending = reply
553
+ source.suspended = action
554
+ return
555
+ if self.channels and reply.get("executed"):
556
+ session._admit(command, commit=True)
557
+ self._sent_held = command
558
+ for part in live:
559
+ if part.execution is not None:
560
+ try:
561
+ self._receive(part, reply)
562
+ except BaseException as error:
563
+ self._fail(part.execution, error)
564
+
565
+ def _send(self, action, command, cameras, *, approval_id=None):
566
+ """Return a receipt, or on a trusted scheduler a deferred receipt for `action`.
567
+
568
+ The continuation has nonblocking ready() and cancel(reason). finish(episode, step)
569
+ applies and returns the final receipt (the original refusal on denial) or raises
570
+ on unknown delivery. The host owns the payload, cursor validation and assent.
571
+ """
572
+ dispatch = getattr(self.session, "_dispatch_action", None)
573
+ if action is not None and dispatch is not None:
574
+ if approval_id is not None:
575
+ return dispatch(action.id, command, cameras, approval_id=approval_id)
576
+ return dispatch(action.id, command, cameras)
577
+ return self.session._tick(command, cameras=cameras)
578
+
579
+ def _receipt(self, action, reply):
580
+ if action is None:
581
+ return reply
582
+ expected = None if self.channels and self.session.profile.get("action_ids") else action.id
583
+ if reply.get("action_id", expected) != action.id:
584
+ raise RuntimeError("The worker's receipt belongs to a different action; delivery is unverified")
585
+ return {**reply, "action_id": action.id}
586
+
587
+ def _delivery_inputs(self, parts):
588
+ live, inputs = [], []
589
+ for part in parts:
590
+ sent, entry = part.sent, part.execution
591
+ if entry is not None:
592
+ entry.queued -= 1
593
+ if part.generation != entry.generation or not self._execution_live(entry):
594
+ continue
595
+ elif part.reflex is not None:
596
+ if self.session.reactive.rules.get(part.reflex.name) is not part.reflex:
597
+ continue
598
+ elif self._withdrawn(part.owner):
599
+ continue
600
+ else:
601
+ sent = self._surviving_holds(part.owner, sent)
602
+ live.append(part)
603
+ if sent:
604
+ inputs.append(sent)
605
+ return live, inputs
606
+
607
+ def _execution_live(self, entry):
608
+ return not (entry.done.is_set() or self._interruption(entry, self._tree()))
609
+
610
+ @staticmethod
611
+ def _withdrawn(owner):
612
+ return owner is not None and any(entry._cancel.is_set() for entry in owner.lineage())
613
+
614
+ def _receive(self, part, reply):
615
+ entry = part.execution
616
+ if self._execution_live(entry) and not self._stopped:
617
+ if "action_id" in reply and (record := getattr(self.session, "_record_receipt", None)):
618
+ with spans.under(entry.parent):
619
+ record(part.part, reply)
620
+ self._settle(part, reply)
621
+ else:
622
+ # A late receipt belongs to its original entry and is recorded once.
623
+ detail = {"entry": getattr(entry.owner, "id", None), "span": entry.parent,
624
+ "action_id": reply.get("action_id"), "step": reply["state"]["step"],
625
+ "executed": reply["executed"], "verdict": reply["shield"]["verdict"],
626
+ "delivery": reply.get("delivery")}
627
+ if record := getattr(self.session, "_record_late_receipt", None):
628
+ record(detail)
629
+ else:
630
+ spans.note("late_receipt", **detail)
631
+
632
+ def _settle(self, part, reply, tree=None):
633
+ entry = part.execution
634
+ if entry is None:
635
+ with self._changed:
636
+ self._let_go(part.owner, {part.channel} if part.channel is not None else set(self.channels))
637
+ reactive.emit(tree, getattr(part.owner, "id", None), "hold", ev.input_refusal(
638
+ reply, self.session.state.get("step")))
639
+ return
640
+ accepted = reply.get("executed")
641
+ if not accepted:
642
+ self._discard_plan(entry, refused=True)
643
+ elif self.channels and part.last and any(part.part.get(field) for field in self.session.hold_fields):
644
+ self._dirty = True
645
+ if not accepted or part.last:
646
+ entry.fresh = reply
647
+
648
+ def _mark(self, part):
649
+ if self._periods is not None:
650
+ self._periods.mark(part)
651
+
652
+ def _failed_period(self, entries, error):
653
+ if not entries:
654
+ print(f"harness tick: holding stopped: {type(error).__name__}: {error}", file=sys.stderr)
655
+ self._holding = False
656
+ for entry in entries:
657
+ self._fail(entry, error)
658
+
659
+ def _interruption(self, entry, tree, take=False):
660
+ if entry.cancelled:
661
+ return RuntimeError("the program that ran this execution was interrupted")
662
+ if tree is not None and entry.owner is not None:
663
+ return tree.interruption(entry.owner, take=take)
664
+
665
+ def _advance(self, execution, tree):
666
+ """Advance a generator, or take this period's delivery slot to finish a suspension."""
667
+ if execution.done.is_set():
668
+ return
669
+ if execution.cancelled or execution.trace is None:
670
+ if stop := self._interruption(execution, tree, take=True):
671
+ raise stop
672
+ if waiting := execution.suspended:
673
+ session = self.session
674
+ if self._stopped or session.state.get("ended") or control.pause_requested():
675
+ raise RuntimeError("the suspended action was interrupted")
676
+ with spans.under(execution.parent), _acting(tree, execution.owner):
677
+ stop = execution.check()
678
+ if stop is not None:
679
+ self._cancel_receipt(execution, "stop guard vetoed the action")
680
+ execution.fresh = (stop, session.state)
681
+ return
682
+ answer = None
683
+ if waiting.refusal is not None:
684
+ identifier = waiting.refusal["approval"]["id"]
685
+ answer = control.wait_answer(identifier, poll=0)
686
+ if answer is None and time.monotonic() < waiting.deadline:
687
+ return
688
+ elif not waiting.pending.ready():
689
+ return
690
+ if self._stopped or control.pause_requested():
691
+ raise RuntimeError("the suspended action was interrupted")
692
+ if stop := self._interruption(execution, tree, take=True):
693
+ raise stop
694
+ try:
695
+ with spans.under(execution.parent), _acting(tree, execution.owner):
696
+ if waiting.refusal is None:
697
+ reply = waiting.pending.finish(session.episode_id, session.state["step"])
698
+ else:
699
+ reply = waiting.refusal
700
+ sensitive = reply["approval"].get("retry") == "host_tick"
701
+ current = session.state["step"]
702
+ if answer is not None and not sensitive and current == reply["state"]["step"]:
703
+ session.env.call("physical", op="answer", episode_id=session.episode_id,
704
+ id=identifier, accept=bool(answer.get("accept")),
705
+ remember=answer.get("remember") or "once")
706
+ if answer and answer.get("accept") and (sensitive or current == reply["state"]["step"]):
707
+ if record := getattr(session, "_record_receipt", None):
708
+ record(waiting.command, reply)
709
+ reply = self._send(waiting, waiting.command, waiting.cameras,
710
+ approval_id=identifier if sensitive else None)
711
+ else:
712
+ reason = (f"the user said no: {answer['reason']}" if answer and answer.get("reason")
713
+ else "the user said no" if answer and not answer.get("accept")
714
+ else "the input approval expired or the observation changed")
715
+ for check in reply["shield"]["reasons"]:
716
+ if check.get("approval"):
717
+ check["reason"] += f" ({reason})"
718
+ self._cancel_receipt(execution, "input approval settled")
719
+ reply = self._receipt(waiting, reply)
720
+ execution.suspended = None
721
+ self._receive(waiting.parts[0], reply)
722
+ except BaseException as error:
723
+ self._fail(execution, error)
724
+ return True
725
+ if execution.trace is not None or execution.plan or execution.queued:
726
+ return
727
+ with self._changed:
728
+ self._undrive(execution)
729
+ for _ in range(4 if self.channels else 1):
730
+ reply, execution.fresh = execution.fresh, None
731
+ try:
732
+ with spans.under(execution.parent), _acting(tree, execution.owner):
733
+ decided = execution.steps.send(reply) if execution.started else next(execution.steps)
734
+ except StopIteration as returned:
735
+ execution.trace = returned.value
736
+ return
737
+ execution.started = True
738
+ command, cameras, *checks = decided
739
+ execution.check = checks[0] if checks else None
740
+ refused = self._plan(execution, command) if self.channels else None
741
+ if not self.channels:
742
+ execution.plan.append(command)
743
+ if refused is None:
744
+ execution.cameras = cameras
745
+ return
746
+ execution.fresh = refused
747
+
748
+ def _plan(self, execution, command):
749
+ """Take on an execution's command: its periods, the channels it drives, and a
750
+ change of what its entry holds down. The reply that refuses it (a channel another
751
+ entry has, an input of no channel), or None."""
752
+ state = dict(self.session.state)
753
+ try:
754
+ uses, periods, change = self.session._plan(command)
755
+ except Refused as refused:
756
+ return _rejected(state, refused.reason)
757
+ with self._changed:
758
+ if found := self.conflicts(execution.owner, uses):
759
+ return _rejected(state, {"check": "channel_conflict", "channels": found}, conflict={"channels": found})
760
+ self._driving.update({name: execution for name in uses})
761
+ execution.uses = frozenset(uses)
762
+ execution.plan = list(periods)
763
+ execution.change = self._apply(execution.owner, change) if change else None
764
+ return None
765
+
766
+ def _set_held(self, owner, held):
767
+ previous = self._held.pop(owner, {})
768
+ current = {kind: {item: previous.get(kind, {}).get(item) or object() for item in items}
769
+ for kind, items in held.items()}
770
+ if any(current.values()):
771
+ self._held[owner] = current
772
+ self._dirty = True
773
+ return current
774
+
775
+ def _surviving_holds(self, owner, snapshot):
776
+ current = self._held.get(owner, {})
777
+ return {kind: {item: token for item, token in tokens.items() if token is current.get(kind, {}).get(item)}
778
+ for kind, tokens in snapshot.items()}
779
+
780
+ def _invalidate_release(self, owner, keep):
781
+ for entry in self._entries:
782
+ if entry.owner is owner and entry.change is not None:
783
+ added, released = entry.change
784
+ if released:
785
+ entry.change = added, keep(released)
786
+
787
+ def _apply(self, owner, change):
788
+ before = self._held.get(owner, {})
789
+ requested = {kind: set(change.get(kind, ())) for kind in before.keys() | (change.keys() - {"op"})}
790
+ down = change["op"] == "down"
791
+ all_up = not down and not any(requested.values())
792
+
793
+ def keep(fragment):
794
+ return {} if all_up else {kind: set(items) - requested.get(kind, set()) for kind, items in fragment.items()}
795
+
796
+ self._invalidate_release(owner, keep)
797
+ if not down:
798
+ after = self._set_held(owner, keep(before))
799
+ return {}, {kind: tokens.keys() - after.get(kind, {}).keys() for kind, tokens in before.items()}
800
+ after = self._set_held(owner, {kind: items | before.get(kind, {}).keys() for kind, items in requested.items()})
801
+ return {kind: {item: token for item, token in tokens.items() if item not in before.get(kind, ())}
802
+ for kind, tokens in after.items()}, {}
803
+
804
+ def _discard_plan(self, entry, *, refused=False):
805
+ entry.plan.clear()
806
+ entry.generation += 1
807
+ with self._changed:
808
+ change, entry.change = entry.change, None
809
+ if change is None:
810
+ return
811
+ added, released = change
812
+ owner = entry.owner
813
+ held = self._held.get(owner, {})
814
+ remove = self._surviving_holds(owner, added)
815
+ restore = released if refused and self._execution_live(entry) else {}
816
+ # Undo restores an input with a fresh lifetime, never with the released token.
817
+ self._set_held(owner, {kind: held.get(kind, {}).keys() - remove.get(kind, {}).keys() | restore.get(kind, set())
818
+ for kind in held.keys() | restore.keys()})
819
+
820
+ def _idle(self) -> set:
821
+ """The channels nobody claims, drives or holds: at their default."""
822
+ with self._changed:
823
+ busy = set(self._claimed) | set(self._driving)
824
+ for held in self._held.values():
825
+ busy |= self.session._channels_of(held)
826
+ return set(self.channels) - busy
827
+
828
+ def _blame(self, parts, held, reason, acts):
829
+ """The part of a period's command a shield's reason is about: a reflex's act, else
830
+ the newest execution's, else a hold, on the channel it names; the last act, else
831
+ the newest execution's, else the last hold, when it names none."""
832
+ channel = reason.get("channel") or self.session._channel_of_reason(reason)
833
+ for part in reversed(held + parts + acts):
834
+ uses = part.execution.uses if part.execution is not None else set()
835
+ if channel is None or channel in self.session._channels_of(part.part) | uses:
836
+ part.channel = channel
837
+ return part
838
+ return None
839
+
840
+ def _holds(self):
841
+ with self._changed:
842
+ return [_Part(None, held, owner=owner) for owner, held in self._held.items()]
843
+
844
+ def _acts(self, parts, executions, tree):
845
+ if self.clock == "steps" and not executions:
846
+ return [], set()
847
+ goal = self.session._merge([part.part for part in parts], set())
848
+ acts, taken = reactive.apply(self.session, tree, goal=goal, channels=sorted(set(self.channels) - self._idle()))
849
+ return [_Part(None, part, reflex=rule) for rule, part in acts], set(taken)
850
+
851
+ def _fail(self, execution, error):
852
+ if execution.done.is_set():
853
+ return
854
+ execution.error = error
855
+ try:
856
+ with _acting(self._tree(), execution.owner):
857
+ execution.steps.close()
858
+ except BaseException as closing:
859
+ if closing is not error:
860
+ error.add_note(f"Closing the execution raised {type(closing).__name__}: {closing}")
861
+ finally:
862
+ self._discard_plan(execution)
863
+ self._end(execution)
864
+
865
+
866
+ class _Action:
867
+ """A sealed period, with its contributing sources and optional trusted completion."""
868
+
869
+ def __init__(self, command, parts, cameras, due, idle):
870
+ self.command, self.parts, self.cameras = command, parts, cameras
871
+ self.due, self.idle = due, idle
872
+ self.id = uuid.uuid4().hex
873
+ self.pending = self.refusal = None
874
+
875
+
876
+ class Refused(Exception):
877
+ """A command the session cannot take apart into its channels' periods (an input of no
878
+ channel, a command it does not know): its `reason`, as a shield's."""
879
+
880
+ def __init__(self, reason: dict):
881
+ super().__init__(reason.get("reason") or reason.get("check"))
882
+ self.reason = reason
883
+
884
+
885
+ class _Part:
886
+ """One period's part of an execution's command (`last` when it is the command's last),
887
+ what an entry (`owner`) holds down, or a reflex's act (`reflex`, its name)."""
888
+
889
+ def __init__(self, execution, part, last=False, owner=None, reflex=None):
890
+ self.execution = execution
891
+ self.generation = execution.generation if execution is not None else None
892
+ self.part = part
893
+ self.last = last
894
+ self.owner = owner
895
+ self.channel = None
896
+ self.reflex = reflex
897
+ self.sent = part
898
+ self.cameras = execution.cameras if execution is not None else None
899
+
900
+
901
+
902
+ def _rejected(state, reason, **detail):
903
+ return {"executed": False, "state": state, **detail,
904
+ "shield": {"verdict": "rejected", "command": None, "reasons": [reason]}}
905
+
906
+
907
+ def _acting(tree, owner):
908
+ """Code inside runs as `owner`, the tree's entry an execution belongs to."""
909
+ return tree.acting(owner) if tree is not None and owner is not None else contextlib.nullcontext()