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
« 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.
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.
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.
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"""
19from __future__ import annotations
21import contextlib
22import json
23import re
24import time
25import unicodedata
26from collections.abc import Callable, Iterator
27from pathlib import Path
28from typing import Any
30from . import config as cfg
31from . import flows, lock, workspace
33ACTIVITY_SCHEMA_VERSION = "keel.activity.v1"
34RECORD_TYPE_ACTIVITY = "command_activity"
35DEFAULT_ACTIVITY_DIR = ".keel/activity"
36STATUSES = ("running", "done", "merged")
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")
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"
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
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
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._-]+")
72class ActivityError(ValueError):
73 """Raised when an activity record or path is malformed."""
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 }
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"
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
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
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"
132def _phase_ids(command: str) -> tuple[str, ...]:
133 return tuple(phase.id for phase in flows.flow_for(command))
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.
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``).
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.
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
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
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.
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
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}")
267def _is_count(value: Any) -> bool:
268 return isinstance(value, int) and not isinstance(value, bool) and value >= 0
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
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.
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
313def carry_usage(record: dict[str, Any], existing: dict[str, Any] | None) -> dict[str, Any]:
314 """``record`` with the delegate counts ``existing`` already held.
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)}
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"
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
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"))
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))
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.
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)
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.
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"
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
440def read_all_activity(dir_path: str | Path) -> list[dict[str, Any]]:
441 """Every readable activity record in ``dir_path``, sorted by run_id.
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