@lmmslab/harness 0.83.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 (32) hide show
  1. package/bin/harness.js +6 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +1 -1
  4. package/python/harness/builtin/prompts/core/core.md +45 -30
  5. package/python/harness/builtin/prompts/shared/learning-goal.md +1 -1
  6. package/python/harness/cli.py +103 -17
  7. package/python/harness/core/trace.py +23 -3
  8. package/python/harness/core/worker.py +6 -0
  9. package/python/harness/host/client.py +26 -21
  10. package/python/harness/host/http.py +11 -1
  11. package/python/harness/host/sessions.py +38 -3
  12. package/python/harness/host/tasks.py +62 -26
  13. package/python/harness/model_list.py +25 -5
  14. package/python/harness/packages/environments.py +51 -12
  15. package/python/harness/packages/manager.py +379 -102
  16. package/python/harness/packages/resolve.py +52 -15
  17. package/python/harness/packages/sources.py +17 -5
  18. package/python/harness/packages/state.py +10 -0
  19. package/python/harness/providers.py +66 -24
  20. package/python/harness/runtime/decision/model.py +9 -4
  21. package/python/harness/runtime/execution/entries.py +53 -7
  22. package/python/harness/runtime/execution/session.py +52 -7
  23. package/python/harness/runtime/learning/active.py +4 -4
  24. package/python/harness/runtime/reactive/tree.py +35 -22
  25. package/python/harness/runtime/task/run.py +25 -3
  26. package/python/harness/runtime/tick.py +34 -3
  27. package/python/harness/settings.py +5 -1
  28. package/python/harness/tui/__init__.py +28 -6
  29. package/python/harness/tui/chat.py +243 -67
  30. package/python/harness/tui/pty.py +16 -0
  31. package/python/harness/tui/renderer.py +34 -0
  32. 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)):
@@ -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):
@@ -59,6 +59,31 @@ def _short(value, limit=200) -> str:
59
59
  return text if len(text) <= limit else text[:limit] + "..."
60
60
 
61
61
 
62
+ class _Priority:
63
+ """What `at_priority(n)` gives: a block in which the unit holds the embodiment with n.
64
+ Outside a `with` it does nothing, and says so where the program's output is read."""
65
+
66
+ def __init__(self, tree, entry, priority):
67
+ self.tree, self.entry, self.priority, self.before, self.used = tree, entry, priority, None, False
68
+
69
+ def __enter__(self):
70
+ self.used, self.before = True, self.entry.priority
71
+ self.tree._held_with(self.entry, self.priority)
72
+ return self
73
+
74
+ def __exit__(self, *raised):
75
+ self.tree._held_with(self.entry, self.before)
76
+ return False
77
+
78
+ def __del__(self):
79
+ if not self.used:
80
+ try:
81
+ print(f"at_priority({self.priority:g}) did nothing: it holds the environment for the block of "
82
+ f"`with at_priority({self.priority:g}):` only.")
83
+ except Exception:
84
+ pass
85
+
86
+
62
87
  class Entry:
63
88
  """One unit of a session (see the module docstring): its `id`, `name`, `kind` ("root"
64
89
  for the model, "program" for code, "agent" for a sub-agent), the model it belongs to
@@ -83,6 +108,9 @@ class Entry:
83
108
  self.cell = None
84
109
  self.rule = None
85
110
  self.priority = 0
111
+ # The priority the code it runs in the environment asks for now (the environment
112
+ # reports it with its state: core/worker.py), None when it asks for none.
113
+ self.asked = None
86
114
  self.restart = False
87
115
  # What it is for: a condition of the view that holds when its work is done (None: it
88
116
  # states none), and whether it held when the unit ended (None: no condition).
@@ -115,6 +143,12 @@ class Entry:
115
143
  """Whether it has not ended yet."""
116
144
  return self.status == "running"
117
145
 
146
+ @property
147
+ def rank(self) -> float:
148
+ """What it holds the environment with now: its priority, or the one the code it
149
+ runs in the environment asks for, whichever is higher."""
150
+ return max(self.priority or 0, self.asked or 0)
151
+
118
152
  def lineage(self) -> list:
119
153
  """This entry and the entries above it, up to the root."""
120
154
  chain, entry = [], self
@@ -363,20 +397,32 @@ class Tree:
363
397
  raise RuntimeError("until() is called by a program: it says what that program is for")
364
398
  entry.until = condition
365
399
 
366
- def at_priority(self, priority) -> None:
367
- """The unit this code runs in holds the embodiment with `priority` from now until it
368
- ends, between its executions too (runtime/tick.py hold). A unit of higher priority
400
+ def at_priority(self, priority) -> "_Priority":
401
+ """`with at_priority(priority):` the unit this code runs in holds the embodiment
402
+ with `priority` for the block, between its executions too (runtime/tick.py hold),
403
+ and with what it held it before from the block's end on. A unit of higher priority
369
404
  still takes it (a reflex whose place is `priority` or above); one of lower priority
370
- waits. Its own ends stay: it is cancelled, its calls reach their time, a reflex that
371
- ends what runs holds, the episode ends."""
405
+ waits, and is judged again when the block ends. Its own ends stay: it is cancelled,
406
+ its calls reach their time, a reflex that ends what runs holds, the episode ends."""
372
407
  entry = self.current()
373
408
  if entry is self.root:
374
- raise RuntimeError("at_priority() is called by a program: it says with what this program holds the environment")
409
+ raise RuntimeError("at_priority() is used by a program: it says with what the program holds the "
410
+ "environment for an action")
375
411
  if isinstance(priority, bool) or not isinstance(priority, (int, float)) or not priority >= 0:
376
412
  raise ValueError(f"at_priority(priority): a number, 0 or more, got {priority!r}")
413
+ return _Priority(self, entry, priority)
414
+
415
+ def _held_with(self, entry, priority) -> None:
416
+ """`entry` holds the embodiment with `priority` from now: the tick and the tree hear
417
+ of it (a reflex that waited below it is judged again)."""
377
418
  entry.priority = priority
378
419
  spans.note("priority", unit=entry.id, priority=priority)
379
- self.session._ticker.hold(entry)
420
+ ticker = self.session._ticker
421
+ ticker.hold(entry)
422
+ layer = getattr(self.session, "reactive", None)
423
+ if layer is not None:
424
+ layer.changed = True
425
+ ticker.judge()
380
426
 
381
427
  def claim(self, names) -> bool:
382
428
  """The caller's entry claims the channels `names` (see the module docstring): True;
@@ -172,6 +172,7 @@ class EpisodeCore:
172
172
  @state.setter
173
173
  def state(self, value):
174
174
  self.__dict__["_state"] = value
175
+ self._note_changes(value)
175
176
  # The host keeps the state as it was last reported (the `state` note, at most every
176
177
  # STATE_NOTE_SECONDS): what the model is told with every call (runtime/task/run.py _ambient).
177
178
  now = time.monotonic()
@@ -187,14 +188,57 @@ class EpisodeCore:
187
188
 
188
189
  def _view(self, state, tick):
