programgarden-core 2.4.0__tar.gz → 2.5.1__tar.gz

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.4.0
+Version: 2.5.1
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/i18n/locales/en.json

@@ -112,7 +112,7 @@
   "nodes.NewOrderNode.name": "New Order",
   "nodes.OverseasFuturesAccountNode.description": "Retrieves overseas futures holdings, margin balance, and position details as a one-time REST API snapshot. Outputs held_symbols, balance (margin, maintenance margin, available margin), and positions (per-contract quantity, average cost, unrealized P&L). Requires an upstream OverseasFuturesBrokerNode for authentication. Use OverseasFuturesOpenOrdersNode separately for pending orders. For real-time updates, use OverseasFuturesRealAccountNode instead. Can be used as an AI Agent tool.",
   "nodes.OverseasFuturesAccountNode.name": "Futures Account",
-  "nodes.OverseasFuturesBrokerNode.description": "Establishes an LS Securities OpenAPI connection for overseas futures trading (CME, EUREX, SGX, HKEX). Acts as the authentication gateway — downstream account, market data, and order nodes automatically inherit this broker connection through DAG traversal. Requires credential_id referencing broker_ls_overseas_futures credentials. Supports paper trading mode for risk-free testing. Typical connection: StartNode → OverseasFuturesBrokerNode → FuturesAccountNode / FuturesMarketDataNode / FuturesNewOrderNode.",
+  "nodes.OverseasFuturesBrokerNode.description": "Establishes an LS Securities OpenAPI connection for overseas futures trading (CME, EUREX, SGX, HKEX and others — which of them an account opens differs per account). Acts as the authentication gateway — downstream account, market data, and order nodes automatically inherit this broker connection through DAG traversal. Requires credential_id referencing broker_ls_overseas_futures credentials. Works with BOTH live and paper-trading accounts — it follows the mode of the credential you registered (paper trading is risk-free practice; live trading is equally supported). Which exchanges an account opens differs per account, so confirm with an orderable-symbol lookup. Typical connection: StartNode → OverseasFuturesBrokerNode → FuturesAccountNode / FuturesMarketDataNode / FuturesNewOrderNode.",
   "nodes.OverseasFuturesBrokerNode.name": "Futures Broker",
   "nodes.OverseasFuturesCancelOrderNode.description": "Cancels a pending overseas futures order by its original order ID. Requires original_order_id from FuturesOpenOrdersNode or FuturesRealOrderEventNode. Outputs cancel result and cancelled order ID. Rate-limited to 5-second minimum interval. Typical connection: FuturesOpenOrdersNode → FuturesCancelOrderNode.",
   "nodes.OverseasFuturesCancelOrderNode.name": "Futures Cancel Order",
@@ -294,7 +294,9 @@
   "fields.PerformanceReportNode.benchmark": "Optional benchmark series (same format as data). When provided, beta and alpha are added to metrics.",
   "fields.PerformanceReportNode.periods_per_year": "Annualization factor (252 for daily, 12 for monthly data). Default 252.",
   "fields.PerformanceReportNode.risk_free_rate": "Annual risk-free rate as a fraction (e.g. 0.02 for 2%) for Sharpe/Sortino. Default 0.",
+  "fields.HTTPRequestNode.auth_required": "Does the API require authentication? Leave unset to let the chatbot decide from context; set true for private APIs (a credential is then required), false for public APIs.",
   "fields.HTTPRequestNode.body": "Request body for POST/PUT/PATCH. Automatically serialized to JSON.",
+
   "fields.HTTPRequestNode.credential_id": "Credential ID for authentication. Supports: http_bearer, http_header, http_basic, http_query",
   "fields.HTTPRequestNode.headers": "HTTP headers. Click + to add custom headers (e.g., Content-Type, X-API-Key).",
   "fields.HTTPRequestNode.method": "HTTP method for the request",
@@ -598,7 +600,9 @@
   "fieldNames.PerformanceReportNode.benchmark": "Benchmark",
   "fieldNames.PerformanceReportNode.periods_per_year": "Periods / Year",
   "fieldNames.PerformanceReportNode.risk_free_rate": "Risk-Free Rate",
+  "fieldNames.HTTPRequestNode.auth_required": "Requires Auth",
   "fieldNames.HTTPRequestNode.body": "Request Body",
+
   "fieldNames.HTTPRequestNode.credential_id": "Credential",
   "fieldNames.HTTPRequestNode.headers": "Headers",
   "fieldNames.HTTPRequestNode.method": "HTTP Method",
@@ -872,6 +876,8 @@
   "ports.http_error": "Error message",
   "ports.http_request_data": "Request data",
   "ports.http_response": "API response data",
+  "ports.http_results": "Per-item results (one {item, response, status_code, success, error} entry per iterated item)",
+
   "ports.http_status_code": "HTTP status code",
   "ports.http_success": "Request success flag",
   "ports.items": "Item list",
@@ -1194,7 +1200,14 @@
   "connection_rules.realtime_to_ai_agent.suggestion": "Place a ThrottleNode between the realtime node and AI Agent to control call frequency.",
   "connection_rules.realtime_to_external_api.reason": "Direct connection from realtime node to external API node is not recommended. Each tick would trigger an external API request, potentially hitting rate limits.",
   "connection_rules.realtime_to_external_api.suggestion": "Place a ThrottleNode between the realtime node and external API node to control request frequency.",
+  "connection.HTTPRequestNode.label": "API key",
+  "connection.KoreaStockBrokerNode.label": "LS Securities Korea stock account",
+  "connection.LLMModelNode.label": "AI model key",
+  "connection.OverseasFuturesBrokerNode.label": "LS Securities overseas futures account",
+  "connection.OverseasStockBrokerNode.label": "LS Securities overseas stock account",
+  "connection.TelegramNode.label": "Telegram bot",
   "connection_rules.realtime_to_http.reason": "Direct connection from realtime node to HTTPRequestNode is not recommended. Each tick would trigger an HTTP request, potentially hitting external API rate limits.",
+
   "connection_rules.realtime_to_http.suggestion": "Place a ThrottleNode between the realtime node and HTTP request node to control request frequency.",
   "fields.BaseOrderNode.rate_limit_interval": "Minimum order interval (seconds). Default 5 seconds. The next order will only execute after this time has elapsed since the last order.",
   "fields.BaseOrderNode.rate_limit_action": "Action when order interval is not met. skip: silently skip, error: raise error",

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/i18n/locales/ko.json

