Coverage for src/keel/activity.py: 100%

208 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""Lightweight, additive **command-activity** records for live observability. 

2 

3The resumable ``checkpoint`` is the ship backbone's own artifact (s0–s12) and is 

4deliberately ship-shaped. Most other keel commands (``triage``, ``morning``, 

5``pr-loop`` …) run in the main checkout, never write a checkpoint, and so are 

6invisible to ``keel-visual``'s live board. 

7 

8This module adds a *separate, additive* channel: a per-run JSON record under 

9``.keel/activity/`` that any command's adapter can stamp as it moves through its 

10own flow phases (from :mod:`keel.flows`). It never touches the checkpoint 

11contract. Records are keyed by ``run_id`` (one file each), so two commands in the 

12same repo never clobber one another. 

13 

14Pure-core + thin I/O, mirroring :mod:`keel.checkpoint`: the builders/validators 

15are deterministic (stable ordering, no wall-clock, no randomness); only 

16read/write/remove touch the filesystem. 

17""" 

18 

19from __future__ import annotations 

20 

21import contextlib 

22import json 

23import re 

24import time 

25import unicodedata 

26from collections.abc import Callable, Iterator 

27from pathlib import Path 

28from typing import Any 

29 

30from . import config as cfg 

31from . import flows, lock, workspace 

32 

33ACTIVITY_SCHEMA_VERSION = "keel.activity.v1" 

34RECORD_TYPE_ACTIVITY = "command_activity" 

35DEFAULT_ACTIVITY_DIR = ".keel/activity" 

36STATUSES = ("running", "done", "merged") 

37 

38#: Whether the phase the run reached was actually *passed*. Separate from 

39#: :data:`STATUSES` because "advanced to s8" and "cleared s8" are different facts and 

40#: were previously written identically (#636) — a run whose gates came back red 

41#: recorded as ``phase: s8, status: running``, carrying no failure signal at all, and 

42#: the board painted it as in-progress. ``None`` means the step reached this stamp 

43#: without a verdict to report (planning, a phase with nothing to pass), which is not 

44#: the same as passing. 

45VERDICTS = ("pass", "blocked") 

46 

47#: The field a record keeps its delegates' measured token counts in (#1373): an object 

48#: keyed by the delegate call's id, each value ``{"model", "prompt_tokens", 

49#: "completion_tokens"}``. Keyed rather than summed, for two reasons: one ship run makes 

50#: several delegate calls, often to different vendors, and a sum could only be priced at 

51#: one model; and a key makes recording the same call twice a no-op instead of a double 

52#: count. Absent until a delegate records into the run. 

53USAGE_FIELD = "delegate_usage" 

54 

55#: Optional "who is driving this run" fields (#1482): the host (Claude Code, Codex…), 

56#: the agent or delegate (claude, codex…), its model id and reasoning effort. Additive 

57#: to ``keel.activity.v1`` — absent from a record means unknown, never ``None``. 

58IDENTITY_FIELDS = ("host", "agent", "model", "effort") 

59IDENTITY_MAX_LEN = 64 

60 

61#: How long a writer waits for another writer of the same record: attempts x poll. 

62#: Holding the lock takes one read and one atomic write, so two seconds is ample; it is 

63#: bounded because a holder killed mid-write leaves its claim behind. 

64LOCK_ATTEMPTS = 40 

65LOCK_POLL_S = 0.05 

66 

67# A run_id reduces to this slug for its filename; anything else is rejected so a 

68# crafted run_id can never escape the activity directory. 

69_RUN_ID_SLUG = re.compile(r"[^a-z0-9._-]+") 

70 

71 

72class ActivityError(ValueError): 

73 """Raised when an activity record or path is malformed.""" 

74 

75 

76def activity_contract_as_dict() -> dict[str, Any]: 

77 """Return the stable activity-record contract consumed by adapters.""" 

78 return { 

79 "schema_version": ACTIVITY_SCHEMA_VERSION, 

80 "record_type": RECORD_TYPE_ACTIVITY, 

81 "dir": DEFAULT_ACTIVITY_DIR, 

82 "keyed_by": "run_id", 

83 "statuses": list(STATUSES), 

84 "additive": True, 

85 "touches_checkpoint": False, 

86 "phase_source": "keel.flows.flow_for(command)", 

87 "usage_field": USAGE_FIELD, 

88 "identity_fields": list(IDENTITY_FIELDS), 

89 } 

90 

91 

92def configured_activity_dir(config: cfg.ProjectConfig) -> tuple[str, str]: 

93 """Return the configured activity directory and its source.""" 

94 pack = config.policy_pack or {} 

95 reports = pack.get("reports") if isinstance(pack.get("reports"), dict) else {} 

96 value = reports.get("activity") 

97 if isinstance(value, str) and value.strip(): 

98 return value, "policy_pack.reports.activity" 

99 return DEFAULT_ACTIVITY_DIR, "default" 

100 

101 

102def resolve_dir(root: str | Path, config: cfg.ProjectConfig) -> Path: 

103 """Resolve the activity directory under ``root`` and reject escapes.""" 

104 raw, _ = configured_activity_dir(config) 

105 path = Path(raw) 

106 if workspace.is_root_anchored(raw): 

107 raise ActivityError("activity dir must be relative to the project root") 

108 root_path = Path(root).resolve() 

109 resolved = (root_path / path).resolve() 

110 try: 

111 resolved.relative_to(root_path) 

112 except ValueError as exc: 

113 raise ActivityError("activity dir escapes the project root") from exc 

114 return resolved 

115 

116 

117def run_id_slug(run_id: str) -> str: 

118 """Reduce a run_id to a safe filename stem (lowercase ``[a-z0-9._-]``).""" 

119 if not isinstance(run_id, str) or not run_id.strip(): 

120 raise ActivityError("run_id must be a non-empty string") 

121 slug = _RUN_ID_SLUG.sub("-", run_id.strip().lower()).strip("-.") 

122 if not slug: 

123 raise ActivityError("run_id has no usable characters") 

124 return slug 

125 

126 

127def record_path(root: str | Path, config: cfg.ProjectConfig, run_id: str) -> Path: 

128 """Path of the activity record for ``run_id`` under ``root``.""" 

129 return resolve_dir(root, config) / f"{run_id_slug(run_id)}.json" 

130 

131 

132def _phase_ids(command: str) -> tuple[str, ...]: 

133 return tuple(phase.id for phase in flows.flow_for(command)) 

134 

135 

136def build_activity_record( 

137 *, 

138 command: str, 

139 run_id: str, 

140 phase: str, 

141 status: str = "running", 

142 verdict: str | None = None, 

143 issue: int | None = None, 

144 pr: int | None = None, 

145 note: str | None = None, 

146 host: str | None = None, 

147 agent: str | None = None, 

148 model: str | None = None, 

149 effort: str | None = None, 

150) -> dict[str, Any]: 

151 """Build one deterministic activity record, validating command + phase. 

