@lmmslab/harness 0.82.0 → 0.84.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 (39) hide show
  1. package/README.md +2 -2
  2. package/bin/harness.js +6 -1
  3. package/package.json +1 -1
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/prompts/core/core.md +61 -30
  6. package/python/harness/builtin/prompts/reflect/core.md +3 -12
  7. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  8. package/python/harness/builtin/prompts/shared/learning-goal.md +1 -1
  9. package/python/harness/cli.py +104 -18
  10. package/python/harness/config/agent.py +3 -0
  11. package/python/harness/core/trace.py +23 -3
  12. package/python/harness/core/worker.py +6 -0
  13. package/python/harness/host/client.py +26 -21
  14. package/python/harness/host/http.py +11 -1
  15. package/python/harness/host/sessions.py +38 -3
  16. package/python/harness/host/tasks.py +62 -26
  17. package/python/harness/model_list.py +25 -5
  18. package/python/harness/packages/environments.py +51 -12
  19. package/python/harness/packages/manager.py +379 -102
  20. package/python/harness/packages/resolve.py +52 -15
  21. package/python/harness/packages/sources.py +17 -5
  22. package/python/harness/packages/state.py +10 -0
  23. package/python/harness/providers.py +66 -24
  24. package/python/harness/runtime/decision/loop.py +18 -9
  25. package/python/harness/runtime/decision/messages.py +5 -10
  26. package/python/harness/runtime/decision/model.py +21 -11
  27. package/python/harness/runtime/decision/notices.py +66 -0
  28. package/python/harness/runtime/execution/entries.py +53 -7
  29. package/python/harness/runtime/execution/session.py +60 -7
  30. package/python/harness/runtime/learning/active.py +12 -9
  31. package/python/harness/runtime/reactive/tree.py +35 -22
  32. package/python/harness/runtime/task/run.py +259 -162
  33. package/python/harness/runtime/tick.py +34 -3
  34. package/python/harness/settings.py +8 -3
  35. package/python/harness/tui/__init__.py +28 -6
  36. package/python/harness/tui/chat.py +243 -67
  37. package/python/harness/tui/pty.py +16 -0
  38. package/python/harness/tui/renderer.py +34 -0
  39. package/python/harness/tui/views.py +160 -38
@@ -8,6 +8,7 @@ tunnel to the server's port. It is also how every frontend drives a session of t
8
8
  session host (host/): `run` is then the session's id, or "<session>/<agent>".
9
9
  """
10
10
 
11
+ from http.client import IncompleteRead
11
12
  import json
12
13
  import time
13
14
  from urllib.error import HTTPError
@@ -112,6 +113,10 @@ class RemoteConversation:
112
113
  """Send terminal input to a session started with an interactive PTY."""
113
114
  self._post("terminal", text=text)
114
115
 
116
+ def terminal_resize(self, columns: int, rows: int) -> None:
117
+ """Match a hosted PTY to the attached terminal's character dimensions."""
118
+ self._post("terminal/resize", columns=columns, rows=rows)
119
+
115
120
  def handoff(self, agent: str, context: str, *, folder=None, isolation=None):
116
121
  """Start another agent with the context chosen by the user."""
