@lmmslab/harness 0.82.0 → 0.84.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 (39) hide show
  1. package/README.md +2 -2
  2. package/bin/harness.js +6 -1
  3. package/package.json +1 -1
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/prompts/core/core.md +61 -30
  6. package/python/harness/builtin/prompts/reflect/core.md +3 -12
  7. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  8. package/python/harness/builtin/prompts/shared/learning-goal.md +1 -1
  9. package/python/harness/cli.py +104 -18
  10. package/python/harness/config/agent.py +3 -0
  11. package/python/harness/core/trace.py +23 -3
  12. package/python/harness/core/worker.py +6 -0
  13. package/python/harness/host/client.py +26 -21
  14. package/python/harness/host/http.py +11 -1
  15. package/python/harness/host/sessions.py +38 -3
  16. package/python/harness/host/tasks.py +62 -26
  17. package/python/harness/model_list.py +25 -5
  18. package/python/harness/packages/environments.py +51 -12
  19. package/python/harness/packages/manager.py +379 -102
  20. package/python/harness/packages/resolve.py +52 -15
  21. package/python/harness/packages/sources.py +17 -5
  22. package/python/harness/packages/state.py +10 -0
  23. package/python/harness/providers.py +66 -24
  24. package/python/harness/runtime/decision/loop.py +18 -9
  25. package/python/harness/runtime/decision/messages.py +5 -10
  26. package/python/harness/runtime/decision/model.py +21 -11
  27. package/python/harness/runtime/decision/notices.py +66 -0
  28. package/python/harness/runtime/execution/entries.py +53 -7
  29. package/python/harness/runtime/execution/session.py +60 -7
  30. package/python/harness/runtime/learning/active.py +12 -9
  31. package/python/harness/runtime/reactive/tree.py +35 -22
  32. package/python/harness/runtime/task/run.py +259 -162
  33. package/python/harness/runtime/tick.py +34 -3
  34. package/python/harness/settings.py +8 -3
  35. package/python/harness/tui/__init__.py +28 -6
  36. package/python/harness/tui/chat.py +243 -67
  37. package/python/harness/tui/pty.py +16 -0
  38. package/python/harness/tui/renderer.py +34 -0
  39. package/python/harness/tui/views.py +160 -38
@@ -7,6 +7,7 @@ and works with this harness is taken. With a dozen packages a simple fixed point
7
7
  a conflict names who needs what.
8
8
  """
9
9
 
10
+ from .manifest import platform
10
11
  from .registry import RegistryError, harness_fits
11
12
  from .versions import best, satisfies
12
13
 
@@ -16,28 +17,43 @@ class ResolveError(ValueError):
16
17
 
17
18
 
18
19
  def resolve(requests: dict, registry, *, harness: str, have: dict | None = None, fixed: dict | None = None,
19
- depends_of=None) -> dict:
20
+ depends_of=None, use_installed=None) -> dict:
20
21
  """{name: version} for `requests` ({name: range}) and their dependencies.
21
22
 
22
23
  `have`: {name: version} already installed (kept when they fit); `fixed`: {name:
23
24
  (version, depends)} of packages from other sources, which cannot change;