152 

153 ``command`` must be a known :mod:`keel.flows` command and ``phase`` one of 

154 that command's flow phase ids. ``status`` is ``running``, ``done`` or 

155 ``merged`` (a real merge landed, distinct from a soft ``done``). 

156 

157 ``verdict`` (:data:`VERDICTS`) says whether the phase was **passed**, which 

158 ``status`` deliberately does not: a blocked gate run is still ``running`` in the 

159 board's sense — it advanced, it did not finish — and recording only that made a 

160 red gate indistinguishable from an in-progress one (#636). ``None`` = no verdict 

161 to report, which must not read as a pass. 

162 

163 ``host`` / ``agent`` / ``model`` / ``effort`` (:data:`IDENTITY_FIELDS`) say who is 

164 driving the run; each is a short single-line string and is left out of the record 

165 when not given. 

166 """ 

167 if not flows.is_known(command): 

168 raise ActivityError(f"unknown command: {command!r}") 

169 if phase not in _phase_ids(command): 

170 raise ActivityError(f"phase {phase!r} is not a {command} flow phase") 

171 if status not in STATUSES: 

172 raise ActivityError(f"unsupported status: {status!r}") 

173 if verdict is not None and verdict not in VERDICTS: 

174 raise ActivityError(f"unsupported verdict: {verdict!r}") 

175 record: dict[str, Any] = { 

176 "schema_version": ACTIVITY_SCHEMA_VERSION, 

177 "record_type": RECORD_TYPE_ACTIVITY, 

178 "command": command, 

179 "run_id": run_id, 

180 "phase": phase, 

181 "status": status, 

182 "verdict": verdict, 

183 "issue": issue, 

184 "pr": pr, 

185 "note": note, 

186 } 

187 for name, value in zip(IDENTITY_FIELDS, (host, agent, model, effort), strict=True): 

188 if value is not None: 

189 issue_text = identity_issue(value) 

190 if issue_text is not None: 

191 raise ActivityError(f"{name}: {issue_text}") 

192 record[name] = value 

193 return record 

194 

195 

196def identity_issue(value: Any) -> str | None: 

197 """Why ``value`` is not a valid identity string, or ``None`` when it is.""" 

198 if not isinstance(value, str) or not value.strip(): 

199 return "must be a non-empty string" 

200 if len(value) > IDENTITY_MAX_LEN: 

201 return f"must be at most {IDENTITY_MAX_LEN} characters" 

202 if value != value.strip(): 

203 return "must not start or end with whitespace" 

204 # Cc: C0, DEL and C1 (incl. NEL); Zl/Zp: U+2028/U+2029 — anything that breaks a line. 

205 if any(unicodedata.category(ch) in ("Cc", "Zl", "Zp") for ch in value): 

206 return "must not contain control characters or line breaks" 

207 return None 

208 

209 

210def carry_identity(record: dict[str, Any], existing: dict[str, Any] | None) -> dict[str, Any]: 

211 """``record`` with the identity ``existing`` held, where the stamp does not restate it. 

212 

213 A later stamp that names neither ``agent`` nor ``model`` keeps all four fields (it may 

214 still change one, e.g. ``effort``). A stamp that names an ``agent`` or a ``model`` is a 

215 new driver: it replaces the whole set it names and drops what it does not restate (the 

216 old effort belonged to the old model), so a delegate's identity never leaks into the next 

217 phase. Only ``host`` — where the run lives, whoever drives it — is always kept. 

218 """ 

219 new_driver = "agent" in record or "model" in record 

220 names = ("host",) if new_driver else IDENTITY_FIELDS 

221 carried = { 

222 name: existing[name] 

223 for name in names 

224 if name not in record and existing and name in existing 

225 } 

226 return {**record, **carried} if carried else record 

227 

228 

229def validate_activity(record: Any) -> None: 

230 """Validate the stable activity-record shape.""" 

231 if not isinstance(record, dict): 

232 raise ActivityError("activity must be an object") 

233 if record.get("schema_version") != ACTIVITY_SCHEMA_VERSION: 

234 raise ActivityError("unsupported schema_version") 

235 if record.get("record_type") != RECORD_TYPE_ACTIVITY: 

236 raise ActivityError("unsupported record_type") 

237 command = record.get("command") 

238 if not isinstance(command, str) or not flows.is_known(command): 

239 raise ActivityError("unsupported command") 

240 if not isinstance(record.get("run_id"), str) or not record["run_id"].strip(): 

241 raise ActivityError("run_id must be a non-empty string") 

242 if record.get("phase") not in _phase_ids(command): 

243 raise ActivityError("unsupported phase") 

244 if record.get("status") not in STATUSES: 

245 raise ActivityError("unsupported status") 

246 # Absent is fine (older records, phases with nothing to pass); a *wrong* value is 

247 # not — a board that trusts this field must never read a typo as a pass. 

248 if record.get("verdict") is not None and record.get("verdict") not in VERDICTS: 

249 raise ActivityError("unsupported verdict") 

250 for name in IDENTITY_FIELDS: 

251 if name in record: 

252 problem = identity_issue(record[name]) 

253 if problem is not None: 

254 raise ActivityError(f"{name}: {problem}") 

255 usage = record.get(USAGE_FIELD) 

256 if usage is not None: 

257 # The cost report prices whatever is here as measured, so a malformed entry is 

258 # refused at the door rather than read as a count. 

259 if not isinstance(usage, dict): 

260 raise ActivityError(f"{USAGE_FIELD} must be an object") 

261 for call_id, entry in usage.items(): 

262 issue = usage_entry_issue(entry) 

263 if issue is not None: 

264 raise ActivityError(f"{USAGE_FIELD}[{call_id!r}]: {issue}") 

265 

266 

267def _is_count(value: Any) -> bool: 

268 return isinstance(value, int) and not isinstance(value, bool) and value >= 0 

269 

270 

271def usage_entry_issue(entry: Any) -> str | None: 

272 """Why ``entry`` is not a well-formed delegate-usage entry, or ``None`` when it is.""" 

273 if not isinstance(entry, dict): 

274 return "entry must be an object" 

275 model = entry.get("model") 

276 if not isinstance(model, str) or not model.strip(): 

277 return "model must be a non-empty string" 

278 for name in ("prompt_tokens", "completion_tokens"): 

279 if not _is_count(entry.get(name)): 

280 return f"{name} must be a non-negative integer" 

281 return None 

282 

283 

284def with_delegate_usage( 

285 record: dict[str, Any], 

286 call_id: str, 

287 *, 

288 model: str, 

289 prompt_tokens: int, 

290 completion_tokens: int, 

291) -> dict[str, Any]: 

292 """A copy of ``record`` that also carries one delegate call's token counts. 

293 

294 Keyed by ``call_id``, so recording the same call again replaces its entry rather than 

295 adding it twice. The entry is validated here, not only on write, so a bad count fails 

296 before anything is built on it. 

297 """ 

298 entry = { 

299 "model": model, 

300 "prompt_tokens": prompt_tokens, 

301 "completion_tokens": completion_tokens, 

302 } 

303 issue = usage_entry_issue(entry) 

304 if issue is not None: 

305 raise ActivityError(f"{USAGE_FIELD}: {issue}") 

306 if not isinstance(call_id, str) or not call_id.strip(): 

307 raise ActivityError(f"{USAGE_FIELD}: call id must be a non-empty string") 

308 updated = dict(record) 

309 updated[USAGE_FIELD] = {**(record.get(USAGE_FIELD) or {}), call_id: entry} 

310 return updated 

311 

312 

313def carry_usage(record: dict[str, Any], existing: dict[str, Any] | None) -> dict[str, Any]: 

314 """``record`` with the delegate counts ``existing`` already held. 

315 

316 Every phase stamp rebuilds the record from :func:`build_activity_record`, which knows 

317 nothing of counts; without this, the next stamp after a delegate recorded would erase 

318 what it recorded (#1373). 

319 """ 

320 usage = (existing or {}).get(USAGE_FIELD) 

321 if not usage: 

322 return record 

323 return {**record, USAGE_FIELD: dict(usage)} 

324 

325 

326def encode_activity(record: dict[str, Any]) -> str: 

327 """Encode one activity record as stable JSON.""" 

328 validate_activity(record) 

329 return json.dumps(record, indent=2, sort_keys=True) + "\n" 

330 

331 

332def parse_activity(text: str) -> dict[str, Any]: 

333 """Parse and validate one activity record.""" 

334 try: 

335 record = json.loads(text) 

336 except json.JSONDecodeError as exc: 

337 raise ActivityError("invalid JSON") from exc 

338 validate_activity(record) 

339 return record 

340 

341 

342def read_activity(path: str | Path) -> dict[str, Any] | None: 

343 """Read one activity record; a missing file means no such run.""" 

344 activity_path = Path(path) 

345 if not activity_path.exists(): 

346 return None 

347 return parse_activity(activity_path.read_text(encoding="utf-8")) 

348 

349 

350def write_activity(path: str | Path, record: dict[str, Any]) -> None: 

351 """Write one validated activity record atomically.""" 

352 workspace.write_text_atomic(path, encode_activity(record)) 

353 

354 

355@contextlib.contextmanager 

356def record_lock( 

357 lock_root: str | Path, 

358 path: str | Path, 

359 *, 

360 owner: str, 

361 attempts: int | None = None, 

362 _sleep: Callable[[float], None] | None = None, 

363) -> Iterator[bool]: 

364 """Serialise the read-modify-write of one activity record; yields whether it is held. 

365 

366 Detached reviewers finish independently, and two recording at once would each read 

367 the record without the other's counts and the second write would drop the first's. 

368 The claim is :mod:`keel.lock`'s atomic ``mkdir``. Bounded: after ``attempts`` tries — 

369 or on an I/O error claiming it — this yields ``False`` and the caller decides whether 

370 to go ahead unlocked (a phase stamp must land) or skip (a count may not be guessed). 

371 """ 

372 # Resolved at call time, not bound as defaults, so the bound and the sleep can be 

373 # changed where they are defined rather than at every caller. 

374 attempts = LOCK_ATTEMPTS if attempts is None else attempts 

375 sleep = time.sleep if _sleep is None else _sleep 

376 resource = f"activity-{Path(path).stem}" 

377 held = False 

378 for attempt in range(attempts): 

379 try: 

380 held = lock.claim_resource(lock_root, resource, owner=owner).granted 

381 except OSError: 

382 break 

383 if held or attempt + 1 == attempts: 

384 break 

385 sleep(LOCK_POLL_S) 

386 try: 

387 yield held 

388 finally: 

389 if held: 

390 with contextlib.suppress(OSError): 

391 lock.release_resource(lock_root, resource, owner=owner, best_effort=True) 

392 

393 

394def record_delegate_usage( 

395 path: str | Path, 

396 lock_root: str | Path, 

397 *, 

398 call_id: str, 

399 model: str, 

400 prompt_tokens: int, 

401 completion_tokens: int, 

402 attempts: int | None = None, 

403 _sleep: Callable[[float], None] | None = None, 

404) -> str: 

405 """Add one delegate call's counts to the run's existing record, under the record lock. 

406 

407 Returns ``recorded``; ``no-record`` when the run has no record to add to (a count is 

408 never the thing that creates one — it has no phase); or ``busy`` when the lock could 

409 not be taken, in which case nothing is written rather than risking a lost update. 

410 Raises :class:`ActivityError` / ``OSError`` for a malformed record or a failed write. 

411 """ 

412 with record_lock(lock_root, path, owner=call_id, attempts=attempts, _sleep=_sleep) as held: 

413 if not held: 

414 return "busy" 

415 existing = read_activity(path) 

416 if existing is None: 

417 return "no-record" 

418 write_activity( 

419 path, 

420 with_delegate_usage( 

421 existing, 

422 call_id, 

423 model=model, 

424 prompt_tokens=prompt_tokens, 

425 completion_tokens=completion_tokens, 

426 ), 

427 ) 

428 return "recorded" 

429 

430 

431def remove_activity(path: str | Path) -> bool: 

432 """Delete an activity record. Returns ``True`` if a file was removed.""" 

433 activity_path = Path(path) 

434 if not activity_path.exists(): 

435 return False 

436 activity_path.unlink() 

437 return True 

438 

439 

440def read_all_activity(dir_path: str | Path) -> list[dict[str, Any]]: 

441 """Every readable activity record in ``dir_path``, sorted by run_id. 

442 

443 Fail-soft: an unreadable or malformed file is skipped, never raised — one bad 

444 record must not blank the board. The directory missing yields ``[]``. 

445 """ 

446 directory = Path(dir_path) 

447 if not directory.is_dir(): 

448 return [] 

449 records: list[dict[str, Any]] = [] 

450 for entry in sorted(directory.glob("*.json")): 

451 try: 

452 record = parse_activity(entry.read_text(encoding="utf-8")) 

453 except (ActivityError, OSError): 

454 continue 

455 records.append(record) 

456 return records