@lmmslab/harness 0.81.0 → 0.82.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 (79) hide show
  1. package/README.md +24 -35
  2. package/package.json +2 -2
  3. package/python/harness/README.md +3 -3
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/configs/assistant.toml +0 -1
  6. package/python/harness/builtin/configs/default.toml +1 -1
  7. package/python/harness/builtin/prompts/conversation/core.md +2 -2
  8. package/python/harness/builtin/prompts/core/core.md +177 -41
  9. package/python/harness/builtin/prompts/core/pack.toml +2 -2
  10. package/python/harness/builtin/prompts/reflect/core.md +1 -1
  11. package/python/harness/builtin/prompts/shared/learning-goal.md +5 -29
  12. package/python/harness/builtin/prompts/shared/learning.md +8 -10
  13. package/python/harness/builtin/prompts/shared/web.md +11 -0
  14. package/python/harness/builtin/skills/agents/__init__.py +24 -22
  15. package/python/harness/builtin/skills/entries/__init__.py +43 -28
  16. package/python/harness/builtin/skills/entries/skill.toml +2 -3
  17. package/python/harness/builtin/skills/environments/__init__.py +2 -9
  18. package/python/harness/builtin/skills/mcp/__init__.py +2 -3
  19. package/python/harness/builtin/skills/memory/__init__.py +2 -5
  20. package/python/harness/builtin/skills/web/__init__.py +92 -0
  21. package/python/harness/builtin/skills/web/skill.toml +9 -0
  22. package/python/harness/cli.py +84 -16
  23. package/python/harness/config/agent.py +33 -9
  24. package/python/harness/core/episodes.py +5 -4
  25. package/python/harness/core/lanes.py +3 -0
  26. package/python/harness/core/memory.py +5 -1
  27. package/python/harness/core/remote.py +4 -3
  28. package/python/harness/core/worker.py +58 -3
  29. package/python/harness/extensions.py +23 -2
  30. package/python/harness/host/__init__.py +43 -1
  31. package/python/harness/host/client.py +36 -6
  32. package/python/harness/host/http.py +19 -0
  33. package/python/harness/host/server.py +17 -3
  34. package/python/harness/host/sessions.py +3 -2
  35. package/python/harness/host/tasks.py +158 -29
  36. package/python/harness/host/workspaces.py +69 -7
  37. package/python/harness/model_list.py +1 -1
  38. package/python/harness/packages/manager.py +5 -1
  39. package/python/harness/packages/manifest.py +12 -1
  40. package/python/harness/providers.py +14 -5
  41. package/python/harness/runtime/decision/loop.py +100 -121
  42. package/python/harness/runtime/decision/messages.py +156 -48
  43. package/python/harness/runtime/decision/model.py +79 -21
  44. package/python/harness/runtime/decision/prompts.py +15 -11
  45. package/python/harness/runtime/decision/protocol.py +12 -6
  46. package/python/harness/runtime/decision/thoughts.py +10 -16
  47. package/python/harness/runtime/events.py +28 -13
  48. package/python/harness/runtime/execution/attached.py +1 -1
  49. package/python/harness/runtime/execution/control.py +17 -35
  50. package/python/harness/runtime/execution/entries.py +204 -124
  51. package/python/harness/runtime/execution/kernel.py +471 -281
  52. package/python/harness/runtime/execution/managed.py +231 -0
  53. package/python/harness/runtime/execution/noenv.py +2 -2
  54. package/python/harness/runtime/execution/results.py +2 -0
  55. package/python/harness/runtime/execution/session.py +276 -115
  56. package/python/harness/runtime/learning/active.py +36 -48
  57. package/python/harness/runtime/learning/fixtures.py +2 -2
  58. package/python/harness/runtime/learning/learner.py +75 -2
  59. package/python/harness/runtime/learning/library.py +77 -10
  60. package/python/harness/runtime/learning/views.py +12 -1
  61. package/python/harness/runtime/reactive/__init__.py +1 -1
  62. package/python/harness/runtime/reactive/rules.py +29 -394
  63. package/python/harness/runtime/reactive/tree.py +611 -0
  64. package/python/harness/runtime/safety/approval.py +8 -3
  65. package/python/harness/runtime/safety/permissions.py +242 -0
  66. package/python/harness/runtime/status.py +7 -2
  67. package/python/harness/runtime/task/delegation.py +97 -58
  68. package/python/harness/runtime/task/environments.py +3 -4
  69. package/python/harness/runtime/task/inbound.py +64 -0
  70. package/python/harness/runtime/task/run.py +1092 -726
  71. package/python/harness/runtime/tick.py +257 -91
  72. package/python/harness/sdk/__init__.py +7 -4
  73. package/python/harness/settings.py +27 -3
  74. package/python/harness/terminal.py +10 -6
  75. package/python/harness/transcript.py +18 -6
  76. package/python/harness/tui/answer.py +51 -0
  77. package/python/harness/tui/chat.py +75 -26
  78. package/python/harness/tui/views.py +1 -0
  79. package/python/harness/builtin/prompts/shared/entries.md +0 -86
package/README.md CHANGED
@@ -1,55 +1,44 @@
1
- <p align="center">
1
+ <h1 align="center">
2
2
  <a href="https://harness.lmms-lab.com">
