@lmmslab/harness 0.83.0 → 0.85.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 (38) hide show
  1. package/bin/harness.js +6 -1
  2. package/package.json +1 -1
  3. package/python/harness/__init__.py +1 -1
  4. package/python/harness/builtin/prompts/core/core.md +68 -38
  5. package/python/harness/builtin/prompts/shared/learning-goal.md +1 -1
  6. package/python/harness/cli.py +140 -18
  7. package/python/harness/config/agent.py +3 -0
  8. package/python/harness/core/trace.py +23 -3
  9. package/python/harness/core/worker.py +6 -0
  10. package/python/harness/host/client.py +26 -21
  11. package/python/harness/host/http.py +11 -1
  12. package/python/harness/host/sessions.py +38 -3
  13. package/python/harness/host/tasks.py +71 -27
  14. package/python/harness/instructions.py +329 -0
  15. package/python/harness/model_list.py +25 -5
  16. package/python/harness/packages/environments.py +51 -12
  17. package/python/harness/packages/manager.py +379 -102
  18. package/python/harness/packages/resolve.py +52 -15
  19. package/python/harness/packages/sources.py +17 -5
  20. package/python/harness/packages/state.py +10 -0
  21. package/python/harness/providers.py +66 -24
  22. package/python/harness/runtime/decision/model.py +9 -4
  23. package/python/harness/runtime/events.py +1 -0
  24. package/python/harness/runtime/execution/entries.py +53 -7
  25. package/python/harness/runtime/execution/session.py +57 -10
  26. package/python/harness/runtime/learning/active.py +4 -4
  27. package/python/harness/runtime/reactive/tree.py +96 -53
  28. package/python/harness/runtime/task/environments.py +3 -1
  29. package/python/harness/runtime/task/run.py +93 -4
  30. package/python/harness/runtime/tick.py +34 -3
  31. package/python/harness/settings.py +23 -1
  32. package/python/harness/terminal.py +3 -0
  33. package/python/harness/transcript.py +12 -0
  34. package/python/harness/tui/__init__.py +28 -6
  35. package/python/harness/tui/chat.py +323 -80
  36. package/python/harness/tui/pty.py +16 -0
  37. package/python/harness/tui/renderer.py +1 -0
  38. package/python/harness/tui/views.py +160 -38
