loopx 0.4.8__py3-none-any.whl

loopx/control_plane/todos/markdown.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .contract import TODO_STATUS_OPEN, todo_marker_for_status
+
+
+def render_todo_markdown(payload: dict[str, Any]) -> str:
+    if payload.get("command") == "list":
+        lines = [
+            "# LoopX Todo List",
+            "",
+            f"- ok: `{payload.get('ok')}`",
+            f"- read_only: `{payload.get('read_only')}`",
+            f"- goal_id: `{payload.get('goal_id')}`",
+            f"- role: `{payload.get('role')}`",
+            f"- status_filter: `{payload.get('status_filter')}`",
+            f"- source: `{payload.get('source')}`",
+            f"- todo_count: `{payload.get('todo_count')}`",
+            f"- state_file: `{payload.get('state_file')}`",
+        ]
+        if payload.get("agent_id_filter"):
+            lines.extend(
+                [
+                    f"- agent_id_filter: `{payload.get('agent_id_filter')}`",
+                    (
+                        "- unfiltered_todo_count: `"
+                        f"{payload.get('unfiltered_todo_count')}`"
+                    ),
+                    f"- filter_semantics: `{payload.get('filter_semantics')}`",
+                ]
+            )
+        projection = payload.get("todo_list_projection")
+        if isinstance(projection, dict):
+            lines.append(
+                f"- returned_todo_count: `{payload.get('returned_todo_count')}`"
+            )
+        state_event_projection = payload.get("state_event_projection")
+        if isinstance(state_event_projection, dict):
+            lines.extend(
+                [
+                    f"- event_log: `{state_event_projection.get('event_log')}`",
+                    (
+                        "- source_event_count: `"
+                        f"{state_event_projection.get('source_event_count')}`"
+                    ),
+                    f"- last_event_id: `{state_event_projection.get('last_event_id')}`",
+                ]
+            )
+        for key, heading in (
+            ("user_todos", "User Todo"),
+            ("agent_todos", "Agent Todo"),
+        ):
+            summary = payload.get(key)
+            if not isinstance(summary, dict):
+                continue
+            lines.extend(["", f"## {heading}", ""])
+            items = summary.get("items") or []
+            if not items:
+                lines.append("- none")
+                continue
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                marker = todo_marker_for_status(item.get("status") or TODO_STATUS_OPEN)
+                text = item.get("text") or item.get("title") or ""
+                metadata = []
+                for metadata_key in (
+                    "todo_id",
+                    "status",
+                    "task_class",
+                    "action_kind",
+                    "task_domain",
+                    "task_repository",
+                    "continuation_policy",
+                    "claimed_by",
+                    "bound_agent",
+                    "goal_bound",
+                    "blocks_agent",
+                    "global_gate",
+                    "excluded_agents",
+                    "target_key",
+                    "cadence",
+                    "next_due_at",
+                    "expires_at",
+                ):
+                    if item.get(metadata_key):
+                        metadata.append(f"{metadata_key}={item.get(metadata_key)}")
+                suffix = f" <!-- {' '.join(metadata)} -->" if metadata else ""
+                lines.append(f"- [{marker}] {text}{suffix}")
+        if payload.get("error"):
+            lines.append(f"- error: {payload.get('error')}")
+        if payload.get("operator_action"):
+            action = payload["operator_action"]
+            lines.append(f"- error_code: `{payload.get('error_code')}`")
+            lines.append(
+                "- operator_action: "
+                f"action={action.get('action')} "
+                f"holder_pid={action.get('holder_pid') or 'unknown'} "
+                f"retry_mode={action.get('retry_mode')}"
+            )
+        return "\n".join(lines)
+
+    lines = [
+        "# LoopX Todo",
+        "",
+        f"- ok: `{payload.get('ok')}`",
+        f"- dry_run: `{payload.get('dry_run')}`",
+        f"- goal_id: `{payload.get('goal_id')}`",
+        f"- role: `{payload.get('role')}`",
+        f"- section: `{payload.get('section')}`",
+        f"- state_file: `{payload.get('state_file')}`",
+    ]
+    if "moved_count" in payload:
+        lines.extend(
+            [
+                f"- changed: `{payload.get('changed')}`",
+                f"- archive_section: `{payload.get('archive_section')}`",
+                f"- active_done_before: `{payload.get('active_done_before')}`",
+                f"- active_done_after: `{payload.get('active_done_after')}`",
+                f"- max_active_done: `{payload.get('max_active_done')}`",
+                f"- moved_count: `{payload.get('moved_count')}`",
+            ]
+        )
+    else:
+        lines.extend(
+            [
+                f"- changed: `{payload.get('changed')}`",
+                f"- added: `{payload.get('added')}`",
+                f"- already_exists: `{payload.get('already_exists')}`",
+                f"- todo_id: `{payload.get('todo_id')}`",
+                f"- status: `{payload.get('status')}`",
+                f"- required_capabilities: `{payload.get('required_capabilities')}`",
+                f"- target_capabilities: `{payload.get('target_capabilities')}`",
+                f"- claimed_by: `{payload.get('claimed_by')}`",
+                f"- bound_agent: `{payload.get('bound_agent')}`",
+                f"- goal_bound: `{payload.get('goal_bound')}`",
+                f"- blocks_agent: `{payload.get('blocks_agent')}`",
+                f"- excluded_agents: `{payload.get('excluded_agents')}`",
+                f"- global_gate: `{payload.get('global_gate')}`",
+                f"- resume_when: `{payload.get('resume_when')}`",
+                f"- target_key: `{payload.get('target_key')}`",
+                f"- cadence: `{payload.get('cadence')}`",
+                f"- next_due_at: `{payload.get('next_due_at')}`",
+                f"- expires_at: `{payload.get('expires_at')}`",
+            ]
+        )
+    if payload.get("error"):
+        lines.append(f"- error: {payload.get('error')}")
+        if payload.get("operator_action"):
+            action = payload["operator_action"]
+            lines.append(f"- error_code: `{payload.get('error_code')}`")
+            lines.append(
+                "- operator_action: "
+                f"action={action.get('action')} "
+                f"holder_pid={action.get('holder_pid') or 'unknown'} "
+                f"retry_mode={action.get('retry_mode')}"
+            )
+    elif "todo" in payload:
+        marker = todo_marker_for_status(payload.get("status") or TODO_STATUS_OPEN)
+        lines.extend(["", "## Todo", "", f"- [{marker}] {payload.get('todo')}"])
+    correctness = payload.get("local_state_write_correctness")
+    if isinstance(correctness, dict):
+        intent = correctness.get("write_intent") if isinstance(correctness.get("write_intent"), dict) else {}
+        apply_result = (
+            correctness.get("apply_result")
+            if isinstance(correctness.get("apply_result"), dict)
+            else {}
+        )
+        lines.extend(
+            [
+                "",
+                "## Local State Write Correctness",
+                "",
+                f"- schema_version: `{correctness.get('schema_version')}`",
+                f"- write_id: `{intent.get('write_id')}`",
+                f"- write_class: `{intent.get('write_class')}`",
+                f"- idempotency_key: `{intent.get('idempotency_key')}`",
+                f"- status: `{apply_result.get('status')}`",
+            ]
+        )
+    validation = payload.get("validation")
+    if isinstance(validation, dict):
+        lines.extend(
+            [
+                "",
+                "## Validation",
+                "",
+                f"- validation_blocked_completion: `{payload.get('validation_blocked_completion')}`",
+                f"- command_label: `{validation.get('command_label')}`",
+                f"- passed: `{validation.get('passed')}`",
+                f"- status: `{validation.get('status')}`",
+                f"- exit_code: `{validation.get('exit_code')}`",
+            ]
+        )
+        summary = validation.get("summary")
+        if summary:
+            lines.append(f"- summary: {summary}")
+    return "\n".join(lines)

