bazaar-compute-node 0.1.3__py3-none-any.whl

bazaar_compute_node/core/orchestration/turn.py

@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, replace
+
+from ..approval import ApprovalBinding
+from ..audit import ErrorKind
+from ..channel import IChannel
+from ..concurrency import ISessionConcurrency
+from ..correlation import CorrelationContext
+from ..lifecycle import TimeoutBudget
+from ..models import (
+    AgentSignal,
+    AgentTick,
+    AgentTickSource,
+    ApprovalRequest,
+    ApprovalResult,
+    BcnSession,
+    ChannelSession,
+    InboundMessage,
+    RuntimeEvent,
+    RuntimeEventState,
+    RuntimeSession,
+    RuntimeTurn,
+    RuntimeTurnState,
+    StreamEvent,
+)
+from ..runtime import IRuntime, IRuntimeTurnStream, RuntimeSessionUnavailable
+from ..storage import IStorage
+from .services import SessionAuditRecorder, SessionStateWriter
+
+
+def _is_compaction_event(event_name: str) -> bool:
+    return "compaction" in event_name.casefold()
+
+
+def _is_turn_event(event_name: str) -> bool:
+    return "turn" in event_name.casefold()
+
+
+def _runtime_event_agent_signal(event: RuntimeEvent) -> AgentSignal:
+    if _is_compaction_event(event.event_name):
+        normalized = event.event_name.casefold()
+        if any(token in normalized for token in ("start", "begin")):
+            return AgentSignal.COMPACTION_STARTED
+        if any(token in normalized for token in ("complete", "finish", "end")):
+            return AgentSignal.COMPACTION_COMPLETED
+        if event.state is RuntimeEventState.COMPLETED:
+            return AgentSignal.COMPACTION_COMPLETED
+        return AgentSignal.COMPACTION_IN_PROGRESS
+
+    if not _is_turn_event(event.event_name):
+        if event.state is RuntimeEventState.UNKNOWN:
+            return AgentSignal.UNKNOWN
+        if (
+            event.state is RuntimeEventState.FAILED
+            or "error" in event.event_name.casefold()
+        ):
+            return AgentSignal.FAILED
+        return AgentSignal.WORKING_OBSERVED
+
+    if event.state is RuntimeEventState.STARTED:
+        return AgentSignal.TURN_STARTED
+    if event.state is RuntimeEventState.COMPLETED:
+        return AgentSignal.TURN_COMPLETED
+    if event.state is RuntimeEventState.FAILED:
+        return AgentSignal.TURN_FAILED
+    if event.state is RuntimeEventState.CANCELLED:
+        return AgentSignal.TURN_CANCELLED
+    return AgentSignal.UNKNOWN
+
+
+def _is_terminal_turn_event(event: RuntimeEvent) -> bool:
+    return _is_turn_event(event.event_name) and event.state in {
+        RuntimeEventState.COMPLETED,
+        RuntimeEventState.FAILED,
+        RuntimeEventState.CANCELLED,
+        RuntimeEventState.UNKNOWN,
+    }
+
+
+@dataclass(frozen=True, slots=True)
+class SessionContext:
+    channel_session: ChannelSession
+    bcn_session: BcnSession
+    runtime_session: RuntimeSession
+
+
+class _ApprovalHandler:
+    def __init__(
+        self,
+        callback: Callable[[ApprovalRequest, float], Awaitable[ApprovalResult]],
+    ) -> None:
+        self._callback = callback
+
+    async def request_approval(
+        self, request: ApprovalRequest, *, timeout: float
+    ) -> ApprovalResult:
+        return await self._callback(request, timeout)
+
+
+class SessionTurnCoordinator:
+    """Drive runtime turns and persist their event/state transitions."""
+
+    def __init__(
+        self,
+        *,
+        channel: IChannel,
+        runtime: IRuntime,
+        storage: IStorage,
+        audit: SessionAuditRecorder,
+        state_writer: SessionStateWriter,
+        timeout_budget: TimeoutBudget,
+        concurrency: ISessionConcurrency,
+        turns: dict[str, RuntimeTurn],
+        node_id: Callable[[], str],
+        clock: Callable[[], int],
+    ) -> None:
+        self._channel = channel
+        self._runtime = runtime
+        self._storage = storage
+        self._audit = audit
+        self._state_writer = state_writer
+        self._timeout_budget = timeout_budget
+        self._concurrency = concurrency
+        self._turns = turns
+        self._node_id = node_id
+        self._clock = clock
+        self._logger = logging.getLogger("bazaar_compute_node.orchestration.turn")
+
+    async def run_turn(
+        self,
+        message: InboundMessage,
+        context: SessionContext,
+        turn: RuntimeTurn,
+        *,
+        unread_count: int,
+    ) -> RuntimeTurn:
+        binding = ApprovalBinding(
+            request_id="pending",
+            bcn_session_id=context.bcn_session.id,
+            channel_session_id=context.channel_session.id,
+            runtime_session_id=context.runtime_session.id,
+            turn_id=turn.turn_id,
+        )
+        turn_correlation = self.turn_correlation(message, context, turn)
+
+        async def request_approval(
+            request: ApprovalRequest, *, timeout: float
+        ) -> ApprovalResult:
+            request_id = request.request_id
+            current_binding = replace(binding, request_id=request_id)
+            if not current_binding.matches(request):
+                raise ValueError("runtime approval request correlation mismatch")
+            approval_correlation = CorrelationContext(
+                node_id=self._node_id(),
+                channel=context.channel_session.channel,
+                channel_session_id=context.channel_session.id,
+                bcn_session_id=context.bcn_session.id,
+                runtime_session_id=context.runtime_session.id,
+                turn_id=turn.turn_id,
+                request_id=request_id,
+                inbound_seq=message.seq,
+            )
+            await self._audit.append(
+                event_name="approval.requested",
+                state=RuntimeEventState.STARTED,
+                correlation=approval_correlation,
+                metadata={"action": request.action},
+            )
+            try:
+                result = await self._channel.request_approval(request, timeout=timeout)
+                if result.request_id != request_id:
+                    raise ValueError("channel approval result correlation mismatch")
+            except Exception as error:
+                await self._audit.append(
+                    event_name="approval.failed",
+                    state=RuntimeEventState.FAILED,
+                    correlation=approval_correlation,
+                    error_kind=ErrorKind.PROVIDER_FAILED,
+                    error_message=f"approval failed: {type(error).__name__}",
+                    metadata={"action": request.action},
+                )
+                raise
+            await self._audit.append(
+                event_name="approval.decided",
+                state=RuntimeEventState.COMPLETED,
+                correlation=approval_correlation,
+                metadata={
+                    "action": request.action,
+                    "decision": result.decision.value,
+                },
+            )
+            return result
+
+        stream: IRuntimeTurnStream | None = None
+        observed_terminal = False
+        try:
+            approval_handler = _ApprovalHandler(
+                lambda request, timeout: request_approval(request, timeout=timeout)
+            )
+            await self._audit.append(
+                event_name="runtime.request.turn.started",
+                state=RuntimeEventState.STARTED,
+                correlation=turn_correlation,
+                metadata={"provider_method": "turn/start"},
+            )
+            try:
+                stream = await self._runtime.start_turn(
+                    context.runtime_session,
+                    turn,
+                    f"[inbox notice session={context.bcn_session.id}]\n"
+                    f"Inbox update: {unread_count} unread message(s). "
+                    "Use the message command to read them.",
+                    approval_handler,
+                    timeout=self._timeout_budget.provider_call_seconds,
+                )
+            except Exception as error:
+                await self._audit.append(
+                    event_name="runtime.request.turn.failed",
+                    state=RuntimeEventState.FAILED,
+                    correlation=turn_correlation,
+                    error_kind=ErrorKind.PROVIDER_FAILED,
+                    error_message=f"turn request failed: {type(error).__name__}",
+                    metadata={"provider_method": "turn/start"},
+                )
+                raise
+            async for event in stream:
+                if isinstance(event, StreamEvent):
+                    if event.session_id != context.bcn_session.id:
+                        self._logger.error(
+                            "runtime emitted stream event for another session",
+                            extra={
+                                "expected_session_id": context.bcn_session.id,
+                                "actual_session_id": event.session_id,
+                            },
+                        )
+                        continue
+                    try:
+                        self._channel.offer_stream_event(event)
+                    except Exception:
+                        self._logger.exception("channel rejected stream event")
+                    continue
+                turn = await self._apply_runtime_event(message, context, turn, event)
+                if _is_terminal_turn_event(event):
+                    observed_terminal = True
+                    break
+            if not observed_terminal:
+                return await self.finish_turn(
+                    turn,
+                    RuntimeTurnState.UNKNOWN,
+                    error_kind=ErrorKind.PROVIDER_UNKNOWN,
+                    error_message="runtime stream ended without a terminal event",
+                    correlation=turn_correlation,
+                    session_id=context.bcn_session.id,
+                )
+            return turn
+        except asyncio.CancelledError:
+            await self._close_stream(stream)
+            await self.finish_turn(
+                turn,
+                RuntimeTurnState.CANCELLED,
+                error_kind=ErrorKind.CANCELLED,
+                error_message="runtime turn cancelled",
+                correlation=turn_correlation,
+                session_id=context.bcn_session.id,
+            )
+            raise
+        except RuntimeSessionUnavailable:
+            await self._close_stream(stream)
+            raise
+        except Exception as error:  # noqa: BLE001
+            await self._close_stream(stream)
+            return await self.finish_turn(
+                turn,
+                RuntimeTurnState.FAILED,
+                error_kind=ErrorKind.PROVIDER_FAILED,
+                error_message=f"runtime turn failed: {type(error).__name__}",
+                correlation=turn_correlation,
+                session_id=context.bcn_session.id,
+            )
+        finally:
+            await self._close_stream(stream)
+
+    async def finish_turn(
+        self,
+        turn: RuntimeTurn,
+        state: RuntimeTurnState,
+        *,
+        error_kind: ErrorKind | None,
+        error_message: str | None,
+        correlation: CorrelationContext | None,
+        session_id: str,
+    ) -> RuntimeTurn:
+        async with self._concurrency.for_session(session_id):
+            if turn.state in {
+                RuntimeTurnState.COMPLETED,
+                RuntimeTurnState.FAILED,
+                RuntimeTurnState.CANCELLED,
+                RuntimeTurnState.UNKNOWN,
+            }:
+                return turn
+            current_turn = turn.transition_to(
+                state,
+                at_ms=self._clock(),
+                error_kind=error_kind.value if error_kind else None,
+                error_message=error_message,
+            )
+            self._turns.pop(turn.turn_id, None)
+            if state is RuntimeTurnState.COMPLETED:
+                agent_signal = AgentSignal.TURN_COMPLETED
+            elif state is RuntimeTurnState.FAILED:
+                agent_signal = AgentSignal.TURN_FAILED
+            elif state is RuntimeTurnState.CANCELLED:
+                agent_signal = AgentSignal.TURN_CANCELLED
+            else:
+                agent_signal = AgentSignal.UNKNOWN
+            self._state_writer.apply_observation(
+                session_id,
+                AgentTick(
+                    source=AgentTickSource.RUNTIME,
+                    signal=agent_signal,
+                    observed_at_ms=self._clock(),
+                    error_kind=error_kind.value if error_kind else None,
+                    error_message=error_message,
+                ),
+            )
+        await self._audit.append(
+            event_name=f"runtime.turn.{state.value}",
+            state=(
+                RuntimeEventState.COMPLETED
+                if state is RuntimeTurnState.COMPLETED
+                else RuntimeEventState.CANCELLED
+                if state is RuntimeTurnState.CANCELLED
+                else RuntimeEventState.FAILED
+                if state is not RuntimeTurnState.UNKNOWN
+                else RuntimeEventState.UNKNOWN
+            ),
+            correlation=correlation or CorrelationContext(turn_id=turn.turn_id),
+            error_kind=error_kind,
+            error_message=error_message,
+        )
+        return current_turn
+
+    async def _apply_runtime_event(
+        self,
+        message,
+        context: SessionContext,
+        turn: RuntimeTurn,
+        event: RuntimeEvent,
+    ) -> RuntimeTurn:
+        if event.turn_id is not None and event.turn_id != turn.turn_id:
+            raise ValueError("runtime event turn correlation mismatch")
+        async with self._concurrency.for_session(message.session_id):
+            async with self._storage.transaction() as transaction:
+                event = await transaction.append_runtime_event(event)
+                agent_signal = _runtime_event_agent_signal(event)
+                if not _is_turn_event(event.event_name):
+                    target_state = turn.state
+                elif event.state is RuntimeEventState.STARTED:
+                    target_state = RuntimeTurnState.RUNNING
+                elif event.state is RuntimeEventState.COMPLETED:
+                    target_state = RuntimeTurnState.COMPLETED
+                elif event.state is RuntimeEventState.FAILED:
+                    target_state = RuntimeTurnState.FAILED
+                elif event.state is RuntimeEventState.CANCELLED:
+                    target_state = RuntimeTurnState.CANCELLED
+                else:
+                    target_state = RuntimeTurnState.UNKNOWN
+                provider_turn_id = event.metadata.get("provider_turn_id")
+                if provider_turn_id is not None and (
+                    not isinstance(provider_turn_id, str) or not provider_turn_id
+                ):
+                    raise ValueError("runtime event provider_turn_id is invalid")
+                if (
+                    provider_turn_id is not None
+                    and turn.provider_turn_id is not None
+                    and turn.provider_turn_id != provider_turn_id
+                ):
+                    raise ValueError("runtime event provider turn correlation mismatch")
+                error_kind = event.error_kind
+                if event.state is RuntimeEventState.FAILED and error_kind is None:
+                    error_kind = ErrorKind.PROVIDER_FAILED.value
+                if event.state is RuntimeEventState.UNKNOWN and error_kind is None:
+                    error_kind = ErrorKind.PROVIDER_UNKNOWN.value
+                if event.state is RuntimeEventState.CANCELLED and error_kind is None:
+                    error_kind = ErrorKind.CANCELLED.value
+                updated_turn = turn.transition_to(
+                    target_state,
+                    at_ms=event.created_at_ms,
+                    error_kind=error_kind,
+                    error_message=event.error_message,
+                    latest_event_name=event.event_name,
+                )
+                if provider_turn_id is not None:
+                    updated_turn = replace(
+                        updated_turn,
+                        provider_turn_id=provider_turn_id,
+                    )
+                agent_tick = AgentTick(
+                    source=AgentTickSource.RUNTIME,
+                    signal=agent_signal,
+                    observed_at_ms=self._clock(),
+                    error_kind=error_kind,
+                    error_message=event.error_message,
+                )
+            if _is_terminal_turn_event(event):
+                self._turns.pop(turn.turn_id, None)
+            else:
+                self._turns[turn.turn_id] = updated_turn
+            self._state_writer.apply_observation(
+                context.bcn_session.id,
+                agent_tick,
+            )
+        try:
+            audit_kind = ErrorKind(event.error_kind) if event.error_kind else None
+        except ValueError:
+            audit_kind = ErrorKind.INTERNAL
+        audit_error_message = event.error_message if audit_kind else None
+        await self._audit.append(
+            event_name=event.event_name,
+            state=event.state,
+            correlation=self.turn_correlation(message, context, updated_turn),
+            error_kind=audit_kind,
+            error_message=audit_error_message,
+        )
+        return updated_turn
+
+    async def _close_stream(self, stream: IRuntimeTurnStream | None) -> None:
+        if stream is not None:
+            await stream.aclose()
+
+    def turn_correlation(
+        self,
+        message: InboundMessage,
+        context: SessionContext,
+        turn: RuntimeTurn,
+    ) -> CorrelationContext:
+        return CorrelationContext(
+            node_id=self._node_id(),
+            channel=context.channel_session.channel,
+            channel_session_id=context.channel_session.id,
+            bcn_session_id=context.bcn_session.id,
+            runtime_session_id=context.runtime_session.id,
+            turn_id=turn.turn_id,
+            inbound_seq=message.seq,
+            provider_thread_id=context.runtime_session.provider_thread_id,
+            provider_turn_id=turn.provider_turn_id,
+        )

