by-framework 0.2.2.dev9__py3-none-any.whl → 0.2.2.dev11__py3-none-any.whl

by_framework/__init__.py

@@ -8,6 +8,7 @@ from `GatewayWorker` and running `run_worker`.
 from .admin import WorkerManager
 from .client.byai_client import ByaiGatewayClient
 from .client.client import (
+    CancelSessionResponse,
     CancelTaskResponse,
     DataStreamEntry,
     GatewayClient,
@@ -148,6 +149,7 @@ __all__ = [
     "DataStreamEntry",
     "SendMessageResponse",
     "CancelTaskResponse",
+    "CancelSessionResponse",
     "run_worker",
     "logger",
     "setup_logging",

by_framework/__main__.py

@@ -12,6 +12,17 @@ import importlib
 from .worker.app import run_worker
 
 
+def _parse_cluster_nodes(value: str):
+    """Parse a comma-separated "host:port,host:port" string, mirroring
+    RedisConfig.from_env()'s REDIS_CLUSTER_HOST/REDIS_CLUSTER_NODES parsing
+    so the CLI and env-var paths accept the same format."""
+    nodes = []
+    for node in value.split(","):
+        node_host, node_port = node.rsplit(":", 1)
+        nodes.append((node_host, int(node_port)))
+    return nodes
+
+
 def parse_args():
     """Parse command line arguments for the CLI runner."""
     parser = argparse.ArgumentParser(description="By-Framework CLI Runner")
@@ -25,12 +36,55 @@ def parse_args():
         ),
     )
     parser.add_argument(
-        "--redis-host", type=str, default="localhost", help="Redis server hostname"
+        "--redis-host",
+        type=str,
+        default=None,
+        help="Redis server hostname (default: REDIS_HOST env var, then 'localhost')",
+    )
+    parser.add_argument(
+        "--redis-port",
+        type=int,
+        default=None,
+        help="Redis server port (default: REDIS_PORT env var, then 6379)",
+    )
+    parser.add_argument(
+        "--redis-db",
+        type=int,
+        default=None,
+        help="Redis database number (default: REDIS_DATABASE env var, then 0)",
     )
     parser.add_argument(
-        "--redis-port", type=int, default=6379, help="Redis server port"
+        "--redis-password",
+        type=str,
+        default=None,
+        help="Redis password (default: REDIS_PASSWORD env var)",
+    )
+    parser.add_argument(
+        "--redis-username",
+        type=str,
+        default=None,
+        help="Redis username, for ACL-enabled Redis (default: REDIS_USERNAME env var)",
+    )
+    parser.add_argument(
+        "--redis-mode",
+        type=str,
+        choices=["standalone", "cluster"],
+        default=None,
+        help=(
+            "Redis deployment mode (default: REDIS_MODE env var; implied by "
+            "--redis-cluster-nodes/REDIS_CLUSTER_HOST alone if neither is set)"
+        ),
+    )
+    parser.add_argument(
+        "--redis-cluster-nodes",
+        type=str,
+        default=None,
+        help=(
+            "Comma-separated Redis Cluster seed nodes, 'host:port,host:port' "
+            "(default: REDIS_CLUSTER_HOST/REDIS_CLUSTER_NODES env var). "
+            "Passing this alone implies --redis-mode cluster."
+        ),
     )
-    parser.add_argument("--redis-db", type=int, default=0, help="Redis database number")
     parser.add_argument(
         "--worker-id", type=str, default="worker-1", help="Unique worker identifier"
     )
@@ -47,6 +101,17 @@ def parse_args():
     parser.add_argument(
         "--redis-max-connections", type=int, help="Max Redis connections allowed"
     )
+    parser.add_argument(
+        "--health-port",
+        type=int,
+        default=None,
+        help=(
+            "Port for the local /readyz readiness endpoint (Docker/Kubernetes "
+            "health checks). Opt-in only - omit to leave it disabled, no "
+            "default port is provided. Also settable via BYAI_WORKER_HEALTH_PORT. "
+            "See docs/architecture/worker-readiness-endpoint.md."
+        ),
+    )
 
     return parser.parse_args()
 
@@ -68,17 +133,31 @@ def main():
 
     print(f"Starting worker class: {worker_class.__name__} (ID: {args.worker_id})")
 
-    # Delegate to the common launcher
+    redis_cluster_nodes = (
+        _parse_cluster_nodes(args.redis_cluster_nodes)
+        if args.redis_cluster_nodes
+        else None
+    )
+
+    # Delegate to the common launcher. Every redis_* arg defaults to None
+    # here (not a literal like "localhost"), same as run_worker()'s own
+    # defaults, so an unset CLI flag actually falls through to the
+    # corresponding REDIS_* env var instead of silently shadowing it.
     run_worker(
         worker_class=worker_class,
         worker_id=args.worker_id,
         redis_host=args.redis_host,
         redis_port=args.redis_port,
         redis_db=args.redis_db,
+        redis_password=args.redis_password,
+        redis_username=args.redis_username,
+        redis_mode=args.redis_mode,
+        redis_cluster_nodes=redis_cluster_nodes,
         workspace_dir=args.workspace,
         max_concurrency=args.max_concurrency,
         fetch_count=args.fetch_count,
         redis_max_connections=args.redis_max_connections,
+        health_port=args.health_port,
     )
 
 

by_framework/admin/cli.py

@@ -50,7 +50,6 @@ app.add_typer(metrics_app, name="metrics", help="Metrics and observability")
 
 console = Console()
 err_console = Console(stderr=True)
-_DEFAULT_REDIS_URL = "redis://localhost:6379/0"
 _redis_url: Optional[str] = None
 
 
@@ -85,10 +84,12 @@ def _get_redis(redis_url: Optional[str] = None):
     configured_url = redis_url if redis_url is not None else _redis_url
     if configured_url:
         return init_redis_from_url(configured_url)