117
122
  answer = self._post("handoff", agent=agent, context=context, folder=str(folder) if folder else None,
@@ -154,22 +159,24 @@ class RemoteConversation:
154
159
  turn's end is its turn_result record, after which the conversation waits). With
155
160
  `stop` (a threading.Event), it ends once the event is set, within the server's
156
161
  keep-alive interval. When the server stops answering, it tries again, waiting longer
157
- each time, and raises HostGone after GONE_SECONDS without a connection."""
162
+ each time, and raises HostGone after GONE_SECONDS of failures without records or keep-alives."""
158
163
  failing, delay = None, RETRY_SECONDS
159
164
  while True:
160
165
  if stop is not None and stop.is_set():
161
166
  return
162
- ended = False
167
+ reason = "the records stream ended before its end event"
163
168
  try:
164
169
  with open_url(f"{self.url}/api/stream?run={quote(self.run)}", timeout=self.timeout,
165
170
  headers={"X-Session-API-Key": self.token, "Last-Event-ID": str(after)}) as response:
166
- failing, delay = None, RETRY_SECONDS
167
171
  for event, data in read_sse(response):
168
172
  if stop is not None and stop.is_set():
169
173
  return
174
+ # Headers alone do not prove a working stream. Records and
175
+ # keep-alive comments do, including on an otherwise quiet turn.
176
+ if event in (None, "record", "end"):
177
+ failing, delay = None, RETRY_SECONDS
170
178
  if event == "end":
171
- ended = True
172
- break
179
+ return
173
180
  if event == "record":
174
181
  record = json.loads(data)
175
182
  after = record["seq"]
@@ -178,23 +185,21 @@ class RemoteConversation:
178
185
  yield record
179
186
  except HTTPError as error:
180
187
  raise RemoteError(_reason(error)) from None
181
- except TimeoutError: # a quiet stream: open it again
182
- continue
183
- except OSError as error: # refused, reset: the server may be restarting, or gone
184
- now = time.monotonic()
185
- failing = failing or now
186
- if now - failing >= GONE_SECONDS:
187
- raise HostGone(f"the session host at {self.url} does not answer "
188
- f"({getattr(error, 'reason', None) or error})") from None
189
- if stop is not None:
190
- if stop.wait(delay):
191
- return
192
- else:
193
- time.sleep(delay)
194
- delay = min(delay * 2, RETRY_LIMIT)
195
- continue
196
- if ended:
188
+ except (OSError, IncompleteRead) as error: # Timeouts, truncated bodies and connection failures.
189
+ reason = getattr(error, "reason", None) or error
190
+ if stop is not None and stop.is_set():
197
191
  return
192
+ now = time.monotonic()
193
+ if failing is None:
194
+ failing = now
195
+ if now - failing >= GONE_SECONDS:
196
+ raise HostGone(f"the session host at {self.url} does not answer ({reason})") from None
197
+ if stop is not None:
198
+ if stop.wait(delay):
199
+ return
200
+ else:
201
+ time.sleep(delay)
202
+ delay = min(delay * 2, RETRY_LIMIT)
198
203
 
199
204
 
200
205
  def _reason(error: HTTPError) -> str:
@@ -480,6 +480,7 @@ class Handler(BaseHTTPRequestHandler):
480
480
 
481
481
  def post_conversations_message(self, body):
482
482
  self._conversation(body).send_message(str(body.get("text") or ""), files=body.get("files") or ())
483
+ self.server.conversations.interact(self.server.conversations.resolve(body.get("run")))
483
484
  self._json({"ok": True})
484
485
 
485
486
  def _control(self, body, capability, method, *args):
@@ -490,6 +491,7 @@ class Handler(BaseHTTPRequestHandler):
490
491
 
491
492
  def post_conversations_steer(self, body):
492
493
  self._control(body, "steer", "steer", str(body.get("text") or ""), body.get("files") or ())
494
+ self.server.conversations.interact(self.server.conversations.resolve(body.get("run")))
493
495
  self._json({"ok": True})
494
496
 
495
497
  def post_conversations_cancel(self, body):
@@ -516,12 +518,17 @@ class Handler(BaseHTTPRequestHandler):
516
518
  self._control(body, "terminal_input", "terminal_input", body.get("text"))
517
519
  self._json({"ok": True})
518
520
 
521
+ def post_conversations_terminal_resize(self, body):
522
+ self._control(body, "terminal_resize", "terminal_resize", body.get("columns"), body.get("rows"))
523
+ self._json({"ok": True})
524
+
519
525
  def post_conversations_pause(self, body):
520
526
  self._conversation(body).pause()
521
527
  self._json({"ok": True})
522
528
 
523
529
  def post_conversations_resume(self, body):
524
530
  self._conversation(body).resume()
531
+ self.server.conversations.interact(self.server.conversations.resolve(body.get("run")))
525
532
  self._json({"ok": True})
526
533
 
527
534
  def post_conversations_confirm(self, body):
@@ -584,11 +591,14 @@ class Handler(BaseHTTPRequestHandler):
584
591
  row = self._session((query.get("id") or [""])[0])
585
592
  lines = int((query.get("lines") or ["40"])[0])
586
593
  for agent in row["agents"]:
594
+ agent["lines"] = []
595
+ if lines <= 0:
596
+ continue
587
597
  directory = Path(agent["directory"]) if agent["directory"] else None
588
598
  records = runs.read_records(directory) if directory and (directory / "events.jsonl").is_file() else []
589
599
  printer = TextTranscript()
590
600
  text = [line for record in records for line in printer.lines(record)]
591
- agent["lines"] = text[-lines:] if lines > 0 else []
601
+ agent["lines"] = text[-lines:]
592
602
  self._json(row)
593
603
 
594
604
  def post_sessions_stop(self, body):
@@ -17,6 +17,7 @@ listed after the host exits (history()).
17
17
  import json
18
18
  from pathlib import Path
19
19
  import secrets
20
+ import sys
20
21
  import threading
21
22
  import time
22
23
 
@@ -54,7 +55,10 @@ def waiting(status, note=None) -> str | None:
54
55
 
55
56
  def ended_status(directory: Path) -> str:
56
57
  """The status of an agent nothing runs any more, from how its episode ended (none: interrupted)."""
57
- return {"error": "ERROR", "interrupted": "INTERRUPTED", None: "INTERRUPTED"}.get(episodes.ending(episodes.summary(directory)), "FINISHED")
58
+ summary = episodes.summary(directory)
59
+ if summary.get("open"):
60
+ return "INTERRUPTED"
61
+ return {"error": "ERROR", "interrupted": "INTERRUPTED", None: "INTERRUPTED"}.get(episodes.ending(summary), "FINISHED")
58
62
 
59
63
 
60
64
  def _usage(conversation) -> dict:
@@ -91,6 +95,8 @@ class Sessions(dict):
91
95
  # Run -> (session id, agent id).
92
96
  self._runs = {}
93
97
  self._lock = threading.RLock()
98
+ # Last session whose user selection was persisted; repeated messages need no new row.
99
+ self._last_interacted = None
94
100
 
95
101
  # The dict, as servers use it.
96
102
 
@@ -127,7 +133,8 @@ class Sessions(dict):
127
133
  now = created if created is not None else time.time()
128
134
  if new:
129
135
  entry = {"id": session, "title": title or _title(conversation),
130
- "frontend": frontend or self.default_frontend, "created": now, "agents": {}}
136
+ "frontend": frontend or self.default_frontend, "created": now,
137
+ "last_interaction": time.time(), "agents": {}}
131
138
  self._sessions[session] = entry