loopx/control_plane/todos/monitor_metadata.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..runtime.time import parse_timestamp
+from .contract import (
+    TODO_MONITOR_METADATA_FIELDS,
+    TODO_TASK_CLASS_MONITOR,
+    normalize_todo_watch_only,
+)
+
+
+MONITOR_CADENCE_PATTERN = re.compile(
+    r"^\s*(?P<count>[1-9][0-9]{0,4})\s*"
+    r"(?P<unit>s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days)\s*$",
+    re.IGNORECASE,
+)
+
+
+def normalize_monitor_metadata(metadata: dict[str, Any] | None) -> dict[str, str]:
+    normalized: dict[str, str] = {}
+    for key, value in (metadata or {}).items():
+        if key not in TODO_MONITOR_METADATA_FIELDS:
+            continue
+        candidate = str(value or "").strip()
+        if candidate:
+            normalized[key] = candidate
+    if "cadence" in normalized and not MONITOR_CADENCE_PATTERN.match(normalized["cadence"]):
+        raise ValueError("--cadence must look like 30m, 2h, or 1d")
+    if "next_due_at" in normalized and parse_timestamp(normalized["next_due_at"]) is None:
+        raise ValueError("--next-due-at must be an ISO timestamp")
+    if "expires_at" in normalized and parse_timestamp(normalized["expires_at"]) is None:
+        raise ValueError("--expires-at must be an ISO timestamp")
+    if "last_checked_at" in normalized and parse_timestamp(normalized["last_checked_at"]) is None:
+        raise ValueError("--last-checked-at must be an ISO timestamp")
+    if "consecutive_no_change" in normalized:
+        try:
+            int(normalized["consecutive_no_change"])
+        except ValueError as exc:
+            raise ValueError("--consecutive-no-change must be an integer") from exc
+    if "material_change" in normalized and normalized["material_change"] not in {"true", "false"}:
+        raise ValueError("--material-change metadata must be true or false")
+    if "watch_only" in normalized and normalize_todo_watch_only(
+        normalized["watch_only"]
+    ) is None:
+        raise ValueError("--watch-only metadata must be true or false")
+    return normalized
+
+
+def require_continuous_monitor_boundedness(
+    *,
+    task_class: str | None,
+    resume_when: str | None,
+    monitor_metadata: dict[str, Any] | None,
+) -> None:
+    if task_class != TODO_TASK_CLASS_MONITOR:
+        return
+    metadata = monitor_metadata or {}
+    if (
+        str(metadata.get("expires_at") or "").strip()
+        or str(resume_when or "").strip()
+        or normalize_todo_watch_only(metadata.get("watch_only")) is True
+    ):
+        return
+    raise ValueError(
+        "continuous_monitor requires one of: --expires-at, --resume-when, "
+        "or --watch-only"
+    )
+
+
+def require_monitor_metadata_scope(
+    *,
+    monitor_metadata: dict[str, Any] | None,
+    role: str,
+    task_class: str | None,
+) -> dict[str, str]:
+    normalized = normalize_monitor_metadata(monitor_metadata)
+    if not normalized:
+        return {}
+    schedule_fields = set(normalized) - {"target_key"}
+    if schedule_fields and (role != "agent" or task_class != "continuous_monitor"):
+        raise ValueError(
+            "monitor schedule metadata requires --role agent --task-class continuous_monitor"
+        )
+    if "target_key" in normalized and role != "agent":
+        raise ValueError("target_key requires --role agent")
+    return normalized

