@lmmslab/harness 0.0.0-stage → 0.81.1

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 +1356 -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 +232 -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,218 @@
1
+ """Where the harness finds its own files, and where it keeps what it installs.
2
+
3
+ ROOT is the core's own content, a folder of the package (harness/builtin/: configs/,
4
+ skills/, services/, prompts/, benches/, environment/, scripts/ and
5
+ third_party/sources.toml), the same in a source checkout and in an installed wheel.
6
+ CHECKOUT_ROOT is the repository of a source checkout (None once installed): its
7
+ packages/ are developed in place and its third_party/ holds benchmarks' checkouts. Paths
8
+ recorded in locks and traces are relative to ROOT or to their package, so they read the
9
+ same everywhere.
10
+
11
+ Packages hold the rest, each folder laid out as ROOT is (skills/, benches/,
12
+ embodiments/, services/, prompts/, configs/...): a checkout's packages/<name>/, and the
13
+ installed ones that are enabled (HARNESS_PACKAGE_ROOTS, which harness.packages sets).
14
+ roots() is ROOT and then them; content is looked up in each in turn (find, locate).
15
+
16
+ HOME ($HARNESS_HOME, default ~/.cache/harness) holds what the harness installs on first
17
+ use: envs/<name>/<hash>/ (the environment of a service or benchmark), sources/ (checkouts
18
+ at pinned commits: a benchmark's, with its assets), weights/, services/ (pid files and
19
+ logs of started services), deploy/ (the placement it chose itself) and logs/.
20
+ """
21
+
22
+ import os
23
+ from pathlib import Path
24
+ import sys
25
+
26
+
27
+ PACKAGE = Path(__file__).resolve().parent
28
+
29
+
30
+ ROOT = PACKAGE / "builtin"
31
+
32
+
33
+ def _checkout() -> Path | None:
34
+ checkout = PACKAGE.parents[1]
35
+ # A kernel's sandbox shows only parts of a checkout (src/, packages/).
36
+ if PACKAGE.parent.name == "src" and (checkout / "packages").is_dir():
37
+ return checkout
38
+ return None
39
+
40
+
41
+ CHECKOUT_ROOT = _checkout()
42
+ # The core's built-in skills and benches import as skills.<name> and benches.<name>, here
43
+ # as in the processes it starts (import_roots).
44
+ if str(ROOT) not in sys.path:
45
+ sys.path.append(str(ROOT))
46
+ # Whether this is a source checkout (a git repository can be exported, `third_party/` is
47
+ # the developer's).
48
+ CHECKOUT = CHECKOUT_ROOT is not None
49
+ if CHECKOUT:
50
+ # A checkout develops its packages: their skills, benches and modules import as the
51
+ # core's do, in this process and in the tests.
52
+ for _manifest in sorted((CHECKOUT_ROOT / "packages").glob("*/package.toml")):
53
+ if str(_manifest.parent) not in sys.path:
54
+ sys.path.append(str(_manifest.parent))
55
+ HOME_ENV = "HARNESS_HOME"
56
+ DATA_ENV = "HARNESS_DATA"
57
+ PACKAGES_ENV = "HARNESS_PACKAGE_ROOTS"
58
+
59
+
60
+ def home() -> Path:
61
+ """The directory of what the harness installs ($HARNESS_HOME, default ~/.cache/harness)."""
62
+ return Path(os.path.expanduser(os.environ.get(HOME_ENV) or "~/.cache/harness")).resolve()
63
+
64
+
65
+ def data() -> Path:
66
+ """The directory of what the app keeps for its user ($HARNESS_DATA, default ~/.harness):
67
+ conversations/, config.toml (the model, its key and the settings: settings.py) and logs/."""
68
+ return Path(os.path.expanduser(os.environ.get(DATA_ENV) or "~/.harness")).resolve()
69
+
70
+
71
+ _PACKAGES: dict = {}
72
+
73
+
74
+ def packages() -> list:
75
+ """The packages this process uses (manifest.Package), one per name, each package.toml
76
+ read once (until packages_changed()): a checkout's packages/<name>/ (a source checkout
77
+ develops them all), then the installed ones that are enabled (HARNESS_PACKAGE_ROOTS,
78
+ which harness.packages sets; before that, the user's list). When a checkout's package
79
+ and an installed one have the same name, the checkout's wins: its folder is on
80
+ sys.path first (above), so its modules are the ones this process imports, and its
81
+ skills, benches and prompts must be the ones it finds. One that does not load is left
82
+ out (harness list says why). The user's list is kept only once it was read: a module
83
+ that asks while the harness is still being imported (the embodiment kinds of
84
+ config/__init__.py) gets the packages without it, and the next call reads it."""
85
+ named = os.environ.get(PACKAGES_ENV)
86
+ key = (named, os.environ.get(DATA_ENV))
87
+ if key not in _PACKAGES:
88
+ from .packages.manifest import load
89
+
90
+ folders = sorted(path.parent for path in (CHECKOUT_ROOT / "packages").glob("*/package.toml")) \
91
+ if CHECKOUT else []
92
+ folders += [Path(item) for item in (named or "").split(os.pathsep) if item]
93
+ loaded = []
94
+ for folder in folders:
95
+ try:
96
+ loaded.append(load(folder))
97
+ except ValueError:
98
+ continue
99
+ enabled = _enabled() if named is None else []
100
+ found = {}
101
+ for package in loaded + (enabled or []):
102
+ found.setdefault(package.name, package)
103
+ if enabled is None:
104
+ return list(found.values())
105
+ _PACKAGES.clear()
106
+ _PACKAGES[key] = list(found.values())
107
+ return _PACKAGES[key]
108
+
109
+
110
+ def packages_changed() -> None:
111
+ """Read the packages again on the next packages(): one was installed, removed, enabled
112
+ or disabled (harness.packages.activate)."""
113
+ _PACKAGES.clear()
114
+
115
+
116
+ def package_roots() -> list[Path]:
117
+ """The folders of the packages this process uses (packages())."""
118
+ return [package.path for package in packages()]
119
+
120
+
121
+ def _enabled() -> list | None:
122
+ """The user's enabled packages, before harness.packages.activate() has named them in
123
+ HARNESS_PACKAGE_ROOTS (a command a package brings is parsed first); None when they
124
+ cannot be read now (the harness is still being imported, or a broken configuration
125
+ file, which the package commands report)."""
126
+ try:
127
+ from .packages.manager import Packages
128
+
129
+ return Packages().enabled()
130
+ except Exception:
131
+ return None
132
+
133
+
134
+ def roots() -> list[Path]:
135
+ """Where content is looked up, in order: ROOT, then each package (package_roots)."""
136
+ return [ROOT, *package_roots()]
137
+
138
+
139
+ def find(relative) -> list[Path]:
140
+ """`relative` (a path as it is under ROOT: "benches", "configs/models/x.toml") in
141
+ every root that has it."""
142
+ return [root / relative for root in roots() if (root / relative).exists()]
143
+
144
+
145
+ def locate(path) -> Path:
146
+ """`path` when it exists; else, for a path under ROOT or a package, the same relative
147
+ path in the first root that has it (a configuration in one package naming a prompt
148
+ another one holds); else `path`."""
149
+ path = Path(path)
150
+ if path.exists():
151
+ return path
152
+ absolute = path.resolve()
153
+ for base in roots():
154
+ try:
155
+ relative = absolute.relative_to(base.resolve())
156
+ except ValueError:
157
+ continue
158
+ found = find(relative)
159
+ if found:
160
+ return found[0]
161
+ return path
162
+
163
+
164
+ def import_roots() -> list[str]:
165
+ """What another process (a service, a worker, a kernel) puts on PYTHONPATH to import
166
+ the harness and its benches and skills, and nothing else: ROOT, and the directory of
167
+ the harness package (a checkout's src/; for an installed wheel, a directory under
168
+ HOME that links to the package alone, so a service's environment never sees the
169
+ packages installed next to it). Then each package's folder (package_roots), and the
170
+ .deps of each of its skills (their requirements)."""
171
+ packages = package_roots()
172
+ deps = [str(deps) for root in packages for deps in sorted(root.glob("skills/*/.deps")) if deps.is_dir()]
173
+ return list(dict.fromkeys(_package_roots() + [str(root) for root in packages] + deps))
174
+
175
+
176
+ def _package_roots() -> list[str]:
177
+ if CHECKOUT:
178
+ return [str(ROOT), str(PACKAGE.parent)]
179
+ # The link folder this process was imported through already (a kernel's, whose HOME is
180
+ # an empty one of its own): it holds the harness package alone.
181
+ imported = Path(os.path.abspath(__file__)).parent.parent
182
+ if not any(item.name != PACKAGE.name for item in imported.iterdir()):
183
+ return [str(ROOT), str(imported)]
184
+ link_root = home() / "python"
185
+ link = link_root / PACKAGE.name
186
+ if not (link.exists() and link.resolve() == PACKAGE.resolve()):
187
+ link_root.mkdir(parents=True, exist_ok=True)
188
+ if link.is_symlink() or link.is_file():
189
+ link.unlink()
190
+ elif link.exists():
191
+ os.rmdir(link) # a junction: removed without what it points to
192
+ try:
193
+ link.symlink_to(PACKAGE, target_is_directory=True)
194
+ except OSError:
195
+ if os.name != "nt":
196
+ raise
197
+ # A symbolic link needs a privilege a Windows user may lack; a junction does not.
198
+ import _winapi
199
+
200
+ _winapi.CreateJunction(str(PACKAGE), str(link))
201
+ return [str(ROOT), str(link_root)]
202
+
203
+
204
+ def third_party(name: str) -> Path:
205
+ """A benchmark's checkout (RoboDojo, RoboTwin): $HARNESS_<NAME>_ROOT, else a source
206
+ checkout's third_party/<name> when it is there, else where the harness checks it out
207
+ (HOME/sources/<name>)."""
208
+ variable = os.environ.get(f"HARNESS_{name.upper()}_ROOT")
209
+ if variable:
210
+ return Path(os.path.expanduser(variable))
211
+ if CHECKOUT and (CHECKOUT_ROOT / "third_party" / name).exists():
212
+ return CHECKOUT_ROOT / "third_party" / name
213
+ return home() / "sources" / name
214
+
215
+
216
+ def python_path(*extra) -> str:
217
+ """PYTHONPATH for another process: import_roots(), then `extra` (empty items left out)."""
218
+ return os.pathsep.join(import_roots() + [str(item) for item in extra if item])
@@ -0,0 +1,303 @@
1
+ """Model providers the app connects to, after OpenHands' LLM settings: a provider, a
2
+ model, a key, and under Advanced a base URL, so any OpenAI-compatible endpoint works
3
+ (a self-hosted vLLM or SGLang server, Ollama, LM Studio, a company gateway).
4
+
5
+ OpenRouter runs on the harness's openrouter backend (usage cost reported); every other
6
+ provider on openai_chat with its base URL and key variable (runtime/decision/model.py MODEL_KEYS).
7
+ A model need not read images: each turn is text (the state, what programs returned), and a
8
+ view is sent only when a program looks. The model list keeps whether a model reads them
9
+ (model_list.py `images`, from the provider's catalog where it says, the user's to change);
10
+ one that reads none is sent none, and the choice of where a conversation works says so
11
+ beside the environments that have a screen.
12
+ """
13
+
14
+ from dataclasses import dataclass, field
15
+ import json
16
+ import os
17
+ from pathlib import Path
18
+ import re
19
+ from urllib.error import HTTPError, URLError
20
+
21
+ from .core.http import open_url
22
+
23
+
24
+ @dataclass(frozen=True)
25
+ class Provider:
26
+ id: str
27
+ name: str
28
+ base_url: str | None
29
+ key_env: str | None
30
+ backend: str = "openai_chat"
31
+ # The request field of the output limit, when not max_tokens.
32
+ max_tokens_key: str | None = None
33
+ note: str = ""
34
+ extra: dict = field(default_factory=dict)
35
+
36
+
37
+ PROVIDERS = {provider.id: provider for provider in (
38
+ Provider("openrouter", "OpenRouter", None, "OPENROUTER_API_KEY",
39
+ backend="openrouter", note="one key for most models"),
40
+ Provider("openai", "OpenAI", "https://api.openai.com/v1", "OPENAI_API_KEY",
41
+ max_tokens_key="max_completion_tokens"),
42
+ Provider("anthropic", "Anthropic", "https://api.anthropic.com/v1", "ANTHROPIC_API_KEY"),
43
+ Provider("gemini", "Google Gemini", "https://generativelanguage.googleapis.com/v1beta/openai", "GEMINI_API_KEY"),
44
+ Provider("xai", "xAI", "https://api.x.ai/v1", "XAI_API_KEY"),
45
+ Provider("deepseek", "DeepSeek", "https://api.deepseek.com/v1", "DEEPSEEK_API_KEY"),
46
+ Provider("dashscope", "Qwen (DashScope)", "https://dashscope.aliyuncs.com/compatible-mode/v1", "DASHSCOPE_API_KEY"),
47
+ Provider("zhipu", "Zhipu GLM", "https://open.bigmodel.cn/api/paas/v4", "ZHIPU_API_KEY"),
48
+ Provider("moonshot", "Moonshot Kimi", "https://api.moonshot.cn/v1", "MOONSHOT_API_KEY"),
49
+ Provider("ollama", "Ollama (this computer)", "http://localhost:11434/v1", None,
50
+ note="no key; the model must be pulled in Ollama"),
51
+ Provider("custom", "Custom (OpenAI-compatible)", None, "HARNESS_LLM_API_KEY",
52
+ note="vLLM, SGLang, LM Studio, a gateway: give the base URL"),
53
+ )}
54
+ DEFAULT = {"provider": "openrouter", "model": "deepseek/deepseek-v4.1-flash", "base_url": None}
55
+ # Every key variable a provider uses (the app loads them from its credentials).
56
+ KEY_NAMES = sorted({provider.key_env for provider in PROVIDERS.values() if provider.key_env})
57
+
58
+
59
+ def load(directory: Path) -> dict:
60
+ """The model the user chose ({provider, model, base_url}: [model] of config.toml,
61
+ settings.py), or the default."""
62
+ from . import settings as config
63
+
64
+ data = config.read(directory).get("model") or {}
65
+ if data.get("provider") not in PROVIDERS:
66
+ return dict(DEFAULT)
67
+ return {"provider": data["provider"], "model": data.get("model") or "", "base_url": data.get("base_url")}
68
+
69
+
70
+ def save(directory: Path, settings: dict) -> None:
71
+ from . import settings as config
72
+
73
+ def apply(data):
74
+ # [model] also holds the model's advanced settings (settings.SCHEMA "model").
75
+ section = data.setdefault("model", {})
76
+ for key in ("provider", "model", "base_url"):
77
+ section.pop(key, None)
78
+ section.update({key: value for key, value in settings.items() if value is not None})
79
+
80
+ config.change(directory, apply)
81
+
82
+
83
+ def check(settings: dict) -> dict:
84
+ """Whether the provider answers with the key: {settings} normalized, or ValueError."""
85
+ provider = PROVIDERS.get(settings.get("provider"))
86
+ if provider is None:
87
+ raise ValueError(f"no provider {settings.get('provider')!r}")
88
+ model = str(settings.get("model") or "").strip()
89
+ if not model:
90
+ raise ValueError("name a model")
91
+ base_url = str(settings.get("base_url") or "").strip() or provider.base_url
92
+ if provider.backend != "openrouter" and not base_url:
93
+ raise ValueError("give the base URL of the endpoint")
94
+ if base_url and not re.match(r"^https?://", base_url):
95
+ raise ValueError("the base URL starts with http:// or https://")
96
+ return {"provider": provider.id, "model": model,
97
+ "base_url": base_url if base_url != provider.base_url else None}
98
+
99
+
100
+ def models_url(settings: dict) -> str:
101
+ provider = PROVIDERS[settings["provider"]]
102
+ if provider.backend == "openrouter":
103
+ return "https://openrouter.ai/api/v1/key"
104
+ return (settings.get("base_url") or provider.base_url).rstrip("/") + "/models"
105
+
106
+
107
+ def reach(settings: dict, key: str | None, timeout: float = 20.0) -> dict:
108
+ """Ask the provider whether the key works (OpenRouter's key endpoint, else the
109
+ OpenAI-compatible model list): {ok, detail}; the key goes to that provider only."""
110
+ headers = {"authorization": f"Bearer {key}", "x-api-key": key, "anthropic-version": "2023-06-01"} if key else {}
111
+ try:
112
+ with open_url(models_url(settings), headers=headers, timeout=timeout) as response:
113
+ body = json.load(response)
114
+ except HTTPError as error:
115
+ if error.code in (401, 403):
116
+ return {"ok": False, "detail": "refused"}
117
+ # Some endpoints have no model list; the key may still be right.
118
+ return {"ok": True, "detail": f"connected (the model list answered HTTP {error.code})"}
119
+ except (URLError, OSError, ValueError) as error:
120
+ return {"ok": False, "detail": f"unreachable: {error}"}
121
+ if PROVIDERS[settings["provider"]].backend == "openrouter":
122
+ remaining = (body.get("data") or {}).get("limit_remaining")
123
+ return {"ok": True, "detail": None if remaining is None else f"${remaining:.2f} left"}
124
+ ids = [item.get("id") for item in body.get("data") or [] if isinstance(item, dict)]
125
+ known = settings["model"] in ids if ids else None
126
+ return {"ok": True, "detail": None if known is not False else f"{settings['model']} is not in the provider's list",
127
+ "models": ids[:200]}
128
+
129
+
130
+ def catalog(directory: Path, identifier: str) -> list[dict]:
131
+ provider = PROVIDERS.get(identifier)
132
+ if provider is None:
133
+ raise ValueError("choose a model provider")
134
+ chosen = load(directory)
135
+ base = (chosen.get("base_url") if chosen["provider"] == identifier else None) or provider.base_url
136
+ if provider.backend == "openrouter":
137
+ url = "https://openrouter.ai/api/v1/models"
138
+ elif base:
139
+ url = base.rstrip("/") + "/models"
140
+ else:
141
+ raise ValueError("configure the endpoint before looking up models")
142
+ key = os.environ.get(provider.key_env) if provider.key_env else None
143
+ headers = {"Authorization": f"Bearer {key}"} if key else {}
144
+ if identifier == "anthropic":
145
+ headers = {"x-api-key": key or "", "anthropic-version": "2023-06-01"}
146
+ try:
147
+ with open_url(url, headers=headers, timeout=12) as response:
148
+ raw = json.load(response)
149
+ except (OSError, ValueError) as error:
150
+ raise ValueError(f"{provider.name} model catalog is unavailable: {error}") from error
151
+ models = []
152
+ for item in raw.get("data", []):
153
+ if not isinstance(item, dict) or not isinstance(item.get("id"), str) or not item["id"]:
154
+ continue
155
+ reasoning = item.get("reasoning") or {} if provider.backend == "openrouter" else {}
156
+ efforts = reasoning.get("supported_efforts", [])
157
+ if efforts is None:
158
+ # Null explicitly means all the gateway's documented effort values.
159
+ efforts = ["max", "xhigh", "high", "medium", "low", "minimal", "none"]
160
+ efforts = [level for level in efforts if level != "none" or not reasoning.get("mandatory")]
161
+ # Whether it reads images, where the provider says (OpenRouter's input modalities).
162
+ modalities = (item.get("architecture") or {}).get("input_modalities")
163
+ models.append({"id": item["id"], "name": item.get("display_name") or item.get("name") or item["id"],
164
+ "efforts": efforts, "base_url": base if base != provider.base_url else None,
165
+ **({"images": "image" in modalities} if isinstance(modalities, list) else {})})
166
+ return models
167
+
168
+
169
+ def model_file(settings: dict, directory: Path, advanced: dict | None = None) -> Path:
170
+ """A model file (configs/models format) for the user's choice: the same model in
171
+ every role the agent uses (main, vlm, verifier), as the default model file does.
172
+ `advanced` (the app's model settings): reasoning_effort, max_output_tokens, and
173
+ checker, another model of the provider for the verifier."""
174
+ provider = PROVIDERS[settings["provider"]]
175
+ advanced = advanced or {}
176
+ role = model_role(settings, advanced)
177
+ # The role that answers about images inside programs: the vision model when the main
178
+ # one reads none and one is set.
179
+ sees = viewer_role(settings, advanced) or role
180
+ roles = {"main": role, "vlm": sees, "verifier": {**role, **({"model": advanced["checker"]}
181
+ if advanced.get("checker") else {})}}
182
+ from .config import dumps
183
+
184
+ from .core import atomic_write, sha256
185
+
186
+ slug = re.sub(r"[^A-Za-z0-9.-]+", "-", f"{provider.id}-{settings['model']}")[:100]
187
+ slug += "-" + sha256(roles)[:16]
188
+ path = directory / "models" / (slug + ".toml")
189
+ atomic_write(path, dumps({"description": f"{provider.name}: {settings['model']} (the app's model)", **roles}))
190
+ return path
191
+
192
+
193
+ def model_role(settings: dict, advanced: dict | None = None) -> dict:
194
+ """The model role (runtime/decision/model.py MODEL_KEYS) of the user's choice with the
195
+ advanced settings; `images` false when the model list says it reads none."""
196
+ provider = PROVIDERS[settings["provider"]]
197
+ advanced = advanced or {}
198
+ role = {"model": settings["model"]}
199
+ if provider.backend == "openrouter":
200
+ # Streamed, as configs/models' OpenRouter files are: chunks keep coming while the
201
+ # model thinks, so a dropped connection shows within the read timeout.
202
+ role.update(backend="openrouter", stream=True)
203
+ else:
204
+ role.update(backend="openai_chat", base_url=settings.get("base_url") or provider.base_url)
205
+ if provider.key_env:
206
+ role["api_key_env"] = provider.key_env
207
+ if provider.max_tokens_key:
208
+ role["max_tokens_key"] = provider.max_tokens_key
209
+ effort = advanced.get("reasoning_effort")
210
+ if effort and effort != "default":
211
+ # Sent in the field the provider reads (runtime/decision/model.py effort_fields).
212
+ role["reasoning_effort"] = effort
213
+ if advanced.get("max_output_tokens"):
214
+ role["max_output_tokens"] = int(advanced["max_output_tokens"])
215
+ if advanced.get("images") is False:
216
+ role["images"] = False
217
+ return role
218
+
219
+
220
+ def viewer_role(settings: dict, advanced: dict | None = None) -> dict | None:
221
+ """The role of the vision model (the setting model.vision: another model of the same
222
+ provider) that describes a view for a main model that reads no images; None when the
223
+ main model reads them or none is set."""
224
+ advanced = advanced or {}
225
+ if advanced.get("images") is not False or not advanced.get("vision"):
226
+ return None
227
+ role = model_role(settings, {key: value for key, value in advanced.items()
228
+ if key not in ("images", "reasoning_effort")})
229
+ return {**role, "model": str(advanced["vision"])}
230
+
231
+
232
+ def described() -> list[dict]:
233
+ """The providers as the page lists them."""
234
+ return [{"id": provider.id, "name": provider.name, "base_url": provider.base_url, "key_env": provider.key_env,
235
+ "note": provider.note} for provider in PROVIDERS.values()]
236
+
237
+
238
+ def ready(directory: Path) -> dict:
239
+ """Whether a model is chosen and its key is there (the environment, [keys] of
240
+ config.toml): {ready, provider, model, key_env}."""
241
+ from .settings import Credentials, read
242
+
243
+ chosen = load(directory)
244
+ provider = PROVIDERS[chosen["provider"]]
245
+ if provider.key_env:
246
+ Credentials(directory, [provider.key_env]).load()
247
+ configured = bool((read(directory).get("model") or {}).get("provider"))
248
+ has_key = not provider.key_env or bool(os.environ.get(provider.key_env))
249
+ return {"ready": has_key and (configured or provider.id == DEFAULT["provider"]), "provider": provider.id,
250
+ "model": chosen["model"], "key_env": provider.key_env}
251
+
252
+
253
+ def setup(directory: Path, read=input, secret=None, write=print, check_key=True) -> dict:
254
+ """The first run in a terminal: which provider and model, and the key; checked with
255
+ the provider (check_key), then kept in config.toml ([model], [keys]). Returns the
256
+ choice."""
257
+ import getpass
258
+
259
+ secret = secret or getpass.getpass
260
+ ids = list(PROVIDERS)
261
+ write("Which model should the agent use? (the key stays in ~/.harness/config.toml, readable by you only)")
262
+ for number, provider in enumerate(PROVIDERS.values(), 1):
263
+ write(f" {number:2}. {provider.name}" + (f" ({provider.note})" if provider.note else ""))
264
+ while True:
265
+ answer = read(f"Provider [1-{len(ids)}, default 1 {PROVIDERS[ids[0]].name}]: ").strip()
266
+ if not answer:
267
+ provider = PROVIDERS[ids[0]]
268
+ elif answer.isdigit() and 1 <= int(answer) <= len(ids):
269
+ provider = PROVIDERS[ids[int(answer) - 1]]
270
+ elif answer in PROVIDERS:
271
+ provider = PROVIDERS[answer]
272
+ else:
273
+ write(f" {answer!r} is not one of them")
274
+ continue
275
+ suggested = DEFAULT["model"] if provider.id == DEFAULT["provider"] else ""
276
+ model = read(f"Model{f' [{suggested}]' if suggested else ''}: ").strip() or suggested
277
+ base_url = read("Base URL of the endpoint: ").strip() if provider.base_url is None and \
278
+ provider.backend != "openrouter" else None
279
+ key = secret(f"{provider.key_env}: ").strip() if provider.key_env else None
280
+ try:
281
+ chosen = check({"provider": provider.id, "model": model, "base_url": base_url})
282
+ except ValueError as error:
283
+ write(f" {error}")
284
+ continue
285
+ if provider.key_env and not key:
286
+ write(" a key is needed for this provider")
287
+ continue
288
+ if check_key:
289
+ result = reach(chosen, key)
290
+ if not result["ok"]:
291
+ write(f" {provider.name} did not take it: {result['detail']}")
292
+ continue
293
+ save(directory, chosen)
294
+ if key:
295
+ from .settings import Credentials
296
+
297
+ Credentials(directory, [provider.key_env]).save(key, provider.key_env)
298
+ from . import model_list
299
+
300
+ if not any(row["id"] == model_list.entry(chosen)["id"] for row in model_list.models(directory)):
301
+ model_list.models(directory, {"action": "save", **chosen})
302
+ write(f"Saved: {provider.name}, {chosen['model']} (~/.harness/models.json).")
303
+ return chosen
@@ -0,0 +1,8 @@
1
+ """The runtime: the model writes programs (conversation, messages), a kernel runs them
2
+ in a session whose API comes from the skills (session, skills, prompts), guards and
3
+ controllers run at every tick (reactive) and a fixed shield checks every command
4
+ (shield).
5
+
6
+ The conversation and its helpers are standard library; the session and the skills import
7
+ numpy and model clients inside the kernel process.
8
+ """
@@ -0,0 +1 @@
1
+ """Semantic decisions at task decision points."""