@lmmslab/harness 0.0.0-stage → 0.81.1

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 (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1356 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +232 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. package/python/harness/tui/views.py +434 -0
@@ -0,0 +1,31 @@
1
+ Get to know this environment for this task, then stop: do not do the task itself in this run. The task you are learning for: {task}
2
+
3
+ You have {minutes} minutes of live time. Learn the environment the way a careful person learns a new game, app, website or machine before using it for real, and put what you learn into your library with library.propose, so the runs that do the task start with it. Nobody will tell you what to watch out for: working that out is your job.
4
+
5
+ 1. Read what there is: its help, its manual, its tutorial, its settings or controls screen. Note what you read but have not seen yet as something to check.
6
+ 2. Try every control and see what it does: compare what you see and what you read before and after each one.
7
+ {probe}
8
+ <!-- if: legacy_memory -->
9
+ 3. Think the task through before you build anything, as hard as you can, and write it down as the memory entry "situations" (library.propose("memory", "situations", text)):
10
+ <!-- else -->
11
+ 3. Think the task through before you build anything, as hard as you can, and write it down as the memory entry "situations" (remember("plan", text, name="situations", keep=True)):
12
+ <!-- end -->
13
+ - the path: the steps from where you are to the goal, each a milestone you can check by what you see or read;
14
+ - for each step, what you must be able to do (a skill each, built on the basic moves of this body: {skills}), and its hardest version you can expect: the toughest material or target, the longest distance, an action that must last or repeat, a screen or layout that differs, a slow or missing response;
15
+ - how each step can fail, and how you would notice from what you see that it did not really work;
16
+ - what can happen faster than you can think: being hurt or attacked, falling, losing what you hold, a window, dialog or error that appears, something coming at you; each of these needs a reactive rule, not a skill;
17
+ - then argue against your own plan: what would most likely make it fail? Add that too.
18
+ Mark each line with its state: [ ] not covered, [skill name] or [rule name] when an entry covers it and its test passed, [unknown] when you cannot test it here. Keep this entry up to date: propose it again whenever it changes.
19
+ 4. Cover the list. For each line, write the skill or the rule it needs:
20
+ - a skill is a closed loop (ClosedLoop) whose test calls it on the hardest version of its case and asserts on the real result in the environment (calling the class runs it: r = Walk(...); assert r.ok, r.reason), not on its return value alone;
21
+ - a reactive rule is proposed with library.propose("reactive", name, code, test=...); its test feeds it the views or events of its situation and checks that it acts then and only then;
22
+ - code proposals stay pending until an independent fixture checks them. Mark pending cases [unknown] and record what you observed in practice.
23
+ {sandbox}
24
+ <!-- if: legacy_memory -->
25
+ 5. Drill toward the task, from the first milestone on, as a player or a new user would, and seek out the hard and the dangerous situations on your list instead of waiting for them: {drills}. Use your skills; when a drill fails or something happens that your list did not foresee, add it to "situations", rewrite the entry that failed, and propose it again. Keep each drill's outcome as a memory entry (what you tried, what happened, what to do instead) as the run records skill results by revision.
26
+ <!-- else -->
27
+ 5. Drill toward the task, from the first milestone on, as a player or a new user would, and seek out the hard and the dangerous situations on your list instead of waiting for them: {drills}. Use your skills; when a drill fails or something happens that your list did not foresee, add it to "situations", rewrite the entry that failed, and propose it again. Keep each drill's outcome as a memory entry (remember(kind, text, name=..., keep=True): what you tried, what happened, what to do instead); each result of your closed loops counts as a use of its skill by itself.
28
+ <!-- end -->
29
+ 6. Stop when every line of "situations" is covered or marked [unknown], or when the time is nearly up. Finish with a short note of what you learned and what is still unknown.
30
+
31
+ After each program you are told what you have learned so far, your "situations" list and what to do next. Spend your time on controls, skills, rules and drills, not on long thinking: the live time is the budget.
@@ -0,0 +1,27 @@
1
+ Keep observations and notes you will need again. Skill and rule proposals require trusted verification before use. Use what your library already holds first: its tested skills and
2
+ rules are listed at the start; call them, and rewrite one that falls short instead of writing
3
+ new code beside it. When something happens that your memory entry "situations" did not
4
+ foresee, add it there and learn for it. Propose an entry when you learned something you will
5
+ need again:
6
+ library.propose(kind, name, text, test=None, summary="")
7
+ kind "note": a sentence or two you want in your instructions from now on (what a
8
+ <!-- if: legacy_memory -->
9
+ control does, a rule of this place); "memory": a situation and what worked in it,
10
+ for recall(query); "skill": code (functions, or a ClosedLoop class) your programs call
11
+ <!-- else -->
12
+ control does, a rule of this place); "skill": code (functions, or a ClosedLoop class) your programs call
13
+ <!-- end -->
14
+ by name; "reactive": code for the reactive layer.
15
+ Include a test that calls the skill or rule and checks its effect. Code stays pending
16
+ until a trusted host verifies the exact revision. A successful proposal can return
17
+ {"ok": True, "queued": True}. End that program to give the host its verification
18
+ boundary. Use a skill in a later program once the active library lists it.
19
+ For a practice scene, supply setup with the test. Its code can call
20
+ sandbox(op, **arguments) when the verifier provides a compatible environment.
21
+ library.entries() proposals and admitted entries with their evidence
22
+ Write a skill that acts as a closed loop: a subclass of ClosedLoop fills in confirm() (the
23
+ target is what you think: True or the reason not to act), do() (the action), check() (the
24
+ world changed as it should: True or why not) and recover(reason) (between tries); `tries`
25
+ and `max_seconds` bound it, and calling the class runs it and returns a Result: .ok,
26
+ .reason, .tries, .seconds, .detail. Keep a skill to one thing (open a menu, walk to what you
27
+ see, pick an item).
@@ -0,0 +1,9 @@
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.
7
+
8
+ mcp_tools() every tool: name, server, description, input_schema
9
+ mcp_call(tool, **arguments) call one; returns the complete MCP result: content, structuredContent, isError
@@ -0,0 +1 @@
1
+ Query the positioned observations in working memory with things(kind=None, near=None, radius=None, limit=50). Use thing(id) to inspect one observation and forget_thing(id) when it no longer holds.
@@ -0,0 +1,10 @@
1
+ # Skills
2
+
3
+ What a model's programs can call: one directory per skill, a `skill.toml` manifest and an
4
+ `__init__.py` with a mixin class. A system turns skills on by interface layer or by name;
5
+ a skill whose services are missing drops out, and the prompt drops its text with it.
6
+
7
+ - How it works: [docs/src/content/docs/concepts/skills.md](../docs/src/content/docs/concepts/skills.md)
8
+ - Write one: [docs/src/content/docs/guides/write-a-skill.md](../docs/src/content/docs/guides/write-a-skill.md)
9
+ - Every skill with its functions: the documentation site's *Reference → Skills*
10
+ (generated from these directories by `scripts/gen_docs_reference.py`)
@@ -0,0 +1,88 @@
1
+ """Sub-agents: a program hands parts of its task to agents of its own, which work at the
2
+ same time, each in a workspace of its own (or with the windows this agent hands over),
3
+ and waits for their results. The conversation that runs the program starts and keeps
4
+ them (runtime/task/delegation.py): every call here is a request to it, sent as a note, and its
5
+ answer comes back through the kernel (runtime/execution/control.py). Each sub-agent is an entry of
6
+ the session's tree (runtime/execution/entries.py) under the code that started it: when it ends, the
7
+ conversation tells the kernel, and a sub-agent that did not finish is an ENTRY_FAILED
8
+ event of that code."""
9
+
10
+ import uuid
11
+
12
+ from harness.sdk import spans
13
+ from harness.sdk import control
14
+ from harness.sdk import user_message
15
+ from harness.sdk import Escalation
16
+
17
+
18
+ # A sub-agent's statuses while it works on (runtime/task/delegation.py state()).
19
+
20
+
21
+ class Agents:
22
+ def _agents(self, operation, **detail):
23
+ if not spans.connected():
24
+ raise RuntimeError("sub-agents need the conversation that runs this program; none is connected")
25
+ identifier = uuid.uuid4().hex[:12]
26
+ tree = getattr(self, "_entries", None)
27
+ # The program's own code (not an entry it started) leaves a wait for a message for
28
+ # the model, with a USER_MESSAGE event; the sub-agents go on.
29
+ own = tree is None or tree.current() is tree.root
30
+ spans.note("agents", action=operation, id=identifier, own=own, **detail)
31
+ answer = control.wait_answer(identifier, stop=control.message_arrived if own else None)
32
+ if answer is None:
33
+ if own and control.message_arrived():
34
+ raise Escalation(user_message(f"{operation}_agents" if operation == "wait" else operation, detail))
35
+ return None
36
+ if answer.get("error"):
37
+ raise ValueError(answer["error"])
38
+ return answer.get("value")
39
+
40
+ def delegate(self, task, workspace="new", budget=None, model=None, agent=None, multi_turn=False):
41
+ """Start a sub-agent on `task` (what it is to do and what to report back); returns its
42
+ id. `workspace`: "new" (a workspace of its own, of this one's kind), "browser",
43
+ "desktop", "apps" or "display" (a new one of that kind), or "share" (it takes over the windows this agent
44
+ holds now and hands them back when it ends). `budget`: {"calls", "cost", "seconds"},
45
+ taken from this agent's own (default: all that is left). `model`: another model of
46
+ the same provider. `agent`: another harness's agent ("claude-code", "codex") that does
47
+ the task in its own bounded directory. `multi_turn=True` keeps a supported external
48
+ agent available for `send_agent` within the original budget; cancel it when done."""
49
+ agent = self._agents("delegate", task=str(task), workspace=str(workspace),
50
+ budget=budget if budget is None or isinstance(budget, (int, float)) else dict(budget),
51
+ model=None if model is None else str(model), agent=None if agent is None else str(agent),
52
+ multi_turn=multi_turn)
53
+ tree = getattr(self, "_entries", None)
54
+ if agent is not None and tree is not None:
55
+ tree.adopt_agent(agent, task)
56
+ return agent
57
+
58
+ def wait_agents(self, ids=None, timeout=None):
59
+ """Wait until each sub-agent in `ids` (default: all this agent started) has ended or
60
+ asks this agent something, at most `timeout` seconds; returns {id: {"status",
61
+ "result", "question", "model_calls", "cost_usd", "seconds", "directory", "files"}}, or
62
+ None when the user paused this agent first. A message for this agent ends the wait
63
+ at once with a USER_MESSAGE event; the sub-agents go on."""
64
+ ids = [ids] if isinstance(ids, str) else (list(ids) if ids else None)
65
+ ids = [self._agent_id(item) for item in ids] if ids else ids
66
+ return self._agents("wait", ids=ids, timeout=timeout)
67
+
68
+ def send_agent(self, agent, text):
69
+ """Send sub-agent `agent` a message (the answer to its question, or more to do)."""
70
+ return self._agents("send", agent=self._agent_id(agent), text=str(text))
71
+
72
+ def cancel_agent(self, agent):
73
+ """Stop sub-agent `agent` (and those it started); returns its report."""
74
+ return self._agents("cancel", agent=self._agent_id(agent))
75
+
76
+ def _agent_id(self, agent) -> str:
77
+ """A sub-agent by its id (a3), or by the id of its entry (e3: a program's output lists
78
+ the entries of the sub-agents it started), as the model may name it."""
79
+ tree = getattr(self, "_entries", None)
80
+ entry = tree.entries.get(str(agent)) if tree is not None else None
81
+ if entry is not None and entry.kind == "agent" and entry.agent:
82
+ return entry.agent
83
+ return str(agent)
84
+
85
+
86
+ def exports(session):
87
+ return {"delegate": session.delegate, "wait_agents": session.wait_agents, "send_agent": session.send_agent,
88
+ "cancel_agent": session.cancel_agent}
@@ -0,0 +1,11 @@
1
+ name = "agents"
2
+ summary = "Hand parts of the task to sub-agents that work at the same time, each in a workspace of its own, and wait for their results."
3
+ layer = "base"
4
+ mixin = "skills.agents:Agents"
5
+ exports = ["delegate", "wait_agents", "send_agent", "cancel_agent"]
6
+ # Where the conversation's server can give sub-agents workspaces (the app's assistant
7
+ # enables it while the nesting depth setting allows sub-agents); in a game they only look
8
+ # (runtime/viewing.py: a view of the agent's episode, every input refused).
9
+ optional = true
10
+ order = 96
11
+ embodiments = ["*"]
@@ -0,0 +1,32 @@
1
+ """A plan the user sees while the agent works: the task's steps, checked off as the
2
+ programs do them. The steps go to the host as they change (core/spans.py notes), so the
3
+ page shows them while a program still runs."""
4
+
5
+ from harness.sdk import spans
6
+
7
+
8
+ class Checklist:
9
+ def plan(self, *steps):
10
+ """Show the user your plan: the task's steps in order, short and in their language,
11
+ as strings (or one list). Call it again to change the plan; the steps done so far
12
+ stay checked when their text is the same. Returns the number of steps."""
13
+ if len(steps) == 1 and isinstance(steps[0], (list, tuple)):
14
+ steps = tuple(steps[0])
15
+ items = [" ".join(str(step).split()) for step in steps if str(step).strip()]
16
+ if not items:
17
+ raise ValueError("plan() takes the steps of the task")
18
+ done = {entry["step"] for entry in self.__dict__.get("_plan", []) if entry["done"]}
19
+ self._plan = [{"step": step, "done": step in done} for step in items]
20
+ self._send_plan()
21
+ return len(items)
22
+
23
+ def step_done(self, number):
24
+ """Check off step `number` of your plan (1 for the first)."""
25
+ steps = self.__dict__.get("_plan") or []
26
+ if not 1 <= int(number) <= len(steps):
27
+ raise ValueError(f"the plan has steps 1 to {len(steps)}" if steps else "call plan() first")
28
+ steps[int(number) - 1]["done"] = True
29
+ self._send_plan()
30
+
31
+ def _send_plan(self):
32
+ spans.note("plan", steps=[dict(entry) for entry in self._plan])
@@ -0,0 +1,9 @@
1
+ name = "checklist"
2
+ summary = "Show the user a checklist of task steps and check them off as they are done."
3
+ layer = "base"
4
+ mixin = "skills.checklist:Checklist"
5
+ exports = ["plan", "step_done"]
6
+ # Only where a user watches (the app's assistant enables it).
7
+ optional = true
8
+ order = 90
9
+ embodiments = ["*"]
@@ -0,0 +1,23 @@
1
+ """What every program of a conversation without an environment has: finish(), the (empty)
2
+ state and show(). There is nothing to act on; the connected tools are the mcp skill's."""
3
+
4
+ from harness.runtime.events import ProgramFinished
5
+
6
+
7
+ class Conversation:
8
+ def finish(self, summary=""):
9
+ """End the task now with `summary` as the answer."""
10
+ raise ProgramFinished(summary)
11
+
12
+ def _wrap_up(self):
13
+ return []
14
+
15
+ __wrap_up__ = _wrap_up
16
+
17
+ def get_state(self):
18
+ """The state: there is no environment, so only the step count."""
19
+ return dict(self.state)
20
+
21
+ def get_observation(self):
22
+ """Nothing to see: {"state", "images": {}}."""
23
+ return {"state": dict(self.state), "images": {}}
@@ -0,0 +1,8 @@
1
+ name = "conversation"
2
+ summary = "A conversation without an environment: its state, show() and finish()."
3
+ layer = "base"
4
+ mixin = "skills.conversation:Conversation"
5
+ exports = ["finish", "__wrap_up__", "get_state", "get_observation", "show"]
6
+ required = true
7
+ order = 0
8
+ embodiments = ["none"]
@@ -0,0 +1,62 @@
1
+ """Entries: parts of a program that run at the same time, as a tree (runtime/execution/entries.py).
2
+ spawn() starts one; its handle waits for it, stops it and sends it messages. What an
3
+ entry's executions end with goes to its own handlers first, then up to the entry that
4
+ started it, and only what nobody handles reaches the model. Where the embodiment declares
5
+ channels (a game's keys, mouse and wheel in groups), entries run at the same time on their
6
+ own channels: claim() and unclaim() say which an entry has."""
7
+
8
+
9
+ class Entries:
10
+ def spawn(self, fn, name=None, claims=None):
11
+ """Run fn() at the same time as this code, as an entry of its own under this one,
12
+ and return its handle: .wait(timeout=None) returns what fn returned (raises its
13
+ failure, an ENTRY_FAILED event; None when it was cancelled or the timeout passed),
14
+ .cancel() stops it and the entries it started, .send(message) gives it a message
15
+ that its code reads with receive(), .state() says how it stands, .status is
16
+ running, done, failed or cancelled. `name` labels it (default: fn's name); `claims`
17
+ names the channels it uses (the game's CHANNELS; e.g. ["move", "look"]): it has them until it
18
+ ends, and their keys and buttons are let go then; one another entry has makes it
19
+ fail at once with a CHANNEL_CONFLICT event. Without channels, executions of entries
20
+ take turns on the embodiment, in the order they start. Guards (when, watch) and handlers
21
+ (on) set inside fn are the entry's: they watch its executions and those of the
22
+ entries it starts, and end with it. An entry that fails goes to whoever waits for
23
+ it, else to the handlers of the entry that started it (on("ENTRY_FAILED", ...)),
24
+ then up; one nobody handles reaches you. Entries this program starts keep running
25
+ after it ends, and you hear how they stand after each program; an entry's own
26
+ entries end with it."""
27
+ return self._entries.spawn(fn, name=name, claims=claims)
28
+
29
+ def receive(self, timeout=None):
30
+ """The oldest message sent to the entry this code runs in (handle.send), waiting at
31
+ most `timeout` seconds for one (None: as long as it takes); None when none came."""
32
+ return self._entries.current().receive(timeout)
33
+
34
+ def claim(self, *channels):
35
+ """Claim channels for the entry this code runs in until it unclaims them or ends;
36
+ no other entry may use them meanwhile, its own entries may. True; when one is
37
+ another entry's, a CHANNEL_CONFLICT event goes to this entry's handlers and up
38
+ (False when a handler took it)."""
39
+ return self._entries.claim(list(channels))
40
+
41
+ def unclaim(self, *channels):
42
+ """Let go of channels (none named: all this entry has): its claims, and the keys
43
+ and buttons it holds down on them."""
44
+ self._entries.release(list(channels) or None)
45
+
46
+ def channel_board(self):
47
+ """Who has each channel now: {channel: {"entry", "how": "claimed" | "driving" |
48
+ "holding"}}, None for a free one (at its default)."""
49
+ return self._entries.channels()
50
+
51
+ def entries(self, running=True):
52
+ """The handles of the entries started so far (only those running, unless
53
+ `running` is False), oldest first; each has .state(), .wait(), .cancel(),
54
+ .send(); a sub-agent's (delegate) has .agent."""
55
+ tree = self._entries
56
+ return [entry for entry in list(tree.entries.values())
57
+ if entry is not tree.root and (entry.running or not running)]
58
+
59
+
60
+ def exports(session):
61
+ return {"spawn": session.spawn, "receive": session.receive, "entries": session.entries,
62
+ "claim": session.claim, "unclaim": session.unclaim, "channels": session.channel_board}
@@ -0,0 +1,8 @@
1
+ name = "entries"
2
+ summary = "Run parts of a program at the same time as entries of a tree: spawn, wait, cancel, send; events go up the tree; claim and unclaim channels."
3
+ layer = "base"
4
+ mixin = "skills.entries:Entries"
5
+ exports = ["spawn", "receive", "entries", "claim", "unclaim", "channels"]
6
+ # Streaming: a configuration that wants entries names it.
7
+ order = 115
8
+ embodiments = ["*"]
@@ -0,0 +1,69 @@
1
+ """Another environment for one conversation, and sub-agents on request.
2
+
3
+ A conversation works in the environment its user chose. When a step cannot be done there
4
+ (a project task must see a rendered page; a desktop task must run a command), the program
5
+ asks for another kind with use_environment(kind, why). The session host decides as the
6
+ user's settings say (environments.attach and its rules): it may ask the user, showing
7
+ `why`; where nobody can be asked and the settings require asking, it refuses with the
8
+ reason. Once taken, that environment's calls are name.call(...) (desktop.click,
9
+ project.run_command, browser.read_page) until release_environment(name) or the end of the
10
+ conversation. The host keeps every attachment and its reason in the trace.
11
+
12
+ Sub-agents are off unless the user switched them on: request_agents(why) asks the user to.
13
+ """
14
+
15
+ from harness.sdk import Escalation, control, user_message
16
+
17
+
18
+ class Environments:
19
+ def _ask_conversation(self, operation, **detail):
20
+ tree = getattr(self, "_entries", None)
21
+ # The program's own code leaves the wait when a message for the model comes.
22
+ own = tree is None or tree.current() is tree.root
23
+ answer = control.ask_host("environment", stop=control.message_arrived if own else None, action=operation,
24
+ **detail)
25
+ if answer is None and own and control.message_arrived():
26
+ raise Escalation(user_message(operation, detail))
27
+ return answer
28
+
29
+ def use_environment(self, kind, why, folder=None):
30
+ """Take another environment into this conversation: `kind` is one the user's
31
+ installation has ("project", "browser", "desktop", "apps", "display"), `why` one
32
+ sentence the user reads when they are asked. A project needs `folder`. Returns the
33
+ environment, whose calls are then kind.call(...); raises ValueError with the reason
34
+ when the user or their settings refuse. None when the user paused first."""
35
+ name = str(kind).strip()
36
+ if name in self._attached:
37
+ return self.namespace[name]
38
+ given = self._ask_conversation("use", environment=name, why=str(why or "").strip(),
39
+ **({"folder": str(folder)} if folder else {}))
40
+ if given is None:
41
+ return None
42
+ try:
43
+ proxy = self.attach(name, given["session"])
44
+ except Exception as error:
45
+ # The host took a workspace for it: give it back.
46
+ control.ask_host("environment", action="release", environment=name, failed=f"{type(error).__name__}: {error}")
47
+ raise
48
+ print(given.get("about") or f"{name} is attached: call it as {name}.NAME(...)")
49
+ return proxy
50
+
51
+ def release_environment(self, kind):
52
+ """Give an environment taken with use_environment back. True when it was attached."""
53
+ name = str(kind).strip()
54
+ if not self.detach(name):
55
+ return False
56
+ self._ask_conversation("release", environment=name)
57
+ return True
58
+
59
+ def request_agents(self, why):
60
+ """Ask the user to switch sub-agents on for this conversation (`why`: one sentence
61
+ they read). True once they are on (delegate, wait_agents, send_agent and cancel_agent
62
+ are then calls of this conversation); ValueError with the reason when refused."""
63
+ given = self._ask_conversation("agents", why=str(why or "").strip())
64
+ if given is None:
65
+ return None
66
+ added = self.load_skills(given.get("skills") or [])
67
+ if given.get("about"):
68
+ print(given["about"])
69
+ return bool(added) or "agents" in self.skills
@@ -0,0 +1,9 @@
1
+ name = "environments"
2
+ summary = "Take another environment into the conversation when the chosen one cannot do a step, and ask for sub-agents."
3
+ layer = "base"
4
+ mixin = "skills.environments:Environments"
5
+ exports = ["use_environment", "release_environment", "request_agents"]
6
+ # Only where a user started the conversation (the session host enables it).
7
+ optional = true
8
+ order = 97
9
+ embodiments = ["*"]
@@ -0,0 +1,27 @@
1
+ """Compatibility names for old programs. Hints and results use the library's memory."""
2
+
3
+ import json
4
+
5
+ from skills.memory import Memory
6
+
7
+
8
+ class Experience:
9
+ def hint(self, kind, key):
10
+ rows = Memory._memory(self, "recall", kind=f"hint:{kind}", k=0)
11
+ return next((json.loads(row["text"]) for row in rows if row["name"] == str(key)), None)
12
+
13
+ def keep_hint(self, kind, key, value):
14
+ kind, key = f"hint:{kind}", str(key)
15
+ if value is None:
16
+ rows = Memory._memory(self, "recall", kind=kind, k=0)
17
+ return any(Memory._memory(self, "forget", id=row["id"]) for row in rows if row["name"] == key)
18
+ text = json.dumps(value, ensure_ascii=False)
19
+ settings = (getattr(self, "library_given", None) or {}).get("settings") or {}
20
+ return Memory._memory(self, "remember", kind=kind, name=key, text=text, keep=settings.get("learn") == "on")
21
+
22
+ def experience(self, skill=None):
23
+ rows = Memory._memory(self, "recall", kind="historical_use", k=0)
24
+ found = {row["name"]: {**json.loads(row["text"]), "revision": None} for row in rows}
25
+ found.update({row["name"]: json.loads(row["text"])
26
+ for row in Memory._memory(self, "recall", kind="skill_use", k=0)})
27
+ return found if skill is None else found.get(skill)
@@ -0,0 +1,9 @@
1
+ name = "experience"
2
+ summary = "Experience from practice in the library: how each skill did (runs, success rate, time, common failures) and hints a skill remembered as working (hint, keep_hint), to try first and check."
3
+ layer = "base"
4
+ mixin = "skills.experience:Experience"
5
+ exports = ["hint", "keep_hint", "experience"]
6
+ # Retained for the frozen robot scoring path.
7
+ optional = true
8
+ order = 75
9
+ embodiments = ["*"]
@@ -0,0 +1,29 @@
1
+ """Skills the user installed in the app in the Agent Skills format (a folder with
2
+ SKILL.md: instructions for a kind of task, and the files they refer to). The system
3
+ prompt names each one with its description; read_skill() gives the rest when a task
4
+ needs it, so the prompt stays short however many there are."""
5
+
6
+ from pathlib import Path
7
+
8
+ # Files read_skill gives at most, in characters.
9
+ LIMIT = 60000
10
+
11
+
12
+ class AgentSkills:
13
+ def read_skill(self, name, file="SKILL.md"):
14
+ """The instructions of installed skill `name` (its SKILL.md), or another of its
15
+ files by its path inside the skill ("reference.md", "scripts/fill.py"). Without
16
+ such a file, ValueError lists the skill's files."""
17
+ skills = getattr(self, "agent_skills", None) or {}
18
+ if name not in skills:
19
+ raise ValueError(f"No installed skill {name!r}; skills: {sorted(skills)}")
20
+ folder = Path(skills[name]["path"]).resolve()
21
+ path = (folder / str(file)).resolve()
22
+ if folder not in path.parents or not path.is_file():
23
+ files = sorted(str(item.relative_to(folder)).replace("\\", "/") for item in folder.rglob("*")
24
+ if item.is_file() and ".deps" not in item.parts)
25
+ raise ValueError(f"No file {file!r} in skill {name}; its files: {files[:100]}")
26
+ text = path.read_text(encoding="utf-8", errors="replace")
27
+ if len(text) > LIMIT:
28
+ text = text[:LIMIT] + f"\n[... {len(text) - LIMIT} more characters]"
29
+ return text
@@ -0,0 +1,9 @@
1
+ name = "instructions"
2
+ summary = "Skills the user installed in the app (Agent Skills: SKILL.md folders): read their instructions and files."
3
+ layer = "base"
4
+ mixin = "skills.instructions:AgentSkills"
5
+ exports = ["read_skill"]
6
+ # Only where the user installed some (the app enables it).
7
+ optional = true
8
+ order = 95
9
+ embodiments = ["*"]