prefactor-core 0.2.4__tar.gz → 0.2.6__tar.gz

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/.gitignore

@@ -70,3 +70,4 @@ htmlcov/
 .env
 mise.local.toml
 prefactor.json
+.worktrees/

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: prefactor-core
-Version: 0.2.4
+Version: 0.2.6
 Summary: Core Prefactor SDK with async queue-based operations
 Author-email: Prefactor Pty Ltd <josh@prefactor.tech>
 License: MIT
 Requires-Python: <4.0.0,>=3.11.0
-Requires-Dist: prefactor-http>=0.1.1
+Requires-Dist: prefactor-http>=0.1.4
 Requires-Dist: pydantic>=2.0.0
 Description-Content-Type: text/markdown
 
@@ -81,6 +81,10 @@ async def main():
 asyncio.run(main())
 ```
 
+`create_agent_instance()` supports two auth modes:
+- Account-scoped token: pass `agent_id` and usually `environment_id`.
+- Deployment-scoped token: omit `agent_id` and `environment_id`; the API derives both from the token.
+
 ## API Reference
 
 ### `PrefactorCoreClient`
@@ -98,9 +102,9 @@ await client.close()
 
 ```python
 handle = await client.create_agent_instance(
-    agent_id="my-agent",
     agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
     agent_schema_version=None,        # Optional: auto-generated if schema_registry is configured
+    agent_id="my-agent",              # Optional for deployment-scoped tokens
     external_schema_version_id=None,  # Optional: reference an existing schema version
 ) -> AgentInstanceHandle
 ```
@@ -240,8 +244,8 @@ config = PrefactorCoreConfig(
 async with PrefactorCoreClient(config) as client:
     # agent_schema_version is generated automatically from the registry
     instance = await client.create_agent_instance(
-        agent_id="my-agent",
         agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
+        agent_id="my-agent",  # Optional for deployment-scoped tokens
     )
 ```
 

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/README.md

@@ -70,6 +70,10 @@ async def main():
 asyncio.run(main())
 ```
 
+`create_agent_instance()` supports two auth modes:
+- Account-scoped token: pass `agent_id` and usually `environment_id`.
+- Deployment-scoped token: omit `agent_id` and `environment_id`; the API derives both from the token.
+
 ## API Reference
 
 ### `PrefactorCoreClient`
@@ -87,9 +91,9 @@ await client.close()
 
 ```python
 handle = await client.create_agent_instance(
-    agent_id="my-agent",
     agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
     agent_schema_version=None,        # Optional: auto-generated if schema_registry is configured
+    agent_id="my-agent",              # Optional for deployment-scoped tokens
     external_schema_version_id=None,  # Optional: reference an existing schema version
 ) -> AgentInstanceHandle
 ```
@@ -229,8 +233,8 @@ config = PrefactorCoreConfig(
 async with PrefactorCoreClient(config) as client:
     # agent_schema_version is generated automatically from the registry
     instance = await client.create_agent_instance(
-        agent_id="my-agent",
         agent_version={"name": "My Agent", "external_identifier": "v1.0.0"},
+        agent_id="my-agent",  # Optional for deployment-scoped tokens
     )
 ```
 

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/examples/agent_e2e.py

@@ -24,10 +24,15 @@ Run via mise (env vars set automatically):
 Or manually:
     PREFACTOR_API_URL=https://api.prefactor.ai \\
     PREFACTOR_API_TOKEN=your-token \\
-    PREFACTOR_AGENT_ID=your-agent-id \\
     python packages/core/examples/agent_e2e.py
