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

nexus/__init__.py

@@ -0,0 +1,4 @@
+"""Nexus coding-agent runtime."""
+
+__version__ = "0.1.0"
+

nexus/application/__init__.py

@@ -0,0 +1,2 @@
+"""Nexus application services."""
+

nexus/application/approval_service.py

@@ -0,0 +1,130 @@
+"""Day 3 approval persistence and Run/Session correlation rules."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from nexus.domain.approvals import ApprovalRequest
+from nexus.domain.ports.approval_unit_of_work import ApprovalUnitOfWork, ApprovalUnitOfWorkFactory
+from nexus.domain.tooling import ApprovalDecision, RiskLevel, ToolInvocation
+from nexus.errors import PermissionDeniedError, ToolExecutionError
+
+
+class ApprovalService:
+    def __init__(self, unit_of_work_factory: ApprovalUnitOfWorkFactory) -> None:
+        self._unit_of_work_factory = unit_of_work_factory
+
+    async def create_pending(
+        self,
+        invocation: ToolInvocation,
+        *,
+        risk_level: RiskLevel,
+        summary: str,
+    ) -> ApprovalRequest:
+        approval = ApprovalRequest(
+            approval_id=str(uuid4()),
+            run_id=invocation.run_id,
+            session_id=invocation.session_id,
+            operation=invocation.tool_name,
+            risk_level=risk_level,
+            resource_or_command_summary=summary,
+            decision=ApprovalDecision.PENDING,
+            actor="runtime",
+            reason=None,
+            created_at=datetime.now(UTC),
+            decided_at=None,
+        )
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                await _validate_correlation(unit_of_work, approval)
+                await unit_of_work.approvals.add(approval)
+            return approval
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not persist the pending approval.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+    async def persist_decision(self, approval: ApprovalRequest) -> ApprovalRequest:
+        if approval.decision is ApprovalDecision.PENDING:
+            raise ToolExecutionError(
+                "A pending approval cannot be persisted as a terminal decision.",
+                code="INVALID_APPROVAL_TRANSITION",
+            )
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                await _validate_correlation(unit_of_work, approval)
+                current = await unit_of_work.approvals.get(approval.approval_id)
+                if current is None:
+                    raise ToolExecutionError(
+                        "The approval does not exist.",
+                        code="APPROVAL_NOT_FOUND",
+                    )
+                if current.decision is not ApprovalDecision.PENDING:
+                    raise ToolExecutionError(
+                        "The approval already has a terminal decision.",
+                        code="INVALID_APPROVAL_TRANSITION",
+                    )
+                await unit_of_work.approvals.update(approval)
+            return approval
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not persist the approval decision.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+    async def record_denied(
+        self,
+        invocation: ToolInvocation,
+        *,
+        risk_level: RiskLevel,
+        summary: str,
+        reason: str,
+    ) -> ApprovalRequest:
+        now = datetime.now(UTC)
+        approval = ApprovalRequest(
+            approval_id=str(uuid4()),
+            run_id=invocation.run_id,
+            session_id=invocation.session_id,
+            operation=invocation.tool_name,
+            risk_level=risk_level,
+            resource_or_command_summary=summary,
+            decision=ApprovalDecision.DENIED,
+            actor="security_policy",
+            reason=reason,
+            created_at=now,
+            decided_at=now,
+        )
+        try:
+            async with self._unit_of_work_factory() as unit_of_work:
+                await _validate_correlation(unit_of_work, approval)
+                await unit_of_work.approvals.add(approval)
+            return approval
+        except (PermissionDeniedError, ToolExecutionError):
+            raise
+        except Exception as exc:
+            raise ToolExecutionError(
+                "Nexus could not persist the denied security decision.",
+                code="APPROVAL_PERSISTENCE_ERROR",
+                retryable=True,
+            ) from exc
+
+
+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 approval Run/Session correlation is invalid.",
+            code="APPROVAL_CORRELATION_DENIED",
+        )

nexus/application/diff_service.py

@@ -0,0 +1,177 @@
+"""Exact Day 4 final-diff collection through Tool Runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+from nexus.application.tool_runtime import ToolRuntime
+from nexus.domain.planning import ChangedFile, ChangeKind
+from nexus.domain.tooling import ToolInvocation, ToolResult
+
+
+@dataclass(frozen=True, slots=True)
+class FinalDiffEvidence:
+    diff: str | None
+    includes_preexisting_changes: bool
+    tool_results: tuple[ToolResult, ...]
+    error_code: str | None = None
+
+
+class FinalDiffCollector:
+    def __init__(self, tool_runtime: ToolRuntime) -> None:
+        self._tool_runtime = tool_runtime
+
+    async def collect(
+        self,
+        *,
+        run_id: str,
+        session_id: str,
+        changed_files: tuple[ChangedFile, ...],
+        initial_git_status: ToolResult | None,
+    ) -> FinalDiffEvidence:
+        if not changed_files:
+            return FinalDiffEvidence(
+                "",
+                _dirty(initial_git_status),
+                (),
+            )
+        if initial_git_status is None or not _exact_success(initial_git_status):
+            return FinalDiffEvidence(None, False, (), "DIFF_UNAVAILABLE")
+        results: list[ToolResult] = []
+
+        async def invoke(name: str, arguments: dict[str, object]) -> ToolResult:
+            result = await self._tool_runtime.execute(
+                ToolInvocation(str(uuid4()), name, arguments, run_id, session_id)
+            )
+            results.append(result)
+            return result
+
+        status = await invoke("git_status", {})
+        tracked = await invoke("git_diff", {"staged": False})
+        if not _exact_success(status) or not _exact_success(tracked):
+            return FinalDiffEvidence(
+                None,
+                _dirty(initial_git_status),
+                tuple(results),
+                "DIFF_UNAVAILABLE",
+            )
+        untracked = _untracked_paths(status)
+        if any(
+            changed.change_kind is ChangeKind.MODIFIED and changed.path in untracked
+            for changed in changed_files
+        ):
+            return FinalDiffEvidence(
+                None,
+                _dirty(initial_git_status),
+                tuple(results),
+                "DIFF_UNAVAILABLE",
+            )
+        tracked_text = _stdout(tracked)
+        new_patches: list[str] = []
+        for changed in changed_files:
+            if changed.change_kind is not ChangeKind.ADDED:
+                continue
+            content = await self._read_complete(
+                changed.path,
+                run_id=run_id,
+                session_id=session_id,
+                results=results,
+            )
+            if content is None:
+                return FinalDiffEvidence(
+                    None,
+                    _dirty(initial_git_status),
+                    tuple(results),
+                    "DIFF_UNAVAILABLE",
+                )
+            new_patches.append(_new_file_patch(changed.path, content))
+        pieces = [piece for piece in (tracked_text, *new_patches) if piece]
+        return FinalDiffEvidence(
+            "\n".join(piece.rstrip("\n") for piece in pieces) + ("\n" if pieces else ""),
+            _dirty(initial_git_status),
+            tuple(results),
+        )
+
+    async def _read_complete(
+        self,
+        path: str,
+        *,
+        run_id: str,
+        session_id: str,
+        results: list[ToolResult],
+    ) -> str | None:
+        chunks: list[str] = []
+        start_line = 1
+        while True:
+            result = await self._tool_runtime.execute(
+                ToolInvocation(
+                    str(uuid4()),
+                    "read_file",
+                    {"path": path, "start_line": start_line, "max_lines": 400},
+                    run_id,
+                    session_id,
+                )
+            )
+            results.append(result)
+            if not result.success or result.output is None:
+                return None
+            content = result.output.get("content")
+            end_line = result.output.get("end_line")
+            if not isinstance(content, str) or not isinstance(end_line, int):
+                return None
+            chunks.append(content)
+            if result.output.get("truncated") is not True:
+                return "".join(chunks)
+            if end_line < start_line:
+                return None
+            start_line = end_line + 1
+
+
+def _exact_success(result: ToolResult) -> bool:
+    return bool(
+        result.success
+        and result.output is not None
+        and result.output.get("truncated") is not True
+    )
+
+
+def _stdout(result: ToolResult) -> str:
+    value = None if result.output is None else result.output.get("stdout")
+    return value if isinstance(value, str) else ""
+
+
+def _dirty(result: ToolResult | None) -> bool:
+    if result is None or not _exact_success(result):
+        return False
+    return any(
+        line.strip() and not line.startswith("## ")
+        for line in _stdout(result).splitlines()
+    )
+
+
+def _untracked_paths(result: ToolResult) -> set[str]:
+    return {
+        line[3:]
+        for line in _stdout(result).splitlines()
+        if line.startswith("?? ") and not line[3:].startswith('"')
+    }
+
+
+def _new_file_patch(path: str, content: str) -> str:
+    lines = content.splitlines(keepends=True)
+    count = len(lines)
+    header = (
+        f"diff --git a/{path} b/{path}\n"
+        "new file mode 100644\n"
+        "--- /dev/null\n"
+        f"+++ b/{path}\n"
+        f"@@ -0,0 +1,{count} @@\n"
+    )
+    body = "".join(
+        f"+{line}" if line.endswith(("\n", "\r")) else f"+{line}\n"
+        for line in lines
+    )
+    if lines and not lines[-1].endswith(("\n", "\r")):
+        body += "\\n"
+    return header + body

