@lmmslab/harness 0.85.0 → 0.86.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 (94) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +2 -2
  4. package/python/harness/bench.py +2 -2
  5. package/python/harness/builtin/benches/README.md +1 -2
  6. package/python/harness/builtin/configs/default.toml +4 -19
  7. package/python/harness/builtin/configs/deploy/example-api.toml +1 -1
  8. package/python/harness/builtin/configs/models/deepseek-flash.toml +1 -1
  9. package/python/harness/builtin/configs/models/grok-low.toml +1 -1
  10. package/python/harness/builtin/configs/models/grok-medium.toml +3 -6
  11. package/python/harness/builtin/environment/README.md +8 -25
  12. package/python/harness/builtin/prompts/conversation/core.md +6 -5
  13. package/python/harness/builtin/prompts/core/core.md +147 -203
  14. package/python/harness/builtin/prompts/core/pack.toml +0 -1
  15. package/python/harness/builtin/prompts/reflect/core.md +8 -32
  16. package/python/harness/builtin/prompts/reflect/pack.toml +2 -4
  17. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -3
  18. package/python/harness/builtin/prompts/shared/agents.md +20 -10
  19. package/python/harness/builtin/prompts/shared/checklist.md +13 -17
  20. package/python/harness/builtin/prompts/shared/environments.md +20 -15
  21. package/python/harness/builtin/prompts/shared/learning-goal.md +2 -3
  22. package/python/harness/builtin/prompts/shared/learning.md +73 -23
  23. package/python/harness/builtin/prompts/shared/mcp.md +11 -6
  24. package/python/harness/builtin/prompts/shared/reflex-method.md +243 -0
  25. package/python/harness/builtin/prompts/shared/units.md +138 -0
  26. package/python/harness/builtin/prompts/shared/web.md +5 -6
  27. package/python/harness/builtin/skills/agents/__init__.py +18 -3
  28. package/python/harness/builtin/skills/agents/skill.toml +3 -3
  29. package/python/harness/builtin/skills/checklist/__init__.py +34 -32
  30. package/python/harness/builtin/skills/checklist/skill.toml +9 -9
  31. package/python/harness/builtin/skills/environments/__init__.py +9 -5
  32. package/python/harness/builtin/skills/environments/skill.toml +1 -1
  33. package/python/harness/builtin/skills/experience/skill.toml +1 -1
  34. package/python/harness/builtin/skills/learning/__init__.py +19 -5
  35. package/python/harness/builtin/skills/mcp/skill.toml +1 -1
  36. package/python/harness/builtin/skills/memory/__init__.py +4 -1
  37. package/python/harness/builtin/skills/memory/skill.toml +0 -5
  38. package/python/harness/builtin/skills/verify/skill.toml +1 -0
  39. package/python/harness/builtin/skills/web/__init__.py +4 -1
  40. package/python/harness/builtin/third_party/sources.toml +2 -40
  41. package/python/harness/cli.py +16 -25
  42. package/python/harness/config/__init__.py +2 -2
  43. package/python/harness/config/agent.py +59 -47
  44. package/python/harness/core/__init__.py +1 -1
  45. package/python/harness/core/codec.py +4 -4
  46. package/python/harness/core/contracts.py +1 -1
  47. package/python/harness/core/media.py +1 -1
  48. package/python/harness/core/ports.py +2 -2
  49. package/python/harness/core/procs.py +1 -1
  50. package/python/harness/core/remote.py +1 -1
  51. package/python/harness/core/worker.py +19 -13
  52. package/python/harness/embodiments.py +53 -44
  53. package/python/harness/extensions.py +22 -0
  54. package/python/harness/host/__init__.py +1 -1
  55. package/python/harness/host/http.py +6 -12
  56. package/python/harness/host/sessions.py +1 -1
  57. package/python/harness/host/tasks.py +15 -11
  58. package/python/harness/host/workspaces.py +36 -8
  59. package/python/harness/packages/__init__.py +5 -5
  60. package/python/harness/packages/environments.py +30 -18
  61. package/python/harness/packages/manager.py +1 -1
  62. package/python/harness/packages/manifest.py +6 -6
  63. package/python/harness/packages/provision.py +1 -1
  64. package/python/harness/packages/sources.py +1 -1
  65. package/python/harness/paths.py +1 -1
  66. package/python/harness/runtime/decision/loop.py +95 -5
  67. package/python/harness/runtime/decision/messages.py +128 -2
  68. package/python/harness/runtime/decision/model.py +4 -5
  69. package/python/harness/runtime/decision/prompts.py +20 -32
  70. package/python/harness/runtime/events.py +7 -5
  71. package/python/harness/runtime/execution/attached.py +3 -3
  72. package/python/harness/runtime/execution/entries.py +189 -8
  73. package/python/harness/runtime/execution/kernel.py +26 -1
  74. package/python/harness/runtime/execution/results.py +2 -3
  75. package/python/harness/runtime/execution/session.py +417 -32
  76. package/python/harness/runtime/execution/skills.py +63 -16
  77. package/python/harness/runtime/learning/active.py +7 -7
  78. package/python/harness/runtime/learning/learner.py +3 -2
  79. package/python/harness/runtime/learning/library.py +9 -4
  80. package/python/harness/runtime/learning/reflect.py +10 -9
  81. package/python/harness/runtime/reactive/rules.py +4 -4
  82. package/python/harness/runtime/reactive/tree.py +506 -25
  83. package/python/harness/runtime/safety/input.py +1 -1
  84. package/python/harness/runtime/safety/isolation.py +3 -3
  85. package/python/harness/runtime/safety/shield.py +4 -50
  86. package/python/harness/runtime/task/delegation.py +5 -5
  87. package/python/harness/runtime/task/environments.py +10 -0
  88. package/python/harness/runtime/task/run.py +222 -27
  89. package/python/harness/runtime/tick.py +24 -1
  90. package/python/harness/sdk/__init__.py +2 -5
  91. package/python/harness/services/registry.py +23 -19
  92. package/python/harness/settings.py +9 -9
  93. package/python/harness/builtin/environment/constraints.txt +0 -31
  94. package/python/harness/builtin/prompts/shared/world.md +0 -1
