@lmmslab/harness 0.85.0 → 0.86.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 (94) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +2 -2
  4. package/python/harness/bench.py +2 -2
  5. package/python/harness/builtin/benches/README.md +1 -2
  6. package/python/harness/builtin/configs/default.toml +4 -19
  7. package/python/harness/builtin/configs/deploy/example-api.toml +1 -1
  8. package/python/harness/builtin/configs/models/deepseek-flash.toml +1 -1
  9. package/python/harness/builtin/configs/models/grok-low.toml +1 -1
  10. package/python/harness/builtin/configs/models/grok-medium.toml +3 -6
  11. package/python/harness/builtin/environment/README.md +8 -25
  12. package/python/harness/builtin/prompts/conversation/core.md +6 -5
  13. package/python/harness/builtin/prompts/core/core.md +147 -203
  14. package/python/harness/builtin/prompts/core/pack.toml +0 -1
  15. package/python/harness/builtin/prompts/reflect/core.md +8 -32
  16. package/python/harness/builtin/prompts/reflect/pack.toml +2 -4
  17. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -3
  18. package/python/harness/builtin/prompts/shared/agents.md +20 -10
  19. package/python/harness/builtin/prompts/shared/checklist.md +13 -17
  20. package/python/harness/builtin/prompts/shared/environments.md +20 -15
  21. package/python/harness/builtin/prompts/shared/learning-goal.md +2 -3
  22. package/python/harness/builtin/prompts/shared/learning.md +73 -23
  23. package/python/harness/builtin/prompts/shared/mcp.md +11 -6
  24. package/python/harness/builtin/prompts/shared/reflex-method.md +243 -0
  25. package/python/harness/builtin/prompts/shared/units.md +138 -0
  26. package/python/harness/builtin/prompts/shared/web.md +5 -6
  27. package/python/harness/builtin/skills/agents/__init__.py +18 -3
  28. package/python/harness/builtin/skills/agents/skill.toml +3 -3
  29. package/python/harness/builtin/skills/checklist/__init__.py +34 -32
  30. package/python/harness/builtin/skills/checklist/skill.toml +9 -9
  31. package/python/harness/builtin/skills/environments/__init__.py +9 -5
  32. package/python/harness/builtin/skills/environments/skill.toml +1 -1
  33. package/python/harness/builtin/skills/experience/skill.toml +1 -1
  34. package/python/harness/builtin/skills/learning/__init__.py +19 -5
  35. package/python/harness/builtin/skills/mcp/skill.toml +1 -1
  36. package/python/harness/builtin/skills/memory/__init__.py +4 -1
  37. package/python/harness/builtin/skills/memory/skill.toml +0 -5
  38. package/python/harness/builtin/skills/verify/skill.toml +1 -0
  39. package/python/harness/builtin/skills/web/__init__.py +4 -1
  40. package/python/harness/builtin/third_party/sources.toml +2 -40
  41. package/python/harness/cli.py +16 -25
  42. package/python/harness/config/__init__.py +2 -2
  43. package/python/harness/config/agent.py +59 -47
  44. package/python/harness/core/__init__.py +1 -1
  45. package/python/harness/core/codec.py +4 -4
  46. package/python/harness/core/contracts.py +1 -1
  47. package/python/harness/core/media.py +1 -1
  48. package/python/harness/core/ports.py +2 -2
  49. package/python/harness/core/procs.py +1 -1
  50. package/python/harness/core/remote.py +1 -1
  51. package/python/harness/core/worker.py +19 -13
  52. package/python/harness/embodiments.py +53 -44
  53. package/python/harness/extensions.py +22 -0
  54. package/python/harness/host/__init__.py +1 -1
  55. package/python/harness/host/http.py +6 -12
  56. package/python/harness/host/sessions.py +1 -1
  57. package/python/harness/host/tasks.py +15 -11
  58. package/python/harness/host/workspaces.py +36 -8
  59. package/python/harness/packages/__init__.py +5 -5
  60. package/python/harness/packages/environments.py +30 -18
  61. package/python/harness/packages/manager.py +1 -1
  62. package/python/harness/packages/manifest.py +6 -6
  63. package/python/harness/packages/provision.py +1 -1
  64. package/python/harness/packages/sources.py +1 -1
  65. package/python/harness/paths.py +1 -1
  66. package/python/harness/runtime/decision/loop.py +95 -5
  67. package/python/harness/runtime/decision/messages.py +128 -2
  68. package/python/harness/runtime/decision/model.py +4 -5
  69. package/python/harness/runtime/decision/prompts.py +20 -32
  70. package/python/harness/runtime/events.py +7 -5
  71. package/python/harness/runtime/execution/attached.py +3 -3
  72. package/python/harness/runtime/execution/entries.py +189 -8
  73. package/python/harness/runtime/execution/kernel.py +26 -1
  74. package/python/harness/runtime/execution/results.py +2 -3
  75. package/python/harness/runtime/execution/session.py +417 -32
  76. package/python/harness/runtime/execution/skills.py +63 -16
  77. package/python/harness/runtime/learning/active.py +7 -7
  78. package/python/harness/runtime/learning/learner.py +3 -2
  79. package/python/harness/runtime/learning/library.py +9 -4
  80. package/python/harness/runtime/learning/reflect.py +10 -9
  81. package/python/harness/runtime/reactive/rules.py +4 -4
  82. package/python/harness/runtime/reactive/tree.py +506 -25
  83. package/python/harness/runtime/safety/input.py +1 -1
  84. package/python/harness/runtime/safety/isolation.py +3 -3
  85. package/python/harness/runtime/safety/shield.py +4 -50
  86. package/python/harness/runtime/task/delegation.py +5 -5
  87. package/python/harness/runtime/task/environments.py +10 -0
  88. package/python/harness/runtime/task/run.py +222 -27
  89. package/python/harness/runtime/tick.py +24 -1
  90. package/python/harness/sdk/__init__.py +2 -5
  91. package/python/harness/services/registry.py +23 -19
  92. package/python/harness/settings.py +9 -9
  93. package/python/harness/builtin/environment/constraints.txt +0 -31
  94. package/python/harness/builtin/prompts/shared/world.md +0 -1
