@lmmslab/harness 0.83.0 → 0.85.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 (38) hide show
  1. package/bin/harness.js +6 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +1 -1
  4. package/python/harness/builtin/prompts/core/core.md +68 -38
  5. package/python/harness/builtin/prompts/shared/learning-goal.md +1 -1
  6. package/python/harness/cli.py +140 -18
  7. package/python/harness/config/agent.py +3 -0
  8. package/python/harness/core/trace.py +23 -3
  9. package/python/harness/core/worker.py +6 -0
  10. package/python/harness/host/client.py +26 -21
  11. package/python/harness/host/http.py +11 -1
  12. package/python/harness/host/sessions.py +38 -3
  13. package/python/harness/host/tasks.py +71 -27
  14. package/python/harness/instructions.py +329 -0
  15. package/python/harness/model_list.py +25 -5
  16. package/python/harness/packages/environments.py +51 -12
  17. package/python/harness/packages/manager.py +379 -102
  18. package/python/harness/packages/resolve.py +52 -15
  19. package/python/harness/packages/sources.py +17 -5
  20. package/python/harness/packages/state.py +10 -0
  21. package/python/harness/providers.py +66 -24
  22. package/python/harness/runtime/decision/model.py +9 -4
  23. package/python/harness/runtime/events.py +1 -0
  24. package/python/harness/runtime/execution/entries.py +53 -7
  25. package/python/harness/runtime/execution/session.py +57 -10
  26. package/python/harness/runtime/learning/active.py +4 -4
  27. package/python/harness/runtime/reactive/tree.py +96 -53
  28. package/python/harness/runtime/task/environments.py +3 -1
  29. package/python/harness/runtime/task/run.py +93 -4
  30. package/python/harness/runtime/tick.py +34 -3
  31. package/python/harness/settings.py +23 -1
  32. package/python/harness/terminal.py +3 -0
  33. package/python/harness/transcript.py +12 -0
  34. package/python/harness/tui/__init__.py +28 -6
  35. package/python/harness/tui/chat.py +323 -80
  36. package/python/harness/tui/pty.py +16 -0
  37. package/python/harness/tui/renderer.py +1 -0
  38. package/python/harness/tui/views.py +160 -38
@@ -1,22 +1,30 @@
1
1
  """The reactive layer: one tree of reflexes.
2
2
 
3
- What acts without the model is one tree, empty at first. A node says when it has its turn
4
- (`when`: a condition of the view, or the name of an event) and what it does then (`do`: a
5
- program, the name of an event to raise, an action that ends what runs, or nothing: then it
6
- is a group, and the nodes under it are its content). Three statements are the whole of it:
7
-
8
- 1. A node under another has its turn only while that one's condition holds.
3
+ What acts without the model is one tree, empty at first. A node is a situation: it says
4
+ when the agent is in it (`when`: a condition of the view, or the name of an event) and what
5
+ answers it (`do`: a program, the name of an event to raise, an action that ends what runs,
6
+ or nothing). Any node may have nodes under it: the narrower situations within it. Four
7
+ statements are the whole of it:
8
+
9
+ 1. A node under another has its turn only while that one's condition holds, and before
10
+ it: while a node under it is answering, the node itself does not act. What the node
11
+ does itself answers what is in its situation and in none of those under it. So a
12
+ node is complete when it is set, and the tree grows by putting nodes under nodes,
13
+ which changes none of them.
9
14
  2. Among the nodes at one place the earlier (the higher priority, then the older) takes
10
15
  the environment from the later, and gives it back when it is done.
11
16
  3. A node has done its work when the situation it answers is over: its program is a
12
17
  unit whose completion condition is that the node's condition no longer holds
13
18
  (runtime/execution/entries.py: how a unit ended and whether its work is done are two
14
19
  things, for every unit). When its program ends and the situation is not over, or
15
- the program fails, a later node at that place whose condition holds has the
16
- environment; when none has, the model is told what the program did (the event
17
- REFLEX_FAILED), once until the node has done its work again.
18
-
19
- A node's program runs as a unit whose priority is the node's place in the tree (rank()):
20
+ the program fails, what comes after it has the environment: a later node at that
21
+ place whose condition holds, then what the node above does itself; when nothing
22
+ has, the model is told what the program did (the event REFLEX_FAILED), once until
23
+ the node has done its work again.
24
+ 4. A node that tells the model (`do` an event's name) has its turn like any other: it
25
+ tells when neither a node before it at its place nor one under it is answering.
26
+
27
+ A node's program runs as a unit whose priority is the node's own priority (rank()):
20
28
  the units' priorities are how the tick lets the earlier take the environment from the later
21
29
  (runtime/tick.py: the later call is paused where the environment pauses, else ended, and
22
30
  its node begins again). Every node's place is above the model's own programs: a reflex
@@ -73,9 +81,9 @@ def told(nodes: dict, before: dict) -> str:
73
81
  @dataclass
74
82
  class Reflex:
75
83
  """A node of the tree: its `name`; `when` it has its turn (a condition of the view) or
