@lmmslab/harness 0.82.0 → 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.
package/README.md CHANGED
@@ -13,8 +13,8 @@
13
13
  </p>
14
14
 
15
15
  <p align="center">
16
- <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm version" src="https://img.shields.io/npm/v/@lmmslab/harness?style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
17
- <a href="https://pypi.org/project/the-harness/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/the-harness?style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
16
+ <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm version" src="https://img.shields.io/npm/v/@lmmslab/harness?cacheSeconds=3600&amp;style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
17
+ <a href="https://pypi.org/project/the-harness/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/the-harness?cacheSeconds=3600&amp;style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
18
18
  <a href="https://discord.gg/zhkzEznBs"><img alt="Discord community" src="https://img.shields.io/badge/discord-community-bc276e?style=flat-square&amp;logo=discord&amp;logoColor=white&amp;labelColor=112332" /></a>
19
19
  </p>
20
20
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lmmslab/harness",
3
- "version": "0.82.0",
3
+ "version": "0.83.0",
4
4
  "description": "Automatic Control for intelligence in action",
5
5
  "license": "MIT",
6
6
  "homepage": "https://harness.lmms-lab.com",
@@ -2,7 +2,7 @@
2
2
 
3
3
  # The one version: the core's. A lock records it with the versions of the packages that
4
4
  # ran and the hash of the whole lock (the agent's identity, config/agent.py).
5
- __version__ = "0.82.0"
5
+ __version__ = "0.83.0"
6
6
 
7
7
  # A checkout's packages import beside the harness (paths.py).
8
8
  from . import paths as _paths # noqa: E402,F401
@@ -11,14 +11,14 @@ time with exactly one of:
11
11
  next message starts your next turn, and you keep what you have.
12
12
 
13
13
  <!-- if: look -->
14
- When a program ends you see its output, what went wrong if anything did and the state, as
15
- text. A picture reaches you only when a program looks (look and watch below); read what
14
+ When a program ends you see its output and what went wrong if anything did, as text.
15
+ A picture reaches you only when a program looks (look and watch below); read what
16
16
  the state and the environment's calls give as text first, and look when that does not
17
17
  tell, while a program runs as much as after it. Write one program for a coherent phase
18
18
  with a clear completion condition.
19
19
  <!-- else -->
20
- When a program ends you see its output, what went wrong if anything did, the state and
21
- new pictures. Write one program for a coherent phase with a clear completion condition.
20
+ When a program ends you see its output, what went wrong if anything did and new
21
+ pictures. Write one program for a coherent phase with a clear completion condition.
22
22
  <!-- end -->
23
23
  Let it observe, act, wait for a condition, and check the result as it goes. Handle
24
24
  expected outcomes and bound any waits or retries. End the program when the phase is
@@ -40,19 +40,27 @@ is not that. Say what the task needs as things that must be true, not as a seque
40
40
  what is already true needs no step, and the order follows from what is there.
41
41
 
42
42
  The tree is designed as a whole, not grown from what went wrong last. Before you rely on
43
- it, name every kind of thing that can happen to the agent where it is going to be: to its
44
- condition, to where it stands, from what is around it, to what it is doing. Give each
45
- kind a node. A kind you do not yet know how to answer still gets its node: one that tells
46
- you. What you set out to do is not among them, however often you do it: a way of doing
47
- something that you have learned is kept as a skill you call, not as a node. A node has
48
- done its work when its situation is over: when its program ends and the situation is not
49
- over, a later node at its place has the environment, or you are told what the program
50
- did. The tree is consistent when in every situation it is settled which node has the
51
- environment: a node's place is what it costs when it does not act now, the costlier the
52
- earlier; and a node takes the environment only where you would, seeing everything as it
53
- is then. A reflex acts in your place, so its condition is your whole judgement, what it
54
- interrupts and whether this is the moment included, and what it does leaves things so
55
- that what it interrupted can go on.
43
+ it, name every kind of thing that can happen to the agent where it is going to be: to
44
+ its condition, to where it stands, from what is around it, to what it is doing. The tree
45
+ divides all of that. A node is a situation: its condition says when the agent is in it.
46
+ The nodes under it divide the situation further, wherever a narrower one needs an answer
47
+ of its own, and the last of them answers what is in the situation and in none of the
48
+ others, with what fits the whole situation or by telling you. This holds at every depth,
49
+ and how far a situation is divided follows from how much you know of it. So what you
50
+ have never met is still answered, by the narrowest situation it falls in; and when you
51
+ come to know it, you divide there, where its place among everything else is already
52
+ settled. What happens to the agent whatever it is doing belongs in the tree, also when
53
+ you met it inside one program: answered there, it is answered nowhere else. What you set
54
+ out to do is not in it, however often you do it: a way of doing something that you have
55
+ learned is kept as a skill you call, not as a node. A node has done its work when its
56
+ situation is over: when its program ends and the situation is not over, a later node at
57
+ its place has the environment, or you are told what the program did. The tree is
58
+ consistent when in every situation it is settled which node has the environment: a
59
+ node's place is what it costs when it does not act now, the costlier the earlier; and a
60
+ node takes the environment only where you would, seeing everything as it is then. A
61
+ reflex acts in your place, so its condition is your whole judgement, what it interrupts
62
+ and whether this is the moment included, and what it does leaves things so that what it
63
+ interrupted can go on.
56
64
 
57
65
  Build each thing for the situations it has to work in, and think and test in proportion
58
66
  to what a failure costs: settle in the design what is cheap to settle; test what is