3
- <picture>
4
- <source srcset="docs/readme/logo-dark.svg" media="(prefers-color-scheme: dark)">
5
- <source srcset="docs/readme/logo-light.svg" media="(prefers-color-scheme: light)">
6
- <img alt="The Harness logo" src="docs/readme/logo-light.svg" width="96">
7
- </picture>
3
+ <img alt="The Harness — by LMMs-Lab" src="docs/readme/header.svg" width="960">
8
4
  </a>
9
- </p>
10
- <p align="center">
11
- <a href="https://discord.gg/zhkzEznBs"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
12
- <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm" src="https://img.shields.io/npm/v/@lmmslab/harness?style=flat-square" /></a>
13
- <a href="https://pypi.org/project/the-harness/"><img alt="PyPI" src="https://img.shields.io/pypi/v/the-harness?style=flat-square" /></a>
14
- </p>
15
-
16
- <h1 align="center">The Harness</h1>
5
+ </h1>
17
6
 
18
- <p align="center">Automatic Control for anything that acts.</p>
7
+ <p align="center"><strong>Automatic Control for intelligence in action.</strong></p>
19
8
 
20
- ---
9
+ <p align="center">
10
+ <a href="https://harness.lmms-lab.com/docs/getting-started/quickstart/">Quickstart</a> &nbsp; · &nbsp;
11
+ <a href="https://harness.lmms-lab.com/docs/">Documentation</a> &nbsp; · &nbsp;
12
+ <a href="https://harness.lmms-lab.com/docs/concepts/harness/">How it works</a>
13
+ </p>
21
14
 
22
- The Harness is Automatic Control for anything that acts. You tell an agent what to do in
23
- your own words; a language model plans and writes short programs, and The Harness runs
24
- them in an environment the agent can see and act in, while you watch, add a message or
25
- take over.
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>
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
+ </p>
26
20
 
27
- The agent thinks while it acts: between model calls, its programs, skills and reactive
28
- rules keep working, and what it learns along the way (notes, tested skills, rules)
29
- applies in the same run.
21
+ Tell an agent what to do in your own words. A language model plans and writes short programs; The Harness runs them in an environment the agent can see and act in. Watch, send a message, or take over at any time.
30
22
 
