@lmmslab/harness 0.81.1 → 0.83.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 (80) hide show
  1. package/README.md +24 -35
  2. package/package.json +2 -2
  3. package/python/harness/README.md +3 -3
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/configs/assistant.toml +0 -1
  6. package/python/harness/builtin/configs/default.toml +1 -1
  7. package/python/harness/builtin/prompts/conversation/core.md +2 -2
  8. package/python/harness/builtin/prompts/core/core.md +197 -45
  9. package/python/harness/builtin/prompts/core/pack.toml +2 -2
  10. package/python/harness/builtin/prompts/reflect/core.md +4 -13
  11. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  12. package/python/harness/builtin/prompts/shared/learning-goal.md +5 -29
  13. package/python/harness/builtin/prompts/shared/learning.md +8 -10
  14. package/python/harness/builtin/prompts/shared/web.md +11 -0
  15. package/python/harness/builtin/skills/agents/__init__.py +24 -22
  16. package/python/harness/builtin/skills/entries/__init__.py +43 -28
  17. package/python/harness/builtin/skills/entries/skill.toml +2 -3
  18. package/python/harness/builtin/skills/environments/__init__.py +2 -9
  19. package/python/harness/builtin/skills/mcp/__init__.py +2 -3
  20. package/python/harness/builtin/skills/memory/__init__.py +2 -5
  21. package/python/harness/builtin/skills/web/__init__.py +92 -0
  22. package/python/harness/builtin/skills/web/skill.toml +9 -0
  23. package/python/harness/cli.py +85 -17
  24. package/python/harness/config/agent.py +36 -9
  25. package/python/harness/core/episodes.py +5 -4
  26. package/python/harness/core/lanes.py +3 -0
  27. package/python/harness/core/memory.py +5 -1
  28. package/python/harness/core/remote.py +4 -3
  29. package/python/harness/core/worker.py +58 -3
  30. package/python/harness/extensions.py +23 -2
  31. package/python/harness/host/__init__.py +43 -1
  32. package/python/harness/host/client.py +36 -6
  33. package/python/harness/host/http.py +19 -0
  34. package/python/harness/host/server.py +17 -3
  35. package/python/harness/host/sessions.py +3 -2
  36. package/python/harness/host/tasks.py +107 -26
  37. package/python/harness/host/workspaces.py +69 -7
  38. package/python/harness/model_list.py +1 -1
  39. package/python/harness/packages/manager.py +5 -1
  40. package/python/harness/providers.py +14 -5
  41. package/python/harness/runtime/decision/loop.py +105 -117
  42. package/python/harness/runtime/decision/messages.py +158 -55
  43. package/python/harness/runtime/decision/model.py +85 -22
  44. package/python/harness/runtime/decision/notices.py +66 -0
  45. package/python/harness/runtime/decision/prompts.py +15 -11
  46. package/python/harness/runtime/decision/protocol.py +12 -6
  47. package/python/harness/runtime/decision/thoughts.py +10 -16
  48. package/python/harness/runtime/events.py +28 -13
  49. package/python/harness/runtime/execution/attached.py +1 -1
  50. package/python/harness/runtime/execution/control.py +17 -35
  51. package/python/harness/runtime/execution/entries.py +204 -124
  52. package/python/harness/runtime/execution/kernel.py +471 -281
  53. package/python/harness/runtime/execution/managed.py +231 -0
  54. package/python/harness/runtime/execution/noenv.py +2 -2
  55. package/python/harness/runtime/execution/results.py +2 -0
  56. package/python/harness/runtime/execution/session.py +284 -115
  57. package/python/harness/runtime/learning/active.py +41 -50
  58. package/python/harness/runtime/learning/fixtures.py +2 -2
  59. package/python/harness/runtime/learning/learner.py +75 -2
  60. package/python/harness/runtime/learning/library.py +77 -10
  61. package/python/harness/runtime/learning/views.py +12 -1
  62. package/python/harness/runtime/reactive/__init__.py +1 -1
  63. package/python/harness/runtime/reactive/rules.py +29 -394
  64. package/python/harness/runtime/reactive/tree.py +611 -0
  65. package/python/harness/runtime/safety/approval.py +8 -3
  66. package/python/harness/runtime/safety/permissions.py +242 -0
  67. package/python/harness/runtime/status.py +7 -2
  68. package/python/harness/runtime/task/delegation.py +97 -58
  69. package/python/harness/runtime/task/environments.py +3 -4
  70. package/python/harness/runtime/task/inbound.py +64 -0
  71. package/python/harness/runtime/task/run.py +1231 -790
  72. package/python/harness/runtime/tick.py +257 -91
  73. package/python/harness/sdk/__init__.py +7 -4
  74. package/python/harness/settings.py +30 -5
  75. package/python/harness/terminal.py +10 -6
  76. package/python/harness/transcript.py +18 -6
  77. package/python/harness/tui/answer.py +51 -0
  78. package/python/harness/tui/chat.py +75 -26
  79. package/python/harness/tui/views.py +1 -0
  80. package/python/harness/builtin/prompts/shared/entries.md +0 -86
