cortex-agent-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-agent-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Sesiones y capacidades puntuales para agentes multiprovider con Pydantic AI
 Project-URL: Repository, https://github.com/epok200/cortex_agent_sdk
 Project-URL: Issues, https://github.com/epok200/cortex_agent_sdk/issues
@@ -16,8 +16,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: pydantic-ai-slim[google,openai]<3,>=2.27
+Requires-Dist: pydantic-ai-slim<3,>=2.27
+Provides-Extra: google
+Requires-Dist: pydantic-ai-slim[google]<3,>=2.27; extra == 'google'
 Provides-Extra: openai
+Requires-Dist: pydantic-ai-slim[openai]<3,>=2.27; extra == 'openai'
 Provides-Extra: redis
 Requires-Dist: redis>=8.1.0; extra == 'redis'
 Description-Content-Type: text/markdown
@@ -37,30 +40,36 @@ opcionales construidas sobre sus hooks públicos.
 ## Requisitos
 
 - Python `>=3.13`.
-- Pydantic AI `>=2.27,<3`, con Google y OpenAI instalados por Cortex.
+- Pydantic AI `>=2.27,<3`.
 
 ## Instalación
 
-Google, OpenAI y sesiones en memoria:
+Solo sesiones en memoria y capabilities:
 
 ```bash
 uv add cortex-agent-sdk
 ```
 
-Google, OpenAI y Redis:
+OpenAI y sesiones en memoria:
 
 ```bash
-uv add "cortex-agent-sdk[redis]"
+uv add "cortex-agent-sdk[openai]"
 ```
 
-La instalación base incluye Google y OpenAI, además de los endpoints compatibles con OpenAI. Otros
-providers pueden agregarse desde los extras oficiales de Pydantic AI cuando un producto realmente
-los necesite. Cortex no implementa adapters paralelos.
+OpenAI y Redis:
+
+```bash
+uv add "cortex-agent-sdk[openai,redis]"
+```
+
+Google se instala con el extra `google`. Cada producto elige únicamente sus providers. Cortex no
+implementa adapters paralelos ni ofrece un extra que los instale todos.
 
 ## Uso
 
 El agente es el `Agent` nativo de Pydantic AI. El store entrega el historial bajo exclusión y lo
 guarda cuando `session.replace(...)` marca un resultado completo.
+El siguiente ejemplo requiere el extra `openai`.
 
 ```python
 import asyncio
@@ -93,6 +102,7 @@ asyncio.run(main())
 
 - Si no se llama, el store no modifica el historial.
 - Si el bloque termina con una excepción, el store no guarda el reemplazo.
+- Los checkpoints confirmados dentro del turno permanecen aunque una operación posterior falle.
 - Si guardar falla, la excepción se propaga.
 
 ## Redis
@@ -115,6 +125,47 @@ historial se serializa con `ModelMessagesTypeAdapter`, el formato público de Py
 Al cambiar desde el runtime anterior, usa un prefix nuevo. Los formatos no son compatibles y Cortex
 no intenta convertir el historial legacy.
 
+## Checkpoints de tools
+
+`session_checkpoints` guarda el `ToolReturn` canónico al terminar cada `CallToolsNode`, antes de la
+siguiente petición al modelo. Las tools con efectos se declaran por nombre para marcar el turno antes
+de ejecutarlas:
+
+```python
+from cortex_agent_sdk.capabilities import session_checkpoints
+
+async with sessions.turn("usuario:42") as session:
+    result = await agent.run(
+        "Agenda la cita.",
+        message_history=session.messages,
+        conversation_id=session.session_id,
+        capabilities=[
+            session_checkpoints(
+                session,
+                effect_tools={"crear_evento", "mover_evento"},
+            )
+        ],
+    )
+    session.replace(result.all_messages())
+```
+
+El marcador activo contiene únicamente nombre e ID de cada tool, nunca argumentos. Memory lo cambia
+bajo su lock y Redis guarda el historial y elimina el marcador en una sola operación Lua. Si el
+proceso se interrumpe después de comenzar un efecto y antes del checkpoint, el siguiente `turn()`
+falla con `SESION_RECUPERACION_REQUERIDA` mientras el marcador siga vigente. Cada intento renueva su
+TTL y, sin intentos, expira junto con la sesión al cumplir `ttl_seconds`.
+
+Este marcador es un latch fail-closed, no una API de reconciliación. El consumidor debe comprobar o
+reconciliar el efecto por sus propios medios y después llamar `reset()`. Cortex no conserva los
+argumentos de la tool, no determina si la escritura externa ocurrió y no automatiza la recuperación.
+El latch sólo se elimina cuando todas las tools de efecto marcadas devuelven un `ToolReturn` exitoso;
+fallos, retries, denegaciones, interrupciones o resultados ausentes conservan el bloqueo.
+
+Todos los procesos que comparten `key_prefix` deben entender el marcador `:active`. La versión
+`0.3.1` lo ignora, por lo que no debe convivir mediante rolling deploy ni rollback con una versión
+que use checkpoints bajo el mismo prefix. La migración requiere un namespace nuevo y un corte
+coordinado de procesos.
+
 ## Endpoint compatible con OpenAI
 
 Pydantic AI puede conectarse directamente. Para un endpoint que no debe reintentar peticiones,
@@ -153,7 +204,10 @@ agent = Agent(
 ```
 
 La aplicación conserva la decisión sobre las tools elegibles. La capacidad no usa resultados
-fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo.
+fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo. Si
+la petición al provider falla después de un resultado elegible, devuelve ese resultado verificado,
+siempre que el run no contenga fallos ni retries de tools. Sin un resultado elegible y limpio,
+propaga intacta la excepción del provider. Los errores de tools no pasan por este fallback.
 
 ## Migración desde el runtime anterior
 
@@ -184,6 +238,7 @@ Pydantic AI.
 - `cortex_agent_sdk.sessions.MemorySessionStore`
 - `cortex_agent_sdk.redis.RedisSessionStore`
 - `cortex_agent_sdk.capabilities.last_tool_result_fallback`
+- `cortex_agent_sdk.capabilities.session_checkpoints`
 - `cortex_agent_sdk.errores.AppError`
 - `cortex_agent_sdk.errores.CodigoError`
 - `cortex_agent_sdk.errores.Severidad`

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/README.md

@@ -13,30 +13,36 @@ opcionales construidas sobre sus hooks públicos.
 ## Requisitos
 
 - Python `>=3.13`.
-- Pydantic AI `>=2.27,<3`, con Google y OpenAI instalados por Cortex.
+- Pydantic AI `>=2.27,<3`.
 
 ## Instalación
 
-Google, OpenAI y sesiones en memoria:
+Solo sesiones en memoria y capabilities:
 
 ```bash
 uv add cortex-agent-sdk
 ```
 
-Google, OpenAI y Redis:
+OpenAI y sesiones en memoria:
 
 ```bash
-uv add "cortex-agent-sdk[redis]"
+uv add "cortex-agent-sdk[openai]"
 ```
 
-La instalación base incluye Google y OpenAI, además de los endpoints compatibles con OpenAI. Otros
-providers pueden agregarse desde los extras oficiales de Pydantic AI cuando un producto realmente
-los necesite. Cortex no implementa adapters paralelos.
+OpenAI y Redis:
+
+```bash
+uv add "cortex-agent-sdk[openai,redis]"
+```
+
+Google se instala con el extra `google`. Cada producto elige únicamente sus providers. Cortex no
+implementa adapters paralelos ni ofrece un extra que los instale todos.
 
 ## Uso
 
 El agente es el `Agent` nativo de Pydantic AI. El store entrega el historial bajo exclusión y lo
 guarda cuando `session.replace(...)` marca un resultado completo.
+El siguiente ejemplo requiere el extra `openai`.
 
 ```python
 import asyncio
@@ -69,6 +75,7 @@ asyncio.run(main())
 
 - Si no se llama, el store no modifica el historial.
 - Si el bloque termina con una excepción, el store no guarda el reemplazo.
+- Los checkpoints confirmados dentro del turno permanecen aunque una operación posterior falle.
 - Si guardar falla, la excepción se propaga.
 
 ## Redis
@@ -91,6 +98,47 @@ historial se serializa con `ModelMessagesTypeAdapter`, el formato público de Py
 Al cambiar desde el runtime anterior, usa un prefix nuevo. Los formatos no son compatibles y Cortex
 no intenta convertir el historial legacy.
 
+## Checkpoints de tools
+
+`session_checkpoints` guarda el `ToolReturn` canónico al terminar cada `CallToolsNode`, antes de la
+siguiente petición al modelo. Las tools con efectos se declaran por nombre para marcar el turno antes
+de ejecutarlas:
+
+```python
+from cortex_agent_sdk.capabilities import session_checkpoints
+
+async with sessions.turn("usuario:42") as session:
+    result = await agent.run(
+        "Agenda la cita.",
+        message_history=session.messages,
+        conversation_id=session.session_id,
+        capabilities=[
+            session_checkpoints(
+                session,
+                effect_tools={"crear_evento", "mover_evento"},
+            )
+        ],
+    )
+    session.replace(result.all_messages())
+```
+
+El marcador activo contiene únicamente nombre e ID de cada tool, nunca argumentos. Memory lo cambia
+bajo su lock y Redis guarda el historial y elimina el marcador en una sola operación Lua. Si el
+proceso se interrumpe después de comenzar un efecto y antes del checkpoint, el siguiente `turn()`
+falla con `SESION_RECUPERACION_REQUERIDA` mientras el marcador siga vigente. Cada intento renueva su
+TTL y, sin intentos, expira junto con la sesión al cumplir `ttl_seconds`.
+
+Este marcador es un latch fail-closed, no una API de reconciliación. El consumidor debe comprobar o
+reconciliar el efecto por sus propios medios y después llamar `reset()`. Cortex no conserva los
+argumentos de la tool, no determina si la escritura externa ocurrió y no automatiza la recuperación.
+El latch sólo se elimina cuando todas las tools de efecto marcadas devuelven un `ToolReturn` exitoso;
+fallos, retries, denegaciones, interrupciones o resultados ausentes conservan el bloqueo.
+
+Todos los procesos que comparten `key_prefix` deben entender el marcador `:active`. La versión
+`0.3.1` lo ignora, por lo que no debe convivir mediante rolling deploy ni rollback con una versión
+que use checkpoints bajo el mismo prefix. La migración requiere un namespace nuevo y un corte
+coordinado de procesos.
+
 ## Endpoint compatible con OpenAI
 
 Pydantic AI puede conectarse directamente. Para un endpoint que no debe reintentar peticiones,
@@ -129,7 +177,10 @@ agent = Agent(
 ```
 
 La aplicación conserva la decisión sobre las tools elegibles. La capacidad no usa resultados
-fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo.
+fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo. Si
+la petición al provider falla después de un resultado elegible, devuelve ese resultado verificado,
+siempre que el run no contenga fallos ni retries de tools. Sin un resultado elegible y limpio,
+propaga intacta la excepción del provider. Los errores de tools no pasan por este fallback.
 
 ## Migración desde el runtime anterior
 
@@ -160,6 +211,7 @@ Pydantic AI.
 - `cortex_agent_sdk.sessions.MemorySessionStore`
 - `cortex_agent_sdk.redis.RedisSessionStore`
 - `cortex_agent_sdk.capabilities.last_tool_result_fallback`
+- `cortex_agent_sdk.capabilities.session_checkpoints`
 - `cortex_agent_sdk.errores.AppError`
 - `cortex_agent_sdk.errores.CodigoError`
 - `cortex_agent_sdk.errores.Severidad`

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Sesiones y capacidades puntuales para agentes multiprovider con Pydantic AI"
 readme = "README.md"
 license = "Apache-2.0"
@@ -17,7 +17,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "pydantic-ai-slim[google,openai]>=2.27,<3",
+    "pydantic-ai-slim>=2.27,<3",
 ]
 
 [project.urls]
@@ -25,7 +25,12 @@ Repository = "https://github.com/epok200/cortex_agent_sdk"
 Issues = "https://github.com/epok200/cortex_agent_sdk/issues"
 
 [project.optional-dependencies]
-openai = []
+google = [
+    "pydantic-ai-slim[google]>=2.27,<3",
+]
+openai = [
+    "pydantic-ai-slim[openai]>=2.27,<3",
+]
 redis = [
     "redis>=8.1.0",
 ]

cortex_agent_sdk-0.4.0/src/cortex_agent_sdk/capabilities.py

