@lmmslab/harness 0.81.1 → 0.83.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/README.md +24 -35
  2. package/package.json +2 -2
  3. package/python/harness/README.md +3 -3
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/configs/assistant.toml +0 -1
  6. package/python/harness/builtin/configs/default.toml +1 -1
  7. package/python/harness/builtin/prompts/conversation/core.md +2 -2
  8. package/python/harness/builtin/prompts/core/core.md +197 -45
  9. package/python/harness/builtin/prompts/core/pack.toml +2 -2
  10. package/python/harness/builtin/prompts/reflect/core.md +4 -13
  11. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  12. package/python/harness/builtin/prompts/shared/learning-goal.md +5 -29
  13. package/python/harness/builtin/prompts/shared/learning.md +8 -10
  14. package/python/harness/builtin/prompts/shared/web.md +11 -0
  15. package/python/harness/builtin/skills/agents/__init__.py +24 -22
  16. package/python/harness/builtin/skills/entries/__init__.py +43 -28
  17. package/python/harness/builtin/skills/entries/skill.toml +2 -3
  18. package/python/harness/builtin/skills/environments/__init__.py +2 -9
  19. package/python/harness/builtin/skills/mcp/__init__.py +2 -3
  20. package/python/harness/builtin/skills/memory/__init__.py +2 -5
  21. package/python/harness/builtin/skills/web/__init__.py +92 -0
  22. package/python/harness/builtin/skills/web/skill.toml +9 -0
  23. package/python/harness/cli.py +85 -17
  24. package/python/harness/config/agent.py +36 -9
  25. package/python/harness/core/episodes.py +5 -4
  26. package/python/harness/core/lanes.py +3 -0
  27. package/python/harness/core/memory.py +5 -1
  28. package/python/harness/core/remote.py +4 -3
  29. package/python/harness/core/worker.py +58 -3
  30. package/python/harness/extensions.py +23 -2
  31. package/python/harness/host/__init__.py +43 -1
  32. package/python/harness/host/client.py +36 -6
  33. package/python/harness/host/http.py +19 -0
  34. package/python/harness/host/server.py +17 -3
  35. package/python/harness/host/sessions.py +3 -2
  36. package/python/harness/host/tasks.py +107 -26
  37. package/python/harness/host/workspaces.py +69 -7
  38. package/python/harness/model_list.py +1 -1
  39. package/python/harness/packages/manager.py +5 -1
  40. package/python/harness/providers.py +14 -5
  41. package/python/harness/runtime/decision/loop.py +105 -117
  42. package/python/harness/runtime/decision/messages.py +158 -55
  43. package/python/harness/runtime/decision/model.py +85 -22
  44. package/python/harness/runtime/decision/notices.py +66 -0
  45. package/python/harness/runtime/decision/prompts.py +15 -11
  46. package/python/harness/runtime/decision/protocol.py +12 -6
  47. package/python/harness/runtime/decision/thoughts.py +10 -16
  48. package/python/harness/runtime/events.py +28 -13
  49. package/python/harness/runtime/execution/attached.py +1 -1
  50. package/python/harness/runtime/execution/control.py +17 -35
  51. package/python/harness/runtime/execution/entries.py +204 -124
  52. package/python/harness/runtime/execution/kernel.py +471 -281
  53. package/python/harness/runtime/execution/managed.py +231 -0
  54. package/python/harness/runtime/execution/noenv.py +2 -2
  55. package/python/harness/runtime/execution/results.py +2 -0
  56. package/python/harness/runtime/execution/session.py +284 -115
  57. package/python/harness/runtime/learning/active.py +41 -50
  58. package/python/harness/runtime/learning/fixtures.py +2 -2
  59. package/python/harness/runtime/learning/learner.py +75 -2
  60. package/python/harness/runtime/learning/library.py +77 -10
  61. package/python/harness/runtime/learning/views.py +12 -1
  62. package/python/harness/runtime/reactive/__init__.py +1 -1
  63. package/python/harness/runtime/reactive/rules.py +29 -394
  64. package/python/harness/runtime/reactive/tree.py +611 -0
  65. package/python/harness/runtime/safety/approval.py +8 -3
  66. package/python/harness/runtime/safety/permissions.py +242 -0
  67. package/python/harness/runtime/status.py +7 -2
  68. package/python/harness/runtime/task/delegation.py +97 -58
  69. package/python/harness/runtime/task/environments.py +3 -4
  70. package/python/harness/runtime/task/inbound.py +64 -0
  71. package/python/harness/runtime/task/run.py +1231 -790
  72. package/python/harness/runtime/tick.py +257 -91
  73. package/python/harness/sdk/__init__.py +7 -4
  74. package/python/harness/settings.py +30 -5
  75. package/python/harness/terminal.py +10 -6
  76. package/python/harness/transcript.py +18 -6
  77. package/python/harness/tui/answer.py +51 -0
  78. package/python/harness/tui/chat.py +75 -26
  79. package/python/harness/tui/views.py +1 -0
  80. package/python/harness/builtin/prompts/shared/entries.md +0 -86
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?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
+ <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.1",
4
- "description": "Automatic Control for anything that acts",
3
+ "version": "0.83.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.1"
5
+ __version__ = "0.83.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,222 @@
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
- When a program ends you see its output, what went wrong if anything did and the state, as
12
- 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
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
- When a program ends you see its output, what went wrong if anything did, the state and
17
- 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.
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
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 by telling you. This holds at every depth,
49
+ and how far a situation is divided follows from how much you know of it. So what you
50
+ have never met is still answered, by the narrowest situation it falls in; and when you
51
+ come to know it, you divide there, where its place among everything else is already
52
+ settled. What happens to the agent whatever it is doing belongs in the tree, also when
53
+ you met it inside one program: answered there, it is answered nowhere else. What you set
54
+ out to do is not in it, however often you do it: a way of doing something that you have
55
+ learned is kept as a skill you call, not as a node. A node has done its work when its
56
+ situation is over: when its program ends and the situation is not over, a later node at
57
+ its place has the environment, or you are told what the program did. The tree is
58
+ consistent when in every situation it is settled which node has the environment: a
59
+ node's place is what it costs when it does not act now, the costlier the earlier; and a
60
+ node takes the environment only where you would, seeing everything as it is then. A
61
+ reflex acts in your place, so its condition is your whole judgement, what it interrupts
62
+ and whether this is the moment included, and what it does leaves things so that what it
63
+ interrupted can go on.
64
+
65
+ Build each thing for the situations it has to work in, and think and test in proportion
66
+ to what a failure costs: settle in the design what is cheap to settle; test what is
67
+ uncertain and matters with the smallest test that could prove it wrong, where a failure
68
+ costs little, and once. When something fails, or something arises that nothing answered,
69
+ find the first point where it differed from what you expected, say what kind of
70
+ situation that is, repair what is responsible for the kind, and look for the same flaw
71
+ elsewhere. The same kind again means the design is wrong: return to the design.
72
+
73
+ Your work is made of units. A program is a unit: it runs beside the others, with its own
74
+ output and result. One that is over within a moment gives you its result at once; a
75
+ longer one goes on, you are asked again at once with its name, and its result reaches
76
+ you when it ends. Meanwhile you are free: start another program, cancel one, or
77
+ wait. A wait ends when a unit you started ended, when a message or an event reached you,
78
+ or when its time is over, and you are told which. What a program starts (units, reflexes)
79
+ is yours: it outlives the program and the turn. After your answer it goes on,
80
+ and the end of a unit or an event starts your next turn; cancel what should not go on.
81
+
82
+ Whatever you are asked for, you are told in the same order: what your last reply came
83
+ to; then what reached you by itself since (the end of a unit, an event, a message), the
84
+ more urgent first; last, how things stand now: the state, the units that run, what
85
+ changed in the tree of reflexes. What cannot wait (an event, what the environment tells,
86
+ a unit that ended with an error) reaches you at once: a reply you were writing then is
87
+ set aside, what it held does not run, and you are asked again. The rest is told when you
88
+ are next asked.
89
+
90
+ Every unit ends with the same report, whoever started it: how it ended (by itself, an
91
+ error, an event, cancelled, its time limit), whether what it was for is the case (done:
92
+ yes or no), and what it returned. How it ended and whether it is done are two things: a
93
+ unit that ended by itself has not done its work when what it was for is not the case. A
94
+ program says what it is for with until(condition), a function of the view that holds when
95
+ its work is done; it is judged when the program ends. Without one, the report says how it
96
+ ended and nothing of done.
97
+
98
+ What you leave running is yours to supervise. Before a long program, say what should be
99
+ true while it runs. When you are asked again while it runs, check that before you wait
100
+ again: its output so far, the state, a picture where there is one. Wait no longer than
101
+ you are content not to know. When it is not doing what you expected, cancel it and plan
102
+ again. To be woken for a condition instead of checking for it, set a reflex that raises
103
+ an event.
104
+
105
+ <!-- if: machine -->
106
+ Your programs run on the machine this conversation runs on, as its user. They read its
107
+ files. What they do beyond their own folder (start a process, reach the network, write
108
+ or delete elsewhere, open a file that holds credentials) goes by the user's settings: it
109
+ happens, the user is asked first, or it is refused, and then the call raises
110
+ PermissionError with the reason.
29
111
  <!-- end -->
