aury-agent 0.0.12__py3-none-any.whl → 0.0.14__py3-none-any.whl

aury/agents/core/types/tool.py

@@ -65,8 +65,8 @@ class ToolContext:
         
         await global_emit(block)
     
-    async def emit_hitl(self, request_id: str, data: dict[str, Any]) -> None:
-        """Emit a HITL request block.
+    async def emit_hitl(self, hitl_id: str, data: dict[str, Any]) -> None:
+        """Emit a HITL block.
         
         Convenience method for tools that need user interaction.
         The data format is flexible - can be anything the frontend understands:
@@ -76,15 +76,15 @@ class ToolContext:
         - Rich content (product cards, file selection, etc.)
         
         Args:
-            request_id: Unique ID for this HITL request
+            hitl_id: Unique ID for this HITL request
             data: Arbitrary data dict for frontend to render.
                   Common fields: type, question, choices, default, context
         """
         from .block import BlockEvent, BlockKind
         
         await self.emit(BlockEvent(
-            kind=BlockKind.HITL_REQUEST,
-            data={"request_id": request_id, **data},
+            kind=BlockKind.HITL,
+            data={"hitl_id": hitl_id, **data},
         ))
 
 
@@ -92,15 +92,29 @@ class ToolContext:
 class ToolResult:
     """Tool execution result for LLM.
     
-    Supports dual output for context management:
-    - output: Complete output (raw), for storage and recall
-    - truncated_output: Shortened output for context window
+    This is the text result returned to LLM. For frontend rendering,
+    tools should use ctx.emit(BlockEvent(...)) to PATCH the TOOL_USE block
+    with structured data during execution.
     
-    If truncated_output is not provided, it defaults to output.
+    Fields:
+    - output: Complete text output for LLM
+    - truncated_output: Shortened output for context window management
+    
+    Example (image generation tool):
+        # During execution, PATCH block with structured data for frontend
+        await ctx.emit(BlockEvent(
+            block_id=ctx.block_id,
+            kind=BlockKind.TOOL_USE,
+            op=BlockOp.PATCH,
+            data={"images": [{"url": "..."}], "progress": 100},
+        ))
+        
+        # Return text for LLM
+        return ToolResult.success("已生成4张图片")
     """
-    output: str  # Complete output (raw)
+    output: str  # Text output for LLM
     is_error: bool = False
-    truncated_output: str | None = None  # Shortened output (defaults to output)
+    truncated_output: str | None = None  # Shortened output for LLM context window
     
     def __post_init__(self):
         # Default truncated to output if not provided
@@ -117,8 +131,8 @@ class ToolResult:
         """Create a successful result.
         
         Args:
-            output: Complete output (raw)
-            truncated_output: Shortened output for context (defaults to output)
+            output: Text output for LLM
+            truncated_output: Shortened output for LLM context (defaults to output)
         """
         return cls(
             output=output,
@@ -136,7 +150,11 @@ class ToolInvocationState(Enum):
     """Tool invocation state machine."""
     PARTIAL_CALL = "partial-call"  # Arguments streaming
     CALL = "call"  # Arguments complete, ready to execute
-    RESULT = "result"  # Execution complete
+    RESULT = "result"  # Execution complete (deprecated, use SUCCESS/FAILED/ABORTED)
+    # Execution result states
+    SUCCESS = "success"  # Execution successful
+    FAILED = "failed"  # Execution failed (including timeout)
+    ABORTED = "aborted"  # User aborted
 
 
 @dataclass
@@ -144,6 +162,7 @@ class ToolInvocation:
     """Tool invocation tracking (state machine)."""
     tool_call_id: str
     tool_name: str
+    block_id: str = ""  # Associated TOOL_USE block ID
     state: ToolInvocationState = ToolInvocationState.PARTIAL_CALL
     args: dict[str, Any] = field(default_factory=dict)
     args_raw: str = ""  # Raw JSON string for streaming
@@ -167,6 +186,7 @@ class ToolInvocation:
         result: str,
         is_error: bool = False,
         truncated_result: str | None = None,
+        status: ToolInvocationState | None = None,
     ) -> None:
         """Mark execution complete.
         
@@ -174,8 +194,17 @@ class ToolInvocation:
             result: Complete result (raw)
             is_error: Whether this is an error result
             truncated_result: Shortened result for context window (defaults to result)
