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