aury-agent 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

aury/agents/backends/__init__.py

@@ -29,6 +29,7 @@ from .invocation import InvocationBackend, InMemoryInvocationBackend
 from .message import MessageBackend, InMemoryMessageBackend
 from .memory import MemoryBackend, InMemoryMemoryBackend
 from .artifact import ArtifactBackend, ArtifactSource, InMemoryArtifactBackend
+from .hitl import HITLBackend, InMemoryHITLBackend
 
 # State backend - simplified to key-value
 from .state import StateBackend, StateStore, StoreBasedStateBackend, SQLiteStateBackend, MemoryStateBackend, FileStateBackend, CompositeStateBackend
@@ -87,6 +88,7 @@ class Backends:
     memory: MemoryBackend | None = None
     artifact: ArtifactBackend | None = None
     state: StateBackend | None = None
+    hitl: HITLBackend | None = None
     
     # Capability backends - optional
     snapshot: SnapshotBackend | None = None
@@ -108,6 +110,7 @@ class Backends:
             memory=InMemoryMemoryBackend(),
             artifact=InMemoryArtifactBackend(),
             state=MemoryStateBackend(),
+            hitl=InMemoryHITLBackend(),
         )
     
     @classmethod
@@ -127,6 +130,7 @@ class Backends:
             memory=InMemoryMemoryBackend(),
             artifact=InMemoryArtifactBackend(),
             state=SQLiteStateBackend(db_path),
+            hitl=InMemoryHITLBackend(),
         )
 
 