+            status: Explicit status (SUCCESS/FAILED/ABORTED). If not provided,
+                    automatically inferred from is_error flag.
         """
-        self.state = ToolInvocationState.RESULT
+        # Set state based on explicit status or infer from is_error
+        if status:
+            self.state = status
+        elif is_error:
+            self.state = ToolInvocationState.FAILED
+        else:
+            self.state = ToolInvocationState.SUCCESS
+        
         self.result = result
         self.truncated_result = truncated_result if truncated_result is not None else result
         self.is_error = is_error
@@ -190,9 +219,61 @@ class ToolInvocation:
 
 
 class BaseTool:
-    """Base class for tools with common functionality."""
+    """Base class for tools with common functionality.
+    
+    Tools can operate in two modes:
+    
+    1. Standard mode (default):
+       - Implement execute() method
+       - Tool runs to completion or raises HITLSuspend
+       - If HITLSuspend raised, user response becomes tool result
+    
+    2. Continuation mode:
+       - Set supports_continuation = True
+       - Implement execute_resumable() method
+       - Tool can pause mid-execution with HITLSuspend(resume_mode="continuation")
+       - When user responds, tool resumes from checkpoint
+       - Useful for OAuth, payment, multi-step wizards
+    
+    Emit support:
+        Tools can emit BlockEvents using self.emit(). The emitter is automatically
+        set when the tool is executed via the agent framework. If no emitter is
+        available (e.g., standalone testing), emit calls are silently skipped.
+        
+        Example:
+            async def execute(self, params, ctx):
+                await self.emit(BlockEvent(...))
+                return ToolResult.success("done")
+    
+    Example (continuation mode):
+        class OAuthTool(BaseTool):
+            _name = "oauth_connect"
+            supports_continuation = True
+            
+            async def execute_resumable(
+                self,
+                params: dict[str, Any],
+                ctx: ToolContext,
+                checkpoint: "ToolCheckpoint | None" = None,
+            ) -> ToolResult:
+                if checkpoint:
+                    # Resume from checkpoint
+                    token = checkpoint.user_response["access_token"]
+                    return await self._complete_oauth(token, params)
+                
+                # First execution - generate auth URL
+                auth_url = self._build_auth_url(params)
+                raise HITLSuspend(
+                    request_id=generate_id("hitl"),
+                    request_type="external_auth",
+                    resume_mode="continuation",
+                    tool_state={"step": "awaiting_callback"},
+                    metadata={"auth_url": auth_url, "callback_id": "..."},
+                )
+    """
     
     _name: str = "base_tool"
+    _display_name: str | None = None  # Optional display name for UI
     _description: str = "Base tool"
     _parameters: dict[str, Any] = {
         "type": "object",
@@ -201,10 +282,21 @@ class BaseTool:
     }
     _config: ToolConfig | None = None
     
+    # Continuation mode support
+    supports_continuation: bool = False
+    
+    # Runtime context (set during execution)
+    _ctx: ToolContext | None = None
+    
     @property
     def name(self) -> str:
         return self._name
     
+    @property
+    def display_name(self) -> str:
+        """Get display name for UI. Falls back to name if not set."""
+        return self._display_name or self._name
+    
     @property
     def description(self) -> str:
         return self._description
@@ -218,10 +310,92 @@ class BaseTool:
         """Get tool config. Returns default config if not set."""
         return self._config or ToolConfig()
     
+    @property
+    def ctx(self) -> ToolContext | None:
+        """Get current execution context."""
+        return self._ctx
+    
+    def _set_ctx(self, ctx: ToolContext | None) -> None:
+        """Set execution context. Called by framework before execute()."""
+        self._ctx = ctx
+    
+    async def emit(self, block: Any) -> None:
+        """Emit a BlockEvent.
+        
+        Uses the current ToolContext's emit function if available.
+        Silently skips if no context is set (e.g., standalone testing).
+        
+        Args:
+            block: BlockEvent to emit
+        """
+        if self._ctx is not None:
+            await self._ctx.emit(block)
+        # If no ctx, silently skip - allows standalone testing
+    
+    async def emit_hitl(self, hitl_id: str, data: dict[str, Any]) -> None:
+        """Emit a HITL block.
+        
+        Convenience method for tools that need user interaction.
+        Silently skips if no context is set.
+        
+        Args:
+            hitl_id: Unique ID for this HITL request
+            data: Arbitrary data dict for frontend to render.
+        """
+        if self._ctx is not None:
+            await self._ctx.emit_hitl(hitl_id, data)
+    
     async def execute(self, params: dict[str, Any], ctx: ToolContext) -> ToolResult:
-        """Override this method."""
+        """Execute tool (standard mode).
+        
+        Override this method for standard tools.
+        For continuation-capable tools, override execute_resumable() instead.
+        """
         raise NotImplementedError("Subclass must implement execute()")
     
+    async def execute_resumable(
+        self,
+        params: dict[str, Any],
+        ctx: ToolContext,
+        checkpoint: Any | None = None,  # ToolCheckpoint, use Any to avoid circular import
+    ) -> ToolResult:
+        """Execute tool with continuation support.
+        
+        Override this method for tools that need to pause mid-execution
+        and resume later (e.g., OAuth, payment, external callbacks).
+        
+        Args:
+            params: Tool parameters from LLM
+            ctx: Tool execution context
+            checkpoint: If resuming, contains saved state and user response.
+                       None on first execution.
+        
+        Returns:
+            ToolResult on completion
+            
+        Raises:
+            HITLSuspend: To pause and wait for user/callback.
+                        Set resume_mode="continuation" and provide tool_state.
+        
+        Example:
+            async def execute_resumable(self, params, ctx, checkpoint=None):
+                if checkpoint:
+                    # Resuming - use checkpoint.user_response
+                    return await self._continue(checkpoint)
+                
+                # First run - do initial work, then suspend
+                partial_result = await self._step_one(params)
+                raise HITLSuspend(
+                    request_id=generate_id("hitl"),
+                    resume_mode="continuation",
+                    tool_state={"partial": partial_result},
+                    ...
+                )
+        """
+        # Default: delegate to standard execute()
+        # Tools that support continuation should override this
+        return await self.execute(params, ctx)
+    
     def get_info(self) -> ToolInfo:
         """Get tool info."""
         return ToolInfo(
@@ -239,8 +413,10 @@ class ToolConfig:
     requires_permission: bool = False  # Needs HITL approval
     permission_message: str | None = None
     stream_arguments: bool = False  # Stream tool arguments to client
+    require_purpose: bool = False  # Generate purpose via middleware (async LLM call)
+    
     
     # Retry configuration
     max_retries: int = 0  # 0 = no retry
     retry_delay: float = 1.0  # Base delay between retries (seconds)
-    retry_backoff: float = 2.0  # Exponential backoff multiplier
+    retry_backoff: float = 2.0  # Exponential backoff multiplier

aury/agents/hitl/__init__.py

@@ -14,6 +14,7 @@ from .exceptions import (
     HITLTimeoutError,
     HITLCancelledError,
     HITLRequest,
+    ToolCheckpoint,
 )
 from .ask_user import (
     AskUserTool,
@@ -44,6 +45,7 @@ __all__ = [
     "HITLCancelledError",
     # Types
     "HITLRequest",
+    "ToolCheckpoint",
     # Tools
     "AskUserTool",
     "ConfirmTool",

aury/agents/hitl/ask_user.py

@@ -87,13 +87,13 @@ class AskUserTool(BaseTool):
         
         from ..core.logging import tool_logger as logger
         
-        # Generate request ID
-        request_id = generate_id("req")
+        # Generate HITL ID
+        hitl_id = generate_id("hitl")
         logger.info(
             "ask_user HITL request",
             extra={
                 "invocation_id": ctx.invocation_id,
-                "request_id": request_id,
+                "hitl_id": hitl_id,
                 "question": question[:100],
                 "has_options": options is not None,
             },
@@ -101,10 +101,9 @@ class AskUserTool(BaseTool):
         
         # Create HITL request data
         request = HITLRequest(
-            request_id=request_id,
-            request_type="ask_user",
-            message=question,
-            options=options,
+            hitl_id=hitl_id,
+            hitl_type="ask_user",
+            data={"message": question, "options": options},
             tool_name=self._name,
             metadata={"context": context} if context else {},
         )
@@ -121,18 +120,27 @@ class AskUserTool(BaseTool):
         if ctx.backends and ctx.backends.invocation:
             await ctx.backends.invocation.update(ctx.invocation_id, {
                 "status": "suspended",
-                "pending_request_id": request_id,
-                "pending_request_type": "ask_user",
-                "pending_request_data": request.to_dict(),
             })
         
-        # Emit HITL request block to frontend
+        # Store HITL record
+        if ctx.backends and ctx.backends.hitl:
+            await ctx.backends.hitl.create(
+                hitl_id=hitl_id,
+                hitl_type="ask_user",
+                session_id=ctx.session_id,
+                invocation_id=ctx.invocation_id,
+                data={"message": question, "options": options},
+                metadata={"context": context} if context else None,
+                tool_name=self._name,
+            )
+        
+        # Emit HITL block to frontend
         await ctx.emit(BlockEvent(
-            kind="hitl_request",
+            kind="hitl",
             data={
-                "request_id": request_id,
-                "type": "ask_user",
-                "question": question,
+                "hitl_id": hitl_id,
+                "hitl_type": "ask_user",
+                "message": question,
                 "options": options,
                 "context": context,
             },
@@ -143,14 +151,13 @@ class AskUserTool(BaseTool):
             "Suspending execution for HITL ask_user",
             extra={
                 "invocation_id": ctx.invocation_id,
-                "request_id": request_id,
+                "hitl_id": hitl_id,
             },
         )
         raise HITLSuspend(
-            request_id=request_id,
-            request_type="ask_user",
-            message=question,
-            options=options,
+            hitl_id=hitl_id,
+            hitl_type="ask_user",
+            data={"message": question, "options": options},
             tool_name=self._name,
             metadata={"context": context} if context else {},
         )
@@ -208,12 +215,12 @@ class ConfirmTool(BaseTool):
         
         from ..core.logging import tool_logger as logger
         
-        request_id = generate_id("req")
+        hitl_id = generate_id("hitl")
         logger.info(
             "confirm HITL request",
             extra={
                 "invocation_id": ctx.invocation_id,
-                "request_id": request_id,
+                "hitl_id": hitl_id,
                 "action": action[:100],
                 "risk_level": risk_level,
             },
@@ -223,17 +230,19 @@ class ConfirmTool(BaseTool):
         if details:
             message += f"\n\nDetails: {details}"
         
+        hitl_data = {
+            "message": message,
+            "options": ["Yes, proceed", "No, cancel"],
+            "action": action,
+            "details": details,
+            "risk_level": risk_level,
+        }
+        
         request = HITLRequest(
-            request_id=request_id,
-            request_type="confirm",
-            message=message,
-            options=["Yes, proceed", "No, cancel"],
+            hitl_id=hitl_id,
+            hitl_type="confirm",
+            data=hitl_data,
             tool_name=self._name,
-            metadata={
-                "action": action,
-                "details": details,
-                "risk_level": risk_level,
-            },
         )
         
         # Checkpoint
@@ -248,21 +257,26 @@ class ConfirmTool(BaseTool):
         if ctx.backends and ctx.backends.invocation:
             await ctx.backends.invocation.update(ctx.invocation_id, {
                 "status": "suspended",
-                "pending_request_id": request_id,
-                "pending_request_type": "confirm",
-                "pending_request_data": request.to_dict(),
             })
         
+        # Store HITL record
+        if ctx.backends and ctx.backends.hitl:
+            await ctx.backends.hitl.create(
+                hitl_id=hitl_id,
+                hitl_type="confirm",
+                session_id=ctx.session_id,
+                invocation_id=ctx.invocation_id,
+                data=hitl_data,
+                tool_name=self._name,
+            )
+        
         # Emit block
         await ctx.emit(BlockEvent(
-            kind="hitl_request",
+            kind="hitl",
             data={
-                "request_id": request_id,
-                "type": "confirm",
-                "action": action,
-                "details": details,
-                "risk_level": risk_level,
-                "options": ["Yes, proceed", "No, cancel"],
+                "hitl_id": hitl_id,
+                "hitl_type": "confirm",
+                **hitl_data,
             },
         ))
         
@@ -270,16 +284,14 @@ class ConfirmTool(BaseTool):
             "Suspending execution for confirm",
             extra={
                 "invocation_id": ctx.invocation_id,
-                "request_id": request_id,
+                "hitl_id": hitl_id,
             },
         )
         raise HITLSuspend(
-            request_id=request_id,
-            request_type="confirm",
-            message=message,
-            options=["Yes, proceed", "No, cancel"],
+            hitl_id=hitl_id,
+            hitl_type="confirm",
+            data=hitl_data,
             tool_name=self._name,
-            metadata=request.metadata,
         )