@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,15 +1,14 @@
1
- """What the host asks of a running program besides its cells.
1
+ """What the host asks of the kernel's units besides starting programs.
2
2
 
3
3
  The kernel process reads the host's requests on a thread of its own, so a request
4
- reaches a program while it runs: a pause (the user paused the conversation) makes the
5
- next step of a bounded execution end it with USER_PAUSED (runtime/execution/session.py). A
6
- message for the model (the user's, or the parent agent's) interrupts the program's own
7
- code, not the entries it started: its execution ends at the next step with USER_MESSAGE,
8
- and a wait of it (an entry's wait(), wait_agents()) raises that event at once
9
- (runtime/execution/entries.py). The flags are cleared when the next cell starts. An answer is the host's reply to a request a
10
- program sent it as a note (the user's answer to a physical-input request,
11
- runtime/safety/input.py): the program waits for it, or for a pause. When a sub-agent the
12
- program started ends, the host says so, and its entry ends (runtime/execution/entries.py).
4
+ reaches a unit while it runs. A pause (the user paused the conversation) stops every unit
5
+ of the model: the next step of a bounded execution ends it with USER_PAUSED
6
+ (runtime/execution/session.py), a wait raises that event (runtime/execution/entries.py), and
7
+ nothing acts until the host resumes. A message for the model stops nothing here: it is an
8
+ event to the model, whose turn is its own (runtime/task/run.py). An answer is the host's
9
+ reply to a request a unit sent it as a note (the user's answer to a physical-input request,
10
+ runtime/safety/input.py): the unit waits for it, or for a pause. When a sub-agent ends, the
11
+ host says so, and its unit ends (runtime/execution/entries.py).
13
12
  """
14
13
 
15
14
  import sys
@@ -19,7 +18,6 @@ import uuid
19
18
 
20
19
 
21
20
  _pause = threading.Event()
22
- _message = threading.Event()
23
21
  _answers = {}
24
22
  _answered = threading.Condition()
25
23
  _agent_listeners = []
@@ -31,32 +29,19 @@ host_thoughts = False
31
29
 
32
30
 
33
31
  def request_pause() -> None:
34
- """Ask the running program to stop at its next execution step."""
32
+ """Stop the model's units: each at its next execution step or wait."""
35
33
  with _answered:
36
34
  _pause.set()
37
35
  _answered.notify_all()
38
36
 
39
37
 
40
- def request_message() -> None:
41
- """Tell the running program a message for the model came."""
42
- with _answered:
43
- _message.set()
44
- _answered.notify_all()
45
-
46
-
47
- def clear() -> None:
48
- """Forget earlier requests (a new cell starts)."""
38
+ def resume() -> None:
39
+ """The pause is over: units may act again."""
49
40
  _pause.clear()
50
- _message.clear()
51
-
52
-
53
- def message_arrived() -> bool:
54
- """Whether a message for the model came while the program runs."""
55
- return _message.is_set()
56
41
 
57
42
 
58
43
  def pause_requested() -> bool:
59
- """Whether the host asked the running program to pause."""
44
+ """Whether the model's units are paused."""
60
45
  return _pause.is_set()
61
46
 
62
47
 
@@ -153,12 +138,10 @@ def think(role, text="", *, images=(), system=None, entry=None, frame=None, stop
153
138
  sys.audit("harness.model_request", role)
154
139
  if not host_thoughts or not spans.connected():
155
140
  return None
156
- if stop is None and threading.current_thread() is threading.main_thread():
157
- stop = message_arrived
158
141
  owner = current_entry()
159
142
 
160
143
  def owner_cancelled():
161
- return owner is not None and any(entry._cancel.is_set() for entry in owner.lineage())
144
+ return owner is not None and owner._cancel.is_set()
162
145
 
163
146
  identifier = uuid.uuid4().hex
164
147
  with _answered:
@@ -186,11 +169,10 @@ def think(role, text="", *, images=(), system=None, entry=None, frame=None, stop
186
169
 
187
170
 
188
171
  def stopped(skill: str = "program"):
189
- """The typed escalation for an interrupted program wait."""
190
- from harness.runtime.events import USER_MESSAGE, USER_PAUSED, Escalation, Event, ExecutionTrace
172
+ """The typed escalation for a unit's wait that the user's pause interrupted."""
173
+ from harness.runtime.events import USER_PAUSED, Escalation, Event, ExecutionTrace
191
174
 
192
- event = Event(USER_PAUSED if pause_requested() else USER_MESSAGE, "user")
193
- return Escalation(ExecutionTrace(skill, {}, 0, 0, event))
175
+ return Escalation(ExecutionTrace(skill, {}, 0, 0, Event(USER_PAUSED, "user")))
194
176
 
195
177
 
196
178
  def on_agent_ended(listener, remove: bool = False) -> None:
@@ -1,7 +1,10 @@
1
- """Concurrent entries and bounded ClosedLoop executions.
1
+ """Units of a kernel session, and bounded ClosedLoop executions.
2
2
 
3
- Entry events go through handlers from their source to the root. An unanswered event
4
- reaches the running program at its next harness call, or at the end of the program.
3
+ A session has one model (the root entry) and the units it started: every program the model
4
+ writes, every function a program spawns, every sub-agent. A unit has its own output, events
5
+ and pictures (its box) and its own result. What a unit starts belongs to the model, not to
6
+ the unit: it outlives the program that started it and ends with the model. An event goes
7
+ through the handlers; one nobody answers reaches the model, and so does every unit's end.
5
8
  """
6
9
 
7
10
  import collections
@@ -14,15 +17,11 @@ from harness.core import spans
14
17
  from harness.runtime.execution import control
15
18
  from harness.runtime import events as ev
16
19
  from harness.runtime.reactive import rules as reactive
20
+ from harness.runtime.reactive import tree as reflexes
17
21
  from harness.runtime.events import EpisodeEnded, Escalation, Event, ExecutionTrace, ProgramFinished
18
22
 
19
23
 
20
- def user_message(skill: str, parameters: dict | None = None) -> ExecutionTrace:
21
- """The trace of what a message for the model stopped (runtime/execution/control.py)."""
22
- return ExecutionTrace(skill, dict(parameters or {}), 0, 0, Event(ev.USER_MESSAGE, "user"))
23
-
24
-
25
- # The root entry: the agent's own programs.
24
+ # The root entry: the model, to which every unit of the session belongs.
26
25
  ROOT = "e0"
27
26
  # How long a cancelled entry has to stop by itself before it is interrupted where it is.
28
27
  GRACE = 0.5
@@ -35,10 +34,21 @@ _local = threading.local()
35
34
 
36
35
 
37
36
  def current_entry():
38
- """The entry executing on this thread, or None for the main program."""
37
+ """The entry executing on this thread, or None outside every unit."""
39
38
  return getattr(_local, "entry", None)
40
39
 
41
40
 
41
+ class Box:
42
+ """What one unit gathered for the model: its output (a writer the kernel gives it, whose
43
+ recent(chars) is what was printed last), the pictures it showed and looked at, and the
44
+ events of its executions."""
45
+
46
+ def __init__(self):
47
+ self.output = None
48
+ self.attachments, self.events, self.looks = [], [], []
49
+ self.event_counts = {}
50
+
51
+
42
52
  class Cancelled(BaseException):
43
53
  """Raised in an entry's code when the entry was cancelled; a BaseException so that the
44
54
  broad excepts of a program do not keep it running."""
@@ -50,10 +60,16 @@ def _short(value, limit=200) -> str:
50
60
 
51
61
 
52
62
  class Entry:
53
- """One entry of a session's tree (see the module docstring): its `id`, `name`, `kind`
54
- ("root", "program" for spawned code, "agent" for a sub-agent), the entry that started
55
- it (`parent`), its `claims`, its `status` (running, done, failed, cancelled) and, once
56
- ended, what its function returned (`result`) or why it failed (`error`)."""
63
+ """One unit of a session (see the module docstring): its `id`, `name`, `kind` ("root"
64
+ for the model, "program" for code, "agent" for a sub-agent), the model it belongs to
65
+ (`parent`), its `claims`, its `status` (running, done, failed, cancelled) and, once
66
+ ended, what its function returned (`result`) or why it failed (`error`). `cell` is the
67
+ number of the model's program it is (None for spawned code), `rule` the name of the rule
68
+ whose program it is (the rules that program sets live with it), `priority` what it holds
69
+ the embodiment with and `restart` whether an execution of it that a higher unit ended
70
+ is started again (runtime/tick.py; default: it ends with PREEMPTED), `box` what it gathered,
71
+ `outcome` how its code ended ({"status": ok, error, escalated, episode_ended, finished
72
+ or cancelled, ...}), `raised` the exception of an error."""
57
73
 
58
74
  def __init__(self, tree, identifier, name, kind, parent, claims=(), agent=None):
59
75
  self.tree = tree
@@ -64,6 +80,20 @@ class Entry:
64
80
  self.claims = tuple(claims)
65
81
  self.agent = agent
66
82
  self.children = []
83
+ self.cell = None
84
+ self.rule = None
85
+ self.priority = 0
86
+ self.restart = False
87
+ # What it is for: a condition of the view that holds when its work is done (None: it
88
+ # states none), and whether it held when the unit ended (None: no condition).
89
+ self.until = None
90
+ self.ok = None
91
+ # A tree started it (runtime/reactive/tree.py): its end is the tree's business and
92
+ # is recorded without being told to the model.
93
+ self.quiet = False
94
+ self.box = Box()
95
+ self.outcome = None
96
+ self.raised = None
67
97
  self.status = "running"
68
98
  self.result = None
69
99
  self.error = None
@@ -76,9 +106,6 @@ class Entry:
76
106
  self._cancel = threading.Event()
77
107
  self._done = threading.Event()
78
108
  self._waiters = 0
79
- # The root only: what nobody handled, for the model (an Escalation, EpisodeEnded or
80
- # ProgramFinished to raise in the program that runs).
81
- self.pending = collections.deque()
82
109
 
83
110
  def __repr__(self) -> str:
84
111
  return f"<entry {self.id} {self.name!r} {self.kind} {self.status}>"
@@ -138,6 +165,14 @@ class Entry:
138
165
  raise self.failure
139
166
  return self.result if self.status == "done" else None
140
167
 
168
+ def output(self, chars=2000) -> str:
169
+ """What this unit has printed so far: the last `chars` characters (at most 30000),
170
+ while it runs or after it ended. Reading takes nothing away: its result still has
171
+ the whole output when it ends. "" for a unit that printed nothing (a sub-agent
172
+ prints nothing here: its report is its result)."""
173
+ writer = self.box.output
174
+ return writer.recent(chars) if writer is not None else ""
175
+
141
176
  def send(self, message):
142
177
  """Send this entry a message, which its code reads with receive() (a sub-agent: the
143
178
  answer to its question, or more to do)."""
@@ -151,14 +186,11 @@ class Entry:
151
186
  self.tree._changed.notify_all()
152
187
 
153
188
  def cancel(self, timeout=5.0):
154
- """Stop this entry and the entries it started (theirs first): the execution it runs
155
- ends at its next step, a wait or receive it is in raises, and code that does not
156
- reach the harness is interrupted where it is after a moment. Returns its state."""
189
+ """Stop this unit: the execution it runs ends at its next step, a wait or receive it
190
+ is in raises, and code that does not reach the harness is interrupted where it is
191
+ after a moment. What it started goes on (it is the model's). Returns its state."""
157
192
  if self.kind == "root":
158
- raise ValueError("the root entry is the agent's own program; finish() ends it")
159
- for child in list(self.children):
160
- if child.running:
161
- child.cancel(timeout)
193
+ raise ValueError("the root entry is the model; finish() ends the run")
162
194
  if not self.running:
163
195
  return self.state()
164
196
  self._cancel.set()
@@ -194,16 +226,19 @@ class Entry:
194
226
 
195
227
 
196
228
  class Tree:
197
- """The entries of one kernel session (see the module docstring)."""
229
+ """The units of one kernel session (see the module docstring). `on_end(entry, handled)`
230
+ is called once for every unit that ended (the kernel tells the model,
231
+ runtime/execution/kernel.py); `new_output(entry)` gives a new unit the writer of its output."""
198
232
 
199
233
  def __init__(self, session):
200
234
  self.session = session
201
235
  self._changed = threading.Condition(threading.RLock())
202
236
  self._count = 0
203
- self.root = Entry(self, ROOT, "main", "root", None)
237
+ self.root = Entry(self, ROOT, "model", "root", None)
204
238
  self.entries = {ROOT: self.root}
205
- self._ended = []
206
239
  self._closed = False
240
+ self.on_end = None
241
+ self.new_output = None
207
242
  control.on_agent_ended(self.agent_ended)
208
243
 
209
244
  # Where code runs.
@@ -229,40 +264,45 @@ class Tree:
229
264
 
230
265
  def check(self, entry=None) -> None:
231
266
  """Raise in the code of `entry` (default: the caller's) what it must stop for: its
232
- cancellation, or, for the root, an event that reaches the model."""
267
+ cancellation, or the user's pause."""
233
268
  stop = self.interruption(entry or self.current())
234
269
  if stop is not None:
235
270
  raise stop
236
271
 
237
272
  def interruption(self, entry, take=True):
238
- """What `entry`'s code must stop for now (see check), or None; `take` False leaves
239
- the root's event waiting. The root's code also stops for a message for the model
240
- (runtime/execution/control.py), with a USER_MESSAGE event."""
241
- for above in entry.lineage():
242
- if above._cancel.is_set():
243
- return Cancelled(f"entry {above.id} ({above.name}) was cancelled")
244
- if entry is self.root and control.message_arrived():
245
- return Escalation(user_message("program"))
246
- if entry is self.root and self.root.pending:
247
- with self._changed:
248
- if self.root.pending:
249
- return self.root.pending.popleft() if take else self.root.pending[0]
273
+ """What `entry`'s code must stop for now (see check), or None: every unit of the
274
+ model stops while the user has paused it (runtime/execution/control.py)."""
275
+ if entry._cancel.is_set():
276
+ return Cancelled(f"entry {entry.id} ({entry.name}) was cancelled")
277
+ if entry is not self.root and control.pause_requested():
278
+ return Escalation(ExecutionTrace("program", {}, 0, 0, Event(ev.USER_PAUSED, "user")))
250
279
  return None
251
280
 
252
281
  # Starting entries.
253
282
 
254
- def spawn(self, fn, name=None, claims=None) -> Entry:
255
- """Run fn() as a new entry under the caller's (see the module docstring)."""
283
+ def spawn(self, fn, name=None, claims=None, *, cell=None, rule=None, priority=None, restart=False,
284
+ quiet=False, until=None) -> Entry:
285
+ """Run fn() as a new unit of the model (see the module docstring); `cell`: it is the
286
+ model's program of that number; `rule`: it is the program of that rule; `priority`:
287
+ its own (default: that of the unit that starts it); `restart` True: an execution of
288
+ it that a unit of higher priority ends is started again when that unit is over
289
+ (default: it ends there with PREEMPTED)."""
256
290
  sys.audit("harness.execution")
257
291
  if not callable(fn):
258
292
  raise TypeError("spawn(fn, name, claims): fn must be callable")
259
- parent = self.current()
260
- self.check(parent)
293
+ self.check(self.current())
261
294
  claims = [claims] if isinstance(claims, str) else list(claims or [])
262
295
  tick = self._channels()
263
296
  if tick is not None:
264
297
  tick.known(claims)
265
- entry = self._add(str(name or getattr(fn, "__name__", "entry")), "program", parent, claims)
298
+ if priority is not None and (isinstance(priority, bool) or not isinstance(priority, (int, float))):
299
+ raise ValueError(f"priority is a number, got {priority!r}")
300
+ entry = self._add(str(name or getattr(fn, "__name__", "entry")), "program", self.root, claims, cell=cell,
301
+ rule=rule, priority=self.current().priority if priority is None else priority)
302
+ entry.restart, entry.quiet = bool(restart), bool(quiet)
303
+ if until is not None and not callable(until):
304
+ raise TypeError("until is a condition: a function of the view that holds when the unit's work is done")
305
+ entry.until = until
266
306
  conflict = tick.claim(entry, claims) if tick is not None and claims else {}
267
307
  span = spans.current()
268
308
  testing = spans.in_test()
@@ -271,6 +311,7 @@ class Tree:
271
311
  _local.entry = entry
272
312
  spans.set_entry(entry.id)
273
313
  status, result, error, failure = "done", None, None, None
314
+ entry.outcome = {"status": "ok"}
274
315
  try:
275
316
  with spans.under(span), spans.testing(testing):
276
317
  self.check(entry)
@@ -278,23 +319,65 @@ class Tree:
278
319
  raise Escalation(self._conflict(entry, conflict))
279
320
  result = fn()
280
321
  except Cancelled:
281
- status = "cancelled"
322
+ status, entry.outcome = "cancelled", {"status": "cancelled"}
282
323
  except Escalation as escalation:
283
324
  status, failure = "failed", escalation.trace.event
284
325
  error = f"{failure.kind} from {failure.source}"
285
- except (EpisodeEnded, ProgramFinished) as stop:
286
- # The episode ended, or the task is done: the agent's program hears of it,
287
- # and the entry is no event of its own.
288
- status, error = ("cancelled", "the episode ended") if isinstance(stop, EpisodeEnded) else ("done", None)
289
- self._for_model(stop, entry)
326
+ entry.outcome = {"status": "escalated", "escalation": escalation.trace.to_dict()}
327
+ except EpisodeEnded as stop:
328
+ # The episode ended: the model hears of it with this unit's end, and the
329
+ # unit is no event of its own.
330
+ status, error = "cancelled", "the episode ended"
331
+ entry.outcome = {"status": "episode_ended", "episode_ended": stop.trace.to_dict()}
332
+ except ProgramFinished as stop:
333
+ entry.outcome = {"status": "finished", "finish": stop.summary}
290
334
  except BaseException as raised:
291
335
  status, error = "failed", f"{type(raised).__name__}: {_short(str(raised), 300)}"
336
+ entry.outcome, entry.raised = {"status": "error", "error": error}, raised
292
337
  finally:
338
+ entry.ok = self._completed(entry)
293
339
  self._end(entry, status, result=result, error=error, failure=failure)
294
340
  entry.thread = threading.Thread(target=run, name=f"entry-{entry.id}", daemon=True)
295
341
  entry.thread.start()
296
342
  return entry
297
343
 
344
+ def _completed(self, entry):
345
+ """Whether what the unit was for is the case now that it has ended: its completion
346
+ condition on the view as it is (None: it stated none; False when it cannot be
347
+ judged). How the unit ended and whether its work is done are two things."""
348
+ if entry.until is None:
349
+ return None
350
+ try:
351
+ return bool(entry.until(self.session._view(self.session.state, 0)))
352
+ except BaseException:
353
+ return False
354
+
355
+ def until(self, condition) -> None:
356
+ """The unit this code runs in is for `condition`: a function of the view that holds
357
+ when its work is done. It is judged when the unit ends, and the end says whether it
358
+ held."""
359
+ if not callable(condition):
360
+ raise TypeError("until(condition): a function of the view that holds when this program's work is done")
361
+ entry = self.current()
362
+ if entry is self.root:
363
+ raise RuntimeError("until() is called by a program: it says what that program is for")
364
+ entry.until = condition
365
+
366
+ def at_priority(self, priority) -> None:
367
+ """The unit this code runs in holds the embodiment with `priority` from now until it
368
+ ends, between its executions too (runtime/tick.py hold). A unit of higher priority
369
+ still takes it (a reflex whose place is `priority` or above); one of lower priority
370
+ waits. Its own ends stay: it is cancelled, its calls reach their time, a reflex that
371
+ ends what runs holds, the episode ends."""
372
+ entry = self.current()
373
+ if entry is self.root:
374
+ raise RuntimeError("at_priority() is called by a program: it says with what this program holds the environment")
375
+ if isinstance(priority, bool) or not isinstance(priority, (int, float)) or not priority >= 0:
376
+ raise ValueError(f"at_priority(priority): a number, 0 or more, got {priority!r}")
377
+ entry.priority = priority
378
+ spans.note("priority", unit=entry.id, priority=priority)
379
+ self.session._ticker.hold(entry)
380
+
298
381
  def claim(self, names) -> bool:
299
382
  """The caller's entry claims the channels `names` (see the module docstring): True;
300
383
  False when one is another entry's and a handler took the CHANNEL_CONFLICT event,
@@ -341,12 +424,17 @@ class Tree:
341
424
  Event(ev.CHANNEL_CONFLICT, "channels", {"channels": found, "entry": entry.id}, step))
342
425
 
343
426
  def adopt_agent(self, agent, task) -> Entry:
344
- """The entry of a sub-agent the caller started (delegate)."""
345
- return self._add(_short(" ".join(str(task).split()), 80), "agent", self.current(), (), agent=str(agent))
427
+ """The unit of a sub-agent the model's code started (delegate)."""
428
+ return self._add(_short(" ".join(str(task).split()), 80), "agent", self.root, (), agent=str(agent))
429
+
430
+ def agent_runs(self, agent) -> bool:
431
+ """Whether a unit of sub-agent `agent` has not ended."""
432
+ return any(item.kind == "agent" and item.agent == str(agent) and item.running
433
+ for item in list(self.entries.values()))
346
434
 
347
435
  def agent_ended(self, agent, report, *, cancelled=False) -> None:
348
- """A sub-agent ended (the conversation tells the kernel, runtime/execution/kernel.py): so does
349
- its entry, failed unless it finished."""
436
+ """A turn of a sub-agent ended (the conversation tells the kernel, runtime/execution/kernel.py):
437
+ so does its entry, failed unless the turn ended with an answer."""
350
438
  entry = next((item for item in list(self.entries.values()) if item.kind == "agent" and item.agent == str(agent)
351
439
  and item.running), None)
352
440
  if entry is None:
@@ -361,15 +449,20 @@ class Tree:
361
449
  self._end(entry, "failed", result=report, error=f"the sub-agent ended: {status}"
362
450
  + (f" ({report['error']})" if report.get("error") else ""))
363
451
 
364
- def _add(self, name, kind, parent, claims, agent=None) -> Entry:
452
+ def _add(self, name, kind, parent, claims, agent=None, cell=None, rule=None, priority=0) -> Entry:
365
453
  with self._changed:
366
454
  if self._closed:
367
455
  raise RuntimeError("the session has closed")
368
456
  self._count += 1
369
457
  entry = Entry(self, f"e{self._count}", name, kind, parent, claims, agent=agent)
458
+ entry.cell, entry.rule, entry.priority = cell, rule, priority
459
+ if self.new_output is not None:
460
+ entry.box.output = self.new_output(entry)
370
461
  self.entries[entry.id] = entry
371
462
  parent.children.append(entry)
372
463
  spans.record("entry_start", id=entry.id, parent=parent.id, name=entry.name, kind=kind,
464
+ **({"cell": cell} if cell is not None else {}), **({"rule": rule} if rule else {}),
465
+ **({"priority": priority} if priority else {}),
373
466
  **({"claims": entry.claims} if entry.claims else {}), **({"agent": agent} if agent else {}),
374
467
  span=spans.current())
375
468
  return entry
@@ -377,20 +470,17 @@ class Tree:
377
470
  # Ending entries, and their events.
378
471
 
379
472
  def _end(self, entry, status, result=None, error=None, failure=None) -> None:
380
- """`entry` ended: its own entries end with it, its guards and handlers go, its
381
- waiters wake, and a failure goes up as an ENTRY_FAILED event."""
382
- for child in list(entry.children):
383
- if child.running:
384
- try:
385
- child.cancel()
386
- except BaseException:
387
- pass
473
+ """`entry` ended: its waiters wake, its channels go, and the model hears of it
474
+ (on_end); the failure of a unit nobody waited for goes to the handlers first, as an
475
+ ENTRY_FAILED event. What it started (units, rules, handlers) is the model's and stays."""
388
476
  with self._changed:
389
477
  if not entry.running:
390
478
  return
391
479
  entry.status, entry.result, entry.error = status, result, error
392
480
  entry.ended = time.time()
393
- self._ended.append(entry)
481
+ if entry.outcome is None:
482
+ entry.outcome = {"status": {"done": "ok", "failed": "error"}.get(status, status),
483
+ **({"error": error} if error else {})}
394
484
  if status == "failed":
395
485
  step = (self.session.state or {}).get("step")
396
486
  detail = {"entry": entry.id, "kind": entry.kind}
@@ -402,31 +492,35 @@ class Tree:
402
492
  waited = entry._waiters > 0
403
493
  entry._done.set()
404
494
  self._changed.notify_all()
405
- reactive = getattr(self.session, "reactive", None)
406
- if reactive is not None:
407
- reactive.clear_owner(entry.id)
408
495
  tick = self.session.__dict__.get("_tick_loop")
496
+ if tick is not None:
497
+ # The tree of reflexes waits for its programs' ends (runtime/reactive/tree.py).
498
+ tick.judge()
409
499
  if tick is not None and tick.channels:
410
500
  # Its claims go, and what it held down goes up at the next period.
411
501
  tick.release(entry)
412
502
  spans.record("entry_end", id=entry.id, status=status,
413
503
  **({"error": _short(error, 300)} if error else {}),
414
504
  **({"event_kind": failure.kind} if failure is not None else {}))
415
- if entry.failure is not None and not waited:
416
- if threading.current_thread() is entry.thread:
417
- # Its thread ends after this: the parent's handlers run on it.
418
- self.deliver(entry.parent, entry.failure.trace)
419
- else:
420
- threading.Thread(target=self.deliver, args=(entry.parent, entry.failure.trace),
421
- name=f"event-{ev.ENTRY_FAILED}", daemon=True).start()
422
-
423
- def deliver(self, entry, trace) -> bool:
424
- """Offer the event of `trace` to the handlers of `entry` and up; one nobody
425
- handles reaches the model. Whether a handler resolved it."""
426
- if self.handle(entry, trace):
427
- return True
428
- self._for_model(Escalation(trace), entry)
429
- return False
505
+ if threading.current_thread() is entry.thread:
506
+ # Its thread ends after this: the handlers and the report run on it.
507
+ self._ended(entry, waited)
508
+ else:
509
+ threading.Thread(target=self._ended, args=(entry, waited), name=f"end-{entry.id}", daemon=True).start()
510
+
511
+ def _ended(self, entry, waited) -> None:
512
+ handled = waited
513
+ if entry.failure is not None and not waited and entry.cell is None and not entry.quiet:
514
+ # A program of the model reports its failure with its result; another unit's
515
+ # failure is an event for the handlers first.
516
+ handled = self.handle(self.root, entry.failure.trace)
517
+ if self.on_end is not None:
518
+ try:
519
+ with self.acting(entry):
520
+ self.on_end(entry, handled)
521
+ except BaseException as error:
522
+ print(f"harness kernel: the end of {entry.id} was not reported: {type(error).__name__}: {error}",
523
+ file=sys.stderr)
430
524
 
431
525
  def record_event(self, trace, entry=None):
432
526
  record = {"skill": trace.skill, "event": trace.event.to_dict(), "ticks": trace.ticks}
@@ -435,12 +529,13 @@ class Tree:
435
529
  # Events still pass through the same handlers. History streams to the host;
436
530
  # the next decision gets bounded feedback rather than every operation again.
437
531
  spans.note("execution_event", execution=record)
438
- counts = self.session.__dict__.setdefault("_event_counts", {})
439
- counts[trace.event.kind] = counts.get(trace.event.kind, 0) + 1
532
+ # Kept by the unit whose execution it was (the model's own box outside every unit).
533
+ box = (entry if entry is not None else self.current()).box
534
+ box.event_counts[trace.event.kind] = box.event_counts.get(trace.event.kind, 0) + 1
440
535
  if not trace.ok:
441
- self.session._events.append(record)
442
- if len(self.session._events) > 32:
443
- del self.session._events[0]
536
+ box.events.append(record)
537
+ if len(box.events) > 32:
538
+ del box.events[0]
444
539
  return record
445
540
 
446
541
  def raise_event(self, entry, trace, *, notice=False) -> None:
@@ -456,48 +551,33 @@ class Tree:
456
551
  threading.Thread(target=deliver, name=f"event-{trace.event.kind}", daemon=True).start()
457
552
 
458
553
  def handle(self, entry, trace) -> bool:
459
- """Offer `trace`'s event to the answer for its kind of `entry`, then of each entry
460
- above it (runtime/reactive/rules.py answer): the first that does not return False
461
- resolves it."""
554
+ """Offer `trace`'s event to the tree of reflexes (runtime/reactive/tree.py answer): a
555
+ node that answers its kind, and whose turn it is, starts its program as a unit, and
556
+ the event is answered."""
462
557
  layer = getattr(self.session, "reactive", None)
463
558
  if layer is None:
464
559
  return False
465
- return layer.answer([level.id for level in entry.lineage()], trace, lambda owner: self.acting(self.get(owner)),
466
- lambda owner, fault: reactive.emit(
467
- self, owner, trace.skill, reactive.fault_event(fault, trace.end_tick)))
560
+ try:
561
+ return layer.answer(trace, lambda node, program: self.spawn(
562
+ program, name=node.name, rule=node.name, priority=layer.rank(node), quiet=True))
563
+ except reactive.ReactiveFault as fault:
564
+ reflexes.emit(self, None, trace.skill, reflexes.fault_event(fault, trace.end_tick))
565
+ return False
468
566
 
469
567
  def _for_model(self, stop, entry) -> None:
470
- if control.host_thoughts:
471
- trace = stop.trace
472
- spans.note("escalation", id=uuid.uuid4().hex, entry=entry.id, skill=trace.skill,
473
- event=trace.event.to_dict())
474
- return
475
- with self._changed:
476
- self.root.pending.append(stop)
477
- self._changed.notify_all()
478
-
479
- # What the kernel does around a program.
480
-
481
- def begin_program(self) -> None:
482
- """A program starts: an event that reached the model while none ran ends it at
483
- once (it was written without knowing)."""
484
- self.check(self.root)
485
-
486
- def end_program(self) -> None:
487
- """A program ended: an event that reached the model while it ran and that it did not
488
- meet is its end."""
489
- self.check(self.root)
490
-
491
- def drain(self) -> list[dict]:
492
- """The entries the model hears of after a program: those running, and those that
493
- ended since the last drain (the root aside)."""
568
+ """An event nobody handled reaches the model: a note to the conversation that runs
569
+ this kernel (runtime/task/run.py)."""
570
+ trace = stop.trace
571
+ spans.note("escalation", id=uuid.uuid4().hex, entry=entry.id, skill=trace.skill,
572
+ event=trace.event.to_dict())
573
+
574
+ def running(self) -> list:
575
+ """The units that have not ended, oldest first (the model aside)."""
494
576
  with self._changed:
495
- ended, self._ended = self._ended, []
496
- running = [entry for entry in self.entries.values() if entry.running and entry is not self.root]
497
- return [entry.state() for entry in ended + running]
577
+ return [entry for entry in self.entries.values() if entry.running and entry is not self.root]
498
578
 
499
579
  def close(self, timeout=2.0) -> None:
500
- """The session closes: every entry is cancelled."""
580
+ """The session closes: the model ends, and every unit with it."""
501
581
  with self._changed:
502
582
  self._closed = True
503
583
  for entry in list(self.root.children):
@@ -531,8 +611,8 @@ class _Acting:
531
611
 
532
612
  # -- The closed loop every execution runs as ----------------------------------------------
533
613
 
534
- # Escalations that end the program whatever a loop does: the episode's end, a pause, a message.
535
- PASS_ON = frozenset({ev.EPISODE_ENDED, ev.USER_PAUSED, ev.USER_MESSAGE})
614
+ # Escalations that end the program whatever a loop does: the episode's end, a pause.
615
+ PASS_ON = frozenset({ev.EPISODE_ENDED, ev.USER_PAUSED})
536
616
 
537
617
 
538
618
  class Result(dict):