30
112
 
31
113
  The calls every agent has:
32
114
 
33
115
  - 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.
116
+ get_state(): the state alone; show(image): put a picture (a crop, a plot) with this
117
+ program's result.
36
118
  <!-- 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
119
+ - look(camera=None, region=None, keep=None, pin=None): put a view with this program's
120
+ result, so acting and looking are one program: all the views, one by
39
121
  name, or the part region=(x, y, width, height). A view stays for your next reply only;
40
122
  keep=N keeps the views of your last N programs in sight, pin="name" keeps this one until
41
123
  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.
124
+ - watch(cameras=None, keep=None): from now on the views come with every program's result
125
+ until unwatch().
45
126
  <!-- end -->
46
127
  <!-- 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.
128
+ - spawn(fn, name=None, priority=None, restart=False, until=None): run fn as a unit of
129
+ its own and go on (until: what it is for, as until(condition) says for a program). Its
130
+ handle: .wait(timeout=None) returns what fn returned, .cancel() ends it,
131
+ .send(message) gives it a message that receive(timeout=None) reads inside fn, .status.
132
+ entries(): the handles of the units that run, your programs among them, each with its
133
+ .id (the name you are told).
134
+ output_of(unit, chars=2000): what a unit (its id or its handle) has printed so far, the
135
+ last chars characters (at most 30000); its result still has all of it when it ends.
136
+ What you are told has a limit, and says so where it left something out: what a unit
137
+ printed or returned is told whole up to 30000 characters; more is saved to a file, and
138
+ you are told the file, which a program can read, and its first 2000 characters. Of a
139
+ unit that failed you are told the first and last 5000 characters.
140
+ <!-- if: channels -->
141
+ Where the environment has channels (CHANNELS), units act at the same time, each on the
142
+ channels it took: spawn(..., claims=[...]) or claim(*channels) takes them,
143
+ unclaim(*channels) lets them go, channels() says who has each. Reaching for a channel
144
+ another unit has is a CHANNEL_CONFLICT event.
145
+ <!-- end -->
49
146
  <!-- end -->