+
+Set `PREFACTOR_AGENT_ID` only when using an account-scoped token. With a
+deployment-scoped token, leave it unset and the API derives the agent and
+environment from the token.
 """
 
+from __future__ import annotations
+
 import asyncio
 import os
 
@@ -182,7 +187,9 @@ async def simulate_retrieval(query: str) -> list[str]:
 
 
 async def main() -> None:
-    agent_id = os.environ["PREFACTOR_AGENT_ID"]
+    agent_id = os.environ.get("PREFACTOR_AGENT_ID")
+    if agent_id is not None:
+        agent_id = agent_id.strip() or None
 
     config = PrefactorCoreConfig(
         http_config=HttpClientConfig(
@@ -194,10 +201,21 @@ async def main() -> None:
 
     async with PrefactorCoreClient(config) as client:
         # Register the agent instance — schema version derived from registry.
-        instance = await client.create_agent_instance(
-            agent_id=agent_id,
-            agent_version={"name": "Example Agent", "external_identifier": "v8.0.0"},
-        )
+        if agent_id is None:
+            instance = await client.create_agent_instance(
+                agent_version={
+                    "name": "Example Agent",
+                    "external_identifier": "v8.0.0",
+                }
+            )
+        else:
+            instance = await client.create_agent_instance(
+                agent_id=agent_id,
+                agent_version={
+                    "name": "Example Agent",
+                    "external_identifier": "v8.0.0",
+                },
+            )
 
         await instance.start()
 

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 ]
 requires-python = ">=3.11.0, <4.0.0"
 dependencies = [
-    "prefactor-http>=0.1.1",
+    "prefactor-http>=0.1.4",
     "pydantic>=2.0.0",
 ]
 

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/src/prefactor_core/__init__.py

@@ -16,6 +16,7 @@ from .exceptions import (
     OperationError,
     PrefactorCoreError,
     PrefactorTelemetryFailureError,
+    PrefactorTerminatedError,
     SpanNotFoundError,
 )
 from .managers.agent_instance import AgentInstanceHandle
@@ -43,6 +44,7 @@ __all__ = [
     "InstanceNotFoundError",
     "SpanNotFoundError",
     "PrefactorTelemetryFailureError",
+    "PrefactorTerminatedError",
     # Models
     "AgentInstance",
     "Span",

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/src/prefactor_core/_version.py

@@ -3,5 +3,5 @@
 from __future__ import annotations
 
 PACKAGE_NAME = "prefactor-core"
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 PACKAGE_VERSION = __version__

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/src/prefactor_core/client.py

@@ -7,13 +7,18 @@ through an async queue-based architecture.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import time
 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 prefactor_http.exceptions import (
+    PrefactorApiError,
+    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
@@ -26,6 +31,7 @@ from .exceptions import (
 )
 from .managers.agent_instance import AgentInstanceManager
 from .managers.span import SpanManager
+from .monitoring.termination_monitor import TerminationMonitor
 from .operations import Operation, OperationType
 from .queue.base import Queue
 from .queue.executor import TaskExecutor
@@ -86,6 +92,9 @@ class PrefactorCoreClient:
         self._initialized = False
         self._telemetry_failure: PrefactorTelemetryFailureError | None = None
         self._telemetry_failure_observed = False
+        self._termination_monitor: TerminationMonitor | None = None
+        self._sync_task: asyncio.Task | None = None
+        self._current_instance_id: str | None = None
 
     def _build_http_sdk_header(self) -> str:
         """Build the effective SDK header for HTTP requests."""
@@ -155,6 +164,13 @@ class PrefactorCoreClient:
 
         self._initialized = True
 
+        self._termination_monitor = TerminationMonitor(
+            fetch_instance=self._fetch_instance_for_poll,
+        )
+        self._sync_task = asyncio.create_task(
+            self._run_sync_loop(), name="prefactor-termination-sync"
+        )
+
     async def close(self) -> None:
         """Close the client and cleanup resources.
 
@@ -164,6 +180,24 @@ class PrefactorCoreClient:
         if not self._initialized:
             return
 
+        if self._sync_task is not None:
+            if not self._sync_task.done():
+                self._sync_task.cancel()
+            try:
+                await self._sync_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                logger.exception(
+                    "Termination sync loop exited with error during close()"
+                )
+            finally:
+                self._sync_task = None
+
+        if self._termination_monitor is not None:
+            self._termination_monitor.destroy()
+            self._termination_monitor = None
+
         # Stop executor
         if self._executor:
             await self._executor.stop()
@@ -272,12 +306,23 @@ class PrefactorCoreClient:
                 )
 
             elif operation.type == OperationType.FINISH_AGENT_INSTANCE:
-                await self._http.agent_instances.finish(
-                    agent_instance_id=operation.payload["instance_id"],
-                    status=operation.payload.get("status", "complete"),
-                    timestamp=operation.timestamp,
-                    idempotency_key=operation.payload.get("idempotency_key"),
-                )
+                try:
+                    await self._http.agent_instances.finish(
+                        agent_instance_id=operation.payload["instance_id"],
+                        status=operation.payload.get("status", "complete"),
+                        timestamp=operation.timestamp,
+                        idempotency_key=operation.payload.get("idempotency_key"),
+                    )
+                except PrefactorApiError as finish_err:
+                    if finish_err.status_code == 409:
+                        logger.debug(
+                            "[prefactor:http] Agent instance %s already in"
+                            " terminal state; skipping finish.",
+                            operation.payload["instance_id"],
+                        )
+                        return
+                    raise
+
             elif operation.type == OperationType.CREATE_SPAN:
                 await self._http.agent_spans.create(
                     agent_instance_id=operation.payload["instance_id"],
@@ -286,6 +331,7 @@ class PrefactorCoreClient:
                     id=operation.payload.get("span_id"),
                     parent_span_id=operation.payload.get("parent_span_id"),
                     payload=operation.payload.get("payload"),
+                    control_signal_callback=self._on_control_signal,
                 )
 
             elif operation.type == OperationType.FINISH_SPAN:
@@ -295,6 +341,7 @@ class PrefactorCoreClient:
                     result_payload=operation.payload.get("result_payload"),
                     timestamp=operation.timestamp,
                     idempotency_key=operation.payload.get("idempotency_key"),
