prefactor-core 0.2.2__tar.gz → 0.2.3__tar.gz

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/.gitignore

@@ -69,3 +69,4 @@ htmlcov/
 # Env
 .env
 mise.local.toml
+prefactor.json

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.2
+Version: 0.2.3
 Summary: Core Prefactor SDK with async queue-based operations
 Author-email: Prefactor Pty Ltd <josh@prefactor.tech>
 License: MIT

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prefactor-core"
-version = "0.2.2"
+dynamic = ["version"]
 description = "Core Prefactor SDK with async queue-based operations"
 readme = "README.md"
 license = { text = "MIT" }
@@ -17,6 +17,9 @@ dependencies = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "src/prefactor_core/_version.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/prefactor_core"]
 

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/__init__.py

@@ -3,6 +3,9 @@
 This module exports the main classes and functions for the prefactor-core SDK.
 """
 
+from __future__ import annotations
+
+from ._version import __version__
 from .client import PrefactorCoreClient
 from .config import PrefactorCoreConfig, QueueConfig
 from .context_stack import SpanContextStack
@@ -12,6 +15,7 @@ from .exceptions import (
     InstanceNotFoundError,
     OperationError,
     PrefactorCoreError,
+    PrefactorTelemetryFailureError,
     SpanNotFoundError,
 )
 from .managers.agent_instance import AgentInstanceHandle
@@ -22,8 +26,6 @@ from .schema_registry import SchemaRegistry
 from .span_context import SpanContext
 from .utils import generate_idempotency_key, validate_idempotency_key
 
-__version__ = "0.2.1"
-
 __all__ = [
     # Client
     "PrefactorCoreClient",
@@ -40,6 +42,7 @@ __all__ = [
     "OperationError",
     "InstanceNotFoundError",
     "SpanNotFoundError",
+    "PrefactorTelemetryFailureError",
     # Models
     "AgentInstance",
     "Span",
@@ -58,4 +61,5 @@ __all__ = [
     # Utils
     "generate_idempotency_key",
     "validate_idempotency_key",
+    "__version__",
 ]

prefactor_core-0.2.3/src/prefactor_core/_version.py

@@ -0,0 +1,7 @@
+"""Package version for prefactor-core."""
+
+from __future__ import annotations
+
+PACKAGE_NAME = "prefactor-core"
+__version__ = "0.2.3"
+PACKAGE_VERSION = __version__

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/client.py

@@ -13,12 +13,16 @@ from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
 from prefactor_http.client import PrefactorHttpClient
+from prefactor_http.exceptions import is_permanent_http_error, is_transient_http_error
 
+from ._version import PACKAGE_NAME as CORE_PACKAGE_NAME
+from ._version import PACKAGE_VERSION as CORE_PACKAGE_VERSION
 from .config import PrefactorCoreConfig
 from .context_stack import SpanContextStack
 from .exceptions import (
     ClientAlreadyInitializedError,
     ClientNotInitializedError,
+    PrefactorTelemetryFailureError,
 )
 from .managers.agent_instance import AgentInstanceManager
 from .managers.span import SpanManager
@@ -31,6 +35,7 @@ if TYPE_CHECKING:
     from .managers.agent_instance import AgentInstanceHandle
 
 logger = logging.getLogger(__name__)
+CORE_SDK_HEADER_ENTRY = f"{CORE_PACKAGE_NAME}@{CORE_PACKAGE_VERSION}"
 
 
 class PrefactorCoreClient:
@@ -61,6 +66,7 @@ class PrefactorCoreClient:
         self,
         config: PrefactorCoreConfig,
         queue: Queue[Operation] | None = None,
+        sdk_header_entry: str | None = None,
     ) -> None:
         """Initialize the client.
 
@@ -68,14 +74,30 @@ class PrefactorCoreClient:
             config: Configuration for the client.
             queue: Optional custom queue implementation. If not provided,
                 an InMemoryQueue is used.