@@ -0,0 +1,329 @@
1
+ """Instruction files (AGENTS.md): what the user and a project tell every conversation, as Codex
2
+ and Claude Code read them.
3
+
4
+ user $HARNESS_DATA/AGENTS.override.md, else $HARNESS_DATA/AGENTS.md (~/.harness/)
5
+ project from the project root down to the conversation's folder, one file per
6
+ directory: the first non-empty of instructions.files (default
7
+ AGENTS.override.md, AGENTS.md, CLAUDE.md), then that directory's
8
+ CLAUDE.local.md. The root is the nearest ancestor of the folder holding one of
9
+ instructions.root_markers (default .git); with none, the folder alone. The walk
10
+ never goes above the root.
11
+ below a directory under the folder with its own file is read when a program first
12
+ touches a file in it (nested()), once per conversation.
13
+
14
+ `@path` in a file imports another (relative to the importing file, ~ for home, at most four
15
+ hops, not inside code spans or fenced blocks), when it lies inside the project root or the
16
+ data directory; an import elsewhere is left as text with a warning. Block-level HTML
17
+ comments are left out.
18
+
19
+ The files read at the start share instructions.max_bytes (default 32768, as Codex's
20
+ project_doc_max_bytes; the user file has its own). A file a program's touch brings in is cut
21
+ at 40,000 characters (Claude Code). A file over 4 MiB is skipped. Where something is cut the
22
+ model is told how to read the rest, and the user is warned.
23
+
24
+ The model gets them in its opening message (block()), as Codex gives them; compaction keeps
25
+ that message (runtime/task/run.py). Settings: instructions.load (all, user, off), .files,
26
+ .root_markers, .max_bytes, .exclude (settings.py); harness run --bare loads none.
27
+ """
28
+
29
+ from dataclasses import dataclass, field
30
+ import fnmatch
31
+ import os
32
+ from pathlib import Path
33
+ import re
34
+
35
+ from .paths import data
36
+
37
+ USER_FILES = ("AGENTS.override.md", "AGENTS.md")
38
+ DEFAULTS = {"load": "all", "files": "AGENTS.override.md, AGENTS.md, CLAUDE.md", "root_markers": ".git",
39
+ "max_bytes": 32768, "exclude": ""}
40
+ LOCAL_FILE = "CLAUDE.local.md"
41
+ NESTED_CHARS = 40_000
42
+ SKIP_BYTES = 4 * 1024 * 1024
43
+ IMPORT_DEPTH = 4
44
+ SEPARATOR = "\n\n--- project-doc ---\n\n"
45
+
46
+ _FENCE = re.compile(r"^\s*(```|~~~)")
47
+ _IMPORT = re.compile(r"(?<![\w`@])@((?:\\ |[^\s`])+)")
48
+ _COMMENT = re.compile(r"^[ \t]*<!--.*?-->[ \t]*\n?", re.S | re.M)
49
+
50
+
51
+ @dataclass
52
+ class File:
53
+ path: Path
54
+ label: str # how the model and the user see it: ~/..., or relative to the root
55
+ text: str
56
+ size: int # bytes on disk
57
+ cut: bool = False
58
+
59
+
60
+ @dataclass
61
+ class Loaded:
62
+ folder: Path | None = None
63
+ root: Path | None = None
64
+ files: list[File] = field(default_factory=list)
65
+ skipped: list[tuple[str, str]] = field(default_factory=list) # (label, why)
66
+ warnings: list[str] = field(default_factory=list)
67
+
68
+ def record(self) -> dict:
69
+ """What the trace keeps of it (the instructions record)."""
70
+ return {"folder": str(self.folder) if self.folder else None, "root": str(self.root) if self.root else None,
71
+ "files": [{"path": str(item.path), "label": item.label, "bytes": len(item.text.encode("utf-8")),
72
+ "size": item.size, **({"cut": True} if item.cut else {})} for item in self.files],
73
+ **({"skipped": [{"label": label, "why": why} for label, why in self.skipped]} if self.skipped else {}),
74
+ **({"warnings": list(self.warnings)} if self.warnings else {})}
75
+
76
+
77
+ def options(given=None) -> dict:
78
+ """The instructions settings with their defaults; lists as lists."""
79
+ values = {**DEFAULTS, **{key: value for key, value in (given or {}).items() if value is not None}}
80
+ for key in ("files", "root_markers", "exclude"):
81
+ if isinstance(values[key], str):
82
+ values[key] = [item.strip() for item in values[key].split(",") if item.strip()]
83
+ else:
84
+ values[key] = [str(item) for item in values[key]]
85
+ values["max_bytes"] = max(0, int(values["max_bytes"]))
86
+ if values["load"] not in ("all", "user", "off"):
87
+ raise ValueError("instructions.load is all, user or off")
88
+ return values
89
+
90
+
91
+ def _label(path: Path, root: Path | None) -> str:
92
+ if root is not None and path.is_relative_to(root):
93
+ return path.relative_to(root).as_posix()
94
+ home = Path.home()
95
+ return "~/" + path.relative_to(home).as_posix() if path.is_relative_to(home) else path.as_posix()
96
+
97
+
98
+ def _excluded(path: Path, patterns) -> bool:
99
+ text = path.as_posix()
100
+ return any(fnmatch.fnmatch(text, pattern) or fnmatch.fnmatch(path.name, pattern) for pattern in patterns)
101
+
102
+
103
+ def _read(path: Path, label: str, loaded: Loaded) -> str | None:
104
+ """The file's text, or None (absent, empty, too large, unreadable)."""
105
+ try:
106
+ size = path.stat().st_size
107
+ except OSError:
108
+ return None
109
+ if size > SKIP_BYTES:
110
+ loaded.skipped.append((label, "over 4 MiB"))
111
+ loaded.warnings.append(f"{label} is over 4 MiB and was not loaded")
112
+ return None
113
+ try:
114
+ text = path.read_text(encoding="utf-8", errors="replace")
115
+ except OSError as error:
116
+ loaded.skipped.append((label, f"unreadable: {error}"))
117
+ return None
118
+ text = _without_comments(text)
119
+ if not text.strip():
120
+ loaded.skipped.append((label, "empty"))
121
+ return None
122
+ return text
123
+
124
+
125
+ def _outside_code(text: str):
126
+ """(line, inside_code) for each line: fenced blocks count as code."""
127
+ fenced = False
128
+ for line in text.splitlines(keepends=True):
129
+ if _FENCE.match(line):
130
+ fenced = not fenced
131
+ yield line, True
132
+ continue
133
+ yield line, fenced
134
+
135
+
136
+ def _without_comments(text: str) -> str:
137
+ """The text without block-level HTML comments; comments inside fenced blocks stay."""
138
+ out, chunk = [], []
139
+ for line, code in _outside_code(text):
140
+ if code:
141
+ if chunk:
142
+ out.append(_COMMENT.sub("", "".join(chunk)))
143
+ chunk = []
144
+ out.append(line)
145
+ else:
146
+ chunk.append(line)
147
+ if chunk:
148
+ out.append(_COMMENT.sub("", "".join(chunk)))
149
+ return "".join(out)
150
+
151
+
152
+ def _imports(text: str) -> list[str]:
153
+ """The @paths a file imports: not inside code spans or fenced blocks."""
154
+ found = []
155
+ for line, code in _outside_code(text):
156
+ if code:
157
+ continue
158
+ line = re.sub(r"`[^`]*`", "", line)
159
+ found += [match.group(1).replace("\\ ", " ") for match in _IMPORT.finditer(line)]
160
+ return found
161
+
162
+
163
+ def _imported(path: Path, text: str, allowed, loaded: Loaded, root: Path | None, depth: int = 1, seen=None) -> list[File]:
164
+ """The files `text` (of `path`) imports, and theirs, as entries after it."""
165
+ seen = seen if seen is not None else {path.resolve()}
166
+ entries = []
167
+ if depth > IMPORT_DEPTH:
168
+ return entries
169
+ for name in _imports(text):
170
+ target = Path(os.path.expanduser(name))
171
+ target = (target if target.is_absolute() else path.parent / target).resolve()
172
+ if target in seen or not target.is_file():
173
+ continue
174
+ label = _label(target, root)
175
+ if not any(target.is_relative_to(base) for base in allowed):
176
+ loaded.warnings.append(f"{_label(path, root)} imports {name}, outside the project and "
177
+ f"{_label(data(), None)}: not loaded")
178
+ continue
179
+ seen.add(target)
180
+ body = _read(target, label, loaded)
181
+ if body is None:
182
+ continue
183
+ entries.append(File(target, label, body, target.stat().st_size))
184
+ entries += _imported(target, body, allowed, loaded, root, depth + 1, seen)
185
+ return entries
186
+
187
+
188
+ def project_root(folder: Path, markers) -> Path | None:
189
+ """The nearest ancestor of `folder` (itself included) holding one of `markers`; None without."""
190
+ if not markers:
191
+ return None
192
+ for directory in (folder, *folder.parents):
193
+ if any((directory / marker).exists() for marker in markers):
194
+ return directory
195
+ return None
196
+
197
+
198
+ def _directory_files(directory: Path, names, settings, root, loaded) -> list[File]:
199
+ """The instruction file of one directory (the first of `names` with text), then its CLAUDE.local.md."""
200
+ entries = []
201
+ for name in names:
202
+ path = directory / name
203
+ if not path.is_file():
204
+ continue
205
+ label = _label(path, root)
206
+ if _excluded(path, settings["exclude"]):
207
+ loaded.skipped.append((label, "excluded (instructions.exclude)"))
208
+ continue
209
+ text = _read(path, label, loaded)
210
+ if text is not None:
211
+ entries.append(File(path, label, text, path.stat().st_size))
212
+ break
213
+ local = directory / LOCAL_FILE
214
+ if LOCAL_FILE not in names and local.is_file() and not _excluded(local, settings["exclude"]):
215
+ text = _read(local, _label(local, root), loaded)
216
+ if text is not None:
217
+ entries.append(File(local, _label(local, root), text, local.stat().st_size))
218
+ allowed = [root or directory, data()]
219
+ for entry in list(entries):
220
+ entries[entries.index(entry) + 1:entries.index(entry) + 1] = _imported(
221
+ entry.path, entry.text, allowed, loaded, root)
222
+ return entries
223
+
224
+
225
+ def _budget(entries: list[File], limit: int, loaded: Loaded, what: str) -> list[File]:
226
+ """`entries` within `limit` bytes: the one that crosses it is cut, those after it left out."""
227
+ kept, left = [], limit
228
+ for entry in entries:
229
+ size = len(entry.text.encode("utf-8"))
230
+ if left <= 0:
231
+ loaded.skipped.append((entry.label, f"over the {limit}-byte budget (instructions.max_bytes)"))
232
+ loaded.warnings.append(f"{entry.label} was not loaded: the {what} instructions reached "
233
+ f"instructions.max_bytes ({limit} bytes)")
234
+ continue
235
+ if size > left:
236
+ entry.text = entry.text.encode("utf-8")[:left].decode("utf-8", "ignore")
237
+ entry.text += (f"\n(The rest of {entry.label} is not shown: {size - left} more bytes. "
238
+ "Read it with read_file when you need it.)")
239
+ entry.cut = True
240
+ loaded.warnings.append(f"{entry.label} was cut at {left} of {size} bytes (instructions.max_bytes)")
241
+ size = left
242
+ kept.append(entry)
243
+ left -= size
244
+ return kept
245
+
246
+
247
+ def load(folder, settings=None, *, user: bool = True) -> Loaded:
248
+ """The instruction files a conversation working in `folder` (None: no folder) reads at its
249
+ start; `user` false: the project's only (another folder joining the conversation)."""
250
+ settings = options(settings)
251
+ folder = Path(folder).expanduser().resolve() if folder else None
252
+ loaded = Loaded(folder=folder)
253
+ if settings["load"] == "off":
254
+ return loaded
255
+ limit = settings["max_bytes"]
256
+ found = []
257
+ for name in USER_FILES if user else ():
258
+ path = data() / name
259
+ if path.is_file() and not _excluded(path, settings["exclude"]):
260
+ text = _read(path, _label(path, None), loaded)
261
+ if text is not None:
262
+ found = [File(path, _label(path, None), text, path.stat().st_size)]
263
+ found += _imported(path, text, [data()], loaded, None)
264
+ break
265
+ if limit:
266
+ loaded.files += _budget(found, limit, loaded, "user")
267
+ if folder is None or settings["load"] == "user" or not limit:
268
+ return loaded
269
+ root = project_root(folder, settings["root_markers"])
270
+ loaded.root = root or folder
271
+ project = []
272
+ for directory in _walk(loaded.root, folder):
273
+ project += _directory_files(directory, settings["files"], settings, loaded.root, loaded)
274
+ loaded.files += _budget(project, limit, loaded, "project")
275
+ return loaded
276
+
277
+
278
+ def _walk(root: Path, folder: Path) -> list[Path]:
279
+ """The directories from `root` down to `folder`, both included."""
280
+ if root == folder:
281
+ return [folder]
282
+ relative = folder.relative_to(root)
283
+ return [root, *(root / Path(*relative.parts[:index]) for index in range(1, len(relative.parts) + 1))]
284
+
285
+
286
+ def nested(folder, touched, settings, told: set) -> list[File]:
287
+ """The instruction files of directories below `folder` down to `touched` (a file or a
288
+ directory a program read, wrote or ran in) that the conversation has not been told of; each
289
+ cut at NESTED_CHARS. `told` holds the directories already told and is updated."""
290
+ settings = options(settings)
291
+ if settings["load"] != "all" or folder is None:
292
+ return []
293
+ folder = Path(folder).resolve()
294
+ target = (folder / touched).resolve() if not Path(touched).is_absolute() else Path(touched).resolve()
295
+ if not target.is_relative_to(folder) or target == folder:
296
+ return []
297
+ directory = target if target.is_dir() else target.parent
298
+ loaded = Loaded(folder=folder)
299
+ entries = []
300
+ for current in _walk(folder, directory)[1:]:
301
+ if current in told:
302
+ continue
303
+ told.add(current)
304
+ for entry in _directory_files(current, settings["files"], settings, folder, loaded):
305
+ if len(entry.text) > NESTED_CHARS:
306
+ entry.text = entry.text[:NESTED_CHARS] + (f"\n(The rest of {entry.label} is not shown. Read it with "
307
+ "read_file when you need it.)")
308
+ entry.cut = True
309
+ entries.append(entry)
310
+ return entries
311
+
312
+
313
+ def block(loaded: Loaded) -> str:
314
+ """The model's text: Codex's wrapper, the user's file first, each file under its path."""
315
+ if not loaded.files:
316
+ return ""
317
+ user = [entry for entry in loaded.files if entry.path.is_relative_to(data())]
318
+ project = [entry for entry in loaded.files if entry not in user]
319
+ parts = ["\n\n".join(f"(from {entry.label})\n{entry.text.strip()}" for entry in user)] if user else []
320
+ if project:
321
+ parts.append("\n\n".join(f"(from {entry.label})\n{entry.text.strip()}" for entry in project))
322
+ head = "# AGENTS.md instructions" + (f" for {loaded.folder}" if loaded.folder else "")
323
+ return f"{head}\n\n<INSTRUCTIONS>\n{SEPARATOR.join(parts) if len(parts) > 1 else parts[0]}\n</INSTRUCTIONS>\n\n"
324
+
325
+
326
+ def told(entries: list[File]) -> str:
327
+ """The note for files a program's touch brought in (nested())."""
328
+ return "\n\n".join(f"Instructions for {entry.path.parent.as_posix()} (from {entry.label}):\n{entry.text.strip()}"
329
+ for entry in entries)
@@ -8,6 +8,7 @@ text, and a view it looks at is described by the vision model when one is set
8
8
  (the setting model.vision)."""
9
9
 
10
10
  import json
11
+ import os
11
12
 
12
13
  from . import providers, settings
13
14
  from .core import atomic_write, sha256
@@ -15,6 +16,10 @@ from .core.procs import file_lock
15
16
  from harness.runtime.decision.model import valid_effort
16
17
 
17
18
 
19
+ class SelectionError(ValueError):
20
+ """The selected route is unavailable; management can open without starting a new task."""
21
+
22
+
18
23
  def entry(raw):
19
24
  provider = raw.get("provider")
20
25
  model = str(raw.get("model") or "").strip()
@@ -62,10 +67,14 @@ def _read(path):
62
67
  raise ValueError("duplicate model entries")
63
68
  return rows
64
69
  except (ValueError, TypeError) as error:
65
- raise ValueError(f"{path}: {error}") from error
70
+ raise SelectionError(f"{path}: {error}") from error
66
71
  config = settings.read(path.parent)
67
72
  chosen = providers.load(path.parent)
68
- configured = (config.get("model") or {}).get("provider") or providers.ready(path.parent)["ready"]
73
+ provider = providers.PROVIDERS[chosen["provider"]]
74
+ if provider.key_env:
75
+ settings.Credentials(path.parent, [provider.key_env]).load()
76
+ configured = (config.get("model") or {}).get("provider") or not providers.requires_key(provider.id) or \
77
+ bool(os.environ.get(provider.key_env))
69
78
  legacy = str((config.get("taptab") or {}).get("models") or "").split(",")
70
79
  return [entry({**chosen, "model": model}) for model in dict.fromkeys(
71
80
  [chosen["model"]] * bool(configured) + [value.strip() for value in legacy if value.strip()]) if model]
@@ -73,8 +82,12 @@ def _read(path):
73
82
 
74
83
  def models(directory, change=None):
75
84
  path = directory / "models.json"
76
- if change is None and path.exists():
77
- return _read(path)
85
+ if change is None:
86
+ rows = _read(path)
87
+ # An unsuccessful first-run readiness check is not an explicitly empty list.
88
+ # Leave it absent so exporting a key can still initialize the default later.
89
+ if path.exists() or not rows:
90
+ return rows
78
91
  path.parent.mkdir(parents=True, exist_ok=True)
79
92
  with file_lock(path.with_suffix(".lock")):
80
93
  rows = _read(path)
@@ -109,7 +122,14 @@ def select(directory, identifier=None, *, native=False):
109
122
  and (not native or row["provider"] in providers.PROVIDERS or providers.is_agent(row["provider"]))]
110
123
  if identifier is None:
111
124
  chosen = providers.load(directory)
112
- return next((row for row in rows if all(row[key] == chosen[key] for key in chosen)), rows[0] if rows else None)
125
+ matched = next((row for row in rows if all(row[key] == chosen[key] for key in chosen)), None)
126
+ if matched is not None or not rows:
127
+ return matched
128
+ if (settings.read(directory).get("model") or {}).get("provider"):
129
+ raise SelectionError(f"{directory / 'config.toml'} selects {chosen['provider']}/{chosen['model']}, "
130
+ f"which is not enabled in {directory / 'models.json'}; correct the configuration "
131
+ "or model list, or select an enabled model with --model")
132
+ return rows[0]
113
133
  matches = [row for row in rows if identifier in (row["id"], row["model"], row["provider"] + "/" + row["model"])]
114
134
  if len(matches) != 1:
115
135
  raise ValueError(f"choose one enabled model from {directory / 'models.json'}; "
@@ -246,7 +246,8 @@ class Environment:
246
246
  record = json.loads((self.directory / RECORD).read_text(encoding="utf-8"))
247
247
  except (OSError, ValueError):
248
248
  return None
249
- return record if record.get("hash") == self.hash else None
249
+ return record if isinstance(record, dict) and record.get("hash") == self.hash and \
250
+ self.python.is_file() and os.access(self.python, os.X_OK) else None
250
251
 
251
252
  def variables(self) -> dict:
252
253
  """Placeholders of its commands: python, env and each source's checkout by name."""