@@ -41,6 +41,7 @@ from dataclasses import dataclass, field
41
41
  import inspect
42
42
  import threading
43
43
  import time
44
+ from types import CodeType, FunctionType
44
45
  from typing import Any, Callable
45
46
 
46
47
  from harness.core import spans
@@ -62,16 +63,132 @@ _UNSEEN = object()
62
63
  NO_REFLEXES = "Reflex tree: empty (nothing acts without you)"
63
64
  # The most nodes one reflexes() call gives, and the most changed nodes a turn is told of.
64
65
  LISTED, TOLD = 50, 10
66
+ # What a node says of how the model hears of it (Reflex.tell, Reflex.tell_failed): not at all,
67
+ # the first time only, or each time, with the place the notice takes in the model's queue
68
+ # (runtime/decision/notices.py: later, next, now).
69
+ QUEUE = ("later", "next", "now")
70
+ # What a node or a program says of itself (its report function) is a message: its text is at
71
+ # most SAID_CHARS, with at most REPORT_PICTURES pictures and REPORT_FILES files of at most
72
+ # FILE_CHARS characters each.
73
+ SAID_CHARS = 2000
74
+ REPORT_PICTURES = 4
75
+ REPORT_FILES = 4
76
+ FILE_CHARS = 20000
77
+ _PICTURES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
78
+ ".webp": "image/webp"}
79
+ # A program that asks to be told when a reflex takes the environment from it is told so,
80
+ # one by one, this many times; the rest are counted and told with its end.
81
+ INTERRUPTIONS_TOLD = 3
82
+ TELLS = ("never", "first", *QUEUE)
83
+
84
+
85
+ def _trial_text(trial) -> str:
86
+ """How a node's line says what its trial showed: nothing where it worked or where the
87
+ node was set without one."""
88
+ if not isinstance(trial, dict):
89
+ return ""
90
+ if not trial.get("tried"):
91
+ return ", not tried"
92
+ worked = trial.get("turn") and trial.get("done") is not False and not trial.get("error")
93
+ return "" if worked else ", did not work in its trial"
94
+
95
+
96
+ _ABSENT = object()
97
+
98
+
99
+ def _same_code(a, b) -> bool:
100
+ """Whether two code objects are the same program: what they execute, the names they use
101
+ and their constants, wherever in a source they stand."""
102
+ if (a.co_code != b.co_code or a.co_names != b.co_names or a.co_varnames != b.co_varnames
103
+ or a.co_freevars != b.co_freevars or a.co_argcount != b.co_argcount
104
+ or a.co_kwonlyargcount != b.co_kwonlyargcount or len(a.co_consts) != len(b.co_consts)):
105
+ return False
106
+ for x, y in zip(a.co_consts, b.co_consts):
107
+ if isinstance(x, CodeType) or isinstance(y, CodeType):
108
+ if not (isinstance(x, CodeType) and isinstance(y, CodeType) and _same_code(x, y)):
109
+ return False
110
+ elif type(x) is not type(y) or x != y:
111
+ return False
112
+ return True
113
+
114
+
115
+ def _names(code):
116
+ yield from code.co_names
117
+ for value in code.co_consts:
118
+ if isinstance(value, CodeType):
119
+ yield from _names(value)
120
+
121
+
122
+ def same(a, b, seen=None) -> bool:
123
+ """Whether two values a node is made of (its condition, its program, what those use) are
124
+ the same: for functions the same code, with the same defaults and the same things behind
125
+ the names they use, each compared in this way; for data, equal."""
126
+ seen = set() if seen is None else seen
127
+ if a is b:
128
+ return True
129
+ a = inspect.unwrap(a) if callable(a) else a
130
+ b = inspect.unwrap(b) if callable(b) else b
131
+ if a is b:
132
+ return True
133
+ if isinstance(a, FunctionType) and isinstance(b, FunctionType):
134
+ if (id(a), id(b)) in seen:
135
+ return True
136
+ seen.add((id(a), id(b)))
137
+ if not _same_code(a.__code__, b.__code__):
138
+ return False
139
+ if not same(a.__defaults__, b.__defaults__, seen) or not same(a.__kwdefaults__, b.__kwdefaults__, seen):
140
+ return False
141
+ for x, y in zip(a.__closure__ or (), b.__closure__ or ()):
142
+ try:
143
+ if not same(x.cell_contents, y.cell_contents, seen):
144
+ return False
145
+ except ValueError: # (An empty cell on either side.)
146
+ return False
147
+ for name in set(_names(a.__code__)):
148
+ x, y = a.__globals__.get(name, _ABSENT), b.__globals__.get(name, _ABSENT)
149
+ # (A name neither or only one has is an attribute or a builtin, not something of theirs.)
150
+ if x is not _ABSENT and y is not _ABSENT and not same(x, y, seen):
151
+ return False
152
+ return True
153
+ if isinstance(a, FunctionType) or isinstance(b, FunctionType) or type(a) is not type(b):
154
+ return False
155
+ if isinstance(a, (tuple, list)):
156
+ return len(a) == len(b) and all(same(x, y, seen) for x, y in zip(a, b))
157
+ if isinstance(a, dict):
158
+ return a.keys() == b.keys() and all(same(a[key], b[key], seen) for key in a)
159
+ try:
160
+ return bool(a == b)
161
+ except Exception:
162
+ return False
65
163
 
66
164
 
67
165
  def told(nodes: dict, before: dict) -> str:
