@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
package/README.md CHANGED
@@ -13,8 +13,8 @@
13
13
  </p>
14
14
 
15
15
  <p align="center">
16
- <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm version" src="https://img.shields.io/npm/v/@lmmslab/harness?style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
17
- <a href="https://pypi.org/project/the-harness/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/the-harness?style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
16
+ <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm version" src="https://img.shields.io/npm/v/@lmmslab/harness?cacheSeconds=3600&amp;style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
17
+ <a href="https://pypi.org/project/the-harness/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/the-harness?cacheSeconds=3600&amp;style=flat-square&amp;labelColor=112332&amp;color=087f9c" /></a>
18
18
  <a href="https://discord.gg/zhkzEznBs"><img alt="Discord community" src="https://img.shields.io/badge/discord-community-bc276e?style=flat-square&amp;logo=discord&amp;logoColor=white&amp;labelColor=112332" /></a>
19
19
  </p>
20
20
 
package/bin/harness.js CHANGED
@@ -66,6 +66,11 @@ child.on("error", (error) => {
66
66
  process.exit(1);
67
67
  });
68
68
  child.on("exit", (code, signal) => {
69
- if (signal) process.kill(process.pid, signal);
69
+ if (signal) {
70
+ // Restore the default disposition before replaying the child's signal. Otherwise
71
+ // our forwarding handler catches it again and Node exits with a success status.
72
+ process.removeAllListeners(signal);
73
+ process.kill(process.pid, signal);
74
+ }
70
75
  else process.exit(code === null ? 1 : code);
71
76
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lmmslab/harness",
3
- "version": "0.82.0",
3
+ "version": "0.84.0",
4
4
  "description": "Automatic Control for intelligence in action",
5
5
  "license": "MIT",
6
6
  "homepage": "https://harness.lmms-lab.com",
@@ -2,7 +2,7 @@
2
2
 
3
3
  # The one version: the core's. A lock records it with the versions of the packages that
4
4
  # ran and the hash of the whole lock (the agent's identity, config/agent.py).
5
- __version__ = "0.82.0"
5
+ __version__ = "0.84.0"
6
6
 
7
7
  # A checkout's packages import beside the harness (paths.py).
8
8
  from . import paths as _paths # noqa: E402,F401
@@ -11,14 +11,14 @@ time with exactly one of:
11
11
  next message starts your next turn, and you keep what you have.
12
12
 
13
13
  <!-- if: look -->
14
- When a program ends you see its output, what went wrong if anything did and the state, as
15
- text. A picture reaches you only when a program looks (look and watch below); read what
14
+ When a program ends you see its output and what went wrong if anything did, as text.
15
+ A picture reaches you only when a program looks (look and watch below); read what
16
16
  the state and the environment's calls give as text first, and look when that does not
17
17
  tell, while a program runs as much as after it. Write one program for a coherent phase
18
18
  with a clear completion condition.
19
19
  <!-- else -->
20
- When a program ends you see its output, what went wrong if anything did, the state and
21
- new pictures. Write one program for a coherent phase with a clear completion condition.
20
+ When a program ends you see its output, what went wrong if anything did and new
21
+ pictures. Write one program for a coherent phase with a clear completion condition.
22
22
  <!-- end -->
23
23
  Let it observe, act, wait for a condition, and check the result as it goes. Handle
24
24
  expected outcomes and bound any waits or retries. End the program when the phase is
@@ -40,18 +40,33 @@ is not that. Say what the task needs as things that must be true, not as a seque
40
40
  what is already true needs no step, and the order follows from what is there.
41
41
 
42
42
  The tree is designed as a whole, not grown from what went wrong last. Before you rely on
43
- it, name every kind of thing that can happen to the agent where it is going to be: to its
44
- condition, to where it stands, from what is around it, to what it is doing. Give each
45
- kind a node. A kind you do not yet know how to answer still gets its node: one that tells
46
- you. What you set out to do is not among them, however often you do it: a way of doing
47
- something that you have learned is kept as a skill you call, not as a node. A node has
48
- done its work when its situation is over: when its program ends and the situation is not
49
- over, a later node at its place has the environment, or you are told what the program
50
- did. The tree is consistent when in every situation it is settled which node has the
51
- environment: a node's place is what it costs when it does not act now, the costlier the
52
- earlier; and a node takes the environment only where you would, seeing everything as it
53
- is then. A reflex acts in your place, so its condition is your whole judgement, what it
54
- interrupts and whether this is the moment included, and what it does leaves things so
43
+ it, name every kind of thing that can happen to the agent where it is going to be: to
44
+ its condition, to where it stands, from what is around it, to what it is doing. The tree
45
+ divides all of that. A node is a situation: its condition says when the agent is in it.
46
+ The nodes under it divide the situation further, wherever a narrower one needs an answer
47
+ of its own, and the last of them answers what is in the situation and in none of the
48
+ others: with what fits the whole situation, or, where nothing does, by telling you. This
49
+ holds at every depth, and how far a situation is divided follows from how much you know
50
+ of it. So what you have never met is still answered, by the narrowest situation it falls
51
+ in; and when you come to know it, you divide there, where its place among everything
52
+ else is already settled. The unexpected has two forms, and the tree tells you of both.
53
+ Something happens that no node answers. Or what should happen does not: the agent goes
54
+ on acting and what the action is for does not come; the thing it should change stays as
55
+ it was while time and supplies go. The second is as much a situation of the agent as the
56
+ first, and it is the one that passes unnoticed, because nothing arrives. So for whatever
57
+ is set going, a node watches what it is for, and tells you when that stays away longer
58
+ than it would if things were as you assumed. Neither form may pass with no answer and
59
+ without your hearing of it. What happens to the agent whatever it is doing belongs in
60
+ the tree, also when you met it inside one program: answered there, it is answered
61
+ nowhere else. What you set out to do is not in it, however often you do it: a way of
62
+ doing something that you have learned is kept as a skill you call, not as a node. A node
63
+ has done its work when its situation is over: when its program ends and the situation is
64
+ not over, a later node at its place has the environment, or you are told what the
65
+ program did. The tree is consistent when in every situation it is settled which node has
66
+ the environment: a node's place is what it costs when it does not act now, the costlier
67
+ the earlier; and a node takes the environment only where you would, seeing everything as
68
+ it is then. A reflex acts in your place, so its condition is your whole judgement, what
69
+ it interrupts and whether this is the moment included, and what it does leaves things so
55
70
  that what it interrupted can go on.
56
71
 
57
72
  Build each thing for the situations it has to work in, and think and test in proportion
@@ -71,6 +86,14 @@ or when its time is over, and you are told which. What a program starts (units,
71
86
  is yours: it outlives the program and the turn. After your answer it goes on,
72
87
  and the end of a unit or an event starts your next turn; cancel what should not go on.
73
88
 
89
+ Whatever you are asked for, you are told in the same order: what your last reply came
90
+ to; then what reached you by itself since (the end of a unit, an event, a message), the
91
+ more urgent first; last, how things stand now: the state, the units that run, what
92
+ changed in the tree of reflexes. What cannot wait (an event, what the environment tells,
93
+ a unit that ended with an error) reaches you at once: a reply you were writing then is
94
+ set aside, what it held does not run, and you are asked again. The rest is told when you
95
+ are next asked.
96
+
74
97
  Every unit ends with the same report, whoever started it: how it ended (by itself, an
75
98
  error, an event, cancelled, its time limit), whether what it was for is the case (done:
76
99
  yes or no), and what it returned. How it ended and whether it is done are two things: a
@@ -141,12 +164,14 @@ condition as the node above them or as a sense, an action as a function they cal
141
164
  do: a program (a function): started as a unit when the node's turn comes; what it is
142
165
  for is that the node's condition no longer holds. It begins again while the turn lasts,
143
166
  not before again_seconds after it ended; a program that answers an event gets the event
144
- when it takes an argument. Or the name of an event: you are
145
- told it, once each time the condition comes to hold. Or "stop": what runs is ended.
167
+ when it takes an argument. Or the name of an event: you are told it, once each time
168
+ its turn comes, which is when its condition holds and no node before it at its place
169
+ is answering. Or "stop": what runs is ended.
146
170
  Or nothing: the node is a group, and the nodes set with under=name are its content.
147
- priority (a whole number, 0 or more): the node's place among those where it is, the
148
- higher first, among equals the older. A node's program takes the environment from your
149
- programs.
171
+ priority (a whole number, 0 or more): the node's own, wherever it is in the tree. Of
172
+ two nodes whose turn it is the higher has the environment, among equals the earlier in
173
+ the tree; and it is the number a program's at_priority(n) is compared with. A node's
174
+ program takes the environment from your programs.
150
175
  every: the seconds between judgements of its condition; without it the condition is
151
176
  judged when the state or the facts change.
152
177
  A condition is read, not computed: the conditions judged in one moment share a few
@@ -191,16 +216,22 @@ has its call started again by itself then (its result counts it: .restarts).
191
216
  <!-- end -->
192
217
  What you start meanwhile waits for the higher unit to end. Units of equal priority take
193
218
  turns.
194
- Your programs have priority 0, so every reflex takes the environment from them. A
195
- program has its place among the reflexes like a node: at_priority(n) gives it one, from
196
- that call to its end. A reflex at the top of the tree with priority n or more, and what is
197
- under it, still takes the environment from the program, which goes on as said above. A
198
- reflex below n waits: it is judged again when the program has ended, and you are told
199
- once that it was held back (the event HELD_BACK); cancelling the program lets it act. So a
200
- program that does itself what some reflexes answer stands above those and below the rest:
201
- what happens to the agent and is not the program's business still has its reflex.
219
+ Your programs have priority 0, so every reflex takes the environment from them. An
220
+ action of a program that must not be broken off takes a place among the reflexes for as
221
+ long as it lasts: `with at_priority(n):` around that action, and no longer. During the
222
+ block a reflex whose own priority is n or more still takes the environment from the
223
+ program, which goes on as said above; a reflex below n waits: it is judged again when the
224
+ block ends, and you are told once that it was held back (the event HELD_BACK). The place is the action's, not the program's or a stage's:
225
+ while it is held, nothing below it answers what happens to the agent, so a program that
226
+ holds one for its whole length has taken the tree's work on itself and must do all of it.
227
+ Code that runs for long in the environment itself asks for a place the same way, where
228
+ the environment's page says how.
202
229
  Conditions and controllers read the supplied view. Keep them fast and free of file,
203
- network, process and input operations.
230
+ network, process and input operations. Beside the state as it is, the view holds what a
231
+ state alone does not show: view["was"][key], what that part of the state was before it
232
+ last changed; view["unchanged"][key], for how many seconds it has not changed (the senses
233
+ under ["sensed"] in both); and view["units"], the units that run, each {"name", "kind",
234
+ "reflex", "priority", "seconds"}.
204
235
  <!-- if: memory -->
205
236
  <!-- if: legacy_memory -->
206
237
  - recall(query): what earlier runs kept about a situation like this one.
@@ -1,15 +1,6 @@
1
1
  <!-- if: robot -->
2
2
  You improve a robot-control harness between episodes. A coding agent controls a dual-arm robot by writing Python against a skill API.
3
3
  <!-- end -->
4
- <!-- if: game -->
5
- You improve a game-playing harness between episodes.
6
- <!-- if: minecraft -->
7
- A coding agent plays Minecraft Java 1.16.1 Any% speedruns on random seeds (every seed is a new world) from the pixels of its window with the keyboard and mouse, by writing Python against a skill API: closed-loop actions fed back by F3 and the HUD (get, act, craft, go_to, and for the later phases make_obsidian, build_portal_frame, barter, fight, throw_eye ...), entries that run at the same time on their own channels, and guards on the tick that read view['hud'] and view['see'].
8
- It practices the run in segments (wood and stone tools, iron, the portal, the bastion's pearls, the fortress's rods, the way back, the eyes, the portal room, the dragon), each scored by whether it finished in its time limit, its time and its deaths.
9
- <!-- else -->
10
- A coding agent plays a game from the pixels of its window with the keyboard and mouse, by writing Python against a skill API; guards on the tick read what the worker reads off the HUD and the picture.
11
- <!-- end -->
12
- <!-- end -->
13
4
  <!-- if: desktop -->
14
5
  You improve a computer-use harness between episodes. A coding agent operates a computer's apps from screenshots with the keyboard and mouse, by writing Python against a skill API.
15
6
  <!-- end -->
@@ -21,16 +12,16 @@ You read observed task results and the current library of notes and helper funct
21
12
  <!-- if: robot -->
22
13
  a short note (a general lesson, not about this layout's coordinates),
23
14
  <!-- else -->
24
- a short note (a general lesson, not about this world's or this screen's coordinates: every seed is a new one),
15
+ a short note (a general lesson, not about what holds in this one run only),
25
16
  <!-- end -->
26
17
  a memory entry (a specific situation and what worked or failed, which the agent can look up with recall(query)), a helper skill (a Python function using the API names the agent uses), or
27
18
  <!-- if: robot -->
28
19
  a reactive helper (a pure, fast predicate or controller of obs).
29
20
  <!-- else -->
30
- a reactive helper (a pure, fast guard predicate of the view, such as view['hud'] and view['see']).
21
+ a reactive helper (a pure, fast guard predicate of the view).
31
22
  <!-- end -->
32
23
  <!-- if: experience -->
33
- Do not propose tallies of how often a skill worked or where something was found (a recipe's place in the recipe book): practice counts those by itself in the library's experience, which skills read as hints.
24
+ Do not propose tallies of how often a skill worked or where something was found: practice counts those by itself in the library's experience, which skills read as hints.
34
25
  <!-- end -->
35
26
  Reply with exactly one of <note name="snake_case">...</note>, <memory name="snake_case">...</memory>, <skill name="snake_case">...</skill>, <reactive name="snake_case">...</reactive>, or <none/>.
36
27
  <!-- if: robot -->
@@ -1,7 +1,8 @@
1
1
  # The reflection request (runtime/learning/reflect.py: between episodes, the model proposes one
2
2
  # library entry), one paragraph: the section's lines are joined with spaces once the
3
- # markers are applied. Markers name the embodiment kind (robot, game, desktop), the
4
- # bench (minecraft, robodojo, ...) and the skills the run enabled.
3
+ # markers are applied. Markers name the embodiment kind (robot, desktop), the bench and
4
+ # the skills the run enabled. What belongs to one environment is not said here: its
5
+ # package says it.
5
6
  sections = [
6
7
  { file = "core.md" },
7
8
  ]
@@ -1,6 +1,6 @@
1
1
  This run is practice for a task, not the task itself: {task}
2
2
 
3
- You have {minutes} minutes of live time; what your library holds and what the environment keeps for you when it is over is what the runs that do the task start with.
3
+ What your library holds and what the environment keeps for you when this run is over is what the runs that do the task start with.
4
4
 
5
5
  Something is learned when it has done its work without help, more than once, starting from what the parts before it really leave. Where the environment lets you set that starting situation up directly, do so instead of working your way to it each time. What was practised from a better start than the task gives it has shown nothing yet.
6
6
  {probe}
@@ -266,7 +266,7 @@ def _continue_arguments(command, name: str):
266
266
  """The flags that go on with an earlier session in its own id instead of starting one."""
267
267
  which = command.add_mutually_exclusive_group()
268
268
  which.add_argument("--continue", dest="continue_last", action="store_true",
269
- help="go on with the most recent session: its messages and facts, in the same session id")
269
+ help="go on with the session you last messaged or resumed, in the same session id")
270
270
  which.add_argument(name, dest="session", metavar="SESSION",
271
271
  help="go on with that session (its id, as harness sessions ls --all lists it)")
272
272
 
@@ -286,13 +286,26 @@ def _continued(args):
286
286
  return host, conversation, max((int(record.get("seq", -1)) for record in records), default=-1)
287
287
 
288
288
 
289
+ def _check_continuation_options(args):
290
+ """A continuation uses its saved settings; reject new-task options before any host call."""
291
+ if not (getattr(args, "continue_last", False) or getattr(args, "session", None)):
292
+ return
293
+ selection = any(getattr(args, key, None) is not None for key in ("model", "effort", "workspace", "vm_image", "library"))
294
+ if selection or _coding(args) or _run_options(args) or getattr(args, "learn_while_working", False):
295
+ raise UsageError("continuation keeps the saved model, workspace and run settings; "
296
+ "omit --model/--effort and other new-conversation options with --continue/--resume/--session. "
297
+ "In an open terminal, /effort LEVEL changes that conversation; /model selects only new ones")
298
+
299
+
289
300
  def parser(packages: bool = True):
290
- root = argparse.ArgumentParser(prog="harness", description="Automatic Control for anything that acts.",
301
+ root = argparse.ArgumentParser(prog="harness", description="Automatic Control for intelligence in action.",
291
302
  epilog="harness with no command: the terminal chat with the agent on this computer "
292
303
  "(/help lists its commands: sessions, the session host, settings, model, "
293
304
  "packages, library)")
294
305
  root.add_argument("--version", action="version", version=f"harness {__version__}")
295
306
  _continue_arguments(root, "--resume")
307
+ root.add_argument("--model", help="an enabled model from ~/.harness/models.json (ID or provider/model)")
308
+ root.add_argument("--effort", help="the selected model's reasoning effort ID")
296
309
  run_flags(root)
297
310
  _coding_arguments(root)
298
311
  root.add_argument("--managed-workspace", action="store_true", help="use an isolated managed workspace (supported Linux hosts)")
@@ -322,7 +335,7 @@ def parser(packages: bool = True):
322
335
  _session_commands(commands.add_parser("sessions", help="Manage the session host's coding sessions"))
323
336
  install = commands.add_parser("install", help="Install packages (and what they depend on), or update them; and "
324
337
  "the services and benches they provide",
325
- epilog="harness install browser; harness install computer@^0.5; harness install "
338
+ epilog="harness install browser; harness install computer@^0.8; harness install "
326
339
  "git:github.com/x/y@main#packages/z; harness install ./my-package --link; "
327
340
  "harness install --update (all); harness install sam3 (a service). With no "
328
341
  "names in a folder with harness.toml: the project's packages, from its "
@@ -336,6 +349,8 @@ def parser(packages: bool = True):
336
349
  "without asking (they run code on this computer)")
337
350
  install.add_argument("--link", action="store_true", help="a folder: use it where it is instead of a copy (a "
338
351
  "package under development)")
352
+ install.add_argument("--tui", action="store_true", help="prepare the terminal interface's pinned libraries, "
353
+ "without starting a conversation")
339
354
  install.add_argument("--deploy", help="services: the deploy that places them (default $HARNESS_DEPLOY)")
340
355
  listed = commands.add_parser("list", help="The installed packages; --available: the registry's (QUERY "
341
356
  "searches them); one package by its name: what it provides")
@@ -439,10 +454,14 @@ def _core_report() -> dict:
439
454
  problems, notes = [], []
440
455
  if sys.version_info < (3, 11):
441
456
  problems.append(f"Python {sys.version.split()[0]}: 3.11 or newer is needed")
442
- model = providers.ready(data())
443
- if not model["ready"]:
444
- problems.append(f"no model set up ({model['provider']}: {model['key_env']} is not set): run harness once "
445
- "in a terminal, or export the key")
457
+ try:
458
+ model = providers.ready(data())
459
+ if not model["ready"]:
460
+ problems.append(model["detail"] if model.get("selection_error") else
461
+ f"no model set up ({model['provider']}: {model['detail']}): run harness once "
462
+ "in a terminal, or configure the selected model")
463
+ except (ValueError, OSError) as error:
464
+ problems.append(str(error))
446
465
  notes.append("No package places services here: hosted models only (harness install local-models for "
447
466
  "models on this machine's GPUs).")
448
467
  return {"schema_version": 1, "deploy": "none", "ok": not problems, "problems": problems, "notes": notes,
@@ -506,6 +525,9 @@ def _install(args):
506
525
  from .packages import Packages, activate, provision
507
526
  from .services.placement import load_deploy
508
527
 
528
+ terminal = getattr(args, "tui", False)
529
+ if terminal and args.update:
530
+ raise UsageError("--tui prepares the terminal; run it separately from --update")
509
531
  packages = activate(Packages())
510
532
  if args.update:
511
533
  result = packages.update(args.names, project=args.project, log=_note)
@@ -515,7 +537,7 @@ def _install(args):
515
537
  known = set(deploy.services) | set(bench_specs())
516
538
  specs = [name for name in args.names if name not in known]
517
539
  result = {"installed": [], "problems": []}
518
- if specs or (not args.names and args.project) or (not args.names and packages.project() is not None):
540
+ if specs or (not args.names and args.project) or (not args.names and not terminal and packages.project() is not None):
519
541
  def consent(found):
520
542
  for package in found:
521
543
  _print_package(package, file=sys.stderr)
@@ -532,7 +554,7 @@ def _install(args):
532
554
  result = packages.install(specs, project=project, consent=consent, link=args.link, log=_note)
533
555
  if result.get("needs_trust"):
534
556
  return 1
535
- elif not args.names:
557
+ elif not args.names and not terminal:
536
558
  return _usage("install", "name packages, services or benches (or run it where harness.toml names the "
537
559
  "project's packages)")
538
560
  # A name a package just brought (a bench) is installed as one now too: its environment.
@@ -541,6 +563,14 @@ def _install(args):
541
563
  benches = [name for name in provisioned if name in bench_specs()]
542
564
  services = [name for name in provisioned if name not in benches]
543
565
  rows = [provision.install_bench_environment(deploy, name, log=_note) for name in benches]
566
+ if terminal:
567
+ from .tui import environment
568
+ from .packages import environments
569
+
570
+ prepared = environment()
571
+ environments.install(prepared, log=_note)
572
+ rows.append({"name": "tui", "what": "frontend", "installed": True,
573
+ "environment": str(prepared.directory)})
544
574
  if services:
545
575
  # Services' environments and weights: the package that places services installs them.
546
576
  from .extensions import require
@@ -594,13 +624,19 @@ def _note(message):
594
624
  print(message, file=sys.stderr, flush=True)
595
625
 
596
626
 
597
- def _ready_model(interactive: bool) -> None:
627
+ def _ready_model(interactive: bool, *, recovery: bool = False) -> str | None:
598
628
  """A model and its key, asked for on the first run in a terminal (providers.setup)."""
599
- from . import model_list, providers
629
+ from . import providers
600
630
  from .paths import data
601
631
 
602
- if model_list.select(data()) is not None or providers.ready(data())["ready"]:
632
+ model = providers.ready(data())
633
+ if model["ready"]:
603
634
  return
635
+ if model.get("selection_error") or ((data() / "models.json").exists() and
636
+ model["detail"].startswith("add an enabled model")):
637
+ if recovery:
638
+ return f"{model['detail']}; use /model to choose an enabled model or /models to edit the list"
639
+ raise UsageError(model["detail"])
604
640
  if not (interactive and sys.stdin.isatty()):
605
641
  raise UsageError("no model is set up yet: run harness in a terminal once (it asks for the model and key), "
606
642
  "or export the provider's key")
@@ -667,6 +703,12 @@ def _starter(args):
667
703
  its environment for that many minutes. It keeps the last it started."""
668
704
  def start(text, files=(), log=None, learn=None, model_entry=None, reasoning_effort=None, workspace=None,
669
705
  folder=None, agents=None):
706
+ # Effort belongs to the startup route. A route picked in the TUI with no
707
+ # effort explicitly asks for that route's default, not the CLI route's effort.
708
+ if model_entry is None and start.model_entry is not None:
709
+ model_entry = start.model_entry
710
+ if reasoning_effort is None:
711
+ reasoning_effort = start.model_effort
670
712
  runtime = {**_run_options(args), **({"learn": learn} if learn is not None else {}),
671
713
  **({"agents": True} if agents else {})}
672
714
  coding = _coding(args)
@@ -696,6 +738,23 @@ def _starter(args):
696
738
  return start.host, start.conversation
697
739
 
698
740
  start.host = start.conversation = None
741
+ start.model_entry = start.model_effort = start.model_name = None
742
+ if not _coding(args).get("agent") and not (
743
+ getattr(args, "continue_last", False) or getattr(args, "session", None)) and (
744
+ getattr(args, "model", None) is not None or getattr(args, "effort", None) is not None):
745
+ from .model_list import SelectionError, select
746
+ from .paths import data
747
+
748
+ try:
749
+ initial = select(data(), getattr(args, "model", None))
750
+ except SelectionError:
751
+ # An effort-only flag must not close the UI needed to repair a default.
752
+ if getattr(args, "model", None) is not None:
753
+ raise
754
+ initial = None
755
+ if initial is not None:
756
+ start.model_entry, start.model_effort = initial["id"], getattr(args, "effort", None)
757
+ start.model_name = initial["name"]
699
758
  # The command line already says where it works: the chat does not ask at its opening.
700
759
  start.named = bool(getattr(args, "workspace", None) or getattr(args, "folder", None)
701
760
  or getattr(args, "agent", None))
@@ -777,9 +836,11 @@ def _run_task(args):
777
836
  from .terminal import Printer
778
837
  from .transcript import answer_of
779
838
 
839
+ _check_continuation_options(args)
780
840
  if args.model and _coding(args).get("agent"):
781
841
  raise UsageError("--model selects its own provider; use either --model or --agent")
782
- if not _coding(args).get("agent") and not args.model:
842
+ if not _coding(args).get("agent") and not args.model and not (
843
+ getattr(args, "continue_last", False) or getattr(args, "session", None)):
783
844
  _ready_model(interactive=True)
784
845
  from .settings import ChoiceRequired
785
846
 
@@ -924,6 +985,9 @@ def _rpc(args):
924
985
  it ends when stdin closes, after end, or when the conversation ends."""
925
986
  from .terminal import COMMANDS, command as run_command
926
987
 
988
+ if getattr(args, "continue_last", False) or getattr(args, "session", None):
989
+ raise UsageError("run rpc starts a new conversation; use harness run --continue or --session ID "
990
+ "for an existing conversation")
927
991
  if args.model and _coding(args).get("agent"):
928
992
  raise UsageError("--model selects its own provider; use either --model or --agent")
929
993
  if not _coding(args).get("agent") and not args.model:
@@ -1028,17 +1092,26 @@ def _rpc(args):
1028
1092
  def _default(args):
1029
1093
  """harness with no command: the terminal chat with the agent on this computer, which
1030
1094
  starts a conversation with the first message; the first run asks for the model and key."""
1031
- if not _coding(args).get("agent"):
1032
- _ready_model(interactive=True)
1095
+ _check_continuation_options(args)
1096
+ selecting = getattr(args, "model", None) is not None or getattr(args, "effort", None) is not None
1097
+ if selecting and _coding(args).get("agent"):
1098
+ raise UsageError("the terminal's --agent cannot be combined with --model or --effort; "
1099
+ "use harness run --agent NAME --effort LEVEL for an explicit agent effort")
1033
1100
  if not (sys.stdin.isatty() and sys.stdout.isatty()):
1034
1101
  raise UsageError("the terminal chat needs a terminal: harness run \"task\", or harness run rpc")
1035
1102
  from . import tui
1036
1103
 
1037
1104
  continued = _continued(args)
1105
+ start = _starter(args)
1106
+ start.warning = None
1107
+ if continued is None and not _coding(args).get("agent") and not getattr(args, "model", None):
1108
+ start.warning = _ready_model(interactive=True, recovery=True)
1109
+ if getattr(args, "effort", None) is not None and start.model_entry is None:
1110
+ start.warning = (start.warning or "") + " --effort was not applied; choose a model, then use /effort LEVEL."
1038
1111
  if continued is not None:
1039
- tui.chat(continued[1], host=continued[0], start=_starter(args))
1112
+ tui.chat(continued[1], host=continued[0], start=start)
1040
1113
  else:
1041
- tui.chat(start=_starter(args))
1114
+ tui.chat(start=start)
1042
1115
  return 0
1043
1116
 
1044
1117
 
@@ -1207,6 +1280,11 @@ def _library_command(args):
1207
1280
 
1208
1281
 
1209
1282
  def main(argv=None):
1283
+ """Catch setup and activation failures as well as command-dispatch failures."""
1284
+ return _guarded(lambda: _main(argv))
1285
+
1286
+
1287
+ def _main(argv=None):
1210
1288
  words = list(sys.argv[1:] if argv is None else argv)
1211
1289
  if words[:1] == ["rpc"]:
1212
1290
  words.insert(0, "run")
@@ -1228,13 +1306,21 @@ def main(argv=None):
1228
1306
  return _guarded(lambda: _package_command(words[0], words[1:]))
1229
1307
  command_parser = parser()
1230
1308
  args, rest = command_parser.parse_known_args(words)
1309
+ if args.command is not None and words and words[0].startswith("-"):
1310
+ raise UsageError("put options after the command, for example: harness run \"task\" --model MODEL")
1231
1311
  if rest and args.command != "doctor":
1232
1312
  command_parser.parse_args(words) # says what it does not know, exit status 2
1233
1313
  if args.command not in (None, "install", "remove", "list"):
1234
1314
  # The enabled packages' skills load here and in the kernels it starts.
1235
1315
  from .packages import activate
1236
1316
 
1237
- activate()
1317
+ try:
1318
+ activate()
1319
+ except (ValueError, OSError, RuntimeError, ImportError) as error:
1320
+ if args.command == "doctor" and args.json:
1321
+ output({"schema_version": 1, "ok": False, "problems": [str(error)], "error": str(error)})
1322
+ return 1
1323
+ raise
1238
1324
  commands = {"install": _install, "list": _list, "remove": _remove, "library": _library_command, "sessions": _sessions,
1239
1325
  "replay": _replay}
1240
1326
  if args.command == "run":
@@ -167,6 +167,9 @@ RUNTIME_KEYS = {
167
167
  "back with its handle",
168
168
  "longest_wait_seconds": "the longest a <wait> of the model lasts, and what a wait without a time gets "
169
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)",
170
173
  "thinking": "how long a call of the main model may think (runtime/conversation.py THINKING): model (the "
171
174
  "code's default: the model's own settings), none (reasoning off, replies of at most 2000 tokens, "
172
175
  "and the model is told to think briefly), low (reasoning effort at most low, 2000 tokens, told "
@@ -66,11 +66,31 @@ class Trace:
66
66
  def __init__(self, directory: Path, kinds: dict | None = None, *, append: bool = False):
67
67
  path = directory / "events.jsonl"
68
68
  if append:
69
- from .episodes import read_records
70
-
71
69
  if not path.is_file():
72
70
  raise ValueError("the existing session trace is missing")
73
- sequence = max((record["seq"] for record in read_records(directory)), default=-1) + 1
71
+ # The caller has reclaimed the ended conversation before opening its writer.
72
+ # Validate all complete events before repairing only the interrupted last line.
73
+ sequence = 0
74
+ with path.open("r+b") as handle:
75
+ while True:
76
+ offset = handle.tell()
77
+ line = handle.readline()
78
+ if not line:
79
+ break
80
+ if line.endswith(b"\n"):
81
+ record = json.loads(line)
82
+ else:
83
+ try:
84
+ record = json.loads(line)
85
+ except (ValueError, UnicodeError):
86
+ handle.truncate(offset)
87
+ break
88
+ # A complete JSON event without its newline is still history.
89
+ sequence = max(sequence, record["seq"] + 1)
90
+ handle.seek(0, 2)
91
+ handle.write(b"\n")
92
+ break
93
+ sequence = max(sequence, record["seq"] + 1)
74
94
  else:
75
95
  directory.mkdir(parents=True, exist_ok=False)
76
96
  path.touch()
@@ -42,6 +42,12 @@ from .ports import OwnPort
42
42
  # `by` names who takes the environment (a reflex, or a unit), for what is held to know;
43
43
  # resume(episode_id, held) is given that value and lets it go on. The run then pauses a
44
44
  # call for a unit of higher priority instead of ending it (runtime/tick.py).
45
+ #
46
+ # Priority (optional). Code that runs in the environment for long (a routine the agent saved
47
+ # there) may hold the environment for one action of it, as a program does with
48
+ # `with at_priority(n):`. The worker says so with its state: "priority", the priority that
49
+ # code asks for now (a number above 0; absent or None: none). The unit whose call runs holds
50
+ # the environment with it for as long as the state says so (runtime/tick.py _asked).
45
51
  WORKER_METHODS = ("profile", "state", "tick", "observe", "claim_outcome", "outcome", "tell_to")
46
52
 
47
53