@@ -339,7 +340,7 @@ def install(environment: Environment, *, log=print) -> Environment:
339
340
  started = time.monotonic()
340
341
  log(f"{environment.name}: installing its environment ({environment.directory}); log {path}")
341
342
  try:
342
- _install(environment, out)
343
+ _install(environment, out, log=log)
343
344
  except Exception as error:
344
345
  out.write(f"FAILED: {error}\n")
345
346
  raise RuntimeError(f"{environment.name}: its environment did not install ({error}); see {path}") \
@@ -349,14 +350,46 @@ def install(environment: Environment, *, log=print) -> Environment:
349
350
 
350
351
 
351
352
  def on_first_use(environment: Environment, what: str, *, log=print) -> Environment:
352
- """A frontend's environment (the terminal chat's prompt_toolkit and rich, pywebview, Playwright), installed when first needed with one line to `log`."""
353
+ """A frontend's environment (the terminal chat's prompt_toolkit and rich, pywebview, Playwright), installed when first needed, with progress and retry details sent to `log`."""
353
354
  if environment.installed() is None:
354
355
  log(f"harness: installing {what} once, into {environment.directory} (log: {home() / 'logs' / f'install-{environment.name}.log'})")
355
- install(environment, log=lambda message: None)
356
+ install(environment, log=log)
356
357
  return environment
