process-gpt-agent-sdk 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

processgpt_agent_sdk/simulator.py

@@ -0,0 +1,231 @@
+import asyncio
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+import sys
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue, Event
+
+from .utils.logger import handle_application_error, write_log_message
+
+
+# =============================================================================
+# 시뮬레이터: ProcessGPTAgentSimulator
+# 설명: 데이터베이스 연결 없이 작업을 시뮬레이션하는 핵심 시뮬레이터
+# =============================================================================
+class ProcessGPTAgentSimulator:
+    """ProcessGPT 시뮬레이터
+    
+    - 데이터베이스 연결 없이 에이전트 실행을 시뮬레이션
+    - CLI로 프롬프트를 받아 실행하고 진행상태를 stdout으로 출력
+    """
+
+    def __init__(self, executor: AgentExecutor, agent_orch: str = ""):
+        """시뮬레이터 실행기/오케스트레이션 값을 초기화한다."""
+        self.is_running = False
+        self._executor: AgentExecutor = executor
+        self.agent_orch: str = agent_orch or "simulator"
+        self.task_id = str(uuid.uuid4())
+        self.proc_inst_id = str(uuid.uuid4())
+
+    async def run_simulation(self, prompt: str, **kwargs) -> None:
+        """단일 작업을 시뮬레이션한다."""
+        self.is_running = True
+        write_log_message("ProcessGPT 시뮬레이터 시작")
+        write_log_message(f"작업 시뮬레이션 시작: {self.task_id}")
+        
+        try:
+            # 시뮬레이션용 작업 레코드 생성
+            task_record = self._create_mock_task_record(prompt, **kwargs)
+            
+            # 서비스 데이터 준비 (모든 것을 모킹)
+            prepared_data = self._prepare_mock_service_data(task_record)
+            write_log_message(f"시뮬레이션 데이터 준비 완료 [task_id={self.task_id} agent={prepared_data.get('agent_orch','')}]")
+
+            # 실행
+            await self._execute_simulation(task_record, prepared_data)
+            write_log_message(f"시뮬레이션 실행 완료 [task_id={self.task_id}]")
+            
+        except Exception as e:
+            handle_application_error("시뮬레이션 처리 오류", e, raise_error=False)
+        finally:
+            self.is_running = False
+            write_log_message("ProcessGPT 시뮬레이터 종료")
+
+    def _create_mock_task_record(self, prompt: str, **kwargs) -> Dict[str, Any]:
+        """시뮬레이션용 작업 레코드를 생성한다."""
+        return {
+            "id": self.task_id,
+            "proc_inst_id": self.proc_inst_id,
+            "agent_orch": self.agent_orch,
+            "description": prompt,
+            "activity_name": kwargs.get("activity_name", "simulation_task"),
+            "user_id": kwargs.get("user_id", str(uuid.uuid4())),
+            "tenant_id": kwargs.get("tenant_id", str(uuid.uuid4())),
+            "tool": kwargs.get("tool", "default"),
+            "feedback": kwargs.get("feedback", ""),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def _prepare_mock_service_data(self, task_record: Dict[str, Any]) -> Dict[str, Any]:
+        """시뮬레이션용 서비스 데이터를 준비한다."""
+        # 모킹된 에이전트 데이터
+        mock_agents = [
+            {
+                "id": str(uuid.uuid4()),
+                "name": "simulation_agent",
+                "role": "AI Assistant",
+                "goal": "Simulate task execution",
+                "persona": "A helpful AI assistant for simulation",
+                "tools": "mem0",
+                "profile": "Simulation Agent",
+                "model": "gpt-4",
+                "tenant_id": task_record.get("tenant_id"),
+            }
+        ]
+
+        # 모킹된 폼 데이터
+        mock_form_types = [
+            {"key": "default", "type": "text", "text": "Default form field"}
+        ]
+
+        # 모킹된 MCP 설정
+        mock_mcp_config = {
+            "enabled": True,
+            "tools": ["mem0", "search"],
+            "config": {}
+        }
+
+        prepared: Dict[str, Any] = {
+            "task_id": str(task_record.get("id")),
+            "proc_inst_id": task_record.get("proc_inst_id"),
+            "agent_list": mock_agents,
+            "mcp_config": mock_mcp_config,
+            "form_id": "default",
+            "form_types": mock_form_types,
+            "form_html": "<form>Default simulation form</form>",
+            "activity_name": str(task_record.get("activity_name", "")),
+            "message": str(task_record.get("description", "")),
+            "agent_orch": str(task_record.get("agent_orch", "")),
+            "done_outputs": [],
+            "output_summary": "",
+            "feedback_summary": "",
+            "all_users": "simulation@example.com",
+        }
+
+        return prepared
+
+    async def _execute_simulation(self, task_record: Dict[str, Any], prepared_data: Dict[str, Any]) -> None:
+        """시뮬레이션 실행을 수행한다."""
+        executor = self._executor
+
+        context = SimulatorRequestContext(prepared_data)
+        event_queue = SimulatorEventQueue(task_record)
+
+        write_log_message(f"시뮬레이션 실행 시작 [task_id={task_record.get('id')} agent={prepared_data.get('agent_orch','')}]")
+        
+        try:
+            await executor.execute(context, event_queue)
+        except Exception as e:
+            handle_application_error("시뮬레이터 실행 오류", e, raise_error=False)
+        finally:
+            try:
+                await event_queue.close()
+            except Exception as e:
+                handle_application_error("시뮬레이터 이벤트 큐 종료 실패", e, raise_error=False)
+            write_log_message(f"시뮬레이션 실행 종료 [task_id={task_record.get('id')}]")
+
+
+# =============================================================================
+# 시뮬레이터 요청 컨텍스트: SimulatorRequestContext
+# 설명: 시뮬레이터용 요청 데이터/상태를 캡슐화
+# =============================================================================
+class SimulatorRequestContext(RequestContext):
+    def __init__(self, prepared_data: Dict[str, Any]):
+        """시뮬레이션 실행에 필요한 데이터 묶음을 보관한다."""
+        self._prepared_data = prepared_data
+        self._message = prepared_data.get("message", "")
+        self._current_task = None
+
+    def get_user_input(self) -> str:
+        """사용자 입력 메시지를 반환한다."""
+        return self._message
+
+    @property
+    def message(self) -> str:
+        """현재 메시지(사용자 입력)를 반환한다."""
+        return self._message
+
+    @property
+    def current_task(self):
+        """현재 실행 중 태스크(있다면)를 반환한다."""
+        return getattr(self, "_current_task", None)
+
+    def get_context_data(self) -> Dict[str, Any]:
+        """실행 컨텍스트 전체 데이터를 dict로 반환한다."""
+        return self._prepared_data
+
+
+# =============================================================================
+# 시뮬레이터 이벤트 큐: SimulatorEventQueue
+# 설명: 시뮬레이터용 이벤트를 stdout으로 출력
+# =============================================================================
+class SimulatorEventQueue(EventQueue):
+    def __init__(self, task_record: Dict[str, Any]):
+        """현재 처리 중인 작업 레코드를 보관한다."""
+        self.todo = task_record
+        super().__init__()
+
+    def enqueue_event(self, event: Event):
+        """이벤트를 큐에 넣고, stdout으로 진행상태를 출력한다."""
+        try:
+            super().enqueue_event(event)
+            
+            # 이벤트를 stdout으로 출력
+            event_data = self._convert_event_to_dict(event)
+            self._output_event_to_stdout(event_data)
+            
+        except Exception as e:
+            handle_application_error("시뮬레이터 이벤트 처리 실패", e, raise_error=False)
+        
+    def _convert_event_to_dict(self, event: Event) -> Dict[str, Any]:
+        """이벤트를 딕셔너리로 변환한다."""
+        try:
+            if hasattr(event, "__dict__"):
+                return {k: v for k, v in event.__dict__.items() if not k.startswith("_")}
+            return {"event": str(event)}
+        except Exception as e:
+            handle_application_error("시뮬레이터 이벤트 변환 실패", e, raise_error=False)
+            return {"event": str(event)}
+
+    def _output_event_to_stdout(self, event_data: Dict[str, Any]) -> None:
+        """이벤트 데이터를 stdout으로 출력한다."""
+        try:
+            # 타임스탬프 추가
+            output_data = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "task_id": self.todo.get("id"),
+                "proc_inst_id": self.todo.get("proc_inst_id"),
+                "event": event_data
+            }
+            
+            # JSON 형태로 stdout에 출력
+            json_output = json.dumps(output_data, ensure_ascii=False, indent=2)
+            print(f"[EVENT] {json_output}", file=sys.stdout, flush=True)
+            
+        except Exception as e:
+            handle_application_error("stdout 출력 실패", e, raise_error=False)
+        
+    def task_done(self) -> None:
+        """태스크 완료 로그를 남긴다."""
+        try:
+            write_log_message(f"시뮬레이션 태스크 완료: {self.todo['id']}")
+            self._output_event_to_stdout({"type": "task_completed", "message": "Task simulation completed"})
+        except Exception as e:
+            handle_application_error("시뮬레이터 태스크 완료 처리 실패", e, raise_error=False)
+
+    async def close(self) -> None:
+        """큐 종료 훅."""
+        self._output_event_to_stdout({"type": "queue_closed", "message": "Event queue closed"})