-    config = RedisConfig.from_env()
-    if config.mode == "cluster":
-        return init_redis(config=config)
-    return init_redis_from_url(_DEFAULT_REDIS_URL)
+    # Always resolve through RedisConfig.from_env() - for both standalone and
+    # cluster mode - so REDIS_HOST/PORT/PASSWORD/USERNAME/DATABASE are honored
+    # the same way run_worker()'s config resolution honors them. Previously
+    # only cluster mode read env_config; standalone mode silently ignored it
+    # and connected to a hardcoded localhost:6379/0.
+    return init_redis(config=RedisConfig.from_env())
 
 
 # --------------------------------------------------------------------------- #

by_framework/client/client.py

@@ -37,6 +37,7 @@ from by_framework.core.protocol.commands import (
 from by_framework.core.protocol.data_message import DataMessage
 from by_framework.core.protocol.message_header import MessageHeader
 from by_framework.core.protocol.responses import (
+    CancelSessionResponse,
     CancelTaskResponse,
     ExecutionStatus,
     SendMessageResponse,
@@ -581,6 +582,99 @@ class GatewayClient:
             cancelled_count=len(to_cancel),
         )
 
+    async def cancel_session(
+        self,
+        session_id: str,
+        reason: str = "",
+        requested_by: str = "client",
+        cancel_mode: str = CancelMode.GRACEFUL,
+    ) -> CancelSessionResponse:
+        """Cancel every active execution registered under a session.
+
+        Unlike cancel_task, this does not require a starting message_id:
+        it cancels the whole session's active executions in one call.
+        """
+        if self.registry is None:
+            raise ValueError("GatewayClient requires a WorkerRegistry to cancel tasks")
+
+        all_executions = await self.registry.get_all_session_executions(session_id)
+
+        if not all_executions:
+            return CancelSessionResponse(
+                success=False,
+                session_id=session_id,
+                status=ExecutionStatus.NOT_FOUND,
+                timestamp=int(time.time() * 1000),
+                cancelled_count=0,
+                already_finished_count=0,
+            )
+
+        terminal_states = {"COMPLETED", "FAILED", "CANCELLED"}
+        to_cancel = [
+            node
+            for node in all_executions
+            if node.get("status", "") not in terminal_states
+        ]
+        terminal_nodes = [
+            node for node in all_executions if node.get("status", "") in terminal_states
+        ]
+
+        # Flag terminal executions so a still-running descendant can't wake
+        # them back up via callback, without changing their status.
+        for node in terminal_nodes:
+            await self.registry.mark_cancel_requested(
+                node.get("execution_id", ""), session_id, reason
+            )
+
+        if not to_cancel:
+            return CancelSessionResponse(
+                success=False,
+                session_id=session_id,
+                status=ExecutionStatus.ALREADY_FINISHED,
+                timestamp=int(time.time() * 1000),
+                cancelled_count=0,
+                already_finished_count=len(terminal_nodes),
+            )
+
+        for node in to_cancel:
+            node_execution_id = node.get("execution_id", "")
+            node_worker_id = node.get("worker_id", "")
+            node_message_id = node.get("message_id", "")
+
+            await self.registry.mark_execution_cancelling(
+                node_execution_id, session_id, reason
+            )
+
+            if node_worker_id:
+                cancel_command = CancelTaskCommand(
+                    header=MessageHeader(
+                        message_id=f"{CANCEL_MESSAGE_ID_PREFIX}{uuid.uuid4().hex[:8]}",
+                        session_id=session_id,
+                        trace_id=node.get("trace_id") or uuid.uuid4().hex,
+                        target_agent_type=node.get("target_agent_type", ""),
+                        parent_message_id=node_message_id,
+                    ),
+                    target_message_id=node_message_id,
+                    target_execution_id=node_execution_id,
+                    target_worker_id=node_worker_id,
+                    reason=reason,
+                    requested_by=requested_by,
+                    cancel_mode=cancel_mode,
+                )
+                await self.redis.xadd(
+                    RedisKeys.worker_ctrl_stream(node_worker_id),
+                    cancel_command.to_redis_payload(),
+                )
+
+        return CancelSessionResponse(
+            success=True,
+            session_id=session_id,
+            status=ExecutionStatus.CANCEL_REQUESTED,
+            timestamp=int(time.time() * 1000),
+            cancelled_count=len(to_cancel),
+            already_finished_count=len(terminal_nodes),
+        )
+
     async def send_message(
         self,
         target_agent_type: str,
@@ -691,7 +785,28 @@ class GatewayClient:
             content=params["content"],
             extra_payload=params["extra_payload"],
         )
-        execution_id = f"{EXECUTION_ID_PREFIX}{uuid.uuid4().hex[:8]}"
+
+        # A RESUME reuses the message_id of the original AskAgentCommand so the
+        # worker can look the suspended execution back up. Reuse its
+        # execution_id too, and skip re-initializing the registry record for
+        # it below -- initialize_execution() would otherwise overwrite the
+        # message_id -> execution_id mapping and detach this resume from the
+        # execution it's meant to continue.
+        resumed_execution = None
+        if (
+            params["action_type"] == ActionType.RESUME.value
+            and self.registry
+            and hasattr(self.registry, "get_execution_by_message_id")
+        ):
+            resumed_execution = await self.registry.get_execution_by_message_id(
+                message_id, session_id=params["session_id"]
+            )
+
+        execution_id = (
+            resumed_execution["execution_id"]
+            if resumed_execution
+            else f"{EXECUTION_ID_PREFIX}{uuid.uuid4().hex[:8]}"
+        )
 
         # 3. Resolve route and optionally probe agent type/liveness
         should_dispatch_control = True
@@ -837,8 +952,14 @@ class GatewayClient:
                 error_code=ExecutionStatus.ERR_AGENT_TYPE_UNAVAILABLE,
             )
 