+            sdk_header_entry: Optional upstream SDK header entry to prepend.
         """
         self._config = config
         self._queue = queue or InMemoryQueue()
+        self._sdk_header_entry = sdk_header_entry.strip() if sdk_header_entry else None
         self._http: PrefactorHttpClient | None = None
         self._executor: TaskExecutor | None = None
         self._instance_manager: AgentInstanceManager | None = None
         self._span_manager: SpanManager | None = None
         self._initialized = False
+        self._telemetry_failure: PrefactorTelemetryFailureError | None = None
+        self._telemetry_failure_observed = False
+
+    def _build_http_sdk_header(self) -> str:
+        """Build the effective SDK header for HTTP requests."""
+        if self._sdk_header_entry:
+            return f"{self._sdk_header_entry} {CORE_SDK_HEADER_ENTRY}"
+        return CORE_SDK_HEADER_ENTRY
+
+    def _set_sdk_header_entry(self, sdk_header_entry: str | None) -> None:
+        """Set the upstream SDK header entry for this client lifetime."""
+        self._sdk_header_entry = sdk_header_entry.strip() if sdk_header_entry else None
+        if self._http is not None:
+            self._http._sdk_header = self._build_http_sdk_header()
 
     async def __aenter__(self) -> "PrefactorCoreClient":
         """Enter async context manager."""
@@ -84,7 +106,11 @@ class PrefactorCoreClient:
 
     async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """Exit async context manager."""
-        await self.close()
+        try:
+            await self.close()
+        except PrefactorTelemetryFailureError:
+            if exc_type is None:
+                raise
 
     async def initialize(self) -> None:
         """Initialize the client and start processing.
@@ -101,13 +127,17 @@ class PrefactorCoreClient:
             raise ClientAlreadyInitializedError("Client is already initialized")
 
         # Initialize HTTP client
-        self._http = PrefactorHttpClient(self._config.http_config)
+        self._http = PrefactorHttpClient(
+            self._config.http_config,
+            sdk_header=self._build_http_sdk_header(),
+        )
         await self._http.__aenter__()
 
         # Initialize executor
         self._executor = TaskExecutor(
             queue=self._queue,
             handler=self._process_operation,
+            is_retryable=self._is_retryable_operation_error,
             num_workers=self._config.queue_config.num_workers,
             max_retries=self._config.queue_config.max_retries,
         )
@@ -144,6 +174,10 @@ class PrefactorCoreClient:
 
         self._initialized = False
 
+        if self._telemetry_failure is not None and not self._telemetry_failure_observed:
+            self._telemetry_failure_observed = True
+            raise self._telemetry_failure
+
     def _ensure_initialized(self) -> None:
         """Ensure the client is initialized.
 
@@ -156,12 +190,55 @@ class PrefactorCoreClient:
                 "use as context manager."
             )
 
+    def _record_telemetry_failure(
+        self, cause: Exception, operation_type: OperationType | str
+    ) -> None:
+        """Latch the first permanent telemetry failure."""
+        if self._telemetry_failure is not None:
+            return
+        if isinstance(operation_type, OperationType):
+            operation_name = operation_type.name
+        else:
+            operation_name = str(operation_type)
+        self._telemetry_failure = PrefactorTelemetryFailureError(
+            f"Telemetry permanently failed during {operation_name}",
+            cause=cause,
+            operation_type=operation_name,
+            dropped_operations=0,
+        )
+
+    def _increment_dropped_operations(self) -> None:
+        """Increment the dropped operation counter on the latched failure."""
+        if self._telemetry_failure is None:
+            return
+        self._telemetry_failure.dropped_operations += 1
+
+    def _raise_if_telemetry_failed(self) -> None:
+        """Raise the latched telemetry failure for caller-visible operations."""
+        if self._telemetry_failure is None:
+            return
+        self._telemetry_failure_observed = True
+        raise self._telemetry_failure
+
+    def _is_retryable_operation_error(self, error: Exception) -> bool:
+        """Return True when the worker should retry the operation."""
+        if isinstance(error, PrefactorTelemetryFailureError):
+            return False
+        if is_permanent_http_error(error):
+            return False
+        if is_transient_http_error(error):
+            return True
+        return True
+
     async def _enqueue(self, operation: Operation) -> None:
         """Add an operation to the queue.
 
         Args:
             operation: The operation to queue.
         """
+        if self._telemetry_failure is not None:
+            self._increment_dropped_operations()
+            self._raise_if_telemetry_failed()
         await self._queue.put(operation)
 
     async def _process_operation(self, operation: Operation) -> None:
@@ -174,6 +251,9 @@ class PrefactorCoreClient:
         """
         if not self._http:
             return
+        if self._telemetry_failure is not None:
+            self._increment_dropped_operations()
+            return
 
         try:
             if operation.type == OperationType.REGISTER_AGENT_INSTANCE:
@@ -217,6 +297,8 @@ class PrefactorCoreClient:
                 )
 
         except Exception as e:
+            if is_permanent_http_error(e):
+                self._record_telemetry_failure(e, operation.type)
             # Log error and re-raise so TaskExecutor retries can run
             logger.error(
                 f"Failed to process operation {operation.type}: {e}",
@@ -262,6 +344,7 @@ class PrefactorCoreClient:
             ValueError: If no schema version provided and registry not configured.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._instance_manager is not None
 
         # Determine the agent_schema_version to use
@@ -318,6 +401,7 @@ class PrefactorCoreClient:
             The span ID.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._span_manager is not None
 
         if parent_span_id is None:
@@ -380,6 +464,7 @@ class PrefactorCoreClient:
             SpanContext for the created span.
         """
         self._ensure_initialized()
+        self._raise_if_telemetry_failed()
         assert self._span_manager is not None
 
         # Import here to avoid circular import

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/exceptions.py

@@ -1,5 +1,7 @@
 """Custom exceptions for prefactor-core."""
 
+from __future__ import annotations
+
 
 class PrefactorCoreError(Exception):
     """Base exception for all prefactor-core errors."""
@@ -39,6 +41,23 @@ class SpanNotFoundError(PrefactorCoreError):
     pass
 
 
+class PrefactorTelemetryFailureError(PrefactorCoreError):
+    """Raised when telemetry enters a permanent failure state."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        cause: Exception,
+        operation_type: str | None = None,
+        dropped_operations: int = 0,
+    ) -> None:
+        super().__init__(message)
+        self.cause = cause
+        self.operation_type = operation_type
+        self.dropped_operations = dropped_operations
+
+
 __all__ = [
     "PrefactorCoreError",
     "ClientNotInitializedError",
@@ -46,4 +65,5 @@ __all__ = [
     "OperationError",
     "InstanceNotFoundError",
     "SpanNotFoundError",
+    "PrefactorTelemetryFailureError",
 ]

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/managers/agent_instance.py

@@ -96,11 +96,19 @@ class AgentInstanceManager:
         Args:
             instance_id: The ID of the instance to start.
         """
+        await self.start_with_idempotency_key(instance_id, generate_idempotency_key())
+
+    async def start_with_idempotency_key(
+        self,
+        instance_id: str,
+        idempotency_key: str,
+    ) -> None:
+        """Queue a start operation using a stable idempotency key."""
         operation = Operation(
             type=OperationType.START_AGENT_INSTANCE,
             payload={
                 "instance_id": instance_id,
-                "idempotency_key": generate_idempotency_key(),
+                "idempotency_key": idempotency_key,
             },
             timestamp=datetime.now(timezone.utc),
         )
@@ -115,11 +123,19 @@ class AgentInstanceManager:
         Args:
             instance_id: The ID of the instance to finish.
         """
+        await self.finish_with_idempotency_key(instance_id, generate_idempotency_key())
+
+    async def finish_with_idempotency_key(
+        self,
+        instance_id: str,
+        idempotency_key: str,
+    ) -> None:
+        """Queue a finish operation using a stable idempotency key."""
         operation = Operation(
             type=OperationType.FINISH_AGENT_INSTANCE,
             payload={
                 "instance_id": instance_id,
-                "idempotency_key": generate_idempotency_key(),
+                "idempotency_key": idempotency_key,
             },
             timestamp=datetime.now(timezone.utc),
         )
@@ -159,8 +175,8 @@ class AgentInstanceHandle:
         """
         self._instance_id = instance_id
         self._client = client
-        self._started = False
-        self._finished = False
+        self._start_idempotency_key = generate_idempotency_key()
+        self._finish_idempotency_key = generate_idempotency_key()
 
     @property
     def id(self) -> str:
@@ -176,26 +192,24 @@ class AgentInstanceHandle:
 
         This queues a start operation for the instance.
         """
-        if self._started:
-            return
-
         manager = self._client.instance_manager
         assert manager is not None
-        await manager.start(self._instance_id)
-        self._started = True
+        await manager.start_with_idempotency_key(
+            self._instance_id,
+            self._start_idempotency_key,
+        )
 
     async def finish(self) -> None:
         """Mark the instance as finished.
 
         This queues a finish operation for the instance.
         """
-        if self._finished:
-            return
-
         manager = self._client.instance_manager
         assert manager is not None
-        await manager.finish(self._instance_id)
-        self._finished = True
+        await manager.finish_with_idempotency_key(
+            self._instance_id,
+            self._finish_idempotency_key,
+        )
 
     async def create_span(
         self,
@@ -215,6 +229,7 @@ class AgentInstanceHandle:
         Returns:
             The span ID.
         """
+        self._client._raise_if_telemetry_failed()
         return await self._client.create_span(
             instance_id=self._instance_id,
             schema_name=schema_name,

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/managers/span.py

@@ -151,6 +151,10 @@ class SpanManager:
         del self._spans[temp_id]
         self._spans[api_id] = span
 
+        for child_span in self._spans.values():
+            if child_span.parent_span_id == temp_id:
+                child_span.parent_span_id = api_id
+
         # Replace temp ID on the context stack
         stack = SpanContextStack.get_stack()
         new_stack = [api_id if s == temp_id else s for s in stack]
@@ -242,6 +246,7 @@ class SpanManager:
         span_id: str,
         result_payload: dict[str, Any] | None = None,
         status: "FinishStatus" = "complete",
+        idempotency_key: str | None = None,
     ) -> None:
         """Mark a span as finished.
 
@@ -254,6 +259,8 @@ class SpanManager:
                 ``"cancelled"`` (default: ``"complete"``). The span must be
                 ``active`` for this to succeed; use ``cancel_unstarted()``
                 to cancel a span that was never started.
+            idempotency_key: Optional key to make repeated finish requests
+                duplicate-safe. When omitted, a new key is generated.
 
         Raises:
             KeyError: If the span ID is not known.
@@ -273,7 +280,7 @@ class SpanManager:
         op_payload: dict[str, Any] = {
             "span_id": span_id,
             "status": status,
-            "idempotency_key": generate_idempotency_key(),
+            "idempotency_key": idempotency_key or generate_idempotency_key(),
         }
         if result_payload is not None:
             op_payload["result_payload"] = result_payload

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/queue/executor.py

@@ -42,6 +42,8 @@ class TaskExecutor:
         handler: Callable[[Any], Awaitable[None]],
         num_workers: int = 3,
         max_retries: int = 3,
+        *,
+        is_retryable: Callable[[Exception], bool] | None = None,
     ) -> None:
         """Initialize the task executor.
 
@@ -50,9 +52,12 @@ class TaskExecutor:
             handler: Async function to process each item.
             num_workers: Number of concurrent worker tasks.
             max_retries: Maximum retry attempts per item.
+            is_retryable: Optional predicate that decides whether a
+                handler failure should be retried.
         """
         self._queue = queue
         self._handler = handler
+        self._is_retryable = is_retryable or (lambda exc: True)
         self._num_workers = num_workers
         self._max_retries = max_retries
         self._workers: list[Task] = []
@@ -162,13 +167,17 @@ class TaskExecutor:
         """
         last_error: Exception | None = None
 
-        for attempt in range(self._max_retries):
+        total_attempts = self._max_retries + 1
+
+        for attempt in range(total_attempts):
             try:
                 await self._handler(item)
                 return
             except Exception as e:
                 last_error = e
-                if attempt < self._max_retries - 1:
+                if not self._is_retryable(e):
+                    raise
+                if attempt < total_attempts - 1:
                     delay = 2**attempt  # 1s, 2s, 4s
                     logger.warning(
                         f"Attempt {attempt + 1} failed, retrying in {delay}s: {e}"

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/queue/memory.py

@@ -6,7 +6,7 @@ for durability requirements.
 """
 
 from asyncio import Queue as AsyncQueue
-from typing import TypeVar
+from typing import TypeVar, cast
 
 from .base import Queue, QueueClosedError
 
@@ -34,7 +34,7 @@ class InMemoryQueue(Queue[T]):
 
     def __init__(self) -> None:
         """Initialize an empty in-memory queue."""
-        self._queue: AsyncQueue[T] = AsyncQueue()
+        self._queue: AsyncQueue[T | object] = AsyncQueue()
         self._closed = False
 
     async def put(self, item: T) -> None:
@@ -66,7 +66,7 @@ class InMemoryQueue(Queue[T]):
         # Re-raise as closed so the worker exits cleanly.
         if item is self._SENTINEL:
             raise QueueClosedError("Queue is closed and empty")
-        return item
+        return cast(T, item)
 
     def size(self) -> int:
         """Return the current number of items in the queue.
@@ -89,7 +89,7 @@ class InMemoryQueue(Queue[T]):
         self._closed = True
         # Wake any workers blocked in asyncio.Queue.get() so they can exit.
         for _ in range(num_waiters):
-            await self._queue.put(self._SENTINEL)  # type: ignore[arg-type]
+            await self._queue.put(self._SENTINEL)
 
     @property
     def closed(self) -> bool:

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/schema_registry.py

@@ -4,6 +4,8 @@ This module provides a SchemaRegistry that allows registration of span schemas
 from multiple packages before agent instances are created.
 """
 
+from __future__ import annotations
+
 from typing import Any
 
 
@@ -131,12 +133,13 @@ class SchemaRegistry:
         title: str | None = None,
         description: str | None = None,
         template: str | None = None,
+        data_risk: dict[str, Any] | None = None,
     ) -> None:
         """Register a full structured span type schema.
 
         Adds to ``span_type_schemas``. This is the richest form and supports
         all API fields: params schema, result schema, human-readable title,
-        description, and a display template.
+        description, template, and data risk classification.
 
         Args:
             name: Span type name (e.g., "agent:llm")
@@ -145,6 +148,25 @@ class SchemaRegistry:
             title: Optional human-readable title (defaults to name on the API)
             description: Optional description of the span type
             template: Optional display template using ``{{field}}`` interpolation
+            data_risk: Optional data risk classification dict. See DataRisk model
+                in prefactor_http.models.agent_instance for structure. Must include:
+                - action_profile (object): Permitted actions with keys:
+                  create_data, read_data, update_data, destroy_data,
+                  financial_transactions, external_communication (values:
+                  "unknown" | "allowed" | "disallowed")
+                - params_data_categories (object): Input data categories with keys
+                  like personal_identifiers, contact_information,
+                  financial_information, etc. (values: "unknown" | "included"
+                  | "excluded")
+                - result_data_categories (object): Output data categories,
+                  same structure as params_data_categories
+                All three top-level keys are required; fields within each default
+                to "unknown" when omitted.
+                Example: {
+                    "action_profile": {"read_data": "allowed"},
+                    "params_data_categories": {"personal_identifiers": "included"},
+                    "result_data_categories": {},
+                }
 
         Raises:
             ValueError: If name is already registered as a span type schema.
@@ -161,6 +183,8 @@ class SchemaRegistry:
             entry["description"] = description
         if template is not None:
             entry["template"] = template
+        if data_risk is not None:
+            entry["data_risk"] = data_risk
 
         self._span_type_schemas[name] = entry
 

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/src/prefactor_core/span_context.py

@@ -4,9 +4,15 @@ The SpanContext provides an interface for updating span data during execution
 and ensures proper cleanup when the span completes.
 """
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING, Any
 