68
166
  """What a turn of the model is told of the tree: how many nodes act in it, and the
69
- lines (Reflexes.digest) that differ from `before`, what it was told last."""
167
+ lines (Reflexes.digest) that differ from `before`, what it was told last. Nothing when
168
+ no line differs and every node has had its turn and acts itself: a line that says only
169
+ that nothing changed tells nothing."""
70
170
  if not nodes:
71
171
  return NO_REFLEXES
72
172
  changed = [f" {name}: {line}" for name, line in nodes.items() if before.get(name) != line]
73
173
  count = f"{len(nodes)} node" + ("" if len(nodes) == 1 else "s")
174
+ # A node that has never had its turn has not been seen to work.
175
+ never = sum(1 for line in nodes.values() if line.startswith("began 0,") or line.endswith(("; 0 times", "; began 0")))
176
+ if never:
177
+ count += f", {never} of them never had {'its' if never == 1 else 'their'} turn"
178
+ # A node that only tells acts on nothing itself: what it sees waits for the model's reply.
179
+ only = sum(1 for line in nodes.values() if line.startswith("tells you") and " and ends what runs" not in line)
180
+ if only:
181
+ count += f", {only} of them only tell{'s' if only == 1 else ''} you"
182
+ # What the trials showed (set_reflex test=).
183
+ untried = sum(1 for line in nodes.values() if line.endswith(", not tried"))
184
+ failed = sum(1 for line in nodes.values() if line.endswith(", did not work in its trial"))
185
+ if untried:
186
+ count += f", {untried} not tried"
187
+ if failed:
188
+ count += f", {failed} did not work in {'its' if failed == 1 else 'their'} trial"
74
189
  if not changed:
190
+ if not never and not only and not untried and not failed:
191
+ return ""
75
192
  return f"Reflex tree: {count}, as you were last told (reflexes() lists them)"
76
193
  more = f"\n ... {len(changed) - TOLD} more changed: reflexes()" if len(changed) > TOLD else ""
77
194
  return (f"Reflex tree: {count}; changed since you were last told:\n"
@@ -85,7 +202,10 @@ class Reflex:
85
202
  raise, or one of the environment's actions that end what runs), or neither (then only
86
203
  the nodes under it answer); the node it is `under` (None: the top); its own `priority`; `every`
87
204
  seconds its condition is judged (None: when the state or the facts change);
88
- `again_seconds` before it may begin again after its program ended."""
205
+ `again_seconds` before it may begin again after its program ended; `ends`: the unit its
206
+ program takes the environment from is ended there (and the model told), where it would
207
+ otherwise be resumed when the program is over; of a node that tells, what runs is ended
208
+ with the event it tells."""
89
209
 
90
210
  name: str
91
211
  when: Callable | None = None
@@ -99,6 +219,34 @@ class Reflex:
99
219
  again_seconds: float = 0.0
100
220
  order: int = 0
101
221
  library_origin: tuple | None = None
222
+ ends: bool = False
223
+ # What the node says when the model is told of it, said when it is set: `about`, one
224
+ # sentence on the situation it answers; `report`, a function of the view and of what its
225
+ # program returned, which returns what the model is to read then.
226
+ about: str = ""
227
+ report: Callable | None = None
228
+ # What the model hears of the node, said when it is set. `tell`: of its program having done
229
+ # its work (one of TELLS), or for a node that tells an event, the place of that event in
230
+ # the queue (one of QUEUE). `tell_failed`: of its program not having done its work with
231
+ # nothing else taking the situation ("never" or one of QUEUE).
232
+ tell: str = "never"
233
+ tell_failed: str = "now"
234
+ # What its trial showed (session.set_reflex test=): {"tried": True, "turn", "seconds", "done",
235
+ # "error"} or {"tried": False, "why"}; None for a node set without one. While the trial
236
+ # runs, `trying`; `acted`: the model was told of the first time its program did its work
237
+ # by itself.
238
+ trial: Any = field(default=None, repr=False)
239
+ trying: bool = field(default=False, repr=False)
240
+ acted: bool = field(default=False, repr=False)
241
+ # What went wrong with its condition (Reflexes._faulted): the reason of the last time,
242
+ # how often, the reasons the model was told, and the one it is to be told next. A node
243
+ # whose condition was too slow time after time is `set_aside`: it stays in the tree and
244
+ # is not judged until it is set again.
245
+ fault: Any = field(default=None, repr=False)
246
+ faults: int = 0
247
+ fault_told: set = field(default_factory=set, repr=False)
248
+ fault_tell: Any = field(default=None, repr=False)
249
+ set_aside: bool = False
102
250
  # As it stands: the unit of its program, when it may begin again, whether its condition
103
251
  # held when last judged, whether it raised its event since that came to hold, when it
104
252
  # is next due, how often it acted, the program of higher priority that kept it from acting,
@@ -125,13 +273,15 @@ class Reflex:
125
273
  if self.do is not None:
126
274
  return "answers an event with its program" if self.event else "starts its program"
127
275
  if self.action is not None:
128
- return "ends what runs" if self.stops else "raises an event"
276
+ return ("ends what runs" if self.stops else
277
+ "raises an event and ends what runs" if self.ends else "raises an event")
129
278
  return "holds the nodes under it"
130
279
 
131
280
  def describe(self) -> dict:
132
281
  """What the event it raises reports of it."""
133
282
  return {"name": self.name, "action": self.action, "triggered": self.triggered,
134
- **({} if self.stops else {"stops": False})}
283
+ **({} if self.stops or self.ends else {"stops": False}),
284
+ **({"tell": self.tell} if self.action is not None and not self.stops and self.tell in QUEUE else {})}
135
285
 
136
286
 
137
287
  def _takes_argument(function) -> bool:
@@ -156,6 +306,7 @@ def stage(layer, replacing):
156
306
  staged.library_origin = None
157
307
  staged.replacing = replacing
158
308
  staged.live = layer
309
+ staged.kept = {}
159
310
  _staging.layers = (layer, staged)
160
311
  try:
161
312
  yield staged
@@ -179,6 +330,9 @@ class Reflexes:
179
330
  self.view = None
180
331
  self.library_boundary = threading.RLock()
181
332
  self.library_origin = None
333
+ # Whether the model is told of the first time a node's program does its work by itself
334
+ # (where nodes are set with their trials: session.set_reflex).
335
+ self.tell_first = False
182
336
  self.period = self.min_period = 1.0
183
337
  # What the last judgement left: the state and facts it saw, whether the tree changed
184
338
  # since, and when a node that waits for its time wants the tree judged again.
@@ -186,7 +340,8 @@ class Reflexes:
186
340
 
187
341
  # Setting and removing nodes.
188
342
 
189
- def set(self, name, when, do=None, *, under=None, priority=0, every=None, again_seconds=0.0) -> str:
343
+ def set(self, name, when, do=None, *, under=None, priority=0, every=None, again_seconds=0.0,
344
+ ends=False, tell=None, tell_failed="now", about=None, report=None) -> str:
190
345
  """Put the node `name` into the tree, in place of a node of that name (see Reflex;
191
346
  `when`: a function of the view, or the name of an event; `do`: a program, or the
192
347
  name of an event to raise, or an action of the environment that ends what runs
@@ -194,7 +349,8 @@ class Reflexes:
194
349
  staging = getattr(_staging, "layers", None)
195
350
  if staging is not None and staging[0] is self:
196
351
  return staging[1].set(name, when, do, under=under, priority=priority, every=every,
197
- again_seconds=again_seconds)
352
+ again_seconds=again_seconds, ends=ends, tell=tell, tell_failed=tell_failed,
353
+ about=about, report=report)
198
354
  if not isinstance(name, str) or not name:
199
355
  raise ValueError("a reflex's name is a nonempty string")
200
356
  event = None
@@ -215,10 +371,31 @@ class Reflexes:
215
371
  elif do is not None and not callable(do):
216
372
  raise TypeError("`do` is a program (a function), the name of an event, an action that ends what runs, "
217
373
  "or None (then only the nodes under it answer)")
374
+ if action is not None and not stops:
375
+ # A node that tells: where its event goes in the model's queue.
376
+ tell = "now" if tell is None else tell
377
+ if tell not in QUEUE:
378
+ raise ValueError(f"tell, for a node that tells an event, is one of {QUEUE}, got {tell!r}")
379
+ else:
380
+ # A node with a program: whether the model hears that it did its work.
381
+ tell = ("first" if self.tell_first else "never") if tell is None else tell
382
+ if tell not in TELLS:
383
+ raise ValueError(f"tell is one of {TELLS}, got {tell!r}")
384
+ if tell_failed not in ("never", *QUEUE):
385
+ raise ValueError(f"tell_failed is one of {('never', *QUEUE)}, got {tell_failed!r}")
218
386
  if isinstance(priority, bool) or not isinstance(priority, int) or priority < 0:
219
387
  raise ValueError(f"priority is a whole number, 0 or more, got {priority!r}")
220
388
  if isinstance(again_seconds, bool) or not isinstance(again_seconds, (int, float)) or again_seconds < 0:
221
389
  raise ValueError(f"again_seconds is a number of seconds >= 0, got {again_seconds!r}")
390
+ if about is not None and (not isinstance(about, str) or not about.strip()):
391
+ raise ValueError("about is one sentence: the situation the node answers")
392
+ if report is not None and not callable(report):
393
+ raise TypeError("report is a function of the view and of what the node's program returned")
394
+ if not isinstance(ends, bool):
395
+ raise ValueError(f"ends is True or False, got {ends!r}")
396
+ if ends and ((do is None and action is None) or stops):
397
+ raise ValueError("ends=True goes with a program or with the name of an event to tell: it says that "
398
+ "what runs is ended when the node's turn comes")
222
399
  if every is not None:
223
400
  every = self.period if every is True else every
224
401
  if isinstance(every, bool) or not isinstance(every, (int, float)) or every < self.min_period - 1e-9:
@@ -243,7 +420,8 @@ class Reflexes:
243
420
  self._retire(self.nodes.get(name))
244
421
  self.nodes[name] = Reflex(name, when, event, do, action, stops, under, priority,
245
422
  None if every is None else float(every), float(again_seconds),
246
- old.order if old is not None else self._count, self.library_origin)
423
+ old.order if old is not None else self._count, self.library_origin, ends,
424
+ (about or "").strip(), report, tell, tell_failed)
247
425
  self._touched()
248
426
  return name
249
427
 
@@ -282,11 +460,20 @@ class Reflexes:
282
460
  if node.event is not None:
283
461
  lines[here] = f"answers the event {node.event}; began {node.triggered}"
284
462
  elif node.action is not None:
285
- lines[here] = ("ends what runs" if node.stops else f"tells you {node.action}") + f"; {node.triggered} times"
463
+ lines[here] = (("ends what runs" if node.stops else f"tells you {node.action}"
464
+ + (" and ends what runs" if node.ends else "")) + f"; {node.triggered} times")
286
465
  elif node.do is not None:
287
466
  running = node.unit is not None and bool(getattr(node.unit, "running", False))
288
467
  lines[here] = (f"began {node.triggered}, did its work {node.did}, did not {node.did_not}"
289
- + (", runs now" if running else ""))
468
+ + (", runs now" if running else "")
469
+ + (", ends what it interrupts" if node.ends else ""))
470
+ if here in lines:
471
+ lines[here] += _trial_text(node.trial)
472
+ # What is wrong with its condition, also of a node that does nothing itself.
473
+ wrong = ("not judged, its condition is too slow: set it again" if node.set_aside
474
+ else f"its condition raised {node.faults} time{'' if node.faults == 1 else 's'}" if node.fault else "")
475
+ if wrong:
476
+ lines[here] = f"{lines[here]}, {wrong}" if here in lines else wrong
290
477
  lines.update(self.digest(node.name, here + "/"))
291
478
  return lines
292
479
 
@@ -306,6 +493,39 @@ class Reflexes:
306
493
  if unit is not None and unit.running:
307
494
  threading.Thread(target=unit.cancel, name=f"reflex-{node.name}", daemon=True).start()
308
495
 
