flightdeck-sensor 0.1.0a1__tar.gz

flightdeck_sensor-0.1.0a1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: flightdeck-sensor
+Version: 0.1.0a1
+Summary: In-process agent observability sensor for Flightdeck
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Requires-Dist: tiktoken>=0.5; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# flightdeck-sensor
+
+In-process agent observability sensor for [Flightdeck](https://github.com/flightdeckhq/flightdeck).

flightdeck_sensor-0.1.0a1/README.md

@@ -0,0 +1,3 @@
+# flightdeck-sensor
+
+In-process agent observability sensor for [Flightdeck](https://github.com/flightdeckhq/flightdeck).

flightdeck_sensor-0.1.0a1/flightdeck_sensor/__init__.py

@@ -0,0 +1 @@
+"""flightdeck-sensor: in-process agent observability for Flightdeck."""

flightdeck_sensor-0.1.0a1/flightdeck_sensor/core/exceptions.py

@@ -0,0 +1,34 @@
+"""Exceptions raised by flightdeck-sensor."""
+
+from __future__ import annotations
+
+
+class BudgetExceededError(Exception):
+    """Raised when the token budget is exhausted and policy is BLOCK."""
+
+    def __init__(
+        self,
+        session_id: str,
+        tokens_used: int,
+        token_limit: int,
+    ) -> None:
+        self.session_id = session_id
+        self.tokens_used = tokens_used
+        self.token_limit = token_limit
+        super().__init__(
+            f"Token budget exceeded: {tokens_used}/{token_limit} "
+            f"(session {session_id})"
+        )
+
+
+class DirectiveError(Exception):
+    """Raised when a directive requires halting and halt policy is active."""
+
+    def __init__(self, action: str, reason: str) -> None:
+        self.action = action
+        self.reason = reason
+        super().__init__(f"Directive {action}: {reason}")
+
+
+class ConfigurationError(Exception):
+    """Raised when init() receives invalid arguments."""

flightdeck_sensor-0.1.0a1/flightdeck_sensor/core/policy.py

@@ -0,0 +1,84 @@
+"""Local token budget enforcement cache.
+
+Holds the current policy thresholds (pulled from the control plane via
+directive envelope) and evaluates them on every LLM call.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from flightdeck_sensor.core.types import PolicyDecision
+
+
+class PolicyCache:
+    """Thread-safe local cache of the token budget policy.
+
+    ``check()`` is called on every LLM call before and after the actual
+    provider request.  It is deliberately cheap -- all data is in memory,
+    no I/O, no locking beyond a fast ``threading.Lock`` for the fire-once
+    flag.
+    """
+
+    def __init__(
+        self,
+        token_limit: int | None = None,
+        warn_at_pct: int = 80,
+        degrade_at_pct: int = 90,
+        block_at_pct: int = 100,
+        degrade_to: str | None = None,
+    ) -> None:
+        self.token_limit = token_limit
+        self.warn_at_pct = warn_at_pct
+        self.degrade_at_pct = degrade_at_pct
+        self.block_at_pct = block_at_pct
+        self.degrade_to = degrade_to
+
+        self._warned = False
+        self._lock = threading.Lock()
+
+    def check(self, tokens_used: int, estimated: int) -> PolicyDecision:
+        """Evaluate thresholds against *tokens_used* + *estimated*.
+
+        Returns the highest-severity decision that applies:
+
+        * :attr:`PolicyDecision.BLOCK` -- budget exhausted, call must not
+          proceed.
+        * :attr:`PolicyDecision.DEGRADE` -- budget nearly exhausted, swap
+          to a cheaper model.
+        * :attr:`PolicyDecision.WARN` -- approaching limit (fires once
+          per session).
+        * :attr:`PolicyDecision.ALLOW` -- under all thresholds.
+        """
+        if self.token_limit is None:
+            return PolicyDecision.ALLOW
+
+        projected = tokens_used + estimated
+        pct = (projected * 100) // self.token_limit
+
+        if pct >= self.block_at_pct:
+            return PolicyDecision.BLOCK
+
+        if pct >= self.degrade_at_pct:
+            return PolicyDecision.DEGRADE
+
+        if pct >= self.warn_at_pct:
+            with self._lock:
+                if not self._warned:
+                    self._warned = True
+                    return PolicyDecision.WARN
+            return PolicyDecision.ALLOW
+
+        return PolicyDecision.ALLOW
+
+    def update(self, policy_dict: dict[str, Any]) -> None:
+        """Atomically replace all fields from a directive payload."""
+        self.token_limit = policy_dict.get("token_limit", self.token_limit)
+        self.warn_at_pct = policy_dict.get("warn_at_pct", self.warn_at_pct)
+        self.degrade_at_pct = policy_dict.get("degrade_at_pct", self.degrade_at_pct)
+        self.block_at_pct = policy_dict.get("block_at_pct", self.block_at_pct)
+        self.degrade_to = policy_dict.get("degrade_to", self.degrade_to)
+        # Reset warn flag when policy changes
+        with self._lock:
+            self._warned = False

flightdeck_sensor-0.1.0a1/flightdeck_sensor/core/session.py

@@ -0,0 +1,271 @@
+"""Session lifecycle management for flightdeck-sensor.
+
+A ``Session`` represents one running instance of an agent.  It holds the
+sensor configuration, manages the heartbeat daemon thread, registers
+process-exit handlers, and posts lifecycle events to the control plane.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import signal
+import socket
+import threading
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from flightdeck_sensor.core.policy import PolicyCache
+from flightdeck_sensor.core.types import (
+    Directive,
+    DirectiveAction,
+    EventType,
+    SensorConfig,
+    SessionState,
+    StatusResponse,
+    TokenUsage,
+)
+
+if TYPE_CHECKING:
+    from flightdeck_sensor.transport.client import ControlPlaneClient
+
+_log = logging.getLogger("flightdeck_sensor.core.session")
+
+_HEARTBEAT_INTERVAL_SECS = 30
+
+
+class Session:
+    """Manages the lifecycle of a single sensor session."""
+
+    def __init__(
+        self,
+        config: SensorConfig,
+        client: ControlPlaneClient,
+    ) -> None:
+        self.config = config
+        self.client = client
+        self.policy = PolicyCache()
+
+        self._state = SessionState.ACTIVE
+        self._tokens_used = 0
+        self._token_limit: int | None = None
+        self._lock = threading.Lock()
+
+        self._stopped = threading.Event()
+        self._heartbeat_thread: threading.Thread | None = None
+        self._host = socket.gethostname()
+        self._framework: str | None = None
+        self._model: str | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Fire SESSION_START and begin the heartbeat daemon thread."""
+        self._post_event(EventType.SESSION_START)
+        self._start_heartbeat()
+        self._register_handlers()
+        if not self.config.quiet:
+            _log.info(
+                "Flightdeck session started: flavor=%s session=%s",
+                self.config.agent_flavor,
+                self.config.session_id,
+            )
+
+    def end(self) -> None:
+        """Fire SESSION_END and stop the heartbeat thread.
+
+        Safe to call multiple times -- second call is a no-op.
+        """
+        if self._state == SessionState.CLOSED:
+            return
+        self._state = SessionState.CLOSED
+        self._stopped.set()
+        if self._heartbeat_thread is not None:
+            self._heartbeat_thread.join(timeout=5)
+        self._post_event(EventType.SESSION_END)
+        self.client.close()
+        if not self.config.quiet:
+            _log.info(
+                "Flightdeck session ended: session=%s tokens=%d",
+                self.config.session_id,
+                self._tokens_used,
+            )
+
+    def record_usage(self, usage: TokenUsage) -> None:
+        """Atomically increment session token counts."""
+        with self._lock:
+            self._tokens_used += usage.total
+
+    def record_model(self, model: str) -> None:
+        """Record the model used in the most recent call."""
+        self._model = model
+
+    def record_framework(self, framework: str) -> None:
+        """Record the framework if detected."""
+        self._framework = framework
+
+    def post_call_event(
+        self,
+        event_type: EventType,
+        usage: TokenUsage,
+        model: str,
+        latency_ms: int,
+        tool_name: str | None = None,
+    ) -> Directive | None:
+        """Post a call event and return any received directive."""
+        self.record_usage(usage)
+        self.record_model(model)
+        return self._post_event(
+            event_type,
+            model=model,
+            tokens_input=usage.input_tokens,
+            tokens_output=usage.output_tokens,
+            tokens_total=usage.total,
+            latency_ms=latency_ms,
+            tool_name=tool_name,
+        )
+
+    def get_status(self) -> StatusResponse:
+        """Build a status snapshot of the current session."""
+        with self._lock:
+            tokens = self._tokens_used
+        limit = self._token_limit
+        pct: float | None = None
+        if limit is not None and limit > 0:
+            pct = round((tokens / limit) * 100, 1)
+        return StatusResponse(
+            session_id=self.config.session_id,
+            flavor=self.config.agent_flavor,
+            agent_type=self.config.agent_type,
+            state=self._state,
+            tokens_used=tokens,
+            token_limit=limit,
+            pct_used=pct,
+        )
+
+    @property
+    def state(self) -> SessionState:
+        return self._state
+
+    @property
+    def tokens_used(self) -> int:
+        with self._lock:
+            return self._tokens_used
+
+    @property
+    def token_limit(self) -> int | None:
+        return self._token_limit
+
+    # ------------------------------------------------------------------
+    # Heartbeat
+    # ------------------------------------------------------------------
+
+    def _start_heartbeat(self) -> None:
+        self._heartbeat_thread = threading.Thread(
+            target=self._heartbeat_loop,
+            daemon=True,
+            name="flightdeck-heartbeat",
+        )
+        self._heartbeat_thread.start()
+
+    def _heartbeat_loop(self) -> None:
+        """Daemon thread: post heartbeat every 30 s until stopped."""
+        while not self._stopped.wait(timeout=_HEARTBEAT_INTERVAL_SECS):
+            directive = self.client.post_heartbeat(self.config.session_id)
+            if directive is not None:
+                self._apply_directive(directive)
+
+    # ------------------------------------------------------------------
+    # Event posting
+    # ------------------------------------------------------------------
+
+    def _post_event(
+        self,
+        event_type: EventType,
+        **extra: Any,
+    ) -> Directive | None:
+        """Build the full event payload and POST it to the control plane."""
+        payload = self._build_payload(event_type, **extra)
+        directive = self.client.post_event(payload)
+        if directive is not None:
+            self._apply_directive(directive)
+        return directive
+
+    def _build_payload(
+        self,
+        event_type: EventType,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        with self._lock:
+            tokens_used_session = self._tokens_used
+
+        payload: dict[str, Any] = {
+            "session_id": self.config.session_id,
+            "flavor": self.config.agent_flavor,
+            "agent_type": self.config.agent_type,
+            "event_type": event_type.value,
+            "host": self._host,
+            "framework": self._framework,
+            "model": self._model,
+            "tokens_input": None,
+            "tokens_output": None,
+            "tokens_total": None,
+            "tokens_used_session": tokens_used_session,
+            "token_limit_session": self._token_limit,
+            "latency_ms": None,
+            "tool_name": None,
+            "tool_input": None,
+            "tool_result": None,
+            "has_content": False,
+            "content": None,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        payload.update(extra)
+        return payload
+
+    # ------------------------------------------------------------------
+    # Directives
+    # ------------------------------------------------------------------
+
+    def _apply_directive(self, directive: Directive) -> None:
+        """Handle a directive received from the control plane."""
+        if directive.action == DirectiveAction.POLICY_UPDATE:
+            _log.info("Policy update received")
+        elif directive.action in (
+            DirectiveAction.SHUTDOWN,
+            DirectiveAction.SHUTDOWN_FLAVOR,
+        ):
+            _log.warning(
+                "Shutdown directive received: %s (reason: %s)",
+                directive.action.value,
+                directive.reason,
+            )
+        else:
+            _log.info("Directive received: %s", directive.action.value)
+
+    # ------------------------------------------------------------------
+    # Process exit handlers
+    # ------------------------------------------------------------------
+
+    def _register_handlers(self) -> None:
+        """Register atexit and signal handlers for clean shutdown."""
+        atexit.register(self.end)
+        # Only register signal handlers on the main thread
+        if threading.current_thread() is threading.main_thread():
+            self._register_signal(signal.SIGTERM)
+            if os.name != "nt":
+                self._register_signal(signal.SIGINT)
+
+    def _register_signal(self, sig: signal.Signals) -> None:
+        """Install a signal handler that calls end() and re-raises."""
+        prev = signal.getsignal(sig)
+
+        def _handler(signum: int, frame: Any) -> None:
+            self.end()
+            if callable(prev):
+                prev(signum, frame)
+
+        signal.signal(sig, _handler)

flightdeck_sensor-0.1.0a1/flightdeck_sensor/core/types.py

@@ -0,0 +1,96 @@
+"""Pure data types for flightdeck-sensor. No external dependencies."""
+
+from __future__ import annotations
+
+import enum
+import uuid
+from dataclasses import dataclass, field
+
+
+class SessionState(enum.Enum):
+    """Lifecycle state of a sensor session."""
+
+    ACTIVE = "active"
+    IDLE = "idle"
+    STALE = "stale"
+    CLOSED = "closed"
+    LOST = "lost"
+
+
+class EventType(enum.Enum):
+    """All event types the sensor can emit."""
+
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+    HEARTBEAT = "heartbeat"
+    PRE_CALL = "pre_call"
+    POST_CALL = "post_call"
+    TOOL_CALL = "tool_call"
+
+
+class DirectiveAction(enum.Enum):
+    """Actions the control plane can instruct the sensor to take."""
+
+    SHUTDOWN = "shutdown"
+    SHUTDOWN_FLAVOR = "shutdown_flavor"
+    DEGRADE = "degrade"
+    THROTTLE = "throttle"
+    POLICY_UPDATE = "policy_update"
+    CHECKPOINT = "checkpoint"
+
+
+class PolicyDecision(enum.Enum):
+    """Result of a policy check against current token usage."""
+
+    ALLOW = "allow"
+    WARN = "warn"
+    DEGRADE = "degrade"
+    BLOCK = "block"
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    """Token counts from a single LLM call."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    @property
+    def total(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+@dataclass
+class SensorConfig:
+    """Configuration for a sensor session."""
+
+    server: str
+    token: str
+    capture_prompts: bool = False
+    unavailable_policy: str = "continue"
+    agent_flavor: str = "unknown"
+    agent_type: str = "autonomous"
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    quiet: bool = False
+
+
+@dataclass(frozen=True)
+class Directive:
+    """A control-plane directive received in the event response envelope."""
+
+    action: DirectiveAction
+    reason: str
+    grace_period_ms: int = 5000
+
+
+@dataclass
+class StatusResponse:
+    """Current status of the sensor session, returned by get_status()."""
+
+    session_id: str
+    flavor: str
+    agent_type: str
+    state: SessionState
+    tokens_used: int
+    token_limit: int | None
+    pct_used: float | None

flightdeck_sensor-0.1.0a1/flightdeck_sensor/providers/anthropic.py

@@ -0,0 +1,96 @@
+"""Anthropic provider: token estimation and usage extraction.
+
+Reimplements the patterns from tokencap -- this is a standalone
+implementation with no dependency on tokencap.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from typing import TYPE_CHECKING, Any
+
+from flightdeck_sensor.core.types import TokenUsage
+
+if TYPE_CHECKING:
+    from flightdeck_sensor.providers.protocol import PromptContent
+
+_log = logging.getLogger("flightdeck_sensor.providers.anthropic")
+
+
+class AnthropicProvider:
+    """Provider adapter for the Anthropic Python SDK.
+
+    All methods are safe to call on the hot path.  None of them raise
+    exceptions -- failures return zero/empty defaults.
+    """
+
+    def __init__(self, capture_prompts: bool = False) -> None:
+        self._capture_prompts = capture_prompts
+
+    def estimate_tokens(self, request_kwargs: dict[str, Any]) -> int:
+        """Estimate input tokens using a character-based heuristic.
+
+        Uses ``len(str(messages)) // 4`` as a conservative approximation.
+        The actual token count is reconciled after the call via
+        ``extract_usage()``.
+        """
+        try:
+            messages = request_kwargs.get("messages", [])
+            system = request_kwargs.get("system", "")
+            tools = request_kwargs.get("tools", [])
+            text = str(messages) + str(system) + str(tools)
+            return len(text) // 4
+        except Exception:
+            return 0
+
+    def extract_usage(self, response: Any) -> TokenUsage:
+        """Extract actual token counts from an Anthropic response.
+
+        Handles both sync ``Message`` objects and raw response wrappers.
+        Returns ``TokenUsage(0, 0)`` on any failure -- never raises.
+        """
+        try:
+            obj = response
+            # Handle raw response wrappers
+            if hasattr(obj, "parse") and callable(obj.parse):
+                with contextlib.suppress(Exception):
+                    obj = obj.parse()
+
+            usage = getattr(obj, "usage", None)
+            if usage is None:
+                return TokenUsage(input_tokens=0, output_tokens=0)
+
+            input_tokens = getattr(usage, "input_tokens", 0) or 0
+            output_tokens = getattr(usage, "output_tokens", 0) or 0
+
+            # Include cache tokens in input count for accurate totals
+            cache_read = getattr(usage, "cache_read_input_tokens", 0) or 0
+            cache_write = getattr(usage, "cache_creation_input_tokens", 0) or 0
+
+            return TokenUsage(
+                input_tokens=input_tokens + cache_read + cache_write,
+                output_tokens=output_tokens,
+            )
+        except Exception:
+            return TokenUsage(input_tokens=0, output_tokens=0)
+
+    def extract_content(
+        self,
+        request_kwargs: dict[str, Any],
+        response: Any,
+    ) -> PromptContent | None:
+        """Extract prompt content for storage.
+
+        Returns ``None`` in Phase 1 -- prompt capture is not implemented
+        until Phase 5.
+        """
+        return None
+
+    def get_model(self, request_kwargs: dict[str, Any]) -> str:
+        """Extract the model name from request kwargs."""
+        try:
+            model: str = request_kwargs["model"]
+            return model
+        except (KeyError, TypeError):
+            return ""

flightdeck_sensor-0.1.0a1/flightdeck_sensor/providers/openai.py

@@ -0,0 +1,124 @@
+"""OpenAI provider: token estimation and usage extraction.
+
+Reimplements the patterns from tokencap -- this is a standalone
+implementation with no dependency on tokencap.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from typing import TYPE_CHECKING, Any
+
+from flightdeck_sensor.core.types import TokenUsage
+
+if TYPE_CHECKING:
+    from flightdeck_sensor.providers.protocol import PromptContent
+
+_log = logging.getLogger("flightdeck_sensor.providers.openai")
+
+
+def _try_tiktoken_count(messages: list[Any], model: str) -> int | None:
+    """Attempt to count tokens using tiktoken if installed.
+
+    Returns ``None`` if tiktoken is unavailable or fails.
+    """
+    try:
+        import tiktoken
+
+        try:
+            enc = tiktoken.encoding_for_model(model)
+        except KeyError:
+            enc = tiktoken.get_encoding("cl100k_base")
+
+        total = 0
+        for msg in messages:
+            # Per-message overhead (role, content separators)
+            total += 4
+            if isinstance(msg, dict):
+                for value in msg.values():
+                    total += len(enc.encode(str(value)))
+        total += 2  # reply priming
+        return total
+    except Exception:
+        return None
+
+
+class OpenAIProvider:
+    """Provider adapter for the OpenAI Python SDK.
+
+    All methods are safe to call on the hot path.  None of them raise
+    exceptions -- failures return zero/empty defaults.
+    """
+
+    def __init__(self, capture_prompts: bool = False) -> None:
+        self._capture_prompts = capture_prompts
+
+    def estimate_tokens(self, request_kwargs: dict[str, Any]) -> int:
+        """Estimate input tokens using tiktoken if available, else char//4.
+
+        tiktoken gives accurate counts for OpenAI models.  The character
+        heuristic is a conservative fallback.
+        """
+        try:
+            messages = request_kwargs.get("messages", [])
+            model = request_kwargs.get("model", "")
+
+            # Try tiktoken first
+            count = _try_tiktoken_count(messages, model)
+            if count is not None:
+                return count
+
+            # Fallback: character-based heuristic
+            tools = request_kwargs.get("tools", [])
+            text = str(messages) + str(tools)
+            return len(text) // 4
+        except Exception:
+            return 0
+
+    def extract_usage(self, response: Any) -> TokenUsage:
+        """Extract actual token counts from an OpenAI response.
+
+        Handles both sync ``ChatCompletion`` objects and raw wrappers.
+        Returns ``TokenUsage(0, 0)`` on any failure -- never raises.
+        """
+        try:
+            obj = response
+            # Handle raw response wrappers
+            if hasattr(obj, "parse") and callable(obj.parse):
+                with contextlib.suppress(Exception):
+                    obj = obj.parse()
+
+            usage = getattr(obj, "usage", None)
+            if usage is None:
+                return TokenUsage(input_tokens=0, output_tokens=0)
+
+            prompt_tokens = getattr(usage, "prompt_tokens", 0) or 0
+            completion_tokens = getattr(usage, "completion_tokens", 0) or 0
+
+            return TokenUsage(
+                input_tokens=prompt_tokens,
+                output_tokens=completion_tokens,
+            )
+        except Exception:
+            return TokenUsage(input_tokens=0, output_tokens=0)
+
+    def extract_content(
+        self,
+        request_kwargs: dict[str, Any],
+        response: Any,
+    ) -> PromptContent | None:
+        """Extract prompt content for storage.
+
+        Returns ``None`` in Phase 1 -- prompt capture is not implemented
+        until Phase 5.
+        """
+        return None
+
+    def get_model(self, request_kwargs: dict[str, Any]) -> str:
+        """Extract the model name from request kwargs."""
+        try:
+            model: str = request_kwargs["model"]
+            return model
+        except (KeyError, TypeError):
+            return ""

flightdeck_sensor-0.1.0a1/flightdeck_sensor/providers/protocol.py

@@ -0,0 +1,60 @@
+"""Provider protocol and shared content dataclass."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from flightdeck_sensor.core.types import TokenUsage
+
+
+class Provider(Protocol):
+    """Interface every LLM provider adapter must implement.
+
+    All methods must be safe to call on the hot path. None of them
+    may raise exceptions -- failures return zero/empty defaults.
+    """
+
+    def estimate_tokens(self, request_kwargs: dict[str, Any]) -> int:
+        """Estimate input token count before the call. Never raises."""
+        ...
+
+    def extract_usage(self, response: Any) -> TokenUsage:
+        """Extract actual token counts from the provider response. Never raises."""
+        ...
+
+    def extract_content(
+        self,
+        request_kwargs: dict[str, Any],
+        response: Any,
+    ) -> PromptContent | None:
+        """Extract prompt content when capture_prompts is enabled.
+
+        Returns None when capture is disabled or on any error.
+        Never raises.
+        """
+        ...
+
+    def get_model(self, request_kwargs: dict[str, Any]) -> str:
+        """Extract the model name from request kwargs. Returns '' on failure."""
+        ...
+
+
+@dataclass
+class PromptContent:
+    """Raw content extracted from a single LLM call.
+
+    Provider terminology is preserved exactly -- no normalization.
+    Anthropic uses 'system' as a separate field; OpenAI embeds it in messages.
+    """
+
+    system: str | None
+    messages: list[dict[str, Any]]
+    tools: list[dict[str, Any]] | None
+    response: dict[str, Any]
+    provider: str
+    model: str
+    session_id: str
+    event_id: str
+    captured_at: str

flightdeck_sensor-0.1.0a1/flightdeck_sensor/transport/client.py

@@ -0,0 +1,124 @@
+"""HTTP transport to the Flightdeck control plane.
+
+Uses only the Python standard library (``urllib.request``).
+No ``requests``, no ``httpx`` -- zero required dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from typing import Any
+from urllib.error import HTTPError, URLError
+
+from flightdeck_sensor.core.exceptions import DirectiveError
+from flightdeck_sensor.core.types import Directive, DirectiveAction
+from flightdeck_sensor.transport.retry import with_retry
+
+_log = logging.getLogger("flightdeck_sensor.transport.client")
+
+_TIMEOUT_SECS = 10
+
+
+class ControlPlaneClient:
+    """Fire-and-forget HTTP client for sensor → control plane communication.
+
+    On connectivity failure the behaviour depends on *unavailable_policy*:
+
+    * ``"continue"`` -- log a warning, return ``None``, agent proceeds.
+    * ``"halt"`` -- raise :class:`DirectiveError`, agent must stop.
+    """
+
+    def __init__(
+        self,
+        server: str,
+        token: str,
+        unavailable_policy: str = "continue",
+    ) -> None:
+        self._base_url = server.rstrip("/")
+        self._token = token
+        self._unavailable_policy = unavailable_policy
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def post_event(self, payload: dict[str, Any]) -> Directive | None:
+        """POST an event to ``/v1/events`` and return any embedded directive."""
+        return self._post("/v1/events", payload)
+
+    def post_heartbeat(self, session_id: str) -> Directive | None:
+        """POST a heartbeat to ``/v1/heartbeat``."""
+        return self._post("/v1/heartbeat", {"session_id": session_id})
+
+    def close(self) -> None:
+        """No-op -- stdlib ``urllib`` has no persistent connection to close."""
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _post(self, path: str, body: dict[str, Any]) -> Directive | None:
+        """POST JSON and parse the response envelope for a directive."""
+        url = f"{self._base_url}{path}"
+        data = json.dumps(body).encode()
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._token}",
+            },
+            method="POST",
+        )
+
+        try:
+            raw = with_retry(lambda: self._do_request(req))
+        except (URLError, OSError, TimeoutError, ConnectionError) as exc:
+            return self._handle_unavailable(exc)
+
+        return self._parse_directive(raw)
+
+    def _do_request(self, req: urllib.request.Request) -> dict[str, Any]:
+        """Execute a single HTTP request and return the parsed JSON body.
+
+        Raises on HTTP 5xx so that :func:`with_retry` can retry.
+        HTTP 4xx is a caller bug -- log and return a neutral response.
+        """
+        try:
+            with urllib.request.urlopen(req, timeout=_TIMEOUT_SECS) as resp:
+                body: dict[str, Any] = json.loads(resp.read().decode())
+                return body
+        except HTTPError as exc:
+            if exc.code >= 500:
+                raise  # let retry handle it
+            # 4xx -- caller bug, not retryable
+            _log.warning("Control plane returned HTTP %d: %s", exc.code, exc.reason)
+            return {"status": "ok", "directive": None}
+
+    def _handle_unavailable(self, exc: BaseException) -> Directive | None:
+        """Apply the unavailability policy after exhausting retries."""
+        if self._unavailable_policy == "halt":
+            raise DirectiveError(
+                action="halt",
+                reason=f"Control plane unreachable: {exc}",
+            )
+        _log.warning("Control plane unreachable (policy=continue): %s", exc)
+        return None
+
+    @staticmethod
+    def _parse_directive(body: dict[str, Any]) -> Directive | None:
+        """Extract a :class:`Directive` from the response envelope, if present."""
+        raw = body.get("directive")
+        if raw is None:
+            return None
+        try:
+            return Directive(
+                action=DirectiveAction(raw["action"]),
+                reason=raw.get("reason", ""),
+                grace_period_ms=raw.get("grace_period_ms", 5000),
+            )
+        except (KeyError, ValueError) as exc:
+            _log.warning("Malformed directive in response: %s (%s)", raw, exc)
+            return None

