@lmmslab/harness 0.85.1 → 0.86.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/package.json +1 -1
  2. package/python/harness/__init__.py +2 -2
  3. package/python/harness/bench.py +2 -2
  4. package/python/harness/builtin/benches/README.md +1 -2
  5. package/python/harness/builtin/configs/default.toml +4 -19
  6. package/python/harness/builtin/configs/deploy/example-api.toml +1 -1
  7. package/python/harness/builtin/configs/models/deepseek-flash.toml +1 -1
  8. package/python/harness/builtin/configs/models/grok-low.toml +1 -1
  9. package/python/harness/builtin/configs/models/grok-medium.toml +3 -6
  10. package/python/harness/builtin/environment/README.md +8 -25
  11. package/python/harness/builtin/prompts/conversation/core.md +6 -5
  12. package/python/harness/builtin/prompts/core/core.md +147 -203
  13. package/python/harness/builtin/prompts/core/pack.toml +0 -1
  14. package/python/harness/builtin/prompts/reflect/core.md +8 -32
  15. package/python/harness/builtin/prompts/reflect/pack.toml +2 -4
  16. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -3
  17. package/python/harness/builtin/prompts/shared/agents.md +20 -10
  18. package/python/harness/builtin/prompts/shared/checklist.md +13 -17
  19. package/python/harness/builtin/prompts/shared/environments.md +20 -15
  20. package/python/harness/builtin/prompts/shared/learning-goal.md +2 -3
  21. package/python/harness/builtin/prompts/shared/learning.md +73 -23
  22. package/python/harness/builtin/prompts/shared/mcp.md +11 -6
  23. package/python/harness/builtin/prompts/shared/reflex-method.md +243 -0
  24. package/python/harness/builtin/prompts/shared/units.md +138 -0
  25. package/python/harness/builtin/prompts/shared/web.md +5 -6
  26. package/python/harness/builtin/skills/agents/__init__.py +18 -3
  27. package/python/harness/builtin/skills/agents/skill.toml +3 -3
  28. package/python/harness/builtin/skills/checklist/__init__.py +34 -32
  29. package/python/harness/builtin/skills/checklist/skill.toml +9 -9
  30. package/python/harness/builtin/skills/environments/__init__.py +9 -5
  31. package/python/harness/builtin/skills/environments/skill.toml +1 -1
  32. package/python/harness/builtin/skills/experience/skill.toml +1 -1
  33. package/python/harness/builtin/skills/learning/__init__.py +19 -5
  34. package/python/harness/builtin/skills/mcp/skill.toml +1 -1
  35. package/python/harness/builtin/skills/memory/__init__.py +4 -1
  36. package/python/harness/builtin/skills/memory/skill.toml +0 -5
  37. package/python/harness/builtin/skills/verify/skill.toml +1 -0
  38. package/python/harness/builtin/skills/web/__init__.py +4 -1
  39. package/python/harness/builtin/third_party/sources.toml +2 -40
  40. package/python/harness/cli.py +16 -25
  41. package/python/harness/config/__init__.py +2 -2
  42. package/python/harness/config/agent.py +59 -47
  43. package/python/harness/core/__init__.py +1 -1
  44. package/python/harness/core/codec.py +4 -4
  45. package/python/harness/core/contracts.py +1 -1
  46. package/python/harness/core/media.py +1 -1
  47. package/python/harness/core/ports.py +2 -2
  48. package/python/harness/core/procs.py +1 -1
  49. package/python/harness/core/remote.py +1 -1
  50. package/python/harness/core/worker.py +19 -13
  51. package/python/harness/embodiments.py +53 -44
  52. package/python/harness/extensions.py +22 -0
  53. package/python/harness/host/__init__.py +1 -1
  54. package/python/harness/host/http.py +6 -12
  55. package/python/harness/host/sessions.py +1 -1
  56. package/python/harness/host/tasks.py +15 -11
  57. package/python/harness/host/workspaces.py +36 -8
  58. package/python/harness/packages/__init__.py +5 -5
  59. package/python/harness/packages/environments.py +30 -18
  60. package/python/harness/packages/manager.py +1 -1
  61. package/python/harness/packages/manifest.py +6 -6
  62. package/python/harness/packages/provision.py +1 -1
  63. package/python/harness/packages/sources.py +1 -1
  64. package/python/harness/paths.py +1 -1
  65. package/python/harness/runtime/decision/loop.py +95 -5
  66. package/python/harness/runtime/decision/messages.py +128 -2
  67. package/python/harness/runtime/decision/model.py +4 -5
  68. package/python/harness/runtime/decision/prompts.py +20 -32
  69. package/python/harness/runtime/events.py +7 -5
  70. package/python/harness/runtime/execution/attached.py +3 -3
  71. package/python/harness/runtime/execution/entries.py +189 -8
  72. package/python/harness/runtime/execution/kernel.py +26 -1
  73. package/python/harness/runtime/execution/results.py +2 -3
  74. package/python/harness/runtime/execution/session.py +417 -32
  75. package/python/harness/runtime/execution/skills.py +63 -16
  76. package/python/harness/runtime/learning/active.py +7 -7
  77. package/python/harness/runtime/learning/learner.py +3 -2
  78. package/python/harness/runtime/learning/library.py +9 -4
  79. package/python/harness/runtime/learning/reflect.py +10 -9
  80. package/python/harness/runtime/reactive/rules.py +4 -4
  81. package/python/harness/runtime/reactive/tree.py +506 -25
  82. package/python/harness/runtime/safety/input.py +1 -1
  83. package/python/harness/runtime/safety/isolation.py +3 -3
  84. package/python/harness/runtime/safety/shield.py +4 -50
  85. package/python/harness/runtime/task/delegation.py +5 -5
  86. package/python/harness/runtime/task/environments.py +10 -0
  87. package/python/harness/runtime/task/run.py +222 -27
  88. package/python/harness/runtime/tick.py +24 -1
  89. package/python/harness/sdk/__init__.py +2 -5
  90. package/python/harness/services/registry.py +23 -19
  91. package/python/harness/settings.py +9 -9
  92. package/python/harness/builtin/environment/constraints.txt +0 -31
  93. package/python/harness/builtin/prompts/shared/world.md +0 -1