147
+ What acts without you is one tree, empty at first. A node of it says when it has its
148
+ turn and what it does then; a node under another has its turn only while that one's
149
+ condition holds. Among the nodes at one place the earlier takes the environment from the
150
+ later, and gives it back when it is done. What several nodes need is said once: a
151
+ condition as the node above them or as a sense, an action as a function they call.
152
+ - set_reflex(name, when, do=None, under=None, priority=0, every=None, again_seconds=0):
153
+ put the node `name` into the tree, in place of a node of that name.
154
+ when: a function of the view: the node has its turn while it holds. It is judged
155
+ without you, and the node takes the environment as soon as it holds. Or the name of an
156
+ event: the node answers that event when it happens, and you are not told of it then.
157
+ do: a program (a function): started as a unit when the node's turn comes; what it is
158
+ for is that the node's condition no longer holds. It begins again while the turn lasts,
159
+ not before again_seconds after it ended; a program that answers an event gets the event
160
+ when it takes an argument. Or the name of an event: you are
161
+ told it, once each time the condition comes to hold. Or "stop": what runs is ended.
162
+ Or nothing: the node is a group, and the nodes set with under=name are its content.
163
+ priority (a whole number, 0 or more): the node's place among those where it is, the
164
+ higher first, among equals the older. A node's program takes the environment from your
165
+ programs.
166
+ every: the seconds between judgements of its condition; without it the condition is
167
+ judged when the state or the facts change.
168
+ A condition is read, not computed: the conditions judged in one moment share a few
169
+ milliseconds between them, and may not open files, use the network, sleep or start
170
+ anything. One the moment had no time for is judged in the next. One that is slower
171
+ than that time after time, or that raises, is a fault: its node is removed with the
172
+ nodes under it and you are told (the event REACTIVE_FAULT).
173
+ You are not told when a node's program has done its work. When it ends and its
174
+ situation is not over, or it fails, a later node at its place whose condition holds has
175
+ the environment; when none has, you are told with the program's report (the event
176
+ REFLEX_FAILED), once until the node has done its work again.
177
+ - reflexes(name=None): the nodes at the top of the tree, or the nodes under the node
178
+ name (the node itself where it has none under it), at most 50 at a time: each with
179
+ whether its condition holds, whether its program runs, how often it began, the report
180
+ of its last run and the names of the nodes under it. With every turn you are told how
181
+ many nodes act in the tree and, of those that changed since you were last told, how
182
+ often each one's program began, did its work and did not (at most 10; reflexes() has
183
+ the rest). drop_reflex(names=None): remove nodes with the nodes under them (None: all).
184
+ - facts.set(name, value), facts.get(name, default=None), facts.drop(name): what the run
185
+ knows, shared by your programs and reflexes (view["facts"]). Keep progress there, so that
186
+ what you start again goes on from what was done.
187
+ <!-- if: senses -->
188
+ - sense(name, code): have the environment compute a value itself, each time it reports
189
+ its state: view["sensed"][name] for conditions, get_state()["sensed"][name] for
190
+ programs. `code` is in the environment's own language and reads the environment
191
+ directly (the environment's own page says what the code has). It returns {"value": as
192
+ computed now, "error"}. senses(): those defined, with their code and values;
193
+ drop_sense(name).
194
+ <!-- end -->
195
+ - run_controller(fn, until=None, max_seconds=None): apply the command returned by fn(view)
196
+ for each step. Return None to end it. A reflex or until(view) can end the execution.
197
+ A unit of higher priority (a reflex's program) takes the environment from a lower one and
198
+ holds it until it ends.
199
+ <!-- if: pauses -->
200
+ The lower call is suspended where it is and goes on by itself when the higher unit has
201
+ ended: its program does not end, and you are not asked.
202
+ <!-- else -->
203
+ The lower call ends there with the event PREEMPTED and what it had done, and you are told
204
+ at once: which reflex took the environment, from which program, and the state. You decide
205
+ what goes on: the same again, or something else. Only a unit started with restart=True
206
+ has its call started again by itself then (its result counts it: .restarts).
207
+ <!-- end -->
208
+ What you start meanwhile waits for the higher unit to end. Units of equal priority take
209
+ turns.
210
+ Your programs have priority 0, so every reflex takes the environment from them. A
211
+ program has its place among the reflexes like a node: at_priority(n) gives it one, from
212
+ that call to its end. A reflex at the top of the tree with priority n or more, and what is
213
+ under it, still takes the environment from the program, which goes on as said above. A
214
+ reflex below n waits: it is judged again when the program has ended, and you are told
215
+ once that it was held back (the event HELD_BACK); cancelling the program lets it act. So a
216
+ program that does itself what some reflexes answer stands above those and below the rest:
217
+ what happens to the agent and is not the program's business still has its reflex.
218
+ Conditions and controllers read the supplied view. Keep them fast and free of file,
219
+ network, process and input operations.
50
220
  <!-- if: memory -->
51
221
  <!-- if: legacy_memory -->
52
222
  - recall(query): what earlier runs kept about a situation like this one.
@@ -68,21 +238,3 @@ The calls every agent has:
68
238
  More on learning below.
69
239
  <!-- end -->
70
240
  <!-- 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
  ]
@@ -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,23 +12,23 @@ 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 -->
37
28
  Code must define one public function with a one-line docstring.
38
29
  <!-- else -->
39
30
  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.
31
+ When a frequently useful part of a skill can decide what to do using only the current view, consider a reflex (set_reflex).
41
32
  Cite the outcomes that support the proposal in its docstring. Code defines one public function with a docstring.
42
33
  For code, follow the entry with <test>Python invocation and observable success condition</test>.
43
34
  The host independently checks the behavior. Use <none/> when the evidence does not support an addition.
@@ -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,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
+