@@ -112,7 +112,7 @@
   "nodes.NewOrderNode.name": "신규 주문",
   "nodes.OverseasFuturesAccountNode.description": "해외선물 보유종목, 증거금 잔고, 포지션 상세를 REST API 1회 조회로 가져옵니다. 출력: held_symbols, balance (증거금, 유지증거금, 가용증거금), positions (계약별 수량, 평균 단가, 미실현 손익). 상위 OverseasFuturesBrokerNode 연결 필수. 미체결 주문은 OverseasFuturesOpenOrdersNode를 별도로 사용하세요. 실시간 업데이트가 필요하면 OverseasFuturesRealAccountNode를 사용하세요. AI Agent 도구로 사용 가능.",
   "nodes.OverseasFuturesAccountNode.name": "해외선물 계좌 조회",
-  "nodes.OverseasFuturesBrokerNode.description": "해외선물 거래를 위한 LS증권 OpenAPI 연결을 설정합니다(CME, EUREX, SGX, HKEX). 인증 게이트웨이 역할 — 하위 계좌, 시세, 주문 노드가 DAG 순회를 통해 자동으로 브로커 연결을 상속합니다. credential_id로 broker_ls_overseas_futures 인증 정보를 참조합니다. 위험 없는 테스트를 위한 모의투자 모드를 지원합니다. 일반적인 연결: StartNode → OverseasFuturesBrokerNode → FuturesAccountNode / FuturesMarketDataNode / FuturesNewOrderNode.",
+  "nodes.OverseasFuturesBrokerNode.description": "해외선물 거래를 위한 LS증권 OpenAPI 연결을 설정합니다(CME·EUREX·SGX·HKEX 등 — 어느 거래소가 열려 있는지는 계좌마다 다릅니다). 인증 게이트웨이 역할 — 하위 계좌, 시세, 주문 노드가 DAG 순회를 통해 자동으로 브로커 연결을 상속합니다. credential_id로 broker_ls_overseas_futures 인증 정보를 참조합니다. 실계좌와 모의투자 계좌를 모두 지원합니다 — 등록한 자격증명의 모드를 그대로 따릅니다(모의투자는 위험 없는 연습용이고, 실거래도 그대로 가능합니다). 계좌가 여는 거래소는 계좌마다 다르므로, 주문 가능 종목 조회로 확인하세요. 일반적인 연결: StartNode → OverseasFuturesBrokerNode → FuturesAccountNode / FuturesMarketDataNode / FuturesNewOrderNode.",
   "nodes.OverseasFuturesBrokerNode.name": "해외선물 브로커",
   "nodes.OverseasFuturesCancelOrderNode.description": "해외선물 미체결 주문을 원래 주문 ID로 취소합니다. FuturesOpenOrdersNode 또는 FuturesRealOrderEventNode에서 original_order_id를 받아야 합니다. 출력: 취소 결과, 취소된 주문 ID. 최소 5초 간격 제한 적용. 일반적인 연결: FuturesOpenOrdersNode → FuturesCancelOrderNode.",
   "nodes.OverseasFuturesCancelOrderNode.name": "해외선물 취소주문",
@@ -294,7 +294,9 @@
   "fields.PerformanceReportNode.benchmark": "선택 벤치마크 시계열(data 와 동일 형식). 지정 시 beta/alpha 가 지표에 추가됩니다.",
   "fields.PerformanceReportNode.periods_per_year": "연율화 계수(일간 252, 월간 12). 기본 252.",
   "fields.PerformanceReportNode.risk_free_rate": "무위험 수익률(소수, 예 0.02=2%) — Sharpe/Sortino용. 기본 0.",
+  "fields.HTTPRequestNode.auth_required": "이 API 가 인증이 필요한가요? 미설정이면 챗봇이 문맥으로 판단합니다. 비공개 API 는 true(자격증명 필요), 공개 API 는 false 로 두세요.",
   "fields.HTTPRequestNode.body": "요청 본문 (POST/PUT/PATCH용). 자동으로 JSON 직렬화됨.",
+
   "fields.HTTPRequestNode.credential_id": "인증정보 ID. 지원: http_bearer, http_header, http_basic, http_query",
   "fields.HTTPRequestNode.headers": "HTTP 헤더. + 버튼으로 커스텀 헤더 추가 (예: Content-Type, X-API-Key).",
   "fields.HTTPRequestNode.method": "HTTP 요청 메서드",
@@ -598,7 +600,9 @@
   "fieldNames.PerformanceReportNode.benchmark": "벤치마크",
   "fieldNames.PerformanceReportNode.periods_per_year": "연간 관측수",
   "fieldNames.PerformanceReportNode.risk_free_rate": "무위험 수익률",
+  "fieldNames.HTTPRequestNode.auth_required": "인증 필요 여부",
   "fieldNames.HTTPRequestNode.body": "요청본문",
+
   "fieldNames.HTTPRequestNode.credential_id": "인증정보",
   "fieldNames.HTTPRequestNode.headers": "헤더",
   "fieldNames.HTTPRequestNode.method": "HTTP메소드",
@@ -872,6 +876,8 @@
   "ports.http_error": "에러 메시지",
   "ports.http_request_data": "요청 데이터",
   "ports.http_response": "API 응답 데이터",
+  "ports.http_results": "항목별 결과 (반복된 항목마다 {item, response, status_code, success, error} 한 건)",
+
   "ports.http_status_code": "HTTP 상태 코드",
   "ports.http_success": "요청 성공 여부",
   "ports.items": "아이템 목록",
@@ -1194,7 +1200,14 @@
   "connection_rules.realtime_to_ai_agent.suggestion": "실시간 노드와 AI Agent 사이에 ThrottleNode를 배치하여 호출 빈도를 제어하세요.",
   "connection_rules.realtime_to_external_api.reason": "실시간 노드에서 외부 API 노드로의 직접 연결은 권장하지 않습니다. 틱 데이터마다 외부 API 요청이 발생하여 rate limit에 걸릴 수 있습니다.",
   "connection_rules.realtime_to_external_api.suggestion": "실시간 노드와 외부 API 노드 사이에 ThrottleNode를 배치하여 요청 빈도를 제어하세요.",
