openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/context.py

@@ -0,0 +1,205 @@
+"""ContextStore — contextvars bind/reset plus canonical trace-key correlation.
+
+Two complementary lookup paths (both required):
+
+1. ``ContextVar`` — the bound context for the current async task/thread flow.
+2. trace→context map — hook code running where ContextVars don't propagate
+   (e.g. ``run_in_executor`` worker threads on Python 3.11) resolves the
+   context by OTel trace id instead.
+
+Trace-key invariant: registration and lookup BOTH go through
+``canonical_trace_key()`` — the raw OTel ``SpanContext.trace_id`` integer.
+The 32-hex ``trace_id`` string is a WIRE-ONLY representation; accepting one
+here converts it to the canonical integer so both sides always agree.
+
+Leak safety: callers MUST wrap bind/reset in try/finally (use
+``activity_scope``); ``unregister_trace`` runs on activity completion and
+``clear()`` on runtime close so long-lived workers never grow the map
+unbounded or serve stale correlations.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+from .contracts.context import ActivityContext
+
+__all__ = [
+    "canonical_trace_key",
+    "ContextStore",
+    "default_context_store",
+    "bind_activity_context",
+    "reset_activity_context",
+    "current_activity_context",
+    "register_trace",
+    "context_for_trace",
+    "unregister_trace",
+    "activity_scope",
+]
+
+
+def canonical_trace_key(trace_id: int | str) -> int:
+    """Normalize any accepted trace-id representation to the canonical key.
+
+    The canonical key is the raw OTel ``SpanContext.trace_id`` INTEGER. Hex
+    strings convert through here so the wire representation can never end up
+    on only one side of a lookup.
+    """
+    if isinstance(trace_id, bool):  # bool is an int subclass — reject explicitly
+        raise TypeError("trace_id must be an int or hex string, got bool")
+    if isinstance(trace_id, int):
+        return trace_id
+    if isinstance(trace_id, str):
+        try:
+            return int(trace_id, 16)
+        except ValueError:
+            raise ValueError(f"trace_id string is not hex: {trace_id!r}") from None
+    raise TypeError(f"trace_id must be an int or hex string, got {type(trace_id).__name__}")
+
+
+class ContextStore:
+    """Thread-safe context binding + trace correlation + governance flags."""
+
+    def __init__(self) -> None:
+        self._current: ContextVar[ActivityContext | None] = ContextVar(
+            "openbox_activity_context", default=None
+        )
+        self._lock = threading.Lock()
+        self._trace_to_context: dict[int, ActivityContext] = {}
+        # Governance flags read by the hook runtime (set via adapter/runtime):
+        self._aborted_activities: set[str] = set()
+        self._halt_requested = False
+
+    # ── ContextVar binding ────────────────────────────────────────────────
+
+    def bind(self, ctx: ActivityContext) -> Token:
+        """Bind ``ctx`` to the current flow. Pair with :meth:`reset` in a
+        try/finally — or use :func:`activity_scope`."""
+        return self._current.set(ctx)
+
+    def reset(self, token: Token) -> None:
+        """Restore the previous binding (call in ``finally``)."""
+        self._current.reset(token)
+
+    def current_activity_context(self) -> ActivityContext | None:
+        return self._current.get()
+
+    # ── Trace correlation map ─────────────────────────────────────────────
+
+    def register_trace(self, trace_id: int | str, ctx: ActivityContext) -> None:
+        key = canonical_trace_key(trace_id)
+        with self._lock:
+            self._trace_to_context[key] = ctx
+
+    def context_for_trace(self, trace_id: int | str) -> ActivityContext | None:
+        key = canonical_trace_key(trace_id)
+        with self._lock:
+            return self._trace_to_context.get(key)
+
+    def unregister_trace(self, trace_id: int | str) -> None:
+        """Mandatory cleanup on activity completion/session end."""
+        key = canonical_trace_key(trace_id)
+        with self._lock:
+            self._trace_to_context.pop(key, None)
+
+    def trace_map_size(self) -> int:
+        """Observability/leak-test helper."""
+        with self._lock:
+            return len(self._trace_to_context)
+
+    # ── Governance flags (abort short-circuit, halt) ──────────────────────
+
+    @staticmethod
+    def activity_key(workflow_id: str | None, activity_id: str | None) -> str:
+        return f"{workflow_id}:{activity_id}"
+
+    def mark_activity_aborted(self, workflow_id: str | None, activity_id: str | None) -> None:
+        with self._lock:
+            self._aborted_activities.add(self.activity_key(workflow_id, activity_id))
+
+    def is_activity_aborted(self, workflow_id: str | None, activity_id: str | None) -> bool:
+        with self._lock:
+            return self.activity_key(workflow_id, activity_id) in self._aborted_activities
+
+    def clear_activity_aborted(self, workflow_id: str | None, activity_id: str | None) -> None:
+        with self._lock:
+            self._aborted_activities.discard(self.activity_key(workflow_id, activity_id))
+
+    def request_halt(self) -> None:
+        with self._lock:
+            self._halt_requested = True
+
+    @property
+    def halt_requested(self) -> bool:
+        with self._lock:
+            return self._halt_requested
+
+    # ── Shutdown ──────────────────────────────────────────────────────────
+
+    def clear(self) -> None:
+        """Drop ALL correlation state and flags (runtime close)."""
+        with self._lock:
+            self._trace_to_context.clear()
+            self._aborted_activities.clear()
+            self._halt_requested = False
+
+
+# Default process-wide store: instrumentation resolves context here unless a
+# runtime injects its own store.
+_default_store = ContextStore()
+
+
+def default_context_store() -> ContextStore:
+    return _default_store
+
+
+def bind_activity_context(ctx: ActivityContext) -> Token:
+    return _default_store.bind(ctx)
+
+
+def reset_activity_context(token: Token) -> None:
+    _default_store.reset(token)
+
+
+def current_activity_context() -> ActivityContext | None:
+    return _default_store.current_activity_context()
+
+
+def register_trace(trace_id: int | str, ctx: ActivityContext) -> None:
+    _default_store.register_trace(trace_id, ctx)
+
+
+def context_for_trace(trace_id: int | str) -> ActivityContext | None:
+    return _default_store.context_for_trace(trace_id)
+
+
+def unregister_trace(trace_id: int | str) -> None:
+    _default_store.unregister_trace(trace_id)
+
+
+@contextmanager
+def activity_scope(
+    ctx: ActivityContext,
+    *,
+    trace_id: int | str | None = None,
+    store: ContextStore | None = None,
+) -> Iterator[ActivityContext]:
+    """Bind a context (and optional trace registration) with GUARANTEED reset.
+
+    Reset and trace cleanup run even when the framework operation raises.
+    """
+    target = store if store is not None else _default_store
+    token = target.bind(ctx)
+    try:
+        # Inside the try: a bad trace_id (e.g. non-hex string) must not leak
+        # the ContextVar binding this helper promises to reset.
+        if trace_id is not None:
+            target.register_trace(trace_id, ctx)
+        yield ctx
+    finally:
+        target.reset(token)
+        if trace_id is not None:
+            target.unregister_trace(trace_id)

openbox_core/contracts/__init__.py

@@ -0,0 +1,3 @@
+"""Pure, import-safe contract dataclasses and enums. No network, crypto, OTel, or wall-clock."""
+
+__all__: list[str] = []

openbox_core/contracts/context.py

@@ -0,0 +1,79 @@
+"""ActivityContext dataclass and ActivityContextProvider protocol.
+
+Pure, import-safe module. The base SDK owns THE context shape; framework SDKs
+populate it (they do not define competing context types). Core instrumentation
+reads the bound context without knowing the framework.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["ActivityContext", "ActivityContextProvider"]
+
+
+@dataclass(frozen=True)
+class ActivityContext:
+    """The framework-agnostic activity/task execution context.
+
+    Immutable — per-operation deltas go in ``metadata`` or a freshly bound
+    context, never mutation. Framework-specific extras that have no first-class
+    field here belong in ``metadata``.
+    """
+
+    workflow_id: str | None = None
+    run_id: str | None = None
+    workflow_type: str | None = None
+    task_queue: str | None = None
+    activity_id: str | None = None
+    activity_type: str | None = None
+    activity_input: Any = None
+    agent_name: str | None = None
+    agent_role: str | None = None
+    session_id: str | None = None
+    multi_agent_session_id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_payload_fields(self) -> dict[str, Any]:
+        """Flat wire fields for hook payload assembly (omit-when-absent).
+
+        ``metadata`` entries merge at the top level last, but never overwrite
+        first-class fields.
+        """
+        fields_map = {
+            "workflow_id": self.workflow_id,
+            "run_id": self.run_id,
+            "workflow_type": self.workflow_type,
+            "task_queue": self.task_queue,
+            "activity_id": self.activity_id,
+            "activity_type": self.activity_type,
+            "activity_input": self.activity_input,
+            "agent_name": self.agent_name,
+            "agent_role": self.agent_role,
+            "session_id": self.session_id,
+            "multi_agent_session_id": self.multi_agent_session_id,
+        }
+        payload = {k: v for k, v in fields_map.items() if v is not None}
+        for key, value in self.metadata.items():
+            payload.setdefault(str(key), value)
+        return payload
+
+
+@runtime_checkable
+class ActivityContextProvider(Protocol):
+    """How core instrumentation resolves the bound context.
+
+    Implemented by ``openbox_core.context.ContextStore``; frameworks may plug
+    a custom provider as long as registration and lookup share the SAME
+    canonical trace key.
+    """
+
+    def current_activity_context(self) -> ActivityContext | None:
+        """The context bound to the current execution flow (or None)."""
+        ...
+
+    def context_for_trace(self, trace_id: int) -> ActivityContext | None:
+        """The context registered for an OTel trace id (or None)."""
+        ...

