loopx 0.4.8__py3-none-any.whl

loopx/control_plane/runtime/agent_scoped_evidence_log.py

@@ -0,0 +1,435 @@
+from __future__ import annotations
+
+import shlex
+from collections.abc import Iterable, Mapping
+from datetime import datetime
+from typing import Any
+
+from .public_safety import public_safe_compact_text
+from .time import parse_timestamp
+
+
+SCHEMA_VERSION = "agent_scoped_evidence_log_v0"
+REQUIRED_READ_SCHEMA_VERSION = "loopx_agent_required_read_v0"
+READ_RECEIPT_SCHEMA_VERSION = "evidence_log_read_receipt_v0"
+MAX_PROJECTED_READ_RECEIPTS = 12
+
+def _compact_text(value: Any, *, limit: int = 220) -> str | None:
+    return public_safe_compact_text(value, limit=limit)
+
+
+def _normalize_event_kind(value: str) -> str:
+    return str(value or "").strip().lower().replace("-", "_")
+
+
+def _safe_rollout_event_row(event: Mapping[str, Any]) -> dict[str, Any]:
+    row: dict[str, Any] = {
+        "source": "rollout_event_log",
+        "recorded_at": event.get("recorded_at"),
+        "event_id": event.get("event_id"),
+        "event_kind": event.get("event_kind"),
+    }
+    for key in (
+        "status",
+        "agent_id",
+        "todo_id",
+        "classification",
+        "delivery_outcome",
+        "benchmark_id",
+        "case_id",
+        "run_id",
+    ):
+        safe = _compact_text(event.get(key), limit=180)
+        if safe:
+            row[key] = safe
+    summary = _compact_text(event.get("summary"), limit=360)
+    if summary:
+        row["summary"] = summary
+    for key in ("lane", "state_transition", "causality", "code_refs", "handoff"):
+        value = event.get(key)
+        if isinstance(value, dict):
+            row[key] = value
+    return row
+
+
+def _safe_run_history_row(run: Mapping[str, Any]) -> dict[str, Any]:
+    row: dict[str, Any] = {
+        "source": "run_history",
+        "recorded_at": run.get("generated_at"),
+        "run_ref": run.get("generated_at"),
+    }
+    for key in (
+        "goal_id",
+        "agent_id",
+        "agent_lane",
+        "classification",
+        "delivery_outcome",
+        "delivery_batch_scale",
+        "progress_scope",
+        "health_check",
+    ):
+        safe = _compact_text(run.get(key), limit=260 if key == "health_check" else 180)
+        if safe:
+            row[key] = safe
+    action = _compact_text(run.get("recommended_action"), limit=360)
+    if action:
+        row["recommended_action"] = action
+    return row
+
+
+def _event_matches(
+    event: Mapping[str, Any],
+    *,
+    agent_id: str,
+    todo_id: str | None,
+    event_kinds: set[str],
+    since: datetime | None,
+) -> bool:
+    if str(event.get("agent_id") or "") != agent_id:
+        return False
+    if todo_id and str(event.get("todo_id") or "") != todo_id:
+        return False
+    normalized_event_kind = _normalize_event_kind(str(event.get("event_kind") or ""))
+    if not event_kinds and normalized_event_kind == "evidence_log_read":
+        return False
+    if event_kinds and normalized_event_kind not in event_kinds:
+        return False
+    if since is not None:
+        recorded_at = parse_timestamp(event.get("recorded_at"))
+        if recorded_at is None or recorded_at < since:
+            return False
+    return True
+
+
+def evidence_log_read_receipt(
+    event: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    """Project one durable public-safe evidence-log read receipt."""
+
+    if _normalize_event_kind(str(event.get("event_kind") or "")) != (
+        "evidence_log_read"
+    ):
+        return None
+    status = str(event.get("status") or "").strip()
+    if status not in {"completed", "failed"}:
+        return None
+    goal_id = _compact_text(event.get("goal_id"), limit=180)
+    agent_id = _compact_text(event.get("agent_id"), limit=180)
+    event_id = _compact_text(event.get("event_id"), limit=180)
+    recorded_at = _compact_text(event.get("recorded_at"), limit=80)
+    details = event.get("details") if isinstance(event.get("details"), Mapping) else {}
+    command = _compact_text(details.get("command"), limit=500)
+    if not all((goal_id, agent_id, event_id, recorded_at, command)):
+        return None
+    read_window: dict[str, Any] = {
+        "mode": _compact_text(details.get("mode"), limit=40) or "thin",
+    }
+    for key in ("limit", "history_limit", "rollout_limit"):
+        value = details.get(key)
+        if isinstance(value, int) and value >= 0:
+            read_window[key] = value
+    since = _compact_text(details.get("since"), limit=80)
+    if since:
+        read_window["since"] = since
+    event_kinds = _compact_text(details.get("event_kinds"), limit=240)
+    if event_kinds:
+        read_window["event_kinds"] = [
+            item for item in event_kinds.split(",") if item
+        ]
+    receipt: dict[str, Any] = {
+        "schema_version": READ_RECEIPT_SCHEMA_VERSION,
+        "event_id": event_id,
+        "goal_id": goal_id,
+        "agent_id": agent_id,
+        "status": status,
+        "recorded_at": recorded_at,
+        "command": command,
+        "read_window": read_window,
+    }
+    if status == "failed":
+        error = _compact_text(details.get("error"), limit=240)
+        if error:
+            receipt["error"] = error
+    required_read_id = _compact_text(details.get("required_read_id"), limit=180)
+    if required_read_id:
+        receipt["required_read_id"] = required_read_id
+    todo_id = _compact_text(event.get("todo_id"), limit=180)
+    if todo_id:
+        receipt["todo_id"] = todo_id
+    return receipt
+
+
+def project_evidence_log_read_receipts(
+    events: Iterable[Mapping[str, Any]],
+    *,
+    limit: int = MAX_PROJECTED_READ_RECEIPTS,
+) -> list[dict[str, Any]]:
+    receipts = [
+        receipt
+        for event in events
+        if (receipt := evidence_log_read_receipt(event)) is not None
+    ]
+    return sorted(
+        receipts,
+        key=lambda item: str(item.get("recorded_at") or ""),
+        reverse=True,
+    )[: max(0, int(limit))]
+
+
+def _run_mentions_todo(run: Mapping[str, Any], todo_id: str) -> bool:
+    needles = (
+        run.get("todo_id"),
+        run.get("classification"),
+        run.get("recommended_action"),
+        run.get("health_check"),
+    )
+    return any(todo_id in str(value or "") for value in needles)
+
+
+def _run_matches(
+    run: Mapping[str, Any],
+    *,
+    goal_id: str,
+    agent_id: str,
+    todo_id: str | None,
+    since: datetime | None,
+) -> bool:
+    if str(run.get("goal_id") or goal_id) != goal_id:
+        return False
+    if str(run.get("agent_id") or "") != agent_id:
+        return False
+    if todo_id and not _run_mentions_todo(run, todo_id):
+        return False
+    if since is not None:
+        recorded_at = parse_timestamp(run.get("generated_at"))
+        if recorded_at is None or recorded_at < since:
+            return False
+    return True
+
+
+def _sort_key(row: Mapping[str, Any]) -> tuple[str, str]:
+    return (str(row.get("recorded_at") or ""), str(row.get("source") or ""))
+
+
+def goal_history_runs(
+    history_payload: Mapping[str, Any],
+    goal_id: str,
+) -> list[dict[str, Any]]:
+    """Select compact history rows for one goal from either supported history shape."""
+
+    goals = history_payload.get("goals")
+    for goal in goals if isinstance(goals, list) else []:
+        if not isinstance(goal, Mapping) or str(goal.get("id") or "") != goal_id:
+            continue
+        latest_runs = goal.get("latest_runs")
+        if not isinstance(latest_runs, list):
+            return []
+        return [dict(row) for row in latest_runs if isinstance(row, Mapping)]
+    runs = history_payload.get("runs")
+    return [
+        dict(row)
+        for row in (runs if isinstance(runs, list) else [])
+        if isinstance(row, Mapping) and str(row.get("goal_id") or "") == goal_id
+    ]
+
+
+def build_agent_scoped_evidence_log_command(
+    *,
+    goal_id: str,
+    agent_id: str,
+    todo_id: str | None = None,
+    cli_bin: str = "loopx",
+    output_format: str = "json",
+    limit: int = 24,
+    required_read_id: str | None = None,
+) -> str:
+    safe_goal_id = _compact_text(goal_id, limit=180)
+    safe_agent_id = _compact_text(agent_id, limit=180)
+    if not safe_goal_id:
+        raise ValueError("goal_id is required")
+    if not safe_agent_id:
+        raise ValueError("agent_id is required")
+    safe_todo_id = _compact_text(todo_id, limit=180) if todo_id else None
+    parts = [
+        cli_bin or "loopx",
+        "--format",
+        output_format or "json",
+        "evidence-log",
+        "--goal-id",
+        safe_goal_id,
+        "--agent-id",
+        safe_agent_id,
+        "--thin",
+        "--limit",
+        str(max(0, int(limit))),
+    ]
+    if safe_todo_id:
+        parts.extend(["--todo-id", safe_todo_id])
+    safe_required_read_id = (
+        _compact_text(required_read_id, limit=180) if required_read_id else None
+    )
+    if safe_required_read_id:
+        parts.extend(["--required-read-id", safe_required_read_id])
+    return " ".join(shlex.quote(part) for part in parts)
+
+
+def build_agent_scoped_required_read(
+    *,
+    goal_id: str,
+    agent_id: str | None,
+    todo_id: str | None = None,
+    reason: str = "read this agent's thin public-safe evidence ledger before replan",
+    cli_bin: str = "loopx",
+    limit: int = 24,
+    required_read_id: str | None = None,
+) -> dict[str, Any] | None:
+    safe_agent_id = _compact_text(agent_id, limit=180) if agent_id else None
+    if not safe_agent_id:
+        return None
+    command = build_agent_scoped_evidence_log_command(
+        goal_id=goal_id,
+        agent_id=safe_agent_id,
+        todo_id=todo_id,
+        cli_bin=cli_bin,
+        limit=limit,
+        required_read_id=required_read_id,
+    )
+    required_read = {
+        "schema_version": REQUIRED_READ_SCHEMA_VERSION,
+        "kind": "agent_scoped_evidence_log",
+        "goal_id": _compact_text(goal_id, limit=180),
+        "agent_id": safe_agent_id,
+        "todo_id": _compact_text(todo_id, limit=180) if todo_id else None,
+        "mode": "thin",
+        "command": command,
+        "reason": _compact_text(reason, limit=180),
+        "other_agent_policy": "frontier_only",
+    }
+    if required_read_id:
+        required_read["required_read_id"] = _compact_text(
+            required_read_id,
+            limit=180,
+        )
+    return required_read
+
+
+def _other_agent_frontier(
+    runs: Iterable[Mapping[str, Any]],
+    *,
+    goal_id: str,
+    agent_id: str,
+    limit: int,
+) -> dict[str, Any]:
+    latest_by_agent: dict[str, dict[str, Any]] = {}
+    for run in runs:
+        if str(run.get("goal_id") or goal_id) != goal_id:
+            continue
+        other_agent = _compact_text(run.get("agent_id"), limit=120)
+        if not other_agent or other_agent == agent_id:
+            continue
+        current = latest_by_agent.get(other_agent)
+        if current is None or str(run.get("generated_at") or "") > str(current.get("recorded_at") or ""):
+            row = _safe_run_history_row(run)
+            row["agent_id"] = other_agent
+            latest_by_agent[other_agent] = row
+    rows = sorted(latest_by_agent.values(), key=_sort_key, reverse=True)[: max(0, limit)]
+    return {
+        "schema_version": "other_agent_frontier_v0",
+        "policy": "goal_frontier_only",
+        "item_count": len(rows),
+        "items": rows,
+    }
+
+
+def build_agent_scoped_evidence_log(
+    *,
+    goal_id: str,
+    agent_id: str,
+    rollout_events: Iterable[Mapping[str, Any]],
+    history_runs: Iterable[Mapping[str, Any]],
+    todo_id: str | None = None,
+    since: str | None = None,
+    event_kinds: Iterable[str] | None = None,
+    limit: int = 24,
+) -> dict[str, Any]:
+    """Build a public-safe, agent-scoped ledger for replan and handoff reads."""
+
+    safe_goal_id = _compact_text(goal_id, limit=180)
+    safe_agent_id = _compact_text(agent_id, limit=180)
+    if not safe_goal_id:
+        raise ValueError("goal_id is required")
+    if not safe_agent_id:
+        raise ValueError("agent_id is required")
+    safe_todo_id = _compact_text(todo_id, limit=180) if todo_id else None
+    since_dt = parse_timestamp(since)
+    if since and since_dt is None:
+        raise ValueError(f"invalid --since timestamp: {since}")
+    normalized_kinds = {
+        _normalize_event_kind(kind)
+        for kind in event_kinds or []
+        if _normalize_event_kind(kind)
+    }
+    max_rows = max(0, int(limit))
+
+    event_rows = [
+        _safe_rollout_event_row(event)
+        for event in rollout_events
+        if _event_matches(
+            event,
+            agent_id=safe_agent_id,
+            todo_id=safe_todo_id,
+            event_kinds=normalized_kinds,
+            since=since_dt,
+        )
+    ]
+    run_list = [dict(run) for run in history_runs]
+    run_rows = [
+        _safe_run_history_row(run)
+        for run in run_list
+        if _run_matches(
+            run,
+            goal_id=safe_goal_id,
+            agent_id=safe_agent_id,
+            todo_id=safe_todo_id,
+            since=since_dt,
+        )
+    ]
+    matched_rows = [*event_rows, *run_rows]
+    ledger_rows = sorted(matched_rows, key=_sort_key, reverse=True)[:max_rows]
+
+    return {
+        "ok": True,
+        "schema_version": SCHEMA_VERSION,
+        "mode": "thin",
+        "goal_id": safe_goal_id,
+        "agent_id": safe_agent_id,
+        "todo_id": safe_todo_id,
+        "since": since if since_dt else None,
+        "event_kinds": sorted(normalized_kinds),
+        "limit": max_rows,
+        "matched_count": len(matched_rows),
+        "ledger_count": len(ledger_rows),
+        "truncated": len(matched_rows) > len(ledger_rows),
+        "source_refs": [
+            "rollout_event_log.public_safe_view",
+            "compact_run_history.public_refs",
+        ],
+        "rollout_event_count": len(event_rows),
+        "run_history_ref_count": len(run_rows),
+        "ledger": ledger_rows,
+        "other_agent_frontier": _other_agent_frontier(
+            run_list,
+            goal_id=safe_goal_id,
+            agent_id=safe_agent_id,
+            limit=3,
+        ),
+        "boundary": {
+            "raw_task_text_recorded": False,
+            "raw_logs_recorded": False,
+            "raw_trajectory_recorded": False,
+            "raw_session_transcript_recorded": False,
+            "credential_values_recorded": False,
+            "absolute_paths_recorded": False,
+            "other_agent_event_stream_expanded": False,
+        },
+    }

loopx/control_plane/runtime/decision_freshness.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Any, Callable
+
+from .time import now_utc
+
+DECISION_FRESHNESS_WINDOW_DAYS = 7
+DECISION_FRESHNESS_ITEM_LIMIT = 12
+DECISION_FRESHNESS_WARNING_ITEM_LIMIT = 3
+DECISION_FRESHNESS_PROXY_NOTE = (
+    "checkpointed decision freshness projection; rebase old decisions at the decision point before reuse"
+)
+DECISION_FRESHNESS_WARNING_MESSAGE = (
+    "decision-point rebase required before reusing sampled reward/gate state; "
+    "refresh registry, ACTIVE_GOAL_STATE, quota, policy, and run status first"
+)
+DECISION_FRESHNESS_CLASSIFICATION_PREFIXES = (
+    "human_reward",
+    "reward_overlay",
+)
+
+ParseTimestamp = Callable[[Any], Any]
+DecisionKinds = Callable[[dict[str, Any]], list[str]]
+EventClassForRun = Callable[[dict[str, Any]], str]
+BlankEventClassCounts = Callable[[], dict[str, int]]
+
+
+def decision_event_kinds(
+    run: dict[str, Any],
+    *,
+    decision_classifications: set[str],
+    classification_prefixes: tuple[str, ...] = DECISION_FRESHNESS_CLASSIFICATION_PREFIXES,
+) -> list[str]:
+    kinds: list[str] = []
+    if isinstance(run.get("human_reward"), dict):
+        kinds.append("human_reward")
+    if isinstance(run.get("operator_gate"), dict):
+        kinds.append("operator_gate")
+    if isinstance(run.get("operator_gate_resume_contract"), dict):
+        kinds.append("operator_gate_resume_contract")
+
+    classification = str(run.get("classification") or "").lower()
+    if not kinds and (
+        classification in decision_classifications
+        or classification.startswith(classification_prefixes)
+    ):
+        kinds.append("decision_classification")
+    return kinds
+
+
+def decision_freshness_reason(*, stale_by_age: bool, newer_event_count: int) -> str:
+    if stale_by_age and newer_event_count:
+        return "decision older than freshness window and newer sampled events exist; rebase at decision point"
+    if stale_by_age:
+        return "decision older than freshness window; rebase at decision point"
+    if newer_event_count:
+        return "newer sampled events exist after decision; rebase at decision point"
+    return "no newer sampled events inside freshness window"
+
+
+def build_decision_freshness_summary(
+    history: dict[str, Any],
+    *,
+    parse_timestamp: ParseTimestamp,
+    decision_event_kinds: DecisionKinds,
+    event_class_for_run: EventClassForRun,
+    blank_event_class_counts: BlankEventClassCounts,
+    window_days: int = DECISION_FRESHNESS_WINDOW_DAYS,
+    item_limit: int = DECISION_FRESHNESS_ITEM_LIMIT,
+    proxy_note: str = DECISION_FRESHNESS_PROXY_NOTE,
+) -> dict[str, Any]:
+    now = now_utc()
+    cutoff = now - timedelta(days=window_days)
+    runs = [run for run in history.get("runs") or [] if isinstance(run, dict)]
+    items: list[dict[str, Any]] = []
+    stale_count = 0
+    rebase_required_count = 0
+    fresh_count = 0
+
+    indexed_runs: list[tuple[dict[str, Any], datetime, str]] = []
+    for run in runs:
+        generated_at = parse_timestamp(run.get("generated_at"))
+        if generated_at is None:
+            continue
+        indexed_runs.append((run, generated_at, str(run.get("goal_id") or "unknown-goal")))
+
+    for run, decision_at, goal_id in indexed_runs:
+        for decision_kind in decision_event_kinds(run):
+            newer_class_counts = blank_event_class_counts()
+            newer_event_count = 0
+            for other_run, other_at, other_goal_id in indexed_runs:
+                if other_goal_id != goal_id or other_at <= decision_at or other_at < cutoff:
+                    continue
+                newer_event_count += 1
+                newer_class_counts[event_class_for_run(other_run)] += 1
+
+            stale_by_age = decision_at < cutoff
+            if stale_by_age:
+                stale_count += 1
+            requires_rebase = stale_by_age or newer_event_count > 0
+            if requires_rebase:
+                rebase_required_count += 1
+            else:
+                fresh_count += 1
+            if stale_by_age:
+                freshness_state = "stale_rebase_required"
+            elif newer_event_count:
+                freshness_state = "rebase_required"
+            else:
+                freshness_state = "fresh"
+
+            items.append(
+                {
+                    "goal_id": goal_id,
+                    "decision_kind": decision_kind,
+                    "decision_at": decision_at.isoformat(),
+                    "classification": run.get("classification"),
+                    "age_days": round(max(0.0, (now - decision_at).total_seconds() / 86400), 2),
+                    "stale_by_age": stale_by_age,
+                    "newer_event_count_7d": newer_event_count,
+                    "newer_event_classes_7d": newer_class_counts,
+                    "freshness_state": freshness_state,
+                    "requires_decision_point_rebase": requires_rebase,
+                    "reason": decision_freshness_reason(
+                        stale_by_age=stale_by_age,
+                        newer_event_count=newer_event_count,
+                    ),
+                }
+            )
+
+    items.sort(
+        key=lambda item: (
+            1 if item["requires_decision_point_rebase"] else 0,
+            item["age_days"],
+            item["newer_event_count_7d"],
+            item["decision_at"],
+        ),
+        reverse=True,
+    )
+    return {
+        "available": True,
+        "source": "run_history",
+        "generated_at": now.isoformat(),
+        "sample_run_count": len(runs),
+        "window_days": window_days,
+        "proxy_note": proxy_note,
+        "summary": {
+            "decision_count": len(items),
+            "stale_count": stale_count,
+            "rebase_required_count": rebase_required_count,
+            "fresh_count": fresh_count,
+        },
+        "items": items[:item_limit],
+    }
+
+
+def decision_freshness_warning(
+    status_payload: dict[str, Any],
+    *,
+    goal_id: str,
+    item_limit: int = DECISION_FRESHNESS_WARNING_ITEM_LIMIT,
+    message: str = DECISION_FRESHNESS_WARNING_MESSAGE,
+) -> dict[str, Any] | None:
+    freshness = (
+        status_payload.get("decision_freshness_summary")
+        if isinstance(status_payload.get("decision_freshness_summary"), dict)
+        else {}
+    )
+    raw_items = freshness.get("items") if isinstance(freshness.get("items"), list) else []
+    items: list[dict[str, Any]] = []
+    for item in raw_items:
+        if not isinstance(item, dict):
+            continue
+        if str(item.get("goal_id") or "") != goal_id:
+            continue
+        if item.get("requires_decision_point_rebase") is not True:
+            continue
+        items.append(
+            {
+                "goal_id": item.get("goal_id"),
+                "decision_kind": item.get("decision_kind"),
+                "freshness_state": item.get("freshness_state"),
+                "decision_at": item.get("decision_at"),
+                "classification": item.get("classification"),
+                "age_days": item.get("age_days"),
+                "newer_event_count_7d": item.get("newer_event_count_7d"),
+                "reason": item.get("reason"),
+            }
+        )
+
+    if not items:
+        return None
+    summary = freshness.get("summary") if isinstance(freshness.get("summary"), dict) else {}
+    return {
+        "source": freshness.get("source") or "run_history",
+        "window_days": freshness.get("window_days"),
+        "message": message,
+        "rebase_required_count": len(items),
+        "global_rebase_required_count": summary.get("rebase_required_count"),
+        "global_stale_count": summary.get("stale_count"),
+        "items": items[:item_limit],
+    }