@lmmslab/harness 0.81.1 → 0.83.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 (80) hide show
  1. package/README.md +24 -35
  2. package/package.json +2 -2
  3. package/python/harness/README.md +3 -3
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/configs/assistant.toml +0 -1
  6. package/python/harness/builtin/configs/default.toml +1 -1
  7. package/python/harness/builtin/prompts/conversation/core.md +2 -2
  8. package/python/harness/builtin/prompts/core/core.md +197 -45
  9. package/python/harness/builtin/prompts/core/pack.toml +2 -2
  10. package/python/harness/builtin/prompts/reflect/core.md +4 -13
  11. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  12. package/python/harness/builtin/prompts/shared/learning-goal.md +5 -29
  13. package/python/harness/builtin/prompts/shared/learning.md +8 -10
  14. package/python/harness/builtin/prompts/shared/web.md +11 -0
  15. package/python/harness/builtin/skills/agents/__init__.py +24 -22
  16. package/python/harness/builtin/skills/entries/__init__.py +43 -28
  17. package/python/harness/builtin/skills/entries/skill.toml +2 -3
  18. package/python/harness/builtin/skills/environments/__init__.py +2 -9
  19. package/python/harness/builtin/skills/mcp/__init__.py +2 -3
  20. package/python/harness/builtin/skills/memory/__init__.py +2 -5
  21. package/python/harness/builtin/skills/web/__init__.py +92 -0
  22. package/python/harness/builtin/skills/web/skill.toml +9 -0
  23. package/python/harness/cli.py +85 -17
  24. package/python/harness/config/agent.py +36 -9
  25. package/python/harness/core/episodes.py +5 -4
  26. package/python/harness/core/lanes.py +3 -0
  27. package/python/harness/core/memory.py +5 -1
  28. package/python/harness/core/remote.py +4 -3
  29. package/python/harness/core/worker.py +58 -3
  30. package/python/harness/extensions.py +23 -2
  31. package/python/harness/host/__init__.py +43 -1
  32. package/python/harness/host/client.py +36 -6
  33. package/python/harness/host/http.py +19 -0
  34. package/python/harness/host/server.py +17 -3
  35. package/python/harness/host/sessions.py +3 -2
  36. package/python/harness/host/tasks.py +107 -26
  37. package/python/harness/host/workspaces.py +69 -7
  38. package/python/harness/model_list.py +1 -1
  39. package/python/harness/packages/manager.py +5 -1
  40. package/python/harness/providers.py +14 -5
  41. package/python/harness/runtime/decision/loop.py +105 -117
  42. package/python/harness/runtime/decision/messages.py +158 -55
  43. package/python/harness/runtime/decision/model.py +85 -22
  44. package/python/harness/runtime/decision/notices.py +66 -0
  45. package/python/harness/runtime/decision/prompts.py +15 -11
  46. package/python/harness/runtime/decision/protocol.py +12 -6
  47. package/python/harness/runtime/decision/thoughts.py +10 -16
  48. package/python/harness/runtime/events.py +28 -13
  49. package/python/harness/runtime/execution/attached.py +1 -1
  50. package/python/harness/runtime/execution/control.py +17 -35
  51. package/python/harness/runtime/execution/entries.py +204 -124
  52. package/python/harness/runtime/execution/kernel.py +471 -281
  53. package/python/harness/runtime/execution/managed.py +231 -0
  54. package/python/harness/runtime/execution/noenv.py +2 -2
  55. package/python/harness/runtime/execution/results.py +2 -0
  56. package/python/harness/runtime/execution/session.py +284 -115
  57. package/python/harness/runtime/learning/active.py +41 -50
  58. package/python/harness/runtime/learning/fixtures.py +2 -2
  59. package/python/harness/runtime/learning/learner.py +75 -2
  60. package/python/harness/runtime/learning/library.py +77 -10
  61. package/python/harness/runtime/learning/views.py +12 -1
  62. package/python/harness/runtime/reactive/__init__.py +1 -1
  63. package/python/harness/runtime/reactive/rules.py +29 -394
  64. package/python/harness/runtime/reactive/tree.py +611 -0
  65. package/python/harness/runtime/safety/approval.py +8 -3
  66. package/python/harness/runtime/safety/permissions.py +242 -0
  67. package/python/harness/runtime/status.py +7 -2
  68. package/python/harness/runtime/task/delegation.py +97 -58
  69. package/python/harness/runtime/task/environments.py +3 -4
  70. package/python/harness/runtime/task/inbound.py +64 -0
  71. package/python/harness/runtime/task/run.py +1231 -790
  72. package/python/harness/runtime/tick.py +257 -91
  73. package/python/harness/sdk/__init__.py +7 -4
  74. package/python/harness/settings.py +30 -5
  75. package/python/harness/terminal.py +10 -6
  76. package/python/harness/transcript.py +18 -6
  77. package/python/harness/tui/answer.py +51 -0
  78. package/python/harness/tui/chat.py +75 -26
  79. package/python/harness/tui/views.py +1 -0
  80. package/python/harness/builtin/prompts/shared/entries.md +0 -86