@@ -71,6 +79,14 @@ or when its time is over, and you are told which. What a program starts (units,
71
79
  is yours: it outlives the program and the turn. After your answer it goes on,
72
80
  and the end of a unit or an event starts your next turn; cancel what should not go on.
73
81
 
82
+ Whatever you are asked for, you are told in the same order: what your last reply came
83
+ to; then what reached you by itself since (the end of a unit, an event, a message), the
84
+ more urgent first; last, how things stand now: the state, the units that run, what
85
+ changed in the tree of reflexes. What cannot wait (an event, what the environment tells,
86
+ a unit that ended with an error) reaches you at once: a reply you were writing then is
87
+ set aside, what it held does not run, and you are asked again. The rest is told when you
88
+ are next asked.
89
+
74
90
  Every unit ends with the same report, whoever started it: how it ended (by itself, an
75
91
  error, an event, cancelled, its time limit), whether what it was for is the case (done:
76
92
  yes or no), and what it returned. How it ended and whether it is done are two things: a
@@ -1,15 +1,6 @@
1
1
  <!-- if: robot -->
2
2
  You improve a robot-control harness between episodes. A coding agent controls a dual-arm robot by writing Python against a skill API.
3
3
  <!-- end -->
4
- <!-- if: game -->
5
- You improve a game-playing harness between episodes.
6
- <!-- if: minecraft -->
7
- A coding agent plays Minecraft Java 1.16.1 Any% speedruns on random seeds (every seed is a new world) from the pixels of its window with the keyboard and mouse, by writing Python against a skill API: closed-loop actions fed back by F3 and the HUD (get, act, craft, go_to, and for the later phases make_obsidian, build_portal_frame, barter, fight, throw_eye ...), entries that run at the same time on their own channels, and guards on the tick that read view['hud'] and view['see'].
8
- It practices the run in segments (wood and stone tools, iron, the portal, the bastion's pearls, the fortress's rods, the way back, the eyes, the portal room, the dragon), each scored by whether it finished in its time limit, its time and its deaths.
9
- <!-- else -->
10
- A coding agent plays a game from the pixels of its window with the keyboard and mouse, by writing Python against a skill API; guards on the tick read what the worker reads off the HUD and the picture.
11
- <!-- end -->
12
- <!-- end -->
13
4
  <!-- if: desktop -->
14
5
  You improve a computer-use harness between episodes. A coding agent operates a computer's apps from screenshots with the keyboard and mouse, by writing Python against a skill API.
15
6
  <!-- end -->
@@ -21,16 +12,16 @@ You read observed task results and the current library of notes and helper funct
21
12
  <!-- if: robot -->
22
13
  a short note (a general lesson, not about this layout's coordinates),
23
14
  <!-- else -->
24
- a short note (a general lesson, not about this world's or this screen's coordinates: every seed is a new one),
15
+ a short note (a general lesson, not about what holds in this one run only),
25
16
  <!-- end -->
26
17
  a memory entry (a specific situation and what worked or failed, which the agent can look up with recall(query)), a helper skill (a Python function using the API names the agent uses), or
27
18
  <!-- if: robot -->
28
19
  a reactive helper (a pure, fast predicate or controller of obs).
29
20
  <!-- else -->
30
- a reactive helper (a pure, fast guard predicate of the view, such as view['hud'] and view['see']).
21
+ a reactive helper (a pure, fast guard predicate of the view).
31
22
  <!-- end -->
32
23
  <!-- if: experience -->
33
- Do not propose tallies of how often a skill worked or where something was found (a recipe's place in the recipe book): practice counts those by itself in the library's experience, which skills read as hints.
24
+ Do not propose tallies of how often a skill worked or where something was found: practice counts those by itself in the library's experience, which skills read as hints.
34
25
  <!-- end -->
35
26
  Reply with exactly one of <note name="snake_case">...</note>, <memory name="snake_case">...</memory>, <skill name="snake_case">...</skill>, <reactive name="snake_case">...</reactive>, or <none/>.
36
27
  <!-- if: robot -->
@@ -1,7 +1,8 @@
1
1
  # The reflection request (runtime/learning/reflect.py: between episodes, the model proposes one
2
2
  # library entry), one paragraph: the section's lines are joined with spaces once the
3
- # markers are applied. Markers name the embodiment kind (robot, game, desktop), the
4
- # bench (minecraft, robodojo, ...) and the skills the run enabled.
3
+ # markers are applied. Markers name the embodiment kind (robot, desktop), the bench and
4
+ # the skills the run enabled. What belongs to one environment is not said here: its
5
+ # package says it.
5
6
  sections = [
6
7
  { file = "core.md" },
7
8
  ]
@@ -287,7 +287,7 @@ def _continued(args):
287
287
 
288
288
 
289
289
  def parser(packages: bool = True):
290
- root = argparse.ArgumentParser(prog="harness", description="Automatic Control for anything that acts.",
290
+ root = argparse.ArgumentParser(prog="harness", description="Automatic Control for intelligence in action.",
291
291
  epilog="harness with no command: the terminal chat with the agent on this computer "
292
292
  "(/help lists its commands: sessions, the session host, settings, model, "
293
293
  "packages, library)")
@@ -167,6 +167,9 @@ RUNTIME_KEYS = {
167
167
  "back with its handle",
168
168
  "longest_wait_seconds": "the longest a <wait> of the model lasts, and what a wait without a time gets "
169
169
  "(default 60)",
170
+ "tell_budget": "whether the model is told with every call what the run has left (its model calls, its "
171
+ "environment steps, its live time): never (default: the host keeps the limits and ends the "
172
+ "turn at them) or always (a benchmark with short episodes, where the model plans its end)",
170
173
  "thinking": "how long a call of the main model may think (runtime/conversation.py THINKING): model (the "
171
174
  "code's default: the model's own settings), none (reasoning off, replies of at most 2000 tokens, "
172
175
  "and the model is told to think briefly), low (reasoning effort at most low, 2000 tokens, told "
@@ -38,16 +38,27 @@ EMPTY_RETRIES = 2
38
38
  TURN_GRACE_SECONDS = 2.0
39
39
 
40
40
 
41
+ # runtime.tell_budget: whether the model is told, with every call, what the run has left
42
+ # (model calls, environment steps, live time). "never": the limits are the host's to keep
43
+ # and the model is not told them; "always": told with every call (a benchmark whose
44
+ # episodes are a few dozen calls, where the model must plan its end).
45
+ TELL_BUDGET = ("never", "always")
46
+
47
+
41
48
  # runtime.longest_wait_seconds: the longest a <wait> lasts; one that names no time lasts
42
49
  # this long, so no wait is endless.
43
50
  LONGEST_WAIT_SECONDS = 60.0
44
51
 
45
52
 
46
- # What the model is told when its wait ended: why (WAIT_ENDS), and after how long; the units
47
- # that run follow, each with how long it has run and when it last printed (messages.unit_text).
53
+ # What the model is told when its wait ended: why (WAIT_ENDS: the kind of the notice that
54
+ # ended it, runtime/decision/notices.py, or its time), and after how long.
48
55
  WAIT_ENDED = "Wait ended after {seconds:.1f} s: {why}."
49
56
  WAIT_ENDS = {"unit": "a unit you started ended", "message": "a message reached you", "event": "an event reached you",
50
- "time": "its time is over"}
57
+ "note": "the harness told you something", "time": "its time is over"}
58
+
59
+
60
+ # How the model reads an event that reached it; what the event's record holds follows.
61
+ EVENT = "Event {kind} from {source}"
51
62
 
52
63
 
53
64
  # What the model is told, with its next prompt, when its conversation goes on in a new
@@ -103,12 +114,10 @@ def _thinking(main: dict, level: str) -> dict:
103
114
  return main
104
115
 
105
116
 
106
- # Why the model is called (a model_request's reason): a pending message or unresolved event
107
- # (the method that says whether one is pending) comes before what happened last.
108
- TRIGGERS = {"user": "_pending_message", "escalation": "_unresolved",
109
- "start": None, "program_end": None, "program_running": None, "unit_end": None, "wait_end": None,
110
- "error": None,
111
- "rejected": None, "finish_refused": None, "verify": None, "empty": None, "format": None}
117
+ # Why the model is called (a model_request's reason): a message or an event it was told and
118
+ # has not answered ("user", "escalation") comes before what happened last.
119
+ REASONS = ("user", "escalation", "start", "program_end", "program_running", "unit_end", "wait_end", "error",
120
+ "rejected", "finish_refused", "verify", "empty", "format")
112
121
 
113
122
 
114
123
  # The trigger of a role's request: explicit requests share the transport of decisions.
@@ -110,12 +110,12 @@ def ended_text(result: dict) -> str:
110
110
  + f" ({result.get('seconds', 0):.1f} s)")
111
111
 
112
112
 
113
- def cell_feedback(result: dict, number: int, hz: float | None = None, embodiment: str = "robot",
114
- steps: bool = True) -> str:
113
+ def cell_feedback(result: dict, number: int) -> str:
115
114
  """What the model is told of program `number` it ran: its status, output and error, the
116
- event that ended it, the executions, the skills' turn report, the state and the steps.
117
- It names the program, since programs run side by side and the result of one can reach
118
- the model after the code of the next."""
115
+ event that ended it, the executions and the skills' turn report (the state as it is
116
+ now is told once with every call: runtime/task/run.py _ambient). It names the
117
+ program, since programs run side by side and the result of one can reach the model
118
+ after the code of the next."""
119
119
  lines = [f"Program {number} " + ended_text(result)]
120
120
  if result.get("stdout"):
121
121
  lines.append("Output:\n" + result["stdout"].rstrip())
@@ -136,11 +136,6 @@ def cell_feedback(result: dict, number: int, hz: float | None = None, embodiment
136
136
  lines.append("Execution totals (details in trace): " + json.dumps(result["event_counts"]))
137
137
  if (result.get("report") or {}).get("text"):
138
138
  lines.append(result["report"]["text"])
139
- if result.get("state"):
140
- lines.append(f"{EMBODIMENT_TEXT[embodiment]['state_label']}: "
141
- + state_text(result["state"], embodiment, steps))
142
- if steps and result["state"].get("step") is not None:
143
- lines.append(steps_text(result["state"], hz))
144
139
  for name, part in (result.get("environments") or {}).items():
145
140
  # An environment attached to the conversation (runtime/execution/attached.py).
146
141
  if part.get("events"):
@@ -442,19 +442,24 @@ def scripted_models(script) -> dict:
442
442
  "verifier": ScriptedChat(script.get("verifier") or ["YES (scripted verifier)"] * 100)}
443
443
 
444
444
 
445
- # The end of a request that says the model's program still runs and nothing else happened.
445
+ # A request that says the model's program still runs and nothing else happened.
446
446
  _STILL_RUNNING = re.compile(r"Program \d+ is still running")
447
447
  _WAIT_OVER = re.compile(r"^Wait ended after [\d.]+ s: its time is over")
448
448
 
449
449
 
450
450
  def still_running(messages: list[dict]) -> bool:
451
- """Whether the final content part says a program still runs and nothing reached the
452
- model: it was just started, or a wait's time is over while units run (a wait whose time
453
- is over with nothing running is the script's own to answer)."""
451
+ """Whether the last thing the request tells, before how things stand now (its `ambient`
452
+ part), is that a program still runs and nothing reached the model: it was just started,
453
+ or a wait's time is over while units run (a wait whose time is over with nothing
454
+ running is the script's own to answer)."""
454
455
  content = messages[-1].get("content") if messages else None
455
- last = content if isinstance(content, str) else (content[-1].get("text", "") if content else "")
456
- last = last or ""
457
- return bool(_STILL_RUNNING.match(last) or (_WAIT_OVER.match(last) and "\nUnits running:" in last))
456
+ if isinstance(content, str) or not content:
457
+ return bool(_STILL_RUNNING.match(content or ""))
458
+ told = [part for part in content if not part.get("ambient")]
459
+ ambient = "\n".join(part.get("text", "") for part in content if part.get("ambient"))
460
+ last = (told[-1].get("text") or "") if told else ""
461
+ return bool(_STILL_RUNNING.match(last)
462
+ or (_WAIT_OVER.match(last) and re.search(r"^Units running:", ambient, re.M)))
458
463
 
459
464
 
460
465
  class ScriptedChat:
@@ -0,0 +1,66 @@
1
+ """What reaches the model: one queue of notices.
2
+
3
+ Everything that reaches the model by itself is a notice in one queue: a message (of the
4
+ user, of the agent that started this one, of the environment), an event, the end of a
5
+ unit, a note of the host. A notice has a priority, given by what puts it there:
6
+
7
+ now the model's call in flight is set aside and made again with the notice; a
8
+ reply that did not know of it does nothing
9
+ next the call in flight goes on; the notice is told with the model's next call
10
+ later told with the first call made after a wait of the model, or with the call
11
+ that begins its next turn
12
+
13
+ Every notice ends a wait of the model and, between turns, begins one; but one that does
14
+ not wake (the end of a unit that was cancelled) is only told along with the next call.
15
+ Those told with one call come the more urgent first, each priority in order of arrival.
16
+ What a reply of the model itself comes to (its program's handle, the end of its wait, a
17
+ format error) is not a notice: it is the first thing the next call is told
18
+ (runtime/task/run.py _deliver).
19
+ """
20
+
21
+ from dataclasses import dataclass
22
+
23
+ NOW, NEXT, LATER = "now", "next", "later"
24
+ PRIORITIES = (NOW, NEXT, LATER)
25
+
26
+
27
+ @dataclass
28
+ class Notice:
29
+ """`kind`: "message", "event", "unit" or "note"; `data`: what its kind tells (the
30
+ message's sender, text and parts; the event's record; the unit's result; the note's
31
+ text)."""
32
+ kind: str
33
+ priority: str
34
+ data: object
35
+ wakes: bool = True
36
+
37
+
38
+ class Notices:
39
+ """The queue. Not locked: whoever owns it holds its lock."""
40
+
41
+ def __init__(self):
42
+ self._items = []
43
+
44
+ def put(self, notice: Notice) -> None:
45
+ if notice.priority not in PRIORITIES:
46
+ raise ValueError(f"a notice's priority is one of {PRIORITIES}, got {notice.priority!r}")
47
+ self._items.append(notice)
48
+
49
+ def _found(self, upto, kinds, waking):
50
+ level = PRIORITIES.index(upto)
51
+ return [notice for notice in self._items
52
+ if PRIORITIES.index(notice.priority) <= level and (kinds is None or notice.kind in kinds)
53
+ and (not waking or notice.wakes)]
54
+
55
+ def pending(self, upto: str = LATER, kinds=None, waking: bool = False) -> list:
56
+ """The notices of priority `upto` or more urgent (of `kinds`; `waking`: those that
57
+ wake), in the order they are told."""
58
+ found = self._found(upto, kinds, waking)
59
+ return sorted(found, key=lambda notice: PRIORITIES.index(notice.priority))
60
+
61
+ def take(self, upto: str = LATER, kinds=None) -> list:
62
+ """Remove and return them."""
63
+ found = self.pending(upto, kinds)
64
+ taken = {id(notice) for notice in found}
65
+ self._items = [notice for notice in self._items if id(notice) not in taken]
66
+ return found
@@ -48,6 +48,8 @@ from harness.runtime.tick import Preempted, Tick, delay_ticks, driving
48
48
 
49
49
  # The session of each embodiment kind, as "module:Class" (embodiments.KINDS).
50
50
  SESSIONS = {name: kind.session for name, kind in KINDS.items()}
51
+ # The seconds between two reports of the state to the host (the `state` note).
52
+ STATE_NOTE_SECONDS = 1.0
51
53
 
52
54
 
53
55
  class EpisodeCore:
@@ -170,6 +172,12 @@ class EpisodeCore:
170
172
  @state.setter
171
173
  def state(self, value):
172
174
  self.__dict__["_state"] = value
175
+ # The host keeps the state as it was last reported (the `state` note, at most every
176
+ # STATE_NOTE_SECONDS): what the model is told with every call (runtime/task/run.py _ambient).
177
+ now = time.monotonic()
178
+ if value and now - self.__dict__.get("_state_noted", 0.0) >= STATE_NOTE_SECONDS:
179
+ self.__dict__["_state_noted"] = now
180
+ spans.note("state", state=value)
173
181
  self._facts_changed()
174
182
 
175
183
  def _facts_changed(self):
@@ -239,18 +239,21 @@ WAITS_FOR = {"fixture": "an independent fixture", "own_test": "the host to run i
239
239
  "off": "nothing: the host admits no code here"}
240
240
 
241
241
 
242
- def report(rows: list[dict], seconds_left: float, situations: str | None = None, admission: str = "fixture") -> str:
242
+ def report(rows: list[dict], seconds_left: float | None, situations: str | None = None,
243
+ admission: str = "fixture") -> str:
243
244
  """What an active run has learned so far (progress()): what the library holds, what is
244
245
  pending and what for, and the situations entry when there is one. Facts only: what to do
245
- next is the model's to decide. The lines the model reads after each program of an active
246
- run; `admission` is how the host admits code here (learner.admission)."""
247
- now = progress(rows, seconds_left, 0.0, situations)
246
+ next is the model's to decide. The lines the model reads with each call of an active
247
+ run; `admission` is how the host admits code here (learner.admission). `seconds_left`
248
+ None: the time the run has left is not said (runtime.tell_budget)."""
249
+ now = progress(rows, seconds_left or 0.0, 0.0, situations)
250
+ left = "" if seconds_left is None else f"; {now['seconds_left'] / 60:.0f} min of live time left"
248
251
  tested = now["tested"]
249
252
 
250
253
  def names(found):
251
254
  return ", ".join(found) or "none"
252
255
 
253
- lines = [f"Learned so far ({now['entries']} entries; {now['seconds_left'] / 60:.0f} min of live time left):",
256
+ lines = [f"Learned so far ({now['entries']} entries{left}):",
254
257
  " skills with a passing test: " + (", ".join(
255
258
  f"{row['name']}" + (" [own test]" if row.get("admitted_by") == "own_test" else "")
256
259
  + (f" ({row['uses']} uses, {row['success_rate']:.0%} ok)"
@@ -3,8 +3,11 @@
3
3
  A conversation starts with one model. Every program the model writes runs as a unit of its
4
4
  own in the kernel (runtime/execution/kernel.py): the model's call comes back at once, with
5
5
  the program's result when it was over within a short grace, else with its handle, and the
6
- result reaches the model when the unit ends. A message, an unhandled event and a unit's
7
- end are events to the model; a reply made before one of them is set aside.
6
+ result reaches the model when the unit ends. What reaches the model by itself (a message,
7
+ an event, a unit's end, a note of the host) is a notice in one queue with a priority
8
+ (runtime/decision/notices.py): `now` sets a reply made before it aside, `next` is told with
9
+ the next call, `later` after the model's next wait. One place tells the model with each
10
+ call (_deliver): what its last reply came to, the notices, and how things stand now.
8
11
 
9
12
  A turn is the model's work from what started it (the instruction, a message, a unit's end,
10
13
  an event) to its answer: a reply that is text, with no program and no wait (<finish> and a
@@ -34,6 +37,7 @@ import uuid
34
37
 
35
38
  from harness.runtime.decision import loop as decisions
36
39
  from harness.runtime.decision.messages import _inbox_parts, content_parts
40
+ from harness.runtime.decision.notices import LATER, NEXT, NOW, Notice, Notices
37
41
  from harness.runtime.execution.results import _taken_over, _cell_usage, _wrap_up
38
42
  from harness.runtime.safety.approval import CONFIRMATION_POLICIES
39
43
  from harness.runtime.status import Closed, Interrupted
@@ -52,8 +56,8 @@ from harness.runtime.task import context as memory_view
52
56
  from harness.runtime.task.context import WorkingMemory
53
57
  from harness.runtime.learning.usage import fold_uses
54
58
  from harness.runtime.decision.messages import (EMBODIMENT_TEXT, attachment_parts, cell_feedback, image_parts,
55
- prune_images, prune_views, state_text, text_only, unit_feedback,
56
- unit_text, view_parts)
59
+ prune_images, prune_views, state_text, steps_text, text_only,
60
+ unit_feedback, unit_text, view_parts)
57
61
  from harness.runtime.events import EVENTS
58
62
  from harness.runtime.status import ERROR, FINISHED, IDLE, PAUSED, RUNNING, STATUSES, WAITING_FOR_CONFIRMATION
59
63
  from harness.runtime.learning.active import sandbox_of
@@ -145,6 +149,11 @@ class TaskRun:
145
149
  grace = config.runtime.get("turn_grace_seconds", decisions.TURN_GRACE_SECONDS)
146
150
  if isinstance(grace, bool) or not isinstance(grace, (int, float)) or grace < 0:
147
151
  raise ValueError(f"runtime.turn_grace_seconds must be a number of seconds >= 0, got {grace!r}")
152
+ told = config.runtime.get("tell_budget", "never")
153
+ if told not in decisions.TELL_BUDGET:
154
+ raise ValueError(f"runtime.tell_budget must be one of {decisions.TELL_BUDGET}, got {told!r}")
155
+ # Whether the model is told what the run has left (its calls, its steps, its time).
156
+ self._budget_told = told == "always"
148
157
  longest = config.runtime.get("longest_wait_seconds", decisions.LONGEST_WAIT_SECONDS)
149
158
  if isinstance(longest, bool) or not isinstance(longest, (int, float)) or longest <= 0:
150
159
  raise ValueError(f"runtime.longest_wait_seconds must be a number of seconds > 0, got {longest!r}")
@@ -188,7 +197,18 @@ class TaskRun:
188
197
  self.episode = None
189
198
  self.summary = None
190
199
  self._condition = threading.Condition()
191
- self._inbox = []
200
+ # What reaches the model by itself: one queue (runtime/decision/notices.py). With it:
201
+ # what the model's last output came to (told first with its next call), the
202
+ # priority down to which that call is told the queue, the kinds of notices told
203
+ # that no reply has answered yet with the events among them, how many notices
204
+ # set a call aside, and the state as the kernel last reported it.
205
+ self._notices = Notices()
206
+ self._outcome = []
207
+ self._upto = LATER
208
+ self._unanswered = set()
209
+ self._told_events = []
210
+ self._urgent = 0
211
+ self._state_now = None
192
212
  self._pause = False
193
213
  self._closing = False
194
214
  # The user asked to end the turn that runs (cancel()).
@@ -203,12 +223,10 @@ class TaskRun:
203
223
  self._program_span = None
204
224
  # The model's units that run ({unit id: {"name", "kind", "cell", "started"}}), its
205
225
  # programs whose result has not come ({the kernel's cell: {"number", "code", "action",
206
- # "span", "unit"}}),
207
- # the results of the units that ended and the model has not been told, and how
208
- # long a program may hold the model's turn before the turn comes back with its handle.
226
+ # "span", "unit"}}), and how long a program may hold the model's turn before the
227
+ # turn comes back with its handle.
209
228
  self._units = {}
210
229
  self._programs = {}
211
- self._unit_news = []
212
230
  self._grace = float(grace)
213
231
  # The longest a <wait> of the model lasts.
214
232
  self._longest_wait = float(longest)
@@ -218,10 +236,8 @@ class TaskRun:
218
236
  self._post_from = None
219
237
  self._request = None
220
238
  self._revision = 0
221
- self._pending_events = {}
222
239
  self._inbound = None # the listener its worker tells through (runtime/task/inbound.py)
223
240
  self._seen_events = set()
224
- self._reported_events = set()
225
241
  self._thoughts = ThoughtQueue(self._condition, on_exit=self._came_back, trace=self.trace)
226
242
  self._cancelled_origins = set()
227
243
  self._logged = 0
@@ -292,8 +308,9 @@ class TaskRun:
292
308
 
293
309
  def send_message(self, text: str, sender: str = "user", files=()) -> None:
294
310
  """A message from the user (or, `sender` "parent", from the agent that started this
295
- one): recorded now, sent with the model's next call. `files`: paths the user attached
296
- (read now: messages.attachment_parts)."""
311
+ one): recorded now, told with the model's next call (a notice of priority `next`:
312
+ the call in flight goes on; cancel() is what ends a turn). `files`: paths the user
313
+ attached (read now: messages.attachment_parts)."""
297
314
  text, files = str(text).strip(), [str(path) for path in files or ()]
298
315
  if not text and not files:
299
316
  return
@@ -301,7 +318,6 @@ class TaskRun:
301
318
  with self._condition:
302
319
  if self.status in (FINISHED, ERROR):
303
320
  raise RuntimeError("The episode has ended")
304
- self._inbox.append((sender, text, parts))
305
321
  said = " ".join([text] + [f"@{path}" for path in files]).strip()
306
322
  self._said.append(said if sender == "user" else f"(from the agent that started you) {said}")
307
323
  self.trace.emit("user_message", text=text, **({"files": files} if files else {}),
@@ -315,8 +331,10 @@ class TaskRun:
315
331
  self._worker_approvals.pop(request["id"])
316
332
  self._physical = None
317
333
  self._answer_physical(request, False, "once", "superseded by a user message")
318
- self._preempt("user message")
319
- self._condition.notify_all()
334
+ # (The roles' calls that judged without it are stale.)
335
+ self._thoughts.cancel_where(
336
+ lambda item: item.role in ("verifier", "observer", "vlm", "pointer", "reflection"), "user message")
337
+ self._put("message", NEXT, (sender, text, parts))
320
338
 
321
339
  def pause(self) -> None:
322
340
  """Pause: every unit of the model stops at its next execution step or wait, and
@@ -701,6 +719,10 @@ class TaskRun:
701
719
  # How the tree of reflexes stands (runtime/reactive/tree.py tell): told with every turn.
702
720
  with self._condition:
703
721
  self._reflex_nodes = dict(record.get("nodes") or {})
722
+ elif note == "state":
723
+ # The state as the kernel last had it (runtime/execution/session.py): told with every call.
724
+ with self._condition:
725
+ self._state_now = record.get("state")
704
726
  elif note == "preempted":
705
727
  self._taken(record)
706
728
  elif note == "held_back":
@@ -1074,8 +1096,8 @@ class TaskRun:
1074
1096
  def tell(self, content, source: str | None = None) -> None:
1075
1097
  """The environment tells the model something that happened by itself: a message, in
1076
1098
  the form conversations give content (a string, or a list of text and image parts:
1077
- decision/messages.py content_parts). It reaches the model at once as a message does:
1078
- a wait ends, a call in flight is set aside and asked again; the model reads it as
1099
+ decision/messages.py content_parts). It reaches the model at once (a notice of
1100
+ priority `now`): a wait ends, a call in flight is set aside and asked again; the model reads it as
1079
1101
  "Message from the environment". Called by whoever knows of it: the run's worker
1080
1102
  through its listener (runtime/task/inbound.py), or the code that owns this run."""
1081
1103
  parts = content_parts(content)
@@ -1086,38 +1108,54 @@ class TaskRun:
1086
1108
  with self._condition:
1087
1109
  if self.status in (FINISHED, ERROR):
1088
1110
  raise RuntimeError("The episode has ended")
1089
- self._inbox.append((sender, text, parts))
1090
1111
  self.trace.emit("user_message", text=text, sender=sender,
1091
1112
  **({"images": sum(part["type"] == "input_image" for part in parts)}
1092
1113
  if any(part["type"] == "input_image" for part in parts) else {}))
1114
+ self._put("message", NOW, (sender, text, parts), reason="environment message")
1115
+
1116
+ def _put(self, kind, priority, data, *, wakes=True, reason=None) -> None:
1117
+ """Put a notice into the queue (runtime/decision/notices.py; the caller holds the
1118
+ condition). One of priority `now` sets the model's call in flight aside."""
1119
+ self._notices.put(Notice(kind, priority, data, wakes))
1120
+ if priority == NOW:
1093
1121
  self._revision += 1
1094
- self._preempt("environment message")
1095
- self._condition.notify_all()
1122
+ self._urgent += 1
1123
+ self._preempt(reason or kind)
1124
+ self._condition.notify_all()
1096
1125
 
1097
- def _escalation(self, record):
1126
+ def _note(self, text, priority=NEXT) -> None:
1127
+ """A note of the host for the model."""
1128
+ with self._condition:
1129
+ self._put("note", priority, str(text))
1130
+
1131
+ def _message_waits(self) -> bool:
1132
+ """Whether a message waits to be told (the caller holds the condition)."""
1133
+ return bool(self._notices.pending(kinds=("message",)))
1134
+
1135
+ def _escalation(self, record, priority=NOW):
1136
+ """An event for the model: a notice, at once unless its source says otherwise."""
1098
1137
  with self._condition:
1099
1138
  identifier = record["id"]
1100
1139
  if identifier in self._seen_events:
1101
1140
  return
1102
1141
  self._seen_events.add(identifier)
1103
- self._pending_events[identifier] = record
1104
1142
  self.trace.emit("escalation", **{key: value for key, value in record.items() if key != "event"},
1105
1143
  reported=record["event"])
1106
- self._revision += 1
1107
- self._preempt("unhandled escalation")
1108
- self._condition.notify_all()
1144
+ self._put("event", priority, record, reason="unhandled escalation")
1109
1145
 
1110
1146
  def _held_back(self, record: dict) -> None:
1111
1147
  """A reflex's condition came to hold while a program of higher priority had the
1112
1148
  environment (at_priority; the kernel's `held_back` note, once per reflex and unit):
1113
1149
  the reflex did not act and is judged again when that unit has ended. An event to the
1114
- model, told at once as a preemption is, so that it may let the reflex act by
1150
+ model of priority `later`: the program said itself that it stands above the reflex,
1151
+ so nothing the model thinks is out of date; it may still let the reflex act by
1115
1152
  cancelling the unit."""
1116
1153
  record.pop("time", None)
1117
1154
  self.trace.emit("held_back", **record)
1118
1155
  self._escalation({"id": uuid.uuid4().hex, "entry": record.get("by"), "event": {
1119
1156
  "kind": "HELD_BACK", "source": record.get("rule"),
1120
- "detail": {key: record[key] for key in ("rule", "priority", "by", "by_name") if record.get(key) is not None}}})
1157
+ "detail": {key: record[key] for key in ("rule", "priority", "by", "by_name") if record.get(key) is not None}}},
1158
+ LATER)
1121
1159
 
