@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
@@ -0,0 +1,777 @@
1
+ """The agent configuration: what is evaluated, resolved for one machine.
2
+
3
+ There is one agent, configs/default.toml. It names the prompt pack, the skills (by
4
+ interface layers or by name), the services skills use (segmenter, policies, world
5
+ models), runtime settings, the budget, and its default model roles. Another agent
6
+ file may include it and change some keys; an experiment may override any key.
7
+
8
+ Model roles come from a model file, configs/models/<name>.toml (the agent's `model`,
9
+ an experiment's `model`, or `--model NAME`):
10
+
11
+ [main] the model that writes programs
12
+ backend = "openrouter"
13
+ model = "x-ai/grok-4.7"
14
+ [vlm] questions about images (and pointing without a pointer)
15
+ service = "qwen3-vl-8b" a role may be a service of the deploy ...
16
+ timeout_seconds = 300 ... with its own settings on top
17
+ [pointer]
18
+ service = "molmo2"
19
+ [verifier] overrides on top of main (the success verifier)
20
+ [runtime] settings the model needs (context window, ...)
21
+
22
+ Resolving the agent against a deploy gives the conversation's main model, runtime and
23
+ prompt, and a lock: everything that decides what a run computes and nothing about
24
+ where it runs (URLs, GPUs, ports). The lock records the agent's VERSION, and its hash
25
+ is the configuration's identity; a result and an exported XPolicyLab policy each
26
+ name one.
27
+ """
28
+
29
+ from dataclasses import dataclass, field
30
+ import hashlib
31
+ import os
32
+ from pathlib import Path
33
+ import tomllib
34
+
35
+ from . import deep_merge, load_layered, read_toml, route_openrouter
36
+ from .. import __version__
37
+ from ..core import sha256
38
+ from ..embodiments import KINDS
39
+ from harness.runtime.decision.prompts import assemble_prompt, features_for, select
40
+ from harness.runtime.execution.skills import KNOWLEDGE, LAYER_DEFAULTS, Resolution, available_services, handwritten, resolve, skills_for_layers
41
+ from ..paths import ROOT
42
+ from ..services.placement import automatic, client_config, load_deploy
43
+
44
+
45
+ REPO = ROOT
46
+ # The agent `harness` runs unless told otherwise, and where model files live.
47
+ DEFAULT_AGENT = REPO / "configs" / "default.toml"
48
+ MODELS_ROOT = REPO / "configs" / "models"
49
+ ROLES = ("main", "vlm", "pointer", "verifier")
50
+ SERVICE_KEYS = ("segmenter", "vision", "policies", "world_models", "mcp")
51
+ # What one entry of each list of services is, in messages.
52
+ SERVICE_ENTRY = {"policies": "policy", "world_models": "world model", "mcp": "MCP server"}
53
+ # What [game] knowledge says (runtime/execution/skills.py KNOWLEDGE).
54
+ KNOWLEDGE_DOC = ("what the agent knows of the game: \"learned\" (the default: no skill written for it by hand loads, "
55
+ "nor is imported; what it knows is its library's, which learns with runtime.library learn = \"on\", "
56
+ "runtime/learning/learner.py) or \"handwritten\" (a reference baseline's skills written for the game by hand "
57
+ "may load)")
58
+ # The keys of configs/default.toml (and of an agent file that includes it).
59
+ AGENT_KEYS = {
60
+ "description": "one line, shown by harness config and the run viewer",
61
+ "prompt": "the prompt: a pack directory (assembled for the enabled skills) or files, in order; or a table "
62
+ "of them by embodiment kind (robot = ..., desktop = ...)",
63
+ "mode": "program (default: the model writes programs) or direct (one action per call)",
64
+ "actions": "direct mode: the action vocabulary, \"module:function\" (text, allow_policy, allow_skills) -> the "
65
+ "program of one <action>; a ValueError names what is wrong with it",
66
+ "roles": "the model roles the agent uses, among main, vlm, pointer, verifier (default all)",
67
+ "skills": "layers = { learned, reactive, handlers }, or names = [...]; enable = [...] adds optional skills, "
68
+ "disable = [...] removes skills",
69
+ "services": "segmenter, vision (the vision skill's generic perception), policies = [...], world_models = [...], "
70
+ "mcp = [...] (MCP tool servers for the mcp skill): services the skills use",
71
+ "model": "the default model roles: a model file's name (configs/models/<name>.toml), or the roles inline",
72
+ "runtime": "runtime settings: the [runtime] keys",
73
+ "budget": "max_model_calls per episode (default 30)",
74
+ # A table for each embodiment kind but the robot's ([desktop]).
75
+ **{name: f"the agent on {kind.what} (benches of embodiment kind {name}): roles, skills, services, runtime and "
76
+ "budget keys merged over the ones above (runtime also over the model file's)"
77
+ + (f"; knowledge: {KNOWLEDGE_DOC}" if name == "game" else "")
78
+ for name, kind in KINDS.items() if name != "robot"},
79
+ }
80
+ # The keys of a kind's table ([desktop]): the robot is the agent's top level; `knowledge`
81
+ # only a game's.
82
+ KIND_KEYS = ("roles", "skills", "services", "runtime", "budget", "knowledge")
83
+ # The model roles of a model file (configs/models/<name>.toml), besides `runtime`
84
+ # (settings the model needs) and `description`.
85
+ ROLE_DOCS = {
86
+ "main": "writes the programs (or, in direct mode, the actions)",
87
+ "vlm": "answers questions about images inside programs (query_vlm), and points without a pointer",
88
+ "pointer": "open-vocabulary pointing (point_to, localize)",
89
+ "verifier": "overrides on top of main for the success verifier (verify, <verify>)",
90
+ }
91
+ # Settings of the agent's [runtime] (also of a model file's [runtime], and of an
92
+ # experiment's overrides). Documentation only: the resolution writes some of them
93
+ # itself (skills, skills_dropped, layers, the service configs).
94
+ RUNTIME_KEYS = {
95
+ "bootstrap": "the kernel's session factory, \"module:function\" (default the program runtime's)",
96
+ "cameras": "a standing watch declared by the configuration: these cameras' images reach the model with the "
97
+ "opening message and after every program, as an evaluation's observation contract hands them to a "
98
+ "policy. Without it the model gets text every turn and looks on its own demand (look, watch)",
99
+ "cell_timeout_seconds": "optional deadline for a program, bounded by the episode deadline",
100
+ "contract": "the observation contract (embodiments.contract_filter): native (default), xpolicylab (a robot's) or "
101
+ "screenshot (a desktop's)",
102
+ "default_max_seconds": "max_seconds of a bounded execution that names none",
103
+ "fixed_skills": "direct mode: locate, pick and place in the action vocabulary",
104
+ "isolation": "run programs isolated (default true; \"auto\": where user namespaces work)",
105
+ "keep_images": "with runtime.cameras: images of the most recent turns kept in the history (default 2). "
106
+ "Without it the model says how long a view stays (look(keep=), pin=)",
107
+ "viewer": "written by the session host: the model role that describes a view for a main model that reads no "
108
+ "images (the setting model.vision); none: such a model is told the view was not sent",
109
+ "knowledge": "a game's knowledge: \"learned\" (default: use the agent's own library) or \"handwritten\" "
110
+ "(allow reference knowledge). A worker that declares this setting must report the same mode.",
111
+ "label": "a name the run viewer shows for the configuration",
112
+ "layers": "written by the resolution from [skills] layers",
113
+ "library": "what the agent learned: [runtime.library] path = ... (relative, or under $HARNESS_HOME/; layers = "
114
+ "[...]). uses = \"learn\" (default: a run that learns counts its closed loops' results as uses of the library's "
115
+ "entries, runtime/task/context.py), \"on\" (also with a frozen library: practice) or \"off\". Learning "
116
+ "(runtime/learning/learner.py): learn = "
117
+ "\"off\" (read a frozen snapshot, the experiment default) or \"on\" (keep proposals and enable verified "
118
+ "entries at a safe boundary); trigger = \"passive\" or \"active\"; evidence = \"test\" (trusted verification) "
119
+ "or \"validated\" (paired development scores); load = the minimum evidence to load (proposed, provisional, "
120
+ "replayed, validated). Generated code always needs exact trusted proof. replay = true (recheck provisional "
121
+ "entries at startup); reflect = true (propose from observed results at useful decision points). "
122
+ "The active trigger's schedule (runtime/learning/active.py): active_before = true (before "
123
+ "a task's runs, one run that learns its environment) and active_minutes = 1 to 240 (that run's live "
124
+ "time, default 30)",
125
+ "max_history_turns": "keep only this many exchanges after the first message",
126
+ "mode": "written by the resolution from the agent's mode",
127
+ "actions": "written by the resolution: direct mode's action vocabulary (the agent's actions)",
128
+ "physical": "the physical-input policy of this run over the user's settings (the computer package's "
129
+ "harness_computer/physical.py): {level, rules}; harness run EXPERIMENT sets it from --physical, "
130
+ "--allow-app, --deny-app, --ask-app",
131
+ "privacy": "what the model learns of the user's windows in this run, over the user's settings (the computer "
132
+ "package's harness_computer/privacy.py): {level, rules}; harness run EXPERIMENT sets the level "
133
+ "from --window-details",
134
+ "pointer": "written by the resolution: the pointer role's client config",
135
+ "policies": "written by the resolution: the learned policies' client configs",
136
+ "python": "the kernel's interpreter (default the conversation's)",
137
+ "reactive_budget_ms": "total time for reactive callbacks on a control period (default 5 ms)",
138
+ "sandbox": "written by `harness run` for an active run only: the bench's [sandbox] (runtime/learning/active.py), the "
139
+ "practice sandbox its kernel gets; a task run never has one",
140
+ "reaction_delay_ms": "time between an observation and the action decided on it, rounded up to whole control "
141
+ "periods (runtime/tick.py): 0 (the default) for development and practice; 150-200 for a "
142
+ "person's reaction time, as in a full game run or a recorded demo",
143
+ "observer": "explicit world observation: max_side (default 768), reasoning_effort (none), "
144
+ "max_output_tokens (1200). Legacy timer settings are accepted for old profiles.",
145
+ "segmenter": "written by the resolution: the segmenter's client config",
146
+ "vision": "written by the resolution: the vision service's client config",
147
+ "skills": "written by the resolution: the enabled skills",
148
+ "skills_dropped": "written by the resolution: skills left out, and why",
149
+ "post_policy_calls": "with learned policies: model calls after the first run of a handed-over task, then the policy runs on to the end of the episode (0: it runs on at once; default none: no bound)",
150
+ "policy_progress_seconds": "a run of a learned policy also ends when no object the last locate tracks has moved 3 cm for this many seconds, measured every half of it (default none: only when it stops)",
151
+ "strategy_first": "with learned policies: nothing moves before start(strategy, kind) (default false; the agent sets it)",
152
+ "think_while_acting": "one speculative thought during a long program (default on). off disables speculation. "
153
+ "Legacy on_events and periodic enable the same behavior. User messages and unresolved "
154
+ "events are decision points in all modes",
155
+ "think_interval": "accepted for older profiles. Decision scheduling is event-driven",
156
+ "thinking": "how long a call of the main model may think (runtime/conversation.py THINKING): model (the "
157
+ "code's default: the model's own settings), none (reasoning off, replies of at most 2000 tokens, "
158
+ "and the model is told to think briefly), low (reasoning effort at most low, 2000 tokens, told "
159
+ "likewise), medium (at most medium, 8000 tokens) or high; a model set lower keeps its own. The "
160
+ "agent thinks low on games",
161
+ "max_wait_seconds": "accepted for older profiles. Use an explicit timeout to bound a program wait",
162
+ "strict_skills": "a configuration built in code, without skills: fail instead of dropping a skill (resolve_for)",
163
+ "task_descriptions": "a directory of task descriptions (<task>.md) added to the first message, or false",
164
+ "verifier": "check success with the verifier before finishing (default true)",
165
+ "vlm": "written by the resolution: the vlm role's client config",
166
+ "world_models": "written by the resolution: the world models' client configs",
167
+ "mcp": "written by the resolution: the MCP servers' client configs",
168
+ "approvals": "{ask} (core/approval.py): the recorded choice of sensitive steps or every program.",
169
+ "agent_skills": "the app: Agent Skills the user installed, {name: {description, path}} (skills/agent_skills)",
170
+ "installed_skills": "the app: the Harness skills the user installed, by name (the prompt's installed section, "
171
+ "runtime/decision/prompts.py)",
172
+ }
173
+ def _relative(value):
174
+ """Paths of the core's content written relative to it, a package's as packages/<name>/...
175
+ (locks are machine independent)."""
176
+ if isinstance(value, str) and value.startswith(str(REPO)):
177
+ return Path(value).relative_to(REPO).as_posix()
178
+ if isinstance(value, str):
179
+ from ..paths import packages
180
+
181
+ for package in packages():
182
+ # By whole path parts: packages/robotwin is not in packages/robot.
183
+ if Path(value).is_relative_to(package.path):
184
+ return f"packages/{package.name}/{Path(value).relative_to(package.path).as_posix()}"
185
+ if isinstance(value, list):
186
+ return [_relative(item) for item in value]
187
+ if isinstance(value, dict):
188
+ return {key: _relative(item) for key, item in value.items()}
189
+ return value
190
+
191
+
192
+ @dataclass
193
+ class ResolvedAgent:
194
+ """The agent resolved against one deploy: the conversation's main model, verifier, runtime
195
+ and prompt, the episode's model-call budget, and the lock with its identity (the
196
+ first 16 hex digits of the lock's sha256). `base_prompt` is the prompt without the
197
+ self-improvement library's additions."""
198
+
199
+ name: str
200
+ path: Path | None
201
+ main: dict
202
+ verifier: dict
203
+ runtime: dict
204
+ system_prompt: str
205
+ base_prompt: str
206
+ max_model_calls: int
207
+ lock: dict
208
+ identity: str
209
+ # Where each service the agent uses runs on this deploy (not part of the lock).
210
+ placement: dict = field(default_factory=dict)
211
+ # What it was resolved from (resolve_agent's arguments, trees): an exported
212
+ # policy resolves these again on the machine it lands on.
213
+ sources: dict = field(default_factory=dict)
214
+ # The deploy it was resolved against (without a deploy file, the harness's own
215
+ # placement of the services it uses: services/placement.py automatic()).
216
+ deploy: object = None
217
+ # The embodiment kind its skills and prompt were chosen for (embodiments.KINDS).
218
+ embodiment: str = "robot"
219
+
220
+
221
+ @dataclass
222
+ class TaskConfig:
223
+ """The configuration of one task: the worker endpoint, the main model and the
224
+ verifier, runtime settings, the prompt, the seeds and the per-episode budgets.
225
+ task_config builds one from a resolved agent; a conversation runs it."""
226
+
227
+ path: Path
228
+ environment: dict
229
+ main: dict
230
+ runtime: dict
231
+ system_prompt: str
232
+ task: str
233
+ seeds: list[int]
234
+ max_model_calls: int
235
+ max_wall_seconds: float
236
+ verifier: dict = field(default_factory=dict)
237
+ # The harness prompt without library text; attach_library builds on it.
238
+ base_prompt: str = ""
239
+ # Task description appended to the first message ("with task description").
240
+ task_description: str = ""
241
+ # Stop the episode once model and verifier calls have cost this much (USD).
242
+ max_cost_usd: float | None = None
243
+ # The resolved agent's lock and identity (config/agent.py), and where its services
244
+ # ran; None for configurations built in code.
245
+ lock: dict | None = None
246
+ agent_id: str | None = None
247
+ placement: dict | None = None
248
+ # The embodiment kind the worker drives (embodiments.KINDS).
249
+ embodiment: str = "robot"
250
+
251
+ def __post_init__(self):
252
+ if not self.base_prompt:
253
+ self.base_prompt = self.system_prompt
254
+
255
+ def snapshot(self) -> dict:
256
+ """The configuration as episode manifests and experiment.json record it (all but
257
+ `path` and `base_prompt`; the lock as `agent_lock`; the embodiment kind when it is
258
+ not the default robot). The frozen evaluator keeps its schema-2 agent lock."""
259
+ runtime = self.runtime
260
+ if runtime.get("mcp"):
261
+ runtime = {**runtime, "mcp": {name: {key: value for key, value in server.items()
262
+ if key in ("description", "read_only_tools", "allowed_tools", "tools_off", "resource", "host_write_tool")}
263
+ for name, server in runtime["mcp"].items()}}
264
+ return {"environment": self.environment, "version": __version__, "agent_version": __version__, "main": self.main,
265
+ "runtime": runtime,
266
+ "verifier": self.verifier, "system_prompt": self.system_prompt, "task": self.task,
267
+ "seeds": self.seeds, "max_model_calls": self.max_model_calls,
268
+ "max_wall_seconds": self.max_wall_seconds, "task_description": self.task_description,
269
+ "max_cost_usd": self.max_cost_usd, "agent_id": self.agent_id, "agent_lock": self.lock,
270
+ "placement": self.placement,
271
+ **({"embodiment": self.embodiment} if self.embodiment != "robot" else {})}
272
+
273
+
274
+ def _role(spec, deploy, role: str, strict: bool):
275
+ """A role's model config: its own keys, on top of its service's client config."""
276
+ if not spec:
277
+ return None, None
278
+ spec = dict(spec)
279
+ service = spec.pop("service", None)
280
+ if service is None:
281
+ # The URL is where this machine calls the model, resolved here only: a named
282
+ # variable wins over a URL in the file. The lock keeps base_url_env, not the
283
+ # value, so another machine's endpoint is the same agent.
284
+ named = spec.get("base_url_env")
285
+ from_env = os.environ.get(named, "").strip() if named else ""
286
+ if from_env:
287
+ spec["base_url"] = from_env
288
+ return route_openrouter(spec), None
289
+ base = client_config(deploy, service)
290
+ if base is None:
291
+ message = f"role {role} uses service {service}, which deploy {deploy.name} does not run"
292
+ if strict or role == "main":
293
+ raise ValueError(message)
294
+ return None, {"role": role, "service": service, "dropped": message}
295
+ return {**base, **spec}, {"role": role, "service": service}
296
+
297
+
298
+ def _service(entry, deploy, strict: bool, kind: str):
299
+ """(name, client config or None) of one service entry: a name or {service = ...}."""
300
+ spec = {"service": entry} if isinstance(entry, str) else dict(entry)
301
+ name = spec.pop("service")
302
+ base = client_config(deploy, name)
303
+ if base is None:
304
+ if strict:
305
+ raise ValueError(f"The agent's {kind} {name} is not run by deploy {deploy.name}")
306
+ return name, None
307
+ return name, {**base, **spec}
308
+
309
+
310
+ def model_services(runtime: dict, roles: dict) -> dict:
311
+ """The models and servers the kernel's skills call: VLM, pointer, segmenter, vision,
312
+ policies, world models, and the success verifier ({**main, **verifier} of the model
313
+ `roles`; direct control has none)."""
314
+ return {
315
+ "vlm": runtime.get("vlm"),
316
+ "segmenter": runtime.get("segmenter"),
317
+ "vision": runtime.get("vision"),
318
+ "pointer": runtime.get("pointer"),
319
+ "policies": runtime.get("policies", {}),
320
+ "world_models": runtime.get("world_models", {}),
321
+ "mcp": runtime.get("mcp", {}),
322
+ "verifier": ({**roles.get("main", {}), **roles.get("verifier", {})}
323
+ if runtime.get("verifier", True) and not runtime.get("mode") == "direct" else None),
324
+ }
325
+
326
+
327
+ def image_roles(services: dict) -> dict:
328
+ """The model roles of `services` (model_services) that answer about images (vlm,
329
+ pointer, verifier), each with the class that asks them (a package's host module names
330
+ it: perception's vision_model), which the episode builds in the kernel; without such a
331
+ package they are None."""
332
+ from ..extensions import first
333
+
334
+ client = first("vision_model")
335
+ return {role: ({**services[role], "class": client} if client else None)
336
+ for role in ("vlm", "pointer", "verifier") if services.get(role)}
337
+
338
+
339
+ def resolve_for(runtime: dict, roles: dict, embodiment: str = "robot") -> Resolution:
340
+ """The skills a run of this runtime configuration enables (a conversation's, the
341
+ eval package's): `runtime.skills` as resolve_agent resolved them; a configuration
342
+ built in code without them gets those of its interface layers (runtime.layers over
343
+ LAYER_DEFAULTS) that run on the embodiment kind with its services and model `roles`
344
+ ({"main", "verifier"}), and runtime.strict_skills makes a dropped one an error."""
345
+ if runtime.get("skills"):
346
+ return Resolution(list(runtime["skills"]), dict(runtime.get("skills_dropped") or {}))
347
+ return resolve(skills_for_layers(runtime.get("layers"), embodiment=embodiment),
348
+ available_services(model_services(runtime, roles)),
349
+ strict=bool(runtime.get("strict_skills", False)), embodiment=embodiment)
350
+
351
+
352
+ def model_names() -> list[str]:
353
+ """The model files of configs/models/, by name."""
354
+ return sorted(path.stem for path in MODELS_ROOT.glob("*.toml"))
355
+
356
+
357
+ def config_keys() -> dict:
358
+ """The agent's [runtime] keys and what each does: RUNTIME_KEYS, and those packages
359
+ document in their config_keys.toml ("runtime.<key>" = "what it does")."""
360
+ from ..paths import find
361
+
362
+ keys = dict(RUNTIME_KEYS)
363
+ for path in find("config_keys.toml"):
364
+ with path.open("rb") as handle:
365
+ for key, about in tomllib.load(handle).items():
366
+ name = key.removeprefix("runtime.")
367
+ keys.setdefault(name, str(about))
368
+ return dict(sorted(keys.items()))
369
+
370
+ def agent_file(value) -> Path:
371
+ """An agent file: a path, or the name of a profile (configs/profiles/<name>.toml of the
372
+ core or a package, e.g. robodojo)."""
373
+ from ..paths import find, locate
374
+
375
+ path = locate(Path(value))
376
+ if path.is_file():
377
+ return path.resolve()
378
+ found = find(f"configs/profiles/{Path(str(value)).stem}.toml")
379
+ if not found:
380
+ raise ValueError(f"No agent file or profile {value!r}")
381
+ return found[0].resolve()
382
+
383
+
384
+ def model_path(name) -> Path:
385
+ """The file of a model: a name of configs/models/, or a path to a .toml file."""
386
+ text = str(name)
387
+ if text.endswith(".toml") or "/" in text or "\\" in text:
388
+ path = Path(text).resolve()
389
+ else:
390
+ from ..paths import find
391
+
392
+ path = (find(f"configs/models/{text}.toml") or [MODELS_ROOT / f"{text}.toml"])[0]
393
+ if not path.is_file():
394
+ raise ValueError(f"No model file {path}; models: {', '.join(model_names())}")
395
+ return path
396
+
397
+
398
+ def load_model(source) -> dict:
399
+ """Model roles: a model file's name or path (with its includes), a tree as it is,
400
+ or {} for None."""
401
+ if source is None:
402
+ return {}
403
+ if isinstance(source, dict):
404
+ return source
405
+ return load_layered(model_path(source))
406
+
407
+
408
+ def resolve_agent(agent=None, *, model=None, deploy=None, strict: bool = False, name: str | None = None,
409
+ runtime_overrides: dict | None = None, embodiment: str = "robot",
410
+ channels: bool = False, package_paths=(), frozen_identity: bool = False) -> ResolvedAgent:
411
+ """Resolve the agent (a path or a merged tree; default configs/default.toml) with
412
+ model roles from `model` (a model name, path or tree; default the agent's own
413
+ `model`) against `deploy` (a Deploy, a name, or None for $HARNESS_DEPLOY), for an
414
+ embodiment kind (the bench's: its skills and prompt). strict: a service or skill the
415
+ agent names that cannot run here is an error instead of being left out.
416
+ runtime_overrides (an experiment's changes to the agent) apply after the model file's
417
+ runtime settings. channels: the bench's embodiment declares channels (the prompt's
418
+ `channels` feature). frozen_identity retains the evaluator's schema-2 hash."""
419
+ if embodiment not in KINDS:
420
+ raise ValueError(f"Unknown embodiment kind {embodiment!r}; kinds are {sorted(KINDS)}")
421
+ path = None
422
+ if agent is None:
423
+ agent = DEFAULT_AGENT
424
+ if not isinstance(agent, dict):
425
+ path = agent_file(agent)
426
+ agent = load_layered(path)
427
+ deploy = deploy if deploy is not None and not isinstance(deploy, (str, Path)) else load_deploy(deploy)
428
+ tree = dict(agent)
429
+ label = name or (path.stem if path else None)
430
+ # A kind's table changes the agent on that kind's benches; the top level is the robot's.
431
+ # Its runtime keys win over the model file's too (what a desktop sees does not
432
+ # depend on the model).
433
+ kinds = {kind: tree.pop(kind) for kind in KINDS if kind != "robot" and kind in tree}
434
+ # The table of a kind no package here registers (the core's default names a game's
435
+ # without the game package) is left out: no bench of that kind runs here.
436
+ for key in [key for key, value in tree.items() if key not in AGENT_KEYS and isinstance(value, dict) and value
437
+ and set(value) <= set(KIND_KEYS)]:
438
+ tree.pop(key)
439
+ unknown = set(tree) - set(AGENT_KEYS)
440
+ if unknown:
441
+ raise ValueError(f"Agent {path or label}: unknown keys {sorted(unknown)}")
442
+ for kind, section in kinds.items():
443
+ unknown = set(section) - set(KIND_KEYS)
444
+ if unknown:
445
+ raise ValueError(f"Agent {path or label}: [{kind}] takes {KIND_KEYS}, not {sorted(unknown)}")
446
+ if "knowledge" in section and (KINDS[kind].knowledge is None or section["knowledge"] not in KNOWLEDGE):
447
+ raise ValueError(f"Agent {path or label}: knowledge is declared by its kind, one of {list(KNOWLEDGE)}")
448
+ kind_section = dict(kinds.get(embodiment, {}))
449
+ kind_runtime = kind_section.pop("runtime", {})
450
+ default_knowledge = KINDS[embodiment].knowledge
451
+ knowledge = kind_section.pop("knowledge", default_knowledge)
452
+ tree = deep_merge(tree, kind_section)
453
+ roles_tree = load_model(model if model is not None else tree.get("model"))
454
+ unknown = set(roles_tree) - {*ROLES, "runtime", "description"}
455
+ if unknown:
456
+ raise ValueError(f"Model: unknown roles {sorted(unknown)}; roles are {ROLES} (and runtime)")
457
+ # The roles this agent uses (direct control without perception: main only).
458
+ used = tree.get("roles", list(ROLES))
459
+ if "main" not in used or set(used) - set(ROLES):
460
+ raise ValueError(f"Agent {path or label}: roles must include main and be among {ROLES}")
461
+ roles_tree = {key: value for key, value in roles_tree.items() if key not in ROLES or key in used}
462
+ if deploy.automatic:
463
+ # No deploy file: the harness places the services this agent names itself.
464
+ deploy = automatic(_service_names(roles_tree, tree.get("services", {})))
465
+ runtime = deep_merge(deep_merge(deep_merge(tree.get("runtime", {}), roles_tree.get("runtime", {})), kind_runtime),
466
+ runtime_overrides or {})
467
+ if "approvals" in runtime:
468
+ from harness.runtime.safety import approval
469
+
470
+ policy = runtime["approvals"]
471
+ if (not isinstance(policy, dict) or set(policy) - {"ask"}
472
+ or policy.get("ask", "sensitive") not in approval.ASK):
473
+ raise ValueError("runtime.approvals takes ask = sensitive or programs")
474
+ if runtime.get("task_descriptions") is False:
475
+ runtime.pop("task_descriptions")
476
+ if tree.get("mode", "program") == "direct":
477
+ if not tree.get("actions"):
478
+ raise ValueError(f"Agent {path or label}: direct mode needs actions = \"module:function\", its action "
479
+ "vocabulary")
480
+ runtime["mode"] = "direct"
481
+ runtime["actions"] = tree["actions"]
482
+ if runtime.get("contract", "native") not in KINDS[embodiment].contracts:
483
+ raise ValueError(f"runtime.contract on a {embodiment} must be one of {KINDS[embodiment].contracts}")
484
+ placement = {}
485
+ main, record = _role(roles_tree.get("main"), deploy, "main", strict)
486
+ if main is None:
487
+ raise ValueError(f"Agent {path or label}: no main model role")
488
+ if record:
489
+ placement["main"] = record
490
+ for role in ("vlm", "pointer"):
491
+ config, record = _role(roles_tree.get(role), deploy, role, strict)
492
+ if config is not None:
493
+ runtime[role] = config
494
+ if record:
495
+ placement[role] = record
496
+ # The verifier's keys sit on top of main's; a URL it names is resolved as main's is.
497
+ verifier, record = _role(roles_tree.get("verifier"), deploy, "verifier", strict)
498
+ verifier = verifier or {}
499
+ if record:
500
+ placement["verifier"] = record
501
+ services = tree.get("services", {})
502
+ unknown = set(services) - set(SERVICE_KEYS)
503
+ if unknown:
504
+ raise ValueError(f"Agent {path or label}: services are {SERVICE_KEYS}, not {sorted(unknown)}")
505
+ for key in ("segmenter", "vision"):
506
+ if services.get(key):
507
+ service, config = _service(services[key], deploy, strict, key)
508
+ placement[key] = {"service": service, **({} if config else {"dropped": "not run here"})}
509
+ if config is not None:
510
+ runtime[key] = config
511
+ for key in ("policies", "world_models", "mcp"):
512
+ entries = services.get(key, [])
513
+ chosen = {}
514
+ for entry in entries:
515
+ service, config = _service(entry, deploy, strict, SERVICE_ENTRY[key])
516
+ placement.setdefault(key, {})[service] = {} if config else {"dropped": "not run here"}
517
+ if config is not None:
518
+ chosen[service] = config
519
+ if entries:
520
+ runtime[key] = chosen
521
+ # Skills: the interface layers' (R0-R4) or a list, without the disabled ones.
522
+ skills = tree.get("skills", {})
523
+ unknown = set(skills) - {"layers", "names", "enable", "disable"}
524
+ if unknown:
525
+ raise ValueError(f"Agent {path or label}: skills takes layers, names, enable, disable; not {sorted(unknown)}")
526
+ runtime["layers"] = {**LAYER_DEFAULTS, **skills.get("layers", {})}
527
+ requested = (list(skills.get("names") or skills_for_layers(runtime["layers"], embodiment=embodiment))
528
+ + list(skills.get("enable", [])))
529
+ requested = [skill for skill in dict.fromkeys(requested) if skill not in set(skills.get("disable", []))]
530
+ if knowledge == "learned":
531
+ # The agent learns the game itself: none of the skills written for it by hand, and
532
+ # its own skill library instead.
533
+ named = sorted(set(handwritten()) & (set(skills.get("names") or ()) | set(skills.get("enable", ()))))
534
+ if named:
535
+ raise ValueError(f"Agent {path or label}: knowledge = \"learned\" gives the agent no handwritten skills, "
536
+ f"but it names {named} (knowledge = \"handwritten\" is the baseline with them)")
537
+ requested = [skill for skill in requested if skill not in set(handwritten())]
538
+ if knowledge is not None:
539
+ runtime["knowledge"] = knowledge
540
+ if (runtime.get("library") or {}).get("learn") == "on":
541
+ # A run whose library learns: programs propose entries (in-context learning), and the
542
+ # body can be probed (its package's probe, runtime/learning/active.py; the others are dropped
543
+ # as skills of another embodiment).
544
+ from harness.runtime.learning.active import schedule
545
+ from harness.runtime.execution.skills import probes
546
+
547
+ schedule(runtime["library"])
548
+ requested = [*requested, "learning", *probes()]
549
+ # A skill the agent leaves out by design (R0 has no vision roles) is dropped here on
550
+ # every machine. Strictness is about the machine: the services the agent names were
551
+ # checked above; a skill named in skills.names that cannot run is the one more error.
552
+ resolution = resolve(requested, available_services(model_services(runtime, {"main": main, "verifier": verifier})),
553
+ embodiment=embodiment)
554
+ named = {skill: why for skill, why in resolution.dropped.items()
555
+ if skill in set(skills.get("names") or ()) | set(skills.get("enable", ()))}
556
+ if strict and named:
557
+ raise ValueError(f"Agent {path or label}: skills it names cannot run: {named}")
558
+ runtime["skills"] = resolution.enabled
559
+ if resolution.dropped:
560
+ runtime["skills_dropped"] = resolution.dropped
561
+ # The prompt: a pack directory assembled for the skills, or files as they are; a
562
+ # table of them gives the embodiment's.
563
+ sources = tree.get("prompt", [])
564
+ if isinstance(sources, dict):
565
+ # Keyed by kind; a kind no package here registers names a prompt that is not used here.
566
+ if embodiment not in sources:
567
+ raise ValueError(f"Agent {path or label}: a prompt table is keyed by embodiment kinds "
568
+ f"({', '.join(sorted(KINDS))} here) and needs one for {embodiment}")
569
+ sources = sources[embodiment]
570
+ sources = [sources] if isinstance(sources, str) else list(sources)
571
+ texts = []
572
+ for source in sources:
573
+ source = Path(source)
574
+ features = features_for(runtime, channels, embodiment=embodiment)
575
+ texts.append(assemble_prompt(source, runtime["skills"], features=features,
576
+ installed=runtime.get("installed_skills", ()),
577
+ agent_skills=runtime.get("agent_skills"), embodiment=embodiment) if source.is_dir()
578
+ else select(source.read_text(encoding="utf-8"), set(runtime["skills"]) | features))
579
+ system_prompt = "".join(text if text.endswith("\n") else text + "\n" for text in texts)
580
+ base_prompt = system_prompt
581
+ if runtime.get("library"):
582
+ from harness.runtime.learning.library import library_for
583
+
584
+ library = library_for(runtime, Path("/"))
585
+ if "experience" in runtime["library"]:
586
+ table = runtime["library"]
587
+ modes = {"learn": "on", "read": "off", "off": "off"}
588
+ experience = table["experience"]
589
+ if experience not in modes:
590
+ raise ValueError("runtime.library.experience was one of read, learn, off; use runtime.library.uses")
591
+ if embodiment != "robot":
592
+ table.pop("experience")
593
+ table.setdefault("uses", modes[experience])
594
+ from harness.runtime.learning.usage import USES
595
+
596
+ if runtime["library"].get("uses", "learn") not in USES:
597
+ raise ValueError(f"runtime.library.uses is one of {list(USES)}, not {runtime['library']['uses']!r}")
598
+ from harness.runtime.learning.learner import settings as learning
599
+
600
+ captured = library.capture()
601
+ if learning(runtime["library"])["learn"] == "on":
602
+ # A library that learns grows from run to run: the configuration names it and
603
+ # its settings, and each run records the version it started with.
604
+ runtime["library"] = {**runtime["library"], "manifest": {
605
+ "directory": str(library.directory), "layers": list(library.layers), "learns": True}}
606
+ else:
607
+ runtime["library"] = {**runtime["library"], "path": str(library.directory),
608
+ "manifest": captured.manifest()}
609
+ reactive = "reactive" in runtime["skills"]
610
+ selected = {item.key for item in captured.entries if item.key.startswith("skills/")
611
+ or reactive and item.key.startswith("reactive/")}
612
+ system_prompt += captured.api_summary(selected) + captured.notes()
613
+ budget = tree.get("budget", {})
614
+ calls = int(budget.get("max_model_calls", 30))
615
+ if calls < 1:
616
+ raise ValueError("budget.max_model_calls must be a positive integer")
617
+ lock = {
618
+ "schema": 2,
619
+ "agent": label,
620
+ "mode": runtime.get("mode", "program"),
621
+ # A library that learns: the prompt without what it holds (each run records its version).
622
+ "prompt_sha256": hashlib.sha256((base_prompt if (runtime.get("library") or {}).get("manifest", {}).get("learns")
623
+ else system_prompt).encode()).hexdigest(),
624
+ "prompt_sources": _relative([str(s) for s in sources]),
625
+ "skills": runtime["skills"],
626
+ "skills_dropped": runtime.get("skills_dropped", {}),
627
+ # Roles by what they are, not where they run: a service-backed role is its service.
628
+ "roles": {role: _lock_role(roles_tree.get(role)) for role in ROLES if roles_tree.get(role)},
629
+ "services": {key: services.get(key) for key in SERVICE_KEYS if services.get(key)},
630
+ # Without [environment]: how a service is installed does not change what it computes.
631
+ "service_manifests": {service: sha256({key: value for key, value in read_toml(deploy.services[service].path)
632
+ .items() if key != "environment"})
633
+ for service in _service_names(roles_tree, services) if service in deploy.services},
634
+ "runtime": _relative({key: value for key, value in runtime.items()
635
+ if key not in ("vlm", "pointer", "segmenter", "vision", "policies", "world_models", "mcp")}),
636
+ "budget": {"max_model_calls": calls},
637
+ }
638
+ if frozen_identity:
639
+ # Keep the original hash input for an unchanged score configuration and
640
+ # let the evaluator continue to reject genuinely different settings.
641
+ lock["agent_version"] = __version__
642
+ else:
643
+ lock.update(schema=3, version=__version__,
644
+ packages=package_lock([path, *package_paths, *sources, *(deploy.services[name].path for name in
645
+ _service_names(roles_tree, services) if name in deploy.services), *(
646
+ skill.path for name, skill in _skills().items() if name in runtime["skills"])]))
647
+ if embodiment != "robot":
648
+ lock["embodiment"] = embodiment
649
+ return ResolvedAgent(name=label, path=path, main=main, verifier=verifier, runtime=runtime,
650
+ system_prompt=system_prompt, base_prompt=base_prompt, max_model_calls=calls, lock=lock,
651
+ identity=sha256(lock)[:16], placement=placement,
652
+ sources={"agent": {key: value for key, value in tree.items() if key != "model"},
653
+ "model": roles_tree, "runtime_overrides": runtime_overrides or {}},
654
+ embodiment=embodiment, deploy=deploy)
655
+
656
+
657
+ def _skills() -> dict:
658
+ from harness.runtime.execution.skills import load_skills
659
+
660
+ return load_skills()
661
+
662
+
663
+ def package_lock(used=()) -> dict:
664
+ """Lock the packages containing `used` paths and their installed dependencies.
665
+ Registry store entries use the archive digest. Checkouts and local or linked
666
+ packages use a content hash."""
667
+ from ..packages import Packages
668
+ from ..packages.state import store_path
669
+ from ..paths import packages
670
+
671
+ used = [Path(item).resolve() for item in used if item]
672
+ available = {package.name: package for package in packages()}
673
+ roots = {name: package.path.resolve() for name, package in available.items()}
674
+ selected = {name for name, root in roots.items() if any(path.is_relative_to(root) for path in used)}
675
+ pending = list(selected)
676
+ while pending:
677
+ dependencies = (available[pending.pop()].depends.keys() & available.keys()) - selected
678
+ selected.update(dependencies)
679
+ pending.extend(dependencies)
680
+ if not selected:
681
+ return {}
682
+
683
+ installed = Packages().records()
684
+ lock = {}
685
+ for name in sorted(selected):
686
+ package, root = available[name], roots[name]
687
+ record, _ = installed.get(name, (None, None))
688
+ released = (record is not None and record.source == "registry" and record.sha256 and not record.link
689
+ and record.version == package.version
690
+ and root == store_path(name, record.version, record.sha256).resolve())
691
+ lock[name] = {"version": package.version,
692
+ **({"sha256": record.sha256} if released else {"content": package_content(root)})}
693
+ return lock
694
+
695
+
696
+ def package_content(root: Path) -> str:
697
+ """Hash a local package's file paths and content, excluding installed dependencies and caches."""
698
+ digest = hashlib.sha256()
699
+ excluded = {"__pycache__", ".deps", ".git", "node_modules", ".pytest_cache"}
700
+ for path in sorted(root.rglob("*")):
701
+ relative = path.relative_to(root)
702
+ if not path.is_file() or any(part in excluded or part.startswith(".venv") for part in relative.parts):
703
+ continue
704
+ name = relative.as_posix().encode()
705
+ with path.open("rb") as file:
706
+ content = hashlib.file_digest(file, "sha256").digest()
707
+ digest.update(name + b"\0" + content)
708
+ return digest.hexdigest()
709
+
710
+
711
+ def overridden_agent(overrides: dict | None = None, *, agent=None, model=None, deploy=None, strict: bool = False,
712
+ embodiment: str = "robot", channels: bool = False, package_paths=(), frozen_identity: bool = False) -> ResolvedAgent:
713
+ """The agent file (default configs/default.toml) with `overrides` ({"agent": ...,
714
+ "model": ...}, an experiment's or a conversation's changes) applied and its model roles
715
+ from `model` (default the agent's), resolved against `deploy` (resolve_agent)."""
716
+ overrides = overrides or {}
717
+ unknown = set(overrides) - {"agent", "model"}
718
+ if unknown:
719
+ raise ValueError(f"overrides are [overrides.agent] and [overrides.model], not {sorted(unknown)}")
720
+ path = agent_file(agent or DEFAULT_AGENT)
721
+ tree = deep_merge(load_layered(path), overrides.get("agent", {}))
722
+ roles = deep_merge(load_model(model or tree.get("model")), overrides.get("model", {}))
723
+ return resolve_agent(tree, model=roles, deploy=deploy, strict=strict, name=path.stem,
724
+ runtime_overrides=overrides.get("agent", {}).get("runtime"), embodiment=embodiment,
725
+ channels=channels, package_paths=[path, *package_paths], frozen_identity=frozen_identity)
726
+
727
+
728
+ def task_description(runtime: dict, task: str) -> str:
729
+ """The task's description (RoboDojo wiki recipe) when the agent uses them."""
730
+ directory = runtime.get("task_descriptions")
731
+ if not directory:
732
+ return ""
733
+ source = Path(directory) / f"{task.removesuffix('_random')}.md"
734
+ if not source.is_file():
735
+ raise ValueError(f"No task description for {task} in {directory}")
736
+ return source.read_text(encoding="utf-8").strip()
737
+
738
+
739
+ def task_config(agent: ResolvedAgent, task: str, seeds, *, budget: dict | None = None, endpoint: str | None = None,
740
+ timeout_seconds: float = 600.0, path: Path | None = None):
741
+ """The configuration (TaskConfig) of `task` with `seeds` for a
742
+ resolved agent, under a per-episode `budget` (max_model_calls, max_wall_seconds,
743
+ max_cost_usd) and against the worker at `endpoint`."""
744
+
745
+ seeds = list(seeds)
746
+ if not seeds or any(type(seed) is not int for seed in seeds) or len(set(seeds)) != len(seeds):
747
+ raise ValueError("seeds must be a nonempty list of distinct integers")
748
+ budget = budget or {}
749
+ cost = budget.get("max_cost_usd")
750
+ if cost is not None and (isinstance(cost, bool) or not isinstance(cost, (int, float)) or cost <= 0):
751
+ raise ValueError("budget.max_cost_usd must be a positive number")
752
+ return TaskConfig(
753
+ path=path or Path("."), environment={"endpoint": endpoint, "timeout_seconds": timeout_seconds},
754
+ main=dict(agent.main), runtime=dict(agent.runtime), system_prompt=agent.system_prompt, task=task,
755
+ seeds=seeds, max_model_calls=int(budget.get("max_model_calls", agent.max_model_calls)),
756
+ max_wall_seconds=float(budget.get("max_wall_seconds", 3600)), verifier=dict(agent.verifier),
757
+ base_prompt=agent.base_prompt, task_description=task_description(agent.runtime, task),
758
+ max_cost_usd=None if cost is None else float(cost), lock=agent.lock, agent_id=agent.identity,
759
+ placement={"deploy": getattr(agent.deploy, "name", None), **agent.placement},
760
+ embodiment=agent.embodiment)
761
+
762
+
763
+ def _lock_role(spec):
764
+ spec = dict(spec)
765
+ return {key: value for key, value in spec.items() if key not in ("api_key", "base_url")} \
766
+ if "service" in spec else {key: value for key, value in spec.items() if key != "api_key"}
767
+
768
+
769
+ def _service_names(roles_tree, services):
770
+ names = [spec["service"] for spec in roles_tree.values() if isinstance(spec, dict) and "service" in spec]
771
+ for key in ("segmenter", "vision"):
772
+ if services.get(key):
773
+ entry = services[key]
774
+ names.append(entry if isinstance(entry, str) else entry["service"])
775
+ for key in ("policies", "world_models", "mcp"):
776
+ names += [entry if isinstance(entry, str) else entry["service"] for entry in services.get(key, [])]
777
+ return sorted(set(names))