nexus/application/event_publisher.py

@@ -0,0 +1,180 @@
+"""In-process Day 8 live event publisher with isolated execution streams."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from nexus.application.execution_context import current_execution_context
+from nexus.domain.observability import RunExecutionContext
+from nexus.domain.ports.events import EventSubscriber, EventSubscription
+from nexus.domain.runtime_events import (
+    ApprovalRequested,
+    ErrorOccurred,
+    FinalResult,
+    RunInterrupted,
+    RuntimeEvent,
+)
+
+_END = object()
+
+
+@dataclass(frozen=True, slots=True)
+class PublishedObservation:
+    """Private metadata copied at the synchronous publication boundary."""
+
+    context: RunExecutionContext
+    sequence: int
+
+
+_OBSERVATION: ContextVar[PublishedObservation | None] = ContextVar(
+    "nexus_published_observation", default=None
+)
+
+
+def current_published_observation() -> PublishedObservation:
+    observation = _OBSERVATION.get()
+    if observation is None:
+        raise RuntimeError("No published RuntimeEvent observation is bound.")
+    return observation
+
+
+@dataclass(slots=True)
+class _ExecutionStream:
+    context: RunExecutionContext
+    queue: asyncio.Queue[RuntimeEvent | object]
+    sequence: int = 0
+    terminal_published: bool = False
+
+
+class _Subscription(EventSubscription):
+    def __init__(
+        self, publisher: InProcessEventPublisher, subscriber: EventSubscriber
+    ) -> None:
+        self._publisher = publisher
+        self._subscriber = subscriber
+        self._closed = False
+
+    async def aclose(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._publisher._unsubscribe(self._subscriber)
+
+
+class InProcessEventPublisher:
+    """Required lossless live lane plus bounded subscriber handoff callbacks."""
+
+    def __init__(self) -> None:
+        self._subscribers: list[EventSubscriber] = []
+        self._streams: dict[str, _ExecutionStream] = {}
+        self._seen_plan_approvals: dict[str, set[str]] = {}
+
+    def subscribe(self, subscriber: EventSubscriber) -> EventSubscription:
+        if subscriber not in self._subscribers:
+            self._subscribers.append(subscriber)
+        return _Subscription(self, subscriber)
+
+    def open_execution(self, context: RunExecutionContext) -> None:
+        if context.execution_id in self._streams:
+            raise RuntimeError("Execution stream already exists.")
+        self._streams[context.execution_id] = _ExecutionStream(
+            context=context,
+            queue=asyncio.Queue(),
+        )
+        self._seen_plan_approvals[context.execution_id] = set()
+
+    async def publish(self, event: RuntimeEvent) -> None:
+        context = current_execution_context()
+        stream = self._streams.get(context.execution_id)
+        if stream is None:
+            raise RuntimeError("Execution stream is not open.")
+        if stream.terminal_published:
+            raise RuntimeError("Cannot publish after a terminal RuntimeEvent.")
+        if event.run_id != context.run_id or event.session_id != context.session_id:
+            raise ValueError("RuntimeEvent identity does not match execution context.")
+        if isinstance(event, ApprovalRequested) and event.plan_id is not None:
+            seen = self._seen_plan_approvals[context.execution_id]
+            if event.approval_id in seen:
+                return
+            seen.add(event.approval_id)
+
+        stream.sequence += 1
+        observation = PublishedObservation(context=context, sequence=stream.sequence)
+        stream.queue.put_nowait(event)
+        token = _OBSERVATION.set(observation)
+        try:
+            for subscriber in tuple(self._subscribers):
+                try:
+                    await subscriber.on_event(event)
+                except Exception:
+                    continue
+        finally:
+            _OBSERVATION.reset(token)
+
+        if _is_terminal(event):
+            stream.terminal_published = True
+            stream.queue.put_nowait(_END)
+
+    emit = publish
+
+    async def events(self, execution_id: str) -> AsyncIterator[RuntimeEvent]:
+        stream = self._streams.get(execution_id)
+        if stream is None:
+            raise RuntimeError("Execution stream is not open.")
+        while True:
+            item = await stream.queue.get()
+            if item is _END:
+                return
+            if not isinstance(item, RuntimeEvent):
+                raise RuntimeError("Invalid live event queue item.")
+            yield item
+
+    def close_execution(self, execution_id: str) -> None:
+        stream = self._streams.pop(execution_id, None)
+        self._seen_plan_approvals.pop(execution_id, None)
+        if stream is not None and not stream.terminal_published:
+            stream.queue.put_nowait(_END)
+
+    @asynccontextmanager
+    async def execution(
+        self, context: RunExecutionContext
+    ) -> AsyncIterator[AsyncIterator[RuntimeEvent]]:
+        self.open_execution(context)
+        try:
+            yield self.events(context.execution_id)
+        finally:
+            self.close_execution(context.execution_id)
+
+    def _unsubscribe(self, subscriber: EventSubscriber) -> None:
+        try:
+            self._subscribers.remove(subscriber)
+        except ValueError:
+            pass
+
+
+def _is_terminal(event: RuntimeEvent) -> bool:
+    return isinstance(event, (FinalResult, RunInterrupted, ErrorOccurred))
+
+
+class LiveRuntimeEventBridge:
+    """Publish graph progress live while deferring its terminal result to Runtime."""
+
+    def __init__(self, publisher: InProcessEventPublisher) -> None:
+        self._publisher = publisher
+        self._terminals: dict[str, FinalResult] = {}
+
+    async def emit(self, event: RuntimeEvent) -> None:
+        if isinstance(event, FinalResult):
+            if event.run_id in self._terminals:
+                raise RuntimeError("Graph emitted multiple final results.")
+            self._terminals[event.run_id] = event
+            return
+        await self._publisher.publish(event)
+
+    def drain(self, run_id: str) -> tuple[RuntimeEvent, ...]:
+        terminal = self._terminals.pop(run_id, None)
+        return () if terminal is None else (terminal,)

nexus/application/execution_context.py

@@ -0,0 +1,29 @@
+"""Context-local Day 8 execution identity propagation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from nexus.domain.observability import RunExecutionContext
+
+_EXECUTION_CONTEXT: ContextVar[RunExecutionContext | None] = ContextVar(
+    "nexus_run_execution_context", default=None
+)
+
+
+@contextmanager
+def bind_execution_context(context: RunExecutionContext) -> Iterator[None]:
+    token = _EXECUTION_CONTEXT.set(context)
+    try:
+        yield
+    finally:
+        _EXECUTION_CONTEXT.reset(token)
+
+
+def current_execution_context() -> RunExecutionContext:
+    context = _EXECUTION_CONTEXT.get()
+    if context is None:
+        raise RuntimeError("No RunExecutionContext is bound to this async execution.")
+    return context

