loopx 0.4.8__py3-none-any.whl

loopx/control_plane/work_items/issue_meta_surface.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Callable, Optional
+
+
+MAX_ISSUE_META_SURFACE_ITEMS = 8
+MAX_ISSUE_META_LABELS = 8
+
+ISSUE_META_SURFACE_SCHEMA_VERSION = "issue_meta_surface_v0"
+ISSUE_META_SURFACE_ITEM_SCHEMA_VERSION = "issue_meta_surface_item_v0"
+ISSUE_META_SURFACE_SECTION_HEADINGS = ("Issue Meta Surface", "Issue/PR Meta Surface")
+ISSUE_META_SURFACE_FIELD_PATTERN = re.compile(
+    r"(?P<key>[a-z_][a-z0-9_-]*)=(?P<value>\"[^\"]+\"|'[^']+'|[^\s]+)"
+)
+
+PublicSafeText = Callable[..., Optional[str]]
+SectionParser = Callable[[str, tuple[str, ...]], dict[str, list[str]]]
+
+
+def issue_meta_surface_blocks(lines: list[str]) -> list[str]:
+    blocks: list[str] = []
+    current: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith(("- ", "* ")):
+            if current:
+                blocks.append(" ".join(current))
+            current = [stripped[2:].strip()]
+            continue
+        if current and line.startswith((" ", "\t")):
+            current.append(stripped)
+    if current:
+        blocks.append(" ".join(current))
+    return blocks
+
+
+def issue_meta_public_value(
+    value: Any,
+    *,
+    public_safe_compact_text: PublicSafeText,
+    limit: int = 120,
+) -> str | None:
+    text = public_safe_compact_text(value, limit=limit)
+    if not text:
+        return None
+    if "<" in text or ">" in text:
+        return None
+    return text.strip("\"'")
+
+
+def issue_meta_list(
+    value: Any,
+    *,
+    public_safe_compact_text: PublicSafeText,
+    limit: int = MAX_ISSUE_META_LABELS,
+) -> list[str]:
+    if value is None:
+        return []
+    raw_values = re.split(r"[,;|]", str(value or ""))
+    items: list[str] = []
+    seen: set[str] = set()
+    for raw in raw_values:
+        item = issue_meta_public_value(raw, public_safe_compact_text=public_safe_compact_text, limit=80)
+        if not item or item in seen:
+            continue
+        seen.add(item)
+        items.append(item)
+        if len(items) >= limit:
+            break
+    return items
+
+
+def parse_issue_meta_surface_block(
+    block: str,
+    *,
+    index: int,
+    public_safe_compact_text: PublicSafeText,
+) -> dict[str, Any] | None:
+    fields: dict[str, str] = {}
+    for match in ISSUE_META_SURFACE_FIELD_PATTERN.finditer(block):
+        key = str(match.group("key") or "").strip().lower().replace("-", "_")
+        value = str(match.group("value") or "").strip().strip("\"'")
+        if key and value:
+            fields[key] = value
+    if not fields:
+        return None
+
+    item: dict[str, Any] = {
+        "schema_version": ISSUE_META_SURFACE_ITEM_SCHEMA_VERSION,
+        "index": index,
+    }
+    alias_map = {
+        "anchor_id": ("anchor_id", "id"),
+        "repo_handle": ("repo_handle", "repo"),
+        "issue_handle": ("issue_handle", "issue", "issue_or_pr", "issue_or_pr_handle"),
+        "owner_route": ("owner_route", "owner"),
+        "related_code_hint": ("related_code_hint", "related_code", "code"),
+        "validation_surface": ("validation_surface", "validation"),
+        "promotion_target": ("promotion_target", "promotion"),
+        "status": ("status",),
+        "freshness": ("freshness",),
+    }
+    for output_key, aliases in alias_map.items():
+        raw_value = next((fields[alias] for alias in aliases if alias in fields), None)
+        value = issue_meta_public_value(raw_value, public_safe_compact_text=public_safe_compact_text)
+        if value:
+            item[output_key] = value
+    labels = issue_meta_list(
+        fields.get("labels") or fields.get("label"),
+        public_safe_compact_text=public_safe_compact_text,
+    )
+    if labels:
+        item["labels"] = labels
+
+    required = ("repo_handle", "owner_route", "validation_surface", "promotion_target")
+    if not all(item.get(key) for key in required):
+        return None
+    if not item.get("anchor_id"):
+        repo = str(item.get("repo_handle") or "")
+        issue = str(item.get("issue_handle") or "")
+        anchor_basis = "|".join(part for part in (repo, issue, str(index)) if part)
+        item["anchor_id"] = f"issue_anchor_{hashlib.sha1(anchor_basis.encode('utf-8')).hexdigest()[:10]}"
+    return item
+
+
+def parse_issue_meta_surface(
+    state_text: str,
+    *,
+    section_parser: SectionParser,
+    public_safe_compact_text: PublicSafeText,
+) -> dict[str, Any] | None:
+    section_map = section_parser(state_text, ISSUE_META_SURFACE_SECTION_HEADINGS)
+    for heading in ISSUE_META_SURFACE_SECTION_HEADINGS:
+        lines = section_map.get(heading) or []
+        blocks = issue_meta_surface_blocks(lines)
+        items = [
+            item
+            for index, block in enumerate(blocks, start=1)
+            for item in [
+                parse_issue_meta_surface_block(
+                    block,
+                    index=index,
+                    public_safe_compact_text=public_safe_compact_text,
+                )
+            ]
+            if item
+        ]
+        if items:
+            return {
+                "schema_version": ISSUE_META_SURFACE_SCHEMA_VERSION,
+                "source_section": heading,
+                "item_count": len(items),
+                "items": items[:MAX_ISSUE_META_SURFACE_ITEMS],
+            }
+    return None

