loopx 0.4.8__py3-none-any.whl

loopx/control_plane/goals/goal_channel_projection.py

@@ -0,0 +1,560 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+
+GOAL_CHANNEL_PROJECTION_SCHEMA_VERSION = "goal_channel_projection_v0"
+
+RAW_MATERIAL_KEY_HINTS = (
+    "credential",
+    "local_path",
+    "log",
+    "raw",
+    "secret",
+    "stderr",
+    "stdout",
+    "token",
+    "trace",
+    "transcript",
+)
+
+PRIVATE_VALUE_HINTS = (
+    "/private/",
+    "/users/",
+    "credential" + "-value",
+    "secret" + "-value",
+    "token" + "-value",
+)
+
+
+def _as_mapping(value: Mapping[str, Any] | None) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _as_mappings(values: Sequence[Mapping[str, Any]] | None) -> list[dict[str, Any]]:
+    if not values:
+        return []
+    return [dict(item) for item in values if isinstance(item, Mapping)]
+
+
+def _private_value(value: Any) -> bool:
+    text = str(value).lower()
+    private_doc_host = ".".join(("byte" + "dance", "lark" + "office"))
+    return private_doc_host in text or any(hint in text for hint in PRIVATE_VALUE_HINTS)
+
+
+def compact_goal_channel_text(value: Any, *, limit: int = 180) -> str | None:
+    if value is None or _private_value(value):
+        return None
+    text = " ".join(str(value).split())
+    if not text:
+        return None
+    if len(text) <= limit:
+        return text
+    return text[: max(0, limit - 1)].rstrip() + "..."
+
+
+def _text(value: Any, *, limit: int = 180) -> str | None:
+    return compact_goal_channel_text(value, limit=limit)
+
+
+def _raw_material_keys(*values: Any) -> list[str]:
+    keys: set[str] = set()
+
+    def visit(value: Any) -> None:
+        if isinstance(value, Mapping):
+            for key, child in value.items():
+                lowered = str(key).lower()
+                if any(hint in lowered for hint in RAW_MATERIAL_KEY_HINTS):
+                    keys.add(str(key))
+                if _private_value(child):
+                    keys.add(str(key))
+                visit(child)
+        elif isinstance(value, list):
+            for child in value:
+                visit(child)
+
+    for value in values:
+        visit(value)
+    return sorted(keys)
+
+
+def _first_text(*values: Any, limit: int = 180) -> str | None:
+    for value in values:
+        text = _text(value, limit=limit)
+        if text:
+            return text
+    return None
+
+
+def _project_asset(status_item: Mapping[str, Any]) -> dict[str, Any]:
+    asset = status_item.get("project_asset")
+    return dict(asset) if isinstance(asset, Mapping) else {}
+
+
+def _source_refs(
+    *,
+    status_payload: Mapping[str, Any],
+    project_asset: Mapping[str, Any],
+    run_history_goal: Mapping[str, Any],
+    review_packet: Mapping[str, Any],
+) -> dict[str, Any]:
+    latest_runs = (
+        run_history_goal.get("latest_runs")
+        if isinstance(run_history_goal.get("latest_runs"), list)
+        else []
+    )
+    latest_run = latest_runs[0] if latest_runs and isinstance(latest_runs[0], Mapping) else {}
+    return {
+        "status_generated_at": _first_text(
+            status_payload.get("generated_at"),
+            project_asset.get("status_generated_at"),
+            limit=80,
+        ),
+        "active_state_updated_at": _first_text(
+            project_asset.get("state_updated_at"),
+            project_asset.get("active_state_updated_at"),
+            status_payload.get("state_updated_at"),
+            limit=80,
+        ),
+        "latest_run_generated_at": _first_text(latest_run.get("generated_at"), limit=80),
+        "review_packet_generated_at": _first_text(
+            review_packet.get("generated_at"),
+            review_packet.get("created_at"),
+            limit=80,
+        ),
+        "event_ledger_source": "run_history",
+    }
+
+
+def _compact_quota(quota_payload: Mapping[str, Any], project_asset: Mapping[str, Any]) -> dict[str, Any]:
+    source = quota_payload.get("quota") if isinstance(quota_payload.get("quota"), Mapping) else {}
+    if not source and isinstance(project_asset.get("quota"), Mapping):
+        source = project_asset["quota"]
+    compact: dict[str, Any] = {}
+    for key in ("state", "reason", "spend_policy", "spent_slots", "allowed_slots"):
+        value = _text(source.get(key), limit=220)
+        if value is not None:
+            compact[key] = value
+    return compact
+
+
+def _todo_candidates(summary: Mapping[str, Any]) -> list[dict[str, Any]]:
+    for key in (
+        "first_open_items",
+        "first_executable_items",
+        "open_items",
+        "backlog_items",
+        "items",
+    ):
+        values = summary.get(key)
+        if isinstance(values, list) and values:
+            return [dict(item) for item in values if isinstance(item, Mapping)]
+    return []
+
+
+def _compact_todo(item: Mapping[str, Any]) -> dict[str, Any] | None:
+    title = _first_text(item.get("title"), item.get("text"), limit=220)
+    if not title:
+        return None
+    compact: dict[str, Any] = {
+        "title": title,
+        "status": _first_text(item.get("status"), limit=40) or "open",
+    }
+    for key in (
+        "todo_id",
+        "priority",
+        "claimed_by",
+        "bound_agent",
+        "goal_bound",
+        "task_class",
+        "action_kind",
+        "task_repository",
+    ):
+        value = _text(item.get(key), limit=120)
+        if value:
+            compact[key] = value
+    return compact
+
+
+def _compact_todos(project_asset: Mapping[str, Any], role: str) -> list[dict[str, Any]]:
+    summary = project_asset.get(f"{role}_todos")
+    if not isinstance(summary, Mapping):
+        return []
+    compact: list[dict[str, Any]] = []
+    for item in _todo_candidates(summary):
+        todo = _compact_todo(item)
+        if todo:
+            compact.append(todo)
+    return compact
+
+
+def _user_gate_todos(user_todos: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        dict(todo)
+        for todo in user_todos
+        if todo.get("task_class") == "user_gate"
+        and todo.get("status") not in {"done", "closed", "resolved"}
+    ]
+
+
+def _open_gates(
+    *,
+    quota_payload: Mapping[str, Any],
+    project_asset: Mapping[str, Any],
+    user_todos: Sequence[Mapping[str, Any]],
+) -> list[dict[str, Any]]:
+    gates: list[dict[str, Any]] = []
+    user_gate_todos = _user_gate_todos(user_todos)
+    raw_gates = project_asset.get("open_gates")
+    if isinstance(raw_gates, list):
+        for gate in raw_gates:
+            if not isinstance(gate, Mapping):
+                continue
+            status = _first_text(gate.get("status"), gate.get("state"), limit=80)
+            if status in {None, "done", "closed", "resolved"}:
+                continue
+            compact = {
+                "gate_id": _first_text(gate.get("gate_id"), gate.get("id"), limit=120)
+                or "gate",
+                "kind": _first_text(gate.get("kind"), gate.get("type"), limit=80)
+                or "operator_gate",
+                "status": status or "open",
+            }
+            blocks = gate.get("blocks")
+            if isinstance(blocks, list):
+                compact["blocks"] = [_text(item, limit=120) for item in blocks if _text(item, limit=120)]
+            gates.append(compact)
+    interaction = quota_payload.get("interaction_contract")
+    user_channel = (
+        interaction.get("user_channel")
+        if isinstance(interaction, Mapping) and isinstance(interaction.get("user_channel"), Mapping)
+        else {}
+    )
+    if (user_channel.get("action_required") is True or user_gate_todos) and not gates:
+        blocking_todos = user_gate_todos or list(user_todos)
+        gates.append(
+            {
+                "gate_id": (
+                    "interaction_contract_user_channel"
+                    if user_channel.get("action_required") is True
+                    else "project_asset_user_gate_todos"
+                ),
+                "kind": (
+                    "user_channel"
+                    if user_channel.get("action_required") is True
+                    else "user_todo"
+                ),
+                "status": "action_required",
+                "blocks": [
+                    str(todo.get("todo_id") or todo.get("title") or "user_todo")
+                    for todo in blocking_todos
+                ],
+            }
+        )
+    return gates
+
+
+def _hard_lease_entries(
+    *,
+    runtime_root: Any,
+    goal_id: str,
+    agent_todos: Sequence[Mapping[str, Any]],
+) -> list[dict[str, Any]]:
+    """Best-effort read of the on-disk hard task-lease store.
+
+    Missing or empty lease directories stay silent because most goals never
+    use task leases. A corrupt or unreadable lease file degrades to a typed
+    note instead of failing the status projection.
+    """
+
+    if runtime_root is None:
+        return []
+    from pathlib import Path
+
+    from ..work_items.task_lease import (
+        TaskLeaseError,
+        lease_is_active,
+        read_lease,
+        task_lease_dir,
+    )
+
+    try:
+        lease_dir = task_lease_dir(
+            runtime_root=Path(runtime_root),
+            goal_id=str(goal_id),
+        )
+        lease_paths = sorted(lease_dir.glob("todo_*.json"))
+    except (TaskLeaseError, OSError, TypeError, ValueError):
+        return []
+    if not lease_paths:
+        return []
+    claim_by_todo: dict[str, str] = {}
+    for item in agent_todos:
+        todo_id = str(item.get("todo_id") or "").strip()
+        claimed_by = str(item.get("claimed_by") or "").strip()
+        if todo_id and claimed_by:
+            claim_by_todo[todo_id] = claimed_by
+    entries: list[dict[str, Any]] = []
+    for path in lease_paths:
+        try:
+            lease = read_lease(path)
+        except FileNotFoundError:
+            # Lease released between directory listing and read: nothing left
+            # to surface, so skip instead of mislabeling it as corrupt.
+            continue
+        except (TaskLeaseError, OSError):
+            entries.append(
+                {
+                    "todo_id": path.stem,
+                    "status": "hard_lease_unreadable",
+                    "reason": "corrupt_lease",
+                }
+            )
+            continue
+        if lease is None or not lease_is_active(lease):
+            continue
+        todo_id = _text(lease.get("todo_id"), limit=120) or path.stem
+        entry: dict[str, Any] = {"todo_id": todo_id, "status": "hard_lease"}
+        owner = _text(lease.get("owner"), limit=120)
+        if owner:
+            entry["owner_agent"] = owner
+        version = lease.get("version")
+        if isinstance(version, int):
+            entry["lease_version"] = version
+        expires_at = _text(lease.get("expires_at"), limit=80)
+        if expires_at:
+            entry["expires_at"] = expires_at
+        claimed_by = claim_by_todo.get(todo_id)
+        if owner and claimed_by and claimed_by != owner:
+            entry["reason"] = "owner_conflicts_with_claim"
+            entry["claimed_by"] = claimed_by
+        entries.append(entry)
+    return entries
+
+
+def _active_leases(
+    *,
+    active_leases: Sequence[Mapping[str, Any]] | None,
+    agent_todos: Sequence[Mapping[str, Any]],
+    runtime_root: Any = None,
+    goal_id: str = "",
+) -> list[dict[str, Any]]:
+    explicit = _as_mappings(active_leases)
+    if explicit:
+        source = explicit
+    else:
+        source = [
+            {
+                "todo_id": item.get("todo_id"),
+                "owner_agent": item.get("claimed_by"),
+                "status": "soft_claim",
+            }
+            for item in agent_todos
+            if item.get("claimed_by")
+        ]
+    compact: list[dict[str, Any]] = []
+    for item in source:
+        todo_id = _text(item.get("todo_id"), limit=120)
+        owner = _first_text(item.get("owner_agent"), item.get("claimed_by"), limit=120)
+        if not (todo_id or owner):
+            continue
+        lease: dict[str, Any] = {}
+        if todo_id:
+            lease["todo_id"] = todo_id
+        if owner:
+            lease["owner_agent"] = owner
+        for key in ("lease_until", "status"):
+            value = _text(item.get(key), limit=120)
+            if value:
+                lease[key] = value
+        write_scope = item.get("write_scope")
+        if isinstance(write_scope, list):
+            lease["write_scope"] = [
+                scope
+                for scope in (_text(value, limit=120) for value in write_scope)
+                if scope
+            ]
+        compact.append(lease)
+    compact.extend(
+        _hard_lease_entries(
+            runtime_root=runtime_root,
+            goal_id=goal_id,
+            agent_todos=agent_todos,
+        )
+    )
+    return compact
+
+
+def _compact_artifacts(artifacts: Sequence[Mapping[str, Any]] | None) -> list[dict[str, Any]]:
+    compact: list[dict[str, Any]] = []
+    for item in _as_mappings(artifacts):
+        artifact: dict[str, Any] = {}
+        for key in ("kind", "label", "path", "run_id"):
+            value = _text(item.get(key), limit=160)
+            if value:
+                artifact[key] = value
+        if artifact:
+            compact.append(artifact)
+    return compact
+
+
+def _recent_events(run_history_goal: Mapping[str, Any]) -> list[dict[str, Any]]:
+    runs = (
+        run_history_goal.get("latest_runs")
+        if isinstance(run_history_goal.get("latest_runs"), list)
+        else []
+    )
+    events: list[dict[str, Any]] = []
+    for run in runs[:5]:
+        if not isinstance(run, Mapping):
+            continue
+        event: dict[str, Any] = {}
+        for key in ("generated_at", "classification"):
+            value = _text(run.get(key), limit=160)
+            if value:
+                event[key] = value
+        summary = _first_text(run.get("health_check"), run.get("recommended_action"), limit=260)
+        if summary:
+            event["summary"] = summary
+        if event:
+            events.append(event)
+    return events
+
+
+def _source_warnings(raw_keys: Sequence[str]) -> list[dict[str, Any]]:
+    if not raw_keys:
+        return []
+    return [
+        {
+            "kind": "raw_or_private_material_omitted",
+            "key_names": list(raw_keys),
+            "message": (
+                "raw/private-looking fields were omitted; inspect the compact "
+                "source references instead of copying raw material into the "
+                "frontstage channel projection"
+            ),
+        }
+    ]
+
+
+def build_goal_channel_projection(
+    *,
+    goal_id: str,
+    status_item: Mapping[str, Any] | None = None,
+    status_payload: Mapping[str, Any] | None = None,
+    quota_payload: Mapping[str, Any] | None = None,
+    run_history_goal: Mapping[str, Any] | None = None,
+    review_packet: Mapping[str, Any] | None = None,
+    artifacts: Sequence[Mapping[str, Any]] | None = None,
+    active_leases: Sequence[Mapping[str, Any]] | None = None,
+    generated_at: str | None = None,
+    runtime_root: Any = None,
+) -> dict[str, Any]:
+    """Build a read-only channel snapshot for a LoopX goal.
+
+    The returned object is a frontstage projection, not a new source of truth.
+    It summarizes existing compact status/quota/history/todo surfaces and
+    records raw/private-looking inputs as warnings without copying their values.
+    """
+
+    status_item_dict = _as_mapping(status_item)
+    status_payload_dict = _as_mapping(status_payload)
+    quota_payload_dict = _as_mapping(quota_payload)
+    run_history_goal_dict = _as_mapping(run_history_goal)
+    review_packet_dict = _as_mapping(review_packet)
+    project_asset = _project_asset(status_item_dict)
+    user_todos = _compact_todos(project_asset, "user")
+    agent_todos = _compact_todos(project_asset, "agent")
+    raw_keys = _raw_material_keys(
+        status_item_dict,
+        status_payload_dict,
+        quota_payload_dict,
+        run_history_goal_dict,
+        review_packet_dict,
+        artifacts or [],
+        active_leases or [],
+    )
+
+    interaction = quota_payload_dict.get("interaction_contract")
+    user_channel = (
+        interaction.get("user_channel")
+        if isinstance(interaction, Mapping) and isinstance(interaction.get("user_channel"), Mapping)
+        else {}
+    )
+    agent_channel = (
+        interaction.get("agent_channel")
+        if isinstance(interaction, Mapping) and isinstance(interaction.get("agent_channel"), Mapping)
+        else {}
+    )
+    user_gate_todos = _user_gate_todos(user_todos)
+
+    projection = {
+        "schema_version": GOAL_CHANNEL_PROJECTION_SCHEMA_VERSION,
+        "goal_id": str(goal_id),
+        "mode": "read_only",
+        "generated_at": _text(generated_at, limit=80),
+        "display_name": _first_text(
+            project_asset.get("display_name"),
+            status_item_dict.get("display_name"),
+            status_item_dict.get("domain"),
+            goal_id,
+            limit=120,
+        ),
+        "source_refs": _source_refs(
+            status_payload=status_payload_dict,
+            project_asset=project_asset,
+            run_history_goal=run_history_goal_dict,
+            review_packet=review_packet_dict,
+        ),
+        "waiting_on": _first_text(
+            status_item_dict.get("waiting_on"),
+            quota_payload_dict.get("waiting_on"),
+            limit=80,
+        ),
+        "latest_status": _first_text(
+            status_item_dict.get("status"),
+            quota_payload_dict.get("status"),
+            limit=160,
+        ),
+        "next_action": _first_text(
+            quota_payload_dict.get("recommended_action"),
+            project_asset.get("next_action"),
+            status_item_dict.get("recommended_action"),
+            limit=260,
+        ),
+        "decision_frame": {
+            "user_action_required": bool(
+                user_channel.get("action_required") or user_gate_todos
+            ),
+            "agent_action_required": bool(agent_channel.get("must_attempt")),
+            "quiet_noop_allowed": bool(agent_channel.get("quiet_noop_allowed")),
+        },
+        "quota": _compact_quota(quota_payload_dict, project_asset),
+        "user_todos": user_todos,
+        "agent_todos": agent_todos,
+        "open_gates": _open_gates(
+            quota_payload=quota_payload_dict,
+            project_asset=project_asset,
+            user_todos=user_todos,
+        ),
+        "artifacts": _compact_artifacts(artifacts),
+        "active_leases": _active_leases(
+            active_leases=active_leases,
+            agent_todos=agent_todos,
+            runtime_root=runtime_root,
+            goal_id=str(goal_id),
+        ),
+        "recent_events": _recent_events(run_history_goal_dict),
+        "source_warnings": _source_warnings(raw_keys),
+        "truth_contract": {
+            "event_ledger_is_source_of_truth": True,
+            "projection_is_writable": False,
+            "write_authority": "none",
+            "recompute_rule": (
+                "refresh from LoopX status/quota/run history; do not "
+                "edit the channel projection as project truth"
+            ),
+        },
+    }
+    return {key: value for key, value in projection.items() if value is not None}