@@ -0,0 +1,165 @@
+"""Capacidades opcionales para agentes Pydantic AI."""
+
+from collections.abc import Collection
+from dataclasses import replace
+from typing import Any
+
+from pydantic_ai import CallToolsNode, ModelRequestNode, ModelResponse, RunContext, TextPart
+from pydantic_ai.capabilities.hooks import Hooks
+from pydantic_ai.exceptions import ModelAPIError
+from pydantic_ai.messages import ModelRequest, RetryPromptPart, ToolCallPart, ToolReturnPart
+from pydantic_ai.models import ModelRequestContext
+
+from cortex_agent_sdk.sessions import Session
+
+__all__ = ["last_tool_result_fallback", "session_checkpoints"]
+
+
+def last_tool_result_fallback(tool_names: str | Collection[str]) -> Hooks[Any]:
+    """Usa el último resultado elegible si el modelo termina sin texto."""
+    if isinstance(tool_names, str):
+        eligible_tools = frozenset((tool_names,))
+    else:
+        eligible_tools = frozenset(tool_names)
+
+    def use_last_tool_result(
+        ctx: RunContext[Any],
+        *,
+        request_context: ModelRequestContext,
+        response: ModelResponse,
+    ) -> ModelResponse:
+        if response.finish_reason not in {None, "stop"}:
+            return response
+        if response.text and response.text.strip():
+            return response
+        if response.tool_calls:
+            return response
+
+        result = _last_tool_result(request_context, ctx.run_id, eligible_tools)
+        if result is None:
+            return response
+        return replace(response, parts=[*response.parts, TextPart(result)])
+
+    def recover_provider_failure(
+        ctx: RunContext[Any],
+        *,
+        request_context: ModelRequestContext,
+        error: Exception,
+    ) -> ModelResponse:
+        if not isinstance(error, ModelAPIError):
+            raise error
+        result = _last_tool_result(request_context, ctx.run_id, eligible_tools)
+        if result is None:
+            raise error
+        return ModelResponse(parts=[TextPart(result)], finish_reason="stop")
+
+    return Hooks(
+        after_model_request=use_last_tool_result,
+        model_request_error=recover_provider_failure,
+    )
+
+
+def session_checkpoints(
+    session: Session,
+    *,
+    effect_tools: str | Collection[str],
+) -> Hooks[Any]:
+    """Persiste tools completadas y bloquea efectos ambiguos."""
+    if isinstance(effect_tools, str):
+        effect_tool_names = frozenset((effect_tools,))
+    else:
+        effect_tool_names = frozenset(effect_tools)
+    pending_runs: set[str | None] = set()
+
+    async def checkpoint_node(
+        ctx: RunContext[Any],
+        *,
+        node: Any,
+        result: Any,
+    ) -> Any:
+        if isinstance(result, CallToolsNode):
+            effect_calls = tuple(
+                call
+                for call in result.model_response.tool_calls
+                if call.tool_name in effect_tool_names
+            )
+            if effect_calls:
+                await session.start_tool_turn(effect_calls)
+                pending_runs.add(ctx.run_id)
+
+        if isinstance(node, CallToolsNode) and node.model_response.tool_calls:
+            effect_calls = tuple(
+                call
+                for call in node.model_response.tool_calls
+                if call.tool_name in effect_tool_names
+            )
+            if effect_calls and not _effect_calls_succeeded(ctx, result, effect_calls):
+                return result
+            if effect_calls:
+                pending_runs.discard(ctx.run_id)
+            if ctx.run_id in pending_runs:
+                return result
+
+            messages = list(ctx.messages)
+            if isinstance(result, ModelRequestNode):
+                messages.append(result.request)
+            await session.checkpoint(messages)
+            pending_runs.discard(ctx.run_id)
+
+        return result
+
+    return Hooks(after_node_run=checkpoint_node)
+
+
+def _effect_calls_succeeded(
+    ctx: RunContext[Any],
+    result: Any,
+    effect_calls: Collection[ToolCallPart],
+) -> bool:
+    if isinstance(result, ModelRequestNode):
+        request = result.request
+    else:
+        request = next(
+            (
+                message
+                for message in reversed(ctx.messages)
+                if isinstance(message, ModelRequest) and message.run_id == ctx.run_id
+            ),
+            None,
+        )
+    if request is None:
+        return False
+
+    successful = {
+        (part.tool_name, part.tool_call_id)
+        for part in request.parts
+        if isinstance(part, ToolReturnPart) and part.outcome == "success"
+    }
+    return all((call.tool_name, call.tool_call_id) in successful for call in effect_calls)
+
+
+def _last_tool_result(
+    request_context: ModelRequestContext,
+    run_id: str | None,
+    tool_names: Collection[str],
+) -> str | None:
+    if run_id is None:
+        return None
+    candidate: str | None = None
+    for message in request_context.messages:
+        if not isinstance(message, ModelRequest) or message.run_id != run_id:
+            continue
+        for part in message.parts:
+            if isinstance(part, RetryPromptPart) and part.tool_name is not None:
+                return None
+            if not isinstance(part, ToolReturnPart):
+                continue
+            if part.outcome != "success":
+                return None
+            if (
+                part.tool_name in tool_names
+                and isinstance(part.content, str)
+                and part.content.strip()
+            ):
+                candidate = part.content
+    return candidate

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/src/cortex_agent_sdk/errores/catalogo.py

@@ -14,5 +14,6 @@ class CodigoError(StrEnum):
     RECURSO_CERRADO = "RECURSO_CERRADO"
     SESION_OCUPADA = "SESION_OCUPADA"
     SESION_LEASE_PERDIDO = "SESION_LEASE_PERDIDO"
+    SESION_RECUPERACION_REQUERIDA = "SESION_RECUPERACION_REQUERIDA"
     SESION_INVALIDA = "SESION_INVALIDA"
     SESION_STORE_FALLO = "SESION_STORE_FALLO"

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/src/cortex_agent_sdk/redis/scripts.py