@@ -155,6 +159,10 @@ __all__ = [
     "ArtifactSource",
     "InMemoryArtifactBackend",
     
+    # HITL backend
+    "HITLBackend",
+    "InMemoryHITLBackend",
+    
     # State backend (key-value)
     "StateBackend",
     "StateStore",

aury/agents/backends/hitl/__init__.py

@@ -0,0 +1,8 @@
+"""HITL backend."""
+from .types import HITLBackend
+from .memory import InMemoryHITLBackend
+
+__all__ = [
+    "HITLBackend",
+    "InMemoryHITLBackend",
+]

aury/agents/backends/hitl/memory.py

@@ -0,0 +1,100 @@
+"""In-memory HITL backend implementation."""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class InMemoryHITLBackend:
+    """In-memory HITL backend for development/testing."""
+    
+    def __init__(self) -> None:
+        self._records: dict[str, dict[str, Any]] = {}
+    
+    async def create(
+        self,
+        *,
+        hitl_id: str,
+        hitl_type: str,
+        session_id: str,
+        invocation_id: str,
+        data: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        block_id: str | None = None,
+        resume_mode: str = "response",
+        tool_state: dict[str, Any] | None = None,
+        checkpoint_id: str | None = None,
+        tool_name: str | None = None,
+        tool_call_id: str | None = None,
+        node_id: str | None = None,
+        expires_at: int | None = None,
+    ) -> None:
+        """Create a new HITL record."""
+        now = int(time.time())
+        self._records[hitl_id] = {
+            "hitl_id": hitl_id,
+            "hitl_type": hitl_type,
+            "session_id": session_id,
+            "invocation_id": invocation_id,
+            "data": data or {},
+            "metadata": metadata or {},
+            "block_id": block_id,
+            "status": "pending",
+            "resume_mode": resume_mode,
+            "tool_state": tool_state,
+            "checkpoint_id": checkpoint_id,
+            "tool_name": tool_name,
+            "tool_call_id": tool_call_id,
+            "node_id": node_id,
+            "expires_at": expires_at,
+            "user_response": None,
+            "responded_at": None,
+            "created_at": now,
+            "updated_at": now,
+        }
+    
+    async def get(self, hitl_id: str) -> dict[str, Any] | None:
+        """Get HITL record by ID."""
+        return self._records.get(hitl_id)
+    
+    async def respond(
+        self,
+        hitl_id: str,
+        user_response: dict[str, Any],
+    ) -> None:
+        """Record user response to HITL."""
+        if hitl_id in self._records:
+            now = int(time.time())
+            self._records[hitl_id]["status"] = "completed"
+            self._records[hitl_id]["user_response"] = user_response
+            self._records[hitl_id]["responded_at"] = now
+            self._records[hitl_id]["updated_at"] = now
+    
+    async def cancel(self, hitl_id: str) -> None:
+        """Cancel a pending HITL request."""
+        if hitl_id in self._records:
+            self._records[hitl_id]["status"] = "cancelled"
+            self._records[hitl_id]["updated_at"] = int(time.time())
+    
+    async def get_pending_by_session(
+        self,
+        session_id: str,
+    ) -> list[dict[str, Any]]:
+        """Get all pending HITL for a session."""
+        return [
+            r for r in self._records.values()
+            if r["session_id"] == session_id and r["status"] == "pending"
+        ]
+    
+    async def get_pending_by_invocation(
+        self,
+        invocation_id: str,
+    ) -> list[dict[str, Any]]:
+        """Get all pending HITL for an invocation."""
+        return [
+            r for r in self._records.values()
+            if r["invocation_id"] == invocation_id and r["status"] == "pending"
+        ]
+
+
+__all__ = ["InMemoryHITLBackend"]

aury/agents/backends/hitl/types.py

@@ -0,0 +1,132 @@
+"""HITL backend types and protocols."""
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HITLBackend(Protocol):
+    """Protocol for HITL (Human-in-the-Loop) persistence.
+    
+    Stores HITL requests and user responses for:
+    - ask_user, confirm, permission requests
+    - External auth callbacks
+    - Workflow human tasks
+    
+    Example usage:
+        # Create HITL request
+        await backend.create(
+            hitl_id="hitl_123",
+            hitl_type="ask_user",
+            session_id="sess_456",
+            invocation_id="inv_789",
+            data={"message": "What do you want?", "options": ["A", "B"]},
+        )
+        
+        # Get HITL
+        hitl = await backend.get("hitl_123")
+        
+        # Respond
+        await backend.respond("hitl_123", {"answer": "A"})
+    """
+    
+    async def create(
+        self,
+        *,
+        hitl_id: str,
+        hitl_type: str,
+        session_id: str,
+        invocation_id: str,
+        data: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        block_id: str | None = None,
+        resume_mode: str = "response",
+        tool_state: dict[str, Any] | None = None,
+        checkpoint_id: str | None = None,
+        tool_name: str | None = None,
+        tool_call_id: str | None = None,
+        node_id: str | None = None,
+        expires_at: int | None = None,
+    ) -> None:
+        """Create a new HITL record.
+        
+        Args:
+            hitl_id: Unique HITL identifier
+            hitl_type: Type of HITL (ask_user, confirm, permission, etc.)
+            session_id: Parent session ID
+            invocation_id: Parent invocation ID
+            data: Type-specific data (message, options, etc.)
+            metadata: Additional metadata
+            block_id: Associated UI block ID
+            resume_mode: How to resume ("response" or "continuation")
+            tool_state: Tool internal state for continuation
+            checkpoint_id: Checkpoint ID for continuation
+            tool_name: Tool that triggered HITL
+            tool_call_id: Tool call ID
+            node_id: Workflow node ID
+            expires_at: Expiration timestamp (unix)
+        """
+        ...
+    
+    async def get(self, hitl_id: str) -> dict[str, Any] | None:
+        """Get HITL record by ID.
+        
+        Args:
+            hitl_id: HITL identifier
+            
+        Returns:
+            HITL data dict or None if not found
+        """
+        ...
+    
+    async def respond(
+        self,
+        hitl_id: str,
+        user_response: dict[str, Any],
+    ) -> None:
+        """Record user response to HITL.
+        
+        Args:
+            hitl_id: HITL identifier
+            user_response: User's response data
+        """
+        ...
+    
+    async def cancel(self, hitl_id: str) -> None:
+        """Cancel a pending HITL request.
+        
+        Args:
+            hitl_id: HITL identifier
+        """
+        ...
+    
+    async def get_pending_by_session(
+        self,
+        session_id: str,
+    ) -> list[dict[str, Any]]:
+        """Get all pending HITL for a session.
+        
+        Args:
+            session_id: Session ID
+            
+        Returns:
+            List of pending HITL records
+        """
+        ...
+    
+    async def get_pending_by_invocation(
+        self,
+        invocation_id: str,
+    ) -> list[dict[str, Any]]:
+        """Get all pending HITL for an invocation.
+        
+        Args:
+            invocation_id: Invocation ID
+            
+        Returns:
+            List of pending HITL records
+        """
+        ...
+
+
+__all__ = ["HITLBackend"]

aury/agents/core/base.py

@@ -76,6 +76,11 @@ class AgentConfig:
     # Tool injection mode
     tool_mode: ToolInjectionMode = ToolInjectionMode.FUNCTION_CALL
     
+    # HITL state persistence (for resume support)
+    # If True, save agent_state when suspended for later resume
+    # If False, skip state persistence (lighter weight, but can't resume)
+    persist_hitl_state: bool = False
+    
     # Extra metadata for agent-specific config
     metadata: dict[str, Any] = field(default_factory=dict)
     
@@ -352,6 +357,13 @@ class BaseAgent(ABC):
             logger.error(f"{self.agent_type}Agent run error, error={type(e).__name__}, invocation_id={self._ctx.invocation_id}", exc_info=True)
             raise
         finally:
+            # Cancel exec_task if still running (e.g., when run() is cancelled externally)
+            if exec_task and not exec_task.done():
+                exec_task.cancel()
+                try:
+                    await exec_task
+                except asyncio.CancelledError:
+                    pass
             _reset_current_ctx(ctx_token)
             _emit_queue_var.reset(queue_token)
             self._run_config = {}  # Clear runtime overrides

aury/agents/core/context.py

@@ -276,6 +276,7 @@ class InvocationContext:
     
     # Tool execution context (set when executing a tool)
     tool_call_id: str | None = None
+    tool_block_id: str | None = None
     
     # Abort signals
     abort_self: asyncio.Event = field(default_factory=asyncio.Event)

aury/agents/core/signals.py

@@ -40,54 +40,74 @@ class HITLSuspend(SuspendSignal):
     1. Display the request to user
     2. Resume execution after user responds
     
+    Supports two resume modes:
+    - "response": (Default) User response is returned to LLM as tool output.
+    - "continuation": Tool execution is resumed from checkpoint,
+      user response is passed to tool to continue processing.
+    
     Attributes:
-        request_id: Unique ID for matching response
-        request_type: Type of request (ask_user, confirm, form, etc.)
-        message: Display message for user
-        options: Optional list of choices
+        hitl_id: Unique ID for matching response
+        hitl_type: Type of HITL (ask_user, confirm, external_auth, etc.)
+        data: Type-specific data (message, options, etc.)
         node_id: Workflow node ID if triggered from workflow
         tool_name: Tool name if triggered from tool
         block_id: Associated UI block ID
         metadata: Additional context
+        resume_mode: How to resume after user responds
+        tool_state: Tool internal state for continuation mode
+        checkpoint_id: Unique ID for tool checkpoint
     """
-    request_id: str
-    request_type: str = "ask_user"
-    message: str | None = None
-    options: list[str] | None = None
+    hitl_id: str
+    hitl_type: str = "ask_user"
+    data: dict[str, Any] = field(default_factory=dict)  # Type-specific: {message, options, ...}
     node_id: str | None = None
     tool_name: str | None = None
     block_id: str | None = None
     metadata: dict[str, Any] = field(default_factory=dict)
     
+    # Continuation support
+    resume_mode: str = "response"  # "response" | "continuation"
+    tool_state: dict[str, Any] | None = None  # Internal state for continuation
+    checkpoint_id: str | None = None  # Checkpoint ID for restoration
+    
     def __post_init__(self):
         # Initialize BaseException with a message
-        super().__init__(f"HITL suspend: {self.request_type} ({self.request_id})")
+        super().__init__(f"HITL suspend: {self.hitl_type} ({self.hitl_id})")
+    
+    @property
+    def is_continuation(self) -> bool:
+        """Check if this suspend requires continuation mode."""
+        return self.resume_mode == "continuation"
     
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for storage/transmission."""
         return {
-            "request_id": self.request_id,
-            "request_type": self.request_type,
-            "message": self.message,
-            "options": self.options,
+            "hitl_id": self.hitl_id,
+            "hitl_type": self.hitl_type,
+            "data": self.data,
             "node_id": self.node_id,
             "tool_name": self.tool_name,
             "block_id": self.block_id,
             "metadata": self.metadata,
+            "resume_mode": self.resume_mode,
+            "tool_state": self.tool_state,
+            "checkpoint_id": self.checkpoint_id,
         }
     
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "HITLSuspend":
         """Create from dictionary."""
         return cls(
-            request_id=data["request_id"],
-            request_type=data.get("request_type", "ask_user"),
-            message=data.get("message"),
-            options=data.get("options"),
+            hitl_id=data["hitl_id"],
+            hitl_type=data.get("hitl_type", "ask_user"),
+            data=data.get("data", {}),
             node_id=data.get("node_id"),
             tool_name=data.get("tool_name"),
             block_id=data.get("block_id"),
             metadata=data.get("metadata", {}),
+            resume_mode=data.get("resume_mode", "response"),
+            tool_state=data.get("tool_state"),
+            checkpoint_id=data.get("checkpoint_id"),
         )
 
 

aury/agents/core/types/__init__.py

@@ -32,7 +32,6 @@ from .block import (
     thinking_delta,
     tool_use_block,
     tool_use_patch,
-    tool_result_block,
     error_block,
 )
 from .message import (
@@ -86,7 +85,6 @@ __all__ = [
     "thinking_delta",
     "tool_use_block",
     "tool_use_patch",
-    "tool_result_block",
     "error_block",
     # Message
     "MessageRole",

aury/agents/core/types/block.py

@@ -27,8 +27,11 @@ class BlockKind(str, Enum):
     THINKING = "thinking"      # LLM reasoning (collapsible)
     
     # === Tool Execution ===
-    TOOL_USE = "tool_use"      # Tool call
-    TOOL_RESULT = "tool_result"  # Tool result
+    # TOOL_USE manages entire tool lifecycle via PATCH:
+    # APPLY → {name, call_id, arguments, status: "pending"}
+    # PATCH → {status: "running", progress: ...}  (tool can emit during execution)
+    # PATCH → {status: "success"}  (framework emits on completion)
+    TOOL_USE = "tool_use"
     
     # === Agent ===
     SUB_AGENT = "sub_agent"    # Sub-agent delegation
@@ -40,7 +43,7 @@ class BlockKind(str, Enum):
     NODE = "node"              # Workflow node execution block
     
     # === HITL ===
-    HITL_REQUEST = "hitl_request"  # HITL request (any format - choice, input, confirm, etc.)
+    HITL = "hitl"  # Human-in-the-loop (ask_user, confirm, permission, etc.)
     
     # === Control Flow ===
     YIELD = "yield"               # Return control to parent
@@ -700,26 +703,6 @@ def tool_use_patch(block_id: str, args: dict[str, Any]) -> BlockEvent:
     )
 
 
-def tool_result_block(
-    block_id: str,
-    tool_use_id: str,
-    content: str,
-    is_error: bool = False,
-    parent_id: str | None = None,
-) -> BlockEvent:
-    """Create a tool result block."""
-    return BlockEvent(
-        block_id=block_id,
-        parent_id=parent_id,
-        kind=BlockKind.TOOL_RESULT,
-        op=BlockOp.APPLY,
-        data={
-            "tool_use_id": tool_use_id,
-            "content": content,
-            "is_error": is_error,
-        },
-    )
-
 
 def error_block(
     block_id: str,