+  "connection.HTTPRequestNode.label": "API 키",
+  "connection.KoreaStockBrokerNode.label": "LS증권 국내주식 계좌",
+  "connection.LLMModelNode.label": "AI 모델 키",
+  "connection.OverseasFuturesBrokerNode.label": "LS증권 해외선물 계좌",
+  "connection.OverseasStockBrokerNode.label": "LS증권 해외주식 계좌",
+  "connection.TelegramNode.label": "텔레그램 봇",
   "connection_rules.realtime_to_http.reason": "실시간 노드에서 HTTPRequestNode로의 직접 연결은 권장하지 않습니다. 틱 데이터마다 HTTP 요청이 발생하여 외부 API 제한에 걸릴 수 있습니다.",
+
   "connection_rules.realtime_to_http.suggestion": "실시간 노드와 HTTP 요청 노드 사이에 ThrottleNode를 배치하여 요청 빈도를 제어하세요.",
   "fields.BaseOrderNode.rate_limit_interval": "최소 주문 간격 (초). 기본값 5초. 직전 주문 후 이 시간이 지나야 다음 주문이 실행됩니다.",
   "fields.BaseOrderNode.rate_limit_action": "주문 간격 미달 시 동작. skip: 조용히 건너뜀, error: 에러 발생",

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/models/credential.py

@@ -126,7 +126,7 @@ BUILTIN_CREDENTIAL_SCHEMAS: Dict[str, CredentialTypeSchema] = {
         }
     ),
     # ============================================================
-    # LS증권 해외선물 (overseas_futures) - 모의투자 지원
+    # LS증권 해외선물 (overseas_futures) - 실거래·모의투자 둘 다 지원(등록 폼에서 모드 선택)
     # ============================================================
     "broker_ls_overseas_futures": CredentialTypeSchema(
         type_id="broker_ls_overseas_futures",

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/nodes/ai.py

@@ -42,6 +42,19 @@ class LLMModelNode(BaseNode):
     type: Literal["LLMModelNode"] = "LLMModelNode"
     category: NodeCategory = NodeCategory.AI
 
+    # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. AI 모델 키는 실행에 반드시 필요하다.
+    # missing="ask" (오너 결정 2026-09-28): 키가 없으면 챗봇이 먼저 등록을 묻고, 사용자가
+    # "키 없이 진행" 이라고 명시할 때만 초안으로 저장한다("draft" 의 조용한 자동 초안과 구분).
+    _connection: ClassVar[Dict[str, Any]] = {
+        "purpose": "ai",
+        "need": "run",
+        "when": "always",
+        "label_key": "connection.LLMModelNode.label",
+        "presets": [],
+        "missing": "ask",
+    }
+
+
     # === LLM 설정 ===
     credential_id: Optional[str] = Field(
         default=None,
@@ -193,7 +206,7 @@ class LLMModelNode(BaseNode):
         },
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
-        "input_handling": "credential_id is mandatory and fixed (no expressions). It must reference a registered credential of kind llm_openai, llm_anthropic, llm_deepseek or llm_google whose api_key the user entered themselves; until the user registers and selects such a key the workflow can be built and saved but not run. Set model to the exact model ID for that provider. No data input is needed — this node only establishes the API connection.",
+        "input_handling": "credential_id is mandatory and fixed (no expressions). It must reference a registered credential of kind llm_openai, llm_anthropic, llm_deepseek or llm_google whose api_key the user entered themselves; until the user registers and selects such a key the workflow can be built and saved but not run. Because the key is required to run, the chatbot asks the user to register the AI-model key before building (connection.missing='ask'); it only saves a key-free draft when the user explicitly says to proceed without it. Set model to the exact model ID for that provider. No data input is needed — this node only establishes the API connection.",
         "output_consumption": "The 'connection' output port uses edge type 'ai_model', NOT 'main'. Connect it to AIAgentNode's ai_model input. The connection object is not a data value — it is an internal LLM client handle passed to the agent.",
         "common_combinations": [
             "LLMModelNode → AIAgentNode (ai_model edge) — always paired",
@@ -223,9 +236,11 @@ class LLMModelNode(BaseNode):
         ),
     ]
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.1.0"
+    _updated_at: ClassVar[str] = "2026-09-28"
+    _change_note: ClassVar[Optional[str]] = (
+        "connection.missing='ask' — chatbot asks the user to register the AI-model key before build"
+    )
 
     @classmethod
     def is_tool_enabled(cls) -> bool:

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/nodes/broker.py

@@ -81,6 +81,19 @@ class OverseasStockBrokerNode(BaseBrokerNode):
     _product_scope: ClassVar[ProductScope] = ProductScope.STOCK
     _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
 