496
+ def tried(self, staged) -> tuple:
497
+ """For what a library entry set (stage()): how each of its nodes stands in the tree,
498
+ where it is the same node (its trial where it had one, how often it began and did its
499
+ work), and what is in the way of taking the entry as it stands there. ({name: what it
500
+ showed}, [why not, ...]). Nothing is run. The nodes found the same stay in the tree
501
+ when the entry is published."""
502
+ trials, problems = {}, []
503
+ if not staged.nodes:
504
+ problems.append("it sets no node")
505
+ for name, node in staged.nodes.items():
506
+ live = self.nodes.get(name)
507
+ if live is None:
508
+ problems.append(f"{name} is not in the tree: set it there, with its trial, and propose the same lines")
509
+ continue
510
+ differs = [part for part in ("event", "action", "under", "priority", "every", "again_seconds", "ends",
511
+ "tell", "tell_failed")
512
+ if getattr(node, part) != getattr(live, part)]
513
+ differs += [part for part in ("when", "do") if not same(getattr(node, part), getattr(live, part))]
514
+ if differs:
515
+ problems.append(f"{name} is not the node of that name in the tree (its {', '.join(differs)} "
516
+ "differ): propose the lines that set the node as it was tried")
517
+ elif live.trying:
518
+ problems.append(f"{name} is in its trial now")
519
+ elif isinstance(live.trial, dict) and live.trial.get("tried") and _trial_text(live.trial):
520
+ problems.append(f"{name} did not work in its trial")
521
+ else:
522
+ # (A trial is not required: a node that had none is kept as it stands in the tree.)
523
+ trial = live.trial if isinstance(live.trial, dict) else {"tried": False}
524
+ trials[name] = {**{key: trial[key] for key in ("tried", "turn", "seconds", "done") if key in trial},
525
+ "began": live.triggered, "did": live.did, "did_not": live.did_not}
526
+ staged.kept[name] = live
527
+ return trials, problems
528
+
309
529
  def publish(self, staged) -> None:
310
530
  """Put what a library entry set (stage()) into the tree."""
311
531
  for name, node in list(self.nodes.items()):
@@ -313,6 +533,10 @@ class Reflexes:
313
533
  for found in self._below(name):
314
534
  self._retire(self.nodes.pop(found.name, None))
315
535
  for name, node in staged.nodes.items():
536
+ if name in staged.kept and self.nodes.get(name) is staged.kept[name]:
537
+ # (The node that was tried: it stays as it is, and is the entry's from now on.)
538
+ self.nodes[name].library_origin = node.library_origin
539
+ continue
316
540
  self._retire(self.nodes.get(name))
317
541
  self.nodes[name] = node
318
542
  self._count = staged._count
@@ -359,7 +583,8 @@ class Reflexes:
359
583
  else the nodes under it; the earlier first, at most LISTED of them (then a last row
360
584
  {"omitted": how many}). Each: {"name", "priority", "when" ("a condition" or the event
361
585
  it answers), "does", "holds" (its condition held when last judged), "running" (its
362
- program runs now), "began" (how often its program began), "last" (the end report of
586
+ program runs now), "began" (how often its program began), "ends" (True: the unit its
587
+ program interrupts is ended, not resumed), "last" (the end report of
363
588
  its program's last run: {"ended", "done", "returned", "error", "seconds"}), "under":
364
589
  the names of the nodes under it (listing(name) gives them)}."""
365
590
  if name is not None and name not in self.nodes:
@@ -367,9 +592,12 @@ class Reflexes:
367
592
  nodes = self.children(name) or ([self.nodes[name]] if name is not None else [])
368
593
  rows = [{"name": node.name, "priority": node.priority,
369
594
  "when": f"the event {node.event}" if node.event else "a condition", "does": node.does,
595
+ **({"about": node.about} if node.about else {}),
370
596
  **({"holds": bool(node.holds)} if node.event is None and node.holds is not _UNSEEN else {}),
371
597
  **({"running": node.unit is not None and bool(getattr(node.unit, "running", False)),
372
- "began": node.triggered} if node.do is not None else {}),
598
+ "began": node.triggered, **({"ends": True} if node.ends else {})}
599
+ if node.do is not None else {}),
600
+ **({"trial": dict(node.trial)} if isinstance(node.trial, dict) else {}),
373
601
  **({"last": node.last} if node.last is not None else {}),
374
602
  **({"under": [child.name for child in self.children(node.name)]}
375
603
  if self.children(node.name) else {})}
@@ -381,23 +609,36 @@ class Reflexes:
381
609
  def _run(self, node, view):
382
610
  """Whether the node's condition holds on `view`. Where it was not judged (the
383
611
  period's budget was used up before its turn, or it was ended at the hard limit), what
384
- it was: it is judged in the next period. A condition slower than the budget
385
- LATE_TIMES in a row, ended or not, is a fault."""
612
+ it was: it is judged in the next period. A fault of the condition never removes the
613
+ node (_faulted): one that raises does not hold this once and is judged again the
614
+ next time; one slower than the budget LATE_TIMES in a row, ended or not, is set
615
+ aside, because it would use up every period the nodes after it share: it does not
616
+ hold, and is not judged, until the node is set again."""
386
617
  with self.library_boundary:
387
618
  if self.nodes.get(node.name) is not node:
388
619
  return None
620
+ if node.set_aside:
621
+ return False
389
622
  over, judged = [], True
390
623
  try:
391
624
  result = call_reactive(node.name, node.when, view, budget_seconds=self.budget_seconds, late=over.append)
392
625
  except NotJudged:
393
626
  judged = False
627
+ except ReactiveFault as found:
628
+ node.late, node.waits = 0, False
629
+ self._faulted(node, f"its condition raised {found.reason}. The node stays in the tree: its "
630
+ "condition counts as not holding each time it raises")
631
+ return False
394
632
  if over:
395
633
  node.late += 1
396
634
  elif judged:
397
635
  node.late = 0
398
636
  if node.late >= LATE_TIMES:
399
- raise ReactiveFault(node.name, f"its condition took {over[0] * 1000:.1f} ms, longer than its budget of "
400
- f"{self.budget_seconds * 1000:.1f} ms {LATE_TIMES} times in a row")
637
+ node.set_aside, node.waits = True, False
638
+ self._faulted(node, f"its condition took {over[0] * 1000:.1f} ms, longer than its budget of "
639
+ f"{self.budget_seconds * 1000:.1f} ms {LATE_TIMES} times in a row. The node stays in "
640
+ "the tree and is not judged, nor are the nodes under it, until it is set again")
641
+ return False
401
642
  node.waits = not judged
402
643
  if not judged:
403
644
  return None if node.holds is _UNSEEN else node.holds
@@ -406,6 +647,16 @@ class Reflexes:
406
647
  ok=True, rule=node.name, testing=spans.in_test())
407
648
  return result
408
649
 
