@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,217 @@
1
+ """Embodiments: what a robot or a computer is, independent of how a run reaches it.
2
+
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
18
+ (benches/<name>/bench.toml `kind`).
19
+ """
20
+
21
+ from collections.abc import Mapping
22
+ from dataclasses import dataclass, replace
23
+ from pathlib import Path
24
+ import tomllib
25
+
26
+ from .paths import ROOT
27
+
28
+
29
+ EMBODIMENTS_ROOT = ROOT / "embodiments"
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class Kind:
34
+ """An embodiment kind. A worker reports its kind in its profile (`kind`, default robot)."""
35
+
36
+ name: str
37
+ # What it is, in the documentation ("a robot").
38
+ what: str
39
+ # The keys an embodiment file of the kind must have.
40
+ file_keys: tuple[str, ...]
41
+ # The kernel session that drives it, "module:Class" (runtime/execution/session.py).
42
+ session: str
43
+ # The observation contracts its workers can be served with: native, those it declares and those
44
+ # packages register for it (contracts.toml, contract_filter).
45
+ contracts: tuple[str, ...]
46
+ # The success verifier's instructions (runtime/decision/messages.py).
47
+ verifier: str
48
+ # The label and keys of the state in every message to the model, and the image
49
+ # streams it sees unless runtime.cameras names others.
50
+ state_label: str
51
+ state_keys: tuple[str, ...]
52
+ cameras: tuple[str, ...]
53
+ # 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).
55
+ place: str = ""
56
+ knowledge: str | None = None
57
+ native_features: tuple[str, ...] = ()
58
+ prompt_features: tuple[str, ...] = ()
59
+
60
+
61
+ # The core's own kind: a conversation without an environment (runtime/execution/noenv.py).
62
+ _CORE_KINDS = {kind.name: kind for kind in (
63
+ Kind(name="none", what="no environment", file_keys=("name",),
64
+ session="harness.runtime.execution.noenv:NoSession", contracts=("native",),
65
+ verifier="Check the claim against what the conversation itself established: the user's messages, the "
66
+ "files they attached and the results the connected tools returned. Answer on the first line "
67
+ "with exactly YES or NO, then one sentence of evidence.",
68
+ state_label="State", state_keys=("step",), cameras=()),
69
+ )}
70
+
71
+
72
+ 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:
75
+
76
+ [drone]
77
+ what = "a drone"
78
+ file_keys = ["name", "control_hz", "camera"]
79
+ session = "skills.drone.session:DroneSession"
80
+ contracts = ["native"]
81
+ verifier = "You check a claim about a drone from its camera images. ..."
82
+ state_label = "Drone state"
83
+ state_keys = ["step", "altitude"]
84
+ cameras = ["front"]
85
+
86
+ A package's kind of a name the core has is left out."""
87
+
88
+ def __init__(self, core):
89
+ self._core = core
90
+ self._cache = (None, core)
91
+
92
+ def _kinds(self) -> dict:
93
+ from .paths import find
94
+
95
+ files = tuple(path for path in find("kinds.toml"))
96
+ if files != self._cache[0]:
97
+ kinds = dict(self._core)
98
+ for path in files:
99
+ with path.open("rb") as handle:
100
+ for name, row in tomllib.load(handle).items():
101
+ if name in kinds:
102
+ continue
103
+ kinds[name] = Kind(name=name, what=row["what"], file_keys=tuple(row["file_keys"]),
104
+ session=row["session"], contracts=tuple(row.get("contracts", ("native",))),
105
+ verifier=row["verifier"], state_label=row["state_label"],
106
+ state_keys=tuple(row.get("state_keys", ())),
107
+ cameras=tuple(row.get("cameras", ())), place=str(row.get("place", "")),
108
+ knowledge=row.get("knowledge"),
109
+ native_features=tuple(row.get("native_features", ())),
110
+ prompt_features=tuple(row.get("prompt_features", ())))
111
+ registered = contracts()
112
+ for name, kind in list(kinds.items()):
113
+ extra = tuple(contract for contract, row in registered.items()
114
+ if row["kind"] == name and contract not in kind.contracts)
115
+ if extra:
116
+ kinds[name] = replace(kind, contracts=kind.contracts + extra)
117
+ self._cache = (files, kinds)
118
+ return self._cache[1]
119
+
120
+ def __getitem__(self, name):
121
+ return self._kinds()[name]
122
+
123
+ def __iter__(self):
124
+ return iter(self._kinds())
125
+
126
+ def __len__(self):
127
+ return len(self._kinds())
128
+
129
+
130
+ KINDS = _Kinds(_CORE_KINDS)
131
+
132
+
133
+ def contracts() -> dict:
134
+ """{name: {"kind", "filter", "summary"}}: the observation contracts the packages register in
135
+ their contracts.toml, one table per contract:
136
+
137
+ [xpolicylab]
138
+ kind = "robot"
139
+ filter = "harness_robodojo.contract:XPolicyLabContract"
140
+ summary = "what RoboDojo's official client hands a policy"
141
+
142
+ A filter is a class taking the embodiment, whose apply(method, arguments, result) gives
143
+ what a worker method returned as the contract shows it (core/worker.py)."""
144
+ from .paths import find
145
+
146
+ found = {}
147
+ for path in find("contracts.toml"):
148
+ with path.open("rb") as handle:
149
+ for name, row in tomllib.load(handle).items():
150
+ found.setdefault(name, {"kind": row["kind"], "filter": row["filter"], "summary": row.get("summary", "")})
151
+ return found
152
+
153
+
154
+ def contract_filter(name: str, embodiment: dict):
155
+ """The filter a worker of `embodiment` is served with under the contract `name`: None for
156
+ native (everything is reported); a registered contract's filter otherwise."""
157
+ import importlib
158
+
159
+ kind = embodiment_kind(embodiment)
160
+ allowed = KINDS[kind].contracts
161
+ if name not in allowed:
162
+ raise ValueError(f"A {kind} is served with the contracts {allowed}, not {name!r}")
163
+ if name == "native":
164
+ return None
165
+ module, _, attribute = contracts()[name]["filter"].partition(":")
166
+ return getattr(importlib.import_module(module), attribute)(embodiment)
167
+
168
+
169
+ def embodiment_path(name) -> Path:
170
+ """The embodiment file of a name (`embodiments/<name>/embodiment.toml`) or a path; an
171
+ unknown name is an error."""
172
+ path = Path(name)
173
+ # A file only: a directory named like an embodiment (a checkout called "gamescientist")
174
+ # is not one.
175
+ if path.suffix == ".toml" or path.is_file():
176
+ return path.resolve()
177
+ from .paths import find
178
+
179
+ found = find(f"embodiments/{name}/embodiment.toml")
180
+ if not found:
181
+ known = sorted({p.parent.name for folder in find("embodiments") for p in folder.glob("*/embodiment.toml")})
182
+ raise ValueError(f"Unknown embodiment {name!r}; known: {known}")
183
+ return found[0]
184
+
185
+
186
+ 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")
190
+ if kind not in KINDS:
191
+ raise ValueError(f"Unknown embodiment kind {kind!r}; kinds are {sorted(KINDS)}")
192
+ return kind
193
+
194
+
195
+ def load_embodiment(name) -> dict:
196
+ """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."""
198
+ with embodiment_path(name).open("rb") as handle:
199
+ data = tomllib.load(handle)
200
+ for key in KINDS[embodiment_kind(data)].file_keys:
201
+ if key not in data:
202
+ raise ValueError(f"Embodiment {name}: missing {key}")
203
+ 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}}
@@ -0,0 +1,112 @@
1
+ """What packages add to the session host and its frontends. A package names a module of its
2
+ own in package.toml ([provides] host = "module"); the core calls what that module defines
3
+ by name and imports no package itself. A host module may define:
4
+
5
+ Workspaces(directory, settings) a WorkspaceProvider (harness.sdk). All installed
6
+ providers participate: kinds, selection, binding,
7
+ configuration, provisioning and release belong to
8
+ the package. Duplicate kind names are rejected;
9
+ the core never falls back to a built-in backend.
10
+ note(values) -> str a line about this computer over the terminal chat's /settings
11
+ waiting(owner) -> str | None what an agent of a session waits for (the input lock)
12
+ recording(directory) -> dict a run's screen recording ({"path", "start", "stop",
13
+ "area"}), or None
14
+ areas(text) -> tuple a screen area "x,y,width,height" as numbers
15
+ Chromes(directory, limit) the headless Chromes a suite's background browsers share
16
+ overlay the timeline overlay (the app package's: a window on top of
17
+ the screen; launch, for_session, for_runs, close, Options)
18
+ focus() -> bool bring the package's window to the front (the app's, taptab's);
19
+ False when it is not open (focus() tries each in turn)
20
+ session_adapter(name, directory, *, cwd, isolation, model, effort)
21
+ a host-managed external conversation, or None for a name
22
+ this package does not provide. Its trace lives in directory.
23
+ pages the package's pages: {"/taptab": "taptab.html"}, files of its
24
+ ui/static/ served at those paths (host/http.py); its other
25
+ files are at /static/<package>/<file>
26
+ api the package's API: {"inbox": handler}, served at
27
+ /api/<package>/inbox with the session key; handler(server,
28
+ data) -> JSON, or (body, content type, headers) as it is
29
+ (data: a GET's query, a POST's JSON body; a ValueError or
30
+ KeyError answers 400 with its text)
31
+ mcp_servers(app) -> dict MCP servers for the conversations of the session host's
32
+ assistant (the app's connectors), {name: client config};
33
+ close_app(app) when the assistant closes
34
+ export_video(directory, ...) a run as a video, used by a frontend command
35
+ profiles {name: path}: conversation profiles a frontend starts the
36
+ assistant's conversations with (POST /api/app/conversations
37
+ {profile}); each file names skills only its conversations
38
+ have and prompt text (host/assistant.py PROFILE_KEYS)
39
+ background(server) a service with start(), close(), and keep_alive().
40
+ Optionally registered(run, conversation) is called
41
+ after session registration, before execution.
42
+
43
+ Standard library only.
44
+ """
45
+
46
+ import importlib
47
+
48
+ _CACHE = {}
49
+
50
+
51
+ def hosts() -> list:
52
+ """(package, host module) of the packages this process uses that give one, in their
53
+ order (paths.packages)."""
54
+ from .paths import packages
55
+
56
+ found = packages()
57
+ roots = tuple(package.path for package in found)
58
+ if roots not in _CACHE:
59
+ _CACHE.clear()
60
+ _CACHE[roots] = [(package, importlib.import_module(package.provides["host"][0])) for package in found
61
+ if "host" in package.provides]
62
+ return _CACHE[roots]
63
+
64
+
65
+ def modules() -> list:
66
+ """The host modules of the packages this process uses, in their order (paths.packages)."""
67
+ return [module for _, module in hosts()]
68
+
69
+
70
+ def first(name: str):
71
+ """What the first host module that defines `name` has under it, or None."""
72
+ for module in modules():
73
+ value = getattr(module, name, None)
74
+ if value is not None:
75
+ return value
76
+ return None
77
+
78
+
79
+ def require(name: str, what: str, provider: str):
80
+ """What `name` is in a host module, installing the package that provides `provider` among
81
+ its `what` first (as packages.auto_install says) when none has it: the app package's
82
+ overlay for the frontends that open one."""
83
+ value = first(name)
84
+ if value is None:
85
+ from .packages import Packages, activate
86
+
87
+ packages = Packages()
88
+ packages.ensure(what, provider, log=lambda message: None)
89
+ activate(packages) # its folder on the import path, its host module found
90
+ value = first(name)
91
+ if value is None:
92
+ raise ValueError(f"no package gives {name} (harness install {provider})")
93
+ return value
94
+
95
+
96
+ def focus() -> bool:
97
+ """Bring a frontend's window to the front when a conversation needs the user: each host
98
+ module's focus() in turn, until one finds its window open (the app's, then another
99
+ package's page). Whether one did."""
100
+ for module in modules():
101
+ function = getattr(module, "focus", None)
102
+ if function is not None and function():
103
+ return True
104
+ return False
105
+
106
+
107
+ def overlay():
108
+ """The timeline overlay (the app package's harness_app/overlay.py), provided by an installed frontend."""
109
+ window = first("overlay")
110
+ if window is None:
111
+ raise ValueError("No installed frontend provides an overlay")
112
+ return window