132
139
  agent, parent = MAIN, None
133
140
  else:
@@ -141,6 +148,8 @@ class Sessions(dict):
141
148
  except AttributeError:
142
149
  pass
143
150
  self.save_metadata(run)
151
+ if new:
152
+ self._last_interacted = session
144
153
  self.registered(run, conversation)
145
154
  return session
146
155
 
@@ -232,6 +241,27 @@ class Sessions(dict):
232
241
  """(session id, agent id) of a run."""
233
242
  return self._runs.get(run)
234
243
 
244
+ def interact(self, run: str) -> None:
245
+ """Keep a successful user message or resume, independently of background events."""
246
+ with self._lock:
247
+ found = self._runs.get(run)
248
+ if found is None:
249
+ return
250
+ session, _ = found
251
+ self._sessions[session]["last_interaction"] = time.time()
252
+ if self._last_interacted == session:
253
+ return
254
+ try:
255
+ self.save_metadata(run)
256
+ except OSError as error:
257
+ # The message/resume already succeeded. Leave the selection dirty for retry.
258
+ try:
259
+ print(f"harness: could not save session activity: {error}", file=sys.stderr, flush=True)
260
+ except OSError:
261
+ pass
262
+ else:
263
+ self._last_interacted = session
264
+
235
265
  def save_metadata(self, run: str) -> None:
236
266
  """Persist the public identity once a provider has returned its external ID."""
237
267
  with self._lock:
@@ -242,6 +272,7 @@ class Sessions(dict):
242
272
  self._write({"id": session, "agent": agent, "parent": item["parent"], "run": run,
243
273
  "directory": str(Path(conversation.directory).resolve()), "title": item["title"],
244
274
  "frontend": entry["frontend"], "created": item["created"],
275
+ "last_interaction": entry.get("last_interaction") or entry["created"],
245
276
  "metadata": session_metadata(conversation)})
246
277
 
247
278
  # Describing.
@@ -268,7 +299,8 @@ class Sessions(dict):
268
299
  "model": main.get("model"), "reasoning_effort": main.get("reasoning_effort"),
269
300
  "workspace": getattr(conversation, "workspace_kind", None),
270
301
  "directory": str(Path(conversation.directory).resolve()) if conversation is not None else None,
271
- "created": item["created"], "usage": _usage(conversation) if conversation is not None else None}
302
+ "created": item["created"],
303
+ "usage": _usage(conversation) if conversation is not None else None}
272
304
 
273
305
  def describe(self, session: str) -> dict | None:
274
306
  """One session as it is listed: its id, title, the frontend that started it, its
@@ -325,6 +357,7 @@ def _session_row(entry: dict, agents: dict) -> dict:
325
357
  "cost_usd": round(sum(item["cost_usd"] for item in usage), 6)} if usage else None)
326
358
  return {"id": entry["id"], "title": entry["title"], "frontend": entry["frontend"], "created": entry["created"],
327
359
  "run": main.get("run", entry["id"]), "directory": main.get("directory"), "status": status,
360
+ "last_interaction": entry.get("last_interaction") or entry["created"],
328
361
  "live": any(live(agent["status"]) for agent in tree),
329
362
  "waiting": ("approval" if approvals else main.get("waiting")), "approvals": approvals, "usage": total,
330
363
  "kind": main.get("metadata", {}).get("kind", "harness"),
@@ -377,6 +410,8 @@ def history(index: Path, skip=()) -> list[dict]:
377
410
  entry = entries.setdefault(item["id"], {"id": item["id"], "title": item.get("title") or "",
378
411
  "frontend": item.get("frontend") or "", "created": item.get("created"),
379
412
  "agents": {}})
413
+ if item.get("last_interaction") is not None:
414
+ entry["last_interaction"] = max(entry.get("last_interaction") or 0, item["last_interaction"])
380
415
  if item.get("agent", MAIN) == MAIN:
381
416
  entry.update(title=item.get("title") or "", frontend=item.get("frontend") or "", created=item.get("created"))
382
417
  entry["agents"][item.get("agent", MAIN)] = item
@@ -82,10 +82,20 @@ class TaskHost:
82
82
 
83
83
  def llm(self) -> dict:
84
84
  """The model the user chose, and whether its provider's key is there."""
85
- settings = providers.load(self.directory)
86
- provider = providers.PROVIDERS[settings["provider"]]
87
- key = self.credentials.status(provider.key_env) if provider.key_env else {"set": True, "source": None}
88
- return {**settings, "key_env": provider.key_env, "key": key, "ready": key["set"]}
85
+ from .. import model_list
86
+
87
+ try:
88
+ chosen = model_list.select(self.directory, native=True)
89
+ except model_list.SelectionError as error:
90
+ return {"provider": None, "model": None, "base_url": None, "key_env": None,
91
+ "key": {"set": False, "source": None}, "ready": False,
92
+ "detail": str(error), "selection_error": True}
93
+ settings = chosen if chosen is not None else providers.load(self.directory)
94
+ provider = providers.PROVIDERS.get(settings["provider"])
95
+ key_env = provider.key_env if provider else None
96
+ key = self.credentials.status(key_env) if key_env else {"set": True, "source": None}
97
+ return {**settings, "key_env": key_env, "key": key,
98
+ "ready": chosen is not None and (key["set"] or not providers.requires_key(settings["provider"]))}
89
99
 