bazaar_compute_node/core/outcomes.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class ProviderCallStatus(StrEnum):
+    CONFIRMED = "confirmed"
+    QUEUED = "queued"
+    PARTIAL = "partial"
+    FAILED = "failed"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderCallResult[ResultT]:
+    """Provider outcome that never treats an unconfirmed call as a success."""
+
+    status: ProviderCallStatus
+    value: ResultT | None = None
+    error_kind: str | None = None
+    error_message: str | None = None
+    receipt: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.status in {
+            ProviderCallStatus.CONFIRMED,
+            ProviderCallStatus.QUEUED,
+        }:
+            if self.value is None:
+                raise ValueError(
+                    f"a {self.status.value} provider call requires a value"
+                )
+            if self.error_kind is not None or self.error_message is not None:
+                raise ValueError(
+                    f"a {self.status.value} provider call cannot contain an error"
+                )
+            return
+
+        if self.status is ProviderCallStatus.PARTIAL:
+            if self.value is None:
+                raise ValueError("a partial provider call requires a value")
+            if not self.error_kind:
+                raise ValueError("a partial provider call requires an error_kind")
+            return
+
+        if self.value is not None:
+            raise ValueError("an unconfirmed provider call cannot contain a value")
+        if not self.error_kind:
+            raise ValueError("an unconfirmed provider call requires an error_kind")