650
+ def _faulted(self, node, reason) -> None:
651
+ """Note what went wrong with the node's condition. The model is told each reason
652
+ once (the tick tells `fault_tell`); how often it happened is in the node's line."""
653
+ node.fault, node.faults = reason, node.faults + 1
654
+ key = reason[:200]
655
+ if key not in node.fault_told:
656
+ node.fault_told.add(key)
657
+ node.fault_tell = reason
658
+ self.changed = True
659
+
409
660
  def _above_hold(self, node, view) -> bool:
410
661
  """Whether the conditions of the nodes above `node` hold on `view`."""
411
662
  above = self.nodes.get(node.under) if node.under is not None else None
@@ -417,12 +668,35 @@ class Reflexes:
417
668
 
418
669
  def stops(self) -> bool:
419
670
  """Whether a node ends what runs (those are judged at every step of an execution)."""
420
- return any(node.stops for node in self.nodes.copy().values())
671
+ return any(self._ends_what_runs(node) for node in self.nodes.copy().values())
672
+
673
+ @staticmethod
674
+ def _ends_what_runs(node) -> bool:
675
+ """A node whose turn ends the execution that runs: one that does an action of the
676
+ environment that ends it ("stop"), or one that tells an event and says ends=True (the
677
+ execution then ends with that event, which is how the model is told)."""
678
+ return node.stops or (node.ends and node.action is not None and node.do is None)
679
+
680
+ def _answered(self, node) -> bool:
681
+ """Whether a node whose turn comes before `node`'s is answering now: one under it, or
682
+ one before it at its place. A node that tells does so only when none of them is."""
683
+ place = self.children(node.under)
684
+ earlier = place[:place.index(node)] if node in place else []
685
+ before = self._below(node.name)[1:] + [leaf for other in earlier for leaf in self._leaves(other.name)]
686
+ return any(found.unit is not None and getattr(found.unit, "running", False) for found in before)
421
687
 
422
688
  def evaluate(self, view) -> Reflex | None:
423
- """The first node that ends what runs and whose turn it is now."""
689
+ """The first node that ends what runs and whose turn it is now. One that tells and
690
+ ends what runs has its turn as in the tick: not while a node under it, or before it
691
+ at its place, is answering (what runs then is that node's answer, not something the
692
+ situation is unanswered in)."""
424
693
  for node in self._ordered():
425
- if node.stops and self._above_hold(node, view) and self._run(node, view):
694
+ if self._ends_what_runs(node) and self._above_hold(node, view) and self._run(node, view):
695
+ if not node.stops:
696
+ if node.raised or time.monotonic() < node.ready_at or self._answered(node):
697
+ continue
698
+ # (Told by the end of what ran: not told again while its condition holds.)
699
+ node.raised, node.ready_at = True, time.monotonic() + node.again_seconds
426
700
  node.triggered += 1
427
701
  return node
428
702
  return None
@@ -453,7 +727,7 @@ class Reflexes:
453
727
  def next_due(self, now) -> float | None:
454
728
  """Seconds until the tree is due on time (0 when it is), None when it never is."""
455
729
  due = [node.next_at for node in self.nodes.copy().values()
456
- if node.every is not None and node.event is None and not node.stops]
730
+ if node.every is not None and node.event is None and not node.stops and not node.set_aside]
457
731
  if self.wake_at is not None:
458
732
  due.append(self.wake_at)
459
733
  return max(0.0, min(due) - now) if due else None
@@ -467,6 +741,174 @@ def fault_event(fault, step, **detail):
467
741
  return Event(ev.REACTIVE_FAULT, fault.source, {"reason": fault.reason, **detail}, step)
468
742
 
469
743
 