processgpt_agent_sdk/tools/human_query_tool.py

@@ -1,211 +1,211 @@
-from __future__ import annotations
-
-# =============================================================================
-# Imports
-# =============================================================================
-
-import time
-import uuid
-from typing import Optional, List, Literal, Type, Dict, Any
-from datetime import datetime, timezone
-
-from pydantic import BaseModel, Field
-from crewai.tools import BaseTool
-
-from ..utils.context_manager import todo_id_var, proc_id_var, all_users_var
-from ..utils.logger import write_log_message, handle_application_error
-from ..core.database import fetch_human_response_sync, save_notification, initialize_db, get_db_client
-
-
-# =============================================================================
-# 입력 스키마
-# =============================================================================
-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일 때 선택지 목록"
-    )
-
-
-# =============================================================================
-# HumanQueryTool
-# 설명: 보안/모호성 관련 질문을 사용자에게 전송하고 응답을 동기 대기
-# =============================================================================
-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
-
-    # =============================================================================
-    # 동기 실행
-    # 설명: 질문 이벤트를 저장하고 DB 폴링으로 응답을 기다린다
-    # =============================================================================
-    def _run(
-        self, role: str, text: str, type: str = "text", options: Optional[List[str]] = None
-    ) -> str:
-        """질문 이벤트를 기록하고 최종 응답 문자열을 반환."""
-        try:
-            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
-
-            payload_with_status = {
-                **payload,
-                "status": "ASKED",
-                "agent_profile": "/images/chat-icon.png"
-            }
-            
-            initialize_db()
-            supabase = get_db_client()
-            record = {
-                "id": str(uuid.uuid4()),
-                "job_id": query_id,
-                "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,
-                "event_type": "human_asked",
-                "crew_type": "action",
-                "data": payload_with_status,
-                "timestamp": datetime.now(timezone.utc).isoformat(),
-            }
-            supabase.table("events").insert(record).execute()
-
-            try:
-                tenant_id = self._tenant_id
-                target_emails_csv = all_users_var.get() 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)
-
-            answer = self._wait_for_response(query_id)
-            return answer
-        except Exception as e:
-            handle_application_error("HumanQueryTool", e, raise_error=False)
-            return "사용자 미응답 거절"
-
-    # =============================================================================
-    # 응답 대기
-    # 설명: events 테이블에서 human_response를 폴링하여 응답을 가져온다
-    # =============================================================================
-    def _wait_for_response(
-        self, job_id: str, timeout_sec: int = 180, poll_interval_sec: int = 5
-    ) -> str:
-        """DB 폴링으로 사람의 응답을 기다려 문자열로 반환."""
-        deadline = time.time() + timeout_sec
-
-        while time.time() < deadline:
-            try:
-                write_log_message(f"HumanQueryTool 응답 폴링: {job_id}")
-                event = fetch_human_response_sync(job_id=job_id)
-                if event:
-                    write_log_message(f"HumanQueryTool 응답 수신: {event}")
-                    data = event.get("data") or {}
-                    answer = (data or {}).get("answer")
-                    if isinstance(answer, str):
-                        write_log_message("사람 응답 수신 완료")
-                        return answer
-                    return str(data)
-
-            except Exception as e:
-                write_log_message(f"인간 응답 대기 중... (오류: {str(e)[:100]})")
-            time.sleep(poll_interval_sec)
-        return "사용자 미응답 거절"
-
+from __future__ import annotations
+
+# =============================================================================
+# Imports
+# =============================================================================
+
+import time
+import uuid
+from typing import Optional, List, Literal, Type, Dict, Any
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field
+from crewai.tools import BaseTool
+
+from ..utils.context_manager import todo_id_var, proc_id_var, all_users_var
+from ..utils.logger import write_log_message, handle_application_error
+from ..core.database import fetch_human_response_sync, save_notification, initialize_db, get_db_client
+
+
+# =============================================================================
+# 입력 스키마
+# =============================================================================
+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일 때 선택지 목록"
+    )
+
+
+# =============================================================================
+# HumanQueryTool
+# 설명: 보안/모호성 관련 질문을 사용자에게 전송하고 응답을 동기 대기
+# =============================================================================
+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
+
+    # =============================================================================
+    # 동기 실행
+    # 설명: 질문 이벤트를 저장하고 DB 폴링으로 응답을 기다린다
+    # =============================================================================
+    def _run(
+        self, role: str, text: str, type: str = "text", options: Optional[List[str]] = None
+    ) -> str:
+        """질문 이벤트를 기록하고 최종 응답 문자열을 반환."""
+        try:
+            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
+
+            payload_with_status = {
+                **payload,
+                "status": "ASKED",
+                "agent_profile": "/images/chat-icon.png"
+            }
+            
+            initialize_db()
+            supabase = get_db_client()
+            record = {
+                "id": str(uuid.uuid4()),
+                "job_id": query_id,
+                "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,
+                "event_type": "human_asked",
+                "crew_type": "action",
+                "data": payload_with_status,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+            supabase.table("events").insert(record).execute()
+
+            try:
+                tenant_id = self._tenant_id
+                target_emails_csv = all_users_var.get() 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)
+
+            answer = self._wait_for_response(query_id)
+            return answer
+        except Exception as e:
+            handle_application_error("HumanQueryTool", e, raise_error=False)
+            return "사용자 미응답 거절"
+
+    # =============================================================================
+    # 응답 대기
+    # 설명: events 테이블에서 human_response를 폴링하여 응답을 가져온다
+    # =============================================================================
+    def _wait_for_response(
+        self, job_id: str, timeout_sec: int = 180, poll_interval_sec: int = 5
+    ) -> str:
+        """DB 폴링으로 사람의 응답을 기다려 문자열로 반환."""
+        deadline = time.time() + timeout_sec
+
+        while time.time() < deadline:
+            try:
+                write_log_message(f"HumanQueryTool 응답 폴링: {job_id}")
+                event = fetch_human_response_sync(job_id=job_id)
+                if event:
+                    write_log_message(f"HumanQueryTool 응답 수신: {event}")
+                    data = event.get("data") or {}
+                    answer = (data or {}).get("answer")
+                    if isinstance(answer, str):
+                        write_log_message("사람 응답 수신 완료")
+                        return answer
+                    return str(data)
+
+            except Exception as e:
+                write_log_message(f"인간 응답 대기 중... (오류: {str(e)[:100]})")
+            time.sleep(poll_interval_sec)
+        return "사용자 미응답 거절"
+