@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,397 @@
1
+ """The session host: one local process per user that runs the conversations of every
2
+ frontend, so a session outlives the window or terminal that started it.
3
+
4
+ The terminal chat (`harness`, its /sessions and /host), `harness run`, the app and the
5
+ Python API are its clients: they find it through DATA/host/host.json (its port, process and
6
+ session key; readable by the user only), start it when it does not run (`python -m
7
+ harness.host.server`, in a process of its own that no terminal owns) and drive its
8
+ sessions with its HTTP API (host/http.py) through RemoteConversation (host/client.py). The
9
+ host is the assistant's server (host/tasks.py) with the sessions as a tree
10
+ (host/sessions.py) and these routes:
11
+
12
+ GET /api/host its process, version, how long it has been idle
13
+ POST /api/host/stop {force}: exit (force: end the open sessions first)
14
+ GET /api/sessions?all=1&limit=N the open sessions; all: also those that ended
15
+
16
+ It listens on 127.0.0.1 only, with a new session key each time it starts, and exits
17
+ once no session is open and no client has asked for anything for HARNESS_HOST_IDLE
18
+ seconds (30 minutes). Every session it starts is appended to DATA/host/sessions.jsonl,
19
+ so the sessions that ended are listed after it exits.
20
+
21
+ from harness.host import Host
22
+ host = Host.connect()
23
+ for session in host.sessions():
24
+ print(session.id, session.status, [agent["id"] for agent in session.agents()])
25
+ host.sessions()[0].overlay() # its timeline on top of the screen
26
+ """
27
+
28
+ from contextlib import contextmanager
29
+ import json
30
+ import os
31
+ from pathlib import Path
32
+ import sys
33
+ import time
34
+ from urllib.error import URLError
35
+ from urllib.parse import quote
36
+
37
+ from ..core.procs import file_lock, start_detached
38
+ from ..core.wait import wait_until
39
+ from ..paths import PACKAGE, data, python_path
40
+ from .client import RemoteConversation, RemoteError, _call, _fetch, _get
41
+
42
+ IDLE_ENV = "HARNESS_HOST_IDLE"
43
+ PORT_ENV = "HARNESS_HOST_PORT"
44
+ # Seconds without an open session or a client's request before the host exits.
45
+ IDLE_SECONDS = 30 * 60
46
+ # The port it takes when it is free (the app's), else any free one.
47
+ PORT = 8780
48
+ # Seconds a client waits for a host it started.
49
+ START_SECONDS = 60.0
50
+
51
+
52
+ def folder(base: Path | None = None) -> Path:
53
+ """DATA/host: the host's address file, its index of sessions and the start lock."""
54
+ return Path(base or data()) / "host"
55
+
56
+
57
+ def address_file(base: Path | None = None) -> Path:
58
+ return folder(base) / "host.json"
59
+
60
+
61
+ def index_file(base: Path | None = None) -> Path:
62
+ return folder(base) / "sessions.jsonl"
63
+
64
+
65
+ def idle_seconds() -> float:
66
+ return float(os.environ.get(IDLE_ENV) or IDLE_SECONDS)
67
+
68
+
69
+ def identity() -> dict:
70
+ """What tells this harness's code from another's: a host started by other code (another
71
+ version, another checkout) is replaced when nothing runs in it."""
72
+ from .. import __version__
73
+
74
+ return {"version": __version__, "source": str(PACKAGE)}
75
+
76
+
77
+ def read_address(base: Path | None = None) -> dict | None:
78
+ try:
79
+ return json.loads(address_file(base).read_text(encoding="utf-8"))
80
+ except (OSError, ValueError):
81
+ return None
82
+
83
+
84
+ class Session:
85
+ """A session as the host listed it: its row's fields as attributes (id, title,
86
+ frontend, status, waiting, live, directory) and the calls on it."""
87
+
88
+ def __init__(self, host: "Host", row: dict):
89
+ self.host = host
90
+ self.row = row
91
+ for key in ("id", "title", "frontend", "status", "waiting", "live", "directory", "created", "kind",
92
+ "project", "metadata", "capabilities"):
93
+ setattr(self, key, row.get(key))
94
+
95
+ def agents(self) -> list[dict]:
96
+ """Its agents in tree order: id, parent, depth, run, status, waiting, directory."""
97
+ return list(self.row.get("agents") or [])
98
+
99
+ def conversation(self, agent: str = "main") -> RemoteConversation:
100
+ """One of its agents, to drive and follow (host/client.py)."""
101
+ return self.host.conversation(self.id if agent == "main" else f"{self.id}/{agent}")
102
+
103
+ def stop(self, agent: str | None = None) -> None:
104
+ self.host.stop_session(self.id, agent)
105
+
106
+ def diff(self) -> dict:
107
+ """Read the project's current diff through the main agent."""
108
+ return self.conversation().diff()
109
+
110
+ def merge(self) -> dict:
111
+ """Fast-forward the original branch to the closed managed worktree."""
112
+ return self.conversation().merge()
113
+
114
+ def handoff(self, agent: str, context: str, **options) -> RemoteConversation:
115
+ """Start the next agent with the context selected by the caller."""
116
+ return self.conversation().handoff(agent, context, **options)
117
+
118
+ def overlay(self, agent: str | None = None, **options):
119
+ """Its timeline (or one agent's) in a window on top of the screen (the app package's overlay;
120
+ options: corner, width, height, seconds, alpha, click_through, hide, hotkey);
121
+ returns the window's process."""
122
+ return self.host.overlay(self.id if agent in (None, "main") else f"{self.id}/{agent}", **options)
123
+
124
+ def approve(self, accept: bool = True, reason: str = "", agent: str | None = None,
125
+ remember: str | None = None, *, request_id: str | None = None) -> str:
126
+ return self.host.approve(self.id, accept, reason, agent, remember, request_id=request_id)
127
+
128
+ def __repr__(self):
129
+ return f"Session({self.id!r}, {self.status!r}, {self.title!r})"
130
+
131
+
132
+ class Host:
133
+ """A client of the session host at `url` with its session key `token`."""
134
+
135
+ def __init__(self, url: str, token: str, timeout: float = 60.0, pid: int | None = None):
136
+ self.url = url.rstrip("/")
137
+ self.token = token
138
+ self.timeout = timeout
139
+ self.pid = pid
140
+ # Its answer to GET /api/host when it was found.
141
+ self.state = None
142
+
143
+ @classmethod
144
+ def connect(cls, start: bool = True, *, port: int | None = None, log=None) -> "Host | None":
145
+ """The host of this user, started first when none runs (with `start`; else None).
146
+ A host of other code is replaced only when idle. New work cannot silently run
147
+ under older code. start=False observes an existing host without replacing it."""
148
+ log = log or (lambda message: None)
149
+ host = _reachable(read_address())
150
+ if not start:
151
+ return host
152
+ if host is not None:
153
+ host = _same_code(host, log)
154
+ if host is not None or not start:
155
+ return host
156
+ with _start_lock():
157
+ host = _reachable(read_address())
158
+ if host is not None:
159
+ host = _same_code(host, log)
160
+ if host is not None:
161
+ return host
162
+ return _spawn(port, log)
163
+
164
+ def page(self) -> str:
165
+ """The app's address, with the session key."""
166
+ return f"{self.url}/?token={self.token}"
167
+
168
+ def get(self, path: str) -> dict:
169
+ """GET one of the host's routes (host/http.py, host/tasks.py): its JSON answer."""
170
+ return _get(self.url, self.token, path, self.timeout)
171
+
172
+ def post(self, path: str, body: dict, timeout: float | None = None) -> dict:
173
+ """POST `body` to one of the host's routes: its JSON answer."""
174
+ return _call(self.url, self.token, path, body, timeout or self.timeout)
175
+
176
+ def fetch(self, path: str) -> bytes:
177
+ """GET one of the host's routes that answers with bytes (a session's screen, a file)."""
178
+ return _fetch(self.url, self.token, path, self.timeout)
179
+
180
+
181
+ def info(self) -> dict:
182
+ """Its process, version, idle time and whether a session is open."""
183
+ return self.get("/api/host")
184
+
185
+ def sessions(self, all: bool = False, limit: int = 50) -> list[Session]:
186
+ """The open sessions, newest first; with `all`, those that ended too (at most `limit`)."""
187
+ answer = self.get(f"/api/sessions?all={int(bool(all))}&limit={int(limit)}")
188
+ return [Session(self, row) for row in answer["sessions"]]
189
+
190
+ def session(self, identifier: str, lines: int = 40) -> Session:
191
+ """One session by its id (or the unique start of it), with the last `lines` lines
192
+ of each agent's trace (row["agents"][i]["lines"])."""
193
+ return Session(self, self.get(f"/api/sessions/show?id={quote(str(identifier))}&lines={int(lines)}"))
194
+
195
+ def start(self, **request) -> RemoteConversation:
196
+ """Start a session: an interactive conversation of an experiment (experiment, task,
197
+ seed, model, endpoint, instruction, confirmation, sets, deploy; directory: where it
198
+ is written; title; frontend)."""
199
+ request.setdefault("frontend", "python")
200
+ return RemoteConversation.start(self.url, self.token, **request)
201
+
202
+ def task(self, text: str, workspace: str | None = "auto", confirmation: str | None = None,
203
+ runtime: dict | None = None, timeout: float = 600, files=(), *, learn=None,
204
+ agent: str | None = None, folder=None, isolation: str | None = None,
205
+ mcp_tools=(), model_entry=None, reasoning_effort=None, library=None, budget=None) -> RemoteConversation:
206
+ """Start a conversation of the app's agent with the first message `text`. `workspace`:
207
+ where it works: "none" (no environment: the conversation, the model and the connected
208
+ tools only), "project" (with `folder`), "browser", "desktop", "apps", "display"; with
209
+ "auto" (and no `folder`) the setting session.environment decides, and its default
210
+ `ask` raises ChoiceRequired here, where nobody can be asked: name the workspace.
211
+ `confirmation`: else approvals.ask;
212
+ `files`: paths the message attaches; `learn`: True for the default minutes, or a number)."""
213
+ if learn is not None:
214
+ runtime = {**(runtime or {}), "learn": learn}
215
+ given = {"confirmation": confirmation, "workspace": workspace, "runtime": runtime,
216
+ "files": [str(path) for path in files], "agent": agent, "folder": str(folder) if folder else None,
217
+ "library": library, "budget": budget, "isolation": isolation, "frontend": "python" if agent else None, "mcp_tools": list(mcp_tools)}
218
+ answer = self.post("/api/tasks", {"text": text, "model_entry": model_entry,
219
+ "reasoning_effort": reasoning_effort, **{key: value for key, value in given.items() if value}},
220
+ timeout=timeout)
221
+ return RemoteConversation(self.url, self.token, answer["run"])
222
+
223
+ def learning(self, run: str) -> dict:
224
+ """Where a conversation that learns its environment (task(..., runtime=
225
+ {"learn": minutes})) stands: live time, tested entries, open situations
226
+ (runtime/learning/active.py progress()); {"active": False} for any other."""
227
+ from urllib.parse import quote
228
+
229
+ return self.get(f"/api/app/learning?run={quote(run)}")
230
+
231
+ def agents(self) -> list[dict]:
232
+ """The external agent adapters this host can discover or start."""
233
+ return self.get("/api/app/agents")["agents"]
234
+
235
+ def import_session(self, file, provider: str, *, follow: bool = False) -> RemoteConversation:
236
+ """Observe one user-selected native JSONL transcript."""
237
+ result = self.post("/api/sessions/import", {"file": str(file), "provider": provider, "follow": follow})
238
+ return RemoteConversation(self.url, self.token, result["run"], session=result["id"])
239
+
240
+ def discover_sessions(self, agent: str, folder=None, cursor: str | None = None) -> dict:
241
+ """List sessions the selected ACP agent exposes for the project directory."""
242
+ return self.post("/api/sessions/discover", {"agent": agent, "folder": str(folder) if folder else None,
243
+ "cursor": cursor})
244
+
245
+ def observe_cloud(self, agent: str, external_id: str) -> RemoteConversation:
246
+ """Follow a cloud session created outside the host in read-only mode."""
247
+ return self.observe_external(agent, external_id)
248
+
249
+ def observe_external(self, agent: str, external_id: str, *, folder=None) -> RemoteConversation:
250
+ """Index a discovered ACP session or follow an existing cloud session in read-only mode."""
251
+ result = self.post("/api/sessions/observe", {"agent": agent, "external_id": external_id, "frontend": "python",
252
+ "folder": str(folder) if folder else None})
253
+ return RemoteConversation(self.url, self.token, result["run"])
254
+
255
+ def reconnect_session(self, identifier: str, *, released: bool, agent: str | None = None) -> RemoteConversation:
256
+ """Recover the original native ID after the user has released its old controller."""
257
+ result = self.post("/api/conversations/reconnect", {"run": identifier, "released": released, "agent": agent})
258
+ return RemoteConversation(self.url, self.token, result["run"], session=result["id"])
259
+
260
+ def conversation(self, identifier: str) -> RemoteConversation:
261
+ """A session's main agent ("<session>") or one of its agents ("<session>/<agent>")."""
262
+ conversation = RemoteConversation(self.url, self.token, str(identifier), self.timeout)
263
+ conversation.describe()
264
+ return conversation
265
+
266
+ def stop_session(self, identifier: str, agent: str | None = None) -> list[str]:
267
+ """End a session's agents (or one of them); returns the agents told to end."""
268
+ return self.post("/api/sessions/stop", {"id": identifier, "agent": agent})["stopped"]
269
+
270
+ def approve(self, identifier: str, accept: bool = True, reason: str = "", agent: str | None = None,
271
+ remember: str | None = None, *, request_id: str | None = None) -> str:
272
+ """Approve (or reject) what an agent of the session waits for; returns that agent. For
273
+ physical input `remember` keeps the answer: once, app, session or always."""
274
+ return self.post("/api/sessions/approve", {"id": identifier, "agent": agent, "accept": bool(accept),
275
+ "reason": reason, "remember": remember,
276
+ **({"request_id": request_id} if request_id else {})})["agent"]
277
+
278
+ def overlay(self, session: str | None = None, **options):
279
+ """The timeline overlay following `session` (None: the newest session that runs, and
280
+ the next one that starts); returns the window's process (the app package's overlay,
281
+ installed first when no package gives it)."""
282
+ from ..extensions import overlay
283
+
284
+ window = overlay()
285
+ return window.for_session(session, window.Options(**options), host=self)
286
+
287
+ def stop(self, force: bool = False) -> None:
288
+ """Make the host exit; with `force` it ends the open sessions first."""
289
+ self.post("/api/host/stop", {"force": bool(force)})
290
+
291
+
292
+ def connect(start: bool = True, **options) -> Host | None:
293
+ return Host.connect(start, **options)
294
+
295
+
296
+ def _reachable(address: dict | None) -> Host | None:
297
+ """The host at `address` when it answers (which counts as a client's activity, so it
298
+ does not exit right after); its answer is kept as `state`."""
299
+ if not address or not address.get("url") or not address.get("token"):
300
+ return None
301
+ host = Host(address["url"], address["token"], pid=address.get("pid"))
302
+ try:
303
+ host.timeout = 5.0
304
+ host.state = host.info()
305
+ except (RemoteError, URLError, OSError, ValueError):
306
+ return None
307
+ host.timeout = 60.0
308
+ return host
309
+
310
+
311
+ def _same_code(host: Host, log) -> Host | None:
312
+ info = host.state
313
+ mine = identity()
314
+ if all(info.get(key) == value for key, value in mine.items()):
315
+ return host
316
+ if info.get("running"):
317
+ raise RuntimeError(f"The session host runs different code ({info.get('version')} from {info.get('source')}) "
318
+ "and still has open sessions. New tasks were not submitted. "
319
+ "Use harness sessions ls and harness sessions stop SESSION to end the old sessions, "
320
+ "then retry; the idle host will be replaced automatically.")
321
+ log(f"harness: replacing the session host of other code ({info.get('version')} from {info.get('source')})")
322
+ try:
323
+ host.stop()
324
+ except (RemoteError, URLError, OSError):
325
+ pass
326
+ if not wait_until(lambda: _reachable(read_address()) is None, 15, 0.2):
327
+ raise RuntimeError("The previous session host did not stop; no replacement was started. Retry after it exits.")
328
+ return None
329
+
330
+
331
+ @contextmanager
332
+ def _start_lock(seconds: float = 90.0):
333
+ """One client at a time starts the host (a file lock, which a client that died no longer
334
+ holds); TimeoutError after `seconds`."""
335
+ path = folder() / "start.lock"
336
+ lock = file_lock(path, timeout=seconds)
337
+ try:
338
+ lock.__enter__()
339
+ except TimeoutError:
340
+ raise TimeoutError(f"another client is starting the session host ({path})") from None
341
+ try:
342
+ yield
343
+ finally:
344
+ lock.__exit__(None, None, None)
345
+
346
+
347
+ def _spawn(port: int | None, log) -> Host:
348
+ """Start the host in a process of its own: no terminal owns it (a new session on
349
+ POSIX; a new process group with a console of its own and no window on Windows, so
350
+ the processes it starts open no windows either) and it logs to DATA/logs/host.log."""
351
+ logs = data() / "logs"
352
+ logs.mkdir(parents=True, exist_ok=True)
353
+ command = [sys.executable, "-m", "harness.host.server"]
354
+ if port is not None:
355
+ command += ["--port", str(port)]
356
+ env = {**os.environ, "PYTHONPATH": python_path(), "PYTHONUTF8": "1", "PYTHONUNBUFFERED": "1"}
357
+ log(f"harness: starting the session host (log: {logs / 'host.log'})")
358
+ began = time.time()
359
+ process = start_detached(command, log=logs / "host.log", env=env)
360
+
361
+ def answers():
362
+ address = read_address()
363
+ # Its address, written after it began (a venv's python.exe on Windows is a launcher:
364
+ # the host's process id is not the one started here).
365
+ if address and (address.get("started") or 0) >= began - 1 and (host := _reachable(address)):
366
+ return host
367
+ if process.poll() is not None:
368
+ raise RuntimeError(f"the session host exited ({process.returncode}); see {logs / 'host.log'}")
369
+
370
+ if host := wait_until(answers, START_SECONDS):
371
+ return host
372
+ raise TimeoutError(f"the session host did not answer within {START_SECONDS:.0f} s; see {logs / 'host.log'}")
373
+
374
+
375
+ def resolve_run(name, sessions: bool = True) -> Path:
376
+ """The episode directory `name` names: an episode's directory, a conversation of the app
377
+ (its folder or name), or with `sessions` SESSION or SESSION/AGENT of this computer's host."""
378
+ from ..paths import data
379
+
380
+ name = str(name or "").strip()
381
+ if not name:
382
+ raise ValueError("give a run: an episode directory, a conversation or a session")
383
+ for path in (Path(name), data() / "conversations" / name):
384
+ if (path / "events.jsonl").is_file():
385
+ return path
386
+ if not sessions:
387
+ raise ValueError(f"no run {name}: give an episode directory or a conversation")
388
+ host, (session, _, agent) = Host.connect(start=False), name.partition("/")
389
+ try:
390
+ agents = host.session(session, lines=0).row.get("agents") or []
391
+ except Exception as error: # no host runs (None), or it has no such session
392
+ raise ValueError(f"no run {name}: no episode, conversation or session by that name "
393
+ f"({error if host else 'no session host runs'})") from None
394
+ for each in agents:
395
+ if (each["id"] == agent if agent else not each["depth"]) and each.get("directory"):
396
+ return Path(each["directory"])
397
+ raise ValueError(f"Session {session} has no agent {agent or 'main'} with a trace")
@@ -0,0 +1,201 @@
1
+ """A conversation run elsewhere, driven from here (after OpenHands' RemoteConversation).
2
+
3
+ RemoteConversation talks to the session host (host/http.py) with the calls of a
4
+ local TaskRun (runtime/task/run.py): send_message, pause, resume, confirm,
5
+ close, and the trace records as they are written. So a script or a terminal on a
6
+ laptop drives an episode that runs where the worker and the models are, over an ssh
7
+ tunnel to the server's port. It is also how every frontend drives a session of the
8
+ session host (host/): `run` is then the session's id, or "<session>/<agent>".
9
+ """
10
+
11
+ import json
12
+ from urllib.error import HTTPError
13
+ from urllib.parse import quote
14
+
15
+ from ..core.http import open_url, post_json, read_sse
16
+ from ..settings import ChoiceRequired
17
+
18
+
19
+ class RemoteError(RuntimeError):
20
+ """The server refused a request; the message is its reason."""
21
+
22
+
23
+ class RemoteConversation:
24
+ """The conversation `run` on the GUI server at `url` (http://host:port), with the
25
+ session key `token`. `status` is the last status its records reported."""
26
+
27
+ def __init__(self, url: str, token: str, run: str, timeout: float = 60.0, session: str | None = None):
28
+ self.url = url.rstrip("/")
29
+ self.token = token
30
+ self.run = run
31
+ self.timeout = timeout
32
+ self.status = None
33
+ self.agent = None
34
+ # The session the conversation is an agent of (when the server said).
35
+ self.session = session
36
+
37
+ @classmethod
38
+ def start(cls, url: str, token: str, **request) -> "RemoteConversation":
39
+ """Start a conversation on the server: experiment, task, seed, model, endpoint,
40
+ instruction, confirmation, sets (host/http.py start_conversation)."""
41
+ answer = _call(url.rstrip("/"), token, "/api/conversations", request, timeout=600)
42
+ return cls(url, token, answer["run"], session=answer.get("session"))
43
+
44
+ def describe(self) -> dict:
45
+ """The session this conversation belongs to, as the server lists it (its status,
46
+ what it waits for, its agents); refreshes `status`."""
47
+ row = _get(self.url, self.token, f"/api/sessions/show?id={quote(self.run)}&lines=0", self.timeout)
48
+ selected = row.get("selected_agent")
49
+ if selected is None: # Hosts from before the session details named the selected agent.
50
+ selected = next((item["id"] for item in row["agents"] if item["run"] == self.run),
51
+ self.run.partition("/")[2] or "main")
52
+ self.agent = next((item for item in row["agents"] if item["id"] == selected), None)
53
+ self.session = row["id"]
54
+ if self.agent is not None:
55
+ self.status = self.agent["status"]
56
+ return row
57
+
58
+ def memory(self) -> list[dict]:
59
+ """What it remembers: this run's entries (what it saw and where) and its library's,
60
+ in one format (runtime/task/context.py rows), as every frontend shows them."""
61
+ return _get(self.url, self.token, f"/api/library?run={quote(self.run)}", self.timeout)["entries"]
62
+
63
+ def _post(self, route: str, **body):
64
+ return _call(self.url, self.token, f"/api/conversations/{route}", {"run": self.run, **body}, self.timeout)
65
+
66
+ def send_message(self, text: str, files=()) -> None:
67
+ """A message from the user, for the model's next call; `files`: paths it attaches."""
68
+ self._post("message", text=text, **({"files": [str(path) for path in files]} if files else {}))
69
+
70
+ def steer(self, text: str, files=()) -> None:
71
+ """Redirect an active turn of an external session that supports steering."""
72
+ self._post("steer", text=text, files=[str(path) for path in files])
73
+
74
+ def cancel(self) -> None:
75
+ """Cancel an external session's current turn."""
76
+ self._post("cancel")
77
+
78
+ def set_config(self, identifier: str, value) -> dict:
79
+ """Select an advertised session configuration value."""
80
+ return self._post("config", id=identifier, value=value)
81
+
82
+ def answer(self, request_id: str, content: dict | None) -> None:
83
+ """Answer the current external form, or decline it with None."""
84
+ self._post("answer", request_id=request_id, content=content)
85
+
86
+ def diff(self) -> dict:
87
+ """Review the working changes in a Git-backed external session."""
88
+ return self._post("diff")
89
+
90
+ def merge(self) -> dict:
91
+ """Fast-forward the original branch to a closed session's committed work."""
92
+ return self._post("merge")
93
+
94
+ def discard(self) -> dict:
95
+ """Remove a closed session's managed worktree."""
96
+ return self._post("discard")
97
+
98
+ def terminal_input(self, text: str) -> None:
99
+ """Send terminal input to a session started with an interactive PTY."""
100
+ self._post("terminal", text=text)
101
+
102
+ def handoff(self, agent: str, context: str, *, folder=None, isolation=None):
103
+ """Start another agent with the context chosen by the user."""
104
+ answer = self._post("handoff", agent=agent, context=context, folder=str(folder) if folder else None,
105
+ isolation=isolation)
106
+ return RemoteConversation(self.url, self.token, answer["run"], self.timeout)
107
+
108
+ def enable_agents(self) -> None:
109
+ """Switch sub-agents on for this conversation (off unless session.agents is on): their
110
+ calls load before its next program."""
111
+ self._post("agents")
112
+
113
+ def pause(self) -> None:
114
+ """Pause at the next execution step."""
115
+ self._post("pause")
116
+
117
+ def resume(self) -> None:
118
+ """Go on after a pause."""
119
+ self._post("resume")
120
+
121
+ def confirm(self, accept: bool, reason: str = "", remember: str | None = None,
122
+ *, request_id: str | None = None) -> None:
123
+ """Approve or reject the program waiting for confirmation, or the step waiting for
124
+ physical input (remember: once, app, session, always)."""
125
+ self._post("confirm", accept=bool(accept), reason=reason, **({"remember": remember} if remember else {}),
126
+ **({"request_id": request_id} if request_id else {}))
127
+
128
+ def set_model(self, model: str | None = None, reasoning_effort: str | None = None) -> dict:
129
+ """Another main model (an id of its provider) or reasoning effort from its next call on."""
130
+ answer = self._post("model", **({"model": model} if model else {}),
131
+ **({"reasoning_effort": reasoning_effort} if reasoning_effort is not None else {}))
132
+ return {"model": answer.get("model"), "reasoning_effort": answer.get("reasoning_effort")}
133
+
134
+ def close(self) -> None:
135
+ """End the episode."""
136
+ self._post("close")
137
+
138
+ def records(self, after: int = -1, stop=None):
139
+ """The trace records after seq `after`, then each new one as it is written, until
140
+ the episode's last record (a generator; a dropped connection is resumed). With
141
+ `stop` (a threading.Event), it ends once the event is set, within the server's
142
+ keep-alive interval."""
143
+ while True:
144
+ if stop is not None and stop.is_set():
145
+ return
146
+ ended = False
147
+ try:
148
+ with open_url(f"{self.url}/api/stream?run={quote(self.run)}", timeout=self.timeout,
149
+ headers={"X-Session-API-Key": self.token, "Last-Event-ID": str(after)}) as response:
150
+ for event, data in read_sse(response):
151
+ if stop is not None and stop.is_set():
152
+ return
153
+ if event == "end":
154
+ ended = True
155
+ break
156
+ if event == "record":
157
+ record = json.loads(data)
158
+ after = record["seq"]
159
+ if record["event"] == "state":
160
+ self.status = record["status"]
161
+ yield record
162
+ except HTTPError as error:
163
+ raise RemoteError(_reason(error)) from None
164
+ except (TimeoutError, OSError):
165
+ continue
166
+ if ended:
167
+ return
168
+
169
+
170
+ def _reason(error: HTTPError) -> str:
171
+ try:
172
+ return json.loads(error.read()).get("error") or str(error)
173
+ except ValueError:
174
+ return str(error)
175
+
176
+
177
+ def _get(url: str, token: str, path: str, timeout: float) -> dict:
178
+ return json.loads(_fetch(url, token, path, timeout))
179
+
180
+
181
+ def _fetch(url: str, token: str, path: str, timeout: float) -> bytes:
182
+ try:
183
+ with open_url(url + path, headers={"X-Session-API-Key": token}, timeout=timeout) as response:
184
+ return response.read()
185
+ except HTTPError as error:
186
+ raise RemoteError(_reason(error)) from None
187
+
188
+
189
+ def _call(url: str, token: str, path: str, body: dict, timeout: float) -> dict:
190
+ try:
191
+ return post_json(url + path, body, {"X-Session-API-Key": token}, timeout)
192
+ except HTTPError as error:
193
+ try:
194
+ payload = json.loads(error.read())
195
+ except ValueError:
196
+ payload = {}
197
+ finally:
198
+ error.close()
199
+ if error.code == 409 and isinstance(payload.get("choice_required"), dict):
200
+ raise ChoiceRequired(payload["choice_required"]) from None
201
+ raise RemoteError(payload.get("error") or str(error)) from None