1122
1160
  def _taken(self, record: dict) -> None:
1123
1161
  """A unit of higher priority (a rule's program) took the environment from an
@@ -1144,10 +1182,7 @@ class TaskRun:
1144
1182
  thought = self._request
1145
1183
  if thought is not None and thought.outcome is None:
1146
1184
  self._settle(thought, "discarded", reason)
1147
- if reason == "user message":
1148
- self._thoughts.cancel_where(lambda item: item.role in ("verifier", "observer", "vlm", "pointer", "reflection"),
1149
- reason)
1150
- elif reason == "unhandled escalation":
1185
+ if reason == "unhandled escalation":
1151
1186
  self._thoughts.cancel_where(lambda item: item.role == "observer", reason)
1152
1187
 
1153
1188
  def _busy(self) -> bool:
@@ -1229,7 +1264,8 @@ class TaskRun:
1229
1264
  if not active.is_active(self.config.runtime):
1230
1265
  return ""
1231
1266
  level = self._admission()
1232
- report = active.report(self._learning_rows(), self.seconds_left(), self._situations(), level)
1267
+ report = active.report(self._learning_rows(), self.seconds_left() if self._budget_told else None,
1268
+ self._situations(), level)
1233
1269
  if self._fixture_descriptions:
1234
1270
  report += "\n" + "\n".join(self._fixture_descriptions)
1235
1271
  if level == "off":
@@ -1259,7 +1295,7 @@ class TaskRun:
1259
1295
  self._fixture_status = "off"
1260
1296
  return
1261
1297
  with self._condition:
1262
- if self._closing or self._pause or self._busy() or (self._inbox and not replay):
1298
+ if self._closing or self._pause or self._busy() or (self._message_waits() and not replay):
1263
1299
  return
1264
1300
  generation = self._activation_interrupt, self._revision
1265
1301
 
@@ -1444,7 +1480,7 @@ class TaskRun:
1444
1480
  active = (self.config.runtime.get("library") or {}).get("trigger") == "active"
1445
1481
  if "admitted" in observed:
1446
1482
  if not active:
1447
- self._tell(f"The host ran the test of your proposal {key} and it passed"
1483
+ self._note(f"The host ran the test of your proposal {key} and it passed"
1448
1484
  + (": it is active from your next program." if outcome.get("status") == "activated"
1449
1485
  else "; it waits for validation before it is loaded."))
1450
1486
  return
@@ -1457,7 +1493,7 @@ class TaskRun:
1457
1493
  self.trace.emit("library", action="trial_pending", key=key, revision=expected, reason=str(error))
1458
1494
  self._fixture_feedback[key] = f"Its own test failed when the host ran it: {receipt['error'][-300:]}"
1459
1495
  if not active:
1460
- self._tell(f"The host ran the test of your proposal {key} and it failed: {receipt['error'][-300:]}\n"
1496
+ self._note(f"The host ran the test of your proposal {key} and it failed: {receipt['error'][-300:]}\n"
1461
1497
  "It stays out of your library; rewrite it and propose it again if you still need it.")
1462
1498
  return
1463
1499
  # No verdict: the revision could not be staged, or the boundary was taken (a pause, a
@@ -1515,7 +1551,7 @@ class TaskRun:
1515
1551
  if not selected:
1516
1552
  return {"status": "cancelled"}
1517
1553
  def can_switch():
1518
- return startup or (not (self._busy() or self._inbox)
1554
+ return startup or (not (self._busy() or self._message_waits())
1519
1555
  and (publish is not None or all(
1520
1556
  self._activation_queue.get(item.key, (None,))[0] == item for item, _ in selected)))
1521
1557
 
@@ -1795,11 +1831,6 @@ class TaskRun:
1795
1831
  raise Interrupted()
1796
1832
  self._set_status(RUNNING)
1797
1833
 
1798
- def _take_inbox(self) -> list[str]:
1799
- with self._condition:
1800
- pending, self._inbox = self._inbox, []
1801
- return pending
1802
-
1803
1834
  def _checkpoint(self) -> None:
1804
1835
  """Between steps: stop when closing, wait while paused."""
1805
1836
  with self._condition:
@@ -1809,7 +1840,7 @@ class TaskRun:
1809
1840
  if interrupted:
1810
1841
  raise Interrupted()
1811
1842
  if paused:
1812
- self._wait(PAUSED, lambda: not self._pause or bool(self._inbox))
1843
+ self._wait(PAUSED, lambda: not self._pause or self._message_waits())
1813
1844
  with self._condition:
1814
1845
  self._pause = False
1815
1846
  kernel = self.kernel
@@ -1831,12 +1862,9 @@ class TaskRun:
1831
1862
  pass
1832
1863
 
1833
1864
  def _woken(self) -> bool:
1834
- """Whether something reached the model that starts a turn: a message, the end of a
1835
- unit (one that was cancelled is told with the next turn, it starts none), an event
1836
- it has not been told."""
1837
- return (bool(self._inbox) or self._run_end is not None
1838
- or any(item["status"] != "cancelled" for item in self._unit_news)
1839
- or any(identifier not in self._reported_events for identifier in self._pending_events))
1865
+ """Whether something reached the model that starts a turn: a notice that wakes (the
1866
+ end of a unit that was cancelled is told with the next turn, it starts none)."""
1867
+ return bool(self._notices.pending(waking=True)) or self._run_end is not None
1840
1868
 
1841
1869
  def _idle(self, reason: str) -> None:
1842
1870
  """Between turns: the conversation waits, IDLE with the reason its last turn ended
