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

nexus/application/tracing_dispatcher.py

@@ -0,0 +1,283 @@
+"""Failure-isolated per-execution FIFO lifecycle dispatcher for Tracer sinks."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+from nexus.application.execution_context import bind_execution_context
+from nexus.domain.observability import (
+    RunExecutionContext,
+    TelemetryEvent,
+    TraceRunFinish,
+    TraceRunStart,
+)
+from nexus.domain.ports.tracer import Tracer
+from nexus.domain.runtime_events import TraceFallback, TraceOperation, TraceSink
+
+WarningEmitter = Callable[
+    [str, TraceSink, TraceOperation, TraceFallback], Awaitable[None]
+]
+
+
+@dataclass(frozen=True, slots=True)
+class TracerSink:
+    kind: TraceSink
+    tracer: Tracer
+
+
+@dataclass(frozen=True, slots=True)
+class _Start:
+    value: TraceRunStart
+
+
+@dataclass(frozen=True, slots=True)
+class _Record:
+    value: TelemetryEvent
+
+
+@dataclass(frozen=True, slots=True)
+class _Finish:
+    value: TraceRunFinish
+
+
+_Control = _Start | _Record | _Finish
+
+
+@dataclass(slots=True)
+class _SinkExecution:
+    sink: TracerSink
+    context: RunExecutionContext
+    queue: asyncio.Queue[_Control]
+    worker: asyncio.Task[None] | None = None
+    healthy: bool = True
+    warned: bool = False
+
+
+class SafeTracerDispatcher:
+    """Give every enabled sink one FIFO worker and contain every adapter failure."""
+
+    def __init__(
+        self,
+        sinks: tuple[TracerSink, ...],
+        *,
+        warning_emitter: WarningEmitter,
+        queue_size: int = 256,
+        flush_timeout_seconds: float = 2.0,
+    ) -> None:
+        if queue_size < 1 or flush_timeout_seconds <= 0:
+            raise ValueError("Tracer queue and flush timeout must be positive.")
+        if len({sink.kind for sink in sinks}) != len(sinks):
+            raise ValueError("Tracer sink kinds must be unique.")
+        self._sinks = sinks
+        self._warning_emitter = warning_emitter
+        self._queue_size = queue_size
+        self._flush_timeout_seconds = flush_timeout_seconds
+        self._executions: dict[str, dict[TraceSink, _SinkExecution]] = {}
+        self._cleanup_tasks: dict[str, asyncio.Task[None]] = {}
+
+    def start_execution(self, start: TraceRunStart) -> None:
+        execution_id = start.context.execution_id
+        if execution_id in self._executions:
+            raise RuntimeError("Tracer execution already exists.")
+        states: dict[TraceSink, _SinkExecution] = {}
+        self._executions[execution_id] = states
+        for sink in self._sinks:
+            queue: asyncio.Queue[_Control] = asyncio.Queue(self._queue_size)
+            state = _SinkExecution(sink=sink, context=start.context, queue=queue)
+            state.worker = asyncio.create_task(self._work(execution_id, state))
+            states[sink.kind] = state
+            queue.put_nowait(_Start(start))
+
+    def record(self, event: TelemetryEvent) -> None:
+        states = self._executions.get(event.execution_id)
+        if states is None:
+            return
+        excluded = _warning_sink(event)
+        for kind, state in states.items():
+            if not state.healthy or kind is excluded:
+                continue
+            self._offer(execution_id=event.execution_id, state=state, item=_Record(event))
+
+    def finish_execution(self, finish: TraceRunFinish) -> None:
+        execution_id = finish.context.execution_id
+        states = self._executions.get(execution_id)
+        if states is None:
+            return
+        for state in states.values():
+            if state.healthy:
+                self._offer(
+                    execution_id=execution_id,
+                    state=state,
+                    item=_Finish(finish),
+                )
+            else:
+                _discard_queued(state.queue)
+                state.queue.put_nowait(_Finish(finish))
+        self._schedule_cleanup(execution_id)
+
+    async def drain_execution(self, execution_id: str) -> None:
+        task = self._cleanup_tasks.get(execution_id)
+        if task is None:
+            if execution_id not in self._executions:
+                return
+            task = self._schedule_cleanup(execution_id)
+        await asyncio.shield(task)
+
+    async def _drain_execution(self, execution_id: str) -> None:
+        states = self._executions.get(execution_id)
+        if not states:
+            self._executions.pop(execution_id, None)
+            return
+        workers = tuple(
+            state.worker for state in states.values() if state.worker is not None
+        )
+        if not workers:
+            self._executions.pop(execution_id, None)
+            return
+        _, pending = await asyncio.wait(
+            workers, timeout=self._flush_timeout_seconds
+        )
+        if pending:
+            for state in states.values():
+                if state.worker is not None and state.worker in pending:
+                    state.worker.cancel()
+                    await self._warn(
+                        execution_id,
+                        state,
+                        "TRACE_FLUSH_FAILED",
+                        TraceOperation.FLUSH,
+                    )
+        await asyncio.gather(*workers, return_exceptions=True)
+        self._executions.pop(execution_id, None)
+
+    async def close(self) -> None:
+        execution_ids = tuple(self._executions.keys() | self._cleanup_tasks.keys())
+        for execution_id in execution_ids:
+            await self.drain_execution(execution_id)
+
+    def _schedule_cleanup(self, execution_id: str) -> asyncio.Task[None]:
+        existing = self._cleanup_tasks.get(execution_id)
+        if existing is not None:
+            return existing
+        task = asyncio.create_task(self._run_cleanup(execution_id))
+        self._cleanup_tasks[execution_id] = task
+        return task
+
+    async def _run_cleanup(self, execution_id: str) -> None:
+        try:
+            await self._drain_execution(execution_id)
+        finally:
+            self._executions.pop(execution_id, None)
+            current = asyncio.current_task()
+            if self._cleanup_tasks.get(execution_id) is current:
+                self._cleanup_tasks.pop(execution_id, None)
+
+    def _offer(
+        self,
+        *,
+        execution_id: str,
+        state: _SinkExecution,
+        item: _Control,
+    ) -> None:
+        try:
+            state.queue.put_nowait(item)
+        except asyncio.QueueFull:
+            state.healthy = False
+            asyncio.create_task(
+                self._warn(
+                    execution_id,
+                    state,
+                    "TRACE_SINK_OVERFLOW",
+                    TraceOperation.RECORD,
+                )
+            )
+
+    async def _work(self, execution_id: str, state: _SinkExecution) -> None:
+        while True:
+            item = await state.queue.get()
+            if not state.healthy:
+                if isinstance(item, _Finish):
+                    return
+                continue
+            try:
+                if isinstance(item, _Start):
+                    await state.sink.tracer.start_run(item.value)
+                elif isinstance(item, _Record):
+                    await state.sink.tracer.record(item.value)
+                else:
+                    await state.sink.tracer.finish(item.value)
+                    return
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                state.healthy = False
+                operation = (
+                    TraceOperation.START
+                    if isinstance(item, _Start)
+                    else TraceOperation.RECORD
+                    if isinstance(item, _Record)
+                    else TraceOperation.FINISH
+                )
+                await self._warn(
+                    execution_id,
+                    state,
+                    "TRACE_SINK_FAILED",
+                    operation,
+                )
+                if isinstance(item, _Finish):
+                    return
+
+    async def _warn(
+        self,
+        execution_id: str,
+        state: _SinkExecution,
+        code: str,
+        operation: TraceOperation,
+    ) -> None:
+        if state.warned:
+            return
+        state.warned = True
+        try:
+            with bind_execution_context(state.context):
+                await self._warning_emitter(
+                    code,
+                    state.sink.kind,
+                    operation,
+                    self._fallback(execution_id, state.sink.kind),
+                )
+        except Exception:
+            return
+
+    def _fallback(self, execution_id: str, failed: TraceSink) -> TraceFallback:
+        states = self._executions.get(execution_id, {})
+        if failed is not TraceSink.CONSOLE:
+            console = states.get(TraceSink.CONSOLE)
+            if console is not None and console.healthy:
+                return TraceFallback.CONSOLE
+        if failed is not TraceSink.LANGSMITH:
+            langsmith = states.get(TraceSink.LANGSMITH)
+            if langsmith is not None and langsmith.healthy:
+                return TraceFallback.LANGSMITH
+        return TraceFallback.NOOP
+
+
+def _warning_sink(event: TelemetryEvent) -> TraceSink | None:
+    if event.event_type.value != "observability.warning":
+        return None
+    value = event.payload.get("sink")
+    if not isinstance(value, str):
+        return None
+    try:
+        return TraceSink(value)
+    except ValueError:
+        return None
+
+
+def _discard_queued(queue: asyncio.Queue[_Control]) -> None:
+    while True:
+        try:
+            queue.get_nowait()
+        except asyncio.QueueEmpty:
+            return

nexus/application/validation.py

@@ -0,0 +1,293 @@
+"""Deterministic Day 4 validation selection and governed execution."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Awaitable, Callable
+from uuid import uuid4
+
+from nexus.application.tool_runtime import ToolRuntime
+from nexus.domain.exploration import ExplorationResult, WorkingContext
+from nexus.domain.planning import ApprovedPlanEvidence, ChangedFile, Plan
+from nexus.domain.runtime_events import (
+    RuntimeEvent,
+    ValidationFinished,
+    ValidationStarted,
+)
+from nexus.domain.tooling import ToolInvocation, ToolResult
+from nexus.domain.validation import (
+    ValidationCheck,
+    ValidationCheckKind,
+    ValidationCheckResult,
+    ValidationConfidence,
+    ValidationPlan,
+    ValidationResult,
+    ValidationStatus,
+    aggregate_repairable,
+)
+from nexus.errors import ValidationError
+
+RuntimeEventEmitter = Callable[[RuntimeEvent], Awaitable[None]]
+
+_PREFIX_KINDS = {
+    "TEST": ValidationCheckKind.TEST,
+    "BUILD": ValidationCheckKind.BUILD,
+    "LINT": ValidationCheckKind.LINT,
+    "TYPE_CHECK": ValidationCheckKind.TYPE_CHECK,
+    "REPOSITORY_COMMAND": ValidationCheckKind.REPOSITORY_COMMAND,
+    "GENERATED_TARGETED_TEST": ValidationCheckKind.GENERATED_TARGETED_TEST,
+    "BASIC_EXECUTION": ValidationCheckKind.BASIC_EXECUTION,
+}
+_PRIORITY = {kind: index for index, kind in enumerate(_PREFIX_KINDS.values())}
+_CONCLUSIVE_CODE_KINDS = {
+    ValidationCheckKind.TEST,
+    ValidationCheckKind.BUILD,
+    ValidationCheckKind.GENERATED_TARGETED_TEST,
+    ValidationCheckKind.BASIC_EXECUTION,
+}
+
+
+class DeterministicValidationPlanner:
+    async def plan(
+        self,
+        *,
+        task: str,
+        plan: Plan,
+        exploration: ExplorationResult,
+        context: WorkingContext,
+        changed_files: tuple[ChangedFile, ...],
+    ) -> ValidationPlan:
+        del task, exploration, context
+        candidates: list[tuple[int, int, ValidationCheckKind, tuple[str, ...], str]] = []
+        for step in plan.steps:
+            if step.command_argv is None or step.command_cwd is None:
+                continue
+            kind = _kind_from_description(step.description)
+            candidates.append(
+                (_PRIORITY[kind], step.sequence, kind, step.command_argv, step.command_cwd)
+            )
+        candidates.sort(key=lambda item: (item[0], item[1]))
+
+        checks: list[ValidationCheck] = []
+        for _, _, kind, argv, cwd in candidates:
+            checks.append(
+                ValidationCheck(
+                    str(uuid4()),
+                    len(checks) + 1,
+                    kind,
+                    "shell",
+                    {"argv": list(argv), "cwd": cwd},
+                    "Explicit validation command in the approved Plan.",
+                    True,
+                )
+            )
+        read_only = (
+            not changed_files
+            and not plan.authorization_scope.allowed_write_actions
+            and not plan.authorization_scope.allowed_commands
+            and not candidates
+        )
+        if changed_files or read_only:
+            checks.append(
+                ValidationCheck(
+                    str(uuid4()),
+                    len(checks) + 1,
+                    ValidationCheckKind.DIFF_INSPECTION,
+                    "git_diff",
+                    {"staged": False},
+                    "Every changed-file run requires exact diff inspection.",
+                    True,
+                )
+            )
+        return ValidationPlan(tuple(checks))
+
+
+class ToolValidationRunner:
+    def __init__(
+        self,
+        tool_runtime: ToolRuntime,
+        *,
+        emit: RuntimeEventEmitter | None = None,
+    ) -> None:
+        self._tool_runtime = tool_runtime
+        self._emit = emit or _ignore_event
+
+    async def run(
+        self,
+        plan: ValidationPlan,
+        *,
+        run_id: str,
+        session_id: str,
+        authorization: ApprovedPlanEvidence,
+        repair_count: int,
+        changed: bool,
+    ) -> ValidationResult:
+        _validate_plan(plan, authorization)
+        started = time.perf_counter()
+        await self._emit(
+            ValidationStarted(
+                run_id=run_id,
+                session_id=session_id,
+                check_ids=tuple(check.check_id for check in plan.checks),
+                check_kinds=tuple(check.kind for check in plan.checks),
+            )
+        )
+        results: list[ValidationCheckResult] = []
+        for check in plan.checks:
+            invocation = ToolInvocation(
+                check.check_id,
+                check.tool_name,
+                check.arguments,
+                run_id,
+                session_id,
+            )
+            result = await self._tool_runtime.execute(
+                invocation,
+                authorization=authorization if check.tool_name == "shell" else None,
+            )
+            results.append(_check_result(check, result))
+
+        status = _aggregate_status(
+            tuple(results),
+            changed=changed,
+        )
+        confidence = _confidence(status, tuple(results))
+        repairable = aggregate_repairable(status, tuple(results))
+        validation = ValidationResult(
+            plan.checks,
+            tuple(results),
+            status,
+            confidence,
+            repairable,
+            repair_count,
+            _summary(status, tuple(results)),
+        )
+        await self._emit(
+            ValidationFinished(
+                run_id=run_id,
+                session_id=session_id,
+                validation_status=status,
+                confidence=confidence,
+                executed_check_count=len(results),
+                repair_count=repair_count,
+                duration_ms=max(0, int((time.perf_counter() - started) * 1000)),
+            )
+        )
+        return validation
+
+
+def _kind_from_description(description: str) -> ValidationCheckKind:
+    prefix, separator, _ = description.partition(":")
+    if separator:
+        kind = _PREFIX_KINDS.get(prefix.strip().upper())
+        if kind is not None:
+            return kind
+    return ValidationCheckKind.REPOSITORY_COMMAND
+
+
+def _check_result(check: ValidationCheck, result: ToolResult) -> ValidationCheckResult:
+    truncated = bool(
+        result.output
+        and (
+            result.output.get("truncated") is True
+            or result.output.get("output_truncated") is True
+        )
+    )
+    if result.success and not truncated:
+        status = ValidationStatus.PASS
+        summary = f"{check.kind.value} completed successfully."
+    elif result.error is not None and result.error.code == "COMMAND_EXIT_NONZERO":
+        status = ValidationStatus.FAIL
+        summary = f"{check.kind.value} completed with a non-zero exit."
+    else:
+        status = ValidationStatus.UNKNOWN
+        code = "NO_EVIDENCE" if result.error is None else result.error.code
+        summary = f"{check.kind.value} is inconclusive ({code})."
+    return ValidationCheckResult(check, status, result, summary)
+
+
+def _aggregate_status(
+    results: tuple[ValidationCheckResult, ...],
+    *,
+    changed: bool,
+) -> ValidationStatus:
+    required = tuple(result for result in results if result.check.required)
+    if any(result.status is ValidationStatus.FAIL for result in required):
+        return ValidationStatus.FAIL
+    if not required or any(result.status is ValidationStatus.UNKNOWN for result in required):
+        return ValidationStatus.UNKNOWN
+    has_diff = any(
+        result.check.kind is ValidationCheckKind.DIFF_INSPECTION
+        and result.status is ValidationStatus.PASS
+        for result in required
+    )
+    has_code_check = any(
+        result.check.kind in _CONCLUSIVE_CODE_KINDS
+        and result.status is ValidationStatus.PASS
+        for result in required
+    )
+    if changed and (not has_diff or not has_code_check):
+        return ValidationStatus.UNKNOWN
+    return ValidationStatus.PASS
+
+
+def _confidence(
+    status: ValidationStatus,
+    results: tuple[ValidationCheckResult, ...],
+) -> ValidationConfidence:
+    if status is ValidationStatus.UNKNOWN:
+        return ValidationConfidence.LOW
+    behavioral_count = sum(
+        result.check.kind in _CONCLUSIVE_CODE_KINDS
+        and result.status is ValidationStatus.PASS
+        for result in results
+    )
+    if status is ValidationStatus.PASS and behavioral_count > 1:
+        return ValidationConfidence.HIGH
+    return ValidationConfidence.MEDIUM
+
+
+def _summary(
+    status: ValidationStatus,
+    results: tuple[ValidationCheckResult, ...],
+) -> str:
+    counts = {
+        value: sum(result.status is value for result in results)
+        for value in ValidationStatus
+    }
+    return (
+        f"Validation {status.value}: {counts[ValidationStatus.PASS]} passed, "
+        f"{counts[ValidationStatus.FAIL]} failed, "
+        f"{counts[ValidationStatus.UNKNOWN]} unknown."
+    )
+
+
+async def _ignore_event(event: RuntimeEvent) -> None:
+    del event
+
+
+def _validate_plan(
+    plan: ValidationPlan,
+    authorization: ApprovedPlanEvidence,
+) -> None:
+    for check in plan.checks:
+        if check.kind is ValidationCheckKind.DIFF_INSPECTION:
+            valid = check.tool_name == "git_diff" and check.arguments == {
+                "staged": False
+            }
+        else:
+            argv = check.arguments.get("argv")
+            cwd = check.arguments.get("cwd")
+            valid = (
+                check.tool_name == "shell"
+                and isinstance(argv, list)
+                and all(isinstance(item, str) for item in argv)
+                and isinstance(cwd, str)
+                and (tuple(argv), cwd)
+                in authorization.authorization_scope.allowed_commands
+            )
+        if not valid:
+            raise ValidationError(
+                "A selected check violates the approved validation contract.",
+                code="VALIDATION_PLAN_INVALID",
+            )

nexus/config/__init__.py

@@ -0,0 +1,17 @@
+"""Typed runtime configuration and source resolution."""
+
+from nexus.config.loader import load_runtime_config
+from nexus.config.models import (
+    MCPServerConfig,
+    MCPToolRiskConfig,
+    MCPTransport,
+    RuntimeConfig,
+)
+
+__all__ = [
+    "MCPServerConfig",
+    "MCPToolRiskConfig",
+    "MCPTransport",
+    "RuntimeConfig",
+    "load_runtime_config",
+]