90
100
  def status(self) -> dict:
91
101
  workspaces = self.available_workspaces()
@@ -252,7 +262,7 @@ class TaskHost:
252
262
  settings = providers.check(body)
253
263
  provider = providers.PROVIDERS[settings["provider"]]
254
264
  key = str(body.get("key") or "").strip() or (os.environ.get(provider.key_env) if provider.key_env else None)
255
- if provider.key_env and not key:
265
+ if providers.requires_key(settings["provider"]) and not key:
256
266
  return {"ok": False, "detail": "no key"}
257
267
  result = providers.reach(settings, key)
258
268
  if result["ok"]:
@@ -280,14 +290,22 @@ class TaskHost:
280
290
  kind = self.kind(kind)
281
291
  from .. import model_list
282
292
 
283
- current = providers.load(self.directory)
293
+ try:
294
+ current = providers.load(self.directory)
295
+ except model_list.SelectionError:
296
+ if choice is None:
297
+ raise
298
+ current = {}
284
299
  advanced = values["model"]
285
300
  if choice is not None:
286
301
  advanced = {**advanced, "reasoning_effort": effort}
287
- if any(choice.get(key) != current.get(key) for key in ("provider", "base_url")):
288
- advanced.pop("checker", None)
289
- advanced.pop("vision", None)
290
- choice = choice or current
302
+ choice = choice if choice is not None else model_list.select(self.directory, native=True)
303
+ if choice is None:
304
+ raise ValueError("add an enabled Harness model in Settings")
305
+ if any(choice.get(key) != current.get(key) for key in ("provider", "base_url")):
306
+ advanced = dict(advanced)
307
+ advanced.pop("checker", None)
308
+ advanced.pop("vision", None)
291
309
  if model:
292
310
  choice = {**choice, "model": str(model)}
293
311
  # A model the list says reads no images is sent none (its role's `images`).
@@ -403,6 +421,18 @@ class TaskHost:
403
421
  enable.append("agents")
404
422
  return {"enable": enable, "installed": installed, "agent": agent}
405
423
 
424
+ def _package_context(self):
425
+ """Optional workspace context for package management, which also works before setup."""
426
+ from ..bench import bench_spec
427
+
428
+ available = self.workspaces.providers()
429
+ matches = [provider for provider in available if provider.accepts({})]
430
+ if len(matches) != 1 and len(available) != 1:
431
+ # Installing the first environment or managing several needs no default.
432
+ return None, None
433
+ kind = self.kind()
434
+ return kind, bench_spec(self.workspaces.bench(kind)).kind
435
+
406
436
  def skills(self) -> dict:
407
437
  """The skills as Settings lists them: the built-in ones of this computer and the
408
438
  installed ones, each on or off; why an installed one cannot load."""
@@ -410,18 +440,19 @@ class TaskHost:
410
440
 
411
441
  off = set((self.settings.get().get("skills") or {}).get("off", []))
412
442
  loaded = load_skills()
413
- from ..bench import bench_spec
414
- embodiment = bench_spec(self.workspaces.bench(self.kind())).kind
415
- rows = [{"name": embodiment, "format": "built-in", "summary": loaded[embodiment].summary, "locked": True,
416
- "on": True},
417
- {"name": "checklist", "format": "built-in", "summary": loaded["checklist"].summary,
418
- "on": not {"checklist", "plan"} & off}]
419
- for name in self.workspaces.provider().builtin_skills(self.kind()):
420
- if name != embodiment:
443
+ kind, embodiment = self._package_context()
444
+ rows = ([{"name": embodiment, "format": "built-in", "summary": loaded[embodiment].summary,
445
+ "locked": True, "on": True}] if embodiment in loaded else [])
446
+ rows.append({"name": "checklist", "format": "built-in", "summary": loaded["checklist"].summary,
447
+ "on": not {"checklist", "plan"} & off})
448
+ builtin = self.workspaces.provider(kind).builtin_skills(kind) if kind is not None else ()
449
+ for name in builtin:
450
+ if name != embodiment and name in loaded:
421
451
  rows.append({"name": name, "format": "built-in", "summary": loaded[name].summary,
422
452
  "locked": True, "on": True})