744
+ def message(function, *arguments) -> dict:
745
+ """What a report function (a node's report=, a program's until(report=)) returns, as the
746
+ message the model reads. It returns what a message holds, alone or in a list, in the
747
+ order given: text; plain data (told as JSON); a picture (what look() or get_observation()
748
+ returned, or an RGB array); a file (a pathlib.Path: an image file as its picture, a folder
749
+ as its names, any other file as its text). {"says": the text, "shows": [{"caption",
750
+ "image_url"}], "files": [{"name", "text"}]}, each only where there is something; the text
751
+ at most SAID_CHARS, REPORT_PICTURES pictures, REPORT_FILES files of FILE_CHARS each. What
752
+ went wrong where the function raises is the text."""
753
+ import json
754
+ import os
755
+ from pathlib import Path
756
+
757
+ if function is None:
758
+ return {}
759
+ texts, shows, files = [], [], []
760
+
761
+ def add(item, depth=0):
762
+ if item is None:
763
+ return
764
+ if isinstance(item, str):
765
+ texts.append(item)
766
+ elif isinstance(item, os.PathLike):
767
+ path = Path(item)
768
+ if not path.exists():
769
+ texts.append(f"(no file {path})")
770
+ elif path.is_dir():
771
+ names = sorted(child.name + ("/" if child.is_dir() else "") for child in path.iterdir())
772
+ files.append({"name": str(path), "text": "\n".join(names[:500])})
773
+ elif path.suffix.lower() in _PICTURES:
774
+ from harness.core.codec import data_url
775
+
776
+ shows.append({"caption": path.name, "image_url": data_url(path.read_bytes(), _PICTURES[path.suffix.lower()])})
777
+ else:
778
+ text = path.read_text(encoding="utf-8", errors="replace")
779
+ files.append({"name": str(path), "text": text if len(text) <= FILE_CHARS
780
+ else text[:FILE_CHARS] + f" ... [{len(text) - FILE_CHARS} more characters]"})
781
+ elif isinstance(getattr(item, "_urls", None), dict):
782
+ shows.extend({"caption": str(name), "image_url": url} for name, url in item._urls.items())
783
+ elif isinstance(item, (list, tuple)) and depth < 3:
784
+ for each in item:
785
+ add(each, depth + 1)
786
+ elif hasattr(item, "shape") and hasattr(item, "dtype"):
787
+ from harness.core.codec import image_data_url
788
+
789
+ shows.append({"caption": "", "image_url": image_data_url(item, "jpeg")})
790
+ else:
791
+ texts.append(json.dumps(item, default=str, ensure_ascii=False))
792
+
793
+ try:
794
+ add(function(*arguments))
795
+ except BaseException as error:
796
+ texts.append(f"(its report raised {type(error).__name__}: {error})")
797
+ text = " ".join(part for part in texts if part)
798
+ if len(text) > SAID_CHARS:
799
+ text = text[:SAID_CHARS] + "..."
800
+ return {**({"says": text} if text else {}), **({"shows": shows[:REPORT_PICTURES]} if shows else {}),
801
+ **({"files": files[:REPORT_FILES]} if files else {})}
802
+
803
+
804
+ def message(function, *arguments) -> dict:
805
+ """What a report function (a node's report=, a program's until(report=)) returns, as the
806
+ message the model reads. It returns what a message holds, alone or in a list, in the
807
+ order given: text; plain data (told as JSON); a picture (what look() or get_observation()
808
+ returned, or an RGB array); a file (a pathlib.Path: an image file as its picture, a folder
809
+ as its names, any other file as its text). {"says": the text, "shows": [{"caption",
810
+ "image_url"}], "files": [{"name", "text"}]}, each only where there is something; the text
811
+ at most SAID_CHARS, REPORT_PICTURES pictures, REPORT_FILES files of FILE_CHARS each. What
812
+ went wrong where the function raises is the text."""
813
+ import json
814
+ import os
815
+ from pathlib import Path
816
+
817
+ if function is None:
818
+ return {}
819
+ texts, shows, files = [], [], []
820
+
821
+ def add(item, depth=0):
822
+ if item is None:
823
+ return
824
+ if isinstance(item, str):
825
+ texts.append(item)
826
+ elif isinstance(item, os.PathLike):
827
+ path = Path(item)
828
+ if not path.exists():
829
+ texts.append(f"(no file {path})")
830
+ elif path.is_dir():
831
+ names = sorted(child.name + ("/" if child.is_dir() else "") for child in path.iterdir())
832
+ files.append({"name": str(path), "text": "\n".join(names[:500])})
833
+ elif path.suffix.lower() in _PICTURES:
834
+ from harness.core.codec import data_url
835
+
836
+ shows.append({"caption": path.name, "image_url": data_url(path.read_bytes(), _PICTURES[path.suffix.lower()])})
837
+ else:
838
+ text = path.read_text(encoding="utf-8", errors="replace")
839
+ files.append({"name": str(path), "text": text if len(text) <= FILE_CHARS
840
+ else text[:FILE_CHARS] + f" ... [{len(text) - FILE_CHARS} more characters]"})
841
+ elif isinstance(getattr(item, "_urls", None), dict):
842
+ shows.extend({"caption": str(name), "image_url": url} for name, url in item._urls.items())
843
+ elif isinstance(item, (list, tuple)) and depth < 3:
844
+ for each in item:
845
+ add(each, depth + 1)
846
+ elif hasattr(item, "shape") and hasattr(item, "dtype"):
847
+ from harness.core.codec import image_data_url
848
+
849
+ shows.append({"caption": "", "image_url": image_data_url(item, "jpeg")})
850
+ else:
851
+ texts.append(json.dumps(item, default=str, ensure_ascii=False))
852
+
853
+ try:
854
+ add(function(*arguments))
855
+ except BaseException as error:
856
+ texts.append(f"(its report raised {type(error).__name__}: {error})")
857
+ text = " ".join(part for part in texts if part)
858
+ if len(text) > SAID_CHARS:
859
+ text = text[:SAID_CHARS] + "..."
860
+ return {**({"says": text} if text else {}), **({"shows": shows[:REPORT_PICTURES]} if shows else {}),
861
+ **({"files": files[:REPORT_FILES]} if files else {})}
862
+
863
+
864
+ def said(function, *arguments):
865
+ """The text of what a report function returns (message), or None."""
866
+ return message(function, *arguments).get("says")
867
+
868
+
869
+ def urgent(*places):
870
+ """The most urgent of the places in the model's queue (QUEUE; None: none)."""
871
+ named = [place for place in places if place in QUEUE]
872
+ return max(named, key=QUEUE.index) if named else None
873
+
874
+
875
+ def interrupted_by(session, node, unit, view) -> tuple:
876
+ """The units the program `unit` of `node` took the environment from and that go on: a
877
+ row for each ({"unit", "name", "times" this node took it from that unit, "paused_seconds"
878
+ in all, "seconds" it has run, "done" (its condition now), "says" (its own report),
879
+ "asked" (it asks to be told)}), those of them that ask to be told (until(interrupted="tell")), and the place in the queue
880
+ they ask for ("next" where one was told fewer than INTERRUPTIONS_TOLD times; else None)."""
881
+ rows, asking, now = [], [], time.monotonic()
882
+ entries = getattr(session, "_entries", None)
883
+ for entry in dict.fromkeys(getattr(unit, "took", ())):
884
+ if not entry.running:
885
+ continue
886
+ done = entries._completed(entry) if entries is not None else None
887
+ rows.append({"unit": entry.id, "name": entry.name,
888
+ "times": sum(1 for pause in entry.pauses if pause["by"] == node.name),
889
+ "paused_seconds": round(sum((pause.get("until") or now) - pause["at"] for pause in entry.pauses), 1),
890
+ "seconds": round(time.time() - entry.started, 1),
891
+ **({"done": done} if done is not None else {}),
892
+ **(entries.reports(entry) if entries is not None else {})})
893
+ # (A reflex's own program is the tree's: its node says what the model hears of it.)
894
+ if entry.interrupted == "tell" and getattr(entry, "rule", None) is None:
895
+ asking.append(entry)
896
+ rows[-1]["asked"] = True
897
+ place = "next" if any(entry.interruptions_told < INTERRUPTIONS_TOLD for entry in asking) else None
898
+ return rows, asking, place
899
+
900
+
901
+ def counted(asking, told: bool) -> None:
902
+ """The units that asked to be told of this interruption: counted as told where the
903
+ message went out and they were told fewer than INTERRUPTIONS_TOLD times, else as one
904
+ more that is told with their end."""
905
+ for entry in asking:
906
+ if told and entry.interruptions_told < INTERRUPTIONS_TOLD:
907
+ entry.interruptions_told += 1
908
+ else:
909
+ entry.interruptions_untold += 1
910
+
911
+
470
912
  def emit(tree, owner, skill, event, *, notice=False):