+    # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. types 는 credential_id 필드의
+    # credential_types 에서 자동 추출된다. 이 계좌를 상속하는 시세/계좌/주문 노드는
+    # 자기 선언 없이 이 브로커 연결을 물려받는다.
+    _connection: ClassVar[Dict[str, Any]] = {
+        "purpose": "trading",
+        "need": "run",
+        "when": "always",
+        "label_key": "connection.OverseasStockBrokerNode.label",
+        "presets": [],
+        "missing": "draft",
+    }
+
+
     _usage: ClassVar[Dict[str, Any]] = {
         "when_to_use": [
             "Every workflow that reads overseas stock market data, account state, or places orders",
@@ -268,7 +281,10 @@ class OverseasFuturesBrokerNode(BaseBrokerNode):
     LS증권 OpenAPI를 통해 해외선물 거래를 위한 브로커 연결을 생성합니다.
 
     Note:
-    - 해외선물은 모의투자 지원
+    - 해외선물은 **실거래와 모의투자 둘 다** 지원한다. 등록 폼에서 모드를 고르는 유일한
+      상품이며, ``paper_trading`` 은 등록한 자격증명의 모드를 따른다. (모의투자를 자주
+      쓰는 것은 증거금 비용 때문이지, 실거래가 안 되기 때문이 아니다.)
+    - 계좌가 여는 거래소(CME 등)는 **계좌마다 다르다** — 주문 가능 종목 조회로만 알 수 있다.
     - credential_types: broker_ls_overseas_futures
     """
 
@@ -280,6 +296,19 @@ class OverseasFuturesBrokerNode(BaseBrokerNode):
     _product_scope: ClassVar[ProductScope] = ProductScope.FUTURES
     _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
 
+    # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. types 는 credential_id 필드의
+    # credential_types 에서 자동 추출된다. 이 계좌를 상속하는 시세/계좌/주문 노드는
+    # 자기 선언 없이 이 브로커 연결을 물려받는다.
+    _connection: ClassVar[Dict[str, Any]] = {
+        "purpose": "trading",
+        "need": "run",
+        "when": "always",
+        "label_key": "connection.OverseasFuturesBrokerNode.label",
+        "presets": [],
+        "missing": "draft",
+    }
+
+
     _usage: ClassVar[Dict[str, Any]] = {
         "when_to_use": [
             "Every overseas futures workflow — CME ES / NQ, SGX Nikkei, HKEX HSI mini, etc.",
@@ -442,6 +471,19 @@ class KoreaStockBrokerNode(BaseBrokerNode):
     _product_scope: ClassVar[ProductScope] = ProductScope.KOREA_STOCK
     _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
 
+    # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. types 는 credential_id 필드의
+    # credential_types 에서 자동 추출된다. 이 계좌를 상속하는 시세/계좌/주문 노드는
+    # 자기 선언 없이 이 브로커 연결을 물려받는다.
+    _connection: ClassVar[Dict[str, Any]] = {
+        "purpose": "trading",
+        "need": "run",
+        "when": "always",
+        "label_key": "connection.KoreaStockBrokerNode.label",
+        "presets": [],
+        "missing": "draft",
+    }
+
+
     _usage: ClassVar[Dict[str, Any]] = {
         "when_to_use": [
             "Every KRX-listed (KOSPI / KOSDAQ / NXT) stock workflow",

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/nodes/data.py

@@ -13,7 +13,7 @@ MarketDataNode는 상품별 분리됨:
 계좌 조회는 account_stock/account_futures 참조
 """
 
-from typing import Optional, List, Literal, Dict, Any, ClassVar, TYPE_CHECKING
+from typing import Optional, List, Literal, Dict, Any, ClassVar, Tuple, TYPE_CHECKING
 from pydantic import Field
 
 if TYPE_CHECKING:
@@ -47,8 +47,15 @@ class HTTPServerError(Exception):
 
 
 class HTTPRateLimitError(Exception):
-    """HTTP 429 Rate Limit 에러 - 재시도 가능"""
-    pass
+    """HTTP 429 Rate Limit 에러 - 재시도 가능.
+
+    `Retry-After` 헤더가 있으면 그 값을 `retry_after`(초, float)에 실어 RetryExecutor 가
+    지수 백오프 대신(또는 그와 함께) 서버가 요구한 대기 시간을 존중하게 한다.
+    """
+
+    def __init__(self, message: str, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.retry_after = retry_after
 
 
 class HTTPNetworkError(Exception):
@@ -61,6 +68,72 @@ class HTTPTimeoutError(Exception):
     pass
 
 
+class HTTPCredentialError(Exception):
+    """An authenticated HTTP node has no injected credential; no request was sent."""
+
+
+# ── HTTP 외부 API 보호 (오너 우려 2026-09-28: 클라우드 공유 IP 로 종목마다 요청이 동시에
+#    나가면 외부 API 사가 차단할 수 있다) ─────────────────────────────────────────────
+# 호스트별 동시 요청 상한. auto-iterate 반복은 원래 순차 실행 + rate_limit_interval 간격이라
+# 안전하지만, 실시간/병렬(fan-out) 경로에서 같은 호스트로 요청이 몰리는 것을 막는 프로세스
+# 전역 가드다. 기본 1 = 한 호스트에 한 번에 한 요청. 상수는 여기 한 곳에서만 정의한다.
+HTTP_MAX_CONCURRENCY_PER_HOST: int = 1
+
+# (event-loop id, host) → Semaphore. asyncio.Semaphore 는 생성된 이벤트 루프에 묶이므로
+# 루프별로 따로 만든다(워커는 보통 루프 하나지만, 다른 루프에서 재사용 시 RuntimeError 회피).
+_HOST_SEMAPHORES: Dict[Tuple[int, str], "object"] = {}
+
+
+def _host_semaphore(url: str):
+    """이 URL 호스트의 프로세스 전역 동시성 세마포어(현재 이벤트 루프 기준)."""
+    import asyncio
+    from urllib.parse import urlparse
+
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except Exception:
+        host = ""
+    try:
+        loop_id = id(asyncio.get_running_loop())
+    except RuntimeError:
+        loop_id = 0
+    key = (loop_id, host)
+    sem = _HOST_SEMAPHORES.get(key)
+    if sem is None:
+        sem = asyncio.Semaphore(HTTP_MAX_CONCURRENCY_PER_HOST)
+        _HOST_SEMAPHORES[key] = sem
+    return sem
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """HTTP `Retry-After` 헤더 → 대기 초. delta-seconds(정수) 또는 HTTP-date 지원.
+
+    음수/파싱 실패는 None (그러면 RetryExecutor 가 순수 지수 백오프로 되돌아간다).
+    """
+    if not value:
+        return None
+    value = value.strip()
+    # delta-seconds (가장 흔한 형태)
+    try:
+        secs = float(value)
+        return secs if secs >= 0 else None
+    except (TypeError, ValueError):
+        pass
+    # HTTP-date (RFC 7231)
+    try:
+        from email.utils import parsedate_to_datetime
+        from datetime import datetime, timezone
+
+        dt = parsedate_to_datetime(value)
+        if dt is None:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
+    except Exception:
+        return None
+
+
 class SQLiteNode(BaseNode):
     """
     로컬 SQLite 데이터베이스 노드 (단순 DB)
@@ -552,6 +625,24 @@ class HTTPRequestNode(BaseNode):
         on_throttle="skip",
     )
 
+    # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. HTTP 는 인증형 API 일 때만 키가
+    # 필요(when=auth_required, auth_required 설정 참조)하고, 실제 응답 검증에도 필요해
+    # need=validate 다. FMP/Finnhub 는 http_query 프리셋으로 param_name 을 잡아준다.
+    _connection: ClassVar[Dict[str, Any]] = {
+        "purpose": "data",
+        "need": "validate",
+        "when": "auth_required",
+        "label_key": "connection.HTTPRequestNode.label",
+        "presets": [
+            {"id": "fmp", "label": "FMP", "type": "http_query",
+             "fields": {"param_name": "apikey"}},
+            {"id": "finnhub", "label": "Finnhub", "type": "http_query",
+             "fields": {"param_name": "token"}},
+        ],
+        "missing": "draft",
+    }
+
+
     # === PARAMETERS: 핵심 HTTP 요청 설정 ===
     method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] = Field(
         default="GET",
@@ -566,6 +657,10 @@ class HTTPRequestNode(BaseNode):
         default=None, 
         description="Credential ID (credentials 섹션에서 참조)"
     )
+    credential_preset: Optional[Literal["fmp", "finnhub"]] = Field(
+        default=None,
+        description="Non-secret provider preset for the credential registration form; never selects a stored key.",
+    )
 
     # === Headers: UI에서 동적 추가 ===
     headers: Optional[Dict[str, str]] = Field(default=None, description="HTTP headers")
@@ -573,6 +668,15 @@ class HTTPRequestNode(BaseNode):
     # === SETTINGS: 부가 설정 ===
     timeout_seconds: int = Field(default=30, description="Request timeout (seconds)")
 
+    # 이 API 가 인증이 필요한가(비공개 키). None = 챗봇이 판단(기본) — 문맥으로 결정한다.
+    # True = 인증 필요(credential 없으면 검증/실행 불가), False = 공개 API(credential 불필요).
+    # 기본값을 False 로 두면 비공개 API 에 위험하므로 None(미지정)으로 둔다.
+    # `connection.when="auth_required"` 가 이 값을 참조한다.
+    auth_required: Optional[bool] = Field(
+        default=None,
+        description="Does this API require authentication? None = chatbot decides (default), True = auth required, False = public.",
+    )
+
     # === Resilience: 재시도/실패 처리 (H-21: HTTP 요청은 기본 재시도 활성화) ===
     resilience: ResilienceConfig = Field(
         default_factory=lambda: ResilienceConfig(
@@ -601,11 +705,13 @@ class HTTPRequestNode(BaseNode):
     }
     _features: ClassVar[List[str]] = [
         "Supports all HTTP methods: GET, POST, PUT, PATCH, DELETE with optional query params and request body",
-        "Built-in resilience: retry on 5xx and 429 with exponential backoff (enabled by default, max_retries=3)",
+        "Built-in resilience: retry on 5xx and 429 with exponential backoff (enabled by default, max_retries=3). Retry-After is a minimum wait. When it exceeds max_delay or the 5-second validation wait budget, retrying stops with the original failure; the server's wait is never shortened. Existing fallback and per-item error handling apply.",
+        "Per-host concurrency cap (default 1): the engine lets only one request per host run at a time process-wide, so many parallel/fan-out requests to the same external API (shared cloud egress IP) queue instead of stampeding. Auto-iterate is already sequential and paced by rate_limit_interval.",
         "Credential integration for Bearer token, HTTP Basic, custom header, and query-param auth patterns",
         "Rate-limited: minimum 1-second interval and max 3 concurrent calls; real-time node connections blocked",
         "is_tool_enabled=True — AI Agent can invoke HTTPRequestNode as a tool to fetch live external data",
         "Outputs response (parsed JSON or raw text), status_code, success flag, and error string for downstream branching",
+        "Runs once per upstream list element when the config references {{ item… }}/{{ index }}/{{ total }} (e.g. one request per watchlist symbol); the per-item outcomes are exposed on the `results` array port while response/status_code/success/error hold the last item's values. A config without an item reference runs once (unchanged).",
     ]
     _anti_patterns: ClassVar[List[Dict[str, str]]] = [
         {
@@ -693,7 +799,7 @@ class HTTPRequestNode(BaseNode):
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
         "input_handling": "The 'url' field is the only required config. Use 'body' for POST/PUT/PATCH payloads (auto-serialized to JSON). Use 'query_params' for GET parameters. The 'data' input port can supply dynamic values from upstream nodes via expression.",
-        "output_consumption": "Check 'success' (boolean) before consuming 'response'. On failure, 'error' contains the HTTP status string. 'response' is auto-parsed JSON when the Content-Type is application/json, otherwise raw text.",
+        "output_consumption": "Check 'success' (boolean) before consuming 'response'. On failure, 'error' contains the HTTP status string. 'response' is auto-parsed JSON when the Content-Type is application/json, otherwise raw text. When the config references {{ item… }} the node runs once per upstream item: read the 'results' array (one {item, response, status_code, success, error} entry per item, in order) for per-item outcomes; 'response'/'status_code'/'success'/'error' then reflect the LAST item, and top-level 'success' is the AND of all items while top-level 'error' is set only when every item failed.",
         "common_combinations": [
             "StartNode → HTTPRequestNode (GET) → FieldMappingNode → ConditionNode",
             "ConditionNode → HTTPRequestNode (POST webhook) → SummaryDisplayNode",
@@ -719,13 +825,31 @@ class HTTPRequestNode(BaseNode):
         OutputPort(name="status_code", type="number", description="i18n:ports.http_status_code"),
         OutputPort(name="success", type="boolean", description="i18n:ports.http_success"),
         OutputPort(name="error", type="string", description="i18n:ports.http_error"),
+        # Per-item results when the node auto-iterates over an upstream list
+        # (config references {{ item… }}/{{ index }}/{{ total }}). One entry per
+        # item, in order: {item, response, status_code, success, error}. A node
+        # that does not reference an iteration item runs once and this array holds
+        # that single execution. `response`/`status_code`/`success`/`error` above
+        # stay as the LAST item's scalar values (backward compatible with
+        # {{ nodes.x.response }}).
+        OutputPort(
+            name="results", type="array",
+            description="i18n:ports.http_results",
+            example=[
+                {"item": {"symbol": "AAPL", "exchange": "NASDAQ"},
+                 "response": {"price": 189.2}, "status_code": 200,
+                 "success": True, "error": None},
+            ],
+        ),
     ]
 
     _field_schema: ClassVar[Dict[str, "FieldSchema"]] = {}
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.2.0"
+    _updated_at: ClassVar[str] = "2026-09-28"
+    _change_note: ClassVar[Optional[str]] = (
+        "429 honours Retry-After + per-host concurrency cap (1) for shared-IP safety"
+    )
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
@@ -785,6 +909,14 @@ class HTTPRequestNode(BaseNode):
                 credential_types=["http_bearer", "http_header", "http_basic", "http_query"],
                 ui_component=UIComponent.CUSTOM_CREDENTIAL_SELECT,
             ),
+            "credential_preset": FieldSchema(
+                name="credential_preset", type=FieldType.ENUM, required=False,
+                description="Non-secret provider preset for credential registration",
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                enum_values=[p["id"] for p in cls._connection["presets"]],
+                group="advanced",
+            ),
             "headers": FieldSchema(
                 name="headers", type=FieldType.KEY_VALUE_PAIRS, required=False,
                 description="i18n:fields.HTTPRequestNode.headers",
@@ -812,6 +944,16 @@ class HTTPRequestNode(BaseNode):
                 max_value=300,
                 group="advanced",
             ),
+            "auth_required": FieldSchema(
+                name="auth_required", type=FieldType.BOOLEAN, required=False,
+                description="i18n:fields.HTTPRequestNode.auth_required",
+                category=FieldCategory.SETTINGS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example=True,
+                expected_type="bool",
+                group="advanced",
+            ),
+
             # === RESILIENCE: 재시도/실패 처리 (단순화된 UI) ===
             "resilience": FieldSchema(
                 name="resilience", type=FieldType.OBJECT, required=False,
@@ -876,6 +1018,16 @@ class HTTPRequestNode(BaseNode):
         - 5xx 서버 에러, 네트워크 에러, 타임아웃 → Exception raise → 재시도
         - 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
         """
+        if self.auth_required is True and not (
+            getattr(self, "token", None)
+            or (getattr(self, "header_name", None) and getattr(self, "header_value", None))
+            or (getattr(self, "username", None) and getattr(self, "password", None))
+            or (getattr(self, "param_name", None) and getattr(self, "param_value", None))
+        ):
+            raise HTTPCredentialError(
+                "CREDENTIAL_REQUIRED_TO_RUN: register and bind this HTTP node's API credential"
+            )
+
         import aiohttp
         import asyncio
         import json
@@ -929,41 +1081,49 @@ class HTTPRequestNode(BaseNode):
                     else:
                         request_kwargs["data"] = self.body
 
-                async with session.request(**request_kwargs) as resp:
-                    status_code = resp.status
-
-                    # 응답 파싱 (JSON 시도 → 실패하면 text)
-                    try:
-                        data = await resp.json()
-                    except Exception:
-                        data = await resp.text()
-
-                    # 5xx 서버 에러 → Exception raise (RetryExecutor가 재시도)
-                    if status_code >= 500:
-                        error_msg = data if isinstance(data, str) else json.dumps(data, ensure_ascii=False)[:200]
-                        raise HTTPServerError(f"HTTP {status_code}: {error_msg}")
-
-                    # 429 Rate Limit → Exception raise (RetryExecutor가 재시도)
-                    if status_code == 429:
-                        raise HTTPRateLimitError(f"HTTP 429: Rate limit exceeded")
-
-                    # 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
-                    if status_code >= 400:
-                        return {
-                            "response": data,
-                            "status_code": status_code,
-                            "success": False,
-                            "error": f"HTTP {status_code}",
-                        }
-
-                    # 성공 (2xx, 3xx)
+                # 호스트별 동시성 상한(기본 1) — 같은 호스트로 요청이 병렬로 몰리는 것을
+                # 프로세스 전역에서 막는다(공유 IP 보호). 반복은 어차피 순차라 무영향.
+                async with _host_semaphore(self.url):
+                    async with session.request(**request_kwargs) as resp:
+                        status_code = resp.status
+                        # Retry-After 는 응답 컨텍스트를 벗어나기 전에 읽어둔다.
+                        retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+
+                        # 응답 파싱 (JSON 시도 → 실패하면 text)
+                        try:
+                            data = await resp.json()
+                        except Exception:
+                            data = await resp.text()
+
+                # 5xx 서버 에러 → Exception raise (RetryExecutor가 재시도)
+                if status_code >= 500:
+                    error_msg = data if isinstance(data, str) else json.dumps(data, ensure_ascii=False)[:200]
+                    raise HTTPServerError(f"HTTP {status_code}: {error_msg}")
+
+                # 429 Rate Limit → Exception raise (RetryExecutor가 지수 백오프 재시도).
+                # Retry-After 헤더가 있으면 그 대기 시간을 예외에 실어 존중하게 한다.
+                if status_code == 429:
+                    raise HTTPRateLimitError(
+                        "HTTP 429: Rate limit exceeded", retry_after=retry_after
+                    )
+
+                # 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
+                if status_code >= 400:
                     return {
                         "response": data,
                         "status_code": status_code,
-                        "success": True,
-                        "error": None,
+                        "success": False,
+                        "error": f"HTTP {status_code}",
                     }
 
+                # 성공 (2xx, 3xx)
+                return {
+                    "response": data,
+                    "status_code": status_code,
+                    "success": True,
+                    "error": None,
+                }
+
         except aiohttp.ClientError as e:
             # 네트워크 에러 → RetryExecutor가 재시도
             raise HTTPNetworkError(f"Network error: {e}")

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/nodes/trigger.py

@@ -74,6 +74,22 @@ class ScheduleNode(BaseNode):
             "investor named a fixed number of cycles (>= 1)."
         ),
     )
+    # Owner concern 2026-09-28: many workflows sharing one cron instant (e.g.
+    # "0 9 * * *") all fire at the same second and stampede a shared cloud
+    # egress IP. jitter_seconds staggers the ACTUAL fire by a random 0..jitter
+    # seconds past each cron instant. 0 (default) = fire exactly on the instant
+    # (unchanged). Max 300s. dry_run never applies jitter (it emits one tick and
+    # exits), so it does not affect the build budget or replay semantics.
+    jitter_seconds: int = Field(
+        default=0,
+        ge=0,
+        le=300,
+        description=(
+            "Random 0..N second delay applied to each fire past the cron instant, "
+            "to spread many same-cron workflows across a shared egress IP. "
+            "0 (default) fires exactly on the cron instant; max 300."
+        ),
+    )
 
     _inputs: List[InputPort] = []
     _outputs: List[OutputPort] = [
@@ -106,6 +122,7 @@ class ScheduleNode(BaseNode):
         "Standard 5-field cron expression — minute / hour / day / month / weekday",
         "Timezone-aware (IANA names) — 'America/New_York', 'Asia/Seoul', 'UTC'",
         "max_duration_hours and count are optional bounds: omit both and the schedule runs until the workflow is stopped; set one and the scheduler exits cleanly at that limit",
+        "jitter_seconds (optional, 0..300, default 0) delays each fire by a random 0..N seconds past the cron instant, so many workflows sharing one cron ('0 9 * * *') do not all hit a shared egress IP at the same second; the cron cadence anchor is unchanged and the logical replay instant is not affected. Keep jitter well below the interval (do not set 300s jitter on an every-minute cron).",
         "enabled=False freezes the trigger without removing the node from the DAG",
         "A tick re-executes the whole main flow: the ScheduleNode returns {trigger: true} without re-registering, so every node downstream of it runs again on each tick",
         "Startup account and open-order snapshots are not retained across schedule ticks; they are retained only across realtime events",
@@ -189,7 +206,7 @@ class ScheduleNode(BaseNode):
         },
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
-        "input_handling": "No data inputs. All behavior is configured via `cron`, `timezone`, `enabled`, and the optional bounds `max_duration_hours` / `count` (omit both to run until the workflow is stopped).",
+        "input_handling": "No data inputs. All behavior is configured via `cron`, `timezone`, `enabled`, the optional bounds `max_duration_hours` / `count` (omit both to run until the workflow is stopped), and the optional `jitter_seconds` (0..300, default 0) which staggers each fire a random 0..N seconds past the cron instant to avoid a shared-IP stampede.",
         "output_consumption": "`trigger` output carries `{fired_at, cycle_index}`. Downstream nodes usually just need an incoming edge; explicit binding is optional.",
         "common_combinations": [
             "StartNode → ScheduleNode → trading body (plain cron workflow)",
@@ -203,9 +220,11 @@ class ScheduleNode(BaseNode):
         ],
     }
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.1.0"
+    _updated_at: ClassVar[str] = "2026-09-28"
+    _change_note: ClassVar[Optional[str]] = (
+        "Added optional jitter_seconds (0..300) to stagger fires past the cron instant"
+    )
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
@@ -271,6 +290,18 @@ class ScheduleNode(BaseNode):
                 expected_type="int",
                 example=1000,
             ),