loopx/control_plane/work_items/lifecycle.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+
+CompactProjection = Callable[[Any], Optional[dict[str, Any]]]
+
+
+def ordered_lifecycle_flags(
+    flags: list[str],
+    *,
+    lifecycle_priority: tuple[str, ...],
+) -> list[str]:
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for flag in flags:
+        if not flag or flag in seen:
+            continue
+        seen.add(flag)
+        deduped.append(flag)
+    priority = {phase: index for index, phase in enumerate(lifecycle_priority)}
+    return sorted(deduped, key=lambda phase: priority.get(phase, len(priority)))
+
+
+def primary_lifecycle_phase(
+    flags: list[str],
+    *,
+    lifecycle_priority: tuple[str, ...],
+    fallback: str = "registered",
+) -> str:
+    ordered = ordered_lifecycle_flags(flags, lifecycle_priority=lifecycle_priority)
+    return ordered[0] if ordered else fallback
+
+
+def run_lifecycle_flags(
+    run: dict[str, Any] | None,
+    *,
+    lifecycle_priority: tuple[str, ...],
+    compact_human_reward: CompactProjection,
+    compact_operator_gate: CompactProjection,
+    compact_controller_readiness: CompactProjection,
+) -> list[str]:
+    if not isinstance(run, dict):
+        return []
+
+    flags: list[str] = []
+    classification = str(run.get("classification") or "")
+    if classification == "state_refreshed":
+        flags.append("refreshed")
+    elif classification == "read_only_project_map" or isinstance(run.get("project_map"), dict):
+        flags.append("mapped")
+    elif classification:
+        flags.append("adapter_inspected")
+    else:
+        flags.append("run_recorded")
+
+    if compact_human_reward(run.get("human_reward")):
+        flags.append("reward_judged")
+
+    operator_gate = compact_operator_gate(run.get("operator_gate"))
+    if operator_gate:
+        if operator_gate.get("decision") == "approve":
+            flags.append("operator_approved")
+        else:
+            flags.append("operator_gated")
+
+    readiness = compact_controller_readiness(run.get("controller_readiness"))
+    if readiness:
+        if readiness.get("decision_advisor_ready") or readiness.get("write_controller_ready"):
+            flags.append("controller_ready")
+        elif readiness.get("read_only_observer_ready") or readiness.get("classification"):
+            flags.append("controller_gated")
+
+    return ordered_lifecycle_flags(flags, lifecycle_priority=lifecycle_priority)
+
+
+def run_lifecycle_phase(
+    run: dict[str, Any] | None,
+    *,
+    lifecycle_priority: tuple[str, ...],
+    compact_human_reward: CompactProjection,
+    compact_operator_gate: CompactProjection,
+    compact_controller_readiness: CompactProjection,
+) -> str:
+    return primary_lifecycle_phase(
+        run_lifecycle_flags(
+            run,
+            lifecycle_priority=lifecycle_priority,
+            compact_human_reward=compact_human_reward,
+            compact_operator_gate=compact_operator_gate,
+            compact_controller_readiness=compact_controller_readiness,
+        ),
+        lifecycle_priority=lifecycle_priority,
+        fallback="run_recorded",
+    )
+
+
+def goal_lifecycle_fields(
+    goal: dict[str, Any],
+    current_run: dict[str, Any] | None,
+    *,
+    lifecycle_priority: tuple[str, ...],
+    connected_adapter_statuses: set[str],
+    compact_human_reward: CompactProjection,
+    compact_operator_gate: CompactProjection,
+    compact_controller_readiness: CompactProjection,
+) -> dict[str, Any]:
+    if current_run:
+        flags = run_lifecycle_flags(
+            current_run,
+            lifecycle_priority=lifecycle_priority,
+            compact_human_reward=compact_human_reward,
+            compact_operator_gate=compact_operator_gate,
+            compact_controller_readiness=compact_controller_readiness,
+        )
+        return {
+            "lifecycle_phase": primary_lifecycle_phase(
+                flags,
+                lifecycle_priority=lifecycle_priority,
+            ),
+            "lifecycle_flags": flags,
+        }
+
+    adapter_status = str(goal.get("adapter_status") or "")
+    status = str(goal.get("status") or "")
+    if adapter_status in connected_adapter_statuses:
+        flags = ["connected"]
+    elif "planned" in status or adapter_status == "planned":
+        flags = ["planned"]
+    else:
+        flags = ["registered"]
+    flags = ordered_lifecycle_flags(flags, lifecycle_priority=lifecycle_priority)
+    return {
+        "lifecycle_phase": primary_lifecycle_phase(
+            flags,
+            lifecycle_priority=lifecycle_priority,
+        ),
+        "lifecycle_flags": flags,
+    }