@@ -1859,22 +1887,15 @@ class TaskRun:
1859
1887
  finally:
1860
1888
  self.waiting_since = None
1861
1889
 
1862
- def _add_user_messages(self) -> None:
1863
- """Put the user's messages into the next request: into the user message that
1864
- ends the history, or as a new one after a reply."""
1865
- pending = self._take_inbox()
1866
- if not pending:
1867
- return
1868
- parts = _inbox_parts(pending)
1869
- if self.messages[-1]["role"] == "user":
1870
- self._extend_request(parts)
1871
- else:
1872
- self._tell(parts)
1873
-
1874
1890
  def _tell(self, content) -> None:
1875
1891
  """Add a user message to the history."""
1876
1892
  self.messages.append({"role": "user", "content": content})
1877
1893
 
1894
+ def _came_to(self, content) -> None:
1895
+ """What the model's last output came to (its program's handle, the end of its wait,
1896
+ why nothing ran): the first thing its next call is told (_deliver)."""
1897
+ self._outcome += content_parts(content)
1898
+
1878
1899
  def _say(self, parts) -> None:
1879
1900
  """Tell the model `parts` with its next call: in the user message that ends the
1880
1901
  history, or as a new one after a reply."""
@@ -2291,8 +2312,10 @@ class TaskRun:
2291
2312
  if reason in decisions.TURN_STOPS:
2292
2313
  # What reached the model in this turn and met no call of it is in its
2293
2314
  # history: it starts no turn by itself, the user's next message does.
2294
- self._include_escalations()
2295
- self._add_user_messages()
2315
+ parts = [part for notice in self._notices.take(kinds=("message", "event", "note"))
2316
+ for part in self._notice_parts(notice)]
2317
+ if parts:
2318
+ self._say(parts)
2296
2319
  summary["status"] = decisions.TURN_ENDS[reason]
2297
2320
  if reason != "answer":
2298
2321
  self.kernel.cancel()
@@ -2358,8 +2381,10 @@ class TaskRun:
2358
2381
  malformed_from=None, nudged=0, empties=0,
2359
2382
  post_calls=None if post_calls is None else int(post_calls))
2360
2383
  # What the first call of the turn is made for: the instruction, else what started
2361
- # the turn (a message or an event comes first: decisions.TRIGGERS).
2384
+ # the turn (a message or an event it was told comes first: _think).
2362
2385
  self.reason = "start" if self._turns == 1 else "unit_end"
2386
+ with self._condition:
2387
+ self._upto = LATER
2363
2388
  while True:
2364
2389
  self._checkpoint()
2365
2390
  self._load_due_skills()
@@ -2370,7 +2395,7 @@ class TaskRun:
2370
2395
  self._checkpoint()