423
453
  for row in addons.skills(self.packages):
424
- if row["format"] == "harness" and "embodiments" in row and embodiment not in row["embodiments"]:
454
+ if (embodiment is not None and row["format"] == "harness" and "embodiments" in row
455
+ and embodiment not in row["embodiments"]):
425
456
  continue
426
457
  problem = row.get("problem") or USER_PROBLEMS.get(row["path"]) if row["format"] == "harness" else \
427
458
  row.get("problem")
@@ -451,7 +482,6 @@ class TaskHost:
451
482
  installed only with `trust`, after the page showed what it brings. A folder of
452
483
  skills becomes a package per skill, taken only when it runs on this computer."""
453
484
  import base64
454
- from ..bench import bench_spec
455
485
 
456
486
  zip_bytes = base64.b64decode(body["zip"]) if body.get("zip") else None
457
487
  if not zip_bytes and not body.get("source"):
@@ -459,11 +489,13 @@ class TaskHost:
459
489
 
460
490
  def kernel_python():
461
491
  # A skill's requirements are for the kernel: the environment of the computer's mode.
462
- return self.workspaces.provider().python(self.kind(), log=lambda message: None)
492
+ kind = self.kind()
493
+ return self.workspaces.provider(kind).python(kind, log=lambda message: None)
463
494
 
495
+ _, embodiment = self._package_context()
464
496
  result = self.packages.install([body["source"]] if body.get("source") else [], zip_bytes=zip_bytes,
465
497
  consent=lambda found: bool(body.get("trust")), python=kernel_python,
466
- embodiment=bench_spec(self.workspaces.bench(self.kind())).kind,
498
+ embodiment=embodiment,
467
499
  log=lambda message: None)
468
500
  if result.get("found"):
469
501
  result = {**result, "found": [{**found, "shown": describe(found)} for found in result["found"]]}
@@ -609,10 +641,12 @@ class TaskHost:
609
641
  provider = providers.PROVIDERS[choice["provider"]]
610
642
  if provider.key_env:
611
643
  self.credentials.load()
612
- if not os.environ.get(provider.key_env):
644
+ if providers.requires_key(choice["provider"]) and not os.environ.get(provider.key_env):
613
645
  raise ValueError(f"configure credentials for {provider.name} in Settings")
614
- elif not self.llm()["ready"]:
615
- raise ValueError("no model key yet")
646
+ else:
647
+ state = self.llm()
648
+ if not state["ready"]:
649
+ raise ValueError(state.get("detail") or "no model key yet")
616
650
  kind, folder = self.environment(workspace, folder, last=frontend == "taptab", model_entry=model_entry)
617
651
  request = {"folder": folder} if folder is not None else {}
618
652
  self.workspaces.require_choices(kind, runtime)
@@ -793,7 +827,8 @@ class TaskHost:
793
827
  rows = [row for row in active + (history(index, skip={row["id"] for row in active}) if index else [])
794
828
  if row.get("kind", "harness") == "harness" and row.get("directory")]
795
829
  if identifier is None:
796
- found = sorted(rows, key=lambda row: row["created"] or 0)[-1:]
830
+ found = sorted(rows, key=lambda row: (row.get("last_interaction") or row["created"] or 0,
831
+ row["created"] or 0))[-1:]
797
832
  else:
798
833
  name = str(identifier)
799
834
  found = ([row for row in rows if name in (row["id"], row["run"])]
@@ -803,6 +838,7 @@ class TaskHost:
803
838
  f"no session {identifier} to continue (harness sessions ls --all lists them)")
804
839
  row = found[0]
805
840
  if row["live"]:
841
+ server.conversations.interact(row["run"])
806
842
  return row["run"]
807
843
  directory = Path(row["directory"])
808
844
  kept = saved(directory)
@@ -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}/...).