@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,536 @@
1
+ """The user's configuration: one file, config.toml in the data directory
2
+ (~/.harness/config.toml), with
3
+
4
+ [model] the model chosen (providers.py) and its advanced settings (SCHEMA)
5
+ [keys] the keys given to the harness (Credentials), readable by the user only
6
+ [packages] packages.auto_install and packages.registry, the installed packages
7
+ ([packages.installed.<name>], packages/state.py) and the trusted projects
8
+ [general] ... the settings the user changes in Settings (SCHEMA), and the sections
9
+ other modules keep (connectors, skills)
10
+
11
+ A project adds a harness.toml of its own (its [packages] and harness.lock). The files of
12
+ earlier versions (settings.json, model.json, credentials.env, packages.toml) are merged
13
+ into config.toml the first time it is read, and no longer read after that.
14
+
15
+ Each value has a default, a kind and its bounds (SCHEMA); update() takes a section's
16
+ changes, checks them and keeps the file. The settings reach a conversation when it
17
+ starts (App.config): its budget, its skills (sub-agents while limits.agent_depth allows
18
+ them), the model's advanced settings, the user's instructions; the computer's settings reach a workspace's worker when it starts, and
19
+ its limits (workspaces, chromes, displays) the workspace pool at once; the physical-input
20
+ policy and what the model learns of the user's windows are read by the workers each time
21
+ they change (the computer package's sections: its settings.toml).
22
+ Settings are changed from the app's page and the terminal chat's /settings.
23
+ """
24
+
25
+ from collections import namedtuple
26
+ from collections.abc import Mapping
27
+ import json
28
+ import os
29
+ from pathlib import Path
30
+ import threading
31
+ import tomllib
32
+
33
+ from .config import dumps
34
+ from .core import atomic_write
35
+
36
+
37
+ # One setting: `applies` is now, next_conversation or app_start; a list of rules has the fields a
38
+ # rule names besides its level ({name: "text", "id", "float" or its choices}), the rule a page
39
+ # adds, and any additional fields keyed by level.
40
+ Setting = namedtuple("Setting", "default kind bounds about applies fields example fields_when",
41
+ defaults=("next_conversation", None, None, None))
42
+ # (default, kind, choices or (min, max), what it is[, applies]). Kinds: choice, bool, int,
43
+ # float, text, rules (a list of the section's rules, at most max of them, checked by the row's check).
44
+ _CORE_SCHEMA = {section: {key: Setting(*row) for key, row in rows.items()} for section, rows in {
45
+ "general": {
46
+ "language": ("system", "choice", ("system", "zh", "en"), "the page's language (system: the browser's)", "now"),
47
+ "theme": ("system", "choice", ("system", "light", "dark"), "light or dark (system: the computer's)", "now"),
48
+ "open_browser": (True, "bool", None, "open the page in the browser when the app starts", "app_start"),
49
+ "notifications": (True, "bool", None, "a notification when the agent asks or finishes, while the page "
50
+ "is in the background", "now"),
51
+ },
52
+ "model": {
53
+ "reasoning_effort": ("default", "choice", ("default", "low", "medium", "high"),
54
+ "how much the model reasons before it answers (default: the provider's)"),
55
+ "max_output_tokens": (0, "int", (0, 200000), "tokens per reply (0: the harness's default)"),
56
+ "checker": ("", "text", (0, 200), "a model of the same provider that checks the result (empty: the "
57
+ "model itself)"),
58
+ "vision": ("", "text", (0, 200), "a model of the same provider that reads images, asked to describe a "
59
+ "view when the main model reads none (empty: such a model is told the "
60
+ "view was not sent and works from text)"),
61
+ "think_while_acting": ("default", "choice", ("default", "off", "on", "on_events", "periodic"),
62
+ "one speculative thought during a long program. Legacy on_events and periodic mean on"),
63
+ "think_interval": (0, "int", (0, 600), "accepted for older configurations"),
64
+ },
65
+ "session": {
66
+ "environment": ("ask", "text", (0, 40),
67
+ "where a new conversation works when none is named: ask (ask every new conversation, the last "
68
+ "choice highlighted), last (the last choice again, without asking), or one kind (none, project, "
69
+ "browser, apps, desktop, display: those the installed packages give)", "next_conversation"),
70
+ "agents": ("off", "choice", ("off", "on"),
71
+ "sub-agents in new conversations: off (their calls and prompt are not loaded; you can switch "
72
+ "them on in a conversation, and the agent may ask you to), on (loaded from the start, as deep "
73
+ "as limits.agent_depth allows)"),
74
+ },
75
+ "environments": {
76
+ "attach": ("ask_once_session", "choice", ("never", "ask_each", "ask_once_session", "allow"),
77
+ "when an agent may take another environment into its conversation (a project task that needs "
78
+ "to see a page takes the browser or your desktop), where no rule says otherwise: never, ask "
79
+ "each time, ask once per conversation and kind, allow. Each attachment and its reason is shown "
80
+ "and recorded whether or not it asked. When you skip confirmations (physical.level allow) it "
81
+ "does not ask; never still refuses", "now"),
82
+ "rules": ([], "rules", (0, 50),
83
+ "a level for one environment kind (desktop, apps, display, browser, project); it wins over "
84
+ "environments.attach", "now", {"kind": "text"}, {"level": "never", "kind": "desktop"}),
85
+ },
86
+ "approvals": {
87
+ "ask": ("sensitive", "choice", ("sensitive", "programs"),
88
+ "what waits for your approval: sensitive (steps that touch credentials, a payment, sending, deleting "
89
+ "or cannot be undone; they always wait) or programs (every program as well)"),
90
+ },
91
+ "limits": {
92
+ "max_steps": (60, "int", (1, 1000), "model calls a task may take"),
93
+ "max_minutes": (360, "int", (1, 1440), "minutes a conversation may run"),
94
+ "max_cost_usd": (5.0, "float", (0.01, 1000.0), "dollars a conversation may spend on the model"),
95
+ "agent_depth": (1, "int", (0, 4), "how deep agents start sub-agents (their budgets come out of the "
96
+ "conversation's): 0 none, 1 the conversation's agent does and they do "
97
+ "not, 2 theirs do too"),
98
+ },
99
+ "learning": {
100
+ "mode": ("on", "choice", ("on", "replay_always", "frozen"),
101
+ "default mode for explicitly selected learning libraries (legacy paths under "
102
+ "$HARNESS_HOME/libraries): on (keep observations and proposals; use executable entries once "
103
+ "a trusted verifier has checked them and they are activated); replay_always (also independently "
104
+ "recheck eligible entries at the start of ordinary conversations); frozen (read one snapshot)"),
105
+ "active_minutes": (30, "int", (1, 240), "minutes of live time a \"learn this environment\" conversation "
106
+ "takes (the app's Learn, /learn, harness run --learn)"),
107
+ },
108
+ "packages": {
109
+ "auto_install": ("official", "choice", ("official", "ask", "off"),
110
+ "when a task needs an embodiment, bench, skill or service no installed package provides: "
111
+ "official (install the registry's package that provides it), ask (ask first), off (stop "
112
+ "and say which package to install)", "now"),
113
+ "registry": ("", "text", (0, 300), "where packages come from: an https address or a folder of a registry "
114
+ "(empty: harness.lmms-lab.com; $HARNESS_REGISTRY wins over it)", "now"),
115
+ },
116
+ "data": {
117
+ "keep_days": (0, "int", (0, 3650), "conversations older than this are deleted when the app starts (0: "
118
+ "kept)", "app_start"),
119
+ },
120
+ }.items()}
121
+
122
+
123
+ class _Schema(Mapping):
124
+ """The core's sections and those packages add in their settings.toml, one table per
125
+ setting with its default, kind, bounds (choices for a choice) and what it is:
126
+
127
+ [kit.speed]
128
+ default = 1.0
129
+ kind = "float"
130
+ bounds = [0.1, 10.0]
131
+ about = "how fast the kit moves"
132
+
133
+ with applies, fields, example and fields_when as in Setting (a section's applies: its rows' default).
134
+ A row may name what checks its value (check = "module:function", returning the value as
135
+ kept or raising ValueError): a list of rules, a text of a form of its own. A package's
136
+ section of a name the core has is left out."""
137
+
138
+ def __init__(self, core):
139
+ self._core = core
140
+ self._cache = (None, core)
141
+ self._checks = {}
142
+
143
+ @staticmethod
144
+ def _row(row: dict, applies: str) -> Setting:
145
+ bounds = row.get("choices", row.get("bounds"))
146
+ return Setting(row.get("default"), row.get("kind", "text"), tuple(bounds) if bounds is not None else None,
147
+ row.get("about", ""), row.get("applies", applies), row.get("fields"), row.get("example"),
148
+ row.get("fields_when"))
149
+
150
+ def _sections(self) -> dict:
151
+ from .paths import find
152
+
153
+ files = tuple(find("settings.toml"))
154
+ if files != self._cache[0]:
155
+ sections = dict(self._core)
156
+ checks = {}
157
+ for path in files:
158
+ with path.open("rb") as handle:
159
+ for section, keys in tomllib.load(handle).items():
160
+ if section in self._core or not isinstance(keys, dict):
161
+ continue
162
+ sections[section] = {key: self._row(row, keys.get("applies", "next_conversation"))
163
+ for key, row in keys.items() if isinstance(row, dict)}
164
+ checks.update({(section, key): row["check"] for key, row in keys.items()
165
+ if isinstance(row, dict) and row.get("check")})
166
+ self._cache, self._checks = (files, sections), checks
167
+ return self._cache[1]
168
+
169
+ def __getitem__(self, section):
170
+ return self._sections()[section]
171
+
172
+ def checker(self, section: str, key: str):
173
+ """The function that checks section.key's value, when its row names one."""
174
+ import importlib
175
+
176
+ self._sections()
177
+ reference = self._checks.get((section, key))
178
+ if reference is None:
179
+ return None
180
+ module, _, attribute = reference.partition(":")
181
+ return getattr(importlib.import_module(module), attribute)
182
+
183
+ def __iter__(self):
184
+ return iter(self._sections())
185
+
186
+ def __len__(self):
187
+ return len(self._sections())
188
+
189
+
190
+ SCHEMA = _Schema(_CORE_SCHEMA)
191
+
192
+
193
+ # The configuration file, and the files of earlier versions merged into it once.
194
+ FILE = "config.toml"
195
+ OLD_FILES = ("settings.json", "model.json", "credentials.env", "packages.toml")
196
+ # The app's provider key.
197
+ KEY = "OPENROUTER_API_KEY"
198
+ COMMENT = "The Harness: your configuration (/settings in harness, the app's Settings)."
199
+ # Not settings: never in get(), never written by put() ([model] is a SCHEMA section too).
200
+ PRIVATE = ("model", "keys")
201
+
202
+
203
+ def defaults() -> dict:
204
+ return {section: {key: (list(spec[0]) if isinstance(spec[0], list) else spec[0]) for key, spec in keys.items()}
205
+ for section, keys in SCHEMA.items()}
206
+
207
+
208
+ def check(section: str, key: str, value):
209
+ """`value` for section.key as its kind takes it, or ValueError."""
210
+ if section not in SCHEMA or key not in SCHEMA[section]:
211
+ raise ValueError(f"no setting {section}.{key}")
212
+ kind, bounds = SCHEMA[section][key].kind, SCHEMA[section][key].bounds
213
+ checker = SCHEMA.checker(section, key) or _CORE_CHECKS.get((section, key))
214
+ if checker is not None and kind != "rules":
215
+ try:
216
+ return checker(value)
217
+ except ValueError as error:
218
+ raise ValueError(f"{section}.{key}: {error}") from None
219
+ if kind == "choice":
220
+ if value not in bounds:
221
+ raise ValueError(f"{section}.{key} is one of {', '.join(bounds)}")
222
+ return value
223
+ if kind == "bool":
224
+ if not isinstance(value, bool):
225
+ raise ValueError(f"{section}.{key} is true or false")
226
+ return value
227
+ if kind == "rules":
228
+ if not isinstance(value, (list, tuple)):
229
+ raise ValueError(f"{section}.{key} is a list of rules")
230
+ if len(value) > bounds[1]:
231
+ raise ValueError(f"{section}.{key} has at most {bounds[1]} rules")
232
+ if checker is None:
233
+ raise ValueError(f"{section}.{key}: nothing checks its rules here")
234
+ try:
235
+ return checker(value)
236
+ except ValueError as error:
237
+ raise ValueError(f"{section}.{key}: {error}") from None
238
+ if kind in ("int", "float"):
239
+ if isinstance(value, bool):
240
+ raise ValueError(f"{section}.{key} is a number")
241
+ try:
242
+ number = int(value) if kind == "int" else float(value)
243
+ except (TypeError, ValueError):
244
+ raise ValueError(f"{section}.{key} is a number") from None
245
+ if kind == "int" and float(value) != number:
246
+ raise ValueError(f"{section}.{key} is a whole number")
247
+ low, high = bounds
248
+ if not low <= number <= high:
249
+ raise ValueError(f"{section}.{key} is between {low} and {high}")
250
+ return number
251
+ text = str(value if value is not None else "").strip()
252
+ if len(text) > bounds[1]:
253
+ raise ValueError(f"{section}.{key} has at most {bounds[1]} characters")
254
+ return text
255
+
256
+
257
+ def _environment(value):
258
+ """session.environment: ask, last, or the name of a workspace kind (checked against the
259
+ installed packages when a conversation starts)."""
260
+ import re
261
+
262
+ text = str(value if value is not None else "").strip()
263
+ if not re.fullmatch(r"[a-z][a-z0-9_-]{0,39}", text):
264
+ raise ValueError("ask, last, or a workspace kind (none, project, browser, apps, desktop, display)")
265
+ return text
266
+
267
+
268
+ def _attach_rules(value):
269
+ """environments.rules: each {"level": one of environments.attach's, "kind": a workspace kind},
270
+ one rule per kind."""
271
+ levels = _CORE_SCHEMA["environments"]["attach"].bounds
272
+ rules, seen = [], set()
273
+ for row in value:
274
+ if not isinstance(row, dict) or set(row) != {"level", "kind"}:
275
+ raise ValueError("a rule is {level, kind}")
276
+ kind = _environment(row["kind"])
277
+ if row["level"] not in levels:
278
+ raise ValueError(f"a rule's level is one of {', '.join(levels)}")
279
+ if kind in ("ask", "last", "none") or kind in seen:
280
+ raise ValueError(f"one rule for each workspace kind; {kind!r} cannot have one here")
281
+ seen.add(kind)
282
+ rules.append({"level": row["level"], "kind": kind})
283
+ return rules
284
+
285
+
286
+ # What checks a core setting whose kind's own check is not enough.
287
+ _CORE_CHECKS = {("session", "environment"): _environment, ("environments", "rules"): _attach_rules}
288
+
289
+
290
+ # One change at a time in this process (the page's requests come on threads of their own).
291
+ _WRITING = threading.RLock()
292
+
293
+
294
+ def path(directory) -> Path:
295
+ return Path(directory) / FILE
296
+
297
+
298
+ def read(directory) -> dict:
299
+ """The whole configuration file ({} when there is none), the files of earlier
300
+ versions merged into it first."""
301
+ file = path(directory)
302
+ if not file.is_file() and any((Path(directory) / name).is_file() for name in OLD_FILES):
303
+ with _WRITING:
304
+ if not file.is_file():
305
+ write(directory, _merged_old(Path(directory)))
306
+ try:
307
+ with file.open("rb") as handle:
308
+ data = tomllib.load(handle)
309
+ except (OSError, tomllib.TOMLDecodeError):
310
+ return {}
311
+ return data
312
+
313
+
314
+ def write(directory, data: dict) -> None:
315
+ """Keep the whole configuration file (readable by the user only: it holds keys)."""
316
+ atomic_write(path(directory), dumps(data, COMMENT), private=True)
317
+
318
+
319
+ def change(directory, function) -> dict:
320
+ """Read the file, let `function` change the data in place, keep it; returns the data."""
321
+ with _WRITING:
322
+ data = read(directory)
323
+ function(data)
324
+ write(directory, data)
325
+ return data
326
+
327
+
328
+ def env_file(path) -> dict:
329
+ """NAME=value (or `export NAME=value`) lines of an env file ({} when there is none)."""
330
+ try:
331
+ text = Path(path).read_text(encoding="utf-8")
332
+ except OSError:
333
+ return {}
334
+ values = {}
335
+ for line in text.splitlines():
336
+ name, sep, value = line.strip().removeprefix("export ").partition("=")
337
+ if sep and name.strip().isidentifier():
338
+ values[name.strip()] = value.strip().strip("\"'")
339
+ return values
340
+
341
+
342
+ class Credentials:
343
+ """The providers' keys (providers.KEY_NAMES), loaded here only: from the environment or
344
+ [keys] of the user's config.toml (put into this process's environment on load); a key
345
+ given in a frontend goes to [keys] (the file is readable by the user only)."""
346
+
347
+ def __init__(self, directory: Path, names=None):
348
+ from .providers import KEY_NAMES
349
+
350
+ self.directory = Path(directory)
351
+ self.file = path(directory)
352
+ self.names = list(names or KEY_NAMES)
353
+ self.sources = {}
354
+
355
+ @property
356
+ def source(self):
357
+ return self.sources.get(KEY)
358
+
359
+ def _kept(self) -> dict:
360
+ return {str(name): str(value) for name, value in (read(self.directory).get("keys") or {}).items()}
361
+
362
+ def load(self) -> None:
363
+ kept = self._kept()
364
+ for name in self.names:
365
+ if os.environ.get(name):
366
+ self.sources[name] = "environment"
367
+ continue
368
+ if kept.get(name):
369
+ os.environ[name] = kept[name]
370
+ self.sources[name] = str(self.file)
371
+
372
+ def status(self, name: str = KEY) -> dict:
373
+ return {"set": bool(os.environ.get(name)), "source": self.sources.get(name), "name": name}
374
+
375
+ def save(self, value: str, name: str = KEY) -> None:
376
+ value = value.strip()
377
+ self.keep(name, value)
378
+ os.environ[name] = value
379
+ self.sources[name] = str(self.file)
380
+
381
+ def secret(self, name: str) -> str | None:
382
+ """A secret kept for a connector (only in [keys]: never put into the
383
+ environment, so no process the app starts inherits it)."""
384
+ return self._kept().get(name) or None
385
+
386
+ def keep(self, name: str, value: str | None) -> None:
387
+ """Persist a key in [keys] of config.toml (None removes it), leaving the process
388
+ environment and provider source tracking unchanged."""
389
+ def apply(data):
390
+ keys = data.setdefault("keys", {})
391
+ if value is None:
392
+ keys.pop(name, None)
393
+ else:
394
+ keys[name] = str(value).strip()
395
+
396
+ change(self.directory, apply)
397
+
398
+
399
+ def _merged_old(directory: Path) -> dict:
400
+ """settings.json, model.json, credentials.env and packages.toml as one configuration."""
401
+ data = {}
402
+ try:
403
+ old = json.loads((directory / "settings.json").read_text(encoding="utf-8"))
404
+ data.update({key: value for key, value in old.items() if key != "keys"})
405
+ except (OSError, ValueError, AttributeError):
406
+ pass
407
+ try:
408
+ model = json.loads((directory / "model.json").read_text(encoding="utf-8"))
409
+ if isinstance(model, dict):
410
+ data.setdefault("model", {}).update({key: value for key, value in model.items() if value is not None})
411
+ except (OSError, ValueError):
412
+ pass
413
+ keys = env_file(directory / "credentials.env")
414
+ if keys:
415
+ data["keys"] = keys
416
+ try:
417
+ with (directory / "packages.toml").open("rb") as handle:
418
+ packages = tomllib.load(handle)
419
+ section = data.setdefault("packages", {})
420
+ section["installed"] = packages.get("packages", {})
421
+ section["trusted_projects"] = packages.get("trusted_projects", [])
422
+ section["addons_migrated"] = bool(packages.get("migrated", False))
423
+ except (OSError, tomllib.TOMLDecodeError):
424
+ pass
425
+ return data
426
+
427
+
428
+ class ChoiceRequired(ValueError):
429
+ """A user preference is unset; no task has started and no value was selected."""
430
+
431
+ def __init__(self, choice):
432
+ self.choice = choice
433
+ super().__init__(choice.get("message")
434
+ or f"Choose {choice['section']}.{choice['key']} before using this capability")
435
+
436
+
437
+ class Settings:
438
+ """The settings in config.toml (FILE) of a data directory, over the defaults.
439
+ Sections other modules keep (connectors, skills) are stored as they give them."""
440
+
441
+ def __init__(self, directory: Path):
442
+ self.directory = Path(directory)
443
+ self.file = path(directory)
444
+
445
+ def _read(self) -> dict:
446
+ return read(self.directory)
447
+
448
+ def require_choice(self, section, key, *, title, options, override=None):
449
+ """Use an explicit valid value, never a schema default, for a user decision."""
450
+ value = override if override is not None else self._read().get(section, {}).get(key)
451
+ if value is not None:
452
+ try:
453
+ value = check(section, key, value)
454
+ if any(option['value'] == value for option in options):
455
+ return value
456
+ except ValueError:
457
+ pass
458
+ raise ChoiceRequired({"section": section, "key": key, "title": title, "options": options})
459
+
460
+ def remembered(self, section, key):
461
+ """What the harness itself kept under section.key (remember), or None: state beside
462
+ the settings (the last environment a conversation chose), never a setting."""
463
+ return (self._read().get(section) or {}).get(key)
464
+
465
+ def remember(self, section, key, value) -> None:
466
+ """Keep `value` under section.key for remembered() (None forgets it)."""
467
+ if key in SCHEMA.get(section, {}):
468
+ raise ValueError(f"{section}.{key} is a setting; use update()")
469
+
470
+ def apply(saved):
471
+ if value is None:
472
+ saved.get(section, {}).pop(key, None)
473
+ else:
474
+ saved.setdefault(section, {})[key] = value
475
+
476
+ change(self.directory, apply)
477
+
478
+ def get(self) -> dict:
479
+ """Every setting: the saved ones, the defaults for the rest (a saved value that no
480
+ longer checks falls back to its default)."""
481
+ saved = self._read()
482
+ # limits.ask_before_acting (before 1.0) is approvals.ask = "programs".
483
+ if (saved.get("limits") or {}).get("ask_before_acting") is True and "ask" not in (saved.get("approvals") or {}):
484
+ saved.setdefault("approvals", {})["ask"] = "programs"
485
+ values = defaults()
486
+ for section, keys in SCHEMA.items():
487
+ for key in keys:
488
+ if key in (saved.get(section) or {}):
489
+ try:
490
+ values[section][key] = check(section, key, saved[section][key])
491
+ except ValueError:
492
+ pass
493
+ for section, value in saved.items():
494
+ if section not in SCHEMA and section not in PRIVATE:
495
+ values[section] = value
496
+ return values
497
+
498
+ def update(self, changes: dict) -> dict:
499
+ """Apply {section: {key: value}} (every value checked first) and keep the file."""
500
+ if not isinstance(changes, dict):
501
+ raise ValueError("send {section: {key: value}}")
502
+ checked = {}
503
+ for section, values in changes.items():
504
+ if not isinstance(values, dict):
505
+ raise ValueError(f"{section}: send {{key: value}}")
506
+ checked[section] = {key: check(section, key, value) for key, value in values.items()}
507
+ def apply(saved):
508
+ for section, values in checked.items():
509
+ saved.setdefault(section, {}).update(values)
510
+
511
+ change(self.directory, apply)
512
+ return self.get()
513
+
514
+ def put(self, section: str, value) -> None:
515
+ """Keep a section another module owns (connectors, skills) as it is."""
516
+ if section in SCHEMA or section in PRIVATE:
517
+ raise ValueError(f"{section} is not kept by put()")
518
+ change(self.directory, lambda saved: saved.__setitem__(section, value))
519
+
520
+
521
+ def described() -> dict:
522
+ """The schema as the pages read it: {section: {key: Setting as a dict}}."""
523
+ return {section: {key: spec._asdict() for key, spec in keys.items()} for section, keys in SCHEMA.items()}
524
+
525
+
526
+ def rows(values: dict) -> list[dict]:
527
+ """Every setting as a row of a list (the terminal chat's /settings, the app's Settings)."""
528
+ return [{"setting": f"{section}.{key}", "section": section, "key": key, "kind": spec.kind,
529
+ "value": values.get(section, {}).get(key, spec.default), "applies": spec.applies, "about": spec.about}
530
+ for section, keys in SCHEMA.items() for key, spec in keys.items()]
531
+
532
+
533
+ def rule_fields(section: str) -> dict:
534
+ """The fields a rule of `section` names besides its level; {} when it has no rules."""
535
+ return next((dict(spec.fields or {}) for spec in SCHEMA.get(section, {}).values() if spec.kind == "rules"), {})
536
+
@@ -0,0 +1,79 @@
1
+ """A conversation's records as lines for a terminal (harness run, harness replay, a session's
2
+ last lines), each after the path of its lane on the timeline (core/lanes.py: model, e0,
3
+ e0/e2, env); and the commands the user gives a conversation, one table for the terminal
4
+ chat (tui/) and harness run rpc."""
5
+
6
+ from typing import NamedTuple
7
+
8
+ from .transcript import TextTranscript as Printer, item_lines as item_lines, record_lines as record_lines
9
+
10
+
11
+ class Command(NamedTuple):
12
+ """A word the user gives a conversation: its `method`, called with `fixed` and the values
13
+ for `takes` (a terminal gives the words after it to the first); `words`, `note`: its help.
14
+ One without a method is the terminal chat's own (tui/chat.py do_<name>)."""
15
+
16
+ method: str = ""
17
+ fixed: dict = {}
18
+ takes: tuple = ()
19
+ words: str = ""
20
+ note: str = ""
21
+
22
+
23
+ # The commands, the same in the terminal chat (/pause, ...) and harness run rpc
24
+ # ({"type": "pause"}, those with a method).
25
+ COMMANDS = {
26
+ "help": Command(note="the commands and keys"),
27
+ "new": Command(note="a new conversation (this one goes on)"),
28
+ "resume": Command(note="pick an earlier conversation and go on with it"),
29
+ "sessions": Command(note="the sessions that run: switch to one"),
30
+ "host": Command(words="[stop]", note="the session host: how it runs; stop: end it (and what runs in it)"),
31
+ "environment": Command(note="where this conversation works; choose where the next one does"),
32
+ "model": Command(note="pick an enabled model for new conversations"),
33
+ "models": Command(note="edit the local model list"),
34
+ "effort": Command(words="[LEVEL]", note="choose a reasoning effort for the selected model"),
35
+ "experiment": Command(words="NAME [TASK [SEED]] [-- instruction]",
36
+ note="a conversation of an experiment's task on its worker (the eval package's)"),
37
+ "agents": Command(note="switch sub-agents on: for this conversation, or for the next one before it starts"),
38
+ "settings": Command(note="change the settings"),
39
+ "packages": Command(note="the installed packages and the registry's: install, update, turn off, remove"),
40
+ "library": Command(note="what the agent remembers: this conversation's memory and each library's entries"),
41
+ "learn": Command(words="[minutes] [for what]", note="a new conversation that learns this environment instead of "
42
+ "doing a task (default: the settings' minutes); during it, where "
43
+ "it stands"),
44
+ "pause": Command("pause", note="stop at the next step, as Esc does"),
45
+ "cancel": Command("cancel", note="cancel an external turn"),
46
+ "steer": Command("steer", takes=("text",), words="TEXT", note="redirect an external turn"),
47
+ "terminal": Command("terminal_input", takes=("text",), words="TEXT", note="send raw PTY input"),
48
+ "answer": Command(words="REQUEST_ID JSON", note="answer the agent's form, or decline with null"),
49
+ "config": Command(words="OPTION VALUE", note="select an advertised external model or mode"),
50
+ "diff": Command(note="inspect this coding session's changes"),
51
+ "merge": Command(note="fast-forward to a closed session's committed work"),
52
+ "handoff": Command(words="AGENT CONTEXT", note="start a new agent with the context you supply"),
53
+ "import": Command(words="PROVIDER FILE", note="open a selected native session transcript read-only"),
54
+ "continue": Command("resume", note="go on after a pause"),
55
+ # remember: for physical input, once (or step), app, session or always.
56
+ "approve": Command("confirm", {"accept": True}, ("remember", "reason", "request_id"), "[app | session | always]",
57
+ "allow what waits; for physical input, keep it for the app, the session or always"),
58
+ "reject": Command("confirm", {"accept": False}, ("reason", "request_id"), "[why]", "refuse it, saying why"),
59
+ "end": Command("close", note="end it; the evaluator scores an episode"),
60
+ "timeline": Command(note="the timeline (Ctrl+T)"),
61
+ "detach": Command(note="leave; the session goes on (/sessions comes back to it)"),
62
+ "exit": Command(note="leave (Ctrl+C twice)"),
63
+ }
64
+ # Other words for a remember value.
65
+ REMEMBER = {"step": "once"}
66
+
67
+ HELP = ("Type a message for the agent, or a command: "
68
+ + ", ".join(f"/{name}" + (f" {command.words}" if command.words else "")
69
+ + (f" ({command.note})" if command.note else "") for name, command in COMMANDS.items()
70
+ if command.method or name == "help") + ".")
71
+
72
+
73
+ def command(conversation, name: str, values: dict | None = None) -> None:
74
+ """Do COMMANDS[name] on `conversation` with the user's `values` of its `takes` (empty ones
75
+ left out); KeyError for a name that is none."""
76
+ found = COMMANDS[name]
77
+ given = {key: REMEMBER.get(value, value) if key == "remember" else value for key, value in (values or {}).items()
78
+ if key in found.takes and value not in (None, "")}
79
+ getattr(conversation, found.method)(**found.fixed, **given)