2371
2396
  if ended := self._ended_by_unit(loop):
2372
2397
  return ended
2373
- self._tell_news(loop)
2398
+ self._deliver(loop)
2374
2399
  if ended := self._ended_by_unit(loop):
2375
2400
  return ended
2376
2401
  self._compact_if_due(loop)
@@ -2378,12 +2403,15 @@ class TaskRun:
2378
2403
  if self._iterations >= config.max_model_calls:
2379
2404
  return "budget"
2380
2405
  policy = (self._post_from is not None and loop.post_calls is not None
2381
- and summary["model_calls"] - self._post_from >= loop.post_calls and not self._inbox)
2406
+ and summary["model_calls"] - self._post_from >= loop.post_calls and not self._message_waits())
2382
2407
  if self.seconds_left() <= 0:
2383
2408
  return "wall_time"
2384
2409
  if not self._within_budget():
2385
2410
  return "cost"
2386
2411
  if not policy:
2412
+ if self._notices.pending(self._upto):
2413
+ continue # (It came meanwhile: told first.)
2414
+ asked = self._urgent
2387
2415
  current = self._think()
2388
2416
  self._condition.wait_for(lambda: current.back(0) or self._closing or self._interrupt)
2389
2417
  if self._closing:
@@ -2403,8 +2431,9 @@ class TaskRun:
2403
2431
  or (sum(row["chars"] for row in context_summary(current.messages, current.system))
2404
2432
  + len(reply.text)) // 4)
2405
2433
  self._settle(current, "used")
2406
- self._pending_events.clear()
2407
- loop.revision = current.revision
2434
+ self._unanswered.clear()
2435
+ self._told_events = []
2436
+ loop.revision, loop.urgent = current.revision, asked
2408
2437
  loop.call, loop.thought = current.call, current.id
2409
2438
  if policy:
2410
2439
  return self._policy_to_end()
@@ -2421,7 +2450,7 @@ class TaskRun:
2421
2450
  return None
2422
2451
  if end == "episode_ended":
2423
2452
  return "episode_ended"
2424
- if self._inbox or self._pending_events:
2453
+ if self._unanswered or self._notices.pending(kinds=("message", "event")):
2425
2454
  return None
2426
2455
  return self._out_answer(None, SimpleNamespace(body=end[1], source="program"), loop)
2427
2456
 
@@ -2480,8 +2509,9 @@ class TaskRun:
2480
2509
  self.reason = "empty"
2481
2510
 
2482
2511
  def _current_output(self, loop):
2483
- """Whether nothing reached the model since the call whose reply is being done."""
2484
- return not self._inbox and not self._pending_events and loop.revision == self._revision
2512
+ """Whether the reply being done knew of everything that set a call aside: no notice
2513
+ of priority `now` came since its call was made."""
2514
+ return loop.urgent == self._urgent
2485
2515
 
2486
2516
  def _out_invalid(self, reply, parsed, loop):
2487
2517
  """A reply nothing came of: told why, and asked again."""
@@ -2497,7 +2527,7 @@ class TaskRun:
2497
2527
  blocks = "<action> or <wait>" if loop.direct else "<python>, <verify> or <wait>"
2498
2528
  text = (f"Format error: {parsed}. Nothing ran. Reply with the {blocks} block itself, starting with its "
2499
2529
  "opening tag, or with your answer in plain text.")
2500
- self._tell(text)
2530
+ self._came_to(text)
2501
2531
  self.trace.emit("protocol_error", message=str(parsed), truncated=reply.usage.get("finish_reason") == "length",
2502
2532
  **({"announced": True} if text.startswith("Nothing ran") else {}))
2503
2533
  self.reason = "format"
@@ -2519,8 +2549,8 @@ class TaskRun:
2519
2549
  before = getattr(self, "_library_version", None)
2520
2550
  self._trial_at_boundary()
2521
2551
  if getattr(self, "_library_version", None) != before:
2522
- self._tell("The host activated your proposal. Use the new revision in a brief practice program, "
2523
- "check what it does, then answer with the result.")
2552
+ self._came_to("The host activated your proposal. Use the new revision in a brief practice program, "
2553
+ "check what it does, then answer with the result.")
2524
2554
  self.reason = "program_end"
2525
2555
  return None
2526
2556
  self.result = text.strip()
@@ -2533,17 +2563,18 @@ class TaskRun:
2533
2563
  return "answer"
2534
2564
 
2535
2565
  def _out_wait(self, reply, parsed, loop):
2536
- """The model waits by choice: no call is made until the first of a unit it started
2537
- ended, a message or an event reached it, or its time (the block's seconds, at most
2538
- the run's longest wait, which a wait without a time gets). It is told which."""
2566
+ """The model waits by choice: no call is made until a notice reaches it (the end of
2567
+ a unit it started, a message, an event, a note), or its time is over (the block's
2568
+ seconds, at most the run's longest wait, which a wait without a time gets). It is
2569
+ told which."""
2539
2570
  asked = wait_seconds(parsed.body)
2540
2571
  limit = max(0.0, min(asked if asked is not None else self._longest_wait, self._longest_wait,
2541
2572
  self.seconds_left()))
2542
2573
  began = time.monotonic()
2543
2574
 
2544
2575
  def reached():
2545
- return ("unit" if self._unit_news or self._run_end is not None else "message" if self._inbox
2546
- else "event" if self._pending_events else None)
2576
+ waking = self._notices.pending(waking=True)
2577
+ return "unit" if self._run_end is not None else waking[0].kind if waking else None
2547
2578
 
2548
2579
  with self._condition:
2549
2580
  self.trace.emit("wait", seconds=round(limit, 3), **({"asked": asked} if asked is not None else {}))
@@ -2552,12 +2583,10 @@ class TaskRun:
2552
2583
  why = reached() or ("time" if time.monotonic() - began >= limit else "pause")
2553
2584
  waited = time.monotonic() - began
2554
2585
  self.trace.emit("wait_end", why=why, seconds=round(waited, 3))
2555
- running = [unit_text(identifier, unit) for identifier, unit in self._units.items()]
2556
- # (Last in the message when nothing else is told: the bare end of a wait.)
2557
- self._say([{"type": "input_text", "text": decisions.WAIT_ENDED.format(
2558
- seconds=waited, why=decisions.WAIT_ENDS.get(why, "the user paused"))
2559
- + ("\nUnits running: " + latest(running) if running else "")
2560
- + "\n" + self._tree_told()}])
2586
+ self._came_to(decisions.WAIT_ENDED.format(seconds=waited,
2587
+ why=decisions.WAIT_ENDS.get(why, "the user paused")))
2588
+ # (After a wait the queue is told whole.)
2589
+ self._upto = LATER
2561
2590
  self.reason = "wait_end"
2562
2591
 
2563
2592
  def _out_verify(self, reply, parsed, loop):
@@ -2569,12 +2598,13 @@ class TaskRun:
2569
2598
  answer, view = self._verify(parsed.body)
2570
2599
  except ThoughtCancelled:
2571
2600
  with self._condition:
2572
- if self._inbox or self._pending_events or self._closing:
2601
+ if self._notices.pending() or self._closing:
2573
2602
  return None
2574
2603
  raise
2575
- state = state_text(view["state"], self.config.embodiment, self._steps_shown())
2576
- self._tell([{"type": "input_text", "text": f"Verifier: {answer}\n{loop.told['state_label']}: {state}"},
2577
- *(image_parts(view["images"], self.cameras) if self._standing else [])])
2604
+ with self._condition:
2605
+ self._state_now = view["state"]
2606
+ self._came_to([{"type": "input_text", "text": f"Verifier: {answer}"},
2607
+ *(image_parts(view["images"], self.cameras) if self._standing else [])])
2578
2608
  self.reason = "verify"
2579
2609
 
2580
2610
  def _verify(self, claim, cameras=None, request=None):
@@ -2712,11 +2742,12 @@ class TaskRun:
2712
2742
  trace.emit("program_held")
2713
2743
  self._checkpoint()
2714
2744
  with self._condition:
2715
- if not self._current_output(loop):
2716
- trace.emit("program_dropped", reason="user_message" if self._inbox else "inputs_changed")
2717
- self._tell("The user paused before this program ran, so nothing ran." if waiting
2718
- else "A user message came before this program ran, so nothing ran." if self._inbox
2719
- else "An event reached you before this program ran, so nothing ran.")
2745
+ # (After a pause a message of the user replaces the program.)
2746
+ replaced = waiting and self._message_waits()
2747
+ if replaced or not self._current_output(loop):
2748
+ trace.emit("program_dropped", reason="user_message" if replaced else "inputs_changed")
2749
+ self._came_to("The user paused before this program ran, so nothing ran." if waiting
2750
+ else "Something reached you before this program ran, so nothing ran.")
2720
2751
  self.reason = "user"
2721
2752
  return None
2722
2753
  summary["cells"] += 1
@@ -2744,16 +2775,16 @@ class TaskRun:
2744
2775
  with self._condition:
2745
2776
  if started in self._programs.values():
2746
2777
  # (Else it ended meanwhile: its result is what the model is told.)
2747
- self._tell(decisions.RUNNING.format(number=number, unit=result["unit"])
2748
- + f"\nModel calls left: {self.config.max_model_calls - self._iterations}")
2778
+ self._came_to(decisions.RUNNING.format(number=number, unit=result["unit"]))
2749
2779
  self.reason = "program_running"
2750
2780
  return None
2751
2781
 
2752
2782
  def _unit_arrived(self, result: dict) -> None:
2753
2783
  """A unit of the model ended: its result came as the reply to its program, or as the
2754
- kernel's unit_end message (any thread). It is recorded now and told to the model
2755
- with its next call (_tell_news); an end that is an event (an error, an unhandled
2756
- event, the episode's end, finish()) sets a call in flight aside."""
2784
+ kernel's unit_end message (any thread). It is recorded now and is a notice for the
2785
+ model: told with its next call, or at once (a call in flight is set aside) when the
2786
+ end is an event (an error, an unhandled event, the episode's end, finish()). The
2787
+ end of a unit that was cancelled wakes nobody."""
2757
2788
  trace, summary = self.trace, self.summary
2758
2789
  result = {key: value for key, value in result.items() if key not in ("op", "time")}
2759
2790
  number = result.get("cell")
@@ -2791,25 +2822,48 @@ class TaskRun:
2791
2822
  self._run_end = "episode_ended"
2792
2823
  elif status == "finished" and self._run_end is None:
2793
2824
  self._run_end = ("finished", str(result.get("finish") or ""))
2794
- self._unit_news.append(result)
2795
- if status not in ("ok", "cancelled") and not result.get("handled"):
2796
- self._revision += 1
2797
- self._preempt("a unit ended with an event")
2798
- self._condition.notify_all()
2825
+ if result.get("state"):
2826
+ self._state_now = result["state"]
2827
+ urgent = status not in ("ok", "cancelled") and not result.get("handled")
2828
+ self._put("unit", NOW if urgent else NEXT, result, wakes=status != "cancelled",
2829
+ reason="a unit ended with an event")
2799
2830
  self.charge_up()
2800
2831
 
2801
- def _tell_news(self, loop) -> None:
2802
- """Tell the model what its units ended with since its last call: each program's
2803
- feedback (status, output, events, state), each other unit's end, what they showed
2804
- and looked at, the units still running and the calls left."""
2832
+ def _notice_parts(self, notice) -> list:
2833
+ """A message, an event or a note of the queue as the model reads it."""
2834
+ if notice.kind == "message":
2835
+ return _inbox_parts([notice.data])
2836
+ if notice.kind == "event":
2837
+ record = notice.data
2838
+ event = record.get("event") or {}
2839
+ more = {key: value for key, value in record.items() if key not in ("id", "event", "time")}
2840
+ if event.get("detail") not in (None, {}, ""):
2841
+ more["detail"] = event["detail"]
2842
+ return [{"type": "input_text", "text": decisions.EVENT.format(
2843
+ kind=event.get("kind"), source=event.get("source")) + (": " + json.dumps(more) if more else "")}]
2844
+ return [{"type": "input_text", "text": str(notice.data)}]
2845
+
2846
+ def _deliver(self, loop) -> None:
2847
+ """Tell the model what there is to tell, with its next call: the one place that
2848
+ does. First what its last output came to (_came_to), then the notices of the queue
2849
+ down to the priority that is due (runtime/decision/notices.py), each as its kind
2850
+ reads (a program's feedback with what it showed and looked at, another unit's end,
2851
+ a message, an event, a note), then how things stand now (_ambient). Nothing when
2852
+ there is neither."""
2805
2853
  with self._condition:
2806
- news, self._unit_news = self._unit_news, []
2807
- if not news:
2854
+ upto, self._upto = self._upto, NEXT
2855
+ notices = self._notices.take(upto)
2856
+ outcome, self._outcome = self._outcome, []
2857
+ if not notices and not outcome:
2808
2858
  return
2809
- config, trace, embodiment, cameras = self.config, self.trace, self.config.embodiment, self.cameras
2859
+ trace, cameras = self.trace, self.cameras
2810
2860
  order = ("unit_end", "program_end", "escalation", "error")
2811
- content, looks, outlines, reason, taken, state, programs = [], [], {}, "unit_end", None, None, 0
2812
- for result in news:
2861
+ content, looks, outlines, reason, taken, state, programs = list(outcome), [], {}, None, None, None, 0
2862
+ for notice in notices:
2863
+ if notice.kind != "unit":
2864
+ content += self._notice_parts(notice)
2865
+ continue
2866
+ result = notice.data
2813
2867
  program, status = result.get("program"), result["status"]
2814
2868
  if program is not None:
2815
2869
  programs += 1
@@ -2817,15 +2871,14 @@ class TaskRun:
2817
2871
  self._stuck(program["code"], result)
2818
2872
  taken = taken or _taken_over(result)
2819
2873
  why = {"escalated": "escalation", "error": "error"}.get(status, "program_end")
2820
- text = cell_feedback(result, program["number"], self.profile.get("control_hz"), embodiment,
2821
- self._steps_shown())
2874
+ text = cell_feedback(result, program["number"])
2822
2875
  if why == "program_end":
2823
2876
  text += decisions.PROGRAM_ENDED
2824
2877
  state = result.get("state") or state
2825
2878
  else:
2826
2879
  why = "escalation" if status in ("error", "escalated") and not result.get("handled") else "unit_end"
2827
2880
  text = unit_feedback(result)
2828
- reason = max(reason, why, key=order.index)
2881
+ reason = why if reason is None else max(reason, why, key=order.index)
2829
2882
  content.append({"type": "input_text", "text": text, "result": True})
2830
2883
  for item in result.get("attachments", [])[:6]:
2831
2884
  content.append({"type": "input_text", "text": f"show(): {item['caption']}"})
@@ -2841,22 +2894,14 @@ class TaskRun:
2841
2894
  views=[{key: item[key] for key in ("camera", "region", "pin") if key in item}
2842
2895
  for item in seen])
2843
2896
  looks += seen
2844
- self.reason = reason
2897
+ if reason is not None:
2898
+ self.reason = reason
2845
2899
  with self._condition:
2846
- calls_left = config.max_model_calls - self._iterations
2847
- running = [unit_text(identifier, unit) for identifier, unit in self._units.items()]
2848
- tree = self._tree_told()
2849
- note = ""
2850
- if self._post_from is not None and loop.post_calls:
2851
- calls_left = min(calls_left, loop.post_calls - (self.summary["model_calls"] - self._post_from))
2852
- note = ("After these calls the learned policy runs on by itself to the end of the episode.\n"
2853
- if calls_left > 0 else "")
2854
- # What was learned so far, where this run learns: whole when it changed, else its first line.
2855
- head, _, body = self._learning_report().strip().partition("\n")
2856
- learned = (head + ("\n" + body if body != self._learning_told else " as you were last told") + "\n") if head else ""
2857
- self._learning_told = body
2858
- content.append({"type": "input_text", "text": ("Units running: " + latest(running) + "\n" if running else "")
2859
- + (tree + "\n" if tree else "") + learned + note + f"Model calls left: {calls_left}"})
2900
+ for notice in notices:
2901
+ if notice.kind in ("message", "event"):
2902
+ self._unanswered.add(notice.kind)
2903
+ if notice.kind == "event":
2904
+ self._told_events.append(notice.data.get("id"))
2860
2905
  if not taken and reason in ("error", "escalation"):
2861
2906
  self._reflect_learning()
2862
2907
  if taken is not None:
@@ -2871,27 +2916,72 @@ class TaskRun:
2871
2916
  view = self.env.call("observe", episode_id=self.episode, cameras=cameras)
2872
2917
  content.extend(image_parts({**view["images"], **outlines}, cameras))
2873
2918
  state = view["state"]
2919
+ with self._condition:
2920
+ self._state_now = state
2874
2921
  else:
2875
2922
  # Only what the units looked at (look, a standing watch of the model's own).
2876
2923
  with self._condition:
2877
2924
  self._view_pins |= {item["pin"] for item in looks if item.get("pin")}
2878
2925
  content.extend(view_parts(looks) if self._images else self._described(looks))
2926
+ with self._condition:
2927
+ # How things stand is told once, last: where the message this call ends with
2928
+ # already says it (a call that was set aside), that part gives way to this one,
2929
+ # which tells again what that one told as changed.
2930
+ last = self.messages[-1] if self.messages else None
2931
+ if last is not None and last["role"] == "user" and not isinstance(last["content"], str) and any(
2932
+ part.get("ambient") for part in last["content"]):
2933
+ last["content"] = [part for part in last["content"] if not part.get("ambient")]
2934
+ self._reflex_told, self._learning_told = getattr(self, "_ambient_before", ({}, None))
2935
+ self._ambient_before = dict(getattr(self, "_reflex_told", {})), self._learning_told
2936
+ content.append(self._ambient(loop))
2879
2937
  with self._condition:
2880
2938
  self._say(content)
2881
2939
  if (state or {}).get("ended"):
2882
2940
  self._run_end = "episode_ended"
2883
2941
 
2942
+ def _ambient(self, loop) -> dict:
2943
+ """How things stand now, told last with every call that tells the model anything,
2944
+ whatever it is told: the state, the units that run, what changed in the tree of
2945
+ reflexes, what was learned. What the run has left (its steps, its calls, its time)
2946
+ is told only where the run asks for it (runtime.tell_budget): the limits are the
2947
+ host's to keep, and a countdown with every call weighs on every judgement."""
2948
+ config, embodiment = self.config, self.config.embodiment
2949
+ with self._condition:
2950
+ calls_left = config.max_model_calls - self._iterations
2951
+ running = [unit_text(identifier, unit) for identifier, unit in self._units.items()]
2952
+ tree = self._tree_told()
2953
+ state = self._state_now
2954
+ lines = []
2955
+ if state:
2956
+ lines.append(f"{EMBODIMENT_TEXT[embodiment]['state_label']}: "
2957
+ + state_text(state, embodiment, self._steps_shown()))
2958
+ if self._budget_told and self._steps_shown() and state.get("step") is not None:
2959
+ lines.append(steps_text(state, self.profile.get("control_hz")))
2960
+ if running:
2961
+ lines.append("Units running: " + latest(running))
2962
+ if tree:
2963
+ lines.append(tree)
2964
+ # What was learned so far, where this run learns: whole when it changed, else its first line.
2965
+ head, _, body = self._learning_report().strip().partition("\n")
2966
+ if head:
2967
+ lines.append(head + ("\n" + body if body != self._learning_told else " as you were last told"))
2968
+ self._learning_told = body
2969
+ if self._budget_told:
2970
+ if self._post_from is not None and loop.post_calls:
2971
+ calls_left = min(calls_left, loop.post_calls - (self.summary["model_calls"] - self._post_from))
2972
+ if calls_left > 0:
2973
+ lines.append("After these calls the learned policy runs on by itself to the end of the episode.")
2974
+ lines.append(f"Model calls left: {calls_left}")
2975
+ return {"type": "input_text", "text": "\n".join(lines), "ambient": True}
2976
+
2884
2977
  def _think(self):
2885
- """Queue the model's next call with its immutable input, on the trigger of what is
2886
- pending (a message, an unresolved event), else of what happened last (self.reason)."""
2887
- triggers = decisions.TRIGGERS
2888
- trigger = next((name for name, check in triggers.items() if check and getattr(self, check)()), None)
2889
- if trigger is None:
2890
- trigger = self.reason
2891
- if trigger not in triggers:
2892
- raise ValueError(f"No model trigger for {trigger!r}")
2893
- self._include_escalations()
2894
- self._add_user_messages()
2978
+ """Queue the model's next call with its immutable input, on the trigger of what it
2979
+ was told and has not answered (a message, then an event), else of what happened
2980
+ last (self.reason)."""
2981
+ trigger = ("user" if "message" in self._unanswered else "escalation" if "event" in self._unanswered
2982
+ else self.reason)
2983
+ if trigger not in decisions.REASONS:
2984
+ raise ValueError(f"No model trigger for {trigger!r}")
2895
2985
  config, summary, messages = self.config, self.summary, self.messages
2896
2986
  if self._standing:
2897
2987
  prune_images(messages, int(config.runtime.get("keep_images", 2)))
@@ -2917,7 +3007,7 @@ class TaskRun:
2917
3007
  total_messages=len(messages), sent_messages=len(request),
2918
3008
  new_messages=history[self._logged:], context=context_summary(request, system),
2919
3009
  library_version=getattr(self, "_library_version", None), revision=thought.revision,
2920
- events=list(self._pending_events), **self._replaced())
3010
+ events=list(self._told_events), **self._replaced())
2921
3011
  self._logged = len(messages)