@@ -1,12 +1,13 @@
1
1
  """The episode core: the session skeleton every embodiment's kernel session is.
2
2
 
3
3
  A kernel session connects to a worker, keeps the state it reports, the model clients of the
4
- skills (VLM, pointer, verifier, segmenter) and the episode's events, and runs bounded
5
- executions as program entries on its always-on tick (runtime/tick.py): at each step the
6
- reactive layer's rules that stop are asked, the termination conditions are checked, and one
7
- command goes to the worker, whose shield passes or rejects it. An execution ends with an
8
- event; one that is not nominal goes to the rules that answer it (on()), up the tree of
9
- entries (runtime/execution/entries.py), and one nobody answers escalates to the model.
4
+ skills (VLM, pointer, verifier, segmenter) and the units of the model
5
+ (runtime/execution/entries.py), and runs their bounded executions on its tick
6
+ (runtime/tick.py): at each step the reactive layer's rules that stop are asked, the
7
+ termination conditions are checked, and one command goes to the worker, whose shield passes
8
+ or rejects it. An execution ends with an event; one that is not nominal goes to the rules
9
+ that answer it (on()), and one nobody answers ends the unit and reaches the model. What a
10
+ unit gathers for the model (pictures, events, views) is its own: its box.
10
11
 
11
12
  An embodiment (a robot, a computer, a game) is a worker that serves the worker protocol
12
13
  (core/worker.py WORKER_METHODS) behind a shield (runtime/safety/shield.py CommandShield), and a
@@ -27,7 +28,9 @@ Options: {"endpoint", "episode_id", "embodiment", "skills", "reactive_budget_ms"
27
28
  """
28
29
 
29
30
  import importlib
31
+ import json
30
32
  import math
33
+ import threading
31
34
  import time
32
35
 
33
36
  from harness.core import spans
@@ -38,17 +41,20 @@ from harness.runtime.execution import control
38
41
  from harness.runtime import events as ev
39
42
  from harness.runtime.decision.model import USAGE
40
43
  from harness.runtime.execution.entries import ClosedLoop, Tree
41
- from harness.runtime.reactive.rules import HOLD, RAISES, STOP, ReactiveFault, ReactiveLayer, call_reactive, fault_event
42
- from harness.runtime.tick import Tick, delay_ticks
44
+ from harness.runtime.reactive.rules import HOLD, STOP, ReactiveFault, call_reactive
45
+ from harness.runtime.reactive.tree import Reflexes, fault_event
46
+ from harness.runtime.tick import Preempted, Tick, delay_ticks, driving
43
47
 
44
48
 
45
49
  # The session of each embodiment kind, as "module:Class" (embodiments.KINDS).
46
50
  SESSIONS = {name: kind.session for name, kind in KINDS.items()}
51
+ # The seconds between two reports of the state to the host (the `state` note).
52
+ STATE_NOTE_SECONDS = 1.0
47
53
 
48
54
 
49
55
  class EpisodeCore:
50
56
  """The session skeleton every embodiment and skill builds on: the worker connection and
51
- profile, the state, the model clients, the reactive layer (guards, reflexes, answers to
57
+ profile, the state, the model clients, the reactive layer (rules, facts, answers to
52
58
  events), the tree of entries and bounded executions on the tick. An embodiment's session
53
59
  subclasses it (see the module docstring); its `namespace` holds the enabled skills'
54
60
  exports."""
@@ -76,7 +82,13 @@ class EpisodeCore:
76
82
  self.profile = self.env.call("profile")
77
83
  self.hz = float(self.profile.get("control_hz", 1))
78
84
  self.default_max_seconds = float(options.get("default_max_seconds", 30.0))
79
- self.reactive = ReactiveLayer(float(options.get("reactive_budget_ms", 5.0)) / 1000.0, self.guard_actions)
85
+ self.reactive = Reflexes(float(options.get("reactive_budget_ms", 5.0)) / 1000.0, self.guard_actions)
86
+ # A rule on time is judged at the environment's rate unless it names a period,
87
+ # never faster than the environment can be driven (runtime/tick.py driving).
88
+ bound = driving(self.profile)[0]
89
+ self.reactive.period, self.reactive.min_period = 1.0 / self.hz, 1.0 / (bound or self.hz)
90
+ # What the run knows, shared by its programs and rules.
91
+ self.facts = Facts(self._facts_changed, options.get("facts"))
80
92
  # Between an observation and the action decided on it (runtime/tick.py).