76
- the `event` it answers; what it does: `do` (a program), or `action` (an event to raise,
77
- or one of the environment's actions that end what runs), or neither (a group); the node
78
- it is `under` (None: the top); its `priority` among the nodes at its place; `every`
84
+ the `event` it answers; what it does itself: `do` (a program), or `action` (an event to
85
+ raise, or one of the environment's actions that end what runs), or neither (then only
86
+ the nodes under it answer); the node it is `under` (None: the top); its own `priority`; `every`
79
87
  seconds its condition is judged (None: when the state or the facts change);
80
88
  `again_seconds` before it may begin again after its program ended."""
81
89
 
@@ -182,7 +190,7 @@ class Reflexes:
182
190
  """Put the node `name` into the tree, in place of a node of that name (see Reflex;
183
191
  `when`: a function of the view, or the name of an event; `do`: a program, or the
184
192
  name of an event to raise, or an action of the environment that ends what runs
185
- ("stop"), or None for a group). Its name."""
193
+ ("stop"), or None: then only the nodes under it answer). Its name."""
186
194
  staging = getattr(_staging, "layers", None)
187
195
  if staging is not None and staging[0] is self:
188
196
  return staging[1].set(name, when, do, under=under, priority=priority, every=every,
@@ -206,7 +214,7 @@ class Reflexes:
206
214
  action, stops, do = do, do in self.actions, None
207
215
  elif do is not None and not callable(do):
208
216
  raise TypeError("`do` is a program (a function), the name of an event, an action that ends what runs, "
209
- "or None for a group")
217
+ "or None (then only the nodes under it answer)")
210
218
  if isinstance(priority, bool) or not isinstance(priority, int) or priority < 0:
211
219
  raise ValueError(f"priority is a whole number, 0 or more, got {priority!r}")
212
220
  if isinstance(again_seconds, bool) or not isinstance(again_seconds, (int, float)) or again_seconds < 0:
@@ -220,17 +228,17 @@ class Reflexes:
220
228
  above = known.get(under)
221
229
  if above is None:
222
230
  raise ValueError(f"no reflex is named {under!r}: the node a reflex is under is set first")
223
- if above.do is not None or above.action is not None or above.event is not None:
224
- raise ValueError(f"{under!r} does something itself: a node that has nodes under it is a group "
225
- "(set without `do`)")
231
+ if above.event is not None or above.stops:
232
+ # (Neither is a situation the agent is in for a while, which others could narrow.)
233
+ raise ValueError(f"{under!r} answers an event or ends what runs: nodes go under a node whose "
234
+ "`when` is a condition")
226
235
  while above is not None:
227
236
  if above.name == name:
228
237
  raise ValueError(f"{name!r} cannot be under itself")
229
238
  above = known.get(above.under) if above.under is not None else None
230
239
  old = known.get(name)
231
- if (do is not None or action is not None or event is not None) and any(
232
- node.under == name for node in known.values()):
233
- raise ValueError(f"{name!r} has nodes under it: it stays a group (set without `do`)")
240
+ if (event is not None or stops) and any(node.under == name for node in known.values()):
241
+ raise ValueError(f"{name!r} has nodes under it: its `when` stays a condition, and it does not end what runs")
234
242
  self._count += 1
235
243
  self._retire(self.nodes.get(name))
236
244
  self.nodes[name] = Reflex(name, when, event, do, action, stops, under, priority,
@@ -279,8 +287,7 @@ class Reflexes:
279
287
  running = node.unit is not None and bool(getattr(node.unit, "running", False))
280
288
  lines[here] = (f"began {node.triggered}, did its work {node.did}, did not {node.did_not}"
281
289
  + (", runs now" if running else ""))
282
- else:
283
- lines.update(self.digest(node.name, here + "/"))
290
+ lines.update(self.digest(node.name, here + "/"))
284
291
  return lines
285
292
 
286
293
  def tell(self) -> None:
@@ -320,25 +327,32 @@ class Reflexes:
320
327
  key=lambda node: (-node.priority, node.order))
321
328
 
322
329
  def _leaves(self, name) -> list:
323
- """The nodes with a program at and under `name`, in the tree's order."""
330
+ """The nodes with a program at and under `name`, in the order their turn comes: those
331
+ under a node before the node itself."""
324
332
  node = self.nodes.get(name)
325
333
  if node is None:
326
334
  return []
327
- if node.do is not None:
328
- return [node]
329
- return [leaf for child in self.children(name) for leaf in self._leaves(child.name)]
335
+ return [leaf for child in self.children(name) for leaf in self._leaves(child.name)] + (
336
+ [node] if node.do is not None else [])
337
+
338
+ def _above(self, node) -> list:
339
+ """The nodes `node` is under, the nearest first."""
340
+ found, above = [], self.nodes.get(node.under) if node.under is not None else None
341
+ while above is not None and above not in found:
342
+ found.append(above)
343
+ above = self.nodes.get(above.under) if above.under is not None else None
344
+ return found
330
345
 
331
346
  def rank(self, node) -> float:
332
- """What a node's program holds the environment with: above the priority of the node
333
- at the top of its part of the tree by a part of 1, the larger the earlier the node
334
- comes among the nodes with a program there. So the tree's order is the order of its
335
- units' priorities, and every node is above the model's programs (0)."""
336
- top = node
337
- while top.under is not None and top.under in self.nodes:
338
- top = self.nodes[top.under]
339
- leaves = self._leaves(top.name)
347
+ """What a node's program holds the environment with: the node's own priority,
348
+ wherever it is in the tree, and above it a part of 1, the larger the earlier the
349
+ node comes in the tree's order among the nodes with a program. So the node that
350
+ runs is what a program's priority (at_priority) and every other node's is compared
351
+ with: the higher has the environment, among equals the earlier in the tree; and
352
+ every node is above the model's programs (0)."""
353
+ leaves = [leaf for top in self.children() for leaf in self._leaves(top.name)]
340
354
  place = next((index for index, leaf in enumerate(leaves) if leaf is node), 0)
341
- return top.priority + (len(leaves) - place) / (len(leaves) + 1)
355
+ return node.priority + (len(leaves) - place) / (len(leaves) + 1)
342
356
 
343
357
  def listing(self, name=None) -> list:
344
358
  """The nodes at the top of the tree, or the node `name` where it has none under it,
@@ -538,13 +552,18 @@ def judge(session, tree):
538
552
  layer.wake_at = now if layer.wake_at is None else min(layer.wake_at, now)
539
553
  return node.holds
540
554
 
541
- wanting = []
555
+ wanting, telling = [], []
542
556
 
543
557
  def over(node):
544
558
  # What a node's program is for: the situation the node answers is over.
545
559
  return lambda view: not layer._run(node, view)
546
560
 
547
561
  def walk(name):
562
+ # The nodes at and under `name` whose condition holds, the earlier first; under a
563
+ # node before the node itself, which answers only what none of them does. Those with
564
+ # a program are returned; each node that acts is kept with the ones whose turn comes
565
+ # before its own: those under it, and for one that tells, those before it at its place.
566
+ before = []
548
567
  for node in layer.children(name):
549
568
  if node.event is not None or node.stops or layer.nodes.get(node.name) is not node:
550
569
  continue
@@ -554,28 +573,31 @@ def judge(session, tree):
554
573
  fault(node, error)
555
574
  continue
556
575
  if not held:
557
- # The situation is over.
558
- node.raised = node.told = False
576
+ # The situation is over. (Whether the model was told that the node failed
577
+ # stays: it is told again only after the node has done its work, else a
578
+ # condition that comes and goes tells the same failure every time.)
579
+ node.raised = False
559
580
  # (What is under it is judged anew when its turn comes again.)
560
581
  for below in layer._below(node.name)[1:]:
561
- below.holds = _UNSEEN
582
+ below.holds, below.raised = _UNSEEN, False
562
583
  continue
584
+ under = walk(node.name)
563
585
  if node.action is not None:
564
- if not node.raised and now >= node.ready_at:
565
- node.raised, node.ready_at = True, now + node.again_seconds
566
- node.triggered += 1
567
- event = session._rule_event(node, state)
568
- needs_model = isinstance(event.detail, dict) and event.detail.get("needs_model") is True
569
- emit(tree, None, "reflex", event, notice=not needs_model)
586
+ telling.append((node, before + under))
570
587
  elif node.do is not None:
571
- wanting.append(node)
572
- else:
573
- walk(node.name)
588
+ wanting.append((node, under))
589
+ before += under + ([node] if node.do is not None else [])
590
+ return before
574
591
 
575
592
  walk(None)
576
593
  running = [entry for entry in tree.running() if entry.kind != "agent"]
577
594
  startable = set()
578
- for node in wanting:
595
+ for node, under in wanting:
596
+ if any(found.name in startable for found in under):
597
+ # A narrower situation under it is being answered: what the node does itself
598
+ # gives way, also where it already runs.
599
+ layer._retire(node)
600
+ continue
579
601
  if node.unit is not None:
580
602
  startable.add(node.name)
581
603
  continue
@@ -583,7 +605,10 @@ def judge(session, tree):
583
605
  layer.wake_at = node.ready_at if layer.wake_at is None else min(layer.wake_at, node.ready_at)
584
606
  continue
585
607
  rank = layer.rank(node)
586
- above = next((entry for entry in running if (entry.priority or 0) > rank), None)
608
+ # (The programs of the nodes it is under give way to it: they do not keep it waiting.)
609
+ giving_way = {above.name for above in layer._above(node)}
610
+ above = next((entry for entry in running if entry.rank > rank
611
+ and getattr(entry, "rule", None) not in giving_way), None)
587
612
  if above is not None:
588
613
  # What is before it has the environment: its turn is judged when that ends. Where
589
614
  # that is a program that said so (at_priority), the model is told once.
@@ -600,11 +625,29 @@ def judge(session, tree):
600
625
  running.append(node.unit)
601
626
  startable.add(node.name)
602
627
  spans.note("rule", name=node.name, action="began", unit=node.unit.id, priority=rank)
628
+ # A node that tells the model has its turn like any other: when none of those whose
629
+ # turn comes before its own (under it, and before it at its place) is acting. So it
630
+ # tells what nothing answered, and no more.
631
+ for node, before in telling:
632
+ if any(found.name in startable for found in before):
633
+ continue
634
+ if not node.raised and now >= node.ready_at:
635
+ node.raised, node.ready_at = True, now + node.again_seconds
636
+ node.triggered += 1
637
+ # (The event is offered to the nodes that answer its kind; one that none answers
638
+ # reaches the model: that is what telling is.)
639
+ emit(tree, None, "reflex", session._rule_event(node, state))
603
640
  layer.tell()
604
641
  for node, unit in failures:
642
+ # What comes after a node whose program did not do its work: a later node at its
643
+ # place, then what the nodes above it do themselves (a program that is acting, or
644
+ # their telling the model).
605
645
  later = layer.children(node.under)
606
646
  later = later[later.index(node) + 1:] if node in later else []
607
- if node.told or any(found.name in startable for other in later for found in layer._leaves(other.name)):
647
+ taken = any(found.name in startable for other in later for found in layer._leaves(other.name)) or any(
648
+ above.name in startable or (above.action is not None and not above.stops and above.raised)
649
+ for above in layer._above(node))
650
+ if node.told or taken:
608
651
  continue
609
652
  node.told = True
610
653
  emit(tree, None, "reflex", Event(ev.REFLEX_FAILED, node.name, {
@@ -174,6 +174,8 @@ class Environments:
174
174
  with self._lock:
175
175
  self.attached[kind] = row
176
176
  conversation._prompt_added(row["prompt"])
177
+ # A folder of its own: that project's instruction files (instructions.py).
178
+ conversation.instructions_attached(row.get("root"))
177
179
  trace.emit("environment_attached", kind=kind, label=label, why=why, level=level, asked=asked,
178
180
  skipped_confirmation=bool(skips and level not in ("allow",) and not granted),
179
181
  **{**(taken.get("metadata") or {}), **({"folder": str(folder)} if folder else {})})
@@ -218,7 +220,7 @@ class Environments:
218
220
  # itself would make them.
219
221
  "plain": RemoteEnvironment(endpoint, timeout=float(getattr(env, "timeout", 300.0)))
220
222
  if endpoint else env,
221
- "slot": threading.BoundedSemaphore(8), "prompt": prompt,
223
+ "slot": threading.BoundedSemaphore(8), "prompt": prompt, "root": profile.get("root"),
222
224
  "answer": {"session": session,
223
225
  "about": f"{kind} ({label}) is attached: call it as {kind}.NAME(...). Its calls are "
224
226
  "described in your instructions from your next reply on; "
@@ -193,6 +193,9 @@ class TaskRun:
193
193
  self._facts = dict((restore or {}).get("facts") or {})
194
194
  self.status = IDLE
195
195
  self.messages = []
196
+ # The instruction files read (instructions.Loaded, one per folder) and the directories
197
+ # below the folder whose files a program's touch brought in (_instructions_touched).
198
+ self.instructions, self._instructions_told = [], set()
196
199
  self.kernel = None
197
200
  self.episode = None
198
201
  self.summary = None
@@ -207,6 +210,9 @@ class TaskRun:
207
210
  self._upto = LATER
208
211
  self._unanswered = set()
209
212
  self._told_events = []
213
+ # The events told and not answered yet, by (kind, source): one that comes again
214
+ # meanwhile tells nothing new.
215
+ self._told_sources = set()
210
216
  self._urgent = 0
211
217
  self._state_now = None
212
218
  self._pause = False
@@ -769,6 +775,8 @@ class TaskRun:
769
775
  self._mcp_entries.discard(record["id"])
770
776
  self._units.pop(record["id"], None)
771
777
  self._condition.notify_all()
778
+ if kind == "span_start" and record.get("lane") == "skill":
779
+ self._instructions_touched(record)
772
780
  if kind == "span_start" and record.get("parent") is None:
773
781
  # Under the program whose unit made it, else under the host's own program span.
774
782
  cell = (self._units.get(record.get("entry")) or {}).get("cell")
@@ -1132,8 +1140,17 @@ class TaskRun:
1132
1140
  """Whether a message waits to be told (the caller holds the condition)."""
1133
1141
  return bool(self._notices.pending(kinds=("message",)))
1134
1142
 
1143
+ @staticmethod
1144
+ def _event_key(record) -> tuple:
1145
+ event = record.get("event") or {}
1146
+ return event.get("kind"), event.get("source")
1147
+
1135
1148
  def _escalation(self, record, priority=NOW):
1136
- """An event for the model: a notice, at once unless its source says otherwise."""
1149
+ """An event for the model: a notice, at once unless its source says otherwise. One
1150
+ that repeats an event the model has not answered yet (the same kind from the same
1151
+ source) tells nothing new: where that one still waits in the queue it is counted
1152
+ with it (`times`), and where the model is being told it, the new one is told with
1153
+ the next call and sets none aside."""
1137
1154
  with self._condition:
1138
1155
  identifier = record["id"]
1139
1156
  if identifier in self._seen_events:
@@ -1141,6 +1158,15 @@ class TaskRun:
1141
1158
  self._seen_events.add(identifier)
1142
1159
  self.trace.emit("escalation", **{key: value for key, value in record.items() if key != "event"},
1143
1160
  reported=record["event"])
1161
+ key = self._event_key(record)
1162
+ waiting = next((notice for notice in self._notices.pending(kinds=("event",))
1163
+ if self._event_key(notice.data) == key), None)
1164
+ if waiting is not None:
1165
+ waiting.data = {**record, "times": int(waiting.data.get("times", 1)) + 1}
1166
+ self._condition.notify_all()
1167
+ return
1168
+ if priority == NOW and key in self._told_sources:
1169
+ priority = NEXT
1144
1170
  self._put("event", priority, record, reason="unhandled escalation")
1145
1171
 
1146
1172
  def _held_back(self, record: dict) -> None:
@@ -1912,6 +1938,63 @@ class TaskRun:
1912
1938
  self._reflex_told = dict(nodes)
1913
1939
  return text
1914
1940
 
1941
+ def _instruction_files(self) -> str:
1942
+ """The opening's instruction files: those a conversation working in the environment's
1943
+ folder (its profile's root) reads at its start, recorded in the trace (instructions)."""
1944
+ settings = self.config.runtime.get("instructions")
1945
+ if not settings:
1946
+ return ""
1947
+ from harness import instructions
1948
+
1949
+ try:
1950
+ loaded = instructions.load((self.profile or {}).get("root"), settings)
1951
+ except (OSError, ValueError) as error:
1952
+ self.trace.emit("instructions", files=[], warnings=[f"instruction files not read: {error}"])
1953
+ return ""
1954
+ self.instructions = [loaded]
1955
+ self.trace.emit("instructions", **loaded.record())
1956
+ return instructions.block(loaded)
1957
+
1958
+ def _instructions_touched(self, record) -> None:
1959
+ """A program read, wrote or ran something in the folder (a skill's span): the
1960
+ instruction files of the directories below the folder down to it, not told yet, reach
1961
+ the model with its next call (Claude Code's files in subdirectories, read on demand)."""
1962
+ settings = self.config.runtime.get("instructions")
1963
+ parameters = record.get("parameters")
1964
+ if (not settings or not self.instructions or self.instructions[0].folder is None
1965
+ or record.get("name") not in ("read", "write", "run", "start") or not isinstance(parameters, dict)):
1966
+ return
1967
+ touched = parameters.get("path") if record.get("name") in ("read", "write") else parameters.get("cwd")
1968
+ if not isinstance(touched, str) or not touched or touched == ".":
1969
+ return
1970
+ from harness import instructions
1971
+
1972
+ try:
1973
+ with self._condition:
1974
+ found = instructions.nested(self.instructions[0].folder, touched, settings, self._instructions_told)
1975
+ except (OSError, ValueError):
1976
+ return
1977
+ if found:
1978
+ self.trace.emit("instructions", folder=str(self.instructions[0].folder), nested=True,
1979
+ files=[{"path": str(item.path), "label": item.label,
1980
+ "bytes": len(item.text.encode("utf-8")), "size": item.size,
1981
+ **({"cut": True} if item.cut else {})} for item in found])
1982
+ self._note(instructions.told(found))
1983
+
1984
+ def instructions_attached(self, root) -> None:
1985
+ """An environment with a folder of its own joined the conversation: the model is told
1986
+ that folder's project instruction files (not the user's again) with its next call."""
1987
+ settings = self.config.runtime.get("instructions")
1988
+ if not settings or not root:
1989
+ return
1990
+ from harness import instructions
1991
+
1992
+ loaded = instructions.load(root, settings, user=False)
1993
+ self.instructions = [*getattr(self, "instructions", []), loaded]
1994
+ self.trace.emit("instructions", **loaded.record())
1995
+ if loaded.files:
1996
+ self._note(instructions.block(loaded).strip())
1997
+
1915
1998
  def _compact_if_due(self, loop) -> None:
1916
1999
  """Compaction: when the context the model's last call read has reached
1917
2000
  runtime.compact_at_tokens, the model writes a summary of the conversation
@@ -1962,6 +2045,9 @@ class TaskRun:
1962
2045
  self._replaces, self._logged = self._replaces + self._logged, 0
1963
2046
  self._context_tokens, self._compact_failures = 0, 0
1964
2047
  self._reflex_told, self._learning_told = {}, None
2048
+ # Files below the folder are told again when a program touches them (the summary
2049
+ # does not carry them), as Claude Code reloads them on demand.
2050
+ self._instructions_told = set()
1965
2051
  self.trace.emit("compaction", action="done", tokens=tokens, messages_before=before, messages=len(messages),
1966
2052
  summary=text)
1967
2053
  self._save()
@@ -2184,11 +2270,12 @@ class TaskRun:
2184
2270
 
2185
2271
  if active.is_active(runtime):
2186
2272
  # The active trigger: this run learns the environment for the task (runtime/learning/active.py).
2187
- instruction = active.goal(instruction, active.schedule(runtime.get("library"))["minutes"],
2188
- runtime.get("skills") or (), sandbox_of(runtime),
2273
+ instruction = active.goal(instruction, runtime.get("skills") or (), sandbox_of(runtime),
2189
2274
  legacy_memory="legacy_memory" in EMBODIMENT_KINDS[embodiment].prompt_features)
2190
2275
  self._said.insert(0, instruction)
2191
- opening = f"Instruction: {instruction}\n"
2276
+ # The user's and the project's instruction files (AGENTS.md, instructions.py), before
2277
+ # the task, as Codex gives them; compaction keeps this first message.
2278
+ opening = self._instruction_files() + f"Instruction: {instruction}\n"
2192
2279
  if config.task_description:
2193
2280
  opening += f"\nTask description:\n{config.task_description}\n\n"
2194
2281
  # What the library holds, from the first call on.
@@ -2433,6 +2520,7 @@ class TaskRun:
2433
2520
  self._settle(current, "used")
2434
2521
  self._unanswered.clear()
2435
2522
  self._told_events = []
2523
+ self._told_sources.clear()
2436
2524
  loop.revision, loop.urgent = current.revision, asked
2437
2525
  loop.call, loop.thought = current.call, current.id
2438
2526
  if policy:
@@ -2902,6 +2990,7 @@ class TaskRun:
2902
2990
  self._unanswered.add(notice.kind)
2903
2991
  if notice.kind == "event":
2904
2992
  self._told_events.append(notice.data.get("id"))
2993
+ self._told_sources.add(self._event_key(notice.data))
2905
2994
  if not taken and reason in ("error", "escalation"):
2906
2995
  self._reflect_learning()
2907
2996
  if taken is not None:
@@ -104,8 +104,11 @@ class Preempted(Exception):
104
104
 
105
105
 
106
106
  def _rank(unit) -> float:
107
- """What a unit holds the embodiment with: its priority."""
108
- return getattr(unit, "priority", 0) or 0
107
+ """What a unit holds the embodiment with now: its priority for the action it does (a
108
+ program's `with at_priority(n):`, a reflex's place), or what the code it runs in the
109
+ environment asks for (runtime/execution/entries.py Entry.rank)."""
110
+ rank = getattr(unit, "rank", None)
111
+ return rank if rank is not None else (getattr(unit, "priority", 0) or 0)
109
112
 
110
113
 
111
114
  class _Entry:
@@ -117,7 +120,6 @@ class _Entry:
117
120
  self.steps = None if callable(steps) else steps
118
121
  self.parent = parent
119
122
  self.owner = owner
120
- self.priority = _rank(owner)
121
123
  self.restart = getattr(owner, "restart", False)
122
124
  self.restarts = 0
123
125
  self.picked = False
@@ -139,6 +141,12 @@ class _Entry:
139
141
  self.fresh = None
140
142
  self.change = None
141
143
 
144
+ @property
145
+ def priority(self) -> float:
146
+ """What its unit holds the embodiment with now: it may change while the execution
147
+ runs (a block of `with at_priority(n):` ends, the environment's code asks for one)."""
148
+ return _rank(self.owner)
149
+
142
150
 
143
151
  class Tick:
144
152
  """The tick of one kernel session (see the module docstring): `run(steps)` runs an
@@ -430,7 +438,29 @@ class Tick:
430
438
  return
431
439
  spans.note("call_resumed", unit=getattr(entry.owner, "id", None), name=getattr(entry.owner, "name", None))
432
440
 
441
+ def _asked(self, entries) -> None:
442
+ """The priority the environment's own code asks for now (its state's "priority":
443
+ code that runs there for long holds the environment for one action of it, and says
444
+ so itself) is that of the unit whose execution runs."""
445
+ asked = self.session.state.get("priority")
446
+ asked = asked if isinstance(asked, (int, float)) and not isinstance(asked, bool) and asked > 0 else None
447
+ for entry in entries:
448
+ owner = entry.owner
449
+ if owner is None or not hasattr(owner, "asked") or owner.asked == asked:
450
+ continue
451
+ owner.asked = asked
452
+ spans.note("priority", unit=getattr(owner, "id", None), priority=_rank(owner), asked=asked)
453
+ if asked is not None and owner not in self._holders:
454
+ self._holders.append(owner)
455
+ layer = getattr(self.session, "reactive", None)
456
+ if layer is not None:
457
+ layer.changed = True
458
+ with self._changed:
459
+ self._judge = True
460
+
433
461
  def _end(self, entry):
462
+ if getattr(entry.owner, "asked", None) is not None:
463
+ entry.owner.asked = None
434
464
  with self._changed:
435
465
  self._undrive(entry)
436
466
  if entry in self._entries:
@@ -556,6 +586,7 @@ class Tick:
556
586
  if (self.bound and (entries or self._line)) or waiting or timed or (
557
587
  self._line and layer is not None and layer.stops()):
558
588
  session._observe()
589
+ self._asked(entries)
559
590
  if session.state.get("ended"):
560
591
  self._line.clear()
561
592
  with self._changed:
@@ -99,6 +99,24 @@ _CORE_SCHEMA = {section: {key: Setting(*row) for key, row in rows.items()} for s
99
99
  "command's program, the host or the folder; it wins over approvals.programs", "now",
100
100
  {"action": "text", "match": "text"}, {"level": "allow", "action": "network", "match": "*.github.com"}),
101
101
  },
102
+ "instructions": {
103
+ "load": ("all", "choice", ("all", "user", "off"),
104
+ "the instruction files a new conversation reads (instructions.py): all (yours, "
105
+ "~/.harness/AGENTS.md, and the project's AGENTS.md from its root down to the folder), user (yours "
106
+ "only), off (none)"),
107
+ "files": ("AGENTS.override.md, AGENTS.md, CLAUDE.md", "text", (0, 300),
108
+ "the file names tried in each directory, in order; the first with text is read (a directory's "
109
+ "CLAUDE.local.md is read after it)"),
110
+ "root_markers": (".git", "text", (0, 300),
111
+ "what marks a project's root: the nearest folder above holding one of these (comma-separated; "
112
+ "empty: only the conversation's folder is read)"),
113
+ "max_bytes": (32768, "int", (0, 1048576),
114
+ "bytes of instructions read at a conversation's start (yours and the project's each); "
115
+ "what is over it is cut and the model is told how to read the rest (0: yours and the "
116
+ "project's are not read)"),
117
+ "exclude": ("", "text", (0, 2000), "files never read, as path patterns (comma-separated, e.g. "
118
+ "*/vendor/*/AGENTS.md)"),
119
+ },
102
120
  "limits": {
103
121
  "max_steps": (60, "int", (1, 1000), "model calls a task may take"),
104
122
  "max_minutes": (360, "int", (1, 1440), "minutes a conversation may run"),
@@ -331,8 +349,12 @@ def read(directory) -> dict:
331
349
  try:
332
350
  with file.open("rb") as handle:
333
351
  data = tomllib.load(handle)
334
- except (OSError, tomllib.TOMLDecodeError):
352
+ except FileNotFoundError:
335
353
  return {}
354
+ except UnicodeError:
355
+ raise ValueError(f"{file}: invalid UTF-8; correct the configuration before saving changes") from None
356
+ except (OSError, tomllib.TOMLDecodeError) as error:
357
+ raise ValueError(f"{file}: {error}; correct the configuration before saving changes") from None
336
358
  return data
337
359
 
338
360
 
@@ -40,6 +40,9 @@ COMMANDS = {
40
40
  "settings": Command(note="change the settings"),
41
41
  "packages": Command(note="the installed packages and the registry's: install, update, turn off, remove"),
42
42
  "library": Command(note="what the agent remembers: this conversation's memory and each library's entries"),
43
+ "instructions": Command(words="[N]", note="the instruction files (AGENTS.md) this conversation read; N: open "
44
+ "that one in your editor"),
45
+ "init": Command(note="have the agent write the project's AGENTS.md, or suggest improvements to the one there"),
43
46
  "learn": Command(words="[minutes] [for what]", note="a new conversation that learns this environment instead of "
44
47
  "doing a task (default: the settings' minutes); during it, where "
45
48
  "it stands"),
@@ -184,6 +184,18 @@ def items(record: dict, names: dict, timeline: bool = False) -> list[dict]:
184
184
  f"({how}): {get('why')}", environment=get("kind"), why=get("why"))]
185
185
  if kind == "environment_refused":
186
186
  return [_item("environment", "note", f"did not take {get('kind')}: {get('reason')}", environment=get("kind"))]
187
+ if kind == "instructions":
188
+ # The instruction files read (instructions.py): at the start, for a folder that joined,
189
+ # or below the folder when a program touched it; and what was cut or left out.
190
+ files, out = get("files") or [], []
191
+ if files:
192
+ size = sum(item.get("bytes") or 0 for item in files)
193
+ out.append(_item("instructions", "note", ("instructions below the folder: " if get("nested") else
194
+ "instructions: ")
195
+ + ", ".join(item["label"] + (" (cut)" if item.get("cut") else "") for item in files)
196
+ + f" ({size / 1024:.1f} KB)", files=[item["path"] for item in files]))
197
+ out += [_item("instructions", "note", warning, warning=True) for warning in get("warnings") or ()]
198
+ return out
187
199
  if kind == "agents_enabled":
188
200
  return [_item("environment", "note", "sub-agents are on for this conversation" if get("enabled")
189
201
  else "sub-agents stay off")]