2922
3012
  summary["model_calls"] += 1
2923
3013
  summary["decisions"][trigger] = summary["decisions"].get(trigger, 0) + 1
@@ -2943,21 +3033,6 @@ class TaskRun:
2943
3033
  self._logged -= 1
2944
3034
  self._replaces = 1
2945
3035
 
2946
- def _include_escalations(self):
2947
- parts = []
2948
- for identifier, report in self._pending_events.items():
2949
- if identifier not in self._reported_events:
2950
- self._reported_events.add(identifier)
2951
- parts.append({"type": "input_text", "text": f"Unresolved event: {json.dumps(report)}"})
2952
- if parts:
2953
- self._say(parts)
2954
-
2955
- def _pending_message(self):
2956
- return bool(self._inbox)
2957
-
2958
- def _unresolved(self):
2959
- return bool(self._pending_events)
2960
-
2961
3036
  def _came_back(self, thought):
2962
3037
  from harness.runtime.decision.model import add_usage
2963
3038
 
@@ -3053,7 +3128,7 @@ class TaskRun:
3053
3128
  identifier = self._program_approval_id = uuid.uuid4().hex
3054
3129
  self.trace.emit("confirmation_request", id=identifier, code=program)
3055
3130
  try:
3056
- self._wait(WAITING_FOR_CONFIRMATION, lambda: self._decision is not None or bool(self._inbox),
3131
+ self._wait(WAITING_FOR_CONFIRMATION, lambda: self._decision is not None or self._message_waits(),
3057
3132
  reason="program", request={"id": identifier, "code": program})
3058
3133
  finally:
3059
3134
  with self._condition:
@@ -3066,7 +3141,7 @@ class TaskRun:
3066
3141
  self.trace.emit("confirmation", id=identifier, accepted=accepted, reason=reason)
3067
3142
  if accepted:
3068
3143
  return True
3069
- self._tell("The user rejected this program, so nothing ran." + (f" Their reason: {reason}" if reason else ""))
3144
+ self._came_to("The user rejected this program, so nothing ran." + (f" Their reason: {reason}" if reason else ""))
3070
3145
  self.reason = "rejected"
3071
3146
  return False
3072
3147
 
@@ -3086,7 +3161,7 @@ class TaskRun:
3086
3161
  or cells <= self._reflected_cells or self.seconds_left() <= 0):
3087
3162
  return
3088
3163
  with self._condition:
3089
- if self._pause or self._closing or self._inbox or self._busy():
3164
+ if self._pause or self._closing or self._message_waits() or self._busy():
3090
3165
  return
3091
3166
  revision = self._revision
3092
3167
  since = self._reflected_cells
@@ -85,8 +85,9 @@ _CORE_SCHEMA = {section: {key: Setting(*row) for key, row in rows.items()} for s
85
85
  },
86
86
  "approvals": {
87
87
  "ask": ("sensitive", "choice", ("sensitive", "programs"),
88
- "what waits for your approval: sensitive (steps that touch credentials, a payment, sending, deleting "
89
- "or cannot be undone; they always wait) or programs (every program as well)"),
88
+ "what waits for your approval: sensitive (steps the environment recognizes as touching credentials, "
89
+ "a payment, sending, deleting or what cannot be undone; they always wait; Permissions lists which "
90
+ "environments check) or programs (every program as well)"),
90
91
  "programs": ("ask_once_session", "choice", ("never", "ask_each", "ask_once_session", "allow"),
91
92
  "what a program of the agent may do on this computer beyond its own folder (run a command, "
92
93
  "reach the network, write a file elsewhere), where no rule says otherwise: never, ask each "