@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,720 @@
1
+ """The session host's HTTP server: the API every frontend drives conversations and follows
2
+ episodes through, over a runs directory, and the app package's pages when it is installed.
3
+
4
+ Standard library only (http.server). Every API call needs the session key: the
5
+ `token` query parameter of the URL harness app prints (the page then keeps it in a
6
+ cookie), or the X-Session-API-Key header. Records are followed with server-sent
7
+ events: a client that reconnects sends Last-Event-ID (the last `seq` it has) and gets
8
+ what came after it. Every record they send carries `view`, its items (transcript.py).
9
+
10
+ GET /api/runs the episodes, newest first
11
+ GET /api/meta?run=R an episode's manifest, summary, ending and usage
12
+ GET /api/events?run=R&after=N its trace records after seq N
13
+ GET /api/lanes?run=R its timeline's lanes, spans and markers (core/lanes.py
14
+ Lanes.snapshot), what every web view draws
15
+ GET /api/stream?run=R the same, then new ones as they are written
16
+ GET /api/file?run=R&name=F one of its files (videos, logs), or a range of it
17
+
18
+ The page at / (the app's), the runs page at /dev, and at
19
+ /overlay?run=R the timeline overlay's (the app package's overlay: one run's timeline, or
20
+ without run the newest session that runs). Another package's pages are at the paths its host
21
+ module declares (pages(), harness/extensions.py), their files at /static/<package>/<file>;
22
+ its API (`api`) at /api/<package>/<name>, GET and POST alike, with the session key as every
23
+ other route.
24
+
25
+ Conversations the server runs itself (runtime/conversation.py, interactive), written
26
+ under <runs>/ui/; a POST takes a JSON body and the session key:
27
+
28
+ GET /api/options experiments, model files and the deploy to start from
29
+ GET /api/libraries what the agent learned: the libraries under $HARNESS_HOME
30
+ GET /api/library?name=N | run=R a library's entries, or a run's memory beside its library's
31
+ (runtime/task/context.py rows: one format, columns and cells)
32
+ POST /api/conversations start one: experiment, task, seed, model, endpoint,
33
+ instruction, confirmation, sets, deploy, title,
34
+ frontend, workspace (a kind: the app's server
35
+ takes one from its pool for the session);
36
+ {run, session}
37
+ POST /api/conversations/message {run, text, files}: a message for the model's next call (files:
38
+ paths on this computer it attaches)
39
+ POST /api/conversations/pause {run}: stop at the next execution step
40
+ POST /api/conversations/resume {run}
41
+ POST /api/conversations/model {run, model, reasoning_effort}: the main model (another id of
42
+ its provider) and its effort (none, low, medium, high; "" the
43
+ provider's default) from its next call on
44
+ POST /api/conversations/confirm {run, accept, reason, remember}: the verdict on a waiting program, or
45
+ on a step waiting for physical input (remember: once, app,
46
+ session, always)
47
+ POST /api/conversations/close {run}: end the episode
48
+
49
+ A conversation's programs may start sub-agents (runtime/task/delegation.py); this server gives
50
+ them no workspaces (it has no pool: delegate says so), the app's does (app.py).
51
+
52
+ A run is the path of an episode under the runs directory or, for a conversation the
53
+ server runs, also its session's id ("<session>/<agent>" for an agent of it). The sessions
54
+ it runs, each a tree of agents (host/sessions.py):
55
+
56
+ GET /api/sessions the sessions, newest first
57
+ GET /api/sessions/show?id=S&lines=N one session, its agents and the last lines of each
58
+ POST /api/sessions/stop {id, agent}: end its agents (or that one)
59
+ POST /api/sessions/approve {id, agent, accept, reason}: the verdict on what waits
60
+ """
61
+
62
+ from contextlib import suppress
63
+ from functools import partial
64
+ import hmac
65
+ from http import HTTPStatus
66
+ from http.cookies import SimpleCookie
67
+ from http.server import BaseHTTPRequestHandler, SimpleHTTPRequestHandler, ThreadingHTTPServer
68
+ import json
69
+ from pathlib import Path
70
+ import re
71
+ import secrets
72
+ import threading
73
+ import time
74
+ from urllib.parse import parse_qs, urlparse
75
+
76
+ from .. import __version__
77
+ from ..settings import ChoiceRequired
78
+ from .sessions import ENDED, LIVE, Sessions, live
79
+ from ..paths import find
80
+ from harness.runtime.safety import approval
81
+ from harness.core import episodes as runs
82
+ from ..core.ports import OwnPort
83
+ from ..transcript import TextTranscript, items
84
+
85
+
86
+ def statics() -> dict:
87
+ """{package: its ui/static/ folder} of the packages this process uses that have one."""
88
+ from ..paths import packages
89
+
90
+ return {package.name: (package.path / "ui" / "static").resolve() for package in packages()
91
+ if (package.path / "ui" / "static").is_dir()}
92
+
93
+
94
+ def static() -> Path | None:
95
+ """The folder of the page at / and of the files at /static/<file>: the app package's
96
+ ui/static/; without it, that of the first package whose host module gives a page at /,
97
+ else of the first package that has pages. None when no package this process uses has them."""
98
+ from ..extensions import hosts
99
+
100
+ folders = statics()
101
+ if "app" in folders or not folders:
102
+ return folders.get("app")
103
+ for package, module in hosts():
104
+ if "/" in (getattr(module, "pages", None) or {}) and package.name in folders:
105
+ return folders[package.name]
106
+ return next(iter(folders.values()))
107
+
108
+
109
+ def pages() -> dict:
110
+ """{path: (folder, file)}: the pages this server has. The legacy ones (PAGES) are files
111
+ of static()'s folder; a package's host module adds its own (`pages`, harness/extensions.py),
112
+ files of its ui/static/. The page at / stays the app's; "/": None is the server's own
113
+ (Server.page)."""
114
+ from ..extensions import hosts
115
+
116
+ folders = statics()
117
+ default = static()
118
+ found = {path: (default, page) for path, page in PAGES.items()
119
+ if page is None or default is not None and (default / page).is_file()}
120
+ for package, module in hosts():
121
+ folder = folders.get(package.name)
122
+ for path, page in (getattr(module, "pages", None) or {}).items():
123
+ if folder is None or (path == "/" and folder != default) or path in found and path != "/":
124
+ continue
125
+ found[path] = (folder, page)
126
+ return found
127
+
128
+
129
+ def package_api(path: str):
130
+ """The handler a package's host module gives for /api/<package>/<name> (its `api`,
131
+ harness/extensions.py), or None."""
132
+ from ..extensions import hosts
133
+
134
+ package, _, name = path.removeprefix("/api/").partition("/")
135
+ if not path.startswith("/api/") or not name:
136
+ return None
137
+ for found, module in hosts():
138
+ if found.name == package:
139
+ return (getattr(module, "api", None) or {}).get(name)
140
+ return None
141
+
142
+
143
+ MISSING = (b"<!doctype html><meta charset=utf-8><title>The Harness</title><p>No web frontend is installed. Use the terminal CLI or install a frontend package. "
144
+ b"")
145
+ STATIC_TYPES = {".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8",
146
+ ".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png",
147
+ ".json": "application/json; charset=utf-8"}
148
+ COOKIE = "harness_ui"
149
+ # The pages of the package at / besides that one (the server's own: Server.page); other
150
+ # packages' pages are their host modules' (pages()).
151
+ PAGES = {"/": None, "/dev": "index.html", "/overlay": "overlay.html", "/replay": "app.html"}
152
+ # The workspace kind of a bench's worker (the computer package's workspaces.py KINDS, the
153
+ # other way round); a computer worker with the option workspace = "apps" or "display"
154
+ # serves that kind.
155
+ BENCH_KINDS = {"browser": "browser", "computer": "desktop"}
156
+
157
+
158
+ def bench_kind(bench: str, worker: dict | None = None) -> str | None:
159
+ """The workspace kind an experiment's worker serves (None: one no pool starts)."""
160
+ if bench == "computer" and (worker or {}).get("workspace") in ("apps", "display"):
161
+ return worker["workspace"]
162
+ return BENCH_KINDS.get(bench)
163
+ # Seconds between looks at a followed trace, and between keep-alive comments.
164
+ POLL_SECONDS = 0.25
165
+ KEEPALIVE_SECONDS = 15.0
166
+
167
+
168
+ # A run's lanes as last computed: {directory: ((size, mtime) of its trace, snapshot)}.
169
+ _LANES = {}
170
+ _LANES_LOCK = threading.Lock()
171
+
172
+
173
+ def lanes_of(directory: Path) -> dict:
174
+ """The lanes of the run in `directory` (core/lanes.py: the one computation of them), as
175
+ a snapshot every web view draws; computed again only when its trace changed."""
176
+ from ..core.lanes import Lanes
177
+
178
+ trace = Path(directory) / "events.jsonl"
179
+ try:
180
+ stat = trace.stat()
181
+ mark = (stat.st_size, stat.st_mtime_ns)
182
+ except OSError:
183
+ mark = None
184
+ with _LANES_LOCK:
185
+ cached = _LANES.get(str(directory))
186
+ if cached and cached[0] == mark:
187
+ return cached[1]
188
+ lanes = Lanes()
189
+ for record in runs.read_records(Path(directory)):
190
+ lanes.add(record)
191
+ snapshot = lanes.snapshot()
192
+ with _LANES_LOCK:
193
+ _LANES[str(directory)] = (mark, snapshot)
194
+ return snapshot
195
+
196
+
197
+ class Server(OwnPort, ThreadingHTTPServer):
198
+ """The GUI's HTTP server over the runs directory `root`, with the session key
199
+ `token` (a new random one by default)."""
200
+
201
+ daemon_threads = True
202
+ # The page at /, and the request handler (the app's server adds routes).
203
+ page = "index.html"
204
+ handler_class = None
205
+
206
+ def __init__(self, address, root: Path, token: str | None = None, deploy: str | None = None):
207
+ self.root = Path(root).resolve()
208
+ self.token = token or secrets.token_urlsafe(18)
209
+ # The deploy experiments are resolved against (default $HARNESS_DEPLOY).
210
+ self.deploy = deploy
211
+ # The conversations this server runs, by run, as sessions (host/sessions.py).
212
+ self.conversations = Sessions()
213
+ self._starting = threading.Lock()
214
+ super().__init__(address, self.handler_class or Handler)
215
+
216
+ def url(self) -> str:
217
+ """The address to open, with the session key."""
218
+ host, port = self.server_address[:2]
219
+ host = "127.0.0.1" if host in ("0.0.0.0", "") else host
220
+ return f"http://{host}:{port}/?token={self.token}"
221
+
222
+ def info(self) -> dict:
223
+ """What the page is told about the server, the statuses of a conversation and the words of an approval."""
224
+ return {"version": __version__, "root": str(self.root), "live": True, "statuses": {"live": LIVE, "ended": ENDED},
225
+ "words": approval.WORDS}
226
+
227
+ def touch(self) -> None:
228
+ """A client asked for something (the session host counts this as activity)."""
229
+
230
+ def model_changed(self, run: str, changed: dict) -> None:
231
+ """A conversation's model or reasoning effort changed (POST /api/conversations/model)."""
232
+
233
+ def session_directory(self, request: dict, config, seed: int) -> tuple[Path, str | None]:
234
+ """Where a conversation started here is written, and its run (None: its session's id)."""
235
+ directory = self.root / "ui" / runs.new_name(config.task) / f"seed-{seed}"
236
+ return directory, directory.relative_to(self.root).as_posix()
237
+
238
+ def directory(self, run: str) -> Path:
239
+ """The episode directory of `run`: a conversation's this server runs, else an episode
240
+ under the root (ValueError when there is none)."""
241
+ found = self.conversations.resolve(run)
242
+ if found is not None:
243
+ return Path(self.conversations[found].directory).resolve()
244
+ return runs.episode_dir(self.root, run)
245
+
246
+ def sub_agents(self, kind: str | None):
247
+ """The sub-agents of a session started here whose workspace is of `kind` (None: a
248
+ bench no workspace pool serves)."""
249
+ from harness.runtime.task.delegation import Agents
250
+
251
+ return Agents(sessions=self.conversations)
252
+
253
+ def start_conversation(self, request: dict) -> str:
254
+ """Start an interactive conversation (see the module docstring) and return its run."""
255
+ from ..config.agent import REPO, package_lock
256
+ from ..core import sha256
257
+ from ..bench import bench_spec
258
+ from ..extensions import require
259
+ from harness.runtime.task.run import TaskRun
260
+ from harness.runtime.safety.approval import confirmation_policy
261
+
262
+ # An experiment's worker: the eval package's (installed first when it is not).
263
+ load_experiment = require("load_experiment", "commands", "program")
264
+ preflight = require("preflight", "commands", "program")
265
+ experiment = request.get("experiment") or "dev"
266
+ path = Path(experiment)
267
+ if not path.suffix:
268
+ path = (find(f"configs/experiments/{experiment}.toml")
269
+ or [REPO / "configs" / "experiments" / f"{experiment}.toml"])[0]
270
+ if not path.is_file():
271
+ raise ValueError(f"no experiment {experiment}")
272
+ seed = int(request.get("seed", 0))
273
+ sets = [str(item) for item in request.get("sets") or []]
274
+ task = request.get("task") or None
275
+ experiment = load_experiment(path, deploy=request.get("deploy") or self.deploy, sets=sets,
276
+ tasks=[task] if task else None,
277
+ seeds=[seed], model=request.get("model") or None)
278
+ confirmation = confirmation_policy(request.get("confirmation") or None)
279
+ workspace = self.workspace(request, experiment)
280
+ try:
281
+ config = experiment.task_config(task, [seed], endpoint=(workspace or {}).get("endpoint")
282
+ or request.get("endpoint") or None)
283
+ if config.lock is not None and config.lock.get("schema") == 3:
284
+ packages = {**config.lock["packages"], **package_lock([bench_spec(experiment.bench).path])}
285
+ config.lock = {**config.lock, "packages": packages}
286
+ config.agent_id = sha256(config.lock)[:16]
287
+ if (workspace or {}).get("python"):
288
+ config.runtime = {**config.runtime, "python": workspace["python"]}
289
+ if not config.environment.get("endpoint"):
290
+ raise ValueError("no worker endpoint: give one, or set endpoint in the experiment")
291
+ # As harness program: the agent's services must answer (on-demand ones get the broker).
292
+ preflight(experiment, log=lambda message: print(message, flush=True))
293
+ with self._starting:
294
+ directory, run = self.session_directory(request, config, seed)
295
+ kind = (workspace or {}).get("kind") or bench_kind(experiment.bench, experiment.worker)
296
+ conversation = TaskRun(config, seed, directory, interactive=True, confirmation=confirmation,
297
+ environment=(workspace or {}).get("environment"),
298
+ instruction=(request.get("instruction") or "").strip() or None,
299
+ agents=self.sub_agents(kind),
300
+ )
301
+ conversation.workspace_kind = kind
302
+ session = self.conversations.add(run, conversation, title=request.get("title") or None,
303
+ frontend=request.get("frontend") or None)
304
+ thread = conversation.start()
305
+ except BaseException:
306
+ if workspace is not None:
307
+ workspace["release"]()
308
+ raise
309
+ if workspace is not None:
310
+ # The workspace goes back to the pool when the episode ends.
311
+ threading.Thread(target=lambda: (thread.join(), workspace["release"]()), name="workspace-release",
312
+ daemon=True).start()
313
+ return run or session
314
+
315
+ def workspace(self, request: dict, experiment):
316
+ """The workspace a conversation asked for ({endpoint, python, release}), or None.
317
+ This server keeps none: the app's server takes one from its pool."""
318
+ if request.get("workspace"):
319
+ raise ValueError("this server keeps no workspaces: give the worker's endpoint")
320
+ return None
321
+
322
+
323
+ class Handler(BaseHTTPRequestHandler):
324
+ server: Server
325
+ protocol_version = "HTTP/1.1"
326
+
327
+ def log_message(self, format, *args):
328
+ pass
329
+
330
+ # Answers.
331
+
332
+ def _send(self, status, body: bytes, content_type: str, headers=()):
333
+ self.send_response(status)
334
+ self.send_header("Content-Type", content_type)
335
+ self.send_header("Content-Length", str(len(body)))
336
+ self.send_header("Cache-Control", "no-store")
337
+ for name, value in headers:
338
+ self.send_header(name, value)
339
+ self.end_headers()
340
+ if self.command != "HEAD":
341
+ self.wfile.write(body)
342
+
343
+ def _file(self, path: Path, content_type: str):
344
+ """A file, or the one byte range a Range header asks for (206; 416 outside it), so a video can seek."""
345
+ data = path.read_bytes()
346
+ asked = re.fullmatch(r"\s*bytes=(\d*)-(\d*)\s*", self.headers.get("Range") or "")
347
+ first, last, size = *(asked.groups() if asked else ("", "")), len(data)
348
+ if not first and not last:
349
+ return self._send(HTTPStatus.OK, data, content_type, [("Accept-Ranges", "bytes")])
350
+ start, end = (int(first), min(int(last or size - 1), size - 1)) if first else (max(size - int(last), 0), size - 1)
351
+ if start > end or start >= size:
352
+ return self._send(HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE, b"", content_type, [("Content-Range", f"bytes */{size}")])
353
+ self._send(HTTPStatus.PARTIAL_CONTENT, data[start:end + 1], content_type,
354
+ [("Accept-Ranges", "bytes"), ("Content-Range", f"bytes {start}-{end}/{size}")])
355
+
356
+ def _json(self, data, status=HTTPStatus.OK):
357
+ self._send(status, json.dumps(data, ensure_ascii=False, allow_nan=False).encode(),
358
+ "application/json; charset=utf-8")
359
+
360
+ def _error(self, status, message):
361
+ self._json({"error": message}, status)
362
+
363
+ # The session key.
364
+
365
+ # Routes that take more than 1 MB (the app's skill upload).
366
+ body_limits = {}
367
+
368
+ def _body(self) -> dict:
369
+ if (self.headers.get("Content-Type") or "").split(";")[0].strip() != "application/json":
370
+ raise ValueError("send JSON")
371
+ size = int(self.headers.get("Content-Length") or 0)
372
+ if not 0 <= size <= self.body_limits.get(urlparse(self.path).path, 1024 * 1024):
373
+ raise ValueError("body too large")
374
+ data = json.loads(self.rfile.read(size) or b"{}")
375
+ if not isinstance(data, dict):
376
+ raise ValueError("send a JSON object")
377
+ return data
378
+
379
+ def _authorized(self, query) -> bool:
380
+ self.server.touch()
381
+ given = self.headers.get("X-Session-API-Key") or (query.get("token") or [None])[0]
382
+ if given is None:
383
+ cookie = SimpleCookie(self.headers.get("Cookie") or "")
384
+ given = cookie[COOKIE].value if COOKIE in cookie else None
385
+ return given is not None and hmac.compare_digest(str(given), self.server.token)
386
+
387
+ # Requests.
388
+
389
+ def do_GET(self):
390
+ url = urlparse(self.path)
391
+ query = parse_qs(url.query)
392
+ if url.path.startswith("/static/"):
393
+ return self._static(url.path[len("/static/"):])
394
+ found = pages()
395
+ if not self._authorized(query):
396
+ if url.path in found:
397
+ return self._send(HTTPStatus.UNAUTHORIZED, b"Open the address harness app printed (it has the "
398
+ b"session key).\n", "text/plain; charset=utf-8")
399
+ return self._error(HTTPStatus.UNAUTHORIZED, "missing or wrong session key")
400
+ try:
401
+ if url.path in found:
402
+ folder, page = found[url.path]
403
+ return self._page(query, page or self.server.page, folder)
404
+ route = getattr(self, "get_" + url.path.removeprefix("/api/").replace("/", "_"), None)
405
+ if not url.path.startswith("/api/") or route is None:
406
+ handler = package_api(url.path)
407
+ if handler is None:
408
+ return self._error(HTTPStatus.NOT_FOUND, "no such route")
409
+ data = {key: values[0] for key, values in query.items() if key != "token"}
410
+ return self._answer(handler(self.server, data))
411
+ return route(query)
412
+ except (ValueError, KeyError) as error:
413
+ return self._error(HTTPStatus.BAD_REQUEST, str(error))
414
+ except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
415
+ return None
416
+
417
+ do_HEAD = do_GET
418
+
419
+ def do_POST(self):
420
+ url = urlparse(self.path)
421
+ if not self._authorized({}):
422
+ return self._error(HTTPStatus.UNAUTHORIZED, "missing or wrong session key")
423
+ route = getattr(self, "post_" + url.path.removeprefix("/api/").replace("/", "_"), None)
424
+ if not url.path.startswith("/api/") or route is None:
425
+ handler = package_api(url.path)
426
+ if handler is None:
427
+ return self._error(HTTPStatus.NOT_FOUND, "no such route")
428
+ route = lambda body: self._answer(handler(self.server, body)) # noqa: E731
429
+ try:
430
+ return route(self._body())
431
+ except ChoiceRequired as error:
432
+ return self._json({"error": str(error), "choice_required": error.choice}, HTTPStatus.CONFLICT)
433
+ except (ValueError, KeyError, RuntimeError, OSError) as error:
434
+ return self._error(HTTPStatus.BAD_REQUEST, f"{type(error).__name__}: {error}")
435
+
436
+ def _answer(self, answer):
437
+ """A package handler's answer: JSON, or a tuple (body, content type, headers) as it is."""
438
+ if isinstance(answer, tuple):
439
+ body, content_type, headers = answer
440
+ return self._send(HTTPStatus.OK, body, content_type, headers)
441
+ return self._json(answer)
442
+
443
+ def _conversation(self, body):
444
+ run = self.server.conversations.resolve(body.get("run"))
445
+ if run is None:
446
+ raise ValueError("this server does not run that conversation")
447
+ return self.server.conversations[run]
448
+
449
+ def get_options(self, query):
450
+ from ..config.agent import MODELS_ROOT
451
+
452
+ experiments = sorted({path.stem for folder in find("configs/experiments") for path in folder.glob("*.toml")})
453
+ models = sorted(path.stem for path in MODELS_ROOT.glob("*.toml"))
454
+ self._json({"experiments": experiments, "models": models, "deploy": self.server.deploy,
455
+ "confirmation": ["never", "always"]})
456
+
457
+ def post_conversations(self, body):
458
+ run = self.server.start_conversation(body)
459
+ found = self.server.conversations.session_of(run)
460
+ self._json({"run": run, "session": found[0] if found else None})
461
+
462
+ def post_conversations_message(self, body):
463
+ self._conversation(body).send_message(str(body.get("text") or ""), files=body.get("files") or ())
464
+ self._json({"ok": True})
465
+
466
+ def _control(self, body, capability, method, *args):
467
+ conversation = self._conversation(body)
468
+ if not (getattr(conversation, "capabilities", None) or {}).get(capability):
469
+ raise ValueError(f"the conversation does not support {capability}")
470
+ return getattr(conversation, method)(*args)
471
+
472
+ def post_conversations_steer(self, body):
473
+ self._control(body, "steer", "steer", str(body.get("text") or ""), body.get("files") or ())
474
+ self._json({"ok": True})
475
+
476
+ def post_conversations_cancel(self, body):
477
+ self._control(body, "cancel_turn", "cancel")
478
+ self._json({"ok": True})
479
+
480
+ def post_conversations_config(self, body):
481
+ self._json(self._control(body, "configure", "set_config", body.get("id"), body.get("value")))
482
+
483
+ def post_conversations_answer(self, body):
484
+ self._control(body, "answer", "answer", body.get("request_id"), body.get("content"))
485
+ self._json({"ok": True})
486
+
487
+ def post_conversations_diff(self, body):
488
+ self._json(self._control(body, "diff", "diff"))
489
+
490
+ def post_conversations_merge(self, body):
491
+ self._json(self._control(body, "merge", "merge"))
492
+
493
+ def post_conversations_discard(self, body):
494
+ self._json(self._control(body, "discard", "discard"))
495
+
496
+ def post_conversations_terminal(self, body):
497
+ self._control(body, "terminal_input", "terminal_input", body.get("text"))
498
+ self._json({"ok": True})
499
+
500
+ def post_conversations_pause(self, body):
501
+ self._conversation(body).pause()
502
+ self._json({"ok": True})
503
+
504
+ def post_conversations_resume(self, body):
505
+ self._conversation(body).resume()
506
+ self._json({"ok": True})
507
+
508
+ def post_conversations_confirm(self, body):
509
+ if type(body.get("accept")) is not bool:
510
+ raise ValueError("accept must be a boolean")
511
+ self._conversation(body).confirm(body["accept"], str(body.get("reason") or ""),
512
+ body.get("remember") or None,
513
+ **({"request_id": body["request_id"]} if body.get("request_id") else {}))
514
+ self._json({"ok": True})
515
+
516
+ def post_conversations_model(self, body):
517
+ run = self.server.conversations.resolve(body.get("run"))
518
+ changed = self._conversation(body).set_model(body.get("model") or None, body.get("reasoning_effort"))
519
+ self.server.model_changed(run, changed)
520
+ self._json({"ok": True, **changed})
521
+
522
+ def post_conversations_close(self, body):
523
+ self._conversation(body).close()
524
+ self._json({"ok": True})
525
+
526
+ def _page(self, query, page="index.html", folder=None):
527
+ folder = folder or static()
528
+ body = (folder / page).read_bytes() if folder is not None and (folder / page).is_file() else MISSING
529
+ headers = []
530
+ if query.get("token"):
531
+ headers.append(("Set-Cookie", f"{COOKIE}={self.server.token}; HttpOnly; SameSite=Strict; Path=/"))
532
+ self._send(HTTPStatus.OK, body, STATIC_TYPES[".html"], headers)
533
+
534
+ def _static(self, name):
535
+ # /static/<package>/<file>: a package's; /static/<file>: static()'s (the app's).
536
+ package, _, rest = name.partition("/")
537
+ folders = statics()
538
+ folder = folders[package] if rest and package in folders else static()
539
+ name = rest if rest and package in folders else name
540
+ path = (folder / name).resolve() if folder is not None else None
541
+ if path is None or folder not in path.parents or not path.is_file() or path.suffix not in STATIC_TYPES:
542
+ return self._error(HTTPStatus.NOT_FOUND, "no such file")
543
+ self._file(path, STATIC_TYPES[path.suffix])
544
+
545
+ def _run(self, query) -> Path:
546
+ run = (query.get("run") or [None])[0]
547
+ if not run:
548
+ raise ValueError("give run=")
549
+ return self.server.directory(run)
550
+
551
+ # The sessions.
552
+
553
+ def _session(self, identifier) -> dict:
554
+ run = self.server.conversations.resolve(identifier)
555
+ found = self.server.conversations.session_of(run) if run else None
556
+ row = self.server.conversations.describe(found[0]) if found else None
557
+ if row is None:
558
+ raise ValueError(f"this server runs no session {identifier}")
559
+ return {**row, "selected_agent": found[1]}
560
+
561
+ def get_sessions(self, query):
562
+ self._json({"sessions": self.server.conversations.sessions()})
563
+
564
+ def get_sessions_show(self, query):
565
+ row = self._session((query.get("id") or [""])[0])
566
+ lines = int((query.get("lines") or ["40"])[0])
567
+ for agent in row["agents"]:
568
+ directory = Path(agent["directory"]) if agent["directory"] else None
569
+ records = runs.read_records(directory) if directory and (directory / "events.jsonl").is_file() else []
570
+ printer = TextTranscript()
571
+ text = [line for record in records for line in printer.lines(record)]
572
+ agent["lines"] = text[-lines:] if lines > 0 else []
573
+ self._json(row)
574
+
575
+ def post_sessions_stop(self, body):
576
+ row = self._session(body.get("id"))
577
+ chosen = [agent for agent in row["agents"] if body.get("agent") in (None, agent["id"])]
578
+ if not chosen:
579
+ raise ValueError(f"session {row['id']} has no agent {body.get('agent')}")
580
+ # Sub-agents first, the main agent last.
581
+ for agent in sorted(chosen, key=lambda item: -item["depth"]):
582
+ if live(agent["status"]):
583
+ self.server.conversations[agent["run"]].close()
584
+ self._json({"ok": True, "stopped": [agent["id"] for agent in chosen]})
585
+
586
+ def post_sessions_approve(self, body):
587
+ row = self._session(body.get("id"))
588
+ waiting = [agent["id"] for agent in row["agents"] if agent["status"] == "WAITING_FOR_CONFIRMATION"]
589
+ agent = body.get("agent")
590
+ if agent is None:
591
+ if len(waiting) != 1:
592
+ raise ValueError(f"session {row['id']}: " + ("nothing waits for an approval" if not waiting else
593
+ f"several agents wait ({', '.join(waiting)}): name one"))
594
+ agent = waiting[0]
595
+ elif agent not in waiting:
596
+ raise ValueError(f"agent {agent} of session {row['id']} waits for no approval")
597
+ run = next(item["run"] for item in row["agents"] if item["id"] == agent)
598
+ request_id = body.get("request_id")
599
+ accept = body.get("accept", True if request_id is None else None)
600
+ if type(accept) is not bool:
601
+ raise ValueError("accept must be a boolean")
602
+ self.server.conversations[run].confirm(accept, str(body.get("reason") or ""), body.get("remember") or None,
603
+ **({"request_id": request_id} if request_id is not None else {}))
604
+ self._json({"ok": True, "agent": agent})
605
+
606
+ def get_info(self, query):
607
+ self._json(self.server.info())
608
+
609
+ def get_libraries(self, query):
610
+ from ..paths import home
611
+ from harness.runtime.learning import learner
612
+
613
+ self._json({"libraries": learner.libraries(), "root": str(home() / "libraries")})
614
+
615
+ def get_library(self, query):
616
+ from ..paths import home
617
+ from harness.core import memory as memory_view
618
+ from harness.runtime.learning.library import Library
619
+
620
+ if query.get("run"):
621
+ self._json({"columns": list(memory_view.COLUMNS), "entries": memory_view.rows(run=self._run(query))})
622
+ return
623
+ name = (query.get("name") or [""])[0]
624
+ if not name or "/" in name or "\\" in name or name.startswith("."):
625
+ raise ValueError("a library's name under $HARNESS_HOME/libraries")
626
+ directory = home() / "libraries" / name
627
+ self._json({"name": name, "version": Library(directory).version(), "columns": list(memory_view.COLUMNS),
628
+ "entries": memory_view.rows(library=directory)})
629
+
630
+ def get_runs(self, query):
631
+ limit = int((query.get("limit") or ["500"])[0])
632
+ episodes = runs.list_episodes(self.server.root, limit)
633
+ for episode in episodes:
634
+ conversation = self.server.conversations.get(episode["run"])
635
+ episode["controllable"] = conversation is not None and live(conversation.status)
636
+ self._json({"root": str(self.server.root), "episodes": episodes})
637
+
638
+ def get_meta(self, query):
639
+ directory = self._run(query)
640
+ summary = runs.summary(directory)
641
+ self._json({"manifest": runs._read_json(directory / "manifest.json"),
642
+ "summary": summary or None, "ending": runs.ending(summary), "usage": runs.usage(directory),
643
+ "files": sorted(path.name for path in directory.iterdir()
644
+ if path.is_file() and path.suffix in runs.MEDIA_TYPES)})
645
+
646
+ def get_events(self, query):
647
+ after = int((query.get("after") or ["-1"])[0])
648
+ names = {} # filled from the records before `after` too
649
+ self._json([{**record, "view": view} for record in runs.read_records(self._run(query))
650
+ for view in [items(record, names, True)] if record.get("seq", -1) > after])
651
+
652
+ def get_lanes(self, query):
653
+ self._json(lanes_of(self._run(query)))
654
+
655
+ def get_file(self, query):
656
+ directory = self._run(query)
657
+ name = (query.get("name") or [""])[0]
658
+ path = (directory / name).resolve()
659
+ if path.parent != directory or not path.is_file() or path.suffix not in runs.MEDIA_TYPES:
660
+ return self._error(HTTPStatus.NOT_FOUND, "no such file")
661
+ self._file(path, runs.MEDIA_TYPES[path.suffix])
662
+
663
+ def get_stream(self, query):
664
+ directory = self._run(query)
665
+ after = int(self.headers.get("Last-Event-ID") or (query.get("after") or ["-1"])[0])
666
+ follow, names = runs.Follow(directory), {} # from the start: the names of the spans before `after`
667
+ self.send_response(HTTPStatus.OK)
668
+ self.send_header("Content-Type", "text/event-stream; charset=utf-8")
669
+ self.send_header("Cache-Control", "no-store")
670
+ self.send_header("Connection", "close")
671
+ self.end_headers()
672
+ self.close_connection = True
673
+ quiet = time.monotonic()
674
+ ended_at = None
675
+ while True:
676
+ self.server.touch()
677
+ records = [{**record, "view": view} for record in follow.next()
678
+ for view in [items(record, names, True)] if record.get("seq", -1) > after]
679
+ for record in records:
680
+ data = json.dumps(record, ensure_ascii=False, allow_nan=False)
681
+ self.wfile.write(f"id: {record['seq']}\nevent: record\ndata: {data}\n\n".encode())
682
+ if records:
683
+ self.wfile.flush()
684
+ quiet = time.monotonic()
685
+ if follow.ended():
686
+ # The summary is written just before the last records.
687
+ ended_at = ended_at or time.monotonic()
688
+ if time.monotonic() - ended_at > 1.0:
689
+ self.wfile.write(b"event: end\ndata: {}\n\n")
690
+ self.wfile.flush()
691
+ return
692
+ elif time.monotonic() - quiet > KEEPALIVE_SECONDS:
693
+ self.wfile.write(b": keep-alive\n\n")
694
+ self.wfile.flush()
695
+ quiet = time.monotonic()
696
+ time.sleep(POLL_SECONDS)
697
+
698
+
699
+ class FilesHandler(SimpleHTTPRequestHandler):
700
+ """The files under a directory, read-only and without a key (serve_files), with ranges."""
701
+
702
+ def send_head(self): # a folder's index.html or listing, a redirect, a 404 as the standard handler's
703
+ path = Path(self.translate_path(self.path))
704
+ return self._file(path, self.guess_type(path)) if path.is_file() else super().send_head()
705
+
706
+ def log_message(self, *args):
707
+ pass
708
+
709
+ _send, _file = Handler._send, Handler._file
710
+
711
+
712
+ class _FilesServer(OwnPort, ThreadingHTTPServer):
713
+ pass
714
+
715
+
716
+ def serve_files(root: Path, host: str = "127.0.0.1", port: int = 8000) -> None:
717
+ """Serve the files under `root` until interrupted (harness view); print where."""
718
+ with _FilesServer((host, port), partial(FilesHandler, directory=str(root))) as server, suppress(KeyboardInterrupt):
719
+ print(f"serving {Path(root).resolve()} on http://{host}:{server.server_address[1]}/", flush=True)
720
+ server.serve_forever()