loopx/control_plane/todos/mutation_authority.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from ...agent_registry import (
+    load_goal_from_registry,
+    registered_agent_ids_from_registry,
+    require_registered_agent_id,
+)
+from .contract import (
+    TODO_TASK_CLASS_USER_GATE,
+    normalize_todo_blocks_agent,
+    normalize_todo_bound_agent,
+    normalize_todo_claimed_by,
+    normalize_todo_decision_outcome,
+    normalize_todo_decision_scope,
+    normalize_todo_excluded_agents,
+    normalize_todo_id,
+    normalize_todo_required_decision_scopes,
+)
+
+
+TODO_MUTATION_AUTHORITY_SCHEMA_VERSION = "todo_mutation_authority_v0"
+TODO_LIFECYCLE_AUTHORITY_ACTIONS = frozenset(
+    {"complete", "reassign", "supersede", "update"}
+)
+
+
+def normalize_todo_lifecycle_authority(
+    values: Any,
+    *,
+    registered_agents: list[str],
+) -> list[dict[str, Any]]:
+    if values is None:
+        return []
+    if not isinstance(values, list):
+        raise ValueError("coordination.todo_lifecycle_authority must be a list")
+    normalized: list[dict[str, Any]] = []
+    seen_agents: set[str] = set()
+    for raw in values:
+        if not isinstance(raw, Mapping):
+            raise ValueError("each todo lifecycle authority grant must be an object")
+        agent_id = normalize_todo_claimed_by(raw.get("agent_id"))
+        if not agent_id:
+            raise ValueError("todo lifecycle authority agent_id must be a public-safe token")
+        if agent_id not in registered_agents:
+            raise ValueError(
+                f"todo lifecycle authority agent_id={agent_id!r} must already be registered"
+            )
+        if agent_id in seen_agents:
+            raise ValueError(f"duplicate todo lifecycle authority grant for {agent_id!r}")
+        raw_actions = raw.get("actions")
+        if not isinstance(raw_actions, list) or not raw_actions:
+            raise ValueError("todo lifecycle authority actions must be a non-empty list")
+        actions: list[str] = []
+        for value in raw_actions:
+            action = str(value or "").strip().lower()
+            if action not in TODO_LIFECYCLE_AUTHORITY_ACTIONS:
+                raise ValueError(
+                    f"unsupported todo lifecycle authority action={action!r}; "
+                    "expected one of: "
+                    + ", ".join(sorted(TODO_LIFECYCLE_AUTHORITY_ACTIONS))
+                )
+            if action not in actions:
+                actions.append(action)
+        requires_reason = raw.get("requires_reason", True)
+        if not isinstance(requires_reason, bool):
+            raise ValueError("todo lifecycle authority requires_reason must be boolean")
+        normalized.append(
+            {
+                "agent_id": agent_id,
+                "actions": actions,
+                "requires_reason": requires_reason,
+            }
+        )
+        seen_agents.add(agent_id)
+    return normalized
+
+
+def todo_lifecycle_authority_for_goal(
+    goal: Mapping[str, Any] | None,
+    *,
+    agent_id: str,
+    registered_agents: list[str],
+) -> dict[str, Any] | None:
+    if not isinstance(goal, Mapping):
+        return None
+    coordination = goal.get("coordination")
+    if not isinstance(coordination, Mapping):
+        return None
+    grants = normalize_todo_lifecycle_authority(
+        coordination.get("todo_lifecycle_authority"),
+        registered_agents=registered_agents,
+    )
+    return next((grant for grant in grants if grant["agent_id"] == agent_id), None)
+
+
+def todo_update_authority_action(
+    *,
+    existing_role: str,
+    role: str | None,
+    claimed_by: str | None,
+    clear_claim: bool,
+    other_values: tuple[Any, ...],
+    monitor_metadata: Mapping[str, Any] | None,
+) -> str | None:
+    if claimed_by is None and not clear_claim:
+        return None
+    has_other_change = bool(
+        (role is not None and role != existing_role)
+        or any(value is not None and value is not False for value in other_values)
+        or any(value is not None for value in (monitor_metadata or {}).values())
+    )
+    return "update" if has_other_change else "reassign"
+
+
+def _scope_identity(scope: Mapping[str, Any] | None) -> tuple[str, str, str] | None:
+    normalized = normalize_todo_decision_scope(scope)
+    if not normalized:
+        return None
+    return (
+        str(normalized.get("kind") or ""),
+        str(normalized.get("granularity") or ""),
+        str(normalized.get("scope_key") or ""),
+    )
+
+
+def _exact_user_gate_override(
+    *,
+    command: str,
+    todo: Mapping[str, Any],
+    decision_outcome: str | None,
+    decision_target: Mapping[str, Any] | None,
+) -> dict[str, Any] | None:
+    if (
+        command != "complete"
+        or str(todo.get("role") or "") != "user"
+        or str(todo.get("task_class") or "") != TODO_TASK_CLASS_USER_GATE
+        or normalize_todo_decision_outcome(decision_outcome) is None
+    ):
+        return None
+    gate_scope = normalize_todo_decision_scope(todo.get("decision_scope"))
+    gate_scope_identity = _scope_identity(gate_scope)
+    target_todo_id = normalize_todo_id(todo.get("unblocks_todo_id"))
+    if (
+        not gate_scope
+        or not gate_scope_identity
+        or not target_todo_id
+        or not decision_target
+        or normalize_todo_id(decision_target.get("todo_id")) != target_todo_id
+    ):
+        return None
+    target_scope_identities = {
+        identity
+        for scope in normalize_todo_required_decision_scopes(
+            decision_target.get("required_decision_scopes")
+        )
+        if (identity := _scope_identity(scope)) is not None
+    }
+    if gate_scope_identity not in target_scope_identities:
+        return None
+    return {
+        "schema_version": TODO_MUTATION_AUTHORITY_SCHEMA_VERSION,
+        "command": command,
+        "mode": "exact_user_gate_decision_scope_override",
+        "actor_agent_id": None,
+        "todo_id": normalize_todo_id(todo.get("todo_id")),
+        "target_todo_id": target_todo_id,
+        "decision_outcome": normalize_todo_decision_outcome(decision_outcome),
+        "decision_scope": gate_scope,
+        "authority_source": "linked_user_gate_decision_scope",
+    }
+
+
+def authorize_todo_lifecycle_mutation(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    command: str,
+    todo: Mapping[str, Any],
+    actor_agent_id: str | None,
+    authority_action: str | None = None,
+    authority_reason: str | None = None,
+    requested_claimed_by: str | None = None,
+    decision_outcome: str | None = None,
+    decision_target: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Authorize one existing-todo lifecycle mutation before state changes."""
+
+    registered_agents = registered_agent_ids_from_registry(registry_path, goal_id)
+    normalized_actor = normalize_todo_claimed_by(actor_agent_id)
+    normalized_todo_id = normalize_todo_id(todo.get("todo_id"))
+    if len(registered_agents) <= 1:
+        if normalized_actor and registered_agents:
+            normalized_actor = require_registered_agent_id(
+                registry_path=registry_path,
+                goal_id=goal_id,
+                agent_id=normalized_actor,
+                field="agent_id",
+            )
+        return {
+            "schema_version": TODO_MUTATION_AUTHORITY_SCHEMA_VERSION,
+            "command": command,
+            "mode": "single_agent_compatibility",
+            "actor_agent_id": normalized_actor,
+            "todo_id": normalized_todo_id,
+            "registered_agent_count": len(registered_agents),
+        }
+
+    override = _exact_user_gate_override(
+        command=command,
+        todo=todo,
+        decision_outcome=decision_outcome,
+        decision_target=decision_target,
+    )
+    if override:
+        override["registered_agent_count"] = len(registered_agents)
+        return override
+
+    if not normalized_actor:
+        raise ValueError(
+            f"multi-agent todo {command} requires --agent-id to attribute the "
+            "lifecycle actor; only completion of an exactly linked user_gate "
+            "decision_scope may use the typed owner/controller override"
+        )
+    normalized_actor = require_registered_agent_id(
+        registry_path=registry_path,
+        goal_id=goal_id,
+        agent_id=normalized_actor,
+        field="agent_id",
+    )
+    excluded_agents = normalize_todo_excluded_agents(todo.get("excluded_agents"))
+    if normalized_actor in excluded_agents:
+        raise ValueError(
+            f"agent_id={normalized_actor!r} is excluded from mutating todo_id="
+            f"{normalized_todo_id!r}"
+        )
+    bound_agent = normalize_todo_bound_agent(todo.get("bound_agent"))
+    if not bound_agent and str(todo.get("role") or "") == "user":
+        bound_agent = normalize_todo_blocks_agent(todo.get("blocks_agent"))
+    if bound_agent and bound_agent != normalized_actor:
+        raise ValueError(
+            f"agent_id={normalized_actor!r} cannot {command} user todo_id="
+            f"{normalized_todo_id!r}; its response continuation is bound to "
+            f"bound_agent={bound_agent!r}"
+        )
+    claim_owner = normalize_todo_claimed_by(todo.get("claimed_by"))
+    if claim_owner and claim_owner != normalized_actor:
+        effective_action = str(authority_action or command).strip().lower()
+        grant = todo_lifecycle_authority_for_goal(
+            load_goal_from_registry(registry_path, goal_id),
+            agent_id=normalized_actor,
+            registered_agents=registered_agents,
+        )
+        if grant is None:
+            raise ValueError(
+                f"agent_id={normalized_actor!r} cannot {command} todo_id="
+                f"{normalized_todo_id!r}; it is claimed_by={claim_owner!r}"
+            )
+        if effective_action not in grant["actions"]:
+            raise ValueError(
+                "coordination.todo_lifecycle_authority for "
+                f"agent_id={normalized_actor!r} does not grant "
+                f"action={effective_action!r}"
+            )
+        normalized_reason = str(authority_reason or "").strip()
+        if grant["requires_reason"] and not normalized_reason:
+            raise ValueError(
+                f"delegated {effective_action} override requires --authority-reason"
+            )
+        return {
+            "schema_version": TODO_MUTATION_AUTHORITY_SCHEMA_VERSION,
+            "command": command,
+            "mode": "delegated_orchestration_override",
+            "actor_agent_id": normalized_actor,
+            "todo_id": normalized_todo_id,
+            "claim_owner": claim_owner,
+            "authority_action": effective_action,
+            "authority_source": "coordination.todo_lifecycle_authority",
+            "authority_reason": normalized_reason or None,
+            "requires_reason": grant["requires_reason"],
+            "registered_agent_count": len(registered_agents),
+        }
+    requested_owner = normalize_todo_claimed_by(requested_claimed_by)
+    if command == "claim" and requested_owner != normalized_actor:
+        raise ValueError(
+            "todo claim requires --claimed-by to match the lifecycle "
+            "--agent-id; use todo update for an owner-attributed transfer"
+        )
+    return {
+        "schema_version": TODO_MUTATION_AUTHORITY_SCHEMA_VERSION,
+        "command": command,
+        "mode": "registered_peer_actor",
+        "actor_agent_id": normalized_actor,
+        "todo_id": normalized_todo_id,
+        "claim_owner": claim_owner,
+        "registered_agent_count": len(registered_agents),
+    }