loopx 0.4.8__py3-none-any.whl

loopx/control_plane/goals/goal_vision_wait.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from ..todos.contract import (
+    TODO_TASK_CLASS_BLOCKER,
+    normalize_todo_claimed_by,
+    normalize_todo_id,
+    normalize_todo_status,
+)
+from ..todos.deferred_resume import todo_summary_blocked_successor_items
+
+GOAL_VISION_WAIT_STATE_SCHEMA_VERSION = "goal_vision_wait_state_v0"
+VISION_ACCEPTANCE_GAP_KIND = "vision_acceptance_gap"
+
+
+def exact_blocked_successor_wait_state(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    candidate = value
+    if value.get("schema_version") != GOAL_VISION_WAIT_STATE_SCHEMA_VERSION:
+        candidate = (
+            value.get("vision_wait_state")
+            if isinstance(value.get("vision_wait_state"), dict)
+            else {}
+        )
+        if not candidate:
+            projection = (
+                value.get("goal_frontier_projection")
+                if isinstance(value.get("goal_frontier_projection"), dict)
+                else {}
+            )
+            candidate = (
+                projection.get("vision_wait_state")
+                if isinstance(projection.get("vision_wait_state"), dict)
+                else {}
+            )
+    if (
+        candidate.get("schema_version") != GOAL_VISION_WAIT_STATE_SCHEMA_VERSION
+        or candidate.get("state") != "waiting"
+        or candidate.get("reason_code") != "exact_blocked_successor"
+        or candidate.get("automatic_resume") is not True
+        or not normalize_todo_id(candidate.get("selected_todo_id"))
+        or not str(candidate.get("resume_when") or "").strip()
+    ):
+        return {}
+    return candidate
+
+
+def exact_blocked_successor_frontier_identity(value: Any) -> str | None:
+    wait = exact_blocked_successor_wait_state(value)
+    if not wait:
+        return None
+    parts = {
+        "agent_id": str(wait.get("agent_id") or "").strip(),
+        "reason_code": "exact_blocked_successor",
+        "selected_todo_id": normalize_todo_id(wait.get("selected_todo_id")),
+        "resume_when": str(wait.get("resume_when") or "").strip(),
+    }
+    return hashlib.sha256(
+        json.dumps(parts, ensure_ascii=True, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def _compact_resume_condition(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    compact = {
+        key: value.get(key)
+        for key in (
+            "schema_version",
+            "resume_when",
+            "satisfied",
+            "kind",
+            "target",
+            "target_todo_id",
+            "target_status",
+            "target_archive_state",
+            "target_source_section",
+            "target_task_class",
+            "target_claimed_by",
+            "capability",
+            "provider",
+        )
+        if value.get(key) is not None
+    }
+    compact["satisfied"] = False
+    return compact
+
+
+def _acceptance_gap_causal_todo_ids(
+    gaps: list[dict[str, Any]],
+) -> set[str]:
+    todo_ids: set[str] = set()
+    for gap in gaps:
+        for key in (
+            "todo_id",
+            "current_todo_id",
+            "blocked_todo_id",
+            "completed_todo_id",
+            "successor_todo_id",
+        ):
+            todo_id = normalize_todo_id(gap.get(key))
+            if todo_id:
+                todo_ids.add(todo_id)
+        for key in (
+            "vision_todo_ids",
+            "lineage_todo_ids",
+            "successor_todo_ids",
+            "completed_todo_ids",
+        ):
+            values = gap.get(key) if isinstance(gap.get(key), list) else []
+            todo_ids.update(
+                todo_id
+                for value in values
+                if (todo_id := normalize_todo_id(value))
+            )
+    return todo_ids
+
+
+def _causal_blocked_successor_items(
+    candidates: list[dict[str, Any]],
+    *,
+    causal_todo_ids: set[str],
+) -> list[dict[str, Any]]:
+    """Keep only waits in the active vision's explicit Todo lineage."""
+
+    if not causal_todo_ids:
+        return []
+    lineage_ids = set(causal_todo_ids)
+    changed = True
+    while changed:
+        changed = False
+        for item in candidates:
+            todo_id = normalize_todo_id(item.get("todo_id"))
+            condition = (
+                item.get("resume_condition")
+                if isinstance(item.get("resume_condition"), dict)
+                else {}
+            )
+            target_todo_id = normalize_todo_id(
+                condition.get("target_todo_id") or condition.get("target")
+            )
+            successor_todo_ids = {
+                successor_todo_id
+                for value in (
+                    item.get("successor_todo_ids")
+                    if isinstance(item.get("successor_todo_ids"), list)
+                    else []
+                )
+                if (successor_todo_id := normalize_todo_id(value))
+            }
+            if not (
+                (todo_id and todo_id in lineage_ids)
+                or (target_todo_id and target_todo_id in lineage_ids)
+                or successor_todo_ids.intersection(lineage_ids)
+            ):
+                continue
+            expanded = {
+                value
+                for value in (todo_id, target_todo_id, *successor_todo_ids)
+                if value
+            }
+            if not expanded.issubset(lineage_ids):
+                lineage_ids.update(expanded)
+                changed = True
+    return [
+        item
+        for item in candidates
+        if normalize_todo_id(item.get("todo_id")) in lineage_ids
+    ]
+
+
+def build_goal_vision_wait_state(
+    *,
+    agent_todo_summary: dict[str, Any] | None,
+    agent_id: str | None,
+    acceptance_gaps: list[dict[str, Any]] | None,
+    selectable_advancement_count: int,
+) -> dict[str, Any] | None:
+    """Project a temporary vision wait over an authoritative blocked frontier.
+
+    This is deliberately a read model, not a new todo or vision lifecycle
+    state. It may defer only ordinary open-vision acceptance gaps. Missing
+    checkpoints and closed-stage successor requirements remain strict.
+    """
+
+    gaps = [gap for gap in (acceptance_gaps or []) if isinstance(gap, dict)]
+    if not gaps or any(gap.get("kind") != VISION_ACCEPTANCE_GAP_KIND for gap in gaps):
+        return None
+    if selectable_advancement_count > 0:
+        return None
+
+    causal_todo_ids = _acceptance_gap_causal_todo_ids(gaps)
+
+    blocker_items = (
+        agent_todo_summary.get("current_agent_blocker_items")
+        if isinstance(agent_todo_summary, dict)
+        and isinstance(agent_todo_summary.get("current_agent_blocker_items"), list)
+        else []
+    )
+    safe_agent_id = normalize_todo_claimed_by(agent_id)
+    blocker_items = [
+        item
+        for item in blocker_items
+        if isinstance(item, dict)
+        and safe_agent_id is not None
+        and item.get("task_class") == TODO_TASK_CLASS_BLOCKER
+        and normalize_todo_status(item.get("status")) == "blocked"
+        and str(item.get("reason") or "").strip()
+        and normalize_todo_claimed_by(item.get("claimed_by"))
+        == safe_agent_id
+        and normalize_todo_id(item.get("todo_id")) in causal_todo_ids
+    ]
+    candidates = []
+    if not blocker_items:
+        candidates = _causal_blocked_successor_items(
+            todo_summary_blocked_successor_items(
+                agent_todo_summary or {},
+                agent_id=agent_id,
+            ),
+            causal_todo_ids=causal_todo_ids,
+        )
+    if candidates:
+        selected = candidates[0]
+        waiting_todo_ids = [
+            todo_id
+            for todo_id in (
+                normalize_todo_id(item.get("todo_id")) for item in candidates[:5]
+            )
+            if todo_id
+        ]
+        payload: dict[str, Any] = {
+            "schema_version": GOAL_VISION_WAIT_STATE_SCHEMA_VERSION,
+            "state": "waiting",
+            "reason_code": "exact_blocked_successor",
+            "agent_id": agent_id,
+            "waiting_todo_count": len(candidates),
+            "waiting_todo_ids": waiting_todo_ids,
+            "selected_todo_id": normalize_todo_id(selected.get("todo_id")),
+            "selected_todo_status": selected.get("status"),
+            "selected_todo_priority": selected.get("priority"),
+            "selected_todo_claimed_by": selected.get("claimed_by"),
+            "resume_when": selected.get("resume_when"),
+            "resume_condition": _compact_resume_condition(
+                selected.get("resume_condition")
+            ),
+            "deferred_acceptance_gap_count": len(gaps),
+            "deferred_acceptance_gap_kinds": [VISION_ACCEPTANCE_GAP_KIND],
+            "automatic_resume": True,
+            "resume_behavior": (
+                "when resume_ready becomes true, restore ordinary open-todo or "
+                "deferred-successor routing without closing the active vision"
+            ),
+        }
+        return {key: value for key, value in payload.items() if value is not None}
+
+    if not blocker_items:
+        return None
+    selected = blocker_items[0]
+    waiting_todo_ids = [
+        todo_id
+        for todo_id in (
+            normalize_todo_id(item.get("todo_id")) for item in blocker_items[:5]
+        )
+        if todo_id
+    ]
+    payload = {
+        "schema_version": GOAL_VISION_WAIT_STATE_SCHEMA_VERSION,
+        "state": "waiting",
+        "reason_code": "current_agent_blocker",
+        "agent_id": agent_id,
+        "waiting_todo_count": len(blocker_items),
+        "waiting_todo_ids": waiting_todo_ids,
+        "selected_todo_id": normalize_todo_id(selected.get("todo_id")),
+        "selected_todo_status": selected.get("status"),
+        "selected_todo_priority": selected.get("priority"),
+        "selected_todo_claimed_by": selected.get("claimed_by"),
+        "blocker_reason": str(selected.get("reason") or "").strip(),
+        "deferred_acceptance_gap_count": len(gaps),
+        "deferred_acceptance_gap_kinds": [VISION_ACCEPTANCE_GAP_KIND],
+        "automatic_resume": False,
+        "resume_behavior": (
+            "re-evaluate the active vision when the blocker is resolved or "
+            "superseded, or when runnable scoped advancement appears"
+        ),
+    }
+    return {key: value for key, value in payload.items() if value is not None}

loopx/control_plane/goals/path_resolution.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def same_path(left: Path, right: Path) -> bool:
+    return left.expanduser().resolve() == right.expanduser().resolve()
+
+
+def resolve_goal_local_path(raw: Any, goal: dict[str, Any], *, fallback_base: Path) -> Path | None:
+    if not raw:
+        return None
+    path = Path(str(raw)).expanduser()
+    if path.is_absolute():
+        return path
+    repo = goal.get("repo")
+    if repo:
+        return Path(str(repo)).expanduser() / path
+    return fallback_base / path

loopx/control_plane/goals/start_contract.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+from typing import Any
+
+GOAL_START_SCHEMA_VERSION = "loopx_goal_start_command_v0"
+
+
+def build_goal_start_contract(
+    *,
+    goal_text: str | None,
+    selected_capability_route: dict[str, Any] | None,
+    connected: bool,
+    agent_type: str,
+    issue_fix_commands: dict[str, str],
+    fine_grained: bool,
+) -> dict[str, Any]:
+    contract = {
+        "schema_version": GOAL_START_SCHEMA_VERSION,
+        "behavior_authority": (
+            "ordered_steps + goal_start_contract; skill passes raw arguments after host "
+            "detection, executes packet"
+        ),
+        "slash_syntax": "/loopx <goal text>",
+        "goal_text": goal_text,
+        "selected_capability_route": selected_capability_route,
+        "explicit_invocation_confirms_project_local_state_writes": True,
+        "connect_if_needed": True,
+        "bootstrap_policy": "create project-local LoopX state only when no matching registry goal exists",
+        "planner": {
+            "required_before_todo_write": True,
+            "default_profile": "open_ended_product_direction",
+            "profile_selection": (
+                "Use open_ended_product_direction when the user's goal is a broad, "
+                "fuzzy product direction or new initiative. Use clear_bounded_problem "
+                "when the target is a concrete task with a clear success condition. "
+                "In both cases, let the model produce a real ordered plan before writes."
+            ),
+            "profiles": {
+                "open_ended_product_direction": {
+                    "suggested_items_min": 2,
+                    "suggested_items_max": 5,
+                    "intent": (
+                        "turn an ambiguous product direction into public-safe, ranked "
+                        "todo options before execution"
+                    ),
+                },
+                "clear_bounded_problem": {
+                    "item_count_policy": "planner_sized",
+                    "may_reuse_current_todo_when_it_already_represents_the_plan": True,
+                    "intent": (
+                        "make the approach explicit with enough concise ordered todos, "
+                        "without arbitrary caps or management-only filler"
+                    ),
+                },
+            },
+            "allowed_priorities": ["P0", "P1", "P2"],
+            "default_role": "agent",
+            "default_task_class": "advancement_task",
+            "required_fields": ["priority", "text", "task_class", "action_kind"],
+            "public_safe_only": True,
+            "budget_policy": "minimum sufficient plan; no fixed-count filler",
+        },
+        "priority_ordering": {
+            "bucket_order": ["P0", "P1", "P2"],
+            "same_priority_tie_breaker": "planner_order_then_todo_write_order",
+            "prompt_constraint": "priority then exact write order",
+            "storage_contract": "Todo index is same-priority rank; no extra field",
+        },
+        "execution_invariants": (
+            "identity: fresh public-safe agent after verified/active; explicit takeover; "
+            "bind/readback before Todo; no peer inference; unknown: "
+            "loopx agent-onboard --list-agent-types | route: selected_capability_route only; "
+            "never infer from text/URLs; #/activation+#/stop_conditions; review/pasteable "
+            "gates | Todo/writeback: Agent advancement_task; User owner/private; business Todo "
+            "before work; current evidence + next Todo; refresh/quota; chat not durable | "
+            "returned typed quota_guard; one bounded validation+writeback or exact blocker; "
+            "optional need/preview/explicit apply"
+        ),
+        "activation": {
+            "after_write": ["refresh-state", "host_loop_activation", "quota should-run"],
+            "host_loop_required_after_todo_writeback": True,
+            "agent_type": agent_type,
+            "agent_type_discovery": "loopx agent-onboard --list-agent-types",
+            "host_surfaces": {
+                "codex-app": "Codex App heartbeat automation",
+                "codex-cli": "visible Codex CLI `/goal <task_body>`",
+                "claude-code": "Claude Code native `/loop` after `/loopx <task>` arms LoopX",
+                "opencode": "OpenCode `loopx_goal_activate`",
+                "pi": "Pi `loopx_goal_activate`",
+                "gemini-cli": "agent-driven Gemini CLI loop; every turn enters through quota should-run",
+                "cursor-agent": "agent-driven cursor-agent loop; every turn enters through quota should-run",
+                "ark-managed-agent": "one-shot Goal",
+                "manual": "external scheduler or manual quota/status loop",
+                "other-agent": "custom host loop driver using the returned task body and quota guard",
+            },
+            "missing_host_loop_policy": (
+                "Do not claim autonomous setup complete from registry/quota identity alone. "
+                "If the host cannot mutate its loop surface, report the exact pasteable gate."
+            ),
+            "low_cost_recheck_policy": "missing/unknown/stale/type-changed only",
+            "begin_automation_when_quota_allows": True,
+            "spend_quota_after_writeback": True,
+        },
+        "domain_route_hints": {
+            "issue_fix_workflow": {
+                "when": (
+                    "selected_capability_route.capability_id is explicitly "
+                    "set to issue-fix"
+                ),
+                "preview_command": issue_fix_commands[
+                    "issue_fix_workflow_plan_template"
+                ],
+                "decision_command": issue_fix_commands[
+                    "issue_fix_feasibility_template"
+                ],
+                "post_pr_reviewer_request_command": issue_fix_commands[
+                    "issue_fix_reviewer_request_template"
+                ],
+                "post_pr_monitor_command": issue_fix_commands[
+                    "issue_fix_pr_lifecycle_template"
+                ],
+                "writeback": (
+                    "persist candidate preflight; only proceed enters feasibility and writes "
+                    "its successor; keep private/external/publish/destructive/production gates; "
+                    "after PR creation verify reviewer-request, then monitor one PR state bucket"
+                ),
+            }
+        },
+        "connected_at_preview_time": connected,
+        "stop_conditions": [
+            "private material requested before a public-safe todo can be written",
+            "credentials or secrets are required",
+            "destructive git or production operation would be needed",
+            "the host cannot execute shell/CLI/tool calls or persist LoopX state",
+            "the host cannot activate or expose the required host loop and no concrete pasteable gate can be shown",
+        ],
+    }
+    if fine_grained:
+        contract["turn_mode"] = "fine_grained"
+        contract["fine_grained"] = {
+            "todo_granularity": "small_checkpoint",
+            "turn_work_budget": "coherent_slice",
+            "turn_boundary": "settle_after_coherent_slice",
+            "replan": "direction_change_or_bounded_chain",
+            "checkpoint_accounting": "advancement_only",
+        }
+        planner = contract["planner"]
+        planner["fine_grained_plan_horizon"] = (
+            "write one current runnable checkpoint; keep later options as evidence-linked "
+            "planning notes until the existing replan path qualifies the successor"
+        )
+        planner["maximum_runnable_todos_written_ahead"] = 1
+    return contract
+
+
+def build_goal_start_prompt(
+    *,
+    goal_text: str | None,
+    goal_id: str,
+    agent_id: str | None,
+    fine_grained: bool,
+) -> str:
+    goal_clause = (
+        f"Goal text: {goal_text}"
+        if goal_text
+        else "Goal text: use the text after `/loopx`; if it is empty, handle bare `/loopx` instead."
+    )
+    agent_clause = f" Use agent id `{agent_id}` for quota/claim commands." if agent_id else ""
+    todo_rule = (
+        "plan the broader direction as evidence-linked notes, but write exactly one "
+        "current small, verifiable Agent advancement_task Todo; do not write a runnable "
+        "successor ahead. Use `[P0]`/`[P1]`/`[P2]`, no `--priority`; User Todo only "
+        "for owner/private gates"
+        if fine_grained
+        else "broad goal 2-5 public-safe items, bounded goal minimum sufficient plan; "
+        "`[P0]`/`[P1]`/`[P2]`, no `--priority`, preserve order, prefer Agent "
+        "`advancement_task`, User Todo only for owner/private gates. Write one business "
+        "Todo before work"
+    )
+    fine_rule = (
+        "\n8. Fine-grained mode: the current Todo must be one small verifiable checkpoint. "
+        "If it is too broad, split it before work. A coherent decision slice may complete "
+        "one or more causally related Agent advancement Todos in the same turn: after each "
+        "completion inspect its fresh evidence before creating or claiming the next Todo, "
+        "and settle only once after the slice. Use the existing replan obligation/ACK path "
+        "when evidence changes direction or the bounded-chain review becomes due; never "
+        "prewrite a long runnable chain. Protocol/setup and capability re-entry steps stay "
+        "inline in the guided transaction, are not Todos, and do not count as advancement "
+        "checkpoints or turn settlement."
+        if fine_grained
+        else ""
+    )
+    return f"""Plan; returned `ordered_steps` + `goal_start_contract` are authoritative.
+
+{goal_clause}
+Goal id: {goal_id}.{agent_clause}
+
+Rules:
+1. Identity: use verified binding/active contract; a stable unbound host gets a fresh public-safe agent. Existing lanes require explicit takeover plus bind/readback before Todo; never infer peers from Todo/worktree/arguments. Unknown host: `loopx agent-onboard --list-agent-types`.
+2. Capability: only `selected_capability_route`; run entry/admission and its later `capability show`; never infer from text/URLs. Capability state owns facts; generic Todos schedule.
+3. Todos: {todo_rule}.
+4. Writeback: current Todo evidence + next executable Todo, then `loopx refresh-state --goal-id {goal_id}` and quota readback. Chat/model summaries are not durable state.
+5. Host loop: after Todo write, activate missing/unknown/stale/type-changed Codex App heartbeat automation, CLI/TraeX `/goal`, Claude `/loop`, OpenCode bridge, Ark one-shot, or custom gate. Else surface the exact pasteable gate; never claim autonomy.
+6. Run the returned typed `quota_guard`; finish one bounded segment with validation + LoopX writeback or an exact blocker. Setup/planning/claim is not delivery.
+7. Optional features: need, preview, explicit apply. Respect private data, credentials, destructive git, production authority, and review rules.{fine_rule}
+"""

loopx/control_plane/goals/vision_checkpoint.py

@@ -0,0 +1,92 @@
+"""Agent-vision checkpoint contract for accountable state refreshes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...feedback import validate_public_safe_text
+
+VISION_CHECKPOINT_SCHEMA_VERSION = "vision_checkpoint_v0"
+VISION_CHECKPOINT_MATERIAL_OUTCOMES = {
+    "outcome_gap",
+    "outcome_progress",
+    "primary_goal_outcome",
+}
+VISION_UNCHANGED_REASON_LIMIT = 240
+
+
+def normalize_vision_unchanged_reason(value: str | None) -> str:
+    """Normalize and validate a vision closeout reason before state mutation."""
+
+    unchanged = " ".join(str(value or "").strip().split())
+    if not unchanged:
+        return ""
+    validate_public_safe_text("vision_unchanged_reason", unchanged)
+    if len(unchanged) > VISION_UNCHANGED_REASON_LIMIT:
+        raise ValueError(
+            "vision_unchanged_reason exceeds "
+            f"{VISION_UNCHANGED_REASON_LIMIT} chars"
+        )
+    return unchanged
+
+
+def build_vision_checkpoint(
+    *,
+    agent_id: str | None,
+    agent_vision: dict[str, Any] | None,
+    existing_agent_vision: dict[str, Any] | None,
+    vision_unchanged_reason: str | None,
+    delivery_outcome: str | None,
+    active_state_next_action_update: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Return the explicit vision closeout decision for this refresh run."""
+
+    triggers: list[dict[str, Any]] = []
+    if delivery_outcome in VISION_CHECKPOINT_MATERIAL_OUTCOMES:
+        triggers.append(
+            {
+                "kind": "material_delivery_outcome",
+                "delivery_outcome": delivery_outcome,
+            }
+        )
+    if active_state_next_action_update and active_state_next_action_update.get(
+        "would_update"
+    ):
+        triggers.append({"kind": "durable_next_action_update"})
+
+    unchanged = normalize_vision_unchanged_reason(vision_unchanged_reason)
+    required = bool(triggers or unchanged)
+    if agent_vision:
+        decision = "patched"
+        satisfied = True
+    elif unchanged and existing_agent_vision:
+        decision = "unchanged_with_reason"
+        satisfied = True
+    elif unchanged or required:
+        decision = "missing_required"
+        satisfied = False
+    else:
+        decision = "not_required"
+        satisfied = True
+
+    checkpoint: dict[str, Any] = {
+        "schema_version": VISION_CHECKPOINT_SCHEMA_VERSION,
+        "agent_id": agent_id,
+        "required": required,
+        "satisfied": satisfied,
+        "decision": decision,
+        "triggers": triggers,
+    }
+    if agent_vision:
+        checkpoint["agent_vision_state"] = agent_vision.get("state")
+    if unchanged and existing_agent_vision:
+        checkpoint["unchanged_reason"] = unchanged
+        checkpoint["agent_vision_state"] = existing_agent_vision.get("state")
+    elif unchanged:
+        checkpoint["missing_baseline"] = True
+        checkpoint["rejected_unchanged_reason"] = unchanged
+    if not satisfied:
+        checkpoint["required_resolution"] = ["write_vision_patch"]
+        if not checkpoint.get("missing_baseline"):
+            checkpoint["required_resolution"].append("record_unchanged_reason")
+    return checkpoint

loopx/control_plane/handoff/__init__.py

@@ -0,0 +1 @@
+"""Handoff control-plane read models."""