+            "jitter_seconds": FieldSchema(
+                name="jitter_seconds",
+                type=FieldType.INTEGER,
+                description="Random 0..N second delay applied to each fire past the cron instant, to spread many same-cron workflows across a shared egress IP. 0 (default) fires exactly on the cron instant; max 300.",
+                default=0,
+                min_value=0,
+                max_value=300,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                category=FieldCategory.SETTINGS,
+                expected_type="int",
+                example=30,
+            ),
         }
 
 

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/registry/node_registry.py

@@ -9,7 +9,7 @@ from typing import Optional, List, Dict, Any, Type
 from pydantic import BaseModel, Field
 
 from programgarden_core.nodes.base import BaseNode, NodeCategory, InputPort, OutputPort, ProductScope, BrokerProvider
-from programgarden_core.i18n import translate_schema, translate_category
+from programgarden_core.i18n import translate_schema, translate_category, t
 
 
 class NodeTypeSchema(BaseModel):
@@ -112,6 +112,29 @@ class NodeTypeSchema(BaseModel):
             "time_rules, venue."
         ),
     )
+    connection: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Credential/connection declaration — one place the chatbot, editor "
+            "and validator read a node's credential need. Built by the core "
+            "registry from the node's `_connection` ClassVar + its credential "
+            "field's `credential_types` (locale-independent: both label_ko and "
+            "label_en are always present). None when the node needs no credential "
+            "of its own — broker-connected nodes (market data / account / order) "
+            "inherit their upstream broker's connection and declare nothing. "
+            "Keys (all present when set): types (== credential_types), purpose "
+            "(trading|data|ai|notify), need (run|validate|optional; run = needed "
+            "only to execute, validate = also needed for real-response "
+            "validation), when (always|auth_required|never; auth_required = only "
+            "when the node config marks the API authenticated), label_ko, "
+            "label_en (plain user-facing names), presets (HTTPRequestNode only; "
+            "[] elsewhere), missing (draft = may be saved without it and the run "
+            "gate blocks; block = must exist before build; ask = the chatbot "
+            "must ask the user to register the credential and only drafts "
+            "without it when the user explicitly says to proceed without it — "
+            "owner decision 2026-09-28 for AI-model keys and the Telegram bot)."
+        ),
+    )
 
     # === Version metadata (UI change detection) ===
     version: str = Field(
@@ -388,6 +411,14 @@ class NodeTypeRegistry:
 
         config_schema = self._build_config_schema(node_class, type_name)
 
+        # 연결(자격증명) 선언 직렬화 (_connection ClassVar → 챗봇/편집기/검증기 공용 dict).
+        # types 는 노드의 credential 필드가 export 한 credential_types 에서 그대로 뽑아
+        # 항상 동기화한다(별도 선언 안 함). label_ko/label_en 은 i18n 키를 양 언어로
+        # 즉시 해석해 locale-독립적으로 둘 다 싣는다(포트/설명과 달리 get_schema(locale)
+        # 재번역에 의존하지 않음). credential 필드가 없거나 _connection 미선언이면 None
+        # (브로커 연결을 상속하는 시세/계좌/주문 노드는 자기 선언이 없다).
+        connection = self._build_connection(node_class, config_schema)
+
         # Display 노드의 런타임 데이터 스키마
         display_data_schema = getattr(node_class, '_display_data_schema', None)
 
@@ -423,6 +454,7 @@ class NodeTypeRegistry:
             outputs=outputs,
             config_schema=config_schema,
             display_data_schema=display_data_schema,
+            connection=connection,
             connection_rules=serialized_connection_rules,
             rate_limit=serialized_rate_limit,
             usage=getattr(node_class, "_usage", None),
@@ -463,6 +495,45 @@ class NodeTypeRegistry:
 
         return result
 
+    # 닫힌 값 집합 — 잘못된 선언을 조기에 잡는다(테스트에서도 이 집합으로 검증).
+    _CONNECTION_PURPOSES = ("trading", "data", "ai", "notify")
+    _CONNECTION_NEEDS = ("run", "validate", "optional")
+    _CONNECTION_WHENS = ("always", "auth_required", "never")
+    _CONNECTION_MISSINGS = ("draft", "block", "ask")
+
+    def _build_connection(
+        self, node_class: Type[BaseNode], config_schema: Dict[str, Any],
+    ) -> Optional[Dict[str, Any]]:
+        """`_connection` ClassVar + credential_types → 공용 connection 선언.
+
+        모든 키가 항상 존재한다. `types` 는 config_schema 안 credential 필드가 export 한
+        `credential_types` 의 합집합이라 선언과 어긋나지 않는다. `label_ko`/`label_en` 은
+        `label_key` i18n 키를 양 언어로 해석해 둘 다 싣는다(locale-독립).
+        """
+        decl = getattr(node_class, "_connection", None)
+        if not decl:
+            return None
+
+        cred_types: List[str] = []
+        for field_cfg in config_schema.values():
+            if not isinstance(field_cfg, dict):
+                continue
+            for ct in field_cfg.get("credential_types") or []:
+                if ct not in cred_types:
+                    cred_types.append(ct)
+
+        label_key = decl.get("label_key", "")
+        return {
+            "types": cred_types,
+            "purpose": decl["purpose"],
+            "need": decl["need"],
+            "when": decl["when"],
+            "label_ko": t(label_key, "ko") if label_key else "",
+            "label_en": t(label_key, "en") if label_key else "",
+            "presets": [dict(p) for p in decl.get("presets", [])],
+            "missing": decl["missing"],
+        }
+
     def _build_config_schema(self, node_class: Type[BaseNode], node_type: str) -> Dict[str, Any]:
         """
         노드의 필드 스키마를 단순한 config_schema 형식으로 변환합니다.
@@ -516,6 +587,20 @@ class NodeTypeRegistry:
             return NodeTypeSchema(**translated)
         return schema
 
+    def connection_declaration(self, node_type: str) -> Optional[Dict[str, Any]]:
+        """이 노드가 필요로 하는 자격증명/연결 선언(챗봇·편집기·검증기 공용).
+
+        credential 이 필요 없는 노드(브로커 연결을 상속하는 시세/계좌/주문 등)는 None.
+        반환 dict 는 복사본이라 호출부가 수정해도 캐시에 영향 없다.
+        """
+        schema = self._schemas.get(node_type)
+        if schema is None or schema.connection is None:
+            return None
+        conn = dict(schema.connection)
+        conn["types"] = list(conn.get("types", []))
+        conn["presets"] = [dict(p) for p in conn.get("presets", [])]
+        return conn
+
     def list_types(self, category: Optional[str] = None) -> List[str]:
         """List registered node types"""
         if category:

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/programgarden_core/retry_executor.py

@@ -34,6 +34,10 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("programgarden.retry_executor")
 
+# Validation has a bounded wait budget. If Retry-After exceeds it, stop this
+# retry sequence and preserve the failure instead of contacting the API early.
+DRY_RUN_MAX_RETRY_WAIT_SEC: float = 5.0
+
 
 class RetryExecutor:
     """
@@ -106,12 +110,23 @@ class RetryExecutor:
                     )
                     break
 
