@lmmslab/harness 0.85.0 → 0.86.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +2 -2
  4. package/python/harness/bench.py +2 -2
  5. package/python/harness/builtin/benches/README.md +1 -2
  6. package/python/harness/builtin/configs/default.toml +4 -19
  7. package/python/harness/builtin/configs/deploy/example-api.toml +1 -1
  8. package/python/harness/builtin/configs/models/deepseek-flash.toml +1 -1
  9. package/python/harness/builtin/configs/models/grok-low.toml +1 -1
  10. package/python/harness/builtin/configs/models/grok-medium.toml +3 -6
  11. package/python/harness/builtin/environment/README.md +8 -25
  12. package/python/harness/builtin/prompts/conversation/core.md +6 -5
  13. package/python/harness/builtin/prompts/core/core.md +147 -203
  14. package/python/harness/builtin/prompts/core/pack.toml +0 -1
  15. package/python/harness/builtin/prompts/reflect/core.md +8 -32
  16. package/python/harness/builtin/prompts/reflect/pack.toml +2 -4
  17. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -3
  18. package/python/harness/builtin/prompts/shared/agents.md +20 -10
  19. package/python/harness/builtin/prompts/shared/checklist.md +13 -17
  20. package/python/harness/builtin/prompts/shared/environments.md +20 -15
  21. package/python/harness/builtin/prompts/shared/learning-goal.md +2 -3
  22. package/python/harness/builtin/prompts/shared/learning.md +73 -23
  23. package/python/harness/builtin/prompts/shared/mcp.md +11 -6
  24. package/python/harness/builtin/prompts/shared/reflex-method.md +243 -0
  25. package/python/harness/builtin/prompts/shared/units.md +138 -0
  26. package/python/harness/builtin/prompts/shared/web.md +5 -6
  27. package/python/harness/builtin/skills/agents/__init__.py +18 -3
  28. package/python/harness/builtin/skills/agents/skill.toml +3 -3
  29. package/python/harness/builtin/skills/checklist/__init__.py +34 -32
  30. package/python/harness/builtin/skills/checklist/skill.toml +9 -9
  31. package/python/harness/builtin/skills/environments/__init__.py +9 -5
  32. package/python/harness/builtin/skills/environments/skill.toml +1 -1
  33. package/python/harness/builtin/skills/experience/skill.toml +1 -1
  34. package/python/harness/builtin/skills/learning/__init__.py +19 -5
  35. package/python/harness/builtin/skills/mcp/skill.toml +1 -1
  36. package/python/harness/builtin/skills/memory/__init__.py +4 -1
  37. package/python/harness/builtin/skills/memory/skill.toml +0 -5
  38. package/python/harness/builtin/skills/verify/skill.toml +1 -0
  39. package/python/harness/builtin/skills/web/__init__.py +4 -1
  40. package/python/harness/builtin/third_party/sources.toml +2 -40
  41. package/python/harness/cli.py +16 -25
  42. package/python/harness/config/__init__.py +2 -2
  43. package/python/harness/config/agent.py +59 -47
  44. package/python/harness/core/__init__.py +1 -1
  45. package/python/harness/core/codec.py +4 -4
  46. package/python/harness/core/contracts.py +1 -1
  47. package/python/harness/core/media.py +1 -1
  48. package/python/harness/core/ports.py +2 -2
  49. package/python/harness/core/procs.py +1 -1
  50. package/python/harness/core/remote.py +1 -1
  51. package/python/harness/core/worker.py +19 -13
  52. package/python/harness/embodiments.py +53 -44
  53. package/python/harness/extensions.py +22 -0
  54. package/python/harness/host/__init__.py +1 -1
  55. package/python/harness/host/http.py +6 -12
  56. package/python/harness/host/sessions.py +1 -1
  57. package/python/harness/host/tasks.py +15 -11
  58. package/python/harness/host/workspaces.py +36 -8
  59. package/python/harness/packages/__init__.py +5 -5
  60. package/python/harness/packages/environments.py +30 -18
  61. package/python/harness/packages/manager.py +1 -1
  62. package/python/harness/packages/manifest.py +6 -6
  63. package/python/harness/packages/provision.py +1 -1
  64. package/python/harness/packages/sources.py +1 -1
  65. package/python/harness/paths.py +1 -1
  66. package/python/harness/runtime/decision/loop.py +95 -5
  67. package/python/harness/runtime/decision/messages.py +128 -2
  68. package/python/harness/runtime/decision/model.py +4 -5
  69. package/python/harness/runtime/decision/prompts.py +20 -32
  70. package/python/harness/runtime/events.py +7 -5
  71. package/python/harness/runtime/execution/attached.py +3 -3
  72. package/python/harness/runtime/execution/entries.py +189 -8
  73. package/python/harness/runtime/execution/kernel.py +26 -1
  74. package/python/harness/runtime/execution/results.py +2 -3
  75. package/python/harness/runtime/execution/session.py +417 -32
  76. package/python/harness/runtime/execution/skills.py +63 -16
  77. package/python/harness/runtime/learning/active.py +7 -7
  78. package/python/harness/runtime/learning/learner.py +3 -2
  79. package/python/harness/runtime/learning/library.py +9 -4
  80. package/python/harness/runtime/learning/reflect.py +10 -9
  81. package/python/harness/runtime/reactive/rules.py +4 -4
  82. package/python/harness/runtime/reactive/tree.py +506 -25
  83. package/python/harness/runtime/safety/input.py +1 -1
  84. package/python/harness/runtime/safety/isolation.py +3 -3
  85. package/python/harness/runtime/safety/shield.py +4 -50
  86. package/python/harness/runtime/task/delegation.py +5 -5
  87. package/python/harness/runtime/task/environments.py +10 -0
  88. package/python/harness/runtime/task/run.py +222 -27
  89. package/python/harness/runtime/tick.py +24 -1
  90. package/python/harness/sdk/__init__.py +2 -5
  91. package/python/harness/services/registry.py +23 -19
  92. package/python/harness/settings.py +9 -9
  93. package/python/harness/builtin/environment/constraints.txt +0 -31
  94. package/python/harness/builtin/prompts/shared/world.md +0 -1