-        # Initialize execution tracking
-        if self.registry and hasattr(self.registry, "initialize_execution"):
+        # Initialize execution tracking. Skipped for a RESUME that reattached
+        # to an existing execution -- that execution is already tracked, and
+        # re-initializing it here would overwrite its message_id mapping.
+        if (
+            not resumed_execution
+            and self.registry
+            and hasattr(self.registry, "initialize_execution")
+        ):
             try:
                 await self.registry.initialize_execution(
                     {

by_framework/common/config.py

@@ -43,6 +43,8 @@ class RedisConfig:
         """
         password = os.environ.get("REDIS_PASSWORD", "")
         username = os.environ.get("REDIS_USERNAME") or None
+        host = os.environ.get("REDIS_HOST") or "localhost"
+        port_str = os.environ.get("REDIS_PORT")
         max_connections = os.environ.get("REDIS_MAX_CONNECTIONS")
         cluster_host_str = os.environ.get("REDIS_CLUSTER_HOST")
         cluster_nodes_str = cluster_host_str or os.environ.get("REDIS_CLUSTER_NODES")
@@ -61,8 +63,8 @@ class RedisConfig:
             if db_str is not None:
                 logger.warning("REDIS_DB is deprecated, use REDIS_DATABASE instead")
         return cls(
-            host=os.environ.get("REDIS_HOST", "localhost"),
-            port=int(os.environ.get("REDIS_PORT", "6379")),
+            host=host,
+            port=int(port_str) if port_str else 6379,
             db=int(db_str) if db_str is not None else 0,
             password=password,
             username=username,

by_framework/common/emitter.py

@@ -107,6 +107,22 @@ class DefaultSseLayoutBuilder(DataLayoutBuilder):
         parent_order_id: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Build default BaiYing-compatible user input form payload."""
+        try:
+            parsed_prompt = json.loads(prompt)
+        except (json.JSONDecodeError, TypeError):
+            parsed_prompt = None
+
+        # Structured question prompts are already in the format expected by clients.
+        if isinstance(parsed_prompt, dict) and "questions" in parsed_prompt:
+            return self.build(
+                content=prompt,
+                role="assistant",
+                content_type=SseReasonMessageType.ask_user_question.value,
+                source_agent_type=source_agent_type,
+                order_id=order_id,
+                parent_order_id=parent_order_id,
+            )
+
         input_form = {
             "formStatus": 0,
             "pluginMachineFields": [

by_framework/core/__init__.py

@@ -26,6 +26,7 @@ from .protocol import (
     BaiYingMessage,
     BaiYingMessageRole,
     BaseCommand,
+    CancelSessionResponse,
     CancelTaskCommand,
     CancelTaskResponse,
     DataMessage,
@@ -53,6 +54,7 @@ from .workspace import WorkspaceManager
 __all__ = [
     "SendMessageResponse",
     "CancelTaskResponse",
+    "CancelSessionResponse",
     "BaiYingMessage",
     "BaiYingMessageRole",
     "MessageContent",

by_framework/core/protocol/__init__.py

@@ -65,6 +65,7 @@ from .message import (
 )
 from .message_header import MessageHeader
 from .responses import (
+    CancelSessionResponse,
     CancelTaskResponse,
     CancelTaskResponseDict,
     SendMessageResponse,
@@ -81,6 +82,7 @@ from .results import (
 __all__ = [
     "SendMessageResponse",
     "CancelTaskResponse",
+    "CancelSessionResponse",
     "SendMessageResponseDict",
     "CancelTaskResponseDict",
     "AgentTaskResult",

by_framework/core/protocol/content_type.py

@@ -33,6 +33,7 @@ class SseReasonMessageType(str, Enum):
     think_code_result = "3007"  # thinking process code execution result
     task_finished = "3009"  # task finished
     task_user_input = "3013"  # user input
+    ask_user_question = "3014"  # ask user question
     task_create_file = "3010"  # create file
     task_title = "3011"  # task title
     agent_card = "2015"  # agent card

by_framework/core/protocol/responses.py

@@ -92,3 +92,14 @@ class CancelTaskResponse:
     timestamp: int
     error: str = ""
     cancelled_count: int = 0
+
+
+@dataclass(frozen=True)
+class CancelSessionResponse:
+    success: bool
+    session_id: str
+    status: str
+    timestamp: int
+    cancelled_count: int = 0
+    already_finished_count: int = 0
+    error: str = ""

by_framework/core/registry.py

@@ -1011,7 +1011,8 @@ class WorkerRegistry:
         old_execution = dict(current)
         current["status"] = status
         now = int(time.time() * 1000)
-        current["finished_at"] = now
+        if is_terminal_state(status):
+            current["finished_at"] = now
         current["updated_at"] = now
         if completion:
             for key, value in completion.items():

by_framework/worker/app.py

@@ -3,6 +3,7 @@
 import asyncio
 import inspect
 import pkgutil
+import signal
 from dataclasses import replace
 from importlib import import_module
 from types import ModuleType
@@ -108,6 +109,7 @@ async def _run_worker_async(
     layout_builder: Optional[DataLayoutBuilder] = None,
     redis_mode: Optional[Literal["standalone", "cluster"]] = None,
     redis_cluster_nodes: Optional[List[Tuple[str, int]]] = None,
+    health_port: Optional[int] = None,
     **worker_kwargs,
 ):
     """Async worker runner initialization."""
@@ -243,6 +245,7 @@ async def _run_worker_async(
         group_name=consumer_group,
         max_concurrency=max_concurrency,
         fetch_count=fetch_count,
+        health_port=health_port,
     )
 
     try:
@@ -253,6 +256,36 @@ async def _run_worker_async(
         await close_redis()
 
 
+async def _run_with_graceful_shutdown(coro: Awaitable) -> None:
+    """Drive `coro` to completion, cancelling it on SIGTERM/SIGINT so the
+    caller's own try/finally (WorkerRunner._shutdown's drain-in-flight-tasks
+    sequence) runs. Without this, only Ctrl+C (SIGINT, raised by the
+    interpreter as KeyboardInterrupt) triggered graceful shutdown -
+    `docker stop`/Kubernetes pod termination send SIGTERM by default, which
+    Python's default handler turns into an immediate, non-graceful exit."""
+    loop = asyncio.get_running_loop()
+    task = asyncio.ensure_future(coro)
+
+    def _request_shutdown(sig: signal.Signals) -> None:
+        logger.info("Received %s, shutting down gracefully...", sig.name)
+        task.cancel()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            loop.add_signal_handler(sig, _request_shutdown, sig)
+        except NotImplementedError:
+            # e.g. Windows' default event loop - falls back to the
+            # KeyboardInterrupt handling in run_worker() for SIGINT only.
+            logger.debug(
+                "Signal handler for %s not supported on this platform", sig.name
+            )
+
+    try:
+        await task
+    except asyncio.CancelledError:
+        pass
+
+
 def run_worker(
     worker_class: Type[GatewayWorker],
     worker_id: str = "worker-1",
@@ -278,6 +311,7 @@ def run_worker(
     layout_builder: Optional[DataLayoutBuilder] = None,
     redis_mode: Optional[Literal["standalone", "cluster"]] = None,
     redis_cluster_nodes: Optional[List[Tuple[str, int]]] = None,
+    health_port: Optional[int] = None,
     **worker_kwargs,
 ):
     """
@@ -323,33 +357,43 @@ def run_worker(
         max_concurrency = int(os.environ.get("BYAI_WORKER_CONCURRENCY", 50))
     if fetch_count is None:
         fetch_count = int(os.environ.get("BYAI_WORKER_FETCH_COUNT", 10))
+    if health_port is None:
+        # Opt-in only, unlike the two above - no default port number, stays
+        # None (disabled) unless explicitly set. See
+        # docs/architecture/worker-readiness-endpoint.md Decision 4.
+        env_health_port = os.environ.get("BYAI_WORKER_HEALTH_PORT")
+        if env_health_port:
+            health_port = int(env_health_port)
 
     try:
         asyncio.run(
-            _run_worker_async(
-                worker_class,
-                worker_id,
-                redis_host,
-                redis_port,
-                redis_db,
-                redis_password,
-                redis_username,
-                workspace_dir,
-                consumer_group,
-                max_concurrency=max_concurrency,
-                fetch_count=fetch_count,
-                redis_max_connections=redis_max_connections,
-                plugin_list=plugin_list,
-                plugin_configurator=plugin_configurator,
-                plugin_hook_timeout_seconds=plugin_hook_timeout_seconds,
-                plugin_log_hook_stats_on_shutdown=plugin_log_hook_stats_on_shutdown,
-                history_backend=history_backend,
-                plugin_dir=plugin_dir,
-                storage=storage,
-                layout_builder=layout_builder,
-                redis_mode=redis_mode,
-                redis_cluster_nodes=redis_cluster_nodes,
-                **worker_kwargs,
+            _run_with_graceful_shutdown(
+                _run_worker_async(
+                    worker_class,
+                    worker_id,
+                    redis_host,
+                    redis_port,
+                    redis_db,
+                    redis_password,
+                    redis_username,
+                    workspace_dir,
+                    consumer_group,
+                    max_concurrency=max_concurrency,
+                    fetch_count=fetch_count,
+                    redis_max_connections=redis_max_connections,
+                    plugin_list=plugin_list,
+                    plugin_configurator=plugin_configurator,
+                    plugin_hook_timeout_seconds=plugin_hook_timeout_seconds,
+                    plugin_log_hook_stats_on_shutdown=plugin_log_hook_stats_on_shutdown,
+                    history_backend=history_backend,
+                    plugin_dir=plugin_dir,
+                    storage=storage,
+                    layout_builder=layout_builder,
+                    redis_mode=redis_mode,
+                    redis_cluster_nodes=redis_cluster_nodes,
+                    health_port=health_port,
+                    **worker_kwargs,
+                )
             )
         )
     except KeyboardInterrupt:

by_framework/worker/health_server.py

@@ -0,0 +1,169 @@
+"""Worker readiness HTTP endpoint for Docker/Kubernetes health checks.
+
+See docs/architecture/worker-readiness-endpoint.md for the full design
+record (why readiness-only, why a dedicated thread, why /readyz, the
+reason-priority order, and the hard rule against ever wiring this to a
+liveness probe).
+"""
+
+import json
+import threading
+import time
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Callable, Optional
+from urllib.parse import urlparse
+
+from by_framework.common.logger import logger
+
+READYZ_PATH = "/readyz"
+
+
+def _make_readyz_handler(
+    compute_state: Callable[[], dict],
+) -> type[BaseHTTPRequestHandler]:
+    """Build a request handler bound to the given state computation."""
+
+    class ReadyzHandler(BaseHTTPRequestHandler):
+        """Serves /readyz; every other path is 404."""
+
+        server_version = "ByFrameworkWorkerReadiness/0.1"
+
+        def do_GET(self) -> None:  # pylint: disable=invalid-name
+            if urlparse(self.path).path != READYZ_PATH:
+                self.send_response(HTTPStatus.NOT_FOUND)
+                self.end_headers()
+                return
+
+            state = compute_state()
+            status = HTTPStatus.OK if state["ready"] else HTTPStatus.SERVICE_UNAVAILABLE
+            body = json.dumps(state).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, format: str, *args) -> None:  # pylint: disable=redefined-builtin
+            # The stdlib default logs every request to stderr - a probe
+            # hitting this every few seconds would spam Worker logs.
+            pass
+
+    return ReadyzHandler
+
+
+class WorkerHealthServer:
+    """Runs /readyz on a dedicated thread, never the Worker's main event loop.
+
+    Mirrors WorkerHeartbeat's "dedicated thread" pattern for the same
+    reason: a busy consume loop must not make readiness checks
+    unreachable. Reads Worker state via plain callables passed in by the
+    caller (WorkerRunner) - this class has no knowledge of WorkerRunner
+    itself, so it can be started standalone against fake state in tests.
+    """
+
+    def __init__(
+        self,
+        worker_id: str,
+        port: int,
+        has_started: Callable[[], bool],
+        is_draining: Callable[[], bool],
+        admin_lifecycle: Callable[[], str],
+        consumer_healthy: Callable[[], bool],
+        host: str = "0.0.0.0",
+    ):
+        self.worker_id = worker_id
+        self.host = host
+        self.port = port
+        self._has_started = has_started
+        self._is_draining = is_draining
+        self._admin_lifecycle = admin_lifecycle
+        self._consumer_healthy = consumer_healthy
+        self._server: Optional[ThreadingHTTPServer] = None
+        self._thread: Optional[threading.Thread] = None
+        self._started_at_monotonic = 0.0
+
+    @staticmethod
+    def _compute_reason(
+        has_started: bool,
+        is_draining: bool,
+        admin_lifecycle: str,
+        consumer_healthy: bool,
+    ) -> str:
+        # Priority order, first match wins - see
+        # docs/architecture/worker-readiness-endpoint.md.
+        if not has_started:
+            return "starting"
+        if is_draining:
+            return "draining"
+        if admin_lifecycle == "evicted":
+            return "evicted"
+        if admin_lifecycle == "suspended":
+            return "suspended"
+        if not consumer_healthy:
+            return "consumer_stalled"
+        return "serving"
+
+    def _compute_state(self) -> dict:
+        # Read each accessor once - _compute_reason() takes the values
+        # rather than re-deriving them, so a request never calls into
+        # WorkerRunner's state twice for the same field.
+        admin_lifecycle = self._admin_lifecycle()
+        consumer_healthy = self._consumer_healthy()
+        reason = self._compute_reason(
+            has_started=self._has_started(),
+            is_draining=self._is_draining(),
+            admin_lifecycle=admin_lifecycle,
+            consumer_healthy=consumer_healthy,
+        )
+        uptime_ms = 0
+        if self._started_at_monotonic:
+            uptime_ms = int((time.monotonic() - self._started_at_monotonic) * 1000)
+        return {
+            "ready": reason == "serving",
+            "reason": reason,
+            "worker_id": self.worker_id,
+            "admin_lifecycle": admin_lifecycle,
+            "consumer_healthy": consumer_healthy,
+            "uptime_ms": uptime_ms,
+        }
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the server has actually bound and is serving - distinct
+        from the WorkerHealthServer object merely having been constructed."""
+        return self._server is not None
+
+    def start(self) -> None:
+        """Bind and start serving /readyz on a dedicated thread. No-op if
+        already started."""
+        if self._server is not None:
+            return
+        self._started_at_monotonic = time.monotonic()
+        handler = _make_readyz_handler(self._compute_state)
+        self._server = ThreadingHTTPServer((self.host, self.port), handler)
+        self.port = self._server.server_address[1]
+        self._thread = threading.Thread(
+            target=self._server.serve_forever,
+            daemon=True,
+            name=f"health-server-{self.worker_id}",
+        )
+        self._thread.start()
+        logger.info(
+            "[%s] Readiness endpoint listening on %s:%d%s",
+            self.worker_id,
+            self.host,
+            self.port,
+            READYZ_PATH,
+        )
+
+    def stop(self) -> None:
+        """Stop serving and release the port. Safe to call more than once."""
+        if self._server is None:
+            return
+        self._server.shutdown()
+        self._server.server_close()
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+        self._server = None
+        self._thread = None

by_framework/worker/runner.py

@@ -41,6 +41,7 @@ from by_framework.trace.trace_schema import TraceRecord
 from by_framework.trace.trace_writer import TraceWriteClient
 from by_framework.util.generate_message_id import generate_message_id
 from by_framework.worker.context import current_worker_id_var
+from by_framework.worker.health_server import WorkerHealthServer
 from by_framework.worker.worker import GatewayWorker
 
 from ._control_handling import (
@@ -69,6 +70,7 @@ class WorkerRunner:
         max_concurrency: int = 50,
         fetch_count: int = 10,
         span_recorder: Optional[SpanRecorder] = None,
+        health_port: Optional[int] = None,
     ):
         if (
             worker is None
@@ -117,6 +119,22 @@ class WorkerRunner:
             float(self.worker.heartbeat_lease_ttl_seconds) * 2.0,
             stream_block_seconds * 3.0,
         )
+        # Set as the first step of _shutdown() - see
+        # docs/architecture/worker-readiness-endpoint.md Decision 6.
+        self._draining: bool = False
+        # Opt-in only - see docs/architecture/worker-readiness-endpoint.md.
+        # None (the default) means no port opens and nothing here changes
+        # behavior for existing deployments.
+        self._health_server: Optional[WorkerHealthServer] = None
+        if health_port is not None:
+            self._health_server = WorkerHealthServer(
+                worker_id=self.worker.worker_id,
+                port=health_port,
+                has_started=lambda: self._consumer_last_tick_monotonic > 0,
+                is_draining=lambda: self._draining,
+                admin_lifecycle=lambda: self._admin_lifecycle,
+                consumer_healthy=self._is_consumer_healthy,
+            )
 
     @property
     def _terminal_execution_states(self) -> frozenset[str]:
@@ -505,6 +523,16 @@ class WorkerRunner:
                     header.message_id, session_id=header.session_id
                 )
 
+            if isinstance(command, ResumeCommand) and existing_execution is None:
+                logger.warning(
+                    "[%s] ResumeCommand did not resolve to an existing execution "
+                    "(message_id=%s, session_id=%s); starting a new, disconnected "
+                    "execution instead of continuing the suspended one.",
+                    self.worker.worker_id,
+                    header.message_id,
+                    header.session_id,
+                )
+
             # Skip terminal state replays
             if (
                 existing_execution
@@ -906,6 +934,12 @@ class WorkerRunner:
         """Start the worker runner main loop."""
         self._running_tasks = set()
         try:
+            # As early as possible, so a probe hitting the port during
+            # startup gets an honest "starting" 503 instead of connection-
+            # refused - see docs/architecture/worker-readiness-endpoint.md.
+            if self._health_server is not None:
+                self._health_server.start()
+
             if hasattr(self.worker.registry, "claim_worker_id"):
                 self._lock_token = await self._claim_worker_id_with_retry()
 
@@ -974,6 +1008,10 @@ class WorkerRunner:
 
     async def _shutdown(self):
         """Graceful shutdown sequence."""
+        # First step, deliberately - readiness must flip the instant
+        # shutdown begins, not once the drain below finishes. See
+        # docs/architecture/worker-readiness-endpoint.md Decision 6.
+        self._draining = True
         if self._metrics_collector_task:
             self._metrics_collector_task.cancel()
             await asyncio.gather(self._metrics_collector_task, return_exceptions=True)
@@ -1019,3 +1057,8 @@ class WorkerRunner:
             if getattr(plugin_registry, "log_hook_stats_on_shutdown", True):
                 plugin_registry.log_hook_stats()
             await plugin_registry.on_worker_shutdown(self.worker)
+
+        # Stopped last, deliberately - the readiness endpoint should keep
+        # responding for the entire drain, not disappear before it.
+        if self._health_server is not None:
+            self._health_server.stop()

{by_framework-0.2.2.dev9.dist-info → by_framework-0.2.2.dev11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: by-framework
-Version: 0.2.2.dev9
+Version: 0.2.2.dev11
 Summary: 分布式 Agent 调度框架
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -250,6 +250,13 @@ async def main():
 asyncio.run(main())
 ```
 
+A runnable version of this pair lives at
+[`examples/echo_worker.py`](examples/echo_worker.py) (Worker) and
+[`examples/send_and_verify.py`](examples/send_and_verify.py) (client — blocks
+until it sees the echoed reply) — the same pair `deploy/`'s CI smoke test
+drives end to end, see
+[`docs/architecture/production-deployment.md`](docs/architecture/production-deployment.md).
+
 ---
 
 ## Core Concepts
@@ -602,7 +609,7 @@ Tests are organized by module under `tests/`:
 
 ```bash
 # 1. Start Redis
-docker run -d --name by-redis -p 6379:6379 registry:7-alpine
+docker run -d --name by-redis -p 6379:6379 redis:7-alpine
 
 # 2. Start a Worker
 python -m by_framework \
@@ -621,11 +628,27 @@ python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-02 &
 python -m by_framework --worker-class my_agent.MyAgent --worker-id worker-03 &
 ```
 
+`&` is fine for a quick local check but isn't real process supervision — for
+an actual deployment, use the reference Dockerfile, Compose file, and
+Kubernetes Deployment under [`deploy/`](deploy/):
+
+```bash
+# Docker Compose — N supervised replicas, distinct worker ids, restart policy
+docker compose -f deploy/docker-compose.yml up --build --scale worker=3
+
+# Kubernetes — same idea as a Deployment
+kubectl apply -f deploy/kubernetes/worker-deployment.yaml
+```
+
+The CLI also exposes `--redis-password`, `--redis-username`, `--redis-mode`,
+and `--redis-cluster-nodes` (all mirrored by the `REDIS_*` env vars used in
+the Compose/Kubernetes examples above) — see `python -m by_framework --help`.
+
 ### Reliability
 
 - **Message persistence:** Messages are stored in Redis Streams until explicitly acknowledged (`XACK`). Unacknowledged messages are redelivered on Worker restart.
 - **Durable config:** Agent config snapshots are persisted to Redis, so a restarted Worker recovers the last-known plugin configuration.
-- **Gradual shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work.
+- **Graceful shutdown:** `WorkerRunner` drains in-flight tasks before shutting down, acknowledging completed work. This is wired to both `SIGINT` (Ctrl+C) and `SIGTERM` — the signal `docker stop`/Kubernetes pod termination actually send — so it fires under real container orchestration, not just an interactive terminal. Give it enough `stop_grace_period`/`terminationGracePeriodSeconds` to cover your longest task (see the `deploy/` examples), since a hard `SIGKILL` after the grace period skips the drain entirely.
 - **Separate data path:** Data output goes to session-scoped streams independently of control, so backend consumers are decoupled from Worker scaling.
 
 ### Logging

{by_framework-0.2.2.dev9.dist-info → by_framework-0.2.2.dev11.dist-info}/RECORD

@@ -1,23 +1,23 @@
-by_framework/__init__.py,sha256=5Ff4xfX-TNXcp4RMoBLQCWuehPMLpNRHwZrXofgFx5A,5300
-by_framework/__main__.py,sha256=_vIEieJzSHfZnPp-zna_hbVtWQUgE0I3mrWD41WzXiA,2561
+by_framework/__init__.py,sha256=aNq4eeO-5WfFC86JJlfDgCvI11vk90ZWtL3yaREcJl4,5356
+by_framework/__main__.py,sha256=P2smZtTse__MOhvJXBo4YZG1Rs2AAjX4Xk5aGrZgnAY,5237
 by_framework/admin/__init__.py,sha256=MKGQBtKk8YdnMrZ5gkzEemMl4iL8OfeFhEV6HdWR2XI,138
-by_framework/admin/cli.py,sha256=KBmTHONKdb6BeskW6d3DL6GRnL91xen0PJ80JB0h0lc,11710
+by_framework/admin/cli.py,sha256=YW4tQxb0kBheRNQR53zOkoAlYHWP4bgycuZkaJIU3WA,11917
 by_framework/admin/worker_manager.py,sha256=ihXRMlFJAR74T2JSh3xTNCDjzAElWd0-_yVDAZwSTJU,5924
 by_framework/client/__init__.py,sha256=kGP7uoXIlTJuiJ2Cgl1Q5wqYjnMA4SZqoa7Q7BhQ5JQ,272
 by_framework/client/byai_client.py,sha256=bB1NyKLvVW82bXefD_3zymqZ1vk2O925CIbxOho9Qww,2426
-by_framework/client/client.py,sha256=T_5ahX9enmsaXm-xBGvwpMx-yALzO7wOTgY-qAVj0Q4,40342
+by_framework/client/client.py,sha256=hT_IRR51jsu3MIPFbZDmmL9xQHtNUFJCADBep9iFyQI,45157
 by_framework/common/__init__.py,sha256=EkfIiVdmb8SCpi7OOUm6Hu84B7Wzekb-TG2hbvD_R1w,1685
-by_framework/common/config.py,sha256=RGe5Ce-uUgpZv1bgkdT4kCRcaIpaYhzskyvQy17Qn_o,5043
+by_framework/common/config.py,sha256=mTbCn3YspY8k00b4URSbi07MNC3Cfdj7RPtDLrXrJV8,5107
 by_framework/common/constants.py,sha256=xUp6Nvx31EH7EzkxDNBzXD0GIE9FpPnPmuVbL-BAAoI,22089
-by_framework/common/emitter.py,sha256=Mcp6vglFlS7_JVsLd_KVKvV49TKjoyoN4eCM_tm4I8s,11310
+by_framework/common/emitter.py,sha256=bobdekSsA3vnMu8TMHonkjfgK-awW_p11dgcTU_3mQw,11940
 by_framework/common/exceptions.py,sha256=NKQC7ueLZ4-gVTRz3SFRZNoPHsayu6jxi3-YlW0n_jg,962
 by_framework/common/logger.py,sha256=DX6S7U5CLcCQIUQ3IWqeeDnSC7QGuHKYaEhiKvKrBpk,5823
 by_framework/common/redis_client.py,sha256=JfYE-QutI9G27dbehzvLw0LziTM1gHmG4tdVjxd0IoA,4668
-by_framework/core/__init__.py,sha256=bEaOfjGoCF0WacR_PoYSb5kUqJv-g59pngdnEE7fJzo,2070
+by_framework/core/__init__.py,sha256=cGG93S1gzd1N64JaTCVD7JLV0ZzbF92Q9C6Sog0yDSE,2126
 by_framework/core/availability.py,sha256=ZME5S002eNzNpzaW_QuWw8AmUN1JelUxwCt2U3PPAeQ,17624
 by_framework/core/delivery_gate.py,sha256=yijlCOw8zEou1HCyQzwRHDJZtLBsUnXtQ3x1FZsc4yU,2012
 by_framework/core/discovery.py,sha256=12mAnPzJph0zqlfJwu8k-IN5AKc7dpC0sXToBGLU2Fw,13116
-by_framework/core/registry.py,sha256=Qp_ghu47Wzjf2AKDUpRmzipPUGsbnc6vyB-wb4ubkGI,52864
+by_framework/core/registry.py,sha256=bpthWbuVrUIBO1Wtz5F3A2s2GAon9zX_6FR9zn7fxAw,52906
 by_framework/core/wakeup_controller.py,sha256=0v3Fr69XzIKO0fesYUPvQvsGLYt0f648Xq7XEM_jk6c,5545
 by_framework/core/workspace.py,sha256=R9mxghDh_INtPOIXHilBamAIue8jZMrlQoQRI02KSxw,3980
 by_framework/core/extensions/__init__.py,sha256=MvPh029FXvkR1Lk4bZxiq9SfzUQ57paUfoD17-whvn4,1032
@@ -26,7 +26,7 @@ by_framework/core/extensions/agent_config_audit.py,sha256=Ax67XF2dg_oqz8GvCQ5vsu
 by_framework/core/extensions/plugin.py,sha256=rmV4wjf_x-v8E55s9_bDQPyvsqZT4ebZ2fnScbmUGkg,9236
 by_framework/core/extensions/registry.py,sha256=s2UYEOvNzZ3Q8CH1vPBCUw3hhOfQTJ6GKTJ2aXPxVCY,25314
 by_framework/core/extensions/trace_provider.py,sha256=ShM-aJWfenHD006m5sj3M3fi5zZOiTaQ9MZyKV9yv2o,582
-by_framework/core/protocol/__init__.py,sha256=oQeO2E9DD8Wz2qwvBrKOlm4SgIqnEBlpZwa-BuijCnQ,3388
+by_framework/core/protocol/__init__.py,sha256=wxpD8UMYIYmpXtwZZvT9FQZA6hSjHyoEUZ2kFw1_McA,3444
 by_framework/core/protocol/action_type.py,sha256=5uhwzpaf_PwYMPharJHoX_oc4Cf1dZruCpJ8eyUdwXQ,1112
 by_framework/core/protocol/agent_state.py,sha256=CtqwisNWuPy91FEPXjQrR3r0jLeOrUF1huu23ODnEPo,1919
 by_framework/core/protocol/byai_codec.py,sha256=BqCCYS_uEXOpAHogrNl7-3Tce9HBxMKRpO0ccQN80SA,3185
@@ -34,14 +34,14 @@ by_framework/core/protocol/byai_command.py,sha256=FJjU4H9b7S5Q59OZqDpVu3JBln7_P9
 by_framework/core/protocol/byai_types.py,sha256=szP6yONsMwtErZZUOOgLRnwqIJnPYKM7qcqrgwkEyIc,187
 by_framework/core/protocol/commands.py,sha256=5MFP0EjElbPBAOUE_D0gErUJsHD06EuWCkmqyLsRX8U,11144
 by_framework/core/protocol/content_codec.py,sha256=E8uHhRU6jlH16MQ3UmA8jPexm71l3HKxpquF9xJk04o,643
-by_framework/core/protocol/content_type.py,sha256=fjzNIQQ_-1z7dEMsyEEz7imv1fTBwO1OFyU2H6sk1d4,1217
+by_framework/core/protocol/content_type.py,sha256=fagsdHPIoPyWwmgYfb3JzP52olxDDzpGbmQ9q3bmQxE,1269
 by_framework/core/protocol/data_message.py,sha256=UEK9W1lIt_6DLdu0o_CW5YoQJrsEjRUHHEtH2syRO-A,1290
 by_framework/core/protocol/data_shapes.py,sha256=nA6OnfwXRJB1lmwcME3K5TEn_IwmShmBOlYSmOF7y3k,2245
 by_framework/core/protocol/event_type.py,sha256=no7rh1Mx_mhyqqPzEM4aK-W8JB8NwzyOdWN6R_CqaPw,1106
 by_framework/core/protocol/events.py,sha256=SVUXWWVIgxC9VuKjPE1qnvWJgKhWqY48pOHKD0HLcRg,1594
 by_framework/core/protocol/message.py,sha256=sBLm374jsCNa5UPCBJK7xgxJBw3CjrNsoEAnPSp3rAc,2374
 by_framework/core/protocol/message_header.py,sha256=udZkcUv-NEz2j-vpxGglrHWaIJy6k3ZJ9M5ajtL3WQo,3140
-by_framework/core/protocol/responses.py,sha256=fJhWIgkWoIbrNpS0sHWnVwPsS0pNCav-qGMu9AiTK9g,2376
+by_framework/core/protocol/responses.py,sha256=Q2xNFL1zPAGR0OpAB4uxu6iHHKUMIsBjc7yren4c0UA,2589
 by_framework/core/protocol/results.py,sha256=xRr0FhTyuck0ANSOD8yuozzJoVOHFp0G2iSK9V69Hec,5297
 by_framework/core/runtime/__init__.py,sha256=mYbe9D2BvZ3eYTjvU64CZyHLuMoRUU7DGwAIQXf7KR4,991
 by_framework/core/runtime/agent_config_manager.py,sha256=QpBkBXqWHEgqx8VXaQnRWJsG1TbHNJMHbLBMv0tQqJ8,8301
@@ -82,18 +82,19 @@ by_framework/worker/__init__.py,sha256=GBkUWYnHc2j3_Wx2AC2P49DzFl0CSrl0SKhdRP5CT
 by_framework/worker/_control_handling.py,sha256=0bL1Alx8_qaeXQV32Xv4ARSd9q77ySh9LMd7KtZZXu8,8111
 by_framework/worker/_execution_tracking.py,sha256=AWahfDKTXGrx_JWSCNisjGKkGAQruu9vSlXisof0BYQ,2493
 by_framework/worker/_message_processing.py,sha256=rgKzJTgPVDFp_HUfMcqJBwNdTCEfspuRAo5IM9VKsxs,2622
-by_framework/worker/app.py,sha256=pf_q4F1ypf6u97HP4IpHVPVW5pssMg9_XXAwzv0wJfM,14387
+by_framework/worker/app.py,sha256=UHaQZzalqfPmHvfq-XL7vlPOJ8mTm5ULIU4JpeXA85g,16319
 by_framework/worker/byai_context.py,sha256=DvKw-X8ePZr5c5osdapvzTvH4G23u0J80U-fgMLtge4,2388
 by_framework/worker/byai_worker.py,sha256=0NoRqzuTG_MPMxVbZ1ueeOrqI0H8-Adxh7dM3vckjJo,1757
 by_framework/worker/context.py,sha256=XTNeTAhXvzS2OMDRCDKVD0s3uQscE1rFo9eImUw773w,44747
+by_framework/worker/health_server.py,sha256=4Jw3ltAD7Ow4dPHhwTUU_4JjKz-iDCNG7RJzD2VzPlM,6090
 by_framework/worker/heartbeat.py,sha256=trHDS8FUALsA6jyzDPa087hpr8_2vY8ZUFn0ld1kI2o,15465
 by_framework/worker/processor.py,sha256=D5GcV1T21z4mwJnrZFDRNsxdkhW2WZ3TgpygSKKJUfg,8008
-by_framework/worker/runner.py,sha256=ZuuhzdXB4oIjSaNyJCjOIYhzvw6L5N7X6kPzvrbWET8,43719
+by_framework/worker/runner.py,sha256=32T5BeCWalSxpp_eTH1vesF_kLs0HLIx0zm48ywCqT4,45954
 by_framework/worker/worker.py,sha256=_RmNkvHEN5kDPlqbHtVQhkhgiKx37xjnCxNkf_tvASM,35441
 by_framework/worker/sandbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 by_framework/worker/sandbox/hook_sandbox.py,sha256=XXSdH5YGX814LvV03vkq-zn5DVIBPYYt2NhRv1lT1Bk,2329
-by_framework-0.2.2.dev9.dist-info/METADATA,sha256=qmdF2bXuu0_IfQI5_QazjrVOxd8EjIHiqnm0PiIVZVo,26533
-by_framework-0.2.2.dev9.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-by_framework-0.2.2.dev9.dist-info/entry_points.txt,sha256=5t6kgMjkR0UgJTpOsbuQDo0fOf7zeXjQW9DhkxfAGFc,56
-by_framework-0.2.2.dev9.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-by_framework-0.2.2.dev9.dist-info/RECORD,,
+by_framework-0.2.2.dev11.dist-info/METADATA,sha256=pr4rQABuXWzDZP2yc50J0qPN3qyuPxTR3tMJ8Xcu2Uc,28018
+by_framework-0.2.2.dev11.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+by_framework-0.2.2.dev11.dist-info/entry_points.txt,sha256=5t6kgMjkR0UgJTpOsbuQDo0fOf7zeXjQW9DhkxfAGFc,56
+by_framework-0.2.2.dev11.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+by_framework-0.2.2.dev11.dist-info/RECORD,,