@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,63 @@
1
+ """Ports on this machine that a process may listen on now: the session host's, a suite's
2
+ workers', the computer's workspaces', a service's. No bench hard-codes one, so they never
3
+ take each other's (a worker on 8790 and the computer's own on 8790 once did). Standard
4
+ library only."""
5
+
6
+ import os
7
+ import socket
8
+
9
+
10
+ class OwnPort:
11
+ """Place before a socketserver base to reject competing listeners on the same address.
12
+
13
+ Windows needs an exclusive bind. POSIX can reuse ports after a restart without
14
+ sharing a live listener. A plain Windows wildcard socket can still coexist with
15
+ an exclusive socket bound to a specific address.
16
+ """
17
+
18
+ allow_reuse_address = os.name != "nt"
19
+ allow_reuse_port = False
20
+
21
+ def server_bind(self):
22
+ if os.name == "nt":
23
+ self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
24
+ super().server_bind()
25
+
26
+
27
+ def free_port(preferred: int | None = None) -> int:
28
+ """`preferred` when nothing listens on it on 127.0.0.1, else a port the system gives."""
29
+ if preferred and _free(preferred):
30
+ return preferred
31
+ return free_ports(1)[0]
32
+
33
+
34
+ def free_ports(count: int, start: int | None = None) -> list[int]:
35
+ """`count` distinct ports free now: from `start` upward, skipping the taken ones (a
36
+ deploy that names its workers' ports), else ports the system gives."""
37
+ if start is None:
38
+ # Held open together, so the system gives distinct ones.
39
+ probes = [socket.socket() for _ in range(count)]
40
+ try:
41
+ for probe in probes:
42
+ probe.bind(("127.0.0.1", 0))
43
+ return [probe.getsockname()[1] for probe in probes]
44
+ finally:
45
+ for probe in probes:
46
+ probe.close()
47
+ ports, port = [], int(start)
48
+ while len(ports) < count:
49
+ if port > 65535:
50
+ raise RuntimeError(f"no {count} free ports from {start}")
51
+ if _free(port):
52
+ ports.append(port)
53
+ port += 1
54
+ return ports
55
+
56
+
57
+ def _free(port: int) -> bool:
58
+ with socket.socket() as probe:
59
+ try:
60
+ probe.bind(("127.0.0.1", port))
61
+ except OSError:
62
+ return False
63
+ return True
@@ -0,0 +1,227 @@
1
+ """Processes and locks on this computer, one way for every package: whether a process runs
2
+ (pid_alive), a lock on a file across processes and threads (file_lock), a detached process (start_detached).
3
+
4
+ Standard library only.
5
+ """
6
+
7
+ import contextlib
8
+ import functools
9
+ import os
10
+ from pathlib import Path
11
+ import subprocess
12
+ import sys
13
+ import tempfile
14
+ import time
15
+
16
+ # Linux kernels have private temporary directories and share this directory for file locks.
17
+ SHARED_LOCK_DIR = os.path.join("/dev/shm" if os.path.isdir("/dev/shm") else tempfile.gettempdir(),
18
+ "harness-locks")
19
+
20
+
21
+ # GetExitCodeProcess's code of a process that has not exited (Windows).
22
+ _STILL_ACTIVE = 259
23
+ _ERROR_ACCESS_DENIED = 5
24
+ _LIBRARY_INJECTION = ("LD_PRELOAD", "LD_AUDIT", "DYLD_INSERT_LIBRARIES")
25
+
26
+
27
+ def service_environment(environment=None, log=None) -> dict:
28
+ """Copy the environment for a service or installer, dropping inherited library injection.
29
+
30
+ Keep library search paths and let the caller apply explicit service settings on top.
31
+ Report only the removed names. Worker and desktop launchers keep their run environment.
32
+ """
33
+ result = dict(os.environ if environment is None else environment)
34
+ removed = [name for name in _LIBRARY_INJECTION if name in result]
35
+ for name in removed:
36
+ del result[name]
37
+ if removed and log is not None:
38
+ log("Removed inherited library injection: " + ", ".join(removed))
39
+ return result
40
+
41
+
42
+ def pid_alive(pid, *, reap: bool = False) -> bool:
43
+ """Whether process `pid` runs on this computer. A process we may not query runs (access
44
+ denied means it exists); this process runs; a zombie (exited, not yet reaped) does not,
45
+ and with `reap` an exited child of this process is reaped. It never signals the process
46
+ (os.kill(pid, 0) would send CTRL_C_EVENT on Windows)."""
47
+ try:
48
+ pid = int(pid)
49
+ except (TypeError, ValueError):
50
+ return False
51
+ if pid <= 0:
52
+ return False
53
+ if pid == os.getpid():
54
+ return True
55
+ if sys.platform == "win32":
56
+ import ctypes
57
+
58
+ kernel32 = ctypes.windll.kernel32
59
+ handle = kernel32.OpenProcess(0x1000, False, pid) # PROCESS_QUERY_LIMITED_INFORMATION
60
+ if not handle:
61
+ return ctypes.GetLastError() == _ERROR_ACCESS_DENIED
62
+ try:
63
+ code = ctypes.c_ulong()
64
+ if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
65
+ return True
66
+ return code.value == _STILL_ACTIVE
67
+ finally:
68
+ kernel32.CloseHandle(handle)
69
+ if reap:
70
+ try:
71
+ if os.waitpid(pid, os.WNOHANG)[0] == pid:
72
+ return False
73
+ except ChildProcessError:
74
+ pass # not our child
75
+ try:
76
+ os.kill(pid, 0)
77
+ except ProcessLookupError:
78
+ return False
79
+ except PermissionError:
80
+ return True
81
+ if sys.platform == "darwin":
82
+ state = _mac_state(pid)
83
+ return state is None or state not in (0, _MAC_ZOMBIE)
84
+ try:
85
+ return Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").split(") ", 1)[1][:1] != "Z"
86
+ except (OSError, IndexError):
87
+ return True # no /proc: it answered the signal check
88
+
89
+
90
+ # macOS has no /proc: sysctl's kinfo_proc of one process (CTL_KERN, KERN_PROC, KERN_PROC_PID)
91
+ # holds its state, kp_proc.p_stat, at byte 36 of 648 (sys/sysctl.h, sys/proc.h: 5 a zombie).
92
+ _MAC_PROCESS = (1, 14, 1)
93
+ _MAC_INFO_SIZE = 648
94
+ _MAC_STATE_AT = 36
95
+ _MAC_ZOMBIE = 5
96
+
97
+
98
+ @functools.cache
99
+ def _mac_sysctl():
100
+ """libc's sysctl, or None where it cannot be loaded (a program kernel refuses ctypes)."""
101
+ try:
102
+ import ctypes
103
+
104
+ function = ctypes.CDLL(None, use_errno=True).sysctl
105
+ function.argtypes = [ctypes.POINTER(ctypes.c_int), ctypes.c_uint, ctypes.c_void_p,
106
+ ctypes.POINTER(ctypes.c_size_t), ctypes.c_void_p, ctypes.c_size_t]
107
+ function.restype = ctypes.c_int
108
+ return function
109
+ except Exception:
110
+ return None
111
+
112
+
113
+ def _mac_state(pid: int) -> int | None:
114
+ """The state macOS keeps for process `pid` (kp_proc.p_stat: 2 runs, 5 a zombie), 0 when
115
+ it has no such process, None when it does not say."""
116
+ import ctypes
117
+
118
+ sysctl = _mac_sysctl()
119
+ if sysctl is None:
120
+ return None
121
+ names = (ctypes.c_int * 4)(*_MAC_PROCESS, pid)
122
+ info = ctypes.create_string_buffer(_MAC_INFO_SIZE)
123
+ size = ctypes.c_size_t(_MAC_INFO_SIZE)
124
+ if sysctl(names, 4, info, ctypes.byref(size), None, 0) != 0:
125
+ return None
126
+ if size.value == 0:
127
+ return 0
128
+ return info.raw[_MAC_STATE_AT] if size.value == _MAC_INFO_SIZE else None
129
+
130
+
131
+ def _open(path: Path, mode):
132
+ """A descriptor of the lock file, created when missing (with `mode`'s permission bits,
133
+ whatever the umask); read-only when another account's file cannot be opened for writing."""
134
+ path.parent.mkdir(parents=True, exist_ok=True)
135
+ flags = getattr(os, "O_BINARY", 0)
136
+ if path.parent == Path(SHARED_LOCK_DIR):
137
+ flags |= getattr(os, "O_NOFOLLOW", 0)
138
+ for _ in range(10):
139
+ # An existing file is opened without O_CREAT: in a sticky directory the kernel refuses
140
+ # O_CREAT on another account's file (fs.protected_regular), even one that exists.
141
+ try:
142
+ return os.open(path, os.O_RDWR | flags)
143
+ except PermissionError:
144
+ return os.open(path, os.O_RDONLY | flags)
145
+ except FileNotFoundError:
146
+ pass
147
+ try:
148
+ descriptor = os.open(path, os.O_RDWR | os.O_CREAT | os.O_EXCL | flags, 0o666 if mode is None else mode)
149
+ except FileExistsError:
150
+ continue # another process created it in between (or a dangling symlink)
151
+ if mode is not None and hasattr(os, "fchmod"):
152
+ with contextlib.suppress(OSError):
153
+ os.fchmod(descriptor, mode)
154
+ return descriptor
155
+ raise OSError(f"cannot open or create the lock file {path}")
156
+
157
+
158
+ def _try(descriptor) -> bool:
159
+ if sys.platform == "win32":
160
+ import msvcrt
161
+
162
+ os.lseek(descriptor, 0, os.SEEK_SET)
163
+ try:
164
+ msvcrt.locking(descriptor, msvcrt.LK_NBLCK, 1)
165
+ except OSError:
166
+ return False
167
+ return True
168
+ import fcntl
169
+
170
+ try:
171
+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
172
+ except BlockingIOError:
173
+ return False
174
+ return True
175
+
176
+
177
+ def _unlock(descriptor) -> None:
178
+ if sys.platform == "win32":
179
+ import msvcrt
180
+
181
+ os.lseek(descriptor, 0, os.SEEK_SET)
182
+ with contextlib.suppress(OSError):
183
+ msvcrt.locking(descriptor, msvcrt.LK_UNLCK, 1)
184
+ return
185
+ import fcntl
186
+
187
+ fcntl.flock(descriptor, fcntl.LOCK_UN)
188
+
189
+
190
+ @contextlib.contextmanager
191
+ def file_lock(path, *, blocking: bool = True, timeout: float | None = None, mode: int | None = None):
192
+ """Hold an exclusive lock on the file at `path` while the block runs, across the
193
+ processes and threads of this computer: fcntl.flock on POSIX, a lock on the file's first
194
+ byte on Windows. The file is created when missing (`mode`: its permission bits). It waits
195
+ for the lock, at most `timeout` seconds (then TimeoutError); without `blocking` it raises
196
+ BlockingIOError at once when another holds it. The system releases the lock when its
197
+ process ends, so a holder that died never leaves it behind."""
198
+ descriptor = _open(Path(path), mode)
199
+ try:
200
+ deadline = None if timeout is None else time.monotonic() + float(timeout)
201
+ if blocking and deadline is None and sys.platform != "win32":
202
+ import fcntl
203
+
204
+ fcntl.flock(descriptor, fcntl.LOCK_EX)
205
+ else:
206
+ while not _try(descriptor):
207
+ if not blocking:
208
+ raise BlockingIOError(f"{path} is locked by another process")
209
+ if deadline is not None and time.monotonic() > deadline:
210
+ raise TimeoutError(f"{path} stayed locked for {timeout} s")
211
+ time.sleep(0.05)
212
+ try:
213
+ yield
214
+ finally:
215
+ _unlock(descriptor)
216
+ finally:
217
+ os.close(descriptor)
218
+
219
+
220
+ def start_detached(command, *, log: Path | None = None, popen=None, **options) -> subprocess.Popen:
221
+ """`command` in a session (Windows: a process group, no window) of its own, its output appended to `log`."""
222
+ detached = ({"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW}
223
+ if os.name == "nt" else {"start_new_session": True})
224
+ with open(log, "ab") if log is not None else contextlib.nullcontext(subprocess.DEVNULL) as out:
225
+ return (popen or subprocess.Popen)(command, **{"stdin": subprocess.DEVNULL, "close_fds": True, "stdout": out,
226
+ "stderr": subprocess.DEVNULL if log is None else subprocess.STDOUT,
227
+ **detached, **options})
@@ -0,0 +1,102 @@
1
+ """JSON/HTTP transport to a worker in a separate Python environment.
2
+
3
+ This is the framework's protocol, NOT the native RoboDojo/XPolicyLab protocol.
4
+ An integration must implement Environment on the worker side.
5
+ """
6
+
7
+ import os
8
+ from urllib.error import HTTPError
9
+ from urllib.parse import urlparse
10
+
11
+ from harness.runtime.safety.approval import WORKER_APPROVAL_HEADER, worker_approval_proof
12
+ from .contracts import Action, Observation, Transition
13
+ from .http import post_json
14
+
15
+
16
+ class RemoteEnvironment:
17
+ """A worker reached over HTTP (POST /rpc), with the bearer token from
18
+ $HARNESS_WORKER_TOKEN when it is set. A worker error is raised as a RuntimeError, and
19
+ no request is retried: a motion that timed out may have executed."""
20
+
21
+ name = "remote"
22
+
23
+ def __init__(self, endpoint: str, timeout: float = 120.0, *, approval_key=None, host_controls=(), relay=None):
24
+ url = urlparse(endpoint)
25
+ if url.scheme not in ("http", "https") or not url.hostname or url.username or url.password:
26
+ raise ValueError("Worker endpoint must be an HTTP(S) URL without embedded credentials")
27
+ self.endpoint = endpoint.rstrip("/")
28
+ self.timeout = timeout
29
+ self.token = os.environ.get("HARNESS_WORKER_TOKEN")
30
+ self.approval_key = approval_key
31
+ self.host_controls = frozenset(host_controls)
32
+ self.program_controls = frozenset()
33
+ self.relay = relay
34
+
35
+ def _call(self, method: str, **arguments):
36
+ if method == "call" and arguments["name"] in self.host_controls and self.approval_key is None:
37
+ if self.relay is None:
38
+ raise RuntimeError("Worker control requires a host connection")
39
+ return self.relay(arguments, self.timeout)
40
+ return self._request(method, arguments, approval_key=self.approval_key)
41
+
42
+ def _request(self, method, arguments, *, approval_key=None):
43
+ headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
44
+ request = {"method": method, "arguments": arguments}
45
+ if approval_key:
46
+ headers[WORKER_APPROVAL_HEADER] = worker_approval_proof(approval_key, request)
47
+ # Deliberately no automatic retry: a timed-out motion may have executed.
48
+ try:
49
+ result = post_json(self.endpoint + "/rpc", request, headers, self.timeout)
50
+ except HTTPError as error:
51
+ with error:
52
+ detail = error.read().decode(errors="replace")
53
+ raise RuntimeError(f"Worker HTTP {error.code}: {detail}") from error
54
+ if "error" in result:
55
+ raise RuntimeError(result["error"])
56
+ return result["result"]
57
+
58
+ def tools(self) -> list[dict]:
59
+ """The worker's tool schemas. Checks its protocol version and takes its name; it
60
+ also serves as the check that a worker answers."""
61
+ description = self._call("describe")
62
+ if description["protocol_version"] != 1:
63
+ raise ValueError("Unsupported worker protocol version")
64
+ if self.approval_key:
65
+ if not (description.get("authenticated_controls") or description.get("managed_approval")) or not description.get("managed_control_calls"):
66
+ raise RuntimeError("Worker did not enable authenticated controls")
67
+ self.host_controls = frozenset([*description["managed_control_calls"], "sensitive_approval"])
68
+ self.program_controls = frozenset(description.get("program_control_calls", ())) & self.host_controls
69
+ self.name = description["name"]
70
+ return description["tools"]
71
+
72
+ def reset(self, task: str, seed: int) -> Observation:
73
+ """Start an episode of `task` with `seed` and return its first observation."""
74
+ return Observation(**self._call("reset", task=task, seed=seed))
75
+
76
+ def execute(self, action: Action, episode_id: str, step: int) -> Transition:
77
+ """Execute `action` on the observation (`episode_id`, `step`); the worker rejects a
78
+ stale pair. Returns the transition to the next observation."""
79
+ return Transition.from_dict(self._call(
80
+ "execute", action=action.to_dict(), episode_id=episode_id, step=step,
81
+ ))
82
+
83
+ def call(self, name: str, **arguments):
84
+ """Invoke an environment-specific worker method."""
85
+ return self._call("call", name=name, arguments=arguments)
86
+
87
+ def managed_call(self, name, *, approval_key, **arguments):
88
+ """Send one worker control call with the trusted host's proof."""
89
+ return self._request("call", {"name": name, "arguments": arguments}, approval_key=approval_key)
90
+
91
+ def sensitive_approval(self, op, *, approval_key, **arguments):
92
+ """Host only: inspect a worker request, retry after assent, or cancel the request.
93
+
94
+ The host supplies its key directly. The proof authenticates the request without putting the key in
95
+ the RPC body, and the generated program never needs a copy of the key or proof.
96
+ """
97
+ return self._request("sensitive_approval", {"op": op, **arguments}, approval_key=approval_key)
98
+
99
+ def close(self) -> None:
100
+ """Nothing: the worker belongs to the process that launched it."""
101
+ # Worker lifecycle is explicitly owned by its launching process.
102
+ pass
@@ -0,0 +1,166 @@
1
+ """Spans: when each part of an episode worked, for the timeline of a run.
2
+
3
+ A span is a stretch of wall-clock time one part spent on one thing: the main model
4
+ answering, a program running, a skill's bounded execution, one call to a service. It
5
+ starts with a `span_start` record and ends with a `span_end` record of the same id. A
6
+ span of code an entry runs (runtime/execution/entries.py) names that entry (`entry`); the entries
7
+ themselves start and end with `entry_start` and `entry_end` records.
8
+ Parts of the host (the conversation) write them to the trace themselves; code in the
9
+ kernel process writes them through the sink the kernel installs (runtime/execution/kernel.py),
10
+ and the host adds them to the trace as they arrive. Without a sink a span costs
11
+ nothing and records nothing.
12
+
13
+ A span's `lane` names the kind of part that worked (PARTS). The timeline does not draw
14
+ one lane per kind: core/lanes.py reads the lanes from the records, one per entry (and
15
+ the model, the verifier, the environment), as they start and end.
16
+ """
17
+
18
+ from contextlib import contextmanager
19
+ import threading
20
+ import time
21
+ import uuid
22
+
23
+
24
+ # The kinds of part a span is of (its `lane` field).
25
+ PARTS = ("model", "verifier", "program", "skill", "service", "env")
26
+
27
+ _sink = None
28
+ _local = threading.local()
29
+
30
+
31
+ def _emit(record) -> None:
32
+ try:
33
+ _sink(record)
34
+ except Exception:
35
+ # A span that cannot be sent is lost; the code it records goes on.
36
+ pass
37
+
38
+
39
+ def note(kind: str, **detail) -> None:
40
+ """Send the host a note of `kind` (a plan the user sees) now, while the program runs;
41
+ nothing without a sink."""
42
+ if _sink is not None:
43
+ _emit({"op": "note", "kind": kind, "time": time.time(), **detail})
44
+
45
+
46
+ def step(skill: str, number: int, what: str, ok: bool, seconds: float | None = None, reason: str | None = None,
47
+ of: int | None = None, library=None) -> None:
48
+ """Say a step of a skill's plan ended (step `number` of `of`, what it did, whether it
49
+ did it, in how many seconds, why not): a skill_step record, news for the model's next
50
+ look while the program runs (runtime/conversation.py); nothing without a sink. A step
51
+ of a library entry's test or replay says so (`testing`, set by testing())."""
52
+ note("skill_step", skill=skill, step=int(number), what=str(what)[:200], ok=bool(ok),
53
+ **({"seconds": round(float(seconds), 1)} if seconds is not None else {}),
54
+ **({"reason": str(reason)[:300]} if reason else {}), **({"of": int(of)} if of else {}),
55
+ **({"library_key": library[0], "library_sha256": library[1]} if library else {}),
56
+ **({"library_revision": library[2]} if library and len(library) > 2 else {}),
57
+ **({"testing": True} if in_test() else {}))
58
+
59
+
60
+ def in_test():
61
+ return getattr(_local, "testing", False)
62
+
63
+
64
+ @contextmanager
65
+ def testing(active=True):
66
+ """Keep proposal and replay steps out of practice use counts."""
67
+ previous = in_test()
68
+ _local.testing = active
69
+ try:
70
+ yield
71
+ finally:
72
+ _local.testing = previous
73
+
74
+
75
+ def record(op: str, **detail) -> None:
76
+ """Send the host a record `op` other than a span's (an entry's start or end, with
77
+ `detail`) now; nothing without a sink."""
78
+ if _sink is not None:
79
+ _emit({"op": op, "time": time.time(), **{key: _short(value) for key, value in detail.items()}})
80
+
81
+
82
+ def set_entry(entry):
83
+ """The spans this thread records from now on name `entry` (an entry id; None: none);
84
+ the one they named before."""
85
+ saved = _local.__dict__.get("entry")
86
+ _local.entry = entry
87
+ return saved
88
+
89
+
90
+ def current_entry():
91
+ return getattr(_local, "entry", None)
92
+
93
+
94
+ def connected() -> bool:
95
+ """Whether notes reach a host (a kernel installed the sink)."""
96
+ return _sink is not None
97
+
98
+
99
+ def set_sink(sink) -> None:
100
+ """Send every span record from now on to `sink(record)` (None: record nothing)."""
101
+ global _sink
102
+ _sink = sink
103
+
104
+
105
+ def current():
106
+ """The id of the span this thread is in (None outside every span)."""
107
+ stack = _local.__dict__.get("stack")
108
+ return stack[-1] if stack else None
109
+
110
+
111
+ @contextmanager
112
+ def under(parent):
113
+ """Spans recorded inside have `parent` (a span id from current(), or None) as their
114
+ parent: code another thread runs for a span (the tick runs a skill's steps)."""
115
+ saved = _local.__dict__.get("stack")
116
+ _local.stack = [parent] if parent is not None else []
117
+ try:
118
+ yield
119
+ finally:
120
+ _local.stack = saved if saved is not None else []
121
+
122
+
123
+ def _short(value, limit=200):
124
+ """A value as a span detail keeps it: JSON scalars as they are, anything else as a
125
+ clipped repr (parameters may hold arrays or callables)."""
126
+ if value is None or isinstance(value, (bool, int, float)):
127
+ return value
128
+ if isinstance(value, str):
129
+ return value if len(value) <= limit else value[:limit] + "..."
130
+ if isinstance(value, (list, tuple)) and len(value) <= 16 and all(
131
+ item is None or isinstance(item, (bool, int, float, str)) for item in value):
132
+ return [_short(item, limit) for item in value]
133
+ if isinstance(value, dict) and len(value) <= 16:
134
+ return {str(key): _short(item, limit) for key, item in value.items()}
135
+ text = repr(value)
136
+ return text if len(text) <= limit else text[:limit] + "..."
137
+
138
+
139
+ @contextmanager
140
+ def span(lane: str, name: str, **detail):
141
+ """Record the code inside as a span of the part `lane` (PARTS) named `name` with `detail`. Yields a
142
+ dict whose items end up in the span's end record (an event kind, a status); an
143
+ exception leaving the block is recorded as the span's error and raised on."""
144
+ if _sink is None:
145
+ yield {}
146
+ return
147
+ stack = _local.__dict__.setdefault("stack", [])
148
+ identifier = uuid.uuid4().hex[:12]
149
+ record = {"op": "span_start", "id": identifier, "lane": lane, "name": name, "time": time.time(),
150
+ "parent": stack[-1] if stack else None, **{key: _short(value) for key, value in detail.items()}}
151
+ if _local.__dict__.get("entry") is not None:
152
+ record["entry"] = _local.entry
153
+ _emit(record)
154
+ stack.append(identifier)
155
+ end = {}
156
+ try:
157
+ yield end
158
+ except BaseException as error:
159
+ # An execution's event raised as an escalation is its end, not an error.
160
+ if "event_kind" not in end:
161
+ end.setdefault("error", f"{type(error).__name__}: {_short(str(error))}")
162
+ raise
163
+ finally:
164
+ stack.pop()
165
+ _emit({"op": "span_end", "id": identifier, "time": time.time(),
166
+ **{key: _short(value) for key, value in end.items()}})