@@ -1,21 +1,26 @@
1
1
 
2
- You work in the environment the user chose. Take another one only when a step cannot be
3
- done here; what a command, a file or this environment's own calls can confirm, confirm
4
- there.
2
+ You work in the environment the user chose. You can take another one into this conversation.
5
3
 
6
- use_environment(kind, why, folder=None) take "project" (files and commands in one
7
- folder: give folder), "browser" (an isolated background
8
- browser), "desktop" (the user's screen), "apps" or
9
- "display" into this conversation. why: one sentence the
10
- user reads if they are asked. Its calls are then
11
- kind.NAME(...), described once it is attached. A refusal
12
- raises ValueError with the reason: go on without it and
13
- say in your answer what you could not confirm.
4
+ environment_kinds() the kinds this installation gives: [{"kind", "about",
5
+ "folder"}] (folder: it works in one folder)
6
+ use_environment(kind, why, folder=None)
7
+ take one of those kinds. why: one sentence the user
8
+ reads if they are asked. folder: for a kind that works
9
+ in one. Its calls are then kind.NAME(...), described
10
+ once it is attached. A refusal raises ValueError with
11
+ the reason.
14
12
  release_environment(kind) give it back when the step is done
15
13
  <!-- if: agents -->
16
14
  <!-- else -->
17
- request_agents(why) sub-agents are off; ask the user to switch them on only
18
- when the task splits into parts that can run at the
19
- same time. Another environment is no reason: take it
20
- yourself.
15
+ request_agents(why) sub-agents are off: ask the user to switch them on
16
+ <!-- end -->
17
+
18
+ - Take another environment only when a step cannot be done in this one.
19
+ - What a command, a file or this environment's own calls can confirm, confirm there.
20
+ - When an environment is refused, go on without it and say in your answer what you could
21
+ not confirm.
22
+ <!-- if: agents -->
23
+ <!-- else -->
24
+ - Ask for sub-agents only when the task splits into parts that can run at the same time.
25
+ Needing another environment is no reason: take it yourself.
21
26
  <!-- end -->
@@ -1,7 +1,6 @@
1
1
  This run is practice for a task, not the task itself: {task}
2
2
 
3
- What your library holds and what the environment keeps for you when this run is over is what the runs that do the task start with.
4
-
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.
3
+ The runs that do the task start with what your library holds and what the environment keeps for you when this run is over.
4
+ Practice from a better start than the task gives proves nothing.
6
5
  {probe}
7
6
  {sandbox}
@@ -1,25 +1,75 @@
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:
4
- library.propose(kind, name, text, test=None, summary="")
5
- kind "note": a sentence or two you want in your instructions from now on (what a
1
+
2
+ Your library keeps what you learned, for your later programs and for later runs. What it
3
+ holds is listed at the start.
4
+
5
+ How to learn.
6
+ When a step of your work needs something your library does not hold, learn it this
7
+ way. What the library holds you use as it is, and fix when it falls short.
8
+ 1. Take the goals of your plan that the library does not cover, in order.
9
+ 2. Before you start one, think it through and write down, with the goal:
10
+ - what has to be done, and the hardest form of it you expect;
11
+ - how it can fail, and what will show that it did not work;
12
+ - what can happen to the agent there faster than you can reply: add it to
13
+ situations(...) and set a node of the tree for each before the agent goes there;
14
+ - what it costs: time, and what gets used up.
15
+ Then argue against this plan: name what is most likely to make it fail, and change
16
+ the plan for that.
17
+ 3. Build a skill for each thing that has to be done. Each takes its case as arguments
18
+ and reports in numbers what it did and what is left to do. When skills have worked
19
+ one after the other, build the skill that calls them in that order.
20
+ 4. Try each skill on the hardest form first, in the smallest setup that shows it.
21
+ 5. When a try fails, find what the plan assumed that was not so, and correct the plan
22
+ before you change the skill.
23
+ 6. Keep what passed at once: the skill, the tree as it stands, and a note of what you
24
+ found out.
25
+ 7. Mark the goal in your plan, note how long it took, and go to the next.
26
+
27
+ What counts as learned:
28
+ - A way of doing something is learned when it worked without help, starting from what
29
+ the steps before it really leave behind.
30
+ - Where its result depends on chance, repeat it until you can tell it was not luck.
31
+ - Where the environment lets you set up that starting situation directly, do that
32
+ instead of working your way to it each time.
33
+ - The nodes of the tree of reflexes are not learned this way: follow the page on the tree.
34
+
35
+ library.propose(kind, name, text, test=None, summary="", setup=None)
36
+ propose an entry
37
+ library.entries() proposals and admitted entries with their evidence
38
+
39
+ The kinds of entry:
40
+ - "note": a sentence or two that you want in your instructions from now on (what a
41
+ control does, a rule of this place).
6
42
  <!-- if: legacy_memory -->
7
- control does, a rule of this place); "memory": a situation and what worked in it,
8
- for recall(query); "skill": code (functions, or a ClosedLoop class) your programs call
9
- <!-- else -->
10
- control does, a rule of this place); "skill": code (functions, or a ClosedLoop class) your programs call
43
+ - "memory": a situation and what worked in it, for recall(query).
11
44
  <!-- end -->
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
15
- until a trusted host verifies the exact revision. A successful proposal can return
16
- {"ok": True, "queued": True}. End that program to give the host its verification
17
- boundary. Use a skill in a later program once the active library lists it.
18
- For a practice scene, supply setup with the test. Its code can call
19
- sandbox(op, **arguments) when the verifier provides a compatible environment.
20
- library.entries() proposals and admitted entries with their evidence
21
- ClosedLoop is a skill that acts as a closed loop: a subclass fills in confirm() (the
22
- target is what you think: True or the reason not to act), do() (the action), check() (the
23
- world changed as it should: True or why not) and recover(reason) (between tries); `tries`
24
- and `max_seconds` bound it, and calling the class runs it and returns a Result: .ok,
25
- .reason, .tries, .seconds, .detail.
45
+ - "skill": code (functions, or a ClosedLoop class) that your programs call by name. Give
46
+ it a test: one case that calls the skill and checks what it is for. For a practice
47
+ scene, give setup with the test; its code can call sandbox(op, **arguments) when the
48
+ verifier provides a compatible environment.
49
+ - "reactive": the lines that set nodes of the tree of reflexes (set_reflex). Give no
50
+ test. Propose the lines that set the nodes as they are in the tree: they are kept as
51
+ they stand there, and nothing of them is run again. Lines that set a node otherwise
52
+ than it is in the tree are not kept, and neither is a node that did not work in a
53
+ trial it had. Kept nodes are set again by themselves when a later session starts.
54
+ The text is code that is run when it is loaded. At its top level it defines
55
+ functions and calls situations(...) and set_reflex(...), and nothing else: no other
56
+ call, no print. A function is given by its name or as a lambda, not by calling
57
+ another function that makes it. Put the situations(...) call first, so that the
58
+ list comes back with the nodes that answer it:
59
+ def low(view): return view["facts"].get("level", 9) < 3
60
+ def refill(): return fill()
61
+ situations("the level is low")
62
+ set_reflex("refill", low, refill, tell="never", tell_failed="never", covers=[1])
63
+
64
+ After proposing code:
65
+ - The host checks it between programs: the proposal returns {"ok": True, "queued":
66
+ True}. End the program after proposing.
67
+ - Use the entry in a later program, once the library lists it.
68
+
69
+ ClosedLoop is the base of a skill that acts, checks and tries again. A subclass fills in:
70
+ - confirm(): the target is what you think. True, or the reason not to act.
71
+ - do(): the action.
72
+ - check(): the world changed as it should. True, or why not.
73
+ - recover(reason): what to do between tries.
74
+ - `tries` and `max_seconds` bound it. Calling the class runs it and returns a Result:
75
+ .ok, .reason, .tries, .seconds, .detail.
@@ -1,9 +1,14 @@
1
1
 