357
358
 
358
359
 
359
- def _install(environment: Environment, out) -> None:
360
+ class _InstallFailure(RuntimeError):
361
+ def __init__(self, command, code, detail):
362
+ self.detail = detail
363
+ super().__init__(f"{command} exited with {code}" + (f": {detail}" if detail else ""))
364
+
365
+
366
+ def _transient_install_failure(detail: str) -> bool:
367
+ text = detail.lower()
368
+ deterministic = ("no matching distribution", "could not find a version", "no solution found",
369
+ "resolutionimpossible", "conflicting dependencies", "failed building wheel",
370
+ "permission denied", "certificate_verify_failed", "requires a different python")
371
+ if any(phrase in text for phrase in deterministic):
372
+ return False
373
+ return any(phrase in text for phrase in (
374
+ "connection reset", "connection aborted", "connection refused", "connectionerror",
375
+ "temporary failure in name resolution", "network is unreachable", "dns error",
376
+ "timed out", "timeout", "502 bad gateway", "503 service unavailable", "504 gateway timeout",
377
+ "status code 502", "status code 503", "status code 504"))
378
+
379
+
380
+ def _output_tail(out, start: int) -> str:
381
+ out.flush()
382
+ if hasattr(out, "getvalue"):
383
+ return out.getvalue()[start:][-8192:].strip()
384
+ # Read a bounded tail without changing the writer's position or retaining a
385
+ # potentially very large installer log in memory.
386
+ with open(out.name, "rb") as handle:
387
+ handle.seek(0, os.SEEK_END)
388
+ handle.seek(max(start, handle.tell() - 8192))
389
+ return handle.read().decode("utf-8", errors="replace").strip()
390
+
391
+
392
+ def _install(environment: Environment, out, *, log=lambda message: None) -> None:
360
393
  spec = environment.spec