81
93
  self.reaction_delay_ms = float(options.get("reaction_delay_ms") or 0.0)
82
94
  delay_ticks(self.reaction_delay_ms, self.hz)
@@ -90,20 +102,15 @@ class EpisodeCore:
90
102
  self.policies = dict(options.get("policies") or {})
91
103
  self._policy_clients = {}
92
104
  self.world_models = dict(options.get("world_models") or {})
93
- self._attachments = []
94
- self._events = []
95
- self._event_counts = {}
96
105
  # Other environments taken into this conversation, by name (runtime/execution/attached.py),
97
106
  # and the names the namespace gained or gave up since the last cell ended (the kernel
98
107
  # keeps its API in step).
99
108
  self._attached = {}
100
109
  self._api_changes = {}
101
- # What runs at the same time (runtime/execution/entries.py); a guard belongs to the entry that
102
- # set it.
110
+ # The model's units (runtime/execution/entries.py). The reflexes a unit sets are the
111
+ # model's: they outlive the unit.
103
112
  self._entry_tree = Tree(self)
104
- self.reactive.owner = lambda: self._entries.current().id
105
- # The guards a wall clock's idle tick saw firing (each is an event once: reactive.apply).
106
- self._idle_fired = set()
113
+ self.reactive.view = lambda: self._view(self.state, 0)
107
114
  # Latest views of a running controller that servos on images.
108
115
  self._live = None
109
116
  self.state = self.env.call("state", episode_id=self.episode_id)
@@ -133,8 +140,9 @@ class EpisodeCore:
133
140
  self.skills = list(options["skills"])