loopx/control_plane/work_items/operator_inbox.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+OPERATOR_INBOX_URGENCY_SCHEMA_VERSION = "operator_inbox_urgency_v0"
+CAPTURE_SCOPES = {"addressed_only", "configured_chat_all"}
+QUESTION_SIGNAL_PATTERN = re.compile(
+    r"[?？]|(?:请问|怎么|怎样|为何|为什么|是不是|是否|能否|可以吗|行吗|结论呢|回复吗)"
+)
+
+
+@dataclass(frozen=True)
+class OperatorInboxSourceContract:
+    config_schema_version: str
+    event_schema_version: str
+    processed_schema_version: str
+    message_id_pattern: re.Pattern[str]
+    event_id_pattern: re.Pattern[str]
+    sender_profile_pattern: re.Pattern[str]
+    required_sender_identity: str
+    reply_flag_field: str
+    operator_display_name_field: str
+    destination_field: str
+    destination_pattern: re.Pattern[str]
+
+
+def _safe_inbox_path(project: Path, raw_path: object) -> Path:
+    relative = PurePosixPath(str(raw_path or "").strip().replace("\\", "/"))
+    if (
+        not relative.parts
+        or relative.is_absolute()
+        or ".." in relative.parts
+        or relative.parts[:2] != (".loopx", "inbox")
+    ):
+        raise ValueError("operator inbox path must stay under .loopx/inbox")
+    resolved = (project / Path(*relative.parts)).resolve()
+    try:
+        resolved.relative_to(project)
+    except ValueError as exc:
+        raise ValueError("operator inbox path escapes the project") from exc
+    return resolved
+
+
+def _read_mapping(path: Path) -> Mapping[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, Mapping):
+        raise ValueError(f"operator inbox JSON must be an object: {path.name}")
+    return payload
+
+
+def _pending_events(
+    inbox: Path,
+    *,
+    source_contract: OperatorInboxSourceContract,
+) -> list[dict[str, Any]]:
+    processed_path = inbox / "processed.json"
+    processed: set[str] = set()
+    if processed_path.is_file():
+        processed_payload = _read_mapping(processed_path)
+        if (
+            processed_payload.get("schema_version")
+            != source_contract.processed_schema_version
+        ):
+            raise ValueError("operator inbox processed-state schema is invalid")
+        message_ids = processed_payload.get("message_ids")
+        if not isinstance(message_ids, list):
+            raise ValueError("operator inbox processed message_ids must be a list")
+        processed = {
+            str(value)
+            for value in message_ids
+            if source_contract.message_id_pattern.fullmatch(str(value))
+        }
+
+    events: dict[str, dict[str, Any]] = {}
+    for path in sorted(inbox.glob("*.json")) if inbox.is_dir() else []:
+        if path.name == "processed.json":
+            continue
+        try:
+            payload = _read_mapping(path)
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+        message_id = str(payload.get("message_id") or "").strip()
+        event_id = str(payload.get("event_id") or message_id).strip()
+        parent_id = str(payload.get("parent_id") or "").strip()
+        content = " ".join(str(payload.get("content") or "").split())[:1200]
+        if (
+            payload.get("schema_version") != source_contract.event_schema_version
+            or not source_contract.message_id_pattern.fullmatch(message_id)
+            or not source_contract.event_id_pattern.fullmatch(event_id)
+            or not content
+        ):
+            continue
+        events.setdefault(
+            message_id,
+            {
+                "message_id": message_id,
+                "create_time": str(payload.get("create_time") or "")[:40],
+                "content": content,
+                "reply_context_verified": payload.get("reply_context_verified") is True,
+                "reply_to_operator": bool(
+                    payload.get("reply_context_verified") is True
+                    and source_contract.message_id_pattern.fullmatch(parent_id)
+                    and payload.get(source_contract.reply_flag_field) is True
+                ),
+            },
+        )
+    return [
+        event for message_id, event in events.items() if message_id not in processed
+    ]
+
+
+def _parse_event_time(value: object) -> datetime | None:
+    raw = str(value or "").strip()
+    if not raw:
+        return None
+    if raw.isdigit():
+        number = int(raw)
+        if number > 10_000_000_000:
+            number //= 1000
+        try:
+            return datetime.fromtimestamp(number, tz=timezone.utc)
+        except (OverflowError, OSError, ValueError):
+            return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def operator_inbox_attention_kind(
+    event: Mapping[str, Any],
+    *,
+    operator_display_name: str,
+    capture_scope: str,
+) -> str | None:
+    if (
+        event.get("reply_context_verified") is True
+        and event.get("reply_to_operator") is True
+    ):
+        return "reply_to_operator"
+    content = str(event.get("content") or "")
+    folded = content.casefold()
+    operator_name = " ".join(operator_display_name.split()).casefold()
+    explicit_mention = bool(
+        operator_name and "@" in content and operator_name in folded
+    )
+    loopx_mention = "@" in content and "loopx" in folded
+    if capture_scope != "addressed_only" and not explicit_mention and not loopx_mention:
+        return None
+    if QUESTION_SIGNAL_PATTERN.search(content):
+        return "direct_question"
+    if explicit_mention or loopx_mention:
+        return "direct_mention"
+    return None
+
+
+def project_operator_inbox_urgency(
+    *,
+    project: str | Path,
+    config_path: str | Path,
+    source_contract: OperatorInboxSourceContract,
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    """Project provider-owned inbox files into a content-free control-plane read model."""
+
+    root = Path(project).expanduser().resolve()
+    path = Path(config_path).expanduser()
+    path = (path if path.is_absolute() else root / path).resolve()
+    try:
+        path.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("operator inbox config must stay inside the project") from exc
+    config = _read_mapping(path)
+    if config.get("schema_version") != source_contract.config_schema_version:
+        raise ValueError("operator inbox config schema is invalid")
+    enabled = config.get("enabled") is True
+    capture_scope = str(config.get("capture_scope") or "addressed_only").strip()
+    if capture_scope not in CAPTURE_SCOPES:
+        raise ValueError("operator inbox capture_scope is invalid")
+    reply = config.get("reply")
+    if reply is not None and not isinstance(reply, Mapping):
+        raise ValueError("operator inbox reply config must be an object")
+    reply = reply if isinstance(reply, Mapping) else {}
+    reply_enabled = reply.get("enabled") is True
+    operator_display_name = " ".join(
+        str(reply.get(source_contract.operator_display_name_field) or "").split()
+    )[:100]
+    sender_profile = str(reply.get("sender_profile") or "").strip()
+    sender_identity = str(reply.get("sender_identity") or "").strip()
+    destination = str(reply.get(source_contract.destination_field) or "").strip()
+    if reply_enabled and (
+        capture_scope != "configured_chat_all"
+        or not source_contract.sender_profile_pattern.fullmatch(sender_profile)
+        or sender_profile.lower() == "default"
+        or sender_identity != source_contract.required_sender_identity
+        or not operator_display_name
+        or not source_contract.destination_pattern.fullmatch(destination)
+    ):
+        raise ValueError(
+            "enabled operator inbox reply does not satisfy its source contract"
+        )
+    if not enabled:
+        return {
+            "schema_version": OPERATOR_INBOX_URGENCY_SCHEMA_VERSION,
+            "enabled": False,
+            "pending_count": 0,
+            "direct_question_count": 0,
+            "direct_mention_count": 0,
+            "reply_to_operator_count": 0,
+            "attention_required_count": 0,
+            "reply_due": False,
+            "local_private_content_returned": False,
+        }
+
+    inbox = _safe_inbox_path(root, config.get("inbox_dir"))
+    pending = _pending_events(
+        inbox,
+        source_contract=source_contract,
+    )
+    kinds = [
+        operator_inbox_attention_kind(
+            event,
+            operator_display_name=operator_display_name,
+            capture_scope=capture_scope,
+        )
+        for event in pending
+    ]
+    direct_question_count = kinds.count("direct_question")
+    direct_mention_count = kinds.count("direct_mention")
+    reply_to_operator_count = kinds.count("reply_to_operator")
+    attention_required_count = (
+        direct_question_count + direct_mention_count + reply_to_operator_count
+    )
+    parsed_times = [
+        parsed
+        for event in pending
+        if (parsed := _parse_event_time(event.get("create_time"))) is not None
+    ]
+    oldest = min(parsed_times) if parsed_times else None
+    current = (now or datetime.now(timezone.utc)).astimezone(timezone.utc)
+    return {
+        "schema_version": OPERATOR_INBOX_URGENCY_SCHEMA_VERSION,
+        "enabled": True,
+        "thread_complete": capture_scope == "configured_chat_all",
+        "pending_count": len(pending),
+        "direct_question_count": direct_question_count,
+        "direct_mention_count": direct_mention_count,
+        "reply_to_operator_count": reply_to_operator_count,
+        "attention_required_count": attention_required_count,
+        "oldest_pending_at": oldest.isoformat() if oldest else None,
+        "oldest_pending_age_seconds": (
+            max(0, int((current - oldest).total_seconds())) if oldest else None
+        ),
+        "reply_due": bool(attention_required_count > 0 and reply_enabled),
+        "local_private_content_returned": False,
+    }

loopx/control_plane/work_items/outcome_followthrough.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .delivery_outcome import (
+    DeliveryOutcome,
+    DeliveryTurnKind,
+    FOLLOWTHROUGH_REQUIRED_DELIVERY_OUTCOMES,
+    delivery_turn_kind_for_run,
+    normalize_delivery_outcome,
+)
+
+
+def build_outcome_followthrough_hint(
+    latest_run: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    """Build the follow-through obligation for a post-handoff latest run.
+
+    The helper intentionally preserves the quota payload shape. It only moves
+    the policy decision out of the quota builder so future rule changes can be
+    tested without touching the broader status/quota extraction path.
+    """
+
+    if not isinstance(latest_run, dict) or not latest_run:
+        return None
+
+    explicit_required = latest_run.get("outcome_followthrough_required") is True
+    delivery_outcome = normalize_delivery_outcome(latest_run.get("delivery_outcome"))
+    delivery_turn_kind = delivery_turn_kind_for_run(
+        latest_run,
+        delivery_outcome=delivery_outcome,
+    )
+    if delivery_outcome == DeliveryOutcome.PRIMARY_GOAL_OUTCOME:
+        return None
+    if (
+        not explicit_required
+        and delivery_turn_kind == DeliveryTurnKind.BLOCKER_WRITEBACK.value
+    ):
+        return None
+
+    classification = str(latest_run.get("classification") or "").strip()
+    kind_requires_followthrough = (
+        delivery_turn_kind == DeliveryTurnKind.CONTRACT_ONLY_PREPARATION.value
+    )
+    if (
+        not explicit_required
+        and delivery_outcome not in FOLLOWTHROUGH_REQUIRED_DELIVERY_OUTCOMES
+        and not kind_requires_followthrough
+    ):
+        return None
+
+    return {
+        "source": "post_handoff_latest_run",
+        "required": True,
+        "latest_classification": classification,
+        "latest_delivery_outcome": delivery_outcome.value if delivery_outcome else None,
+        "latest_delivery_turn_kind": delivery_turn_kind,
+        "obligation": "advance_primary_outcome_or_write_blocker",
+        "accepted_resolution_kinds": [
+            DeliveryTurnKind.PRODUCT_PATH_EXECUTION.value,
+            DeliveryTurnKind.COMPACT_EVIDENCE.value,
+            DeliveryTurnKind.BLOCKER_WRITEBACK.value,
+        ],
+        "spend_policy": (
+            "do not spend for another contract/preparation-only slice; spend only "
+            "after validated product-path evidence, benchmark/case evidence, or a "
+            "precise blocker writeback"
+        ),
+    }