@@ -101,9 +101,14 @@ RUNTIME_KEYS = {
101
101
  "screenshot (a desktop's)",
102
102
  "default_max_seconds": "max_seconds of a bounded execution that names none",
103
103
  "fixed_skills": "direct mode: locate, pick and place in the action vocabulary",
104
- "isolation": "run programs isolated (default true; \"auto\": where user namespaces work)",
104
+ "isolation": "evaluation: run programs isolated, reaching only the installation, the source and the "
105
+ "environment's services (true; \"auto\": with namespaces where the machine allows them). false: "
106
+ "programs run on the machine as the user, under runtime.approvals. Experiments default to "
107
+ "\"auto\"; a conversation a user starts is not isolated",
105
108
  "keep_images": "with runtime.cameras: images of the most recent turns kept in the history (default 2). "
106
109
  "Without it the model says how long a view stays (look(keep=), pin=)",
110
+ "search": "the web search of search() (skills/web): {model, engine} on OpenRouter: a model id whose web plugin "
111
+ "searches, and optionally the plugin's engine (exa, native, ...). None: search() says there is none",
107
112
  "viewer": "written by the session host: the model role that describes a view for a main model that reads no "
108
113
  "images (the setting model.vision); none: such a model is told the view was not sent",
109
114
  "knowledge": "a game's knowledge: \"learned\" (default: use the agent's own library) or \"handwritten\" "
@@ -122,7 +127,12 @@ RUNTIME_KEYS = {
122
127
  "The active trigger's schedule (runtime/learning/active.py): active_before = true (before "
123
128
  "a task's runs, one run that learns its environment) and active_minutes = 1 to 240 (that run's live "
124
129
  "time, default 30)",
125
- "max_history_turns": "keep only this many exchanges after the first message",
130
+ "clear_results_after_minutes": "after this long without a reply of the model (the provider's cache of the "
131
+ "conversation is cold), the results of all programs but the last 5 are cleared "
132
+ "from the conversation (default 60; 0: never)",
133
+ "compact_at_tokens": "compaction: when the context a call of the model read reaches this many tokens, the model "
134
+ "writes a summary that replaces the conversation before its last messages (default 150000; "
135
+ "0: never)",
126
136
  "mode": "written by the resolution from the agent's mode",
127
137
  "actions": "written by the resolution: direct mode's action vocabulary (the agent's actions)",
128
138
  "physical": "the physical-input policy of this run over the user's settings (the computer package's "
@@ -149,10 +159,17 @@ RUNTIME_KEYS = {
149
159
  "post_policy_calls": "with learned policies: model calls after the first run of a handed-over task, then the policy runs on to the end of the episode (0: it runs on at once; default none: no bound)",
150
160
  "policy_progress_seconds": "a run of a learned policy also ends when no object the last locate tracks has moved 3 cm for this many seconds, measured every half of it (default none: only when it stops)",
151
161
  "strategy_first": "with learned policies: nothing moves before start(strategy, kind) (default false; the agent sets it)",
152
- "think_while_acting": "one speculative thought during a long program (default on). off disables speculation. "
153
- "Legacy on_events and periodic enable the same behavior. User messages and unresolved "
154
- "events are decision points in all modes",
162
+ "think_while_acting": "accepted for older profiles; it has no effect. Every program runs as a unit and the "
163
+ "model's turn is its own while one runs",
155
164
  "think_interval": "accepted for older profiles. Decision scheduling is event-driven",
165
+ "turn_grace_seconds": "how long a program may hold the model's turn (default 2): one that is over by then "
166
+ "gives the turn back with its result, a longer one goes on as a unit and the turn comes "
167
+ "back with its handle",
168
+ "longest_wait_seconds": "the longest a <wait> of the model lasts, and what a wait without a time gets "
169
+ "(default 60)",
170
+ "tell_budget": "whether the model is told with every call what the run has left (its model calls, its "
171
+ "environment steps, its live time): never (default: the host keeps the limits and ends the "
172
+ "turn at them) or always (a benchmark with short episodes, where the model plans its end)",
156
173
  "thinking": "how long a call of the main model may think (runtime/conversation.py THINKING): model (the "
157
174
  "code's default: the model's own settings), none (reasoning off, replies of at most 2000 tokens, "
158
175
  "and the model is told to think briefly), low (reasoning effort at most low, 2000 tokens, told "
@@ -165,7 +182,11 @@ RUNTIME_KEYS = {
165
182
  "vlm": "written by the resolution: the vlm role's client config",
166
183
  "world_models": "written by the resolution: the world models' client configs",
167
184
  "mcp": "written by the resolution: the MCP servers' client configs",
168
- "approvals": "{ask} (core/approval.py): the recorded choice of sensitive steps or every program.",
185
+ "approvals": "{ask, programs, rules} (runtime/safety/approval.py, permissions.py): ask = sensitive or programs "
186
+ "(whether every program waits for the user); programs = the level of what a program does on the "
187
+ "machine beyond its own folder (a command, the network, a file written elsewhere): never, "
188
+ "ask_each, ask_once_session (default), allow; rules = [{level, action, match}] that win over it. "
189
+ "Where nobody can be asked a level that asks refuses.",
169
190
  "agent_skills": "the app: Agent Skills the user installed, {name: {description, path}} (skills/agent_skills)",
170
191
  "installed_skills": "the app: the Harness skills the user installed, by name (the prompt's installed section, "
171
192
  "runtime/decision/prompts.py)",
@@ -467,10 +488,16 @@ def resolve_agent(agent=None, *, model=None, deploy=None, strict: bool = False,
467
488
  if "approvals" in runtime:
468
489
  from harness.runtime.safety import approval
469
490
 
491
+ from harness.runtime.safety import permissions
492
+
470
493
  policy = runtime["approvals"]
471
- if (not isinstance(policy, dict) or set(policy) - {"ask"}
472
- or policy.get("ask", "sensitive") not in approval.ASK):
473
- raise ValueError("runtime.approvals takes ask = sensitive or programs")
494
+ if (not isinstance(policy, dict) or set(policy) - {"ask", "programs", "rules"}
495
+ or policy.get("ask", "sensitive") not in approval.ASK
496
+ or policy.get("programs", permissions.DEFAULT_LEVEL) not in approval.LEVELS):
497
+ raise ValueError("runtime.approvals takes ask = sensitive or programs, programs = one of "
498
+ f"{', '.join(approval.LEVELS)}, and rules")
499
+ if "rules" in policy:
500
+ policy["rules"] = permissions.rules(policy["rules"])
474
501
  if runtime.get("task_descriptions") is False:
475
502
  runtime.pop("task_descriptions")
476
503
  if tree.get("mode", "program") == "direct":
@@ -2,7 +2,8 @@
2
2
 
3
3
  An episode is a directory with an events.jsonl (runtime/conversation.py); its
4
4
  manifest.json and summary.json say what ran and how it ended. An episode without a
5
- summary is still being written (or was cut off).
5
+ summary, or whose summary is `open` (a conversation between two turns), is still being
6
+ written (or was cut off).
6
7
  """
7
8
 
8
9
  import json
@@ -84,7 +85,7 @@ def describe(root: Path, directory: Path) -> dict:
84
85
  "model": (config.get("main") or {}).get("model"),
85
86
  "interactive": "interactive" in manifest,
86
87
  "modified": trace.stat().st_mtime,
87
- "live": not done,
88
+ "live": not done or bool(done.get("open")),
88
89
  }
89
90
 
90
91
 
@@ -146,5 +147,5 @@ class Follow:
146
147
  return records
147
148
 
148
149
  def ended(self) -> bool:
149
- """Whether the episode has its summary (nothing more will be written)."""
150
- return (self.path.parent / "summary.json").is_file()
150
+ """Whether the episode has its last summary (nothing more will be written)."""
151
+ return bool(summary(self.path.parent)) and not summary(self.path.parent).get("open")
@@ -67,6 +67,9 @@ class Lanes:
67
67
  kind = record.get("event") or ""
68
68
  if kind in ("outcome", "interrupted") or kind == "state" and record.get("status") in ("FINISHED", "ERROR"):
69
69
  self.ended = True
70
+ elif kind == "state":
71
+ # It goes on: after a turn that was cancelled, or continued after it had ended.
72
+ self.ended = False
70
73
  self._mark(record, kind, time)
71
74
  if kind == "span_start":
72
75
  self.has_spans = True
@@ -61,7 +61,11 @@ def rows(run=None, library=None, *, at=None) -> list[dict]:
61
61
  item = Revision.read(store.directory, row["revision"])
62
62
  candidate = _library_entry(item.key, item.source.decode("utf-8"), row, captured.version,
63
63
  evidence="proposed", sha256=item.source_sha256)
64
- found.append({**candidate, "id": key, "revision": item.revision, "status": "pending"})
64
+ waiting = {**candidate, "id": key, "revision": item.revision, "status": "pending"}
65
+ if row.get("demoted"):
66
+ # Admitted by its own test once, then sent back after failing in use.
67
+ waiting["cells"] = ["proposed (demoted)", waiting["name"] or ""]
68
+ found.append(waiting)
65
69
  return _cells(found)
66
70
 
67
71
 
@@ -80,11 +80,12 @@ class RemoteEnvironment:
80
80
  "execute", action=action.to_dict(), episode_id=episode_id, step=step,
81
81
  ))
82
82
 
83
- def call(self, name: str, **arguments):
84
- """Invoke an environment-specific worker method."""
83
+ def call(self, name: str, /, **arguments):
84
+ """Invoke an environment-specific worker method. The method's name is positional, so
85
+ that a method may have an argument called `name` of its own."""
85
86
  return self._call("call", name=name, arguments=arguments)
86
87
 
87
- def managed_call(self, name, *, approval_key, **arguments):
88
+ def managed_call(self, name, /, *, approval_key, **arguments):
88
89
  """Send one worker control call with the trusted host's proof."""
89
90
  return self._request("call", {"name": name, "arguments": arguments}, approval_key=approval_key)
90
91
 
@@ -8,6 +8,7 @@ anything. The session skeleton (runtime/execution/session.py EpisodeCore) needs
8
8
  from http.server import BaseHTTPRequestHandler, HTTPServer
9
9
  import hmac
10
10
  import json
11
+ import threading
11
12
 
12
13
  from harness.runtime.safety.approval import APPROVAL_PIPE_FLAG, WORKER_APPROVAL_HEADER, WORKER_APPROVAL_KEY, read_worker_startup, worker_approval_proof
13
14
  from .codec import EpisodeCursor, OutcomeToken
@@ -16,14 +17,68 @@ from .ports import OwnPort
16
17
 
17
18
  # The worker protocol: what every worker serves to the session skeleton and the
18
19
  # conversation, besides describe, reset and execute: what the embodiment is (profile: its kind,
19
- # control rate, clock, channels, cameras and shield), its state now, one control period's
20
+ # control rate, how it is driven (max_hz, step_seconds: runtime/tick.py driving), channels, cameras and shield),
21
+ # its state now, one control period's
20
22
  # command, judged by its shield (tick), the views of its cameras or screen (observe), and
21
23
  # the evaluator's outcome (claim_outcome, outcome). An embodiment adds its own methods (a robot's
22
24
  # fk, ik and plan; a computer's windows; a game's world): `methods = (*WORKER_METHODS, ...)`.
23
- WORKER_METHODS = ("profile", "state", "tick", "observe", "claim_outcome", "outcome")
25
+ #
26
+ # Senses (optional). A worker whose environment can run code where it is says so in its
27
+ # profile, "senses": True, and serves three more methods: sense(episode_id, sense, code)
28
+ # keeps `code` under the name `sense` and answers {"defined", "value", "error"};
29
+ # senses(episode_id) answers {name: {"code", "value", "error"}}; drop_sense(episode_id,
30
+ # sense) removes one. From then on its state carries "sensed": {name: value}, computed by
31
+ # the environment each time it reports its state (None for a sense whose code failed). The
32
+ # language of the code and what it has in scope are the environment's (its prompt says).
33
+ #
34
+ # References (optional). A worker whose environment gives the agent things to act with that
35
+ # are documented or readable where the worker runs (the libraries its programs call) names
36
+ # the folders that hold them in its profile, "references": [path, ...]. Programs may read
37
+ # them, and the model is told where they are with its first message.
38
+ #
39
+ # Pausing (optional). A worker whose environment can hold what a call is doing and let it go
40
+ # on later says so in its profile, "pauses": True, and serves two more methods:
41
+ # pause(episode_id, by) holds what runs and answers what it needs to let it go on (any value);
42
+ # `by` names who takes the environment (a reflex, or a unit), for what is held to know;
43
+ # resume(episode_id, held) is given that value and lets it go on. The run then pauses a
44
+ # call for a unit of higher priority instead of ending it (runtime/tick.py).
45
+ WORKER_METHODS = ("profile", "state", "tick", "observe", "claim_outcome", "outcome", "tell_to")
46
+
47
+
48
+ class Tells:
49
+ """A worker that tells the run what happens in its environment by itself. Its profile
50
+ says "tells": True; the run then gives it where to tell (`tell_to`: runtime/task/
51
+ inbound.py), and `tell()` puts a message before the model at once."""
52
+
53
+ _told_to = None
54
+
55
+ def _call_tell_to(self, url, token, episode_id=None):
56
+ self._told_to = (str(url), str(token))
57
+ return {"tells": True}
58
+
59
+ def tell(self, content, source=None) -> bool:
60
+ """Tell the model now: `content` is a message as conversations give it, a string or
61
+ a list of parts ({"type": "text", "text"}, {"type": "image_url", "image_url":
62
+ {"url": a data URL}}). Returns at once; False when no run listens. It is sent on a
63
+ thread of its own, so the worker's calls go on."""
64
+ if self._told_to is None:
65
+ return False
66
+ url, token = self._told_to
67
+ body = json.dumps({"token": token, "content": content, "source": source}).encode()
68
+
69
+ def send():
70
+ import urllib.request
71
+
72
+ try:
73
+ request = urllib.request.Request(url, data=body, method="POST", headers={"content-type": "application/json"})
74
+ urllib.request.urlopen(request, timeout=20).read()
75
+ except Exception: # the run is gone or busy: what happened is still in the state
76
+ pass
77
+ threading.Thread(target=send, name="worker-tells", daemon=True).start()
78
+ return True
24
79
 
25
80
 
26
- class BenchWorker:
81
+ class BenchWorker(Tells):
27
82
  """What a benchmark's worker shares (a mixin): the call dispatch to its `_call_<name>`
28
83
  methods, input refused outside tick (which its shield checks), the state call, the
29
84
  check of the views observe takes, the envelope of a tick, and the outcome behind a
@@ -20,6 +20,12 @@ by name and imports no package itself. A host module may define:
20
20
  session_adapter(name, directory, *, cwd, isolation, model, effort)
21
21
  a host-managed external conversation, or None for a name
22
22
  this package does not provide. Its trace lives in directory.
23
+ model_backend(config) the transport of a model role (runtime/decision/model.py
24
+ MODEL_KEYS) whose `backend` this package provides, or None
25
+ for another backend: called like a Chat Completions request
26
+ (url, headers, payload, timeout), it answers in that shape.
27
+ `streams_text` true: it takes on_text; `cancellable` true:
28
+ it takes cancellation
23
29
  pages the package's pages: {"/taptab": "taptab.html"}, files of its
24
30
  ui/static/ served at those paths (host/http.py); its other
25
31
  files are at /static/<package>/<file>
@@ -46,6 +52,7 @@ Standard library only.
46
52
  import importlib
47
53
 
48
54
  _CACHE = {}
55
+ _PROBLEMS = {}
49
56
 
50
57
 
51
58
  def hosts() -> list:
@@ -57,11 +64,25 @@ def hosts() -> list:
57
64
  roots = tuple(package.path for package in found)
58
65
  if roots not in _CACHE:
59
66
  _CACHE.clear()
60
- _CACHE[roots] = [(package, importlib.import_module(package.provides["host"][0])) for package in found
61
- if "host" in package.provides]
67
+ _PROBLEMS.clear()
68
+ loaded = []
69
+ for package in found:
70
+ if "host" not in package.provides:
71
+ continue
72
+ try:
73
+ loaded.append((package, importlib.import_module(package.provides["host"][0])))
74
+ except Exception as error: # a package made for another harness: it alone is left out
75
+ _PROBLEMS[package.name] = (f"{package.name} {package.version} was skipped: its host module did not "
76
+ f"import ({type(error).__name__}: {error}): harness install --update")
77
+ _CACHE[roots] = loaded
62
78
  return _CACHE[roots]
63
79
 
64
80
 
81
+ def host_problems() -> dict:
82
+ """{package: why its host module was left out} of the last hosts()."""
83
+ return dict(_PROBLEMS)
84
+
85
+
65
86
  def modules() -> list:
66
87
  """The host modules of the packages this process uses, in their order (paths.packages)."""
67
88
  return [module for _, module in hosts()]
@@ -74,6 +74,17 @@ def identity() -> dict:
74
74
  return {"version": __version__, "source": str(PACKAGE)}
75
75
 
76
76
 
77
+ def installed_packages(directory: Path | None = None) -> list[str]:
78
+ """The user's enabled packages as a host starting now loads them ("name version folder",
79
+ in name order). A host reports the ones it loaded (`packages` of GET /api/host), so a
80
+ client finds a host that predates an install, a removal or an update (_same_packages). A
81
+ trusted project's packages are left out: they follow a client's working directory."""
82
+ from ..packages import Packages
83
+
84
+ listed = Packages(directory).user().packages
85
+ return [f"{name} {record.version} {record.path}" for name, record in sorted(listed.items()) if record.enabled]
86
+
87
+
77
88
  def read_address(base: Path | None = None) -> dict | None:
78
89
  try:
79
90
  return json.loads(address_file(base).read_text(encoding="utf-8"))
@@ -257,6 +268,13 @@ class Host:
257
268
  result = self.post("/api/conversations/reconnect", {"run": identifier, "released": released, "agent": agent})
258
269
  return RemoteConversation(self.url, self.token, result["run"], session=result["id"])
259
270
 
271
+ def resume_session(self, identifier: str | None = None) -> RemoteConversation:
272
+ """Continue a session of the Harness agent in its own id (None: the most recent one).
273
+ One that ended (the host stopped, it was closed or parked) starts again with its
274
+ messages and facts and a new kernel; one that runs is given as it is."""
275
+ result = self.post("/api/sessions/resume", {"id": identifier}, timeout=600)
276
+ return RemoteConversation(self.url, self.token, result["run"], session=result["id"])
277
+
260
278
  def conversation(self, identifier: str) -> RemoteConversation:
261
279
  """A session's main agent ("<session>") or one of its agents ("<session>/<agent>")."""
262
280
  conversation = RemoteConversation(self.url, self.token, str(identifier), self.timeout)
@@ -312,13 +330,37 @@ def _same_code(host: Host, log) -> Host | None:
312
330
  info = host.state
313
331
  mine = identity()
314
332
  if all(info.get(key) == value for key, value in mine.items()):
315
- return host
333
+ return _same_packages(host, log)
316
334
  if info.get("running"):
317
335
  raise RuntimeError(f"The session host runs different code ({info.get('version')} from {info.get('source')}) "
318
336
  "and still has open sessions. New tasks were not submitted. "
319
337
  "Use harness sessions ls and harness sessions stop SESSION to end the old sessions, "
320
338
  "then retry; the idle host will be replaced automatically.")
321
339
  log(f"harness: replacing the session host of other code ({info.get('version')} from {info.get('source')})")
340
+ return _replace(host)
341
+
342
+
343
+ def _same_packages(host: Host, log) -> Host | None:
344
+ """A host of this code that loaded other packages than are installed now (harness
345
+ install, remove or update ran in another process since it started) is replaced once
346
+ idle: its process keeps the modules it imported, so only a new one loads the packages
347
+ as they are. While its sessions run it is kept, and they go on with what they started with."""
348
+ loaded = host.state.get("packages")
349
+ try:
350
+ same = loaded is None or loaded == installed_packages()
351
+ except (OSError, ValueError): # the list cannot be read here: nothing to compare with
352
+ same = True
353
+ if same:
354
+ return host
355
+ if host.state.get("running"):
356
+ log("harness: the session host keeps the packages it started with until its sessions end")
357
+ return host
358
+ log("harness: restarting the session host for the packages installed, removed or updated since it started")
359
+ return _replace(host)
360
+
361
+
362
+ def _replace(host: Host) -> None:
363
+ """Stop an idle host so that a new one starts; refused when it does not go away."""
322
364
  try:
323
365
  host.stop()
324
366
  except (RemoteError, URLError, OSError):
@@ -9,6 +9,7 @@ session host (host/): `run` is then the session's id, or "<session>/<agent>".
9
9
  """
10
10
 
11
11
  import json
12
+ import time
12
13
  from urllib.error import HTTPError
13
14
  from urllib.parse import quote
14
15
 
@@ -20,6 +21,17 @@ class RemoteError(RuntimeError):
20
21
  """The server refused a request; the message is its reason."""
21
22
 
22
23
 
24
+ class HostGone(RemoteError):
25
+ """The server stopped answering: no connection for GONE_SECONDS in a row."""
26
+
27
+
28
+ # How long the records stream tries again, waiting longer each time (RETRY_SECONDS up to
29
+ # RETRY_LIMIT), before it says the server is gone.
30
+ GONE_SECONDS = 15.0
31
+ RETRY_SECONDS = 0.1
32
+ RETRY_LIMIT = 2.0
33
+
34
+
23
35
  class RemoteConversation:
24
36
  """The conversation `run` on the GUI server at `url` (http://host:port), with the
25
37
  session key `token`. `status` is the last status its records reported."""
@@ -64,7 +76,8 @@ class RemoteConversation:
64
76
  return _call(self.url, self.token, f"/api/conversations/{route}", {"run": self.run, **body}, self.timeout)
65
77
 
66
78
  def send_message(self, text: str, files=()) -> None:
67
- """A message from the user, for the model's next call; `files`: paths it attaches."""
79
+ """A message from the user: for the model's next call while a turn runs, else it starts
80
+ the conversation's next turn; `files`: paths it attaches."""
68
81
  self._post("message", text=text, **({"files": [str(path) for path in files]} if files else {}))
69
82
 
70
83
  def steer(self, text: str, files=()) -> None:
@@ -72,7 +85,7 @@ class RemoteConversation:
72
85
  self._post("steer", text=text, files=[str(path) for path in files])
73
86
 
74
87
  def cancel(self) -> None:
75
- """Cancel an external session's current turn."""
88
+ """End the turn that runs; the conversation waits for the next message."""
76
89
  self._post("cancel")
77
90
 
78
91
  def set_config(self, identifier: str, value) -> dict:
@@ -132,14 +145,17 @@ class RemoteConversation:
132
145
  return {"model": answer.get("model"), "reasoning_effort": answer.get("reasoning_effort")}
133
146
 
134
147
  def close(self) -> None:
135
- """End the episode."""
148
+ """End the conversation."""
136
149
  self._post("close")
137
150
 
138
151
  def records(self, after: int = -1, stop=None):
139
152
  """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
153
+ the conversation's last record (a generator; a dropped connection is resumed; a
154
+ turn's end is its turn_result record, after which the conversation waits). With
141
155
  `stop` (a threading.Event), it ends once the event is set, within the server's
142
- keep-alive interval."""
156
+ keep-alive interval. When the server stops answering, it tries again, waiting longer
157
+ each time, and raises HostGone after GONE_SECONDS without a connection."""
158
+ failing, delay = None, RETRY_SECONDS
143
159
  while True:
144
160
  if stop is not None and stop.is_set():
145
161
  return
@@ -147,6 +163,7 @@ class RemoteConversation:
147
163
  try:
148
164
  with open_url(f"{self.url}/api/stream?run={quote(self.run)}", timeout=self.timeout,
149
165
  headers={"X-Session-API-Key": self.token, "Last-Event-ID": str(after)}) as response:
166
+ failing, delay = None, RETRY_SECONDS
150
167
  for event, data in read_sse(response):
151
168
  if stop is not None and stop.is_set():
152
169
  return
@@ -161,7 +178,20 @@ class RemoteConversation:
161
178
  yield record
162
179
  except HTTPError as error:
163
180
  raise RemoteError(_reason(error)) from None
164
- except (TimeoutError, OSError):
181
+ except TimeoutError: # a quiet stream: open it again
182
+ continue
183
+ except OSError as error: # refused, reset: the server may be restarting, or gone
184
+ now = time.monotonic()
185
+ failing = failing or now
186
+ if now - failing >= GONE_SECONDS:
187
+ raise HostGone(f"the session host at {self.url} does not answer "
188
+ f"({getattr(error, 'reason', None) or error})") from None
189
+ if stop is not None:
190
+ if stop.wait(delay):
191
+ return
192
+ else:
193
+ time.sleep(delay)
194
+ delay = min(delay * 2, RETRY_LIMIT)
165
195
  continue
166
196
  if ended:
167
197
  return
@@ -71,6 +71,7 @@ import re
71
71
  import secrets
72
72
  import threading
73
73
  import time
74
+ import traceback
74
75
  from urllib.parse import parse_qs, urlparse
75
76
 
76
77
  from .. import __version__
@@ -329,6 +330,10 @@ class Handler(BaseHTTPRequestHandler):
329
330
 
330
331
  # Answers.
331
332
 
333
+ def send_response(self, code, message=None):
334
+ self.answered = True # this request's answer has begun (see _failed)
335
+ super().send_response(code, message)
336
+
332
337
  def _send(self, status, body: bytes, content_type: str, headers=()):
333
338
  self.send_response(status)
334
339
  self.send_header("Content-Type", content_type)
@@ -387,6 +392,7 @@ class Handler(BaseHTTPRequestHandler):
387
392
  # Requests.
388
393
 
389
394
  def do_GET(self):
395
+ self.answered = False
390
396
  url = urlparse(self.path)
391
397
  query = parse_qs(url.query)
392
398
  if url.path.startswith("/static/"):
@@ -413,10 +419,21 @@ class Handler(BaseHTTPRequestHandler):
413
419
  return self._error(HTTPStatus.BAD_REQUEST, str(error))
414
420
  except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
415
421
  return None
422
+ except Exception as error:
423
+ return self._failed(error)
424
+
425
+ def _failed(self, error):
426
+ """Any other error of a route (a bug, or a package's code that does not fit): logged,
427
+ and answered with what it was, so the client says why instead of losing the connection."""
428
+ traceback.print_exc()
429
+ if getattr(self, "answered", False):
430
+ return None # part of an answer was sent: nothing more can be said on it
431
+ return self._error(HTTPStatus.INTERNAL_SERVER_ERROR, f"{type(error).__name__}: {error}")
416
432
 
417
433
  do_HEAD = do_GET
418
434
 
419
435
  def do_POST(self):
436
+ self.answered = False
420
437
  url = urlparse(self.path)
421
438
  if not self._authorized({}):
422
439
  return self._error(HTTPStatus.UNAUTHORIZED, "missing or wrong session key")
@@ -432,6 +449,8 @@ class Handler(BaseHTTPRequestHandler):
432
449
  return self._json({"error": str(error), "choice_required": error.choice}, HTTPStatus.CONFLICT)
433
450
  except (ValueError, KeyError, RuntimeError, OSError) as error:
434
451
  return self._error(HTTPStatus.BAD_REQUEST, f"{type(error).__name__}: {error}")
452
+ except Exception as error:
453
+ return self._failed(error)
435
454
 
436
455
  def _answer(self, answer):
437
456
  """A package handler's answer: JSON, or a tuple (body, content type, headers) as it is."""
@@ -16,7 +16,7 @@ from ..core.ports import free_port
16
16
  from ..core import atomic_write
17
17
  from ..core.wait import wait_until
18
18
  from ..paths import data
19
- from . import PORT, PORT_ENV, address_file, identity, idle_seconds, index_file, read_address, _reachable
19
+ from . import PORT, PORT_ENV, address_file, identity, idle_seconds, index_file, installed_packages, read_address, _reachable
20
20
  from .sessions import Sessions, history, live
21
21
 
22
22
 
@@ -50,6 +50,20 @@ class HostServer(TaskServer):
50
50
  self.started = time.time()
51
51
  self._last = time.monotonic()
52
52
  self.background = {}
53
+ # The user's packages this process loaded (state()["packages"]), against which a
54
+ # client tells an install, a removal or an update in another process.
55
+ self.loaded = installed_packages(app.directory)
56
+ if getattr(app, "packages", None) is not None:
57
+ app.packages.on_change = self._packages_changed
58
+
59
+ def _packages_changed(self) -> None:
60
+ """This host installed, removed or updated packages itself (/packages, a first use).
61
+ Packages it only added load in this process, so they count as loaded; a removal or an
62
+ update needs a new process, so it goes on reporting what it loaded and a client
63
+ replaces it once it is idle."""
64
+ now = installed_packages(self.app.directory)
65
+ if set(self.loaded) <= set(now):
66
+ self.loaded = now
53
67
 
54
68
  def start_background(self):
55
69
  from ..extensions import hosts
@@ -81,8 +95,8 @@ class HostServer(TaskServer):
81
95
 
82
96
  def state(self) -> dict:
83
97
  host, port = self.server_address[:2]
84
- return {**identity(), "pid": os.getpid(), "url": f"http://127.0.0.1:{port}", "started": self.started,
85
- "idle_seconds": round(time.monotonic() - self._last, 1), "idle_limit": self.idle,
98
+ return {**identity(), "packages": self.loaded, "pid": os.getpid(), "url": f"http://127.0.0.1:{port}",
99
+ "started": self.started, "idle_seconds": round(time.monotonic() - self._last, 1), "idle_limit": self.idle,
86
100
  "running": self.running(), "open": sum(1 for row in self.conversations.sessions() if row["live"])}
87
101
 
88
102
  def session_directory(self, request: dict, config, seed: int):
@@ -63,10 +63,11 @@ def _usage(conversation) -> dict:
63
63
 
64
64
 
65
65
  def spent(usage: dict | None) -> str:
66
- """Usage as a cell: "12 calls $0.034"."""
66
+ """Usage as a cell: "12 calls". No dollars: only OpenRouter reports a cost, so a
67
+ total would read $0 on every other provider (usage keeps cost_usd as recorded)."""
67
68
  usage = usage or {}
68
69
  calls = usage.get("model_calls") or 0
69
- return f"{calls} call{'s' if calls != 1 else ''} {formats.cost(usage.get('cost_usd') or 0)}" if usage else ""
70
+ return f"{calls} call{'s' if calls != 1 else ''}" if usage else ""
70
71
 
71
72
 
72
73
  def _title(conversation) -> str: