loopx 0.4.8__py3-none-any.whl

loopx/control_plane/scheduler/monitor_poll_policy.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..goals.goal_vision_wait import exact_blocked_successor_wait_state
+from ..todos.contract import TODO_TASK_CLASS_MONITOR, normalize_todo_id
+from ..todos.projection import todo_item_task_class
+
+EXTERNAL_MONITOR_POLICIES = {
+    "material_transition_only",
+    "read_only_observation_then_no_spend_if_unchanged",
+}
+EXTERNAL_MONITOR_REASON_CODES = {
+    "external_monitor_context",
+    "external_evidence_poll_signal",
+}
+DUE_MONITOR_OBLIGATION = "attempt_due_monitor"
+
+
+def allows_no_spend_blocked_successor_wait_poll(decision: dict[str, Any]) -> bool:
+    return bool(
+        decision.get("effective_action") in {"agent_scope_wait", "monitor_quiet_skip"}
+        and decision.get("should_run") is False
+        and decision.get("requires_user_action") is not True
+        and exact_blocked_successor_wait_state(decision)
+    )
+
+
+def work_lane_reason_codes(work_lane_contract: dict[str, Any]) -> set[str]:
+    reason_codes = work_lane_contract.get("reason_codes")
+    if not isinstance(reason_codes, list):
+        return set()
+    return {str(value) for value in reason_codes if str(value or "").strip()}
+
+
+def explicit_external_evidence_observation(decision: dict[str, Any]) -> bool:
+    observation = (
+        decision.get("external_evidence_observation")
+        if isinstance(decision.get("external_evidence_observation"), dict)
+        else {}
+    )
+    return observation.get("required") is True and observation.get("must_attempt_observation") is True
+
+
+def allows_no_spend_external_monitor_poll(decision: dict[str, Any]) -> bool:
+    """Return true when should-run represents observation, not delivery completion."""
+
+    work_lane_contract = (
+        decision.get("work_lane_contract")
+        if isinstance(decision.get("work_lane_contract"), dict)
+        else {}
+    )
+    reason_codes = work_lane_reason_codes(work_lane_contract)
+    monitor_policy = str(work_lane_contract.get("monitor_policy") or "")
+    if decision.get("requires_user_action") is True:
+        return False
+    if decision.get("should_run") is not True:
+        return False
+    if explicit_external_evidence_observation(decision):
+        return True
+    if work_lane_contract.get("must_attempt_work") is not True:
+        return False
+    if monitor_policy not in EXTERNAL_MONITOR_POLICIES:
+        return False
+    if reason_codes.intersection(EXTERNAL_MONITOR_REASON_CODES):
+        return True
+    return bool(decision.get("external_evidence_observation"))
+
+
+def quota_decision_due_monitor_item(decision: dict[str, Any]) -> dict[str, Any]:
+    item = (
+        decision.get("agent_lane_next_action")
+        if isinstance(decision.get("agent_lane_next_action"), dict)
+        else {}
+    )
+    if todo_item_task_class(item) != TODO_TASK_CLASS_MONITOR:
+        item = {}
+    if item:
+        return item
+    contract = (
+        decision.get("work_lane_contract")
+        if isinstance(decision.get("work_lane_contract"), dict)
+        else {}
+    )
+    selected_todo_id = normalize_todo_id(contract.get("selected_todo_id"))
+    due_items = (
+        contract.get("monitor_due_items")
+        if isinstance(contract.get("monitor_due_items"), list)
+        else []
+    )
+    for due_item in due_items:
+        if not isinstance(due_item, dict):
+            continue
+        if selected_todo_id and normalize_todo_id(due_item.get("todo_id")) != selected_todo_id:
+            continue
+        if todo_item_task_class(due_item) == TODO_TASK_CLASS_MONITOR:
+            return due_item
+    return item
+
+
+def _requested_auxiliary_due_monitor_item(
+    decision: dict[str, Any],
+    *,
+    todo_id: str | None,
+    target_key: str | None,
+) -> dict[str, Any]:
+    if not todo_id and not target_key:
+        return {}
+    summary = (
+        decision.get("agent_todo_summary")
+        if isinstance(decision.get("agent_todo_summary"), dict)
+        else {}
+    )
+    due_items = (
+        summary.get("monitor_due_items")
+        if isinstance(summary.get("monitor_due_items"), list)
+        else []
+    )
+    for item in due_items:
+        if not isinstance(item, dict) or todo_item_task_class(item) != TODO_TASK_CLASS_MONITOR:
+            continue
+        if todo_id and normalize_todo_id(item.get("todo_id")) != normalize_todo_id(todo_id):
+            continue
+        if target_key and str(item.get("target_key") or "").strip() != str(target_key).strip():
+            continue
+        return item
+    return {}
+
+
+def allows_due_monitor_poll(
+    decision: dict[str, Any],
+    *,
+    todo_id: str | None = None,
+    target_key: str | None = None,
+) -> bool:
+    contract = (
+        decision.get("work_lane_contract")
+        if isinstance(decision.get("work_lane_contract"), dict)
+        else {}
+    )
+    if contract.get("must_attempt_work") is not True:
+        return False
+    if contract.get("obligation") != DUE_MONITOR_OBLIGATION:
+        return bool(
+            "due_monitor_context" in work_lane_reason_codes(contract)
+            and _requested_auxiliary_due_monitor_item(
+                decision,
+                todo_id=todo_id,
+                target_key=target_key,
+            )
+        )
+    item = quota_decision_due_monitor_item(decision)
+    if not item:
+        return False
+    if todo_id and normalize_todo_id(item.get("todo_id")) != normalize_todo_id(todo_id):
+        return False
+    if target_key:
+        item_target_key = str(item.get("target_key") or "").strip()
+        if item_target_key != str(target_key).strip():
+            return False
+    return True

loopx/control_plane/scheduler/monitor_poll_writeback.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from ..todos.contract import (
+    TODO_TASK_CLASS_ADVANCEMENT,
+    TODO_TASK_CLASS_MONITOR,
+    TODO_TASK_CLASS_USER_GATE,
+    normalize_required_capabilities,
+    normalize_todo_action_kind,
+    normalize_todo_continuation_policy,
+    normalize_todo_id,
+    normalize_todo_task_repository,
+    resolve_next_user_task_class,
+    resolve_todo_continuation_policy,
+)
+from .monitor_todo import (
+    monitor_next_due_at,
+    monitor_todo_task_class,
+    parse_monitor_counter,
+)
+
+
+def require_monitor_successor_route(
+    *,
+    next_agent_todo: str | None,
+    next_action_kind: str | None,
+    next_task_repository: str | None,
+    next_required_capabilities: list[str] | None,
+    next_continuation_policy: str | None,
+    next_target_key: str | None,
+) -> None:
+    route_fields = {
+        "--next-action-kind": next_action_kind,
+        "--next-task-repository": next_task_repository,
+        "--next-continuation-policy": next_continuation_policy,
+        "--next-target-key": next_target_key,
+    }
+    if not next_agent_todo:
+        if any(route_fields.values()) or next_required_capabilities:
+            raise ValueError("monitor successor routing options require --next-agent-todo")
+        return
+    if not str(next_action_kind or "").strip():
+        raise ValueError(
+            "`quota monitor-poll --next-agent-todo` requires explicit successor "
+            "action semantics via --next-action-kind"
+        )
+
+
+def _derived_monitor_successor_target_key(*, todo_id: str, result_hash: str) -> str:
+    digest = hashlib.sha256(result_hash.encode("utf-8")).hexdigest()[:16]
+    return f"monitor-successor:{todo_id}:{digest}"
+
+
+def _resolve_monitor_successor_route(
+    *,
+    next_agent_todo: str | None,
+    next_action_kind: str | None,
+    next_task_repository: str | None,
+    next_required_capabilities: list[str] | None,
+    next_continuation_policy: str | None,
+    next_target_key: str | None,
+    source_task_repository: str | None,
+    todo_id: str,
+    result_hash: str,
+) -> dict[str, Any]:
+    if not next_agent_todo:
+        return {}
+    action_kind = normalize_todo_action_kind(next_action_kind)
+    if not action_kind:
+        raise ValueError(
+            "--next-action-kind must be a public-safe token: lowercase letters, "
+            "digits, '_' or '-'"
+        )
+    task_repository = normalize_todo_task_repository(next_task_repository)
+    if next_task_repository and not task_repository:
+        raise ValueError(
+            "--next-task-repository must be a credential-free Git remote or "
+            "canonical git:<host>/<path> identity"
+        )
+    if source_task_repository and not task_repository:
+        raise ValueError(
+            "repository-bound monitor successors require explicit "
+            "--next-task-repository so same-repository and cross-repository "
+            "routing cannot be confused"
+        )
+    required_capabilities = normalize_required_capabilities(
+        next_required_capabilities
+    )
+    if next_required_capabilities and not required_capabilities:
+        raise ValueError(
+            "--next-required-capability must contain public-safe capability tokens"
+        )
+    if next_continuation_policy and not normalize_todo_continuation_policy(
+        next_continuation_policy
+    ):
+        raise ValueError(
+            "--next-continuation-policy must be a supported todo continuation policy"
+        )
+    return {
+        "action_kind": action_kind,
+        "task_repository": task_repository,
+        "required_capabilities": required_capabilities,
+        "continuation_policy": resolve_todo_continuation_policy(
+            next_continuation_policy
+        ).value,
+        "target_key": str(next_target_key or "").strip()
+        or _derived_monitor_successor_target_key(
+            todo_id=todo_id,
+            result_hash=result_hash,
+        ),
+    }
+
+
+def resolve_monitor_todo_item(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    todo_id: str | None = None,
+    target_key: str | None = None,
+) -> dict[str, Any]:
+    from ...todos import list_goal_todos
+
+    normalized_todo_id = normalize_todo_id(todo_id) if todo_id else None
+    safe_target_key = str(target_key or "").strip()
+    if not normalized_todo_id and not safe_target_key:
+        raise ValueError("monitor todo writeback requires --todo-id or --target-key")
+    payload = list_goal_todos(registry_path=registry_path, goal_id=goal_id, role="agent")
+    items = payload.get("todos") if isinstance(payload.get("todos"), list) else []
+    if normalized_todo_id:
+        matches = [
+            item
+            for item in items
+            if isinstance(item, dict)
+            and normalize_todo_id(item.get("todo_id")) == normalized_todo_id
+        ]
+        if not matches:
+            raise ValueError(f"monitor todo_id {normalized_todo_id!r} was not found")
+        if len(matches) > 1:
+            raise ValueError(f"monitor todo_id {normalized_todo_id!r} matched multiple todos")
+        item = matches[0]
+        item_target_key = str(item.get("target_key") or "").strip()
+        if safe_target_key and item_target_key and safe_target_key != item_target_key:
+            raise ValueError(
+                f"monitor todo_id {normalized_todo_id!r} resolves target_key "
+                f"{item_target_key!r}, not {safe_target_key!r}"
+            )
+        if monitor_todo_task_class(item) != TODO_TASK_CLASS_MONITOR:
+            raise ValueError("monitor-poll todo writeback target must be task_class=continuous_monitor")
+        return item
+
+    matches: list[dict[str, Any]] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        if safe_target_key and str(item.get("target_key") or "").strip() == safe_target_key:
+            matches.append(item)
+    if not matches:
+        target = normalized_todo_id or safe_target_key
+        raise ValueError(f"monitor todo target {target!r} was not found")
+    if len(matches) > 1:
+        raise ValueError(f"monitor target_key {safe_target_key!r} matched multiple todos; pass --todo-id")
+    item = matches[0]
+    if monitor_todo_task_class(item) != TODO_TASK_CLASS_MONITOR:
+        raise ValueError("monitor-poll todo writeback target must be task_class=continuous_monitor")
+    return item
+
+
+def write_monitor_poll_todo_state(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    generated_at: str,
+    execute: bool,
+    todo_id: str | None = None,
+    target_key: str | None = None,
+    result_hash: str | None = None,
+    material_change: bool = False,
+    cadence: str | None = None,
+    next_due_at: str | None = None,
+    reason_summary: str | None = None,
+    next_agent_todo: str | None = None,
+    next_action_kind: str | None = None,
+    next_task_repository: str | None = None,
+    next_required_capabilities: list[str] | None = None,
+    next_continuation_policy: str | None = None,
+    next_target_key: str | None = None,
+    next_user_todo: str | None = None,
+    next_user_task_class: str | None = None,
+    next_claimed_by: str | None = None,
+    agent_id: str | None = None,
+) -> dict[str, Any] | None:
+    from ...todos import add_goal_todo, update_goal_todo
+
+    if not todo_id and not target_key:
+        return None
+    safe_result_hash = str(result_hash or "").strip()
+    if not safe_result_hash:
+        raise ValueError("monitor todo writeback requires --result-hash")
+    effective_next_user_task_class = resolve_next_user_task_class(
+        next_user_todo,
+        next_user_task_class,
+    )
+    require_monitor_successor_route(
+        next_agent_todo=next_agent_todo,
+        next_action_kind=next_action_kind,
+        next_task_repository=next_task_repository,
+        next_required_capabilities=next_required_capabilities,
+        next_continuation_policy=next_continuation_policy,
+        next_target_key=next_target_key,
+    )
+    item = resolve_monitor_todo_item(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        todo_id=todo_id,
+        target_key=target_key,
+    )
+    resolved_todo_id = normalize_todo_id(item.get("todo_id"))
+    if not resolved_todo_id:
+        raise ValueError("resolved monitor todo has no stable todo_id")
+    successor_route = _resolve_monitor_successor_route(
+        next_agent_todo=next_agent_todo,
+        next_action_kind=next_action_kind,
+        next_task_repository=next_task_repository,
+        next_required_capabilities=next_required_capabilities,
+        next_continuation_policy=next_continuation_policy,
+        next_target_key=next_target_key,
+        source_task_repository=str(item.get("task_repository") or "").strip()
+        or None,
+        todo_id=resolved_todo_id,
+        result_hash=safe_result_hash,
+    )
+    safe_target_key = str(target_key or item.get("target_key") or "").strip()
+    effective_cadence = str(cadence or item.get("cadence") or "").strip()
+    effective_next_due_at = monitor_next_due_at(
+        generated_at=generated_at,
+        cadence=effective_cadence,
+        explicit_next_due_at=next_due_at,
+    )
+    if not material_change and not effective_next_due_at:
+        raise ValueError(
+            "unchanged monitor todo writeback requires --next-due-at or a parseable cadence such as 30m/2h/1d"
+        )
+    previous_hash = str(item.get("result_hash") or "").strip()
+    previous_no_change = parse_monitor_counter(item.get("consecutive_no_change"))
+    consecutive_no_change = (
+        0
+        if material_change or (previous_hash and previous_hash != safe_result_hash)
+        else previous_no_change + 1
+    )
+    monitor_metadata: dict[str, Any] = {
+        "last_checked_at": generated_at,
+        "result_hash": safe_result_hash,
+        "consecutive_no_change": str(consecutive_no_change),
+        "material_change": "true" if material_change else "false",
+    }
+    if safe_target_key:
+        monitor_metadata["target_key"] = safe_target_key
+    if effective_cadence:
+        monitor_metadata["cadence"] = effective_cadence
+    if effective_next_due_at:
+        monitor_metadata["next_due_at"] = effective_next_due_at
+    update_result = update_goal_todo(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        todo_id=resolved_todo_id,
+        role="agent",
+        reason=reason_summary,
+        monitor_metadata=monitor_metadata,
+        enforce_monitor_boundedness=False,
+        agent_id=agent_id,
+        dry_run=not execute,
+    )
+    next_results: list[dict[str, Any]] = []
+    if material_change and next_agent_todo:
+        next_results.append(
+            add_goal_todo(
+                registry_path=registry_path,
+                goal_id=goal_id,
+                role="agent",
+                text=next_agent_todo,
+                task_class=TODO_TASK_CLASS_ADVANCEMENT,
+                action_kind=successor_route["action_kind"],
+                task_repository=successor_route["task_repository"],
+                continuation_policy=successor_route["continuation_policy"],
+                required_capabilities=successor_route["required_capabilities"],
+                claimed_by=next_claimed_by,
+                unblocks_todo_id=resolved_todo_id,
+                monitor_metadata={"target_key": successor_route["target_key"]},
+                dry_run=not execute,
+            )
+        )
+    if material_change and next_user_todo:
+        next_results.append(
+            add_goal_todo(
+                registry_path=registry_path,
+                goal_id=goal_id,
+                role="user",
+                text=next_user_todo,
+                task_class=effective_next_user_task_class,
+                action_kind=(
+                    "gate"
+                    if effective_next_user_task_class == TODO_TASK_CLASS_USER_GATE
+                    else None
+                ),
+                agent_id=agent_id,
+                unblocks_todo_id=(
+                    resolved_todo_id
+                    if effective_next_user_task_class == TODO_TASK_CLASS_USER_GATE
+                    else None
+                ),
+                dry_run=not execute,
+            )
+        )
+    successor_receipts = [
+        {
+            key: result.get(key)
+            for key in (
+                "todo_id",
+                "role",
+                "task_class",
+                "action_kind",
+                "task_repository",
+                "continuation_policy",
+                "required_capabilities",
+                "claimed_by",
+                "unblocks_todo_id",
+                "target_key",
+            )
+            if result.get(key) not in (None, "", [])
+        }
+        for result in next_results
+    ]
+    return {
+        "schema_version": "monitor_poll_todo_writeback_v0",
+        "dry_run": not execute,
+        "goal_id": goal_id,
+        "todo_id": resolved_todo_id,
+        "target_key": safe_target_key or None,
+        "result_hash": safe_result_hash,
+        "material_change": material_change,
+        "consecutive_no_change": consecutive_no_change,
+        "last_checked_at": generated_at,
+        "next_due_at": effective_next_due_at,
+        "cadence": effective_cadence or None,
+        "todo_update": update_result,
+        "next_todos": next_results,
+        "successor_receipts": successor_receipts,
+    }

loopx/control_plane/scheduler/monitor_target.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any
+
+from ..goals.goal_vision_wait import exact_blocked_successor_frontier_identity
+from ..todos.contract import normalize_todo_claimed_by
+
+QUOTA_MONITOR_TARGET_SCHEMA_VERSION = "quota_monitor_target_v0"
+
+
+def monitor_target_summary(value: Any, *, limit: int = 160) -> str:
+    text = re.sub(r"\s+", " ", str(value or "").strip())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3].rstrip() + "..."
+
+
+def monitor_target_agent_id(decision: dict[str, Any]) -> str | None:
+    agent_identity = (
+        decision.get("agent_identity")
+        if isinstance(decision.get("agent_identity"), dict)
+        else {}
+    )
+    return normalize_todo_claimed_by(agent_identity.get("agent_id"))
+
+
+def build_quota_monitor_target(
+    decision: dict[str, Any],
+    *,
+    monitor_mode: str,
+) -> dict[str, Any]:
+    action_summary = monitor_target_summary(
+        decision.get("recommended_action") or decision.get("reason") or "",
+        limit=160,
+    )
+    agent_id = monitor_target_agent_id(decision) or ""
+    frontier_identity = exact_blocked_successor_frontier_identity(decision)
+    parts = {
+        "goal_id": str(decision.get("goal_id") or ""),
+        "agent_id": agent_id,
+        "monitor_mode": str(monitor_mode or ""),
+        "effective_action": str(decision.get("effective_action") or ""),
+        "frontier_identity": frontier_identity or "",
+    }
+    if not frontier_identity:
+        parts["action_summary"] = action_summary
+    target_id = hashlib.sha256(
+        json.dumps(parts, ensure_ascii=True, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+    target: dict[str, Any] = {
+        "schema_version": QUOTA_MONITOR_TARGET_SCHEMA_VERSION,
+        "target_id": target_id,
+        "monitor_mode": parts["monitor_mode"],
+        "effective_action": parts["effective_action"],
+        "action_summary": action_summary,
+    }
+    if agent_id:
+        target["agent_id"] = agent_id
+    if frontier_identity:
+        target["frontier_identity"] = frontier_identity
+    return target