@lmmslab/harness 0.85.1 → 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.
- package/package.json +1 -1
- package/python/harness/__init__.py +2 -2
- package/python/harness/bench.py +2 -2
- package/python/harness/builtin/benches/README.md +1 -2
- package/python/harness/builtin/configs/default.toml +4 -19
- package/python/harness/builtin/configs/deploy/example-api.toml +1 -1
- package/python/harness/builtin/configs/models/deepseek-flash.toml +1 -1
- package/python/harness/builtin/configs/models/grok-low.toml +1 -1
- package/python/harness/builtin/configs/models/grok-medium.toml +3 -6
- package/python/harness/builtin/environment/README.md +8 -25
- package/python/harness/builtin/prompts/conversation/core.md +6 -5
- package/python/harness/builtin/prompts/core/core.md +147 -203
- package/python/harness/builtin/prompts/core/pack.toml +0 -1
- package/python/harness/builtin/prompts/reflect/core.md +8 -32
- package/python/harness/builtin/prompts/reflect/pack.toml +2 -4
- package/python/harness/builtin/prompts/shared/agent-skills.md +5 -3
- package/python/harness/builtin/prompts/shared/agents.md +20 -10
- package/python/harness/builtin/prompts/shared/checklist.md +13 -17
- package/python/harness/builtin/prompts/shared/environments.md +20 -15
- package/python/harness/builtin/prompts/shared/learning-goal.md +2 -3
- package/python/harness/builtin/prompts/shared/learning.md +73 -23
- package/python/harness/builtin/prompts/shared/mcp.md +11 -6
- package/python/harness/builtin/prompts/shared/reflex-method.md +243 -0
- package/python/harness/builtin/prompts/shared/units.md +138 -0
- package/python/harness/builtin/prompts/shared/web.md +5 -6
- package/python/harness/builtin/skills/agents/__init__.py +18 -3
- package/python/harness/builtin/skills/agents/skill.toml +3 -3
- package/python/harness/builtin/skills/checklist/__init__.py +34 -32
- package/python/harness/builtin/skills/checklist/skill.toml +9 -9
- package/python/harness/builtin/skills/environments/__init__.py +9 -5
- package/python/harness/builtin/skills/environments/skill.toml +1 -1
- package/python/harness/builtin/skills/experience/skill.toml +1 -1
- package/python/harness/builtin/skills/learning/__init__.py +19 -5
- package/python/harness/builtin/skills/mcp/skill.toml +1 -1
- package/python/harness/builtin/skills/memory/__init__.py +4 -1
- package/python/harness/builtin/skills/memory/skill.toml +0 -5
- package/python/harness/builtin/skills/verify/skill.toml +1 -0
- package/python/harness/builtin/skills/web/__init__.py +4 -1
- package/python/harness/builtin/third_party/sources.toml +2 -40
- package/python/harness/cli.py +16 -25
- package/python/harness/config/__init__.py +2 -2
- package/python/harness/config/agent.py +59 -47
- package/python/harness/core/__init__.py +1 -1
- package/python/harness/core/codec.py +4 -4
- package/python/harness/core/contracts.py +1 -1
- package/python/harness/core/media.py +1 -1
- package/python/harness/core/ports.py +2 -2
- package/python/harness/core/procs.py +1 -1
- package/python/harness/core/remote.py +1 -1
- package/python/harness/core/worker.py +19 -13
- package/python/harness/embodiments.py +53 -44
- package/python/harness/extensions.py +22 -0
- package/python/harness/host/__init__.py +1 -1
- package/python/harness/host/http.py +6 -12
- package/python/harness/host/sessions.py +1 -1
- package/python/harness/host/tasks.py +15 -11
- package/python/harness/host/workspaces.py +36 -8
- package/python/harness/packages/__init__.py +5 -5
- package/python/harness/packages/environments.py +30 -18
- package/python/harness/packages/manager.py +1 -1
- package/python/harness/packages/manifest.py +6 -6
- package/python/harness/packages/provision.py +1 -1
- package/python/harness/packages/sources.py +1 -1
- package/python/harness/paths.py +1 -1
- package/python/harness/runtime/decision/loop.py +95 -5
- package/python/harness/runtime/decision/messages.py +128 -2
- package/python/harness/runtime/decision/model.py +4 -5
- package/python/harness/runtime/decision/prompts.py +20 -32
- package/python/harness/runtime/events.py +7 -5
- package/python/harness/runtime/execution/attached.py +3 -3
- package/python/harness/runtime/execution/entries.py +189 -8
- package/python/harness/runtime/execution/kernel.py +26 -1
- package/python/harness/runtime/execution/results.py +2 -3
- package/python/harness/runtime/execution/session.py +417 -32
- package/python/harness/runtime/execution/skills.py +63 -16
- package/python/harness/runtime/learning/active.py +7 -7
- package/python/harness/runtime/learning/learner.py +3 -2
- package/python/harness/runtime/learning/library.py +9 -4
- package/python/harness/runtime/learning/reflect.py +10 -9
- package/python/harness/runtime/reactive/rules.py +4 -4
- package/python/harness/runtime/reactive/tree.py +506 -25
- package/python/harness/runtime/safety/input.py +1 -1
- package/python/harness/runtime/safety/isolation.py +3 -3
- package/python/harness/runtime/safety/shield.py +4 -50
- package/python/harness/runtime/task/delegation.py +5 -5
- package/python/harness/runtime/task/environments.py +10 -0
- package/python/harness/runtime/task/run.py +222 -27
- package/python/harness/runtime/tick.py +24 -1
- package/python/harness/sdk/__init__.py +2 -5
- package/python/harness/services/registry.py +23 -19
- package/python/harness/settings.py +9 -9
- package/python/harness/builtin/environment/constraints.txt +0 -31
- 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.
|
|
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
|
-
|
|
7
|
-
folder:
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
kind.NAME(...), described
|
|
12
|
-
|
|
13
|
-
|
|
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
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2
|
-
|
|
3
|
-
holds
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
5
|
-
text with the addresses of its links, anything
|
|
6
|
-
it is; at most 100000 characters from
|
|
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),
|
|
35
|
-
|
|
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}
|