31
- Use The Harness [in the terminal](https://harness.lmms-lab.com/docs/use/terminal/), run one task from
32
- [the CLI](https://harness.lmms-lab.com/docs/use/cli/), drive it from another program with JSON lines, call it from
33
- [apps, editors and other agents](https://harness.lmms-lab.com/docs/extend/editors/) over MCP and ACP, or build on the
34
- [Python API](https://harness.lmms-lab.com/docs/extend/python-api/).
23
+ The agent thinks while it acts: between model calls, its programs, skills and reactive rules keep working. What it learns along the way—notes, tested skills and rules—applies in the same run.
35
24
 
36
25
  ## Getting started
37
26
 
38
27
  ```bash
39
- npm install -g @lmmslab/harness # or: pip install the-harness
28
+ npm install -g @lmmslab/harness
40
29
  harness
41
30
  ```
42
31
 
43
- The Harness needs Python 3.11 or newer. `harness` opens a conversation in your terminal.
44
- The first time, it asks which model to use and for its key; then type a task. Any model
45
- works: hosted ones through OpenRouter, OpenAI, Anthropic and other providers, or a model
46
- you run yourself.
32
+ The Harness needs Python 3.11 or newer. You can also install it with `pip install the-harness`.
47
33
 
48
- See [Install](https://harness.lmms-lab.com/docs/getting-started/install/) and the
49
- [Quickstart](https://harness.lmms-lab.com/docs/getting-started/quickstart/) for a real task on your own computer.
34
+ `harness` opens a conversation in your terminal. The first time, it asks which model to use and for its key; then type a task. Any model works: hosted ones through OpenRouter, OpenAI, Anthropic and other providers, or a model you run yourself.
35
+
36
+ See [Install](https://harness.lmms-lab.com/docs/getting-started/install/) and the [Quickstart](https://harness.lmms-lab.com/docs/getting-started/quickstart/) for a real task on your own computer.
50
37
 
51
38
  ## Commands
52
39
 
40
+ Use The Harness [in the terminal](https://harness.lmms-lab.com/docs/use/terminal/), run one task from [the CLI](https://harness.lmms-lab.com/docs/use/cli/), drive it from another program with JSON lines, call it from [apps, editors and other agents](https://harness.lmms-lab.com/docs/extend/editors/) over MCP and ACP, or build on the [Python API](https://harness.lmms-lab.com/docs/extend/python-api/).
41
+
53
42
  ```bash
54
43
  harness # talk with the agent in the terminal
55
44
  harness run "task" -p # do one task and print the answer (--json: every event)
@@ -113,7 +102,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [the validation guide](docs/TESTING.m
113
102
  ```bibtex
114
103
  @misc{lmmslab2026harness,
115
104
  author = {{LMMs-Lab}},
116
- title = {The Harness: One Agent Harness for Anything that Acts},
105
+ title = {The Harness: Automatic Control for Intelligence in Action.},
117
106
  howpublished = {\url{https://github.com/EvolvingLMMs-Lab/the-harness}},
118
107
  year = {2026}
119
108
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lmmslab/harness",
3
- "version": "0.81.0",
4
- "description": "Automatic Control for anything that acts",
3
+ "version": "0.82.0",
4
+ "description": "Automatic Control for intelligence in action",
5
5
  "license": "MIT",
6
6
  "homepage": "https://harness.lmms-lab.com",
7
7
  "repository": {
@@ -9,9 +9,9 @@ boundary. The controller's Python process and the task's target environment are
9
9
 
10
10
  | Concept | Source | Responsibility |
11
11
  |---|---|---|
12
- | Model decisions | `runtime/decision/` | Model transport, requests and cancellation, messages, prompts, reply protocol and speculative-reply rules |
12
+ | Model decisions | `runtime/decision/` | Model transport, requests and cancellation, messages, prompts and the reply protocol |
13
13
  | Programs and learned policies | `runtime/execution/` | Controller process, session bootstrap, bounded executions, skills and control API |
14
- | Reactive control | `runtime/reactive/` | Guards, reflexes and event handlers evaluated during execution |
14
+ | Reactive control | `runtime/reactive/` | Rules (a condition, a priority and a program) and event handlers |
15
15
  | Fixed safety | `runtime/safety/` | Shield mechanism, input ownership, approval contracts and controller isolation |
16
16
 
17
17
  These are control responsibilities, not four sequential RPC services. The shared
@@ -50,7 +50,7 @@ agent package. A CLI task and a benchmark episode use the same task engine witho
50
50
  - A program starts or returns a receipt: `runtime/execution/kernel.py` and `results.py`.
51
51
  - Controller API and environment session setup: `runtime/execution/session.py`.
52
52
  - Bounded actions and interruptions: `runtime/execution/entries.py` and `runtime/tick.py`.
53
- - A guard, reflex or handler runs: `runtime/reactive/rules.py`.
53
+ - A rule or handler runs: `runtime/reactive/rules.py`.
54
54
  - A command is refused or needs approval: `runtime/safety/shield.py`, `approval.py` and the package's worker.
55
55
  - A proposal is tested or admitted: `runtime/learning/learner.py` and `fixtures.py`.
56
56
  - Library contents become runnable: `runtime/learning/active.py` and the task's activation boundary.
@@ -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.81.0"
5
+ __version__ = "0.82.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
@@ -5,7 +5,6 @@ description = "the session host's assistant"
5
5
  [budget]
6
6
  max_model_calls = 60
7
7
  max_wall_seconds = 21600
8
- max_cost_usd = 5.0
9
8
 
10
9
  [overrides.agent]
11
10
  prompt = {}
@@ -29,5 +29,5 @@ budget = { max_model_calls = 60 }
29
29
  [game]
30
30
  knowledge = "learned"
31
31
  skills = { enable = ["vision"] }
32
- runtime = { contract = "native", strategy_first = false, max_history_turns = 8, think_while_acting = "off", thinking = "low", max_wait_seconds = 30 }
32
+ runtime = { contract = "native", strategy_first = false, compact_at_tokens = 150000, clear_results_after_minutes = 60, thinking = "low", max_wait_seconds = 30 }
33
33
  budget = { max_model_calls = 5000 }
@@ -1,5 +1,5 @@
1
1
  This conversation has no environment: no screen, no project folder and no browser. You
2
2
  have your own knowledge, the user's messages and files, plain Python in your programs,
3
- and the connected tools listed below when there are any. Answer questions directly with
4
- <finish>. Do not claim to have looked at, opened or changed anything on the user's
3
+ and the connected tools listed below when there are any. Answer questions directly in
4
+ plain text. Do not claim to have looked at, opened or changed anything on the user's
5
5
  computer.
@@ -1,52 +1,206 @@
1
- You act by writing Python programs. Each turn, reply with exactly one of:
1
+ You act by writing Python programs. A turn is your work from what reached you (a message,
2
+ the end of a unit, an event) to your answer. In it you reply as often as it takes, each
3
+ time with exactly one of:
2
4
 
3
- - <python>...</python>: a program, run at once. Put a short explanation in # comments
5
+ - <python>...</python>: a program, started at once. Put a short explanation in # comments
4
6
  inside it. Every call below is an ordinary Python call inside the block, never an XML
5
7
  tag or a native tool call.
6
- - <finish>your complete answer</finish>, or finish(summary) inside a program: the task
7
- is done. No later turn writes the answer for you.
8
- - Plain text: a question for the user. It runs nothing and waits for the answer.
8
+ - <wait></wait>, or <wait>seconds</wait>: wait for what you started.
9
+ - Plain text, with no block: your answer, complete (what you did or found, or a question
10
+ you need answered). It runs nothing and ends this turn. The conversation goes on: the
11
+ next message starts your next turn, and you keep what you have.
9
12
 
10
13
  <!-- if: look -->
11
14
  When a program ends you see its output, what went wrong if anything did and the state, as
12
15
  text. A picture reaches you only when a program looks (look and watch below); read what
13
16
  the state and the environment's calls give as text first, and look when that does not
14
- tell. Write one program for a coherent phase with a clear completion condition.
17
+ tell, while a program runs as much as after it. Write one program for a coherent phase
18
+ with a clear completion condition.
15
19
  <!-- else -->
16
20
  When a program ends you see its output, what went wrong if anything did, the state and
17
21
  new pictures. Write one program for a coherent phase with a clear completion condition.
18
22
  <!-- end -->
19
23
  Let it observe, act, wait for a condition, and check the result as it goes. Handle
20
- expected outcomes and bound any waits or retries. Use rules for changes that need an
21
- immediate response. End the program when the phase is complete, a choice needs your
22
- judgment, or an unexpected result makes it unsafe to continue. A format error ran
23
- nothing: send one correct block. After a program error, check the state before repeating
24
- anything because earlier steps may already have run.
24
+ expected outcomes and bound any waits or retries. End the program when the phase is
25
+ complete, a choice needs your judgment, or an unexpected result makes it unsafe to
26
+ continue. A format error ran nothing: send one correct block. After a program error,
27
+ check the state before repeating anything because earlier steps may already have run.
25
28
 
26
- <!-- if: think_while_acting -->
27
- During a long program you may be asked once to prepare its next decision. Give an
28
- `<assume>` check on the final result, or reply `<wait>` to see the result first.
29
+ You are one part of an agent that lives in a world that goes on by itself. An agent does
30
+ two kinds of things. It answers what happens to it and around it, and is then where it
31
+ was: that is its tree of reflexes, which acts by itself, all the time, without you. And it
32
+ sets out to make something the case that is not: that is yours, done by your programs, and
33
+ over when it is done. The tree never sets out for anything.
34
+
35
+ Start from what is there. Before you settle anything, find out what you have and what is
36
+ within reach. What you are given to act with is part of that: before you rely on
37
+ something you did not make, find out from the thing itself, its documentation and its
38
+ source, what it does, what it assumes and what it leaves to you; what you remember of it
39
+ is not that. Say what the task needs as things that must be true, not as a sequence:
40
+ what is already true needs no step, and the order follows from what is there.
41
+
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
55
+ that what it interrupted can go on.
56
+
57
+ Build each thing for the situations it has to work in, and think and test in proportion
58
+ to what a failure costs: settle in the design what is cheap to settle; test what is
59
+ uncertain and matters with the smallest test that could prove it wrong, where a failure
60
+ costs little, and once. When something fails, or something arises that nothing answered,
61
+ find the first point where it differed from what you expected, say what kind of
62
+ situation that is, repair what is responsible for the kind, and look for the same flaw
63
+ elsewhere. The same kind again means the design is wrong: return to the design.
64
+
65
+ Your work is made of units. A program is a unit: it runs beside the others, with its own
66
+ output and result. One that is over within a moment gives you its result at once; a
67
+ longer one goes on, you are asked again at once with its name, and its result reaches
68
+ you when it ends. Meanwhile you are free: start another program, cancel one, or
69
+ wait. A wait ends when a unit you started ended, when a message or an event reached you,
70
+ or when its time is over, and you are told which. What a program starts (units, reflexes)
71
+ is yours: it outlives the program and the turn. After your answer it goes on,
72
+ and the end of a unit or an event starts your next turn; cancel what should not go on.
73
+
74
+ Every unit ends with the same report, whoever started it: how it ended (by itself, an
75
+ error, an event, cancelled, its time limit), whether what it was for is the case (done:
76
+ yes or no), and what it returned. How it ended and whether it is done are two things: a
77
+ unit that ended by itself has not done its work when what it was for is not the case. A
78
+ program says what it is for with until(condition), a function of the view that holds when
79
+ its work is done; it is judged when the program ends. Without one, the report says how it
80
+ ended and nothing of done.
81
+
82
+ What you leave running is yours to supervise. Before a long program, say what should be
83
+ true while it runs. When you are asked again while it runs, check that before you wait
84
+ again: its output so far, the state, a picture where there is one. Wait no longer than
85
+ you are content not to know. When it is not doing what you expected, cancel it and plan
86
+ again. To be woken for a condition instead of checking for it, set a reflex that raises
87
+ an event.
88
+
89
+ <!-- if: machine -->
90
+ Your programs run on the machine this conversation runs on, as its user. They read its
91
+ files. What they do beyond their own folder (start a process, reach the network, write
92
+ or delete elsewhere, open a file that holds credentials) goes by the user's settings: it
93
+ happens, the user is asked first, or it is refused, and then the call raises
94
+ PermissionError with the reason.
29
95
  <!-- end -->
30
96
 
31
97
  The calls every agent has:
32
98
 
33
99
  - get_observation(): what the world shows now (its pictures and its state);
34
- get_state(): the state alone; show(image): put a picture (a crop, a plot) in your
35
- next turn.
100
+ get_state(): the state alone; show(image): put a picture (a crop, a plot) with this
101
+ program's result.
36
102
  <!-- if: look -->
37
- - look(camera=None, region=None, keep=None, pin=None): put a view in your next turn with
38
- this program's result, so acting and looking are one program: all the views, one by
103
+ - look(camera=None, region=None, keep=None, pin=None): put a view with this program's
104
+ result, so acting and looking are one program: all the views, one by
39
105
  name, or the part region=(x, y, width, height). A view stays for your next reply only;
40
106
  keep=N keeps the views of your last N programs in sight, pin="name" keeps this one until
41
107
  unpin("name").
42
- - watch(cameras=None, every="program", keep=None): from now on the views come with every
43
- program's result (every=seconds: also that often while a long program runs) until
44
- unwatch(). Turn it on yourself for work that is seen, not read: a game, a moving scene.
108
+ - watch(cameras=None, keep=None): from now on the views come with every program's result
109
+ until unwatch().
45
110
  <!-- end -->
46
111
  <!-- if: entries -->
47
- - spawn(fn, name=None): run fn as an entry of its own beside the program and go on;
48
- receive(): what the entries sent and how they ended. More on entries below.
112
+ - spawn(fn, name=None, priority=None, restart=False, until=None): run fn as a unit of
113
+ its own and go on (until: what it is for, as until(condition) says for a program). Its
114
+ handle: .wait(timeout=None) returns what fn returned, .cancel() ends it,
115
+ .send(message) gives it a message that receive(timeout=None) reads inside fn, .status.
116
+ entries(): the handles of the units that run, your programs among them, each with its
117
+ .id (the name you are told).
118
+ output_of(unit, chars=2000): what a unit (its id or its handle) has printed so far, the
119
+ last chars characters (at most 30000); its result still has all of it when it ends.
120
+ What you are told has a limit, and says so where it left something out: what a unit
121
+ printed or returned is told whole up to 30000 characters; more is saved to a file, and
122
+ you are told the file, which a program can read, and its first 2000 characters. Of a
123
+ unit that failed you are told the first and last 5000 characters.
124
+ <!-- if: channels -->
125
+ Where the environment has channels (CHANNELS), units act at the same time, each on the
126
+ channels it took: spawn(..., claims=[...]) or claim(*channels) takes them,
127
+ unclaim(*channels) lets them go, channels() says who has each. Reaching for a channel
128
+ another unit has is a CHANNEL_CONFLICT event.
129
+ <!-- end -->
49
130
  <!-- end -->
131
+ What acts without you is one tree, empty at first. A node of it says when it has its
132
+ turn and what it does then; a node under another has its turn only while that one's
133
+ condition holds. Among the nodes at one place the earlier takes the environment from the
134
+ later, and gives it back when it is done. What several nodes need is said once: a
135
+ condition as the node above them or as a sense, an action as a function they call.
136
+ - set_reflex(name, when, do=None, under=None, priority=0, every=None, again_seconds=0):
137
+ put the node `name` into the tree, in place of a node of that name.
138
+ when: a function of the view: the node has its turn while it holds. It is judged
139
+ without you, and the node takes the environment as soon as it holds. Or the name of an
140
+ event: the node answers that event when it happens, and you are not told of it then.
141
+ do: a program (a function): started as a unit when the node's turn comes; what it is
142
+ for is that the node's condition no longer holds. It begins again while the turn lasts,
143
+ 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.
146
+ 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.
150
+ every: the seconds between judgements of its condition; without it the condition is
151
+ judged when the state or the facts change.
152
+ A condition is read, not computed: the conditions judged in one moment share a few
153
+ milliseconds between them, and may not open files, use the network, sleep or start
154
+ anything. One the moment had no time for is judged in the next. One that is slower
155
+ than that time after time, or that raises, is a fault: its node is removed with the
156
+ nodes under it and you are told (the event REACTIVE_FAULT).
157
+ You are not told when a node's program has done its work. When it ends and its
158
+ situation is not over, or it fails, a later node at its place whose condition holds has
159
+ the environment; when none has, you are told with the program's report (the event
160
+ REFLEX_FAILED), once until the node has done its work again.
161
+ - reflexes(name=None): the nodes at the top of the tree, or the nodes under the node
162
+ name (the node itself where it has none under it), at most 50 at a time: each with
163
+ whether its condition holds, whether its program runs, how often it began, the report
164
+ of its last run and the names of the nodes under it. With every turn you are told how
165
+ many nodes act in the tree and, of those that changed since you were last told, how
166
+ often each one's program began, did its work and did not (at most 10; reflexes() has
167
+ the rest). drop_reflex(names=None): remove nodes with the nodes under them (None: all).
168
+ - facts.set(name, value), facts.get(name, default=None), facts.drop(name): what the run
169
+ knows, shared by your programs and reflexes (view["facts"]). Keep progress there, so that
170
+ what you start again goes on from what was done.
171
+ <!-- if: senses -->
172
+ - sense(name, code): have the environment compute a value itself, each time it reports
173
+ its state: view["sensed"][name] for conditions, get_state()["sensed"][name] for
174
+ programs. `code` is in the environment's own language and reads the environment
175
+ directly (the environment's own page says what the code has). It returns {"value": as
176
+ computed now, "error"}. senses(): those defined, with their code and values;
177
+ drop_sense(name).
178
+ <!-- end -->
179
+ - run_controller(fn, until=None, max_seconds=None): apply the command returned by fn(view)
180
+ for each step. Return None to end it. A reflex or until(view) can end the execution.
181
+ A unit of higher priority (a reflex's program) takes the environment from a lower one and
182
+ holds it until it ends.
183
+ <!-- if: pauses -->
184
+ The lower call is suspended where it is and goes on by itself when the higher unit has
185
+ ended: its program does not end, and you are not asked.
186
+ <!-- else -->
187
+ The lower call ends there with the event PREEMPTED and what it had done, and you are told
188
+ at once: which reflex took the environment, from which program, and the state. You decide
189
+ what goes on: the same again, or something else. Only a unit started with restart=True
190
+ has its call started again by itself then (its result counts it: .restarts).
191
+ <!-- end -->
192
+ What you start meanwhile waits for the higher unit to end. Units of equal priority take
193
+ 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.
202
+ Conditions and controllers read the supplied view. Keep them fast and free of file,
203
+ network, process and input operations.
50
204
  <!-- if: memory -->
51
205
  <!-- if: legacy_memory -->
52
206
  - recall(query): what earlier runs kept about a situation like this one.
@@ -68,21 +222,3 @@ The calls every agent has:
68
222
  More on learning below.
69
223
  <!-- end -->
70
224
  <!-- end -->
71
- - run_controller(fn, until=None, max_seconds=None): apply the command returned by fn(view)
72
- for each step. Return None to finish. A guard or until(view) can end the execution.
73
- - when(predicate, action, name=None, stops=True): stop an execution in scope when
74
- predicate(view) holds, or raise an event and continue when stops=False.
75
- <!-- if: look -->
76
- - watch(signal_name, low=None, high=None, event=None, name=None, stops=True): with low or
77
- high, the same check for a number from a dotted state key or a callable.
78
- <!-- else -->
79
- - watch(signal_name, low=None, high=None, event=None, name=None, stops=True): the same check
80
- for a number from a dotted state key or a callable.
81
- <!-- end -->
82
- - on(event, handler): answer an event with handler(trace). Return False to pass it up.
83
- - rule(decide, name=None, priority=0): the callback receives view and state. It may
84
- return None, an Event from harness.sdk, or {"stop_entry": entry.id} to stop an entry in scope.
85
- - clear_rules(names=None): remove guards and observation rules, optionally by name.
86
- Rules and controllers read the supplied view. Keep callbacks fast and free of file,
87
- network, process and input operations. Callbacks on the tick share one time budget.
88
- - finish(summary): the task is done (or reply <finish>).
@@ -1,9 +1,9 @@
1
1
  # The page every agent reads first (runtime/decision/prompts.py): how to reply and the calls every
2
- # agent has, then entries, learning and world memory when they are on. A package's pack
2
+ # agent has (units, rules and facts among them), then learning and world memory when they are on. A package's pack
3
3
  # starts with it ({ pack = "../core" }) and adds its own sections.
4
4
  sections = [
5
5
  { file = "core.md" },
6
- { file = "../shared/entries.md", skills = ["entries"] },
7
6
  { file = "../shared/world.md", skills = ["world"] },
7
+ { file = "../shared/web.md", skills = ["web"] },
8
8
  { file = "../shared/learning.md", skills = ["learning"] },
9
9
  ]
@@ -37,7 +37,7 @@ Reply with exactly one of <note name="snake_case">...</note>, <memory name="snak
37
37
  Code must define one public function with a one-line docstring.
38
38
  <!-- else -->
39
39
  When the observations show a judgment repeatedly worked, consider turning it into a skill.
40
- When a frequently useful part of a skill can decide what to do using only the current view, consider a reactive rule.
40
+ When a frequently useful part of a skill can decide what to do using only the current view, consider a reflex (set_reflex).
41
41
  Cite the outcomes that support the proposal in its docstring. Code defines one public function with a docstring.
42
42
  For code, follow the entry with <test>Python invocation and observable success condition</test>.
43
43
  The host independently checks the behavior. Use <none/> when the evidence does not support an addition.
@@ -1,31 +1,7 @@
1
- Get to know this environment for this task, then stop: do not do the task itself in this run. The task you are learning for: {task}
1
+ This run is practice for a task, not the task itself: {task}
2
2
 
3
- You have {minutes} minutes of live time. Learn the environment the way a careful person learns a new game, app, website or machine before using it for real, and put what you learn into your library with library.propose, so the runs that do the task start with it. Nobody will tell you what to watch out for: working that out is your job.
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.
4
4
 
5
- 1. Read what there is: its help, its manual, its tutorial, its settings or controls screen. Note what you read but have not seen yet as something to check.
6
- 2. Try every control and see what it does: compare what you see and what you read before and after each one.
7
- {probe}
8
- <!-- if: legacy_memory -->
9
- 3. Think the task through before you build anything, as hard as you can, and write it down as the memory entry "situations" (library.propose("memory", "situations", text)):
10
- <!-- else -->
11
- 3. Think the task through before you build anything, as hard as you can, and write it down as the memory entry "situations" (remember("plan", text, name="situations", keep=True)):
12
- <!-- end -->
13
- - the path: the steps from where you are to the goal, each a milestone you can check by what you see or read;
14
- - for each step, what you must be able to do (a skill each, built on the basic moves of this body: {skills}), and its hardest version you can expect: the toughest material or target, the longest distance, an action that must last or repeat, a screen or layout that differs, a slow or missing response;
15
- - how each step can fail, and how you would notice from what you see that it did not really work;
16
- - what can happen faster than you can think: being hurt or attacked, falling, losing what you hold, a window, dialog or error that appears, something coming at you; each of these needs a reactive rule, not a skill;
17
- - then argue against your own plan: what would most likely make it fail? Add that too.
18
- Mark each line with its state: [ ] not covered, [skill name] or [rule name] when an entry covers it and its test passed, [unknown] when you cannot test it here. Keep this entry up to date: propose it again whenever it changes.
19
- 4. Cover the list. For each line, write the skill or the rule it needs:
20
- - a skill is a closed loop (ClosedLoop) whose test calls it on the hardest version of its case and asserts on the real result in the environment (calling the class runs it: r = Walk(...); assert r.ok, r.reason), not on its return value alone;
21
- - a reactive rule is proposed with library.propose("reactive", name, code, test=...); its test feeds it the views or events of its situation and checks that it acts then and only then;
22
- - code proposals stay pending until an independent fixture checks them. Mark pending cases [unknown] and record what you observed in practice.
23
- {sandbox}
24
- <!-- if: legacy_memory -->
25
- 5. Drill toward the task, from the first milestone on, as a player or a new user would, and seek out the hard and the dangerous situations on your list instead of waiting for them: {drills}. Use your skills; when a drill fails or something happens that your list did not foresee, add it to "situations", rewrite the entry that failed, and propose it again. Keep each drill's outcome as a memory entry (what you tried, what happened, what to do instead) as the run records skill results by revision.
26
- <!-- else -->
27
- 5. Drill toward the task, from the first milestone on, as a player or a new user would, and seek out the hard and the dangerous situations on your list instead of waiting for them: {drills}. Use your skills; when a drill fails or something happens that your list did not foresee, add it to "situations", rewrite the entry that failed, and propose it again. Keep each drill's outcome as a memory entry (remember(kind, text, name=..., keep=True): what you tried, what happened, what to do instead); each result of your closed loops counts as a use of its skill by itself.
28
- <!-- end -->
29
- 6. Stop when every line of "situations" is covered or marked [unknown], or when the time is nearly up. Finish with a short note of what you learned and what is still unknown.
30
-
31
- After each program you are told what you have learned so far, your "situations" list and what to do next. Spend your time on controls, skills, rules and drills, not on long thinking: the live time is the budget.
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
+ {probe}
7
+ {sandbox}
@@ -1,8 +1,6 @@
1
- Keep observations and notes you will need again. Skill and rule proposals require trusted verification before use. Use what your library already holds first: its tested skills and
2
- rules are listed at the start; call them, and rewrite one that falls short instead of writing
3
- new code beside it. When something happens that your memory entry "situations" did not
4
- foresee, add it there and learn for it. Propose an entry when you learned something you will
5
- need again:
1
+ Your library keeps what you learned, for your later programs and for later runs. Skill and
2
+ reflex proposals require trusted verification before use; the tested skills and reflexes it
3
+ holds are listed at the start. An entry is proposed with:
6
4
  library.propose(kind, name, text, test=None, summary="")
7
5
  kind "note": a sentence or two you want in your instructions from now on (what a
8
6
  <!-- if: legacy_memory -->
@@ -11,17 +9,17 @@ need again:
11
9
  <!-- else -->
12
10
  control does, a rule of this place); "skill": code (functions, or a ClosedLoop class) your programs call
13
11
  <!-- end -->
14
- by name; "reactive": code for the reactive layer.
15
- Include a test that calls the skill or rule and checks its effect. Code stays pending
12
+ by name; "reactive": the lines that set reflexes or a tree (set_reflex, tree): they
13
+ are set again by themselves when a later session starts.
14
+ Include a test that calls the skill or reflex and checks its effect. Code stays pending
16
15
  until a trusted host verifies the exact revision. A successful proposal can return
17
16
  {"ok": True, "queued": True}. End that program to give the host its verification
18
17
  boundary. Use a skill in a later program once the active library lists it.
19
18
  For a practice scene, supply setup with the test. Its code can call
20
19
  sandbox(op, **arguments) when the verifier provides a compatible environment.
21
20
  library.entries() proposals and admitted entries with their evidence
22
- Write a skill that acts as a closed loop: a subclass of ClosedLoop fills in confirm() (the
21
+ ClosedLoop is a skill that acts as a closed loop: a subclass fills in confirm() (the
23
22
  target is what you think: True or the reason not to act), do() (the action), check() (the
24
23
  world changed as it should: True or why not) and recover(reason) (between tries); `tries`
25
24
  and `max_seconds` bound it, and calling the class runs it and returns a Result: .ok,
26
- .reason, .tries, .seconds, .detail. Keep a skill to one thing (open a menu, walk to what you
27
- see, pick an item).
25
+ .reason, .tries, .seconds, .detail.
@@ -0,0 +1,11 @@
1
+
2
+ The web:
3
+
4
+ fetch(url, start=0) the text of a page (http, https): an HTML page as its
5
+ text with the addresses of its links, anything else as
6
+ it is; at most 100000 characters from character start,
7
+ then how to read on
8
+ search(query, results=5) search the web: a list of {"title", "url", "text"},
9
+ at most results (1 to 10); ValueError where this
10
+ conversation has no search
11
+
@@ -2,17 +2,15 @@
2
2
  same time, each in a workspace of its own (or with the windows this agent hands over),
3
3
  and waits for their results. The conversation that runs the program starts and keeps
4
4
  them (runtime/task/delegation.py): every call here is a request to it, sent as a note, and its
5
- answer comes back through the kernel (runtime/execution/control.py). Each sub-agent is an entry of
6
- the session's tree (runtime/execution/entries.py) under the code that started it: when it ends, the
7
- conversation tells the kernel, and a sub-agent that did not finish is an ENTRY_FAILED
8
- event of that code."""
5
+ answer comes back through the kernel (runtime/execution/control.py). Each turn of a sub-agent is
6
+ a unit of the model (runtime/execution/entries.py): when it ends, the conversation tells the kernel,
7
+ the model hears of it, and a turn that ended without an answer is an ENTRY_FAILED event for
8
+ the handlers first."""
9
9
 
10
10
  import uuid
11
11
 
12
12
  from harness.sdk import spans
13
13
  from harness.sdk import control
14
- from harness.sdk import user_message
15
- from harness.sdk import Escalation
16
14
 
17
15
 
18
16
  # A sub-agent's statuses while it works on (runtime/task/delegation.py state()).
@@ -23,15 +21,9 @@ class Agents:
23
21
  if not spans.connected():
24
22
  raise RuntimeError("sub-agents need the conversation that runs this program; none is connected")
25
23
  identifier = uuid.uuid4().hex[:12]
26
- tree = getattr(self, "_entries", None)
27
- # The program's own code (not an entry it started) leaves a wait for a message for
28
- # the model, with a USER_MESSAGE event; the sub-agents go on.
29
- own = tree is None or tree.current() is tree.root
30
- spans.note("agents", action=operation, id=identifier, own=own, **detail)
31
- answer = control.wait_answer(identifier, stop=control.message_arrived if own else None)
24
+ spans.note("agents", action=operation, id=identifier, **detail)
25
+ answer = control.wait_answer(identifier)
32
26
  if answer is None:
33
- if own and control.message_arrived():
34
- raise Escalation(user_message(f"{operation}_agents" if operation == "wait" else operation, detail))
35
27
  return None
36
28
  if answer.get("error"):
37
29
  raise ValueError(answer["error"])
@@ -41,7 +33,7 @@ class Agents:
41
33
  """Start a sub-agent on `task` (what it is to do and what to report back); returns its
42
34
  id. `workspace`: "new" (a workspace of its own, of this one's kind), "browser",
43
35
  "desktop", "apps" or "display" (a new one of that kind), or "share" (it takes over the windows this agent
44
- holds now and hands them back when it ends). `budget`: {"calls", "cost", "seconds"},
36
+ holds now and hands them back when its turn ends). `budget`: {"calls", "cost", "seconds"},
45
37
  taken from this agent's own (default: all that is left). `model`: another model of
46
38
  the same provider. `agent`: another harness's agent ("claude-code", "codex") that does
47
39
  the task in its own bounded directory. `multi_turn=True` keeps a supported external
@@ -56,18 +48,28 @@ class Agents:
56
48
  return agent
57
49
 
58
50
  def wait_agents(self, ids=None, timeout=None):
59
- """Wait until each sub-agent in `ids` (default: all this agent started) has ended or
60
- asks this agent something, at most `timeout` seconds; returns {id: {"status",
61
- "result", "question", "model_calls", "cost_usd", "seconds", "directory", "files"}}, or
62
- None when the user paused this agent first. A message for this agent ends the wait
63
- at once with a USER_MESSAGE event; the sub-agents go on."""
51
+ """Wait until the turn of each sub-agent in `ids` (default: all this agent started) is
52
+ over, at most `timeout` seconds; returns {id: {"status", "result", "model_calls",
53
+ "cost_usd", "seconds", "directory", "files"}}, or None when the user paused this
54
+ agent first."""
64
55
  ids = [ids] if isinstance(ids, str) else (list(ids) if ids else None)
65
56
  ids = [self._agent_id(item) for item in ids] if ids else ids
66
57
  return self._agents("wait", ids=ids, timeout=timeout)
67
58
 
68
59
  def send_agent(self, agent, text):
69
- """Send sub-agent `agent` a message (the answer to its question, or more to do)."""
70
- return self._agents("send", agent=self._agent_id(agent), text=str(text))
60
+ """Send sub-agent `agent` a message (more to do, or the answer to what it asked). One
61
+ whose turn was over goes on with what it has, and the end of that turn reaches this
62
+ agent as the end of its first did."""
63
+ agent = self._agent_id(agent)
64
+ tree = getattr(self, "_entries", None)
65
+ # The turn the message starts is a unit of this agent, unless one of it still runs.
66
+ turn = tree.adopt_agent(agent, text) if tree is not None and not tree.agent_runs(agent) else None
67
+ try:
68
+ return self._agents("send", agent=agent, text=str(text))
69
+ except Exception:
70
+ if turn is not None:
71
+ tree.agent_ended(agent, {"status": "cancelled"}, cancelled=True)
72
+ raise
71
73
 
72
74
  def cancel_agent(self, agent):
73
75
  """Stop sub-agent `agent` (and those it started); returns its report."""