agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/workflow/model_usage.py

@@ -0,0 +1,106 @@
+"""Workflow enforcement for model-route usage receipts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError
+from agent_lifecycle.model_routing import validate_usage_receipt
+
+UNSAFE_CRITICAL_REVIEW_CLASSES = {"budget", "local-compact"}
+
+
+def validate_attempt_model_route(task: dict[str, Any]) -> None:
+    """Validate that a task route is executable before an attempt starts."""
+
+    route = task.get("modelRoute")
+    if not isinstance(route, dict) or not route:
+        return
+    model_class = _required_route_string(route, "modelClass")
+    if model_class == "no-model":
+        return
+    _required_route_string(route, "operationId")
+    _required_route_string(route, "decisionDigest")
+    if route.get("requiresUsageReceipt") is False:
+        raise LifecycleError(
+            "model-usage-receipt-required",
+            "model-backed routes must require usage receipts",
+        )
+    if route.get("criticalReview") is True and model_class in UNSAFE_CRITICAL_REVIEW_CLASSES:
+        raise LifecycleError(
+            "model-route-critical-downgrade",
+            "critical review route cannot use a budget or compact model class",
+            {"modelClass": model_class},
+        )
+
+
+def model_usage_receipt_required(task: dict[str, Any]) -> bool:
+    route = _attempt_route(task)
+    if route is None:
+        return False
+    model_class = route.get("modelClass")
+    if model_class == "no-model":
+        return False
+    return route.get("requiresUsageReceipt", True) is True
+
+
+def validate_task_model_usage_receipt(
+    state: dict[str, Any],
+    task: dict[str, Any],
+    receipt: dict[str, Any],
+    *,
+    budget_targets: dict[str, Any] | None = None,
+    fail_on_invalid: bool = True,
+) -> dict[str, Any]:
+    route = _attempt_route(task)
+    if route is None or not model_usage_receipt_required(task):
+        raise LifecycleError("unexpected-model-usage-receipt", "task attempt does not require a model usage receipt")
+    _require_lineage(state, task, receipt)
+    result = validate_usage_receipt(receipt, budget_targets=budget_targets, route_decision=route)
+    if result["status"] == "FAIL" and fail_on_invalid:
+        raise LifecycleError(
+            "model-usage-validation-failed",
+            "model usage receipt validation failed",
+            {"validation": result},
+        )
+    return result
+
+
+def _attempt_route(task: dict[str, Any]) -> dict[str, Any] | None:
+    route = task.get("attemptModelRoute")
+    if isinstance(route, dict) and route:
+        return route
+    route = task.get("modelRoute")
+    if isinstance(route, dict) and route:
+        return route
+    return None
+
+
+def _require_lineage(state: dict[str, Any], task: dict[str, Any], receipt: dict[str, Any]) -> None:
+    expected = {
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "taskId": task.get("id"),
+        "attempt": task.get("attempt"),
+        "planDigest": state.get("planDigest"),
+        "sourceRevision": state.get("sourceRevision"),
+    }
+    for key, value in expected.items():
+        if receipt.get(key) != value:
+            raise LifecycleError(
+                "model-usage-lineage-mismatch",
+                f"model usage receipt {key} mismatch",
+            )
+    route = _attempt_route(task) or {}
+    if receipt.get("routeDecisionDigest") != route.get("decisionDigest"):
+        raise LifecycleError(
+            "model-usage-lineage-mismatch",
+            "model usage receipt routeDecisionDigest mismatch",
+        )
+
+
+def _required_route_string(route: dict[str, Any], key: str) -> str:
+    value = route.get(key)
+    if not isinstance(value, str) or not value:
+        raise LifecycleError("invalid-model-route", f"modelRoute.{key} is required")
+    return value

agent_lifecycle/workflow/next_action.py

@@ -0,0 +1,86 @@
+"""Typed next-action projection for the managed lifecycle runner."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import canonical_digest
+from agent_lifecycle.workflow.query import next_action as workflow_next_action
+
+
+MODEL_CALLS_STARTED = False
+
+
+def build_managed_next_action(state: dict[str, Any]) -> dict[str, Any]:
+    """Return a host-owned next action without mutating workflow state."""
+
+    projected = workflow_next_action(state)
+    blockers = _blockers_for_projected_action(projected)
+    action = {
+        "schemaVersion": "agent-managed-lifecycle-next-action.v1",
+        "type": projected.get("type", "continue-phase"),
+        "status": "BLOCKED" if blockers else "READY",
+        "hostActionRequired": _host_action_required(projected),
+        "modelCallsStarted": MODEL_CALLS_STARTED,
+        "stateMutationRequired": _state_mutation_required(projected),
+        "projectedAction": projected,
+        "taskIds": list(projected.get("taskIds", [])) if isinstance(projected.get("taskIds"), list) else [],
+        "blockers": blockers,
+    }
+    return {**action, "actionDigest": canonical_digest(action)}
+
+
+def _host_action_required(projected: dict[str, Any]) -> bool:
+    action_type = projected.get("type")
+    return action_type in {
+        "launch-tasks",
+        "request-human-decision",
+        "record-budget-decision",
+        "record-external-action-receipt",
+        "request-execution-authorization",
+        "start-execution",
+        "run-final-audit",
+        "finalize-run",
+    }
+
+
+def _state_mutation_required(projected: dict[str, Any]) -> bool:
+    action_type = projected.get("type")
+    return action_type in {
+        "start-execution",
+        "record-budget-decision",
+        "record-external-action-receipt",
+        "request-execution-authorization",
+        "finalize-run",
+    }
+
+
+def _blockers_for_projected_action(projected: dict[str, Any]) -> list[dict[str, Any]]:
+    action_type = projected.get("type")
+    if action_type == "request-human-decision":
+        blocker = projected.get("blocker")
+        if isinstance(blocker, dict):
+            return [{
+                "code": str(blocker.get("code") or "workflow-blocked"),
+                "message": str(blocker.get("reason") or "workflow is blocked"),
+            }]
+        return [{"code": "workflow-blocked", "message": "workflow is blocked"}]
+    if action_type == "record-budget-decision":
+        blocker = projected.get("blocker")
+        if isinstance(blocker, dict):
+            return [{
+                "code": str(blocker.get("code") or "budget-decision-required"),
+                "message": str(blocker.get("reason") or "budget decision is required"),
+            }]
+        return [{"code": "budget-decision-required", "message": "budget decision is required"}]
+    if action_type == "record-external-action-receipt":
+        external_action = projected.get("externalAction")
+        action_id = external_action.get("actionId") if isinstance(external_action, dict) else None
+        return [{
+            "code": "external-action-receipt-required",
+            "message": "external action receipt is required",
+            "actionId": action_id,
+        }]
+    if action_type == "request-execution-authorization":
+        return [{"code": "execution-authorization-required", "message": "execution authorization is required"}]
+    return []

