@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,2878 @@
1
+ """One bounded natural-language task, including model decisions and Automatic Control.
2
+
3
+ Programs, reactive rules and learned policies execute independently of model transport.
4
+ The runtime calls the model at decision points, permits steering/clarification during
5
+ execution, and settles speculative decisions against their input revisions. Finish and
6
+ budget exhaustion end the run. Persistent identity and multi-task conversations are not
7
+ part of this lifecycle. Benchmark and interactive task callers use this same engine.
8
+ """
9
+
10
+ import ast
11
+ import base64
12
+ import hashlib
13
+ import json
14
+ from contextlib import contextmanager
15
+ from pathlib import Path
16
+ import threading
17
+ import time
18
+ from types import SimpleNamespace
19
+ import uuid
20
+
21
+ from harness.runtime.decision import loop as decisions
22
+ from harness.runtime.decision.messages import _inbox_parts
23
+ from harness.runtime.execution.results import _taken_over, _cell_usage, _wrap_up
24
+ from harness.runtime.safety.approval import CONFIRMATION_POLICIES
25
+ from harness.runtime.status import Closed
26
+
27
+ from harness.bench import bench_names, bench_spec
28
+ from harness.core.remote import RemoteEnvironment
29
+ from harness.core.media import write_episode_videos
30
+ from harness.core import sha256
31
+ from harness.core.http import Preempted
32
+ from harness.core.trace import Trace, context_summary, provenance, write_json
33
+ from harness.embodiments import KINDS as EMBODIMENT_KINDS, embodiment_kind
34
+ from harness.runtime.decision.thoughts import Thought, ThoughtCancelled, ThoughtQueue
35
+ from harness.runtime.execution.kernel import DEFAULT_BOOTSTRAP, Kernel, KernelDied, kernel_python
36
+ from harness.runtime.learning.library import SECTIONS, eligible, executable, library_for
37
+ from harness.runtime.task import context as memory_view
38
+ from harness.runtime.task.context import WorkingMemory
39
+ from harness.runtime.learning.usage import fold_uses
40
+ from harness.runtime.decision.messages import (EMBODIMENT_TEXT, attachment_parts, cell_feedback, image_parts,
41
+ prune_images, prune_views, state_text, text_only, view_parts, window)
42
+ from harness.runtime.events import EVENTS
43
+ from harness.runtime.status import ERROR, FINISHED, IDLE, PAUSED, RUNNING, STATUSES, WAITING_FOR_CONFIRMATION
44
+ from harness.runtime.learning.active import sandbox_of
45
+ from harness.runtime.decision.protocol import DIRECT_KINDS, KINDS, ProtocolError, announces, looks_like_action, parse_reply
46
+
47
+ import harness.runtime.learning.views as library_view
48
+
49
+
50
+ class TaskRun:
51
+ """One episode of `config.task` with `seed`, its trace and files under `directory`.
52
+ `chat`, `verifier` and `environment` replace the configured models and worker.
53
+ `interactive`: a user takes part (see the module docstring); `confirmation`: one of
54
+ CONFIRMATION_POLICIES; `instruction`: the user's own instruction in place of the
55
+ task's (the evaluator's outcome still scores the task). `agents` (runtime/task/delegation.py)
56
+ starts the sub-agents its programs ask for; `parent`: the agent that started this one.
57
+ Managed workspaces are acquired by the host before the conversation starts."""
58
+
59
+ def __init__(self, config, seed: int, directory, *, chat=None, verifier=None, environment=None,
60
+ interactive: bool = False, confirmation: str = "never", instruction: str | None = None,
61
+ agents=None, parent=None, memory=None):
62
+ from copy import copy
63
+
64
+ from harness.config.agent import resolve_for
65
+ from harness.runtime.task.delegation import NO_DEEPER, SUB_AGENT_PROMPT
66
+
67
+ if confirmation not in CONFIRMATION_POLICIES:
68
+ raise ValueError(f"confirmation must be one of {CONFIRMATION_POLICIES}")
69
+ # The configuration as given: a sub-agent's is a copy of it.
70
+ self.base_config = config
71
+ self.parent = parent
72
+ self.depth = parent.depth + 1 if parent is not None else 0
73
+ self.agents = agents
74
+ roles = {"main": config.main, "verifier": config.verifier}
75
+ self._skills = resolve_for(config.runtime, roles, config.embodiment).enabled
76
+ # Working state belongs to this task; sharing requires an explicit argument.
77
+ self.working_memory = memory if memory is not None else WorkingMemory()
78
+ self._active_library = {}
79
+ self._library_prompt = ""
80
+ self._captured_library = None
81
+ self._activation_queue = {}
82
+ self._activation_interrupt = 0
83
+ self._fixture_attempts = set()
84
+ self._fixture_status = "unchecked"
85
+ self._fixture_descriptions = []
86
+ self._fixture_feedback = {}
87
+ self._reflected_cells = 0
88
+ self._recall_library = []
89
+ self._recall_since = None
90
+ self._admissions = parent._admissions if parent is not None else {}
91
+ self._admission_lock = parent._admission_lock if parent is not None else threading.Lock()
92
+ table = config.runtime.get("library") or {}
93
+ config = copy(config)
94
+ if table and table.get("learn") == "on":
95
+ config.system_prompt = config.base_prompt
96
+ self.ahead = str(config.runtime.get("think_while_acting") or "on")
97
+ if self.ahead not in decisions.THINK_WHILE_ACTING:
98
+ raise ValueError(f"runtime.think_while_acting must be one of {decisions.THINK_WHILE_ACTING}, got {self.ahead!r}")
99
+ thinking = self.thinking_level = str(config.runtime.get("thinking") or "model")
100
+ if thinking not in decisions.THINKING:
101
+ raise ValueError(f"runtime.thinking must be one of {tuple(decisions.THINKING)}, got {thinking!r}")
102
+ if thinking != "model":
103
+ config = copy(config)
104
+ config.main = decisions._thinking(config.main, thinking)
105
+ if thinking in ("none", "low"):
106
+ config.system_prompt += decisions.THINK_BRIEFLY
107
+ config.base_prompt += decisions.THINK_BRIEFLY
108
+ if interactive:
109
+ config = copy(config)
110
+ message_prompt = decisions.MESSAGE_PROMPT
111
+ if parent is None:
112
+ role_prompt = decisions.INTERACTIVE_PROMPT + message_prompt
113
+ else:
114
+ deepest = agents is None or self.depth >= agents.max_depth
115
+ role_prompt = SUB_AGENT_PROMPT + message_prompt + (
116
+ NO_DEEPER if deepest and "agents" in (config.runtime.get("skills") or []) else "")
117
+ config.system_prompt += role_prompt
118
+ config.base_prompt += role_prompt
119
+ self.config = config
120
+ self.seed = seed
121
+ self.directory = directory
122
+ self.program_directory: Path | None = None
123
+ self.interactive = interactive
124
+ self.confirmation = confirmation
125
+ self.instruction = instruction
126
+ self.chat, self.verifier, self.env = chat, verifier, environment
127
+ self.trace = Trace(directory, EVENTS)
128
+ self.status = IDLE
129
+ self.messages = []
130
+ self.kernel = None
131
+ self.episode = None
132
+ self.summary = None
133
+ self._condition = threading.Condition()
134
+ self._inbox = []
135
+ self._pause = False
136
+ self._closing = False
137
+ self._decision = None
138
+ self._waited = 0.0
139
+ self._cell_running = False
140
+ self._program_span = None
141
+ # Thinking while acting: what the next user message starts with (a used reply's program
142
+ # result), the messages logged and replaced, the calls set aside before they were back.
143
+ self._carry = []
144
+ # What a call made for a message while a program runs needs (_think_on_message).
145
+ self._kinds, self._turns = KINDS, None
146
+ # Programs run beside the running one, by id (_run_beside).
147
+ self._sides = {}
148
+ self._request = None
149
+ self._revision = self._ahead_generation = 0
150
+ self._pending_events = {}
151
+ self._seen_events = set()
152
+ self._reported_events = set()
153
+ self._ahead_due = None
154
+ self._program_completing = False
155
+ self._interruptions = 0
156
+ self._thoughts = ThoughtQueue(self._condition, advance=self._decision_tick,
157
+ on_exit=self._came_back, trace=self.trace)
158
+ self._cancelled_origins = set()
159
+ # Set when the episode deadline expires while a program runs.
160
+ self._wall_up = False
161
+ self._logged = 0
162
+ self._replaces = 0
163
+ # What the user said, in order: the instruction, then every message.
164
+ self._said = []
165
+ # The physical-input request waiting for the user's answer.
166
+ self._physical = None
167
+ self._program_approval_id = None
168
+ self._host_tool = None
169
+ self._worker_approvals = {}
170
+ self._worker_slot = threading.BoundedSemaphore(1)
171
+ self.mcp_prepare = None
172
+ self.mcp_authorize = parent.mcp_authorize if parent is not None else None
173
+ self._mcp_slot = threading.BoundedSemaphore(16)
174
+ self._mcp_cancelled = set()
175
+ self._mcp_entries = set()
176
+ self.mcp_resources = parent.mcp_resources if parent is not None else None
177
+ self._managed_workspace = self._managed_dispatcher = None
178
+ # Other environments this conversation may take, and its sub-agents on request
179
+ # (runtime/task/environments.py): the session host's, None where there is none.
180
+ self.environments = None
181
+ # Skills the user switched on while it runs: loaded between programs.
182
+ self._skills_due = []
183
+ # How views reach the model. A configuration that declares runtime.cameras has a
184
+ # standing watch from the opening message on (an evaluation's observation contract:
185
+ # every turn carries those cameras, keep_images of them stay). Any other looks on
186
+ # the model's demand: text every turn, a view only when a program looked (look,
187
+ # watch), kept for `_view_keep` replies or while pinned (the model says).
188
+ self._standing = "cameras" in config.runtime
189
+ self._view_keep, self._view_pins = 1, set()
190
+ # The views a watch(every=seconds) sent while a program runs, for the model's next look.
191
+ self._watched = None
192
+ # A main model that reads no images gets none (its role's `images` is false).
193
+ self._images = config.main.get("images") is not False
194
+ # {session, agent} in a sessions registry (host/sessions.py).
195
+ self.identity = None
196
+ # Sub-agents: their models, this agent's workspace kind, what its sub-agents spent and
197
+ # it charged its parent, and its result and question for its parent.
198
+ self.agent_chat, self.agent_verifier = chat, verifier
199
+ self.workspace_kind = None
200
+ place = EMBODIMENT_KINDS[config.embodiment].place if config.embodiment in EMBODIMENT_KINDS else ""
201
+ if self.agents is None and parent is None and place and "agents" in (config.runtime.get("skills") or []):
202
+ # Its kind gives the sub-agents a place (a game has one body: its sub-agents
203
+ # only look, at a view of this episode, and never act).
204
+ import importlib
205
+
206
+ from harness.runtime.task.delegation import Agents
207
+
208
+ module, _, name = place.partition(":")
209
+ self.agents = Agents(place=getattr(importlib.import_module(module), name)())
210
+ self.workspace_kind = self.agents.place.kinds[0] if self.agents.place.kinds else None
211
+ self.agents_usage = {"started": 0, "model_calls": 0, "cost_usd": 0.0}
212
+ self._charged = (0, 0.0)
213
+ self._iterations = 0
214
+ self.result = None
215
+ self.question = None
216
+ self.waiting_since = None
217
+ self.trace.context = self._who
218
+
219
+ def _who(self) -> dict:
220
+ """What every record of the trace says of whose it is, once it is in a session."""
221
+ identity = self.identity
222
+ if not identity:
223
+ return {}
224
+ parent = (self.parent.identity or {}).get("agent") if self.parent is not None else None
225
+ return {"who": {"session": identity.get("session"), "agent": identity.get("agent"),
226
+ "parent": identity.get("parent") or parent}}
227
+
228
+ # What others call, from any thread.
229
+
230
+ def send_message(self, text: str, sender: str = "user", files=()) -> None:
231
+ """A message from the user (or, `sender` "parent", from the agent that started this
232
+ one): recorded now, sent with the model's next call. `files`: paths the user attached
233
+ (read now: messages.attachment_parts)."""
234
+ text, files = str(text).strip(), [str(path) for path in files or ()]
235
+ if not text and not files:
236
+ return
237
+ parts = attachment_parts(files)
238
+ with self._condition:
239
+ if self.status in (FINISHED, ERROR):
240
+ raise RuntimeError("The episode has ended")
241
+ self._inbox.append((sender, text, parts))
242
+ said = " ".join([text] + [f"@{path}" for path in files]).strip()
243
+ self._said.append(said if sender == "user" else f"(from the agent that started you) {said}")
244
+ self.question = None
245
+ self.trace.emit("user_message", text=text, **({"files": files} if files else {}),
246
+ **({"sender": sender} if sender != "user" else {}))
247
+ self._revision += 1
248
+ if self._managed_dispatcher is not None:
249
+ self._managed_dispatcher.stop()
250
+ self._cancel_managed_worker_approvals("a new user message arrived")
251
+ if self._physical is not None and self._physical["id"] in self._worker_approvals:
252
+ request = self._physical
253
+ self._worker_approvals.pop(request["id"])
254
+ self._physical = None
255
+ self._answer_physical(request, False, "once", "superseded by a user message")
256
+ self._preempt("user message")
257
+ self._condition.notify_all()
258
+
259
+ def pause(self) -> None:
260
+ """Pause: a running program stops at its next execution step; the model is not
261
+ called again until resume() or a message."""
262
+ with self._condition:
263
+ if self.status in (FINISHED, ERROR):
264
+ return
265
+ self._pause = True
266
+ self._activation_interrupt += 1
267
+ self._thoughts.cancel_where(lambda item: item.role == "reflection", "paused")
268
+ if self._managed_dispatcher is not None:
269
+ self._managed_dispatcher.stop()
270
+ self._cancel_managed_worker_approvals("paused")
271
+ kernel = self.kernel if self._cell_running else None
272
+ self.invalidate_lookahead()
273
+ self._condition.notify_all()
274
+ if self.agents is not None:
275
+ self.agents.wake()
276
+ self._drop_physical("paused")
277
+ if kernel is not None:
278
+ kernel.pause()
279
+
280
+ def resume(self) -> None:
281
+ """Go on after a pause."""
282
+ with self._condition:
283
+ self._pause = False
284
+ self._condition.notify_all()
285
+
286
+ def set_model(self, model: str | None = None, reasoning_effort: str | None = None) -> dict:
287
+ """Change the main model (another id of its provider) or its reasoning effort (EFFORTS,
288
+ "" for the provider's default; runtime.thinking still bounds it) from its next call on:
289
+ a model_changed record. Returns the model and effort now."""
290
+ from harness.runtime.decision.model import ChatModel
291
+
292
+ main = dict(self.config.main)
293
+ if model:
294
+ main["model"] = str(model).strip()
295
+ if reasoning_effort is not None:
296
+ from harness.runtime.decision.model import valid_effort
297
+
298
+ if not valid_effort(reasoning_effort):
299
+ raise ValueError("invalid reasoning effort ID")
300
+ main.pop("reasoning_effort", None)
301
+ if reasoning_effort:
302
+ main["reasoning_effort"] = reasoning_effort
303
+ if self.thinking_level != "model":
304
+ main = decisions._thinking(main, self.thinking_level)
305
+ with self._condition:
306
+ if self.status in (FINISHED, ERROR):
307
+ raise RuntimeError("The episode has ended")
308
+ chat = self.chat
309
+ if chat is not None:
310
+ if not isinstance(chat, ChatModel):
311
+ raise ValueError("this conversation's model is not one a model id names")
312
+ # Its connection as it is (a provider's transport), with the new role.
313
+ chat = ChatModel(main, transport=chat.transport)
314
+ self.config.main = main
315
+ if chat is not None:
316
+ self.chat = chat
317
+ changed = {"model": main["model"], "reasoning_effort": main.get("reasoning_effort")}
318
+ self.trace.emit("model_changed", **changed)
319
+ return changed
320
+
321
+ @property
322
+ def waiting_for(self) -> str | None:
323
+ """What the conversation waits for the user to approve, when it is physical input."""
324
+ request = self._physical
325
+ if request is None:
326
+ return None
327
+ where = request.get("app") or request.get("window") or "a window"
328
+ return f"approval: physical input in {where} ({'/'.join(request.get('actions') or [])})"
329
+
330
+ @property
331
+ def approval_id(self):
332
+ with self._condition:
333
+ return self._physical.get("id") if self._physical is not None else self._program_approval_id
334
+
335
+ def confirm(self, accept: bool, reason: str = "", remember: str | None = None, *, request_id=None) -> None:
336
+ """Answer a pending approval. A sensitive step requires its exact request ID."""
337
+ from harness.runtime.safety.input import REMEMBER
338
+
339
+ with self._condition:
340
+ request = self._physical
341
+ if request_id is not None and request_id != self.approval_id:
342
+ raise RuntimeError("The approval request is no longer pending")
343
+ if request is None:
344
+ if self.status != WAITING_FOR_CONFIRMATION or self._program_approval_id is None or self._decision is not None:
345
+ raise RuntimeError("No program is waiting for confirmation")
346
+ self._decision = (bool(accept), str(reason or ""))
347
+ self._condition.notify_all()
348
+ return
349
+ if request.get("sensitive") and request_id != request["id"]:
350
+ raise RuntimeError("The sensitive approval requires its exact request id")
351
+ if (remember or "once") not in REMEMBER:
352
+ raise ValueError(f"remember is one of {', '.join(REMEMBER)}")
353
+ host_tool = self._host_tool is not None and request is self._host_tool["request"]
354
+ if host_tool and time.monotonic() >= self._host_tool["deadline"]:
355
+ raise RuntimeError("The approval request expired")
356
+ pending = self._worker_approvals.get(request["id"])
357
+ if pending is not None:
358
+ if not self._worker_approval_current(pending):
359
+ raise RuntimeError("The worker approval is no longer pending")
360
+ pending["answer"] = (bool(accept), "once" if request.get("sensitive") else remember or "once")
361
+ self._physical = None
362
+ if host_tool:
363
+ self._host_tool["decision"] = bool(accept)
364
+ self._host_tool["reason"] = str(reason or "")
365
+ self._answer_physical(request, accept, "once", reason, host_only=True)
366
+ self._condition.notify_all()
367
+ return
368
+ if pending is not None and pending["workspace"] is not None:
369
+ self._answer_physical(request, accept, "once", reason, host_only=True)
370
+ if not accept:
371
+ self.cancel_worker_approval(pending, reason=reason or "the approval was refused")
372
+ return
373
+ self._answer_physical(request, accept, remember or "once", reason)
374
+
375
+ def close(self) -> None:
376
+ """End the episode: at once while it waits, else at the next step boundary."""
377
+ with self._condition:
378
+ self._closing = True
379
+ if self._request is not None:
380
+ self._preempt("conversation closed")
381
+ if self._managed_dispatcher is not None:
382
+ self._managed_dispatcher.stop()
383
+ self._cancel_managed_worker_approvals("closed")
384
+ kernel = self.kernel if self._cell_running else None
385
+ self._condition.notify_all()
386
+ if self.agents is not None:
387
+ self.agents.wake()
388
+ self._drop_physical("closed")
389
+ if kernel is not None:
390
+ kernel.pause()
391
+
392
+ # Physical input the policy asks the user for (runtime/safety/input.py).
393
+
394
+ def _register_worker_approval(self, request, tick, *, workspace=None):
395
+ """Record a refusal from a host-authenticated worker call under the condition."""
396
+ from harness.runtime.safety.approval import WORKER_APPROVAL_SECONDS
397
+
398
+ now = time.monotonic()
399
+ self._worker_approvals = {key: row for key, row in self._worker_approvals.items()
400
+ if row["deadline"] > now and row["revision"] == self._revision}
401
+ pending = {"request": request, "tick": tick, "workspace": workspace, "revision": self._revision,
402
+ "answer": None, "deadline": now + WORKER_APPROVAL_SECONDS}
403
+ self._worker_approvals[request["id"]] = pending
404
+ return pending
405
+
406
+ def _worker_approval_current(self, pending):
407
+ return (self._worker_approvals.get(pending["request"]["id"]) is pending
408
+ and pending["revision"] == self._revision and time.monotonic() < pending["deadline"])
409
+
410
+ def _claim_worker_retry(self, pending, action_id, step):
411
+ """Consume consent once and recover the original tick payload under the condition."""
412
+ if not (self._worker_approval_current(pending) and pending["answer"] and pending["answer"][0]
413
+ and pending["request"].get("retry") == "host_tick" and action_id == pending["tick"]["action_id"]):
414
+ return None
415
+ identifier = pending["request"]["id"]
416
+ del self._worker_approvals[identifier]
417
+ return {**pending["tick"], "step": step, "request_id": identifier}
418
+
419
+ def offer_managed_worker_approval(self, workspace, reply, tick):
420
+ """Publish the private worker's attributed refusal through the normal host prompt."""
421
+ from harness.runtime.safety.approval import SENSITIVE
422
+
423
+ request = reply.get("approval")
424
+ if (reply["executed"] or not isinstance(request, dict) or request.get("retry") != "host_tick"
425
+ or request.get("sensitive") not in SENSITIVE or not isinstance(request.get("id"), str)
426
+ or not request["id"] or not isinstance(request.get("target"), str)
427
+ or not isinstance(request.get("actions"), list)
428
+ or any(request.get(key) != tick[key] for key in ("episode_id", "execution_id", "action_id", "step"))
429
+ or reply["state"]["step"] != tick["step"]):
430
+ return None
431
+ with self._condition:
432
+ if (not self.interactive or self._managed_workspace is not workspace
433
+ or tick["episode_id"] != self.episode or self._closing or self._pause
434
+ or self.status != RUNNING or self._physical is not None or self._host_tool is not None
435
+ or self._managed_dispatcher.stopped()):
436
+ return None
437
+ pending = self._register_worker_approval(request, tick, workspace=workspace)
438
+ self._physical_request(request)
439
+ return pending
440
+
441
+ def worker_approval_ready(self, pending):
442
+ with self._condition:
443
+ return not self._worker_approval_current(pending) or pending["answer"] is not None
444
+
445
+ def claim_managed_worker_retry(self, pending, episode_id, step):
446
+ with self._condition:
447
+ if (self._managed_workspace is pending["workspace"] and not self._closing and not self._pause
448
+ and self.status not in (FINISHED, ERROR) and episode_id == self.episode == pending["tick"]["episode_id"]
449
+ and not self._managed_dispatcher.stopped()):
450
+ if arguments := self._claim_worker_retry(pending, pending["tick"]["action_id"], step):
451
+ return arguments
452
+ self.cancel_worker_approval(pending, reason="the approval expired or the action was interrupted")
453
+
454
+ def _cancel_managed_worker_approvals(self, reason):
455
+ for pending in tuple(self._worker_approvals.values()):
456
+ if pending["workspace"] is not None:
457
+ self.cancel_worker_approval(pending, reason=reason)
458
+
459
+ def cancel_worker_approval(self, pending, *, reason):
460
+ with self._condition:
461
+ request = pending["request"]
462
+ if self._worker_approvals.get(request["id"]) is not pending:
463
+ return
464
+ del self._worker_approvals[request["id"]]
465
+ if self._physical is request:
466
+ self._drop_physical(reason)
467
+ threading.Thread(target=pending["workspace"].cancel_approval,
468
+ args=(request["id"], pending["tick"]), daemon=True).start()
469
+
470
+ def _physical_request(self, request: dict) -> None:
471
+ """A running program waits for the user's answer to a physical-input request: in
472
+ an interactive conversation the user is asked; nobody is in an evaluation."""
473
+ if not isinstance(request.get("id"), str):
474
+ return
475
+ with self._condition:
476
+ managed = bool(getattr(self.env, "approval_key", None)) or (
477
+ self.environments is not None and self.environments.any_managed())
478
+ pending = None
479
+ if managed or request.get("retry") in ("tick", "host_tick"):
480
+ pending = self._worker_approvals.get(request["id"])
481
+ if (pending is None or not self._worker_approval_current(pending) or pending["answer"] is not None
482
+ or self._pause or self._closing):
483
+ self._answer_physical(request, False, "once", "worker approval requires a trusted due receipt",
484
+ update_status=False)
485
+ return
486
+ offered = pending["request"]
487
+ request = ({**offered, "scope": request["scope"], "why": str(request.get("why", ""))[:500]}
488
+ if request.get("scope") and not offered.get("sensitive") else offered)
489
+ detail = ({"action_step": pending["tick"]["step"]}
490
+ if pending is not None and pending["workspace"] is not None else {})
491
+ self.trace.emit("physical_request", **request, **detail)
492
+ if not self.interactive:
493
+ self._worker_approvals.pop(request["id"], None)
494
+ self._answer_physical(request, False, "once", "nobody is there to ask in this run")
495
+ return
496
+ if self._physical is not None or self._host_tool is not None:
497
+ self._answer_physical(request, False, "once", "another approval is pending", update_status=False)
498
+ return
499
+ self._physical = request
500
+ self._set_status(WAITING_FOR_CONFIRMATION, reason="physical", request=request)
501
+
502
+ def _answer_physical(self, request: dict, accept: bool, remember: str, reason: str = "",
503
+ *, update_status=True, host_only=False) -> None:
504
+ if request.get("sensitive"):
505
+ remember = "once"
506
+ self.trace.emit("physical_answer", id=request.get("id"), accepted=bool(accept), remember=remember,
507
+ reason=str(reason or ""))
508
+ if self.kernel is not None and not host_only:
509
+ self.kernel.answer(request.get("id"), {"accept": bool(accept), "remember": remember,
510
+ "reason": str(reason or ""), "physical": True})
511
+ with self._condition:
512
+ waiting = update_status and self.status == WAITING_FOR_CONFIRMATION and self._decision is None
513
+ if waiting and self.status not in (FINISHED, ERROR):
514
+ self._set_status(RUNNING)
515
+
516
+ def _drop_physical(self, why: str) -> None:
517
+ """Pausing or closing answers no physical-input request: the program stops waiting."""
518
+ with self._condition:
519
+ request, self._physical = self._physical, None
520
+ if self._pause or self._closing:
521
+ self._worker_approvals.clear()
522
+ if request is not None:
523
+ self.trace.emit("physical_answer", id=request.get("id"), accepted=False, remember="once", reason=why)
524
+ if self.status == WAITING_FOR_CONFIRMATION:
525
+ self._set_status(RUNNING)
526
+
527
+ def start(self) -> threading.Thread:
528
+ """Run the episode on a thread of its own and return the thread."""
529
+ self._set_status(RUNNING)
530
+ thread = threading.Thread(target=self.run, name=f"conversation-{self.directory.name}", daemon=True)
531
+ thread.start()
532
+ return thread
533
+
534
+ # The episode.
535
+
536
+ @contextmanager
537
+ def _span(self, lane: str, name: str, **detail):
538
+ """Record the code inside as a span of the timeline (core/spans.py); yields a
539
+ dict whose items go into its end record."""
540
+ identifier = uuid.uuid4().hex[:12]
541
+ self.trace.emit("span_start", id=identifier, lane=lane, name=name, parent=None, **detail)
542
+ if lane == "program":
543
+ self._program_span = identifier
544
+ end = {}
545
+ try:
546
+ yield end
547
+ except BaseException as error:
548
+ end.setdefault("error", f"{type(error).__name__}: {error}"[:300])
549
+ raise
550
+ finally:
551
+ if lane == "program":
552
+ self._program_span = None
553
+ self.trace.emit("span_end", id=identifier, **end)
554
+
555
+ def _steps_shown(self) -> bool:
556
+ """Whether the model is told the step count and what is left of the step budget: not
557
+ when the worker keeps them to itself (profile steps_shown false: a practice segment,
558
+ whose time limit the model must not play against)."""
559
+ return (getattr(self, "profile", None) or {}).get("steps_shown", True) is not False
560
+
561
+ def _kernel_span(self, record: dict) -> None:
562
+ """A span from the kernel (a skill's execution, a service call), under the
563
+ program that runs."""
564
+ record = dict(record)
565
+ kind = record.pop("op")
566
+ if kind == "worker_request":
567
+ self._queue_host_request(record, worker=True)
568
+ return
569
+ if kind == "side_result":
570
+ self._side_ended(record)
571
+ return
572
+ if kind == "note":
573
+ note = record.pop("kind", None)
574
+ if note == "physical_request" and isinstance(record.get("request"), dict):
575
+ self._physical_request(record["request"])
576
+ elif note == "physical_cancel":
577
+ with self._condition:
578
+ self._worker_approvals.pop(record.get("id"), None)
579
+ if self._physical is not None and self._physical["id"] == record.get("id"):
580
+ self._drop_physical(str(record.get("reason") or "execution ended"))
581
+ elif note == "agents":
582
+ self._agents_request(record)
583
+ elif note == "environment":
584
+ threading.Thread(target=self._environment_request, args=(record,), name="environment",
585
+ daemon=True).start()
586
+ elif note == "views":
587
+ self._views_changed(record)
588
+ elif note == "view":
589
+ with self._condition:
590
+ if self._cell_running and not self._standing and isinstance(record.get("images"), dict):
591
+ self._watched = [{"camera": name, "image_url": url}
592
+ for name, url in record["images"].items()]
593
+ self._thoughts.wake()
594
+ elif note == "mcp_request":
595
+ self._queue_host_request(record)
596
+ elif note == "mcp_cancel":
597
+ with self._condition:
598
+ self._mcp_cancelled.add(record["id"])
599
+ elif note == "thought_cancel":
600
+ with self._condition:
601
+ self._cancelled_origins.add(record["id"])
602
+ self._thoughts.cancel_where(lambda thought: thought.origin == record["id"], "caller stopped")
603
+ elif note in ("library", "thought") and record.get("action") != "test":
604
+ if note == "thought":
605
+ with self._condition:
606
+ record["revision"] = self._revision
607
+ handle = self._library_request if note == "library" else self._thought_request
608
+ threading.Thread(target=handle, args=(record,), name=note, daemon=True).start()
609
+ elif note == "library_use":
610
+ record.pop("time", None)
611
+ self.trace.emit("library_use", **record)
612
+ elif note == "cell_finishing":
613
+ with self._condition:
614
+ if self._cell_running:
615
+ self._program_completing = True
616
+ self._condition.notify_all()
617
+ elif note == "escalation":
618
+ self._escalation(record)
619
+ elif note == "memory":
620
+ self._memory_request(record)
621
+ elif note in EVENTS:
622
+ record.pop("time", None)
623
+ self.trace.emit(note, **record)
624
+ if note == "guard" and self.summary is not None:
625
+ self.summary["guard_triggers"] += 1
626
+ if note == "memory":
627
+ self.invalidate_lookahead()
628
+ return
629
+ if kind in ("entry_start", "entry_end"):
630
+ with self._condition:
631
+ if kind == "entry_start":
632
+ self._mcp_entries.add(record["id"])
633
+ else:
634
+ self._mcp_entries.discard(record["id"])
635
+ if kind == "span_start" and record.get("parent") is None:
636
+ record["parent"] = self._program_span
637
+ self.trace.emit(kind, **record)
638
+
639
+ def _queue_host_request(self, request, *, worker=False):
640
+ identifier = request.get("id")
641
+ owner = request.get("entry") if not worker else None
642
+ if not isinstance(identifier, str) or len(identifier) != 32:
643
+ return
644
+ with self._condition:
645
+ kernel = self.kernel
646
+ if kernel is None or (not worker and not (owner in self._mcp_entries if owner else self._cell_running)) or self._closing or self._pause:
647
+ if worker and kernel is not None:
648
+ kernel.answer(identifier, {"worker": True, "error": "The calling program has stopped"})
649
+ return
650
+ slot = self._worker_slot if worker else self._mcp_slot
651
+ if worker and request.get("environment"):
652
+ # An attached environment's call (runtime/execution/attached.py): its own slots.
653
+ try:
654
+ slot = self.environments.of(request["environment"])["slot"]
655
+ except Exception as error:
656
+ kernel.answer(identifier, {"worker": True, "error": str(error)})
657
+ return
658
+ if not slot.acquire(blocking=False):
659
+ kernel.answer(identifier, {"worker": worker, "error": "Another request is still running"})
660
+ return
661
+ revision, cell = self._revision, self.summary["cells"]
662
+
663
+ def still_current():
664
+ return (self.kernel is kernel and (worker or (owner in self._mcp_entries if owner else
665
+ self._cell_running and self.summary["cells"] == cell))
666
+ and (owner or self._revision == revision) and not self._pause and not self._closing
667
+ and (worker or identifier not in self._mcp_cancelled))
668
+
669
+ threading.Thread(target=self._host_request, args=(kernel, request, still_current, slot),
670
+ kwargs={"worker": worker}, name="host-request", daemon=True).start()
671
+
672
+ def _host_request(self, kernel, request, still_current, slot, *, worker=False):
673
+ """Make a host-owned worker or MCP call without blocking the kernel reader."""
674
+ from harness.services.mcp import ToolAccess
675
+
676
+ action = None
677
+ dispatched = False
678
+ def mark_dispatched(server):
679
+ nonlocal dispatched
680
+ dispatched = True
681
+ self.trace.emit("mcp_dispatched", id=request["id"], server=server, tool=request.get("tool"))
682
+ if not worker:
683
+ self.trace.emit("mcp_submitted", **request)
684
+ try:
685
+ with self._condition:
686
+ if not still_current():
687
+ raise PermissionError("The calling program has stopped")
688
+ if not worker and not hasattr(self, "_mcp_access"):
689
+ self._mcp_access = ToolAccess(self.config.runtime.get("mcp") or {}, prepare=self.mcp_prepare,
690
+ resources=self.mcp_resources, directory=self.directory / "services",
691
+ authorize=self.mcp_authorize)
692
+ plain = None
693
+ if worker:
694
+ name, args = request.get("name"), dict(request.get("arguments") or {})
695
+ env, episode = self.env, self.episode
696
+ if request.get("environment"):
697
+ attached = self.environments.of(request["environment"])
698
+ env, episode = attached["env"], attached["episode"]
699
+ if not getattr(env, "approval_key", None) or name not in env.host_controls:
700
+ # What the worker serves to anyone: sent as the kernel would send it.
701
+ if args.get("episode_id", episode) != episode:
702
+ raise PermissionError("The call belongs to another episode")
703
+ plain = attached["plain"]
704
+ if worker and plain is None:
705
+ if not getattr(env, "approval_key", None) or name not in env.host_controls:
706
+ raise PermissionError("The host does not own this worker control")
707
+ if args.setdefault("episode_id", episode) != episode:
708
+ raise PermissionError("The control belongs to another episode")
709
+ op = args.get("op")
710
+ if name == "tick":
711
+ action = args.get("action_id")
712
+ args.pop("execution_id", None)
713
+ if isinstance(action, str) and 0 < len(action) <= 128:
714
+ args["execution_id"] = action
715
+ elif name == "sensitive_approval" or (name == "physical" and op == "answer"):
716
+ identifier = args.get("id")
717
+ pending = self._worker_approvals.get(identifier)
718
+ if (pending is None or not self._worker_approval_current(pending) or pending["answer"] is None
719
+ or pending["workspace"] is not None):
720
+ raise PermissionError("No current user approval for this worker request")
721
+ accept, remember = pending["answer"]
722
+ sensitive = pending["request"].get("retry") == "host_tick"
723
+ if name == "sensitive_approval":
724
+ if op != "retry" or not (retry := self._claim_worker_retry(
725
+ pending, args.get("action_id"), args["step"])):
726
+ raise PermissionError("Approval does not match the refused action")
727
+ args, action = retry, retry["action_id"]
728
+ elif sensitive:
729
+ raise PermissionError("A sensitive action requires the original worker retry")
730
+ else:
731
+ args = {"op": "answer", "episode_id": episode, "id": identifier,
732
+ "accept": accept, "remember": remember}
733
+ del self._worker_approvals[identifier]
734
+ elif (name not in getattr(env, "program_controls", ()) and name != "use_screen"
735
+ and not (name == "physical" and op in ("check", "status"))):
736
+ raise PermissionError("This worker control is reserved to the host")
737
+ if worker and plain is not None:
738
+ reply = {"value": plain.call(name, **args)}
739
+ elif worker:
740
+ if name == "sensitive_approval":
741
+ value = env.sensitive_approval("retry", approval_key=env.approval_key, **args)
742
+ else:
743
+ value = env.managed_call(name, approval_key=env.approval_key, **args)
744
+ reply = {"value": value}
745
+ offered = (value.get("approval") if name == "tick" else
746
+ value.get("request") if name == "physical" and op == "check" else None)
747
+ if isinstance(offered, dict) and (offered.get("retry") != "host_tick" or
748
+ name == "tick" and "execution_id" in args and
749
+ (offered.get("episode_id"), offered.get("execution_id"), offered.get("action_id")) ==
750
+ (episode, args["execution_id"], action)):
751
+ with self._condition:
752
+ if still_current():
753
+ self._register_worker_approval(offered, args)
754
+ elif request.get("method") == "list":
755
+ reply = {"value": self._mcp_access.tools()}
756
+ elif request.get("method") == "call":
757
+ reply = {"value": self._mcp_access.call(request.get("tool"), request.get("arguments"),
758
+ approve=lambda tool, target: self._approve_host_tool(tool, target, still_current),
759
+ current=still_current, dispatched=mark_dispatched)}
760
+ else:
761
+ raise ValueError("Unknown MCP operation")
762
+ except Exception as error:
763
+ reply = {"error": f"{type(error).__name__}: {error}"}
764
+ finally:
765
+ slot.release()
766
+ with self._condition:
767
+ if not worker:
768
+ self.trace.emit("mcp_receipt", id=request["id"], tool=request.get("tool"),
769
+ late=not still_current(), dispatched=dispatched,
770
+ outcome="unknown" if dispatched and "error" in reply else
771
+ "not_dispatched" if "error" in reply else "returned", **reply)
772
+ if worker and action and self.kernel is not kernel:
773
+ result = reply.get("value") or {}
774
+ self.trace.emit("late_receipt", action_id=action, executed=result.get("executed"),
775
+ step=(result.get("state") or {}).get("step"), error=reply.get("error"))
776
+ if still_current() or worker and self.kernel is kernel:
777
+ kernel.answer(request["id"], {"worker" if worker else "mcp": True, **reply})
778
+
779
+ def _approve_host_tool(self, tool, target, still_current):
780
+ """Await and claim a decision for one operation already bound by the host."""
781
+ from harness.runtime.safety import approval
782
+
783
+ request = approval.request("irreversible", target, [tool])
784
+ return self._await_host_decision(request, still_current, approval.WORKER_APPROVAL_SECONDS)[0]
785
+
786
+ def _await_host_decision(self, request, still_current, seconds=None):
787
+ """Put a request of the host's own to the user as every frontend shows an approval,
788
+ and wait for their answer: (accepted, their reason). Refused without asking when
789
+ nobody is there, another approval is pending or the asking program has stopped."""
790
+ with self._condition:
791
+ if (not self.interactive or not still_current() or self._physical is not None
792
+ or self._host_tool is not None):
793
+ return False, "another approval is pending" if self._physical is not None else ""
794
+ deadline = time.monotonic() + seconds if seconds else float("inf")
795
+ pending = self._host_tool = {"request": request, "decision": None, "deadline": deadline, "reason": ""}
796
+ self._physical = request
797
+ self.trace.emit("physical_request", **request)
798
+ self._set_status(WAITING_FOR_CONFIRMATION, reason="physical", request=request)
799
+
800
+ ready = self._condition.wait_for(lambda: pending["decision"] is not None or not still_current(),
801
+ timeout=seconds)
802
+ self._host_tool = None
803
+ if self._physical is request:
804
+ self._drop_physical("the approval expired or was interrupted")
805
+ accepted = ready and still_current() and time.monotonic() < deadline and pending["decision"] is True
806
+ return accepted, pending["reason"] or ("" if ready else "the question was interrupted")
807
+
808
+ def _ask_user(self, kind, target, *, why="", **detail):
809
+ """Ask the user one of the host's own questions (another environment, sub-agents) from
810
+ a running program: (accepted, their reason). It waits as long as the user takes; a
811
+ pause, a new message or the conversation's end leaves it unanswered."""
812
+ from harness.runtime.safety import approval
813
+
814
+ with self._condition:
815
+ kernel, revision, cell = self.kernel, self._revision, self.summary["cells"]
816
+
817
+ def still_current():
818
+ return (self.kernel is kernel and self._cell_running and self.summary["cells"] == cell
819
+ and self._revision == revision and not self._pause and not self._closing)
820
+
821
+ request = approval.request(kind, target, [kind], why=str(why)[:500], **detail)
822
+ return self._await_host_decision(request, still_current)
823
+
824
+ def _views_changed(self, record):
825
+ """What a program said of its views (runtime/execution/session.py): how many programs'
826
+ views stay in sight, a watch begun or ended, a pin let go."""
827
+ action = record.get("action")
828
+ with self._condition:
829
+ if action == "keep":
830
+ self._view_keep = max(1, min(20, int(record.get("keep") or 1)))
831
+ elif action == "unpin":
832
+ if record.get("pin") is None:
833
+ self._view_pins.clear()
834
+ else:
835
+ self._view_pins.discard(str(record["pin"]))
836
+ elif action == "unwatch":
837
+ self._watched = None
838
+ self.trace.emit("views", **{key: value for key, value in record.items() if key not in ("time", "id")})
839
+
840
+ def _described(self, looks) -> list[dict]:
841
+ """Views for a main model that reads no images: what the vision role says of each
842
+ (runtime.viewer), or that it was not sent."""
843
+ from harness.runtime.decision.model import ChatModel
844
+
845
+ viewer = self.config.runtime.get("viewer")
846
+ parts = []
847
+ for item in list(looks)[-4:]:
848
+ name = f"View: {item['camera']}" + (f" region {item['region']}" if item.get("region") else "")
849
+ if not isinstance(viewer, dict) or not viewer.get("model"):
850
+ parts.append({"type": "input_text", "text": f"{name}: not sent. This model reads no images and no "
851
+ "vision model is configured (model.vision); use the state and what the "
852
+ "environment's calls return as text."})
853
+ continue
854
+ try:
855
+ chat = self.__dict__.setdefault("_viewer_chat", None) or ChatModel(
856
+ {"max_output_tokens": 1024, **{key: value for key, value in viewer.items() if key != "images"}})
857
+ self._viewer_chat = chat
858
+ reply = self._ask_role("vlm", chat, VIEWER, [{"role": "user", "content": [
859
+ {"type": "input_image", "image_url": item["image_url"], "detail": "auto"},
860
+ {"type": "input_text", "text": "Describe this view."}]}])
861
+ parts.append({"type": "input_text", "text": f"{name}, as the vision model describes it:\n"
862
+ + reply.text.strip()})
863
+ except Exception as error:
864
+ parts.append({"type": "input_text", "text": f"{name}: not described ({type(error).__name__}: {error})"})
865
+ return parts
866
+
867
+ def _environment_request(self, request):
868
+ """A program asks for another environment, to give one back, or for sub-agents
869
+ (skills/environments): answered through the kernel."""
870
+ if self.environments is None:
871
+ answer = {"error": "this conversation cannot take another environment"}
872
+ else:
873
+ answer = self.environments.handle(request)
874
+ if self.kernel is not None:
875
+ self.kernel.answer(request.get("id"), answer)
876
+
877
+ def _prompt_added(self, text):
878
+ from copy import copy
879
+
880
+ with self._condition:
881
+ self.config = copy(self.config)
882
+ self.config.system_prompt += text
883
+ self.invalidate_lookahead()
884
+
885
+ def _prompt_removed(self, text):
886
+ from copy import copy
887
+
888
+ with self._condition:
889
+ self.config = copy(self.config)
890
+ self.config.system_prompt = self.config.system_prompt.replace(text, "", 1)
891
+ self.invalidate_lookahead()
892
+
893
+ def _skill_added(self, name) -> bool:
894
+ """A skill switched on while the conversation runs: part of its skills and prompt now."""
895
+ with self._condition:
896
+ if name in self._skills:
897
+ return False
898
+ self._skills = [*self._skills, name]
899
+ if self.environments is not None and name == "agents":
900
+ self._prompt_added("\n\nSub-agents are on for this conversation now.\n"
901
+ + (self.environments.place.agents().get("prompt") or ""))
902
+ return True
903
+
904
+ def enable_agents(self) -> bool:
905
+ """The user switches sub-agents on for this conversation (any frontend): their calls
906
+ load before its next program."""
907
+ if self.environments is None:
908
+ raise RuntimeError("this conversation cannot start sub-agents")
909
+ with self._condition:
910
+ if self.status in (FINISHED, ERROR):
911
+ raise RuntimeError("The episode has ended")
912
+ given = self.environments.enable_agents(asked_by="user")
913
+ with self._condition:
914
+ self._skills_due += given["skills"]
915
+ self._condition.notify_all()
916
+ return True
917
+
918
+ def _load_due_skills(self) -> None:
919
+ with self._condition:
920
+ due, self._skills_due = self._skills_due, []
921
+ kernel = self.kernel
922
+ if due and kernel is not None:
923
+ result = kernel.run(f"__load_skills__({due!r})", timeout=60)
924
+ if result["status"] != "ok":
925
+ self.trace.emit("cleanup_error", message=f"skills {due}: {result.get('error')}")
926
+
927
+ def _escalation(self, record):
928
+ with self._condition:
929
+ identifier = record["id"]
930
+ if identifier in self._seen_events:
931
+ return
932
+ self._seen_events.add(identifier)
933
+ self._pending_events[identifier] = record
934
+ self.trace.emit("escalation", **{key: value for key, value in record.items() if key != "event"},
935
+ reported=record["event"])
936
+ self._revision += 1
937
+ self._preempt("unhandled escalation")
938
+ self._condition.notify_all()
939
+
940
+ def heard(self, text: str, *, escalation=False, agent_report=False) -> None:
941
+ """Child reports are execution results; only explicit escalation asks the model."""
942
+ if escalation:
943
+ self._escalation({"id": uuid.uuid4().hex, "event": {"kind": "ESCALATION", "detail": str(text)}})
944
+
945
+ def _preempt(self, reason):
946
+ self._ahead_due = None
947
+ thought = self._request
948
+ if thought is not None and thought.outcome is None:
949
+ self._settle(thought, "discarded", reason)
950
+ if reason == "user message":
951
+ self._thoughts.cancel_where(lambda item: item.role in ("verifier", "observer", "vlm", "pointer", "reflection"),
952
+ reason)
953
+ elif reason == "unhandled escalation":
954
+ self._thoughts.cancel_where(lambda item: item.role == "observer", reason)
955
+
956
+ def invalidate_lookahead(self) -> None:
957
+ with self._condition:
958
+ self._ahead_due = None
959
+ self._ahead_generation += 1
960
+ if self._request is not None and self._request.trigger == "ahead":
961
+ self._settle(self._request, "discarded", "inputs changed")
962
+ self._condition.notify_all()
963
+
964
+ def _learner(self):
965
+ """The run's library ([runtime.library]) and what its settings allow, opened once per
966
+ conversation (runtime/learning/learner.py)."""
967
+ if self.__dict__.get("_opened") is None:
968
+ from harness.runtime.learning.learner import Learner
969
+
970
+ runtime = self.base_config.runtime
971
+ self._opened = Learner(library_for(runtime, Path("/")).directory, runtime["library"])
972
+ return self._opened
973
+
974
+ def _learning(self) -> dict | None:
975
+ """The run's learning settings (runtime/learning/learner.py) when its library learns, else None."""
976
+ table = self.config.runtime.get("library") or {}
977
+ if not table:
978
+ return None
979
+ from harness.runtime.learning.learner import settings
980
+
981
+ chosen = settings(table)
982
+ return chosen if chosen["learn"] == "on" else None
983
+
984
+ def _learning_rows(self, snapshot=None):
985
+ rows = self._learner().entries(snapshot=snapshot)
986
+ with self._condition:
987
+ active = self._active_library.copy()
988
+ shown = set()
989
+ for row in rows:
990
+ item = active.get(row["file"])
991
+ if executable(row["file"]):
992
+ row["loaded"] = bool(item and not row["waiting"] and item[0].revision == row["revision"])
993
+ if row["loaded"]:
994
+ shown.add(row["file"])
995
+ for key, (item, row) in active.items():
996
+ if key in shown:
997
+ continue
998
+ info = self._active_row(item, row)
999
+ rows.append({**info, "section": key.split("/", 1)[0], "file": key, "loaded": True,
1000
+ "verified": bool(row.get("proof")), "uses": info["seen"], "success_rate": info["rate"]})
1001
+ return rows
1002
+
1003
+ def _learning_progress(self):
1004
+ from harness.runtime.learning.active import progress
1005
+
1006
+ return {**progress(self._learning_rows(), self.seconds_left(), self.config.max_wall_seconds or 0.0,
1007
+ self._situations()), "fixture_status": self._fixture_status,
1008
+ "fixture_feedback": dict(self._fixture_feedback)}
1009
+
1010
+ def _learning_report(self) -> str:
1011
+ from harness.runtime.learning import active
1012
+
1013
+ if not active.is_active(self.config.runtime):
1014
+ return ""
1015
+ report = active.report(self._learning_rows(), self.seconds_left(), self._situations())
1016
+ if self._fixture_descriptions:
1017
+ report += "\n" + "\n".join(self._fixture_descriptions)
1018
+ elif self._fixture_status == "unavailable":
1019
+ report += "\nNo trusted fixture is configured here. Keep observations and leave executable proposals pending."
1020
+ if self._fixture_feedback:
1021
+ report += "\n" + "\n".join(f"{key}: {why}" for key, why in self._fixture_feedback.items())
1022
+ return "\n" + report
1023
+
1024
+ def _trial_at_boundary(self, *, replay=False):
1025
+ """Run at most one trial between programs, or recheck pinned entries at startup."""
1026
+ from harness.runtime.learning import fixtures
1027
+ from harness.runtime.learning.learner import CANDIDATES
1028
+
1029
+ learning = self._learning()
1030
+ if not learning or self.parent is not None or (replay and not learning["replay"]):
1031
+ return
1032
+ with self._condition:
1033
+ if self._closing or self._pause or self._cell_running or self._sides or (self._inbox and not replay):
1034
+ return
1035
+ generation = self._activation_interrupt, self._revision
1036
+
1037
+ def cancelled():
1038
+ with self._condition:
1039
+ return (self._closing or self._pause or self._cell_running or bool(self._sides)
1040
+ or generation != (self._activation_interrupt, self._revision))
1041
+
1042
+ try:
1043
+ inventory = fixtures.configured(self.profile)
1044
+ except (OSError, TypeError, ValueError) as error:
1045
+ self._fixture_status = "unavailable"
1046
+ self.trace.emit("library", action="fixture_unavailable", reason=str(error))
1047
+ return
1048
+ self._fixture_descriptions = fixtures.describe(inventory)
1049
+ self._fixture_status = "configured" if self._fixture_descriptions else "unavailable"
1050
+ if not self._fixture_descriptions:
1051
+ return
1052
+ learner = self._learner()
1053
+ trials = {fixture.get("skill"): fixture for fixture in inventory}
1054
+ for index_key, row in learner.index().items():
1055
+ pending = index_key.startswith(f"{CANDIDATES}/")
1056
+ if pending and (replay or row.get("evidence") != "proposed"):
1057
+ continue
1058
+ if not pending and (not replay or row.get("evidence") != "provisional" or not row.get("proof")):
1059
+ continue
1060
+ key = index_key.removeprefix(f"{CANDIDATES}/")
1061
+ if not executable(key):
1062
+ continue
1063
+ fixture = trials.get(Path(key).stem)
1064
+ expected = row.get("revision")
1065
+ if (not fixture or not expected or expected in self._fixture_attempts or cancelled()
1066
+ or self.seconds_left() <= 0):
1067
+ continue
1068
+ self._fixture_attempts.add(expected)
1069
+ budget = fixtures.Budget(self.seconds_left(), cancelled)
1070
+ try:
1071
+ entry = learner.candidate_from(key, pending=pending)
1072
+ if entry is None or pending and entry.revision().revision != expected:
1073
+ continue
1074
+ self.trace.emit("library", action="trial_started", key=key, revision=expected)
1075
+ began = time.monotonic()
1076
+ item, receipt = fixtures.verify(entry, fixture, budget, str(self.directory))
1077
+ receipt["seconds"] = round(time.monotonic() - began, 3)
1078
+ self.trace.emit("library", action="trial_observed", key=key, **receipt)
1079
+ if not pending:
1080
+ proof = row["proof"]
1081
+ if (item.revision != expected or proof["conditions"].get("fixture_sha256") != receipt["fixture_sha256"]
1082
+ or proof["conditions"].get("profile_sha256") != sha256(self.profile)
1083
+ or proof.get("receipt", {}).get("run") == receipt["run"]
1084
+ or proof.get("receipt", {}).get("episode_id") == receipt["episode_id"]):
1085
+ raise ValueError("the replay conditions differ from the verified revision")
1086
+ if not receipt["ok"] or not pending:
1087
+ with self._admission_lock, self._condition:
1088
+ budget.remaining()
1089
+ learner.record_trial(key, expected, item, pending=pending,
1090
+ evidence="replayed" if receipt["ok"] else "failed",
1091
+ receipt=receipt, check=budget.remaining)
1092
+ if not receipt["ok"]:
1093
+ self._fixture_feedback[key] = "Trusted verification failed: the expected input effect was absent."
1094
+ else:
1095
+ proof = {"revision": item.revision, "conditions": {"method": "fixture",
1096
+ "fixture_sha256": receipt["fixture_sha256"], "profile_sha256": sha256(self.profile)},
1097
+ "receipt": receipt}
1098
+ admitted = {**row, "revision": item.revision, "proof": proof, "evidence": "provisional"}
1099
+
1100
+ def publish():
1101
+ budget.remaining()
1102
+ value = learner.admit(entry, "provisional", proof=proof, test_run=receipt,
1103
+ bindings=item.bindings, expected=expected, check=budget.remaining)
1104
+ self._library_admitted(learner, value, entry.text, entry.kind, entry.source, entry.origin)
1105
+ self._fixture_feedback.pop(key, None)
1106
+ return value["row"]
1107
+
1108
+ if learner.wanted(entry, "provisional") and self._library_eligible(
1109
+ item, admitted, learner.layers, learner.settings["load"]):
1110
+ self._activate_library([(item, admitted)], publish=publish, budget=budget)
1111
+ else:
1112
+ with self._admission_lock, self._condition:
1113
+ publish()
1114
+ except (OSError, ValueError, RuntimeError, ImportError, SyntaxError, TypeError, KeyError, StopIteration) as error:
1115
+ if isinstance(error, KernelDied):
1116
+ raise
1117
+ if isinstance(error, (ValueError, SyntaxError)):
1118
+ self._fixture_feedback[key] = f"Still pending: {str(error)[:300]}."
1119
+ self.trace.emit("library", action="trial_pending", key=key, revision=expected, reason=str(error))
1120
+ if not replay:
1121
+ return
1122
+
1123
+ def _startup_library(self, learning):
1124
+ library = self._learner().library
1125
+ with self._admission_lock:
1126
+ if learning:
1127
+ self._learner().migrate_experience()
1128
+ captured = library.capture()
1129
+ if not learning:
1130
+ expected = self.config.runtime["library"].get("manifest", {}).get("version")
1131
+ if expected and captured.version != expected:
1132
+ raise RuntimeError(f"Library {library.directory} changed after the configuration was loaded "
1133
+ f"(expected version {expected[:12]}). Evaluation needs a frozen library.")
1134
+ if learning and "notes" in library.layers:
1135
+ self._recall_since = len(self._admissions.get(library.directory, ()))
1136
+ self._captured_library = captured
1137
+ self._recall_library = library_view.library_entries(captured)
1138
+ return captured
1139
+
1140
+ def queue_library_revision(self, item, proof):
1141
+ """A trusted host verifier has admitted this exact revision."""
1142
+ if not executable(item.key) or proof.get("revision") != item.revision or not proof.get("conditions"):
1143
+ raise ValueError("activation requires proof for the exact executable revision")
1144
+ learner = self._learner()
1145
+ row = learner.index().get(item.key) or {}
1146
+ if row.get("revision") != item.revision or row.get("proof") != proof:
1147
+ raise ValueError("the revision and proof must be published together")
1148
+ if self._library_eligible(item, row, learner.layers, learner.settings["load"]):
1149
+ with self._condition:
1150
+ self._activation_queue[item.key] = (item, row)
1151
+
1152
+ def _library_eligible(self, item, row, layers, load):
1153
+ conditions = (row.get("proof") or {}).get("conditions") or {}
1154
+ if isinstance(conditions, dict) and conditions.get("profile_sha256") not in (None, sha256(self.profile)):
1155
+ return False
1156
+ return eligible(item, row, layers, load)
1157
+
1158
+ def _activate_library(self, selected, *, startup=False, publish=None, budget=None):
1159
+ if not selected:
1160
+ return
1161
+ def can_switch():
1162
+ return startup or (not (self._sides or self._cell_running or self._inbox)
1163
+ and (publish is not None or all(
1164
+ self._activation_queue.get(item.key, (None,))[0] == item for item, _ in selected)))
1165
+
1166
+ with self._condition:
1167
+ if self._pause or self._closing or not can_switch():
1168
+ return
1169
+ kernel = self.kernel
1170
+ interrupt = self._activation_interrupt
1171
+ for item, _ in selected:
1172
+ item.save(self.directory)
1173
+ entries = [(item, startup and row.get("origin", "hand") == "hand") for item, row in selected]
1174
+ with self._span("program", "library"):
1175
+ prepared = kernel.load_library("prepare", entries, **({"timeout": budget.remaining()} if budget else {}))
1176
+ rejected = None
1177
+ with self._admission_lock, self._condition:
1178
+ cancelled = (self._closing or self._pause or self.kernel is not kernel
1179
+ or self._activation_interrupt != interrupt or not can_switch())
1180
+ if not cancelled and prepared["status"] == "ok" and publish is not None:
1181
+ try:
1182
+ selected = [(selected[0][0], publish())]
1183
+ except (OSError, ValueError, RuntimeError) as error:
1184
+ rejected = str(error)
1185
+ if prepared["status"] != "ok" or cancelled or rejected:
1186
+ if prepared["status"] == "ok" and self.kernel is kernel:
1187
+ kernel.load_library("discard")
1188
+ self.trace.emit("library", action="load_failed", status="cancelled" if cancelled else "error",
1189
+ error=rejected or prepared.get("error"), revisions={item.key: item.revision for item, _ in selected})
1190
+ if cancelled or rejected:
1191
+ return
1192
+ if startup and any(not hand for _, hand in entries):
1193
+ self._activate_library([(item, row) for item, row in selected
1194
+ if row.get("origin", "hand") == "hand"], startup=True)
1195
+ elif startup:
1196
+ raise RuntimeError(f"Library code failed in the kernel: {prepared.get('error')}")
1197
+ else:
1198
+ with self._condition:
1199
+ for item, _ in selected:
1200
+ if self._activation_queue.get(item.key, (None,))[0] == item:
1201
+ del self._activation_queue[item.key]
1202
+ return
1203
+ # The boundary check reserved the switch. The kernel reader can drain notes while
1204
+ # the commit is acknowledged and the decision loop still owns program scheduling.
1205
+ result = kernel.load_library("commit")
1206
+ if result["status"] != "ok":
1207
+ raise KernelDied(f"Library commit failed: {result.get('error')}")
1208
+ with self._condition:
1209
+ for item, row in selected:
1210
+ self._active_library[item.key] = (item, row)
1211
+ queued = self._activation_queue.get(item.key)
1212
+ if queued and queued[0].revision == item.revision:
1213
+ del self._activation_queue[item.key]
1214
+ self._library_version = sha256(result["active"])
1215
+ self.trace.emit("library", action="activated", version=self._library_version,
1216
+ revisions=result["active"],
1217
+ entries=[self._active_row(item, row) for item, row in self._active_library.values()])
1218
+ if not startup:
1219
+ from copy import copy
1220
+ from harness.runtime.learning.library import active_summary
1221
+
1222
+ self.config = copy(self.config)
1223
+ prior = self._library_prompt
1224
+ updated = active_summary(item for item, _ in self._active_library.values())
1225
+ self.config.system_prompt = (self.config.system_prompt.replace(prior, updated, 1)
1226
+ if prior else self.config.system_prompt + updated)
1227
+ self._library_prompt = updated
1228
+ self.invalidate_lookahead()
1229
+
1230
+ @staticmethod
1231
+ def _active_row(item, row):
1232
+ uses = (row.get("uses_by_revision") or {}).get(item.revision) or {}
1233
+ row_data = memory_view.entry({"id": item.key, "kind": item.key.split("/", 1)[0],
1234
+ "name": Path(item.key).stem, "evidence": row.get("evidence", "validated"),
1235
+ "seen": uses.get("ok", 0) + uses.get("failed", 0), "rate": uses.get("rate")},
1236
+ "library")
1237
+ return {**row_data, "key": item.key, "revision": item.revision, "sha256": item.source_sha256,
1238
+ "source": row.get("origin", "hand"), "summary": row.get("summary", ""),
1239
+ "text": item.source.decode("utf-8")[:400], "active": True,
1240
+ **({"verification": row["proof"]} if row.get("proof") else {})}
1241
+
1242
+ def _startup_holdings(self):
1243
+ from harness.runtime.learning import active
1244
+
1245
+ situations = self._situations()
1246
+ rows = [{"section": item.key.split("/", 1)[0], "name": Path(item.key).stem,
1247
+ "summary": row.get("summary"), "passed": bool(row.get("proof"))}
1248
+ for item, row in self._active_library.values()]
1249
+ holdings = active.holdings(rows, situations)
1250
+ return f"\n{holdings}\n" if holdings else ""
1251
+
1252
+ def _visible_memory(self):
1253
+ if self._recall_since is None:
1254
+ return self._recall_library
1255
+ reader = self._learner().library
1256
+ admitted = self._admissions.get(reader.directory, ())[self._recall_since:]
1257
+ return library_view.overlay(self._recall_library, admitted, reader.layers, reader.load)
1258
+
1259
+ def _situations(self):
1260
+ with self._admission_lock:
1261
+ return next((item["text"] for item in reversed(self._visible_memory())
1262
+ if item["name"] == "situations" and item["where"] is None), None)
1263
+
1264
+ def _library_request(self, request: dict) -> None:
1265
+ """Handle program proposals and reads. Only the host can verify or admit code."""
1266
+ with self._admission_lock:
1267
+ answer = self._handle_library_request(request)
1268
+ if request.get("wait", True) and self.kernel is not None:
1269
+ self.kernel.answer(request.get("id"), answer)
1270
+
1271
+ def _handle_library_request(self, request: dict) -> dict:
1272
+ try:
1273
+ learning = self._learning()
1274
+ if request.get("action") == "entries":
1275
+ return {"value": self._learning_rows(self._captured_library if learning is None else None)}
1276
+ if request.get("action") == "attachment":
1277
+ pinned = [item for item, _ in self._active_library.values()]
1278
+ if self._captured_library is not None:
1279
+ pinned.extend(item for item in self._captured_library.entries if not executable(item.key))
1280
+ for item in pinned:
1281
+ for _, data in item.attachments:
1282
+ if hashlib.sha256(data).hexdigest() == request["sha256"]:
1283
+ return {"value": base64.b64encode(data).decode("ascii")}
1284
+ raise KeyError("no attachment with that digest in the active snapshot")
1285
+ if request.get("action") == "record":
1286
+ # Old learned programs may still call this. The traced result is the only tally.
1287
+ return {"value": None}
1288
+ if learning is None and request.get("action") in ("admit", "grade"):
1289
+ raise ValueError("learning is off in this run: the library is frozen")
1290
+ learner = self._learner()
1291
+ value = learner.handle(request, source=learner.settings["trigger"],
1292
+ run=str(self.directory) if getattr(self, "directory", None) else None)
1293
+ answer = {"value": value}
1294
+ except Exception as error:
1295
+ answer, value = {"error": f"{type(error).__name__}: {error}"}, None
1296
+ action = request.get("action")
1297
+ if action == "admit":
1298
+ if value is not None:
1299
+ self._library_admitted(learner, value, request.get("text", ""), request.get("entry"),
1300
+ learner.settings["trigger"], "model")
1301
+ if value["admitted"] and request.get("entry") == "note":
1302
+ from copy import copy
1303
+
1304
+ with self._condition:
1305
+ self.config = copy(self.config)
1306
+ self.config.system_prompt += f"\nLearned in this run: {str(request.get('text', '')).strip()}\n"
1307
+ self.invalidate_lookahead()
1308
+ else:
1309
+ self.trace.emit("library", action="rejected", kind=request.get("entry"), name=request.get("name"),
1310
+ reason=answer["error"])
1311
+ elif action == "grade":
1312
+ revision = {"sha256": request["sha256"]} if request.get("sha256") else {}
1313
+ if value is not None:
1314
+ self.trace.emit("library", action="promoted", key=request.get("key"), evidence=value["evidence"],
1315
+ why=request.get("why"), history=value.get("history"), **revision)
1316
+ else:
1317
+ self.trace.emit("library", action="rejected", key=request.get("key"), reason=answer["error"], **revision)
1318
+ return answer
1319
+
1320
+ def _library_admitted(self, learner, value, text, kind, source, origin) -> None:
1321
+ holding = library_view.admitted_entry(value, text)
1322
+ self.trace.emit("library", action="admitted", **learner.record_of(value), kind=kind,
1323
+ learned=source, origin=origin, holding=holding)
1324
+ if value["admitted"] and holding["kind"] == "memory":
1325
+ # Keep revisions in order so readers with different floors can keep the last one they selected.
1326
+ self._admissions[learner.directory] = (*self._admissions.get(learner.directory, ()), holding)
1327
+
1328
+ def _memory_request(self, request: dict) -> None:
1329
+ """A program's request to the run's working memory (skills/memory), answered at once;
1330
+ one nobody waits for that fails is a `world` record (refused) with why. A sub-agent in
1331
+ a world of its own (not a view of its parent's, not on its worker) keeps its places in
1332
+ a space of its own."""
1333
+ agent = (getattr(self, "identity", None) or {}).get("agent") or "main"
1334
+ try:
1335
+ if request.get("action") == "observe":
1336
+ request = {**request, "stream": self.episode}
1337
+ with self._admission_lock:
1338
+ library = self._visible_memory()
1339
+ if request.get("kind") == "skill_use":
1340
+ library = library_view.use_entries(self._active_library)
1341
+
1342
+ def persist(item, *, forgotten=False):
1343
+ learner = self._learner()
1344
+ changed = learner.store_memory(item, forgotten=forgotten)
1345
+ self._admissions[learner.directory] = (*self._admissions.get(learner.directory, ()), changed)
1346
+ self.trace.emit("library", action="memory", holding=changed)
1347
+ return changed
1348
+
1349
+ persist_memory = persist if self._recall_since is not None else None
1350
+ answer = {"value": self.working_memory.handle(request, record=self._memory_record, source=agent,
1351
+ space=self._memory_space(), library=library,
1352
+ persist=persist_memory)}
1353
+ except Exception as error:
1354
+ answer = {"error": f"{type(error).__name__}: {error}"}
1355
+ if not request.get("wait", True):
1356
+ self.trace.emit("world", action="refused", request=request.get("action"), reason=answer["error"][:300])
1357
+ if request.get("wait", True) and self.kernel is not None:
1358
+ self.kernel.answer(request.get("id"), answer)
1359
+
1360
+ def _memory_space(self):
1361
+ parent = self.parent
1362
+ if parent is not None and (self.workspace_kind == "view" or
1363
+ self.config.environment.get("endpoint") == parent.config.environment.get("endpoint")):
1364
+ return parent._memory_space()
1365
+ return (self.identity or {}).get("agent") or "main"
1366
+
1367
+ def _memory_record(self, **change) -> None:
1368
+ """A change of the working memory, or what a recall found: a `world` record of this
1369
+ agent's trace."""
1370
+ self.trace.emit("world", **change)
1371
+
1372
+ def _agents_request(self, request: dict) -> None:
1373
+ """A program asks for sub-agents (skills/agents): done on a thread of its own (a wait
1374
+ takes long; the kernel's notes must go on), answered through the kernel."""
1375
+
1376
+ if request.get("action") == "wait" and request.get("own", True):
1377
+ with self._condition:
1378
+ request["interrupt_at"] = self._interruptions
1379
+ self.invalidate_lookahead()
1380
+
1381
+ def answer():
1382
+ if self.agents is None:
1383
+ value = {"error": "this conversation cannot start sub-agents"}
1384
+ else:
1385
+ value = self.agents.handle(self, request)
1386
+ if self.kernel is not None:
1387
+ self.kernel.answer(request.get("id"), value)
1388
+
1389
+ threading.Thread(target=answer, name=f"agents-{request.get('action')}", daemon=True).start()
1390
+
1391
+ def charge_up(self) -> None:
1392
+ """Charge what this sub-agent spent since the last time to its parent (and up)."""
1393
+ if self.parent is None or self.summary is None:
1394
+ return
1395
+ calls, cost = self.summary["model_calls"], self.summary["cost_usd"]
1396
+ with self._condition:
1397
+ before, self._charged = self._charged, (calls, cost)
1398
+ self.parent._charge(calls - before[0], cost - before[1])
1399
+
1400
+ def _charge(self, calls: int, cost: float) -> None:
1401
+ """What a sub-agent (of any depth below) spent: counted against this agent's budget,
1402
+ its calls as this turn's."""
1403
+ if not calls and not cost:
1404
+ return
1405
+ with self._condition:
1406
+ self.agents_usage["model_calls"] += calls
1407
+ self.agents_usage["cost_usd"] += cost
1408
+ self._iterations += calls
1409
+ self._condition.notify_all()
1410
+ if self.parent is not None:
1411
+ self.parent._charge(calls, cost)
1412
+
1413
+ def _set_status(self, status: str, **detail) -> None:
1414
+ if status not in STATUSES:
1415
+ raise ValueError(f"unknown conversation status {status!r}")
1416
+ with self._condition:
1417
+ if status == self.status and not detail:
1418
+ return
1419
+ self.status = status
1420
+ self._condition.notify_all()
1421
+ self.trace.emit("state", status=status, **detail)
1422
+
1423
+ def _wait(self, status: str, ready, **detail):
1424
+ """Wait in `status` until `ready()` holds (under the lock); Closed when the user
1425
+ closes the conversation meanwhile."""
1426
+ self._set_status(status, **detail)
1427
+ began = time.perf_counter()
1428
+ with self._condition:
1429
+ while not self._closing and not ready():
1430
+ self._condition.wait()
1431
+ closing = self._closing
1432
+ self._waited += time.perf_counter() - began
1433
+ if closing:
1434
+ raise Closed()
1435
+ self._set_status(RUNNING)
1436
+
1437
+ def _take_inbox(self) -> list[str]:
1438
+ with self._condition:
1439
+ pending, self._inbox = self._inbox, []
1440
+ return pending
1441
+
1442
+ def _checkpoint(self) -> None:
1443
+ """Between steps: stop when closing, wait while paused."""
1444
+ with self._condition:
1445
+ closing, paused = self._closing, self._pause
1446
+ if closing:
1447
+ raise Closed()
1448
+ if paused:
1449
+ self._wait(PAUSED, lambda: not self._pause or bool(self._inbox))
1450
+ with self._condition:
1451
+ self._pause = False
1452
+ self._handed_back()
1453
+
1454
+ def _handed_back(self) -> None:
1455
+ """After a pause the computer is the agent's again as it is now: what the user did
1456
+ meanwhile is not their using it under the agent's hand (the worker's hand_back,
1457
+ where its profile says it has one)."""
1458
+ episode, profile = getattr(self, "episode", None), getattr(self, "profile", None) or {}
1459
+ if self.env is None or episode is None or not profile.get("hand_back"):
1460
+ return
1461
+ try:
1462
+ self.env.call("hand_back", episode_id=episode)
1463
+ except (ValueError, RuntimeError, OSError):
1464
+ pass
1465
+
1466
+ def _await_input(self) -> None:
1467
+ """Wait for missing task input, without starting a new turn or renewing its budget."""
1468
+ self.waiting_since = time.time()
1469
+ try:
1470
+ self._wait(IDLE, lambda: bool(self._inbox) or bool(self._pending_events), reason="message")
1471
+ finally:
1472
+ self.waiting_since = None
1473
+ self.reason = "user"
1474
+
1475
+ def _add_user_messages(self) -> None:
1476
+ """Put the user's messages into the next request: into the user message that
1477
+ ends the history, or as a new one after a reply."""
1478
+ pending = self._take_inbox()
1479
+ if not pending:
1480
+ return
1481
+ parts = _inbox_parts(pending)
1482
+ if self.messages[-1]["role"] == "user":
1483
+ self._extend_request(parts)
1484
+ else:
1485
+ self._tell(parts)
1486
+
1487
+ def _tell(self, content) -> None:
1488
+ """Add a user message to the history: what the program of the last used reply
1489
+ to a call made while it ran reported (self._carry) first, then `content`."""
1490
+ carry, self._carry = self._carry, []
1491
+ if carry:
1492
+ content = carry + ([{"type": "input_text", "text": content}] if isinstance(content, str) else list(content))
1493
+ self.messages.append({"role": "user", "content": content})
1494
+
1495
+ def _with_what_was_said(self, request, messages):
1496
+ """Interactive: when the window leaves earlier turns out, the first message of the
1497
+ request still lists everything the user said (they hold the task)."""
1498
+ if not self.interactive or len(request) >= len(messages) or len(self._said) < 2:
1499
+ return request
1500
+ text = "The user's messages so far, oldest first:\n" + "\n".join(
1501
+ f"{number}. {said}" for number, said in enumerate(self._said, 1))
1502
+ first = dict(request[0])
1503
+ first["content"] = (list(first["content"]) + [{"type": "input_text", "text": text}]
1504
+ if isinstance(first["content"], list) else f"{first['content']}\n{text}")
1505
+ return [first] + request[1:]
1506
+
1507
+ def seconds_left(self) -> float:
1508
+ """What the episode has left of its wall time (max_wall_seconds): the time it ran,
1509
+ less the time it waited for the user, counts; the whole budget before it starts."""
1510
+ started = getattr(self, "started", None)
1511
+ ran = time.perf_counter() - started - self._waited if started is not None else 0.0
1512
+ return float(self.config.max_wall_seconds) - ran
1513
+
1514
+ def _cell_timeout(self, *, policy=False) -> float:
1515
+ """The program's declared deadline, bounded by the episode."""
1516
+ seconds = self.seconds_left()
1517
+ configured = self.config.runtime.get("cell_timeout_seconds")
1518
+ if configured is not None and not policy:
1519
+ seconds = min(seconds, float(configured))
1520
+ return max(0.01, seconds)
1521
+
1522
+ def _program_deadline(self, number, episode_deadline):
1523
+ with self._condition:
1524
+ if self._cell_running and not self._program_completing and self.summary["cells"] == number:
1525
+ if episode_deadline:
1526
+ self._wall_up = True
1527
+ self.kernel.pause()
1528
+ else:
1529
+ self._program_timed_out = True
1530
+ self._stop_program_for_decision()
1531
+
1532
+ def _stuck(self, program: str, result: dict) -> None:
1533
+ """Interactive: note the same program, or the same unhandled event, three times
1534
+ in a row (after OpenHands' stuck detector). Only noted; nothing changes."""
1535
+ escalation = result.get("escalation") or {}
1536
+ key = (program.strip(), None) if not escalation else (None, (escalation.get("skill"),
1537
+ escalation.get("event", {}).get("kind")))
1538
+ self._recent = (getattr(self, "_recent", []) + [key])[-3:]
1539
+ if len(self._recent) == 3 and len(set(self._recent)) == 1:
1540
+ self.trace.emit("stuck", repeated="program" if key[0] else "event",
1541
+ what=key[0][:200] if key[0] else list(key[1]))
1542
+ self._recent = []
1543
+
1544
+ def run(self) -> dict:
1545
+ """Run the episode to its end and return its summary (status, evaluator outcome,
1546
+ model calls, tokens, cost, times), also written with the trace and manifest under
1547
+ the directory. An error ends the episode with status "error" instead of raising."""
1548
+ from harness.runtime.decision.model import USAGE, ChatModel
1549
+ from harness.config.agent import image_roles, model_services
1550
+
1551
+ config, seed, directory, trace = self.config, self.seed, self.directory, self.trace
1552
+ snapshot = config.snapshot()
1553
+ extra = ({"interactive": {"confirmation": self.confirmation, "instruction": self.instruction}}
1554
+ if self.interactive else {})
1555
+ if self.parent is not None:
1556
+ extra["agent"] = {**(self.identity or {}), "depth": self.depth, "workspace": self.workspace_kind,
1557
+ "budget": {"calls": config.max_model_calls, "cost": config.max_cost_usd,
1558
+ "seconds": config.max_wall_seconds}}
1559
+ write_json(directory / "manifest.json", {
1560
+ "schema_version": 1, "kind": "program", "config": snapshot,
1561
+ "config_sha256": sha256(snapshot), "seed": seed, "provenance": provenance(), **extra,
1562
+ })
1563
+ runtime = config.runtime
1564
+ embodiment = config.embodiment
1565
+ told = EMBODIMENT_TEXT[embodiment]
1566
+ roles = {"main": config.main, "verifier": config.verifier}
1567
+ skills = self._skills
1568
+ summary = self.summary = {
1569
+ "run": str(directory), "task": config.task, "seed": seed, "status": "error",
1570
+ "success": False, "reward": None, "process_score": None, "steps": 0,
1571
+ "model_calls": 0, "verifier_calls": 0, "cells": 0, **USAGE, "agent_seconds": 0.0,
1572
+ "kernel_seconds": 0.0,
1573
+ # Why the high level was called (Sec. 3.2: at the start and when an event
1574
+ # reaches it), and what the lower layers resolved without it.
1575
+ "decisions": {}, "events_handled": 0, "events_escalated": 0,
1576
+ "vision_calls": 0, "vision_cost_usd": 0.0, "guard_triggers": 0}
1577
+ self.started = time.perf_counter()
1578
+ self._set_status(RUNNING)
1579
+ token = None
1580
+ try:
1581
+ self.chat = self.chat or ChatModel(config.main)
1582
+ if runtime.get("verifier", True):
1583
+ self.verifier = self.verifier or ChatModel({**config.main, **config.verifier})
1584
+ env = self.env = self.env or RemoteEnvironment(
1585
+ config.environment["endpoint"], timeout=float(config.environment.get("timeout_seconds", 600)))
1586
+ env.tools()
1587
+ with self._span("env", "reset", task=config.task, seed=seed):
1588
+ observation = env.reset(config.task, seed)
1589
+ self.episode = observation.episode_id
1590
+ token = env.call("claim_outcome", episode_id=self.episode)["token"]
1591
+ # The embodiment profile is part of the frozen configuration (App. A).
1592
+ self.profile = {key: value for key, value in env.call("profile").items()
1593
+ if key not in ("task", "step_limit", "fk_check_error_m")}
1594
+ # The skills, prompt and session were chosen for one embodiment kind; the worker
1595
+ # says which it drives.
1596
+ if embodiment_kind(self.profile) != embodiment:
1597
+ raise RuntimeError(f"The worker drives a {embodiment_kind(self.profile)} embodiment; this "
1598
+ f"configuration was resolved for a {embodiment} one")
1599
+ if (expected := runtime.get("knowledge")) is not None:
1600
+ benchmark = self.profile.get("benchmark")
1601
+ # A bench that exposes this worker setting requires it in the profile,
1602
+ # including when an older external worker omits it.
1603
+ reports_knowledge = ("knowledge" in self.profile or
1604
+ (benchmark in bench_names() and "knowledge" in bench_spec(benchmark).worker))
1605
+ if reports_knowledge and self.profile.get("knowledge") != expected:
1606
+ raise RuntimeError(f"The worker must report knowledge={expected!r}; got "
1607
+ f"{self.profile.get('knowledge')!r}. Start a matching worker.")
1608
+ if self.parent is None:
1609
+ self.working_memory.declare(self.profile.get("world"), self._memory_record)
1610
+ frame = observation.state.get("memory_frame")
1611
+ if frame is not None:
1612
+ self._memory_request({"action": "observe", "wait": False, **frame})
1613
+ library = self._learner().library if runtime.get("library") else None
1614
+ learning = self._learning()
1615
+ self._trial_at_boundary(replay=True)
1616
+ self._checkpoint()
1617
+ startup = self._startup_library(learning) if library is not None else None
1618
+ if startup is not None:
1619
+ for item in startup.entries:
1620
+ item.save(directory)
1621
+ manifest = startup.manifest()
1622
+ manifest["revisions"] = {item.key: item.revision for item in startup.entries}
1623
+ config.runtime = runtime = {**runtime, "library": {**runtime["library"],
1624
+ "manifest": {**manifest, **({"learns": True} if learning else {})}}}
1625
+ trace.emit("library", action="opened", version=startup.version, revision_schema=1, revisions=manifest["revisions"],
1626
+ entries=[item for item in library_view.library_entries(startup, sections=SECTIONS)
1627
+ if not executable(item["id"])])
1628
+ run_manifest = {"schema_version": 1, "kind": "program", "config": snapshot,
1629
+ "config_sha256": sha256(snapshot), "embodiment_profile": self.profile,
1630
+ "embodiment_sha256": sha256(self.profile), "seed": seed,
1631
+ "provenance": provenance(), **extra}
1632
+ write_json(directory / "manifest.json", run_manifest)
1633
+ # The instruction it was given in place of the task's, for the frontends to show.
1634
+ trace.emit("reset", observation=observation.to_dict(),
1635
+ **({"instruction": self.instruction} if self.instruction else {}))
1636
+ if self.profile.get("physical"):
1637
+ # Whose steps these are, and the run's physical-input policy, for the worker.
1638
+ identity, policy = self.identity or {}, dict(runtime.get("physical") or {})
1639
+ seen = dict(runtime.get("privacy") or {})
1640
+ env.call("physical", op="identify", episode_id=self.episode, session=identity.get("session"),
1641
+ agent=identity.get("agent"), level=policy.get("level"), rules=policy.get("rules") or [],
1642
+ interactive=self.interactive,
1643
+ **({"privacy": {key: seen[key] for key in ("level", "rules") if seen.get(key)}}
1644
+ if seen else {}))
1645
+ if self._managed_workspace is not None:
1646
+ self._managed_dispatcher = self._managed_workspace.dispatcher(self, self.workspace_kind)
1647
+ operations = ", ".join(self._managed_dispatcher.options()["operations"])
1648
+ scope = f"\nThis isolated workspace exposes only these synchronous operations: {operations}.\n"
1649
+ config.system_prompt += scope
1650
+ config.base_prompt += scope
1651
+ self.kernel = Kernel(DEFAULT_BOOTSTRAP, {}, managed=self._managed_dispatcher,
1652
+ managed_launcher=self._managed_workspace.program_command,
1653
+ log_path=directory / "kernel.log", start_timeout=30)
1654
+ else:
1655
+ # (The verifier is asked through the conversation, a thought: control.think.)
1656
+ services = model_services(runtime, roles)
1657
+ image_clients = {role: {key: value for key, value in client.items() if key in ("class", "point_format")}
1658
+ if client else None for role, client in image_roles(services).items()}
1659
+ kernel_services = {key: value for key, value in services.items()
1660
+ if key not in ("vlm", "pointer", "verifier", "mcp")}
1661
+ self.kernel = Kernel(runtime.get("bootstrap", DEFAULT_BOOTSTRAP), {
1662
+ "endpoint": config.environment["endpoint"], "episode_id": self.episode, "embodiment": embodiment,
1663
+ "reactive_budget_ms": runtime.get("reactive_budget_ms", 5.0),
1664
+ "reaction_delay_ms": float(runtime.get("reaction_delay_ms") or 0.0),
1665
+ "observer": dict(runtime.get("observer") or {}),
1666
+ "default_max_seconds": runtime.get("default_max_seconds", 30.0),
1667
+ "host_thoughts": True,
1668
+ # The model looks itself (look, watch) unless the configuration declares
1669
+ # a standing watch (runtime.cameras).
1670
+ **({} if self._standing else {"views": {"mode": "demand", "cameras": list(told["cameras"])}}),
1671
+ **({"host_controls": sorted(env.host_controls), "timeout_seconds": env.timeout}
1672
+ if getattr(env, "approval_key", None) and env.host_controls else {}),
1673
+ "skills": skills,
1674
+ **kernel_services, **image_clients,
1675
+ "memory": self._recall_library,
1676
+ # App. A: programs see only the Python installation and the harness source,
1677
+ # and reach only the services named here (runtime/safety/isolation.py).
1678
+ "isolation": runtime.get("isolation", True),
1679
+ "strategy_first": bool(runtime.get("strategy_first", False)),
1680
+ "policy_progress_seconds": float(runtime.get("policy_progress_seconds") or 0.0),
1681
+ # Skills the user installed in the app, for read_skill (skills/instructions).
1682
+ **({"agent_skills": runtime["agent_skills"]} if runtime.get("agent_skills") else {}),
1683
+ # A game the agent learns itself: none of its handwritten skills is loaded.
1684
+ **({"knowledge": runtime["knowledge"]} if runtime.get("knowledge") else {}),
1685
+ # The library and whether this run learns (skills/learning, runtime/learning/learner.py).
1686
+ **({"library": {"directory": str(library.directory), "settings": learning or {"learn": "off"}}}
1687
+ if library is not None else {}),
1688
+ # The practice sandbox: an active run's only (runtime/learning/active.py, the bench's [sandbox]).
1689
+ **({"sandbox": sandbox_of(runtime)} if sandbox_of(runtime) else {}),
1690
+ # The worker's private files (a game's instance): never a program's.
1691
+ **({"private_paths": self.profile["private_paths"]} if self.profile.get("private_paths") else {}),
1692
+ }, python=kernel_python(runtime), cwd=str(self.program_directory) if self.program_directory else None,
1693
+ log_path=directory / "kernel.log",
1694
+ on_span=self._kernel_span)
1695
+ if self.profile.get("private_paths"):
1696
+ trace.emit("private_paths", paths=list(self.profile["private_paths"]), guarded=self.kernel.private)
1697
+ holdings = ""
1698
+ if startup is not None:
1699
+ self._library_version = startup.version
1700
+ index = startup.index
1701
+ selected = [(item, index.get(item.key) or {}) for item in startup.entries
1702
+ if executable(item.key) and self._library_eligible(
1703
+ item, index.get(item.key) or {}, startup.layers, startup.load)]
1704
+ self._activate_library(selected, startup=True)
1705
+ self._library_prompt = startup.api_summary(self._active_library)
1706
+ config.system_prompt = config.base_prompt + self._library_prompt + startup.notes()
1707
+ holdings = self._startup_holdings()
1708
+ snapshot = config.snapshot()
1709
+ snapshot["startup_holdings"] = holdings
1710
+ snapshot["active_library"] = {key: item.revision for key, (item, _) in self._active_library.items()}
1711
+ write_json(directory / "manifest.json", {**run_manifest, "config": snapshot,
1712
+ "config_sha256": sha256(snapshot)})
1713
+ self.cameras = runtime.get("cameras", list(told["cameras"]))
1714
+ if self._managed_workspace is not None:
1715
+ # A managed workspace's programs reach only its listed operations: its views
1716
+ # come with every turn, as before.
1717
+ self._standing = True
1718
+ instruction = self.instruction or observation.instruction
1719
+ from harness.runtime.learning import active
1720
+
1721
+ if active.is_active(runtime):
1722
+ # The active trigger: this run learns the environment for the task (runtime/learning/active.py).
1723
+ instruction = active.goal(instruction, active.schedule(runtime.get("library"))["minutes"],
1724
+ runtime.get("skills") or (), sandbox_of(runtime),
1725
+ legacy_memory="legacy_memory" in EMBODIMENT_KINDS[embodiment].prompt_features)
1726
+ self._said.insert(0, instruction)
1727
+ opening = f"Instruction: {instruction}\n"
1728
+ if config.task_description:
1729
+ opening += f"\nTask description:\n{config.task_description}\n\n"
1730
+ # What the library holds, from the first call on.
1731
+ opening += holdings
1732
+ if self._standing:
1733
+ first = image_parts(observation.images, self.cameras)
1734
+ else:
1735
+ # Text only: the views are named, and the model looks when it needs one.
1736
+ first = []
1737
+ if self.cameras:
1738
+ opening += (f"Views of this environment: {', '.join(self.cameras)}. None is shown until a "
1739
+ "program looks: look().\n")
1740
+ self.messages = [{"role": "user", "content": [
1741
+ {"type": "input_text",
1742
+ "text": opening + f"{told['state_label']}: "
1743
+ f"{state_text(observation.state, embodiment, self._steps_shown())}"},
1744
+ *first]}]
1745
+ summary["status"] = "budget_exhausted"
1746
+ self._loop(skills, told)
1747
+ except Closed:
1748
+ # Finished, closed by the user, or a sub-agent's budget ran out: the benchmark's
1749
+ # convention ends it.
1750
+ summary["status"] = "closed"
1751
+ if self.kernel is not None:
1752
+ _wrap_up(self.kernel, trace)
1753
+ except KeyboardInterrupt:
1754
+ summary["status"] = "interrupted"
1755
+ trace.emit("interrupted")
1756
+ raise
1757
+ except Exception as error:
1758
+ summary["status"] = "error"
1759
+ summary["error"] = f"{type(error).__name__}: {error}"
1760
+ trace.emit("error", message=summary["error"])
1761
+ finally:
1762
+ self._close_episode(token)
1763
+ return summary
1764
+
1765
+ def _loop(self, skills, told) -> None:
1766
+ try:
1767
+ self._steps(skills, told)
1768
+ finally:
1769
+ with self._condition:
1770
+ if self._request is not None:
1771
+ self._settle(self._request, "unused", "the episode or the turn ended first")
1772
+ self._request = None
1773
+
1774
+ def _steps(self, skills, told) -> None:
1775
+ """The loop: a thought on the trigger of what happened last (self.reason), then what
1776
+ its reply's output does (OUTPUTS), until an output, a budget or the episode ends it."""
1777
+ config, trace, summary, runtime = self.config, self.trace, self.summary, self.config.runtime
1778
+ self._logged = 0
1779
+ direct = runtime.get("mode", "program") == "direct"
1780
+ post_calls = runtime.get("post_policy_calls")
1781
+ # What the outputs share in this loop. Direct control: the agent's action vocabulary
1782
+ # turns each <action> into a program (runtime.actions, "module:function"). turns: history
1783
+ # turns sent to the model, lowered after the model server runs out of memory.
1784
+ # malformed_from: the first reply without a valid block since the last valid one (such
1785
+ # exchanges leave the history once a valid reply comes). nudged: replies in a row sent
1786
+ # back for only announcing an action (ANNOUNCED); empties: empty replies in a row asked
1787
+ # again (EMPTY_RETRIES). post_calls: the model's calls after the learned policy's first
1788
+ # run are bounded (finishing with its own tools cost half the spend for no score), from
1789
+ # post_from on; then the policy runs on.
1790
+ loop = SimpleNamespace(skills=skills, told=told, direct=direct, kinds=DIRECT_KINDS if direct else KINDS,
1791
+ actions=_object(runtime["actions"]) if direct else None,
1792
+ turns=runtime.get("max_history_turns"), malformed_from=None, nudged=0, empties=0,
1793
+ post_calls=None if post_calls is None else int(post_calls), post_from=None)
1794
+ self.reason = "start"
1795
+ # Iterations of the loop in this turn (an interactive episode starts one with every
1796
+ # message of the user).
1797
+ with self._condition:
1798
+ self._iterations = 0
1799
+ while True:
1800
+ self._checkpoint()
1801
+ self._load_due_skills()
1802
+ with self._condition:
1803
+ selected = tuple(self._activation_queue.values())
1804
+ self._activate_library(selected)
1805
+ self._trial_at_boundary()
1806
+ self._checkpoint()
1807
+ learning_report = self._learning_report()
1808
+ with self._condition:
1809
+ current = self._request
1810
+ if current is not None and current.cancelled:
1811
+ if "deadline" in str(current.error):
1812
+ raise current.error
1813
+ if current.program is not None and self._carry:
1814
+ self._tell([])
1815
+ self._request = current = None
1816
+ if current is None:
1817
+ if self._iterations >= config.max_model_calls:
1818
+ break
1819
+ if (loop.post_from is not None and loop.post_calls is not None
1820
+ and summary["model_calls"] - loop.post_from >= loop.post_calls and not self._inbox):
1821
+ break_for_policy = True
1822
+ else:
1823
+ break_for_policy = False
1824
+ if self.seconds_left() <= 0:
1825
+ summary["status"] = "wall_time_exhausted"
1826
+ break
1827
+ if not self._ahead_allowed():
1828
+ summary["status"] = "cost_exhausted"
1829
+ break
1830
+ if not break_for_policy:
1831
+ current = self._think("between", loop.turns, learning_report=learning_report)
1832
+ else:
1833
+ break_for_policy = False
1834
+ if not break_for_policy:
1835
+ self._condition.wait_for(lambda: current.back(0) or self._closing)
1836
+ if self._closing:
1837
+ raise Closed()
1838
+ if current.cancelled:
1839
+ if isinstance(current.error, ThoughtCancelled) and "deadline" in str(current.error):
1840
+ raise current.error
1841
+ continue
1842
+ self._request = None
1843
+ reply, loop.turns = current.wait(), current.turns
1844
+ if current.program is not None:
1845
+ if self._completed_decision(current, loop.kinds):
1846
+ continue
1847
+ used = {"ahead": "used"} if current.trigger == "ahead" else {}
1848
+ else:
1849
+ used = {}
1850
+ self._settle(current, "used")
1851
+ self._pending_events.clear()
1852
+ loop.revision = current.revision
1853
+ loop.assumption = getattr(current, "assumption", None)
1854
+ loop.ahead_generation = current.ahead_generation if current.trigger == "ahead" else None
1855
+ loop.call, loop.thought = current.call, current.id
1856
+ if break_for_policy:
1857
+ self._policy_to_end()
1858
+ break
1859
+ output, parsed = self._output(reply, used, loop)
1860
+ if getattr(self, decisions.OUTPUTS["between"][output])(reply, parsed, loop) == "end":
1861
+ break
1862
+
1863
+ def _completed_decision(self, thought, kinds):
1864
+ """A real request outlives program completion. Replan only if its reply depended on it."""
1865
+ if thought.trigger == "ahead":
1866
+ return False
1867
+ if thought.stopped:
1868
+ result = thought.program_result
1869
+ event = (result.get("escalation") or {}).get("event", {}).get("kind")
1870
+ if result["status"] in ("ok", "finished") or event == "USER_MESSAGE":
1871
+ return False
1872
+ parsed, prose = decisions._running_reply(thought.reply.text, kinds)
1873
+ if prose and thought.trigger == "message":
1874
+ return False
1875
+ if parsed is not None and parsed.kind != "wait" and not decisions._STOP.search(thought.reply.text):
1876
+ if parsed.kind not in ("python", "action") or (parsed.kind == "python" and decisions._beside(parsed.body)):
1877
+ return False
1878
+ self._settle(thought, "waited", "the decision needs the completed program result")
1879
+ self._pending_events.clear()
1880
+ if self._carry:
1881
+ self._extend_request(self._carry)
1882
+ self._carry = []
1883
+ return True
1884
+
1885
+ def _output(self, reply, used: dict, loop) -> tuple[str, object]:
1886
+ """What a reply between programs does (a key of OUTPUTS) and its parsed block (or the
1887
+ error that kept it from parsing); the reply joins the trace and the history."""
1888
+ summary, trace, messages = self.summary, self.trace, self.messages
1889
+ if (not used and not reply.text.strip() and reply.usage.get("finish_reason") != "length"
1890
+ and loop.empties < decisions.EMPTY_RETRIES):
1891
+ return "empty", None
1892
+ loop.empties = 0
1893
+ # An empty reply is a format error after EMPTY_RETRIES, never a message.
1894
+ plain = (self.interactive and reply.usage.get("finish_reason") != "length"
1895
+ and bool(reply.text.strip()) and not looks_like_action(reply.text))
1896
+ # A plain reply that only announces the next step ("I'll open the page ...") is
1897
+ # sent back as a format error.
1898
+ announced = plain and loop.nudged < decisions.ANNOUNCED_TIMES and announces(reply.text)
1899
+ plain = plain and not announced
1900
+ loop.nudged = loop.nudged + 1 if announced else 0
1901
+ try:
1902
+ if reply.usage.get("finish_reason") == "length":
1903
+ raise ProtocolError("The reply was truncated; nothing ran")
1904
+ parsed = parse_reply(reply.text, loop.kinds)
1905
+ parsed.program = (loop.actions(parsed.body, allow_policy="vla" in loop.skills,
1906
+ allow_skills=bool(self.config.runtime.get("fixed_skills", False)))
1907
+ if parsed.kind == "action" else parsed.body)
1908
+ thought_text = decisions._STOP.sub("", parsed.thought or "")
1909
+ assumed = decisions._ASSUME.search(thought_text)
1910
+ presentation = {"kind": parsed.kind,
1911
+ "thought": (decisions._ASSUME.sub("", thought_text) if assumed else thought_text).strip(),
1912
+ "body": parsed.body,
1913
+ **({"assume": " ".join(assumed[1].split())} if assumed else {})}
1914
+ output = {"python": "program", "action": "program"}.get(parsed.kind, parsed.kind)
1915
+ except (ProtocolError, ValueError) as failed:
1916
+ parsed, output = failed, "message" if plain else "invalid"
1917
+ if announced:
1918
+ parsed = ProtocolError("The reply said what it would do, without a block")
1919
+ presentation = ({"kind": "message", "body": reply.text.strip(), "announced": True} if announced else
1920
+ {"kind": "message" if plain else "invalid", "body": reply.text.strip() if plain else ""})
1921
+ self._record_reply(reply, loop.call + 1, thought=loop.thought, presentation=presentation, **used)
1922
+ messages.append({"role": "assistant", "content": reply.text})
1923
+ if output == "invalid":
1924
+ if loop.malformed_from is None and not used:
1925
+ # (A used reply's exchange stays: its message holds its program's result.)
1926
+ loop.malformed_from = len(messages) - 1
1927
+ elif loop.malformed_from is not None:
1928
+ dropped = len(messages) - 1 - loop.malformed_from
1929
+ del messages[loop.malformed_from:-1]
1930
+ self._logged -= dropped
1931
+ trace.emit("malformed_dropped", messages=dropped)
1932
+ loop.malformed_from = None
1933
+ return output, parsed
1934
+
1935
+ # The outputs of a reply between programs (OUTPUTS): "end" ends the loop.
1936
+
1937
+ def _out_empty(self, reply, parsed, loop):
1938
+ """Reasoning only: asked again at once, with no format error to show."""
1939
+ loop.empties += 1
1940
+ self.summary["empty_replies"] = self.summary.get("empty_replies", 0) + 1
1941
+ self.trace.emit("empty_reply", call=self.summary["model_calls"], usage=reply.usage, seconds=reply.seconds,
1942
+ **({"reasoning": reply.reasoning} if reply.reasoning else {}))
1943
+ self.reason = "empty"
1944
+
1945
+ def _current_output(self, loop):
1946
+ return (not self._inbox and not self._pending_events and loop.revision == self._revision
1947
+ and (loop.ahead_generation is None or loop.ahead_generation == self._ahead_generation))
1948
+
1949
+ def _out_message(self, reply, parsed, loop):
1950
+ """A plain reply: the model talks to the user (or a sub-agent asks its parent)."""
1951
+ with self._condition:
1952
+ if not self._current_output(loop):
1953
+ return None
1954
+ self.question = reply.text.strip()
1955
+ # Keep the notification for task/inbox consumers, but identify the reply
1956
+ # already recorded by _output so transcript consumers do not show it twice.
1957
+ self.trace.emit("agent_message", text=reply.text.strip(), reply_call=loop.call + 1)
1958
+ self._await_input()
1959
+
1960
+ def _out_invalid(self, reply, parsed, loop):
1961
+ """A reply nothing came of: told why, and asked again."""
1962
+ if reply.usage.get("finish_reason") == "length":
1963
+ # The reply hit the output limit before its closing tag.
1964
+ text = (f"Your reply was cut off after {reply.usage.get('output_tokens')} tokens, before the "
1965
+ f"closing tag, so nothing ran. Write the program again more compactly: short "
1966
+ f"comments, helper functions for repeated steps.")
1967
+ elif str(parsed).startswith("The reply said what it would do"):
1968
+ who = "the agent that started you" if self.parent is not None else "the user"
1969
+ text = decisions.ANNOUNCED.format(block="<action>" if loop.direct else "<python>", who=who)
1970
+ else:
1971
+ blocks = "<action> or <finish>" if loop.direct else "<python>, <verify>, or <finish>"
1972
+ text = (f"Format error: {parsed}. Nothing ran. Reply with the {blocks} block itself, starting with its "
1973
+ "opening tag.")
1974
+ self._tell(text)
1975
+ self.trace.emit("protocol_error", message=str(parsed), truncated=reply.usage.get("finish_reason") == "length",
1976
+ **({"announced": True} if text.startswith("Nothing ran") else {}))
1977
+ self.reason = "format"
1978
+
1979
+ def _out_finish(self, reply, parsed, loop):
1980
+ """The task is done: the reply's <finish>, or a program's finish() (source "program")."""
1981
+ source = getattr(parsed, "source", None)
1982
+ if source is None:
1983
+ if loop.assumption is not None and not self._check_assumption(*loop.assumption):
1984
+ self._tell("The lookahead condition changed before the finish could be applied.")
1985
+ self.reason = "program_end"
1986
+ return None
1987
+ with self._condition:
1988
+ if not self._current_output(loop):
1989
+ return None
1990
+ from harness.runtime.learning.active import is_active
1991
+
1992
+ if is_active(self.config.runtime) and self._ahead_allowed():
1993
+ before = getattr(self, "_library_version", None)
1994
+ self._trial_at_boundary()
1995
+ if getattr(self, "_library_version", None) != before:
1996
+ self._tell("The host activated your proposal. Use the new revision in a brief practice program, "
1997
+ "check what it does, then finish with the result.")
1998
+ self.reason = "program_end"
1999
+ return None
2000
+ self.result = parsed.body.strip()
2001
+ self.trace.emit("finish", text=parsed.body, **({"source": source} if source else {}))
2002
+ self.summary["status"] = "finished"
2003
+ _wrap_up(self.kernel, self.trace)
2004
+ return "end"
2005
+
2006
+ def _out_verify(self, reply, parsed, loop):
2007
+ """The verifier's answer on the reply's claim, with the views it judged."""
2008
+ with self._condition:
2009
+ if not self._current_output(loop):
2010
+ return None
2011
+ try:
2012
+ answer, view = self._verify(parsed.body)
2013
+ except ThoughtCancelled:
2014
+ with self._condition:
2015
+ if self._inbox or self._pending_events or self._closing:
2016
+ return None
2017
+ raise
2018
+ state = state_text(view["state"], self.config.embodiment, self._steps_shown())
2019
+ self._tell([{"type": "input_text", "text": f"Verifier: {answer}\n{loop.told['state_label']}: {state}"},
2020
+ *(image_parts(view["images"], self.cameras) if self._standing else [])])
2021
+ self.reason = "verify"
2022
+
2023
+ def _verify(self, claim, cameras=None, request=None):
2024
+ cameras = cameras if cameras is not None else self.cameras
2025
+ with self._span("env", "observe"):
2026
+ view = self.env.call("observe", episode_id=self.episode, cameras=cameras)
2027
+ if self.verifier is None:
2028
+ answer = "Verifier disabled in this configuration."
2029
+ elif self._standing:
2030
+ content = [{"type": "input_text", "text": f"Claim: {claim}"},
2031
+ *image_parts(view["images"], cameras)]
2032
+ reply = self._ask_role("verifier", self.verifier,
2033
+ EMBODIMENT_TEXT[self.config.embodiment]["verifier"],
2034
+ [{"role": "user", "content": content}], request)
2035
+ answer = reply.text.strip()
2036
+ else:
2037
+ # The verifier judges on what the model itself can get: the state, the structure
2038
+ # the environment reports as text, and its views (a verifier that reads images).
2039
+ told = EMBODIMENT_TEXT[self.config.embodiment]
2040
+ structure = (request or {}).get("evidence")
2041
+ if structure is None and request is None:
2042
+ structure = self._evidence()
2043
+ text = (f"Claim: {claim}\n{told['state_label']}: "
2044
+ f"{state_text(view['state'], self.config.embodiment, self._steps_shown())}"
2045
+ + (f"\nWhat the environment reports as text:\n{str(structure)[:12000]}" if structure else ""))
2046
+ images = image_parts(view["images"], cameras) if {**self.config.main, **self.config.verifier}.get(
2047
+ "images") is not False else []
2048
+ reply = self._ask_role("verifier", self.verifier, told["verifier"] + VERIFIER_EVIDENCE,
2049
+ [{"role": "user", "content": [{"type": "input_text", "text": text}, *images]}],
2050
+ request)
2051
+ answer = reply.text.strip()
2052
+ self.trace.emit("verify", claim=claim, answer=answer)
2053
+ return answer, view
2054
+
2055
+ def _evidence(self) -> str:
2056
+ """What the environment reports as text for a claim (its session's __evidence__: a
2057
+ window's elements, a page's text), read between programs; empty when it has none."""
2058
+ kernel = self.kernel
2059
+ if kernel is None or self._cell_running:
2060
+ return ""
2061
+ try:
2062
+ result = kernel.run("__evidence__()", timeout=30)
2063
+ except Exception:
2064
+ return ""
2065
+ return (result.get("stdout") or "").strip() if result.get("status") == "ok" else ""
2066
+
2067
+ def _ask_role(self, role, chat, system, messages, request=None):
2068
+ request = request or {}
2069
+ origin = request.get("id")
2070
+ with self._condition:
2071
+ if origin in self._cancelled_origins or request.get("revision", self._revision) != self._revision:
2072
+ raise ThoughtCancelled("The calling entry stopped")
2073
+ if self.config.max_cost_usd is not None and (
2074
+ self.summary["cost_usd"] + self.agents_usage["cost_usd"] >= self.config.max_cost_usd):
2075
+ raise RuntimeError("The session model cost budget is exhausted")
2076
+ if origin is not None and role != "observer":
2077
+ current = self._request
2078
+ if current is not None and current.trigger == "ahead":
2079
+ self._settle(current, "discarded", "program requested a model result")
2080
+ thought = Thought(role, decisions.TRIGGERS["request"][role], chat, system, messages,
2081
+ timeout=max(0, self.seconds_left()), program=self.summary["cells"] if self._cell_running else None,
2082
+ revision=self._revision, origin=origin,
2083
+ owner={**self._who().get("who", {}), "entry": request.get("entry"),
2084
+ "frame": request.get("frame")})
2085
+ self._thoughts.submit(thought)
2086
+ return thought.wait()
2087
+
2088
+ def _thought_request(self, request):
2089
+ """Answer the calling entry without holding the kernel reader or worker tick."""
2090
+ role = request.get("role")
2091
+ try:
2092
+ if role == "verifier":
2093
+ if self.verifier is None:
2094
+ value = None
2095
+ else:
2096
+ text, _ = self._verify(str(request.get("claim") or request.get("text")),
2097
+ request.get("cameras"), request)
2098
+ value = {"text": text}
2099
+ elif role in ("observer", "vlm", "pointer"):
2100
+ content = [*({"type": "input_image", "image_url": image, "detail": "auto"}
2101
+ for image in request.get("images") or ()),
2102
+ {"type": "input_text", "text": str(request.get("text") or "")}]
2103
+ reply = self._ask_role(role, self._role_chat(role), str(request.get("system") or ""),
2104
+ [{"role": "user", "content": content}], request)
2105
+ value = {"text": reply.text, "usage": reply.usage, "seconds": reply.seconds}
2106
+ else:
2107
+ raise ValueError(f"Unknown program model role: {role!r}")
2108
+ answer = {"value": value}
2109
+ except Exception as error:
2110
+ answer = {"error": f"{type(error).__name__}: {error}"}
2111
+ if self.kernel is not None:
2112
+ self.kernel.answer(request["id"], {"thought": True, **answer})
2113
+
2114
+ def _role_chat(self, role):
2115
+ from harness.runtime.decision.model import ChatModel
2116
+
2117
+ if role == "verifier":
2118
+ return self.verifier
2119
+ field = "vlm" if role == "observer" else role
2120
+ config = self.config.runtime.get(field)
2121
+ if not isinstance(config, dict) or not config.get("model"):
2122
+ raise RuntimeError(f"No model is configured for {role}")
2123
+ config = {key: value for key, value in config.items() if key not in ("point_format", "class")}
2124
+ extra = {"max_image_side": 0} if config.get("backend") == "openai_chat" else {}
2125
+ if role == "observer":
2126
+ observer = self.config.runtime.get("observer") or {}
2127
+ config.update(reasoning_effort=observer.get("reasoning_effort", "none"),
2128
+ max_output_tokens=int(observer.get("max_output_tokens", 1200)))
2129
+ return ChatModel({"max_output_tokens": 1024, "temperature": 0.0, "extra_body": extra, **config})
2130
+
2131
+ def _policy_to_end(self) -> None:
2132
+ """The model's calls after the learned policy's run are used up: it runs on to the end."""
2133
+ trace, summary, kernel = self.trace, self.summary, self.kernel
2134
+ with self._span("program", "policy to the end"):
2135
+ result = kernel.run("__policy_to_end__()", timeout=self._cell_timeout(policy=True))
2136
+ trace.emit("policy_to_end", status=result["status"], error=result.get("error"))
2137
+ _cell_usage(summary, result)
2138
+ if result.get("strategy"):
2139
+ summary["strategy"] = result["strategy"]
2140
+ if result["status"] == "episode_ended":
2141
+ summary["status"] = "episode_ended"
2142
+ else:
2143
+ trace.emit("finish", text="the model's calls after the policy's run were used up", source="harness")
2144
+ summary["status"] = "finished"
2145
+ _wrap_up(kernel, trace)
2146
+
2147
+ def _out_program(self, reply, parsed, loop):
2148
+ """Run the reply's program, with the thoughts its triggers start while it runs; then
2149
+ what it did is the next thought's news."""
2150
+ config, trace, summary, kernel, env = self.config, self.trace, self.summary, self.kernel, self.env
2151
+ program, embodiment, cameras = parsed.program, config.embodiment, self.cameras
2152
+ if not self._approved(program):
2153
+ return None
2154
+ self._load_due_skills()
2155
+ if loop.assumption is not None and not self._check_assumption(*loop.assumption):
2156
+ self._tell("The lookahead condition changed before the program could start.")
2157
+ self.reason = "program_end"
2158
+ return None
2159
+ with self._condition:
2160
+ waiting = self._pause or self._closing
2161
+ if waiting:
2162
+ # Paused (or closed) while the model was answering: the program waits. It
2163
+ # runs after a plain resume; a message from the user replaces it.
2164
+ trace.emit("program_held")
2165
+ self._checkpoint()
2166
+ with self._condition:
2167
+ if not self._current_output(loop):
2168
+ trace.emit("program_dropped", reason="user_message" if self._inbox else "inputs_changed")
2169
+ self._tell("The user paused before this program ran, so nothing ran." if waiting
2170
+ else "A user message came before this program ran, so nothing ran.")
2171
+ self.reason = "user"
2172
+ return None
2173
+ summary["cells"] += 1
2174
+ number, policy_ran = summary["cells"], loop.post_from is not None
2175
+ self._kinds, self._turns = loop.kinds, loop.turns
2176
+ self._request = None
2177
+ self._ahead_due = time.monotonic() + decisions.AHEAD_SECONDS if self.ahead != "off" and not policy_ran else None
2178
+ self._cell_running = True
2179
+ self._budget_stop = self._program_timed_out = False
2180
+ self._thoughts.wake()
2181
+ if self._pause or self._closing:
2182
+ kernel.pause()
2183
+ before = time.perf_counter()
2184
+ remaining = self._cell_timeout()
2185
+ limit = config.runtime.get("cell_timeout_seconds")
2186
+ episode_deadline = limit is None or float(limit) >= self.seconds_left()
2187
+ deadline = threading.Timer(remaining, self._program_deadline, (number, episode_deadline))
2188
+ deadline.daemon = True
2189
+ deadline.start()
2190
+ try:
2191
+ with self._span("program", f"program {number}") as end:
2192
+ result = kernel.run(program, timeout=remaining + 60.0)
2193
+ end.update(status=result["status"])
2194
+ except KernelDied as error:
2195
+ summary["kernel_seconds"] += time.perf_counter() - before
2196
+ trace.emit("kernel_died", message=str(error))
2197
+ if self.seconds_left() > 0:
2198
+ raise
2199
+ summary["status"] = "wall_time_exhausted"
2200
+ return "end"
2201
+ finally:
2202
+ deadline.cancel()
2203
+ with self._condition:
2204
+ self._cell_running = False
2205
+ self._program_completing = True
2206
+ self._ahead_due = None
2207
+ ahead = self._request
2208
+ if ahead is not None and ahead.trigger == "ahead" and not ahead.exited:
2209
+ self._settle(ahead, "discarded", "program ended before lookahead returned")
2210
+ self._condition.notify_all()
2211
+ summary["kernel_seconds"] += time.perf_counter() - before
2212
+ if self._program_timed_out and result["status"] not in ("episode_ended", "finished"):
2213
+ result = {**result, "status": "error", "error": result.get("error") or "Program deadline exceeded"}
2214
+ recorded = {k: v for k, v in result.items() if k not in ("attachments", "report")}
2215
+ if result.get("report"):
2216
+ recorded["report"] = {"text": result["report"].get("text", ""),
2217
+ "images": sorted(result["report"].get("images") or {})}
2218
+ trace.emit("cell", code=program, action=parsed.body if loop.direct else None, result=recorded,
2219
+ attachments=len(result.get("attachments", [])))
2220
+ if self.interactive:
2221
+ self._stuck(program, result)
2222
+ _cell_usage(summary, result)
2223
+ self.charge_up()
2224
+ if result.get("strategy"):
2225
+ summary["strategy"] = result["strategy"]
2226
+ if not policy_ran and result["strategy"].get("policy_ran"):
2227
+ loop.post_from = summary["model_calls"]
2228
+ if result["status"] == "episode_ended":
2229
+ summary["status"] = "episode_ended"
2230
+ return "end"
2231
+ if self._wall_up:
2232
+ # (Its USER_PAUSED was the wall time's.)
2233
+ self._wall_up = False
2234
+ summary["status"] = "wall_time_exhausted"
2235
+ return "end"
2236
+ finished = False
2237
+ with self._condition:
2238
+ if result["status"] == "finished":
2239
+ self.reason = "program_end"
2240
+ if ahead is not None and ahead.trigger == "ahead":
2241
+ self._settle(ahead, "discarded", "the program finished the task")
2242
+ self._request = ahead = None
2243
+ if ahead is None and not self._inbox and not self._pending_events:
2244
+ self._program_completing = False
2245
+ finished = True
2246
+ else:
2247
+ self.reason = {"escalated": "escalation", "error": "error"}.get(result["status"], "program_end")
2248
+ taken = _taken_over(result) if self.interactive else None
2249
+ calls_left = config.max_model_calls - self._iterations
2250
+ if finished:
2251
+ return self._out_finish(None, SimpleNamespace(body=str(result.get("finish") or ""),
2252
+ source="program"), loop)
2253
+ outcome, why = self._program_outcome(ahead, loop.kinds, result, taken)
2254
+ note = ("\nThe program ended without calling finish(). If the task is done, finish; otherwise "
2255
+ "write a program for the rest of the task." if self.reason == "program_end" and outcome != "used"
2256
+ else "")
2257
+ if loop.post_from is not None and loop.post_calls:
2258
+ calls_left = min(calls_left, loop.post_calls - (summary["model_calls"] - loop.post_from))
2259
+ note += ("\nAfter these calls the learned policy runs on by itself to the end of the episode."
2260
+ if calls_left > 0 else "")
2261
+ feedback = cell_feedback(result, number, self.profile.get("control_hz"), embodiment, self._steps_shown())
2262
+ if ahead is not None and ahead.stopped:
2263
+ feedback = f"Program {ahead.program} stopped for your decision.\n" + feedback
2264
+ content = [{"type": "input_text", "text": feedback + note
2265
+ + f"\nModel calls left: {calls_left}"}]
2266
+ for item in result.get("attachments", [])[:6]:
2267
+ content.append({"type": "input_text", "text": f"show(): {item['caption']}"})
2268
+ content.append({"type": "input_image", "image_url": item["image_url"], "detail": "auto"})
2269
+ if not taken and self.reason in ("error", "escalation") and not self._request:
2270
+ self._reflect_learning()
2271
+ if taken is not None:
2272
+ # The user brought a window of theirs to the front: the computer is theirs
2273
+ # until they hand it back, as after Take over.
2274
+ trace.emit("user_took_over", window=taken.get("front"))
2275
+ self.pause()
2276
+ self._checkpoint()
2277
+ if self._standing:
2278
+ with self._span("env", "observe"):
2279
+ view = env.call("observe", episode_id=self.episode, cameras=cameras)
2280
+ # A skill's report (the tracked scene) may outline objects in the same views.
2281
+ images = {**view["images"], **((result.get("report") or {}).get("images") or {})}
2282
+ content.extend(image_parts(images, cameras))
2283
+ else:
2284
+ # Only what the program looked at (look, a standing watch of the model's own).
2285
+ view = {"state": result.get("state") or {}}
2286
+ looks = list(result.get("looks") or ())
2287
+ outlined = (result.get("report") or {}).get("images") or {}
2288
+ looks = [{**item, "image_url": outlined[item["camera"]]}
2289
+ if item["camera"] in outlined and not item.get("region") else item for item in looks]
2290
+ with self._condition:
2291
+ self._view_pins |= {item["pin"] for item in looks if item.get("pin")}
2292
+ if looks:
2293
+ trace.emit("views", action="looked", program=number,
2294
+ views=[{key: item[key] for key in ("camera", "region", "pin") if key in item}
2295
+ for item in looks])
2296
+ content.extend(view_parts(looks) if self._images else self._described(looks))
2297
+ with self._condition:
2298
+ self._program_completing = False
2299
+ if ahead is not None and (ahead.cancelled or ahead.revision != self._revision) and outcome == "used":
2300
+ outcome, why = "discarded", "inputs changed before adoption"
2301
+ if outcome in ("used", "pending") and not ahead.cancelled:
2302
+ self._carry = content
2303
+ else:
2304
+ if ahead is not None and outcome in ("waited", "discarded"):
2305
+ self._settle(ahead, outcome, why)
2306
+ if ahead is not None and ahead.said:
2307
+ self.messages.append({"role": "assistant", "content": ahead.reply.text})
2308
+ if ahead is not None and ahead.side is not None:
2309
+ self.messages.append({"role": "assistant", "content": ahead.reply.text})
2310
+ content.insert(0, {"type": "input_text", "text": self._beside_report(ahead)})
2311
+ self._request = None
2312
+ self._tell(content)
2313
+ self._condition.notify_all()
2314
+ if view["state"].get("ended"):
2315
+ summary["status"] = "episode_ended"
2316
+ return "end"
2317
+ return None
2318
+
2319
+ def _program_outcome(self, thought, kinds, result, taken):
2320
+ if thought is None:
2321
+ return None, ""
2322
+ if thought.side is not None or thought.said:
2323
+ return "beside", ""
2324
+ if thought.cancelled or taken is not None:
2325
+ return "discarded", "the decision was superseded"
2326
+ if thought.trigger != "ahead":
2327
+ thought.program_result = result
2328
+ return "pending", ""
2329
+ if result["status"] != "ok" or not thought.exited or thought.error is not None:
2330
+ return "discarded", "lookahead needs a normal completion and a ready reply"
2331
+ reply = thought.reply
2332
+ if reply is None or reply.usage.get("finish_reason") == "length":
2333
+ return "discarded", "lookahead returned no complete reply"
2334
+ parsed, _ = decisions._running_reply(reply.text, kinds)
2335
+ if parsed is None or parsed.kind == "wait":
2336
+ return "waited", "lookahead deferred to the program result"
2337
+ condition = decisions._ASSUME.search(reply.text)
2338
+ if condition is None or decisions._STOP.search(reply.text):
2339
+ return "discarded", "lookahead requires a checkable completion condition"
2340
+ thought.assumption = (condition[1].strip(), result)
2341
+ if not self._check_assumption(*thought.assumption):
2342
+ return "discarded", "lookahead condition was false or could not be checked"
2343
+ return "used", ""
2344
+
2345
+ def _check_assumption(self, condition, result):
2346
+ """Evaluate a bounded expression over JSON data, never the program namespace."""
2347
+ try:
2348
+ tree = ast.parse(condition, mode="eval")
2349
+ nodes = list(ast.walk(tree))
2350
+ if len(nodes) > 64 or not all(isinstance(node, decisions._ASSUME_NODES) for node in nodes):
2351
+ return False
2352
+ names = {node.id for node in nodes if isinstance(node, ast.Name)}
2353
+ if not names <= {"result", "output", "state"} or not names:
2354
+ return False
2355
+ snapshot = json.loads(json.dumps({key: value for key, value in result.items()
2356
+ if key not in ("attachments", "report")}))
2357
+ state = (self.env.call("state", episode_id=self.episode) if "state" in names else None)
2358
+ values = {"result": snapshot, "output": snapshot.get("stdout") or "", "state": state}
2359
+ return bool(eval(compile(tree, "<assume>", "eval"), {"__builtins__": {}}, values))
2360
+ except Exception:
2361
+ return False
2362
+
2363
+ def _think(self, phase, turns, *, learning_report=""):
2364
+ """Select a decision from the table and queue its immutable input."""
2365
+ triggers = decisions.TRIGGERS[phase]
2366
+ now = time.monotonic()
2367
+ trigger = next((name for name, check in triggers.items() if check and getattr(self, check)(now)), None)
2368
+ running = phase == "running"
2369
+ if trigger is None:
2370
+ if running:
2371
+ return None
2372
+ trigger = self.reason
2373
+ if trigger not in triggers:
2374
+ raise ValueError(f"No model trigger for {trigger!r}")
2375
+
2376
+ number = self.summary["cells"] if running else None
2377
+ earlier = self._request
2378
+ if running and earlier is not None and (earlier.said or earlier.side is not None):
2379
+ self.messages.append({"role": "assistant", "content": earlier.reply.text})
2380
+ if earlier.side is not None:
2381
+ self._tell(self._beside_report(earlier))
2382
+ self._include_escalations()
2383
+ self._add_user_messages()
2384
+ if running:
2385
+ watched = []
2386
+ if trigger == "ahead":
2387
+ self._ahead_due = None
2388
+ text = decisions.AHEAD_RUNNING.format(number=number)
2389
+ elif trigger == "watch":
2390
+ watched, self._watched = self._watched or [], None
2391
+ text = decisions.WATCH_RUNNING.format(number=number)
2392
+ else:
2393
+ text = decisions.LOOK_RUNNING.format(number=number)
2394
+ if trigger == "message":
2395
+ text += " You may also answer the user in plain text."
2396
+ parts = [{"type": "input_text", "text": text},
2397
+ *(view_parts(watched) if self._images else self._described(watched) if watched else [])]
2398
+ if self.messages[-1]["role"] == "user":
2399
+ self._extend_request(parts)
2400
+ else:
2401
+ self._tell(parts)
2402
+
2403
+ config, summary, messages = self.config, self.summary, self.messages
2404
+ if self._standing:
2405
+ prune_images(messages, int(config.runtime.get("keep_images", 2)))
2406
+ else:
2407
+ prune_views(messages, self._view_keep, self._view_pins)
2408
+ request = self._with_what_was_said(window(messages, turns), messages)
2409
+ if not self._images:
2410
+ request = text_only(request)
2411
+ call = summary["model_calls"]
2412
+ from copy import deepcopy
2413
+ history = deepcopy(messages)
2414
+ system = config.system_prompt + learning_report
2415
+ thought = Thought("main", trigger, self.chat, system, request,
2416
+ timeout=max(0, self.seconds_left()), program=number, owner=self._who().get("who"),
2417
+ revision=self._revision, call=call, turns=turns,
2418
+ invoke=lambda item: self._complete(item, history))
2419
+ thought.ahead_generation = self._ahead_generation
2420
+ self.trace.emit("model_request", call=call, thought=thought.id, **decisions._model_of(thought.chat), reason=trigger,
2421
+ program=number, total_messages=len(messages), sent_messages=len(request),
2422
+ new_messages=history[self._logged:], context=context_summary(request, system),
2423
+ library_version=getattr(self, "_library_version", None), revision=thought.revision,
2424
+ events=list(self._pending_events),
2425
+ **({"message": True} if trigger == "message" else {}), **self._replaced())
2426
+ self._logged = len(messages)
2427
+ summary["model_calls"] += 1
2428
+ summary["decisions"][trigger] = summary["decisions"].get(trigger, 0) + 1
2429
+ self._iterations += 1
2430
+ self._request = thought
2431
+ self._thoughts.submit(thought)
2432
+ return thought
2433
+
2434
+ def _ahead_allowed(self, reserve=0):
2435
+ return (self._iterations + reserve < self.config.max_model_calls
2436
+ and (self.config.max_cost_usd is None
2437
+ or self.summary["cost_usd"] + self.agents_usage["cost_usd"] < self.config.max_cost_usd))
2438
+
2439
+ def _extend_request(self, parts):
2440
+ last = self.messages[-1]
2441
+ content = last["content"]
2442
+ if isinstance(content, str):
2443
+ content = [{"type": "input_text", "text": content}]
2444
+ last["content"] = [*content, *parts]
2445
+ if self._logged == len(self.messages):
2446
+ self._logged -= 1
2447
+ self._replaces = 1
2448
+
2449
+ def _include_escalations(self):
2450
+ parts = []
2451
+ for identifier, report in self._pending_events.items():
2452
+ if identifier not in self._reported_events:
2453
+ self._reported_events.add(identifier)
2454
+ parts.append({"type": "input_text", "text": f"Unresolved event: {json.dumps(report)}"})
2455
+ if parts:
2456
+ if self.messages[-1]["role"] == "user":
2457
+ self._extend_request(parts)
2458
+ else:
2459
+ self._tell(parts)
2460
+
2461
+ def _pending_message(self, now):
2462
+ return bool(self._inbox)
2463
+
2464
+ def _unresolved(self, now):
2465
+ return bool(self._pending_events)
2466
+
2467
+ def _pending_escalation(self, now):
2468
+ return bool(self._pending_events) and not self._pending_events.keys() <= self._reported_events
2469
+
2470
+ def _pending_watch(self, now):
2471
+ return (self._watched is not None and self._request is None and self._ahead_allowed(reserve=1)
2472
+ and not self._thoughts.pending)
2473
+
2474
+ def _pending_ahead(self, now):
2475
+ return (self._ahead_due is not None and self._ahead_due <= now and self._request is None
2476
+ and self._ahead_allowed(reserve=1) and not self._thoughts.pending)
2477
+
2478
+ def _decision_tick(self):
2479
+ """Coalesce what is visible at this tick before acquiring a transport."""
2480
+ if not self._cell_running or self._program_completing or self._closing or self._pause:
2481
+ return None
2482
+ if not self._ahead_allowed():
2483
+ if self._inbox and not self._budget_stop:
2484
+ self._budget_stop = True
2485
+ self._stop_program_for_decision()
2486
+ return None
2487
+ if self._thoughts.active is not None:
2488
+ return None
2489
+ now = time.monotonic()
2490
+ if self._think("running", self._turns) is not None:
2491
+ return None
2492
+ if self._ahead_due is not None and self._ahead_due > now:
2493
+ return self._ahead_due
2494
+ return None
2495
+
2496
+ def _came_back(self, thought):
2497
+ from harness.runtime.decision.model import add_usage
2498
+
2499
+ summary = self.summary
2500
+ key = decisions.OUTPUTS["request"].get(thought.role)
2501
+ if key is not None:
2502
+ summary[key] = summary.get(key, 0) + 1
2503
+ summary["agent_seconds"] += thought.seconds
2504
+ if thought.reply is not None:
2505
+ usage = thought.reply.usage
2506
+ add_usage(summary, usage)
2507
+ if key == "vision_calls":
2508
+ summary["vision_cost_usd"] += float(usage.get("cost_usd") or 0.0)
2509
+ self.charge_up()
2510
+ if key is not None:
2511
+ return
2512
+ if thought.outcome is not None:
2513
+ self._record_settlement(thought)
2514
+ elif (self._cell_running and not self._program_completing and self._request is thought
2515
+ and thought.revision == self._revision
2516
+ and not self._inbox and not self._pause):
2517
+ self._dispatch_running_reply(thought)
2518
+
2519
+ def _dispatch_running_reply(self, thought):
2520
+ if thought.cancelled or thought.trigger == "ahead" or thought.reply is None:
2521
+ return
2522
+ text = thought.reply.text
2523
+ if thought.reply.usage.get("finish_reason") == "length":
2524
+ return
2525
+ parsed, prose = decisions._running_reply(text, self._kinds)
2526
+ kind = getattr(parsed, "kind", None)
2527
+ stop = bool(decisions._STOP.search(text))
2528
+ if prose and thought.trigger == "message":
2529
+ output = "message"
2530
+ elif kind == "python" and not stop and self.confirmation != "always" and decisions._beside(parsed.body):
2531
+ output = "parallel"
2532
+ elif kind not in (None, "wait") and (stop or thought.trigger == "message"):
2533
+ output = "replace"
2534
+ else:
2535
+ output = "wait"
2536
+ handler = decisions.OUTPUTS["running"][output]
2537
+ if handler is not None:
2538
+ if output == "parallel":
2539
+ self._run_beside(thought, parsed.body)
2540
+ else:
2541
+ getattr(self, handler)(thought)
2542
+
2543
+ def _interrupt(self, thought: Thought) -> None:
2544
+ """Stop the running program at its next step for `thought`'s reply, which runs next
2545
+ (the loop uses it when the program ends on the stop); a failed thought made for a
2546
+ message stops it too: the model reads the message once it has."""
2547
+ if thought.trigger in ("escalation", "watch"):
2548
+ found = decisions._STOP.search(thought.reply.text)
2549
+ why = " ".join(found.group(1).split()) if found else ""
2550
+ why = f"a look: {why}"[:300] if why else "a look"
2551
+ else:
2552
+ why = "the call failed" if thought.error is not None else "the reply to a message"
2553
+ with self._condition:
2554
+ if self.kernel is None or not self._cell_running or self._request is not thought:
2555
+ return
2556
+ thought.stopped = thought.error is None
2557
+ self.trace.emit("program_stopped", program=thought.program, call=thought.call + 1, why=why)
2558
+ self._stop_program_for_decision()
2559
+
2560
+ def _stop_program_for_decision(self):
2561
+ self._interruptions += 1
2562
+ if self.agents is not None:
2563
+ self.agents.wake()
2564
+ self.kernel.message()
2565
+
2566
+ def _say_beside(self, thought: Thought) -> bool:
2567
+ """A reply in prose to a message that came while a program runs: it reaches the user
2568
+ at once (an agent_message), the program going on, and joins the history when the
2569
+ program ends; False when the program has ended."""
2570
+ with self._condition:
2571
+ if not (self._cell_running and self._request is thought):
2572
+ return False
2573
+ thought.said = True
2574
+ self._settle(thought, "said", "told the user while the program ran")
2575
+ self._pending_events.clear()
2576
+ self.question = thought.reply.text.strip()
2577
+ self.trace.emit("agent_message", text=self.question, program=thought.program)
2578
+ return True
2579
+
2580
+ def _beside_report(self, ahead: Thought) -> str:
2581
+ """What a block run beside the program did, for the model."""
2582
+ side = ahead.side["result"] or {"status": "still running"}
2583
+ return (f"The program you ran beside program {ahead.program}: {side.get('status')}"
2584
+ + (f"\n{side['error']}" if side.get("error") else "")
2585
+ + (f"\nEvent: {side['escalation']['event']['kind']}" if side.get("escalation") else ""))
2586
+
2587
+ def _run_beside(self, ahead: Thought, program: str) -> bool:
2588
+ """Start a block that can run beside the program."""
2589
+ identifier = uuid.uuid4().hex[:12]
2590
+ with self._condition:
2591
+ kernel = self.kernel if self._cell_running and self._request is ahead else None
2592
+ if kernel is None or not kernel.side(program, identifier):
2593
+ return False
2594
+ ahead.side = {"id": identifier, "code": program, "result": None}
2595
+ self._sides[identifier] = ahead
2596
+ self.trace.emit("side_program", id=identifier, program=ahead.program, call=ahead.call + 1,
2597
+ code=program)
2598
+ self._settle(ahead, "beside", "ran beside the program")
2599
+ self._pending_events.clear()
2600
+ return True
2601
+
2602
+ def _side_ended(self, record: dict) -> None:
2603
+ """How a program run beside the running one ended (the kernel's side_result)."""
2604
+ with self._condition:
2605
+ ahead = self._sides.pop(record.get("id"), None)
2606
+ result = {key: record.get(key) for key in ("status", "error", "escalation") if record.get(key) is not None}
2607
+ self.trace.emit("side_program_end", id=record.get("id"), **result)
2608
+ if ahead is not None:
2609
+ ahead.side["result"] = result
2610
+ if result.get("status") in ("error", "escalated"):
2611
+ self._escalation({"id": record["id"], "entry": record["id"], "event": result})
2612
+
2613
+ def _replaced(self) -> dict:
2614
+ """What the next request record says of the history messages it replaces."""
2615
+ replaces, self._replaces = self._replaces, 0
2616
+ return {"replaces": replaces} if replaces else {}
2617
+
2618
+ def _settle(self, thought, outcome, why=""):
2619
+ if thought.outcome is not None:
2620
+ return
2621
+ thought.outcome = outcome, why
2622
+ if outcome in ("discarded", "unused"):
2623
+ if thought.exited:
2624
+ thought.cancel(why)
2625
+ self.trace.emit("thought_cancelled", thought=thought.id, role=thought.role,
2626
+ trigger=thought.trigger, reason=why)
2627
+ else:
2628
+ self._thoughts.cancel_where(lambda item: item is thought, why)
2629
+ if thought.exited:
2630
+ self._record_settlement(thought)
2631
+
2632
+ def _record_settlement(self, thought):
2633
+ outcome, why = thought.outcome
2634
+ summary, reply = self.summary, thought.reply
2635
+ if thought.program is not None:
2636
+ outcomes = summary.setdefault("ahead_outcomes", {})
2637
+ outcomes[outcome] = outcomes.get(outcome, 0) + 1
2638
+ self.trace.emit("ahead", thought=thought.id, call=thought.call + 1, program=thought.program,
2639
+ trigger=thought.trigger, outcome=outcome, why=why,
2640
+ seconds=round(thought.seconds, 3), cancelled=thought.cancelled)
2641
+ if thought.program is None and outcome != "used":
2642
+ self.trace.emit("model_preempted", thought=thought.id, call=thought.call + 1, reason=why,
2643
+ back=reply is not None, **({"text": reply.text, "usage": reply.usage} if reply else {}))
2644
+ elif reply is not None and outcome != "used":
2645
+ self._record_reply(reply, thought.call + 1, thought=thought.id, ahead=outcome)
2646
+
2647
+ def _record_reply(self, reply, call, **detail):
2648
+ self.trace.emit("model_reply", call=call, text=reply.text, usage=reply.usage, response_id=reply.response_id,
2649
+ seconds=reply.seconds, **detail, **({"reasoning": reply.reasoning} if reply.reasoning else {}))
2650
+
2651
+ def _complete(self, thought, history):
2652
+ """The main transport, including bounded context shortening within one Thought."""
2653
+ from harness.runtime.decision.model import ChatModel
2654
+
2655
+ request, chat, turns = thought.messages, thought.chat, thought.turns
2656
+ options = {"on_text": self._streamed(thought.call + 1, stop=lambda: thought.cancelled)} if getattr(
2657
+ chat, "streams_text", False) else {}
2658
+ if isinstance(chat, ChatModel):
2659
+ options["cancellation"] = thought.cancellation
2660
+ attempt = 0
2661
+ name = decisions._model_of(chat).get("model") or str(self.config.main.get("model", "model"))
2662
+ with self._span("model", name, call=thought.call + 1,
2663
+ thought=thought.id, role="main", reason=thought.trigger, program=thought.program) as end:
2664
+ while True:
2665
+ thought.cancellation.check()
2666
+ attempt += 1
2667
+ try:
2668
+ reply = chat.complete(thought.system, request, **options)
2669
+ end.update(output_tokens=reply.usage.get("output_tokens"), attempts=attempt)
2670
+ thought.turns = turns
2671
+ return reply
2672
+ except RuntimeError as error:
2673
+ if "out of GPU memory" not in str(error) or len(request) <= 2:
2674
+ raise
2675
+ turns = max(1, (turns or (len(history) - 1) // 2) - 1)
2676
+ shorter = window(history, turns)
2677
+ if len(shorter) >= len(request):
2678
+ raise
2679
+ self.trace.emit("context_shortened", history_turns=turns, sent_messages=len(shorter))
2680
+ request = shorter
2681
+
2682
+ def _streamed(self, call, every=decisions.STREAMED_SECONDS, stop=None):
2683
+ """What gets the pieces of a streamed reply of call `call`: model_text records of
2684
+ what came, at most one per kind every `every` seconds (the timeline shows the text
2685
+ so far); it cuts the reply off once `stop()` holds, at a piece or a keep-alive
2686
+ (an empty piece)."""
2687
+ pending, sent = {}, {}
2688
+
2689
+ def on_text(kind, text):
2690
+ if stop is not None and stop():
2691
+ raise Preempted()
2692
+ if not text:
2693
+ return
2694
+ pending[kind] = pending.get(kind, "") + text
2695
+ now = time.monotonic()
2696
+ if kind not in sent or now - sent[kind] >= every:
2697
+ sent[kind] = now
2698
+ self.trace.emit("model_text", call=call, kind=kind, text=pending.pop(kind))
2699
+ return on_text
2700
+
2701
+ def _approved(self, program: str) -> bool:
2702
+ """Under the confirmation policy always: wait for the user's verdict on the
2703
+ program; a rejection goes to the model as the user's answer and nothing runs."""
2704
+ if self.confirmation != "always":
2705
+ return True
2706
+ with self._condition:
2707
+ self._decision = None
2708
+ identifier = self._program_approval_id = uuid.uuid4().hex
2709
+ self.trace.emit("confirmation_request", id=identifier, code=program)
2710
+ try:
2711
+ self._wait(WAITING_FOR_CONFIRMATION, lambda: self._decision is not None or bool(self._inbox),
2712
+ reason="program", request={"id": identifier, "code": program})
2713
+ finally:
2714
+ with self._condition:
2715
+ self._program_approval_id = None
2716
+ with self._condition:
2717
+ if self._decision is None:
2718
+ return False
2719
+ accepted, reason = self._decision
2720
+ self._decision = None
2721
+ self.trace.emit("confirmation", id=identifier, accepted=accepted, reason=reason)
2722
+ if accepted:
2723
+ return True
2724
+ self._tell("The user rejected this program, so nothing ran." + (f" Their reason: {reason}" if reason else ""))
2725
+ self.reason = "rejected"
2726
+ return False
2727
+
2728
+ def _reflected(self, system, messages):
2729
+ reply = self._ask_role("reflection", self.chat, system, messages)
2730
+ with self._condition:
2731
+ decisions = self.summary["decisions"]
2732
+ decisions["reflect"] = decisions.get("reflect", 0) + 1
2733
+ return reply
2734
+
2735
+ def _reflect_learning(self):
2736
+ from harness.runtime.learning.learner import executable
2737
+
2738
+ learning = self._learning()
2739
+ cells = self.summary["cells"]
2740
+ if (not learning or not learning["reflect"] or self.parent is not None
2741
+ or cells <= self._reflected_cells or self.seconds_left() <= 0):
2742
+ return
2743
+ with self._condition:
2744
+ if self._pause or self._closing or self._inbox or self._sides:
2745
+ return
2746
+ revision = self._revision
2747
+ since = self._reflected_cells
2748
+ self._reflected_cells = cells
2749
+ try:
2750
+ learner = self._learner()
2751
+ names = (self.config.embodiment, self.profile.get("execution") or self.workspace_kind, *self._skills)
2752
+ names = tuple(name for name in names if name)
2753
+ found, _ = learner.reflect(SimpleNamespace(complete=self._reflected, thinks=True),
2754
+ self.directory, names, since=since,
2755
+ holdings=self._active_library)
2756
+ if found is not None:
2757
+ with self._admission_lock, self._condition:
2758
+ if revision != self._revision or self._pause or self._closing:
2759
+ return
2760
+ value = learner.admit(found, "proposed", pending=executable(found.key),
2761
+ why="reflection on observed program results")
2762
+ self._library_admitted(learner, value, found.text, found.kind, found.source, "reflection")
2763
+ if value["admitted"] and found.kind == "note":
2764
+ from copy import copy
2765
+
2766
+ self.config = copy(self.config)
2767
+ self.config.system_prompt += f"\nObservation from this run: {found.text.strip()}\n"
2768
+ self.invalidate_lookahead()
2769
+ except ThoughtCancelled:
2770
+ pass
2771
+ except Exception as error:
2772
+ self.trace.emit("cleanup_error", message=f"reflection: {type(error).__name__}: {error}")
2773
+
2774
+ def _shutdown_ends_the_episode(self, outcome) -> bool:
2775
+ """The eval client stops the policy server with SIGTERM after scoring. The kernel
2776
+ then exits -15 and the bridge is already closed: the episode ended, it did not fail."""
2777
+ summary = self.summary
2778
+ return (summary.get("status") == "error" and bool(outcome.get("closed"))
2779
+ and str(summary.get("error", "")).startswith("KernelDied:")
2780
+ and "code -15" in summary["error"])
2781
+
2782
+ def _close_episode(self, token) -> None:
2783
+ """End its sub-agents, close the kernel, read the evaluator's outcome with the token,
2784
+ write the summary."""
2785
+ trace, summary, directory, env = self.trace, self.summary, self.directory, self.env
2786
+ with self._condition:
2787
+ self._cancel_managed_worker_approvals("the episode ended")
2788
+ if self.agents is not None:
2789
+ try:
2790
+ self.agents.end_all(self)
2791
+ except Exception as error:
2792
+ trace.emit("cleanup_error", message=f"sub-agents: {type(error).__name__}: {error}")
2793
+ if self.kernel is not None:
2794
+ try:
2795
+ self.kernel.close()
2796
+ except Exception as error:
2797
+ trace.emit("cleanup_error", message=f"kernel: {type(error).__name__}: {error}")
2798
+ if self.environments is not None:
2799
+ self.environments.close()
2800
+ if hasattr(self, "_mcp_access"):
2801
+ try:
2802
+ self._mcp_access.close()
2803
+ except Exception as error:
2804
+ trace.emit("cleanup_error", message=f"MCP: {type(error).__name__}: {error}")
2805
+ if self._managed_dispatcher is not None:
2806
+ try:
2807
+ self._managed_dispatcher.close()
2808
+ except Exception as error:
2809
+ trace.emit("cleanup_error", message=f"managed scheduler: {type(error).__name__}: {error}")
2810
+ if token is not None:
2811
+ try:
2812
+ with self._span("env", "outcome"):
2813
+ outcome = env.call("outcome", token=token)
2814
+ videos = outcome.pop("videos", None)
2815
+ video_error = outcome.pop("video_error", None)
2816
+ trace.emit("outcome", outcome=outcome)
2817
+ if video_error:
2818
+ trace.emit("cleanup_error", message=f"video: {video_error}")
2819
+ if videos:
2820
+ try:
2821
+ trace.emit("episode_video", files=write_episode_videos(directory, videos))
2822
+ except Exception as error:
2823
+ trace.emit("cleanup_error", message=f"video: {type(error).__name__}: {error}")
2824
+ summary.update(success=outcome["success"], reward=outcome["reward"],
2825
+ process_score=outcome["process_score"], steps=outcome["steps"])
2826
+ # The eval client's SIGTERM after scoring ends the episode; no agent error.
2827
+ if self._shutdown_ends_the_episode(outcome):
2828
+ summary["status"] = "episode_ended"
2829
+ summary.pop("error", None)
2830
+ if outcome.get("unscorable") and summary["status"] != "interrupted":
2831
+ # The environment dropped this episode (e.g. RoboDojo marked it unstable
2832
+ # mid-way): neither a success nor a failure of the policy.
2833
+ summary["status"] = "error"
2834
+ summary["error"] = f"Unscorable: {outcome['unscorable']}"
2835
+ trace.emit("error", message=summary["error"])
2836
+ except Exception as error:
2837
+ trace.emit("cleanup_error", message=f"outcome: {type(error).__name__}: {error}")
2838
+ learning = self._learning()
2839
+ if self.kernel is not None:
2840
+ self._reflect_learning()
2841
+ table = self.config.runtime.get("library") or {}
2842
+ uses = table.get("uses", {"learn": "on", "off": "off"}.get(table.get("experience"), "learn"))
2843
+ self._thoughts.close()
2844
+ with self._condition:
2845
+ if not self._condition.wait_for(lambda: self._thoughts.active is None, timeout=2):
2846
+ summary["model_transport_pending"] = self._thoughts.active.id
2847
+ if self.kernel is not None and table and (
2848
+ uses == "on" or uses == "learn" and learning is not None):
2849
+ # What this episode's closed loops of library skills did, as their uses in the
2850
+ # library's index (runtime/learning/usage.py fold_uses).
2851
+ try:
2852
+ trace.emit("library", action="used", uses=fold_uses(self._learner(), directory))
2853
+ except Exception as error:
2854
+ trace.emit("cleanup_error", message=f"library uses: {type(error).__name__}: {error}")
2855
+ summary["wall_seconds"] = time.perf_counter() - self.started
2856
+ if self.agents_usage["started"] or self.agents_usage["model_calls"]:
2857
+ summary["agents"] = {**self.agents_usage, "cost_usd": round(self.agents_usage["cost_usd"], 6)}
2858
+ write_json(directory / "summary.json", summary)
2859
+ self.charge_up()
2860
+ self._set_status(ERROR if summary["status"] == "error" else FINISHED, reason=summary["status"])
2861
+
2862
+
2863
+ # Added to a kind's verifier instructions when the model looks on demand.
2864
+ VERIFIER_EVIDENCE = (" Besides any pictures, the message gives the state and what the environment reports as text "
2865
+ "(a window's elements, a page's text): judge on all of it, and answer NO when together it "
2866
+ "does not show enough to confirm the claim.")
2867
+ # What the vision role is asked of a view, for a main model that reads no images.
2868
+ VIEWER = ("You describe a view for an agent that cannot see it. Say what is shown: the windows or objects, the "
2869
+ "text and numbers exactly as written, the controls and where each is (pixel coordinates from the top "
2870
+ "left). Facts only, no advice.")
2871
+
2872
+
2873
+ def _object(reference: str):
2874
+ """The object a "module:attribute" reference names."""
2875
+ import importlib
2876
+
2877
+ module, _, attribute = reference.partition(":")
2878
+ return getattr(importlib.import_module(module), attribute)