2
- Explicit connections the user configured (MCP servers, listed at the end):
3
- Images returned in content are attached to your next observation automatically. Inspect isError
4
- and the native receipt before proceeding. A transport error after dispatch has an unknown
5
- outcome: observe before any new action, never blindly replay it. Print useful text or
6
- structuredContent; do not print base64 image data. Tools on the same resource serialize.
2
+ The tools of the MCP servers the user connected. The servers are listed at the end.
7
3
 
8
4
  mcp_tools() every tool: name, server, description, input_schema
9
- mcp_call(tool, **arguments) call one; returns the complete MCP result: content, structuredContent, isError
5
+ mcp_call(tool, **arguments) call one; returns the whole MCP result: content,
6
+ structuredContent, isError
7
+
8
+ - Read isError in the result before you go on.
9
+ - If a call fails with a transport error after it was sent, you do not know whether it
10
+ took effect. Look at what it changed before anything else; do not send the same call
11
+ again without looking.
12
+ - Images in a result's content are attached to your next observation by themselves.
13
+ Print the text or structuredContent you need; do not print base64 image data.
14
+ - Calls to tools that share a resource run one after another.
@@ -0,0 +1,243 @@
1
+ guide("tree"): how to design and set the tree of reflexes.
2
+
3
+ The tree acts for the agent while you are not there. Your reply takes seconds; during
4
+ those seconds only the tree can act. Build it before the agent starts work that depends
5
+ on it.
6
+
7
+ 1. Plan the whole tree.
8
+
9
+ - List everything that can happen to the agent during the whole task, not only during
10
+ the part it is in now: to its own condition, to the place it stands on, from what is
11
+ around it, and to what it is doing. Give the list to situations(...), one line for
12
+ each: set_reflex is refused until you have.
13
+ - Group the list from wide to narrow. Make one node for each wide kind of thing that
14
+ can happen. Under it, put one node for each narrower case that you know a better
15
+ action for.
16
+ - Check the plan: for each thing on the list, name the node it falls into. Add a node
17
+ for whatever falls into none. Each node names the lines it answers (covers=), and
18
+ situations() returns the lines nothing answers yet. A line that needs no node is given
19
+ with its reason: (line, reason). While a line has nothing that answers it, a program
20
+ that acts on the environment is refused.
21
+ - Put only what happens to the agent into the tree. What you set out to do belongs in
22
+ your programs and skills.
23
+
24
+ 2. Write each node. Every node needs these four things.
25
+
26
+ The condition (when=).
27
+ - It is true exactly while the agent is in the situation, and false once the situation
28
+ is over and stays over.
29
+ - Write it from what is happening to the agent, as the state shows it.
30
+ - Put what several nodes share into the node above them. Each node under it then tests
31
+ only what makes it different.
32
+ - It must work on every state, also when a value it reads is missing. When you set a
33
+ node, its condition is run once on the current state. If it raises, the node is
34
+ refused and nothing is set.
35
+
36
+ The action (do=).
37
+ - A function that gets the agent out of the situation. Every node has one. A node
38
+ without one is refused.
39
+ - Write it for the worst form of the situation you expect.
40
+ - If you do not know the right action yet, write what you would do yourself at that
41
+ moment. A rough action is better than none; improve it later.
42
+ - A node that has nodes under it needs an action that works whatever the cause. It runs
43
+ in two cases: when no node under it applies, and when a node under it ran and the
44
+ agent is still in the situation.
45
+ - Do not give such a node the name of an event as its action. That only tells you, and
46
+ by the time you reply it is too late.
47
+
48
+ What happens to the work it interrupts (ends=). Decide this for each node, by asking
49
+ whether that work is still correct after the node's action.
50
+ - ends=False: after the action, the interrupted work goes on from where it stopped. Use
51
+ it when the action leaves everything that work relies on as it was.
52
+ - ends=True: the interrupted work is ended and you are told at once. Use it when the
53
+ action changes something that work relies on, so that going on from where it stopped
54
+ would be wrong.
55
+
56
+ What you are told (tell=, tell_failed=). Decide this for each node, by asking what you
57
+ would do with the news.
58
+ - tell is for when the action worked.
59
+ "never": you are not told. Use it when you would do nothing with the news.
60
+ "first": you are told the first time only. This is the default.
61
+ "later" or "next": you are told every time, without being interrupted. Use it when you
62
+ want the news for later decisions and nothing you are doing now depends on it.
63
+ "now": you are told every time, and each time the reply you are writing is dropped.
64
+ Use it only when the news means you have to change what you are doing right now.
65
+ - tell_failed is for when the action did not get the agent out of the situation and no
66
+ other node took over. It takes "now" (the default), "next", "later" or "never", with
67
+ the same meaning as for tell.
68
+
69
+ What you read when you are told (about=, report=). Write both for every node that tells
70
+ you anything: every node but one with tell="never" and tell_failed="never". A node that
71
+ tells and has not both is refused.
72
+ - about: one sentence, the situation the node answers. You read it in every message about
73
+ the node.
74
+ - report: the message you read when you are told of this node. Write it for this node's
75
+ situation: put in it what you will need at that moment to judge whether the situation
76
+ is over and to decide what to do next.
77
+ It is a function, called at the moment you are told as report(view, returned): view
78
+ is the state then, returned is what the node's program returned (None for a node
79
+ without a program).
80
+ A message is text, plain data, a picture, a file, or a list of these in the order you
81
+ want them: a picture is what look(...) or get_observation() returns, or an image you
82
+ made; a file is a pathlib.Path (an image file is shown, a folder is listed, any other
83
+ file is given as its text). At most 2000 characters of text, 4 pictures and 4 files.
84
+ - A message about a node says, in this order: the node with its sentence and how its
85
+ program ended; which of your programs it took the environment from, how often so far
86
+ and for how long; the node's report; that program's own report (guide("units"):
87
+ until(report=)).
88
+
89
+ 3. Set the tree.
90
+
91
+ - Set every node you planned: the wide ones first, then the ones under them. Do not stop
92
+ to perfect one node before the rest are set. A situation with no node has nothing
93
+ acting for it.
94
+ - A test is optional. To test a node, pass test= a function that creates the node's
95
+ situation once, in an ordinary form, where a failure costs little. set_reflex runs it
96
+ at once and returns what happened: whether the node reacted, how long that took, and
97
+ whether the situation was over afterwards.
98
+ - If the situation was over, the node has passed. Move on. Do not test it again to make
99
+ it better, and do not add protection that goes beyond getting the agent out.
100
+ - If the situation was not over, fix the node.
101
+ - If the test passed but the agent is plainly still in the situation, the condition is
102
+ wrong. Fix the condition.
103
+ - The first time a node acts for real, you are told what it did, unless its tell says
104
+ otherwise. Compare that with what you intended.
105
+
106
+ 4. Watch your own work.
107
+
108
+ Every program reports when it ends, whether it succeeded or not. To hear before the end
109
+ that something you started is getting nowhere, set a node whose condition says "this
110
+ should have happened by now and has not", and give it the name of an event as do=. You
111
+ are told that event. This is the only place to use an event name as do=.
112
+
113
+ 5. Revise the tree.
114
+
115
+ Fix one node when only that node is wrong: its action failed, or it acted differently
116
+ from what you intended.
117
+ - A node acted when it should not have, or took the environment from work it should have
118
+ left alone: change that node. Narrow its condition, change its action, or put it under
119
+ the node whose situation it belongs to. Then run the work again.
120
+
121
+ Before the agent enters conditions it has not been in (another place, another stage of
122
+ the task), do step 1 for those conditions: add their lines to situations(...) and set
123
+ the nodes, then enter. Where the environment names a part of its state as the agent's
124
+ situation, the list counts for the values that part had when you gave the list: once it
125
+ has another value, a program that acts is refused until you give the list again.
126
+
127
+ Go back to step 1 and check the whole plan when one of these happens. Each of them means
128
+ the plan missed something, and fixing one node will not cover it.
129
+ - Something happened to the agent that no node covered.
130
+ - A problem you already fixed in a node shows up again, in that node or in another.
131
+ - You are told that a part of the state has a value it has not had before in this run
132
+ (the message names it and gives the value). The agent is now in conditions the plan
133
+ was not made for. List what can happen to it there and add the nodes that are missing.
134
+
135
+ 6. Reference: every call and setting of the tree.
136
+
137
+ There is one tree of reflexes, empty at first.
138
+ - A node has a condition (when it acts) and an action (what it does).
139
+ - A node can have nodes under it. A node under another is checked only while the upper
140
+ node's condition is true, and it goes first. The upper node's own action runs when no
141
+ node under it is acting, and gives way when one of them starts.
142
+ - Among the nodes at one place, the earlier takes the environment from the later and
143
+ gives it back when it is done.
144
+ - A value that several nodes read is defined once, as a sense. An action that several
145
+ nodes take is written once, as a function they call.
146
+ - set_reflex(name, when, do, under=None, priority=0, every=None, again_seconds=0,
147
+ ends=False, tell=None, tell_failed="now", about=None, report=None, test=None,
148
+ covers=None):
149
+ put the node `name` into the tree, in place of a node of that name.
150
+ covers: the lines of situations() this node answers, each by its text or by its
151
+ number (1 for the first).
152
+ again_seconds: counted from the moment the node's program ended. While that program
153
+ runs, or is paused because a higher unit has the environment, the node does not begin
154
+ again. After the program ended with the situation over, the node may begin again
155
+ after again_seconds, and not before 0.2 seconds. After a program that failed, not
156
+ before 2 seconds. A program that a higher unit ended may begin again after 0.2
157
+ seconds. A node that tells an event tells it again not before again_seconds.
158
+ when: a function of the view: the node has its turn while it holds. It is judged
159
+ without you, and the node takes the environment as soon as it holds. Beside the state
160
+ as it is, the view holds what a state alone does not show: view["was"][key], what that
161
+ part of the state was before it last changed; view["unchanged"][key], for how many
162
+ seconds it has not changed (the senses under ["sensed"] in both); and view["units"], the
163
+ units that run, each {"name", "kind", "reflex", "priority", "seconds"}. Or the name of
164
+ an event: the node answers that event when it happens, and you are not told of it then.
165
+ do: a program (a function): started as a unit when the node's turn comes; what it is
166
+ for is that the node's situation is over: its condition, or that of a node it is under,
167
+ no longer holds. It begins again while the turn lasts,
168
+ not before again_seconds after it ended; a program that answers an event gets the event
169
+ when it takes an argument. Or the name of an event: you are told it, once each time
170
+ its turn comes, which is when its condition holds and no node under it or before it at
171
+ its place is answering. Or "stop": what runs is ended.
172
+ Every node needs a do=: a node set without one is refused. For anything that happens
173
+ to the agent, do= is a function, also on a node that has nodes under it: there it runs
174
+ when no node under it applies, and when one of them ran and the agent is still in the
175
+ situation. Use the name of an event as do= only to watch your own work (section 4).
176
+ under: the node `name` is a narrower situation within that one. A node may be put
177
+ under any node whose `when` is a condition, whatever that node does itself and without
178
+ setting it again.
179
+ priority (a whole number, 0 or more): the node's own, wherever it is in the tree. Of
180
+ two nodes whose turn it is the higher has the environment, among equals the earlier in
181
+ the tree; and it is the number a program's at_priority(n) is compared with. A node's
182
+ program takes the environment from your programs.
183
+ every: the seconds between judgements of its condition; without it the condition is
184
+ judged when the state or the facts change.
185
+ ends, tell, tell_failed, about, report: section 2 says what they are and how to choose
186
+ them. report is called as report(view, returned). For a
187
+ node that tells an event: ends=True ends what runs with that event, ends=False lets it
188
+ run on; tell is the place of that event in your queue ("now" when it says nothing).
189
+ The places in your queue: later (with the first call after a wait of yours), next (with
190
+ your next call), now (the reply you are writing is set aside and you are asked again).
191
+ test: a trial of the node, where you want one; none is required. A function that
192
+ brings the node's situation about: it is run at once, and set_reflex returns what it
193
+ showed: {"name", "tried": True, "turn" (the node had its turn), "seconds" (from the
194
+ trial's start to its turn), "done" (its program left the situation over, as the node's
195
+ condition says it; None for a node that tells), "last" (its program's report), "error"
196
+ (what the trial itself raised, or why the condition could not be judged)}.
197
+ When a node is set its condition is judged once on the state as it is (a node under
198
+ others: while the conditions above it hold). A condition that raises is refused and
199
+ nothing is set: a condition answers on every state it can be given.
200
+ A condition is read, not computed: the conditions judged in one moment share a few
201
+ milliseconds between them, and may not open files, use the network, sleep or start
202
+ anything. One the moment had no time for is judged in the next. A condition that
203
+ raises does not hold that once: its node stays in the tree and is judged again the next
204
+ time. One that is slower than that time after time is no longer judged, nor are the
205
+ nodes under it, until you set the node again. In both cases you are told what went
206
+ wrong, once for each reason (the event REACTIVE_FAULT), and the node's line says how
207
+ often.
208
+ What you are told of a node's work is what the node said (tell, tell_failed). When its
209
+ program ends and its situation is not over, or it fails, a later node at its place
210
+ whose condition holds has the environment, and then the node above it with its own
211
+ program. When none has, the tree could not handle what happened: you are told with the
212
+ program's report (the event REFLEX_FAILED), once until the node has done its work
213
+ again. When a node's program has done its work and the node says you are told, that is
214
+ the event REFLEX_ACTED.
215
+ - situations(*lines): say what can happen to the agent during the whole task: one line
216
+ for each, a sentence, or (sentence, reason) for one that needs no node. The list given
217
+ takes the place of the one before; without arguments nothing changes. Returns
218
+ {"lines": [{"line", "answered": the nodes that name it in covers=, or "no node:
219
+ REASON"}], "unanswered": the lines nothing answers}.
220
+ - reflexes(name=None): the nodes at the top of the tree, or the nodes under the node
221
+ name (the node itself where it has none under it), at most 50 at a time: each with
222
+ whether its condition holds, whether its program runs, how often it began, the report
223
+ of its last run and the names of the nodes under it. What the tree did without waking
224
+ you is told with your next turn: how many nodes it has, how many of them never had
225
+ their turn, how many only tell you, and of those that changed since you were last
226
+ told, how often each one's program began, did its work and did not (at most 10;
227
+ reflexes() has the rest). When nothing changed and there is nothing of that to say,
228
+ nothing is said. drop_reflex(names=None): remove nodes with the nodes under them (None:
229
+ all).
230
+ - facts.set(name, value), facts.get(name, default=None), facts.drop(name): what the run
231
+ knows, shared by your programs and reflexes (view["facts"]). Keep progress there, so that
232
+ what you start again goes on from what was done.
233
+ - sense(name, code): have the environment compute a value itself, each time it reports
234
+ its state: view["sensed"][name] for conditions, get_state()["sensed"][name] for
235
+ programs. `code` is in the environment's own language and reads the environment
236
+ directly (the environment's own page says what the code has). It returns {"value": as
237
+ computed now, "error"}. senses(): those defined, with their code and values;
238
+ drop_sense(name).
239
+ - at_priority(n): `with at_priority(n):` around one action of a program keeps reflexes
240
+ whose priority is below n from taking the environment while that action lasts. It is
241
+ for rare cases. Before you use it, ask whether the tree is wrong: when a node breaks
242
+ off your work, look at that node first and change it (section 5). guide("units") says
243
+ how.
@@ -0,0 +1,138 @@
1
+ guide("units"): how units run, what you are told of them, and how they share the environment.
2
+
3
+ Units.
4
+ - Your work runs as units. A program is a unit: it runs alongside the others, with its
5
+ own output and result.
6
+ - A program that is over within a moment gives you its result at once. A longer one
7
+ keeps running: you are asked again at once, with its name, and you get its result when
8
+ it ends.
9
+ - While it runs you can start another program, cancel one, or wait.
10
+ - A program that is to act when the running one is over begins with after(unit): it
11
+ returns when that unit has ended, however it ended, with {"ended", "done"}. Put the
12
+ expect after it, so that it checks what the earlier program left. Without after(unit),
13
+ each call that acts waits only for the call that has the environment at that moment:
14
+ two programs that each act several times take the environment in turn, call by call.
15
+ - A wait ends when a unit you started ends, when a message or an event reaches you, or
16
+ when its time is over. You are told which.
17
+ - What a program starts (units, reflexes) keeps running after the program and after your
18
+ turn. When a unit ends or an event arrives, your next turn starts. Cancel what should
19
+ not keep running.
20
+
21
+ What you are told, and in what order.
22
+ - Each time you are asked, you are told, in this order: what your last reply led to;
23
+ then what reached you by itself since (a unit ending, an event, a message), the most
24
+ urgent first; last, how things stand now: the state, the units that run, and what
25
+ changed in the tree of reflexes. While a program of yours runs, how things stand ends
26
+ with the same words each time, whatever woke you: what that program asks of you.
27
+ - What cannot wait reaches you at once: what the environment tells, a unit that ended
28
+ with an error, and an event (one from a node of the tree comes when that node's tell
29
+ says). The reply you were writing is dropped, nothing in it runs, and you are asked
30
+ again. Everything else is told the next time you are asked.
31
+ - Something that happened before comes with its count: which one of its kind it is in
32
+ this run, and when the earlier ones happened.
33
+ - Everything you were told and everything you replied in this run is kept, in order, in
34
+ one file that a program can read. The summary that stands in for an earlier part of
35
+ the conversation gives its name. To say something about the run as a whole, count from
36
+ that file; do not rely on what you remember.
37
+
38
+ How a unit ends.
39
+ - Every unit ends with the same report, whoever started it: how it ended (by itself, an
40
+ error, an event, cancelled, its time limit), whether its result is there (done: yes or
41
+ no), and what it returned.
42
+ - A unit that ended by itself is not thereby done. Read done.
43
+ - A program states its result with until(condition): a function of the view that is true
44
+ when the work is done. It is checked when the program ends.
45
+ - A program that only reads says until(None).
46
+ - A program that says neither is not started. You are told, and you send it again with
47
+ its result stated.
48
+ - A program checks what it relies on with expect(text, check), before it acts on the
49
+ environment. An action with no expect before it in the program is refused, and the
50
+ program ends there. When a check does not return True, a program that acts ends there,
51
+ with what the check found; a program that only reads (until(None)) goes on. What a
52
+ check itself does in the environment is reading. A reflex's program is held to none of
53
+ this.
54
+ - The report lists every expect with what its check showed. When all of them held and
55
+ done is no, the program relied on something it did not check, or its until does not
56
+ say the result.
57
+ - until(condition, report=None, interrupted="tell") takes two more settings.
58
+ report: the message you read whenever you are told of this program: when a reflex
59
+ takes the environment from it, when it ends, and its text also in the line of running
60
+ units. Write it for this program: put in it what you will need at that moment to judge
61
+ how far its work is and whether it still gets there.
62
+ It is a function, called at the moment you are told as report(view): view is the
63
+ state then.
64
+ A message is text, plain data, a picture, a file, or a list of these in the order you
65
+ want them: a picture is what look(...) or get_observation() returns, or an image you
66
+ made; a file is a pathlib.Path (an image file is shown, a folder is listed, any other
67
+ file is given as its text). At most 2000 characters of text, 4 pictures and 4 files.
68
+ interrupted: what happens when a reflex takes the environment from the program.
69
+ "tell" (the default): the program goes on, and you are told, in one message with what
70
+ the reflex says. You are told so of one program 3 times; the times after that are
71
+ counted and told with its end. When you are told, do not wait on as before: compare
72
+ what the program reports with what it is for, find out why the reflex had to act during
73
+ it, and decide: the program goes on as it is, the program is changed or ended, or the
74
+ node is changed.
75
+ "stop": the program ends there, and you are told at once.
76
+ "never": the program goes on, and you are not told.
77
+
78
+ While something runs.
79
+ - What you leave running is yours to follow. You are told when it ends without its
80
+ result.
81
+ - When you are asked while it runs, compare what it has done so far with its result,
82
+ from its output and from what the environment shows.
83
+ - If it is not getting there, find out why before you change it, let it go on or end it.
84
+ - Know how long it has to run, and do not wait for its end to learn that it failed:
85
+ that costs all the time it ran. Wait much shorter than its run and look; have its
86
+ report show the numbers that tell how far it is (until(report=)); set a node of the
87
+ tree that tells you when what it relies on is gone.
88
+ - When it is getting there, prepare what comes after it, with what needs no acting on
89
+ the environment: read the pages the next goal needs, write and keep the code it needs,
90
+ set the nodes for where the agent goes next, bring the plan up to date.
91
+
92
+ Units of your own.
93
+ - spawn(fn, name=None, priority=None, restart=False, until=None): run fn as a unit of
94
+ its own and go on (until: what it is for, as until(condition) says for a program). Its
95
+ handle: .wait(timeout=None) returns what fn returned, .cancel() ends it,
96
+ .send(message) gives it a message that receive(timeout=None) reads inside fn, .status.
97
+ entries(): the handles of the units that run, your programs among them, each with its
98
+ .id (the name you are told).
99
+ output_of(unit, chars=2000): what a unit (its id or its handle) has printed so far, the
100
+ last chars characters (at most 30000); its result still has all of it when it ends.
101
+ What you are told has a limit, and says so where it left something out: what a unit
102
+ printed or returned is told whole up to 30000 characters; more is saved to a file, and
103
+ you are told the file, which a program can read, and its first 2000 characters. Of a
104
+ unit that failed you are told the first and last 5000 characters.
105
+ Where the environment has channels (CHANNELS), units act at the same time, each on the
106
+ channels it took: spawn(..., claims=[...]) or claim(*channels) takes them,
107
+ unclaim(*channels) lets them go, channels() says who has each. Reaching for a channel
108
+ another unit has is a CHANNEL_CONFLICT event.
109
+
110
+ Who has the environment.
111
+ - A unit of higher priority (a reflex's program) takes the environment from a lower one
112
+ and holds it until it ends. What you start meanwhile waits for the higher unit to end.
113
+ Units of equal priority take turns.
114
+ - What becomes of the lower call depends on the environment. Your instructions say which
115
+ of the two it is.
116
+ - Where it is paused: the lower call is suspended where it is and goes on by itself when
117
+ the higher unit has ended. Its program does not end, and you are not asked.
118
+ - Where it is ended: the lower call ends there with the event PREEMPTED and what it had
119
+ done, and you are told at once: which reflex took the environment, from which program,
120
+ and the state. You decide what goes on: the same again, or something else. Only a unit
121
+ started with restart=True has its call started again by itself (its result counts it:
122
+ .restarts).
123
+ - Your programs have priority 0, so every reflex takes the environment from them.
124
+ - An action of a program that must not be broken off: put `with at_priority(n):` around
125
+ that action, and no more than that action. During the block a reflex whose own
126
+ priority is n or more still takes the environment; a reflex below n waits. It is
127
+ judged again when the block ends, and you are told once that it was held back (the
128
+ event HELD_BACK).
129
+ - While a block holds a place, nothing below it answers what happens to the agent. A
130
+ program that holds one for its whole length has taken the tree's work on itself and
131
+ must do all of it.
132
+ - at_priority is for rare cases. Before you use it, ask whether the tree is wrong: when
133
+ a node breaks off your work, look at that node first. A node that takes the
134
+ environment when it should not is changed in the tree (guide("tree"), section 5).
135
+ Use at_priority only when the node is right and this one action still must not be
136
+ broken off.
137
+ - Code that runs for long in the environment itself asks for a place the same way, where
138
+ the environment's page says how.
@@ -1,11 +1,10 @@
1
1
 
2
- The web:
2
+ The web.
3
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
4
+ fetch(url, start=0) the text of a page (http, https): an HTML page as
5
+ its text with the addresses of its links, anything
6
+ else as it is; at most 100000 characters from
7
+ character start, then how to read on
8
8
  search(query, results=5) search the web: a list of {"title", "url", "text"},
9
9
  at most results (1 to 10); ValueError where this
10
10
  conversation has no search
11
-
@@ -16,6 +16,15 @@ from harness.sdk import control
16
16
  # A sub-agent's statuses while it works on (runtime/task/delegation.py state()).
17
17
 
18
18
 
19
+ # What a reviewer is asked (Agents.review).
20
+ REVIEW = ("Review the code below. It is for: {purpose}\n\nYou have not seen how it was written: read it as it "
21
+ "is. Report, the most serious first, what in it would make it fail, do something other than what it is "
22
+ "for, or do its work much more slowly or wastefully than it could; for each, the place in the code and "
23
+ "what would show it when the code runs. Where it calls something you can read (its documentation, its "
24
+ "source), check the call against that. Do not rewrite the code. If you find nothing, say so.\n\n"
25
+ "```\n{code}\n```")
26
+
27
+
19
28
  class Agents:
20
29
  def _agents(self, operation, **detail):
21
30
  if not spans.connected():
@@ -31,8 +40,8 @@ class Agents:
31
40
 
32
41
  def delegate(self, task, workspace="new", budget=None, model=None, agent=None, multi_turn=False):
33
42
  """Start a sub-agent on `task` (what it is to do and what to report back); returns its
34
- id. `workspace`: "new" (a workspace of its own, of this one's kind), "browser",
35
- "desktop", "apps" or "display" (a new one of that kind), or "share" (it takes over the windows this agent
43
+ id. `workspace`: "new" (a workspace of its own, of this one's kind), the name
44
+ of another kind the installation has (a new one of that kind), or "share" (it takes over the windows this agent
36
45
  holds now and hands them back when its turn ends). `budget`: {"calls", "cost", "seconds"},
37
46
  taken from this agent's own (default: all that is left). `model`: another model of
38
47
  the same provider. `agent`: another harness's agent ("claude-code", "codex") that does
@@ -47,6 +56,12 @@ class Agents:
47
56
  tree.adopt_agent(agent, task)
48
57
  return agent
49
58
 
59
+ def review(self, code, purpose, budget=None):
60
+ """Have code read by a sub-agent that has not seen how it was written; returns its id
61
+ (wait_agents gives its report). It is given the code and what the code is for, not
62
+ the author's conclusions, as Claude Code has code reviewed."""
63
+ return self.delegate(REVIEW.format(purpose=" ".join(str(purpose).split()), code=str(code)), budget=budget)
64
+
50
65
  def wait_agents(self, ids=None, timeout=None):
51
66
  """Wait until the turn of each sub-agent in `ids` (default: all this agent started) is
52
67
  over, at most `timeout` seconds; returns {id: {"status", "result", "model_calls",
@@ -87,4 +102,4 @@ class Agents:
87
102
 
88
103
  def exports(session):
89
104
  return {"delegate": session.delegate, "wait_agents": session.wait_agents, "send_agent": session.send_agent,
90
- "cancel_agent": session.cancel_agent}
105
+ "cancel_agent": session.cancel_agent, "review": session.review}