agent_lifecycle/workflow/operation_kernel.py

@@ -0,0 +1,98 @@
+"""Shared workflow operation commit kernel."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError
+from agent_lifecycle.workflow.events import append_event, event_log_path
+from agent_lifecycle.workflow.state import (
+    load_state,
+    now_iso,
+    record_operation,
+    require_expected_revision,
+    require_operation_unused,
+    write_state_replace,
+)
+
+
+def load_for_update(
+    state_path: Path,
+    *,
+    operation_id: str,
+    expected_revision: int,
+) -> dict[str, Any]:
+    state = load_state(state_path)
+    _require_no_split_brain(state_path, state)
+    require_expected_revision(state, expected_revision)
+    require_operation_unused(state, operation_id)
+    return state
+
+
+def _require_no_split_brain(state_path: Path, state: dict[str, Any]) -> None:
+    path = event_log_path(state_path, state)
+    if not path.exists():
+        return
+    last_event = _last_event(path)
+    if last_event is None:
+        return
+    event_revision = last_event.get("stateRevision")
+    if not isinstance(event_revision, int):
+        raise LifecycleError("invalid-workflow-event-log", "workflow event stateRevision is invalid")
+    if event_revision > state["stateRevision"]:
+        raise LifecycleError(
+            "workflow-split-brain",
+            "workflow event log is ahead of state",
+            {
+                "stateRevision": state["stateRevision"],
+                "eventRevision": event_revision,
+                "operationId": last_event.get("operationId"),
+                "eventType": last_event.get("eventType"),
+            },
+        )
+
+
+def _last_event(path: Path) -> dict[str, Any] | None:
+    last: dict[str, Any] | None = None
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise LifecycleError(
+                "invalid-workflow-event-log",
+                "workflow event log contains malformed JSON",
+                {"path": path.as_posix(), "line": line_number},
+            ) from exc
+        if not isinstance(event, dict):
+            raise LifecycleError(
+                "invalid-workflow-event-log",
+                "workflow event log entry must be an object",
+                {"path": path.as_posix(), "line": line_number},
+            )
+        last = event
+    return last
+
+
+def commit_state(
+    state_path: Path,
+    state: dict[str, Any],
+    *,
+    operation_id: str,
+    event_type: str,
+    payload: dict[str, Any],
+) -> None:
+    state["stateRevision"] += 1
+    state["updatedAt"] = now_iso()
+    record_operation(state, operation_id=operation_id, event_type=event_type)
+    append_event(
+        state_path=state_path,
+        state=state,
+        operation_id=operation_id,
+        event_type=event_type,
+        payload=payload,
+    )
+    write_state_replace(state_path, state)