flightdeck_sensor-0.1.0a1/flightdeck_sensor/transport/retry.py

@@ -0,0 +1,53 @@
+"""Exponential backoff retry for transient HTTP failures."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable, TypeVar
+from urllib.error import URLError
+
+_T = TypeVar("_T")
+
+_log = logging.getLogger("flightdeck_sensor.transport.retry")
+
+
+def with_retry(
+    fn: Callable[[], _T],
+    *,
+    max_attempts: int = 3,
+    backoff_base: float = 0.5,
+    retryable: tuple[type[BaseException], ...] = (
+        ConnectionError,
+        TimeoutError,
+        URLError,
+        OSError,
+    ),
+) -> _T:
+    """Execute *fn* with exponential backoff on transient failures.
+
+    Retries on connection errors, timeouts, and ``URLError``.
+    HTTP 5xx responses must be converted to exceptions by the caller
+    before reaching this function.
+
+    Raises the final exception unchanged after *max_attempts* failures.
+    """
+    last_exc: BaseException | None = None
+    for attempt in range(max_attempts):
+        try:
+            return fn()
+        except retryable as exc:
+            last_exc = exc
+            if attempt < max_attempts - 1:
+                delay = backoff_base * (2**attempt)
+                _log.warning(
+                    "Transient failure (attempt %d/%d), retrying in %.1fs: %s",
+                    attempt + 1,
+                    max_attempts,
+                    delay,
+                    exc,
+                )
+                time.sleep(delay)
+    # Should never reach here without last_exc being set, but mypy needs the assert.
+    assert last_exc is not None
+    raise last_exc

flightdeck_sensor-0.1.0a1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "flightdeck-sensor"
+version = "0.1.0a1"
+description = "In-process agent observability sensor for Flightdeck"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.20"]
+openai = ["openai>=1.0", "tiktoken>=0.5"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.8",
+    "ruff>=0.3",
+    "httpx>=0.25",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["flightdeck_sensor"]
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_any_generics = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"