134
141
  self.namespace = {
135
142
  "__name__": "__program__", **namespace(self, self.skills),
136
- "rule": self.rule, "when": self.reactive.when, "watch": self.reactive.watch,
137
- "on": self.reactive.on, "clear_rules": self.reactive.clear,
143
+ # The reactive layer: one tree, one call that puts a node into it (runtime/reactive/tree.py).
144
+ "set_reflex": self.set_reflex, "drop_reflex": self.reactive.drop, "reflexes": self.reactive.listing,
145
+ "facts": self.facts, "at_priority": self.at_priority, "until": self._entries.until,
138
146
  "run_controller": self.run_controller,
139
147
  # The host switches skills on between programs (sub-agents the user turned on).
140
148
  "__load_skills__": self.load_skills,
@@ -147,23 +155,108 @@ class EpisodeCore:
147
155
  # every turn (a configuration that declares runtime.cameras) and nothing is added.
148
156
  views = dict(options.get("views") or {})
149
157
  self._views = {"cameras": list(views.get("cameras") or ()), "watch": None}
150
- self._looks = []
151
158
  if views.get("mode") == "demand":
152
- guard = self.reactive.watch
153
-
154
- def watch(*args, **kwargs):
155
- """watch(cameras=None, every="program", keep=None): the views with every
156
- program's result from now on. watch(signal, low=..., high=...): a guard on
157
- a number (a rule)."""
158
- if len(args) > 1 or {"low", "high", "event", "name", "stops", "signal_name"} & set(kwargs) \
159
- or (args and callable(args[0])):
160
- return guard(*args, **kwargs)
161
- return self.watch_views(*args, **kwargs)
162
-
163
- self.namespace.update(look=self.look, watch=watch, unwatch=self.unwatch, unpin=self.unpin)
159
+ self.namespace.update(look=self.look, watch=self.watch_views, unwatch=self.unwatch, unpin=self.unpin)
160
+ if self.profile.get("senses"):
161
+ # The environment computes values the model defines, in its own language (senses).
162
+ self.namespace.update(sense=self.sense, senses=self.senses, drop_sense=self.drop_sense)
164
163
  self._embodiment_ready(options)
165
- self.reactive.wake_observer = self._ticker._wake
166
- self._ticker.start()
164
+ self.reactive.wake_observer = self._ticker.judge
165
+
166
+ # The state: the tree of reflexes is judged when it changes (runtime/reactive/tree.py).
167
+
168
+ @property
169
+ def state(self):
170
+ return self.__dict__.get("_state")
171
+
172
+ @state.setter
173
+ def state(self, value):
174
+ self.__dict__["_state"] = value
175
+ # The host keeps the state as it was last reported (the `state` note, at most every
176
+ # STATE_NOTE_SECONDS): what the model is told with every call (runtime/task/run.py _ambient).
177
+ now = time.monotonic()
178
+ if value and now - self.__dict__.get("_state_noted", 0.0) >= STATE_NOTE_SECONDS:
179
+ self.__dict__["_state_noted"] = now
180
+ spans.note("state", state=value)
181
+ self._facts_changed()
182
+
183
+ def _facts_changed(self):
184
+ tick, layer = self.__dict__.get("_tick_loop"), self.__dict__.get("reactive")
185
+ if tick is not None and layer is not None and layer.reads_changes():
186
+ tick.judge()
187
+
188
+ def _view(self, state, tick):
189
+ """What rules, controllers and until predicates observe: the embodiment's view
190
+ (_reactive_view) with the run's facts as "facts"."""
191
+ view = self._reactive_view(state, tick)
192
+ if isinstance(view, dict):
193
+ view.setdefault("facts", self.facts.view())
194
+ if isinstance(state, dict) and "sensed" in state:
195
+ view.setdefault("sensed", state["sensed"])
196
+ return view
197
+
198
+ # Senses: values the environment computes itself, in its own language, each time it
199
+ # reports its state (a worker whose profile says "senses": core/worker.py). What a
200
+ # condition cannot read from the reported state and may not ask for (it makes no
201
+ # calls) is computed where the environment is, by code the model defines, and reported
202
+ # as state["sensed"][name]: one definition serves conditions and programs alike.
203
+
204
+ def sense(self, name, code):
205
+ """Have the environment compute `code` (in its own language; its page says which,
206
+ and what the code has in scope) each time it reports its state, as
207
+ view["sensed"][name]. Returns {"name", "value" (as computed now), "error"}."""
208
+ answer = self.env.call("sense", episode_id=self.episode_id, sense=str(name), code=str(code))
209
+ if answer.get("defined") is False:
210
+ raise ValueError(f"sense {name!r} was not defined: {answer.get('error')}")
211
+ self._observe()
212
+ return answer
213
+
214
+ def senses(self):
215
+ """The senses defined: {name: {"code", "value", "error"}}."""
216
+ return self.env.call("senses", episode_id=self.episode_id)
217
+
218
+ def drop_sense(self, name):
219
+ """Remove the sense `name`."""
220
+ answer = self.env.call("drop_sense", episode_id=self.episode_id, sense=str(name))
221
+ self._observe()
222
+ return answer
223
+
224
+ # What the unit that runs the calling code gathered for the model (its box).
225
+
226
+ def _box(self):
227
+ return self._entries.current().box
228
+
229
+ @property
230
+ def _attachments(self):
231
+ return self._box().attachments
232
+
233
+ @_attachments.setter
234
+ def _attachments(self, value):
235
+ self._box().attachments = value
236
+
237
+ @property
238
+ def _events(self):
239
+ return self._box().events
240
+
241
+ @_events.setter
242
+ def _events(self, value):
243
+ self._box().events = value
244
+
245
+ @property
246
+ def _event_counts(self):
247
+ return self._box().event_counts
248
+
249
+ @_event_counts.setter
250
+ def _event_counts(self, value):
251
+ self._box().event_counts = value
252
+
253
+ @property
254
+ def _looks(self):
255
+ return self._box().looks
256
+
257
+ @_looks.setter
258
+ def _looks(self, value):
259
+ self._box().looks = value
167
260
 
168
261
  def _evidence(self) -> str:
169
262
  """What this environment reports as text about where it stands, as evidence for a
@@ -243,38 +336,14 @@ class EpisodeCore:
243
336
  raise ValueError("keep is how many programs' views stay in sight: 1 to 20")
244
337
  spans.note("views", action="keep", keep=int(keep))
245
338
 
246
- def watch_views(self, cameras=None, every="program", keep=None):
339
+ def watch_views(self, cameras=None, keep=None):
247
340
  """From now on the views (all, or those named) come with every program's result,
248
- until unwatch(); every=seconds: also that often while a long program runs. For
249
- work that is seen, not read: a game, a moving scene."""
341
+ until unwatch(). For work that is seen, not read: a game, a moving scene."""
250
342
  names = self._camera_names(cameras)
251
- seconds = None
252
- if every != "program":
253
- if isinstance(every, bool) or not isinstance(every, (int, float)) or every < 2:
254
- raise ValueError('every is "program" or a number of seconds, at least 2')
255
- seconds = float(every)
256
343
  if keep is not None:
257
344
  self.keep_views(keep)
258
- watch = self._views["watch"] = {"cameras": names, "every": seconds}
259
- spans.note("views", action="watch", cameras=names, every=every)
260
- if seconds is not None:
261
- import threading
262
-
263
- def run():
264
- # While this watch stands: the views to the host, which gives them to the
265
- # model while a program runs.
266
- while self._views["watch"] is watch and not self.state.get("ended"):
267
- time.sleep(seconds)
268
- if self._views["watch"] is not watch:
269
- return
270
- try:
271
- data = self.env.call("observe", episode_id=self.episode_id, cameras=names)
272
- except Exception:
273
- continue
274
- spans.note("view", images={name: url for name, url in (data.get("images") or {}).items()
275
- if name in names})
276
-
277
- threading.Thread(target=run, name="watch", daemon=True).start()
345
+ self._views["watch"] = {"cameras": names}
346
+ spans.note("views", action="watch", cameras=names)
278
347
  return names
279
348
 
280
349
  def unwatch(self):
@@ -288,9 +357,17 @@ class EpisodeCore:
288
357
  spans.note("views", action="unpin", **({"pin": str(name)} if name is not None else {}))
289
358
 
290
359
  def drain(self):
291
- """What the last cell produced, for the kernel's reply: attachments and events
292
- gathered since the previous drain (then cleared), the state, model usage, and the
293
- enabled skills' turn report."""
360
+ """What the unit that calls this produced, for its result (the kernel calls it at a
361
+ program's end, runtime/execution/kernel.py): its attachments, events and views (then
362
+ cleared), the state, model usage, and the enabled skills' turn report."""
363
+ box, own = self._box(), self._entries.root.box
364
+ if box is not own:
365
+ # What the model's own rules and handlers gathered outside every unit comes
366
+ # with the next program's result.
367
+ box.attachments[:0], box.events[:0], box.looks[:0] = own.attachments, own.events, own.looks
368
+ for kind, count in own.event_counts.items():
369
+ box.event_counts[kind] = box.event_counts.get(kind, 0) + count
370
+ own.attachments, own.events, own.looks, own.event_counts = [], [], [], {}
294
371
  watch = self._views["watch"]
295
372
  if watch is not None and not self.state.get("ended"):
296
373
  # A standing watch: the views the program did not look at itself.
@@ -309,9 +386,6 @@ class EpisodeCore:
309
386
  self._event_counts = {}
310
387
  if report is not None:
311
388
  data["report"] = report
312
- entries = self._entries.drain()
313
- if entries:
314
- data["entries"] = entries
315
389
  self._attachments, self._events = [], []
316
390
  if self._looks:
317
391
  data["looks"], self._looks = self._looks, []
@@ -402,7 +476,7 @@ class EpisodeCore:
402
476
  return {"text": "\n".join(texts), "images": images}
403
477
 
404
478
  def close(self):
405
- """Cancel the entries, stop the tick and close the worker connection."""
479
+ """End the model's units, stop the tick and close the worker connection."""
406
480
  for name in list(self.__dict__.get("_attached", {})):
407
481
  self.detach(name)
408
482
  self._entries.close()
@@ -453,13 +527,16 @@ class EpisodeCore:
453
527
  inside `region` (the embodiment's scope), until `until(view)` holds. It runs on the
454
528
  tick as a program entry (_steps) and returns its trace once that ended."""
455
529
  max_seconds = self.default_max_seconds if max_seconds is None else float(max_seconds)
456
- steps = self._steps(skill, parameters, command_fn, max_seconds, region, until, timeout_is_nominal,
457
- cameras_at)
530
+
531
+ def steps():
532
+ # (Made anew each time the harness starts the execution again: runtime/tick.py.)
533
+ return self._steps(skill, parameters, command_fn, max_seconds, region, until, timeout_is_nominal,
534
+ cameras_at)
535
+
458
536
  result = Execution(session=self, skill=skill, parameters=parameters, steps=steps)
459
537
  trace = result.detail.get("trace")
460
538
  if trace is None:
461
539
  # Not confirmed: the run does not let it act now.
462
- steps.close()
463
540
  step = self.state["step"]
464
541
  trace = ExecutionTrace(skill, parameters, step, step, Event(
465
542
  ev.SKILL_ERROR, skill, {"reason": result.reason, **result.detail}, step))
@@ -476,15 +553,16 @@ class EpisodeCore:
476
553
  observes, runs the guards and the termination conditions, and yields the command
477
554
  to send with the cameras whose images the reply should carry; it receives the
478
555
  worker's reply to the step the tick sent, and returns the execution's trace."""
479
- max_ticks = max(1, math.ceil(max_seconds * self.hz))
480
- # The guards of the entry that runs it and of those above it watch it.
481
- scope = {entry.id for entry in self._entries.current().lineage()}
556
+ # Its time is the environment's steps where each step is a fixed time of it (a
557
+ # simulation), else the wall's (runtime/tick.py driving).
558
+ step_seconds = self._ticker.step_seconds
559
+ max_ticks = max(1, math.ceil(max_seconds / step_seconds)) if step_seconds else None
560
+ over = ev.COMPLETED if timeout_is_nominal else ev.TIMEOUT
482
561
  start = self.state["step"]
483
562
  samples = []
484
563
  receipt = None
485
564
  value = None
486
565
  deadline = time.monotonic() + max_seconds
487
- discrete = self.profile.get("clock") == "events"
488
566
  tick = 0
489
567
  event = None
490
568
 
@@ -492,13 +570,13 @@ class EpisodeCore:
492
570
  state = self.state
493
571
  if control.pause_requested():
494
572
  return Event(ev.USER_PAUSED, "user", tick=state["step"])
495
- if discrete and time.monotonic() >= deadline:
496
- return Event(ev.TIMEOUT, skill, {"max_seconds": max_seconds}, state["step"])
497
- view = self._reactive_view(state, tick)
573
+ if max_ticks is None and time.monotonic() >= deadline:
574
+ return Event(over, skill, {"max_seconds": max_seconds}, state["step"])
575
+ view = self._view(state, tick)
498
576
  if cameras_at is not None:
499
577
  view["observation"] = self._live
500
578
  try:
501
- guard = self.reactive.evaluate(view, scope)
579
+ guard = self.reactive.evaluate(view)
502
580
  if guard is not None or predicate is None:
503
581
  return guard
504
582
  if call_reactive("until", predicate, view, budget_seconds=self.reactive.budget_seconds):
@@ -517,10 +595,9 @@ class EpisodeCore:
517
595
  raise EpisodeEnded(ExecutionTrace(skill, parameters, start, state["step"],
518
596
  Event(ev.EPISODE_ENDED, "environment", tick=state["step"]),
519
597
  samples))
520
- paused = control.pause_requested()
521
- if paused or control.message_arrived() and self._entries.current() is self._entries.root:
598
+ if control.pause_requested():
522
599
  self._motion_stopped(state)
523
- event = Event(ev.USER_PAUSED if paused else ev.USER_MESSAGE, "user", tick=state["step"])
600
+ event = Event(ev.USER_PAUSED, "user", tick=state["step"])
524
601
  break
525
602
  outcome, observed = stop or (check(until), state)
526
603
  if outcome is not None:
@@ -531,11 +608,15 @@ class EpisodeCore:
531
608
  if isinstance(outcome, ReactiveFault):
532
609
  command = self._base_command(observed)
533
610
  else:
534
- self._idle_fired.add(outcome.name)
535
- self._let_go_under(outcome.owner)
611
+ # What the unit whose execution ends holds down goes up; the other
612
+ # units' holds stay (the rule may be the model's, watching them all).
613
+ self._let_go_under(self._entries.current().id)
536
614
  command = self._guard_command(outcome.action, observed) if (
537
615
  outcome.action in self.guard_actions and outcome.action != STOP) else None
538
- held = (yield command, None) if command is not None else None
616
+ try:
617
+ held = (yield command, None) if command is not None else None
618
+ except Preempted:
619
+ held = None
539
620
  if self.state.get("ended"):
540
621
  continue
541
622
  event = self._rule_event(outcome, observed, held)
@@ -543,9 +624,8 @@ class EpisodeCore:
543
624
  if region is not None and self._outside(region, state):
544
625
  event = Event(ev.REGION_EXIT, skill, {"region": region}, state["step"])
545
626
  break
546
- if not discrete and tick >= max_ticks:
547
- kind = ev.COMPLETED if timeout_is_nominal else ev.TIMEOUT
548
- event = Event(kind, skill, {"max_seconds": max_seconds}, state["step"])
627
+ if max_ticks is not None and tick >= max_ticks:
628
+ event = Event(over, skill, {"max_seconds": max_seconds}, state["step"])
549
629
  break
550
630
  try:
551
631
  target = command_fn(state, tick)
@@ -554,7 +634,13 @@ class EpisodeCore:
554
634
  if target is None or isinstance(target, Event):
555
635
  event = target if target is not None else Event(ev.COMPLETED, skill, receipt or {}, state["step"])
556
636
  break
557
- result = yield target, (cameras_at(tick) if cameras_at else None), check
637
+ try:
638
+ result = yield target, (cameras_at(tick) if cameras_at else None), check
639
+ except Preempted as taken:
640
+ # A unit of higher priority takes the embodiment: this execution ends here.
641
+ self._motion_stopped(self.state)
642
+ event = Event(ev.PREEMPTED, skill, {"by": taken.by, "priority": taken.priority}, self.state["step"])
643
+ break
558
644
  if result is None and self.state.get("ended"):
559
645
  continue
560
646
  if isinstance(result, tuple):
@@ -605,7 +691,7 @@ class EpisodeCore:
605
691
  def _finish(self, trace):
606
692
  tree = self._entries
607
693
  entry = tree.current()
608
- handled_here = not trace.ok and trace.event.kind not in (ev.USER_PAUSED, ev.USER_MESSAGE)
694
+ handled_here = not trace.ok and trace.event.kind != ev.USER_PAUSED
609
695
  record = tree.record_event(trace, entry if handled_here and entry is not tree.root else None)
610
696
  if trace.ok:
611
697
  return trace
@@ -618,34 +704,54 @@ class EpisodeCore:
618
704
  step = self.state["step"]
619
705
  return ExecutionTrace(skill, parameters, step, step, Event(ev.SKILL_ERROR, skill, {"reason": reason}, step))
620
706
 
621
- def rule(self, decide, name=None, priority=0):
622
- """Register an observation rule that can raise an event or stop an entry in scope."""
623
- return self.reactive.rule(decide, RAISES, name, priority).name
707
+ def set_reflex(self, name, when, do=None, *, under=None, priority=0, every=None, again_seconds=0.0):
708
+ """Put the node `name` into the tree of reflexes (runtime/reactive/tree.py), in place
709
+ of a node of that name. `when`: a function of the view (the node has its turn while
710
+ it holds: the situation it answers), or the name of an event (it answers that
711
+ event). `do`: a program (a function, started as a unit; its work is done when the
712
+ situation is over), the name of an event to raise, an action of the environment that
713
+ ends what runs ("stop"), or None: then the node is a group for the nodes set `under`
714
+ it. `priority`: its place among the nodes where it is (the higher first, 0 or more). `every`: the seconds between judgements of its condition (None: when the
715
+ state or the facts change). `again_seconds`: before it may begin again. Its name."""
716
+ return self.reactive.set(name, when, do, under=under, priority=priority, every=every,
717
+ again_seconds=again_seconds)
718
+
719
+ @property
720
+ def pauses(self) -> bool:
721
+ """Whether the environment pauses a call for a unit of higher priority and lets it
722
+ go on afterwards (its profile says "pauses"); else that call ends with PREEMPTED."""
723
+ return bool(self.profile.get("pauses"))
724
+
725
+ def _pause_execution(self, by=None):
726
+ """Have the environment hold what the call that runs is doing, for the unit `by`
727
+ (a reflex's name, or the unit's); what it answers is given back to it when that
728
+ call goes on."""
729
+ return self.env.call("pause", episode_id=self.episode_id, by=by)
730
+
731
+ def _resume_execution(self, held):
732
+ self.env.call("resume", episode_id=self.episode_id, held=held)
733
+ self._observe()
734
+
735
+ def at_priority(self, priority):
736
+ """This program holds the environment with `priority` from here until it ends. A
737
+ reflex whose place is `priority` or above takes it from the program as before. One
738
+ below does not act while the program runs: it is judged again when the program has
739
+ ended and acts if its condition still holds, and the model is told once that it was
740
+ held back. What still ends the program: cancelling it, the time of its calls, a
741
+ reflex that ends what runs, the end of the episode."""
742
+ self._entries.at_priority(priority)
624
743
 
625
744
  def run_controller(self, fn, until=None, max_seconds=None):
626
745
  """Run `fn(view)` for each step, until it returns None or a stopping condition holds."""
627
746
  def command(state, tick):
628
- return call_reactive("controller", fn, self._reactive_view(state, tick),
747
+ return call_reactive("controller", fn, self._view(state, tick),
629
748
  budget_seconds=self.reactive.budget_seconds)
630
749
 
631
750
  return self._execute("run_controller", {}, command, max_seconds, None, until)
632
751
 
633
- def reflex(self, control, priority="survival", name=None):
634
- """Run `control(view)` on the tick every control period from now on, as a rule of
635
- this entry that acts (runtime/reactive/rules.py): it returns None or the period's act ({"keys",
636
- "buttons", "dx", "dy", "take"}) and wins the channels it needs over lower
637
- priorities and over what the entries do. Its name."""
638
- if not self.channels:
639
- raise ValueError("reflexes run on an embodiment with channels (a game's)")
640
- name = name or getattr(control, "__name__", None) or type(control).__name__
641
- self.reactive.reflex(name, control, priority)
642
- self._ticker.start()
643
- return name
644
-
645
752
  def _let_go_under(self, owner):
646
- """A guard that stops fired: with channels, the keys and buttons that the entry
647
- `owner` and the entries below it hold down (key_down) go up at the next period, as
648
- a stop of all they do (None: every entry's)."""
753
+ """A rule ended what the unit `owner` does: with channels, the keys and buttons it
754
+ holds down (key_down) go up at the next period (None: every unit's)."""
649
755
  tick = self.__dict__.get("_tick_loop")
650
756
  if tick is None or not tick.channels:
651
757
  return
@@ -658,7 +764,7 @@ class EpisodeCore:
658
764
  return fault_event(guard, state.get("step"), **detail)
659
765
  detail = {"guard": guard.describe(), **detail}
660
766
  # Counted per episode (summary guard_triggers) and tallied by practice.
661
- spans.note("guard", name=guard.name, action=guard.action, stops=guard.does == "stop")
767
+ spans.note("guard", name=guard.name, action=guard.action, stops=guard.stops)
662
768
  if guard.action in self.guard_actions:
663
769
  return Event(ev.GUARD_TRIGGERED, guard.name, {**detail, "action": guard.action}, state["step"])
664
770
  return Event(guard.action, guard.name, detail, state["step"])
@@ -728,8 +834,8 @@ class EpisodeCore:
728
834
  return None
729
835
 
730
836
  def _observe(self):
731
- """Refresh the state at the start of a tick of a wall-clock embodiment (between
732
- two ticks the world moved on); a steps clock's last reply is the state."""
837
+ """Refresh the state from the worker (between two ticks the world may have moved
838
+ on): for a rule on time, and at each period of an environment driven at a rate."""
733
839
  self.state = self.env.call("state", episode_id=self.episode_id)
734
840
 
735
841
  def _outside(self, region, state):
@@ -741,6 +847,69 @@ class EpisodeCore:
741
847
  return {"step": state["step"]}
742
848
 
743
849
 
850
+ class Facts:
851
+ """What the run knows, shared: named values that its programs read and write and its
852
+ rule conditions read (the view's "facts"). A program that was ended and started again
853
+ goes on from them. Values are plain data (what JSON holds); a change is a `fact`
854
+ record, and the rules that read facts are judged."""
855
+
856
+ LIMIT = 20000
857
+
858
+ def __init__(self, changed=None, values=None):
859
+ # (`values`: the facts an earlier process of the conversation kept.)
860
+ self._values, self._lock, self._changed = dict(values or {}), threading.Lock(), changed
861
+ self.version = 0
862
+
863
+ def set(self, name, value):
864
+ """Set the fact `name` to `value`; returns the value."""
865
+ if not isinstance(name, str) or not name:
866
+ raise ValueError("a fact's name is a nonempty string")
867
+ try:
868
+ text = json.dumps(value)
869
+ except (TypeError, ValueError):
870
+ raise ValueError("a fact's value is plain data: numbers, text, true/false, None, lists and dicts") from None
871
+ if len(text) > self.LIMIT:
872
+ raise ValueError(f"a fact holds at most {self.LIMIT} characters of data; keep large data elsewhere")
873
+ with self._lock:
874
+ self._values[name] = json.loads(text)
875
+ self.version += 1
876
+ # (`data`: the whole value, for the conversation that keeps the facts; not recorded.)
877
+ spans.note("fact", name=name, value=text[:300], data=text)
878
+ if self._changed is not None:
879
+ self._changed()
880
+ return value
881
+
882
+ def get(self, name, default=None):
883
+ """The fact `name`, or `default`."""
884
+ with self._lock:
885
+ return self._values.get(name, default)
886
+
887
+ def drop(self, name):
888
+ """Forget the fact `name`; whether it was there."""
889
+ with self._lock:
890
+ there = self._values.pop(name, self) is not self
891
+ self.version += there
892
+ if there:
893
+ spans.note("fact", name=name, dropped=True)
894
+ if self._changed is not None:
895
+ self._changed()
896
+ return there
897
+
898
+ def view(self) -> dict:
899
+ """The facts as they are now, as a dict of their own."""
900
+ with self._lock:
901
+ return dict(self._values)
902
+
903
+ __getitem__ = lambda self, name: self.view()[name] # noqa: E731
904
+ __setitem__ = set
905
+
906
+ def __contains__(self, name):
907
+ return name in self.view()
908
+
909
+ def __repr__(self):
910
+ return f"facts({self.view()!r})"
911
+
912
+
744
913
  class Looked:
745
914
  """What look() saw: .state, .cameras, and the pictures show() takes (a crop of one is
746
915
  look(region=...))."""
@@ -750,7 +919,7 @@ class Looked:
750
919
  self.cameras = list(urls)
751
920
 
752
921
  def __repr__(self):
753
- return f"Looked({', '.join(self.cameras) or 'nothing'}): it is in your next turn"
922
+ return f"Looked({', '.join(self.cameras) or 'nothing'}): it comes with this program's result"
754
923
 
755
924
 
756
925
  def _cropped(url, region, fmt):