openbox_core/contracts/events.py

@@ -0,0 +1,401 @@
+"""Event contracts — EventType, EventKind, EventEnvelope, classification, factories.
+
+Pure, import-safe module: no network, crypto, OTel, logging, wall-clock, or
+random. Timestamps are RFC3339 strings *passed in* by callers — never generated
+here (``datetime.now`` is forbidden in contracts; the sending layer stamps
+missing timestamps).
+
+Core wire rules:
+
+- ``EventEnvelope.event_type`` stores the **backend wire type**.
+- Hook evaluations are internally ``EventKind.HOOK`` but serialize as
+  ``ActivityStarted`` + ``hook_trigger=true`` + non-empty ``spans``.
+- ``ActivityCompleted`` must not carry non-empty hook spans (validated by the
+  strict gate; factories make invalid states hard to build).
+- Handoff payloads require ``from_agent_did`` + ``multi_agent_session_id``
+  (both non-empty); ``to_agent_did`` is omitted because the receiver is derived
+  server-side from the authenticated signed identity.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "SOURCE_WORKFLOW_TELEMETRY",
+    "EventType",
+    "EventKind",
+    "EventEnvelope",
+    "classify_event",
+    "wire_event_type",
+    "rfc3339_from_datetime",
+    "workflow_started",
+    "workflow_completed",
+    "workflow_failed",
+    "activity_started",
+    "activity_completed",
+    "signal_received",
+    "handoff",
+    "hook",
+]
+
+# ``source`` field Core receives on every governance event.
+SOURCE_WORKFLOW_TELEMETRY = "workflow-telemetry"
+
+
+class EventType(str, Enum):
+    """Backend wire event types (Core's accepted ``event_type`` values)."""
+
+    WORKFLOW_STARTED = "WorkflowStarted"
+    WORKFLOW_COMPLETED = "WorkflowCompleted"
+    WORKFLOW_FAILED = "WorkflowFailed"
+    SIGNAL_RECEIVED = "SignalReceived"
+    ACTIVITY_STARTED = "ActivityStarted"
+    ACTIVITY_COMPLETED = "ActivityCompleted"
+    HANDOFF = "Handoff"
+
+
+class EventKind(Enum):
+    """Internal event classification. Not a wire concept."""
+
+    LIFECYCLE = "lifecycle"
+    HOOK = "hook"
+    SIGNAL = "signal"
+    HANDOFF = "handoff"
+
+
+def rfc3339_from_datetime(ts: datetime) -> str:
+    """Format a datetime as RFC3339 (UTC, millisecond precision, trailing ``Z``).
+
+    Pure formatter — the caller supplies the datetime; naive datetimes are
+    assumed UTC. This is the *event-payload* timestamp format. It is distinct
+    from the request-*signing* timestamp, which keeps ``+00:00`` (never ``Z``).
+    """
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=UTC)
+    return ts.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+@dataclass(frozen=True)
+class EventEnvelope:
+    """A governance event addressed to OpenBox Core.
+
+    Attributes:
+        event_type: Backend **wire** event type (hook events store
+            ``ACTIVITY_STARTED`` — the wire type Core accepts).
+        payload: Flat wire fields (``workflow_id``, ``run_id``, ...). Serialized
+            at the top level of the request body, not nested.
+        spans: Flat Core SpanData hook payloads. Empty for lifecycle events.
+        hook_trigger: True only for hook evaluations.
+        activity_id / activity_type: The bound activity for activity-scoped and
+            hook events.
+        timestamp: RFC3339 ``Z`` string, passed in. ``None`` means the sending
+            layer stamps it (``setdefault`` semantics — an explicit value is
+            preserved).
+        source: Constant event source tag Core expects.
+    """
+
+    event_type: EventType
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    spans: tuple[Any, ...] = ()
+    hook_trigger: bool = False
+    activity_id: str | None = None
+    activity_type: str | None = None
+    timestamp: str | None = None
+    source: str = SOURCE_WORKFLOW_TELEMETRY
+
+    def to_payload_dict(self) -> dict[str, Any]:
+        """Flat lifecycle wire dict (omit-when-absent; never null keys).
+
+        Spans and ``span_count`` are deliberately NOT emitted here — hook body
+        assembly is owned by ``wire/evaluate_payload.py``, the single owner of
+        the evaluate body shape.
+        """
+        body: dict[str, Any] = {
+            "source": self.source,
+            "event_type": wire_event_type(self).value,
+            **dict(self.payload),
+        }
+        if self.activity_id is not None:
+            body["activity_id"] = self.activity_id
+        if self.activity_type is not None:
+            body["activity_type"] = self.activity_type
+        if self.hook_trigger:
+            body["hook_trigger"] = True
+        if self.timestamp is not None:
+            body["timestamp"] = self.timestamp
+        return body
+
+
+def classify_event(event: EventEnvelope) -> EventKind:
+    """Classify an envelope. Derived from stored fields — never trust callers
+    to pass a separate, possibly-inconsistent kind."""
+    if event.hook_trigger:
+        return EventKind.HOOK
+    if event.event_type is EventType.HANDOFF:
+        return EventKind.HANDOFF
+    if event.event_type is EventType.SIGNAL_RECEIVED:
+        return EventKind.SIGNAL
+    return EventKind.LIFECYCLE
+
+
+def wire_event_type(event: EventEnvelope) -> EventType:
+    """Backend wire event type. A HOOK-kind event is always ``ActivityStarted``
+    on the wire regardless of what the envelope stores."""
+    if event.hook_trigger:
+        return EventType.ACTIVITY_STARTED
+    return event.event_type
+
+
+# ─── Factories ───────────────────────────────────────────────────────────────
+#
+# Factories build wire-consistent envelopes. They raise ValueError on
+# programmer misuse (missing required identity fields); *runtime* contract
+# violations on arbitrary envelopes are the strict gate's job (ContractError).
+
+
+def _base_workflow_payload(
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    task_queue: str | None,
+    multi_agent_session_id: str | None,
+    extra: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "workflow_id": workflow_id,
+        "run_id": run_id,
+        "workflow_type": workflow_type,
+    }
+    if task_queue is not None:
+        payload["task_queue"] = task_queue
+    # Omitted entirely when absent; never emitted as a null key.
+    if multi_agent_session_id:
+        payload["multi_agent_session_id"] = multi_agent_session_id
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def workflow_started(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    task_queue: str | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """WorkflowStarted lifecycle event."""
+    return EventEnvelope(
+        event_type=EventType.WORKFLOW_STARTED,
+        payload=_base_workflow_payload(
+            workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+        ),
+        timestamp=timestamp,
+    )
+
+
+def workflow_completed(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    task_queue: str | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """WorkflowCompleted lifecycle event."""
+    return EventEnvelope(
+        event_type=EventType.WORKFLOW_COMPLETED,
+        payload=_base_workflow_payload(
+            workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+        ),
+        timestamp=timestamp,
+    )
+
+
+def workflow_failed(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    error: str | None = None,
+    task_queue: str | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """WorkflowFailed lifecycle event."""
+    payload = _base_workflow_payload(
+        workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+    )
+    if error is not None:
+        payload["error"] = error
+    return EventEnvelope(
+        event_type=EventType.WORKFLOW_FAILED, payload=payload, timestamp=timestamp
+    )
+
+
+def activity_started(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    activity_id: str,
+    activity_type: str,
+    task_queue: str | None = None,
+    activity_input: Any = None,
+    attempt: int | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """ActivityStarted lifecycle event (NOT a hook — ``hook_trigger`` stays false)."""
+    payload = _base_workflow_payload(
+        workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+    )
+    if activity_input is not None:
+        payload["activity_input"] = activity_input
+    if attempt is not None:
+        payload["attempt"] = attempt
+    return EventEnvelope(
+        event_type=EventType.ACTIVITY_STARTED,
+        payload=payload,
+        activity_id=activity_id,
+        activity_type=activity_type,
+        timestamp=timestamp,
+    )
+
+
+def activity_completed(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    activity_id: str,
+    activity_type: str,
+    task_queue: str | None = None,
+    result: Any = None,
+    error: str | None = None,
+    attempt: int | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """ActivityCompleted lifecycle event.
+
+    Never carries hook spans. Empty ``spans``/``span_count=0`` noise is not
+    produced here at all; the wire assembler additionally strips it from
+    hand-built payloads (recorded as a diagnostic).
+    """
+    payload = _base_workflow_payload(
+        workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+    )
+    if result is not None:
+        payload["result"] = result
+    if error is not None:
+        payload["error"] = error
+    if attempt is not None:
+        payload["attempt"] = attempt
+    return EventEnvelope(
+        event_type=EventType.ACTIVITY_COMPLETED,
+        payload=payload,
+        activity_id=activity_id,
+        activity_type=activity_type,
+        timestamp=timestamp,
+    )
+
+
+def signal_received(
+    *,
+    workflow_id: str,
+    run_id: str,
+    workflow_type: str,
+    signal_name: str,
+    task_queue: str | None = None,
+    multi_agent_session_id: str | None = None,
+    timestamp: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> EventEnvelope:
+    """SignalReceived event."""
+    payload = _base_workflow_payload(
+        workflow_id, run_id, workflow_type, task_queue, multi_agent_session_id, extra
+    )
+    payload["signal_name"] = signal_name
+    return EventEnvelope(
+        event_type=EventType.SIGNAL_RECEIVED, payload=payload, timestamp=timestamp
+    )
+
+
+def handoff(
+    *,
+    from_agent_did: str,
+    multi_agent_session_id: str,
+    timestamp: str | None = None,
+) -> EventEnvelope:
+    """Multi-agent Handoff event.
+
+    Both fields are required and non-empty (raises ValueError before any
+    network call). ``to_agent_did`` is not included; the receiver is derived
+    server-side from the authenticated signed identity.
+    """
+    if not from_agent_did or not from_agent_did.strip():
+        raise ValueError("handoff: from_agent_did is required and must be non-empty")
+    if not multi_agent_session_id or not multi_agent_session_id.strip():
+        raise ValueError(
+            "handoff: multi_agent_session_id is required and must be non-empty"
+        )
+    return EventEnvelope(
+        event_type=EventType.HANDOFF,
+        payload={
+            "from_agent_did": from_agent_did,
+            "multi_agent_session_id": multi_agent_session_id,
+        },
+        timestamp=timestamp,
+    )
+
+
+def hook(
+    *,
+    activity_context: Mapping[str, Any],
+    activity_id: str,
+    activity_type: str,
+    spans: tuple[Any, ...] | list[Any],
+    timestamp: str | None = None,
+) -> EventEnvelope:
+    """Hook (span-bearing) evaluation event.
+
+    Internally ``EventKind.HOOK``; serializes as wire ``ActivityStarted`` +
+    ``hook_trigger=true`` + non-empty ``spans``. Must be attached to a bound
+    activity — callers resolve ``activity_context`` from the ContextStore
+    first (no bound context ⇒ skip the hook entirely; don't call this).
+
+    Args:
+        activity_context: Flat context payload fields (workflow_id, run_id, ...)
+            merged at the top level of the wire body.
+        activity_id / activity_type: The bound activity identity (required).
+        spans: Non-empty flat Core ``SpanData`` payloads.
+    """
+    if not activity_id or not activity_type:
+        raise ValueError(
+            "hook: activity_id and activity_type are required — hook events must "
+            "be attached to a bound activity"
+        )
+    if not spans:
+        raise ValueError("hook: spans must be non-empty for a hook evaluation")
+    return EventEnvelope(
+        event_type=EventType.ACTIVITY_STARTED,
+        payload=dict(activity_context),
+        spans=tuple(spans),
+        hook_trigger=True,
+        activity_id=activity_id,
+        activity_type=activity_type,
+        timestamp=timestamp,
+    )