loopx 0.4.8__py3-none-any.whl

loopx/control_plane/handoff/review_packet_context.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ..runtime.agent_scoped_evidence_log import build_agent_scoped_required_read
+from ..runtime.public_safety import compact_text
+
+
+HANDOFF_TODO_PRIORITY_PATTERN = re.compile(r"^\s*\[(P[0-4])", re.IGNORECASE)
+HANDOFF_MONITOR_TASK_CLASSES = {"blocker", "continuous_monitor", "monitor", "user_gate"}
+HANDOFF_ADVANCEMENT_TASK_CLASSES = {"advancement_task", "execution_task", "delivery_task"}
+HANDOFF_MONITOR_MARKERS = (
+    "monitor",
+    "observation",
+    "readiness",
+    "watch",
+    "poll",
+    "dependency monitor",
+    "观察",
+    "监控",
+    "等待",
+)
+
+
+def compact_packet_text(value: str, limit: int = 180) -> str:
+    return compact_text(str(value), limit=limit)
+
+
+def handoff_todo_priority_rank(text: str) -> int:
+    match = HANDOFF_TODO_PRIORITY_PATTERN.match(text)
+    if not match:
+        return 50
+    return int(match.group(1)[1])
+
+
+def handoff_todo_task_rank(item: dict[str, Any], text: str) -> int:
+    task_class = str(item.get("task_class") or "").strip().lower()
+    if task_class in HANDOFF_ADVANCEMENT_TASK_CLASSES:
+        return 0
+    if task_class in HANDOFF_MONITOR_TASK_CLASSES:
+        return 1
+    lowered = text.lower()
+    if any(marker in lowered for marker in HANDOFF_MONITOR_MARKERS):
+        return 1
+    return 0
+
+
+def handoff_todo_rank(item: dict[str, Any], text: str, ordinal: int) -> tuple[int, int, int]:
+    index = item.get("index")
+    stable_index = index if isinstance(index, int) else ordinal
+    return (
+        handoff_todo_task_rank(item, text),
+        handoff_todo_priority_rank(text),
+        stable_index,
+    )
+
+
+def open_todo_texts(todos: Any, *, limit: int = 3, rank_for_handoff: bool = False) -> list[str]:
+    if not isinstance(todos, dict):
+        return []
+    items = todos.get("items") if isinstance(todos.get("items"), list) else []
+    if not items and isinstance(todos.get("first_open_items"), list):
+        items = todos.get("first_open_items") or []
+    result: list[str] = []
+    ranked_result: list[tuple[tuple[int, int, int], str]] = []
+    for ordinal, item in enumerate(items):
+        if not isinstance(item, dict) or item.get("done"):
+            continue
+        text = str(item.get("text") or "").strip()
+        if text:
+            claimed_by = str(item.get("claimed_by") or "").strip()
+            display_text = text
+            if claimed_by:
+                display_text = f"{display_text} claimed_by={claimed_by}"
+            if rank_for_handoff:
+                ranked_result.append(
+                    (handoff_todo_rank(item, text, ordinal), compact_packet_text(display_text))
+                )
+                continue
+            result.append(compact_packet_text(display_text))
+            if len(result) >= limit:
+                return result
+    if rank_for_handoff:
+        return [text for _, text in sorted(ranked_result, key=lambda ranked: ranked[0])[:limit]]
+    return result
+
+
+def todo_text_from_project_asset(item: dict[str, Any] | None, key: str) -> str | None:
+    items = todo_texts_from_project_asset(item, key, limit=1)
+    return items[0] if items else None
+
+
+def todo_texts_from_project_asset(
+    item: dict[str, Any] | None,
+    key: str,
+    *,
+    limit: int = 3,
+) -> list[str]:
+    if not isinstance(item, dict):
+        return []
+    project_asset = item.get("project_asset") if isinstance(item.get("project_asset"), dict) else {}
+    summary = project_asset.get(key) if isinstance(project_asset.get(key), dict) else {}
+    rank_for_handoff = key == "agent_todos"
+    summary_items = open_todo_texts(summary, limit=limit, rank_for_handoff=rank_for_handoff)
+    if summary_items:
+        return summary_items
+    next_text = str(summary.get("next") or "").strip()
+    if next_text:
+        return [compact_packet_text(next_text)]
+    return open_todo_texts(item.get(key), limit=limit, rank_for_handoff=rank_for_handoff)
+
+
+def agent_lane_todo_text(item: dict[str, Any] | None) -> str | None:
+    if not isinstance(item, dict):
+        return None
+    project_asset = item.get("project_asset") if isinstance(item.get("project_asset"), dict) else {}
+    lane = (
+        project_asset.get("agent_lane_next_action")
+        if isinstance(project_asset.get("agent_lane_next_action"), dict)
+        else item.get("agent_lane_next_action")
+        if isinstance(item.get("agent_lane_next_action"), dict)
+        else None
+    )
+    if not isinstance(lane, dict):
+        return None
+    text = str(lane.get("text") or lane.get("title") or "").strip()
+    if not text:
+        return None
+    claimed_by = str(lane.get("claimed_by") or "").strip()
+    if claimed_by:
+        text = f"{text} claimed_by={claimed_by}"
+    return compact_packet_text(text)
+
+
+def agent_todo_texts_for_handoff(item: dict[str, Any] | None, *, limit: int = 3) -> list[str]:
+    items = todo_texts_from_project_asset(item, "agent_todos", limit=limit)
+    lane_text = agent_lane_todo_text(item)
+    if not lane_text:
+        return items
+    return [lane_text, *[text for text in items if text != lane_text]][:limit]
+
+
+def agent_member_from_item(item: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not isinstance(item, dict):
+        return None
+    project_asset = item.get("project_asset") if isinstance(item.get("project_asset"), dict) else {}
+    member = (
+        project_asset.get("agent_member")
+        if isinstance(project_asset.get("agent_member"), dict)
+        else None
+    )
+    if member is None and isinstance(item.get("agent_member"), dict):
+        member = item["agent_member"]
+    return member if isinstance(member, dict) else None
+
+
+def agent_member_summary(item: dict[str, Any] | None) -> str | None:
+    member = agent_member_from_item(item)
+    if not member:
+        return None
+    claims = [
+        str(claim).strip()
+        for claim in (member.get("current_claims") or [])
+        if str(claim).strip()
+    ]
+    parts = [
+        f"agent={member.get('agent_id')}",
+        f"agent_model={member.get('agent_model')}",
+        "authority=advisory_projection",
+    ]
+    if member.get("profile_role"):
+        parts.append(f"profile_role={member.get('profile_role')}")
+    if member.get("scope_summary"):
+        parts.append(f"scope={member.get('scope_summary')}")
+    if member.get("worktree_policy"):
+        parts.append(f"worktree_policy={member.get('worktree_policy')}")
+    if claims:
+        parts.append(f"claims={','.join(claims[:5])}")
+    if member.get("handoff_assignment_status"):
+        parts.append(f"handoff_assignment={member.get('handoff_assignment_status')}")
+    return compact_packet_text(" ".join(str(part) for part in parts if part))
+
+
+def project_agent_required_reads(
+    goal_id: str,
+    item: dict[str, Any] | None,
+) -> list[dict[str, Any]]:
+    member = agent_member_from_item(item)
+    if not member:
+        return []
+    agent_id = str(member.get("agent_id") or "").strip()
+    read = build_agent_scoped_required_read(
+        goal_id=goal_id,
+        agent_id=agent_id,
+        reason=(
+            "read this target agent's thin evidence ledger before replan or "
+            "handoff continuation; other agents stay frontier-only"
+        ),
+    )
+    return [read] if read else []
+
+
+def project_asset_source(item: dict[str, Any] | None) -> str:
+    if isinstance(item, dict) and isinstance(item.get("project_asset"), dict):
+        return "project_asset"
+    return "legacy_raw_fallback"
+
+
+def project_asset_source_line(source: str) -> str:
+    if source == "project_asset":
+        return "project_asset（owner/gate/next/stop 来自 attention_queue.project_asset）"
+    return (
+        "legacy/raw fallback（未收到 project_asset；summary/action/todos "
+        "来自 raw queue/status 降级判断，不能当 owner/gate/stop authority）"
+    )

loopx/control_plane/heartbeat/agent.py

@@ -0,0 +1,173 @@
+"""Heartbeat agent identity helpers inside the heartbeat bounded context."""
+
+from __future__ import annotations
+
+import shlex
+from typing import Any
+
+from ..agents.runtime_model import PEER_AGENT_PROFILE_SCHEMA_VERSION
+
+
+def normalize_agent_scope(value: Any) -> str | None:
+    candidate = " ".join(str(value or "").strip().split())
+    if not candidate:
+        return None
+    if len(candidate) > 180 or any(char in candidate for char in "<>"):
+        raise ValueError("agent scope must be compact text without angle brackets")
+    return candidate
+
+
+def normalize_agent_scopes(values: list[str] | tuple[str, ...] | None) -> list[str]:
+    scopes: list[str] = []
+    for value in values or []:
+        scope = normalize_agent_scope(value)
+        if scope and scope not in scopes:
+            scopes.append(scope)
+    return scopes
+
+
+def agent_profile_scopes(profile: dict[str, Any] | None) -> list[str]:
+    if not isinstance(profile, dict):
+        return []
+    raw_scopes: list[Any] = []
+    for key in ("scope_summary", "default_scope", "scope"):
+        value = profile.get(key)
+        if isinstance(value, list):
+            raw_scopes.extend(value)
+        elif value:
+            raw_scopes.append(value)
+    for key in ("scope_summaries", "default_scopes", "scopes"):
+        value = profile.get(key)
+        if isinstance(value, list):
+            raw_scopes.extend(value)
+    return normalize_agent_scopes(raw_scopes)
+
+
+def agent_profile_prompt_projection(profile: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not isinstance(profile, dict):
+        return None
+    public_keys = {
+        "schema_version",
+        "agent_id",
+        "profile_role",
+        "scope_summary",
+        "default_scope",
+        "scope",
+        "scope_summaries",
+        "default_scopes",
+        "scopes",
+        "default_task_classes",
+        "vision_requirement",
+        "preferred_action_kinds",
+        "avoid_action_kinds",
+    }
+    projection = {key: value for key, value in profile.items() if key in public_keys}
+    projection["schema_version"] = PEER_AGENT_PROFILE_SCHEMA_VERSION
+    return projection or None
+
+
+def agent_prompt_command_args(*, agent_id: str | None, agent_scopes: list[str]) -> str:
+    parts: list[str] = []
+    if agent_id:
+        parts.extend(["--agent-id", agent_id])
+    for scope in agent_scopes:
+        parts.extend(["--agent-scope", scope])
+    return "".join(f" {shlex.quote(part)}" for part in parts)
+
+
+def build_peer_identity_required_error(
+    *,
+    goal_id: str,
+    cli_bin: str,
+    active_state_arg: str,
+    full: bool,
+    compact: bool,
+    brief: bool,
+    thin: bool,
+    registered_agents: list[str],
+) -> str:
+    mode_arg = (
+        " --thin"
+        if thin
+        else " --brief"
+        if brief
+        else " --compact"
+        if compact
+        else " --full"
+        if full
+        else ""
+    )
+    base = (
+        f"{cli_bin} heartbeat-prompt{mode_arg} "
+        f"--goal-id {shlex.quote(goal_id)}{active_state_arg}"
+    )
+    examples = "; ".join(
+        f"`{base} --agent-id {shlex.quote(agent)} "
+        "--agent-scope 'peer task claims and leases'`"
+        for agent in registered_agents[:2]
+    )
+    return (
+        "identity-aware peer heartbeat prompt required: "
+        f"coordination.registered_agents is configured for goal_id={goal_id!r}, "
+        "so automation prompts without --agent-id are not accepted. Regenerate each "
+        f"installed automation with its registered identity. Examples: {examples}."
+    )
+
+
+def render_peer_agent_scope_instruction(
+    *,
+    goal_id: str,
+    agent_id: str | None,
+    agent_scopes: list[str],
+    cli_bin: str,
+    compact: bool = False,
+    thin: bool = False,
+) -> str:
+    if not agent_id and not agent_scopes:
+        return ""
+    identity = agent_id or "<registered-agent-id>"
+    scope_text = "; ".join(agent_scopes) if agent_scopes else "registered peer lane"
+    scope_text = scope_text.rstrip(".!?")
+    claim_command = (
+        f"{cli_bin} todo claim --goal-id {goal_id} --todo-id <todo_id> "
+        f"--claimed-by {agent_id} --agent-id {agent_id}"
+        if agent_id
+        else f"{cli_bin} todo claim --goal-id {goal_id} --todo-id <todo_id> "
+        "--claimed-by <agent_id> --agent-id <agent_id>"
+    )
+    peer_rule = (
+        "You are an equal peer agent: claim or lease in-scope work; use an independent worktree "
+        "for repository writes; follow todo continuation policy. PR review is "
+        "user_action with a runnable successor; gate only exact merge/release/launch "
+        "authority. Task-scoped coordination grants no authority over other agents."
+    )
+    if thin:
+        return (
+            f"Equal peer `{identity}` (peer_v1); scope: {scope_text}. Claim/lease first; "
+            "independent repo worktree; todo continuation; no cross-agent authority; "
+            "no scope in todo metadata."
+        )
+    if compact:
+        return (
+            f"Agent identity and scope: agent_id `{identity}`; model: peer_v1; "
+            f"scope: {scope_text}. {peer_rule} Claim: `{claim_command}`. "
+            "Do not write scope into todo metadata."
+        )
+    return f"""Agent identity and scope:
+
+- agent_id: `{identity}`
+- agent_model: `peer_v1`
+- scope: {scope_text}
+
+{peer_rule}
+
+Before delivery, claim an in-scope open todo:
+
+```bash
+{claim_command}
+```
+
+If a todo is claimed or leased by another peer, choose another in-scope item or
+record no in-scope work internally. Only `NOTIFY` reports it; `DONT_NOTIFY` stays quiet.
+Scope belongs in the heartbeat prompt, not todo metadata.
+"""

loopx/control_plane/heartbeat/budget.py

@@ -0,0 +1,66 @@
+"""Heartbeat prompt budget helpers inside the heartbeat bounded context."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+INTERFACE_BUDGET_CHARS = {
+    "full": 12_000,
+    "compact": 6_200,
+    "brief": 3_500,
+    "thin": 1_900,
+    "visible_goal": 4_000,
+}
+NATIVE_GOAL_HOST_MAX_CHARS = INTERFACE_BUDGET_CHARS["visible_goal"]
+
+
+def heartbeat_prompt_mode(
+    *,
+    full: bool = False,
+    compact: bool = False,
+    brief: bool = False,
+    thin: bool = False,
+) -> str:
+    if full:
+        return "full"
+    if thin:
+        return "thin"
+    if brief:
+        return "brief"
+    if compact:
+        return "compact"
+    return "thin"
+
+
+def prompt_budget_text(text: str, *, goal_id: str, active_state: str) -> str:
+    return text.replace(goal_id, "<GOAL_ID>").replace(active_state, "<ACTIVE_STATE>")
+
+
+def build_interface_budget(
+    *,
+    task_body: str,
+    goal_id: str,
+    active_state: str,
+    full: bool = False,
+    compact: bool = False,
+    brief: bool = False,
+    thin: bool = False,
+    native_goal_host: bool = False,
+) -> dict[str, Any]:
+    mode = (
+        "visible_goal"
+        if native_goal_host
+        else heartbeat_prompt_mode(full=full, compact=compact, brief=brief, thin=thin)
+    )
+    budget_text = prompt_budget_text(task_body, goal_id=goal_id, active_state=active_state)
+    budget_chars = len(budget_text)
+    max_chars = INTERFACE_BUDGET_CHARS[mode]
+    return {
+        "mode": mode,
+        "char_count": len(task_body),
+        "line_count": len(task_body.splitlines()),
+        "budget_char_count": budget_chars,
+        "max_chars": max_chars,
+        "within_budget": budget_chars <= max_chars,
+    }