+                    control_signal_callback=self._on_control_signal,
                 )
 
         except Exception as e:
@@ -307,6 +354,32 @@ class PrefactorCoreClient:
             )
             raise
 
+    async def _fetch_instance_for_poll(self, instance_id: str):
+        if self._http is None:
+            return None
+        return await self._http.agent_instances.get(instance_id)
+
+    async def _run_sync_loop(self) -> None:
+        while True:
+            await asyncio.sleep(1)
+            if self._termination_monitor is None:
+                continue
+            try:
+                self._termination_monitor.sync(self._current_instance_id)
+            except Exception:
+                logger.exception("Termination sync iteration failed")
+
+    def _on_control_signal(self, reason: str | None) -> None:
+        if self._termination_monitor is not None:
+            self._termination_monitor.detect_termination(reason)
+
+    def _set_current_instance(self, instance_id: str | None) -> None:
+        self._current_instance_id = instance_id
+
+    def _clear_current_instance(self, instance_id: str) -> None:
+        if self._current_instance_id == instance_id:
+            self._current_instance_id = None
+
     @property
     def instance_manager(self) -> AgentInstanceManager | None:
         """Public accessor for the agent instance manager."""
@@ -314,11 +387,12 @@ class PrefactorCoreClient:
 
     async def create_agent_instance(
         self,
-        agent_id: str,
         agent_version: dict[str, Any],
         agent_schema_version: dict[str, Any] | None = None,
+        agent_id: str | None = None,
         instance_id: str | None = None,
         external_schema_version_id: str | None = None,
+        environment_id: str | None = None,
     ) -> "AgentInstanceHandle":
         """Create a new agent instance.
 
@@ -329,13 +403,14 @@ class PrefactorCoreClient:
         the registry's schemas will be used automatically.
 
         Args:
-            agent_id: ID of the agent to create an instance for.
+            agent_id: Agent ID. Omit when using a deployment-scoped token.
             agent_version: Version information (name, etc.).
             agent_schema_version: Schema version. Uses registry if not provided
                 and registry is configured.
             instance_id: Optional custom ID for the instance.
             external_schema_version_id: Optional external identifier for the
                 schema version. Defaults to "auto-generated" when using registry.
+            environment_id: Optional environment ID used to scope the agent instance.
 
         Returns:
             AgentInstanceHandle for the created instance.
@@ -356,7 +431,10 @@ class PrefactorCoreClient:
             # Use registry to generate schema version
             ext_id = external_schema_version_id
             if ext_id is None:
-                ext_id = f"auto-{agent_id}-{time.time()}"
+                if agent_id is None:
+                    ext_id = f"auto-deployment-{time.time()}"
+                else:
+                    ext_id = f"auto-{agent_id}-{time.time()}"
             final_schema_version = self._config.schema_registry.to_agent_schema_version(
                 ext_id
             )
@@ -373,8 +451,11 @@ class PrefactorCoreClient:
             agent_version=agent_version,
             agent_schema_version=final_schema_version,
             instance_id=instance_id,
+            environment_id=environment_id,
         )
 
+        self._set_current_instance(instance_id)
+
         return AgentInstanceHandle(
             instance_id=instance_id,
             client=self,

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/src/prefactor_core/exceptions.py

@@ -58,6 +58,23 @@ class PrefactorTelemetryFailureError(PrefactorCoreError):
         self.dropped_operations = dropped_operations
 
 
+class PrefactorTerminatedError(PrefactorCoreError):
+    """Raised when the agent instance has been terminated by p2.
+
+    Args:
+        reason: Optional reason reported by p2 for the termination.
+    """
+
+    def __init__(self, reason: str | None = None) -> None:
+        msg = (
+            f"Agent instance terminated by p2: {reason}"
+            if reason
+            else "Agent instance terminated by p2"
+        )
+        super().__init__(msg)
+        self.reason = reason
+
+
 __all__ = [
     "PrefactorCoreError",
     "ClientNotInitializedError",
@@ -66,4 +83,5 @@ __all__ = [
     "InstanceNotFoundError",
     "SpanNotFoundError",
     "PrefactorTelemetryFailureError",
+    "PrefactorTerminatedError",
 ]

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/src/prefactor_core/managers/agent_instance.py

@@ -59,10 +59,11 @@ class AgentInstanceManager:
 
     async def register(
         self,
-        agent_id: str,
         agent_version: dict[str, Any],
         agent_schema_version: dict[str, Any],
+        agent_id: str | None = None,
         instance_id: str | None = None,
+        environment_id: str | None = None,
     ) -> str:
         """Register a new agent instance.
 
@@ -70,12 +71,14 @@ class AgentInstanceManager:
         the API-generated ID.
 
         Args:
-            agent_id: ID of the agent to create an instance for.
+            agent_id: Agent ID. Omit when using a deployment-scoped token.
             agent_version: Version information (name, external_identifier, etc.).
             agent_schema_version: Schema version information.
             instance_id: Optional ID to forward to the API as ``id``.  When
                 provided, the API uses it as the instance ID; when omitted,
                 the API generates one.
+            environment_id: Optional environment ID. Required when using an
+                account-scoped token; omit when using a deployment-scoped token.
 
         Returns:
             The instance ID (API-generated).
@@ -84,6 +87,7 @@ class AgentInstanceManager:
             agent_id=agent_id,
             agent_version=agent_version,
             agent_schema_version=agent_schema_version,
+            environment_id=environment_id,
             id=instance_id,
             idempotency_key=generate_idempotency_key(),
         )
@@ -214,12 +218,18 @@ class AgentInstanceHandle:
     async def finish(self, status: "FinishStatus" = "complete") -> None:
         """Mark the instance as finished.
 
-        This queues a finish operation for the instance.
+        Resets the termination monitor (fence + new event) before enqueueing
+        the HTTP finish so stale span responses from the dying run cannot
+        trigger termination on the next run.
 
         Args:
             status: Terminal status for the instance — one of ``"complete"``,
                 ``"failed"``, or ``"cancelled"``. Defaults to ``"complete"``.
         """