24
25
  `depends_of(name, version)`: the depends of an installed version (default: the
25
- registry's)."""
26
+ registry's). Retained installed packages constrain active dependencies without
27
+ adding unrelated dependency requests; a parent selected for replacement uses
28
+ its selected manifest instead. `use_installed(name, version)` can decline an
29
+ installed preference/active manifest without discarding retained parent metadata."""
26
30
  have, fixed = dict(have or {}), dict(fixed or {})
27
31
  needs: dict[str, dict[str, str]] = {}
28
32
 
29
33
  def need(name, wanted, by):
30
34
  needs.setdefault(name, {})[by] = wanted
31
35
 
32
- def depends(name, version):
36
+ def depends(name, version, *, retained=False):
33
37
  if name in fixed:
34
38
  return fixed[name][1]
35
- if depends_of is not None:
39
+ if depends_of is not None and (retained or use_installed is None or use_installed(name, version)):
36
40
  found = depends_of(name, version)
37
- if found is not None:
41
+ if found is not None or retained:
38
42
  return found
39
43
  return registry.entry(name, version).get("depends", {})
40
44
 
45
+ retained = {}
46
+ for name, version in have.items():
47
+ if name in requests or name in fixed:
48
+ continue
49
+ try:
50
+ wants = depends(name, version, retained=True)
51
+ if wants is not None:
52
+ retained[name] = (version, wants)
53
+ except (RegistryError, ValueError):
54
+ # An unavailable retained manifest is not an explicit install request.
55
+ continue
56
+
41
57
  for name, wanted in requests.items():
42
58
  need(name, wanted, "you")
43
59
  chosen = {}
@@ -47,26 +63,43 @@ def resolve(requests: dict, registry, *, harness: str, have: dict | None = None,
47
63
  need(other, wanted, f"{name} {version}")
48
64
  for _ in range(200):
49
65
  changed = False
50
- for name in sorted(needs):
51
- ranges = list(needs[name].values())
66
+ problems = []
67
+ for name in sorted(needs.keys() | fixed.keys()):
68
+ if not needs.get(name) and name not in fixed:
69
+ continue
70
+ constraints = dict(needs.get(name, {}))
71
+ for parent, (version, wants) in retained.items():
72
+ # An active parent contributes the selected version's edges below.
73
+ # An inactive retained parent constrains only already active names.
74
+ if not needs.get(parent) and name in wants:
75
+ constraints[f"{parent} {version}"] = wants[name]
76
+ ranges = list(constraints.values())
52
77
  current = chosen.get(name)
53
78
  if current and all(satisfies(current, wanted) for wanted in ranges):
54
79
  continue
55
80
  if name in fixed:
56
- raise ResolveError(_conflict(name, needs[name], f"{name} {current} (from its source) is not in range"))
57
- pick = have.get(name) if have.get(name) and all(satisfies(have[name], r) for r in ranges) else None
81
+ problems.append(ResolveError(_conflict(name, constraints,
82
+ f"{name} {current} (from its source) is not in range")))
83
+ continue
84
+ pick = (have.get(name) if have.get(name) and all(satisfies(have[name], r) for r in ranges)
85
+ and (use_installed is None or use_installed(name, have[name])) else None)
58
86
  if pick is None:
59
87
  try:
60
88
  published = [version for version in registry.versions(name)
61
- if harness_fits(registry.entry(name, version), harness)]
89
+ if harness_fits(registry.entry(name, version), harness)
90
+ and (not registry.entry(name, version).get("platforms")
91
+ or platform() in registry.entry(name, version)["platforms"])]
62
92
  except RegistryError as error:
63
- raise ResolveError(f"{name}: {error}") from None
93
+ problems.append(ResolveError(f"{name}: {error}"))
94
+ continue
64
95
  if not published and name not in registry.packages():
65
- raise ResolveError(f"no package {name} in {registry.base}" + _who(needs[name]))
96
+ problems.append(ResolveError(f"no package {name} in {registry.base}" + _who(constraints)))
97
+ continue
66
98
  pick = best(published, *ranges)
67
99
  if pick is None:
68
- raise ResolveError(_conflict(name, needs[name], f"published for harness {harness}: "
69
- f"{', '.join(published) or 'none'}"))
100
+ problems.append(ResolveError(_conflict(name, constraints, f"published for harness {harness}: "
101
+ f"{', '.join(published) or 'none'}")))
102
+ continue
70
103
  if current:
71
104
  for other in needs.values():
72
105
  other.pop(f"{name} {current}", None)
@@ -75,7 +108,11 @@ def resolve(requests: dict, registry, *, harness: str, have: dict | None = None,
75
108
  need(other, wanted, f"{name} {pick}")
76
109
  changed = True
77
110
  if not changed:
78
- return {name: chosen[name] for name in sorted(chosen) if name in needs or name in fixed}
111
+ # A later selection can activate/replace a retained parent, removing an
112
+ # apparent conflict. Report it only after no selection can make progress.
113
+ if problems:
114
+ raise problems[0]
115
+ return {name: chosen[name] for name in sorted(chosen) if needs.get(name) or name in fixed}
79
116
  raise ResolveError("the versions did not settle: " + ", ".join(f"{n} {v}" for n, v in sorted(chosen.items())))
80
117
 
81
118
 
@@ -47,12 +47,22 @@ class Source:
47
47
  return self.kind == "registry"
48
48
 
49
49
 
50
- def parse(text) -> Source:
50
+ def parse(text, *, base: Path | None = None) -> Source:
51
51
  """The source `text` names; ValueError when it names none."""
52
52
  text = str(text or "").strip()
53
53
  if not text:
54
54
  raise ValueError("give a package name, a git URL, an archive URL or a folder")
55
- if text.startswith("git:") or text.startswith("git+"):
55
+ original = text
56
+ force_path = text.startswith("path:")
57
+ if force_path:
58
+ text = text[5:]
59
+ if not text:
60
+ raise ValueError("path: needs a folder or archive path")
61
+ elif text.startswith("url:"):
62
+ text = text[4:]
63
+ if not text.startswith(("https://", "http://")):
64
+ raise ValueError("url: needs an HTTP or HTTPS archive URL")
65
+ if not force_path and (text.startswith("git:") or text.startswith("git+")):
56
66
  rest = text[4:]
57
67
  rest = rest if rest.startswith(("https://", "http://", "ssh://", "git@", "file://")) else f"https://{rest}"
58
68
  rest, _, subdir = rest.partition("#")
@@ -63,7 +73,7 @@ def parse(text) -> Source:
63
73
  else:
64
74
  ref = ""
65
75
  return Source("git", text, url=rest, ref=ref, subdir=subdir.strip("/"))
66
- if re.match(r"^https?://", text):
76
+ if not force_path and re.match(r"^https?://", text):
67
77
  github = GITHUB_TREE.match(text)
68
78
  if github:
69
79
  return Source("git", text, url=f"https://github.com/{github.group(1)}/{github.group(2)}",
@@ -74,15 +84,17 @@ def parse(text) -> Source:
74
84
  return Source("git", text, url=text)
75
85
  raise ValueError(f"{text}: a URL of an archive ({', '.join(ARCHIVES)}) or of a git repository (.git)")
76
86
  local = Path(os.path.expanduser(text))
87
+ if base is not None and not local.is_absolute():
88
+ local = base / local
77
89
  # A bare name is the registry's even when a folder of that name is here (./name is the folder).
78
- looks_local = text.startswith((".", "/", "\\", "~")) or re.match(r"^[A-Za-z]:[\\/]", text) or os.sep in text \
90
+ looks_local = force_path or text.startswith((".", "/", "\\", "~")) or re.match(r"^[A-Za-z]:[\\/]", text) or os.sep in text \
79
91
  or "/" in text or text.lower().endswith(ARCHIVES)
80
92
  if looks_local:
81
93
  if not local.exists():
82
94
  raise ValueError(f"{text}: no such folder or file")
83
95
  if local.is_file() and not local.name.lower().endswith(ARCHIVES):
84
96
  raise ValueError(f"{text}: a folder or an archive ({', '.join(ARCHIVES)})")
85
- return Source("path", text, path=str(local.resolve()))
97
+ return Source("path", original, path=str(local.resolve()))
86
98
  match = REGISTRY_NAME.match(text)
87
99
  if not match:
88
100
  raise ValueError(f"{text}: not a package name (lowercase letters, digits, hyphens), a URL or a folder")
@@ -205,6 +205,16 @@ def freeze(folder: Path) -> None:
205
205
 
206
206
  def delete(folder: Path) -> None:
207
207
  """Remove an installed version (its files are read-only)."""
208
+ resolved = Path(folder).resolve()
209
+ cwd = Path.cwd().resolve()
210
+ protected = {cwd, Path(resolved.anchor), *cwd.parents}
211
+ try:
212
+ protected.add(Path.home().resolve())
213
+ except RuntimeError:
214
+ pass # A container may have explicit Harness paths but no home/passwd entry.
215
+ if resolved in protected:
216
+ raise ValueError(f"refusing to delete a working directory, ancestor, home or filesystem root: {resolved}")
217
+
208
218
  def writable(function, path, _):
209
219
  os.chmod(path, stat.S_IWRITE | stat.S_IREAD | stat.S_IEXEC)
210
220
  function(path)
@@ -49,7 +49,7 @@ PROVIDERS = {provider.id: provider for provider in (
49
49
  Provider("ollama", "Ollama (this computer)", "http://localhost:11434/v1", None,
50
50
  note="no key; the model must be pulled in Ollama"),
51
51
  Provider("custom", "Custom (OpenAI-compatible)", None, "HARNESS_LLM_API_KEY",
52
- note="vLLM, SGLang, LM Studio, a gateway: give the base URL"),
52
+ note="vLLM, SGLang, LM Studio, a gateway: give the base URL; key optional"),
53
53
  )}
54
54
  DEFAULT = {"provider": "openrouter", "model": "deepseek/deepseek-v4.1-flash", "base_url": None}
55
55
 
@@ -61,15 +61,27 @@ def is_agent(provider) -> bool:
61
61
  KEY_NAMES = sorted({provider.key_env for provider in PROVIDERS.values() if provider.key_env})
62
62
 
63
63
 
64
+ def requires_key(identifier: str) -> bool:
65
+ """Whether this provider requires credentials; Custom can use an unauthenticated endpoint."""
66
+ return identifier in PROVIDERS and identifier != "custom" and bool(PROVIDERS[identifier].key_env)
67
+
68
+
64
69
  def load(directory: Path) -> dict:
65
70
  """The model the user chose ({provider, model, base_url}: [model] of config.toml,
66
71
  settings.py), or the default."""
67
72
  from . import settings as config
68
73
 
69
74
  data = config.read(directory).get("model") or {}
70
- if data.get("provider") not in PROVIDERS:
75
+ if isinstance(data, dict) and "provider" not in data:
71
76
  return dict(DEFAULT)
72
- return {"provider": data["provider"], "model": data.get("model") or "", "base_url": data.get("base_url")}
77
+ from .model_list import SelectionError
78
+
79
+ if not isinstance(data, dict):
80
+ raise SelectionError(f"{config.path(directory)}: model must be a table")
81
+ try:
82
+ return check(data)
83
+ except ValueError as error:
84
+ raise SelectionError(f"{config.path(directory)}: model: {error}") from None
73
85
 
74
86
 
75
87
  def save(directory: Path, settings: dict) -> None:
@@ -104,9 +116,13 @@ def check(settings: dict) -> dict:
104
116
 
105
117
  def models_url(settings: dict) -> str:
106
118
  provider = PROVIDERS[settings["provider"]]
119
+ base = settings.get("base_url") or provider.base_url
107
120
  if provider.backend == "openrouter":
108
- return "https://openrouter.ai/api/v1/key"
109
- return (settings.get("base_url") or provider.base_url).rstrip("/") + "/models"
121
+ base = base or "https://openrouter.ai/api/v1"
122
+ if not base:
123
+ raise ValueError("give the base URL of the endpoint")
124
+ base = base.rstrip("/").removesuffix("/chat/completions")
125
+ return base + ("/key" if provider.backend == "openrouter" else "/models")
110
126
 
111
127
 
112
128
  def reach(settings: dict, key: str | None, timeout: float = 20.0) -> dict:
@@ -139,9 +155,9 @@ def catalog(directory: Path, identifier: str) -> list[dict]:
139
155
  chosen = load(directory)
140
156
  base = (chosen.get("base_url") if chosen["provider"] == identifier else None) or provider.base_url
141
157
  if provider.backend == "openrouter":
142
- url = "https://openrouter.ai/api/v1/models"
158
+ url = (base or "https://openrouter.ai/api/v1").rstrip("/").removesuffix("/chat/completions") + "/models"
143
159
  elif base:
144
- url = base.rstrip("/") + "/models"
160
+ url = base.rstrip("/").removesuffix("/chat/completions") + "/models"
145
161
  else:
146
162
  raise ValueError("configure the endpoint before looking up models")
147
163
  key = os.environ.get(provider.key_env) if provider.key_env else None
@@ -209,6 +225,8 @@ def model_role(settings: dict, advanced: dict | None = None) -> dict:
209
225
  # Streamed, as configs/models' OpenRouter files are: chunks keep coming while the
210
226
  # model thinks, so a dropped connection shows within the read timeout.
211
227
  role.update(backend="openrouter", stream=True)
228
+ if settings.get("base_url"):
229
+ role["base_url"] = settings["base_url"]
212
230
  else:
213
231
  role.update(backend="openai_chat", base_url=settings.get("base_url") or provider.base_url)
214
232
  if provider.key_env:
@@ -245,18 +263,31 @@ def described() -> list[dict]:
245
263
 
246
264
 
247
265
  def ready(directory: Path) -> dict:
248
- """Whether a model is chosen and its key is there (the environment, [keys] of
249
- config.toml): {ready, provider, model, key_env}."""
250
- from .settings import Credentials, read
266
+ """Whether the actual enabled default model is ready, with its missing requirement.
267
+ Credentials come from the environment before [keys] of config.toml."""
268
+ from .model_list import SelectionError, select
269
+ from .settings import Credentials
251
270
 
252
- chosen = load(directory)
253
- provider = PROVIDERS[chosen["provider"]]
254
- if provider.key_env:
255
- Credentials(directory, [provider.key_env]).load()
256
- configured = bool((read(directory).get("model") or {}).get("provider"))
257
- has_key = not provider.key_env or bool(os.environ.get(provider.key_env))
258
- return {"ready": has_key and (configured or provider.id == DEFAULT["provider"]), "provider": provider.id,
259
- "model": chosen["model"], "key_env": provider.key_env}
271
+ try:
272
+ selected = select(directory)
273
+ chosen = selected or load(directory)
274
+ except SelectionError as error:
275
+ return {"ready": False, "provider": None, "model": None, "key_env": None,
276
+ "detail": str(error), "selection_error": True}
277
+ provider = PROVIDERS.get(chosen["provider"])
278
+ key_env = provider.key_env if provider else None
279
+ if key_env:
280
+ Credentials(directory, [key_env]).load()
281
+ has_key = not requires_key(chosen["provider"]) or bool(os.environ.get(key_env))
282
+ detail = None
283
+ if selected is None:
284
+ detail = f"add an enabled model in {directory / 'models.json'}"
285
+ if not (directory / "models.json").exists() and not has_key:
286
+ detail = f"{key_env} is not set"
287
+ elif not has_key:
288
+ detail = f"{key_env} is not set"
289
+ return {"ready": selected is not None and has_key, "provider": chosen["provider"],
290
+ "model": chosen["model"], "key_env": key_env, "detail": detail}
260
291
 
261
292
 
262
293
  def setup(directory: Path, read=input, secret=None, write=print, check_key=True) -> dict:
@@ -285,13 +316,26 @@ def setup(directory: Path, read=input, secret=None, write=print, check_key=True)
285
316
  model = read(f"Model{f' [{suggested}]' if suggested else ''}: ").strip() or suggested
286
317
  base_url = read("Base URL of the endpoint: ").strip() if provider.base_url is None and \
287
318
  provider.backend != "openrouter" else None
288
- key = secret(f"{provider.key_env}: ").strip() if provider.key_env else None
319
+ credentials = None
320
+ existing = None
321
+ if provider.key_env:
322
+ from .settings import Credentials
323
+
324
+ credentials = Credentials(directory, [provider.key_env])
325
+ credentials.load()
326
+ existing = os.environ.get(provider.key_env)
327
+ if existing:
328
+ write(f" {provider.key_env} is available from {credentials.status(provider.key_env)['source']}; "
329
+ "leave the key blank to reuse it")
330
+ supplied = secret(f"{provider.key_env}{' (optional)' if not requires_key(provider.id) else ''}: ").strip() \
331
+ if provider.key_env else None
332
+ key = supplied or existing
289
333
  try:
290
334
  chosen = check({"provider": provider.id, "model": model, "base_url": base_url})
291
335
  except ValueError as error:
292
336
  write(f" {error}")
293
337
  continue
294
- if provider.key_env and not key:
338
+ if requires_key(provider.id) and not key:
295
339
  write(" a key is needed for this provider")
296
340
  continue
297
341
  if check_key:
@@ -300,10 +344,8 @@ def setup(directory: Path, read=input, secret=None, write=print, check_key=True)
300
344
  write(f" {provider.name} did not take it: {result['detail']}")
301
345
  continue
302
346
  save(directory, chosen)
303
- if key:
304
- from .settings import Credentials
305
-
306
- Credentials(directory, [provider.key_env]).save(key, provider.key_env)
347
+ if supplied:
348
+ credentials.save(supplied, provider.key_env)
307
349
  from . import model_list
308
350
 
309
351
  if not any(row["id"] == model_list.entry(chosen)["id"] for row in model_list.models(directory)):
@@ -38,16 +38,27 @@ EMPTY_RETRIES = 2
38
38
  TURN_GRACE_SECONDS = 2.0
39
39
 
40
40
 
41
+ # runtime.tell_budget: whether the model is told, with every call, what the run has left
42
+ # (model calls, environment steps, live time). "never": the limits are the host's to keep
43
+ # and the model is not told them; "always": told with every call (a benchmark whose
44
+ # episodes are a few dozen calls, where the model must plan its end).
45
+ TELL_BUDGET = ("never", "always")
46
+
47
+
41
48
  # runtime.longest_wait_seconds: the longest a <wait> lasts; one that names no time lasts
42
49
  # this long, so no wait is endless.
43
50
  LONGEST_WAIT_SECONDS = 60.0
44
51
 
45
52
 
46
- # What the model is told when its wait ended: why (WAIT_ENDS), and after how long; the units
47
- # that run follow, each with how long it has run and when it last printed (messages.unit_text).
53
+ # What the model is told when its wait ended: why (WAIT_ENDS: the kind of the notice that
54
+ # ended it, runtime/decision/notices.py, or its time), and after how long.
48
55
  WAIT_ENDED = "Wait ended after {seconds:.1f} s: {why}."
49
56
  WAIT_ENDS = {"unit": "a unit you started ended", "message": "a message reached you", "event": "an event reached you",
50
- "time": "its time is over"}
57
+ "note": "the harness told you something", "time": "its time is over"}
58
+
59
+
60
+ # How the model reads an event that reached it; what the event's record holds follows.
61
+ EVENT = "Event {kind} from {source}"
51
62
 
52
63
 
53
64
  # What the model is told, with its next prompt, when its conversation goes on in a new
@@ -103,12 +114,10 @@ def _thinking(main: dict, level: str) -> dict:
103
114
  return main
104
115
 
105
116
 
106
- # Why the model is called (a model_request's reason): a pending message or unresolved event
107
- # (the method that says whether one is pending) comes before what happened last.
108
- TRIGGERS = {"user": "_pending_message", "escalation": "_unresolved",
109
- "start": None, "program_end": None, "program_running": None, "unit_end": None, "wait_end": None,
110
- "error": None,
111
- "rejected": None, "finish_refused": None, "verify": None, "empty": None, "format": None}
117
+ # Why the model is called (a model_request's reason): a message or an event it was told and
118
+ # has not answered ("user", "escalation") comes before what happened last.
119
+ REASONS = ("user", "escalation", "start", "program_end", "program_running", "unit_end", "wait_end", "error",
120
+ "rejected", "finish_refused", "verify", "empty", "format")
112
121
 
113
122
 
114
123
  # The trigger of a role's request: explicit requests share the transport of decisions.
@@ -110,12 +110,12 @@ def ended_text(result: dict) -> str:
110
110
  + f" ({result.get('seconds', 0):.1f} s)")
111
111
 
112
112
 
113
- def cell_feedback(result: dict, number: int, hz: float | None = None, embodiment: str = "robot",
114
- steps: bool = True) -> str:
113
+ def cell_feedback(result: dict, number: int) -> str:
115
114
  """What the model is told of program `number` it ran: its status, output and error, the
116
- event that ended it, the executions, the skills' turn report, the state and the steps.
117
- It names the program, since programs run side by side and the result of one can reach
118
- the model after the code of the next."""
115
+ event that ended it, the executions and the skills' turn report (the state as it is
116
+ now is told once with every call: runtime/task/run.py _ambient). It names the
117
+ program, since programs run side by side and the result of one can reach the model
118
+ after the code of the next."""
119
119
  lines = [f"Program {number} " + ended_text(result)]
120
120
  if result.get("stdout"):
121
121
  lines.append("Output:\n" + result["stdout"].rstrip())
@@ -136,11 +136,6 @@ def cell_feedback(result: dict, number: int, hz: float | None = None, embodiment
136
136
  lines.append("Execution totals (details in trace): " + json.dumps(result["event_counts"]))
137
137
  if (result.get("report") or {}).get("text"):
138
138
  lines.append(result["report"]["text"])
139
- if result.get("state"):
140
- lines.append(f"{EMBODIMENT_TEXT[embodiment]['state_label']}: "
141
- + state_text(result["state"], embodiment, steps))
142
- if steps and result["state"].get("step") is not None:
143
- lines.append(steps_text(result["state"], hz))
144
139
  for name, part in (result.get("environments") or {}).items():
145
140
  # An environment attached to the conversation (runtime/execution/attached.py).
146
141
  if part.get("events"):
@@ -203,7 +203,6 @@ class ChatModel:
203
203
  self._api_key = os.environ.get(key_env) if key_env else None
204
204
  if self.provider == "openrouter" and not self._api_key:
205
205
  raise ValueError(f"Set {key_env} before selecting the openrouter backend")
206
- self._api_key = self._api_key or "EMPTY"
207
206
 
208
207
  def payload(self, system: str, messages: list[dict]) -> dict:
209
208
  """The request body: `system` and the harness messages as chat messages, the output
@@ -260,7 +259,7 @@ class ChatModel:
260
259
 
261
260
  ensure({"on_demand": self.on_demand})
262
261
  payload = self.payload(system, messages)
263
- headers = {"authorization": f"Bearer {self._api_key}"}
262
+ headers = {"authorization": f"Bearer {self._api_key}"} if self._api_key else {}
264
263
  # Explicit OpenRouter backends include relays; compatible clients can also
265
264
  # target OpenRouter directly. Match the hostname, never URL substrings.
266
265
  if self.provider == "openrouter" or urlsplit(self.url).hostname == "openrouter.ai":
@@ -378,9 +377,15 @@ def _provider_errors():
378
377
  yield
379
378
  except HTTPError as error:
380
379
  detail = error.read().decode("utf-8", "replace")[:500]
381
- raise RuntimeError(f"Provider HTTP {error.code}: {detail}") from error
380
+ hint = {
381
+ 401: "Check the selected provider's API key and endpoint, then retry.",
382
+ 403: "Check that your account has access to the selected model and endpoint.",
383
+ 429: "Wait before retrying, or check the provider's rate limit and remaining quota.",
384
+ }.get(error.code, "The provider is temporarily unavailable; retry later." if error.code >= 500 else "")
385
+ raise RuntimeError(f"Provider HTTP {error.code}: {detail}" + (f"\n{hint}" if hint else "")) from error
382
386
  except OSError as error:
383
- raise RuntimeError(f"Provider request failed: {getattr(error, 'reason', error)}") from error
387
+ raise RuntimeError(f"Provider request failed: {getattr(error, 'reason', error)}\n"
388
+ "Check the model endpoint and network connection, then retry.") from error
384
389
 
385
390
 
386
391
  def _read_sse(lines, on_text=None):
@@ -442,19 +447,24 @@ def scripted_models(script) -> dict:
442
447
  "verifier": ScriptedChat(script.get("verifier") or ["YES (scripted verifier)"] * 100)}
443
448
 
444
449
 
445
- # The end of a request that says the model's program still runs and nothing else happened.
450
+ # A request that says the model's program still runs and nothing else happened.
446
451
  _STILL_RUNNING = re.compile(r"Program \d+ is still running")
447
452
  _WAIT_OVER = re.compile(r"^Wait ended after [\d.]+ s: its time is over")
448
453
 
449
454
 
450
455
  def still_running(messages: list[dict]) -> bool:
451
- """Whether the final content part says a program still runs and nothing reached the
452
- model: it was just started, or a wait's time is over while units run (a wait whose time
453
- is over with nothing running is the script's own to answer)."""
456
+ """Whether the last thing the request tells, before how things stand now (its `ambient`
457
+ part), is that a program still runs and nothing reached the model: it was just started,
458
+ or a wait's time is over while units run (a wait whose time is over with nothing
459
+ running is the script's own to answer)."""
454
460
  content = messages[-1].get("content") if messages else None
455
- last = content if isinstance(content, str) else (content[-1].get("text", "") if content else "")
456
- last = last or ""
457
- return bool(_STILL_RUNNING.match(last) or (_WAIT_OVER.match(last) and "\nUnits running:" in last))
461
+ if isinstance(content, str) or not content:
462
+ return bool(_STILL_RUNNING.match(content or ""))
463
+ told = [part for part in content if not part.get("ambient")]
464
+ ambient = "\n".join(part.get("text", "") for part in content if part.get("ambient"))
465
+ last = (told[-1].get("text") or "") if told else ""
466
+ return bool(_STILL_RUNNING.match(last)
467
+ or (_WAIT_OVER.match(last) and re.search(r"^Units running:", ambient, re.M)))
458
468
 
459
469
 
460
470
  class ScriptedChat:
@@ -0,0 +1,66 @@
1
+ """What reaches the model: one queue of notices.
2
+
3
+ Everything that reaches the model by itself is a notice in one queue: a message (of the
4
+ user, of the agent that started this one, of the environment), an event, the end of a
5
+ unit, a note of the host. A notice has a priority, given by what puts it there:
6
+
7
+ now the model's call in flight is set aside and made again with the notice; a
8
+ reply that did not know of it does nothing
9
+ next the call in flight goes on; the notice is told with the model's next call
10
+ later told with the first call made after a wait of the model, or with the call
11
+ that begins its next turn
12
+
13
+ Every notice ends a wait of the model and, between turns, begins one; but one that does
14
+ not wake (the end of a unit that was cancelled) is only told along with the next call.
15
+ Those told with one call come the more urgent first, each priority in order of arrival.
16
+ What a reply of the model itself comes to (its program's handle, the end of its wait, a
17
+ format error) is not a notice: it is the first thing the next call is told
18
+ (runtime/task/run.py _deliver).
19
+ """
20
+
21
+ from dataclasses import dataclass
22
+
23
+ NOW, NEXT, LATER = "now", "next", "later"
24
+ PRIORITIES = (NOW, NEXT, LATER)
25
+
26
+
27
+ @dataclass
28
+ class Notice:
29
+ """`kind`: "message", "event", "unit" or "note"; `data`: what its kind tells (the
30
+ message's sender, text and parts; the event's record; the unit's result; the note's
31
+ text)."""
32
+ kind: str
33
+ priority: str
34
+ data: object
35
+ wakes: bool = True
36
+
37
+
38
+ class Notices:
39
+ """The queue. Not locked: whoever owns it holds its lock."""
40
+
41
+ def __init__(self):
42
+ self._items = []
43
+
44
+ def put(self, notice: Notice) -> None:
45
+ if notice.priority not in PRIORITIES:
46
+ raise ValueError(f"a notice's priority is one of {PRIORITIES}, got {notice.priority!r}")
47
+ self._items.append(notice)
48
+
49
+ def _found(self, upto, kinds, waking):
50
+ level = PRIORITIES.index(upto)
51
+ return [notice for notice in self._items
52
+ if PRIORITIES.index(notice.priority) <= level and (kinds is None or notice.kind in kinds)
53
+ and (not waking or notice.wakes)]
54
+
55
+ def pending(self, upto: str = LATER, kinds=None, waking: bool = False) -> list:
56
+ """The notices of priority `upto` or more urgent (of `kinds`; `waking`: those that
57
+ wake), in the order they are told."""
58
+ found = self._found(upto, kinds, waking)
59
+ return sorted(found, key=lambda notice: PRIORITIES.index(notice.priority))
60
+
61
+ def take(self, upto: str = LATER, kinds=None) -> list:
62
+ """Remove and return them."""
63
+ found = self.pending(upto, kinds)
64
+ taken = {id(notice) for notice in found}
65
+ self._items = [notice for notice in self._items if id(notice) not in taken]
66
+ return found