@lmmslab/harness 0.0.0-stage → 0.81.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (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 +1308 -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 +221 -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,811 @@
1
+ """A persistent Python kernel for model-written programs, in its own process.
2
+
3
+ The host sends cells over stdin and reads one JSON reply per cell from a
4
+ private descriptor, so anything a program prints cannot corrupt the protocol.
5
+ The kernel namespace comes from a bootstrap callable `module:function` that
6
+ receives JSON options and returns a session object with:
7
+
8
+ namespace: dict names visible to programs
9
+ drain() -> dict attachments and events gathered during the cell
10
+ close() -> None
11
+
12
+ Between cells the host may ask for the truth of an expression on the namespace
13
+ (Kernel.check), which runs no cell and drains nothing. While a cell runs it may run code
14
+ beside it (Kernel.side), on a thread of its own in the same namespace: what it prints
15
+ goes into the running cell's output, and a side_result message says how it ended.
16
+
17
+ The kernel reports imported Harness package modules to the host as a `modules` note:
18
+ those of the bootstrap once it is ready, then those new after each cell, side run and at
19
+ the close. The trace records what code the run loaded.
20
+ """
21
+
22
+ import argparse
23
+ import contextlib
24
+ import importlib
25
+ import io
26
+ from functools import partial
27
+ import json
28
+ import os
29
+ from pathlib import Path
30
+ import queue
31
+ import shutil
32
+ import subprocess
33
+ import sys
34
+ import tempfile
35
+ import threading
36
+ import time
37
+ import traceback
38
+
39
+ from harness.paths import PACKAGE, ROOT, import_roots, package_roots
40
+ from harness.core import spans
41
+ from harness.runtime.execution import control
42
+ from harness.runtime.events import EpisodeEnded, Escalation, ProgramFinished
43
+
44
+
45
+ # The kernel bootstrap: the embodiment's session with its skills (runtime/execution/session.py).
46
+ DEFAULT_BOOTSTRAP = "harness.runtime.execution.session:create_session"
47
+
48
+
49
+ # The kernel's interpreter when the agent's runtime names none: what `harness run` installed
50
+ # for the benchmark (the eval package's preflight), else the conversation's own.
51
+ KERNEL_PYTHON_ENV = "HARNESS_KERNEL_PYTHON"
52
+
53
+
54
+ def kernel_python(runtime: dict) -> str:
55
+ """The interpreter the kernel of an episode runs in."""
56
+ return runtime.get("python") or os.environ.get(KERNEL_PYTHON_ENV) or sys.executable
57
+
58
+
59
+ MAX_OUTPUT_CHARS = 8000
60
+ # Program output is a bounded stream, including when a program never returns.
61
+ MAX_PROGRAM_OUTPUT_CHARS = 1024 * 1024
62
+
63
+
64
+ class ProgramOutput:
65
+ def __init__(self, cell):
66
+ self.cell, self.size, self.pending = cell, 0, ""
67
+ self.head = self.tail = ""
68
+ self.exhausted = False
69
+
70
+ def write(self, text):
71
+ text = str(text)
72
+ if self.size + len(text) > MAX_PROGRAM_OUTPUT_CHARS:
73
+ self.exhausted = True
74
+ self.flush()
75
+ raise RuntimeError("program output limit exceeded (1048576 characters); write large data in the target")
76
+ self.size += len(text)
77
+ self.head = (self.head + text)[:MAX_OUTPUT_CHARS // 2]
78
+ self.tail = (self.tail + text)[-MAX_OUTPUT_CHARS // 2:]
79
+ self.pending += text
80
+ while len(self.pending) >= 8192:
81
+ chunk, self.pending = self.pending[:8192], self.pending[8192:]
82
+ spans.note("program_output", cell=self.cell, text=chunk)
83
+ return len(text)
84
+
85
+ def flush(self):
86
+ if self.pending:
87
+ spans.note("program_output", cell=self.cell, text=self.pending)
88
+ self.pending = ""
89
+
90
+ def getvalue(self):
91
+ self.flush()
92
+ if self.size <= MAX_OUTPUT_CHARS // 2:
93
+ return self.head
94
+ if self.size <= MAX_OUTPUT_CHARS:
95
+ return self.head + self.tail[-(self.size - len(self.head)):]
96
+ return self.head + f"\n... {self.size - MAX_OUTPUT_CHARS} characters omitted; see program_output trace ...\n" + self.tail
97
+ # Top-level packages of the source checkout that kernels import (skills, benches).
98
+ REPO_PACKAGES = ("skills", "benches")
99
+
100
+
101
+ def repo_modules() -> list[str]:
102
+ """Imported modules from Harness packages, including the shared namespaces."""
103
+ roots = {root.absolute() for root in package_roots()}
104
+ found = []
105
+ for name, module in list(sys.modules.items()):
106
+ if name.partition(".")[0] in REPO_PACKAGES:
107
+ found.append(name)
108
+ continue
109
+ origin = getattr(module, "__file__", None)
110
+ if isinstance(origin, str) and any(parent in roots for parent in Path(origin).parents):
111
+ found.append(name)
112
+ return sorted(found)
113
+
114
+
115
+ class PlainSession:
116
+ """A bootstrap with an empty namespace, for tests and debugging."""
117
+
118
+ def __init__(self, options=None):
119
+ self.namespace = {"__name__": "__program__"}
120
+
121
+ def drain(self):
122
+ """Nothing: a plain session gathers no attachments or events."""
123
+ return {}
124
+
125
+ def close(self):
126
+ """Nothing to release."""
127
+ pass
128
+
129
+
130
+ class KernelDied(RuntimeError):
131
+ """The kernel process failed to start, is not running, or did not answer in time (it is
132
+ then killed)."""
133
+ pass
134
+
135
+
136
+ _SANDBOX = None
137
+
138
+
139
+ def sandbox_available() -> bool:
140
+ """Whether this machine can run the kernel's sandbox (util-linux unshare with user,
141
+ mount and PID namespaces)."""
142
+ global _SANDBOX
143
+ if _SANDBOX is None:
144
+ try:
145
+ result = subprocess.run(["unshare", "--user", "--map-root-user", "--mount", "--pid", "--fork",
146
+ "--mount-proc", "true"], capture_output=True, timeout=30)
147
+ _SANDBOX = result.returncode == 0
148
+ except (OSError, subprocess.TimeoutExpired):
149
+ _SANDBOX = False
150
+ return _SANDBOX
151
+
152
+
153
+ class Kernel:
154
+ """Host-side handle. One kernel lives for one episode.
155
+
156
+ A managed workspace supplies its dispatcher and a launcher context manager factory.
157
+ The launcher takes the dispatcher's options and yields the command and descriptors
158
+ to pass to the kernel process.
159
+ """
160
+
161
+ def __init__(self, bootstrap: str, options: dict, *, python: str = sys.executable,
162
+ cwd: str | None = None, env: dict | None = None, log_path: Path | None = None,
163
+ start_timeout: float = 300.0, on_span=None, managed=None, managed_launcher=None):
164
+ if (managed is None) != (managed_launcher is None):
165
+ raise ValueError("A managed kernel requires both a dispatcher and a launcher")
166
+ # Called with every span record of the kernel's skills and service calls.
167
+ self.on_span = on_span
168
+ self._managed = managed
169
+ self._log = open(log_path, "ab") if log_path else subprocess.DEVNULL
170
+ if env is None:
171
+ env = dict(os.environ)
172
+ env["PYTHONPATH"] = os.pathsep.join(import_roots() + [p for p in [env.get("PYTHONPATH")] if p])
173
+ isolation = options.get("isolation")
174
+ if isolation == "auto":
175
+ # Containers often forbid user namespaces; an evaluation host need not allow them.
176
+ # The guard inside the kernel (reachable services, no processes) needs none.
177
+ isolation = True if sandbox_available() else {"sandbox": False}
178
+ if isolation is not True:
179
+ print("kernel: user namespaces are not available here; programs run without the filesystem "
180
+ "sandbox (the network, process and file guard stays)", file=sys.stderr, flush=True)
181
+ options = {**options, "isolation": isolation}
182
+ command = [python, "-u", "-m", "harness.runtime.execution.kernel",
183
+ "--bootstrap", bootstrap, "--options", "-"]
184
+ self._workspace = None
185
+ if isinstance(isolation, dict) and isolation.get("sandbox") is False:
186
+ # No sandbox: the file guard inside the kernel (isolation.py) keeps programs to
187
+ # the installation, the source and this workspace; the environment carries no
188
+ # keys but the models'.
189
+ from harness.runtime.safety.isolation import kernel_environment
190
+
191
+ if cwd is None:
192
+ self._workspace = cwd = tempfile.mkdtemp(prefix="harness-kernel-")
193
+ env = {**kernel_environment(options, env, python), "HOME": cwd, "TMPDIR": cwd,
194
+ "TEMP": cwd, "TMP": cwd, "PYTHONDONTWRITEBYTECODE": "1"}
195
+ elif isolation:
196
+ # App. A: the kernel sees only the Python installation and the harness
197
+ # source, and reaches only the services in its options (isolation.py).
198
+ from harness.runtime.safety.isolation import hidden_roots, kernel_environment, package_dirs, sandbox_command
199
+
200
+ # A virtual environment's interpreter links to a base installation: both are shown.
201
+ prefixes = sorted({Path(python).absolute().parents[1], Path(python).resolve().parents[1]})
202
+ source = [*map(Path, import_roots()[1:]), PACKAGE, *(ROOT / name for name in REPO_PACKAGES),
203
+ *package_dirs(python=python)]
204
+ extra = isolation.get("hide", []) if isinstance(isolation, dict) else []
205
+ workspace = Path(cwd).resolve() if cwd else None
206
+ keep = [workspace] if workspace else []
207
+ command = sandbox_command(command, keep=keep, read_only=[*prefixes, *source],
208
+ hide=hidden_roots([*prefixes, PACKAGE.parent, *keep], extra), cwd=workspace)
209
+ env, cwd = kernel_environment(options, env, python), None
210
+ if workspace:
211
+ env["PYTHONDONTWRITEBYTECODE"] = "1"
212
+ from harness.runtime.safety.approval import WORKER_APPROVAL_KEY
213
+
214
+ env = {name: value for name, value in env.items() if name.upper() != WORKER_APPROVAL_KEY}
215
+ if managed is not None:
216
+ with managed_launcher(managed.options()) as (launch, pass_fds):
217
+ self.process = subprocess.Popen(launch, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
218
+ stderr=self._log, env={}, pass_fds=pass_fds, bufsize=0)
219
+ os.set_blocking(self.process.stdin.fileno(), False)
220
+ else:
221
+ self.process = subprocess.Popen(
222
+ command, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=self._log,
223
+ cwd=cwd, env=env, bufsize=0,
224
+ )
225
+ # Startup data can exceed Windows' command-line limit as the library grows.
226
+ self._send(options)
227
+ self._replies: queue.Queue = queue.Queue()
228
+ # run() and pause() may write from different threads; the order of what they
229
+ # write is the order the kernel sees.
230
+ self._writing = threading.Lock()
231
+ self._running = False
232
+ self._pause_pending = False
233
+ self._reader = threading.Thread(target=self._read, daemon=True)
234
+ self._reader.start()
235
+ self.cells = 0
236
+ ready = self._receive(start_timeout)
237
+ if ready.get("status") != "ready":
238
+ self.close()
239
+ raise KernelDied(f"Kernel failed to start: {ready.get('error')}")
240
+ self.names = ready.get("names", [])
241
+ # The worker's private paths the kernel refuses to programs (isolation.py).
242
+ self.private = ready.get("private", [])
243
+
244
+ def _read(self):
245
+ if self._managed is not None:
246
+ self._read_managed()
247
+ return
248
+ for line in self.process.stdout:
249
+ try:
250
+ message = json.loads(line)
251
+ except json.JSONDecodeError:
252
+ self._replies.put({"status": "protocol_error", "error": line[:200].decode(errors="replace")})
253
+ continue
254
+ if isinstance(message, dict) and message.get("op") == "worker_request":
255
+ try:
256
+ if self.on_span is None:
257
+ raise RuntimeError("Kernel has no worker dispatcher")
258
+ self.on_span(message)
259
+ except Exception as error:
260
+ self.answer(message["id"], {"worker": True, "error": str(error)})
261
+ continue
262
+ if isinstance(message, dict) and message.get("op") in ("span_start", "span_end", "note", "entry_start",
263
+ "entry_claims", "entry_end", "world",
264
+ "side_result"):
265
+ if self.on_span is not None:
266
+ try:
267
+ self.on_span(message)
268
+ except Exception:
269
+ # A span that cannot be recorded never stops the replies.
270
+ pass
271
+ continue
272
+ if not isinstance(message, dict) or message.get("op") is not None or not any(
273
+ key in message for key in ("status", "value", "error")):
274
+ self.process.kill()
275
+ self._replies.put({"status": "protocol_error", "error": "Unknown kernel message; execution stopped"})
276
+ break
277
+ self._replies.put(message)
278
+ self._replies.put(None)
279
+
280
+ def _read_managed(self):
281
+ # After startup every child message is untrusted. Only proposals and one reply
282
+ # for the active host cell enter the managed conversation.
283
+ stream = self.process.stdout
284
+ limit = 64 * 1024
285
+ try:
286
+ line = stream.readline(limit + 1)
287
+ if not line or len(line) > limit:
288
+ return
289
+ self._replies.put(json.loads(line))
290
+ while line := stream.readline(limit + 1):
291
+ if len(line) > limit:
292
+ break
293
+ message = json.loads(line)
294
+ if not isinstance(message, dict):
295
+ break
296
+ if message.get("op") == "workspace_proposal":
297
+ identifier = message.get("id")
298
+ def reply(result, identifier=identifier):
299
+ self._write({"op": "workspace_result", "id": identifier, **result})
300
+ if not self._managed.submit(message, reply):
301
+ break
302
+ elif message.get("op") is None and self._managed.accept_result(message.get("cell")):
303
+ self._replies.put(self._managed.result(message))
304
+ else:
305
+ break
306
+ except (ValueError, OSError):
307
+ pass
308
+ finally:
309
+ self.kill()
310
+ self._replies.put(None)
311
+
312
+ def _receive(self, timeout):
313
+ try:
314
+ reply = self._replies.get(timeout=timeout)
315
+ except queue.Empty:
316
+ self.kill()
317
+ raise KernelDied(f"Kernel did not answer within {timeout:.0f} s; it was killed") from None
318
+ if reply is None:
319
+ raise KernelDied(f"Kernel exited with code {self.process.wait()}")
320
+ return reply
321
+
322
+ def run(self, code: str, timeout: float) -> dict:
323
+ """Run `code` as the next cell and return the kernel's reply: status (ok, error,
324
+ escalated, episode_ended or finished), clipped stdout, error, seconds, and what the
325
+ session drained (attachments, events, state, usage). Raises KernelDied when the
326
+ kernel is not running, exits, or does not reply within `timeout` seconds."""
327
+ return self._cell({"op": "run", "code": code}, timeout)
328
+
329
+ def load_library(self, phase, entries=(), *, timeout=120):
330
+ return self._cell({"op": "library", "phase": phase,
331
+ "entries": [(item.revision, item.pack().decode(), hand) for item, hand in entries]}, timeout)
332
+
333
+ def _cell(self, request, timeout):
334
+ if self.process.poll() is not None:
335
+ raise KernelDied("Kernel is not running")
336
+ self.cells += 1
337
+ if self._managed is not None:
338
+ if request["op"] != "run":
339
+ raise ValueError("Managed workspace cells only support running programs")
340
+ if request["code"] == "__wrap_up__()":
341
+ return self._managed.result({"status": "ok"})
342
+ self._managed.begin(self.cells)
343
+ with self._writing:
344
+ request["cell"] = self.cells
345
+ if self._pause_pending:
346
+ request["pause"] = True
347
+ self._pause_pending = False
348
+ self._running = True
349
+ self._send(request)
350
+ try:
351
+ result = self._receive(timeout)
352
+ if result.get("cell", self.cells) != self.cells:
353
+ self.kill()
354
+ raise KernelDied("Kernel returned a result for another cell")
355
+ return result
356
+ finally:
357
+ if self._managed is not None:
358
+ self._managed.stop()
359
+ with self._writing:
360
+ self._running = False
361
+ self._pause_pending = False
362
+
363
+ def check(self, condition: str, output: str, seconds: float) -> dict:
364
+ """Evaluate `condition` (an expression) on what the last cell left, with `output`
365
+ (what it printed) as the name output: {"value": its truth} or {"error": why not},
366
+ within `seconds` (runtime/conversation.py: what a reply made while the cell ran
367
+ expected it to leave)."""
368
+ if self._managed is not None:
369
+ return {"error": "Managed workspace cells do not support speculative checks"}
370
+ if self.process.poll() is not None:
371
+ raise KernelDied("Kernel is not running")
372
+ with self._writing:
373
+ self._send({"op": "check", "condition": condition, "output": output, "seconds": seconds})
374
+ return self._receive(seconds + 30)
375
+
376
+ def _send(self, request: dict) -> None:
377
+ data = (json.dumps(request) + "\n").encode()
378
+ if self._managed is None:
379
+ self.process.stdin.write(data)
380
+ else:
381
+ import selectors
382
+
383
+ view = memoryview(data)
384
+ deadline = time.monotonic() + 5
385
+ with selectors.DefaultSelector() as selector:
386
+ selector.register(self.process.stdin, selectors.EVENT_WRITE)
387
+ while view:
388
+ if not selector.select(max(0, deadline - time.monotonic())):
389
+ self.kill()
390
+ raise BrokenPipeError("The managed kernel stopped reading")
391
+ count = self.process.stdin.write(view)
392
+ if count is not None:
393
+ view = view[count:]
394
+ self.process.stdin.flush()
395
+
396
+ def _write(self, request: dict) -> None:
397
+ with self._writing:
398
+ self._send(request)
399
+
400
+ def pause(self) -> None:
401
+ """Ask the program that runs, or is about to run, to stop at its next execution step
402
+ (runtime/execution/control.py); nothing when the kernel no longer runs."""
403
+ if self._managed is not None:
404
+ self._managed.stop()
405
+ return
406
+ if self.process.poll() is not None:
407
+ return
408
+ with self._writing:
409
+ if not self._running:
410
+ # run() is about to send its cell: the request goes with it.
411
+ self._pause_pending = True
412
+ return
413
+ try:
414
+ self._send({"op": "pause"})
415
+ except OSError:
416
+ pass
417
+
418
+ def message(self) -> None:
419
+ """Tell the running cell a message for the model came (runtime/execution/control.py)."""
420
+ if self._managed is not None:
421
+ self._managed.stop()
422
+ return
423
+ with self._writing:
424
+ if not self._running or self.process.poll() is not None:
425
+ return
426
+ try:
427
+ self._send({"op": "message"})
428
+ except OSError:
429
+ pass
430
+
431
+ def side(self, code: str, identifier: str) -> bool:
432
+ """Run `code` beside the running cell, in the same namespace (its side_result
433
+ message, with `identifier`, goes to on_span); False when no cell runs."""
434
+ if self._managed is not None:
435
+ return False
436
+ with self._writing:
437
+ if not self._running or self.process.poll() is not None:
438
+ return False
439
+ try:
440
+ self._send({"op": "side", "id": identifier, "code": code})
441
+ except OSError:
442
+ return False
443
+ return True
444
+
445
+ def answer(self, identifier, value) -> None:
446
+ """Answer a request the running program sent as a note (runtime/execution/control.py);
447
+ nothing when the kernel no longer runs."""
448
+ if self.process.poll() is not None:
449
+ return
450
+ try:
451
+ self._write({"op": "answer", "id": str(identifier), "value": value})
452
+ except OSError:
453
+ pass
454
+
455
+ def agent_ended(self, agent, report, *, cancelled=False) -> None:
456
+ """Tell the program that a sub-agent it started ended, with its report (its entry
457
+ ends, runtime/execution/entries.py); nothing when the kernel no longer runs."""
458
+ if self.process.poll() is not None:
459
+ return
460
+ try:
461
+ self._write({"op": "agent_ended", "agent": str(agent), "report": report, "cancelled": cancelled})
462
+ except OSError:
463
+ pass
464
+
465
+ def kill(self):
466
+ """Kill the kernel process if it still runs."""
467
+ if self._managed is not None:
468
+ self._managed.stop()
469
+ if self.process.poll() is None:
470
+ self.process.kill()
471
+ self.process.wait()
472
+
473
+ def close(self):
474
+ """Ask the kernel to close its session and exit (killing it when it does not within
475
+ 30 s), then close the pipes and the log."""
476
+ if self._managed is not None:
477
+ self.kill()
478
+ if self.process.poll() is None:
479
+ try:
480
+ self._write({"op": "close"})
481
+ self.process.wait(timeout=30)
482
+ except (OSError, subprocess.TimeoutExpired):
483
+ self.kill()
484
+ for stream in (self.process.stdin, self.process.stdout):
485
+ stream.close()
486
+ self._reader.join(timeout=5)
487
+ if self._log is not subprocess.DEVNULL:
488
+ self._log.close()
489
+ if self._workspace:
490
+ shutil.rmtree(self._workspace, ignore_errors=True)
491
+
492
+
493
+ def _clip(text: str) -> str:
494
+ if len(text) <= MAX_OUTPUT_CHARS:
495
+ return text
496
+ half = MAX_OUTPUT_CHARS // 2
497
+ return text[:half] + f"\n... [{len(text) - MAX_OUTPUT_CHARS} characters omitted] ...\n" + text[-half:]
498
+
499
+
500
+ def format_error(error: BaseException) -> str:
501
+ """Traceback restricted to program frames, plus the frame that raised."""
502
+ summary = traceback.TracebackException.from_exception(error)
503
+ frames = [frame for frame in summary.stack if frame.filename.startswith("<cell-")]
504
+ if summary.stack and (not frames or frames[-1] is not summary.stack[-1]):
505
+ frames.append(summary.stack[-1])
506
+ lines = ["Traceback (program frames):\n"]
507
+ for frame in frames:
508
+ lines.append(f' File "{frame.filename}", line {frame.lineno}, in {frame.name}\n')
509
+ if frame.line:
510
+ lines.append(f" {frame.line}\n")
511
+ lines.extend(summary.format_exception_only())
512
+ return "".join(lines)
513
+
514
+
515
+ def restore_api(namespace: dict, api: dict) -> list[str]:
516
+ """Put back the session's API names that a program rebound or deleted (a model's
517
+ own `def pick(m): ...` would otherwise break every later call of the skill) and
518
+ return them, sorted."""
519
+ missing = object()
520
+ restored = []
521
+ for name, value in api.items():
522
+ current = namespace.get(name, missing)
523
+ if current is value:
524
+ continue
525
+ try: # a constant set to the same value again (TABLE_Z = 0.765) is not rebound
526
+ same = not callable(value) and bool(current == value)
527
+ except Exception:
528
+ same = False
529
+ if not same:
530
+ namespace[name] = value
531
+ restored.append(name)
532
+ return sorted(restored)
533
+
534
+
535
+ def _serve(bootstrap: str, options: dict, *, forward_workspace_requests: bool = False) -> None:
536
+ channel = os.fdopen(os.dup(1), "w", buffering=1, encoding="utf-8")
537
+ # Stray writes to descriptor 1 from programs or libraries go to the log instead.
538
+ os.dup2(2, 1)
539
+ sys.stdout = io.TextIOWrapper(os.fdopen(1, "wb", buffering=0), encoding="utf-8", errors="replace",
540
+ write_through=True)
541
+
542
+ writing = threading.Lock()
543
+
544
+ def reply(data):
545
+ line = json.dumps(data, allow_nan=False, default=repr) + "\n"
546
+ with writing:
547
+ channel.write(line)
548
+
549
+ control.host_thoughts = bool(options.get("host_thoughts"))
550
+ managed = forward_workspace_requests
551
+ proposal_result = queue.Queue()
552
+ proposal_lock = threading.Lock()
553
+ cell = sequence = 0
554
+
555
+ def propose(name, *args, **kwargs):
556
+ nonlocal sequence
557
+ with proposal_lock:
558
+ sequence += 1
559
+ reply({"op": "workspace_proposal", "id": sequence, "cell": cell,
560
+ "name": name, "args": args, "kwargs": kwargs})
561
+ answer = proposal_result.get()
562
+ if answer.get("id") != sequence or "error" in answer:
563
+ raise RuntimeError(answer.get("error") or "The managed workspace reply is out of order")
564
+ return answer.get("value")
565
+
566
+ if options.get("host_controls"):
567
+ options["worker_relay"] = partial(control.worker_call, reply)
568
+ try:
569
+ module_name, _, function_name = bootstrap.partition(":")
570
+ factory = getattr(importlib.import_module(module_name), function_name)
571
+ session = factory(options, propose) if managed else factory(options)
572
+ namespace = session.namespace
573
+ except BaseException as error:
574
+ reply({"status": "error", "error": format_error(error) if not isinstance(error, SystemExit)
575
+ else "bootstrap exited"})
576
+ return
577
+ isolation = options.get("isolation")
578
+ if isolation:
579
+ from harness.runtime.safety.isolation import endpoints, install_file_guard, install_network_guard, read_roots
580
+
581
+ install_network_guard(endpoints(options))
582
+ sandboxed = not (isinstance(isolation, dict) and isolation.get("sandbox") is False)
583
+ source = [*map(Path, import_roots()[1:]), PACKAGE, *(ROOT / name for name in REPO_PACKAGES)]
584
+ # The sandbox's /tmp is its own; without it the workspace is the kernel's working directory.
585
+ install_file_guard(read_roots(source), [Path.cwd(), *([Path("/tmp")] if sandboxed else [])])
586
+ private = []
587
+ if options.get("private_paths"):
588
+ from harness.runtime.safety.isolation import install_private_guard
589
+
590
+ # The worker's private files: refused, and each attempt noted to the host.
591
+ private = install_private_guard(options["private_paths"],
592
+ lambda event, path: spans.note("file_access", operation=event, path=path))
593
+ reply({"status": "ready", "names": sorted(name for name in namespace if not name.startswith("_")),
594
+ **({"private": private} if private else {})})
595
+ # Spans of skills and service calls go to the host as they start and end.
596
+ if not managed:
597
+ spans.set_sink(reply)
598
+ reported = set()
599
+
600
+ def report_modules():
601
+ # The repository's modules imported since the last report (the bootstrap's first).
602
+ new = [name for name in repo_modules() if name not in reported]
603
+ if new:
604
+ reported.update(new)
605
+ spans.note("modules", loaded=new)
606
+
607
+ report_modules()
608
+ # The names the session provides, restored after every cell that rebinds them.
609
+ api = {name: value for name, value in namespace.items() if not name.startswith("__")}
610
+ # Requests are read on their own thread so that a pause reaches a running program.
611
+ requests = queue.Queue()
612
+ active_library = {}
613
+ staged_library = None
614
+
615
+ def wake_entries():
616
+ tree = getattr(session, "_entry_tree", None)
617
+ if tree is not None:
618
+ with tree._changed:
619
+ tree._changed.notify_all()
620
+
621
+ def read_requests():
622
+ for line in sys.stdin:
623
+ request = json.loads(line)
624
+ if managed and request["op"] == "workspace_result":
625
+ proposal_result.put(request)
626
+ continue
627
+ if request["op"] == "pause":
628
+ control.request_pause()
629
+ wake_entries()
630
+ continue
631
+ if request["op"] == "message":
632
+ control.request_message()
633
+ wake_entries()
634
+ continue
635
+ if request["op"] == "side":
636
+ _side(namespace, request, reply, report_modules, getattr(session, "_entry_tree", None))
637
+ continue
638
+ if request["op"] == "answer":
639
+ control.answer(request["id"], request.get("value"))
640
+ continue
641
+ if request["op"] == "agent_ended":
642
+ control.agent_ended(request.get("agent"), request.get("report"),
643
+ cancelled=bool(request.get("cancelled")))
644
+ continue
645
+ if request["op"] == "run":
646
+ # A pause belongs to the cell after which it was sent.
647
+ control.clear()
648
+ if request.get("pause"):
649
+ control.request_pause()
650
+ requests.put(request)
651
+ requests.put(None)
652
+
653
+ threading.Thread(target=read_requests, daemon=True).start()
654
+ while True:
655
+ request = requests.get()
656
+ if request is None or request["op"] == "close":
657
+ break
658
+ if request["op"] == "check":
659
+ reply(_check(namespace, request))
660
+ continue
661
+ if request["op"] == "library":
662
+ from harness.runtime.learning.library import Revision, publish_entries, stage_entries
663
+
664
+ try:
665
+ phase = request["phase"]
666
+ reactive = getattr(session, "reactive", None)
667
+ if phase == "prepare":
668
+ staged_library = None
669
+ items = []
670
+ for expected, data, hand in request["entries"]:
671
+ item = Revision.unpack(data)
672
+ if item.revision != expected:
673
+ raise ValueError("library payload does not match its revision")
674
+ items.append((item, hand))
675
+ staged_library = stage_entries(items, namespace, active_library, reactive, api=api)
676
+ elif phase == "commit" and staged_library is not None:
677
+ publish_entries(staged_library, namespace, active_library, reactive)
678
+ staged_library = None
679
+ elif phase == "discard":
680
+ staged_library = None
681
+ else:
682
+ raise ValueError("invalid library activation phase")
683
+ reply({"status": "ok", "active": {key: row[0] for key, row in active_library.items()}})
684
+ except BaseException as error:
685
+ staged_library = None
686
+ reply({"status": "error", "error": format_error(error)})
687
+ continue
688
+ if managed:
689
+ cell = request["cell"]
690
+ started = time.perf_counter()
691
+ buffer = ProgramOutput(request["cell"])
692
+ result = {"status": "ok", "error": None, "escalation": None, "episode_ended": None}
693
+ # The session's entries (runtime/execution/entries.py): an event for the model that came while
694
+ # no program ran ends this one before it starts, and one that came while it ran
695
+ # ends it if it did not meet it.
696
+ tree = getattr(session, "_entry_tree", None)
697
+ try:
698
+ code = compile(request["code"], f"<cell-{request['cell']}>", "exec")
699
+ with contextlib.redirect_stdout(buffer), contextlib.redirect_stderr(buffer):
700
+ if tree is not None:
701
+ tree.begin_program()
702
+ exec(code, namespace)
703
+ if tree is not None:
704
+ tree.end_program()
705
+ except Escalation as escalation:
706
+ result["status"] = "escalated"
707
+ result["escalation"] = escalation.trace.to_dict()
708
+ except EpisodeEnded as ended:
709
+ result["status"] = "episode_ended"
710
+ result["episode_ended"] = ended.trace.to_dict()
711
+ except ProgramFinished as finished:
712
+ result["status"] = "finished"
713
+ result["finish"] = finished.summary
714
+ except KeyboardInterrupt:
715
+ result["status"] = "error"
716
+ result["error"] = "KeyboardInterrupt"
717
+ except BaseException as error:
718
+ result["status"] = "error"
719
+ result["error"] = format_error(error)
720
+ if control.host_thoughts:
721
+ spans.note("cell_finishing", cell=request["cell"])
722
+ # Names the session gained while the cell ran (an attached environment, skills
723
+ # switched on) are part of its API from now on; those it gave up are no longer.
724
+ changed = getattr(session, "_api_changes", None)
725
+ if changed:
726
+ for name, value in changed.items():
727
+ if value is None:
728
+ api.pop(name, None)
729
+ namespace.pop(name, None)
730
+ else:
731
+ api[name] = namespace[name] = value
732
+ changed.clear()
733
+ restored = restore_api(namespace, api)
734
+ if restored:
735
+ buffer.write(f"\nWarning: the program rebound the API name(s) {', '.join(restored)}; they were restored "
736
+ "to the built-in skills after it ended. Give your own functions and variables other names.\n")
737
+ result["stdout"] = _clip(buffer.getvalue())
738
+ if buffer.exhausted:
739
+ result.update(status="error", error="Program output resource limit exceeded")
740
+ result["seconds"] = time.perf_counter() - started
741
+ report_modules()
742
+ try:
743
+ result.update(session.drain())
744
+ except Exception as error:
745
+ result["drain_error"] = format_error(error)
746
+ result["cell"] = request["cell"]
747
+ reply(result)
748
+ report_modules()
749
+ session.close()
750
+
751
+
752
+ def _side(namespace: dict, request: dict, reply, report_modules=None, tree=None) -> None:
753
+ """Run a side request's code on a thread of its own in `namespace`, beside the cell,
754
+ and reply how it ended (side_result: status ok, escalated or error), after
755
+ `report_modules()` tells the host the modules it imported."""
756
+
757
+ def run():
758
+ result = {"op": "side_result", "id": request.get("id"), "status": "ok", "error": None}
759
+ try:
760
+ exec(compile(request["code"], f"<side-{request.get('id')}>", "exec"), namespace)
761
+ except Escalation as escalation:
762
+ result.update(status="escalated", escalation=escalation.trace.to_dict())
763
+ except BaseException as error:
764
+ result.update(status="error", error=format_error(error))
765
+ if report_modules is not None:
766
+ report_modules()
767
+ reply(result)
768
+
769
+ if tree is None:
770
+ threading.Thread(target=run, name="side", daemon=True).start()
771
+ else:
772
+ try:
773
+ tree.spawn(run, name=f"parallel {request['id']}")
774
+ except Exception as error:
775
+ reply({"op": "side_result", "id": request.get("id"), "status": "error", "error": format_error(error)})
776
+
777
+
778
+ def _check(namespace: dict, request: dict) -> dict:
779
+ """The truth of a check request's condition on `namespace`, with its output as the
780
+ name output, evaluated on a thread of its own for at most its seconds."""
781
+ checked = {}
782
+
783
+ def evaluate():
784
+ try:
785
+ scope = {**namespace, "output": request.get("output") or ""}
786
+ checked["value"] = bool(eval(compile(request["condition"], "<assume>", "eval"), scope))
787
+ except BaseException as error:
788
+ checked["error"] = f"{type(error).__name__}: {error}"[:300]
789
+
790
+ thread = threading.Thread(target=evaluate, name="check", daemon=True)
791
+ thread.start()
792
+ thread.join(float(request.get("seconds") or 2.0))
793
+ if thread.is_alive():
794
+ return {"status": "check", "error": "the condition took too long"}
795
+ return {"status": "check", **checked}
796
+
797
+
798
+ def main(argv=None):
799
+ """The kernel process: build the session from `--bootstrap` with the JSON
800
+ `--options` (or its first stdin line for `-`), then read cells from stdin."""
801
+ parser = argparse.ArgumentParser()
802
+ parser.add_argument("--bootstrap", required=True)
803
+ parser.add_argument("--options", default="{}")
804
+ parser.add_argument("--forward-workspace-requests", action="store_true")
805
+ args = parser.parse_args(argv)
806
+ _serve(args.bootstrap, json.loads(sys.stdin.readline() if args.options == "-" else args.options),
807
+ forward_workspace_requests=args.forward_workspace_requests)
808
+
809
+
810
+ if __name__ == "__main__":
811
+ main()