471
913
  if tree is not None:
472
914
  tree.raise_event(tree.get(owner), ExecutionTrace(skill, {}, event.tick, event.tick, event), notice=notice)
@@ -524,9 +966,29 @@ def judge(session, tree):
524
966
  node.ready_at = now + RESTART_SECONDS
525
967
  continue
526
968
  node.last = report(unit)
969
+ # What the model reads of this turn of the node: the node's own sentence and report, and
970
+ # the units it took the environment from with theirs.
971
+ rows, asking, theirs = interrupted_by(session, node, unit, view_of())
972
+ with session.reporting():
973
+ own_report = message(node.report, view_of(), unit.result)
974
+ node.reads = {**({"about": node.about} if node.about else {}), **own_report,
975
+ **({"interrupted": rows} if rows else {})}
976
+ node.asked, node.asking = theirs, asking
527
977
  if unit.status == "done" and unit.ok is not False:
528
978
  node.did += 1
529
979
  node.ready_at, node.told = now + max(node.again_seconds, RESTART_SECONDS), False
980
+ # The node says whether the model hears that it did its work, and how soon: each
981
+ # time, with its place in the queue, or the first time only (with the model's
982
+ # next call), or never. A program it took the environment from may ask to be told
983
+ # too (until(interrupted="tell")): one message, at the more urgent of the two places.
984
+ own = node.tell if node.tell in QUEUE else "next" if node.tell == "first" and not node.acted else None
985
+ place = urgent(own, theirs)
986
+ counted(asking, not node.trying and place is not None)
987
+ if not node.trying and place is not None:
988
+ node.acted = node.acted or own is not None
989
+ emit(tree, None, "reflex", Event(ev.REFLEX_ACTED, node.name, {
990
+ "reflex": node.name, "unit": unit.id, "began": node.triggered, **node.last, **node.reads,
991
+ "tell": place}, state.get("step")))
530
992
  else:
531
993
  node.did_not += 1
532
994
  # It failed, or it ended and the situation it answers is not over.
@@ -534,9 +996,8 @@ def judge(session, tree):
534
996
  failures.append((node, unit))
535
997
 
536
998
  def fault(node, error):
537
- found = error if isinstance(error, ReactiveFault) else ReactiveFault(node.name, f"{type(error).__name__}: {error}")
538
- layer.drop(node.name)
539
- emit(tree, None, "reflex", session._rule_event(found, state))
999
+ # (What went wrong while the node was judged, other than in its condition itself.)
1000
+ layer._faulted(node, f"{type(error).__name__}: {error}. The node stays in the tree")
540
1001
 
541
1002
  def holds(node) -> bool:
542
1003
  if node.every is not None:
@@ -555,8 +1016,9 @@ def judge(session, tree):
555
1016
  wanting, telling = [], []
556
1017
 
557
1018
  def over(node):
558
- # What a node's program is for: the situation the node answers is over.
559
- return lambda view: not layer._run(node, view)
1019
+ # What a node's program is for: the situation the node answers is over. A node under
1020
+ # others is a narrower situation within theirs: it is over when theirs is, too.
1021
+ return lambda view: not (layer._above_hold(node, view) and layer._run(node, view))
560
1022
 
561
1023
  def walk(name):
562
1024
  # The nodes at and under `name` whose condition holds, the earlier first; under a
@@ -628,15 +1090,29 @@ def judge(session, tree):
628
1090
  # A node that tells the model has its turn like any other: when none of those whose
629
1091
  # turn comes before its own (under it, and before it at its place) is acting. So it
630
1092
  # tells what nothing answered, and no more.
1093
+ # (While an execution runs, a node that tells and ends what runs does both at that
1094
+ # execution's next step, where it is judged with the nodes that end what runs: the
1095
+ # execution ends with the node's event. Here it tells only when nothing runs.)
1096
+ ticker = session.__dict__.get("_tick_loop")
1097
+ executing = ticker is not None and any(
1098
+ getattr(entry, "steps", None) is not None and getattr(entry, "paused", None) is None
1099
+ for entry in list(getattr(ticker, "_entries", ())))
631
1100
  for node, before in telling:
632
1101
  if any(found.name in startable for found in before):
633
1102
  continue
1103
+ if node.ends and executing:
1104
+ continue
634
1105
  if not node.raised and now >= node.ready_at:
635
1106
  node.raised, node.ready_at = True, now + node.again_seconds
636
1107
  node.triggered += 1
637
1108
  # (The event is offered to the nodes that answer its kind; one that none answers
638
1109
  # reaches the model: that is what telling is.)
639
1110
  emit(tree, None, "reflex", session._rule_event(node, state))
1111
+ for node in list(layer.nodes.values()):
1112
+ if node.fault_tell is not None:
1113
+ reason, node.fault_tell = node.fault_tell, None
1114
+ emit(tree, None, "reflex", Event(ev.REACTIVE_FAULT, node.name, {
1115
+ "reason": reason, "times": node.faults, "set_aside": node.set_aside}, state.get("step")))
640
1116
  layer.tell()
641
1117
  for node, unit in failures:
642
1118
  # What comes after a node whose program did not do its work: a later node at its
@@ -647,8 +1123,13 @@ def judge(session, tree):
647
1123
  taken = any(found.name in startable for other in later for found in layer._leaves(other.name)) or any(
648
1124
  above.name in startable or (above.action is not None and not above.stops and above.raised)
649
1125
  for above in layer._above(node))
1126
+ place = None if node.told or taken else urgent(node.tell_failed, getattr(node, "asked", None))
1127
+ counted(getattr(node, "asking", ()), place is not None)
650
1128
  if node.told or taken:
651
1129
  continue
652
1130
  node.told = True
1131
+ if place is None:
1132
+ continue
653
1133
  emit(tree, None, "reflex", Event(ev.REFLEX_FAILED, node.name, {
654
- "reflex": node.name, "unit": unit.id, "began": node.triggered, **node.last}, state.get("step")))
1134
+ "reflex": node.name, "unit": unit.id, "began": node.triggered, **node.last,
1135
+ **(getattr(node, "reads", None) or {}), "tell": place}, state.get("step")))