@lmmslab/harness 0.0.0-stage → 0.81.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 (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 +1308 -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 +221 -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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The Harness contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,125 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://harness.lmms-lab.com">
3
+ <picture>
4
+ <source srcset="docs/readme/logo-dark.svg" media="(prefers-color-scheme: dark)">
5
+ <source srcset="docs/readme/logo-light.svg" media="(prefers-color-scheme: light)">
6
+ <img alt="The Harness logo" src="docs/readme/logo-light.svg" width="96">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <p align="center">
11
+ <a href="https://discord.gg/zhkzEznBs"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
12
+ <a href="https://www.npmjs.com/package/@lmmslab/harness"><img alt="npm" src="https://img.shields.io/npm/v/@lmmslab/harness?style=flat-square" /></a>
13
+ <a href="https://pypi.org/project/the-harness/"><img alt="PyPI" src="https://img.shields.io/pypi/v/the-harness?style=flat-square" /></a>
14
+ </p>
2
15
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
16
+ <h1 align="center">The Harness</h1>
17
+
18
+ <p align="center">Automatic Control for anything that acts.</p>
19
+
20
+ ---
21
+
22
+ The Harness is Automatic Control for anything that acts. You tell an agent what to do in
23
+ your own words; a language model plans and writes short programs, and The Harness runs
24
+ them in an environment the agent can see and act in, while you watch, add a message or
25
+ take over.
26
+
27
+ The agent thinks while it acts: between model calls, its programs, skills and reactive
28
+ rules keep working, and what it learns along the way (notes, tested skills, rules)
29
+ applies in the same run.
30
+
31
+ Use The Harness [in the terminal](https://harness.lmms-lab.com/docs/use/terminal/), run one task from
32
+ [the CLI](https://harness.lmms-lab.com/docs/use/cli/), drive it from another program with JSON lines, call it from
33
+ [apps, editors and other agents](https://harness.lmms-lab.com/docs/extend/editors/) over MCP and ACP, or build on the
34
+ [Python API](https://harness.lmms-lab.com/docs/extend/python-api/).
35
+
36
+ ## Getting started
37
+
38
+ ```bash
39
+ npm install -g @lmmslab/harness # or: pip install the-harness
40
+ harness
41
+ ```
42
+
43
+ The Harness needs Python 3.11 or newer. `harness` opens a conversation in your terminal.
44
+ The first time, it asks which model to use and for its key; then type a task. Any model
45
+ works: hosted ones through OpenRouter, OpenAI, Anthropic and other providers, or a model
46
+ you run yourself.
47
+
48
+ See [Install](https://harness.lmms-lab.com/docs/getting-started/install/) and the
49
+ [Quickstart](https://harness.lmms-lab.com/docs/getting-started/quickstart/) for a real task on your own computer.
50
+
51
+ ## Commands
52
+
53
+ ```bash
54
+ harness # talk with the agent in the terminal
55
+ harness run "task" -p # do one task and print the answer (--json: every event)
56
+ harness run rpc # drive a conversation with JSON lines, from another program
57
+ harness install # packages (also: list, remove)
58
+ harness library # what the agent learned
59
+ harness replay # a run again in the terminal
60
+ harness doctor # what this computer has and lacks
61
+ ```
62
+
63
+ ## Where it works
64
+
65
+ pip/npm install only the small core. Environments come in packages, installed by
66
+ themselves the first time a task needs them.
67
+
68
+ | Environment | Package |
69
+ |---|---|
70
+ | Your computer: apps and windows, or a display of its own | `computer` |
71
+ | Websites, in a background browser | `browser` |
72
+ | Project files and processes, in a bound working directory | `workspace` |
73
+
74
+ ## Packages
75
+
76
+ <!-- generated: packages -->
77
+ | Package | What it is | Depends on | Provides |
78
+ |---|---|---|---|
79
+ | [acp](https://harness.lmms-lab.com/packages/acp/) | The Harness as an Agent Client Protocol agent for editors such as Zed | – | commands acp |
80
+ | [agent](https://harness.lmms-lab.com/packages/agent/) | Persistent identity, multi-turn dialogue and private memory over the Harness task engine | – | commands agent |
81
+ | [browser](https://harness.lmms-lab.com/packages/browser/) | Search and browse the web in a background browser | computer | skills browser; benches browser |
82
+ | [computer](https://harness.lmms-lab.com/packages/computer/) | Control a computer: its desktop, its applications in the background, displays of its own | – | embodiments computer, ubuntu; skills desktop, physical, screens, windowtools; benches computer |
83
+ | [eval](https://harness.lmms-lab.com/packages/eval/) | Evaluate the agent: experiments over tasks and seeds, their suites, locks, run pages and self-improvement | local-models | commands config, inspect, lock, program, runs, self-improve, serve, view |
84
+ | [external-agents](https://harness.lmms-lab.com/packages/external-agents/) | ACP, terminal and cloud coding sessions, and bounded Claude Code and Codex delegates | – | commands agents |
85
+ | [local-models](https://harness.lmms-lab.com/packages/local-models/) | Models on your own GPUs: where services run (deploys), their weights and servers, Qwen3-VL | – | services qwen3-vl-32b, qwen3-vl-8b; commands down, fetch, services, status, up |
86
+ | [mcp-example](https://harness.lmms-lab.com/packages/mcp-example/) | An example MCP server: unit conversion | – | services mcp-units |
87
+ | [mcp-server](https://harness.lmms-lab.com/packages/mcp-server/) | The Harness as an MCP server (harness mcp), for apps, editors and agents that are MCP clients | – | commands mcp |
88
+ | [perception](https://harness.lmms-lab.com/packages/perception/) | See: segmentation, pointing, scenes, generic vision and vision-language models | local-models | skills pointing, scene, segmentation, vision, vlm; services molmo2, sam3, vision |
89
+ | [workspace](https://harness.lmms-lab.com/packages/workspace/) | Operate project files and processes in a bound working directory | – | embodiments workspace; skills workspace; benches workspace |
90
+ <!-- /generated: packages -->
91
+
92
+ ## Documentation
93
+
94
+ - [Quickstart](https://harness.lmms-lab.com/docs/getting-started/quickstart/)
95
+ - [Automatic Control](https://harness.lmms-lab.com/docs/concepts/harness/): the ideas behind The Harness
96
+ - [Models and providers](https://harness.lmms-lab.com/docs/configure/models/)
97
+ - [Interrupt and take over](https://harness.lmms-lab.com/docs/use/interrupt/)
98
+ - [Let it learn an environment](https://harness.lmms-lab.com/docs/learn/learn-an-environment/)
99
+ - [Write a skill](https://harness.lmms-lab.com/docs/extend/skills/), [write a package](https://harness.lmms-lab.com/docs/extend/packages/), [add an environment](https://harness.lmms-lab.com/docs/extend/environments/)
100
+
101
+ ## Development
102
+
103
+ ```bash
104
+ pip install -e .
105
+ harness install ./packages/computer ./packages/browser ./packages/workspace --link --yes
106
+ harness doctor
107
+ ```
108
+
109
+ See [CONTRIBUTING.md](CONTRIBUTING.md) and [the validation guide](docs/TESTING.md).
110
+
111
+ ## Citation
112
+
113
+ ```bibtex
114
+ @misc{lmmslab2026harness,
115
+ author = {{LMMs-Lab}},
116
+ title = {The Harness: One Agent Harness for Anything that Acts},
117
+ howpublished = {\url{https://github.com/EvolvingLMMs-Lab/the-harness}},
118
+ year = {2026}
119
+ }
120
+ ```
121
+
122
+ ## License
123
+
124
+ MIT; third-party material retains its own terms. See [LICENSE](LICENSE) and
125
+ [CONTRIBUTORS.md](CONTRIBUTORS.md).
package/bin/harness.js ADDED
@@ -0,0 +1,71 @@
1
+ #!/usr/bin/env node
2
+ // The `harness` command of the npm package: runs the Python package shipped next to it
3
+ // (../python/harness, standard library only) with a Python 3.11 or newer found on this computer.
4
+ "use strict";
5
+
6
+ const { spawn, spawnSync } = require("node:child_process");
7
+ const path = require("node:path");
8
+
9
+ const MINIMUM = [3, 11];
10
+ const source = path.join(__dirname, "..", "python");
11
+
12
+ function version(command, args) {
13
+ const probe = spawnSync(command, [...args, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"], {
14
+ encoding: "utf8",
15
+ windowsHide: true,
16
+ });
17
+ if (probe.status !== 0 || !probe.stdout) return null;
18
+ const [major, minor] = probe.stdout.trim().split(".").map(Number);
19
+ return Number.isInteger(major) && Number.isInteger(minor) ? [major, minor] : null;
20
+ }
21
+
22
+ function recentEnough(found) {
23
+ return found !== null && (found[0] > MINIMUM[0] || (found[0] === MINIMUM[0] && found[1] >= MINIMUM[1]));
24
+ }
25
+
26
+ // HARNESS_PYTHON names the interpreter; otherwise the first of these that is new enough.
27
+ function interpreter() {
28
+ const named = process.env.HARNESS_PYTHON;
29
+ const candidates = named
30
+ ? [[named, []]]
31
+ : process.platform === "win32"
32
+ ? [["python", []], ["py", ["-3"]], ["python3", []]]
33
+ : [["python3", []], ["python", []]];
34
+ const seen = [];
35
+ for (const [command, args] of candidates) {
36
+ const found = version(command, args);
37
+ if (recentEnough(found)) return { command, args };
38
+ if (found) seen.push(`${[command, ...args].join(" ")} is ${found.join(".")}`);
39
+ }
40
+ // uv fetches a Python of its own when none is installed.
41
+ if (!named && spawnSync("uv", ["--version"], { windowsHide: true }).status === 0) {
42
+ return { command: "uv", args: ["run", "--no-project", "--python", MINIMUM.join("."), "python"] };
43
+ }
44
+ const detail = seen.length ? ` (${seen.join("; ")})` : "";
45
+ console.error(
46
+ `harness: Python ${MINIMUM.join(".")} or newer was not found${detail}.\n` +
47
+ "Install it from https://www.python.org/downloads/ or install uv (https://docs.astral.sh/uv/),\n" +
48
+ "or set HARNESS_PYTHON to the interpreter to use."
49
+ );
50
+ process.exit(1);
51
+ }
52
+
53
+ const { command, args } = interpreter();
54
+ const env = { ...process.env };
55
+ env.PYTHONPATH = env.PYTHONPATH ? source + path.delimiter + env.PYTHONPATH : source;
56
+
57
+ const child = spawn(command, [...args, "-m", "harness", ...process.argv.slice(2)], { stdio: "inherit", env });
58
+ // The terminal sends an interrupt to the whole process group: Python handles its own.
59
+ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
60
+ process.on(signal, () => {
61
+ if (signal !== "SIGINT") child.kill(signal);
62
+ });
63
+ }
64
+ child.on("error", (error) => {
65
+ console.error(`harness: could not start ${command}: ${error.message}`);
66
+ process.exit(1);
67
+ });
68
+ child.on("exit", (code, signal) => {
69
+ if (signal) process.kill(process.pid, signal);
70
+ else process.exit(code === null ? 1 : code);
71
+ });
package/package.json CHANGED
@@ -1,6 +1,36 @@
1
1
  {
2
2
  "name": "@lmmslab/harness",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.81.0",
4
+ "description": "Automatic Control for anything that acts",
5
+ "license": "MIT",
6
+ "homepage": "https://harness.lmms-lab.com",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/EvolvingLMMs-Lab/the-harness.git"
10
+ },
11
+ "bugs": {
12
+ "url": "https://github.com/EvolvingLMMs-Lab/the-harness/issues"
13
+ },
14
+ "keywords": [
15
+ "agent",
16
+ "harness",
17
+ "automation",
18
+ "computer-use",
19
+ "mcp"
20
+ ],
21
+ "bin": {
22
+ "harness": "bin/harness.js"
23
+ },
24
+ "files": [
25
+ "bin",
26
+ "python",
27
+ "README.md",
28
+ "LICENSE"
29
+ ],
30
+ "engines": {
31
+ "node": ">=18"
32
+ },
33
+ "publishConfig": {
34
+ "access": "public"
35
+ }
36
+ }
@@ -0,0 +1,72 @@
1
+ # Source map
2
+
3
+ The runtime implements the [automatic-control concept](../../docs/src/content/docs/concepts/harness.mdx):
4
+ the model writes a controller at decision points; programs, learned policies and reactive
5
+ rules act without a model call on every step. A worker checks commands at the environment
6
+ boundary. The controller's Python process and the task's target environment are separate.
7
+
8
+ ## The four control layers
9
+
10
+ | Concept | Source | Responsibility |
11
+ |---|---|---|
12
+ | Model decisions | `runtime/decision/` | Model transport, requests and cancellation, messages, prompts, reply protocol and speculative-reply rules |
13
+ | Programs and learned policies | `runtime/execution/` | Controller process, session bootstrap, bounded executions, skills and control API |
14
+ | Reactive control | `runtime/reactive/` | Guards, reflexes and event handlers evaluated during execution |
15
+ | Fixed safety | `runtime/safety/` | Shield mechanism, input ownership, approval contracts and controller isolation |
16
+
17
+ These are control responsibilities, not four sequential RPC services. The shared
18
+ `runtime/tick.py` scheduler advances executions and rules. It is not a fifth layer.
19
+ Environment-specific commands, observations and safety decisions stay in their packages
20
+ and workers; putting generic shield code here does not move the target environment here.
21
+
22
+ ## Task coordination and learning
23
+
24
+ `runtime/task/run.py` owns a bounded task's lifecycle: setup, decision/program transitions,
25
+ steering, budgets, approvals, learning activation boundaries, termination and cleanup.
26
+ It coordinates the four layers. Its state stays on `TaskRun`; this organization adds no
27
+ shared-state container, forwarding properties, component registry or callback framework.
28
+ `runtime/task/delegation.py` manages bounded child executions, not persistent agents.
29
+
30
+ `runtime/learning/` is cross-layer: an explicitly bound library can supply notes, memories,
31
+ skills, policies and reactive rules. Its learner, fixtures and activation machinery retain
32
+ their existing admission contracts. Learning is available without an agent package.
33
+
34
+ Three kinds of data have different owners:
35
+
36
+ | Data | Owner |
37
+ |---|---|
38
+ | Working state of this task | `runtime/task/context.py` |
39
+ | Captured library entries and their evidence | `runtime/learning/library.py`, `views.py`, `usage.py` |
40
+ | Historical projection for frontends and replay | `core/memory.py`, `core/episodes.py` |
41
+
42
+ Persistent identity, personal memory and multi-turn conversations belong to the optional
43
+ agent package. A CLI task and a benchmark episode use the same task engine without it.
44
+
45
+ ## Where to start reading
46
+
47
+ - Task starts, stops, waits or exhausts its budget: `runtime/task/run.py`.
48
+ - A model request is sent, cancelled or settled: `runtime/decision/thoughts.py`.
49
+ - A reply is classified or speculation is interpreted: `runtime/decision/loop.py` and `protocol.py`.
50
+ - A program starts or returns a receipt: `runtime/execution/kernel.py` and `results.py`.
51
+ - Controller API and environment session setup: `runtime/execution/session.py`.
52
+ - Bounded actions and interruptions: `runtime/execution/entries.py` and `runtime/tick.py`.
53
+ - A guard, reflex or handler runs: `runtime/reactive/rules.py`.
54
+ - A command is refused or needs approval: `runtime/safety/shield.py`, `approval.py` and the package's worker.
55
+ - A proposal is tested or admitted: `runtime/learning/learner.py` and `fixtures.py`.
56
+ - Library contents become runnable: `runtime/learning/active.py` and the task's activation boundary.
57
+ - A frontend reads recorded memory: `core/memory.py`.
58
+
59
+ ## Other core directories
60
+
61
+ - `host/`: task hosting, worker leases, workspace ownership and HTTP access.
62
+ - `core/`: shared I/O, traces, records, transport and worker infrastructure.
63
+ - `config/`: resolve and validate configuration.
64
+ - `packages/`: install and activate capabilities owned by external packages.
65
+ - `services/`: service lifecycle and clients.
66
+ - `sdk/`: the package-facing Python API; consumers should use it instead of internal paths.
67
+ - `builtin/`: shipped generic configuration, prompts, skills and services.
68
+ - `tui/` and `cli.py`: terminal interfaces.
69
+
70
+ Runtime implementations import their actual owners. Old flat runtime modules are removed;
71
+ there are no alias tables or fallback imports. Internal bootstrap strings and all tracked
72
+ callers move together. This is a source organization change, not a new execution protocol.
@@ -0,0 +1,8 @@
1
+ """The Harness: a coding agent as a generalist robot policy. No simulator imports here."""
2
+
3
+ # The one version: the core's. A lock records it with the versions of the packages that
4
+ # ran and the hash of the whole lock (the agent's identity, config/agent.py).
5
+ __version__ = "0.81.0"
6
+
7
+ # A checkout's packages import beside the harness (paths.py).
8
+ from . import paths as _paths # noqa: E402,F401
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,124 @@
1
+ """Benches: the environments an agent's worker serves, as their bench.toml describes them.
2
+
3
+ A bench is a package's `benches/<name>/` with
4
+
5
+ bench.toml name, summary, the embodiment kind its worker drives, the worker's
6
+ factory and the [worker] keys it takes, its [environment] and [sandbox]
7
+ bench.py its hooks (BENCH_KEYS `hooks`, a subclass of the eval package's Bench)
8
+
9
+ The core reads what starts a worker (bench_specs): the computer's workspaces start a
10
+ bench's worker from it, the session host knows a bench's embodiment kind from it, active
11
+ learning its sandbox, `harness install` its environment. Running a bench as a benchmark
12
+ (its tasks, the keys of a deploy's [benches.<name>] table, its checkout and assets) is the
13
+ eval package's: those keys of bench.toml stay in BenchSpec.benchmark, which the eval
14
+ package reads and checks (harness_eval/bench.py), with the hooks.
15
+
16
+ Adding a bench touches none of the code that reads it. A bench's hooks import only the standard library and their own package's light modules at import;
17
+ the simulator, the VM and the benchmark's code stay in the worker process.
18
+ """
19
+
20
+ from dataclasses import dataclass, field
21
+ from pathlib import Path
22
+ import tomllib
23
+
24
+ from .embodiments import KINDS
25
+
26
+
27
+ # The keys of benches/<name>/bench.toml the core reads; the others are the eval package's
28
+ # (harness_eval/bench.py BENCHMARK_KEYS).
29
+ BENCH_KEYS = {
30
+ "name": "the bench's name, the same as its directory (an experiment's `bench`)",
31
+ "summary": "one line: what the bench is",
32
+ "kind": "the embodiment kind its worker drives (embodiments.KINDS)",
33
+ "embodiment": "embodiments/<name> for observation contracts (optional: then only the native contract)",
34
+ "factory": "the worker's environment factory, \"module:callable\" (`python -m harness.core.worker --factory`)",
35
+ "hooks": "the Bench subclass with its hooks, \"module:Class\" (default Bench)",
36
+ "worker": "the experiment [worker] keys it takes: {key = \"what it does\"}",
37
+ "environment": "the environment of its workers and of the kernel, installed on first use ([environment] keys)",
38
+ "notes": "anything an operator should know",
39
+ "sandbox": "the practice sandbox of an active run of learning (runtime/learning/active.py), never of a task run: `what` "
40
+ "(what it is, for the model) and [sandbox.ops] {op = \"what it stages\"}; without ops there is none "
41
+ "(`what` says why)",
42
+ }
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class BenchSpec:
47
+ """A bench as its bench.toml declares it (BENCH_KEYS); `path` is its directory."""
48
+
49
+ name: str
50
+ summary: str
51
+ kind: str
52
+ factory: str
53
+ embodiment: str | None = None
54
+ hooks: str | None = None
55
+ worker: dict = field(default_factory=dict)
56
+ environment: dict | None = None
57
+ notes: str = ""
58
+ # The practice sandbox of an active run: {"what", "ops": {op: what it stages}}.
59
+ sandbox: dict = field(default_factory=dict)
60
+ # The rest of bench.toml: running it as a benchmark, the eval package's to read and check.
61
+ benchmark: dict = field(default_factory=dict)
62
+ path: Path = field(default=None, compare=False)
63
+
64
+
65
+ def _spec(directory: Path) -> BenchSpec:
66
+ data = tomllib.loads((directory / "bench.toml").read_text(encoding="utf-8"))
67
+ missing = {"name", "summary", "kind", "factory"} - set(data)
68
+ if missing:
69
+ raise ValueError(f"{directory}/bench.toml: missing {sorted(missing)}")
70
+ if data["name"] != directory.name:
71
+ raise ValueError(f"{directory}/bench.toml: name {data['name']!r} is not its directory's")
72
+ if data["kind"] not in KINDS:
73
+ raise ValueError(f"{directory}/bench.toml: kind must be one of {sorted(KINDS)}")
74
+ if not all(isinstance(text, str) for text in data.get("worker", {}).values()):
75
+ raise ValueError(f"{directory}/bench.toml: [worker] maps each key to what it does")
76
+ sandbox = data.get("sandbox", {})
77
+ if (not isinstance(sandbox, dict) or set(sandbox) - {"what", "ops"} or not isinstance(sandbox.get("what", ""), str)
78
+ or not all(isinstance(text, str) for text in sandbox.get("ops", {}).values())):
79
+ raise ValueError(f"{directory}/bench.toml: [sandbox] is what (a text) and ops {{op = \"what it stages\"}}")
80
+ if "environment" in data:
81
+ from .packages.environments import validate
82
+
83
+ validate(data["environment"], f"{directory}/bench.toml")
84
+ own = {key: value for key, value in data.items() if key in BENCH_KEYS}
85
+ return BenchSpec(**own, benchmark={key: value for key, value in data.items() if key not in BENCH_KEYS},
86
+ path=directory)
87
+
88
+
89
+ def bench_dirs() -> dict[str, Path]:
90
+ """Every bench's directory by name: benches/<name>/ of ROOT and of each package
91
+ (paths.roots), the first one of a name winning."""
92
+ from .paths import find
93
+
94
+ found = {}
95
+ for folder in find("benches"):
96
+ for path in sorted(folder.glob("*/bench.toml")):
97
+ found.setdefault(path.parent.name, path.parent)
98
+ return found
99
+
100
+
101
+ def bench_names() -> list[str]:
102
+ """The benches of the core and of its packages (benches/<name>/bench.toml)."""
103
+ return sorted(bench_dirs())
104
+
105
+
106
+ def bench_spec(name: str) -> BenchSpec:
107
+ """The bench `name`'s bench.toml; ValueError for a bench no package has."""
108
+ if name not in bench_names():
109
+ raise ValueError(f"Unknown bench {name!r}; benches are {bench_names()}")
110
+ return _spec(bench_dirs()[name])
111
+
112
+
113
+ def bench_specs() -> dict[str, BenchSpec]:
114
+ """Every bench's bench.toml by name, without importing its hooks."""
115
+ return {name: _spec(directory) for name, directory in sorted(bench_dirs().items())}
116
+
117
+
118
+ def declares_channels(spec: BenchSpec) -> bool:
119
+ """Whether a bench's embodiment declares channels (embodiment.toml [channels])."""
120
+ if not spec.embodiment:
121
+ return False
122
+ from .embodiments import load_embodiment
123
+
124
+ return bool(load_embodiment(spec.embodiment).get("channels"))
@@ -0,0 +1,5 @@
1
+ # Benches
2
+
3
+ The benchmarks are packages: `packages/<name>/benches/<name>/` (robodojo, robotwin, osworld,
4
+ osomni, computer, browser, minecraft, gamescientist, fakegame in game). This folder stays so
5
+ that each package adds its own `benches.<name>` beside the others.
@@ -0,0 +1,6 @@
1
+ name = "none"
2
+ summary = "No environment: the conversation, the model and the connected tools only"
3
+ kind = "none"
4
+ factory = "harness.runtime.execution.noenv:create_environment"
5
+
6
+ tasks = '"free": a task supplied by the user'
@@ -0,0 +1,26 @@
1
+ # Configs
2
+
3
+ There is one agent, `default.toml`. A run is the agent (or an agent file that includes it) with a
4
+ **model** on a **bench**, resolved against a machine's **deploy**; later layers win:
5
+
6
+ ```text
7
+ configs/
8
+ ├── default.toml the agent: prompt pack, skills, services, runtime, budget, its default model
9
+ ├── ablations/ variants of the agent: each includes default.toml and switches parts off
10
+ ├── models/ model roles: main, vlm, pointer, verifier (hosted models or services)
11
+ ├── experiments/ the agent with a model on a bench: tasks, seeds, layouts, budgets, overrides
12
+ ├── deploy/ per machine: GPUs, weights, where each service runs (examples; yours is git-ignored)
13
+ ├── workers/ options for starting a worker by hand (harness serve --options ...)
14
+ └── scripts/ scripted model replies for pipeline checks
15
+ ```
16
+
17
+ ```bash
18
+ harness config configs/experiments/dev.toml --deploy mine # skills, services, identity
19
+ harness run configs/experiments/dev.toml --deploy mine --output runs/dev
20
+ harness run --tasks stack_bowls --model grok-low --deploy mine --output runs/x
21
+ harness lock --out agent.lock # the agent's identity
22
+ ```
23
+
24
+ - The agent, models, experiments, locks and identity: [docs/src/content/docs/concepts/configuration.md](../docs/src/content/docs/concepts/configuration.md)
25
+ - `--model`, `--set`, includes, tasks, seeds, budgets: [docs/src/content/docs/guides/configure-runs.md](../docs/src/content/docs/guides/configure-runs.md)
26
+ - Every key: the documentation site's *Reference → Configuration keys* (generated)
@@ -0,0 +1,11 @@
1
+ # Session-wide budgets. Installed workspace providers supply their own bench,
2
+ # prompt, embodiment configuration and worker environment.
3
+ description = "the session host's assistant"
4
+
5
+ [budget]
6
+ max_model_calls = 60
7
+ max_wall_seconds = 21600
8
+ max_cost_usd = 5.0
9
+
10
+ [overrides.agent]
11
+ prompt = {}
@@ -0,0 +1,33 @@
1
+ # The agent: what `harness run` runs unless an experiment or --agent names another (a
2
+ # package's profile: configs/profiles/<name>.toml, e.g. robodojo). Generic: the page every
3
+ # agent reads, the prompt of the kind's package (a computer's, a game's), the skills of the
4
+ # packages a run uses, the success verifier.
5
+ description = "The Harness: programs over the skills of the packages a task uses"
6
+ prompt = { robot = "../prompts/core", desktop = "../prompts/computer", game = "../prompts/game" }
7
+ # The model roles (configs/models/<name>.toml); an experiment's `model` or --model NAME
8
+ # picks another.
9
+ model = "deepseek-flash"
10
+ roles = ["main", "vlm", "verifier"]
11
+
12
+ [runtime]
13
+ cell_timeout_seconds = 600
14
+ verifier = true
15
+ # Programs run isolated where the machine allows user namespaces.
16
+ isolation = "auto"
17
+
18
+ [budget]
19
+ max_model_calls = 60
20
+
21
+ # A computer: its state every turn; the screen when a program looks (look, watch).
22
+ [desktop]
23
+ runtime = { contract = "screenshot", strategy_first = false }
24
+ budget = { max_model_calls = 60 }
25
+
26
+ # A game: its window when a program looks (the model turns watch() on itself) and eight
27
+ # exchanges; the game keeps running while rules and programs handle changes. Unresolved
28
+ # events can ask the model.
29
+ [game]
30
+ knowledge = "learned"
31
+ skills = { enable = ["vision"] }
32
+ runtime = { contract = "native", strategy_first = false, max_history_turns = 8, think_while_acting = "off", thinking = "low", max_wait_seconds = 30 }
33
+ budget = { max_model_calls = 5000 }
@@ -0,0 +1,10 @@
1
+ # No GPU for models: only the simulator runs here, every model is hosted (the main and
2
+ # vlm roles). Without a segmenter, segmentation and the tools built on it (locate, pick,
3
+ # release, ...) drop out of runs on this machine, and without a policy server the
4
+ # learned skills: a smaller configuration with another identity.
5
+ weights = "~/harness-weights"
6
+ gpus = [0]
7
+
8
+ [sim]
9
+ gpus = [0]
10
+ workers_per_gpu = 1
@@ -0,0 +1,21 @@
1
+ # DeepSeek V4.1 Flash from DeepSeek's own API (https://api.deepseek.com, model id
2
+ # deepseek-flash) instead of OpenRouter: the same model as deepseek-flash.toml, for an
3
+ # evaluator or a region without OpenRouter. The key is DEEPSEEK_API_KEY, never written
4
+ # here. Thinking stays on: reasoning_effort is sent as DeepSeek's own fields
5
+ # (runtime/decision/model.py effort_fields).
6
+ description = "DeepSeek V4.1 Flash from DeepSeek's API (DEEPSEEK_API_KEY) writes programs and answers questions about images"
7
+ include = ["deepseek-flash.toml"]
8
+
9
+ [main]
10
+ backend = "openai_chat"
11
+ base_url = "https://api.deepseek.com"
12
+ model = "deepseek-flash"
13
+ api_key_env = "DEEPSEEK_API_KEY"
14
+
15
+ # The same model answers questions about images inside programs.
16
+ [vlm]
17
+ backend = "openai_chat"
18
+ base_url = "https://api.deepseek.com"
19
+ model = "deepseek-flash"
20
+ api_key_env = "DEEPSEEK_API_KEY"
21
+ reasoning_effort = "medium"
@@ -0,0 +1,12 @@
1
+ # DeepSeek V4.1 Flash writes the programs: the development model, at medium reasoning
2
+ # effort for a few cents per RoboDojo episode.
3
+ description = "DeepSeek V4.1 Flash writes programs, answers questions about images and points; Molmo2 for a pointer role"
4
+ include = ["grok-medium.toml"]
5
+
6
+ [main]
7
+ model = "deepseek/deepseek-v4.1-flash"
8
+
9
+ # The same model answers questions about images inside programs (see grok-medium.toml).
10
+ [vlm]
11
+ model = "deepseek/deepseek-v4.1-flash"
12
+ reasoning_effort = "medium"
@@ -0,0 +1,8 @@
1
+ # grok-4.7 at low reasoning effort, for development. At medium effort xAI streams no
2
+ # reasoning, and OpenRouter cuts a request after about 5 minutes with nothing received:
3
+ # long replies are lost. Low effort answers in 13-60 s (about $0.11 per RoboDojo episode).
4
+ description = "grok-4.7 (low) writes programs, answers questions about images and points; Molmo2 for a pointer role"
5
+ include = ["grok-medium.toml"]
6
+
7
+ [main]
8
+ reasoning_effort = "low"