361
394
  directory = environment.directory
362
395
  if directory.exists():
@@ -381,9 +414,10 @@ def _install(environment: Environment, out) -> None:
381
414
  argv = [str(item) for item in argv]
382
415
  out.write(f"$ {' '.join(argv)}\n")
383
416
  out.flush()
417
+ start = out.tell()
384
418
  result = subprocess.run(argv, cwd=cwd, env=env or run_env, stdout=out, stderr=subprocess.STDOUT)
385
419
  if result.returncode != 0:
386
- raise RuntimeError(f"{argv[0]} {' '.join(argv[1:4])} ... exited with {result.returncode}")
420
+ raise _InstallFailure(f"{argv[0]} {' '.join(argv[1:4])} ...", result.returncode, _output_tail(out, start))
387
421
 
388
422
  uv = shutil.which("uv")
389
423
  version = spec["python"]
@@ -411,16 +445,21 @@ def _install(environment: Environment, out) -> None:
411
445
  "--override", overrides, *indexes, *arguments]
412
446
  else:
413
447
  argv = [environment.python, "-m", "pip", "install", "--disable-pip-version-check", *indexes, *arguments]
414
- # An index that times out once in a while should not cost the whole install:
415
- # the same installs again (what is in place stays), twice.
448
+ # Retry only recognizable transient index/network failures. Dependency,
449
+ # build, permissions and unknown failures need a correction, not a delay.
416
450
  for attempt in range(3):
417
451
  try:
418
452
  return run(argv)
419
- except RuntimeError:
420
- if attempt == 2:
453
+ except _InstallFailure as error:
454
+ if attempt == 2 or not _transient_install_failure(error.detail):
421
455
  raise
422
- out.write("(again in 30 s)\n")
423
- time.sleep(30)
456
+ delay = 2 ** attempt
457
+ message = (f"{environment.name}: install attempt {attempt + 1}/3 failed: "
458
+ f"{error.detail[-800:]}; retrying in {delay} s")
459
+ out.write(message + "\n")
460
+ out.flush()
461
+ log(message)
462
+ time.sleep(delay)
424
463
 
425
464
  if spec.get("requirements"):
426
465
  # "-r FILE" names a requirements file (of a source: {robodojo}/...).