loopx 0.4.8__py3-none-any.whl

loopx/agent_registry.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .control_plane.todos.contract import normalize_todo_claimed_by
+
+
+def normalize_registered_agents(values: Any) -> list[str]:
+    if values is None:
+        return []
+    if not isinstance(values, list):
+        values = [values]
+    agents: list[str] = []
+    for value in values:
+        if isinstance(value, dict):
+            value = value.get("id") or value.get("agent_id") or value.get("name")
+        agent = normalize_todo_claimed_by(value)
+        if agent and agent not in agents:
+            agents.append(agent)
+    return agents
+
+
+def registered_agent_ids_for_goal(goal: dict[str, Any] | None) -> list[str]:
+    if not isinstance(goal, dict):
+        return []
+    candidates: list[Any] = []
+    coordination = goal.get("coordination")
+    if isinstance(coordination, dict):
+        candidates.append(coordination.get("registered_agents"))
+    candidates.append(goal.get("registered_agents"))
+    spawn_policy = goal.get("spawn_policy")
+    if isinstance(spawn_policy, dict):
+        candidates.append(spawn_policy.get("registered_agents"))
+    agents: list[str] = []
+    for candidate in candidates:
+        for agent in normalize_registered_agents(candidate):
+            if agent not in agents:
+                agents.append(agent)
+    return agents
+
+
+def agent_profile_for_goal(goal: dict[str, Any] | None, agent_id: str | None) -> dict[str, Any] | None:
+    normalized_agent_id = normalize_todo_claimed_by(agent_id)
+    if not isinstance(goal, dict) or not normalized_agent_id:
+        return None
+    coordination = goal.get("coordination")
+    if not isinstance(coordination, dict):
+        return None
+    profiles = coordination.get("agent_profiles")
+    raw_profile: Any = None
+    if isinstance(profiles, dict):
+        raw_profile = profiles.get(normalized_agent_id)
+    elif isinstance(profiles, list):
+        for item in profiles:
+            if not isinstance(item, dict):
+                continue
+            item_id = normalize_todo_claimed_by(item.get("agent_id") or item.get("id") or item.get("name"))
+            if item_id == normalized_agent_id:
+                raw_profile = item
+                break
+    if not isinstance(raw_profile, dict):
+        return None
+    profile = dict(raw_profile)
+    profile["agent_id"] = normalized_agent_id
+    return profile
+
+
+def load_goal_from_registry(registry_path: Path, goal_id: str) -> dict[str, Any] | None:
+    from .registry import read_json, registry_goals
+
+    if not registry_path.exists():
+        return None
+    registry = read_json(registry_path)
+    return next(
+        (goal for goal in registry_goals(registry) if str(goal.get("id")) == str(goal_id)),
+        None,
+    )
+
+
+def registered_agent_ids_from_registry(registry_path: Path, goal_id: str) -> list[str]:
+    return registered_agent_ids_for_goal(load_goal_from_registry(registry_path, goal_id))
+
+
+def agent_profile_from_registry(registry_path: Path, goal_id: str, agent_id: str | None) -> dict[str, Any] | None:
+    return agent_profile_for_goal(load_goal_from_registry(registry_path, goal_id), agent_id)
+
+
+def require_registered_agent_id(
+    *,
+    registry_path: Path,
+    goal_id: str,
+    agent_id: str | None,
+    field: str = "claimed_by",
+) -> str:
+    normalized = normalize_todo_claimed_by(agent_id)
+    if not normalized:
+        raise ValueError(f"{field} must be a public-safe registered agent id")
+    registered = registered_agent_ids_from_registry(registry_path, goal_id)
+    if not registered:
+        raise ValueError(
+            f"{field}={normalized!r} cannot be used because goal {goal_id!r} "
+            "has no coordination.registered_agents list. Register this peer identity first: "
+            "loopx configure-goal --goal-id "
+            f"{goal_id} --registered-agent {normalized} --execute"
+        )
+    if normalized not in registered:
+        raise ValueError(
+            f"{field}={normalized!r} is not registered for goal {goal_id!r}; "
+            f"registered_agents={', '.join(registered)}"
+        )
+    return normalized

loopx/ark_managed_agent_host.py

@@ -0,0 +1,59 @@
+"""Thin one-shot goal activation contract for Ark Managed Agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .control_plane.scheduler.execution_context import (
+    GOAL_RUNTIME_CONTINUATION_SCHEMA_VERSION,
+)
+from .control_plane.work_items.runtime_capability_reentry import (
+    RUNTIME_CAPABILITY_REENTRY_SCHEMA_VERSION,
+)
+
+ARK_MANAGED_AGENT_HOST = "ark-managed-agent"
+ARK_MANAGED_AGENT_HOST_CONTRACT_SCHEMA_VERSION = (
+    "loopx_ark_managed_agent_goal_host_v0"
+)
+ARK_MANAGED_AGENT_PROMPT_FAMILY = "loopx_goal_prompt_v0"
+
+
+def build_ark_managed_agent_host_contract() -> dict[str, Any]:
+    """Describe transport-neutral ownership for one goal prompt activation."""
+
+    return {
+        "schema_version": ARK_MANAGED_AGENT_HOST_CONTRACT_SCHEMA_VERSION,
+        "host_kind": ARK_MANAGED_AGENT_HOST,
+        "activation_mode": "goal_once",
+        "prompt_family": ARK_MANAGED_AGENT_PROMPT_FAMILY,
+        "policy_source": "quota_should_run.interaction_contract",
+        "transport_contract": "goal_prompt_v0",
+        "goal_runtime_owns_continuation": True,
+        "goal_lifecycle_scope": "registered_goal_until_terminal",
+        "phase_handoff_allowed": False,
+        "loopx_turn_driver_required": False,
+        "session_state_authoritative": False,
+        "goal_runtime_continuation": {
+            "source_ref": "quota_should_run.scheduler_hint.goal_runtime_continuation",
+            "packet_schema_version": GOAL_RUNTIME_CONTINUATION_SCHEMA_VERSION,
+            "dispositions": ["continue_now", "defer", "complete"],
+            "defer_wake_policy": "state_change_or_deadline",
+            "reason_source_ref": "quota_should_run.scheduler_hint.reason_code",
+            "state_identity_source_ref": (
+                "quota_should_run.scheduler_hint.reset_policy"
+            ),
+            "goal_prompt_mutated": False,
+        },
+        "runtime_capability_reentry": {
+            "source_ref": (
+                "quota_should_run.interaction_contract.cli_channel."
+                "runtime_capability_reentry"
+            ),
+            "cli_projection_ref": "quota_should_run.runtime_capability_reentry",
+            "packet_schema_version": RUNTIME_CAPABILITY_REENTRY_SCHEMA_VERSION,
+            "delivery_channel": "quota_tool_result",
+            "goal_prompt_mutated": False,
+            "session_scoped": True,
+            "durable_grant_written": False,
+        },
+    }