process-gpt-agent-sdk 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

{process_gpt_agent_sdk-0.1.5.dist-info → process_gpt_agent_sdk-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: process-gpt-agent-sdk
-Version: 0.1.5
+Version: 0.1.6
 Summary: Supabase 기반 이벤트/작업 폴링으로 A2A AgentExecutor를 실행하는 SDK
 License: MIT
 Project-URL: Homepage, https://github.com/your-org/process-gpt-agent-sdk

process_gpt_agent_sdk-0.1.6.dist-info/RECORD

@@ -0,0 +1,18 @@
+processgpt_agent_sdk/__init__.py,sha256=IvAL5WBZhI83LYQogRP6-i04bxZkhmkgmES4FRQY888,185
+processgpt_agent_sdk/server.py,sha256=MQMAnaFFik_1h9aaQdd8yTHf6uYbLA_SMVCJAWdqMYU,8922
+processgpt_agent_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+processgpt_agent_sdk/core/database.py,sha256=o5QEWoMdgliylFN-U7wlYd7Qng_GEnfzixRdhOZN_ZY,18790
+processgpt_agent_sdk/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+processgpt_agent_sdk/tools/human_query_tool.py,sha256=2HSs277Q_8Jn-dS6Hc-ABNvgsXw1Jn94R2GML97rjwU,10308
+processgpt_agent_sdk/tools/knowledge_tools.py,sha256=AOtxvLypu343877ZzzELGq3At-E_2NiAqEw0Njlephg,8937
+processgpt_agent_sdk/tools/safe_tool_loader.py,sha256=7WSR6tMxPdNodY4z-BRAO6hH6zTniY_qM5VlQIdqqjM,6132
+processgpt_agent_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+processgpt_agent_sdk/utils/context_manager.py,sha256=QDL5ya4FfUPx4EKScSVIllJGKS1-zctYvxg2FZB2b0A,1383
+processgpt_agent_sdk/utils/crewai_event_listener.py,sha256=343btAePWM19KbjDwElYb9K3FIbVm80_ZLLdOyFSsj4,8815
+processgpt_agent_sdk/utils/event_handler.py,sha256=ogmKcfhD2PHVQCQHpjVevZOe6LThwKIsrJcWFYqGlPA,2337
+processgpt_agent_sdk/utils/logger.py,sha256=2hX1GClkrE3ZVzvV61ORlZg4QDh59g-lr3qJyIRAfD4,948
+processgpt_agent_sdk/utils/summarizer.py,sha256=XV7e4pyKEK7NiGK_PAc1xorKSO2MKlSHCAiV7slOdus,4527
+process_gpt_agent_sdk-0.1.6.dist-info/METADATA,sha256=oYK0zEBzxwle5ko8csSwsi9LwfhcooF-SN7HPXIzndI,12898
+process_gpt_agent_sdk-0.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+process_gpt_agent_sdk-0.1.6.dist-info/top_level.txt,sha256=Xe6zrj3_3Vv7d0pl5RRtenVUckwOVBVLQn2P03j5REo,21
+process_gpt_agent_sdk-0.1.6.dist-info/RECORD,,

processgpt_agent_sdk/core/database.py

@@ -27,7 +27,7 @@ from typing import Callable, TypeVar
 
 T = TypeVar("T")
 
-from ..utils.logger import handle_error as _emit_error, log as _emit_log
+from ..utils.logger import handle_application_error as _emit_error, write_log_message as _emit_log
 
 
 async def _async_retry(
@@ -370,4 +370,139 @@ async def update_task_error(todo_id: str) -> None:
             .execute()
         )
 
-    await _async_retry(_call, name="update_task_error", fallback=lambda: None)
+    await _async_retry(_call, name="update_task_error", fallback=lambda: None)
+
+
+# ============================================================================
+# 알림 저장
+# ============================================================================
+
+def save_notification(
+    *,
+    title: str,
+    notif_type: str,
+    description: Optional[str] = None,
+    user_ids_csv: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    url: Optional[str] = None,
+    from_user_id: Optional[str] = None,
+) -> None:
+    """notifications 테이블에 알림 저장
+
+    - user_ids_csv: 쉼표로 구분된 사용자 ID 목록. 비어있으면 저장 생략
+    - 테이블 스키마는 다음 컬럼을 가정: user_id, tenant_id, title, description, type, url, from_user_id
+    """
+    try:
+        # 대상 사용자가 없으면 작업 생략
+        if not user_ids_csv:
+            _emit_log(f"알림 저장 생략: 대상 사용자 없음 (user_ids_csv={user_ids_csv})")
+            return
+
+        supabase = get_db_client()
+
+        user_ids: List[str] = [uid.strip() for uid in user_ids_csv.split(',') if uid and uid.strip()]
+        if not user_ids:
+            _emit_log(f"알림 저장 생략: 유효한 사용자 ID 없음 (user_ids_csv={user_ids_csv})")
+            return
+        
+        rows: List[Dict[str, Any]] = []
+        for uid in user_ids:
+            rows.append(
+                {
+                    "id": str(uuid.uuid4()),  # UUID 자동 생성
+                    "user_id": uid,
+                    "tenant_id": tenant_id,
+                    "title": title,
+                    "description": description,
+                    "type": notif_type,
+                    "url": url,
+                    "from_user_id": from_user_id,
+                }
+            )
+
+        supabase.table("notifications").insert(rows).execute()
+        _emit_log(f"알림 저장 완료: {len(rows)}건")
+    except Exception as e:
+        # 알림 저장 실패는 치명적이지 않으므로 오류만 로깅
+        _emit_error("알림저장오류", e, raise_error=False)
+
+
+def _is_valid_uuid(value: str) -> bool:
+    """UUID 문자열 형식 검증 (v1~v8 포함)"""
+    try:
+        uuid.UUID(value)
+        return True
+    except Exception:
+        return False
+
+       
+# ============================================================================
+# 사용자 및 에이전트 정보 조회
+# ============================================================================
+
+async def fetch_human_users_by_proc_inst_id(proc_inst_id: str) -> str:
+    """proc_inst_id로 해당 프로세스의 실제 사용자(is_agent=false)들의 이메일만 쉼표로 구분하여 반환"""
+    if not proc_inst_id:
+        return ""
+    
+    def _sync():
+        try:
+            supabase = get_db_client()
+            
+            # 1. proc_inst_id로 todolist에서 user_id들 조회
+            resp = (
+                supabase
+                .table('todolist')
+                .select('user_id')
+                .eq('proc_inst_id', proc_inst_id)
+                .execute()
+            )
+            
+            if not resp.data:
+                return ""
+            
+            # 2. 모든 user_id를 수집 (중복 제거)
+            all_user_ids = set()
+            for row in resp.data:
+                user_id = row.get('user_id', '')
+                if user_id:
+                    # 쉼표로 구분된 경우 분리
+                    ids = [id.strip() for id in user_id.split(',') if id.strip()]
+                    all_user_ids.update(ids)
+            
+            if not all_user_ids:
+                return ""
+            
+            # 3. 각 user_id가 실제 사용자(is_agent=false 또는 null)인지 확인 후 이메일 수집
+            human_user_emails = []
+            for user_id in all_user_ids:
+                # UUID 형식이 아니면 스킵
+                if not _is_valid_uuid(user_id):
+                    continue
+                
+                # users 테이블에서 해당 user_id 조회
+                user_resp = (
+                    supabase
+                    .table('users')
+                    .select('id, email, is_agent')
+                    .eq('id', user_id)
+                    .execute()
+                )
+                
+                if user_resp.data:
+                    user = user_resp.data[0]
+                    is_agent = user.get('is_agent')
+                    # is_agent가 false이거나 null인 경우만 실제 사용자로 간주
+                    if not is_agent:  # False 또는 None
+                        email = (user.get('email') or '').strip()
+                        if email:
+                            human_user_emails.append(email)
+            
+            # 4. 쉼표로 구분된 문자열로 반환
+            return ','.join(human_user_emails)
+            
+        except Exception as e:
+            _emit_error("사용자조회오류", e, raise_error=False)
+            return ""
+    
+    return await asyncio.to_thread(_sync)

processgpt_agent_sdk/server.py

@@ -5,6 +5,7 @@ from a2a.server.agent_execution import AgentExecutor, RequestContext
 from a2a.server.events import EventQueue, Event
 
 from .core.database import (
+	fetch_human_users_by_proc_inst_id,
 	initialize_db,
 	get_consumer_id,
 	polling_pending_todos,
@@ -13,12 +14,12 @@ from .core.database import (
 	fetch_form_types,
 	fetch_task_status,
 	fetch_tenant_mcp_config,
-    update_task_error,
+	update_task_error,
 )
 
-from .utils.logger import handle_error as _emit_error, log as _emit_log
+from .utils.logger import handle_application_error, write_log_message
 from .utils.summarizer import summarize_async
-from .utils.event_handler import route_event
+from .utils.event_handler import process_event_message
 from .utils.context_manager import set_context, reset_context
 
 
@@ -39,100 +40,106 @@ class ProcessGPTAgentServer:
 
 	async def run(self) -> None:
 		self.is_running = True
-		_emit_log("ProcessGPT 서버 시작")
+		write_log_message("ProcessGPT 서버 시작")
 		
 		while self.is_running:
 			try:
-				todo = await polling_pending_todos(self.agent_orch, get_consumer_id())
-				if not todo:
+				task_record = await polling_pending_todos(self.agent_orch, get_consumer_id())
+				if not task_record:
 					await asyncio.sleep(self.polling_interval)
 					continue
 
-				todo_id = todo["id"]
-				_emit_log(f"[JOB START] todo_id={todo_id}")
+				task_id = task_record["id"]
+				write_log_message(f"[JOB START] task_id={task_id}")
 
 				try:
-					prepared_data = await self._prepare_service_data(todo)
-					_emit_log(f"[RUN] 서비스 데이터 준비 완료 [todo_id={todo_id} agent={prepared_data.get('agent_orch','')}]")
+					prepared_data = await self._prepare_service_data(task_record)
+					write_log_message(f"[RUN] 서비스 데이터 준비 완료 [task_id={task_id} agent={prepared_data.get('agent_orch','')}]")
 
-					await self._execute_with_cancel_watch(todo, prepared_data)
-					_emit_log(f"[RUN] 서비스 실행 완료 [todo_id={todo_id} agent={prepared_data.get('agent_orch','')}]")
+					await self._execute_with_cancel_watch(task_record, prepared_data)
+					write_log_message(f"[RUN] 서비스 실행 완료 [task_id={task_id} agent={prepared_data.get('agent_orch','')}]")
 				except Exception as job_err:
-					_emit_error("작업 처리 오류", job_err, raise_error=False)
+					handle_application_error("작업 처리 오류", job_err, raise_error=False)
 					try:
-						await update_task_error(str(todo_id))
+						await update_task_error(str(task_id))
 					except Exception as upd_err:
-						_emit_error("FAILED 상태 업데이트 실패", upd_err, raise_error=False)
+						handle_application_error("FAILED 상태 업데이트 실패", upd_err, raise_error=False)
 					# 다음 루프로 진행
 					continue
 				
 			except Exception as e:
-				_emit_error("폴링 루프 오류", e, raise_error=False)
+				handle_application_error("폴링 루프 오류", e, raise_error=False)
 				await asyncio.sleep(self.polling_interval)
 
 	def stop(self) -> None:
 		self.is_running = False
-		_emit_log("ProcessGPT 서버 중지")
+		write_log_message("ProcessGPT 서버 중지")
 
-	async def _prepare_service_data(self, todo: Dict[str, Any]) -> Dict[str, Any]:
-		done_outputs = await fetch_done_data(todo.get("proc_inst_id"))
-		_emit_log(f"[PREP] done_outputs → {done_outputs}")
-		feedbacks = todo.get("feedback")
+	async def _prepare_service_data(self, task_record: Dict[str, Any]) -> Dict[str, Any]:
+		done_outputs = await fetch_done_data(task_record.get("proc_inst_id"))
+		write_log_message(f"[PREP] done_outputs → {done_outputs}")
+		feedbacks = task_record.get("feedback")
 
-		agent_list = await fetch_agent_data(str(todo.get("user_id", "")))
-		_emit_log(f"[PREP] agent_list → {agent_list}")
+		agent_list = await fetch_agent_data(str(task_record.get("user_id", "")))
+		write_log_message(f"[PREP] agent_list → {agent_list}")
 
-		mcp_config = await fetch_tenant_mcp_config(str(todo.get("tenant_id", "")))
-		_emit_log(f"[PREP] mcp_config(툴) → {mcp_config}")
+		mcp_config = await fetch_tenant_mcp_config(str(task_record.get("tenant_id", "")))
+		write_log_message(f"[PREP] mcp_config(툴) → {mcp_config}")
 
 		form_id, form_types = await fetch_form_types(
-			str(todo.get("tool", "")),
-			str(todo.get("tenant_id", ""))
+			str(task_record.get("tool", "")),
+			str(task_record.get("tenant_id", ""))
 		)
-		_emit_log(f"[PREP] form → id={form_id} types={form_types}")
+		write_log_message(f"[PREP] form → id={form_id} types={form_types}")
 
 		output_summary, feedback_summary = await summarize_async(
-			done_outputs or [], feedbacks or "", todo.get("description", "")
+			done_outputs or [], feedbacks or "", task_record.get("description", "")
 		)
-		_emit_log(f"[PREP] summary → output={output_summary} feedback={feedback_summary}")
+		write_log_message(f"[PREP] summary → output={output_summary} feedback={feedback_summary}")
+
+
+		all_users = await fetch_human_users_by_proc_inst_id(task_record.get("proc_inst_id"))
+		write_log_message(f"[PREP] all_users → {all_users}")
 
 		prepared: Dict[str, Any] = {
-			"todo_id": str(todo.get("id")),
-			"proc_inst_id": todo.get("proc_inst_id"),
+			"task_id": str(task_record.get("id")),
+			"proc_inst_id": task_record.get("proc_inst_id"),
 			"agent_list": agent_list or [],
 			"mcp_config": mcp_config,
 			"form_id": form_id,
 			"form_types": form_types or [],
-			"activity_name": str(todo.get("activity_name", "")),
-			"message": str(todo.get("description", "")),
-			"agent_orch": str(todo.get("agent_orch", "")),
+			"activity_name": str(task_record.get("activity_name", "")),
+			"message": str(task_record.get("description", "")),
+			"agent_orch": str(task_record.get("agent_orch", "")),
 			"done_outputs": done_outputs or [],
 			"output_summary": output_summary or "",
 			"feedback_summary": feedback_summary or "",
+			"all_users": all_users or "",
 		}
 
 		return prepared
 
-	async def _execute_with_cancel_watch(self, todo: Dict[str, Any], prepared_data: Dict[str, Any]) -> None:
+	async def _execute_with_cancel_watch(self, task_record: Dict[str, Any], prepared_data: Dict[str, Any]) -> None:
 		executor = self._executor
 
 		context = ProcessGPTRequestContext(prepared_data)
-		event_queue = ProcessGPTEventQueue(todo)
+		event_queue = ProcessGPTEventQueue(task_record)
 
 		# 실행 전 컨텍스트 변수 설정 (CrewAI 전역 리스너 등에서 활용)
 		try:
 			set_context(
-				todo_id=str(todo.get("id")),
-				proc_inst_id=str(todo.get("proc_inst_id") or ""),
+				todo_id=str(task_record.get("id")),
+				proc_inst_id=str(task_record.get("proc_inst_id") or ""),
 				crew_type=str(prepared_data.get("agent_orch") or ""),
 				form_id=str(prepared_data.get("form_id") or ""),
+				all_users=str(prepared_data.get("all_users") or ""),
 			)
 		except Exception as e:
-			_emit_error("컨텍스트 설정 실패", e, raise_error=False)
+			handle_application_error("컨텍스트 설정 실패", e, raise_error=False)
 
-		_emit_log(f"[EXEC START] todo_id={todo.get('id')} agent={prepared_data.get('agent_orch','')}")
+		write_log_message(f"[EXEC START] task_id={task_record.get('id')} agent={prepared_data.get('agent_orch','')}")
 		execute_task = asyncio.create_task(executor.execute(context, event_queue))
-		cancel_watch_task = asyncio.create_task(self._watch_cancellation(todo, executor, context, event_queue, execute_task))
+		cancel_watch_task = asyncio.create_task(self._watch_cancellation(task_record, executor, context, event_queue, execute_task))
 		
 		try:
 			done, pending = await asyncio.wait(
@@ -143,7 +150,7 @@ class ProcessGPTAgentServer:
 				task.cancel()
 				
 		except Exception as e:
-			_emit_error("서비스 실행 오류", e, raise_error=False)
+			handle_application_error("서비스 실행 오류", e, raise_error=False)
 			cancel_watch_task.cancel()
 			execute_task.cancel()
 		finally:
@@ -151,15 +158,15 @@ class ProcessGPTAgentServer:
 			try:
 				reset_context()
 			except Exception as e:
-				_emit_error("컨텍스트 리셋 실패", e, raise_error=False)
+				handle_application_error("컨텍스트 리셋 실패", e, raise_error=False)
 			try:
 				await event_queue.close()
 			except Exception as e:
-				_emit_error("이벤트 큐 종료 실패", e, raise_error=False)
-			_emit_log(f"[EXEC END] todo_id={todo.get('id')} agent={prepared_data.get('agent_orch','')}")
+				handle_application_error("이벤트 큐 종료 실패", e, raise_error=False)
+			write_log_message(f"[EXEC END] task_id={task_record.get('id')} agent={prepared_data.get('agent_orch','')}")
 
-	async def _watch_cancellation(self, todo: Dict[str, Any], executor: AgentExecutor, context: RequestContext, event_queue: EventQueue, execute_task: asyncio.Task) -> None:
-		todo_id = str(todo.get("id"))
+	async def _watch_cancellation(self, task_record: Dict[str, Any], executor: AgentExecutor, context: RequestContext, event_queue: EventQueue, execute_task: asyncio.Task) -> None:
+		todo_id = str(task_record.get("id"))
 		
 		while True:
 			await asyncio.sleep(self.cancel_check_interval)
@@ -167,21 +174,21 @@ class ProcessGPTAgentServer:
 			status = await fetch_task_status(todo_id)
 			normalized = (status or "").strip().lower()
 			if normalized in ("cancelled", "fb_requested"):
-				_emit_log(f"작업 취소 감지: {todo_id}, 상태: {status}")
+				write_log_message(f"작업 취소 감지: {todo_id}, 상태: {status}")
 				
 				try:
 					await executor.cancel(context, event_queue)
 				except Exception as e:
-					_emit_error("취소 처리 실패", e, raise_error=False)
+					handle_application_error("취소 처리 실패", e, raise_error=False)
 				finally:
 					try:
 						execute_task.cancel()
 					except Exception as e:
-						_emit_error("실행 태스크 즉시 취소 실패", e, raise_error=False)
+						handle_application_error("실행 태스크 즉시 취소 실패", e, raise_error=False)
 					try:
 						await event_queue.close()
 					except Exception as e:
-						_emit_error("취소 후 이벤트 큐 종료 실패", e, raise_error=False)
+						handle_application_error("취소 후 이벤트 큐 종료 실패", e, raise_error=False)
 				break
 
 
@@ -207,8 +214,8 @@ class ProcessGPTRequestContext(RequestContext):
 
 
 class ProcessGPTEventQueue(EventQueue):
-	def __init__(self, todo: Dict[str, Any]):
-		self.todo = todo
+	def __init__(self, task_record: Dict[str, Any]):
+		self.todo = task_record
 		super().__init__()
 
 	def enqueue_event(self, event: Event):
@@ -216,17 +223,17 @@ class ProcessGPTEventQueue(EventQueue):
 			try:
 				super().enqueue_event(event)
 			except Exception as e:
-				_emit_error("이벤트 큐 삽입 실패", e, raise_error=False)
+				handle_application_error("이벤트 큐 삽입 실패", e, raise_error=False)
 
-			self._create_bg_task(route_event(self.todo, event), "route_event")
+			self._create_bg_task(process_event_message(self.todo, event), "process_event_message")
 		except Exception as e:
-			_emit_error("이벤트 저장 실패", e, raise_error=False)
+			handle_application_error("이벤트 저장 실패", e, raise_error=False)
 		
 	def task_done(self) -> None:
 		try:
-			_emit_log(f"태스크 완료: {self.todo['id']}")
+			write_log_message(f"태스크 완료: {self.todo['id']}")
 		except Exception as e:
-			_emit_error("태스크 완료 처리 실패", e, raise_error=False)
+			handle_application_error("태스크 완료 처리 실패", e, raise_error=False)
 
 	async def close(self) -> None:
 		pass
@@ -237,7 +244,7 @@ class ProcessGPTEventQueue(EventQueue):
 			def _cb(t: asyncio.Task):
 				exc = t.exception()
 				if exc:
-					_emit_error(f"백그라운드 태스크 오류({label})", exc, raise_error=False)
+					handle_application_error(f"백그라운드 태스크 오류({label})", exc, raise_error=False)
 			task.add_done_callback(_cb)
 		except Exception as e:
-			_emit_error(f"백그라운드 태스크 생성 실패({label})", e, raise_error=False)
+			handle_application_error(f"백그라운드 태스크 생성 실패({label})", e, raise_error=False)

processgpt_agent_sdk/tools/human_query_tool.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import time
+import uuid
+import os
+from typing import Optional, List, Literal, Type, Dict, Any
+
+from pydantic import BaseModel, Field
+from crewai.tools import BaseTool
+
+from ..utils.crewai_event_listener import CrewAIEventLogger
+from ..utils.context_manager import todo_id_var, proc_id_var
+from ..utils.logger import write_log_message, handle_application_error
+from ..core.database import fetch_human_response, save_notification
+
+
+class HumanQuerySchema(BaseModel):
+    """사용자 확인/추가정보 요청용 스키마"""
+
+    role: str = Field(..., description="누구에게(역할 또는 대상)")
+    text: str = Field(..., description="질의 내용")
+    type: Literal["text", "select", "confirm"] = Field(
+        default="text", description="질의 유형: 자유 텍스트, 선택형, 확인 여부"
+    )
+    options: Optional[List[str]] = Field(
+        default=None, description="type이 select일 때 선택지 목록"
+    )
+
+
+class HumanQueryTool(BaseTool):
+    """사람에게 보안/모호성 관련 확인을 요청하고 응답을 대기하는 도구"""
+
+    name: str = "human_asked"
+    description: str = (
+        "👀 질문은 반드시 '매우 구체적이고 세부적'으로 작성해야 합니다.\n"
+        "- 목적, 대상, 범위/경계, 입력/출력 형식, 성공/실패 기준, 제약조건(보안/권한/시간/용량),\n"
+        "  필요한 식별자/예시/반례까지 모두 명시하세요. 추측으로 진행하지 말고 누락 정보를 반드시 질문하세요.\n\n"
+        "[1] 언제 사용해야 하나\n"
+        "1. 보안에 민감한 정보(개인정보/인증정보/비밀키 등)를 다루거나 외부로 전송할 때\n"
+        "2. 데이터베이스에 '저장/수정/삭제' 작업을 수행할 때 (읽기 전용 조회는 제외)\n"
+        "3. 요구사항 및 작업지시사항이 모호·불완전·추정에 의존하거나, 전제조건/매개변수가 불명확할 때\n"
+        "4. 외부 시스템 연동, 파일 생성/이동/삭제 등 시스템 상태를 바꾸는 작업일 때\n"
+        "⛔ 위 조건에 해당하면 이 도구 없이 진행 금지\n\n"
+        "[2] 응답 타입과 작성 방식 (항상 JSON으로 질의 전송)\n"
+        "- 공통 형식: { role: <누구에게>, text: <질의>, type: <text|select|confirm>, options?: [선택지...] }\n"
+        "- 질의 작성 가이드(반드시 포함): 5W1H, 목적/맥락, 선택 이유 또는 승인 근거, 기본값/제약,\n"
+        "  입력/출력 형식과 예시, 반례/실패 시 처리, 보안/권한/감사 로그 요구사항, 마감/우선순위\n\n"
+        "// 1) type='text' — 정보 수집(모호/불완전할 때 필수)\n"
+        "{\n"
+        '  "role": "user",\n'
+        '  "text": "어떤 DB 테이블/스키마/키로 저장할까요? 입력값 예시/형식, 실패 시 처리, 보존 기간까지 구체히 알려주세요.",\n'
+        '  "type": "text"\n'
+        "}\n\n"
+        "// 2) type='select' — 여러 옵션 중 선택(옵션은 상호배타적, 명확/완전하게 제시)\n"
+        "{\n"
+        '  "role": "system",\n'
+        '  "text": "배포 환경을 선택하세요. 선택 근거(위험/롤백/감사 로그)를 함께 알려주세요.",\n'
+        '  "type": "select",\n'
+        '  "options": ["dev", "staging", "prod"]\n'
+        "}\n\n"  
+        "// 3) type='confirm' — 보안/DB 변경 등 민감 작업 승인(필수)\n"
+        "{\n"
+        '  "role": "user",\n'
+        '  "text": "DB에서 주문 상태를 shipped로 업데이트합니다. 대상: order_id=..., 영향 범위: ...건, 롤백: ..., 진행 승인하시겠습니까?",\n'
+        '  "type": "confirm"\n'
+        "}\n\n"
+        "타입 선택 규칙\n"
+        "- text: 모호/누락 정보가 있을 때 먼저 세부사항을 수집 (여러 번 질문 가능)\n"
+        "- select: 옵션이 둘 이상이면 반드시 options로 제시하고, 선택 기준을 text에 명시\n"
+        "- confirm: DB 저장/수정/삭제, 외부 전송, 파일 조작 등은 승인 후에만 진행\n\n"
+        "[3] 주의사항\n"
+        "- 이 도구 없이 민감/변경 작업을 임의로 진행 금지.\n"
+        "- select 타입은 반드시 'options'를 포함.\n"
+        "- confirm 응답에 따라: ✅ 승인 → 즉시 수행 / ❌ 거절 → 즉시 중단(건너뛰기).\n"
+        "- 애매하면 추가 질문을 반복하고, 충분히 구체화되기 전에는 실행하지 말 것.\n"
+        "- 민감 정보는 최소한만 노출하고 필요 시 마스킹/요약.\n"
+        "- 예시를 그대로 사용하지 말고 컨텍스트에 맞게 반드시 자연스러운 질의를 재작성하세요.\n"
+        "- 타임아웃/미응답 시 '사용자 미응답 거절'을 반환하며, 후속 변경 작업을 중단하는 것이 안전.\n"
+        "- 한 번에 하나의 주제만 질문(여러 주제면 질문을 분리). 한국어 존댓말 사용, 간결하되 상세하게."
+    )
+    args_schema: Type[HumanQuerySchema] = HumanQuerySchema
+
+    # 선택적 컨텍스트(없어도 동작). ContextVar가 우선 사용됨
+    _tenant_id: Optional[str] = None
+    _user_id: Optional[str] = None
+    _todo_id: Optional[int] = None
+    _proc_inst_id: Optional[str] = None
+
+    def __init__(
+        self,
+        tenant_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        todo_id: Optional[int] = None,
+        proc_inst_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self._tenant_id = tenant_id
+        self._user_id = user_id
+        self._todo_id = todo_id
+        self._proc_inst_id = proc_inst_id
+        self._agent_name = agent_name
+
+    # 동기 실행: CrewAI Tool 실행 컨텍스트에서 블로킹 폴링 허용
+    def _run(
+        self, role: str, text: str, type: str = "text", options: Optional[List[str]] = None
+    ) -> str:
+        try:
+            # 초기화된 기본 agent_name 사용
+            agent_name = getattr(self, "_agent_name", None)
+                
+            write_log_message(f"HumanQueryTool 실행: role={role}, agent_name={agent_name}, type={type}, options={options}")
+            query_id = f"human_asked_{uuid.uuid4()}"
+
+            # 이벤트 발행 데이터
+            payload: Dict[str, Any] = {
+                "role": role,
+                "text": text,
+                "type": type,
+                "options": options or [],
+            }
+
+            # 컨텍스트 식별자
+            todo_id = todo_id_var.get() or self._todo_id
+            proc_inst_id = proc_id_var.get() or self._proc_inst_id
+
+            # 이벤트 발행
+            # 상태 정보는 data 안에 포함시켜 저장 (emit_event 시그니처에 status 없음)
+            payload_with_status = {
+                **payload,
+                "status": "ASKED",
+                "agent_profile": "/images/chat-icon.png"
+            }
+            ev = CrewAIEventLogger()
+            ev.emit_event(
+                event_type="human_asked",
+                data=payload_with_status,
+                job_id=query_id,
+                crew_type="action",
+                todo_id=str(todo_id) if todo_id is not None else None,
+                proc_inst_id=str(proc_inst_id) if proc_inst_id is not None else None,
+            )
+
+            # 알림 저장 (notifications 테이블)
+            try:
+                tenant_id = self._tenant_id
+                # 대상 이메일: context var(all_users_var)에 이메일 CSV가 있어야만 저장
+                target_emails_csv = os.getenv("HUMAN_USERS_CSV") or ""
+                if target_emails_csv and target_emails_csv.strip():
+                    write_log_message(f"알림 저장 시도: target_emails_csv={target_emails_csv}, tenant_id={tenant_id}")
+                    save_notification(
+                        title=text,
+                        notif_type="workitem_bpm",
+                        description=agent_name,
+                        user_ids_csv=target_emails_csv,
+                        tenant_id=tenant_id,
+                        url=f"/todolist/{todo_id}",
+                        from_user_id=agent_name,
+                    )
+                else:
+                    write_log_message("알림 저장 생략: 대상 이메일 없음")
+            except Exception as e:
+                handle_application_error("알림저장HumanTool", e, raise_error=False)
+
+            # 응답 폴링 (events 테이블에서 동일 job_id, event_type=human_response)
+            answer = self._wait_for_response(query_id)
+            return answer
+        except Exception as e:
+            # 사용자 미응답 또는 기타 에러 시에도 작업이 즉시 중단되지 않도록 문자열 반환
+            handle_application_error("HumanQueryTool", e, raise_error=False)
+            return "사용자 미응답 거절"
+
+    def _wait_for_response(
+        self, job_id: str, timeout_sec: int = 180, poll_interval_sec: int = 5
+    ) -> str:
+        """DB events 테이블을 폴링하여 사람의 응답을 기다림"""
+        deadline = time.time() + timeout_sec
+
+        while time.time() < deadline:
+            try:
+                write_log_message(f"HumanQueryTool 응답 폴링: {job_id}")
+                event = fetch_human_response(job_id=job_id)
+                if event:
+                    write_log_message(f"HumanQueryTool 응답 수신: {event}")
+                    data = event.get("data") or {}
+                    # 기대 형식: {"answer": str, ...}
+                    answer = (data or {}).get("answer")
+                    if isinstance(answer, str):
+                        write_log_message("사람 응답 수신 완료")
+                        return answer
+                    # 문자열이 아니면 직렬화하여 반환
+                    return str(data)
+
+            except Exception as e:
+                # 응답이 아직 없는 경우(0개 행) 또는 기타 DB 오류 시 계속 폴링
+                write_log_message(f"인간 응답 대기 중... (오류: {str(e)[:100]})")
+
+            time.sleep(poll_interval_sec)
+
+        # 타임아웃: 사용자 미응답으로 간주
+        return "사용자 미응답 거절"
+