loopx 0.4.8__py3-none-any.whl

loopx/control_plane/todos/unblock_resume.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .active_state_editing import section_bounds, todo_blocks
+from .contract import (
+    TODO_STATUS_OPEN,
+    TODO_STATUS_BLOCKED,
+    TODO_TASK_CLASS_USER_GATE,
+    normalize_todo_decision_outcome,
+    normalize_todo_decision_scope,
+    normalize_todo_decision_scope_outcomes,
+    normalize_todo_id,
+    normalize_todo_required_decision_scopes,
+    normalize_todo_status,
+    require_todo_decision_outcome,
+    todo_done_for_status,
+)
+from .decision_scope import decision_scope_covers
+
+
+TODO_UNBLOCK_RESUME_SCHEMA_VERSION = "todo_unblock_resume_v0"
+TODO_DECISION_SCOPE_RESOLUTION_SCHEMA_VERSION = (
+    "todo_decision_scope_resolution_v0"
+)
+
+
+def require_completion_decision_outcome(
+    completion_todo: dict[str, Any] | None,
+    decision_outcome: str | None,
+    *,
+    materialized: bool,
+) -> str | None:
+    is_user_gate = (
+        str((completion_todo or {}).get("role") or "") == "user"
+        and str((completion_todo or {}).get("task_class") or "")
+        == TODO_TASK_CLASS_USER_GATE
+    )
+    if not is_user_gate:
+        if decision_outcome is not None:
+            raise ValueError(
+                "decision_outcome is only valid when completing a user_gate"
+            )
+        return None
+    if decision_outcome is None:
+        raise ValueError(
+            "user_gate completion requires decision_outcome=approve, reject, or cancel"
+        )
+    if not materialized:
+        raise ValueError(
+            "event-projected user_gate completion must first materialize the gate "
+            "in active state so its decision outcome is durable"
+        )
+    return require_todo_decision_outcome(decision_outcome)
+
+
+def _status(todo: dict[str, Any]) -> str:
+    return normalize_todo_status(todo.get("status")) or TODO_STATUS_OPEN
+
+
+def _find_todo(
+    lines: list[str],
+    *,
+    role: str,
+    todo_id: str,
+) -> dict[str, Any] | None:
+    bounds = section_bounds(lines, role)
+    if not bounds:
+        return None
+    start, end, section = bounds
+    return next(
+        (
+            todo
+            for todo in todo_blocks(
+                lines,
+                start,
+                end,
+                role=role,
+                source_section=section,
+            )
+            if normalize_todo_id(todo.get("todo_id")) == todo_id
+        ),
+        None,
+    )
+
+
+def plan_completed_user_unblock_resume(
+    lines: list[str],
+    *,
+    source_todo_id: str,
+    target_todo_id: str,
+) -> dict[str, Any]:
+    """Plan a safe resume for one explicitly linked blocked advancement todo."""
+
+    receipt: dict[str, Any] = {
+        "schema_version": TODO_UNBLOCK_RESUME_SCHEMA_VERSION,
+        "source_todo_id": source_todo_id,
+        "target_todo_id": target_todo_id,
+        "changed": False,
+    }
+    target = _find_todo(lines, role="agent", todo_id=target_todo_id)
+    if not target:
+        return {**receipt, "state": "target_not_found"}
+    target_status = _status(target)
+    receipt["previous_status"] = target_status
+    receipt["status"] = target_status
+    if target_status != "blocked":
+        return {**receipt, "state": "target_not_blocked"}
+    if str(target.get("task_class") or "") == "blocker":
+        return {**receipt, "state": "explicit_blocker_repair_required"}
+
+    user_bounds = section_bounds(lines, "user")
+    remaining_ids: list[str] = []
+    if user_bounds:
+        start, end, section = user_bounds
+        for candidate in todo_blocks(
+            lines,
+            start,
+            end,
+            role="user",
+            source_section=section,
+        ):
+            candidate_id = normalize_todo_id(candidate.get("todo_id"))
+            if (
+                candidate_id
+                and candidate_id != source_todo_id
+                and not todo_done_for_status(_status(candidate))
+                and normalize_todo_id(candidate.get("unblocks_todo_id")) == target_todo_id
+            ):
+                remaining_ids.append(candidate_id)
+    if remaining_ids:
+        return {
+            **receipt,
+            "state": "other_user_blockers_active",
+            "remaining_user_blocker_todo_ids": sorted(set(remaining_ids)),
+        }
+    return {**receipt, "state": "resume_ready"}
+
+
+def plan_completed_user_gate_decision_scope_resolution(
+    lines: list[str],
+    *,
+    source_todo_id: str,
+    target_todo_id: str,
+    decision_scope: Any,
+) -> dict[str, Any] | None:
+    """Plan consumption of only the target requirements covered by one approval."""
+
+    normalized_scope = normalize_todo_decision_scope(decision_scope)
+    if not normalized_scope:
+        return None
+    target = _find_todo(lines, role="agent", todo_id=target_todo_id)
+    if not target:
+        return None
+    required_scopes = normalize_todo_required_decision_scopes(
+        target.get("required_decision_scopes")
+    )
+    resolved_scopes = [
+        scope
+        for scope in required_scopes
+        if decision_scope_covers(normalized_scope, scope)
+    ]
+    if not resolved_scopes:
+        return None
+    remaining_scopes = [
+        scope
+        for scope in required_scopes
+        if not decision_scope_covers(normalized_scope, scope)
+    ]
+    return {
+        "schema_version": TODO_DECISION_SCOPE_RESOLUTION_SCHEMA_VERSION,
+        "state": "resolution_ready",
+        "source_todo_id": source_todo_id,
+        "target_todo_id": target_todo_id,
+        "decision_scope": normalized_scope,
+        "resolved_required_decision_scopes": resolved_scopes,
+        "remaining_required_decision_scopes": remaining_scopes,
+        "changed": False,
+    }
+
+
+def apply_completed_user_todo_lifecycle(
+    lines: list[str],
+    *,
+    completion_todo: dict[str, Any] | None,
+    update_result: dict[str, Any],
+    fallback_todo_id: str,
+    decision_outcome: str | None,
+    updated_at: str,
+    apply_update: Callable[..., dict[str, Any]],
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Apply exact unblock and decision-scope effects after user completion."""
+
+    completion_role = str((completion_todo or {}).get("role") or "")
+    completion_task_class = str((completion_todo or {}).get("task_class") or "")
+    normalized_outcome = normalize_todo_decision_outcome(decision_outcome)
+    source_todo_id = str(update_result.get("todo_id") or fallback_todo_id)
+    target_todo_id = normalize_todo_id(update_result.get("unblocks_todo_id"))
+    decision_scope_resolution = None
+    if (
+        completion_role == "user"
+        and completion_task_class == TODO_TASK_CLASS_USER_GATE
+        and normalized_outcome == "approve"
+        and target_todo_id
+    ):
+        decision_scope_resolution = plan_completed_user_gate_decision_scope_resolution(
+            lines,
+            source_todo_id=source_todo_id,
+            target_todo_id=target_todo_id,
+            decision_scope=(completion_todo or {}).get("decision_scope"),
+        )
+        if decision_scope_resolution:
+            target = _find_todo(lines, role="agent", todo_id=target_todo_id)
+            remaining_outcomes = [
+                item
+                for item in normalize_todo_decision_scope_outcomes(
+                    (target or {}).get("decision_scope_outcomes")
+                )
+                if not decision_scope_covers(
+                    (completion_todo or {}).get("decision_scope"),
+                    item.get("decision_scope"),
+                )
+            ]
+            resolved_target = apply_update(
+                lines,
+                todo_id=target_todo_id,
+                role="agent",
+                required_decision_scopes=decision_scope_resolution[
+                    "remaining_required_decision_scopes"
+                ],
+                decision_scope_outcomes=remaining_outcomes,
+                updated_at=updated_at,
+            )
+            decision_scope_resolution.update(
+                state="resolved",
+                changed=bool(resolved_target.get("changed")),
+                target_status=resolved_target.get("status"),
+            )
+
+    unblock_resume = None
+    if (
+        completion_role == "user"
+        and completion_task_class == TODO_TASK_CLASS_USER_GATE
+        and normalized_outcome in {"reject", "cancel"}
+        and target_todo_id
+    ):
+        target = _find_todo(lines, role="agent", todo_id=target_todo_id)
+        decision_scope = normalize_todo_decision_scope(
+            (completion_todo or {}).get("decision_scope")
+        )
+        target_outcomes = normalize_todo_decision_scope_outcomes(
+            (target or {}).get("decision_scope_outcomes")
+        )
+        if target and decision_scope:
+            target_outcomes.append(
+                {
+                    "outcome": normalized_outcome,
+                    "decision_scope": decision_scope,
+                    "source_todo_id": source_todo_id,
+                }
+            )
+            recorded = apply_update(
+                lines,
+                todo_id=target_todo_id,
+                role="agent",
+                status=TODO_STATUS_BLOCKED,
+                decision_scope_outcomes=target_outcomes,
+                updated_at=updated_at,
+            )
+            unblock_resume = {
+                "schema_version": TODO_UNBLOCK_RESUME_SCHEMA_VERSION,
+                "source_todo_id": source_todo_id,
+                "target_todo_id": target_todo_id,
+                "state": (
+                    "decision_rejected"
+                    if normalized_outcome == "reject"
+                    else "decision_cancelled"
+                ),
+                "status": recorded.get("status"),
+                "changed": bool(recorded.get("changed")),
+            }
+        else:
+            unblock_resume = {
+                "schema_version": TODO_UNBLOCK_RESUME_SCHEMA_VERSION,
+                "source_todo_id": source_todo_id,
+                "target_todo_id": target_todo_id,
+                "state": "target_or_decision_scope_not_found",
+                "changed": False,
+            }
+    elif (
+        completion_role == "user"
+        and (
+            completion_task_class == "user_action"
+            or (
+                completion_task_class == TODO_TASK_CLASS_USER_GATE
+                and normalized_outcome == "approve"
+            )
+        )
+        and target_todo_id
+    ):
+        unblock_resume = plan_completed_user_unblock_resume(
+            lines,
+            source_todo_id=source_todo_id,
+            target_todo_id=target_todo_id,
+        )
+        if unblock_resume.get("state") == "resume_ready":
+            resumed = apply_update(
+                lines,
+                todo_id=target_todo_id,
+                role="agent",
+                status=TODO_STATUS_OPEN,
+                reason=f"authorization satisfied by completed user todo {source_todo_id}",
+                updated_at=updated_at,
+            )
+            unblock_resume.update(
+                state="resumed",
+                status=resumed.get("status"),
+                changed=bool(resumed.get("changed")),
+                claimed_by=resumed.get("claimed_by"),
+            )
+            unblock_resume = {
+                key: value
+                for key, value in unblock_resume.items()
+                if value not in (None, "", [], {})
+            }
+    return unblock_resume, decision_scope_resolution

loopx/control_plane/todos/user_gate.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .contract import TODO_TASK_CLASS_USER_GATE
+from .projection import todo_item_task_class
+
+
+USER_GATE_ACTION_KIND_HINTS = (
+    "approval",
+    "approve",
+    "boundary",
+    "gate",
+    "blocker",
+    "credential",
+    "private",
+    "production",
+    "leaderboard",
+    "submission",
+    "public_claim",
+)
+
+
+def open_todo_count(summary: dict[str, Any] | None) -> int:
+    if not isinstance(summary, dict):
+        return 0
+    try:
+        return max(0, int(summary.get("open_count") or 0))
+    except (TypeError, ValueError):
+        return 0
+
+
+def is_user_gate_todo_item(item: dict[str, Any]) -> bool:
+    explicit_task_class = str(item.get("task_class") or "").strip()
+    if explicit_task_class:
+        return todo_item_task_class(item) == TODO_TASK_CLASS_USER_GATE
+    if todo_item_task_class(item) == TODO_TASK_CLASS_USER_GATE:
+        return True
+    action_kind = str(item.get("action_kind") or "").strip().lower()
+    if not action_kind:
+        return False
+    return any(hint in action_kind for hint in USER_GATE_ACTION_KIND_HINTS)
+
+
+def open_user_gate_todo_items(summary: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not isinstance(summary, dict):
+        return []
+    candidates: list[dict[str, Any]] = []
+    for key in ("gate_open_items", "first_open_items", "items", "backlog_items"):
+        values = summary.get(key)
+        if not isinstance(values, list):
+            continue
+        for item in values:
+            if not isinstance(item, dict) or item.get("done") is True:
+                continue
+            if not is_user_gate_todo_item(item):
+                continue
+            item_key = (item.get("todo_id"), item.get("index"), item.get("text"))
+            if any(
+                (existing.get("todo_id"), existing.get("index"), existing.get("text"))
+                == item_key
+                for existing in candidates
+            ):
+                continue
+            candidates.append(item)
+    return candidates
+
+
+def has_open_user_gate_todo(summary: dict[str, Any] | None) -> bool:
+    return bool(open_user_gate_todo_items(summary))
+
+
+def user_gate_todo_notify_reason(summary: dict[str, Any] | None) -> str:
+    items = open_user_gate_todo_items(summary)
+    if not items:
+        return "open user todo can resolve the current gate"
+    first = items[0]
+    action_kind = str(first.get("action_kind") or "").strip()
+    if action_kind:
+        return f"open user_gate todo requires owner decision before {action_kind}"
+    return "open user_gate todo requires owner decision before agent execution"
+
+
+def should_notify_user_on_open_todo(
+    *,
+    state: str,
+    waiting_on: str,
+    user_todo_summary: dict[str, Any] | None,
+) -> bool:
+    if state == "operator_gate":
+        return False
+    if open_todo_count(user_todo_summary) <= 0:
+        return False
+    if state in {"focus_wait", "waiting"}:
+        return True
+    return waiting_on in {"user_or_controller", "controller", "external_evidence"}
+
+
+def open_todo_notify_reason(*, state: str, waiting_on: str) -> str:
+    if state == "focus_wait":
+        return "open user todo can unblock focus_wait after owner evidence, external eval, or a clean baseline changes"
+    if waiting_on == "external_evidence":
+        return "open user todo can provide or defer the external-evidence checkpoint"
+    if waiting_on in {"user_or_controller", "controller"}:
+        return "open user todo can resolve the user/controller blocker"
+    return "open user todo can resolve the current waiting lane"
+
+
+def build_user_todo_notification(
+    summary: dict[str, Any] | None,
+    *,
+    state: str,
+    waiting_on: str,
+    repeat_notification_required: bool = False,
+    repeat_notification_reason: Any = None,
+) -> dict[str, Any]:
+    if not isinstance(summary, dict):
+        return {}
+    if has_open_user_gate_todo(summary):
+        return {
+            "notify_user_on_gate": True,
+            "open_todo_notify_reason": user_gate_todo_notify_reason(summary),
+            "open_todo_notification_policy": "repeat_until_resolved",
+        }
+    if not repeat_notification_required and not should_notify_user_on_open_todo(
+        state=state,
+        waiting_on=waiting_on,
+        user_todo_summary=summary,
+    ):
+        return {}
+    reason = open_todo_notify_reason(state=state, waiting_on=waiting_on)
+    if repeat_notification_required:
+        reason = (
+            repeat_notification_reason
+            or "no-work polling should ask the current open user todo"
+        )
+    return {
+        "notify_user_on_open_todo": True,
+        "open_todo_notify_reason": reason,
+        **(
+            {"open_todo_notification_policy": "repeat_until_resolved"}
+            if repeat_notification_required
+            else {}
+        ),
+    }
+
+
+def apply_scoped_user_gate_fallback_projection(
+    payload: dict[str, Any],
+    *,
+    fallback: dict[str, Any] | None,
+    replan_decision_allowed: bool,
+) -> dict[str, Any]:
+    if not fallback or replan_decision_allowed:
+        return payload
+
+    projected = dict(payload)
+    projected["scoped_user_gate_fallback"] = fallback
+    projected["should_run"] = True
+    if projected.get("decision") == "skip":
+        projected["decision"] = "safe_bypass_user_gate_fallback"
+    if projected.get("effective_action") in {"skip", "monitor_quiet_skip", None}:
+        projected["effective_action"] = "scoped_user_gate_fallback"
+
+    execution_obligation = (
+        dict(projected.get("execution_obligation"))
+        if isinstance(projected.get("execution_obligation"), dict)
+        else {}
+    )
+    execution_obligation.update(
+        {
+            "must_attempt_work": True,
+            "kind": "scoped_user_gate_fallback",
+            "minimum": "one_non_gated_fallback_segment_after_user_gate_notice",
+            "delivery_allowed": True,
+            "notify_is_execution_gate": False,
+            "contract": "scoped_user_gate_fallback",
+            "contract_obligation": fallback.get("recommended_action"),
+            "reason": fallback.get("reason"),
+        }
+    )
+    projected["execution_obligation"] = execution_obligation
+    projected["safe_bypass_allowed"] = True
+    projected["safe_bypass_kind"] = "scoped_user_gate_fallback"
+    projected["safe_bypass_policy"] = (
+        "The user gate blocks only the matched agent action scope. Surface "
+        "that gate, then advance the selected non-gated fallback; spend only "
+        "after validated writeback."
+    )
+    projected["actionable_by_codex"] = True
+    return projected
+
+
+def build_gate_prompt(
+    item: dict[str, Any],
+    *,
+    user_todo_summary: dict[str, Any] | None = None,
+) -> str | None:
+    question = str(item.get("operator_question") or "").strip()
+    recommended_action = str(item.get("recommended_action") or "").strip()
+    next_handoff_condition = str(item.get("next_handoff_condition") or "").strip()
+    missing_gates = [
+        str(gate).strip()
+        for gate in (item.get("missing_gates") if isinstance(item.get("missing_gates"), list) else [])
+        if str(gate).strip()
+    ]
+    if user_todo_summary is None:
+        from .quota_summary import summarize_user_todos_for_quota
+
+        user_todo_summary = summarize_user_todos_for_quota(item.get("user_todos"))
+    first_open = (
+        user_todo_summary.get("first_open_items")
+        if isinstance(user_todo_summary, dict)
+        and isinstance(user_todo_summary.get("first_open_items"), list)
+        else []
+    )
+    other_agent_scoped_items = (
+        user_todo_summary.get("other_agent_scoped_items")
+        if isinstance(user_todo_summary, dict)
+        and isinstance(user_todo_summary.get("other_agent_scoped_items"), list)
+        else []
+    )
+
+    if not any(
+        [
+            question,
+            recommended_action,
+            next_handoff_condition,
+            missing_gates,
+            first_open,
+            other_agent_scoped_items,
+        ]
+    ):
+        return None
+
+    lines = ["请用户/控制器确认当前 gate："]
+    if question:
+        lines.append(f"- 问题：{question}")
+    if recommended_action:
+        lines.append(f"- 当前建议：{recommended_action}")
+    if next_handoff_condition:
+        lines.append(f"- 放行条件：{next_handoff_condition}")
+    if missing_gates:
+        lines.append(f"- 缺失 gate：{', '.join(missing_gates)}")
+    if isinstance(user_todo_summary, dict) and first_open:
+        open_count = user_todo_summary.get("open_count")
+        lines.append(f"- 用户待办：{open_count} 项未完成，优先确认：")
+        for todo in first_open:
+            index = todo.get("index")
+            prefix = f"  {index}. " if index is not None else "  - "
+            lines.append(f"{prefix}{todo.get('text')}")
+    elif isinstance(user_todo_summary, dict) and other_agent_scoped_items:
+        scoped_count = user_todo_summary.get("other_agent_scoped_open_count")
+        all_open_count = user_todo_summary.get("all_open_count")
+        count = scoped_count if scoped_count is not None else len(other_agent_scoped_items)
+        suffix = f"（全局共 {all_open_count} 项）" if all_open_count is not None else ""
+        lines.append(f"- 当前 agent 无阻塞用户待办；其他 agent/global 用户待办：{count} 项{suffix}，优先确认：")
+        for todo in other_agent_scoped_items[:3]:
+            index = todo.get("index")
+            prefix = f"  {index}. " if index is not None else "  - "
+            lines.append(f"{prefix}{todo.get('text')}")
+    lines.append("- 建议回复格式：同意 / 不同意 / 已完成 / 仍待确认 + 一句话原因。")
+    return "\n".join(lines)

loopx/control_plane/todos/write_hint.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_todo_write_hint(goal_id: str) -> dict[str, str]:
+    return {
+        "rule": "Write user/owner actions to User Todo, not Next Action/docs/chat.",
+        "user_gate_command_template": (
+            f"loopx todo add --goal-id {goal_id} --role user "
+            "--task-class user_gate --blocks-agent <agent-id> "
+            "--text '<blocking user decision>'"
+        ),
+        "user_action_command_template": (
+            f"loopx todo add --goal-id {goal_id} --role user "
+            "--task-class user_action --bound-agent <id> --text '<action>'"
+        ),
+        "agent_todo_command_template": (
+            f"loopx todo add --goal-id {goal_id} --role agent --text '<agent action>'"
+        ),
+        "section": "User Todo / Owner Review Reading Queue",
+    }
+
+
+def build_capability_resolution_writeback_actions(
+    capability_gate: Any,
+    *,
+    goal_id: str,
+    agent_id: str | None,
+    limit: int = 3,
+) -> list[str]:
+    if not isinstance(capability_gate, dict):
+        return []
+    bindings = capability_gate.get("resolution_bindings")
+    if not isinstance(bindings, list):
+        return []
+    actions: list[str] = []
+    agent = agent_id or "<registered-agent>"
+    for binding in bindings:
+        if not isinstance(binding, dict):
+            continue
+        owner = str(binding.get("owner") or "").strip()
+        capability = str(binding.get("capability") or "").strip()
+        todo_id = str(binding.get("primary_blocked_todo_id") or "").strip()
+        priority = str(binding.get("priority") or "P1").strip().upper()
+        if not capability or not todo_id:
+            continue
+        if priority not in {"P0", "P1", "P2"}:
+            priority = "P1"
+        if owner == "user":
+            text = (
+                f"[{priority}-user] Provide or authorize capability {capability} "
+                f"required by {todo_id}."
+            )
+            actions.append(
+                f"loopx todo add --goal-id {goal_id} --role user "
+                "--task-class user_gate --action-kind provide_capability "
+                f"--target-capability {capability} --blocks-agent {agent} "
+                f"--unblocks-todo-id {todo_id} --text '{text}'"
+            )
+        if len(actions) >= limit:
+            break
+    return actions