@@ -8,6 +8,9 @@ return 0
 RENEW = """
 if redis.call('get', KEYS[1]) == ARGV[1] then
     redis.call('pexpire', KEYS[1], ARGV[2])
+    if redis.call('exists', KEYS[2]) == 1 then
+        redis.call('pexpire', KEYS[2], ARGV[3])
+    end
     return 1
 end
 return 0
@@ -18,11 +21,14 @@ if redis.call('get', KEYS[1]) ~= ARGV[1] then
     return {0}
 end
 local payload = redis.call('get', KEYS[2])
+local active = redis.call('get', KEYS[3])
 if payload then
     redis.call('pexpire', KEYS[2], ARGV[2])
-    return {1, payload}
 end
-return {1}
+if active then
+    redis.call('pexpire', KEYS[3], ARGV[2])
+end
+return {1, payload or false, active or false}
 """
 
 SAVE = """
@@ -33,16 +39,39 @@ redis.call('psetex', KEYS[2], ARGV[3], ARGV[2])
 return 1
 """
 
+MARK_ACTIVE = """
+if redis.call('get', KEYS[1]) ~= ARGV[1] then
+    return 0
+end
+if redis.call('exists', KEYS[2]) == 1 then
+    return -1
+end
+redis.call('psetex', KEYS[2], ARGV[3], ARGV[2])
+return 1
+"""
+
+CHECKPOINT = """
+if redis.call('get', KEYS[1]) ~= ARGV[1] then
+    return 0
+end
+redis.call('psetex', KEYS[2], ARGV[3], ARGV[2])
+redis.call('del', KEYS[3])
+return 1
+"""
+
 RESET = """
 if redis.call('get', KEYS[1]) ~= ARGV[1] then
     return 0
 end
-redis.call('del', KEYS[2])
+redis.call('del', KEYS[2], KEYS[3])
 return 1
 """
 
 RELEASE = """
 if redis.call('get', KEYS[1]) == ARGV[1] then
+    if redis.call('exists', KEYS[2]) == 1 then
+        redis.call('pexpire', KEYS[2], ARGV[2])
+    end
     redis.call('del', KEYS[1])
     return 1
 end

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/src/cortex_agent_sdk/redis/store.py

@@ -1,19 +1,21 @@
 import asyncio
 import time
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from functools import partial
 from hashlib import sha256
 from typing import Self, cast
 from uuid import uuid4
 
+from pydantic_ai.messages import ModelMessage
 from redis.asyncio import Redis
 from redis.exceptions import RedisError
 
 from cortex_agent_sdk.errores import AppError, CodigoError
 from cortex_agent_sdk.redis import scripts
 from cortex_agent_sdk.sessions.codec import decode_messages, encode_messages
-from cortex_agent_sdk.sessions.models import Session
+from cortex_agent_sdk.sessions.models import ActiveTurn, Session
 
 type _RedisArgument = str | bytes | int | float
 
@@ -22,6 +24,7 @@ type _RedisArgument = str | bytes | int | float
 class _RedisKeys:
     lease: str
     history: str
+    active: str
 
 
 class RedisSessionStore:
@@ -69,18 +72,35 @@ class RedisSessionStore:
         timeout_seconds: float = 5.0,
     ) -> AsyncIterator[Session]:
         async with self._lease(session_id, timeout_seconds) as lease:
-            payload = await self._load(session_id, lease.owner)
+            payload, active_payload = await self._load(session_id, lease.owner)
+            if active_payload is not None:
+                raise AppError(
+                    CodigoError.SESION_RECUPERACION_REQUERIDA,
+                    f"turno incompleto en sesión {session_id}",
+                )
             messages = decode_messages(payload) if payload is not None else []
-            session = Session(session_id, messages)
-            yield session
-            self._raise_renewal_failure(lease)
-            if session.changed:
-                await self._save(session_id, lease.owner, encode_messages(session.messages))
+            session = Session(
+                session_id,
+                messages,
+                _start_tool_turn=partial(self._mark_active, session_id, lease.owner),
+                _save_checkpoint=partial(self._checkpoint, session_id, lease.owner),
+            )
+            try:
+                yield session
+                self._raise_renewal_failure(lease)
+                if session.changed:
+                    await self._save(session_id, lease.owner, encode_messages(session.messages))
+            finally:
+                session._detach()
 
     async def reset(self, session_id: str, timeout_seconds: float = 5.0) -> None:
         async with self._lease(session_id, timeout_seconds) as lease:
             keys = self._keys(session_id)
-            result = await self._eval(scripts.RESET, (keys.lease, keys.history), lease.owner)
+            result = await self._eval(
+                scripts.RESET,
+                (keys.lease, keys.history, keys.active),
+                lease.owner,
+            )
             if int(cast(int, result)) != 1:
                 raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
@@ -201,16 +221,17 @@ class RedisSessionStore:
         owner: str,
         owner_task: asyncio.Task,
     ) -> None:
-        interval = self._lease_milliseconds / 3_000
+        interval = min(self._lease_milliseconds, self._ttl_milliseconds) / 3_000
+        keys = self._keys(session_id)
         try:
             while True:
                 await asyncio.sleep(interval)
-                lease_key = self._keys(session_id).lease
                 result = await self._eval(
                     scripts.RENEW,
-                    (lease_key,),
+                    (keys.lease, keys.active),
                     owner,
                     self._lease_milliseconds,
+                    self._ttl_milliseconds,
                 )
                 if int(cast(int, result)) != 1:
                     raise AppError(
@@ -230,20 +251,20 @@ class RedisSessionStore:
             owner_task.cancel()
             raise failure from error
 
-    async def _load(self, session_id: str, owner: str) -> bytes | None:
+    async def _load(self, session_id: str, owner: str) -> tuple[bytes | None, bytes | None]:
         keys = self._keys(session_id)
         raw = await self._eval(
             scripts.LOAD,
-            (keys.lease, keys.history),
+            (keys.lease, keys.history, keys.active),
             owner,
             self._ttl_milliseconds,
         )
         result = cast(list[object], raw)
         if not result or int(cast(int, result[0])) != 1:
             raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
-        if len(result) == 1:
-            return None
-        return cast(bytes, result[1])
+        history = cast(bytes | None, result[1])
+        active = cast(bytes | None, result[2])
+        return history, active
 
     async def _save(self, session_id: str, owner: str, payload: bytes) -> None:
         keys = self._keys(session_id)
@@ -257,9 +278,51 @@ class RedisSessionStore:
         if int(cast(int, result)) != 1:
             raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
+    async def _mark_active(
+        self,
+        session_id: str,
+        owner: str,
+        active_turn: ActiveTurn,
+    ) -> None:
+        keys = self._keys(session_id)
+        result = await self._eval(
+            scripts.MARK_ACTIVE,
+            (keys.lease, keys.active),
+            owner,
+            active_turn.model_dump_json().encode(),
+            self._ttl_milliseconds,
+        )
+        status = int(cast(int, result))
+        if status == -1:
+            raise AppError(CodigoError.SESION_INVALIDA, "la sesión ya tiene un turno activo")
+        if status != 1:
+            raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
+
+    async def _checkpoint(
+        self,
+        session_id: str,
+        owner: str,
+        messages: Sequence[ModelMessage],
+    ) -> None:
+        keys = self._keys(session_id)
+        result = await self._eval(
+            scripts.CHECKPOINT,
+            (keys.lease, keys.history, keys.active),
+            owner,
+            encode_messages(messages),
+            self._ttl_milliseconds,
+        )
+        if int(cast(int, result)) != 1:
+            raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
+
     async def _release(self, session_id: str, owner: str) -> None:
-        lease_key = self._keys(session_id).lease
-        result = await self._eval(scripts.RELEASE, (lease_key,), owner)
+        keys = self._keys(session_id)
+        result = await self._eval(
+            scripts.RELEASE,
+            (keys.lease, keys.active),
+            owner,
+            self._ttl_milliseconds,
+        )
         if int(cast(int, result)) != 1:
             raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
@@ -313,7 +376,11 @@ class RedisSessionStore:
     def _keys(self, session_id: str) -> _RedisKeys:
         digest = sha256(session_id.encode()).hexdigest()
         base = f"{self._key_prefix}:{{{digest}}}"
-        return _RedisKeys(lease=f"{base}:lease", history=f"{base}:history")
+        return _RedisKeys(
+            lease=f"{base}:lease",
+            history=f"{base}:history",
+            active=f"{base}:active",
+        )
 
     def _validate_turn(self, session_id: str, timeout_seconds: float) -> None:
         if not session_id or timeout_seconds <= 0:

{cortex_agent_sdk-0.3.0 → cortex_agent_sdk-0.4.0}/src/cortex_agent_sdk/sessions/memory.py

@@ -1,21 +1,23 @@
 import asyncio
 import time
 from collections import OrderedDict
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
+from functools import partial
 from typing import Self
 
 from pydantic_ai.messages import ModelMessage
 
 from cortex_agent_sdk.errores import AppError, CodigoError
 from cortex_agent_sdk.sessions.codec import decode_messages, encode_messages
-from cortex_agent_sdk.sessions.models import Session
+from cortex_agent_sdk.sessions.models import ActiveTurn, Session
 
 
 @dataclass(slots=True)
 class _Entry:
     payload: bytes
+    active_turn: ActiveTurn | None
     expires_at: float
 
 
@@ -25,6 +27,11 @@ class _SessionLock:
     users: int = 0
 
 
+@dataclass(slots=True)
+class _TurnOwner:
+    active: bool = True
+
+
 class MemorySessionStore:
     """Sesiones locales con exclusión por turno, TTL y LRU."""
 
@@ -52,10 +59,28 @@ class MemorySessionStore:
         timeout_seconds: float = 5.0,
     ) -> AsyncIterator[Session]:
         async with self._lock(session_id, timeout_seconds):
-            session = Session(session_id, await self._load(session_id))
-            yield session
-            if session.changed:
-                await self._save(session_id, session.messages)
+            entry = await self._load(session_id)
+            if entry is not None and entry.active_turn is not None:
+                raise AppError(
+                    CodigoError.SESION_RECUPERACION_REQUERIDA,
+                    f"turno incompleto en sesión {session_id}",
+                )
+            messages = decode_messages(entry.payload) if entry is not None else []
+            owner = _TurnOwner()
+            session = Session(
+                session_id,
+                messages,
+                _start_tool_turn=partial(self._mark_active, session_id, owner),
+                _save_checkpoint=partial(self._checkpoint, session_id, owner),
+            )
+            try:
+                yield session
+                if session.changed:
+                    await self._save(session_id, session.messages)
+            finally:
+                owner.active = False
+                session._detach()
+                await self._refresh_active(session_id)
 
     async def reset(self, session_id: str, timeout_seconds: float = 5.0) -> None:
         async with self._lock(session_id, timeout_seconds), self._guard:
@@ -70,28 +95,89 @@ class MemorySessionStore:
             self._closed = True
             self._entries.clear()
 
-    async def _load(self, session_id: str) -> list[ModelMessage]:
+    async def _load(self, session_id: str) -> _Entry | None:
         async with self._guard:
             self._ensure_open()
             entry = self._entries.get(session_id)
             if entry is None:
-                return []
+                return None
             if entry.expires_at <= time.monotonic():
                 del self._entries[session_id]
-                return []
+                return None
             entry.expires_at = time.monotonic() + self._ttl_seconds
             self._entries.move_to_end(session_id)
-            return decode_messages(entry.payload)
+            return entry
 
     async def _save(self, session_id: str, messages: list[ModelMessage]) -> None:
         payload = encode_messages(messages)
         async with self._guard:
             self._ensure_open()
-            expires_at = time.monotonic() + self._ttl_seconds
-            self._entries[session_id] = _Entry(payload, expires_at)
-            self._entries.move_to_end(session_id)
-            while len(self._entries) > self._max_sessions:
-                self._entries.popitem(last=False)
+            current = self._entries.get(session_id)
+            active_turn = current.active_turn if current is not None else None
+            self._write_entry(session_id, payload, active_turn)
+
+    async def _mark_active(
+        self,
+        session_id: str,
+        owner: _TurnOwner,
+        active_turn: ActiveTurn,
+    ) -> None:
+        async with self._guard:
+            self._ensure_open()
+            if not owner.active:
+                raise AppError(CodigoError.SESION_INVALIDA, "sesión fuera de su turno")
+            current = self._entries.get(session_id)
+            if current is not None and current.active_turn is not None:
+                raise AppError(CodigoError.SESION_INVALIDA, "la sesión ya tiene un turno activo")
+            payload = current.payload if current is not None else encode_messages([])
+            self._write_entry(session_id, payload, active_turn)
+
+    async def _checkpoint(
+        self,
+        session_id: str,
+        owner: _TurnOwner,
+        messages: Sequence[ModelMessage],
+    ) -> None:
+        payload = encode_messages(messages)
+        async with self._guard:
+            self._ensure_open()
+            if not owner.active:
+                raise AppError(CodigoError.SESION_INVALIDA, "sesión fuera de su turno")
+            self._write_entry(session_id, payload, None)
+
+    async def _refresh_active(self, session_id: str) -> None:
+        async with self._guard:
+            entry = self._entries.get(session_id)
+            if entry is not None and entry.active_turn is not None:
+                entry.expires_at = time.monotonic() + self._ttl_seconds
+
+    def _write_entry(
+        self,
+        session_id: str,
+        payload: bytes,
+        active_turn: ActiveTurn | None,
+    ) -> None:
+        now = time.monotonic()
+        expires_at = now + self._ttl_seconds
+        self._entries[session_id] = _Entry(payload, active_turn, expires_at)
+        self._entries.move_to_end(session_id)
+        for key, entry in tuple(self._entries.items()):
+            if entry.expires_at <= now and key not in self._locks:
+                del self._entries[key]
+        while len(self._entries) > self._max_sessions:
+            evictable = next(
+                (
+                    key
+                    for key, entry in self._entries.items()
+                    if key != session_id
+                    and key not in self._locks
+                    and entry.active_turn is None
+                ),
+                None,
+            )
+            if evictable is None:
+                break
+            del self._entries[evictable]
 
     @asynccontextmanager
     async def _lock(

cortex_agent_sdk-0.4.0/src/cortex_agent_sdk/sessions/models.py

@@ -0,0 +1,58 @@
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.messages import ModelMessage, ToolCallPart
+
+from cortex_agent_sdk.errores import AppError, CodigoError
+
+
+class ActiveTurn(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    calls: tuple[tuple[str, str], ...]
+
+
+type _StartToolTurn = Callable[[ActiveTurn], Awaitable[None]]
+type _Checkpoint = Callable[[Sequence[ModelMessage]], Awaitable[None]]
+
+
+@dataclass(slots=True)
+class Session:
+    """Historial aislado mientras un turno posee la sesión."""
+
+    session_id: str
+    messages: list[ModelMessage]
+    _changed: bool = field(default=False, init=False, repr=False)
+    _start_tool_turn: _StartToolTurn | None = field(default=None, repr=False)
+    _save_checkpoint: _Checkpoint | None = field(default=None, repr=False)
+
+    @property
+    def changed(self) -> bool:
+        return self._changed
+
+    def replace(self, messages: Sequence[ModelMessage]) -> None:
+        self.messages = list(messages)
+        self._changed = True
+
+    async def start_tool_turn(self, calls: Sequence[ToolCallPart]) -> None:
+        if self._start_tool_turn is None:
+            raise AppError(CodigoError.CONFIG_INVALIDA, "sesión sin persistencia inmediata")
+        if not calls:
+            raise AppError(CodigoError.SESION_INVALIDA, "turno de tools activo inválido")
+
+        identities = tuple((call.tool_name, call.tool_call_id) for call in calls)
+        active_turn = ActiveTurn(calls=identities)
+        await self._start_tool_turn(active_turn)
+
+    async def checkpoint(self, messages: Sequence[ModelMessage]) -> None:
+        if self._save_checkpoint is None:
+            raise AppError(CodigoError.CONFIG_INVALIDA, "sesión sin persistencia inmediata")
+
+        checkpoint = list(messages)
+        await self._save_checkpoint(checkpoint)
+        self.messages = checkpoint
+
+    def _detach(self) -> None:
+        self._start_tool_turn = None
+        self._save_checkpoint = None

cortex_agent_sdk-0.3.0/src/cortex_agent_sdk/capabilities.py

@@ -1,62 +0,0 @@
-"""Capacidades opcionales para agentes Pydantic AI."""
-
-from collections.abc import Collection
-from dataclasses import replace
-from typing import Any
-
-from pydantic_ai import ModelResponse, RunContext, TextPart
-from pydantic_ai.capabilities.hooks import Hooks
-from pydantic_ai.messages import ModelRequest, ToolReturnPart
-from pydantic_ai.models import ModelRequestContext
-
-__all__ = ["last_tool_result_fallback"]
-
-
-def last_tool_result_fallback(tool_names: str | Collection[str]) -> Hooks[Any]:
-    """Usa el último resultado elegible si el modelo termina sin texto."""
-    if isinstance(tool_names, str):
-        eligible_tools = frozenset((tool_names,))
-    else:
-        eligible_tools = frozenset(tool_names)
-
-    def use_last_tool_result(
-        ctx: RunContext[Any],
-        *,
-        request_context: ModelRequestContext,
-        response: ModelResponse,
-    ) -> ModelResponse:
-        if response.finish_reason not in {None, "stop"}:
-            return response
-        if response.text and response.text.strip():
-            return response
-        if response.tool_calls:
-            return response
-
-        result = _last_tool_result(request_context, ctx.run_id, eligible_tools)
-        if result is None:
-            return response
-        return replace(response, parts=[*response.parts, TextPart(result)])
-
-    return Hooks(after_model_request=use_last_tool_result)
-
-
-def _last_tool_result(
-    request_context: ModelRequestContext,
-    run_id: str | None,
-    tool_names: Collection[str],
-) -> str | None:
-    if run_id is None:
-        return None
-    for message in reversed(request_context.messages):
-        if not isinstance(message, ModelRequest) or message.run_id != run_id:
-            continue
-        for part in reversed(message.parts):
-            if (
-                isinstance(part, ToolReturnPart)
-                and part.outcome == "success"
-                and part.tool_name in tool_names
-                and isinstance(part.content, str)
-                and part.content.strip()
-            ):
-                return part.content
-    return None

cortex_agent_sdk-0.3.0/src/cortex_agent_sdk/sessions/models.py

@@ -1,21 +0,0 @@
-from collections.abc import Sequence
-from dataclasses import dataclass, field
-
-from pydantic_ai.messages import ModelMessage
-
-
-@dataclass(slots=True)
-class Session:
-    """Historial aislado mientras un turno posee la sesión."""
-
-    session_id: str
-    messages: list[ModelMessage]
-    _changed: bool = field(default=False, init=False, repr=False)
-
-    @property
-    def changed(self) -> bool:
-        return self._changed
-
-    def replace(self, messages: Sequence[ModelMessage]) -> None:
-        self.messages = list(messages)
-        self._changed = True