+from .utils import generate_idempotency_key
+
 if TYPE_CHECKING:
+    from prefactor_http.models.types import FinishStatus
+
     from .managers.span import SpanManager
 
 
@@ -67,9 +73,13 @@ class SpanContext:
         self._span_manager = span_manager
         self._default_payload = default_payload
         self._result_payload: dict[str, Any] = {}
-        self._finish_status: str = "complete"
+        self._finish_status: FinishStatus = "complete"
         self._started = False
         self._finished = False
+        self._finish_request: (
+            tuple[FinishStatus, tuple[tuple[str, Any], ...]] | None
+        ) = None
+        self._finish_idempotency_key: str | None = None
 
     @property
     def id(self) -> str:
@@ -167,24 +177,37 @@ class SpanContext:
         valid pre-active cancellation path.  For all other statuses the span
         is auto-started as ``active`` first.
         """
+        request = (
+            self._finish_status,
+            tuple(sorted(self._result_payload.items())),
+        )
         if self._finished:
             return
-
-        self._finished = True
+        if self._finish_request != request:
+            self._finish_request = (
+                self._finish_status,
+                tuple(sorted(self._result_payload.items())),
+            )
+            self._finish_idempotency_key = None
 
         try:
             if not self._started and self._finish_status == "cancelled":
                 await self._span_manager.cancel_unstarted(self._span_id)
+                self._finished = True
                 return
 
             if not self._started:
                 await self.start(self._default_payload)
 
+            if self._finish_idempotency_key is None:
+                self._finish_idempotency_key = generate_idempotency_key()
             await self._span_manager.finish(
                 self._span_id,
                 result_payload=self._result_payload or None,
-                status=self._finish_status,  # type: ignore[arg-type]
+                status=self._finish_status,
+                idempotency_key=self._finish_idempotency_key,
             )
+            self._finished = True
         except Exception:
             raise
 

prefactor_core-0.2.3/tests/test_failure_handling.py

@@ -0,0 +1,322 @@
+"""Tests for permanent telemetry failure handling in prefactor-core."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import aiohttp
+import pytest
+from prefactor_core import PrefactorCoreClient
+from prefactor_core.config import PrefactorCoreConfig, QueueConfig
+from prefactor_core.exceptions import PrefactorTelemetryFailureError
+from prefactor_http.config import HttpClientConfig
+from prefactor_http.exceptions import (
+    PrefactorAuthError,
+    PrefactorResponseContractError,
+    PrefactorRetryExhaustedError,
+)
+
+
+class _StubAgentInstances:
+    def __init__(
+        self,
+        *,
+        start_side_effect: Exception | None = None,
+        finish_side_effect: Exception | None = None,
+    ) -> None:
+        self.start_side_effect = start_side_effect
+        self.finish_side_effect = finish_side_effect
+        self.start_calls = 0
+        self.finish_calls = 0
+
+    async def register(self, **kwargs):
+        return SimpleNamespace(id=kwargs.get("id") or "inst-1")
+
+    async def start(self, **kwargs):
+        self.start_calls += 1
+        if self.start_side_effect is not None:
+            raise self.start_side_effect
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+    async def finish(self, **kwargs):
+        self.finish_calls += 1
+        if self.finish_side_effect is not None:
+            raise self.finish_side_effect
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+
+class _StubAgentSpans:
+    def __init__(self) -> None:
+        self.create_calls = []
+        self.finish_calls = []
+
+    async def create(self, **kwargs):
+        self.create_calls.append(kwargs)
+        return SimpleNamespace(id=f"span-{len(self.create_calls)}")
+
+    async def finish(self, **kwargs):
+        self.finish_calls.append(kwargs)
+        return SimpleNamespace(id=kwargs["agent_span_id"])
+
+
+class _StubHttpClient:
+    def __init__(
+        self,
+        *_args,
+        agent_instances: _StubAgentInstances | None = None,
+        agent_spans: _StubAgentSpans | None = None,
+        **_kwargs,
+    ) -> None:
+        self.agent_instances = agent_instances or _StubAgentInstances()
+        self.agent_spans = agent_spans or _StubAgentSpans()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return None
+
+
+def _make_client_config(max_retries: int = 0) -> PrefactorCoreConfig:
+    return PrefactorCoreConfig(
+        http_config=HttpClientConfig(
+            api_url="https://api.test.com",
+            api_token="test-token",
+            max_retries=0,
+            initial_retry_delay=0.01,
+            max_retry_delay=0.02,
+        ),
+        queue_config=QueueConfig(num_workers=1, max_retries=max_retries),
+    )
+
+
+async def _wait_until(
+    predicate, *, timeout: float = 1.0, interval: float = 0.01
+) -> None:
+    deadline = asyncio.get_running_loop().time() + timeout
+    while asyncio.get_running_loop().time() < deadline:
+        if predicate():
+            return
+        await asyncio.sleep(interval)
+    raise AssertionError("Timed out waiting for expected condition")
+
+
+@pytest.mark.asyncio
+async def test_permanent_worker_failure_latches_and_rejects_future_operations():
+    """Permanent failures should latch and reject later queued operations."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            start_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.start()
+        await _wait_until(lambda: client._telemetry_failure is not None)
+
+        with pytest.raises(PrefactorTelemetryFailureError) as exc_info:
+            await instance.finish()
+
+        assert exc_info.value.operation_type == "START_AGENT_INSTANCE"
+        assert isinstance(exc_info.value.cause, PrefactorAuthError)
+        assert exc_info.value.dropped_operations == 1
+
+        await client.close()
+
+
+@pytest.mark.asyncio
+async def test_close_raises_latched_failure_when_not_previously_observed():
+    """close() should surface the latched permanent failure."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            start_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.start()
+        await _wait_until(lambda: client._telemetry_failure is not None)
+
+        with pytest.raises(PrefactorTelemetryFailureError):
+            await client.close()
+
+
+@pytest.mark.asyncio
+async def test_close_raises_permanent_failure_first_latched_during_shutdown():
+    """close() should surface permanent failures discovered while draining shutdown."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            finish_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.finish()
+
+        with pytest.raises(PrefactorTelemetryFailureError) as exc_info:
+            await client.close()
+
+        assert exc_info.value.operation_type == "FINISH_AGENT_INSTANCE"
+        assert isinstance(exc_info.value.cause, PrefactorAuthError)
+
+
+@pytest.mark.asyncio
+async def test_transient_retry_exhaustion_does_not_latch_permanent_failure():
+    """Transient failures should not poison the client permanently."""
+    retry_error = PrefactorRetryExhaustedError(
+        "network exhausted",
+        last_error=aiohttp.ClientError("network down"),
+    )
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(start_side_effect=retry_error)
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.start()
+        await _wait_until(lambda: stub_http.agent_instances.start_calls == 1)
+
+        await instance.finish()
+        await _wait_until(lambda: stub_http.agent_instances.finish_calls == 1)
+        await client.close()
+
+
+@pytest.mark.asyncio
+async def test_malformed_503_retry_exhaustion_does_not_latch_permanent_failure():
+    """Malformed 5xx responses should still be treated as transient."""
+    retry_error = PrefactorRetryExhaustedError(
+        "server exhausted",
+        last_error=PrefactorResponseContractError(
+            "invalid JSON",
+            status_code=503,
+            body_snippet="<html>temporary outage</html>",
+        ),
+    )
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(start_side_effect=retry_error)
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.start()
+        await _wait_until(lambda: stub_http.agent_instances.start_calls == 1)
+
+        await instance.finish()
+        await _wait_until(lambda: stub_http.agent_instances.finish_calls == 1)
+        await client.close()
+
+
+@pytest.mark.asyncio
+async def test_async_context_preserves_user_exception_when_telemetry_failed():
+    """Context manager exit should not replace the caller's own exception."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            start_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        with pytest.raises(ValueError, match="user boom"):
+            async with PrefactorCoreClient(_make_client_config()) as client:
+                instance = await client.create_agent_instance(
+                    agent_id="agent-1",
+                    agent_version={"name": "v1"},
+                    agent_schema_version={"span_schemas": {}},
+                )
+
+                await instance.start()
+                await _wait_until(lambda: client._telemetry_failure is not None)
+                raise ValueError("user boom")
+
+
+@pytest.mark.asyncio
+async def test_async_context_raises_latched_failure_when_body_succeeds():
+    """Context manager exit should still surface unobserved telemetry failure."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            start_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        with pytest.raises(PrefactorTelemetryFailureError):
+            async with PrefactorCoreClient(_make_client_config()) as client:
+                instance = await client.create_agent_instance(
+                    agent_id="agent-1",
+                    agent_version={"name": "v1"},
+                    agent_schema_version={"span_schemas": {}},
+                )
+
+                await instance.start()
+                await _wait_until(lambda: client._telemetry_failure is not None)
+
+
+@pytest.mark.asyncio
+async def test_latched_failure_drops_already_queued_backlog():
+    """Queued work should be dropped once a permanent telemetry failure is latched."""
+    stub_http = _StubHttpClient(
+        agent_instances=_StubAgentInstances(
+            start_side_effect=PrefactorAuthError("bad token", "unauthorized", 401)
+        )
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        client = PrefactorCoreClient(_make_client_config())
+        await client.initialize()
+        instance = await client.create_agent_instance(
+            agent_id="agent-1",
+            agent_version={"name": "v1"},
+            agent_schema_version={"span_schemas": {}},
+        )
+
+        await instance.start()
+        await instance.finish()
+        await _wait_until(lambda: client._telemetry_failure is not None)
+
+        assert stub_http.agent_instances.start_calls == 1
+        assert stub_http.agent_instances.finish_calls == 0
+
+        with pytest.raises(PrefactorTelemetryFailureError) as exc_info:
+            await client.close()
+
+        assert exc_info.value.dropped_operations == 1

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/tests/test_queue.py

@@ -183,3 +183,34 @@ class TestTaskExecutor:
 
         # Should have attempted 3 times
         assert attempts.count("item1") == 3
+
+    async def test_zero_retries_still_attempts_once(self):
+        """max_retries=0 should still execute the handler once."""
+        queue = InMemoryQueue()
+        attempts = []
+
+        async def failing_handler(item):
+            attempts.append(item)
+            raise Exception("boom")
+
+        executor = TaskExecutor(queue, failing_handler, num_workers=1, max_retries=0)
+        executor.start()
+
+        await queue.put("item1")
+        await asyncio.sleep(0.1)
+        await executor.stop()
+
+        assert attempts == ["item1"]
+
+    async def test_positional_constructor_remains_compatible(self):
+        """Positional num_workers/max_retries args should keep their old meaning."""
+        queue = InMemoryQueue()
+
+        async def handler(_item):
+            return None
+
+        executor = TaskExecutor(queue, handler, 1, 0)
+
+        assert executor._num_workers == 1
+        assert executor._max_retries == 0
+        assert callable(executor._is_retryable)

prefactor_core-0.2.3/tests/test_sdk_header.py

@@ -0,0 +1,78 @@
+"""Tests for core SDK header composition."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+from prefactor_core import PrefactorCoreClient
+from prefactor_core._version import PACKAGE_VERSION
+from prefactor_core.client import CORE_SDK_HEADER_ENTRY
+from prefactor_core.config import PrefactorCoreConfig
+from prefactor_http.config import HttpClientConfig
+
+
+def create_config() -> PrefactorCoreConfig:
+    """Create a minimal core config for SDK header tests."""
+    return PrefactorCoreConfig(
+        http_config=HttpClientConfig(
+            api_url="https://api.test.com",
+            api_token="test-token",
+        )
+    )
+
+
+class TestPrefactorCoreSdkHeader:
+    """Tests for core SDK header behavior."""
+
+    async def test_initialize_sets_core_sdk_header(self):
+        """Core initializes the HTTP client with the core SDK header."""
+        client = PrefactorCoreClient(create_config())
+
+        with (
+            patch(
+                "prefactor_http.client.PrefactorHttpClient.__aenter__",
+                AsyncMock(return_value=None),
+            ),
+            patch(
+                "prefactor_http.client.PrefactorHttpClient.__aexit__",
+                AsyncMock(return_value=None),
+            ),
+        ):
+            await client.initialize()
+            assert client._http is not None
+            assert client._http._sdk_header == CORE_SDK_HEADER_ENTRY
+            await client.close()
+
+    async def test_initialize_prepends_adapter_sdk_header(self):
+        """Core prepends the adapter entry ahead of the core entry."""
+        client = PrefactorCoreClient(
+            create_config(),
+            sdk_header_entry="prefactor-langchain@0.2.4",
+        )
+
+        with (
+            patch(
+                "prefactor_http.client.PrefactorHttpClient.__aenter__",
+                AsyncMock(return_value=None),
+            ),
+            patch(
+                "prefactor_http.client.PrefactorHttpClient.__aexit__",
+                AsyncMock(return_value=None),
+            ),
+        ):
+            await client.initialize()
+            assert client._http is not None
+            assert client._http._sdk_header == (
+                f"prefactor-langchain@0.2.4 {CORE_SDK_HEADER_ENTRY}"
+            )
+            await client.close()
+
+
+class TestCoreVersionHelpers:
+    """Tests for package version exports."""
+
+    def test_package_version_matches_public_export(self):
+        """Test that the package version export matches the internal constant."""
+        import prefactor_core
+
+        assert prefactor_core.__version__ == PACKAGE_VERSION

