nexus-coding-agent 0.1.0__py3-none-any.whl

nexus/application/observed_model_gateway.py

@@ -0,0 +1,194 @@
+"""Single Nexus-owned instrumentation seam around every real model call."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextvars import ContextVar
+from uuid import uuid4
+
+from nexus.application.execution_context import current_execution_context
+from nexus.application.execution_ledger import ToolExecutionLedger
+from nexus.application.model_call_context import current_model_call_phase
+from nexus.domain.model import (
+    ModelCallPhase,
+    ModelChunk,
+    ModelMessage,
+    ModelResponse,
+    TokenUsage,
+)
+from nexus.domain.ports.model_gateway import ModelGateway
+from nexus.domain.runtime_events import ModelCallFinished, ModelCallStarted, RuntimeEvent
+from nexus.errors import NexusError
+
+RuntimeEventEmitter = Callable[[RuntimeEvent], Awaitable[None]]
+
+_LAST_MODEL_CALL_ID: ContextVar[str | None] = ContextVar(
+    "nexus_last_model_call_id", default=None
+)
+
+
+class ObservedModelGateway:
+    """Emit safe model lifecycle events and own model counts and usage."""
+
+    def __init__(
+        self,
+        gateway: ModelGateway,
+        *,
+        emit: RuntimeEventEmitter,
+        ledger: ToolExecutionLedger,
+        provider: str | None,
+        model: str | None,
+    ) -> None:
+        self._gateway = gateway
+        self._emit = emit
+        self._ledger = ledger
+        self._provider = provider
+        self._model = model
+
+    def last_model_call_id(self) -> str:
+        model_call_id = _LAST_MODEL_CALL_ID.get()
+        if model_call_id is None:
+            raise RuntimeError("No model call completed in this async execution.")
+        return model_call_id
+
+    async def complete(self, messages: Sequence[ModelMessage]) -> ModelResponse:
+        context = current_execution_context()
+        phase = current_model_call_phase()
+        call_id = str(uuid4())
+        self._ledger.begin_model(context.run_id)
+        await self._emit_started(call_id, phase)
+        started = time.perf_counter()
+        try:
+            response = await self._gateway.complete(messages)
+        except Exception as exc:
+            usage = TokenUsage.unavailable()
+            self._ledger.record_model_usage(context.run_id, usage)
+            await self._emit_finished(
+                call_id,
+                phase,
+                success=False,
+                started=started,
+                usage=usage,
+                error_code=_safe_error_code(exc),
+            )
+            _LAST_MODEL_CALL_ID.set(call_id)
+            raise
+        usage = response.usage or TokenUsage.unavailable()
+        self._ledger.record_model_usage(context.run_id, usage)
+        await self._emit_finished(
+            call_id,
+            phase,
+            success=True,
+            started=started,
+            usage=usage,
+            error_code=None,
+        )
+        _LAST_MODEL_CALL_ID.set(call_id)
+        return response
+
+    async def stream(self, messages: Sequence[ModelMessage]) -> AsyncIterator[ModelChunk]:
+        context = current_execution_context()
+        phase = current_model_call_phase()
+        call_id = str(uuid4())
+        self._ledger.begin_model(context.run_id)
+        await self._emit_started(call_id, phase)
+        started = time.perf_counter()
+        usage: TokenUsage | None = None
+        try:
+            async for chunk in self._gateway.stream(messages):
+                if chunk.usage is not None:
+                    usage = chunk.usage
+                yield chunk
+        except asyncio.CancelledError:
+            normalized = usage or TokenUsage.unavailable()
+            self._ledger.record_model_usage(context.run_id, normalized)
+            await self._emit_finished(
+                call_id,
+                phase,
+                success=False,
+                started=started,
+                usage=normalized,
+                error_code="MODEL_CALL_CANCELLED",
+            )
+            _LAST_MODEL_CALL_ID.set(call_id)
+            raise
+        except GeneratorExit:
+            normalized = usage or TokenUsage.unavailable()
+            self._ledger.record_model_usage(context.run_id, normalized)
+            await self._emit_finished(
+                call_id,
+                phase,
+                success=False,
+                started=started,
+                usage=normalized,
+                error_code="MODEL_STREAM_CLOSED",
+            )
+            _LAST_MODEL_CALL_ID.set(call_id)
+            raise
+        except Exception as exc:
+            normalized = usage or TokenUsage.unavailable()
+            self._ledger.record_model_usage(context.run_id, normalized)
+            await self._emit_finished(
+                call_id,
+                phase,
+                success=False,
+                started=started,
+                usage=normalized,
+                error_code=_safe_error_code(exc),
+            )
+            _LAST_MODEL_CALL_ID.set(call_id)
+            raise
+        normalized = usage or TokenUsage.unavailable()
+        self._ledger.record_model_usage(context.run_id, normalized)
+        await self._emit_finished(
+            call_id,
+            phase,
+            success=True,
+            started=started,
+            usage=normalized,
+            error_code=None,
+        )
+        _LAST_MODEL_CALL_ID.set(call_id)
+
+    async def _emit_started(self, call_id: str, phase: ModelCallPhase) -> None:
+        context = current_execution_context()
+        await self._emit(
+            ModelCallStarted(
+                run_id=context.run_id,
+                session_id=context.session_id,
+                model_call_id=call_id,
+                phase=phase,
+                provider=self._provider,
+                model=self._model,
+            )
+        )
+
+    async def _emit_finished(
+        self,
+        call_id: str,
+        phase: ModelCallPhase,
+        *,
+        success: bool,
+        started: float,
+        usage: TokenUsage,
+        error_code: str | None,
+    ) -> None:
+        context = current_execution_context()
+        await self._emit(
+            ModelCallFinished(
+                run_id=context.run_id,
+                session_id=context.session_id,
+                model_call_id=call_id,
+                phase=phase,
+                success=success,
+                duration_ms=max(0, int((time.perf_counter() - started) * 1000)),
+                usage=usage,
+                error_code=error_code,
+            )
+        )
+
+
+def _safe_error_code(exc: Exception) -> str:
+    return exc.code if isinstance(exc, NexusError) else "MODEL_ERROR"

nexus/application/plan_approval_service.py

@@ -0,0 +1,250 @@
+"""Day 4 Plan approval persistence and evidence validation."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import UTC, datetime
+from uuid import UUID, uuid5
+
+from nexus.domain.approvals import ApprovalRequest
+from nexus.domain.planning import (
+    ApprovedPlanEvidence,
+    Plan,
+    PlanApprovalResumeInput,
+    PlanAuthorizationSource,
+    PlanStatus,
+    approval_summary,
+    derive_authorization_scope,
+)
+from nexus.domain.ports.approval_unit_of_work import (
+    ApprovalUnitOfWork,
+    ApprovalUnitOfWorkFactory,
+)
+from nexus.domain.tooling import ApprovalDecision, RiskLevel
+from nexus.errors import PermissionDeniedError, ToolExecutionError
+
+
+class PlanApprovalService:
+    def __init__(self, unit_of_work_factory: ApprovalUnitOfWorkFactory) -> None:
+        self._unit_of_work_factory = unit_of_work_factory
+
+    async def create_pending(self, plan: Plan) -> ApprovalRequest:
+        self._validate_created_plan(plan)
+        approval = self._request(plan, auto=False)
+        return await self._persist_idempotent(approval)
+
+    async def create_auto_approved(self, plan: Plan) -> ApprovalRequest:
+        self._validate_created_plan(plan)
+        approval = self._request(plan, auto=True)
+        return await self._persist_idempotent(approval)
+
+    async def persist_user_decision(
+        self,
+        approval_id: str,
+        decision: PlanApprovalResumeInput,
+    ) -> ApprovalRequest:
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                current = await unit_of_work.approvals.get(approval_id)
+                if current is None:
+                    raise ToolExecutionError(
+                        "The Plan approval does not exist.",
+                        code="APPROVAL_NOT_FOUND",
+                    )
+                await _validate_correlation(unit_of_work, current)
+                if current.operation != "approve_plan":
+                    raise PermissionDeniedError(
+                        "The approval does not authorize a Plan.",
+                        code="PLAN_APPROVAL_REQUIRED",
+                    )
+                if current.decision is not ApprovalDecision.PENDING:
+                    if current.decision is decision.decision:
+                        return current
+                    raise ToolExecutionError(
+                        "The Plan approval already has a terminal decision.",
+                        code="INVALID_APPROVAL_TRANSITION",
+                    )
+                updated = replace(
+                    current,
+                    decision=decision.decision,
+                    actor="user",
+                    reason=decision.reason,
+                    decided_at=datetime.now(UTC),
+                )
+                await unit_of_work.approvals.update(updated)
+                return updated
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not persist the Plan approval decision.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+    async def require_approved(
+        self,
+        evidence: ApprovedPlanEvidence,
+    ) -> ApprovalRequest:
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                approval = await unit_of_work.approvals.get(evidence.approval_id)
+                if approval is None:
+                    raise PermissionDeniedError(
+                        "Approved Plan evidence was not found.",
+                        code="PLAN_SCOPE_DENIED",
+                    )
+                try:
+                    await _validate_correlation(unit_of_work, approval)
+                except PermissionDeniedError as exc:
+                    raise PermissionDeniedError(
+                        "Approved Plan correlation is invalid.",
+                        code="PLAN_SCOPE_DENIED",
+                    ) from exc
+                expected = approval_summary(
+                    evidence.plan_id,
+                    evidence.plan_version,
+                    evidence.scope_digest,
+                )
+                if (
+                    approval.run_id != evidence.run_id
+                    or approval.session_id != evidence.session_id
+                    or approval.operation != "approve_plan"
+                    or approval.risk_level is not RiskLevel.WRITE
+                    or approval.resource_or_command_summary != expected
+                    or approval.decision is not ApprovalDecision.APPROVED
+                    or approval.actor not in {"user", "auto_policy"}
+                ):
+                    raise PermissionDeniedError(
+                        "Approved Plan evidence does not match persisted approval.",
+                        code="PLAN_SCOPE_DENIED",
+                    )
+                return approval
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not validate approved Plan evidence.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+    @staticmethod
+    def evidence(plan: Plan, approval: ApprovalRequest) -> ApprovedPlanEvidence:
+        if approval.decision is not ApprovalDecision.APPROVED or approval.decided_at is None:
+            raise PermissionDeniedError(
+                "The Plan has no approved evidence.",
+                code="PLAN_APPROVAL_REQUIRED",
+            )
+        return ApprovedPlanEvidence(
+            plan.plan_id,
+            plan.version,
+            plan.run_id,
+            plan.session_id,
+            PlanAuthorizationSource.AUTO_MODE
+            if approval.actor == "auto_policy"
+            else PlanAuthorizationSource.INTERACTIVE,
+            approval.approval_id,
+            plan.scope_digest,
+            plan.authorization_scope,
+            approval.decided_at,
+        )
+
+    @staticmethod
+    def activate(plan: Plan, approval: ApprovalRequest) -> Plan:
+        if approval.decision is ApprovalDecision.APPROVED and approval.decided_at is not None:
+            return replace(
+                plan,
+                status=PlanStatus.ACTIVE,
+                approval_status=ApprovalDecision.APPROVED,
+                approval_id=approval.approval_id,
+                approved_at=approval.decided_at,
+            )
+        return replace(
+            plan,
+            status=PlanStatus.FAILED,
+            approval_status=ApprovalDecision.DENIED,
+            approval_id=approval.approval_id,
+            approved_at=approval.decided_at,
+        )
+
+    @staticmethod
+    def _validate_created_plan(plan: Plan) -> None:
+        if plan.status is not PlanStatus.CREATED:
+            raise ToolExecutionError(
+                "Only a CREATED Plan may enter approval.",
+                code="INVALID_PLAN_OUTPUT",
+            )
+        if plan.authorization_scope != derive_authorization_scope(plan.steps):
+            raise ToolExecutionError(
+                "Plan authorization exceeds visible Plan steps.",
+                code="INVALID_PLAN_OUTPUT",
+            )
+
+    @staticmethod
+    def _request(plan: Plan, *, auto: bool) -> ApprovalRequest:
+        now = datetime.now(UTC)
+        return ApprovalRequest(
+            approval_id=str(uuid5(UUID(plan.plan_id), f"approval:v{plan.version}")),
+            run_id=plan.run_id,
+            session_id=plan.session_id,
+            operation="approve_plan",
+            risk_level=RiskLevel.WRITE,
+            resource_or_command_summary=approval_summary(
+                plan.plan_id,
+                plan.version,
+                plan.scope_digest,
+            ),
+            decision=ApprovalDecision.APPROVED if auto else ApprovalDecision.PENDING,
+            actor="auto_policy" if auto else "runtime",
+            reason="Approved by scoped Plan auto policy." if auto else None,
+            created_at=now,
+            decided_at=now if auto else None,
+        )
+
+    async def _persist_idempotent(self, approval: ApprovalRequest) -> ApprovalRequest:
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                await _validate_correlation(unit_of_work, approval)
+                existing = await unit_of_work.approvals.get(approval.approval_id)
+                if existing is not None:
+                    if _identity(existing) != _identity(approval):
+                        raise PermissionDeniedError(
+                            "Persisted Plan approval identity is inconsistent.",
+                            code="PLAN_APPROVAL_REQUIRED",
+                        )
+                    return existing
+                await unit_of_work.approvals.add(approval)
+                return approval
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not persist the Plan approval.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+
+def _identity(approval: ApprovalRequest) -> tuple[object, ...]:
+    return (
+        approval.approval_id,
+        approval.run_id,
+        approval.session_id,
+        approval.operation,
+        approval.risk_level,
+        approval.resource_or_command_summary,
+    )
+
+
+async def _validate_correlation(
+    unit_of_work: ApprovalUnitOfWork,
+    approval: ApprovalRequest,
+) -> None:
+    session = await unit_of_work.sessions.get(approval.session_id)
+    run = await unit_of_work.runs.get(approval.run_id)
+    if session is None or run is None or run.session_id != approval.session_id:
+        raise PermissionDeniedError(
+            "The Plan approval Run/Session correlation is invalid.",
+            code="APPROVAL_CORRELATION_DENIED",
+        )