@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,298 @@
1
+ """Client of tool servers that speak the Model Context Protocol (MCP).
2
+
3
+ McpSession is the session every transport shares (initialize, request ids, tools/list,
4
+ tools/call, error answers); a transport only sends a message. McpClient is streamable
5
+ HTTP: messages are JSON-RPC 2.0 POSTed to the server's endpoint, and the answer comes as
6
+ JSON or as a text/event-stream whose data lines carry it. The mcp skill (skills/mcp)
7
+ lists explicitly configured tools and relays calls to the task host. The host owns
8
+ both HTTP and stdio transports; controller programs never launch servers or receive
9
+ connection credentials. No optional app or agent is required.
10
+ """
11
+
12
+ from contextlib import contextmanager
13
+ import json
14
+ from pathlib import Path
15
+ import threading
16
+
17
+ from ..core.http import open_url, read_sse
18
+ from ..core.spans import span
19
+
20
+
21
+ PROTOCOL_VERSION = "2025-06-18"
22
+
23
+
24
+ class McpError(RuntimeError):
25
+ """An MCP server answered with an error, or a tool reported that it failed."""
26
+
27
+
28
+ class SessionGone(Exception):
29
+ """The server no longer knows the session: HTTP 404 to a request with a session id, or
30
+ a stdio server that exited and was started again."""
31
+
32
+
33
+ class McpSession:
34
+ """The client side of one MCP session, whatever carries its messages: it starts on
35
+ first use (initialize, then the initialized notification), numbers the requests and
36
+ turns an error answer into McpError. A transport provides only send()."""
37
+
38
+ def __init__(self):
39
+ self._ready = False
40
+ self._next_id = 0
41
+ self._lock = threading.Lock()
42
+ self._requests = threading.RLock()
43
+
44
+ def send(self, message):
45
+ """Send one JSON-RPC message; the server's answer to it (a dict), None for a
46
+ notification."""
47
+ raise NotImplementedError
48
+
49
+ def request(self, method, params=None):
50
+ """Send one JSON-RPC request and return its result. When the server no longer knows
51
+ the session (it restarted, say after the broker stopped it idle), a new one starts
52
+ with initialize, as the protocol requires, and the request is sent again."""
53
+ with self._requests:
54
+ try:
55
+ return self._request(method, params)
56
+ except SessionGone:
57
+ self._ready = False
58
+ if method == "tools/call":
59
+ raise McpError("The tool call's outcome is unknown; it was not sent again") from None
60
+ return self._request(method, params)
61
+
62
+ def _request(self, method, params):
63
+ if not self._ready and method != "initialize":
64
+ self._request("initialize", {"protocolVersion": PROTOCOL_VERSION, "capabilities": {},
65
+ "clientInfo": {"name": "the-harness", "version": "1"}})
66
+ self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
67
+ self._ready = True
68
+ with self._lock:
69
+ self._next_id += 1
70
+ message = {"jsonrpc": "2.0", "id": self._next_id, "method": method}
71
+ if params is not None:
72
+ message["params"] = params
73
+ reply = self.send(message)
74
+ if "error" in reply:
75
+ raise McpError(f"{reply['error'].get('code')}: {reply['error'].get('message')}")
76
+ return reply.get("result", {})
77
+
78
+ def tools(self):
79
+ """The server's tools: [{"name", "description", "inputSchema", ...}], every page."""
80
+ tools, cursor = [], None
81
+ while True:
82
+ result = self.request("tools/list", {"cursor": cursor} if cursor else {})
83
+ tools += list(result.get("tools", []))
84
+ cursor = result.get("nextCursor")
85
+ if not cursor:
86
+ return tools
87
+
88
+ def call_result(self, name, arguments=None):
89
+ """The complete MCP CallToolResult, including error content and all modalities."""
90
+ with span("service", "mcp", tool=name):
91
+ return self.request("tools/call", {"name": name, "arguments": dict(arguments or {})})
92
+
93
+ def call(self, name, arguments=None):
94
+ """Convenience projection for existing service clients; tasks use call_result()."""
95
+ result = self.call_result(name, arguments)
96
+ if result.get("isError"):
97
+ raise McpError(f"tool {name}: {_text(result) or 'failed'}")
98
+ if result.get("structuredContent") is not None:
99
+ return result["structuredContent"]
100
+ return _text(result)
101
+
102
+ def stop(self):
103
+ """End what the session started (nothing, over HTTP)."""
104
+
105
+
106
+ class McpClient(McpSession):
107
+ """One MCP server over streamable HTTP; the server's Mcp-Session-Id goes back on every
108
+ request after initialize."""
109
+
110
+ def __init__(self, url, timeout=60.0, on_demand=None, headers=None):
111
+ super().__init__()
112
+ self.url = url
113
+ # Sent with every request (a token the server wants).
114
+ self.headers = dict(headers or {})
115
+ self.timeout = float(timeout)
116
+ # A server placed on demand is started by the deploy's broker before a call.
117
+ self.on_demand = on_demand
118
+ self.session_id = None
119
+
120
+ def send(self, message):
121
+ from urllib.error import HTTPError
122
+
123
+ from .broker import ensure
124
+
125
+ ensure({"on_demand": self.on_demand})
126
+ headers = {**self.headers, "Accept": "application/json, text/event-stream",
127
+ "MCP-Protocol-Version": PROTOCOL_VERSION}
128
+ if self.session_id:
129
+ headers["Mcp-Session-Id"] = self.session_id
130
+ try:
131
+ with open_url(self.url, message, headers, self.timeout) as response:
132
+ self.session_id = response.headers.get("Mcp-Session-Id") or self.session_id
133
+ if "id" not in message:
134
+ return None # a notification: accepted, no answer
135
+ return _response(response, message["id"])
136
+ except HTTPError as error:
137
+ with error:
138
+ detail = error.read().decode("utf-8", errors="replace").strip()[:300]
139
+ if error.code == 404 and self.session_id:
140
+ self.session_id = None
141
+ raise SessionGone() from None
142
+ raise McpError(f"HTTP {error.code} from {self.url}: {detail or error.reason}") from None
143
+
144
+
145
+
146
+ class Resources:
147
+ """Host-local resource ownership shared across task MCP clients."""
148
+ def __init__(self):
149
+ self._condition = threading.Condition()
150
+ self._busy = set()
151
+
152
+ @contextmanager
153
+ def acquire(self, resource, current):
154
+ with self._condition:
155
+ while resource in self._busy:
156
+ if not current():
157
+ raise McpError("The calling program stopped before dispatch")
158
+ self._condition.wait(0.05)
159
+ if not current():
160
+ raise McpError("The calling program stopped before dispatch")
161
+ self._busy.add(resource)
162
+ try:
163
+ yield
164
+ finally:
165
+ with self._condition:
166
+ self._busy.remove(resource)
167
+ self._condition.notify_all()
168
+
169
+
170
+ class ToolAccess:
171
+ """Run-scoped transports and explicit user grants; server hints grant no authority."""
172
+ def __init__(self, servers, *, prepare=None, resources=None, directory=None, authorize=None):
173
+ self._servers = dict(servers)
174
+ self._prepare = prepare
175
+ self._authorize = authorize
176
+ self._clients = {}
177
+ self._tools = {}
178
+ self._lock = threading.RLock()
179
+ self._closed = False
180
+ self.resources = resources or Resources()
181
+ self.directory = Path(directory or ".")
182
+
183
+ def _index(self):
184
+ names = {}
185
+ if self._closed:
186
+ raise McpError("The task's MCP clients are closed")
187
+ for server, config in self._servers.items():
188
+ if not self._current(server):
189
+ continue
190
+ if server not in self._clients:
191
+ if config.get("command"):
192
+ from .mcp_stdio import StdioServer
193
+ self._clients[server] = StdioServer(
194
+ [config["command"], *config.get("args", [])], config.get("env", {}),
195
+ self.directory / f"mcp-{server}.log", cwd=config.get("cwd"),
196
+ timeout=float(config.get("timeout_seconds", 60)))
197
+ else:
198
+ self._clients[server] = McpClient(config["url"],
199
+ timeout=float(config.get("timeout_seconds", 60)), on_demand=config.get("on_demand"),
200
+ headers=config.get("headers"))
201
+ if server not in self._tools:
202
+ try:
203
+ self._tools[server] = self._clients[server].tools()
204
+ except Exception as error:
205
+ raise McpError(f"{server}: tool discovery failed: {error}") from error
206
+ for spec in self._tools[server]:
207
+ names.setdefault(spec["name"], []).append((server, spec))
208
+ return {name if len(items) == 1 else f"{server}.{name}": (server, spec)
209
+ for name, items in names.items() for server, spec in items}
210
+
211
+ def tools(self):
212
+ with self._lock:
213
+ return [{"name": name, "server": server, "description": spec.get("description", ""),
214
+ "input_schema": spec.get("inputSchema", {})}
215
+ for name, (server, spec) in sorted(self._index().items())
216
+ if (self._allowed(server, spec["name"]) or self._write_allowed(server, spec["name"]))
217
+ and self._current(server, spec["name"])]
218
+
219
+ def _check_current(self, server, name=None):
220
+ if self._authorize is not None:
221
+ self._authorize(self._servers[server], name)
222
+
223
+ def _current(self, server, name=None):
224
+ try:
225
+ self._check_current(server, name)
226
+ return True
227
+ except McpError:
228
+ return False
229
+
230
+ def _allowed(self, server, name):
231
+ config = self._servers[server]
232
+ if name in config.get("tools_off", ()):
233
+ return False
234
+ grants = config.get("allowed_tools", ())
235
+ return name in config.get("read_only_tools", ()) or name in grants or "*" in grants
236
+
237
+ def _write_allowed(self, server, name):
238
+ config = self._servers[server]
239
+ return name not in config.get("tools_off", ()) and self._prepare is not None and config.get("host_write_tool") == name
240
+
241
+ def call(self, tool, arguments, *, approve=None, current=lambda: True, dispatched=None):
242
+ if not isinstance(tool, str) or not isinstance(arguments, dict):
243
+ raise McpError("An MCP call requires a tool name and an object")
244
+ with self._lock:
245
+ found = self._index().get(tool)
246
+ if found is None:
247
+ raise McpError("The tool has no verified local policy for this call")
248
+ server, spec = found
249
+ config, name = self._servers[server], spec["name"]
250
+ client = self._clients[server]
251
+ with self.resources.acquire(config.get("resource") or server, lambda: not self._closed and current()):
252
+ self._check_current(server, name)
253
+ if self._write_allowed(server, name) and approve is not None:
254
+ with self._prepare(server, config, name, arguments) as (target, commit):
255
+ if not approve(name, target) or not current():
256
+ raise McpError("The user did not authorize this call")
257
+ self._check_current(server, name)
258
+ if dispatched:
259
+ dispatched(server)
260
+ value = commit()
261
+ return {"content": [{"type": "text", "text": json.dumps(value)}], "structuredContent": value}
262
+ if not self._allowed(server, name):
263
+ raise McpError("The tool has no verified local policy for this call")
264
+ if not current():
265
+ raise McpError("The calling program stopped before dispatch")
266
+ if dispatched:
267
+ dispatched(server)
268
+ return client.call_result(name, arguments)
269
+
270
+ def close(self):
271
+ with self._lock:
272
+ self._closed = True
273
+ clients = list(self._clients.values())
274
+ for client in clients:
275
+ client.stop()
276
+
277
+
278
+ def _text(result):
279
+ return "\n".join(str(item.get("text", "")) for item in result.get("content", [])
280
+ if isinstance(item, dict) and item.get("type") == "text")
281
+
282
+
283
+ def _response(response, request_id):
284
+ """The answer to request `request_id`: the JSON body, or the message of the event
285
+ stream that answers it."""
286
+ if "text/event-stream" in response.headers.get("Content-Type", ""):
287
+ messages = (data for event, data in read_sse(response) if event)
288
+ else:
289
+ messages = [response.read().decode("utf-8", errors="replace")]
290
+ for text in messages:
291
+ try:
292
+ reply = json.loads(text)
293
+ except ValueError:
294
+ continue
295
+ for item in reply if isinstance(reply, list) else [reply]:
296
+ if isinstance(item, dict) and item.get("id") == request_id:
297
+ return item
298
+ raise McpError("the server's reply has no answer to the request")
@@ -0,0 +1,131 @@
1
+ """Host-owned stdio MCP transport. No optional UI or agent dependency."""
2
+ import json
3
+ import os
4
+ from pathlib import Path
5
+ import shutil
6
+ import subprocess
7
+ import sys
8
+ import threading
9
+
10
+ from harness.core.procs import service_environment
11
+ from .mcp import McpSession, McpError, SessionGone
12
+
13
+ class StdioServer(McpSession):
14
+ """An MCP server on its standard input and output: newline-delimited JSON-RPC. It
15
+ starts on the first request (and again when it exited); its requests to the client
16
+ (sampling, roots) are answered with an error, its notifications ignored."""
17
+
18
+ def __init__(self, command: list[str], env: dict, log: Path, cwd: Path | None = None, timeout=180.0):
19
+ super().__init__()
20
+ self.command, self.env, self.log, self.cwd = command, env, log, cwd
21
+ self.timeout = float(timeout)
22
+ self.process = None
23
+ self._pending = {}
24
+ self._stopped = False
25
+ self._lifecycle = threading.RLock()
26
+ self._write = threading.Lock()
27
+
28
+ def _start(self):
29
+ executable = shutil.which(self.command[0]) or self.command[0]
30
+ if not Path(executable).is_file():
31
+ raise McpError(f"{self.command[0]} is not installed on this computer")
32
+ self.log.parent.mkdir(parents=True, exist_ok=True)
33
+ flags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if sys.platform == "win32" else 0
34
+ if getattr(self, "_stderr", None) is not None:
35
+ self._stderr.close()
36
+ self._stderr = open(self.log, "ab")
37
+ base = service_environment(log=lambda line: self._stderr.write(f"harness: {line}\n".encode()))
38
+ self._stderr.flush()
39
+ # Its own process group: npx and uvx start the server as a child of theirs, and
40
+ # stop() ends them together.
41
+ self.process = subprocess.Popen([executable, *self.command[1:]], stdin=subprocess.PIPE, stdout=subprocess.PIPE,
42
+ stderr=self._stderr, env={**base, **self.env}, cwd=self.cwd,
43
+ creationflags=flags, start_new_session=sys.platform != "win32")
44
+ threading.Thread(target=self._read, args=(self.process,), daemon=True, name=f"mcp-{self.command[0]}").start()
45
+
46
+ def _read(self, process):
47
+ for line in process.stdout:
48
+ try:
49
+ message = json.loads(line)
50
+ except ValueError:
51
+ continue
52
+ if not isinstance(message, dict):
53
+ continue
54
+ if "method" in message and "id" in message:
55
+ self._write_line({"jsonrpc": "2.0", "id": message["id"],
56
+ "error": {"code": -32601, "message": "not supported by the-harness"}}, process)
57
+ elif "id" in message and message["id"] in self._pending:
58
+ slot = self._pending.get(message["id"])
59
+ if slot is None or slot["process"] is not process:
60
+ continue
61
+ slot["reply"] = message
62
+ slot["done"].set()
63
+ for slot in list(self._pending.values()):
64
+ if slot["process"] is process:
65
+ slot["done"].set()
66
+
67
+ def _write_line(self, message, process=None):
68
+ data = (json.dumps(message) + "\n").encode()
69
+ with self._write:
70
+ (process or self.process).stdin.write(data)
71
+ (process or self.process).stdin.flush()
72
+
73
+ def _tail(self) -> str:
74
+ try:
75
+ return self.log.read_text(encoding="utf-8", errors="replace").strip()[-400:]
76
+ except OSError:
77
+ return ""
78
+
79
+ def send(self, message):
80
+ with self._lifecycle:
81
+ return self._send(message)
82
+
83
+ def _send(self, message):
84
+ if self._stopped:
85
+ raise McpError("The MCP transport is closed")
86
+ if self.process is None or self.process.poll() is not None:
87
+ self._start()
88
+ if message.get("method") != "initialize":
89
+ raise SessionGone() # a new process: the session starts again
90
+ if "id" not in message:
91
+ self._write_line(message)
92
+ return None
93
+ slot = self._pending[message["id"]] = {"done": threading.Event(), "reply": None, "process": self.process}
94
+ try:
95
+ self._write_line(message)
96
+ if not slot["done"].wait(self.timeout):
97
+ raise McpError(f"{message['method']}: no answer within {self.timeout:.0f} s")
98
+ except OSError as error:
99
+ raise McpError(f"the server stopped: {error}; {self._tail()}") from None
100
+ finally:
101
+ self._pending.pop(message["id"], None)
102
+ if slot["reply"] is None:
103
+ raise McpError(f"the server exited ({slot['process'].poll()}): {self._tail()}")
104
+ return slot["reply"]
105
+
106
+ def stop(self):
107
+ """End the server and the processes it started (npx's node, uvx's Python)."""
108
+ self._stopped = True
109
+ if self.process is not None and self.process.poll() is None:
110
+ if sys.platform == "win32":
111
+ subprocess.run(["taskkill", "/T", "/F", "/PID", str(self.process.pid)], capture_output=True,
112
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
113
+ else:
114
+ import signal
115
+
116
+ try:
117
+ os.killpg(self.process.pid, signal.SIGTERM)
118
+ except OSError:
119
+ self.process.terminate()
120
+ try:
121
+ self.process.wait(timeout=5)
122
+ except subprocess.TimeoutExpired:
123
+ self.process.kill()
124
+ self.process.wait()
125
+ if self.process is not None:
126
+ self.process.stdin.close()
127
+ self.process.stdout.close()
128
+ if getattr(self, "_stderr", None) is not None:
129
+ self._stderr.close()
130
+ self._stderr = None
131
+
@@ -0,0 +1,82 @@
1
+ """Where the services an agent names run: what the package that places services gives
2
+ (the local-models package's deploy: a deploy file, or the harness's own placement on this
3
+ machine's GPUs). Without one, no service is placed here: an agent's roles use hosted
4
+ models, and a role or service that needs a placed service is left out (or, strict, an
5
+ error). config/agent.py resolves agents against it. Standard library only."""
6
+
7
+ from dataclasses import dataclass
8
+
9
+
10
+ @dataclass
11
+ class Unplaced:
12
+ """How a service runs where nothing places it: off."""
13
+
14
+ name: str
15
+ mode: str = "off"
16
+ gpu: int | None = None
17
+ python: str | None = None
18
+
19
+
20
+ @dataclass
21
+ class NoDeploy:
22
+ """No package places services here: every service is off."""
23
+
24
+ name: str = "none"
25
+ path: object = None
26
+ environments: str = "own"
27
+ gpus: object = None
28
+
29
+ @property
30
+ def automatic(self) -> bool:
31
+ return True
32
+
33
+ @property
34
+ def services(self) -> dict:
35
+ from .registry import load_services
36
+
37
+ return load_services()
38
+
39
+ @property
40
+ def placements(self) -> dict:
41
+ return {}
42
+
43
+ def placement(self, name: str) -> Unplaced:
44
+ if name not in self.services:
45
+ raise ValueError(f"Unknown service {name!r}; known: {sorted(self.services)}")
46
+ return Unplaced(name)
47
+
48
+ def variables(self) -> dict:
49
+ return {}
50
+
51
+
52
+ def _deploys():
53
+ from ..extensions import first
54
+
55
+ return first("deploys")
56
+
57
+
58
+ def load_deploy(name=None, **options):
59
+ """The deploy `name` (a name of configs/deploy/, a path, None for $HARNESS_DEPLOY) as
60
+ the package that places services loads it; NoDeploy without one."""
61
+ deploys = _deploys()
62
+ if deploys is None:
63
+ if name:
64
+ raise ValueError(f"deploy {name}: placing services needs the local-models package "
65
+ "(harness install local-models)")
66
+ return NoDeploy()
67
+ return deploys.load_deploy(name, **options)
68
+
69
+
70
+ def automatic(names, **options):
71
+ """The harness's own placement of `names` on this machine (NoDeploy without a package
72
+ that places services)."""
73
+ deploys = _deploys()
74
+ return NoDeploy() if deploys is None else deploys.automatic(names, **options)
75
+
76
+
77
+ def client_config(deploy, name: str) -> dict | None:
78
+ """What a client of service `name` gets on `deploy` (its url and what the model is told),
79
+ None when it does not run there."""
80
+ if isinstance(deploy, NoDeploy):
81
+ return None
82
+ return _deploys().client_config(deploy, name)
@@ -0,0 +1,156 @@
1
+ """Service manifests: the model processes skills and agents call.
2
+
3
+ A service is one deployable model server, described by services/<name>.toml:
4
+
5
+ kind = "segmenter" segmenter | vision | pointer | vlm | llm | policy | world_model | kinematics
6
+ summary = "..."
7
+ protocol = "http" http | openai_chat | xpolicylab
8
+ command = ["{python}", "services/servers/serve_sam3.py", "--checkpoint", "{weights}/sam3/sam3.pt",
9
+ "--port", "{port}"]
10
+ port = 8810 default port
11
+ vram_gb = 7.2 GPU memory it holds once loaded (measured)
12
+ load_seconds = 60 start until it answers
13
+ client = { url = "{url}" } the kernel's or agent's config for it ({url}, {host}, {port})
14
+ [environment] the environment it runs in, installed on first use
15
+ python = "3.11" (harness/packages/environments.py); {python} is its interpreter
16
+ requirements = ["torch==2.7.0", ...]
17
+ [[weights]] where its weights come from, downloaded with it
18
+ dir = "sam3"
19
+ modelscope_model = "facebook/sam3"
20
+
21
+ An XPolicyLab policy needs no command: its [xpolicylab] table names the policy folder,
22
+ action type and overrides, and the server is XPolicyLab's own setup_policy_server.py.
23
+ Where a service runs (GPU, port, resident or on demand, or not at all) is the deploy
24
+ file's business (deploy.py), not the manifest's.
25
+ """
26
+
27
+ from dataclasses import dataclass, field
28
+ from pathlib import Path
29
+ import tomllib
30
+
31
+ from ..paths import ROOT
32
+
33
+
34
+ SERVICES_ROOT = ROOT / "services"
35
+ KINDS = ("segmenter", "vision", "pointer", "vlm", "llm", "policy", "world_model", "kinematics", "mcp")
36
+ # mcp: the Model Context Protocol over streamable HTTP (services/mcp.py).
37
+ PROTOCOLS = ("http", "openai_chat", "xpolicylab", "mcp")
38
+ WEIGHT_SOURCES = ("modelscope_model", "modelscope_dataset", "hf_model", "hf_dataset", "local")
39
+ # The keys of services/<name>.toml.
40
+ MANIFEST_KEYS = {
41
+ "kind": f"what the service is for: one of {', '.join(KINDS)}",
42
+ "summary": "one line: the model and where it comes from",
43
+ "protocol": f"how clients talk to it: one of {', '.join(PROTOCOLS)} (default http)",
44
+ "port": "its default port (a deploy may give another)",
45
+ "vram_gb": "GPU memory it takes, measured; placement and swapping use it",
46
+ "load_seconds": "how long it takes to answer after a start (waits allow three times this)",
47
+ "command": "argv that starts it, with {python} {port} {weights} {repo} {robodojo} {xpolicylab} ... "
48
+ "(protocol xpolicylab: optional, in place of XPolicyLab's setup_policy_server.py)",
49
+ "xpolicylab": "for protocol xpolicylab: policy folder, ckpt_name, action_type (joint, or ee: link6 poses "
50
+ "that run_policy solves by IK), action_dim, cwd, pythonpath, overrides",
51
+ "env": "environment variables of the process",
52
+ "python": "interpreter (default {python}: its environment's)",
53
+ "environment": "the environment it runs in, installed the first time a run needs it: [environment] with "
54
+ "python, requirements, sources, ... (the keys below), or the name of a service or benchmark "
55
+ "whose environment it shares",
56
+ "cwd": "working directory (default {package}: the folder of the package, or of the core, that holds the "
57
+ "manifest)",
58
+ "client": "the config its users get: url = \"{url}\" and what the model is told about it (description)",
59
+ "weights": "[[weights]] entries: dir below the deploy's weights root and one source "
60
+ f"({', '.join(WEIGHT_SOURCES)}), with include/exclude globs, a dataset's root, and parallel "
61
+ "(files at once, for many small ones); downloaded with the service",
62
+ "needs_files": "paths that must exist before it can start (checked by harness doctor and up)",
63
+ "notes": "anything an operator should know",
64
+ }
65
+
66
+
67
+ @dataclass(frozen=True)
68
+ class ServiceSpec:
69
+ """A service manifest (MANIFEST_KEYS) as loaded: `name` is the file's stem and `path`
70
+ the file. Placeholders such as {python} or {port} are left for the deploy to fill."""
71
+
72
+ name: str
73
+ kind: str
74
+ summary: str
75
+ protocol: str
76
+ port: int
77
+ vram_gb: float
78
+ load_seconds: float = 120.0
79
+ command: tuple = ()
80
+ xpolicylab: dict = field(default_factory=dict)
81
+ env: dict = field(default_factory=dict)
82
+ python: str = "{python}"
83
+ cwd: str = "{package}"
84
+ client: dict = field(default_factory=dict)
85
+ weights: tuple = ()
86
+ # Its [environment] table, the name of another one, or None (it has none to install).
87
+ environment: dict | str | None = None
88
+ # Paths that must exist before the service can start, with placeholders ({weights}/...).
89
+ needs_files: tuple = ()
90
+ notes: str = ""
91
+ path: Path = field(default=None, compare=False)
92
+
93
+
94
+ def _spec(path: Path) -> ServiceSpec:
95
+ with path.open("rb") as handle:
96
+ data = tomllib.load(handle)
97
+ unknown = set(data) - set(MANIFEST_KEYS)
98
+ if unknown:
99
+ raise ValueError(f"{path}: unknown keys {sorted(unknown)}")
100
+ if data.get("kind") not in KINDS:
101
+ raise ValueError(f"{path}: kind must be one of {KINDS}")
102
+ protocol = data.get("protocol", "http")
103
+ if protocol not in PROTOCOLS:
104
+ raise ValueError(f"{path}: protocol must be one of {PROTOCOLS}")
105
+ if protocol == "xpolicylab":
106
+ if not data.get("xpolicylab", {}).get("policy"):
107
+ raise ValueError(f"{path}: an xpolicylab service names its policy folder in [xpolicylab] policy")
108
+ elif not data.get("command"):
109
+ raise ValueError(f"{path}: needs a command")
110
+ if "environment" in data:
111
+ from ..packages.environments import validate
112
+
113
+ validate(data["environment"], str(path))
114
+ for entry in data.get("weights", []):
115
+ sources = [key for key in WEIGHT_SOURCES if key in entry]
116
+ if "dir" not in entry or len(sources) != 1:
117
+ raise ValueError(f"{path}: each [[weights]] has a dir and exactly one of {WEIGHT_SOURCES}")
118
+ return ServiceSpec(
119
+ name=path.stem, kind=data["kind"], summary=data.get("summary", ""), protocol=protocol,
120
+ port=int(data["port"]), vram_gb=float(data.get("vram_gb", 0.0)),
121
+ load_seconds=float(data.get("load_seconds", 120.0)), command=tuple(data.get("command", ())),
122
+ xpolicylab=dict(data.get("xpolicylab", {})), env=dict(data.get("env", {})),
123
+ python=data.get("python", "{python}"), cwd=data.get("cwd", "{package}"), client=dict(data.get("client", {})),
124
+ weights=tuple(dict(entry) for entry in data.get("weights", [])), environment=data.get("environment"),
125
+ needs_files=tuple(data.get("needs_files", ())), notes=data.get("notes", ""), path=path)
126
+
127
+
128
+ _CACHE: dict[tuple, dict[str, ServiceSpec]] = {}
129
+
130
+
131
+ def load_services(root: Path = SERVICES_ROOT) -> dict[str, ServiceSpec]:
132
+ """Every service manifest under `root` (its *.toml files) by name, validated; read
133
+ once per root. The core's root also brings the services of its packages
134
+ (services/*.toml of each, paths.roots), the first one of a name winning."""
135
+ from ..paths import find
136
+
137
+ root = Path(root).resolve()
138
+ folders = [root] + ([folder.resolve() for folder in find("services") if folder.resolve() != root]
139
+ if root == SERVICES_ROOT.resolve() else [])
140
+ key = (root, *folders)
141
+ if key not in _CACHE:
142
+ found = {}
143
+ for folder in folders:
144
+ for path in sorted(folder.glob("*.toml")):
145
+ spec = _spec(path)
146
+ found.setdefault(spec.name, spec)
147
+ _CACHE[key] = found
148
+ return _CACHE[key]
149
+
150
+
151
+ def service(name: str, root: Path = SERVICES_ROOT) -> ServiceSpec:
152
+ """The manifest of service `name`; an unknown name is an error."""
153
+ services = load_services(root)
154
+ if name not in services:
155
+ raise ValueError(f"Unknown service {name!r}; known: {sorted(services)}")
156
+ return services[name]