prefactor_core-0.2.3/tests/test_span_context.py

@@ -0,0 +1,42 @@
+"""Tests for SpanContext finish behavior."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+from prefactor_core.span_context import SpanContext
+
+
+@pytest.mark.asyncio
+async def test_explicit_complete_then_finish_is_a_no_op():
+    """An already-finished span should not enqueue a duplicate finish."""
+    span_manager = AsyncMock()
+    span_manager.start = AsyncMock(return_value="api-span-id")
+    span_manager.finish = AsyncMock()
+
+    context = SpanContext("temp-span-id", span_manager)
+
+    await context.complete({"ok": True})
+    await context.finish()
+
+    assert span_manager.start.await_count == 1
+    assert span_manager.finish.await_count == 1
+
+
+@pytest.mark.asyncio
+async def test_failed_finish_can_retry_same_request():
+    """The same finish request should be retryable until it succeeds."""
+    span_manager = AsyncMock()
+    span_manager.start = AsyncMock(return_value="api-span-id")
+    span_manager.finish = AsyncMock(side_effect=[RuntimeError("boom"), None])
+
+    context = SpanContext("temp-span-id", span_manager)
+
+    with pytest.raises(RuntimeError, match="boom"):
+        await context.complete({"ok": True})
+
+    await context.finish()
+
+    assert span_manager.start.await_count == 1
+    assert span_manager.finish.await_count == 2

{prefactor_core-0.2.2 → prefactor_core-0.2.3}/tests/test_span_manager.py

@@ -83,3 +83,17 @@ class TestSpanManagerIdempotencyKeys:
         assert key is not None
         assert len(key) <= 64
         uuid.UUID(key)
+
+    async def test_child_spans_remap_temp_parent_id_to_api_id(
+        self, manager, http_client
+    ):
+        """Children prepared before parent start should use the backend parent ID."""
+        parent_temp_id = manager.prepare(instance_id="inst-1", schema_name="agent:root")
+        child_temp_id = manager.prepare(instance_id="inst-1", schema_name="agent:child")
+
+        parent_api_id = await manager.start(parent_temp_id)
+        await manager.start(child_temp_id)
+
+        child_call_kwargs = http_client.agent_spans.create.call_args.kwargs
+        assert parent_api_id == "api-span-id"
+        assert child_call_kwargs["parent_span_id"] == parent_api_id