@lmmslab/harness 0.0.0-stage → 0.81.1

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 (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1356 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +232 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. package/python/harness/tui/views.py +434 -0
@@ -0,0 +1,665 @@
1
+ """Concurrent entries and bounded ClosedLoop executions.
2
+
3
+ Entry events go through handlers from their source to the root. An unanswered event
4
+ reaches the running program at its next harness call, or at the end of the program.
5
+ """
6
+
7
+ import collections
8
+ import sys
9
+ import threading
10
+ import time
11
+ import uuid
12
+
13
+ from harness.core import spans
14
+ from harness.runtime.execution import control
15
+ from harness.runtime import events as ev
16
+ from harness.runtime.reactive import rules as reactive
17
+ from harness.runtime.events import EpisodeEnded, Escalation, Event, ExecutionTrace, ProgramFinished
18
+
19
+
20
+ def user_message(skill: str, parameters: dict | None = None) -> ExecutionTrace:
21
+ """The trace of what a message for the model stopped (runtime/execution/control.py)."""
22
+ return ExecutionTrace(skill, dict(parameters or {}), 0, 0, Event(ev.USER_MESSAGE, "user"))
23
+
24
+
25
+ # The root entry: the agent's own programs.
26
+ ROOT = "e0"
27
+ # How long a cancelled entry has to stop by itself before it is interrupted where it is.
28
+ GRACE = 0.5
29
+ # An entry's status.
30
+ STATUSES = ("running", "done", "failed", "cancelled")
31
+ # A sub-agent's report status that is a normal end (runtime/task/delegation.py state()).
32
+ AGENT_DONE = ("finished", "episode_ended")
33
+
34
+ _local = threading.local()
35
+
36
+
37
+ def current_entry():
38
+ """The entry executing on this thread, or None for the main program."""
39
+ return getattr(_local, "entry", None)
40
+
41
+
42
+ class Cancelled(BaseException):
43
+ """Raised in an entry's code when the entry was cancelled; a BaseException so that the
44
+ broad excepts of a program do not keep it running."""
45
+
46
+
47
+ def _short(value, limit=200) -> str:
48
+ text = value if isinstance(value, str) else repr(value)
49
+ return text if len(text) <= limit else text[:limit] + "..."
50
+
51
+
52
+ class Entry:
53
+ """One entry of a session's tree (see the module docstring): its `id`, `name`, `kind`
54
+ ("root", "program" for spawned code, "agent" for a sub-agent), the entry that started
55
+ it (`parent`), its `claims`, its `status` (running, done, failed, cancelled) and, once
56
+ ended, what its function returned (`result`) or why it failed (`error`)."""
57
+
58
+ def __init__(self, tree, identifier, name, kind, parent, claims=(), agent=None):
59
+ self.tree = tree
60
+ self.id = identifier
61
+ self.name = name
62
+ self.kind = kind
63
+ self.parent = parent
64
+ self.claims = tuple(claims)
65
+ self.agent = agent
66
+ self.children = []
67
+ self.status = "running"
68
+ self.result = None
69
+ self.error = None
70
+ # The Escalation of its failure: what wait() raises.
71
+ self.failure = None
72
+ self.started = time.time()
73
+ self.ended = None
74
+ self.thread = None
75
+ self._inbox = collections.deque()
76
+ self._cancel = threading.Event()
77
+ self._done = threading.Event()
78
+ self._waiters = 0
79
+ # The root only: what nobody handled, for the model (an Escalation, EpisodeEnded or
80
+ # ProgramFinished to raise in the program that runs).
81
+ self.pending = collections.deque()
82
+
83
+ def __repr__(self) -> str:
84
+ return f"<entry {self.id} {self.name!r} {self.kind} {self.status}>"
85
+
86
+ @property
87
+ def running(self) -> bool:
88
+ """Whether it has not ended yet."""
89
+ return self.status == "running"
90
+
91
+ def lineage(self) -> list:
92
+ """This entry and the entries above it, up to the root."""
93
+ chain, entry = [], self
94
+ while entry is not None:
95
+ chain.append(entry)
96
+ entry = entry.parent
97
+ return chain
98
+
99
+ def state(self) -> dict:
100
+ """The entry as a program and the model see it."""
101
+ data = {"entry": self.id, "name": self.name, "kind": self.kind,
102
+ "parent": self.parent.id if self.parent is not None else None, "status": self.status,
103
+ "seconds": round((self.ended or time.time()) - self.started, 1)}
104
+ if self.claims:
105
+ data["claims"] = list(self.claims)
106
+ if self.agent is not None:
107
+ data["agent"] = self.agent
108
+ if self.status == "done" and self.result is not None:
109
+ data["result"] = _short(self.result)
110
+ if self.error is not None:
111
+ data["error"] = self.error
112
+ return data
113
+
114
+ # What a program calls on the handle.
115
+
116
+ def wait(self, timeout=None):
117
+ """Wait until this entry has ended, at most `timeout` seconds (None: as long as it
118
+ takes). Returns what its
119
+ function returned (a sub-agent: its report); raises its failure (an Escalation
120
+ with an ENTRY_FAILED event), which this wait then handles; returns None when it
121
+ was cancelled or is still running at the timeout (`status` says which)."""
122
+ caller = self.tree.current()
123
+ if caller is self:
124
+ raise ValueError("an entry cannot wait for itself")
125
+ deadline = None if timeout is None else time.monotonic() + float(timeout)
126
+ with self.tree._changed:
127
+ self._waiters += 1
128
+ try:
129
+ while not self._done.is_set():
130
+ self.tree.check(caller)
131
+ left = None if deadline is None else deadline - time.monotonic()
132
+ if left is not None and left <= 0:
133
+ break
134
+ self.tree._changed.wait(left)
135
+ finally:
136
+ self._waiters -= 1
137
+ if self.status == "failed":
138
+ raise self.failure
139
+ return self.result if self.status == "done" else None
140
+
141
+ def send(self, message):
142
+ """Send this entry a message, which its code reads with receive() (a sub-agent: the
143
+ answer to its question, or more to do)."""
144
+ if not self.running:
145
+ raise ValueError(f"entry {self.id} ({self.name}) has ended ({self.status})")
146
+ if self.kind == "agent":
147
+ self.tree.session.send_agent(self.agent, message)
148
+ return
149
+ with self.tree._changed:
150
+ self._inbox.append(message)
151
+ self.tree._changed.notify_all()
152
+
153
+ def cancel(self, timeout=5.0):
154
+ """Stop this entry and the entries it started (theirs first): the execution it runs
155
+ ends at its next step, a wait or receive it is in raises, and code that does not
156
+ reach the harness is interrupted where it is after a moment. Returns its state."""
157
+ if self.kind == "root":
158
+ raise ValueError("the root entry is the agent's own program; finish() ends it")
159
+ for child in list(self.children):
160
+ if child.running:
161
+ child.cancel(timeout)
162
+ if not self.running:
163
+ return self.state()
164
+ self._cancel.set()
165
+ control.wake_waiters()
166
+ with self.tree._changed:
167
+ self.tree._changed.notify_all()
168
+ if self.kind == "agent":
169
+ try:
170
+ self.tree.session.cancel_agent(self.agent)
171
+ finally:
172
+ self.tree._end(self, "cancelled")
173
+ return self.state()
174
+ if self.thread is threading.current_thread():
175
+ raise Cancelled(f"entry {self.id} cancelled itself")
176
+ if not self._done.wait(min(GRACE, timeout)):
177
+ if self.thread is not None and self.thread.ident is not None:
178
+ reactive._raise_in(self.thread.ident, Cancelled)
179
+ self._done.wait(max(0.0, timeout - GRACE))
180
+ return self.state()
181
+
182
+ def receive(self, timeout=None):
183
+ """The oldest message sent to this entry, waiting at most `timeout` seconds for one
184
+ (None: as long as it takes); None when none came."""
185
+ deadline = None if timeout is None else time.monotonic() + float(timeout)
186
+ with self.tree._changed:
187
+ while not self._inbox:
188
+ self.tree.check(self)
189
+ left = None if deadline is None else deadline - time.monotonic()
190
+ if left is not None and left <= 0:
191
+ return None
192
+ self.tree._changed.wait(left)
193
+ return self._inbox.popleft()
194
+
195
+
196
+ class Tree:
197
+ """The entries of one kernel session (see the module docstring)."""
198
+
199
+ def __init__(self, session):
200
+ self.session = session
201
+ self._changed = threading.Condition(threading.RLock())
202
+ self._count = 0
203
+ self.root = Entry(self, ROOT, "main", "root", None)
204
+ self.entries = {ROOT: self.root}
205
+ self._ended = []
206
+ self._closed = False
207
+ control.on_agent_ended(self.agent_ended)
208
+
209
+ # Where code runs.
210
+
211
+ def current(self) -> Entry:
212
+ """The entry the calling code belongs to (the root outside every other)."""
213
+ entry = getattr(_local, "entry", None)
214
+ return entry if entry is not None and entry.tree is self else self.root
215
+
216
+ def acting(self, entry):
217
+ """Code inside belongs to `entry` (the tick steps an entry's execution, a handler
218
+ of an entry runs)."""
219
+ return _Acting(entry)
220
+
221
+ def get(self, identifier) -> Entry:
222
+ """The entry `identifier` (the root when there is none)."""
223
+ return self.entries.get(identifier) or self.root
224
+
225
+ def under(self, entry) -> list:
226
+ """`entry` and every entry below it (those it started, those they started, ...)."""
227
+ with self._changed:
228
+ return [each for each in self.entries.values() if entry in each.lineage()]
229
+
230
+ def check(self, entry=None) -> None:
231
+ """Raise in the code of `entry` (default: the caller's) what it must stop for: its
232
+ cancellation, or, for the root, an event that reaches the model."""
233
+ stop = self.interruption(entry or self.current())
234
+ if stop is not None:
235
+ raise stop
236
+
237
+ def interruption(self, entry, take=True):
238
+ """What `entry`'s code must stop for now (see check), or None; `take` False leaves
239
+ the root's event waiting. The root's code also stops for a message for the model
240
+ (runtime/execution/control.py), with a USER_MESSAGE event."""
241
+ for above in entry.lineage():
242
+ if above._cancel.is_set():
243
+ return Cancelled(f"entry {above.id} ({above.name}) was cancelled")
244
+ if entry is self.root and control.message_arrived():
245
+ return Escalation(user_message("program"))
246
+ if entry is self.root and self.root.pending:
247
+ with self._changed:
248
+ if self.root.pending:
249
+ return self.root.pending.popleft() if take else self.root.pending[0]
250
+ return None
251
+
252
+ # Starting entries.
253
+
254
+ def spawn(self, fn, name=None, claims=None) -> Entry:
255
+ """Run fn() as a new entry under the caller's (see the module docstring)."""
256
+ sys.audit("harness.execution")
257
+ if not callable(fn):
258
+ raise TypeError("spawn(fn, name, claims): fn must be callable")
259
+ parent = self.current()
260
+ self.check(parent)
261
+ claims = [claims] if isinstance(claims, str) else list(claims or [])
262
+ tick = self._channels()
263
+ if tick is not None:
264
+ tick.known(claims)
265
+ entry = self._add(str(name or getattr(fn, "__name__", "entry")), "program", parent, claims)
266
+ conflict = tick.claim(entry, claims) if tick is not None and claims else {}
267
+ span = spans.current()
268
+ testing = spans.in_test()
269
+
270
+ def run():
271
+ _local.entry = entry
272
+ spans.set_entry(entry.id)
273
+ status, result, error, failure = "done", None, None, None
274
+ try:
275
+ with spans.under(span), spans.testing(testing):
276
+ self.check(entry)
277
+ if conflict:
278
+ raise Escalation(self._conflict(entry, conflict))
279
+ result = fn()
280
+ except Cancelled:
281
+ status = "cancelled"
282
+ except Escalation as escalation:
283
+ status, failure = "failed", escalation.trace.event
284
+ error = f"{failure.kind} from {failure.source}"
285
+ except (EpisodeEnded, ProgramFinished) as stop:
286
+ # The episode ended, or the task is done: the agent's program hears of it,
287
+ # and the entry is no event of its own.
288
+ status, error = ("cancelled", "the episode ended") if isinstance(stop, EpisodeEnded) else ("done", None)
289
+ self._for_model(stop, entry)
290
+ except BaseException as raised:
291
+ status, error = "failed", f"{type(raised).__name__}: {_short(str(raised), 300)}"
292
+ finally:
293
+ self._end(entry, status, result=result, error=error, failure=failure)
294
+ entry.thread = threading.Thread(target=run, name=f"entry-{entry.id}", daemon=True)
295
+ entry.thread.start()
296
+ return entry
297
+
298
+ def claim(self, names) -> bool:
299
+ """The caller's entry claims the channels `names` (see the module docstring): True;
300
+ False when one is another entry's and a handler took the CHANNEL_CONFLICT event,
301
+ which otherwise escalates."""
302
+ tick = self._channels()
303
+ if tick is None:
304
+ raise ValueError("this embodiment declares no channels to claim")
305
+ entry = self.current()
306
+ names = tick.known(names)
307
+ found = tick.claim(entry, names)
308
+ if not found:
309
+ entry.claims = tuple(dict.fromkeys([*entry.claims, *names]))
310
+ spans.record("entry_claims", id=entry.id, claims=list(entry.claims))
311
+ return True
312
+ self.session._finish(self._conflict(entry, found))
313
+ return False
314
+
315
+ def release(self, names=None) -> None:
316
+ """The caller's entry lets go of the channels `names` (None: all it has): its
317
+ claims, and the keys and buttons it holds down on them."""
318
+ tick = self._channels()
319
+ if tick is None:
320
+ raise ValueError("this embodiment declares no channels to release")
321
+ entry = self.current()
322
+ names = None if names is None else tick.known(names)
323
+ tick.release(entry, names)
324
+ entry.claims = () if names is None else tuple(name for name in entry.claims if name not in names)
325
+ spans.record("entry_claims", id=entry.id, claims=list(entry.claims))
326
+
327
+ def channels(self) -> dict:
328
+ """Who has each channel now ({channel: {"entry", "how"}}, None: nobody); {} when
329
+ the embodiment declares none."""
330
+ tick = self._channels()
331
+ return tick.board() if tick is not None else {}
332
+
333
+ def _channels(self):
334
+ """The session's tick when its embodiment declares channels, else None."""
335
+ tick = self.session._ticker
336
+ return tick if tick.channels else None
337
+
338
+ def _conflict(self, entry, found) -> ExecutionTrace:
339
+ step = (self.session.state or {}).get("step")
340
+ return ExecutionTrace("claim", {"channels": sorted(found)}, step, step,
341
+ Event(ev.CHANNEL_CONFLICT, "channels", {"channels": found, "entry": entry.id}, step))
342
+
343
+ def adopt_agent(self, agent, task) -> Entry:
344
+ """The entry of a sub-agent the caller started (delegate)."""
345
+ return self._add(_short(" ".join(str(task).split()), 80), "agent", self.current(), (), agent=str(agent))
346
+
347
+ def agent_ended(self, agent, report, *, cancelled=False) -> None:
348
+ """A sub-agent ended (the conversation tells the kernel, runtime/execution/kernel.py): so does
349
+ its entry, failed unless it finished."""
350
+ entry = next((item for item in list(self.entries.values()) if item.kind == "agent" and item.agent == str(agent)
351
+ and item.running), None)
352
+ if entry is None:
353
+ return
354
+ report = dict(report or {})
355
+ status = report.get("status")
356
+ if cancelled or entry._cancel.is_set():
357
+ self._end(entry, "cancelled", result=report)
358
+ elif status in AGENT_DONE:
359
+ self._end(entry, "done", result=report)
360
+ else:
361
+ self._end(entry, "failed", result=report, error=f"the sub-agent ended: {status}"
362
+ + (f" ({report['error']})" if report.get("error") else ""))
363
+
364
+ def _add(self, name, kind, parent, claims, agent=None) -> Entry:
365
+ with self._changed:
366
+ if self._closed:
367
+ raise RuntimeError("the session has closed")
368
+ self._count += 1
369
+ entry = Entry(self, f"e{self._count}", name, kind, parent, claims, agent=agent)
370
+ self.entries[entry.id] = entry
371
+ parent.children.append(entry)
372
+ spans.record("entry_start", id=entry.id, parent=parent.id, name=entry.name, kind=kind,
373
+ **({"claims": entry.claims} if entry.claims else {}), **({"agent": agent} if agent else {}),
374
+ span=spans.current())
375
+ return entry
376
+
377
+ # Ending entries, and their events.
378
+
379
+ def _end(self, entry, status, result=None, error=None, failure=None) -> None:
380
+ """`entry` ended: its own entries end with it, its guards and handlers go, its
381
+ waiters wake, and a failure goes up as an ENTRY_FAILED event."""
382
+ for child in list(entry.children):
383
+ if child.running:
384
+ try:
385
+ child.cancel()
386
+ except BaseException:
387
+ pass
388
+ with self._changed:
389
+ if not entry.running:
390
+ return
391
+ entry.status, entry.result, entry.error = status, result, error
392
+ entry.ended = time.time()
393
+ self._ended.append(entry)
394
+ if status == "failed":
395
+ step = (self.session.state or {}).get("step")
396
+ detail = {"entry": entry.id, "kind": entry.kind}
397
+ detail.update({"event": failure.to_dict()} if failure is not None else {"error": error})
398
+ if entry.agent is not None:
399
+ detail["agent"] = entry.agent
400
+ entry.failure = Escalation(ExecutionTrace(entry.name, {}, step, step,
401
+ Event(ev.ENTRY_FAILED, entry.name, detail, step)))
402
+ waited = entry._waiters > 0
403
+ entry._done.set()
404
+ self._changed.notify_all()
405
+ reactive = getattr(self.session, "reactive", None)
406
+ if reactive is not None:
407
+ reactive.clear_owner(entry.id)
408
+ tick = self.session.__dict__.get("_tick_loop")
409
+ if tick is not None and tick.channels:
410
+ # Its claims go, and what it held down goes up at the next period.
411
+ tick.release(entry)
412
+ spans.record("entry_end", id=entry.id, status=status,
413
+ **({"error": _short(error, 300)} if error else {}),
414
+ **({"event_kind": failure.kind} if failure is not None else {}))
415
+ if entry.failure is not None and not waited:
416
+ if threading.current_thread() is entry.thread:
417
+ # Its thread ends after this: the parent's handlers run on it.
418
+ self.deliver(entry.parent, entry.failure.trace)
419
+ else:
420
+ threading.Thread(target=self.deliver, args=(entry.parent, entry.failure.trace),
421
+ name=f"event-{ev.ENTRY_FAILED}", daemon=True).start()
422
+
423
+ def deliver(self, entry, trace) -> bool:
424
+ """Offer the event of `trace` to the handlers of `entry` and up; one nobody
425
+ handles reaches the model. Whether a handler resolved it."""
426
+ if self.handle(entry, trace):
427
+ return True
428
+ self._for_model(Escalation(trace), entry)
429
+ return False
430
+
431
+ def record_event(self, trace, entry=None):
432
+ record = {"skill": trace.skill, "event": trace.event.to_dict(), "ticks": trace.ticks}
433
+ if entry is not None:
434
+ record["entry"] = entry.id
435
+ # Events still pass through the same handlers. History streams to the host;
436
+ # the next decision gets bounded feedback rather than every operation again.
437
+ spans.note("execution_event", execution=record)
438
+ counts = self.session.__dict__.setdefault("_event_counts", {})
439
+ counts[trace.event.kind] = counts.get(trace.event.kind, 0) + 1
440
+ if not trace.ok:
441
+ self.session._events.append(record)
442
+ if len(self.session._events) > 32:
443
+ del self.session._events[0]
444
+ return record
445
+
446
+ def raise_event(self, entry, trace, *, notice=False) -> None:
447
+ """Deliver an independent event without waiting for its handlers on the tick."""
448
+ record = self.record_event(trace, entry)
449
+
450
+ def deliver():
451
+ _local.entry = entry
452
+ if self.handle(entry, trace):
453
+ record["handled"] = True
454
+ elif not notice:
455
+ self._for_model(Escalation(trace), entry)
456
+ threading.Thread(target=deliver, name=f"event-{trace.event.kind}", daemon=True).start()
457
+
458
+ def handle(self, entry, trace) -> bool:
459
+ """Offer `trace`'s event to the answer for its kind of `entry`, then of each entry
460
+ above it (runtime/reactive/rules.py answer): the first that does not return False
461
+ resolves it."""
462
+ layer = getattr(self.session, "reactive", None)
463
+ if layer is None:
464
+ return False
465
+ return layer.answer([level.id for level in entry.lineage()], trace, lambda owner: self.acting(self.get(owner)),
466
+ lambda owner, fault: reactive.emit(
467
+ self, owner, trace.skill, reactive.fault_event(fault, trace.end_tick)))
468
+
469
+ def _for_model(self, stop, entry) -> None:
470
+ if control.host_thoughts:
471
+ trace = stop.trace
472
+ spans.note("escalation", id=uuid.uuid4().hex, entry=entry.id, skill=trace.skill,
473
+ event=trace.event.to_dict())
474
+ return
475
+ with self._changed:
476
+ self.root.pending.append(stop)
477
+ self._changed.notify_all()
478
+
479
+ # What the kernel does around a program.
480
+
481
+ def begin_program(self) -> None:
482
+ """A program starts: an event that reached the model while none ran ends it at
483
+ once (it was written without knowing)."""
484
+ self.check(self.root)
485
+
486
+ def end_program(self) -> None:
487
+ """A program ended: an event that reached the model while it ran and that it did not
488
+ meet is its end."""
489
+ self.check(self.root)
490
+
491
+ def drain(self) -> list[dict]:
492
+ """The entries the model hears of after a program: those running, and those that
493
+ ended since the last drain (the root aside)."""
494
+ with self._changed:
495
+ ended, self._ended = self._ended, []
496
+ running = [entry for entry in self.entries.values() if entry.running and entry is not self.root]
497
+ return [entry.state() for entry in ended + running]
498
+
499
+ def close(self, timeout=2.0) -> None:
500
+ """The session closes: every entry is cancelled."""
501
+ with self._changed:
502
+ self._closed = True
503
+ for entry in list(self.root.children):
504
+ if entry.running and entry.kind != "agent":
505
+ try:
506
+ entry.cancel(timeout)
507
+ except BaseException:
508
+ pass
509
+ control.on_agent_ended(self.agent_ended, remove=True)
510
+
511
+
512
+ def _tag(entry):
513
+ """What an entry's spans carry as their `entry`: none for the root's."""
514
+ return None if entry.kind == "root" else entry.id
515
+
516
+
517
+ class _Acting:
518
+ def __init__(self, entry):
519
+ self.entry = entry
520
+
521
+ def __enter__(self):
522
+ self.saved = getattr(_local, "entry", None), spans.set_entry(_tag(self.entry))
523
+ _local.entry = self.entry
524
+ return self.entry
525
+
526
+ def __exit__(self, *_):
527
+ _local.entry = self.saved[0]
528
+ spans.set_entry(self.saved[1])
529
+ return False
530
+
531
+
532
+ # -- The closed loop every execution runs as ----------------------------------------------
533
+
534
+ # Escalations that end the program whatever a loop does: the episode's end, a pause, a message.
535
+ PASS_ON = frozenset({ev.EPISODE_ENDED, ev.USER_PAUSED, ev.USER_MESSAGE})
536
+
537
+
538
+ class Result(dict):
539
+ """What a closed loop did: {"ok", "reason", "tries", "seconds", "detail"}; true when ok."""
540
+
541
+ def __bool__(self):
542
+ return bool(self.get("ok"))
543
+
544
+ def __getattr__(self, key):
545
+ try:
546
+ return self[key]
547
+ except KeyError:
548
+ raise AttributeError(key) from None
549
+
550
+
551
+ class Stop(Exception):
552
+ """Raised in a step: the loop ends here with this reason (no more tries)."""
553
+
554
+
555
+ class ClosedLoop:
556
+ """Confirm, do, check, retry, give the reason: one bounded execution, in any action
557
+ scenario; a skill the model writes is one, and so is every execution of the session's
558
+ skills (runtime/execution/session.py Execution). A subclass fills in confirm() (before each try:
559
+ True, or the reason not to act), do(), check() (after it: True, or why not) and
560
+ recover(reason) (between tries); a step may raise Stop(reason). Called with the skill's
561
+ parameters (on self), it runs at most `tries` times and `max_seconds` long and returns a
562
+ Result; an exception of `catches` in a step is its reason (the episode's end, finish()
563
+ and PASS_ON always end the program). A step may fill in `detail`. Each try's end is
564
+ report()ed: a skill_step record, news for the model while the program runs."""
565
+
566
+ tries = 3
567
+ max_seconds = 30.0
568
+ catches = Exception
569
+
570
+ def __new__(cls, *args, **kwargs):
571
+ from harness.runtime.learning.library import assert_active
572
+
573
+ assert_active(cls)
574
+ loop = super().__new__(cls)
575
+ loop.__init__(*args, **kwargs)
576
+ return loop.run()
577
+
578
+ def __init__(self, *args, **kwargs):
579
+ self.args = args
580
+ self.__dict__.update(kwargs)
581
+ self.detail = {}
582
+
583
+ def confirm(self):
584
+ return True
585
+
586
+ def do(self):
587
+ raise NotImplementedError("a closed loop's do() is the action")
588
+
589
+ def check(self):
590
+ return True
591
+
592
+ def recover(self, reason):
593
+ pass
594
+
595
+ def report(self, number: int, what: str, ok: bool, seconds: float, reason) -> None:
596
+ from harness.runtime.learning.library import code_origin
597
+
598
+ spans.step(type(self).__name__, number, what, ok, seconds, reason, of=int(self.tries),
599
+ library=code_origin(type(self)))
600
+
601
+ def run(self) -> Result:
602
+ start = time.monotonic()
603
+ reason, tries = None, 0
604
+ try:
605
+ for tries in range(1, max(1, int(self.tries)) + 1):
606
+ if time.monotonic() - start > self.max_seconds:
607
+ reason = f"out of time ({self.max_seconds:g} s)"
608
+ break
609
+ begun = time.monotonic()
610
+ confirmed = self.confirm()
611
+ if confirmed is not True:
612
+ reason = _why(confirmed, "not confirmed")
613
+ break
614
+ wait = 0.0
615
+ try:
616
+ self.do()
617
+ checked = self.check()
618
+ except Escalation as escalation:
619
+ # An event of a step (a rejected command, a guard) is this try's failure:
620
+ # the next try comes after the wait the event asks for, if any.
621
+ if escalation.trace.event.kind in PASS_ON or not isinstance(escalation, self.catches):
622
+ raise
623
+ checked, wait = str(escalation), _wait_asked(escalation)
624
+ if checked is True:
625
+ return self._result(True, None, tries, start)
626
+ reason = _why(checked, "the check failed")
627
+ if tries < self.tries:
628
+ self.report(tries, "try", False, time.monotonic() - begun, reason)
629
+ left = self.max_seconds - (time.monotonic() - start)
630
+ if wait > left:
631
+ break
632
+ time.sleep(wait)
633
+ self.recover(reason)
634
+ except Stop as stop:
635
+ reason = str(stop) or "stopped"
636
+ except (ProgramFinished, EpisodeEnded):
637
+ raise
638
+ except Escalation as escalation:
639
+ if escalation.trace.event.kind in PASS_ON or not isinstance(escalation, self.catches):
640
+ raise
641
+ reason = str(escalation)
642
+ except Exception as error:
643
+ if not isinstance(error, self.catches):
644
+ raise
645
+ reason = f"{type(error).__name__}: {error}"
646
+ return self._result(False, reason, tries, start)
647
+
648
+ def _result(self, ok, reason, tries, start) -> Result:
649
+ result = Result(ok=ok, reason=reason, tries=tries, seconds=round(time.monotonic() - start, 2),
650
+ detail=dict(getattr(self, "detail", None) or {}))
651
+ self.report(tries, "done" if ok else "gave up", ok, result["seconds"], reason)
652
+ return result
653
+
654
+
655
+ def _why(value, default: str) -> str:
656
+ return value if isinstance(value, str) and value else default
657
+
658
+
659
+ def _wait_asked(escalation) -> float:
660
+ """The seconds an event asks to wait before acting again (a shield's reason with
661
+ `wait_seconds`, such as the user using the computer), else 0."""
662
+ detail = escalation.trace.event.detail or {}
663
+ reasons = detail.get("reasons") or (detail.get("shield") or {}).get("reasons") or []
664
+ waits = [float(reason.get("wait_seconds", 0) or 0) for reason in reasons if isinstance(reason, dict)]
665
+ return max(waits, default=0.0)