nexus/application/execution_ledger.py

@@ -0,0 +1,126 @@
+"""In-process Day 4 event and Tool-attempt ledgers shared by composed services."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from nexus.domain.model import TokenUsage, TokenUsageAggregate
+from nexus.domain.runtime_events import ApprovalRequested, RuntimeEvent
+from nexus.domain.tooling import ToolInvocation, ToolResult
+
+
+class ToolExecutionLedger:
+    def __init__(self) -> None:
+        self._counts: dict[str, int] = defaultdict(int)
+        self._model_counts: dict[str, int] = defaultdict(int)
+        self._step_counts: dict[str, int] = defaultdict(int)
+        self._repair_counts: dict[str, int] = defaultdict(int)
+        self._token_usage: dict[str, TokenUsageAggregate] = defaultdict(
+            TokenUsageAggregate
+        )
+        self._results: dict[str, list[ToolResult]] = defaultdict(list)
+        self._restored_runs: set[str] = set()
+
+    def restore(
+        self,
+        run_id: str,
+        *,
+        tool_call_count: int,
+        model_call_count: int,
+        step_count: int,
+        repair_count: int,
+        tool_results: tuple[ToolResult, ...],
+        token_usage: TokenUsageAggregate | None = None,
+    ) -> None:
+        """Merge one durable checkpoint snapshot into this process-local ledger."""
+
+        if run_id not in self._restored_runs:
+            self._counts[run_id] += tool_call_count
+            self._model_counts[run_id] += model_call_count
+            self._step_counts[run_id] += step_count
+            self._repair_counts[run_id] += repair_count
+            if token_usage is not None:
+                self._token_usage[run_id] = token_usage
+            current_results = self._results[run_id]
+            checkpoint_ids = {item.invocation_id for item in tool_results}
+            self._results[run_id] = [
+                *tool_results,
+                *(
+                    item
+                    for item in current_results
+                    if item.invocation_id not in checkpoint_ids
+                ),
+            ]
+            self._restored_runs.add(run_id)
+            return
+
+        self._counts[run_id] = max(self._counts[run_id], tool_call_count)
+        self._model_counts[run_id] = max(
+            self._model_counts[run_id], model_call_count
+        )
+        self._step_counts[run_id] = max(self._step_counts[run_id], step_count)
+        self._repair_counts[run_id] = max(self._repair_counts[run_id], repair_count)
+        known_ids = {item.invocation_id for item in self._results[run_id]}
+        missing_results = [
+            item for item in tool_results if item.invocation_id not in known_ids
+        ]
+        if missing_results:
+            self._results[run_id] = [*missing_results, *self._results[run_id]]
+
+    def begin(self, invocation: ToolInvocation) -> None:
+        self._counts[invocation.run_id] += 1
+
+    def record(self, invocation: ToolInvocation, result: ToolResult) -> None:
+        self._results[invocation.run_id].append(result)
+
+    def count(self, run_id: str) -> int:
+        return self._counts[run_id]
+
+    def begin_model(self, run_id: str) -> None:
+        self._model_counts[run_id] += 1
+
+    def model_count(self, run_id: str) -> int:
+        return self._model_counts[run_id]
+
+    def record_model_usage(self, run_id: str, usage: TokenUsage) -> None:
+        self._token_usage[run_id] = self._token_usage[run_id].add(usage)
+
+    def token_usage(self, run_id: str) -> TokenUsageAggregate:
+        return self._token_usage[run_id]
+
+    def begin_step(self, run_id: str) -> None:
+        self._step_counts[run_id] += 1
+
+    def step_count(self, run_id: str) -> int:
+        return self._step_counts[run_id]
+
+    def begin_repair(self, run_id: str) -> None:
+        self._repair_counts[run_id] += 1
+
+    def repair_count(self, run_id: str) -> int:
+        return self._repair_counts[run_id]
+
+    def results(self, run_id: str) -> tuple[ToolResult, ...]:
+        return tuple(self._results[run_id])
+
+
+class RuntimeEventBuffer:
+    def __init__(self) -> None:
+        self._events: dict[str, list[RuntimeEvent]] = defaultdict(list)
+        self._seen_plan_approvals: set[str] = set()
+
+    async def emit(self, event: RuntimeEvent) -> None:
+        if isinstance(event, ApprovalRequested) and event.plan_id is not None:
+            if event.approval_id in self._seen_plan_approvals:
+                return
+            self._seen_plan_approvals.add(event.approval_id)
+        self._events[event.run_id].append(event)
+
+    def drain(self, run_id: str) -> tuple[RuntimeEvent, ...]:
+        events = tuple(self._events.pop(run_id, ()))
+        self._seen_plan_approvals.difference_update(
+            event.approval_id
+            for event in events
+            if isinstance(event, ApprovalRequested) and event.plan_id is not None
+        )
+        return events

nexus/application/model_call_context.py

@@ -0,0 +1,29 @@
+"""Context-local semantic phase for the next real ModelGateway invocation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from nexus.domain.model import ModelCallPhase
+
+_MODEL_CALL_PHASE: ContextVar[ModelCallPhase | None] = ContextVar(
+    "nexus_model_call_phase", default=None
+)
+
+
+@contextmanager
+def bind_model_call_phase(phase: ModelCallPhase) -> Iterator[None]:
+    token = _MODEL_CALL_PHASE.set(phase)
+    try:
+        yield
+    finally:
+        _MODEL_CALL_PHASE.reset(token)
+
+
+def current_model_call_phase() -> ModelCallPhase:
+    phase = _MODEL_CALL_PHASE.get()
+    if phase is None:
+        raise RuntimeError("No ModelCallPhase is bound to this model invocation.")
+    return phase