bazaar_compute_node/core/paths.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_data_dir() -> Path:
+    """Resolve the persistent node data directory under the user's home."""
+
+    return (Path.home() / ".bcn").resolve(strict=False)
+
+
+def resolve_workspace_dir(
+    workspace_id: str,
+) -> Path:
+    """Resolve the persistent shared workspace for one node identity."""
+
+    if not isinstance(workspace_id, str) or not workspace_id:
+        raise ValueError("workspace_id must be a non-empty string")
+    return resolve_data_dir() / "workspaces" / workspace_id

bazaar_compute_node/core/runtime.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+from .approval import IApprovalHandler
+from .client import CLIENT_INFO, ClientInfo
+from .lifecycle import IAsyncLifecycle
+from .models import RuntimeEvent, RuntimeSession, RuntimeTurn, StreamEvent
+from .outcomes import ProviderCallResult
+
+
+class RuntimeSessionUnavailable(RuntimeError):
+    """The runtime session failed before a provider turn request was written."""
+
+
+class RuntimeSandboxMode(StrEnum):
+    """Provider-neutral filesystem sandbox modes for runtime turns."""
+
+    WORKSPACE_WRITE = "workspace-write"
+    DANGER_FULL_ACCESS = "danger-full-access"
+
+
+type RuntimeStreamItem = RuntimeEvent | StreamEvent
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeCommandContext:
+    """Generic command capability made available to a runtime adapter."""
+
+    run_command: Callable[[str, Sequence[str], str | None], Awaitable[None]]
+    environment_for_session: Callable[[RuntimeSession], Mapping[str, str]]
+    node_id: str = "bcn-node"
+    runtime_options: Mapping[str, str] = field(default_factory=dict)
+    sandbox_mode: RuntimeSandboxMode = RuntimeSandboxMode.WORKSPACE_WRITE
+    network_access: bool = True
+    startup_timeout_seconds: float = 60
+    client_info: ClientInfo = CLIENT_INFO
+
+
+class IRuntimeTurnStream(Protocol):
+    """Cancellable stream of provider-neutral runtime events."""
+
+    def __aiter__(self) -> AsyncIterator[RuntimeStreamItem]:
+        """Iterate stream items without exposing provider wire types."""
+        ...
+
+    async def __anext__(self) -> RuntimeStreamItem:
+        """Return the next stream item or raise StopAsyncIteration."""
+        ...
+
+    async def aclose(self) -> None:
+        """Stop the stream and release its provider resources."""
+        ...
+
+
+class IRuntime(IAsyncLifecycle, Protocol):
+    """Async agent-runtime contract isolated from provider SDK types.
+
+    A stream ending before a terminal runtime event is observed is an unknown
+    provider outcome. Caller cancellation propagates to the provider and is
+    not converted into a confirmed failure.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the stable entry-point identity of this adapter."""
+        ...
+
+    def environment_variable_names(self) -> Sequence[str]:
+        """Return optional daemon environment names required by this runtime."""
+        ...
+
+    async def start_session(
+        self, session: RuntimeSession, *, timeout: float
+    ) -> ProviderCallResult[RuntimeSession]:
+        """Start a new runtime process/session."""
+        ...
+
+    async def resume_session(
+        self, session: RuntimeSession, *, timeout: float
+    ) -> ProviderCallResult[RuntimeSession]:
+        """Reconcile or resume a persisted runtime session."""
+        ...
+
+    async def start_turn(
+        self,
+        session: RuntimeSession,
+        turn: RuntimeTurn,
+        input_text: str,
+        approval_handler: IApprovalHandler,
+        *,
+        timeout: float,
+    ) -> IRuntimeTurnStream:
+        """Start one turn and return its cancellable event stream.
+
+        Raise RuntimeSessionUnavailable only before writing the turn request to
+        the provider so orchestration can safely recover the session and retry.
+        """
+        ...
+
+    async def interrupt_turn(
+        self,
+        session: RuntimeSession,
+        turn: RuntimeTurn,
+        *,
+        timeout: float,
+    ) -> ProviderCallResult[RuntimeTurn]:
+        """Request interruption without claiming provider completion."""
+        ...
+
+    async def stop_session(
+        self, session: RuntimeSession, *, timeout: float
+    ) -> ProviderCallResult[RuntimeSession]:
+        """Stop one runtime process within the bounded shutdown budget."""
+        ...