-                # 대기 시간 계산 (exponential backoff with jitter)
-                delay = self._calculate_delay(config.retry, attempt)
+                # A server-directed wait is a floor, never a delay to truncate.
+                retry_after = getattr(e, "retry_after", None)
+                dry_run = bool(getattr(context, "is_dry_run", False))
+                delay = self._calculate_delay(
+                    config.retry, attempt, retry_after=retry_after, dry_run=dry_run
+                )
+                if delay is None:
+                    logger.warning(
+                        "[%s] Retry-After exceeds the retry wait budget; no further attempt",
+                        node.id,
+                    )
+                    break
 
                 logger.info(
                     f"[{node.id}] {error_type.value} 발생, "
                     f"재시도 {attempt}/{config.retry.max_retries}... {delay:.1f}초 후"
+                    + (f" (Retry-After={retry_after:.0f}s)" if retry_after else "")
                 )
 
                 # 재시도 이벤트 발송 (context.notify_retry 사용)
@@ -143,13 +158,14 @@ class RetryExecutor:
                     category=NotificationCategory.RETRY_EXHAUSTED,
                     severity=NotificationSeverity.WARNING,
                     title=f"Retry exhausted: {node.id}",
-                    message=f"{node.__class__.__name__} failed after {config.retry.max_retries} retries: {last_error}",
+                    message=f"{node.__class__.__name__} failed after {attempt} attempts: {last_error}",
                     node_id=node.id,
                     node_type=node.__class__.__name__,
                     data={
                         "node_id": node.id,
                         "node_type": node.__class__.__name__,
                         "max_retries": config.retry.max_retries,
+                        "attempts": attempt,
                         "last_error": str(last_error),
                     },
                 )