189
190
  """What rules, controllers and until predicates observe: the embodiment's view
190
- (_reactive_view) with the run's facts as "facts"."""
191
+ (_reactive_view) with the run's facts as "facts", and what a state alone does not
192
+ show: what each thing it reports was before it last changed ("was") and for how
193
+ many seconds it has not changed ("unchanged"), the senses under "sensed" in both;
194
+ and the units that run ("units": each {"name", "kind", "reflex", "priority",
195
+ "seconds"})."""
191
196
  view = self._reactive_view(state, tick)
192
197
  if isinstance(view, dict):
193
198
  view.setdefault("facts", self.facts.view())
194
199
  if isinstance(state, dict) and "sensed" in state:
195
200
  view.setdefault("sensed", state["sensed"])
201
+ was, unchanged, now = {"sensed": {}}, {"sensed": {}}, time.monotonic()
202
+ for key, (_, since, before) in list(self.__dict__.get("_changes", {}).items()):
203
+ if isinstance(key, tuple):
204
+ was["sensed"][key[1]], unchanged["sensed"][key[1]] = before, now - since
205
+ else:
206
+ was[key], unchanged[key] = before, now - since
207
+ view.setdefault("was", was)
208
+ view.setdefault("unchanged", unchanged)
209
+ tree, wall = self.__dict__.get("_entry_tree"), time.time()
210
+ view.setdefault("units", [
211
+ {"name": unit.name, "kind": unit.kind, "reflex": unit.rule, "priority": unit.rank,
212
+ "seconds": wall - unit.started} for unit in (tree.running() if tree is not None else ())])
196
213
  return view
197
214
 
215
+ def _note_changes(self, state) -> None:
216
+ """Keep, for each thing the state reports (and each sense), its value, when it last
217
+ changed and what it was before: what a condition needs to see that something
218
+ changes, or that it does not."""
219
+ if not isinstance(state, dict):
220
+ return
221
+ seen, now = self.__dict__.setdefault("_changes", {}), time.monotonic()
222
+
223
+ def note(key, value):
224
+ kept = seen.get(key)
225
+ if kept is None:
226
+ seen[key] = (value, now, None)
227
+ return
228
+ try:
229
+ same = bool(kept[0] == value)
230
+ except Exception:
231
+ same = False
232
+ if not same:
233
+ seen[key] = (value, now, kept[0])
234
+
235
+ for key, value in state.items():
236
+ if key == "sensed" and isinstance(value, dict):
237
+ for name, sensed in value.items():
238
+ note(("sensed", name), sensed)
239
+ else:
240
+ note(key, value)
241
+
198
242
  # Senses: values the environment computes itself, in its own language, each time it
199
243
  # reports its state (a worker whose profile says "senses": core/worker.py). What a
200
244
  # condition cannot read from the reported state and may not ask for (it makes no
@@ -733,13 +777,14 @@ class EpisodeCore:
733
777
  self._observe()
734
778
 
735
779
  def at_priority(self, priority):
736
- """This program holds the environment with `priority` from here until it ends. A
780
+ """`with at_priority(priority):` the program holds the environment with `priority`
781
+ for the block: for one action that must not be broken off, not for a stage. A
737
782
  reflex whose place is `priority` or above takes it from the program as before. One
738
- below does not act while the program runs: it is judged again when the program has
739
- ended and acts if its condition still holds, and the model is told once that it was
740
- held back. What still ends the program: cancelling it, the time of its calls, a
741
- reflex that ends what runs, the end of the episode."""
742
- self._entries.at_priority(priority)
783
+ below does not act during the block: it is judged again when the block ends and
784
+ acts if its condition still holds, and the model is told once that it was held
785
+ back. What still ends the program: cancelling it, the time of its calls, a reflex
786
+ that ends what runs, the end of the episode."""
787
+ return self._entries.at_priority(priority)
743
788
 
744
789
  def run_controller(self, fn, until=None, max_seconds=None):
745
790
  """Run `fn(view)` for each step, until it returns None or a stopping condition holds."""
@@ -96,17 +96,17 @@ def body(skills=()) -> dict:
96
96
  return dict(GENERIC)
97
97
 
98
98
 
99
- def goal(instruction: str, minutes: float, skills=(), sandbox: dict | None = None, *, legacy_memory=False) -> str:
99
+ def goal(instruction: str, skills=(), sandbox: dict | None = None, *, legacy_memory=False) -> str:
100
100
  """The active run's instruction: learn the environment for the task `instruction`, the
101
101
  lines of the prompt for the run's `skills` kept, its body's lines (body()) in it, and,
102
- when the environment offers one, its practice sandbox (sandbox_lines())."""
102
+ when the environment offers one, its practice sandbox (sandbox_lines()). How long the
103
+ run is, it does not say: the host keeps that limit (runtime.tell_budget)."""
103
104
  from harness.runtime.decision.prompts import select
104
105
 
105
106
  features = (*skills, "legacy_memory") if legacy_memory else skills
106
107
  text = select(PROMPT.read_text(encoding="utf-8"), features).strip()
107
108
  lines = body(skills)
108
- text = text.format(task=instruction.strip(), minutes=f"{minutes:g}", probe=lines["try"],
109
- sandbox=sandbox_lines(sandbox))
109
+ text = text.format(task=instruction.strip(), probe=lines["try"], sandbox=sandbox_lines(sandbox))
110
110
  # A placeholder with nothing to say leaves no line.
111
111
  return "\n".join(line for line in text.split("\n") if line.strip() or not line).rstrip()
112
112