@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,131 @@
1
+ """Approvals: which steps wait for the user, and the words every frontend asks with.
2
+
3
+ Every command reaches the world through a shield (a worker's, the gate of another
4
+ harness's agent run as a sub-agent, an MCP tool's call), and some wait for the user first.
5
+ The core holds the mechanism only; what a step is, the side that performs it says, from
6
+ what it really acts on (the element under the pointer, a page's fields, a tool's
7
+ annotations, a command line):
8
+
9
+ - A sensitive step (one of SENSITIVE) always waits for the user, whatever the settings; the
10
+ answer covers that one step only and is never remembered.
11
+ - The rest follows the settings: approvals.ask is sensitive (the default: only those wait)
12
+ or programs (every program waits as well). The physical-input policy of a package that
13
+ uses the user's real mouse and keyboard grades that input on top, per app and window.
14
+ - A sensitive step is refused when nobody can answer.
15
+
16
+ A request goes to the user as a `physical_request` record (its `sensitive` kind and
17
+ `target` in words, or the app and window of physical input); the conversation answers it
18
+ (confirm), in every frontend.
19
+
20
+ WORDS is one key table for every frontend: English with {placeholders}; the terminals
21
+ say() them, the pages get them in GET /api/info and translate by key."""
22
+
23
+ import hmac
24
+ import json
25
+ import re
26
+ import secrets
27
+
28
+
29
+ WORKER_APPROVAL_KEY = "HARNESS_WORKER_APPROVAL_KEY"
30
+ WORKER_APPROVAL_HEADER = "X-Harness-Worker-Approval"
31
+ APPROVAL_PIPE_FLAG = "--_approval-from-stdin"
32
+ APPROVAL_PIPE_FRAME = b"harness-worker-approval-v1 "
33
+ _HOST_PIPE_FRAME = b"harness-worker-host-pipe-v1 "
34
+ _PIPE_FRAME = APPROVAL_PIPE_FRAME
35
+
36
+
37
+ def worker_approval_proof(key: str, request: dict) -> str:
38
+ """Authenticate one host approval RPC, including its operation and all arguments."""
39
+ body = json.dumps(request, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
40
+ return hmac.digest(key.encode(), b"harness worker approval v1\0" + body, "sha256").hex()
41
+
42
+
43
+ def write_approval_key(pipe, key: str, *, host_pipe=False) -> None:
44
+ """Send the key over the managed worker's private startup pipe."""
45
+ prefix = _HOST_PIPE_FRAME if host_pipe else _PIPE_FRAME
46
+ pipe.write(prefix + key.encode("ascii") + b"\n")
47
+ pipe.flush()
48
+
49
+
50
+ def read_worker_startup(pipe) -> tuple[str, bool]:
51
+ """Read one startup frame and leave the pipe positioned at its first request."""
52
+ frame = pipe.readline(max(len(_PIPE_FRAME), len(_HOST_PIPE_FRAME)) + 65)
53
+ for prefix in (_PIPE_FRAME, _HOST_PIPE_FRAME):
54
+ if re.fullmatch(re.escape(prefix) + rb"[0-9a-f]{64}\n", frame):
55
+ return frame[len(prefix):-1].decode("ascii"), prefix == _HOST_PIPE_FRAME
56
+ raise ValueError("Invalid managed worker startup frame")
57
+
58
+
59
+ def read_approval_key(pipe) -> str:
60
+ """Read the legacy approval startup key."""
61
+ key, host_pipe = read_worker_startup(pipe)
62
+ if host_pipe:
63
+ raise ValueError("Expected an approval startup frame")
64
+ return key
65
+
66
+
67
+ # The kinds of sensitive steps.
68
+ WORKER_APPROVAL_SECONDS = 300.0
69
+ SENSITIVE = ("credentials", "payment", "sending", "deleting", "irreversible")
70
+ # What the host itself asks the user through the same request (runtime/task/environments.py):
71
+ # another environment for the conversation, sub-agents switched on. Never a worker's offer.
72
+ HOST_ASKS = ("environment", "agents")
73
+ # The setting approvals.ask (settings.py).
74
+ ASK = ("sensitive", "programs")
75
+
76
+
77
+ def request(kind: str, target: str, actions=(), **detail) -> dict:
78
+ """A sensitive step's request to the user: its kind (SENSITIVE), what it acts on in words."""
79
+ if kind not in SENSITIVE + HOST_ASKS:
80
+ raise ValueError(f"a sensitive step is one of {', '.join(SENSITIVE)}, not {kind!r}")
81
+ return {**detail, "id": f"sensitive-{secrets.token_hex(8)}", "sensitive": kind,
82
+ "target": str(target)[:300], "actions": [str(action) for action in actions]}
83
+
84
+
85
+ # doing.*: what a step does (a rule's actions); answer.* and allowed.*: one per REMEMBER value
86
+ # (runtime/safety/input.py), then the others; label.*: an app and a window as rules and requests name them.
87
+ WORDS = {
88
+ "doing.pointer": "click", "doing.drag": "drag", "doing.keyboard": "press keys", "doing.clipboard": "type",
89
+ "doing.foreground": "switch windows", "doing.other": "act",
90
+ "request": "it wants to {doing} in {app}{window} with your mouse and keyboard",
91
+ "asks": "agent {agent} of session {session} wants to use your mouse and keyboard: {what}",
92
+ "sensitive": "it wants to do something that waits for you ({kind}): {target}",
93
+ "sensitive.credentials": "credentials", "sensitive.payment": "a payment", "sensitive.sending": "sending",
94
+ "sensitive.deleting": "deleting", "sensitive.irreversible": "a step that cannot be undone",
95
+ "sensitive.environment": "another environment", "sensitive.agents": "sub-agents",
96
+ "answer.once": "allow this time", "answer.app": "{app} is fine for this chat",
97
+ "answer.session": "anything is fine for this chat", "answer.always": "always allow {app}",
98
+ "answer.no": "don't allow", "answer.later": "not now", "answer.why": "reason (optional, it will see this)",
99
+ "allowed.once": "allowed this time", "allowed.app": "{app} is allowed for this chat",
100
+ "allowed.session": "anything is allowed for this chat",
101
+ "allowed.always": "{app} is always allowed now: a rule in your settings", "refused": "not allowed{reason}",
102
+ "label.app": "app (e.g. wechat)", "label.window": "words in the window title", "label.that_app": "that app",
103
+ "label.this_window": "this window", "label.the_window": "the window {title}",
104
+ }
105
+
106
+
107
+ def say(key: str, **values) -> str:
108
+ """WORDS[key] with its placeholders filled in (one not given: nothing)."""
109
+ return re.sub(r"\{(\w+)\}", lambda match: str(values.get(match.group(1), "") or ""), WORDS[key])
110
+
111
+
112
+ # The confirmation policies: never ask (evaluation), or ask before every program.
113
+ CONFIRMATION_POLICIES = ("never", "always")
114
+
115
+
116
+ def confirmation_policy(given: str | None = None) -> str:
117
+ """The confirmation policy of a conversation a user starts, the same for every frontend
118
+ (the app, terminal chat and RPC). Use the frontend's explicit choice `given`
119
+ for this conversation, otherwise the settings' `approvals.ask`."""
120
+ if given is not None:
121
+ if given not in CONFIRMATION_POLICIES:
122
+ raise ValueError(f"confirmation must be one of {CONFIRMATION_POLICIES}")
123
+ return given
124
+ from harness.paths import data
125
+ from harness.settings import Settings
126
+
127
+ try:
128
+ asks = Settings(data()).get()["approvals"]["ask"] == "programs"
129
+ except Exception:
130
+ asks = False
131
+ return "always" if asks else "never"
@@ -0,0 +1,62 @@
1
+ """Physical input receipts and the legacy host approval flow.
2
+
3
+ Host-bound refusals pass through to Tick for attribution.
4
+ """
5
+
6
+ from harness.core import spans
7
+ from harness.runtime.execution import control
8
+
9
+
10
+ # What a user's answer keeps: this step, this app or every app for the session, or a rule.
11
+ REMEMBER = ("once", "app", "session", "always")
12
+
13
+ class PhysicalInput:
14
+ """Worker input and the explicit request_physical() operation."""
15
+
16
+ def ask_physical(self, request):
17
+ """Put a physical-input request of the worker to the user, through the host, and
18
+ give the worker their answer: {"accept", "remember", "reason"}, or None when nobody
19
+ answered (no host to ask; the program was paused)."""
20
+ if not spans.connected():
21
+ return None
22
+ identifier = request["id"]
23
+ with control._answered:
24
+ control._physical.add(identifier)
25
+ spans.note("physical_request", request=request)
26
+ try:
27
+ answer = control.wait_answer(identifier)
28
+ finally:
29
+ with control._answered:
30
+ control._physical.discard(identifier)
31
+ control._answers.pop(identifier, None)
32
+ if answer is None:
33
+ return None
34
+ self.env.call("physical", op="answer", episode_id=self.episode_id, id=request["id"],
35
+ accept=bool(answer.get("accept")), remember=answer.get("remember") or "once")
36
+ return answer
37
+
38
+ def _note_input(self, command, result):
39
+ """The host's `input` note of a delivered step: how it went (the worker's delivery)
40
+ and what it sent (input_sent)."""
41
+ detail = result["delivery"]
42
+ if "action_id" in result:
43
+ detail = {**detail, "action_id": result["action_id"]}
44
+ spans.note("input", command=command.get("type"), executed=bool(result["executed"]),
45
+ sent=input_sent(command), **detail)
46
+
47
+
48
+ def input_sent(command) -> dict:
49
+ """What a step sent, for its `input` note: the command's fields but its type (the keys
50
+ and buttons a game's state input holds down, its pointer motion), a typed text by its
51
+ length only."""
52
+ sent = {}
53
+ for name, value in command.items():
54
+ if name == "type":
55
+ continue
56
+ if name in ("text", "value") and isinstance(value, str):
57
+ sent[f"{name}_chars"] = len(value)
58
+ elif isinstance(value, (set, frozenset, tuple, list)):
59
+ sent[name] = sorted(value) if isinstance(value, (set, frozenset)) else list(value)
60
+ else:
61
+ sent[name] = value
62
+ return sent
@@ -0,0 +1,419 @@
1
+ """Isolation of the program kernel (App. A: each episode runs in an isolated
2
+ container holding the kernel and its workspace, which can reach only the model
3
+ endpoint and the policy servers).
4
+
5
+ File system: the kernel starts in new user, mount and PID namespaces (util-linux
6
+ unshare; no privileges needed). Its view of the hidden roots (by default the user's
7
+ home directory) is empty except for the Python installation and, read-only, the
8
+ harness source, so benchmark checkouts, task files, run directories and keys are
9
+ not visible. /tmp is a fresh tmpfs that disappears with the episode; the working
10
+ directory is /tmp/workspace. Host processes are not visible.
11
+
12
+ Network and processes: once the session has started, an audit hook lets sockets
13
+ connect only to the endpoints named in the kernel options (worker, models, policy
14
+ servers) and refuses to start processes or to load native code through ctypes. The
15
+ hook guards against programs reaching data and services, not against deliberate
16
+ escape from the Python interpreter.
17
+
18
+ Files: from then on the same kind of hook lets programs open and list only the Python
19
+ installation, the harness source, system directories and their own process in /proc,
20
+ and write only their workspace (and the sandbox's private /tmp). On Linux a
21
+ dedicated shared lock directory supports coordination across kernels. It holds where the
22
+ sandbox cannot run, and inside it covers what the sandbox leaves visible: directories
23
+ outside the hidden roots, such as another run's results on a data disk. Whether a path
24
+ exists is not hidden.
25
+
26
+ A worker's private files (its profile's `private_paths`, e.g. a game's instance) are
27
+ refused to programs whether or not the kernel is isolated, and each attempt is reported
28
+ to the host, which records it in the trace (`file_access`).
29
+
30
+ Without the sandbox the kernel still gets only the environment of `kernel_environment`
31
+ (no keys but its models'), and runs in a fresh workspace directory, its HOME and
32
+ TMPDIR, that is removed with it.
33
+ """
34
+
35
+ import os
36
+ from pathlib import Path
37
+ import re
38
+ import shlex
39
+ import socket
40
+ import sys
41
+ import threading
42
+ from urllib.parse import urlsplit
43
+
44
+ from harness.runtime.safety.approval import WORKER_APPROVAL_KEY
45
+
46
+ from harness.core.procs import SHARED_LOCK_DIR
47
+
48
+
49
+ # Audit events a program may not trigger once the kernel is serving.
50
+ _BLOCKED_EVENTS = ("subprocess.Popen", "os.system", "os.exec", "os.posix_spawn", "os.fork", "os.forkpty",
51
+ "os.spawn", "pty.spawn", "ctypes.dlopen", "ctypes.dlsym")
52
+ _DEFAULT_PORTS = {"http": 80, "ws": 80, "https": 443, "wss": 443}
53
+ # What programs may read besides the Python installation and the harness source.
54
+ _SYSTEM_ROOTS = ("/usr", "/lib", "/lib32", "/lib64", "/libx32", "/bin", "/sbin", "/etc", "/sys", "/dev")
55
+ _PROC_FILES = ("/proc/cpuinfo", "/proc/meminfo", "/proc/stat", "/proc/loadavg", "/proc/version")
56
+ # Audit events naming paths: (indices of the path arguments, whether they write).
57
+ _PATH_EVENTS = {"os.listdir": ((0,), False), "os.scandir": ((0,), False), "os.chdir": ((0,), False),
58
+ "os.remove": ((0,), True), "os.rmdir": ((0,), True), "os.mkdir": ((0,), True),
59
+ "os.rename": ((0, 1), True), "os.link": ((0, 1), True), "os.symlink": ((1,), True),
60
+ "os.truncate": ((0,), True), "os.chmod": ((0,), True), "os.chown": ((0,), True),
61
+ "os.utime": ((0,), True), "shutil.rmtree": ((0,), True), "sqlite3.connect": ((0,), True)}
62
+ _WRITE_FLAGS = os.O_WRONLY | os.O_RDWR | os.O_CREAT | os.O_APPEND | os.O_TRUNC
63
+ # Environment variables the kernel keeps; API keys named in the options are added.
64
+ _ENVIRONMENT = ("PATH", "LANG", "LC_ALL", "TZ", "PYTHONPATH", "PYTHONUNBUFFERED", "PYTHONNOUSERSITE",
65
+ "HARNESS_WORKER_TOKEN", "HARNESS_PACKAGE_ROOTS",
66
+ "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy")
67
+ _WINDOWS_ENVIRONMENT = ("SYSTEMROOT", "WINDIR", "PATHEXT", "NUMBER_OF_PROCESSORS", "PROCESSOR_ARCHITECTURE")
68
+
69
+
70
+ def sandbox_command(command: list[str], *, keep: list[Path], read_only: list[Path],
71
+ hide: list[Path], cwd: Path | None = None) -> list[str]:
72
+ """Wrap `command` so it runs in the namespaces described above. `hide` are the
73
+ roots whose content is replaced by an empty tmpfs; `keep` (read-write) and
74
+ `read_only` paths inside them stay visible."""
75
+ tmp = Path("/tmp").resolve()
76
+ roots = {tmp, *(Path(p).resolve() for p in hide)}
77
+ visible = {Path(p).resolve(): False for p in keep}
78
+ visible.update({Path(p).resolve(): True for p in read_only})
79
+ visible = {path: ro for path, ro in visible.items()
80
+ if path != tmp and roots.intersection((path, *path.parents))}
81
+
82
+ # The working directory still refers to the old /tmp after the new one covers it.
83
+ # A relative bind source reaches it only if mount leaves the source uncanonicalized.
84
+ lines = ["set -e", "cd /tmp", "mount -t tmpfs tmpfs /tmp", 'staging=$(mktemp -d /tmp/.harness-mounts.XXXXXX)']
85
+ slots = {}
86
+ for index, path in enumerate(visible):
87
+ slot = slots[path] = f'"$staging/{index}"'
88
+ source = f"./{path.relative_to(tmp)}" if tmp in path.parents else str(path)
89
+ lines += [f"mkdir {slot}", f"mount --no-canonicalize --rbind {shlex.quote(source)} {slot}"]
90
+
91
+ # Mount parents first. A hidden child of a restored parent needs its own cover.
92
+ for path in sorted((roots | visible.keys()) - {tmp}, key=lambda path: (len(path.parts), path)):
93
+ target = shlex.quote(str(path))
94
+ lines.append(f"mkdir -p {target}")
95
+ if path in roots and (tmp not in path.parents or any(parent in visible for parent in path.parents)):
96
+ lines.append(f"mount -t tmpfs tmpfs {target}")
97
+ if path in visible:
98
+ lines.append(f"mount --rbind {slots[path]} {target}")
99
+ if visible[path]:
100
+ lines.append(f"mount -o remount,bind,ro {target}")
101
+ for slot in slots.values():
102
+ lines += [f"umount -l {slot}", f"rmdir {slot}"]
103
+ workspace = shlex.quote(str(cwd or "/tmp/workspace"))
104
+ lines += ['rmdir "$staging"', f"mkdir -p {workspace}", f"cd {workspace}",
105
+ "exec " + " ".join(shlex.quote(part) for part in command)]
106
+ return ["unshare", "--user", "--map-root-user", "--mount", "--pid", "--fork", "--mount-proc",
107
+ "--kill-child", "--", "/bin/sh", "-c", "\n".join(lines)]
108
+
109
+
110
+ # Packages the kernel imports that may be installed outside the Python prefix
111
+ # (editable installs): the policy client of XPolicyLab.
112
+ KERNEL_PACKAGES = ("client_server",)
113
+ # Modules imported before the network guard is installed: importing them loads
114
+ # native code through ctypes, which programs may not do.
115
+ KERNEL_IMPORTS = ("client_server.ws.model_client",)
116
+
117
+
118
+ def package_dirs(names=KERNEL_PACKAGES, python: str | None = None) -> list[Path]:
119
+ """Where these packages live on the host, so the sandbox can show them read-only
120
+ at the same paths (an editable install's finder points there): for this interpreter,
121
+ or for another one (`python`, the kernel's), asked in a process of its own."""
122
+ import importlib.util
123
+
124
+ if python and Path(python).absolute() != Path(sys.executable).absolute():
125
+ import json
126
+ import subprocess
127
+
128
+ code = ("import importlib.util, json, sys\n"
129
+ "dirs = []\n"
130
+ "for name in sys.argv[1:]:\n"
131
+ " try:\n"
132
+ " spec = importlib.util.find_spec(name)\n"
133
+ " except (ImportError, ValueError):\n"
134
+ " spec = None\n"
135
+ " dirs += list(spec.submodule_search_locations or []) if spec else []\n"
136
+ "print(json.dumps(dirs))\n")
137
+ result = subprocess.run([python, "-c", code, *names], capture_output=True, encoding="utf-8", errors="replace",
138
+ timeout=60)
139
+ return [Path(item) for item in json.loads(result.stdout or "[]")] if result.returncode == 0 else []
140
+ dirs = []
141
+ for name in names:
142
+ try:
143
+ spec = importlib.util.find_spec(name)
144
+ except (ImportError, ValueError):
145
+ spec = None
146
+ if spec is not None:
147
+ dirs += [Path(location) for location in (spec.submodule_search_locations or [])]
148
+ return dirs
149
+
150
+
151
+ def hidden_roots(paths: list[Path], extra=()) -> list[Path]:
152
+ """The home directory and, for each path, its highest ancestor owned by this
153
+ user (e.g. /data/<user> for a checkout in it): the user's own directories."""
154
+ roots = {Path.home().resolve()}
155
+ uid = os.getuid()
156
+ for path in paths:
157
+ owned = None
158
+ for parent in [Path(path).resolve(), *Path(path).resolve().parents]:
159
+ try:
160
+ if parent != Path("/") and parent.stat().st_uid == uid:
161
+ owned = parent
162
+ except OSError:
163
+ pass
164
+ if owned is not None:
165
+ roots.add(owned)
166
+ roots |= {Path(p).expanduser().resolve() for p in extra}
167
+ # Drop roots inside other roots: hiding the outer one hides them.
168
+ return sorted(root for root in roots if not any(other in root.parents for other in roots))
169
+
170
+
171
+ def kernel_environment(options: dict, base: dict, python: str | None = None) -> dict:
172
+ """The kernel's environment: basic variables, HOME in the empty home, and the
173
+ API keys its model clients need (their URLs are resolved already: config/agent.py
174
+ _role). `python` is the kernel's interpreter (default this one)."""
175
+ names = set(_ENVIRONMENT)
176
+ for config in _model_configs(options):
177
+ names.add(config.get("api_key_env") or ("OPENROUTER_API_KEY"
178
+ if config.get("backend", "openrouter") == "openrouter" else ""))
179
+ if sys.platform == "win32":
180
+ # What Python and its sockets need on Windows.
181
+ names |= set(_WINDOWS_ENVIRONMENT)
182
+ env = {name: base[name] for name in names if name and name.upper() != WORKER_APPROVAL_KEY and name in base}
183
+ env["HOME"] = base.get("HOME", "/tmp")
184
+ env["TMPDIR"] = "/tmp"
185
+ # Packages installed for the user belong to the installation the kernel sees; their
186
+ # directory depends on variables (APPDATA, HOME) the kernel does not keep. They are
187
+ # this interpreter's: a kernel on another one (a bench's environment) gets none, or
188
+ # it would import packages built for another Python.
189
+ users = user_site() if python is None or same_interpreter(python) else None
190
+ if users is not None:
191
+ env["PYTHONPATH"] = os.pathsep.join([path for path in (env.get("PYTHONPATH"), str(users)) if path])
192
+ env[USER_SITE_VARIABLE] = str(users)
193
+ return env
194
+
195
+
196
+ def same_interpreter(python: str) -> bool:
197
+ """Whether `python` is this interpreter."""
198
+ try:
199
+ return Path(python).resolve() == Path(sys.executable).resolve() or Path(python).samefile(sys.executable)
200
+ except OSError:
201
+ return False
202
+
203
+
204
+ # The host's user site-packages, as the kernel is told it (read_roots).
205
+ USER_SITE_VARIABLE = "HARNESS_USER_SITE"
206
+
207
+
208
+ def user_site() -> Path | None:
209
+ """This interpreter's user site-packages when it uses one; in a kernel, the host's."""
210
+ import site
211
+
212
+ if os.environ.get(USER_SITE_VARIABLE):
213
+ return Path(os.environ[USER_SITE_VARIABLE])
214
+ if not site.ENABLE_USER_SITE:
215
+ return None
216
+ path = Path(site.getusersitepackages())
217
+ return path if path.is_dir() else None
218
+
219
+
220
+ def endpoints(options: dict) -> set[tuple[str, int]]:
221
+ """(host, port) of every service named in the kernel options."""
222
+ from harness.runtime.decision.model import chat_url
223
+
224
+ urls = []
225
+
226
+ def scan(value):
227
+ if isinstance(value, dict):
228
+ for key, item in value.items():
229
+ if key in ("endpoint", "url", "base_url") and isinstance(item, str):
230
+ urls.append(item)
231
+ else:
232
+ scan(item)
233
+ elif isinstance(value, list):
234
+ for item in value:
235
+ scan(item)
236
+
237
+ scan(options)
238
+ urls += [chat_url(config.get("backend", "openrouter"), config.get("base_url"))
239
+ for config in _model_configs(options)]
240
+ for name in ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"):
241
+ if os.environ.get(name):
242
+ urls.append(os.environ[name])
243
+ result = set()
244
+ for url in urls:
245
+ parts = urlsplit(url if "://" in url else "http://" + url)
246
+ if parts.hostname:
247
+ result.add((parts.hostname, parts.port or _DEFAULT_PORTS.get(parts.scheme, 80)))
248
+ return result
249
+
250
+
251
+ def _model_configs(options: dict) -> list[dict]:
252
+ return [options[name] for name in ("vlm", "pointer", "verifier") if isinstance(options.get(name), dict)]
253
+
254
+
255
+ def install_network_guard(allowed: set[tuple[str, int]]) -> None:
256
+ """Refuse connections to anything but `allowed`, and process creation and
257
+ ctypes, for the rest of the process's life (audit hooks cannot be removed)."""
258
+ import importlib
259
+
260
+ for name in KERNEL_IMPORTS:
261
+ try:
262
+ importlib.import_module(name)
263
+ except ImportError:
264
+ pass # not installed here; skills that need it report the error
265
+ hosts = frozenset(host for host, _port in allowed)
266
+ addresses: dict[str, set[int]] = {}
267
+
268
+ def resolve():
269
+ for host, port in allowed:
270
+ try:
271
+ infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
272
+ except OSError:
273
+ continue
274
+ for info in infos:
275
+ addresses.setdefault(info[4][0], set()).add(port)
276
+
277
+ def permitted(address) -> bool:
278
+ return (isinstance(address, tuple) and len(address) >= 2
279
+ and address[1] in addresses.get(str(address[0]), ()))
280
+
281
+ resolve()
282
+
283
+ def hook(event, args):
284
+ if event == "socket.getaddrinfo":
285
+ if str(args[0]) not in hosts and str(args[0]) not in addresses:
286
+ raise PermissionError(f"programs may not resolve {args[0]!r}")
287
+ elif event == "socket.connect":
288
+ if not permitted(args[1]):
289
+ resolve() # addresses of the allowed names may have changed
290
+ if not permitted(args[1]):
291
+ raise PermissionError(f"programs may not connect to {args[1]!r}")
292
+ elif event.startswith(_BLOCKED_EVENTS):
293
+ raise PermissionError(f"programs may not use {event}")
294
+
295
+ sys.addaudithook(hook)
296
+
297
+
298
+ def install_private_guard(paths: list, report) -> list[str]:
299
+ """Refuse opening, listing and changing anything under `paths` (the worker's private
300
+ files, e.g. a game's instance) for the rest of the process's life, with or without the
301
+ rest of the isolation, and call `report(event, path)` first for each attempt (the
302
+ trace records it). Paths are compared resolved and, on Windows, without case. Returns
303
+ the guarded roots."""
304
+ roots = tuple(dict.fromkeys(os.path.normcase(os.path.realpath(os.fspath(path))) for path in paths if path))
305
+ if not roots:
306
+ return []
307
+ reporting = threading.local()
308
+
309
+ def private(path) -> str | None:
310
+ if isinstance(path, int) or path is None:
311
+ return None
312
+ resolved = os.path.normcase(os.path.realpath(os.fsdecode(path)))
313
+ return resolved if any(resolved == root or resolved.startswith(root.rstrip(os.sep) + os.sep)
314
+ for root in roots) else None
315
+
316
+ def refuse(event, path):
317
+ if not getattr(reporting, "busy", False):
318
+ reporting.busy = True
319
+ try:
320
+ report(event, path)
321
+ except Exception:
322
+ pass # the refusal stands whether or not it could be recorded
323
+ finally:
324
+ reporting.busy = False
325
+ raise PermissionError(f"programs may not open the worker's private files ({path!r})")
326
+
327
+ def hook(event, args):
328
+ if event == "open":
329
+ hit = private(args[0])
330
+ if hit is not None:
331
+ refuse(event, hit)
332
+ elif event in _PATH_EVENTS:
333
+ for index in _PATH_EVENTS[event][0]:
334
+ hit = private(args[index]) if index < len(args) else None
335
+ if hit is not None:
336
+ refuse(event, hit)
337
+
338
+ sys.addaudithook(hook)
339
+ return list(roots)
340
+
341
+
342
+ def read_roots(source: list[Path]) -> list[Path]:
343
+ """What a program may read: the Python installation (prefixes, site-packages),
344
+ `source`, packages installed outside the prefix (KERNEL_PACKAGES) and system
345
+ directories."""
346
+ import site
347
+
348
+ roots = [sys.prefix, sys.exec_prefix, sys.base_prefix, sys.base_exec_prefix, *site.getsitepackages(),
349
+ *([user_site()] if user_site() else []), *source, *package_dirs(), *_SYSTEM_ROOTS]
350
+ return [Path(root) for root in roots]
351
+
352
+
353
+ def _real(path) -> str:
354
+ r"""The resolved path, in the plain form: on Windows realpath of a file reached through a
355
+ junction (uv's Python is one: cpython-3.12 -> cpython-3.12.15) comes back as
356
+ \\?\C:\..., while a directory's does not, so the two would never compare equal."""
357
+ path = os.path.realpath(path)
358
+ if path.startswith("\\\\?\\UNC\\"):
359
+ return "\\\\" + path[8:]
360
+ if path.startswith("\\\\?\\"):
361
+ return path[4:]
362
+ return path
363
+
364
+
365
+ def install_file_guard(read: list[Path], write: list[Path]) -> None:
366
+ """Refuse opening and listing anything but `read` and `write` (and this process in
367
+ /proc), and changing anything but `write`, for the rest of the process's life. Paths
368
+ are resolved first, so a link in the workspace does not lead out of it. The
369
+ directories on sys.path may be listed (imports scan them), not read."""
370
+ def real(paths):
371
+ resolved = (_real(p) for p in paths)
372
+ return tuple(dict.fromkeys(p for p in resolved if p != "/"))
373
+
374
+ writable = real(write)
375
+ readable = real(read) + writable + (f"/proc/{os.getpid()}",)
376
+ listable = frozenset(real(entry or "." for entry in sys.path))
377
+ proc_files = frozenset(_PROC_FILES)
378
+ # Resolve the system mount, keeping the lock directory itself fixed so a
379
+ # symlink cannot change the scope of the exception.
380
+ lock_directory = (os.path.join(_real("/dev/shm"), "harness-locks")
381
+ if sys.platform.startswith("linux") and Path(SHARED_LOCK_DIR).parent == Path("/dev/shm")
382
+ else None)
383
+
384
+ def inside(path, roots):
385
+ return any(path == root or path.startswith(root + os.sep) for root in roots)
386
+
387
+ def check(path, writes, lists=False):
388
+ if isinstance(path, int) or path is None:
389
+ return # an open descriptor, or the working directory
390
+ path = _real(os.fsdecode(path))
391
+ if writes:
392
+ if not inside(path, writable):
393
+ raise PermissionError(f"programs may not change {path!r}")
394
+ elif not (inside(path, readable) or path in proc_files or (lists and path in listable)):
395
+ raise PermissionError(f"programs may not read {path!r}")
396
+
397
+ def hook(event, args):
398
+ if event == "open":
399
+ path, mode, flags = args
400
+ if (lock_directory and isinstance(path, (str, bytes)) and isinstance(flags, int)
401
+ and flags & os.O_NOFOLLOW and not flags & (os.O_TRUNC | os.O_APPEND)
402
+ and (not flags & os.O_CREAT or flags & os.O_EXCL)):
403
+ parent, name = os.path.split(_real(os.fsdecode(path)))
404
+ if parent == lock_directory and re.fullmatch(r"[a-z0-9._-]+[.]lock", name):
405
+ return
406
+ writes = ((isinstance(mode, str) and any(c in mode for c in "wax+"))
407
+ or (isinstance(flags, int) and bool(flags & _WRITE_FLAGS)))
408
+ check(path, writes)
409
+ elif (lock_directory and event in ("os.mkdir", "os.chmod") and len(args) == 3
410
+ and isinstance(args[0], (str, bytes)) and _real(os.fsdecode(args[0])) == lock_directory
411
+ and args[2] == -1 and (event == "os.mkdir" or args[1] == 0o1777)):
412
+ return
413
+ elif event in _PATH_EVENTS:
414
+ indices, writes = _PATH_EVENTS[event]
415
+ for index in indices:
416
+ if index < len(args):
417
+ check(args[index], writes, lists=event in ("os.listdir", "os.scandir"))
418
+
419
+ sys.addaudithook(hook)