@@ -1,25 +1,19 @@
1
- """Embodiments: what a robot or a computer is, independent of how a run reaches it.
1
+ """Embodiments: what an agent acts through, independent of how a run reaches it.
2
2
 
3
3
  embodiments/<name>/embodiment.toml holds the facts a policy may know about the
4
- embodiment without asking a simulator. Its `kind` (KINDS, default robot) decides the
5
- session that drives it (runtime/execution/session.py), the skills that run on it (a skill's
6
- `embodiments`) and the keys it must have.
7
-
8
- A robot's file holds joint groups and limits, arm mounts, the fingertip offset, gripper
9
- widths and readings, control rate, planner limits, camera calibration (head camera fixed
10
- in the world, wrist cameras fixed on link6), the action keys of XPolicyLab's protocol,
11
- and the shield's defaults. A simulator worker reports the same facts live in its
12
- profile; the XPolicyLab connector and contract-restricted workers take them from here.
13
- A computer's (desktop) file holds its screen and the rate of its input steps; a game's
14
- the screen of its window, the keys its inputs can press and the rate of a still step.
15
-
16
- KINDS is everything the core knows that differs between kinds; a new kind is one entry
17
- here, its session class, its skills (a skill's `embodiments`), a prompt and a bench
4
+ embodiment without asking its worker. Its `kind` (KINDS) decides the session that drives
5
+ it (runtime/execution/session.py), the skills that run on it (a skill's `embodiments`)
6
+ and the keys it must have. An embodiment file and a worker's profile name their kind.
7
+
8
+ KINDS is everything the core knows that differs between kinds. The core has one kind of
9
+ its own, a conversation with no environment ("none"). Every other kind is a package's:
10
+ one table in its kinds.toml, with its session class, its skills (a skill's
11
+ `embodiments`), its prompt, the agent's settings on it and a bench
18
12
  (benches/<name>/bench.toml `kind`).
19
13
  """
20
14
 
21
15
  from collections.abc import Mapping
22
- from dataclasses import dataclass, replace
16
+ from dataclasses import dataclass, field, replace
23
17
  from pathlib import Path
24
18
  import tomllib
25
19
 
@@ -31,10 +25,10 @@ EMBODIMENTS_ROOT = ROOT / "embodiments"
31
25
 
32
26
  @dataclass(frozen=True)
33
27
  class Kind:
34
- """An embodiment kind. A worker reports its kind in its profile (`kind`, default robot)."""
28
+ """An embodiment kind. A worker reports its kind in its profile (`kind`)."""
35
29
 
36
30
  name: str
37
- # What it is, in the documentation ("a robot").
31
+ # What it is, in the documentation ("a computer").
38
32
  what: str
39
33
  # The keys an embodiment file of the kind must have.
40
34
  file_keys: tuple[str, ...]
@@ -51,11 +45,30 @@ class Kind:
51
45
  state_keys: tuple[str, ...]
52
46
  cameras: tuple[str, ...]
53
47
  # Where its agents' sub-agents run when the session has no place of its own to give
54
- # ("module:Class", a runtime/task/delegation.py Place: a game's view of the agent's episode).
48
+ # ("module:Class", a runtime/task/delegation.py Place: a view of the agent's episode).
55
49
  place: str = ""
56
50
  knowledge: str | None = None
57
51
  native_features: tuple[str, ...] = ()
58
52
  prompt_features: tuple[str, ...] = ()
53
+ # Its prompt pack (a directory; in kinds.toml a path from the package's folder), used
54
+ # where the agent's configuration names none for the kind.
55
+ prompt: str = ""
56
+ # The agent's settings on this kind (config/agent.py KIND_KEYS: roles, skills, services,
57
+ # runtime, budget, knowledge), under what the agent's own table for the kind says.
58
+ agent: Mapping = field(default_factory=dict)
59
+ # Locks and snapshots of an agent on this kind do not name the kind: for a kind whose
60
+ # locks were made before kinds were recorded, so that they keep their hash.
61
+ unnamed_in_lock: bool = False
62
+ # Its library keeps the setting `experience` as it is (config/agent.py); for every other
63
+ # kind that setting is read as `uses`.
64
+ library_experience: bool = False
65
+ # Recording a use of a library entry waits for the host's answer (builtin/skills/learning).
66
+ record_waits: bool = True
67
+ # After each program the model is given recent notes and the nearest places (builtin/skills/memory).
68
+ memory_report: bool = True
69
+ # Its own variant of a skill: {skill: {"summary", "mixin", "exports"}} in place of the
70
+ # skill's (runtime/execution/skills.py Skill.for_embodiment).
71
+ interfaces: Mapping = field(default_factory=dict)
59
72
 
60
73
 
61
74
  # The core's own kind: a conversation without an environment (runtime/execution/noenv.py).
@@ -70,8 +83,8 @@ _CORE_KINDS = {kind.name: kind for kind in (
70
83
 
71
84
 
72
85
  class _Kinds(Mapping):
73
- """The core's kinds (robot, desktop, game) and those packages register in their
74
- kinds.toml, one table per kind with the fields of Kind:
86
+ """The core's kind (none) and those packages register in their kinds.toml, one table
87
+ per kind with the fields of Kind:
75
88
 
76
89
  [drone]
77
90
  what = "a drone"
@@ -107,7 +120,15 @@ class _Kinds(Mapping):
107
120
  cameras=tuple(row.get("cameras", ())), place=str(row.get("place", "")),
108
121
  knowledge=row.get("knowledge"),
109
122
  native_features=tuple(row.get("native_features", ())),
110
- prompt_features=tuple(row.get("prompt_features", ())))
123
+ prompt_features=tuple(row.get("prompt_features", ())),
124
+ prompt=str((path.parent / row["prompt"]).resolve()) if row.get("prompt") else "",
125
+ agent=dict(row.get("agent", {})),
126
+ unnamed_in_lock=bool(row.get("unnamed_in_lock", False)),
127
+ library_experience=bool(row.get("library_experience", False)),
128
+ record_waits=bool(row.get("record_waits", True)),
129
+ memory_report=bool(row.get("memory_report", True)),
130
+ interfaces={skill: dict(variant)
131
+ for skill, variant in row.get("interfaces", {}).items()})
111
132
  registered = contracts()
112
133
  for name, kind in list(kinds.items()):
113
134
  extra = tuple(contract for contract, row in registered.items()
@@ -134,10 +155,10 @@ def contracts() -> dict:
134
155
  """{name: {"kind", "filter", "summary"}}: the observation contracts the packages register in
135
156
  their contracts.toml, one table per contract:
136
157
 
137
- [xpolicylab]
138
- kind = "robot"
139
- filter = "harness_robodojo.contract:XPolicyLabContract"
140
- summary = "what RoboDojo's official client hands a policy"
158
+ [name]
159
+ kind = "the kind it is for"
160
+ filter = "package.module:Class"
161
+ summary = "one line: what a policy is handed under it"
141
162
 
142
163
  A filter is a class taking the embodiment, whose apply(method, arguments, result) gives
143
164
  what a worker method returned as the contract shows it (core/worker.py)."""
@@ -184,9 +205,11 @@ def embodiment_path(name) -> Path:
184
205
 
185
206
 
186
207
  def embodiment_kind(data: dict) -> str:
187
- """The kind of an embodiment tree or a worker profile (default robot); an unknown kind
188
- is an error."""
189
- kind = data.get("kind", "robot")
208
+ """The kind of an embodiment tree or a worker profile, which names it; a missing or
209
+ unknown kind is an error."""
210
+ kind = data.get("kind")
211
+ if kind is None:
212
+ raise ValueError(f"No embodiment kind is named (`kind`); kinds are {sorted(KINDS)}")
190
213
  if kind not in KINDS:
191
214
  raise ValueError(f"Unknown embodiment kind {kind!r}; kinds are {sorted(KINDS)}")
192
215
  return kind
@@ -194,24 +217,10 @@ def embodiment_kind(data: dict) -> str:
194
217
 
195
218
  def load_embodiment(name) -> dict:
196
219
  """An embodiment's tree (a name or a path, see embodiment_path); it must have the keys
197
- of its kind (KINDS): a robot's name, control_hz, groups, arm_bases and cameras."""
220
+ of its kind (KINDS)."""
198
221
  with embodiment_path(name).open("rb") as handle:
199
222
  data = tomllib.load(handle)
200
223
  for key in KINDS[embodiment_kind(data)].file_keys:
201
224
  if key not in data:
202
225
  raise ValueError(f"Embodiment {name}: missing {key}")
203
226
  return data
204
-
205
-
206
- def profile(embodiment: dict) -> dict:
207
- """The worker profile a robot embodiment implies (what a simulator worker reports
208
- live), for connections without a simulator."""
209
- if embodiment_kind(embodiment) != "robot":
210
- raise ValueError(f"Embodiment {embodiment['name']}: a worker profile is built here for robots only")
211
- groups = [{"name": name, "joints": list(group["joints"]), "gripper": group["gripper"]}
212
- for name, group in embodiment["groups"].items()]
213
- keys = ("control_hz", "physics_steps_per_tick", "action_low", "action_high", "cameras", "planner_limits",
214
- "tip_offset_m", "gripper_empty_opening", "gripper_open_width_m", "table_z", "return_to_start",
215
- "shield", "planner_world")
216
- return {"groups": groups, "arm_bases": {k: list(v) for k, v in embodiment["arm_bases"].items()},
217
- "embodiment": embodiment["name"], **{key: embodiment[key] for key in keys if key in embodiment}}
@@ -8,6 +8,8 @@ by name and imports no package itself. A host module may define:
8
8
  the package. Duplicate kind names are rejected;
9
9
  the core never falls back to a built-in backend.
10
10
  note(values) -> str a line about this computer over the terminal chat's /settings
11
+ run_arguments(command) the package's own flags of `harness run`, added to its parser
12
+ run_sets(args) -> list what those flags stand for: experiment overrides "key=value"
11
13
  waiting(owner) -> str | None what an agent of a session waits for (the input lock)
12
14
  recording(directory) -> dict a run's screen recording ({"path", "start", "stop",
13
15
  "area"}), or None
@@ -97,6 +99,26 @@ def first(name: str):
97
99
  return None
98
100
 
99
101
 
102
+ def run_arguments(command) -> None:
103
+ """Let each package add its own flags to `harness run` (a host module's
104
+ run_arguments(command), given the command's argument parser)."""
105
+ for module in modules():
106
+ add = getattr(module, "run_arguments", None)
107
+ if add is not None:
108
+ add(command)
109
+
110
+
111
+ def run_sets(args) -> list:
112
+ """What the packages' own flags stand for, as experiment overrides ["key=value", ...]
113
+ (a host module's run_sets(args)); a ValueError says why a flag does not fit."""
114
+ found = []
115
+ for module in modules():
116
+ sets = getattr(module, "run_sets", None)
117
+ if sets is not None:
118
+ found += list(sets(args) or ())
119
+ return found
120
+
121
+
100
122
  def require(name: str, what: str, provider: str):
101
123
  """What `name` is in a host module, installing the package that provides `provider` among
102
124
  its `what` first (as packages.auto_install says) when none has it: the app package's
@@ -216,7 +216,7 @@ class Host:
216
216
  mcp_tools=(), model_entry=None, reasoning_effort=None, library=None, budget=None) -> RemoteConversation:
217
217
  """Start a conversation of the app's agent with the first message `text`. `workspace`:
218
218
  where it works: "none" (no environment: the conversation, the model and the connected
219
- tools only), "project" (with `folder`), "browser", "desktop", "apps", "display"; with
219
+ tools only) or a kind the installed packages give (one that works in a folder: with `folder`); with
220
220
  "auto" (and no `folder`) the setting session.environment decides, and its default
221
221
  `ask` raises ChoiceRequired here, where nobody can be asked: name the workspace.
222
222
  `confirmation`: else approvals.ask;
@@ -150,17 +150,6 @@ COOKIE = "harness_ui"
150
150
  # The pages of the package at / besides that one (the server's own: Server.page); other
151
151
  # packages' pages are their host modules' (pages()).
152
152
  PAGES = {"/": None, "/dev": "index.html", "/overlay": "overlay.html", "/replay": "app.html"}
153
- # The workspace kind of a bench's worker (the computer package's workspaces.py KINDS, the
154
- # other way round); a computer worker with the option workspace = "apps" or "display"
155
- # serves that kind.
156
- BENCH_KINDS = {"browser": "browser", "computer": "desktop"}
157
-
158
-
159
- def bench_kind(bench: str, worker: dict | None = None) -> str | None:
160
- """The workspace kind an experiment's worker serves (None: one no pool starts)."""
161
- if bench == "computer" and (worker or {}).get("workspace") in ("apps", "display"):
162
- return worker["workspace"]
163
- return BENCH_KINDS.get(bench)
164
153
  # Seconds between looks at a followed trace, and between keep-alive comments.
165
154
  POLL_SECONDS = 0.25
166
155
  KEEPALIVE_SECONDS = 15.0
@@ -244,6 +233,11 @@ class Server(OwnPort, ThreadingHTTPServer):
244
233
  return Path(self.conversations[found].directory).resolve()
245
234
  return runs.episode_dir(self.root, run)
246
235
 
236
+ def workspace_kind(self, bench: str, worker: dict | None = None) -> str | None:
237
+ """The workspace kind an experiment's worker serves, as the installed packages'
238
+ providers say (host/workspaces.py kind_of); None here, where no pool starts one."""
239
+ return None
240
+
247
241
  def sub_agents(self, kind: str | None):
248
242
  """The sub-agents of a session started here whose workspace is of `kind` (None: a
249
243
  bench no workspace pool serves)."""
@@ -293,7 +287,7 @@ class Server(OwnPort, ThreadingHTTPServer):
293
287
  preflight(experiment, log=lambda message: print(message, flush=True))
294
288
  with self._starting:
295
289
  directory, run = self.session_directory(request, config, seed)
296
- kind = (workspace or {}).get("kind") or bench_kind(experiment.bench, experiment.worker)
290
+ kind = (workspace or {}).get("kind") or self.workspace_kind(experiment.bench, experiment.worker)
297
291
  conversation = TaskRun(config, seed, directory, interactive=True, confirmation=confirmation,
298
292
  environment=(workspace or {}).get("environment"),
299
293
  instruction=(request.get("instruction") or "").strip() or None,
@@ -434,7 +434,7 @@ def history(index: Path, skip=()) -> list[dict]:
434
434
 
435
435
 
436
436
  def _waiting(owner: dict) -> str | None:
437
- """What an agent of a session waits for, as a package says (the computer's input lock;
437
+ """What an agent of a session waits for, as a package says (its input lock;
438
438
  harness/extensions.py)."""
439
439
  from ..extensions import first
440
440
 
@@ -67,7 +67,7 @@ class TaskHost:
67
67
  # first, as the settings a package adds are checked by its own code.
68
68
  self.packages = activate(Packages(self.directory))
69
69
  self.prune()
70
- # Where conversations run: a package's (the computer's), made when first asked for.
70
+ # Where conversations run: a package's, made when first asked for.
71
71
  self._workspaces = None
72
72
  self.starting = {}
73
73
  # Brings the chat's browser window to the front (the app package's focus, set by run()).
@@ -122,14 +122,14 @@ class TaskHost:
122
122
 
123
123
  def kind(self, workspace: str | None = None, text: str | None = None) -> str:
124
124
  """The workspace kind a new conversation takes: `workspace` ("auto": the one its task
125
- in words asks for), else the computer's mode."""
125
+ in words asks for), else the kind a package preselects."""
126
126
  return self.workspaces.kind(workspace, text)
127
127
 
128
128
  def environments(self, model_entry: str | None = None) -> dict:
129
129
  """What a new conversation may work in, for a frontend's choice: {"options": each
130
130
  kind the core and the installed packages give ({"value", "label", "about"} and its
131
131
  "folder", "views" and "physical" flags), "selected": what the choice highlights (the
132
- last conversation's, else a saved computer.mode, else None: nothing is preselected),
132
+ last conversation's, else what a package preselects, else None),
133
133
  "folder": the last project folder, "setting": session.environment}. An environment
134
134
  with a screen carries a `note` when the model (`model_entry`, default the chosen
135
135
  one) reads no images: the user is told before they choose."""
@@ -142,7 +142,8 @@ class TaskHost:
142
142
  kinds = [row["value"] for row in options]
143
143
  last = self.settings.remembered("session", "last_environment")
144
144
  if last not in kinds:
145
- last = self.settings.remembered("computer", "mode")
145
+ # What a package preselects for its own kinds (a setting of the package's).
146
+ last = self.workspaces.preselected()
146
147
  return {"options": options, "selected": last if last in kinds else None,
147
148
  "folder": self.settings.remembered("session", "last_folder") or None,
148
149
  "setting": self.settings.get()["session"]["environment"]}
@@ -172,8 +173,8 @@ class TaskHost:
172
173
  found.setdefault(kind, {"value": kind, "label": kind.replace("-", " ").capitalize(),
173
174
  "about": f"{row['summary']} (installs the package {row['name']})",
174
175
  "package": row["name"]})
175
- from .workspaces import ORDER
176
- return [found[kind] for kind in (*[k for k in ORDER if k in found], *sorted(set(found) - set(ORDER)))]
176
+ # In the order the registry lists the packages and each package lists its workspaces.
177
+ return list(found.values())
177
178
 
178
179
  def install_environment(self, workspace: str) -> bool:
179
180
  """Install the registry's package of an environment no installed package gives
@@ -280,7 +281,7 @@ class TaskHost:
280
281
  def config(self, model=None, kind=None, profile=None, *, choice=None, effort=None, agents=None):
281
282
  """The configuration (TaskConfig) of an assistant conversation with the user's model (or
282
283
  `model`, another id of the same provider) and settings, in a workspace of `kind`
283
- (default: the computer's mode), of a package's `profile` (profiles()); its endpoint is
284
+ (default: the kind a package preselects), of a package's `profile` (profiles()); its endpoint is
284
285
  set when the workspace runs."""
285
286
  from ..bench import bench_specs, declares_channels
286
287
  from ..extensions import hosts
@@ -393,8 +394,8 @@ class TaskHost:
393
394
  agents: bool | None = None) -> dict:
394
395
  """The skills a new conversation enables: checklist unless the user turned it off, chat
395
396
  (stay_on_screen), screens (several monitors), the installed ones that are on;
396
- instructions when an Agent Skill is on; browser in a browser workspace, physical
397
- (asking for the real mouse and keyboard up front) on the desktop; environments
397
+ instructions when an Agent Skill is on; those the workspace's package names for its
398
+ kind; environments
398
399
  (taking another environment, asking for sub-agents); agents (sub-agents) only when
399
400
  they are on (`agents`, default the setting session.agents) and the nesting depth
400
401
  allows one; entries (parts of the work that run beside the programs). An installed
@@ -493,7 +494,7 @@ class TaskHost:
493
494
  raise ValueError("give a package name, a folder, an archive or a git URL")
494
495
 
495
496
  def kernel_python():
496
- # A skill's requirements are for the kernel: the environment of the computer's mode.
497
+ # A skill's requirements are for the kernel: the environment of the kind a package preselects.
497
498
  kind = self.kind()
498
499
  return self.workspaces.provider(kind).python(kind, log=lambda message: None)
499
500
 
@@ -508,7 +509,7 @@ class TaskHost:
508
509
 
509
510
  def conversation_tree(self, values: dict, kind: str | None = None) -> dict:
510
511
  """The assistant's configuration (configs/assistant.toml) with the user's limits, in a
511
- workspace of `kind` (default: the computer's mode)."""
512
+ workspace of `kind` (default: the kind a package preselects)."""
512
513
  from ..config import load_layered
513
514
 
514
515
  tree = load_layered(CONVERSATION)
@@ -1454,6 +1455,9 @@ class TaskServer(Server):
1454
1455
  def sub_agents(self, kind):
1455
1456
  return self.app.sub_agents(self, kind)
1456
1457
 
1458
+ def workspace_kind(self, bench, worker=None):
1459
+ return self.app.workspaces.kind_of(bench, worker)
1460
+
1457
1461
  def model_changed(self, run, changed):
1458
1462
  self.app.model_changed(self, run, changed)
1459
1463
 
@@ -25,14 +25,20 @@ class WorkspaceProvider:
25
25
  """How a kind is offered when a conversation chooses where to work: {"label",
26
26
  "about"}, and optionally "folder" (it is bound to a folder the user names),
27
27
  "views" (it has pictures the model may look at: a model that reads no images
28
- works there from text and structure only) and "physical" (it may use the user's
29
- real mouse and keyboard)."""
28
+ works there from text and structure only), "physical" (it may use the user's
29
+ real mouse and keyboard) and "order" (its place among the kinds offered, the lower
30
+ the earlier; 100 without one)."""
30
31
  return {"label": kind, "about": ""}
31
32
 
32
33
  def environment(self, kind):
33
34
  """An environment in this process for a kind that takes no worker, else None."""
34
35
  return None
35
36
 
37
+ def preselected(self):
38
+ """The kind of this provider that a new conversation's choice highlights before
39
+ there is a last choice (a setting of the package's own), or None."""
40
+ return None
41
+
36
42
  def require_choices(self, kind, runtime=None):
37
43
  """Check user decisions before starting a task; providers own their choices."""
38
44
 
@@ -76,9 +82,6 @@ class WorkspaceProvider:
76
82
  self.pool.close()
77
83
 
78
84
 
79
- # The order environments are offered in (kinds of other packages follow).
80
- ORDER = ("none", "project", "browser", "apps", "desktop", "display")
81
-
82
85
  # What every provider implements itself; WorkspaceProvider gives the rest.
83
86
  REQUIRED = ("kinds", "kind", "bench", "tree", "acquire")
84
87
  CONTRACT = REQUIRED + tuple(name for name, value in vars(WorkspaceProvider).items()
@@ -142,7 +145,7 @@ class NoWorkspace(WorkspaceProvider):
142
145
  return self.KIND
143
146
 
144
147
  def describe(self, kind):
145
- return {"label": "No environment",
148
+ return {"label": "No environment", "order": 0,
146
149
  "about": "conversation, the model and the connected tools only; nothing is started"}
147
150
 
148
151
  def tree(self, tree, kind):
@@ -253,8 +256,33 @@ class Workspaces:
253
256
  environment, then each kind the installed packages give, as its provider describes
254
257
  it ({"value", "label", "about"} and its "folder", "views" and "physical" flags)."""
255
258
  catalog = self.catalog()
256
- order = [kind for kind in ORDER if kind in catalog] + [kind for kind in catalog if kind not in ORDER]
257
- return [{"value": kind, **catalog[kind].describe(kind)} for kind in order]
259
+ rows = [{"value": kind, **catalog[kind].describe(kind)} for kind in catalog]
260
+ # Each provider says where its kinds stand ("order"); the sort keeps the rest as found.
261
+ return sorted(rows, key=lambda row: row.get("order", 100))
262
+
263
+ def preselected(self) -> str | None:
264
+ """What the choice of a new conversation highlights before there is a last one: the
265
+ first kind a provider preselects (WorkspaceProvider.preselected), or None."""
266
+ catalog = self.catalog()
267
+ for provider in self.providers():
268
+ kind = provider.preselected() if callable(getattr(provider, "preselected", None)) else None
269
+ if kind in catalog:
270
+ return kind
271
+ return None
272
+
273
+ def kind_of(self, bench: str, worker: dict | None = None) -> str | None:
274
+ """The workspace kind an experiment's worker of `bench` serves: among the kinds
275
+ whose provider names that bench, the one the worker's option `workspace` names,
276
+ else the first; None for a bench no provider serves."""
277
+ found = []
278
+ for kind, provider in self.catalog().items():
279
+ try:
280
+ if provider.bench(kind) == bench:
281
+ found.append(kind)
282
+ except Exception:
283
+ continue
284
+ asked = (worker or {}).get("workspace")
285
+ return asked if asked in found else (found[0] if found else None)
258
286
 
259
287
  def provider(self, kind=None):
260
288
  kind = self.kind() if kind is None else kind
@@ -4,12 +4,12 @@ time a run needs it.
4
4
 
5
5
  from harness import packages
6
6
 
7
- packages.install(["minecraft"]) # and what it depends on
7
+ packages.install(["NAME"]) # and what it depends on
8
8
  packages.installed() # [{name, version, source, provides, ...}]
9
- packages.search("robot"), packages.info("robodojo")
10
- packages.update(), packages.remove(["minecraft"])
11
- packages.ensure("embodiments", "minecraft") # install on first use (packages.auto_install)
12
- packages.describe(packages.info("robodojo")) # its fields and lines as every frontend shows them
9
+ packages.search("words"), packages.info("NAME")
10
+ packages.update(), packages.remove(["NAME"])
11
+ packages.ensure("embodiments", "NAME") # install on first use (packages.auto_install)
12
+ packages.describe(packages.info("NAME")) # its fields and lines as every frontend shows them
13
13
 
14
14
  The same as `harness install / remove / update / list / search / info`, the app's
15
15
  Packages page. The modules:
@@ -1,4 +1,4 @@
1
- """Environments: where a service's model or a benchmark's simulator runs, installed the
1
+ """Environments: where a service's model or a benchmark's code runs, installed the
2
2
  first time a run needs it and never before.
3
3
 
4
4
  A service manifest (services/<name>.toml) or a benchmark (benches/<name>/bench.toml)
@@ -9,12 +9,12 @@ describes its environment in an [environment] table:
9
9
  requirements = ["torch==2.7.0", "timm==1.0.30"] pinned requirements (pip syntax)
10
10
  indexes = ["https://download.pytorch.org/whl/cu128"]
11
11
  constraints = "environment/lock/pip-freeze.txt" pins every install respects
12
- sources = [{ source = "sam3", install = "editable", no_deps = true }]
12
+ sources = [{ source = "NAME", install = "editable", no_deps = true }]
13
13
  commands = [["{python}", "-m", "pip", "check"]] run after the installs, in order
14
- imports = ["torch", "sam3"] the check that it works
14
+ imports = ["torch", "timm"] the check that it works
15
15
 
16
- or names another environment to run in: `environment = "openwam"` (that service's) or
17
- `environment = "robodojo"` (that benchmark's). Each environment is a virtual
16
+ or names another environment to run in: `environment = "SERVICE"` (that service's) or
17
+ `environment = "NAME"` (a bench's). Each environment is a virtual
18
18
  environment of its own under HOME/envs/<name>/<hash>/, the hash taken over everything
19
19
  that decides what is installed, so a manifest whose environment changes gets a new one
20
20
  and an unchanged one is reused. A source is checked out once at its pinned commit
@@ -56,10 +56,10 @@ ENVIRONMENT_KEYS = {
56
56
  "sources": "checkouts at fixed commits, and how to install each: [{ source or repo + rev, nested, install, "
57
57
  "subdirectory, no_deps, flags }]",
58
58
  "commands": "commands run after the installs, in order: argv lists, or { run, env, cwd } "
59
- "({python}, {env}, {root}, {home} and the sources' checkouts such as {robodojo} are filled in)",
59
+ "({python}, {env}, {root}, {home} and the sources' checkouts by their names are filled in)",
60
60
  "env": "environment variables of the installs and commands",
61
- "overrides": "versions that win over what a package declares (isaacsim-kernel's websockets==12.0 next to "
62
- "17.1): kept out of the constraints, forced after the installs",
61
+ "overrides": "versions that win over what a package declares: kept out of the constraints, forced after the "
62
+ "installs",
63
63
  "imports": "modules that must import once it is installed (the check)",
64
64
  }
65
65
  # The keys of one entry of `sources`.
@@ -110,9 +110,19 @@ def validate(spec, where: str) -> None:
110
110
 
111
111
 
112
112
  def shared_sources() -> dict:
113
- """third_party/sources.toml: the checkouts several environments share, by name."""
114
- with SOURCES_FILE.open("rb") as handle:
115
- return tomllib.load(handle)
113
+ """The checkouts several environments share, by name: third_party/sources.toml of every
114
+ package that brings one (a package names the sources its services and benches use),
115
+ and the core's own. The first to name a source has it."""
116
+ from ..paths import find
117
+
118
+ found = {}
119
+ for path in dict.fromkeys([*find("third_party/sources.toml"), SOURCES_FILE]):
120
+ if not Path(path).is_file():
121
+ continue
122
+ with Path(path).open("rb") as handle:
123
+ for name, row in tomllib.load(handle).items():
124
+ found.setdefault(name, row)
125
+ return found
116
126
 
117
127
 
118
128
  def mode(deploy=None) -> str:
@@ -155,7 +165,9 @@ def source(entry: dict, deploy=None) -> Source:
155
165
  folder = Path(known.get("path", name)).name
156
166
  wanted = set(entry.get("nested", ()))
157
167
  nested = tuple((path, rev) for path, rev in known.get("nested", {}).items() if path in wanted)
158
- path = Path(getattr(deploy, name)) if name == "robodojo" and deploy is not None else third_party(folder)
168
+ # A deploy that names where this source is on the machine (an attribute of its name) is used as it is.
169
+ given = getattr(deploy, name, None) if deploy is not None else None
170
+ path = Path(given) if isinstance(given, (str, os.PathLike)) else third_party(folder)
159
171
  managed = path == home() / "sources" / folder
160
172
  return Source(name=name, path=path, url=known["url"], rev=known["revision"], nested=nested, managed=managed)
161
173
 
@@ -264,7 +276,7 @@ def _constraints(spec) -> list[str]:
264
276
  """The pins of an environment, without those of the packages it overrides."""
265
277
  value = spec.get("constraints") or []
266
278
  if isinstance(value, str):
267
- # A file of the core or of a package (environment/lock/pip-freeze.txt is local-models').
279
+ # A file of a package (environment/lock/pip-freeze.txt is local-models').
268
280
  from ..paths import find
269
281
 
270
282
  found = find(value)
@@ -401,13 +413,13 @@ def _install(environment: Environment, out, *, log=lambda message: None) -> None
401
413
  base = service_environment(log=lambda line: out.write(line + "\n"))
402
414
  run_env = {**base, **_render(spec.get("env", {}), variables), "VIRTUAL_ENV": str(directory),
403
415
  "PATH": os.pathsep.join([str(environment.python.parent), base.get("PATH", "")])}
404
- # The new environment, not the one the harness runs in (Isaac Lab's installer, for
405
- # one, prefers an active conda environment).
416
+ # The new environment, not the one the harness runs in (an installer may prefer an
417
+ # active conda environment).
406
418
  for name in ("PYTHONPATH", "PYTHONHOME", "CONDA_PREFIX", "CONDA_DEFAULT_ENV"):
407
419
  run_env.pop(name, None)
408
420
  if spec.get("indexes"):
409
421
  run_env["PIP_EXTRA_INDEX_URL"] = " ".join(spec["indexes"])
410
- # Wheels of a GB (torch, Isaac Sim) on a slow link outlast uv's 30 s default.
422
+ # Wheels of a GB on a slow link outlast uv's 30 s default.
411
423
  run_env.setdefault("UV_HTTP_TIMEOUT", "300")
412
424
 
413
425
  def run(argv, cwd=None, env=None):
@@ -436,7 +448,7 @@ def _install(environment: Environment, out, *, log=lambda message: None) -> None
436
448
 
437
449
  overrides = directory / "overrides.txt"
438
450
  overrides.write_text("".join(f"{line}\n" for line in spec.get("overrides", [])), encoding="utf-8")
439
- run_env["UV_OVERRIDE"] = str(overrides) # for the commands' own uv installs too (Isaac Lab's)
451
+ run_env["UV_OVERRIDE"] = str(overrides) # for the commands' own uv installs too
440
452
 
441
453
  def pip(*arguments):
442
454
  indexes = [flag for url in spec.get("indexes", []) for flag in ("--extra-index-url", url)]
@@ -462,7 +474,7 @@ def _install(environment: Environment, out, *, log=lambda message: None) -> None
462
474
  time.sleep(delay)
463
475
 
464
476
  if spec.get("requirements"):
465
- # "-r FILE" names a requirements file (of a source: {robodojo}/...).
477
+ # "-r FILE" names a requirements file (of a source: {NAME}/...).
466
478
  pip(*[part for item in _render(spec["requirements"], variables)
467
479
  for part in (item.split(None, 1) if item.startswith("-r ") else [item])])
468
480
  for entry, item in zip(spec.get("sources", []), environment.sources):
@@ -328,7 +328,7 @@ class Packages:
328
328
  "found": [...]} comes back. With `project`, the project's harness.toml and
329
329
  harness.lock are written (and with no specs, the project's packages are
330
330
  installed and the project trusted). With `embodiment`, a folder's skills are
331
- taken only when they run on it (the app's agent: desktop). Returns
331
+ taken only when they run on it (the kind the app's agent works in). Returns
332
332
  {"installed": [...], "problems": [...]}."""
333
333
  with tempfile.TemporaryDirectory(prefix="harness-package-") as temporary:
334
334
  prepared = self._prepare(specs, Path(temporary), project=project, consent=consent,
@@ -3,17 +3,17 @@
3
3
  A package is a folder with package.toml at its root:
4
4
 
5
5
  [package]
6
- name = "minecraft"
6
+ name = "example"
7
7
  version = "0.1.0"
8
- summary = "Play Minecraft Java Edition through a window of its own"
8
+ summary = "One line that says what the package gives"
9
9
  harness = ">=0.57,<2" # the harness versions it works with
10
- depends = { game = ">=0.1,<1" } # other packages, by name and range
10
+ depends = { other = ">=0.1,<1" } # other packages, by name and range
11
11
  platforms = ["windows", "macos", "linux"]
12
12
 
13
13
  [provides]
14
- commands = { audit-run = "benches.minecraft.audit:main" }
15
- host = "harness_computer.host" # what it adds to the session host (harness/extensions.py)
16
- workspaces = ["desktop", "browser"] # the --workspace values that host gives
14
+ commands = { check-run = "benches.example.check:main" }
15
+ host = "harness_example.host" # what it adds to the session host (harness/extensions.py)
16
+ workspaces = ["example"] # the --workspace values that host gives
17
17
 
18
18
  Everything else it provides is found in its folders and files (CONVENTION): skills/,
19
19
  embodiments/, benches/, services/, prompts/, configs/profiles/, configs/experiments/, agent-skills/,
@@ -5,7 +5,7 @@ assets are the eval package's (harness_eval/provision.py, `harness checkout`).
5
5
 
6
6
  `harness install NAMES` installs a bench's environment ahead of time.
7
7
 
8
- harness install sam3 simate robodojo
8
+ harness install NAME OTHER
9
9
  """
10
10
 
11
11
  from . import environments
@@ -1,6 +1,6 @@
1
1
  """Where a package comes from: the text `harness install` takes, and fetching it.
2
2
 
3
- minecraft, minecraft@^0.1 the registry (registry.py), the highest version in range
3
+ name, name@^0.1 the registry (registry.py), the highest version in range
4
4
  git:github.com/x/y@ref#subdir a git repository at a branch, tag or commit, a folder of it
5
5
  git+https://host/x/y.git@ref the same with a full URL
6
6
  https://github.com/x/y/tree/ref/subdir a folder of a GitHub repository
@@ -202,7 +202,7 @@ def _package_roots() -> list[str]:
202
202
 
203
203
 
204
204
  def third_party(name: str) -> Path:
205
- """A benchmark's checkout (RoboDojo, RoboTwin): $HARNESS_<NAME>_ROOT, else a source
205
+ """A benchmark's checkout: $HARNESS_<NAME>_ROOT, else a source
206
206
  checkout's third_party/<name> when it is there, else where the harness checks it out
207
207
  (HOME/sources/<name>)."""
208
208
  variable = os.environ.get(f"HARNESS_{name.upper()}_ROOT")