@@ -9,7 +9,7 @@ or rejects it. An execution ends with an event; one that is not nominal goes to
9
9
  that answer it (on()), and one nobody answers ends the unit and reaches the model. What a
10
10
  unit gathers for the model (pictures, events, views) is its own: its box.
11
11
 
12
- An embodiment (a robot, a computer, a game) is a worker that serves the worker protocol
12
+ An embodiment is a worker that serves the worker protocol
13
13
  (core/worker.py WORKER_METHODS) behind a shield (runtime/safety/shield.py CommandShield), and a
14
14
  session that subclasses EpisodeCore and says what a step's command is and how it reaches the
15
15
  worker (_tick), the command that leaves everything as it is (_base_command), what reactive
@@ -24,12 +24,14 @@ Bootstrap: harness.runtime.execution.kernel --bootstrap harness.runtime.executio
24
24
  Options: {"endpoint", "episode_id", "embodiment", "skills", "reactive_budget_ms", "reaction_delay_ms", "observer",
25
25
  "default_max_seconds", "vlm", "pointer", "verifier", "segmenter", "vision", "mcp",
26
26
  "memory", "library", "agent_skills", "policies", "world_models"}, and an embodiment's
27
- own (a robot's: "strategy_first", "policy_progress_seconds", harness_robot/session.py)
27
+ own (its package's session class)
28
28
  """
29
29
 
30
+ from contextlib import contextmanager
30
31
  import importlib
31
32
  import json
32
33
  import math
34
+ from pathlib import Path
33
35
  import threading
34
36
  import time
35
37
 
@@ -42,7 +44,7 @@ from harness.runtime import events as ev
42
44
  from harness.runtime.decision.model import USAGE
43
45
  from harness.runtime.execution.entries import ClosedLoop, Tree
44
46
  from harness.runtime.reactive.rules import HOLD, STOP, ReactiveFault, call_reactive
45
- from harness.runtime.reactive.tree import Reflexes, fault_event
47
+ from harness.runtime.reactive.tree import Reflexes, _staging, fault_event
46
48
  from harness.runtime.tick import Preempted, Tick, delay_ticks, driving
47
49
 
48
50
 
@@ -52,6 +54,64 @@ SESSIONS = {name: kind.session for name, kind in KINDS.items()}
52
54
  STATE_NOTE_SECONDS = 1.0
53
55
 
54
56
 
57
+ # The page on how a tree of reflexes is designed and tried (Session.reflex_method), and what
58
+ # set_reflex says when it is called before that page was read, or without the node's trial.
59
+ METHOD_PAGE = Path(__file__).resolve().parents[2] / "builtin" / "prompts" / "shared" / "reflex-method.md"
60
+ # The pages of instructions a program reads on demand (Session.guide): the core prompt keeps
61
+ # what every reply needs and names these for the rest, as Claude Code keeps a skill's text
62
+ # out of its prompt until the skill is used. An enabled skill brings its own pages
63
+ # (skill.toml: guides), and may name the calls of its own that wait for one.
64
+ GUIDES = {"tree": METHOD_PAGE, "units": METHOD_PAGE.with_name("units.md")}
65
+ GUIDE_FIRST = ("Nothing ran: read how {call} is used first. {given} Read it, then call {call} in a later program.")
66
+ # What a refusal for an unread page says of the page: it is given with the refusal (as
67
+ # guide(name) would give it), or it has to be asked for.
68
+ PAGE_COMES = "The page guide(\"{name}\") is given to you with your next message."
69
+ PAGE_ASK = "Call guide(\"{name}\"): the page is given to you with your next message."
70
+ # A page is read when the host has put all of it before the model, as Claude Code counts a
71
+ # file as read when its Read tool returned it: guide(name) asks for the page and returns one
72
+ # of these lines, the host gives the page with the next message (runtime/task/run.py), and a
73
+ # call that waits for the page is refused until then. One message carries pages up to
74
+ # PAGES_CHARS, the size Claude Code lets one read have (25,000 tokens); what is asked beyond
75
+ # that is not given and not read.
76
+ PAGES_CHARS = 100_000
77
+ PAGE_GIVEN = "guide(\"{name}\"): the page is given to you with your next message ({size} characters)."
78
+ PAGE_NOT_GIVEN = ("guide(\"{name}\") was not given: the pages this program asked for before it fill what one "
79
+ "message carries ({room} characters; this page has {size}). It is not read. Ask for it in a "
80
+ "later program.")
81
+ ACTION_NEEDED = ("Nothing was set: every node does something. do= is the node's program, a function that "
82
+ "answers its situation; a node above others has one too, for what none of them answers.")
83
+ CONDITION_FAILS = ("Nothing was set: the node's condition cannot be judged on the state as it is now. It raised "
84
+ "{reason}. A condition returns whether the agent is in the situation on every state it can "
85
+ "be given.")
86
+ METHOD_FIRST = ("Nothing was set: read how a tree of reflexes is designed and set first. {given} Read it, then "
87
+ "set the tree in a later program.")
88
+ # The list of what can happen to the agent (situations(...)), and what is said where it is
89
+ # missing or a line of it has nothing that answers it.
90
+ SITUATIONS_FIRST = ("Nothing was set: say first what can happen to the agent during the whole task. Call "
91
+ "situations(...) with one line for each thing that can happen to it; then set the nodes, "
92
+ "each with covers=[...]: the lines it answers.")
93
+ NO_SITUATIONS = ("{what} did not run: you have not said what can happen to the agent during the whole task. Call "
94
+ "situations(...) with one line for each thing that can happen to it, and set the nodes that "
95
+ "answer them (set_reflex(..., covers=[...])), before a program acts.")
96
+ # The list was made while the part of the state the environment calls the agent's situation
97
+ # (its profile: "situation") had other values: the agent is somewhere the list was not
98
+ # made for.
99
+ LIST_BEFORE = ("{what} did not run: the state's {key} is now {now}, and situations() was listed before that. Think "
100
+ "this through first: what has to be done here, the hardest form of it, how it can fail, and what "
101
+ "can happen to the agent here faster than you can reply. Then call situations(...) with the lines "
102
+ "for here added, and set the nodes that answer them.")
103
+ UNANSWERED = ("{what} did not run: nothing answers these lines of situations() yet: {lines}. Set a node for each "
104
+ "(set_reflex(..., covers=[...])), or give the line with the reason it needs no node: (line, reason).")
105
+ SAYS_NEEDED = ("Nothing was set: a node that tells you anything says what you read then. about= is one "
106
+ "sentence: the situation this node answers. report= is the message you read when you are told of "
107
+ "this node, written for this node's situation: what you will need then to judge whether the "
108
+ "situation is over and to decide what to do next; a function, called as report(view, returned). "
109
+ "Only a node with tell=\"never\" and tell_failed=\"never\" goes without them.")
110
+ TRIAL_IS_A_FUNCTION = "test= is a function that brings the node's situation about; it is run at once"
111
+ # How long a trial waits for the node to have its turn after its function returned.
112
+ TRIAL_SECONDS = 10.0
113
+
114
+
55
115
  class EpisodeCore:
56
116
  """The session skeleton every embodiment and skill builds on: the worker connection and
57
117
  profile, the state, the model clients, the reactive layer (rules, facts, answers to
@@ -83,6 +143,27 @@ class EpisodeCore:
83
143
  self.hz = float(self.profile.get("control_hz", 1))
84
144
  self.default_max_seconds = float(options.get("default_max_seconds", 30.0))
85
145
  self.reactive = Reflexes(float(options.get("reactive_budget_ms", 5.0)) / 1000.0, self.guard_actions)
146
+ # Whether a node is set with its trial, after the page on how a tree is made was read
147
+ # (runtime.reflex_method; see set_reflex).
148
+ self._method_required = options.get("reflex_method", "required") == "required"
149
+ # Whether a program checks what it relies on before it acts (runtime.purpose).
150
+ self._expect_required = options.get("purpose", "optional") == "required"
151
+ self._method_read = False
152
+ # What can happen to the agent during the whole task, as the model listed it
153
+ # (situations): {"text", "why": the reason it needs no node, or None} each; None
154
+ # until it was listed. And the lines each node answers (set_reflex covers=).
155
+ self._situations = None
156
+ self._covers = {}
157
+ # The values the environment's situation (its profile: "situation") had when the list
158
+ # was given: where it has another, the list is from before (LIST_BEFORE).
159
+ self._listed_in = set()
160
+ # The expectations of the last program whose expectations all held and whose result
161
+ # was not there: the next program that acts adds one (entries.py acts).
162
+ self._owed_expects = None
163
+ # The pages there are (the core's and the enabled skills'), and the ones read so far.
164
+ self._guides = dict(GUIDES)
165
+ self._guides_read = set()
166
+ self.reactive.tell_first = self._method_required
86
167
  # A rule on time is judged at the environment's rate unless it names a period,
87
168
  # never faster than the environment can be driven (runtime/tick.py driving).
88
169
  bound = driving(self.profile)[0]
@@ -98,7 +179,7 @@ class EpisodeCore:
98
179
  self.mcp_servers = dict(options.get("mcp") or {})
99
180
  # Agent Skills the user installed in the app: {name: {"description", "path"}}.
100
181
  self.agent_skills = dict(options.get("agent_skills") or {})
101
- # Learned model services belong to the episode, not to a robot session.
182
+ # Learned model services belong to the episode, not to one kind's session.
102
183
  self.policies = dict(options.get("policies") or {})
103
184
  self._policy_clients = {}
104
185
  self.world_models = dict(options.get("world_models") or {})
@@ -118,12 +199,12 @@ class EpisodeCore:
118
199
  # Success verifier (App. E, Tab. 5): a separate model a program may ask.
119
200
  self.verifier = image_role(options.get("verifier"), "verifier")
120
201
  self.vision = image_role(options.get("vlm"), "vlm")
121
- # Open-vocabulary pointing (Molmo2 in the paper); without it point_to uses the vlm.
202
+ # Open-vocabulary pointing; without it point_to uses the vlm.
122
203
  self.pointer = image_role(options.get("pointer"), "pointer")
123
204
  self.segmenter = None
124
205
  if options.get("segmenter"):
125
206
  self.segmenter = service_client(options["segmenter"])
126
- # Generic perception for a game learned from its pictures (skills/vision).
207
+ # Generic perception for an environment learned from its pictures (skills/vision).
127
208
  self.vision_service = None
128
209
  if options.get("vision"):
129
210
  self.vision_service = service_client(options["vision"])
@@ -139,10 +220,12 @@ class EpisodeCore:
139
220
 
140
221
  self.skills = list(options["skills"])
141
222
  self.namespace = {
142
- "__name__": "__program__", **namespace(self, self.skills),
223
+ "__name__": "__program__", **self._with_guides(self.skills, namespace(self, self.skills)),
143
224
  # The reactive layer: one tree, one call that puts a node into it (runtime/reactive/tree.py).
144
225
  "set_reflex": self.set_reflex, "drop_reflex": self.reactive.drop, "reflexes": self.reactive.listing,
226
+ "reflex_method": self.reflex_method, "guide": self.guide,
145
227
  "facts": self.facts, "at_priority": self.at_priority, "until": self._entries.until,
228
+ "expect": self._entries.expect, "after": self._entries.after, "situations": self.situations,
146
229
  "run_controller": self.run_controller,
147
230
  # The host switches skills on between programs (sub-agents the user turned on).
148
231
  "__load_skills__": self.load_skills,
@@ -178,7 +261,14 @@ class EpisodeCore:
178
261
  now = time.monotonic()
179
262
  if value and now - self.__dict__.get("_state_noted", 0.0) >= STATE_NOTE_SECONDS:
180
263
  self.__dict__["_state_noted"] = now
181
- spans.note("state", state=value)
264
+ # With it, what the units that run say of themselves now (until(report=)).
265
+ entries = self.__dict__.get("_entry_tree")
266
+ says = {}
267
+ for entry in (entries.running() if entries is not None else ()):
268
+ text = entries.says(entry) if entry.report is not None else None
269
+ if text is not None:
270
+ says[entry.id] = text
271
+ spans.note("state", state=value, **({"says": says} if says else {}))
182
272
  self._facts_changed()
183
273
 
184
274
  def _facts_changed(self):
@@ -302,6 +392,22 @@ class EpisodeCore:
302
392
  def _looks(self, value):
303
393
  self._box().looks = value
304
394
 
395
+ @property
396
+ def _pages(self):
397
+ return self._box().pages
398
+
399
+ @_pages.setter
400
+ def _pages(self, value):
401
+ self._box().pages = value
402
+
403
+ def _pages_given(self, pages):
404
+ """The pages of a unit's result are before the model with that result: read."""
405
+ for page in pages:
406
+ if page["name"] == "tree":
407
+ self._method_read = True
408
+ self._guides_read.add(page["name"])
409
+ return pages
410
+
305
411
  def _evidence(self) -> str:
306
412
  """What this environment reports as text about where it stands, as evidence for a
307
413
  claim beside its state and views (a window's elements, a page's text). An
@@ -345,16 +451,45 @@ class EpisodeCore:
345
451
  raise ValueError(f"no view {unknown or names}; this environment has {', '.join(known)}")
346
452
  return names
347
453
 
348
- def look(self, camera=None, region=None, keep=None, pin=None):
454
+ @contextmanager
455
+ def reporting(self, pictures=True):
456
+ """While a report function runs (a node's report=, a program's until(report=)): a
457
+ look() gives its pictures to the report alone, and changes neither the state nor
458
+ what the next program is shown; without `pictures` it sees nothing and asks the
459
+ environment nothing."""
460
+ before = self.__dict__.get("_report_mode")
461
+ self.__dict__["_report_mode"] = "pictures" if pictures else "text"
462
+ try:
463
+ yield
464
+ finally:
465
+ self.__dict__["_report_mode"] = before
466
+
467
+ def look(self, camera=None, region=None, keep=None, pin=None, **options):
349
468
  """Put a view of the environment in your next turn, with this program's result:
350
469
  all its views, one by name, or the part region=(x, y, width, height) of it in the
351
470
  view's pixels. Nothing is shown unless a program looks. A view stays for your next
352
471
  reply only; keep=N keeps the views of the last N programs in sight, pin="name"
353
- keeps this one until unpin("name"). Returns what it saw (.state, and an image
354
- show() takes)."""
472
+ keeps this one until unpin("name"). Any other setting is the environment's: it is
473
+ passed on as given, and the environment says which its views take. Returns what
474
+ it saw (.state, and an image show() takes); in a report function, what it saw is
475
+ part of that report and nothing else."""
476
+ mode = self.__dict__.get("_report_mode")
477
+ if mode == "text":
478
+ return Looked(self.state, {})
355
479
  names = self._camera_names(camera)
356
- data = self.env.call("observe", episode_id=self.episode_id, cameras=names)
480
+ try:
481
+ data = self.env.call("observe", episode_id=self.episode_id, cameras=names, **options)
482
+ except Exception as error:
483
+ if options:
484
+ raise ValueError(f"look({', '.join(f'{key}=' for key in options)}): the environment did not take "
485
+ f"these settings for its views ({type(error).__name__}: {error})") from None
486
+ raise
357
487
  images = data.get("images") or {}
488
+ if mode == "pictures":
489
+ if region is not None:
490
+ region = [int(value) for value in region]
491
+ return Looked(self.state, {name: images[name] if region is None else _cropped(images[name], region, self.show_format)
492
+ for name in names if name in images})
358
493
  if isinstance(data.get("state"), dict):
359
494
  self.state = data["state"]
360
495
  if region is not None:
@@ -368,9 +503,9 @@ class EpisodeCore:
368
503
  url = images[name] if region is None else _cropped(images[name], region, self.show_format)
369
504
  seen[name] = url
370
505
  self._looks = [item for item in self._looks
371
- if (item["camera"], item.get("region"), item.get("pin")) != (name, region, pin)]
506
+ if (item["camera"], item.get("region"), item.get("pin"), item.get("options")) != (name, region, pin, options or None)]
372
507
  self._looks.append({"camera": name, "image_url": url, **({"region": region} if region else {}),
373
- **({"pin": str(pin)} if pin else {})})
508
+ **({"pin": str(pin)} if pin else {}), **({"options": options} if options else {})})
374
509
  if keep is not None:
375
510
  self.keep_views(keep)
376
511
  return Looked(self.state, seen)
@@ -382,7 +517,7 @@ class EpisodeCore:
382
517
 
383
518
  def watch_views(self, cameras=None, keep=None):
384
519
  """From now on the views (all, or those named) come with every program's result,
385
- until unwatch(). For work that is seen, not read: a game, a moving scene."""
520
+ until unwatch(). For work that is seen, not read: a moving scene."""
386
521
  names = self._camera_names(cameras)
387
522
  if keep is not None:
388
523
  self.keep_views(keep)
@@ -409,9 +544,10 @@ class EpisodeCore:
409
544
  # What the model's own rules and handlers gathered outside every unit comes
410
545
  # with the next program's result.
411
546
  box.attachments[:0], box.events[:0], box.looks[:0] = own.attachments, own.events, own.looks
547
+ box.pages[:0] = own.pages
412
548
  for kind, count in own.event_counts.items():
413
549
  box.event_counts[kind] = box.event_counts.get(kind, 0) + count
414
- own.attachments, own.events, own.looks, own.event_counts = [], [], [], {}
550
+ own.attachments, own.events, own.looks, own.pages, own.event_counts = [], [], [], [], {}
415
551
  watch = self._views["watch"]
416
552
  if watch is not None and not self.state.get("ended"):
417
553
  # A standing watch: the views the program did not look at itself.
@@ -433,6 +569,8 @@ class EpisodeCore:
433
569
  self._attachments, self._events = [], []
434
570
  if self._looks:
435
571
  data["looks"], self._looks = self._looks, []
572
+ if self._pages:
573
+ data["pages"], self._pages = self._pages_given(self._pages), []
436
574
  for name, other in list(self._attached.items()):
437
575
  # An attached environment's part of the cell: its state and executions under
438
576
  # its name, its pictures with the conversation's own.
@@ -490,7 +628,7 @@ class EpisodeCore:
490
628
  new = [name for name in names if name not in self.skills]
491
629
  if not new:
492
630
  return []
493
- added = namespace(self, new)
631
+ added = self._with_guides(new, namespace(self, new))
494
632
  self.skills = [*self.skills, *new]
495
633
  self.namespace.update(added)
496
634
  self._api_changes.update(added)
@@ -553,7 +691,10 @@ class EpisodeCore:
553
691
 
554
692
  def _execute(self, skill, parameters, *args, **kwargs):
555
693
  """One bounded execution (_bounded), recorded as a span of the skill lane with the
556
- event it ended with (core/spans.py)."""
694
+ event it ended with (core/spans.py). A program that has checked nothing it relies on
695
+ does not act (entries.py acts)."""
696
+ if not kwargs.pop("reads", False):
697
+ self._entries.acts(skill)
557
698
  with spans.span("skill", skill, parameters=parameters, tick=self.state.get("step")) as end:
558
699
  try:
559
700
  trace = self._bounded(skill, parameters, *args, **kwargs)
@@ -588,8 +729,7 @@ class EpisodeCore:
588
729
 
589
730
  def _refuses(self, skill):
590
731
  """Why the run does not let the execution `skill` act now ({"reason", "hint"}), or
591
- None (Execution.confirm). The skeleton refuses nothing; an embodiment may (a robot's
592
- learned policy)."""
732
+ None (Execution.confirm). The skeleton refuses nothing; an embodiment may."""
593
733
  return None
594
734
 
595
735
  def _steps(self, skill, parameters, command_fn, max_seconds, region, until, timeout_is_nominal, cameras_at):
@@ -597,8 +737,8 @@ class EpisodeCore:
597
737
  observes, runs the guards and the termination conditions, and yields the command
598
738
  to send with the cameras whose images the reply should carry; it receives the
599
739
  worker's reply to the step the tick sent, and returns the execution's trace."""
600
- # Its time is the environment's steps where each step is a fixed time of it (a
601
- # simulation), else the wall's (runtime/tick.py driving).
740
+ # Its time is the environment's steps where each step is a fixed time of it,
741
+ # else the wall's (runtime/tick.py driving).
602
742
  step_seconds = self._ticker.step_seconds
603
743
  max_ticks = max(1, math.ceil(max_seconds / step_seconds)) if step_seconds else None
604
744
  over = ev.COMPLETED if timeout_is_nominal else ev.TIMEOUT
@@ -748,9 +888,119 @@ class EpisodeCore:
748
888
  step = self.state["step"]
749
889
  return ExecutionTrace(skill, parameters, step, step, Event(ev.SKILL_ERROR, skill, {"reason": reason}, step))
750
890
 
751
- def set_reflex(self, name, when, do=None, *, under=None, priority=0, every=None, again_seconds=0.0):
891
+ def _with_guides(self, names, exports: dict) -> dict:
892
+ """`exports` of the skills `names`, with their pages added to the session's and each
893
+ call that waits for a page refused until the page was read (skill.toml: guides)."""
894
+ from harness.runtime.execution.skills import guides
895
+
896
+ for page, (file, before) in guides(names).items():
897
+ if page in self._guides:
898
+ raise ValueError(f"guide {page!r} is declared twice")
899
+ self._guides[page] = file
900
+ for call in before:
901
+ exports[call] = self._after_guide(call, page, exports[call])
902
+ return exports
903
+
904
+ def _page_comes(self, name) -> str:
905
+ """Ask for the page `name` for a call that was refused because it was not read, and
906
+ say whether it comes with the refusal."""
907
+ try:
908
+ given = self.guide(name).startswith(PAGE_GIVEN.format(name=name, size=0).split("(")[0])
909
+ except Exception:
910
+ given = False
911
+ return (PAGE_COMES if given else PAGE_ASK).format(name=name)
912
+
913
+ def _after_guide(self, call, page, function):
914
+ def gated(*args, **kwargs):
915
+ if page not in self._guides_read:
916
+ raise ValueError(GUIDE_FIRST.format(call=call, given=self._page_comes(page)))
917
+ return function(*args, **kwargs)
918
+
919
+ gated.__name__, gated.__doc__ = getattr(function, "__name__", call), getattr(function, "__doc__", None)
920
+ return gated
921
+
922
+ def guide(self, name) -> str:
923
+ """Ask for a page of instructions: "tree" (how a tree of reflexes is designed and
924
+ set, and every setting of a node), "units" (how units run and share the
925
+ environment), and the pages the enabled skills bring. The page is not returned: it
926
+ is given to you, whole, with your next message, and it is read from then on. What
927
+ the call returns is one line that says so. One message carries pages up to
928
+ 100,000 characters; a page asked for beyond that is not given (the line says so)
929
+ and is asked for again in a later program. The host gives a page that was read
930
+ again after a summary of the conversation. A call that waits for a page is refused
931
+ until the page was read: set_reflex waits for "tree", and a skill names the calls
932
+ of its own that wait for one of its pages."""
933
+ if name not in self._guides:
934
+ raise ValueError(f"guide(name): name is one of {sorted(self._guides)}, got {name!r}")
935
+ size = len(self._guides[name].read_text(encoding="utf-8"))
936
+ asked = self._pages
937
+ if any(page["name"] == name for page in asked):
938
+ return PAGE_GIVEN.format(name=name, size=size)
939
+ if asked and sum(page["size"] for page in asked) + size > PAGES_CHARS:
940
+ spans.note("guide", name=name, given=False)
941
+ return PAGE_NOT_GIVEN.format(name=name, room=PAGES_CHARS, size=size)
942
+ asked.append({"name": name, "file": str(self._guides[name]), "size": size})
943
+ spans.note("guide", name=name, given=True)
944
+ return PAGE_GIVEN.format(name=name, size=size)
945
+
946
+ def reflex_method(self) -> str:
947
+ """guide("tree"), under its earlier name."""
948
+ return self.guide("tree")
949
+
950
+ def _try_reflex(self, node, test) -> dict:
951
+ """Run the trial of a node that is in the tree: `test` brings its situation about,
952
+ and the node is watched: whether it had its turn, how long that took from the
953
+ trial's start, and for a node with a program whether that left the situation over
954
+ (its condition, which says when the situation is there, no longer held)."""
955
+ began, did, did_not, started, error = node.triggered, node.did, node.did_not, time.monotonic(), None
956
+ ticker = self.__dict__.get("_tick_loop")
957
+
958
+ def look():
959
+ # (The environment is read so that the tree is judged on what the trial did.)
960
+ try:
961
+ self._observe()
962
+ if ticker is not None:
963
+ ticker.judge()
964
+ except Exception:
965
+ pass
966
+ time.sleep(0.1)
967
+
968
+ node.trying = True
969
+ try:
970
+ try:
971
+ test()
972
+ except Exception as raised:
973
+ # (What the trial did may have been ended by the node itself: that is its turn.)
974
+ error = f"{type(raised).__name__}: {raised}"[:300]
975
+ deadline = time.monotonic() + TRIAL_SECONDS
976
+ while node.triggered == began and time.monotonic() < deadline:
977
+ look()
978
+ turn = node.triggered > began
979
+ seconds = round(time.monotonic() - started, 2)
980
+ done = None
981
+ if not turn and node.fault:
982
+ # (Why it had no turn: its condition could not be judged.)
983
+ error = node.fault[:300]
984
+ if turn and node.do is not None:
985
+ deadline = time.monotonic() + 3 * TRIAL_SECONDS
986
+ # (Its program has ended when the tree has counted it as done or not done.)
987
+ while node.did == did and node.did_not == did_not and time.monotonic() < deadline:
988
+ look()
989
+ done = node.did > did
990
+ finally:
991
+ node.trying = False
992
+ shown = {"tried": True, "turn": turn, **({"seconds": seconds} if turn else {}),
993
+ **({"done": done} if node.do is not None and turn else {}),
994
+ **({"error": error} if error and not turn else {})}
995
+ node.trial = shown
996
+ self.reactive._touched()
997
+ return {**shown, **({"last": node.last} if node.do is not None and turn and node.last is not None else {})}
998
+
999
+ def set_reflex(self, name, when, do=None, *, under=None, priority=0, every=None, again_seconds=0.0,
1000
+ ends=False, tell=None, tell_failed="now", about=None, report=None, test=None, covers=None):
752
1001
  """Put the node `name` into the tree of reflexes (runtime/reactive/tree.py), in place
753
- of a node of that name. `when`: a function of the view (the node has its turn while
1002
+ of a node of that name. `covers`: the lines of situations() this node answers, each by
1003
+ its text or its number. `when`: a function of the view (the node has its turn while
754
1004
  it holds: the situation it answers), or the name of an event (it answers that
755
1005
  event). `do`: a program (a function, started as a unit; its work is done when the
756
1006
  situation is over), the name of an event to raise, an action of the environment that
@@ -758,9 +1008,144 @@ class EpisodeCore:
758
1008
  it answer. `under`: the node it is a narrower situation of (any node whose `when` is
759
1009
  a condition, whatever that node does itself). `priority`: its own (the higher first,
760
1010
  0 or more; what a program's at_priority is compared with). `every`: the seconds
761
- between judgements of its condition (None: when the state or the facts change). `again_seconds`: before it may begin again. Its name."""
762
- return self.reactive.set(name, when, do, under=under, priority=priority, every=every,
763
- again_seconds=again_seconds)
1011
+ between judgements of its condition (None: when the state or the facts change). `again_seconds`: before it may begin again.
1012
+ `about`: one sentence, the situation the node answers; `report`: a function of the view
1013
+ and of what its program returned, which returns what the model reads when it is told of
1014
+ the node. A node that tells the model anything has both. Its name."""
1015
+ # (What a library entry sets when a session starts was tried when it was admitted.)
1016
+ staged = getattr(_staging, "layers", None) is not None
1017
+ if self._method_required and not staged:
1018
+ if not self._method_read:
1019
+ raise ValueError(METHOD_FIRST.format(given=self._page_comes("tree")))
1020
+ if self._situations is None:
1021
+ raise ValueError(self._hinted(SITUATIONS_FIRST))
1022
+ if do is None:
1023
+ raise ValueError(ACTION_NEEDED)
1024
+ if not (tell == "never" and tell_failed == "never") and (not about or report is None):
1025
+ raise ValueError(SAYS_NEEDED)
1026
+ self._condition_judges(name, when, under)
1027
+ if test is not None and not callable(test):
1028
+ raise TypeError(TRIAL_IS_A_FUNCTION)
1029
+ answers = self._lines(covers)
1030
+ found = self.reactive.set(name, when, do, under=under, priority=priority, every=every,
1031
+ again_seconds=again_seconds, ends=ends, tell=tell, tell_failed=tell_failed,
1032
+ about=about, report=report)
1033
+ if covers is not None:
1034
+ self._covers[name] = answers
1035
+ if staged or test is None:
1036
+ return found
1037
+ return {"name": name, **self._try_reflex(self.reactive.nodes[name], test)}
1038
+
1039
+ def _lines(self, covers) -> set:
1040
+ """The lines of situations() that `covers` names: each by its text, or by its number
1041
+ (1 for the first)."""
1042
+ if covers is None:
1043
+ return set()
1044
+ if isinstance(covers, (str, int)) and not isinstance(covers, bool):
1045
+ covers = [covers]
1046
+ # (A library entry that sets its nodes when a session starts: a line it names that the
1047
+ # list does not have is left out, not refused.)
1048
+ staged = getattr(_staging, "layers", None) is not None
1049
+ listed = [row["text"] for row in self._situations or []]
1050
+ found = set()
1051
+ for one in covers:
1052
+ if isinstance(one, int) and not isinstance(one, bool) and 1 <= one <= len(listed):
1053
+ found.add(listed[one - 1])
1054
+ elif isinstance(one, str) and " ".join(one.split()) in listed:
1055
+ found.add(" ".join(one.split()))
1056
+ elif staged:
1057
+ continue
1058
+ else:
1059
+ lines = "; ".join(f"{number}. {text}" for number, text in enumerate(listed, 1)) or "none"
1060
+ raise ValueError(f"covers={one!r} is no line of situations(): a line's text or its number. "
1061
+ f"The lines: {lines}")
1062
+ return found
1063
+
1064
+ def situations(self, *lines):
1065
+ """Say what can happen to the agent during the whole task: one line for each, a
1066
+ sentence, or (sentence, reason) for one that needs no node. It takes the place of
1067
+ the list given before. Without arguments nothing changes. Returns the list as it
1068
+ stands: {"lines": [{"line", "answered": the nodes whose covers= name it, or
1069
+ "no node: REASON"}], "unanswered": the lines nothing answers}. While a line is
1070
+ unanswered, a program that acts on the environment is refused."""
1071
+ if lines:
1072
+ if len(lines) == 1 and isinstance(lines[0], list):
1073
+ lines = tuple(lines[0])
1074
+ rows = []
1075
+ for one in lines:
1076
+ text, why = (one[0], one[1]) if isinstance(one, tuple) and len(one) == 2 else (one, None)
1077
+ if not isinstance(text, str) or not text.strip() or (why is not None and not str(why).strip()):
1078
+ raise TypeError("situations(...): each line is a sentence, or (sentence, reason) for one that "
1079
+ "needs no node")
1080
+ rows.append({"text": " ".join(text.split()), "why": None if why is None else " ".join(str(why).split())})
1081
+ self._situations = rows
1082
+ self._listed_in.add(self._situation_now()[1])
1083
+ spans.note("situations", lines=[row["text"] for row in rows], unanswered=self._unanswered())
1084
+ answered = self._answered_by()
1085
+ return {"lines": [{"line": row["text"], "answered": f"no node: {row['why']}" if row["why"] else
1086
+ sorted(answered.get(row["text"], ()))} for row in self._situations or []],
1087
+ "unanswered": self._unanswered()}
1088
+
1089
+ def _answered_by(self) -> dict:
1090
+ """For each line of situations(), the nodes now in the tree that answer it."""
1091
+ found = {}
1092
+ for name, lines in self._covers.items():
1093
+ if name in self.reactive.nodes:
1094
+ for line in lines:
1095
+ found.setdefault(line, set()).add(name)
1096
+ return found
1097
+
1098
+ def _unanswered(self) -> list:
1099
+ """The lines of situations() that no node answers and that give no reason."""
1100
+ answered = self._answered_by()
1101
+ return [row["text"] for row in self._situations or [] if not row["why"] and not answered.get(row["text"])]
1102
+
1103
+ def _situation_now(self):
1104
+ """(the key, its value as text) of what the environment calls the agent's situation
1105
+ in the state as it is; (None, None) where it names none or the state has none."""
1106
+ key = (self.profile or {}).get("situation")
1107
+ value = (self.state or {}).get(key) if key else None
1108
+ return (key, json.dumps(value, sort_keys=True, default=str)) if value is not None else (None, None)
1109
+
1110
+ def _hinted(self, text) -> str:
1111
+ """`text` with what the environment says about listing what can happen in it (its
1112
+ profile: "situations_hint"), where it says anything."""
1113
+ hint = str((self.profile or {}).get("situations_hint") or "").strip()
1114
+ return f"{text} {hint}" if hint else text
1115
+
1116
+ def _uncovered(self, what):
1117
+ """Why the call `what` does not act now for want of the tree, or None: the model has
1118
+ not listed what can happen to the agent, or a line of the list has nothing that
1119
+ answers it (where the run holds the tree to its method)."""
1120
+ if not self._method_required:
1121
+ return None
1122
+ if self._situations is None:
1123
+ return self._hinted(NO_SITUATIONS.format(what=what))
1124
+ key, now = self._situation_now()
1125
+ if key and now not in self._listed_in:
1126
+ return self._hinted(LIST_BEFORE.format(what=what, key=key, now=now))
1127
+ open_lines = self._unanswered()
1128
+ if open_lines:
1129
+ return UNANSWERED.format(what=what, lines="; ".join(f'"{line}"' for line in open_lines))
1130
+ return None
1131
+
1132
+ def _condition_judges(self, name, when, under) -> None:
1133
+ """Refuse a node whose condition raises on the state as it is now: a tree that cannot
1134
+ run is not set. A node under others is judged as the tree would judge it: only while
1135
+ the conditions above it hold."""
1136
+ if not callable(when) or self.reactive.view is None:
1137
+ return
1138
+ try:
1139
+ view = self.reactive.view()
1140
+ except Exception:
1141
+ return
1142
+ above = self.reactive.nodes.get(under) if under is not None else None
1143
+ if above is not None and not (self.reactive._above_hold(above, view) and self.reactive._run(above, view)):
1144
+ return
1145
+ try:
1146
+ call_reactive(name, when, view, budget_seconds=1.0)
1147
+ except ReactiveFault as fault:
1148
+ raise ValueError(CONDITION_FAILS.format(reason=fault.reason)) from None
764
1149
 
765
1150
  @property
766
1151
  def pauses(self) -> bool:
@@ -1062,11 +1447,11 @@ def service_client(config: dict):
1062
1447
  config["url"], timeout=float(config.get("timeout_seconds", 120.0)), on_demand=config.get("on_demand"))
1063
1448
 
1064
1449
 
1065
- def session_class(embodiment: str = "robot", knowledge: str | None = None):
1450
+ def session_class(embodiment: str = "none", knowledge: str | None = None):
1066
1451
  """The session of an embodiment kind with the mixin of every skill for that kind (the
1067
1452
  skills enabled for a run only decide the namespace; a skill's methods may use
1068
- another's); with knowledge "learned" (a game the agent learns itself), without the
1069
- skills written for a game by hand, whose modules are then never imported."""
1453
+ another's); with knowledge "learned" (an environment the agent learns itself), without the
1454
+ skills written for it by hand, whose modules are then never imported."""
1070
1455
  knowledge = knowledge or KINDS[embodiment].knowledge or "handwritten"
1071
1456
  key = (embodiment, knowledge)
1072
1457
  if key not in _SESSION_CLASSES:
@@ -1083,5 +1468,5 @@ def session_class(embodiment: str = "robot", knowledge: str | None = None):
1083
1468
 
1084
1469
 
1085
1470
  def create_session(options):
1086
- """Kernel bootstrap: the session of options["embodiment"] (default robot)."""
1087
- return session_class(options.get("embodiment", "robot"), options.get("knowledge"))(options)
1471
+ """Kernel bootstrap: the session of options["embodiment"] (default: none, no environment)."""
1472
+ return session_class(options.get("embodiment", "none"), options.get("knowledge"))(options)