@@ -159,16 +175,19 @@ class RetryExecutor:
         # Fallback 처리
         return self._handle_fallback(node, last_error, config.fallback)
 
-    def _calculate_delay(self, config: RetryConfig, attempt: int) -> float:
+    def _calculate_delay(
+        self,
+        config: RetryConfig,
+        attempt: int,
+        retry_after: Optional[float] = None,
+        dry_run: bool = False,
+    ) -> Optional[float]:
         """
-        대기 시간 계산 (exponential backoff with jitter).
-
-        Args:
-            config: RetryConfig
-            attempt: 현재 시도 횟수 (1부터 시작)
+        Return bounded exponential backoff with the server's minimum wait.
 
-        Returns:
-            대기 시간 (초)
+        None means Retry-After cannot fit the configured wait budget: callers
+        must end the retry sequence, retaining the original failure. Ordinary
+        backoff remains capped when no server-directed floor prevents a retry.
         """
         if config.exponential_backoff:
             # 2^(attempt-1) * base_delay
@@ -183,8 +202,10 @@ class RetryExecutor:
         jitter = delay * 0.25 * (random.random() * 2 - 1)
         delay = delay + jitter
 
-        # max_delay 제한
-        return min(delay, config.max_delay)
+        limit = min(config.max_delay, DRY_RUN_MAX_RETRY_WAIT_SEC) if dry_run else config.max_delay
+        if retry_after is not None and retry_after > limit:
+            return None
+        return max(min(delay, limit), retry_after or 0.0)
 
     def _handle_fallback(
         self,

{programgarden_core-2.4.0 → programgarden_core-2.5.1}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 homepage = "https://programgarden.com"
 requires-python = ">=3.12"
 name = "programgarden-core"
-version = "2.4.0"
+version = "2.5.1"
 license = "AGPL-3.0-or-later"
 description = "ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의"
 readme = "README.md"