+        monitor = getattr(self._client, "_termination_monitor", None)
+        if monitor is not None:
+            monitor.reset()
+        self._client._clear_current_instance(self._instance_id)
         manager = self._client.instance_manager
         assert manager is not None
         await manager.finish_with_idempotency_key(

prefactor_core-0.2.6/src/prefactor_core/monitoring/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from prefactor_core.monitoring.termination_monitor import TerminationMonitor
+
+__all__ = ["TerminationMonitor"]

prefactor_core-0.2.6/src/prefactor_core/monitoring/termination_monitor.py

@@ -0,0 +1,151 @@
+"""TerminationMonitor — detects agent instance termination via two paths:
+1. Fast: control signal in span API responses (pushed via callback)
+2. Slow: polling the instance status endpoint every `poll_interval` seconds
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class TerminationMonitor:
+    """Monitors an agent instance for termination.
+
+    Thread-safety note: `detect_termination` and `get_termination_event().is_set()`
+    are safe to call from sync worker threads — they only read/write a bool under
+    the GIL (asyncio.Event._value is a plain bool).
+    """
+
+    def __init__(
+        self,
+        fetch_instance: Callable,
+        poll_interval: float = 30.0,
+    ) -> None:
+        self._fetch_instance = fetch_instance
+        self._poll_interval = poll_interval
+
+        self._event = asyncio.Event()
+        self._termination_reason: str | None = None
+        self._callbacks: list[Callable[[], None]] = []
+
+        self._current_instance_id: str | None = None
+        self._poll_task: asyncio.Task | None = None
+        self._destroyed = False
+
+        # Fence blocks stale span callbacks from a previous run after reset()
+        self._fenced = False
+        # Generation increments on each reset so stale polls self-discard
+        self._generation = 0
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def termination_reason(self) -> str | None:
+        return self._termination_reason
+
+    def get_termination_event(self) -> asyncio.Event:
+        return self._event
+
+    def detect_termination(self, reason: str | None) -> None:
+        """Signal that the instance has been terminated.
+
+        No-op if already terminated, destroyed, or fenced (post-reset stale call).
+        """
+        if self._destroyed or self._event.is_set() or self._fenced:
+            return
+        self._termination_reason = reason
+        self._event.set()
+        self._stop_poll()
+        for cb in list(self._callbacks):
+            try:
+                cb()
+            except Exception:
+                logger.exception("Termination callback failed: %r", cb)
+
+    def sync(self, instance_id: str | None) -> None:
+        """Update the tracked instance ID and start/stop the fallback poll.
+
+        Idempotent: calling with the same non-None ID when a poll is already
+        running does not restart it (preserving the sleep interval).
+        """
+        if instance_id is not None:
+            self._fenced = False
+        if instance_id == self._current_instance_id:
+            # Same ID — no change needed; poll (if any) keeps running
+            return
+        self._current_instance_id = instance_id
+        self._stop_poll()
+        if instance_id is not None and not self._event.is_set() and not self._destroyed:
+            self._start_poll(instance_id, self._generation)
+
+    def reset(self) -> None:
+        """Prepare monitor for the next agent run.
+
+        - Creates a fresh (unset) event
+        - Clears the termination reason
+        - Cancels any in-flight poll
+        - Sets fence so stale callbacks from the dying run are ignored
+        - Increments generation so stale polls self-discard
+        """
+        self._stop_poll()
+        self._event = asyncio.Event()
+        self._termination_reason = None
+        self._current_instance_id = None
+        self._generation += 1
+        self._fenced = True
+
+    def subscribe(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Register a callback invoked on termination. Returns an unsubscribe fn."""
+        self._callbacks.append(callback)
+
+        def unsubscribe() -> None:
+            try:
+                self._callbacks.remove(callback)
+            except ValueError:
+                pass
+
+        return unsubscribe
+
+    def destroy(self) -> None:
+        """Permanently shut down the monitor (no further events will fire)."""
+        self._destroyed = True
+        self._stop_poll()
+        self._callbacks.clear()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _start_poll(self, instance_id: str, generation: int) -> None:
+        self._poll_task = asyncio.get_event_loop().create_task(
+            self._poll(instance_id, generation)
+        )
+
+    def _stop_poll(self) -> None:
+        if self._poll_task is not None and not self._poll_task.done():
+            self._poll_task.cancel()
+        self._poll_task = None
+
+    async def _poll(self, instance_id: str, generation: int) -> None:
+        while True:
+            await asyncio.sleep(self._poll_interval)
+            # Guard: generation changed means reset() was called
+            if self._generation != generation:
+                return
+            try:
+                instance = await self._fetch_instance(instance_id)
+            except Exception:
+                logger.debug("Termination poll error (transient)", exc_info=True)
+                continue
+            # Guard again after await
+            if self._generation != generation:
+                return
+            if instance.status == "terminated":
+                self.detect_termination(instance.termination_reason)
+                return

prefactor_core-0.2.6/tests/monitoring/test_termination_monitor.py

@@ -0,0 +1,259 @@
+"""Tests for TerminationMonitor — 19 tests covering primary path, fallback poll,
+reset(), and callback lifecycle."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock
+
+from prefactor_core.monitoring.termination_monitor import TerminationMonitor
+
+
+def _make_monitor(fetch_instance=None) -> TerminationMonitor:
+    if fetch_instance is None:
+        fetch_instance = AsyncMock(
+            return_value=MagicMock(status="active", termination_reason=None)
+        )
+    return TerminationMonitor(fetch_instance=fetch_instance)
+
+
+def _terminated_instance(reason: str | None = "test reason"):
+    inst = MagicMock()
+    inst.status = "terminated"
+    inst.termination_reason = reason
+    return inst
+
+
+# ---------------------------------------------------------------------------
+# Primary path (5 tests)
+# ---------------------------------------------------------------------------
+
+
+class TestPrimaryPath:
+    async def test_detect_termination_sets_event(self):
+        monitor = _make_monitor()
+        assert not monitor.get_termination_event().is_set()
+        monitor.detect_termination("reason")
+        assert monitor.get_termination_event().is_set()
+
+    async def test_reason_propagates(self):
+        monitor = _make_monitor()
+        monitor.detect_termination("my reason")
+        assert monitor.termination_reason == "my reason"
+
+    async def test_null_reason_accepted(self):
+        monitor = _make_monitor()
+        monitor.detect_termination(None)
+        assert monitor.get_termination_event().is_set()
+        assert monitor.termination_reason is None
+
+    async def test_second_detect_termination_is_idempotent(self):
+        callback = MagicMock()
+        monitor = _make_monitor()
+        monitor.subscribe(callback)
+        monitor.detect_termination("first")
+        monitor.detect_termination("second")
+        callback.assert_called_once()
+        assert monitor.termination_reason == "first"
+
+    async def test_detect_termination_noop_after_destroy(self):
+        monitor = _make_monitor()
+        monitor.destroy()
+        monitor.detect_termination("reason")
+        assert not monitor.get_termination_event().is_set()
+
+
+# ---------------------------------------------------------------------------
+# Fallback poll (5 tests)
+# ---------------------------------------------------------------------------
+
+
+class TestFallbackPoll:
+    async def test_poll_starts_when_instance_id_arrives(self):
+        monitor = _make_monitor()
+        monitor.sync("inst-1")
+        await asyncio.sleep(0)  # yield to let task start
+        assert monitor._poll_task is not None
+        assert not monitor._poll_task.done()
+        monitor.destroy()
+
+    async def test_poll_stops_when_sync_called_with_none(self):
+        monitor = _make_monitor()
+        monitor.sync("inst-1")
+        await asyncio.sleep(0)
+        poll_task = monitor._poll_task
+        assert poll_task is not None
+        monitor.sync(None)
+        await asyncio.sleep(0)
+        assert poll_task.cancelled() or poll_task.done()
+        monitor.destroy()
+
+    async def test_no_poll_without_instance_id(self):
+        monitor = _make_monitor()
+        monitor.sync(None)
+        await asyncio.sleep(0)
+        assert monitor._poll_task is None
+        monitor.destroy()
+
+    async def test_poll_stops_after_termination_detected(self):
+        monitor = _make_monitor()
+        monitor.sync("inst-1")
+        await asyncio.sleep(0)
+        poll_task = monitor._poll_task
+        assert poll_task is not None
+        monitor.detect_termination("reason")
+        await asyncio.sleep(0)
+        assert poll_task.cancelled() or poll_task.done()
+        monitor.destroy()
+
+    async def test_poll_survives_transient_http_errors(self):
+        fetch = AsyncMock(side_effect=Exception("network error"))
+        monitor = TerminationMonitor(fetch_instance=fetch, poll_interval=0.05)
+        monitor.sync("inst-1")
+        await asyncio.sleep(0.2)  # let poll fire a couple times
+        # monitor should not be terminated — error was swallowed
+        assert not monitor.get_termination_event().is_set()
+        monitor.destroy()
+
+
+# ---------------------------------------------------------------------------
+# reset() (7 tests)
+# ---------------------------------------------------------------------------
+
+
+class TestReset:
+    async def test_reset_creates_fresh_event(self):
+        monitor = _make_monitor()
+        monitor.detect_termination("reason")
+        old_event = monitor.get_termination_event()
+        assert old_event.is_set()
+        monitor.reset()
+        new_event = monitor.get_termination_event()
+        assert not new_event.is_set()
+        assert new_event is not old_event
+
+    async def test_reset_allows_new_termination_after_sync_with_new_id(self):
+        monitor = _make_monitor()
+        monitor.detect_termination("run 1")
+        monitor.reset()
+        # fenced — detect_termination should be blocked
+        monitor.detect_termination("stale")
+        assert not monitor.get_termination_event().is_set()
+        # sync with new id lifts fence
+        monitor.sync("inst-2")
+        monitor.detect_termination("run 2")
+        assert monitor.get_termination_event().is_set()
+        assert monitor.termination_reason == "run 2"
+        monitor.destroy()
+
+    async def test_get_termination_event_returns_new_event_after_reset(self):
+        monitor = _make_monitor()
+        getter = monitor.get_termination_event
+        monitor.detect_termination("reason")
+        monitor.reset()
+        # getter returns new (unset) event
+        assert not getter().is_set()
+
+    async def test_reset_cancels_poll_task(self):
+        monitor = _make_monitor()
+        monitor.sync("inst-1")
+        await asyncio.sleep(0)
+        poll_task = monitor._poll_task
+        assert poll_task is not None
+        monitor.reset()
+        await asyncio.sleep(0)
+        assert poll_task.cancelled() or poll_task.done()
+
+    async def test_reset_preserves_callbacks(self):
+        callback = MagicMock()
+        monitor = _make_monitor()
+        monitor.subscribe(callback)
+        monitor.reset()
+        # sync to lift fence, then detect
+        monitor.sync("inst-2")
+        monitor.detect_termination("after reset")
+        callback.assert_called_once()
+
+    async def test_fence_blocks_detect_termination_until_sync_with_new_id(self):
+        monitor = _make_monitor()
+        monitor.detect_termination("run 1")
+        monitor.reset()  # fenced = True
+
+        # stale span response fires during queue drain
+        monitor.detect_termination("stale span response")
+        assert not monitor.get_termination_event().is_set()
+
+        # sync with None doesn't lift fence
+        monitor.sync(None)
+        monitor.detect_termination("still stale")
+        assert not monitor.get_termination_event().is_set()
+
+        # sync with new instance id lifts fence
+        monitor.sync("instance-2")
+        monitor.detect_termination("run 2")
+        assert monitor.get_termination_event().is_set()
+        assert monitor.termination_reason == "run 2"
+        monitor.destroy()
+
+    async def test_stale_poll_response_discarded_after_reset(self):
+        """Poll fires for old instance after reset — generation check discards it."""
+        slow_fetch = AsyncMock(return_value=_terminated_instance("old run"))
+        monitor = TerminationMonitor(fetch_instance=slow_fetch, poll_interval=0.05)
+        monitor.sync("inst-1")
+        await asyncio.sleep(0)  # poll task started
+
+        # reset before poll completes
+        monitor.reset()
+        await asyncio.sleep(0.2)  # let poll fire with old generation
+
+        # monitor should NOT be terminated
+        assert not monitor.get_termination_event().is_set()
+        monitor.destroy()
+
+
+# ---------------------------------------------------------------------------
+# Callback lifecycle (2 tests)
+# ---------------------------------------------------------------------------
+
+
+class TestCallbackLifecycle:
+    async def test_unsubscribe_removes_callback(self):
+        callback = MagicMock()
+        monitor = _make_monitor()
+        unsubscribe = monitor.subscribe(callback)
+        unsubscribe()
+        monitor.detect_termination("reason")
+        callback.assert_not_called()
+
+    async def test_callbacks_fire_in_registration_order(self):
+        order = []
+        monitor = _make_monitor()
+        monitor.subscribe(lambda: order.append(1))
+        monitor.subscribe(lambda: order.append(2))
+        monitor.subscribe(lambda: order.append(3))
+        monitor.detect_termination("reason")
+        assert order == [1, 2, 3]
+
+    async def test_bad_callback_does_not_block_later_callbacks(self):
+        order = []
+        monitor = _make_monitor()
+
+        def failing_callback():
+            order.append("bad")
+            raise RuntimeError("callback failed")
+
+        monitor.subscribe(failing_callback)
+        monitor.subscribe(lambda: order.append("good"))
+
+        monitor.detect_termination("reason")
+
+        assert order == ["bad", "good"]
+        assert monitor.get_termination_event().is_set()
+
+    async def test_destroy_clears_callbacks(self):
+        monitor = _make_monitor()
+        monitor.subscribe(MagicMock())
+
+        monitor.destroy()
+
+        assert monitor._callbacks == []

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/tests/test_agent_instance_finish_status.py

@@ -102,3 +102,70 @@ async def test_finish_forwards_explicit_status(status):
 
     assert len(stub_http.agent_instances.finish_calls) == 1
     assert stub_http.agent_instances.finish_calls[0]["status"] == status
+
+
+class TestFinishAgentInstance409Handling:
+    async def test_409_on_finish_treated_as_success(self):
+        """FINISH_AGENT_INSTANCE with 409 response should not raise."""
+        from datetime import datetime, timezone
+        from unittest.mock import AsyncMock, MagicMock
+
+        from prefactor_core.operations import Operation, OperationType
+        from prefactor_http.exceptions import PrefactorApiError
+
+        mock_http = MagicMock()
+        mock_http.agent_instances = MagicMock()
+        mock_http.agent_instances.finish = AsyncMock(
+            side_effect=PrefactorApiError("already terminated", "conflict", 409)
+        )
+        mock_http.agent_spans = MagicMock()
+        mock_http.agent_spans.create = AsyncMock()
+        mock_http.agent_spans.finish = AsyncMock()
+
+        config = PrefactorCoreConfig(
+            http_config=HttpClientConfig(api_url="http://fake", api_token="tok")
+        )
+        client = PrefactorCoreClient(config)
+        client._http = mock_http
+        client._initialized = True
+
+        op = Operation(
+            type=OperationType.FINISH_AGENT_INSTANCE,
+            payload={
+                "instance_id": "inst-1",
+                "idempotency_key": "key-1",
+                "status": "complete",
+            },
+            timestamp=datetime.now(timezone.utc),
+        )
+        # Should not raise
+        await client._process_operation(op)
+
+
+class TestAgentInstanceHandleFinishResetsMonitor:
+    async def test_finish_resets_termination_monitor(self):
+        """handle.finish() should reset the termination monitor before enqueueing."""
+        from unittest.mock import AsyncMock, MagicMock
+
+        from prefactor_core.managers.agent_instance import AgentInstanceHandle
+        from prefactor_core.monitoring.termination_monitor import TerminationMonitor
+
+        fetch = AsyncMock(
+            return_value=MagicMock(status="active", termination_reason=None)
+        )
+        monitor = TerminationMonitor(fetch_instance=fetch)
+        monitor.detect_termination("run 1")
+        assert monitor.get_termination_event().is_set()
+
+        mock_client = MagicMock()
+        mock_client._termination_monitor = monitor
+        mock_client.instance_manager = MagicMock()
+        mock_client.instance_manager.finish_with_idempotency_key = AsyncMock()
+
+        handle = AgentInstanceHandle(instance_id="inst-1", client=mock_client)
+        await handle.finish()
+
+        # Monitor should be reset (new unset event)
+        assert not monitor.get_termination_event().is_set()
+        # finish_with_idempotency_key should still be called
+        mock_client.instance_manager.finish_with_idempotency_key.assert_called_once()

prefactor_core-0.2.6/tests/test_agent_instance_register.py

@@ -0,0 +1,123 @@
+"""Tests for environment_id threading through the core register flow."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from prefactor_core import PrefactorCoreClient
+from prefactor_core.config import PrefactorCoreConfig, QueueConfig
+from prefactor_http.config import HttpClientConfig
+
+
+def _make_config() -> PrefactorCoreConfig:
+    return PrefactorCoreConfig(
+        http_config=HttpClientConfig(
+            api_url="https://api.test.com",
+            api_token="test-token",
+            max_retries=0,
+        ),
+        queue_config=QueueConfig(num_workers=1, max_retries=0),
+    )
+
+
+class _StubAgentInstances:
+    def __init__(self) -> None:
+        self.register_calls: list[dict] = []
+
+    async def register(self, **kwargs):
+        self.register_calls.append(kwargs)
+        return SimpleNamespace(id="inst-1")
+
+    async def start(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+    async def finish(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_instance_id"])
+
+
+class _StubAgentSpans:
+    async def create(self, **kwargs):
+        return SimpleNamespace(id="span-1")
+
+    async def finish(self, **kwargs):
+        return SimpleNamespace(id=kwargs["agent_span_id"])
+
+
+class _StubHttpClient:
+    def __init__(self, *args, **kwargs) -> None:
+        self.agent_instances = _StubAgentInstances()
+        self.agent_spans = _StubAgentSpans()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_passes_environment_id_to_register():
+    """environment_id passed to create_agent_instance() reaches the HTTP layer."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+                environment_id="env-1",
+            )
+    assert stub_http.agent_instances.register_calls[0]["environment_id"] == "env-1"
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_environment_id_omits_field():
+    """Omitting environment_id does not send it to the HTTP register call."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_id="agent-1",
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+    call = stub_http.agent_instances.register_calls[0]
+    assert "environment_id" not in call or call["environment_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_agent_id_omits_field():
+    """Omitting agent_id does not send it to the HTTP register call."""
+    stub_http = _StubHttpClient()
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(_make_config()) as client:
+            await client.create_agent_instance(
+                agent_version={"name": "v1"},
+                agent_schema_version={"span_schemas": {}},
+            )
+    call = stub_http.agent_instances.register_calls[0]
+    assert "agent_id" not in call or call["agent_id"] is None
+
+
+@pytest.mark.asyncio
+async def test_create_agent_instance_without_agent_id_uses_deployment_schema_fallback():
+    """Registry fallback should not require agent_id to generate an external ID."""
+    stub_http = _StubHttpClient()
+    config = _make_config()
+    config.schema_registry = SimpleNamespace(
+        to_agent_schema_version=lambda external_id: {"external_identifier": external_id}
+    )
+
+    with patch("prefactor_core.client.PrefactorHttpClient", return_value=stub_http):
+        async with PrefactorCoreClient(config) as client:
+            await client.create_agent_instance(
+                agent_version={"name": "v1"},
+                agent_schema_version=None,
+            )
+
+    call = stub_http.agent_instances.register_calls[0]
+    assert call["agent_schema_version"]["external_identifier"].startswith(
+        "auto-deployment-"
+    )

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/tests/test_failure_handling.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 from types import SimpleNamespace
-from unittest.mock import patch
+from unittest.mock import Mock, patch
 
 import aiohttp
 import pytest
@@ -103,6 +104,60 @@ async def _wait_until(
     raise AssertionError("Timed out waiting for expected condition")
 
 
+@pytest.mark.asyncio
+async def test_termination_sync_loop_survives_iteration_failures(caplog):
+    """A failed sync iteration should be logged without stopping future syncs."""
+    client = PrefactorCoreClient(_make_client_config())
+    monitor = Mock()
+    calls = 0
+
+    def sync(_instance_id):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            raise RuntimeError("sync failed")
+
+    monitor.sync.side_effect = sync
+    client._termination_monitor = monitor
+    original_sleep = asyncio.sleep
+
+    async def fast_sleep(_delay):
+        await original_sleep(0)
+
+    with (
+        caplog.at_level(logging.ERROR, logger="prefactor_core.client"),
+        patch("prefactor_core.client.asyncio.sleep", side_effect=fast_sleep),
+    ):
+        task = asyncio.create_task(client._run_sync_loop())
+        try:
+            await _wait_until(lambda: monitor.sync.call_count >= 2)
+        finally:
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+
+    assert "Termination sync iteration failed" in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_close_observes_completed_sync_task_exceptions(caplog):
+    """close() should await already-failed sync tasks and clear the task handle."""
+    client = PrefactorCoreClient(_make_client_config())
+    client._initialized = True
+
+    async def fail_sync_loop():
+        raise RuntimeError("sync task failed")
+
+    client._sync_task = asyncio.create_task(fail_sync_loop())
+    await asyncio.sleep(0)
+
+    with caplog.at_level(logging.ERROR, logger="prefactor_core.client"):
+        await client.close()
+
+    assert client._sync_task is None
+    assert "Termination sync loop exited with error during close()" in caplog.text
+
+
 @pytest.mark.asyncio
 async def test_permanent_worker_failure_latches_and_rejects_future_operations():
     """Permanent failures should latch and reject later queued operations."""

{prefactor_core-0.2.4 → prefactor_core-0.2.6}/tests/test_sdk_header.py

@@ -47,7 +47,7 @@ class TestPrefactorCoreSdkHeader:
         """Core prepends the adapter entry ahead of the core entry."""
         client = PrefactorCoreClient(
             create_config(),
-            sdk_header_entry="prefactor-langchain@0.2.4",
+            sdk_header_entry="prefactor-langchain@0.2.5",
         )
 
         with (
@@ -63,7 +63,7 @@ class TestPrefactorCoreSdkHeader:
             await client.initialize()
             assert client._http is not None
             assert client._http._sdk_header == (
-                f"prefactor-langchain@0.2.4 {CORE_SDK_HEADER_ENTRY}"
+                f"prefactor-langchain@0.2.5 {CORE_SDK_HEADER_ENTRY}"
             )
             await client.close()