Merge branch 'blackoutta/hitl-svc-api' into p363-hjlarry

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

.devcontainer/post_create_command.sh

@@ -7,7 +7,7 @@ cd web && pnpm install
 pipx install uv
 
 echo "alias start-api=\"cd $WORKSPACE_ROOT/api && uv run python -m flask run --host 0.0.0.0 --port=5001 --debug\"" >> ~/.bashrc
-echo "alias start-worker=\"cd $WORKSPACE_ROOT/api && uv run python -m celery -A app.celery worker -P threads -c 1 --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention\"" >> ~/.bashrc
+echo "alias start-worker=\"cd $WORKSPACE_ROOT/api && uv run python -m celery -A app.celery worker -P threads -c 1 --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention\"" >> ~/.bashrc
 echo "alias start-web=\"cd $WORKSPACE_ROOT/web && pnpm dev:inspect\"" >> ~/.bashrc
 echo "alias start-web-prod=\"cd $WORKSPACE_ROOT/web && pnpm build && pnpm start\"" >> ~/.bashrc
 echo "alias start-containers=\"cd $WORKSPACE_ROOT/docker && docker-compose -f docker-compose.middleware.yaml -p dify --env-file middleware.env up -d\"" >> ~/.bashrc

.vscode/launch.json.template

@@ -2,21 +2,10 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Python: Flask API",
+            "name": "Python: API (gevent)",
             "type": "debugpy",
             "request": "launch",
-            "module": "flask",
-            "env": {
-                "FLASK_APP": "app.py",
-                "FLASK_ENV": "development"
-            },
-            "args": [
-                "run",
-                "--host=0.0.0.0",
-                "--port=5001",
-                "--no-debugger",
-                "--no-reload"
-            ],
+            "program": "${workspaceFolder}/api/app.py",
             "jinja": true,
             "justMyCode": true,
             "cwd": "${workspaceFolder}/api",

api/.env.example

@@ -33,6 +33,9 @@ TRIGGER_URL=http://localhost:5001
 # The time in seconds after the signature is rejected
 FILES_ACCESS_TIMEOUT=300
 
+# Collaboration mode toggle
+ENABLE_COLLABORATION_MODE=false
+
 # Access token expiration time in minutes
 ACCESS_TOKEN_EXPIRE_MINUTES=60
 

api/.vscode/launch.json.example

@@ -3,29 +3,21 @@
     "compounds": [
         {
             "name": "Launch Flask and Celery",
-            "configurations": ["Python: Flask", "Python: Celery"]
+            "configurations": ["Python: API (gevent)", "Python: Celery"]
         }
     ],
     "configurations": [
         {
-            "name": "Python: Flask",
-            "consoleName": "Flask",
+            "name": "Python: API (gevent)",
+            "consoleName": "API",
             "type": "debugpy",
             "request": "launch",
             "python": "${workspaceFolder}/.venv/bin/python",
             "cwd": "${workspaceFolder}",
             "envFile": ".env",
-            "module": "flask",
+            "program": "${workspaceFolder}/app.py",
             "justMyCode": true,
-            "jinja": true,
-            "env": {
-                "FLASK_APP": "app.py",
-                "GEVENT_SUPPORT": "True"
-            },
-            "args": [
-                "run",
-                "--port=5001"
-            ]
+            "jinja": true
         },
         {
             "name": "Python: Celery",

api/app.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import sys
 from typing import TYPE_CHECKING, cast
 
@@ -9,17 +10,35 @@ if TYPE_CHECKING:
     celery: Celery
 
 
+HOST = "0.0.0.0"
+PORT = 5001
+logger = logging.getLogger(__name__)
+
+
 def is_db_command() -> bool:
     if len(sys.argv) > 1 and sys.argv[0].endswith("flask") and sys.argv[1] == "db":
         return True
     return False
 
 
+def log_startup_banner(host: str, port: int) -> None:
+    debugger_attached = sys.gettrace() is not None
+    logger.info("Serving Dify API via gevent WebSocket server")
+    logger.info("Bound to http://%s:%s", host, port)
+    logger.info("Debugger attached: %s", "on" if debugger_attached else "off")
+    logger.info("Press CTRL+C to quit")
+
+
 # create app
+flask_app = None
+socketio_app = None
+
 if is_db_command():
     from app_factory import create_migrations_app
 
     app = create_migrations_app()
+    socketio_app = app
+    flask_app = app
 else:
     # Gunicorn and Celery handle monkey patching automatically in production by
     # specifying the `gevent` worker class. Manual monkey patching is not required here.
@@ -30,8 +49,14 @@ else:
 
     from app_factory import create_app
 
-    app = create_app()
+    socketio_app, flask_app = create_app()
+    app = flask_app
     celery = cast("Celery", app.extensions["celery"])
 
 if __name__ == "__main__":
-    app.run(host="0.0.0.0", port=5001)
+    from gevent import pywsgi
+    from geventwebsocket.handler import WebSocketHandler  # type: ignore[reportMissingTypeStubs]
+
+    log_startup_banner(HOST, PORT)
+    server = pywsgi.WSGIServer((HOST, PORT), socketio_app, handler_class=WebSocketHandler)
+    server.serve_forever()

api/app_factory.py

@@ -1,6 +1,7 @@
 import logging
 import time
 
+import socketio  # type: ignore[reportMissingTypeStubs]
 from flask import request
 from opentelemetry.trace import get_current_span
 from opentelemetry.trace.span import INVALID_SPAN_ID, INVALID_TRACE_ID
@@ -10,6 +11,7 @@ from contexts.wrapper import RecyclableContextVar
 from controllers.console.error import UnauthorizedAndForceLogout
 from core.logging.context import init_request_context
 from dify_app import DifyApp
+from extensions.ext_socketio import sio
 from services.enterprise.enterprise_service import EnterpriseService
 from services.feature_service import LicenseStatus
 
@@ -122,14 +124,18 @@ def create_flask_app_with_configs() -> DifyApp:
     return dify_app
 
 
-def create_app() -> DifyApp:
+def create_app() -> tuple[socketio.WSGIApp, DifyApp]:
     start_time = time.perf_counter()
     app = create_flask_app_with_configs()
     initialize_extensions(app)
+
+    sio.app = app
+    socketio_app = socketio.WSGIApp(sio, app)
+
     end_time = time.perf_counter()
     if dify_config.DEBUG:
         logger.info("Finished create_app (%s ms)", round((end_time - start_time) * 1000, 2))
-    return app
+    return socketio_app, app
 
 
 def initialize_extensions(app: DifyApp):

api/configs/feature/__init__.py

@@ -1274,6 +1274,13 @@ class PositionConfig(BaseSettings):
         return {item.strip() for item in self.POSITION_TOOL_EXCLUDES.split(",") if item.strip() != ""}
 
 
+class CollaborationConfig(BaseSettings):
+    ENABLE_COLLABORATION_MODE: bool = Field(
+        description="Whether to enable collaboration mode features across the workspace",
+        default=False,
+    )
+
+
 class LoginConfig(BaseSettings):
     ENABLE_EMAIL_CODE_LOGIN: bool = Field(
         description="whether to enable email code login",
@@ -1399,6 +1406,7 @@ class FeatureConfig(
     WorkflowConfig,
     WorkflowNodeExecutionConfig,
     WorkspaceConfig,
+    CollaborationConfig,
     LoginConfig,
     AccountConfig,
     SwaggerUIConfig,

api/controllers/console/__init__.py

@@ -65,6 +65,7 @@ from .app import (
     statistic,
     workflow,
     workflow_app_log,
+    workflow_comment,
     workflow_draft_variable,
     workflow_run,
     workflow_statistic,
@@ -116,6 +117,7 @@ from .explore import (
     saved_message,
     trial,
 )
+from .socketio import workflow as socketio_workflow  # pyright: ignore[reportUnusedImport]
 
 # Import tag controllers
 from .tag import tags
@@ -201,6 +203,7 @@ __all__ = [
     "saved_message",
     "setup",
     "site",
+    "socketio_workflow",
     "spec",
     "statistic",
     "tags",
@@ -211,6 +214,7 @@ __all__ = [
     "website",
     "workflow",
     "workflow_app_log",
+    "workflow_comment",
     "workflow_draft_variable",
     "workflow_run",
     "workflow_statistic",

api/controllers/console/app/workflow.py

@@ -7,6 +7,7 @@ from flask import abort, request
 from flask_restx import Resource, fields, marshal, marshal_with
 from graphon.enums import NodeType
 from graphon.file import File
+from graphon.file import helpers as file_helpers
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.utils.encoders import jsonable_encoder
 from pydantic import BaseModel, Field, ValidationError, field_validator
@@ -39,6 +40,7 @@ from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from factories import file_factory, variable_factory
 from fields.member_fields import simple_account_fields
+from fields.online_user_fields import online_user_list_fields
 from fields.workflow_fields import workflow_fields, workflow_pagination_fields
 from libs import helper
 from libs.datetime_utils import naive_utc_now
@@ -47,6 +49,7 @@ from libs.login import current_account_with_tenant, login_required
 from models import App
 from models.model import AppMode
 from models.workflow import Workflow
+from repositories.workflow_collaboration_repository import WORKFLOW_ONLINE_USERS_PREFIX
 from services.app_generate_service import AppGenerateService
 from services.errors.app import IsDraftWorkflowError, WorkflowHashNotEqualError, WorkflowNotFoundError
 from services.errors.llm import InvokeRateLimitError
@@ -57,6 +60,7 @@ _file_access_controller = DatabaseFileAccessController()
 LISTENING_RETRY_IN = 2000
 DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 RESTORE_SOURCE_WORKFLOW_MUST_BE_PUBLISHED_MESSAGE = "source workflow must be published"
+MAX_WORKFLOW_ONLINE_USERS_QUERY_IDS = 50
 
 # Register models for flask_restx to avoid dict type issues in Swagger
 # Register in dependency order: base models first, then dependent models
@@ -150,6 +154,14 @@ class ConvertToWorkflowPayload(BaseModel):
     icon_background: str | None = None
 
 
+class WorkflowFeaturesPayload(BaseModel):
+    features: dict[str, Any] = Field(..., description="Workflow feature configuration")
+
+
+class WorkflowOnlineUsersQuery(BaseModel):
+    app_ids: str = Field(..., description="Comma-separated app IDs")
+
+
 class DraftWorkflowTriggerRunPayload(BaseModel):
     node_id: str
 
@@ -173,6 +185,8 @@ reg(DefaultBlockConfigQuery)
 reg(ConvertToWorkflowPayload)
 reg(WorkflowListQuery)
 reg(WorkflowUpdatePayload)
+reg(WorkflowFeaturesPayload)
+reg(WorkflowOnlineUsersQuery)
 reg(DraftWorkflowTriggerRunPayload)
 reg(DraftWorkflowTriggerRunAllPayload)
 
@@ -931,6 +945,32 @@ class ConvertToWorkflowApi(Resource):
         }
 
 
+@console_ns.route("/apps/<uuid:app_id>/workflows/draft/features")
+class WorkflowFeaturesApi(Resource):
+    """Update draft workflow features."""
+
+    @console_ns.expect(console_ns.models[WorkflowFeaturesPayload.__name__])
+    @console_ns.doc("update_workflow_features")
+    @console_ns.doc(description="Update draft workflow features")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Workflow features updated successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    @edit_permission_required
+    def post(self, app_model: App):
+        current_user, _ = current_account_with_tenant()
+
+        args = WorkflowFeaturesPayload.model_validate(console_ns.payload or {})
+        features = args.features
+
+        workflow_service = WorkflowService()
+        workflow_service.update_draft_workflow_features(app_model=app_model, features=features, account=current_user)
+
+        return {"result": "success"}
+
+
 @console_ns.route("/apps/<uuid:app_id>/workflows")
 class PublishedAllWorkflowApi(Resource):
     @console_ns.expect(console_ns.models[WorkflowListQuery.__name__])
@@ -1340,3 +1380,62 @@ class DraftWorkflowTriggerRunAllApi(Resource):
                     "status": "error",
                 }
             ), 400
+
+
+@console_ns.route("/apps/workflows/online-users")
+class WorkflowOnlineUsersApi(Resource):
+    @console_ns.expect(console_ns.models[WorkflowOnlineUsersQuery.__name__])
+    @console_ns.doc("get_workflow_online_users")
+    @console_ns.doc(description="Get workflow online users")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @marshal_with(online_user_list_fields)
+    def get(self):
+        args = WorkflowOnlineUsersQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore
+
+        app_ids = list(dict.fromkeys(app_id.strip() for app_id in args.app_ids.split(",") if app_id.strip()))
+        if len(app_ids) > MAX_WORKFLOW_ONLINE_USERS_QUERY_IDS:
+            raise BadRequest(f"Maximum {MAX_WORKFLOW_ONLINE_USERS_QUERY_IDS} app_ids are allowed per request.")
+
+        if not app_ids:
+            return {"data": []}
+
+        _, current_tenant_id = current_account_with_tenant()
+        workflow_service = WorkflowService()
+        accessible_app_ids = workflow_service.get_accessible_app_ids(app_ids, current_tenant_id)
+
+        results = []
+        for app_id in app_ids:
+            if app_id not in accessible_app_ids:
+                continue
+
+            users_json = redis_client.hgetall(f"{WORKFLOW_ONLINE_USERS_PREFIX}{app_id}")
+
+            users = []
+            for _, user_info_json in users_json.items():
+                try:
+                    user_info = json.loads(user_info_json)
+                except Exception:
+                    continue
+
+                if not isinstance(user_info, dict):
+                    continue
+
+                avatar = user_info.get("avatar")
+                if isinstance(avatar, str) and avatar and not avatar.startswith(("http://", "https://")):
+                    try:
+                        user_info["avatar"] = file_helpers.get_signed_file_url(avatar)
+                    except Exception as exc:
+                        logger.warning(
+                            "Failed to sign workflow online user avatar; using original value. "
+                            "app_id=%s avatar=%s error=%s",
+                            app_id,
+                            avatar,
+                            exc,
+                        )
+
+                users.append(user_info)
+            results.append({"app_id": app_id, "users": users})
+
+        return {"data": results}

api/controllers/console/app/workflow_comment.py

@@ -0,0 +1,335 @@
+import logging
+
+from flask_restx import Resource, marshal_with
+from pydantic import BaseModel, Field, TypeAdapter
+
+from controllers.common.schema import register_schema_models
+from controllers.console import console_ns
+from controllers.console.app.wraps import get_app_model
+from controllers.console.wraps import account_initialization_required, edit_permission_required, setup_required
+from fields.member_fields import AccountWithRole
+from fields.workflow_comment_fields import (
+    workflow_comment_basic_fields,
+    workflow_comment_create_fields,
+    workflow_comment_detail_fields,
+    workflow_comment_reply_create_fields,
+    workflow_comment_reply_update_fields,
+    workflow_comment_resolve_fields,
+    workflow_comment_update_fields,
+)
+from libs.login import current_user, login_required
+from models import App
+from services.account_service import TenantService
+from services.workflow_comment_service import WorkflowCommentService
+
+logger = logging.getLogger(__name__)
+DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
+
+
+class WorkflowCommentCreatePayload(BaseModel):
+    content: str = Field(..., description="Comment content")
+    position_x: float = Field(..., description="Comment X position")
+    position_y: float = Field(..., description="Comment Y position")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentUpdatePayload(BaseModel):
+    content: str = Field(..., description="Comment content")
+    position_x: float | None = Field(default=None, description="Comment X position")
+    position_y: float | None = Field(default=None, description="Comment Y position")
+    mentioned_user_ids: list[str] | None = Field(
+        default=None,
+        description="Mentioned user IDs. Omit to keep existing mentions.",
+    )
+
+
+class WorkflowCommentReplyPayload(BaseModel):
+    content: str = Field(..., description="Reply content")
+    mentioned_user_ids: list[str] = Field(default_factory=list, description="Mentioned user IDs")
+
+
+class WorkflowCommentMentionUsersPayload(BaseModel):
+    users: list[AccountWithRole]
+
+
+for model in (
+    WorkflowCommentCreatePayload,
+    WorkflowCommentUpdatePayload,
+    WorkflowCommentReplyPayload,
+):
+    console_ns.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+register_schema_models(console_ns, AccountWithRole, WorkflowCommentMentionUsersPayload)
+
+workflow_comment_basic_model = console_ns.model("WorkflowCommentBasic", workflow_comment_basic_fields)
+workflow_comment_detail_model = console_ns.model("WorkflowCommentDetail", workflow_comment_detail_fields)
+workflow_comment_create_model = console_ns.model("WorkflowCommentCreate", workflow_comment_create_fields)
+workflow_comment_update_model = console_ns.model("WorkflowCommentUpdate", workflow_comment_update_fields)
+workflow_comment_resolve_model = console_ns.model("WorkflowCommentResolve", workflow_comment_resolve_fields)
+workflow_comment_reply_create_model = console_ns.model(
+    "WorkflowCommentReplyCreate", workflow_comment_reply_create_fields
+)
+workflow_comment_reply_update_model = console_ns.model(
+    "WorkflowCommentReplyUpdate", workflow_comment_reply_update_fields
+)
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments")
+class WorkflowCommentListApi(Resource):
+    """API for listing and creating workflow comments."""
+
+    @console_ns.doc("list_workflow_comments")
+    @console_ns.doc(description="Get all comments for a workflow")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Comments retrieved successfully", workflow_comment_basic_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_basic_model, envelope="data")
+    def get(self, app_model: App):
+        """Get all comments for a workflow."""
+        comments = WorkflowCommentService.get_comments(tenant_id=current_user.current_tenant_id, app_id=app_model.id)
+
+        return comments
+
+    @console_ns.doc("create_workflow_comment")
+    @console_ns.doc(description="Create a new workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentCreatePayload.__name__])
+    @console_ns.response(201, "Comment created successfully", workflow_comment_create_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_create_model)
+    @edit_permission_required
+    def post(self, app_model: App):
+        """Create a new workflow comment."""
+        payload = WorkflowCommentCreatePayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.create_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            created_by=current_user.id,
+            content=payload.content,
+            position_x=payload.position_x,
+            position_y=payload.position_y,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>")
+class WorkflowCommentDetailApi(Resource):
+    """API for managing individual workflow comments."""
+
+    @console_ns.doc("get_workflow_comment")
+    @console_ns.doc(description="Get a specific workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(200, "Comment retrieved successfully", workflow_comment_detail_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_detail_model)
+    def get(self, app_model: App, comment_id: str):
+        """Get a specific workflow comment."""
+        comment = WorkflowCommentService.get_comment(
+            tenant_id=current_user.current_tenant_id, app_id=app_model.id, comment_id=comment_id
+        )
+
+        return comment
+
+    @console_ns.doc("update_workflow_comment")
+    @console_ns.doc(description="Update a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentUpdatePayload.__name__])
+    @console_ns.response(200, "Comment updated successfully", workflow_comment_update_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_update_model)
+    @edit_permission_required
+    def put(self, app_model: App, comment_id: str):
+        """Update a workflow comment."""
+        payload = WorkflowCommentUpdatePayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.update_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+            content=payload.content,
+            position_x=payload.position_x,
+            position_y=payload.position_y,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result
+
+    @console_ns.doc("delete_workflow_comment")
+    @console_ns.doc(description="Delete a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(204, "Comment deleted successfully")
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @edit_permission_required
+    def delete(self, app_model: App, comment_id: str):
+        """Delete a workflow comment."""
+        WorkflowCommentService.delete_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+        )
+
+        return {"result": "success"}, 204
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/resolve")
+class WorkflowCommentResolveApi(Resource):
+    """API for resolving and reopening workflow comments."""
+
+    @console_ns.doc("resolve_workflow_comment")
+    @console_ns.doc(description="Resolve a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.response(200, "Comment resolved successfully", workflow_comment_resolve_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_resolve_model)
+    @edit_permission_required
+    def post(self, app_model: App, comment_id: str):
+        """Resolve a workflow comment."""
+        comment = WorkflowCommentService.resolve_comment(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            user_id=current_user.id,
+        )
+
+        return comment
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/replies")
+class WorkflowCommentReplyApi(Resource):
+    """API for managing comment replies."""
+
+    @console_ns.doc("create_workflow_comment_reply")
+    @console_ns.doc(description="Add a reply to a workflow comment")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentReplyPayload.__name__])
+    @console_ns.response(201, "Reply created successfully", workflow_comment_reply_create_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_reply_create_model)
+    @edit_permission_required
+    def post(self, app_model: App, comment_id: str):
+        """Add a reply to a workflow comment."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        payload = WorkflowCommentReplyPayload.model_validate(console_ns.payload or {})
+
+        result = WorkflowCommentService.create_reply(
+            comment_id=comment_id,
+            content=payload.content,
+            created_by=current_user.id,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return result, 201
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/<string:comment_id>/replies/<string:reply_id>")
+class WorkflowCommentReplyDetailApi(Resource):
+    """API for managing individual comment replies."""
+
+    @console_ns.doc("update_workflow_comment_reply")
+    @console_ns.doc(description="Update a comment reply")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID", "reply_id": "Reply ID"})
+    @console_ns.expect(console_ns.models[WorkflowCommentReplyPayload.__name__])
+    @console_ns.response(200, "Reply updated successfully", workflow_comment_reply_update_model)
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @marshal_with(workflow_comment_reply_update_model)
+    @edit_permission_required
+    def put(self, app_model: App, comment_id: str, reply_id: str):
+        """Update a comment reply."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        payload = WorkflowCommentReplyPayload.model_validate(console_ns.payload or {})
+
+        reply = WorkflowCommentService.update_reply(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            reply_id=reply_id,
+            user_id=current_user.id,
+            content=payload.content,
+            mentioned_user_ids=payload.mentioned_user_ids,
+        )
+
+        return reply
+
+    @console_ns.doc("delete_workflow_comment_reply")
+    @console_ns.doc(description="Delete a comment reply")
+    @console_ns.doc(params={"app_id": "Application ID", "comment_id": "Comment ID", "reply_id": "Reply ID"})
+    @console_ns.response(204, "Reply deleted successfully")
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    @edit_permission_required
+    def delete(self, app_model: App, comment_id: str, reply_id: str):
+        """Delete a comment reply."""
+        # Validate comment access first
+        WorkflowCommentService.validate_comment_access(
+            comment_id=comment_id, tenant_id=current_user.current_tenant_id, app_id=app_model.id
+        )
+
+        WorkflowCommentService.delete_reply(
+            tenant_id=current_user.current_tenant_id,
+            app_id=app_model.id,
+            comment_id=comment_id,
+            reply_id=reply_id,
+            user_id=current_user.id,
+        )
+
+        return {"result": "success"}, 204
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflow/comments/mention-users")
+class WorkflowCommentMentionUsersApi(Resource):
+    """API for getting mentionable users for workflow comments."""
+
+    @console_ns.doc("workflow_comment_mention_users")
+    @console_ns.doc(description="Get all users in current tenant for mentions")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(
+        200, "Mentionable users retrieved successfully", console_ns.models[WorkflowCommentMentionUsersPayload.__name__]
+    )
+    @login_required
+    @setup_required
+    @account_initialization_required
+    @get_app_model()
+    def get(self, app_model: App):
+        """Get all users in current tenant for mentions."""
+        members = TenantService.get_tenant_members(current_user.current_tenant)
+        users = TypeAdapter(list[AccountWithRole]).validate_python(members, from_attributes=True)
+        response = WorkflowCommentMentionUsersPayload(users=users)
+        return response.model_dump(mode="json"), 200

api/controllers/console/app/workflow_draft_variable.py

@@ -22,6 +22,7 @@ from controllers.web.error import InvalidArgumentError, NotFoundError
 from core.app.file_access import DatabaseFileAccessController
 from core.workflow.variable_prefixes import CONVERSATION_VARIABLE_NODE_ID, SYSTEM_VARIABLE_NODE_ID
 from extensions.ext_database import db
+from factories import variable_factory
 from factories.file_factory import build_from_mapping, build_from_mappings
 from factories.variable_factory import build_segment_with_type
 from libs.login import current_user, login_required
@@ -45,6 +46,16 @@ class WorkflowDraftVariableUpdatePayload(BaseModel):
     value: Any | None = Field(default=None, description="Variable value")
 
 
+class ConversationVariableUpdatePayload(BaseModel):
+    conversation_variables: list[dict[str, Any]] = Field(
+        ..., description="Conversation variables for the draft workflow"
+    )
+
+
+class EnvironmentVariableUpdatePayload(BaseModel):
+    environment_variables: list[dict[str, Any]] = Field(..., description="Environment variables for the draft workflow")
+
+
 console_ns.schema_model(
     WorkflowDraftVariableListQuery.__name__,
     WorkflowDraftVariableListQuery.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
@@ -53,6 +64,14 @@ console_ns.schema_model(
     WorkflowDraftVariableUpdatePayload.__name__,
     WorkflowDraftVariableUpdatePayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
 )
+console_ns.schema_model(
+    ConversationVariableUpdatePayload.__name__,
+    ConversationVariableUpdatePayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+)
+console_ns.schema_model(
+    EnvironmentVariableUpdatePayload.__name__,
+    EnvironmentVariableUpdatePayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+)
 
 
 def _convert_values_to_json_serializable_object(value: Segment):
@@ -510,6 +529,34 @@ class ConversationVariableCollectionApi(Resource):
         db.session.commit()
         return _get_variable_list(app_model, CONVERSATION_VARIABLE_NODE_ID)
 
+    @console_ns.expect(console_ns.models[ConversationVariableUpdatePayload.__name__])
+    @console_ns.doc("update_conversation_variables")
+    @console_ns.doc(description="Update conversation variables for workflow draft")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Conversation variables updated successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @get_app_model(mode=AppMode.ADVANCED_CHAT)
+    def post(self, app_model: App):
+        payload = ConversationVariableUpdatePayload.model_validate(console_ns.payload or {})
+
+        workflow_service = WorkflowService()
+
+        conversation_variables_list = payload.conversation_variables
+        conversation_variables = [
+            variable_factory.build_conversation_variable_from_mapping(obj) for obj in conversation_variables_list
+        ]
+
+        workflow_service.update_draft_workflow_conversation_variables(
+            app_model=app_model,
+            account=current_user,
+            conversation_variables=conversation_variables,
+        )
+
+        return {"result": "success"}
+
 
 @console_ns.route("/apps/<uuid:app_id>/workflows/draft/system-variables")
 class SystemVariableCollectionApi(Resource):
@@ -561,3 +608,31 @@ class EnvironmentVariableCollectionApi(Resource):
             )
 
         return {"items": env_vars_list}
+
+    @console_ns.expect(console_ns.models[EnvironmentVariableUpdatePayload.__name__])
+    @console_ns.doc("update_environment_variables")
+    @console_ns.doc(description="Update environment variables for workflow draft")
+    @console_ns.doc(params={"app_id": "Application ID"})
+    @console_ns.response(200, "Environment variables updated successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT, AppMode.WORKFLOW])
+    def post(self, app_model: App):
+        payload = EnvironmentVariableUpdatePayload.model_validate(console_ns.payload or {})
+
+        workflow_service = WorkflowService()
+
+        environment_variables_list = payload.environment_variables
+        environment_variables = [
+            variable_factory.build_environment_variable_from_mapping(obj) for obj in environment_variables_list
+        ]
+
+        workflow_service.update_draft_workflow_environment_variables(
+            app_model=app_model,
+            account=current_user,
+            environment_variables=environment_variables,
+        )
+
+        return {"result": "success"}

api/controllers/console/socketio/__init__.py

@@ -0,0 +1 @@
+

api/controllers/console/socketio/workflow.py

@@ -0,0 +1,108 @@
+import logging
+from collections.abc import Callable
+from typing import cast
+
+from flask import Request as FlaskRequest
+
+from extensions.ext_socketio import sio
+from libs.passport import PassportService
+from libs.token import extract_access_token
+from repositories.workflow_collaboration_repository import WorkflowCollaborationRepository
+from services.account_service import AccountService
+from services.workflow_collaboration_service import WorkflowCollaborationService
+
+repository = WorkflowCollaborationRepository()
+collaboration_service = WorkflowCollaborationService(repository, sio)
+
+
+def _sio_on(event: str) -> Callable[[Callable[..., object]], Callable[..., object]]:
+    return cast(Callable[[Callable[..., object]], Callable[..., object]], sio.on(event))
+
+
+@_sio_on("connect")
+def socket_connect(sid, environ, auth):
+    """
+    WebSocket connect event, do authentication here.
+    """
+    try:
+        request_environ = FlaskRequest(environ)
+        token = extract_access_token(request_environ)
+    except Exception:
+        logging.exception("Failed to extract token")
+        token = None
+
+    if not token:
+        logging.warning("Socket connect rejected: missing token (sid=%s)", sid)
+        return False
+
+    try:
+        decoded = PassportService().verify(token)
+        user_id = decoded.get("user_id")
+        if not user_id:
+            logging.warning("Socket connect rejected: missing user_id (sid=%s)", sid)
+            return False
+
+        with sio.app.app_context():
+            user = AccountService.load_logged_in_account(account_id=user_id)
+            if not user:
+                logging.warning("Socket connect rejected: user not found (user_id=%s, sid=%s)", user_id, sid)
+                return False
+            if not user.has_edit_permission:
+                logging.warning("Socket connect rejected: no edit permission (user_id=%s, sid=%s)", user_id, sid)
+                return False
+
+            collaboration_service.save_socket_identity(sid, user)
+            return True
+
+    except Exception:
+        logging.exception("Socket authentication failed")
+        return False
+
+
+@_sio_on("user_connect")
+def handle_user_connect(sid, data):
+    """
+    Handle user connect event. Each session (tab) is treated as an independent collaborator.
+    """
+    workflow_id = data.get("workflow_id")
+    if not workflow_id:
+        return {"msg": "workflow_id is required"}, 400
+
+    result = collaboration_service.authorize_and_join_workflow_room(workflow_id, sid)
+    if not result:
+        return {"msg": "unauthorized"}, 401
+
+    user_id, is_leader = result
+    return {"msg": "connected", "user_id": user_id, "sid": sid, "isLeader": is_leader}
+
+
+@_sio_on("disconnect")
+def handle_disconnect(sid):
+    """
+    Handle session disconnect event. Remove the specific session from online users.
+    """
+    collaboration_service.disconnect_session(sid)
+
+
+@_sio_on("collaboration_event")
+def handle_collaboration_event(sid, data):
+    """
+    Handle general collaboration events, include:
+    1. mouse_move
+    2. vars_and_features_update
+    3. sync_request (ask leader to update graph)
+    4. app_state_update
+    5. mcp_server_update
+    6. workflow_update
+    7. comments_update
+    8. node_panel_presence
+    """
+    return collaboration_service.relay_collaboration_event(sid, data)
+
+
+@_sio_on("graph_event")
+def handle_graph_event(sid, data):
+    """
+    Handle graph events - simple broadcast relay.
+    """
+    return collaboration_service.relay_graph_event(sid, data)

api/controllers/console/workspace/account.py

@@ -6,6 +6,7 @@ from typing import Any, Literal
 import pytz
 from flask import request
 from flask_restx import Resource
+from graphon.file import helpers as file_helpers
 from pydantic import BaseModel, Field, field_validator, model_validator
 from sqlalchemy import select
 
@@ -75,6 +76,10 @@ class AccountAvatarPayload(BaseModel):
     avatar: str
 
 
+class AccountAvatarQuery(BaseModel):
+    avatar: str = Field(..., description="Avatar file ID")
+
+
 class AccountInterfaceLanguagePayload(BaseModel):
     interface_language: str
 
@@ -160,6 +165,7 @@ def reg(cls: type[BaseModel]):
 reg(AccountInitPayload)
 reg(AccountNamePayload)
 reg(AccountAvatarPayload)
+reg(AccountAvatarQuery)
 reg(AccountInterfaceLanguagePayload)
 reg(AccountInterfaceThemePayload)
 reg(AccountTimezonePayload)
@@ -309,6 +315,18 @@ class AccountNameApi(Resource):
 
 @console_ns.route("/account/avatar")
 class AccountAvatarApi(Resource):
+    @console_ns.expect(console_ns.models[AccountAvatarQuery.__name__])
+    @console_ns.doc("get_account_avatar")
+    @console_ns.doc(description="Get account avatar url")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    def get(self):
+        args = AccountAvatarQuery.model_validate(request.args.to_dict(flat=True))  # type: ignore
+
+        avatar_url = file_helpers.get_signed_file_url(args.avatar)
+        return {"avatar_url": avatar_url}
+
     @console_ns.expect(console_ns.models[AccountAvatarPayload.__name__])
     @setup_required
     @login_required

api/controllers/service_api/__init__.py

@@ -23,9 +23,11 @@ from .app import (
     conversation,
     file,
     file_preview,
+    human_input_form,
     message,
     site,
     workflow,
+    workflow_events,
 )
 from .dataset import (
     dataset,
@@ -50,6 +52,7 @@ __all__ = [
     "file",
     "file_preview",
     "hit_testing",
+    "human_input_form",
     "index",
     "message",
     "metadata",
@@ -58,6 +61,7 @@ __all__ = [
     "segment",
     "site",
     "workflow",
+    "workflow_events",
 ]
 
 api.add_namespace(service_api_ns)

api/controllers/service_api/app/human_input_form.py

@@ -0,0 +1,133 @@
+"""
+Service API human input form endpoints.
+
+This module exposes app-token authenticated APIs for fetching and submitting
+paused human input forms in workflow/chatflow runs.
+"""
+
+import json
+import logging
+from datetime import datetime
+from typing import Any
+
+from flask import Response
+from flask_restx import Resource
+from pydantic import BaseModel
+from werkzeug.exceptions import InternalServerError, NotFound
+
+from controllers.common.schema import register_schema_models
+from controllers.service_api import service_api_ns
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from extensions.ext_database import db
+from models.model import App, EndUser
+from services.human_input_service import Form, FormNotFoundError, HumanInputService
+
+logger = logging.getLogger(__name__)
+
+
+class HumanInputFormSubmitPayload(BaseModel):
+    inputs: dict[str, Any]
+    action: str
+
+
+register_schema_models(service_api_ns, HumanInputFormSubmitPayload)
+
+
+def _stringify_default_values(values: dict[str, object]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key, value in values.items():
+        if value is None:
+            result[key] = ""
+        elif isinstance(value, (dict, list)):
+            result[key] = json.dumps(value, ensure_ascii=False)
+        else:
+            result[key] = str(value)
+    return result
+
+
+def _to_timestamp(value: datetime) -> int:
+    return int(value.timestamp())
+
+
+def _jsonify_form_definition(form: Form) -> Response:
+    definition_payload = form.get_definition().model_dump()
+    payload = {
+        "form_content": definition_payload["rendered_content"],
+        "inputs": definition_payload["inputs"],
+        "resolved_default_values": _stringify_default_values(definition_payload["default_values"]),
+        "user_actions": definition_payload["user_actions"],
+        "expiration_time": _to_timestamp(form.expiration_time),
+    }
+    return Response(json.dumps(payload, ensure_ascii=False), mimetype="application/json")
+
+
+def _ensure_form_belongs_to_app(form: Form, app_model: App) -> None:
+    if form.app_id != app_model.id or form.tenant_id != app_model.tenant_id:
+        raise NotFound("Form not found")
+
+
+@service_api_ns.route("/form/human_input/<string:form_token>")
+class WorkflowHumanInputFormApi(Resource):
+    @service_api_ns.doc("get_human_input_form")
+    @service_api_ns.doc(description="Get a paused human input form by token")
+    @service_api_ns.doc(params={"form_token": "Human input form token"})
+    @service_api_ns.doc(
+        responses={
+            200: "Form retrieved successfully",
+            401: "Unauthorized - invalid API token",
+            404: "Form not found",
+            412: "Form already submitted or expired",
+        }
+    )
+    @validate_app_token
+    def get(self, app_model: App, form_token: str):
+        service = HumanInputService(db.engine)
+        form = service.get_form_by_token(form_token)
+        if form is None:
+            raise NotFound("Form not found")
+
+        _ensure_form_belongs_to_app(form, app_model)
+        service.ensure_form_active(form)
+        return _jsonify_form_definition(form)
+
+    @service_api_ns.expect(service_api_ns.models[HumanInputFormSubmitPayload.__name__])
+    @service_api_ns.doc("submit_human_input_form")
+    @service_api_ns.doc(description="Submit a paused human input form by token")
+    @service_api_ns.doc(params={"form_token": "Human input form token"})
+    @service_api_ns.doc(
+        responses={
+            200: "Form submitted successfully",
+            400: "Bad request - invalid submission data",
+            401: "Unauthorized - invalid API token",
+            404: "Form not found",
+            412: "Form already submitted or expired",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, form_token: str):
+        payload = HumanInputFormSubmitPayload.model_validate(service_api_ns.payload or {})
+
+        service = HumanInputService(db.engine)
+        form = service.get_form_by_token(form_token)
+        if form is None:
+            raise NotFound("Form not found")
+
+        _ensure_form_belongs_to_app(form, app_model)
+
+        recipient_type = form.recipient_type
+        if recipient_type is None:
+            logger.warning("Recipient type is None for form, form_id=%s", form.id)
+            raise InternalServerError("Form recipient type is invalid")
+
+        try:
+            service.submit_form_by_token(
+                recipient_type=recipient_type,
+                form_token=form_token,
+                selected_action_id=payload.action,
+                form_data=payload.inputs,
+                submission_end_user_id=end_user.id,
+            )
+        except FormNotFoundError:
+            raise NotFound("Form not found")
+
+        return {}, 200

api/controllers/service_api/app/workflow_events.py

@@ -0,0 +1,133 @@
+"""
+Service API workflow resume event stream endpoints.
+"""
+
+import json
+from collections.abc import Generator
+
+from flask import Response, request
+from flask_restx import Resource
+from sqlalchemy.orm import sessionmaker
+from werkzeug.exceptions import NotFound
+
+from controllers.service_api import service_api_ns
+from controllers.service_api.app.error import NotWorkflowAppError
+from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
+from core.app.apps.advanced_chat.app_generator import AdvancedChatAppGenerator
+from core.app.apps.base_app_generator import BaseAppGenerator
+from core.app.apps.common.workflow_response_converter import WorkflowResponseConverter
+from core.app.apps.message_generator import MessageGenerator
+from core.app.apps.workflow.app_generator import WorkflowAppGenerator
+from extensions.ext_database import db
+from models.enums import CreatorUserRole
+from models.model import App, AppMode, EndUser
+from repositories.factory import DifyAPIRepositoryFactory
+from services.workflow_event_snapshot_service import build_workflow_event_stream
+
+
+@service_api_ns.route("/workflow/<string:task_id>/events")
+class WorkflowEventsApi(Resource):
+    """Service API for getting workflow execution events after resume."""
+
+    @service_api_ns.doc("get_workflow_events")
+    @service_api_ns.doc(description="Get workflow execution events stream after resume")
+    @service_api_ns.doc(
+        params={
+            "task_id": "Workflow run ID",
+            "user": "End user identifier (query param)",
+            "include_state_snapshot": "Whether to replay from persisted state snapshot",
+            "continue_on_pause": "Whether to keep the stream open across workflow_paused events",
+        }
+    )
+    @service_api_ns.doc(
+        responses={
+            200: "SSE event stream",
+            401: "Unauthorized - invalid API token",
+            404: "Workflow run not found",
+        }
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY, required=True))
+    def get(self, app_model: App, end_user: EndUser, task_id: str):
+        app_mode = AppMode.value_of(app_model.mode)
+        if app_mode not in {AppMode.WORKFLOW, AppMode.ADVANCED_CHAT}:
+            raise NotWorkflowAppError()
+
+        session_maker = sessionmaker(db.engine)
+        repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
+        workflow_run = repo.get_workflow_run_by_id_and_tenant_id(
+            tenant_id=app_model.tenant_id,
+            run_id=task_id,
+        )
+
+        if workflow_run is None:
+            raise NotFound("Workflow run not found")
+
+        if workflow_run.app_id != app_model.id:
+            raise NotFound("Workflow run not found")
+
+        if workflow_run.created_by_role != CreatorUserRole.END_USER:
+            raise NotFound("Workflow run not found")
+
+        if workflow_run.created_by != end_user.id:
+            raise NotFound("Workflow run not found")
+
+        workflow_run_entity = workflow_run
+
+        if workflow_run_entity.finished_at is not None:
+            response = WorkflowResponseConverter.workflow_run_result_to_finish_response(
+                task_id=workflow_run_entity.id,
+                workflow_run=workflow_run_entity,
+                creator_user=end_user,
+            )
+
+            payload = response.model_dump(mode="json")
+            payload["event"] = response.event.value
+
+            def _generate_finished_events() -> Generator[str, None, None]:
+                yield f"data: {json.dumps(payload)}\n\n"
+
+            event_generator = _generate_finished_events
+        else:
+            msg_generator = MessageGenerator()
+            generator: BaseAppGenerator
+            if app_mode == AppMode.ADVANCED_CHAT:
+                generator = AdvancedChatAppGenerator()
+            elif app_mode == AppMode.WORKFLOW:
+                generator = WorkflowAppGenerator()
+            else:
+                raise NotWorkflowAppError()
+
+            include_state_snapshot = request.args.get("include_state_snapshot", "false").lower() == "true"
+            continue_on_pause = request.args.get("continue_on_pause", "false").lower() == "true"
+            terminal_events = ["workflow_finished"] if continue_on_pause else None
+
+            def _generate_stream_events():
+                if include_state_snapshot:
+                    return generator.convert_to_event_stream(
+                        build_workflow_event_stream(
+                            app_mode=app_mode,
+                            workflow_run=workflow_run_entity,
+                            tenant_id=app_model.tenant_id,
+                            app_id=app_model.id,
+                            session_maker=session_maker,
+                            close_on_pause=not continue_on_pause,
+                        )
+                    )
+                return generator.convert_to_event_stream(
+                    msg_generator.retrieve_events(
+                        app_mode,
+                        workflow_run_entity.id,
+                        terminal_events=terminal_events,
+                    ),
+                )
+
+            event_generator = _generate_stream_events
+
+        return Response(
+            event_generator(),
+            mimetype="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )

api/core/app/apps/advanced_chat/app_generator.py

@@ -39,7 +39,11 @@ from core.app.apps.exc import GenerateTaskStoppedError
 from core.app.apps.message_based_app_generator import MessageBasedAppGenerator
 from core.app.apps.message_based_app_queue_manager import MessageBasedAppQueueManager
 from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity, InvokeFrom
-from core.app.entities.task_entities import ChatbotAppBlockingResponse, ChatbotAppStreamResponse
+from core.app.entities.task_entities import (
+    ChatbotAppBlockingResponse,
+    ChatbotAppPausedBlockingResponse,
+    ChatbotAppStreamResponse,
+)
 from core.app.layers.pause_state_persist_layer import PauseStateLayerConfig, PauseStatePersistenceLayer
 from core.helper.trace_id_helper import extract_external_trace_id_from_args
 from core.ops.ops_trace_manager import TraceQueueManager
@@ -656,7 +660,11 @@ class AdvancedChatAppGenerator(MessageBasedAppGenerator):
         user: Account | EndUser,
         draft_var_saver_factory: DraftVariableSaverFactory,
         stream: bool = False,
-    ) -> ChatbotAppBlockingResponse | Generator[ChatbotAppStreamResponse, None, None]:
+    ) -> (
+        ChatbotAppBlockingResponse
+        | ChatbotAppPausedBlockingResponse
+        | Generator[ChatbotAppStreamResponse, None, None]
+    ):
         """
         Handle response.
         :param application_generate_entity: application generate entity

api/core/app/apps/advanced_chat/generate_response_converter.py

@@ -3,9 +3,9 @@ from typing import Any, cast
 
 from core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverter
 from core.app.entities.task_entities import (
-    AppBlockingResponse,
     AppStreamResponse,
     ChatbotAppBlockingResponse,
+    ChatbotAppPausedBlockingResponse,
     ChatbotAppStreamResponse,
     ErrorStreamResponse,
     MessageEndStreamResponse,
@@ -14,17 +14,35 @@ from core.app.entities.task_entities import (
     PingStreamResponse,
 )
 
-
-class AdvancedChatAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = ChatbotAppBlockingResponse
+class AdvancedChatAppGenerateResponseConverter(
+    AppGenerateResponseConverter[ChatbotAppBlockingResponse | ChatbotAppPausedBlockingResponse]
+):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: AppBlockingResponse) -> dict[str, Any]:
+    def convert_blocking_full_response(
+        cls, blocking_response: ChatbotAppBlockingResponse | ChatbotAppPausedBlockingResponse
+    ) -> dict[str, Any]:
         """
         Convert blocking full response.
         :param blocking_response: blocking response
         :return:
         """
+        if isinstance(blocking_response, ChatbotAppPausedBlockingResponse):
+            paused_data = blocking_response.data.model_dump(mode="json")
+            return {
+                "event": "workflow_paused",
+                "task_id": blocking_response.task_id,
+                "id": blocking_response.data.id,
+                "message_id": blocking_response.data.message_id,
+                "conversation_id": blocking_response.data.conversation_id,
+                "mode": blocking_response.data.mode,
+                "answer": blocking_response.data.answer,
+                "metadata": blocking_response.data.metadata,
+                "created_at": blocking_response.data.created_at,
+                "workflow_run_id": blocking_response.data.workflow_run_id,
+                "data": paused_data,
+            }
+
         blocking_response = cast(ChatbotAppBlockingResponse, blocking_response)
         response = {
             "event": "message",
@@ -41,7 +59,9 @@ class AdvancedChatAppGenerateResponseConverter(AppGenerateResponseConverter):
         return response
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: AppBlockingResponse) -> dict[str, Any]:
+    def convert_blocking_simple_response(
+        cls, blocking_response: ChatbotAppBlockingResponse | ChatbotAppPausedBlockingResponse
+    ) -> dict[str, Any]:
         """
         Convert blocking simple response.
         :param blocking_response: blocking response
@@ -50,7 +70,8 @@ class AdvancedChatAppGenerateResponseConverter(AppGenerateResponseConverter):
         response = cls.convert_blocking_full_response(blocking_response)
 
         metadata = response.get("metadata", {})
-        response["metadata"] = cls._get_simple_metadata(metadata)
+        if isinstance(metadata, dict):
+            response["metadata"] = cls._get_simple_metadata(metadata)
 
         return response
 

api/core/app/apps/advanced_chat/generate_task_pipeline.py

@@ -9,7 +9,7 @@ from datetime import datetime
 from threading import Thread
 from typing import Any, Union
 
-from graphon.entities.pause_reason import HumanInputRequired
+from graphon.entities.pause_reason import HumanInputRequired, PauseReasonType
 from graphon.enums import WorkflowExecutionStatus
 from graphon.model_runtime.entities.llm_entities import LLMUsage
 from graphon.model_runtime.utils.encoders import jsonable_encoder
@@ -60,14 +60,17 @@ from core.app.entities.queue_entities import (
 )
 from core.app.entities.task_entities import (
     ChatbotAppBlockingResponse,
+    ChatbotAppPausedBlockingResponse,
     ChatbotAppStreamResponse,
     ErrorStreamResponse,
+    HumanInputRequiredResponse,
     MessageAudioEndStreamResponse,
     MessageAudioStreamResponse,
     MessageEndStreamResponse,
     PingStreamResponse,
     StreamResponse,
     WorkflowTaskState,
+    WorkflowPauseStreamResponse,
 )
 from core.app.task_pipeline.based_generate_task_pipeline import BasedGenerateTaskPipeline
 from core.app.task_pipeline.message_cycle_manager import MessageCycleManager
@@ -210,7 +213,13 @@ class AdvancedChatAppGenerateTaskPipeline(GraphRuntimeStateSupport):
         if message.status == MessageStatus.PAUSED and message.answer:
             self._task_state.answer = message.answer
 
-    def process(self) -> Union[ChatbotAppBlockingResponse, Generator[ChatbotAppStreamResponse, None, None]]:
+    def process(
+        self,
+    ) -> Union[
+        ChatbotAppBlockingResponse,
+        ChatbotAppPausedBlockingResponse,
+        Generator[ChatbotAppStreamResponse, None, None],
+    ]:
         """
         Process generate task pipeline.
         :return:
@@ -226,14 +235,39 @@ class AdvancedChatAppGenerateTaskPipeline(GraphRuntimeStateSupport):
         else:
             return self._to_blocking_response(generator)
 
-    def _to_blocking_response(self, generator: Generator[StreamResponse, None, None]) -> ChatbotAppBlockingResponse:
+    def _to_blocking_response(
+        self, generator: Generator[StreamResponse, None, None]
+    ) -> Union[ChatbotAppBlockingResponse, ChatbotAppPausedBlockingResponse]:
         """
         Process blocking response.
         :return:
         """
+        human_input_responses: list[HumanInputRequiredResponse] = []
         for stream_response in generator:
             if isinstance(stream_response, ErrorStreamResponse):
                 raise stream_response.err
+            elif isinstance(stream_response, HumanInputRequiredResponse):
+                human_input_responses.append(stream_response)
+            elif isinstance(stream_response, WorkflowPauseStreamResponse):
+                return ChatbotAppPausedBlockingResponse(
+                    task_id=stream_response.task_id,
+                    data=ChatbotAppPausedBlockingResponse.Data(
+                        id=self._message_id,
+                        mode=self._conversation_mode,
+                        conversation_id=self._conversation_id,
+                        message_id=self._message_id,
+                        workflow_run_id=stream_response.data.workflow_run_id,
+                        answer=self._task_state.answer,
+                        metadata=self._message_end_to_stream_response().metadata,
+                        created_at=self._message_created_at,
+                        paused_nodes=stream_response.data.paused_nodes,
+                        reasons=stream_response.data.reasons,
+                        status=stream_response.data.status,
+                        elapsed_time=stream_response.data.elapsed_time,
+                        total_tokens=stream_response.data.total_tokens,
+                        total_steps=stream_response.data.total_steps,
+                    ),
+                )
             elif isinstance(stream_response, MessageEndStreamResponse):
                 extras = {}
                 if stream_response.metadata:
@@ -254,8 +288,42 @@ class AdvancedChatAppGenerateTaskPipeline(GraphRuntimeStateSupport):
             else:
                 continue
 
+        if human_input_responses:
+            return self._build_paused_blocking_response_from_human_input(human_input_responses)
+
         raise ValueError("queue listening stopped unexpectedly.")
 
+    def _build_paused_blocking_response_from_human_input(
+        self, human_input_responses: list[HumanInputRequiredResponse]
+    ) -> ChatbotAppPausedBlockingResponse:
+        runtime_state = self._resolve_graph_runtime_state()
+        paused_nodes = list(dict.fromkeys(response.data.node_id for response in human_input_responses))
+        reasons = []
+        for response in human_input_responses:
+            reason = response.data.model_dump(mode="json")
+            reason["type"] = PauseReasonType.HUMAN_INPUT_REQUIRED
+            reasons.append(reason)
+
+        return ChatbotAppPausedBlockingResponse(
+            task_id=self._application_generate_entity.task_id,
+            data=ChatbotAppPausedBlockingResponse.Data(
+                id=self._message_id,
+                mode=self._conversation_mode,
+                conversation_id=self._conversation_id,
+                message_id=self._message_id,
+                workflow_run_id=human_input_responses[-1].workflow_run_id,
+                answer=self._task_state.answer,
+                metadata=self._message_end_to_stream_response().metadata,
+                created_at=self._message_created_at,
+                paused_nodes=paused_nodes,
+                reasons=reasons,
+                status=WorkflowExecutionStatus.PAUSED,
+                elapsed_time=time.perf_counter() - self._base_task_pipeline.start_at,
+                total_tokens=runtime_state.total_tokens,
+                total_steps=runtime_state.node_run_steps,
+            ),
+        )
+
     def _to_stream_response(
         self, generator: Generator[StreamResponse, None, None]
     ) -> Generator[ChatbotAppStreamResponse, Any, None]:

api/core/app/apps/agent_chat/generate_response_converter.py

@@ -12,11 +12,10 @@ from core.app.entities.task_entities import (
 )
 
 
-class AgentChatAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = ChatbotAppBlockingResponse
+class AgentChatAppGenerateResponseConverter(AppGenerateResponseConverter[ChatbotAppBlockingResponse]):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: ChatbotAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_full_response(cls, blocking_response: ChatbotAppBlockingResponse):
         """
         Convert blocking full response.
         :param blocking_response: blocking response
@@ -37,7 +36,7 @@ class AgentChatAppGenerateResponseConverter(AppGenerateResponseConverter):
         return response
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: ChatbotAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_simple_response(cls, blocking_response: ChatbotAppBlockingResponse):
         """
         Convert blocking simple response.
         :param blocking_response: blocking response

api/core/app/apps/base_app_generate_response_converter.py

@@ -1,7 +1,7 @@
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import Generator, Mapping
-from typing import Any, Union
+from typing import Any, Generic, TypeVar, Union, cast
 
 from graphon.model_runtime.errors.invoke import InvokeError
 
@@ -12,8 +12,13 @@ from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotIni
 logger = logging.getLogger(__name__)
 
 
-class AppGenerateResponseConverter(ABC):
-    _blocking_response_type: type[AppBlockingResponse]
+TBlockingResponse = TypeVar("TBlockingResponse", bound=AppBlockingResponse)
+
+
+class AppGenerateResponseConverter(Generic[TBlockingResponse], ABC):
+    @classmethod
+    def _cast_blocking_response(cls, response: AppBlockingResponse) -> TBlockingResponse:
+        return cast(TBlockingResponse, response)
 
     @classmethod
     def convert(
@@ -21,7 +26,7 @@ class AppGenerateResponseConverter(ABC):
     ) -> Mapping[str, Any] | Generator[str | Mapping[str, Any], Any, None]:
         if invoke_from in {InvokeFrom.DEBUGGER, InvokeFrom.SERVICE_API}:
             if isinstance(response, AppBlockingResponse):
-                return cls.convert_blocking_full_response(response)
+                return cls.convert_blocking_full_response(cls._cast_blocking_response(response))
             else:
 
                 def _generate_full_response() -> Generator[dict[str, Any] | str, Any, None]:
@@ -30,7 +35,7 @@ class AppGenerateResponseConverter(ABC):
                 return _generate_full_response()
         else:
             if isinstance(response, AppBlockingResponse):
-                return cls.convert_blocking_simple_response(response)
+                return cls.convert_blocking_simple_response(cls._cast_blocking_response(response))
             else:
 
                 def _generate_simple_response() -> Generator[dict[str, Any] | str, Any, None]:
@@ -40,12 +45,12 @@ class AppGenerateResponseConverter(ABC):
 
     @classmethod
     @abstractmethod
-    def convert_blocking_full_response(cls, blocking_response: AppBlockingResponse) -> dict[str, Any]:
+    def convert_blocking_full_response(cls, blocking_response: TBlockingResponse) -> dict[str, Any]:
         raise NotImplementedError
 
     @classmethod
     @abstractmethod
-    def convert_blocking_simple_response(cls, blocking_response: AppBlockingResponse) -> dict[str, Any]:
+    def convert_blocking_simple_response(cls, blocking_response: TBlockingResponse) -> dict[str, Any]:
         raise NotImplementedError
 
     @classmethod

api/core/app/apps/chat/generate_response_converter.py

@@ -12,11 +12,10 @@ from core.app.entities.task_entities import (
 )
 
 
-class ChatAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = ChatbotAppBlockingResponse
+class ChatAppGenerateResponseConverter(AppGenerateResponseConverter[ChatbotAppBlockingResponse]):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: ChatbotAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_full_response(cls, blocking_response: ChatbotAppBlockingResponse):
         """
         Convert blocking full response.
         :param blocking_response: blocking response
@@ -37,7 +36,7 @@ class ChatAppGenerateResponseConverter(AppGenerateResponseConverter):
         return response
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: ChatbotAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_simple_response(cls, blocking_response: ChatbotAppBlockingResponse):
         """
         Convert blocking simple response.
         :param blocking_response: blocking response

api/core/app/apps/common/pause_reason_serializer.py

@@ -0,0 +1,17 @@
+from collections.abc import Mapping
+from typing import Any
+
+from graphon.entities.pause_reason import PauseReason
+
+
+def pause_reason_to_public_dict(reason: PauseReason | Mapping[str, Any]) -> dict[str, Any]:
+    if isinstance(reason, Mapping):
+        data = dict(reason)
+    else:
+        data = dict(reason.model_dump(mode="json"))
+
+    discriminator = data.pop("TYPE", None)
+    if discriminator is not None:
+        data["type"] = discriminator
+
+    return data

api/core/app/apps/common/workflow_response_converter.py

@@ -22,6 +22,7 @@ from graphon.workflow_type_encoder import WorkflowRuntimeTypeConverter
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from core.app.apps.common.pause_reason_serializer import pause_reason_to_public_dict
 from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity, InvokeFrom, WorkflowAppGenerateEntity
 from core.app.entities.queue_entities import (
     QueueAgentLogEvent,
@@ -317,7 +318,7 @@ class WorkflowResponseConverter:
         encoded_outputs = self._encode_outputs(event.outputs) or {}
         if self._application_generate_entity.invoke_from == InvokeFrom.SERVICE_API:
             encoded_outputs = {}
-        pause_reasons = [reason.model_dump(mode="json") for reason in event.reasons]
+        pause_reasons = [pause_reason_to_public_dict(reason) for reason in event.reasons]
         human_input_form_ids = [reason.form_id for reason in event.reasons if isinstance(reason, HumanInputRequired)]
         expiration_times_by_form_id: dict[str, datetime] = {}
         display_in_ui_by_form_id: dict[str, bool] = {}
@@ -338,6 +339,21 @@ class WorkflowResponseConverter:
                     display_in_ui_by_form_id[str(form_id)] = bool(definition_payload.get("display_in_ui"))
                 form_token_by_form_id = load_form_tokens_by_form_id(human_input_form_ids, session=session)
 
+        for pause_reason in pause_reasons:
+            if pause_reason.get("type") != "human_input_required":
+                continue
+
+            form_id = pause_reason.get("form_id")
+            if not isinstance(form_id, str):
+                continue
+
+            expiration_time = expiration_times_by_form_id.get(form_id)
+            if expiration_time is None:
+                raise ValueError(f"HumanInputForm not found for pause reason, form_id={form_id}")
+
+            pause_reason["form_token"] = form_token_by_form_id.get(form_id)
+            pause_reason["expiration_time"] = int(expiration_time.timestamp())
+
         responses: list[StreamResponse] = []
 
         for reason in event.reasons:

api/core/app/apps/completion/generate_response_converter.py

@@ -12,11 +12,10 @@ from core.app.entities.task_entities import (
 )
 
 
-class CompletionAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = CompletionAppBlockingResponse
+class CompletionAppGenerateResponseConverter(AppGenerateResponseConverter[CompletionAppBlockingResponse]):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: CompletionAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_full_response(cls, blocking_response: CompletionAppBlockingResponse):
         """
         Convert blocking full response.
         :param blocking_response: blocking response
@@ -36,7 +35,7 @@ class CompletionAppGenerateResponseConverter(AppGenerateResponseConverter):
         return response
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: CompletionAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_simple_response(cls, blocking_response: CompletionAppBlockingResponse):
         """
         Convert blocking simple response.
         :param blocking_response: blocking response

api/core/app/apps/message_generator.py

@@ -1,5 +1,6 @@
-from collections.abc import Callable, Generator, Mapping
+from collections.abc import Callable, Generator, Iterable, Mapping
 
+from core.app.entities.task_entities import StreamEvent
 from core.app.apps.streaming_utils import stream_topic_events
 from extensions.ext_redis import get_pubsub_broadcast_channel
 from libs.broadcast_channel.channel import Topic
@@ -26,6 +27,7 @@ class MessageGenerator:
         idle_timeout=300,
         ping_interval: float = 10.0,
         on_subscribe: Callable[[], None] | None = None,
+        terminal_events: Iterable[str | StreamEvent] | None = None,
     ) -> Generator[Mapping | str, None, None]:
         topic = cls.get_response_topic(app_mode, workflow_run_id)
         return stream_topic_events(
@@ -33,4 +35,5 @@ class MessageGenerator:
             idle_timeout=idle_timeout,
             ping_interval=ping_interval,
             on_subscribe=on_subscribe,
+            terminal_events=terminal_events,
         )

api/core/app/apps/pipeline/generate_response_converter.py

@@ -13,11 +13,10 @@ from core.app.entities.task_entities import (
 )
 
 
-class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = WorkflowAppBlockingResponse
+class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter[WorkflowAppBlockingResponse]):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, Any]:  # type: ignore[override]
+    def convert_blocking_full_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
         """
         Convert blocking full response.
         :param blocking_response: blocking response
@@ -26,7 +25,7 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter):
         return dict(blocking_response.model_dump())
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, Any]:  # type: ignore[override]
+    def convert_blocking_simple_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
         """
         Convert blocking simple response.
         :param blocking_response: blocking response

api/core/app/apps/workflow/app_generator.py

@@ -29,7 +29,11 @@ from core.app.apps.workflow.app_runner import WorkflowAppRunner
 from core.app.apps.workflow.generate_response_converter import WorkflowAppGenerateResponseConverter
 from core.app.apps.workflow.generate_task_pipeline import WorkflowAppGenerateTaskPipeline
 from core.app.entities.app_invoke_entities import InvokeFrom, WorkflowAppGenerateEntity
-from core.app.entities.task_entities import WorkflowAppBlockingResponse, WorkflowAppStreamResponse
+from core.app.entities.task_entities import (
+    WorkflowAppBlockingResponse,
+    WorkflowAppPausedBlockingResponse,
+    WorkflowAppStreamResponse,
+)
 from core.app.layers.pause_state_persist_layer import PauseStateLayerConfig, PauseStatePersistenceLayer
 from core.db.session_factory import session_factory
 from core.helper.trace_id_helper import extract_external_trace_id_from_args
@@ -612,7 +616,11 @@ class WorkflowAppGenerator(BaseAppGenerator):
         user: Account | EndUser,
         draft_var_saver_factory: DraftVariableSaverFactory,
         stream: bool = False,
-    ) -> WorkflowAppBlockingResponse | Generator[WorkflowAppStreamResponse, None, None]:
+    ) -> (
+        WorkflowAppBlockingResponse
+        | WorkflowAppPausedBlockingResponse
+        | Generator[WorkflowAppStreamResponse, None, None]
+    ):
         """
         Handle response.
         :param application_generate_entity: application generate entity

api/core/app/apps/workflow/generate_response_converter.py

@@ -1,6 +1,8 @@
 from collections.abc import Generator
 from typing import Any, cast
 
+from typing import Any, cast
+
 from core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverter
 from core.app.entities.task_entities import (
     AppStreamResponse,
@@ -9,24 +11,30 @@ from core.app.entities.task_entities import (
     NodeStartStreamResponse,
     PingStreamResponse,
     WorkflowAppBlockingResponse,
+    WorkflowAppPausedBlockingResponse,
     WorkflowAppStreamResponse,
 )
 
 
-class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter):
-    _blocking_response_type = WorkflowAppBlockingResponse
+class WorkflowAppGenerateResponseConverter(
+    AppGenerateResponseConverter[WorkflowAppBlockingResponse | WorkflowAppPausedBlockingResponse]
+):
 
     @classmethod
-    def convert_blocking_full_response(cls, blocking_response: WorkflowAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_full_response(
+        cls, blocking_response: WorkflowAppBlockingResponse | WorkflowAppPausedBlockingResponse
+    ) -> dict[str, Any]:
         """
         Convert blocking full response.
         :param blocking_response: blocking response
         :return:
         """
-        return blocking_response.model_dump()
+        return dict(blocking_response.model_dump())
 
     @classmethod
-    def convert_blocking_simple_response(cls, blocking_response: WorkflowAppBlockingResponse):  # type: ignore[override]
+    def convert_blocking_simple_response(
+        cls, blocking_response: WorkflowAppBlockingResponse | WorkflowAppPausedBlockingResponse
+    ) -> dict[str, Any]:
         """
         Convert blocking simple response.
         :param blocking_response: blocking response
@@ -58,7 +66,7 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter):
 
             if isinstance(sub_stream_response, ErrorStreamResponse):
                 data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
+                response_chunk.update(cast(dict[str, object], data))
             else:
                 response_chunk.update(sub_stream_response.model_dump(mode="json"))
             yield response_chunk
@@ -87,9 +95,9 @@ class WorkflowAppGenerateResponseConverter(AppGenerateResponseConverter):
 
             if isinstance(sub_stream_response, ErrorStreamResponse):
                 data = cls._error_to_stream_response(sub_stream_response.err)
-                response_chunk.update(data)
+                response_chunk.update(cast(dict[str, object], data))
             elif isinstance(sub_stream_response, NodeStartStreamResponse | NodeFinishStreamResponse):
-                response_chunk.update(sub_stream_response.to_ignore_detail_dict())
+                response_chunk.update(cast(dict[str, object], sub_stream_response.to_ignore_detail_dict()))
             else:
                 response_chunk.update(sub_stream_response.model_dump(mode="json"))
             yield response_chunk

api/core/app/apps/workflow/generate_task_pipeline.py

@@ -45,12 +45,14 @@ from core.app.entities.queue_entities import (
 )
 from core.app.entities.task_entities import (
     ErrorStreamResponse,
+    HumanInputRequiredResponse,
     MessageAudioEndStreamResponse,
     MessageAudioStreamResponse,
     PingStreamResponse,
     StreamResponse,
     TextChunkStreamResponse,
     WorkflowAppBlockingResponse,
+    WorkflowAppPausedBlockingResponse,
     WorkflowAppStreamResponse,
     WorkflowFinishStreamResponse,
     WorkflowPauseStreamResponse,
@@ -118,7 +120,9 @@ class WorkflowAppGenerateTaskPipeline(GraphRuntimeStateSupport):
         )
         self._graph_runtime_state: GraphRuntimeState | None = self._base_task_pipeline.queue_manager.graph_runtime_state
 
-    def process(self) -> Union[WorkflowAppBlockingResponse, Generator[WorkflowAppStreamResponse, None, None]]:
+    def process(
+        self,
+    ) -> Union[WorkflowAppBlockingResponse, WorkflowAppPausedBlockingResponse, Generator[WorkflowAppStreamResponse, None, None]]:
         """
         Process generate task pipeline.
         :return:
@@ -129,19 +133,24 @@ class WorkflowAppGenerateTaskPipeline(GraphRuntimeStateSupport):
         else:
             return self._to_blocking_response(generator)
 
-    def _to_blocking_response(self, generator: Generator[StreamResponse, None, None]) -> WorkflowAppBlockingResponse:
+    def _to_blocking_response(
+        self, generator: Generator[StreamResponse, None, None]
+    ) -> Union[WorkflowAppBlockingResponse, WorkflowAppPausedBlockingResponse]:
         """
         To blocking response.
         :return:
         """
+        human_input_responses: list[HumanInputRequiredResponse] = []
         for stream_response in generator:
             if isinstance(stream_response, ErrorStreamResponse):
                 raise stream_response.err
+            elif isinstance(stream_response, HumanInputRequiredResponse):
+                human_input_responses.append(stream_response)
             elif isinstance(stream_response, WorkflowPauseStreamResponse):
-                response = WorkflowAppBlockingResponse(
+                response = WorkflowAppPausedBlockingResponse(
                     task_id=self._application_generate_entity.task_id,
                     workflow_run_id=stream_response.data.workflow_run_id,
-                    data=WorkflowAppBlockingResponse.Data(
+                    data=WorkflowAppPausedBlockingResponse.Data(
                         id=stream_response.data.workflow_run_id,
                         workflow_id=self._workflow.id,
                         status=stream_response.data.status,
@@ -152,6 +161,8 @@ class WorkflowAppGenerateTaskPipeline(GraphRuntimeStateSupport):
                         total_steps=stream_response.data.total_steps,
                         created_at=stream_response.data.created_at,
                         finished_at=None,
+                        paused_nodes=stream_response.data.paused_nodes,
+                        reasons=stream_response.data.reasons,
                     ),
                 )
 
@@ -178,8 +189,41 @@ class WorkflowAppGenerateTaskPipeline(GraphRuntimeStateSupport):
             else:
                 continue
 
+        if human_input_responses:
+            return self._build_paused_blocking_response_from_human_input(human_input_responses)
+
         raise ValueError("queue listening stopped unexpectedly.")
 
+    def _build_paused_blocking_response_from_human_input(
+        self, human_input_responses: list[HumanInputRequiredResponse]
+    ) -> WorkflowAppPausedBlockingResponse:
+        runtime_state = self._resolve_graph_runtime_state()
+        paused_nodes = list(dict.fromkeys(response.data.node_id for response in human_input_responses))
+        reasons = []
+        for response in human_input_responses:
+            reason = response.data.model_dump(mode="json")
+            reason["type"] = "human_input_required"
+            reasons.append(reason)
+
+        return WorkflowAppPausedBlockingResponse(
+            task_id=self._application_generate_entity.task_id,
+            workflow_run_id=human_input_responses[-1].workflow_run_id,
+            data=WorkflowAppPausedBlockingResponse.Data(
+                id=human_input_responses[-1].workflow_run_id,
+                workflow_id=self._workflow.id,
+                status=WorkflowExecutionStatus.PAUSED,
+                outputs={},
+                error=None,
+                elapsed_time=time.perf_counter() - self._base_task_pipeline.start_at,
+                total_tokens=runtime_state.total_tokens,
+                total_steps=runtime_state.node_run_steps,
+                created_at=int(runtime_state.start_at),
+                finished_at=None,
+                paused_nodes=paused_nodes,
+                reasons=reasons,
+            ),
+        )
+
     def _to_stream_response(
         self, generator: Generator[StreamResponse, None, None]
     ) -> Generator[WorkflowAppStreamResponse, None, None]:

api/core/app/entities/task_entities.py

@@ -774,6 +774,34 @@ class ChatbotAppBlockingResponse(AppBlockingResponse):
     data: Data
 
 
+class ChatbotAppPausedBlockingResponse(AppBlockingResponse):
+    """
+    ChatbotAppPausedBlockingResponse entity
+    """
+
+    class Data(BaseModel):
+        """
+        Data entity
+        """
+
+        id: str
+        mode: str
+        conversation_id: str
+        message_id: str
+        workflow_run_id: str
+        answer: str
+        metadata: Mapping[str, object] = Field(default_factory=dict)
+        created_at: int
+        paused_nodes: Sequence[str] = Field(default_factory=list)
+        reasons: Sequence[Mapping[str, Any]] = Field(default_factory=list)
+        status: WorkflowExecutionStatus
+        elapsed_time: float
+        total_tokens: int
+        total_steps: int
+
+    data: Data
+
+
 class CompletionAppBlockingResponse(AppBlockingResponse):
     """
     CompletionAppBlockingResponse entity
@@ -819,6 +847,33 @@ class WorkflowAppBlockingResponse(AppBlockingResponse):
     data: Data
 
 
+class WorkflowAppPausedBlockingResponse(AppBlockingResponse):
+    """
+    WorkflowAppPausedBlockingResponse entity
+    """
+
+    class Data(BaseModel):
+        """
+        Data entity
+        """
+
+        id: str
+        workflow_id: str
+        status: WorkflowExecutionStatus
+        outputs: Mapping[str, Any] | None = None
+        error: str | None = None
+        elapsed_time: float
+        total_tokens: int
+        total_steps: int
+        created_at: int
+        finished_at: int | None
+        paused_nodes: Sequence[str] = Field(default_factory=list)
+        reasons: Sequence[Mapping[str, Any]] = Field(default_factory=list)
+
+    workflow_run_id: str
+    data: Data
+
+
 class AgentLogStreamResponse(StreamResponse):
     """
     AgentLogStreamResponse entity

api/docker/entrypoint.sh

@@ -35,10 +35,10 @@ if [[ "${MODE}" == "worker" ]]; then
   if [[ -z "${CELERY_QUEUES}" ]]; then
     if [[ "${EDITION}" == "CLOUD" ]]; then
       # Cloud edition: separate queues for dataset and trigger tasks
-      DEFAULT_QUEUES="api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow_professional,workflow_team,workflow_sandbox,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution"
+      DEFAULT_QUEUES="api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow_professional,workflow_team,workflow_sandbox,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution"
     else
       # Community edition (SELF_HOSTED): dataset, pipeline and workflow have separate queues
-      DEFAULT_QUEUES="api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution"
+      DEFAULT_QUEUES="api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution"
     fi
   else
     DEFAULT_QUEUES="${CELERY_QUEUES}"
@@ -119,14 +119,16 @@ elif [[ "${MODE}" == "job" ]]; then
 
 else
   if [[ "${DEBUG}" == "true" ]]; then
-    exec flask run --host=${DIFY_BIND_ADDRESS:-0.0.0.0} --port=${DIFY_PORT:-5001} --debug
+    export HOST=${DIFY_BIND_ADDRESS:-0.0.0.0}
+    export PORT=${DIFY_PORT:-5001}
+    exec python -m app
   else
     exec gunicorn \
       --bind "${DIFY_BIND_ADDRESS:-0.0.0.0}:${DIFY_PORT:-5001}" \
       --workers ${SERVER_WORKER_AMOUNT:-1} \
-      --worker-class ${SERVER_WORKER_CLASS:-gevent} \
+      --worker-class ${SERVER_WORKER_CLASS:-geventwebsocket.gunicorn.workers.GeventWebSocketWorker} \
       --worker-connections ${SERVER_WORKER_CONNECTIONS:-10} \
       --timeout ${GUNICORN_TIMEOUT:-200} \
-      app:app
+      app:socketio_app
   fi
 fi

api/extensions/ext_socketio.py

@@ -0,0 +1,5 @@
+import socketio  # type: ignore[reportMissingTypeStubs]
+
+from configs import dify_config
+
+sio = socketio.Server(async_mode="gevent", cors_allowed_origins=dify_config.CONSOLE_CORS_ALLOW_ORIGINS)

api/fields/online_user_fields.py

@@ -0,0 +1,16 @@
+from flask_restx import fields
+
+online_user_partial_fields = {
+    "user_id": fields.String,
+    "username": fields.String,
+    "avatar": fields.String,
+}
+
+workflow_online_users_fields = {
+    "app_id": fields.String,
+    "users": fields.List(fields.Nested(online_user_partial_fields)),
+}
+
+online_user_list_fields = {
+    "data": fields.List(fields.Nested(workflow_online_users_fields)),
+}

api/fields/workflow_comment_fields.py

@@ -0,0 +1,96 @@
+from flask_restx import fields
+
+from libs.helper import AvatarUrlField, TimestampField
+
+# basic account fields for comments
+account_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "email": fields.String,
+    "avatar_url": AvatarUrlField,
+}
+
+# Comment mention fields
+workflow_comment_mention_fields = {
+    "mentioned_user_id": fields.String,
+    "mentioned_user_account": fields.Nested(account_fields, allow_null=True),
+    "reply_id": fields.String,
+}
+
+# Comment reply fields
+workflow_comment_reply_fields = {
+    "id": fields.String,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+}
+
+# Basic comment fields (for list views)
+workflow_comment_basic_fields = {
+    "id": fields.String,
+    "position_x": fields.Float,
+    "position_y": fields.Float,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+    "updated_at": TimestampField,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+    "resolved_by_account": fields.Nested(account_fields, allow_null=True),
+    "reply_count": fields.Integer,
+    "mention_count": fields.Integer,
+    "participants": fields.List(fields.Nested(account_fields)),
+}
+
+# Detailed comment fields (for single comment view)
+workflow_comment_detail_fields = {
+    "id": fields.String,
+    "position_x": fields.Float,
+    "position_y": fields.Float,
+    "content": fields.String,
+    "created_by": fields.String,
+    "created_by_account": fields.Nested(account_fields, allow_null=True),
+    "created_at": TimestampField,
+    "updated_at": TimestampField,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+    "resolved_by_account": fields.Nested(account_fields, allow_null=True),
+    "replies": fields.List(fields.Nested(workflow_comment_reply_fields)),
+    "mentions": fields.List(fields.Nested(workflow_comment_mention_fields)),
+}
+
+# Comment creation response fields (simplified)
+workflow_comment_create_fields = {
+    "id": fields.String,
+    "created_at": TimestampField,
+}
+
+# Comment update response fields (simplified)
+workflow_comment_update_fields = {
+    "id": fields.String,
+    "updated_at": TimestampField,
+}
+
+# Comment resolve response fields
+workflow_comment_resolve_fields = {
+    "id": fields.String,
+    "resolved": fields.Boolean,
+    "resolved_at": TimestampField,
+    "resolved_by": fields.String,
+}
+
+# Reply creation response fields (simplified)
+workflow_comment_reply_create_fields = {
+    "id": fields.String,
+    "created_at": TimestampField,
+}
+
+# Reply update response fields
+workflow_comment_reply_update_fields = {
+    "id": fields.String,
+    "updated_at": TimestampField,
+}

api/libs/email_i18n.py

@@ -37,6 +37,7 @@ class EmailType(StrEnum):
     ENTERPRISE_CUSTOM = auto()
     QUEUE_MONITOR_ALERT = auto()
     DOCUMENT_CLEAN_NOTIFY = auto()
+    WORKFLOW_COMMENT_MENTION = auto()
     EMAIL_REGISTER = auto()
     EMAIL_REGISTER_WHEN_ACCOUNT_EXIST = auto()
     RESET_PASSWORD_WHEN_ACCOUNT_NOT_EXIST_NO_REGISTER = auto()
@@ -453,6 +454,18 @@ def create_default_email_config() -> EmailI18nConfig:
                 branded_template_path="clean_document_job_mail_template_zh-CN.html",
             ),
         },
+        EmailType.WORKFLOW_COMMENT_MENTION: {
+            EmailLanguage.EN_US: EmailTemplate(
+                subject="You were mentioned in a workflow comment",
+                template_path="workflow_comment_mention_template_en-US.html",
+                branded_template_path="without-brand/workflow_comment_mention_template_en-US.html",
+            ),
+            EmailLanguage.ZH_HANS: EmailTemplate(
+                subject="你在工作流评论中被提及",
+                template_path="workflow_comment_mention_template_zh-CN.html",
+                branded_template_path="without-brand/workflow_comment_mention_template_zh-CN.html",
+            ),
+        },
         EmailType.TRIGGER_EVENTS_LIMIT_SANDBOX: {
             EmailLanguage.EN_US: EmailTemplate(
                 subject="You’ve reached your Sandbox Trigger Events limit",

api/migrations/versions/2026_04_15_1726-227822d22895_add_workflow_comments_table.py

@@ -0,0 +1,90 @@
+"""Add workflow comments table
+
+Revision ID: 227822d22895
+Revises: 8574b23a38fd
+Create Date: 2025-08-22 17:26:15.255980
+
+"""
+from alembic import op
+import models as models
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '227822d22895'
+down_revision = '8574b23a38fd'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('workflow_comments',
+    sa.Column('id', models.types.StringUUID(), nullable=False),
+    sa.Column('tenant_id', models.types.StringUUID(), nullable=False),
+    sa.Column('app_id', models.types.StringUUID(), nullable=False),
+    sa.Column('position_x', sa.Float(), nullable=False),
+    sa.Column('position_y', sa.Float(), nullable=False),
+    sa.Column('content', sa.Text(), nullable=False),
+    sa.Column('created_by', models.types.StringUUID(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
+    sa.Column('resolved', sa.Boolean(), server_default=sa.text('false'), nullable=False),
+    sa.Column('resolved_at', sa.DateTime(), nullable=True),
+    sa.Column('resolved_by', models.types.StringUUID(), nullable=True),
+    sa.PrimaryKeyConstraint('id', name='workflow_comments_pkey')
+    )
+    with op.batch_alter_table('workflow_comments', schema=None) as batch_op:
+        batch_op.create_index('workflow_comments_app_idx', ['tenant_id', 'app_id'], unique=False)
+        batch_op.create_index('workflow_comments_created_at_idx', ['created_at'], unique=False)
+
+    op.create_table('workflow_comment_replies',
+    sa.Column('id', models.types.StringUUID(), nullable=False),
+    sa.Column('comment_id', models.types.StringUUID(), nullable=False),
+    sa.Column('content', sa.Text(), nullable=False),
+    sa.Column('created_by', models.types.StringUUID(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), server_default=sa.text('CURRENT_TIMESTAMP'), nullable=False),
+    sa.ForeignKeyConstraint(['comment_id'], ['workflow_comments.id'], name=op.f('workflow_comment_replies_comment_id_fkey'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name='workflow_comment_replies_pkey')
+    )
+    with op.batch_alter_table('workflow_comment_replies', schema=None) as batch_op:
+        batch_op.create_index('comment_replies_comment_idx', ['comment_id'], unique=False)
+        batch_op.create_index('comment_replies_created_at_idx', ['created_at'], unique=False)
+
+    op.create_table('workflow_comment_mentions',
+    sa.Column('id', models.types.StringUUID(), nullable=False),
+    sa.Column('comment_id', models.types.StringUUID(), nullable=False),
+    sa.Column('reply_id', models.types.StringUUID(), nullable=True),
+    sa.Column('mentioned_user_id', models.types.StringUUID(), nullable=False),
+    sa.ForeignKeyConstraint(['comment_id'], ['workflow_comments.id'], name=op.f('workflow_comment_mentions_comment_id_fkey'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['reply_id'], ['workflow_comment_replies.id'], name=op.f('workflow_comment_mentions_reply_id_fkey'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name='workflow_comment_mentions_pkey')
+    )
+    with op.batch_alter_table('workflow_comment_mentions', schema=None) as batch_op:
+        batch_op.create_index('comment_mentions_comment_idx', ['comment_id'], unique=False)
+        batch_op.create_index('comment_mentions_reply_idx', ['reply_id'], unique=False)
+        batch_op.create_index('comment_mentions_user_idx', ['mentioned_user_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('workflow_comment_mentions', schema=None) as batch_op:
+        batch_op.drop_index('comment_mentions_user_idx')
+        batch_op.drop_index('comment_mentions_reply_idx')
+        batch_op.drop_index('comment_mentions_comment_idx')
+
+    op.drop_table('workflow_comment_mentions')
+    with op.batch_alter_table('workflow_comment_replies', schema=None) as batch_op:
+        batch_op.drop_index('comment_replies_created_at_idx')
+        batch_op.drop_index('comment_replies_comment_idx')
+
+    op.drop_table('workflow_comment_replies')
+    with op.batch_alter_table('workflow_comments', schema=None) as batch_op:
+        batch_op.drop_index('workflow_comments_created_at_idx')
+        batch_op.drop_index('workflow_comments_app_idx')
+
+    op.drop_table('workflow_comments')
+    # ### end Alembic commands ###

api/models/__init__.py

@@ -9,6 +9,11 @@ from .account import (
     TenantStatus,
 )
 from .api_based_extension import APIBasedExtension, APIBasedExtensionPoint
+from .comment import (
+    WorkflowComment,
+    WorkflowCommentMention,
+    WorkflowCommentReply,
+)
 from .dataset import (
     AppDatasetJoin,
     Dataset,
@@ -208,6 +213,9 @@ __all__ = [
     "WorkflowAppLog",
     "WorkflowAppLogCreatedFrom",
     "WorkflowArchiveLog",
+    "WorkflowComment",
+    "WorkflowCommentMention",
+    "WorkflowCommentReply",
     "WorkflowNodeExecutionModel",
     "WorkflowNodeExecutionOffload",
     "WorkflowNodeExecutionTriggeredFrom",

api/models/comment.py

@@ -0,0 +1,218 @@
+"""Workflow comment models."""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import Index, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .account import Account
+from .base import Base
+from .engine import db
+from .types import StringUUID
+
+
+class WorkflowComment(Base):
+    """Workflow comment model for canvas commenting functionality.
+
+    Comments are associated with apps rather than specific workflow versions,
+    since an app has only one draft workflow at a time and comments should persist
+    across workflow version changes.
+
+    Attributes:
+        id: Comment ID
+        tenant_id: Workspace ID
+        app_id: App ID (primary association, comments belong to apps)
+        position_x: X coordinate on canvas
+        position_y: Y coordinate on canvas
+        content: Comment content
+        created_by: Creator account ID
+        created_at: Creation time
+        updated_at: Last update time
+        resolved: Whether comment is resolved
+        resolved_at: Resolution time
+        resolved_by: Resolver account ID
+    """
+
+    __tablename__ = "workflow_comments"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comments_pkey"),
+        Index("workflow_comments_app_idx", "tenant_id", "app_id"),
+        Index("workflow_comments_created_at_idx", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    position_x: Mapped[float] = mapped_column(db.Float)
+    position_y: Mapped[float] = mapped_column(db.Float)
+    content: Mapped[str] = mapped_column(db.Text, nullable=False)
+    created_by: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(db.DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_at: Mapped[datetime] = mapped_column(
+        db.DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+    resolved: Mapped[bool] = mapped_column(db.Boolean, nullable=False, server_default=db.text("false"))
+    resolved_at: Mapped[datetime | None] = mapped_column(db.DateTime)
+    resolved_by: Mapped[str | None] = mapped_column(StringUUID)
+
+    # Relationships
+    replies: Mapped[list["WorkflowCommentReply"]] = relationship(
+        "WorkflowCommentReply", back_populates="comment", cascade="all, delete-orphan"
+    )
+    mentions: Mapped[list["WorkflowCommentMention"]] = relationship(
+        "WorkflowCommentMention", back_populates="comment", cascade="all, delete-orphan"
+    )
+
+    @property
+    def created_by_account(self):
+        """Get creator account."""
+        if hasattr(self, "_created_by_account_cache"):
+            return self._created_by_account_cache
+        return db.session.get(Account, self.created_by)
+
+    def cache_created_by_account(self, account: Account | None) -> None:
+        """Cache creator account to avoid extra queries."""
+        self._created_by_account_cache = account
+
+    @property
+    def resolved_by_account(self):
+        """Get resolver account."""
+        if hasattr(self, "_resolved_by_account_cache"):
+            return self._resolved_by_account_cache
+        if self.resolved_by:
+            return db.session.get(Account, self.resolved_by)
+        return None
+
+    def cache_resolved_by_account(self, account: Account | None) -> None:
+        """Cache resolver account to avoid extra queries."""
+        self._resolved_by_account_cache = account
+
+    @property
+    def reply_count(self):
+        """Get reply count."""
+        return len(self.replies)
+
+    @property
+    def mention_count(self):
+        """Get mention count."""
+        return len(self.mentions)
+
+    @property
+    def participants(self):
+        """Get all participants (creator + repliers + mentioned users)."""
+        participant_ids: set[str] = set()
+        participants: list[Account] = []
+
+        # Use account properties to reuse preloaded caches and avoid hidden N+1.
+        if self.created_by not in participant_ids:
+            participant_ids.add(self.created_by)
+            created_by_account = self.created_by_account
+            if created_by_account:
+                participants.append(created_by_account)
+
+        for reply in self.replies:
+            if reply.created_by in participant_ids:
+                continue
+            participant_ids.add(reply.created_by)
+            reply_account = reply.created_by_account
+            if reply_account:
+                participants.append(reply_account)
+
+        for mention in self.mentions:
+            if mention.mentioned_user_id in participant_ids:
+                continue
+            participant_ids.add(mention.mentioned_user_id)
+            mentioned_account = mention.mentioned_user_account
+            if mentioned_account:
+                participants.append(mentioned_account)
+
+        return participants
+
+
+class WorkflowCommentReply(Base):
+    """Workflow comment reply model.
+
+    Attributes:
+        id: Reply ID
+        comment_id: Parent comment ID
+        content: Reply content
+        created_by: Creator account ID
+        created_at: Creation time
+    """
+
+    __tablename__ = "workflow_comment_replies"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comment_replies_pkey"),
+        Index("comment_replies_comment_idx", "comment_id"),
+        Index("comment_replies_created_at_idx", "created_at"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    comment_id: Mapped[str] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comments.id", ondelete="CASCADE"), nullable=False
+    )
+    content: Mapped[str] = mapped_column(db.Text, nullable=False)
+    created_by: Mapped[str] = mapped_column(StringUUID, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(db.DateTime, nullable=False, server_default=func.current_timestamp())
+    updated_at: Mapped[datetime] = mapped_column(
+        db.DateTime, nullable=False, server_default=func.current_timestamp(), onupdate=func.current_timestamp()
+    )
+    # Relationships
+    comment: Mapped["WorkflowComment"] = relationship("WorkflowComment", back_populates="replies")
+
+    @property
+    def created_by_account(self):
+        """Get creator account."""
+        if hasattr(self, "_created_by_account_cache"):
+            return self._created_by_account_cache
+        return db.session.get(Account, self.created_by)
+
+    def cache_created_by_account(self, account: Account | None) -> None:
+        """Cache creator account to avoid extra queries."""
+        self._created_by_account_cache = account
+
+
+class WorkflowCommentMention(Base):
+    """Workflow comment mention model.
+
+    Mentions are only for internal accounts since end users
+    cannot access workflow canvas and commenting features.
+
+    Attributes:
+        id: Mention ID
+        comment_id: Parent comment ID
+        mentioned_user_id: Mentioned account ID
+    """
+
+    __tablename__ = "workflow_comment_mentions"
+    __table_args__ = (
+        db.PrimaryKeyConstraint("id", name="workflow_comment_mentions_pkey"),
+        Index("comment_mentions_comment_idx", "comment_id"),
+        Index("comment_mentions_reply_idx", "reply_id"),
+        Index("comment_mentions_user_idx", "mentioned_user_id"),
+    )
+
+    id: Mapped[str] = mapped_column(StringUUID, server_default=db.text("uuidv7()"))
+    comment_id: Mapped[str] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comments.id", ondelete="CASCADE"), nullable=False
+    )
+    reply_id: Mapped[str | None] = mapped_column(
+        StringUUID, db.ForeignKey("workflow_comment_replies.id", ondelete="CASCADE"), nullable=True
+    )
+    mentioned_user_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
+
+    # Relationships
+    comment: Mapped["WorkflowComment"] = relationship("WorkflowComment", back_populates="mentions")
+    reply: Mapped[Optional["WorkflowCommentReply"]] = relationship("WorkflowCommentReply")
+
+    @property
+    def mentioned_user_account(self):
+        """Get mentioned account."""
+        if hasattr(self, "_mentioned_user_account_cache"):
+            return self._mentioned_user_account_cache
+        return db.session.get(Account, self.mentioned_user_id)
+
+    def cache_mentioned_user_account(self, account: Account | None) -> None:
+        """Cache mentioned account to avoid extra queries."""
+        self._mentioned_user_account_cache = account

api/models/workflow.py

@@ -490,7 +490,7 @@ class Workflow(Base):  # bug
 
         :return: hash
         """
-        entity = {"graph": self.graph_dict, "features": self.features_dict}
+        entity = {"graph": self.graph_dict}
 
         return helper.generate_text_hash(json.dumps(entity, sort_keys=True))
 

api/pyproject.toml

@@ -11,13 +11,16 @@ dependencies = [
     "croniter>=6.2.2",
     "flask-cors>=6.0.2",
     "gevent>=26.4.0",
+    "gevent-websocket>=0.10.1",
     "gmpy2>=2.3.0",
     "google-api-python-client>=2.194.0",
     "gunicorn>=25.3.0",
     "psycogreen>=1.0.2",
     "psycopg2-binary>=2.9.11",
+    "python-socketio>=5.13.0",
     "redis[hiredis]>=7.4.0",
     "sendgrid>=6.12.5",
+    "sseclient-py>=1.8.0",
 
     # Stable: production-proven, cap below the next major
     "aliyun-log-python-sdk>=0.9.44,<1.0.0",
@@ -166,7 +169,6 @@ dev = [
     "celery-types>=0.23.0",
     "mypy>=1.20.1",
     # "locust>=2.40.4",  # Temporarily removed due to compatibility issues. Uncomment when resolved.
-    "sseclient-py>=1.8.0",
     "pytest-timeout>=2.4.0",
     "pytest-xdist>=3.8.0",
     "pyrefly>=0.60.0",

api/repositories/sqlalchemy_api_workflow_run_repository.py

@@ -42,7 +42,7 @@ from libs.helper import convert_datetime_to_date
 from libs.infinite_scroll_pagination import InfiniteScrollPagination
 from libs.time_parser import get_time_threshold
 from models.enums import WorkflowRunTriggeredFrom
-from models.human_input import HumanInputForm
+from models.human_input import HumanInputForm, HumanInputFormRecipient, RecipientType
 from models.workflow import WorkflowAppLog, WorkflowArchiveLog, WorkflowPause, WorkflowPauseReason, WorkflowRun
 from repositories.api_workflow_run_repository import APIWorkflowRunRepository, RunsWithRelatedCountsDict
 from repositories.entities.workflow_pause import WorkflowPauseEntity
@@ -60,9 +60,20 @@ class _WorkflowRunError(Exception):
     pass
 
 
+def _select_recipient_token(
+    recipients: Sequence[HumanInputFormRecipient],
+    recipient_type: RecipientType,
+) -> str | None:
+    recipient = next((recipient for recipient in recipients if recipient.recipient_type == recipient_type), None)
+    if recipient is None or not recipient.access_token:
+        return None
+    return recipient.access_token
+
+
 def _build_human_input_required_reason(
     reason_model: WorkflowPauseReason,
     form_model: HumanInputForm | None,
+    recipients: Sequence[HumanInputFormRecipient] = (),
 ) -> HumanInputRequired:
     form_content = ""
     inputs = []
@@ -89,6 +100,12 @@ def _build_human_input_required_reason(
             resolved_default_values = dict(definition.default_values)
             node_title = definition.node_title or node_title
 
+    # Service API pause payloads and replayed workflow events must expose the public token used by
+    # `/form/human_input/:form_token`, so prefer the standalone web-app surface and only fall back
+    # to the console token when a web-app token is unavailable.
+    form_token = _select_recipient_token(recipients, RecipientType.STANDALONE_WEB_APP) or _select_recipient_token(
+        recipients, RecipientType.CONSOLE
+    )
     return HumanInputRequired(
         form_id=form_id,
         form_content=form_content,
@@ -96,6 +113,7 @@ def _build_human_input_required_reason(
         actions=actions,
         node_id=node_id,
         node_title=node_title,
+        form_token=form_token,
         resolved_default_values=resolved_default_values,
     )
 
@@ -804,12 +822,23 @@ class DifyAPISQLAlchemyWorkflowRunRepository(APIWorkflowRunRepository):
             form_stmt = select(HumanInputForm).where(HumanInputForm.id.in_(form_ids))
             for form in session.scalars(form_stmt).all():
                 form_models[form.id] = form
+        recipients_by_form_id: dict[str, list[HumanInputFormRecipient]] = {}
+        if form_ids:
+            recipient_stmt = select(HumanInputFormRecipient).where(HumanInputFormRecipient.form_id.in_(form_ids))
+            for recipient in session.scalars(recipient_stmt).all():
+                recipients_by_form_id.setdefault(recipient.form_id, []).append(recipient)
 
         pause_reasons: list[PauseReason] = []
         for reason in pause_reason_models:
             if reason.type_ == PauseReasonType.HUMAN_INPUT_REQUIRED:
                 form_model = form_models.get(reason.form_id)
-                pause_reasons.append(_build_human_input_required_reason(reason, form_model))
+                pause_reasons.append(
+                    _build_human_input_required_reason(
+                        reason,
+                        form_model,
+                        recipients_by_form_id.get(reason.form_id, ()),
+                    )
+                )
             else:
                 pause_reasons.append(reason.to_entity())
         return pause_reasons

api/repositories/workflow_collaboration_repository.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import json
+from typing import TypedDict
+
+from extensions.ext_redis import redis_client
+
+SESSION_STATE_TTL_SECONDS = 3600
+WORKFLOW_ONLINE_USERS_PREFIX = "workflow_online_users:"
+WORKFLOW_LEADER_PREFIX = "workflow_leader:"
+WS_SID_MAP_PREFIX = "ws_sid_map:"
+
+
+class WorkflowSessionInfo(TypedDict):
+    user_id: str
+    username: str
+    avatar: str | None
+    sid: str
+    connected_at: int
+
+
+class SidMapping(TypedDict):
+    workflow_id: str
+    user_id: str
+
+
+class WorkflowCollaborationRepository:
+    def __init__(self) -> None:
+        self._redis = redis_client
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(redis_client={self._redis})"
+
+    @staticmethod
+    def workflow_key(workflow_id: str) -> str:
+        return f"{WORKFLOW_ONLINE_USERS_PREFIX}{workflow_id}"
+
+    @staticmethod
+    def leader_key(workflow_id: str) -> str:
+        return f"{WORKFLOW_LEADER_PREFIX}{workflow_id}"
+
+    @staticmethod
+    def sid_key(sid: str) -> str:
+        return f"{WS_SID_MAP_PREFIX}{sid}"
+
+    @staticmethod
+    def _decode(value: str | bytes | None) -> str | None:
+        if value is None:
+            return None
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+        return value
+
+    def refresh_session_state(self, workflow_id: str, sid: str) -> None:
+        workflow_key = self.workflow_key(workflow_id)
+        sid_key = self.sid_key(sid)
+        if self._redis.exists(workflow_key):
+            self._redis.expire(workflow_key, SESSION_STATE_TTL_SECONDS)
+        if self._redis.exists(sid_key):
+            self._redis.expire(sid_key, SESSION_STATE_TTL_SECONDS)
+
+    def set_session_info(self, workflow_id: str, session_info: WorkflowSessionInfo) -> None:
+        workflow_key = self.workflow_key(workflow_id)
+        self._redis.hset(workflow_key, session_info["sid"], json.dumps(session_info))
+        self._redis.set(
+            self.sid_key(session_info["sid"]),
+            json.dumps({"workflow_id": workflow_id, "user_id": session_info["user_id"]}),
+            ex=SESSION_STATE_TTL_SECONDS,
+        )
+        self.refresh_session_state(workflow_id, session_info["sid"])
+
+    def get_sid_mapping(self, sid: str) -> SidMapping | None:
+        raw = self._redis.get(self.sid_key(sid))
+        if not raw:
+            return None
+        value = self._decode(raw)
+        if not value:
+            return None
+        try:
+            return json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return None
+
+    def delete_session(self, workflow_id: str, sid: str) -> None:
+        self._redis.hdel(self.workflow_key(workflow_id), sid)
+        self._redis.delete(self.sid_key(sid))
+
+    def session_exists(self, workflow_id: str, sid: str) -> bool:
+        return bool(self._redis.hexists(self.workflow_key(workflow_id), sid))
+
+    def sid_mapping_exists(self, sid: str) -> bool:
+        return bool(self._redis.exists(self.sid_key(sid)))
+
+    def get_session_sids(self, workflow_id: str) -> list[str]:
+        raw_sids = self._redis.hkeys(self.workflow_key(workflow_id))
+        decoded_sids: list[str] = []
+        for sid in raw_sids:
+            decoded = self._decode(sid)
+            if decoded:
+                decoded_sids.append(decoded)
+        return decoded_sids
+
+    def list_sessions(self, workflow_id: str) -> list[WorkflowSessionInfo]:
+        sessions_json = self._redis.hgetall(self.workflow_key(workflow_id))
+        users: list[WorkflowSessionInfo] = []
+
+        for session_info_json in sessions_json.values():
+            value = self._decode(session_info_json)
+            if not value:
+                continue
+            try:
+                session_info = json.loads(value)
+            except (TypeError, json.JSONDecodeError):
+                continue
+
+            if not isinstance(session_info, dict):
+                continue
+            if "user_id" not in session_info or "username" not in session_info or "sid" not in session_info:
+                continue
+
+            users.append(
+                {
+                    "user_id": str(session_info["user_id"]),
+                    "username": str(session_info["username"]),
+                    "avatar": session_info.get("avatar"),
+                    "sid": str(session_info["sid"]),
+                    "connected_at": int(session_info.get("connected_at") or 0),
+                }
+            )
+
+        return users
+
+    def get_current_leader(self, workflow_id: str) -> str | None:
+        raw = self._redis.get(self.leader_key(workflow_id))
+        return self._decode(raw)
+
+    def set_leader_if_absent(self, workflow_id: str, sid: str) -> bool:
+        return bool(self._redis.set(self.leader_key(workflow_id), sid, nx=True, ex=SESSION_STATE_TTL_SECONDS))
+
+    def set_leader(self, workflow_id: str, sid: str) -> None:
+        self._redis.set(self.leader_key(workflow_id), sid, ex=SESSION_STATE_TTL_SECONDS)
+
+    def delete_leader(self, workflow_id: str) -> None:
+        self._redis.delete(self.leader_key(workflow_id))
+
+    def expire_leader(self, workflow_id: str) -> None:
+        self._redis.expire(self.leader_key(workflow_id), SESSION_STATE_TTL_SECONDS)

api/services/app_generate_service.py

@@ -162,6 +162,7 @@ class AppGenerateService:
                                 invoke_from=invoke_from,
                                 streaming=True,
                                 call_depth=0,
+                                workflow_run_id=str(uuid.uuid4()),
                             )
                             payload_json = payload.model_dump_json()
 
@@ -183,6 +184,10 @@ class AppGenerateService:
                     else:
                         # Blocking mode: run synchronously and return JSON instead of SSE
                         # Keep behaviour consistent with WORKFLOW blocking branch.
+                        pause_config = PauseStateLayerConfig(
+                            session_factory=session_factory.get_session_maker(),
+                            state_owner_user_id=workflow.created_by,
+                        )
                         advanced_generator = AdvancedChatAppGenerator()
                         return rate_limit.generate(
                             advanced_generator.convert_to_event_stream(
@@ -194,6 +199,7 @@ class AppGenerateService:
                                     invoke_from=invoke_from,
                                     workflow_run_id=str(uuid.uuid4()),
                                     streaming=False,
+                                    pause_state_config=pause_config,
                                 )
                             ),
                             request_id=request_id,

api/services/feature_service.py

@@ -164,6 +164,7 @@ class SystemFeatureModel(BaseModel):
     enable_email_code_login: bool = False
     enable_email_password_login: bool = True
     enable_social_oauth_login: bool = False
+    enable_collaboration_mode: bool = False
     is_allow_register: bool = False
     is_allow_create_workspace: bool = False
     is_email_setup: bool = False
@@ -244,6 +245,7 @@ class FeatureService:
         system_features.enable_email_code_login = dify_config.ENABLE_EMAIL_CODE_LOGIN
         system_features.enable_email_password_login = dify_config.ENABLE_EMAIL_PASSWORD_LOGIN
         system_features.enable_social_oauth_login = dify_config.ENABLE_SOCIAL_OAUTH_LOGIN
+        system_features.enable_collaboration_mode = dify_config.ENABLE_COLLABORATION_MODE
         system_features.is_allow_register = dify_config.ALLOW_REGISTER
         system_features.is_allow_create_workspace = dify_config.ALLOW_CREATE_WORKSPACE
         system_features.is_email_setup = dify_config.MAIL_TYPE is not None and dify_config.MAIL_TYPE != ""

api/services/workflow_collaboration_service.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Mapping
+
+from sqlalchemy import select
+
+from core.db.session_factory import session_factory
+from models.account import Account
+from models.model import App
+from repositories.workflow_collaboration_repository import WorkflowCollaborationRepository, WorkflowSessionInfo
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowCollaborationService:
+    def __init__(self, repository: WorkflowCollaborationRepository, socketio) -> None:
+        self._repository = repository
+        self._socketio = socketio
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(repository={self._repository})"
+
+    def save_socket_identity(self, sid: str, user: Account) -> None:
+        """Persist the authenticated console user on the raw socket session."""
+        self._socketio.save_session(
+            sid,
+            {
+                "user_id": user.id,
+                "username": user.name,
+                "avatar": user.avatar,
+                "tenant_id": user.current_tenant_id,
+            },
+        )
+
+    def authorize_and_join_workflow_room(self, workflow_id: str, sid: str) -> tuple[str, bool] | None:
+        """
+        Join a collaboration room only after validating the socket session and tenant-scoped app access.
+
+        The Socket.IO payload still calls the room key `workflow_id`, but the identifier is the workflow app's
+        `App.id`. Returning `None` lets the controller reject the join before any Redis or room state is created.
+        """
+        session = self._socketio.get_session(sid)
+        user_id = session.get("user_id")
+        tenant_id = session.get("tenant_id")
+        if not user_id or not tenant_id:
+            return None
+
+        if not self._can_access_workflow(workflow_id, str(tenant_id)):
+            logger.warning(
+                "Workflow collaboration join rejected: workflow_id=%s tenant_id=%s user_id=%s sid=%s",
+                workflow_id,
+                tenant_id,
+                user_id,
+                sid,
+            )
+            return None
+
+        session_info: WorkflowSessionInfo = {
+            "user_id": str(user_id),
+            "username": str(session.get("username", "Unknown")),
+            "avatar": session.get("avatar"),
+            "sid": sid,
+            "connected_at": int(time.time()),
+        }
+
+        self._repository.set_session_info(workflow_id, session_info)
+
+        leader_sid = self.get_or_set_leader(workflow_id, sid)
+        is_leader = leader_sid == sid
+
+        self._socketio.enter_room(sid, workflow_id)
+        self.broadcast_online_users(workflow_id)
+
+        self._socketio.emit("status", {"isLeader": is_leader}, room=sid)
+
+        return str(user_id), is_leader
+
+    def _can_access_workflow(self, workflow_id: str, tenant_id: str) -> bool:
+        """Check room access without relying on Flask's app-context-bound scoped session."""
+        with session_factory.create_session() as session:
+            app_id = session.scalar(select(App.id).where(App.id == workflow_id, App.tenant_id == tenant_id).limit(1))
+        return app_id is not None
+
+    def disconnect_session(self, sid: str) -> None:
+        mapping = self._repository.get_sid_mapping(sid)
+        if not mapping:
+            return
+
+        workflow_id = mapping["workflow_id"]
+        self._repository.delete_session(workflow_id, sid)
+
+        self.handle_leader_disconnect(workflow_id, sid)
+        self.broadcast_online_users(workflow_id)
+
+    def relay_collaboration_event(self, sid: str, data: Mapping[str, object]) -> tuple[dict[str, str], int]:
+        mapping = self._repository.get_sid_mapping(sid)
+        if not mapping:
+            return {"msg": "unauthorized"}, 401
+
+        workflow_id = mapping["workflow_id"]
+        user_id = mapping["user_id"]
+        self.refresh_session_state(workflow_id, sid)
+
+        event_type = data.get("type")
+        event_data = data.get("data")
+        timestamp = data.get("timestamp", int(time.time()))
+
+        if not event_type:
+            return {"msg": "invalid event type"}, 400
+
+        if event_type == "sync_request":
+            leader_sid = self._repository.get_current_leader(workflow_id)
+            target_sid: str | None
+            if leader_sid and self.is_session_active(workflow_id, leader_sid):
+                target_sid = leader_sid
+            else:
+                if leader_sid:
+                    self._repository.delete_leader(workflow_id)
+                target_sid = self._select_graph_leader(workflow_id, preferred_sid=sid)
+                if target_sid:
+                    self._repository.set_leader(workflow_id, target_sid)
+                    self.broadcast_leader_change(workflow_id, target_sid)
+
+            if not target_sid:
+                return {"msg": "no_active_leader"}, 200
+
+            self._socketio.emit(
+                "collaboration_update",
+                {"type": event_type, "userId": user_id, "data": event_data, "timestamp": timestamp},
+                room=target_sid,
+            )
+
+            return {"msg": "sync_request_forwarded"}, 200
+
+        self._socketio.emit(
+            "collaboration_update",
+            {"type": event_type, "userId": user_id, "data": event_data, "timestamp": timestamp},
+            room=workflow_id,
+            skip_sid=sid,
+        )
+
+        return {"msg": "event_broadcasted"}, 200
+
+    def relay_graph_event(self, sid: str, data: object) -> tuple[dict[str, str], int]:
+        mapping = self._repository.get_sid_mapping(sid)
+        if not mapping:
+            return {"msg": "unauthorized"}, 401
+
+        workflow_id = mapping["workflow_id"]
+        self.refresh_session_state(workflow_id, sid)
+
+        self._socketio.emit("graph_update", data, room=workflow_id, skip_sid=sid)
+
+        return {"msg": "graph_update_broadcasted"}, 200
+
+    def get_or_set_leader(self, workflow_id: str, sid: str) -> str:
+        current_leader = self._repository.get_current_leader(workflow_id)
+
+        if current_leader:
+            if self.is_session_active(workflow_id, current_leader):
+                return current_leader
+            self._repository.delete_session(workflow_id, current_leader)
+            self._repository.delete_leader(workflow_id)
+
+        was_set = self._repository.set_leader_if_absent(workflow_id, sid)
+
+        if was_set:
+            if current_leader:
+                self.broadcast_leader_change(workflow_id, sid)
+            return sid
+
+        current_leader = self._repository.get_current_leader(workflow_id)
+        if current_leader:
+            return current_leader
+
+        return sid
+
+    def handle_leader_disconnect(self, workflow_id: str, disconnected_sid: str) -> None:
+        current_leader = self._repository.get_current_leader(workflow_id)
+        if not current_leader:
+            return
+
+        if current_leader != disconnected_sid:
+            return
+
+        new_leader_sid = self._select_graph_leader(workflow_id)
+        if new_leader_sid:
+            self._repository.set_leader(workflow_id, new_leader_sid)
+            self.broadcast_leader_change(workflow_id, new_leader_sid)
+        else:
+            self._repository.delete_leader(workflow_id)
+
+    def broadcast_leader_change(self, workflow_id: str, new_leader_sid: str | None) -> None:
+        for sid in self._repository.get_session_sids(workflow_id):
+            try:
+                is_leader = new_leader_sid is not None and sid == new_leader_sid
+                self._socketio.emit("status", {"isLeader": is_leader}, room=sid)
+            except Exception:
+                logging.exception("Failed to emit leader status to session %s", sid)
+
+    def get_current_leader(self, workflow_id: str) -> str | None:
+        return self._repository.get_current_leader(workflow_id)
+
+    def _prune_inactive_sessions(self, workflow_id: str) -> list[WorkflowSessionInfo]:
+        """Remove inactive sessions from storage and return active sessions only."""
+        sessions = self._repository.list_sessions(workflow_id)
+        if not sessions:
+            return []
+
+        active_sessions: list[WorkflowSessionInfo] = []
+        stale_sids: list[str] = []
+        for session in sessions:
+            sid = session["sid"]
+            if self.is_session_active(workflow_id, sid):
+                active_sessions.append(session)
+            else:
+                stale_sids.append(sid)
+
+        for sid in stale_sids:
+            self._repository.delete_session(workflow_id, sid)
+
+        return active_sessions
+
+    def broadcast_online_users(self, workflow_id: str) -> None:
+        users = self._prune_inactive_sessions(workflow_id)
+        users.sort(key=lambda x: x.get("connected_at") or 0)
+
+        leader_sid = self.get_current_leader(workflow_id)
+        previous_leader = leader_sid
+        active_sids = {user["sid"] for user in users}
+        if leader_sid and leader_sid not in active_sids:
+            self._repository.delete_leader(workflow_id)
+            leader_sid = None
+
+        if not leader_sid and users:
+            leader_sid = self._select_graph_leader(workflow_id)
+            if leader_sid:
+                self._repository.set_leader(workflow_id, leader_sid)
+
+        if leader_sid != previous_leader:
+            self.broadcast_leader_change(workflow_id, leader_sid)
+
+        self._socketio.emit(
+            "online_users",
+            {"workflow_id": workflow_id, "users": users, "leader": leader_sid},
+            room=workflow_id,
+        )
+
+    def refresh_session_state(self, workflow_id: str, sid: str) -> None:
+        self._repository.refresh_session_state(workflow_id, sid)
+        self._ensure_leader(workflow_id, sid)
+
+    def _ensure_leader(self, workflow_id: str, sid: str) -> None:
+        current_leader = self._repository.get_current_leader(workflow_id)
+        if current_leader and self.is_session_active(workflow_id, current_leader):
+            self._repository.expire_leader(workflow_id)
+            return
+
+        if current_leader:
+            self._repository.delete_leader(workflow_id)
+
+        self._repository.set_leader(workflow_id, sid)
+        self.broadcast_leader_change(workflow_id, sid)
+
+    def _select_graph_leader(self, workflow_id: str, preferred_sid: str | None = None) -> str | None:
+        session_sids = [
+            session["sid"]
+            for session in self._repository.list_sessions(workflow_id)
+            if session.get("graph_active", True) and self.is_session_active(workflow_id, session["sid"])
+        ]
+        if not session_sids:
+            return None
+        if preferred_sid and preferred_sid in session_sids:
+            return preferred_sid
+        return session_sids[0]
+
+    def is_session_active(self, workflow_id: str, sid: str) -> bool:
+        if not sid:
+            return False
+
+        try:
+            if not self._socketio.manager.is_connected(sid, "/"):
+                return False
+        except AttributeError:
+            return False
+
+        if not self._repository.session_exists(workflow_id, sid):
+            return False
+
+        if not self._repository.sid_mapping_exists(sid):
+            return False
+
+        return True

api/services/workflow_comment_service.py

@@ -0,0 +1,564 @@
+import logging
+from collections.abc import Sequence
+
+from sqlalchemy import desc, select
+from sqlalchemy.orm import Session, selectinload
+from werkzeug.exceptions import Forbidden, NotFound
+
+from configs import dify_config
+from extensions.ext_database import db
+from libs.datetime_utils import naive_utc_now
+from libs.helper import uuid_value
+from models import App, TenantAccountJoin, WorkflowComment, WorkflowCommentMention, WorkflowCommentReply
+from models.account import Account
+from tasks.mail_workflow_comment_task import send_workflow_comment_mention_email_task
+
+logger = logging.getLogger(__name__)
+
+
+class WorkflowCommentService:
+    """Service for managing workflow comments."""
+
+    @staticmethod
+    def _validate_content(content: str) -> None:
+        if len(content.strip()) == 0:
+            raise ValueError("Comment content cannot be empty")
+
+        if len(content) > 1000:
+            raise ValueError("Comment content cannot exceed 1000 characters")
+
+    @staticmethod
+    def _filter_valid_mentioned_user_ids(
+        mentioned_user_ids: Sequence[str], *, session: Session, tenant_id: str
+    ) -> list[str]:
+        """Return deduplicated UUID user IDs that belong to the tenant, preserving input order."""
+        unique_user_ids: list[str] = []
+        seen: set[str] = set()
+        for user_id in mentioned_user_ids:
+            if not isinstance(user_id, str):
+                continue
+            if not uuid_value(user_id):
+                continue
+            if user_id in seen:
+                continue
+            seen.add(user_id)
+            unique_user_ids.append(user_id)
+        if not unique_user_ids:
+            return []
+
+        tenant_member_ids = {
+            str(account_id)
+            for account_id in session.scalars(
+                select(TenantAccountJoin.account_id).where(
+                    TenantAccountJoin.tenant_id == tenant_id,
+                    TenantAccountJoin.account_id.in_(unique_user_ids),
+                )
+            ).all()
+        }
+
+        return [user_id for user_id in unique_user_ids if user_id in tenant_member_ids]
+
+    @staticmethod
+    def _format_comment_excerpt(content: str, max_length: int = 200) -> str:
+        """Trim comment content for email display."""
+        trimmed = content.strip()
+        if len(trimmed) <= max_length:
+            return trimmed
+        if max_length <= 3:
+            return trimmed[:max_length]
+        return f"{trimmed[: max_length - 3].rstrip()}..."
+
+    @staticmethod
+    def _build_mention_email_payloads(
+        session: Session,
+        tenant_id: str,
+        app_id: str,
+        mentioner_id: str,
+        mentioned_user_ids: Sequence[str],
+        content: str,
+    ) -> list[dict[str, str]]:
+        """Prepare email payloads for mentioned users, including workflow app link."""
+        if not mentioned_user_ids:
+            return []
+
+        candidate_user_ids = [user_id for user_id in mentioned_user_ids if user_id != mentioner_id]
+        if not candidate_user_ids:
+            return []
+
+        app_name_value = session.scalar(select(App.name).where(App.id == app_id, App.tenant_id == tenant_id))
+        app_name = app_name_value if isinstance(app_name_value, str) and app_name_value else "Dify app"
+        commenter_name_value = session.scalar(select(Account.name).where(Account.id == mentioner_id))
+        commenter_name = (
+            commenter_name_value if isinstance(commenter_name_value, str) and commenter_name_value else "Dify user"
+        )
+        comment_excerpt = WorkflowCommentService._format_comment_excerpt(content)
+        base_url = dify_config.CONSOLE_WEB_URL.rstrip("/")
+        app_url = f"{base_url}/app/{app_id}/workflow"
+
+        accounts = session.scalars(
+            select(Account)
+            .join(TenantAccountJoin, TenantAccountJoin.account_id == Account.id)
+            .where(TenantAccountJoin.tenant_id == tenant_id, Account.id.in_(candidate_user_ids))
+        ).all()
+
+        payloads: list[dict[str, str]] = []
+        for account in accounts:
+            email = account.email
+            if not isinstance(email, str) or not email:
+                continue
+            mentioned_name = account.name if isinstance(account.name, str) and account.name else email
+            language = (
+                account.interface_language
+                if isinstance(account.interface_language, str) and account.interface_language
+                else "en-US"
+            )
+            payloads.append(
+                {
+                    "language": language,
+                    "to": email,
+                    "mentioned_name": mentioned_name,
+                    "commenter_name": commenter_name,
+                    "app_name": app_name,
+                    "comment_content": comment_excerpt,
+                    "app_url": app_url,
+                }
+            )
+        return payloads
+
+    @staticmethod
+    def _dispatch_mention_emails(payloads: Sequence[dict[str, str]]) -> None:
+        """Enqueue mention notification emails."""
+        for payload in payloads:
+            send_workflow_comment_mention_email_task.delay(**payload)
+
+    @staticmethod
+    def get_comments(tenant_id: str, app_id: str) -> Sequence[WorkflowComment]:
+        """Get all comments for a workflow."""
+        with Session(db.engine) as session:
+            # Get all comments with eager loading
+            stmt = (
+                select(WorkflowComment)
+                .options(selectinload(WorkflowComment.replies), selectinload(WorkflowComment.mentions))
+                .where(WorkflowComment.tenant_id == tenant_id, WorkflowComment.app_id == app_id)
+                .order_by(desc(WorkflowComment.created_at))
+            )
+
+            comments = session.scalars(stmt).all()
+
+            # Batch preload all Account objects to avoid N+1 queries
+            WorkflowCommentService._preload_accounts(session, comments)
+
+            return comments
+
+    @staticmethod
+    def _preload_accounts(session: Session, comments: Sequence[WorkflowComment]) -> None:
+        """Batch preload Account objects for comments, replies, and mentions."""
+        # Collect all user IDs
+        user_ids: set[str] = set()
+        for comment in comments:
+            user_ids.add(comment.created_by)
+            if comment.resolved_by:
+                user_ids.add(comment.resolved_by)
+            user_ids.update(reply.created_by for reply in comment.replies)
+            user_ids.update(mention.mentioned_user_id for mention in comment.mentions)
+
+        if not user_ids:
+            return
+
+        # Batch query all accounts
+        accounts = session.scalars(select(Account).where(Account.id.in_(user_ids))).all()
+        account_map = {str(account.id): account for account in accounts}
+
+        # Cache accounts on objects
+        for comment in comments:
+            comment.cache_created_by_account(account_map.get(comment.created_by))
+            comment.cache_resolved_by_account(account_map.get(comment.resolved_by) if comment.resolved_by else None)
+            for reply in comment.replies:
+                reply.cache_created_by_account(account_map.get(reply.created_by))
+            for mention in comment.mentions:
+                mention.cache_mentioned_user_account(account_map.get(mention.mentioned_user_id))
+
+    @staticmethod
+    def get_comment(tenant_id: str, app_id: str, comment_id: str, session: Session | None = None) -> WorkflowComment:
+        """Get a specific comment."""
+
+        def _get_comment(session: Session) -> WorkflowComment:
+            stmt = (
+                select(WorkflowComment)
+                .options(selectinload(WorkflowComment.replies), selectinload(WorkflowComment.mentions))
+                .where(
+                    WorkflowComment.id == comment_id,
+                    WorkflowComment.tenant_id == tenant_id,
+                    WorkflowComment.app_id == app_id,
+                )
+            )
+            comment = session.scalar(stmt)
+
+            if not comment:
+                raise NotFound("Comment not found")
+
+            # Preload accounts to avoid N+1 queries
+            WorkflowCommentService._preload_accounts(session, [comment])
+
+            return comment
+
+        if session is not None:
+            return _get_comment(session)
+        else:
+            with Session(db.engine, expire_on_commit=False) as session:
+                return _get_comment(session)
+
+    @staticmethod
+    def create_comment(
+        tenant_id: str,
+        app_id: str,
+        created_by: str,
+        content: str,
+        position_x: float,
+        position_y: float,
+        mentioned_user_ids: list[str] | None = None,
+    ) -> dict:
+        """Create a new workflow comment and send mention notification emails."""
+        WorkflowCommentService._validate_content(content)
+
+        with Session(db.engine) as session:
+            comment = WorkflowComment(
+                tenant_id=tenant_id,
+                app_id=app_id,
+                position_x=position_x,
+                position_y=position_y,
+                content=content,
+                created_by=created_by,
+            )
+
+            session.add(comment)
+            session.flush()  # Get the comment ID for mentions
+
+            # Create mentions if specified
+            mentioned_user_ids = WorkflowCommentService._filter_valid_mentioned_user_ids(
+                mentioned_user_ids or [],
+                session=session,
+                tenant_id=tenant_id,
+            )
+            for user_id in mentioned_user_ids:
+                mention = WorkflowCommentMention(
+                    comment_id=comment.id,
+                    reply_id=None,  # This is a comment mention, not reply mention
+                    mentioned_user_id=user_id,
+                )
+                session.add(mention)
+
+            mention_email_payloads = WorkflowCommentService._build_mention_email_payloads(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=app_id,
+                mentioner_id=created_by,
+                mentioned_user_ids=mentioned_user_ids,
+                content=content,
+            )
+
+            session.commit()
+            WorkflowCommentService._dispatch_mention_emails(mention_email_payloads)
+
+            # Return only what we need - id and created_at
+            return {"id": comment.id, "created_at": comment.created_at}
+
+    @staticmethod
+    def update_comment(
+        tenant_id: str,
+        app_id: str,
+        comment_id: str,
+        user_id: str,
+        content: str,
+        position_x: float | None = None,
+        position_y: float | None = None,
+        mentioned_user_ids: list[str] | None = None,
+    ) -> dict:
+        """Update a workflow comment and notify newly mentioned users.
+
+        `mentioned_user_ids=None` means "leave mentions unchanged".
+        Passing an explicit list replaces the existing comment mentions, including clearing them with `[]`.
+        """
+        WorkflowCommentService._validate_content(content)
+
+        with Session(db.engine, expire_on_commit=False) as session:
+            # Get comment with validation
+            stmt = select(WorkflowComment).where(
+                WorkflowComment.id == comment_id,
+                WorkflowComment.tenant_id == tenant_id,
+                WorkflowComment.app_id == app_id,
+            )
+            comment = session.scalar(stmt)
+
+            if not comment:
+                raise NotFound("Comment not found")
+
+            # Only the creator can update the comment
+            if comment.created_by != user_id:
+                raise Forbidden("Only the comment creator can update it")
+
+            # Update comment fields
+            comment.content = content
+            if position_x is not None:
+                comment.position_x = position_x
+            if position_y is not None:
+                comment.position_y = position_y
+
+            mention_email_payloads: list[dict[str, str]] = []
+            if mentioned_user_ids is not None:
+                # Replace comment mentions only when the client explicitly sends the mention list.
+                existing_mentions = session.scalars(
+                    select(WorkflowCommentMention).where(
+                        WorkflowCommentMention.comment_id == comment.id,
+                        WorkflowCommentMention.reply_id.is_(None),  # Only comment mentions, not reply mentions
+                    )
+                ).all()
+                existing_mentioned_user_ids = {mention.mentioned_user_id for mention in existing_mentions}
+                for mention in existing_mentions:
+                    session.delete(mention)
+
+                filtered_mentioned_user_ids = WorkflowCommentService._filter_valid_mentioned_user_ids(
+                    mentioned_user_ids,
+                    session=session,
+                    tenant_id=tenant_id,
+                )
+                new_mentioned_user_ids = [
+                    mentioned_user_id
+                    for mentioned_user_id in filtered_mentioned_user_ids
+                    if mentioned_user_id not in existing_mentioned_user_ids
+                ]
+                for mentioned_user_id in filtered_mentioned_user_ids:
+                    mention = WorkflowCommentMention(
+                        comment_id=comment.id,
+                        reply_id=None,  # This is a comment mention
+                        mentioned_user_id=mentioned_user_id,
+                    )
+                    session.add(mention)
+
+                mention_email_payloads = WorkflowCommentService._build_mention_email_payloads(
+                    session=session,
+                    tenant_id=tenant_id,
+                    app_id=app_id,
+                    mentioner_id=user_id,
+                    mentioned_user_ids=new_mentioned_user_ids,
+                    content=content,
+                )
+
+            session.commit()
+            WorkflowCommentService._dispatch_mention_emails(mention_email_payloads)
+
+            return {"id": comment.id, "updated_at": comment.updated_at}
+
+    @staticmethod
+    def delete_comment(tenant_id: str, app_id: str, comment_id: str, user_id: str) -> None:
+        """Delete a workflow comment."""
+        with Session(db.engine, expire_on_commit=False) as session:
+            comment = WorkflowCommentService.get_comment(tenant_id, app_id, comment_id, session)
+
+            # Only the creator can delete the comment
+            if comment.created_by != user_id:
+                raise Forbidden("Only the comment creator can delete it")
+
+            # Delete associated mentions (both comment and reply mentions)
+            mentions = session.scalars(
+                select(WorkflowCommentMention).where(WorkflowCommentMention.comment_id == comment_id)
+            ).all()
+            for mention in mentions:
+                session.delete(mention)
+
+            # Delete associated replies
+            replies = session.scalars(
+                select(WorkflowCommentReply).where(WorkflowCommentReply.comment_id == comment_id)
+            ).all()
+            for reply in replies:
+                session.delete(reply)
+
+            session.delete(comment)
+            session.commit()
+
+    @staticmethod
+    def resolve_comment(tenant_id: str, app_id: str, comment_id: str, user_id: str) -> WorkflowComment:
+        """Resolve a workflow comment."""
+        with Session(db.engine, expire_on_commit=False) as session:
+            comment = WorkflowCommentService.get_comment(tenant_id, app_id, comment_id, session)
+            if comment.resolved:
+                return comment
+
+            comment.resolved = True
+            comment.resolved_at = naive_utc_now()
+            comment.resolved_by = user_id
+            session.commit()
+
+        return comment
+
+    @staticmethod
+    def create_reply(
+        comment_id: str, content: str, created_by: str, mentioned_user_ids: list[str] | None = None
+    ) -> dict:
+        """Add a reply to a workflow comment and notify mentioned users."""
+        WorkflowCommentService._validate_content(content)
+
+        with Session(db.engine, expire_on_commit=False) as session:
+            # Check if comment exists
+            comment = session.get(WorkflowComment, comment_id)
+            if not comment:
+                raise NotFound("Comment not found")
+
+            reply = WorkflowCommentReply(comment_id=comment_id, content=content, created_by=created_by)
+
+            session.add(reply)
+            session.flush()  # Get the reply ID for mentions
+
+            # Create mentions if specified
+            mentioned_user_ids = WorkflowCommentService._filter_valid_mentioned_user_ids(
+                mentioned_user_ids or [],
+                session=session,
+                tenant_id=comment.tenant_id,
+            )
+            for user_id in mentioned_user_ids:
+                # Create mention linking to specific reply
+                mention = WorkflowCommentMention(comment_id=comment_id, reply_id=reply.id, mentioned_user_id=user_id)
+                session.add(mention)
+
+            mention_email_payloads = WorkflowCommentService._build_mention_email_payloads(
+                session=session,
+                tenant_id=comment.tenant_id,
+                app_id=comment.app_id,
+                mentioner_id=created_by,
+                mentioned_user_ids=mentioned_user_ids,
+                content=content,
+            )
+
+            session.commit()
+            WorkflowCommentService._dispatch_mention_emails(mention_email_payloads)
+
+            return {"id": reply.id, "created_at": reply.created_at}
+
+    @staticmethod
+    def _get_reply_in_comment_scope(
+        *,
+        session: Session,
+        tenant_id: str,
+        app_id: str,
+        comment_id: str,
+        reply_id: str,
+    ) -> WorkflowCommentReply:
+        """Get a reply scoped to tenant/app/comment to prevent cross-thread mutations."""
+        stmt = (
+            select(WorkflowCommentReply)
+            .join(WorkflowComment, WorkflowComment.id == WorkflowCommentReply.comment_id)
+            .where(
+                WorkflowCommentReply.id == reply_id,
+                WorkflowCommentReply.comment_id == comment_id,
+                WorkflowComment.tenant_id == tenant_id,
+                WorkflowComment.app_id == app_id,
+            )
+            .limit(1)
+        )
+        reply = session.scalar(stmt)
+        if not reply:
+            raise NotFound("Reply not found")
+        return reply
+
+    @staticmethod
+    def update_reply(
+        tenant_id: str,
+        app_id: str,
+        comment_id: str,
+        reply_id: str,
+        user_id: str,
+        content: str,
+        mentioned_user_ids: list[str] | None = None,
+    ) -> dict:
+        """Update a comment reply and notify newly mentioned users."""
+        WorkflowCommentService._validate_content(content)
+
+        with Session(db.engine, expire_on_commit=False) as session:
+            reply = WorkflowCommentService._get_reply_in_comment_scope(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=app_id,
+                comment_id=comment_id,
+                reply_id=reply_id,
+            )
+
+            # Only the creator can update the reply
+            if reply.created_by != user_id:
+                raise Forbidden("Only the reply creator can update it")
+
+            reply.content = content
+
+            # Update mentions - first remove existing mentions for this reply
+            existing_mentions = session.scalars(
+                select(WorkflowCommentMention).where(WorkflowCommentMention.reply_id == reply.id)
+            ).all()
+            existing_mentioned_user_ids = {mention.mentioned_user_id for mention in existing_mentions}
+            for mention in existing_mentions:
+                session.delete(mention)
+
+            # Add mentions
+            raw_mentioned_user_ids = mentioned_user_ids or []
+            comment = session.get(WorkflowComment, reply.comment_id)
+            mentioned_user_ids = []
+            if comment:
+                mentioned_user_ids = WorkflowCommentService._filter_valid_mentioned_user_ids(
+                    raw_mentioned_user_ids,
+                    session=session,
+                    tenant_id=comment.tenant_id,
+                )
+            new_mentioned_user_ids = [
+                user_id for user_id in mentioned_user_ids if user_id not in existing_mentioned_user_ids
+            ]
+            for user_id_str in mentioned_user_ids:
+                mention = WorkflowCommentMention(
+                    comment_id=reply.comment_id, reply_id=reply.id, mentioned_user_id=user_id_str
+                )
+                session.add(mention)
+
+            mention_email_payloads: list[dict[str, str]] = []
+            if comment:
+                mention_email_payloads = WorkflowCommentService._build_mention_email_payloads(
+                    session=session,
+                    tenant_id=comment.tenant_id,
+                    app_id=comment.app_id,
+                    mentioner_id=user_id,
+                    mentioned_user_ids=new_mentioned_user_ids,
+                    content=content,
+                )
+
+            session.commit()
+            session.refresh(reply)  # Refresh to get updated timestamp
+            WorkflowCommentService._dispatch_mention_emails(mention_email_payloads)
+
+            return {"id": reply.id, "updated_at": reply.updated_at}
+
+    @staticmethod
+    def delete_reply(tenant_id: str, app_id: str, comment_id: str, reply_id: str, user_id: str) -> None:
+        """Delete a comment reply."""
+        with Session(db.engine, expire_on_commit=False) as session:
+            reply = WorkflowCommentService._get_reply_in_comment_scope(
+                session=session,
+                tenant_id=tenant_id,
+                app_id=app_id,
+                comment_id=comment_id,
+                reply_id=reply_id,
+            )
+
+            # Only the creator can delete the reply
+            if reply.created_by != user_id:
+                raise Forbidden("Only the reply creator can delete it")
+
+            # Delete associated mentions first
+            mentions = session.scalars(
+                select(WorkflowCommentMention).where(WorkflowCommentMention.reply_id == reply_id)
+            ).all()
+            for mention in mentions:
+                session.delete(mention)
+
+            session.delete(reply)
+            session.commit()
+
+    @staticmethod
+    def validate_comment_access(comment_id: str, tenant_id: str, app_id: str) -> WorkflowComment:
+        """Validate that a comment belongs to the specified tenant and app."""
+        return WorkflowCommentService.get_comment(tenant_id, app_id, comment_id)

api/services/workflow_event_snapshot_service.py

@@ -16,8 +16,10 @@ from graphon.workflow_type_encoder import WorkflowRuntimeTypeConverter
 from sqlalchemy import desc, select
 from sqlalchemy.orm import Session, sessionmaker
 
+from core.app.apps.common.pause_reason_serializer import pause_reason_to_public_dict
 from core.app.apps.message_generator import MessageGenerator
 from core.app.entities.task_entities import (
+    HumanInputRequiredResponse,
     MessageReplaceStreamResponse,
     NodeFinishStreamResponse,
     NodeStartStreamResponse,
@@ -26,6 +28,8 @@ from core.app.entities.task_entities import (
     WorkflowStartStreamResponse,
 )
 from core.app.layers.pause_state_persist_layer import WorkflowResumptionContext
+from core.workflow.human_input_forms import load_form_tokens_by_form_id
+from models.human_input import HumanInputForm
 from models.model import AppMode, Message
 from models.workflow import WorkflowNodeExecutionTriggeredFrom, WorkflowRun
 from repositories.api_workflow_node_execution_repository import WorkflowNodeExecutionSnapshot
@@ -61,6 +65,7 @@ def build_workflow_event_stream(
     session_maker: sessionmaker[Session],
     idle_timeout: float = 300,
     ping_interval: float = 10.0,
+    close_on_pause: bool = True,
 ) -> Generator[Mapping[str, Any] | str, None, None]:
     topic = MessageGenerator.get_response_topic(app_mode, workflow_run.id)
     workflow_run_repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
@@ -115,13 +120,14 @@ def build_workflow_event_stream(
                     message_context=message_context,
                     pause_entity=pause_entity,
                     resumption_context=resumption_context,
+                    session_maker=session_maker,
                 )
 
                 for event in snapshot_events:
                     last_msg_time = time.time()
                     last_ping_time = last_msg_time
                     yield event
-                    if _is_terminal_event(event, include_paused=True):
+                    if _is_terminal_event(event, close_on_pause=close_on_pause):
                         return
 
                 while True:
@@ -146,7 +152,7 @@ def build_workflow_event_stream(
                     last_msg_time = time.time()
                     last_ping_time = last_msg_time
                     yield event
-                    if _is_terminal_event(event, include_paused=True):
+                    if _is_terminal_event(event, close_on_pause=close_on_pause):
                         return
             finally:
                 buffer_state.stop_event.set()
@@ -207,6 +213,7 @@ def _build_snapshot_events(
     message_context: MessageContext | None,
     pause_entity: WorkflowPauseEntity | None,
     resumption_context: WorkflowResumptionContext | None,
+    session_maker: sessionmaker[Session] | None = None,
 ) -> list[Mapping[str, Any]]:
     events: list[Mapping[str, Any]] = []
 
@@ -241,12 +248,22 @@ def _build_snapshot_events(
             events.append(node_finished)
 
     if workflow_run.status == WorkflowExecutionStatus.PAUSED and pause_entity is not None:
+        for human_input_event in _build_human_input_required_events(
+            workflow_run_id=workflow_run.id,
+            task_id=task_id,
+            pause_entity=pause_entity,
+            session_maker=session_maker,
+        ):
+            _apply_message_context(human_input_event, message_context)
+            events.append(human_input_event)
+
         pause_event = _build_pause_event(
             workflow_run=workflow_run,
             workflow_run_id=workflow_run.id,
             task_id=task_id,
             pause_entity=pause_entity,
             resumption_context=resumption_context,
+            session_maker=session_maker,
         )
         if pause_event is not None:
             _apply_message_context(pause_event, message_context)
@@ -314,6 +331,78 @@ def _build_node_started_event(
     return response.to_ignore_detail_dict()
 
 
+def _build_human_input_required_events(
+    *,
+    workflow_run_id: str,
+    task_id: str,
+    pause_entity: WorkflowPauseEntity,
+    session_maker: sessionmaker[Session] | None,
+) -> list[dict[str, Any]]:
+    reasons = [pause_reason_to_public_dict(reason) for reason in pause_entity.get_pause_reasons()]
+    human_input_form_ids = [
+        form_id
+        for reason in reasons
+        if reason.get("type") == "human_input_required"
+        for form_id in [reason.get("form_id")]
+        if isinstance(form_id, str)
+    ]
+
+    expiration_times_by_form_id: dict[str, int] = {}
+    display_in_ui_by_form_id: dict[str, bool] = {}
+    form_tokens_by_form_id: dict[str, str] = {}
+    if human_input_form_ids and session_maker is not None:
+        stmt = select(HumanInputForm.id, HumanInputForm.expiration_time, HumanInputForm.form_definition).where(
+            HumanInputForm.id.in_(human_input_form_ids)
+        )
+        with session_maker() as session:
+            for form_id, expiration_time, form_definition in session.execute(stmt):
+                expiration_times_by_form_id[str(form_id)] = int(expiration_time.timestamp())
+                try:
+                    definition_payload = json.loads(form_definition) if form_definition else {}
+                except (TypeError, json.JSONDecodeError):
+                    definition_payload = {}
+                display_in_ui_by_form_id[str(form_id)] = bool(definition_payload.get("display_in_ui"))
+            form_tokens_by_form_id = load_form_tokens_by_form_id(human_input_form_ids, session=session)
+
+    events: list[dict[str, Any]] = []
+    for reason in reasons:
+        if reason.get("type") != "human_input_required":
+            continue
+
+        form_id = reason.get("form_id")
+        node_id = reason.get("node_id")
+        node_title = reason.get("node_title")
+        form_content = reason.get("form_content")
+        if not all(isinstance(value, str) for value in (form_id, node_id, node_title, form_content)):
+            continue
+
+        expiration_time = expiration_times_by_form_id.get(form_id)
+        if expiration_time is None:
+            continue
+
+        response = HumanInputRequiredResponse(
+            task_id=task_id,
+            workflow_run_id=workflow_run_id,
+            data=HumanInputRequiredResponse.Data(
+                form_id=form_id,
+                node_id=node_id,
+                node_title=node_title,
+                form_content=form_content,
+                inputs=reason.get("inputs") or [],
+                actions=reason.get("actions") or [],
+                display_in_ui=display_in_ui_by_form_id.get(form_id, False),
+                form_token=form_tokens_by_form_id.get(form_id),
+                resolved_default_values=reason.get("resolved_default_values") or {},
+                expiration_time=expiration_time,
+            ),
+        )
+        payload = response.model_dump(mode="json")
+        payload["event"] = response.event.value
+        events.append(payload)
+
+    return events
+
+
 def _build_node_finished_event(
     *,
     workflow_run_id: str,
@@ -356,6 +445,7 @@ def _build_pause_event(
     task_id: str,
     pause_entity: WorkflowPauseEntity,
     resumption_context: WorkflowResumptionContext | None,
+    session_maker: sessionmaker[Session] | None,
 ) -> dict[str, Any] | None:
     paused_nodes: list[str] = []
     outputs: dict[str, Any] = {}
@@ -364,7 +454,24 @@ def _build_pause_event(
         paused_nodes = state.get_paused_nodes()
         outputs = dict(WorkflowRuntimeTypeConverter().to_json_encodable(state.outputs or {}))
 
-    reasons = [reason.model_dump(mode="json") for reason in pause_entity.get_pause_reasons()]
+    reasons = [pause_reason_to_public_dict(reason) for reason in pause_entity.get_pause_reasons()]
+    human_input_form_ids = [
+        form_id
+        for reason in reasons
+        if reason.get("type") == "human_input_required"
+        for form_id in [reason.get("form_id")]
+        if isinstance(form_id, str)
+    ]
+    if human_input_form_ids and session_maker is not None:
+        with session_maker() as session:
+            form_tokens_by_form_id = load_form_tokens_by_form_id(human_input_form_ids, session=session)
+        for reason in reasons:
+            if reason.get("type") != "human_input_required":
+                continue
+            form_id = reason.get("form_id")
+            if isinstance(form_id, str):
+                reason["form_token"] = form_tokens_by_form_id.get(form_id)
+
     response = WorkflowPauseStreamResponse(
         task_id=task_id,
         workflow_run_id=workflow_run_id,
@@ -449,12 +556,12 @@ def _parse_event_message(message: bytes) -> Mapping[str, Any] | None:
     return event
 
 
-def _is_terminal_event(event: Mapping[str, Any] | str, include_paused=False) -> bool:
+def _is_terminal_event(event: Mapping[str, Any] | str, close_on_pause: bool = True) -> bool:
     if not isinstance(event, Mapping):
         return False
     event_type = event.get("event")
     if event_type == StreamEvent.WORKFLOW_FINISHED.value:
         return True
-    if include_paused:
+    if close_on_pause:
         return event_type == StreamEvent.WORKFLOW_PAUSED.value
     return False

api/services/workflow_service.py

@@ -199,6 +199,16 @@ class WorkflowService:
 
         return workflow
 
+    def get_accessible_app_ids(self, app_ids: Sequence[str], tenant_id: str) -> set[str]:
+        """
+        Return app IDs that belong to the given tenant.
+        """
+        if not app_ids:
+            return set()
+
+        stmt = select(App.id).where(App.id.in_(app_ids), App.tenant_id == tenant_id)
+        return {str(app_id) for app_id in db.session.scalars(stmt).all()}
+
     def get_all_published_workflow(
         self,
         *,
@@ -296,6 +306,78 @@ class WorkflowService:
         # return draft workflow
         return workflow
 
+    def update_draft_workflow_environment_variables(
+        self,
+        *,
+        app_model: App,
+        environment_variables: Sequence[VariableBase],
+        account: Account,
+    ):
+        """
+        Update draft workflow environment variables
+        """
+        # fetch draft workflow by app_model
+        workflow = self.get_draft_workflow(app_model=app_model)
+
+        if not workflow:
+            raise ValueError("No draft workflow found.")
+
+        workflow.environment_variables = environment_variables
+        workflow.updated_by = account.id
+        workflow.updated_at = naive_utc_now()
+
+        # commit db session changes
+        db.session.commit()
+
+    def update_draft_workflow_conversation_variables(
+        self,
+        *,
+        app_model: App,
+        conversation_variables: Sequence[VariableBase],
+        account: Account,
+    ):
+        """
+        Update draft workflow conversation variables
+        """
+        # fetch draft workflow by app_model
+        workflow = self.get_draft_workflow(app_model=app_model)
+
+        if not workflow:
+            raise ValueError("No draft workflow found.")
+
+        workflow.conversation_variables = conversation_variables
+        workflow.updated_by = account.id
+        workflow.updated_at = naive_utc_now()
+
+        # commit db session changes
+        db.session.commit()
+
+    def update_draft_workflow_features(
+        self,
+        *,
+        app_model: App,
+        features: dict,
+        account: Account,
+    ):
+        """
+        Update draft workflow features
+        """
+        # fetch draft workflow by app_model
+        workflow = self.get_draft_workflow(app_model=app_model)
+
+        if not workflow:
+            raise ValueError("No draft workflow found.")
+
+        # validate features structure
+        self.validate_features_structure(app_model=app_model, features=features)
+
+        workflow.features = json.dumps(features)
+        workflow.updated_by = account.id
+        workflow.updated_at = naive_utc_now()
+
+        # commit db session changes
+        db.session.commit()
+
     def restore_published_workflow_to_draft(
         self,
         *,

api/tasks/app_generate/workflow_execute_task.py

@@ -399,6 +399,8 @@ def _resume_advanced_chat(
     workflow_run_id: str,
     workflow_run: WorkflowRun,
 ) -> None:
+    resumed_generate_entity = generate_entity.model_copy(update={"stream": True})
+
     try:
         triggered_from = WorkflowRunTriggeredFrom(workflow_run.triggered_from)
     except ValueError:
@@ -426,7 +428,7 @@ def _resume_advanced_chat(
             user=user,
             conversation=conversation,
             message=message,
-            application_generate_entity=generate_entity,
+            application_generate_entity=resumed_generate_entity,
             workflow_execution_repository=workflow_execution_repository,
             workflow_node_execution_repository=workflow_node_execution_repository,
             graph_runtime_state=graph_runtime_state,
@@ -436,9 +438,8 @@ def _resume_advanced_chat(
         logger.exception("Failed to resume chatflow execution for workflow run %s", workflow_run_id)
         raise
 
-    if generate_entity.stream:
-        assert isinstance(response, Generator)
-        _publish_streaming_response(response, workflow_run_id, AppMode.ADVANCED_CHAT)
+    assert isinstance(response, Generator)
+    _publish_streaming_response(response, workflow_run_id, AppMode.ADVANCED_CHAT)
 
 
 def _resume_workflow(
@@ -455,6 +456,8 @@ def _resume_workflow(
     workflow_run_repo,
     pause_entity,
 ) -> None:
+    resumed_generate_entity = generate_entity.model_copy(update={"stream": True})
+
     try:
         triggered_from = WorkflowRunTriggeredFrom(workflow_run.triggered_from)
     except ValueError:
@@ -480,7 +483,7 @@ def _resume_workflow(
             app_model=app_model,
             workflow=workflow,
             user=user,
-            application_generate_entity=generate_entity,
+            application_generate_entity=resumed_generate_entity,
             graph_runtime_state=graph_runtime_state,
             workflow_execution_repository=workflow_execution_repository,
             workflow_node_execution_repository=workflow_node_execution_repository,
@@ -490,9 +493,8 @@ def _resume_workflow(
         logger.exception("Failed to resume workflow execution for workflow run %s", workflow_run_id)
         raise
 
-    if generate_entity.stream:
-        assert isinstance(response, Generator)
-        _publish_streaming_response(response, workflow_run_id, AppMode.WORKFLOW)
+    assert isinstance(response, Generator)
+    _publish_streaming_response(response, workflow_run_id, AppMode.WORKFLOW)
 
     workflow_run_repo.delete_workflow_pause(pause_entity)
 

api/tasks/mail_workflow_comment_task.py

@@ -0,0 +1,65 @@
+import logging
+import time
+
+import click
+from celery import shared_task
+
+from extensions.ext_mail import mail
+from libs.email_i18n import EmailType, get_email_i18n_service
+
+logger = logging.getLogger(__name__)
+
+
+@shared_task(queue="mail")
+def send_workflow_comment_mention_email_task(
+    language: str,
+    to: str,
+    mentioned_name: str,
+    commenter_name: str,
+    app_name: str,
+    comment_content: str,
+    app_url: str,
+):
+    """
+    Send workflow comment mention email with internationalization support.
+
+    Args:
+        language: Language code for email localization
+        to: Recipient email address
+        mentioned_name: Name of the mentioned user
+        commenter_name: Name of the comment author
+        app_name: Name of the app where the comment was made
+        comment_content: Comment content excerpt
+        app_url: Link to the app workflow page
+    """
+    if not mail.is_inited():
+        return
+
+    logger.info(click.style(f"Start workflow comment mention mail to {to}", fg="green"))
+    start_at = time.perf_counter()
+
+    try:
+        email_service = get_email_i18n_service()
+        email_service.send_email(
+            email_type=EmailType.WORKFLOW_COMMENT_MENTION,
+            language_code=language,
+            to=to,
+            template_context={
+                "to": to,
+                "mentioned_name": mentioned_name,
+                "commenter_name": commenter_name,
+                "app_name": app_name,
+                "comment_content": comment_content,
+                "app_url": app_url,
+            },
+        )
+
+        end_at = time.perf_counter()
+        logger.info(
+            click.style(
+                f"Send workflow comment mention mail to {to} succeeded: latency: {end_at - start_at}",
+                fg="green",
+            )
+        )
+    except Exception:
+        logger.exception("workflow comment mention email to %s failed", to)

api/templates/without-brand/workflow_comment_mention_template_en-US.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <style>
+    body {
+      font-family: 'Arial', sans-serif;
+      line-height: 16pt;
+      color: #101828;
+      background-color: #e9ebf0;
+      margin: 0;
+      padding: 0;
+    }
+
+    .container {
+      width: 504px;
+      min-height: 374px;
+      margin: 40px auto;
+      padding: 0 48px;
+      background-color: #fcfcfd;
+      border-radius: 16px;
+      border: 1px solid #ffffff;
+      box-shadow: 0px 3px 10px -2px rgba(9, 9, 11, 0.08), 0px 2px 4px -2px rgba(9, 9, 11, 0.06);
+    }
+
+    .header {
+      padding-top: 36px;
+      padding-bottom: 24px;
+    }
+
+    .header img {
+      max-width: 63px;
+      height: auto;
+    }
+
+    .title {
+      margin: 0;
+      padding-top: 8px;
+      padding-bottom: 16px;
+      color: #101828;
+      font-size: 24px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 600;
+      line-height: 120%;
+    }
+
+    .description {
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+
+    .content1 {
+      margin: 0;
+      padding-top: 16px;
+      padding-bottom: 8px;
+    }
+
+    .content2 {
+      margin: 0;
+      padding-bottom: 16px;
+    }
+
+    .comment-box {
+      margin-bottom: 16px;
+      padding: 12px 16px;
+      border-radius: 12px;
+      background-color: #f2f4f7;
+    }
+
+    .comment-text {
+      margin: 0;
+      color: #101828;
+      font-family: Inter;
+      font-size: 14px;
+      font-style: normal;
+      font-weight: 500;
+      line-height: 20px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+
+    .tips {
+      margin: 0;
+      padding-bottom: 24px;
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+  </style>
+</head>
+
+<body>
+  <div class="container">
+    <div class="header">
+      <img src="https://assets.dify.ai/images/logo.png" alt="Dify Logo" />
+    </div>
+    <p class="title">You were mentioned in a workflow comment</p>
+    <div class="description">
+      <p class="content1">Hi {{ mentioned_name }},</p>
+      <p class="content2">{{ commenter_name }} mentioned you in {{ app_name }}.</p>
+    </div>
+    <div class="comment-box">
+      <p class="comment-text">{{ comment_content }}</p>
+    </div>
+    <p class="tips"><a href="{{ app_url }}" style="color: #155AEF; text-decoration: none;">Open {{ application_title }}</a> to reply to the comment.</p>
+  </div>
+</body>
+
+</html>

api/templates/without-brand/workflow_comment_mention_template_zh-CN.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <style>
+    body {
+      font-family: 'Arial', sans-serif;
+      line-height: 16pt;
+      color: #101828;
+      background-color: #e9ebf0;
+      margin: 0;
+      padding: 0;
+    }
+
+    .container {
+      width: 504px;
+      min-height: 374px;
+      margin: 40px auto;
+      padding: 0 48px;
+      background-color: #fcfcfd;
+      border-radius: 16px;
+      border: 1px solid #ffffff;
+      box-shadow: 0px 3px 10px -2px rgba(9, 9, 11, 0.08), 0px 2px 4px -2px rgba(9, 9, 11, 0.06);
+    }
+
+    .header {
+      padding-top: 36px;
+      padding-bottom: 24px;
+    }
+
+    .header img {
+      max-width: 63px;
+      height: auto;
+    }
+
+    .title {
+      margin: 0;
+      padding-top: 8px;
+      padding-bottom: 16px;
+      color: #101828;
+      font-size: 24px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 600;
+      line-height: 120%;
+    }
+
+    .description {
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+
+    .content1 {
+      margin: 0;
+      padding-top: 16px;
+      padding-bottom: 8px;
+    }
+
+    .content2 {
+      margin: 0;
+      padding-bottom: 16px;
+    }
+
+    .comment-box {
+      margin-bottom: 16px;
+      padding: 12px 16px;
+      border-radius: 12px;
+      background-color: #f2f4f7;
+    }
+
+    .comment-text {
+      margin: 0;
+      color: #101828;
+      font-family: Inter;
+      font-size: 14px;
+      font-style: normal;
+      font-weight: 500;
+      line-height: 20px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+
+    .tips {
+      margin: 0;
+      padding-bottom: 24px;
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+  </style>
+</head>
+
+<body>
+  <div class="container">
+    <div class="header">
+      <img src="https://assets.dify.ai/images/logo.png" alt="Dify Logo" />
+    </div>
+    <p class="title">你在工作流评论中被提及</p>
+    <div class="description">
+      <p class="content1">你好，{{ mentioned_name }}：</p>
+      <p class="content2">{{ commenter_name }} 在 {{ app_name }} 中提及了你。</p>
+    </div>
+    <div class="comment-box">
+      <p class="comment-text">{{ comment_content }}</p>
+    </div>
+    <p class="tips">请在 <a href="{{ app_url }}" style="color: #155AEF; text-decoration: none;">{{ application_title }}</a> 中查看并回复此评论。</p>
+  </div>
+</body>
+
+</html>

api/templates/workflow_comment_mention_template_en-US.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <style>
+    body {
+      font-family: 'Arial', sans-serif;
+      line-height: 16pt;
+      color: #101828;
+      background-color: #e9ebf0;
+      margin: 0;
+      padding: 0;
+    }
+
+    .container {
+      width: 504px;
+      min-height: 374px;
+      margin: 40px auto;
+      padding: 0 48px;
+      background-color: #fcfcfd;
+      border-radius: 16px;
+      border: 1px solid #ffffff;
+      box-shadow: 0px 3px 10px -2px rgba(9, 9, 11, 0.08), 0px 2px 4px -2px rgba(9, 9, 11, 0.06);
+    }
+
+    .header {
+      padding-top: 36px;
+      padding-bottom: 24px;
+    }
+
+    .header img {
+      max-width: 63px;
+      height: auto;
+    }
+
+    .title {
+      margin: 0;
+      padding-top: 8px;
+      padding-bottom: 16px;
+      color: #101828;
+      font-size: 24px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 600;
+      line-height: 120%;
+    }
+
+    .description {
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+
+    .content1 {
+      margin: 0;
+      padding-top: 16px;
+      padding-bottom: 8px;
+    }
+
+    .content2 {
+      margin: 0;
+      padding-bottom: 16px;
+    }
+
+    .comment-box {
+      margin-bottom: 16px;
+      padding: 12px 16px;
+      border-radius: 12px;
+      background-color: #f2f4f7;
+    }
+
+    .comment-text {
+      margin: 0;
+      color: #101828;
+      font-family: Inter;
+      font-size: 14px;
+      font-style: normal;
+      font-weight: 500;
+      line-height: 20px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+
+    .tips {
+      margin: 0;
+      padding-bottom: 24px;
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+  </style>
+</head>
+
+<body>
+  <div class="container">
+    <div class="header">
+      <img src="https://assets.dify.ai/images/logo.png" alt="Dify Logo" />
+    </div>
+    <p class="title">You were mentioned in a workflow comment</p>
+    <div class="description">
+      <p class="content1">Hi {{ mentioned_name }},</p>
+      <p class="content2">{{ commenter_name }} mentioned you in {{ app_name }}.</p>
+    </div>
+    <div class="comment-box">
+      <p class="comment-text">{{ comment_content }}</p>
+    </div>
+    <p class="tips"><a href="{{ app_url }}" style="color: #155AEF; text-decoration: none;">Open {{ application_title }}</a> to reply to the comment.</p>
+  </div>
+</body>
+
+</html>

api/templates/workflow_comment_mention_template_zh-CN.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <style>
+    body {
+      font-family: 'Arial', sans-serif;
+      line-height: 16pt;
+      color: #101828;
+      background-color: #e9ebf0;
+      margin: 0;
+      padding: 0;
+    }
+
+    .container {
+      width: 504px;
+      min-height: 374px;
+      margin: 40px auto;
+      padding: 0 48px;
+      background-color: #fcfcfd;
+      border-radius: 16px;
+      border: 1px solid #ffffff;
+      box-shadow: 0px 3px 10px -2px rgba(9, 9, 11, 0.08), 0px 2px 4px -2px rgba(9, 9, 11, 0.06);
+    }
+
+    .header {
+      padding-top: 36px;
+      padding-bottom: 24px;
+    }
+
+    .header img {
+      max-width: 63px;
+      height: auto;
+    }
+
+    .title {
+      margin: 0;
+      padding-top: 8px;
+      padding-bottom: 16px;
+      color: #101828;
+      font-size: 24px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 600;
+      line-height: 120%;
+    }
+
+    .description {
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+
+    .content1 {
+      margin: 0;
+      padding-top: 16px;
+      padding-bottom: 8px;
+    }
+
+    .content2 {
+      margin: 0;
+      padding-bottom: 16px;
+    }
+
+    .comment-box {
+      margin-bottom: 16px;
+      padding: 12px 16px;
+      border-radius: 12px;
+      background-color: #f2f4f7;
+    }
+
+    .comment-text {
+      margin: 0;
+      color: #101828;
+      font-family: Inter;
+      font-size: 14px;
+      font-style: normal;
+      font-weight: 500;
+      line-height: 20px;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+
+    .tips {
+      margin: 0;
+      padding-bottom: 24px;
+      color: #354052;
+      font-size: 14px;
+      font-family: Inter;
+      font-style: normal;
+      font-weight: 400;
+      line-height: 20px;
+      letter-spacing: -0.07px;
+    }
+  </style>
+</head>
+
+<body>
+  <div class="container">
+    <div class="header">
+      <img src="https://assets.dify.ai/images/logo.png" alt="Dify Logo" />
+    </div>
+    <p class="title">你在工作流评论中被提及</p>
+    <div class="description">
+      <p class="content1">你好，{{ mentioned_name }}：</p>
+      <p class="content2">{{ commenter_name }} 在 {{ app_name }} 中提及了你。</p>
+    </div>
+    <div class="comment-box">
+      <p class="comment-text">{{ comment_content }}</p>
+    </div>
+    <p class="tips">请在 <a href="{{ app_url }}" style="color: #155AEF; text-decoration: none;">{{ application_title }}</a> 中查看并回复此评论。</p>
+  </div>
+</body>
+
+</html>

api/tests/integration_tests/conftest.py

@@ -48,7 +48,7 @@ os.environ["OPENDAL_FS_ROOT"] = "/tmp/dify-storage"
 os.environ.setdefault("STORAGE_TYPE", "opendal")
 os.environ.setdefault("OPENDAL_SCHEME", "fs")
 
-_CACHED_APP = create_app()
+_SIO_APP, _CACHED_APP = create_app()
 
 
 @pytest.fixture(scope="session")

api/tests/test_containers_integration_tests/conftest.py

@@ -369,7 +369,7 @@ def _create_app_with_containers() -> Flask:
 
     # Create and configure the Flask application
     logger.info("Initializing Flask application...")
-    app = create_app()
+    sio_app, app = create_app()
     logger.info("Flask application created successfully")
 
     # Initialize database schema

api/tests/test_containers_integration_tests/repositories/test_sqlalchemy_api_workflow_run_repository.py

@@ -628,12 +628,12 @@ class TestPrivateWorkflowPauseEntity:
 class TestBuildHumanInputRequiredReason:
     """Integration tests for _build_human_input_required_reason using real DB models."""
 
-    def test_builds_reason_from_form_definition(
+    def test_prefers_standalone_web_app_token_when_available(
         self,
         db_session_with_containers: Session,
         test_scope: _TestScope,
     ) -> None:
-        """Build the graph pause reason from the stored form definition."""
+        """Use the public standalone web-app token for service API payloads."""
 
         expiration_time = naive_utc_now()
         form_definition = FormDefinition(
@@ -660,6 +660,40 @@ class TestBuildHumanInputRequiredReason:
         db_session_with_containers.add(form_model)
         db_session_with_containers.flush()
 
+        delivery = HumanInputDelivery(
+            form_id=form_model.id,
+            delivery_method_type=DeliveryMethodType.WEBAPP,
+            channel_payload="{}",
+        )
+        db_session_with_containers.add(delivery)
+        db_session_with_containers.flush()
+
+        backstage_access_token = secrets.token_urlsafe(8)
+        backstage_recipient = HumanInputFormRecipient(
+            form_id=form_model.id,
+            delivery_id=delivery.id,
+            recipient_type=RecipientType.BACKSTAGE,
+            recipient_payload=BackstageRecipientPayload().model_dump_json(),
+            access_token=backstage_access_token,
+        )
+        console_access_token = secrets.token_urlsafe(8)
+        console_recipient = HumanInputFormRecipient(
+            form_id=form_model.id,
+            delivery_id=delivery.id,
+            recipient_type=RecipientType.CONSOLE,
+            recipient_payload="{}",
+            access_token=console_access_token,
+        )
+        web_app_access_token = secrets.token_urlsafe(8)
+        web_app_recipient = HumanInputFormRecipient(
+            form_id=form_model.id,
+            delivery_id=delivery.id,
+            recipient_type=RecipientType.STANDALONE_WEB_APP,
+            recipient_payload="{}",
+            access_token=web_app_access_token,
+        )
+        db_session_with_containers.add_all([backstage_recipient, console_recipient, web_app_recipient])
+        db_session_with_containers.flush()
         # Create a pause so the reason has a valid pause_id
         workflow_run = _create_workflow_run(
             db_session_with_containers,
@@ -688,12 +722,109 @@ class TestBuildHumanInputRequiredReason:
         # Refresh to ensure we have DB-round-tripped objects
         db_session_with_containers.refresh(form_model)
         db_session_with_containers.refresh(reason_model)
+        db_session_with_containers.refresh(backstage_recipient)
+        db_session_with_containers.refresh(console_recipient)
+        db_session_with_containers.refresh(web_app_recipient)
 
-        reason = _build_human_input_required_reason(reason_model, form_model)
+        reason = _build_human_input_required_reason(
+            reason_model,
+            form_model,
+            [backstage_recipient, console_recipient, web_app_recipient],
+        )
 
         assert isinstance(reason, HumanInputRequired)
+        assert reason.form_token == web_app_access_token
         assert reason.node_title == "Ask Name"
         assert reason.form_content == "content"
         assert reason.inputs[0].output_variable_name == "name"
         assert reason.actions[0].id == "approve"
         assert reason.resolved_default_values == {"name": "Alice"}
+
+    def test_falls_back_to_console_token_when_web_app_token_missing(
+        self,
+        db_session_with_containers: Session,
+        test_scope: _TestScope,
+    ) -> None:
+        """Use the console token only when no standalone web-app token exists."""
+
+        expiration_time = naive_utc_now()
+        form_definition = FormDefinition(
+            form_content="content",
+            inputs=[FormInput(type=FormInputType.TEXT_INPUT, output_variable_name="name")],
+            user_actions=[UserAction(id="approve", title="Approve")],
+            rendered_content="rendered",
+            expiration_time=expiration_time,
+            default_values={"name": "Alice"},
+            node_title="Ask Name",
+            display_in_ui=True,
+        )
+
+        form_model = HumanInputForm(
+            tenant_id=test_scope.tenant_id,
+            app_id=test_scope.app_id,
+            workflow_run_id=str(uuid4()),
+            node_id="node-1",
+            form_definition=form_definition.model_dump_json(),
+            rendered_content="rendered",
+            status=HumanInputFormStatus.WAITING,
+            expiration_time=expiration_time,
+        )
+        db_session_with_containers.add(form_model)
+        db_session_with_containers.flush()
+
+        delivery = HumanInputDelivery(
+            form_id=form_model.id,
+            delivery_method_type=DeliveryMethodType.WEBAPP,
+            channel_payload="{}",
+        )
+        db_session_with_containers.add(delivery)
+        db_session_with_containers.flush()
+
+        backstage_access_token = secrets.token_urlsafe(8)
+        backstage_recipient = HumanInputFormRecipient(
+            form_id=form_model.id,
+            delivery_id=delivery.id,
+            recipient_type=RecipientType.BACKSTAGE,
+            recipient_payload=BackstageRecipientPayload().model_dump_json(),
+            access_token=backstage_access_token,
+        )
+        console_access_token = secrets.token_urlsafe(8)
+        console_recipient = HumanInputFormRecipient(
+            form_id=form_model.id,
+            delivery_id=delivery.id,
+            recipient_type=RecipientType.CONSOLE,
+            recipient_payload="{}",
+            access_token=console_access_token,
+        )
+        db_session_with_containers.add_all([backstage_recipient, console_recipient])
+        db_session_with_containers.flush()
+
+        workflow_run = _create_workflow_run(
+            db_session_with_containers,
+            test_scope,
+            status=WorkflowExecutionStatus.RUNNING,
+        )
+        pause = WorkflowPause(
+            id=str(uuid4()),
+            workflow_id=test_scope.workflow_id,
+            workflow_run_id=workflow_run.id,
+            state_object_key=f"workflow-state-{uuid4()}.json",
+        )
+        db_session_with_containers.add(pause)
+        db_session_with_containers.flush()
+        test_scope.state_keys.add(pause.state_object_key)
+
+        reason_model = WorkflowPauseReason(
+            pause_id=pause.id,
+            type_=PauseReasonType.HUMAN_INPUT_REQUIRED,
+            form_id=form_model.id,
+            node_id="node-1",
+            message="",
+        )
+        db_session_with_containers.add(reason_model)
+        db_session_with_containers.commit()
+
+        reason = _build_human_input_required_reason(reason_model, form_model, [backstage_recipient, console_recipient])
+
+        assert isinstance(reason, HumanInputRequired)
+        assert reason.form_token == console_access_token

api/tests/test_containers_integration_tests/services/test_feature_service.py

@@ -274,6 +274,7 @@ class TestFeatureService:
             mock_config.ENABLE_EMAIL_CODE_LOGIN = True
             mock_config.ENABLE_EMAIL_PASSWORD_LOGIN = True
             mock_config.ENABLE_SOCIAL_OAUTH_LOGIN = False
+            mock_config.ENABLE_COLLABORATION_MODE = True
             mock_config.ALLOW_REGISTER = False
             mock_config.ALLOW_CREATE_WORKSPACE = False
             mock_config.MAIL_TYPE = "smtp"
@@ -298,6 +299,7 @@ class TestFeatureService:
         # Verify authentication settings
         assert result.enable_email_code_login is True
         assert result.enable_email_password_login is False
+        assert result.enable_collaboration_mode is True
         assert result.is_allow_register is False
         assert result.is_allow_create_workspace is False
 
@@ -401,6 +403,7 @@ class TestFeatureService:
             mock_config.ENABLE_EMAIL_CODE_LOGIN = True
             mock_config.ENABLE_EMAIL_PASSWORD_LOGIN = True
             mock_config.ENABLE_SOCIAL_OAUTH_LOGIN = False
+            mock_config.ENABLE_COLLABORATION_MODE = False
             mock_config.ALLOW_REGISTER = True
             mock_config.ALLOW_CREATE_WORKSPACE = True
             mock_config.MAIL_TYPE = "smtp"
@@ -422,6 +425,7 @@ class TestFeatureService:
             assert result.enable_email_code_login is True
             assert result.enable_email_password_login is True
             assert result.enable_social_oauth_login is False
+            assert result.enable_collaboration_mode is False
             assert result.is_allow_register is True
             assert result.is_allow_create_workspace is True
             assert result.is_email_setup is True

api/tests/unit_tests/controllers/console/app/test_workflow.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from datetime import datetime
 from types import SimpleNamespace
 from unittest.mock import Mock
@@ -347,3 +348,87 @@ def test_advanced_chat_run_conversation_not_exists(app, monkeypatch: pytest.Monk
     ):
         with pytest.raises(NotFound):
             handler(api, app_model=SimpleNamespace(id="app"))
+
+
+def test_workflow_online_users_filters_inaccessible_workflow(app, monkeypatch: pytest.MonkeyPatch) -> None:
+    app_id_1 = "11111111-1111-1111-1111-111111111111"
+    app_id_2 = "22222222-2222-2222-2222-222222222222"
+    signed_avatar_url = "https://files.example.com/signed/avatar-1"
+    sign_avatar = Mock(return_value=signed_avatar_url)
+    monkeypatch.setattr(workflow_module, "current_account_with_tenant", lambda: (SimpleNamespace(), "tenant-1"))
+    monkeypatch.setattr(
+        workflow_module,
+        "WorkflowService",
+        lambda: SimpleNamespace(get_accessible_app_ids=lambda app_ids, tenant_id: {app_id_1}),
+    )
+    monkeypatch.setattr(workflow_module.file_helpers, "get_signed_file_url", sign_avatar)
+
+    workflow_module.redis_client.hgetall.side_effect = lambda key: (
+        {
+            b"sid-1": json.dumps(
+                {
+                    "user_id": "u-1",
+                    "username": "Alice",
+                    "avatar": "avatar-file-id",
+                    "sid": "sid-1",
+                }
+            )
+        }
+        if key == f"{workflow_module.WORKFLOW_ONLINE_USERS_PREFIX}{app_id_1}"
+        else {}
+    )
+
+    api = workflow_module.WorkflowOnlineUsersApi()
+    handler = _unwrap(api.get)
+
+    with app.test_request_context(
+        f"/apps/workflows/online-users?app_ids={app_id_1},{app_id_2}",
+        method="GET",
+    ):
+        response = handler(api)
+
+    assert response == {
+        "data": [
+            {
+                "app_id": app_id_1,
+                "users": [
+                    {
+                        "user_id": "u-1",
+                        "username": "Alice",
+                        "avatar": signed_avatar_url,
+                        "sid": "sid-1",
+                    }
+                ],
+            }
+        ]
+    }
+    workflow_module.redis_client.hgetall.assert_called_once_with(
+        f"{workflow_module.WORKFLOW_ONLINE_USERS_PREFIX}{app_id_1}"
+    )
+    sign_avatar.assert_called_once_with("avatar-file-id")
+
+
+def test_workflow_online_users_rejects_excessive_workflow_ids(app, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(workflow_module, "current_account_with_tenant", lambda: (SimpleNamespace(), "tenant-1"))
+    accessible_app_ids = Mock(return_value=set())
+    monkeypatch.setattr(
+        workflow_module,
+        "WorkflowService",
+        lambda: SimpleNamespace(get_accessible_app_ids=accessible_app_ids),
+    )
+
+    excessive_ids = ",".join(f"wf-{index}" for index in range(workflow_module.MAX_WORKFLOW_ONLINE_USERS_QUERY_IDS + 1))
+
+    api = workflow_module.WorkflowOnlineUsersApi()
+    handler = _unwrap(api.get)
+
+    with app.test_request_context(
+        f"/apps/workflows/online-users?app_ids={excessive_ids}",
+        method="GET",
+    ):
+        with pytest.raises(HTTPException) as exc:
+            handler(api)
+
+    assert exc.value.code == 400
+    assert "Maximum" in exc.value.description
+    accessible_app_ids.assert_not_called()

api/tests/unit_tests/controllers/console/app/test_workflow_comment_api.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+from contextlib import nullcontext
+from dataclasses import dataclass
+from datetime import datetime
+from types import SimpleNamespace
+from unittest.mock import MagicMock, PropertyMock, patch
+
+import pytest
+from flask import Flask
+from werkzeug.exceptions import Forbidden
+
+from controllers.console import console_ns
+from controllers.console import wraps as console_wraps
+from controllers.console.app import workflow_comment as workflow_comment_module
+from controllers.console.app import wraps as app_wraps
+from libs import login as login_lib
+from models.account import Account, AccountStatus, TenantAccountRole
+
+
+def _make_account(role: TenantAccountRole) -> Account:
+    account = Account(name="tester", email="tester@example.com")
+    account.status = AccountStatus.ACTIVE
+    account.role = role
+    account.id = "account-123"  # type: ignore[assignment]
+    account._current_tenant = SimpleNamespace(id="tenant-123")  # type: ignore[attr-defined]
+    account._get_current_object = lambda: account  # type: ignore[attr-defined]
+    return account
+
+
+def _make_app() -> SimpleNamespace:
+    return SimpleNamespace(id="app-123", tenant_id="tenant-123", status="normal", mode="workflow")
+
+
+def _patch_console_guards(monkeypatch: pytest.MonkeyPatch, account: Account, app_model: SimpleNamespace) -> None:
+    monkeypatch.setattr(login_lib.dify_config, "LOGIN_DISABLED", True)
+    monkeypatch.setattr(login_lib, "current_user", account)
+    monkeypatch.setattr(login_lib, "current_account_with_tenant", lambda: (account, account.current_tenant_id))
+    monkeypatch.setattr(login_lib, "check_csrf_token", lambda *_, **__: None)
+    monkeypatch.setattr(console_wraps, "current_account_with_tenant", lambda: (account, account.current_tenant_id))
+    monkeypatch.setattr(console_wraps.dify_config, "EDITION", "CLOUD")
+    monkeypatch.setattr(app_wraps, "current_account_with_tenant", lambda: (account, account.current_tenant_id))
+    monkeypatch.setattr(app_wraps, "_load_app_model", lambda _app_id: app_model)
+    monkeypatch.setattr(workflow_comment_module, "current_user", account)
+
+
+def _patch_write_services(monkeypatch: pytest.MonkeyPatch) -> None:
+    for method_name in (
+        "create_comment",
+        "update_comment",
+        "delete_comment",
+        "resolve_comment",
+        "validate_comment_access",
+        "create_reply",
+        "update_reply",
+        "delete_reply",
+    ):
+        monkeypatch.setattr(workflow_comment_module.WorkflowCommentService, method_name, MagicMock())
+
+
+def _patch_payload(payload: dict[str, object] | None):
+    if payload is None:
+        return nullcontext()
+    return patch.object(
+        type(console_ns),
+        "payload",
+        new_callable=PropertyMock,
+        return_value=payload,
+    )
+
+
+@dataclass(frozen=True)
+class WriteCase:
+    resource_cls: type
+    method_name: str
+    path: str
+    kwargs: dict[str, str]
+    payload: dict[str, object] | None = None
+
+
+@pytest.mark.parametrize(
+    "case",
+    [
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentListApi,
+            method_name="post",
+            path="/console/api/apps/app-123/workflow/comments",
+            kwargs={"app_id": "app-123"},
+            payload={"content": "hello", "position_x": 1.0, "position_y": 2.0, "mentioned_user_ids": []},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentDetailApi,
+            method_name="put",
+            path="/console/api/apps/app-123/workflow/comments/comment-1",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1"},
+            payload={"content": "hello", "position_x": 1.0, "position_y": 2.0, "mentioned_user_ids": []},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentDetailApi,
+            method_name="delete",
+            path="/console/api/apps/app-123/workflow/comments/comment-1",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1"},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentResolveApi,
+            method_name="post",
+            path="/console/api/apps/app-123/workflow/comments/comment-1/resolve",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1"},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentReplyApi,
+            method_name="post",
+            path="/console/api/apps/app-123/workflow/comments/comment-1/replies",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1"},
+            payload={"content": "reply", "mentioned_user_ids": []},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentReplyDetailApi,
+            method_name="put",
+            path="/console/api/apps/app-123/workflow/comments/comment-1/replies/reply-1",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1", "reply_id": "reply-1"},
+            payload={"content": "reply", "mentioned_user_ids": []},
+        ),
+        WriteCase(
+            resource_cls=workflow_comment_module.WorkflowCommentReplyDetailApi,
+            method_name="delete",
+            path="/console/api/apps/app-123/workflow/comments/comment-1/replies/reply-1",
+            kwargs={"app_id": "app-123", "comment_id": "comment-1", "reply_id": "reply-1"},
+        ),
+    ],
+)
+def test_write_endpoints_require_edit_permission(app: Flask, monkeypatch: pytest.MonkeyPatch, case: WriteCase) -> None:
+    app.config.setdefault("RESTX_MASK_HEADER", "X-Fields")
+    account = _make_account(TenantAccountRole.NORMAL)
+    app_model = _make_app()
+    _patch_console_guards(monkeypatch, account, app_model)
+    _patch_write_services(monkeypatch)
+
+    with app.test_request_context(case.path, method=case.method_name.upper(), json=case.payload):
+        with _patch_payload(case.payload):
+            handler = getattr(case.resource_cls(), case.method_name)
+            with pytest.raises(Forbidden):
+                handler(**case.kwargs)
+
+
+def test_create_comment_allows_editor(app: Flask, monkeypatch: pytest.MonkeyPatch) -> None:
+    app.config.setdefault("RESTX_MASK_HEADER", "X-Fields")
+    account = _make_account(TenantAccountRole.EDITOR)
+    app_model = _make_app()
+    _patch_console_guards(monkeypatch, account, app_model)
+
+    create_comment_mock = MagicMock(return_value={"id": "comment-1"})
+    monkeypatch.setattr(workflow_comment_module.WorkflowCommentService, "create_comment", create_comment_mock)
+    payload = {"content": "hello", "position_x": 1.0, "position_y": 2.0, "mentioned_user_ids": []}
+
+    with app.test_request_context("/console/api/apps/app-123/workflow/comments", method="POST", json=payload):
+        with _patch_payload(payload):
+            result = workflow_comment_module.WorkflowCommentListApi().post(app_id="app-123")
+
+    if isinstance(result, tuple):
+        response = result[0]
+    else:
+        response = result
+    assert response["id"] == "comment-1"
+    create_comment_mock.assert_called_once_with(
+        tenant_id="tenant-123",
+        app_id="app-123",
+        created_by="account-123",
+        content="hello",
+        position_x=1.0,
+        position_y=2.0,
+        mentioned_user_ids=[],
+    )
+
+
+def test_update_comment_omits_mentions_when_payload_does_not_include_them(
+    app: Flask, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    app.config.setdefault("RESTX_MASK_HEADER", "X-Fields")
+    account = _make_account(TenantAccountRole.EDITOR)
+    app_model = _make_app()
+    _patch_console_guards(monkeypatch, account, app_model)
+
+    update_comment_mock = MagicMock(return_value={"id": "comment-1", "updated_at": datetime(2024, 1, 1, 12, 0, 0)})
+    monkeypatch.setattr(workflow_comment_module.WorkflowCommentService, "update_comment", update_comment_mock)
+    payload = {"content": "hello", "position_x": 10.0, "position_y": 20.0}
+
+    with app.test_request_context("/console/api/apps/app-123/workflow/comments/comment-1", method="PUT", json=payload):
+        with _patch_payload(payload):
+            workflow_comment_module.WorkflowCommentDetailApi().put(app_id="app-123", comment_id="comment-1")
+
+    update_comment_mock.assert_called_once_with(
+        tenant_id="tenant-123",
+        app_id="app-123",
+        comment_id="comment-1",
+        user_id="account-123",
+        content="hello",
+        position_x=10.0,
+        position_y=20.0,
+        mentioned_user_ids=None,
+    )

api/tests/unit_tests/controllers/service_api/app/test_hitl_service_api.py

@@ -0,0 +1,701 @@
+"""Dedicated tests for HITL behavior exposed through the Service API."""
+
+from __future__ import annotations
+
+import sys
+import json
+import queue
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from threading import Event
+from types import SimpleNamespace
+from unittest.mock import ANY, MagicMock, Mock
+
+import pytest
+
+import services.app_generate_service as ags_module
+from controllers.service_api.app.workflow_events import WorkflowEventsApi
+from core.app.app_config.entities import AppAdditionalFeatures, WorkflowUIBasedAppConfig
+from core.app.apps.common import workflow_response_converter
+from core.app.apps.common.workflow_response_converter import WorkflowResponseConverter
+from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity, InvokeFrom, WorkflowAppGenerateEntity
+from core.app.entities.queue_entities import QueueWorkflowPausedEvent
+from core.app.entities.task_entities import (
+    ChatbotAppPausedBlockingResponse,
+    HumanInputRequiredResponse,
+    WorkflowAppPausedBlockingResponse,
+    WorkflowPauseStreamResponse,
+)
+from core.app.layers.pause_state_persist_layer import WorkflowResumptionContext, _WorkflowGenerateEntityWrapper
+from graphon.entities import WorkflowStartReason
+from graphon.entities.pause_reason import HumanInputRequired, PauseReasonType
+from graphon.enums import WorkflowExecutionStatus, WorkflowNodeExecutionStatus
+from graphon.nodes.human_input.entities import FormInput, UserAction
+from graphon.nodes.human_input.enums import FormInputType
+from graphon.runtime import GraphRuntimeState, VariablePool
+from core.workflow.system_variables import build_system_variables
+from models.account import Account
+from models.enums import CreatorUserRole
+from models.model import AppMode
+from models.workflow import WorkflowRun
+from repositories.api_workflow_node_execution_repository import WorkflowNodeExecutionSnapshot
+from repositories.entities.workflow_pause import WorkflowPauseEntity
+from services.app_generate_service import AppGenerateService
+from services.workflow_event_snapshot_service import _build_snapshot_events
+from tests.unit_tests.controllers.service_api.conftest import _unwrap
+
+
+class _DummyRateLimit:
+    @staticmethod
+    def gen_request_key() -> str:
+        return "dummy-request-id"
+
+    def __init__(self, client_id: str, max_active_requests: int) -> None:
+        self.client_id = client_id
+        self.max_active_requests = max_active_requests
+
+    def enter(self, request_id: str | None = None) -> str:
+        return request_id or "dummy-request-id"
+
+    def exit(self, request_id: str) -> None:
+        return None
+
+    def generate(self, generator, request_id: str):
+        return generator
+
+
+def _mock_repo_for_run(monkeypatch: pytest.MonkeyPatch, workflow_run):
+    workflow_events_module = sys.modules["controllers.service_api.app.workflow_events"]
+    repo = SimpleNamespace(get_workflow_run_by_id_and_tenant_id=lambda **_kwargs: workflow_run)
+    monkeypatch.setattr(
+        workflow_events_module.DifyAPIRepositoryFactory,
+        "create_api_workflow_run_repository",
+        lambda *_args, **_kwargs: repo,
+    )
+    monkeypatch.setattr(workflow_events_module, "db", SimpleNamespace(engine=object()))
+    return workflow_events_module
+
+
+def _build_service_api_pause_converter() -> WorkflowResponseConverter:
+    application_generate_entity = SimpleNamespace(
+        inputs={},
+        files=[],
+        invoke_from=InvokeFrom.SERVICE_API,
+        app_config=SimpleNamespace(app_id="app-id", tenant_id="tenant-id"),
+    )
+    system_variables = build_system_variables(
+        user_id="user",
+        app_id="app-id",
+        workflow_id="workflow-id",
+        workflow_execution_id="run-id",
+    )
+    user = MagicMock(spec=Account)
+    user.id = "account-id"
+    user.name = "Tester"
+    user.email = "tester@example.com"
+    return WorkflowResponseConverter(
+        application_generate_entity=application_generate_entity,
+        user=user,
+        system_variables=system_variables,
+    )
+
+
+def _build_advanced_chat_paused_blocking_response() -> ChatbotAppPausedBlockingResponse:
+    data = ChatbotAppPausedBlockingResponse.Data(
+        id="msg-1",
+        mode="chat",
+        conversation_id="c1",
+        message_id="m1",
+        workflow_run_id="run-1",
+        answer="partial",
+        metadata={"usage": {"total_tokens": 1}},
+        created_at=1,
+        paused_nodes=["node-1"],
+        reasons=[
+            {
+                "type": PauseReasonType.HUMAN_INPUT_REQUIRED,
+                "form_id": "form-1",
+                "expiration_time": 100,
+            }
+        ],
+        status=WorkflowExecutionStatus.PAUSED,
+        elapsed_time=0.1,
+        total_tokens=0,
+        total_steps=0,
+    )
+    return ChatbotAppPausedBlockingResponse(task_id="t1", data=data)
+
+
+def _build_workflow_paused_blocking_response() -> WorkflowAppPausedBlockingResponse:
+    return WorkflowAppPausedBlockingResponse(
+        task_id="t1",
+        workflow_run_id="r1",
+        data=WorkflowAppPausedBlockingResponse.Data(
+            id="r1",
+            workflow_id="wf-1",
+            status=WorkflowExecutionStatus.PAUSED,
+            outputs={},
+            error=None,
+            elapsed_time=0.5,
+            total_tokens=0,
+            total_steps=2,
+            created_at=1,
+            finished_at=None,
+            paused_nodes=["node-1"],
+            reasons=[{"type": "human_input_required", "form_id": "form-1", "expiration_time": 100}],
+        ),
+    )
+
+
+@dataclass(frozen=True)
+class _FakePauseEntity(WorkflowPauseEntity):
+    pause_id: str
+    workflow_run_id: str
+    paused_at_value: datetime
+    pause_reasons: Sequence[HumanInputRequired]
+
+    @property
+    def id(self) -> str:
+        return self.pause_id
+
+    @property
+    def workflow_execution_id(self) -> str:
+        return self.workflow_run_id
+
+    def get_state(self) -> bytes:
+        raise AssertionError("state is not required for snapshot tests")
+
+    @property
+    def resumed_at(self) -> datetime | None:
+        return None
+
+    @property
+    def paused_at(self) -> datetime:
+        return self.paused_at_value
+
+    def get_pause_reasons(self) -> Sequence[HumanInputRequired]:
+        return self.pause_reasons
+
+
+def _build_workflow_run(status: WorkflowExecutionStatus) -> WorkflowRun:
+    return WorkflowRun(
+        id="run-1",
+        tenant_id="tenant-1",
+        app_id="app-1",
+        workflow_id="workflow-1",
+        type="workflow",
+        triggered_from="app-run",
+        version="v1",
+        graph=None,
+        inputs=json.dumps({"input": "value"}),
+        status=status,
+        outputs=json.dumps({}),
+        error=None,
+        elapsed_time=0.0,
+        total_tokens=0,
+        total_steps=0,
+        created_by_role=CreatorUserRole.END_USER,
+        created_by="user-1",
+        created_at=datetime(2024, 1, 1, tzinfo=UTC),
+    )
+
+
+def _build_snapshot(status: WorkflowNodeExecutionStatus) -> WorkflowNodeExecutionSnapshot:
+    created_at = datetime(2024, 1, 1, tzinfo=UTC)
+    finished_at = datetime(2024, 1, 1, 0, 0, 5, tzinfo=UTC)
+    return WorkflowNodeExecutionSnapshot(
+        execution_id="exec-1",
+        node_id="node-1",
+        node_type="human-input",
+        title="Human Input",
+        index=1,
+        status=status.value,
+        elapsed_time=0.5,
+        created_at=created_at,
+        finished_at=finished_at,
+        iteration_id=None,
+        loop_id=None,
+    )
+
+
+def _build_resumption_context(task_id: str) -> WorkflowResumptionContext:
+    app_config = WorkflowUIBasedAppConfig(
+        tenant_id="tenant-1",
+        app_id="app-1",
+        app_mode=AppMode.WORKFLOW,
+        workflow_id="workflow-1",
+    )
+    generate_entity = WorkflowAppGenerateEntity(
+        task_id=task_id,
+        app_config=app_config,
+        inputs={},
+        files=[],
+        user_id="user-1",
+        stream=True,
+        invoke_from=InvokeFrom.EXPLORE,
+        call_depth=0,
+        workflow_execution_id="run-1",
+    )
+    runtime_state = GraphRuntimeState(variable_pool=VariablePool(), start_at=0.0)
+    runtime_state.register_paused_node("node-1")
+    runtime_state.outputs = {"result": "value"}
+    wrapper = _WorkflowGenerateEntityWrapper(entity=generate_entity)
+    return WorkflowResumptionContext(
+        generate_entity=wrapper,
+        serialized_graph_runtime_state=runtime_state.dumps(),
+    )
+
+
+class TestHitlServiceApi:
+    # Service API event-stream continuation
+    def test_workflow_events_continue_on_pause_keeps_stream_open(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="end-user-1",
+            finished_at=None,
+        )
+        workflow_events_module = _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        msg_generator = Mock()
+        msg_generator.retrieve_events.return_value = ["raw-event"]
+        workflow_generator = Mock()
+        workflow_generator.convert_to_event_stream.return_value = iter(["data: streamed\n\n"])
+        monkeypatch.setattr(workflow_events_module, "MessageGenerator", lambda: msg_generator)
+        monkeypatch.setattr(workflow_events_module, "WorkflowAppGenerator", lambda: workflow_generator)
+
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1&continue_on_pause=true", method="GET"):
+            response = handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+        assert response.get_data(as_text=True) == "data: streamed\n\n"
+        msg_generator.retrieve_events.assert_called_once_with(
+            AppMode.WORKFLOW,
+            "run-1",
+            terminal_events=["workflow_finished"],
+        )
+        workflow_generator.convert_to_event_stream.assert_called_once_with(["raw-event"])
+
+    def test_workflow_events_snapshot_continue_on_pause_keeps_pause_open(
+        self, app, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="end-user-1",
+            finished_at=None,
+        )
+        workflow_events_module = _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        msg_generator = Mock()
+        workflow_generator = Mock()
+        workflow_generator.convert_to_event_stream.return_value = iter(["data: snapshot\n\n"])
+        snapshot_builder = Mock(return_value=["snapshot-events"])
+        monkeypatch.setattr(workflow_events_module, "MessageGenerator", lambda: msg_generator)
+        monkeypatch.setattr(workflow_events_module, "WorkflowAppGenerator", lambda: workflow_generator)
+        monkeypatch.setattr(workflow_events_module, "build_workflow_event_stream", snapshot_builder)
+
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context(
+            "/workflow/run-1/events?user=u1&include_state_snapshot=true&continue_on_pause=true",
+            method="GET",
+        ):
+            response = handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+        assert response.get_data(as_text=True) == "data: snapshot\n\n"
+        msg_generator.retrieve_events.assert_not_called()
+        snapshot_builder.assert_called_once_with(
+            app_mode=AppMode.WORKFLOW,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=ANY,
+            close_on_pause=False,
+        )
+        workflow_generator.convert_to_event_stream.assert_called_once_with(["snapshot-events"])
+
+    def test_advanced_chat_blocking_injects_pause_state_config(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setattr(ags_module.dify_config, "BILLING_ENABLED", False)
+        monkeypatch.setattr(ags_module, "RateLimit", _DummyRateLimit)
+
+        workflow = MagicMock()
+        workflow.created_by = "owner-id"
+        monkeypatch.setattr(AppGenerateService, "_get_workflow", lambda *args, **kwargs: workflow)
+        monkeypatch.setattr(ags_module.session_factory, "get_session_maker", lambda: "session-maker")
+
+        generator_instance = MagicMock()
+        generator_instance.generate.return_value = {"result": "advanced-blocking"}
+        generator_instance.convert_to_event_stream.side_effect = lambda payload: payload
+        monkeypatch.setattr(ags_module, "AdvancedChatAppGenerator", lambda: generator_instance)
+
+        app_model = MagicMock()
+        app_model.mode = AppMode.ADVANCED_CHAT
+        app_model.id = "app-id"
+        app_model.tenant_id = "tenant-id"
+        app_model.max_active_requests = 0
+        app_model.is_agent = False
+
+        user = MagicMock()
+        user.id = "user-id"
+
+        result = AppGenerateService.generate(
+            app_model=app_model,
+            user=user,
+            args={"workflow_id": None, "query": "hi", "inputs": {}},
+            invoke_from=InvokeFrom.SERVICE_API,
+            streaming=False,
+        )
+
+        assert result == {"result": "advanced-blocking"}
+        call_kwargs = generator_instance.generate.call_args.kwargs
+        assert call_kwargs["streaming"] is False
+        assert call_kwargs["pause_state_config"] is not None
+        assert call_kwargs["pause_state_config"].session_factory == "session-maker"
+        assert call_kwargs["pause_state_config"].state_owner_user_id == "owner-id"
+
+    # Blocking payload contract
+    def test_advanced_chat_blocking_pause_payload_contract(self) -> None:
+        from core.app.apps.advanced_chat.generate_response_converter import AdvancedChatAppGenerateResponseConverter
+
+        response = AdvancedChatAppGenerateResponseConverter.convert_blocking_full_response(
+            _build_advanced_chat_paused_blocking_response()
+        )
+
+        assert response["event"] == "workflow_paused"
+        assert response["workflow_run_id"] == "run-1"
+        assert response["answer"] == "partial"
+        assert response["data"]["reasons"][0]["type"] == PauseReasonType.HUMAN_INPUT_REQUIRED
+        assert response["data"]["reasons"][0]["expiration_time"] == 100
+        assert "human_input_forms" not in response["data"]
+
+    def test_workflow_blocking_pause_payload_contract(self) -> None:
+        from core.app.apps.workflow.generate_response_converter import WorkflowAppGenerateResponseConverter
+
+        response = WorkflowAppGenerateResponseConverter.convert_blocking_full_response(
+            _build_workflow_paused_blocking_response()
+        )
+
+        assert response["workflow_run_id"] == "r1"
+        assert response["data"]["status"] == WorkflowExecutionStatus.PAUSED
+        assert response["data"]["paused_nodes"] == ["node-1"]
+        assert response["data"]["reasons"] == [
+            {"type": "human_input_required", "form_id": "form-1", "expiration_time": 100}
+        ]
+        assert "human_input_forms" not in response["data"]
+
+    def test_advanced_chat_blocking_pipeline_pause_payload_contract(self) -> None:
+        from core.app.apps.advanced_chat.generate_task_pipeline import AdvancedChatAppGenerateTaskPipeline
+        from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity
+        from core.app.app_config.entities import AppAdditionalFeatures
+        from models.enums import MessageStatus
+        from models.model import EndUser
+
+        app_config = WorkflowUIBasedAppConfig(
+            tenant_id="tenant",
+            app_id="app",
+            app_mode=AppMode.ADVANCED_CHAT,
+            additional_features=AppAdditionalFeatures(),
+            variables=[],
+            workflow_id="workflow-id",
+        )
+        application_generate_entity = AdvancedChatAppGenerateEntity.model_construct(
+            task_id="task",
+            app_config=app_config,
+            inputs={},
+            query="hello",
+            files=[],
+            user_id="user",
+            stream=False,
+            invoke_from=InvokeFrom.WEB_APP,
+            extras={},
+            trace_manager=None,
+            workflow_run_id="run-id",
+        )
+        pipeline = AdvancedChatAppGenerateTaskPipeline(
+            application_generate_entity=application_generate_entity,
+            workflow=SimpleNamespace(id="workflow-id", tenant_id="tenant", features_dict={}),
+            queue_manager=SimpleNamespace(invoke_from=InvokeFrom.WEB_APP, graph_runtime_state=None),
+            conversation=SimpleNamespace(id="conv-id", mode=AppMode.ADVANCED_CHAT),
+            message=SimpleNamespace(
+                id="message-id",
+                query="hello",
+                created_at=datetime.utcnow(),
+                status=MessageStatus.NORMAL,
+                answer="",
+            ),
+            user=EndUser(tenant_id="tenant", type="session", name="tester", session_id="session"),
+            stream=False,
+            dialogue_count=1,
+            draft_var_saver_factory=lambda **kwargs: None,
+        )
+        pipeline._task_state.answer = "partial answer"
+        pipeline._workflow_run_id = "run-id"
+
+        def _gen():
+            yield HumanInputRequiredResponse(
+                task_id="task",
+                workflow_run_id="run-id",
+                data=HumanInputRequiredResponse.Data(
+                    form_id="form-1",
+                    node_id="node-1",
+                    node_title="Approval",
+                    form_content="Need approval",
+                    inputs=[],
+                    actions=[UserAction(id="approve", title="Approve")],
+                    display_in_ui=True,
+                    form_token="token-1",
+                    resolved_default_values={},
+                    expiration_time=123,
+                ),
+            )
+            yield WorkflowPauseStreamResponse(
+                task_id="task",
+                workflow_run_id="run-id",
+                data=WorkflowPauseStreamResponse.Data(
+                    workflow_run_id="run-id",
+                    paused_nodes=["node-1"],
+                    outputs={},
+                    reasons=[
+                        {
+                            "type": PauseReasonType.HUMAN_INPUT_REQUIRED,
+                            "form_id": "form-1",
+                            "node_id": "node-1",
+                            "expiration_time": 123,
+                        },
+                    ],
+                    status="paused",
+                    created_at=1,
+                    elapsed_time=0.1,
+                    total_tokens=0,
+                    total_steps=0,
+                ),
+            )
+
+        response = pipeline._to_blocking_response(_gen())
+
+        assert isinstance(response, ChatbotAppPausedBlockingResponse)
+        assert response.data.answer == "partial answer"
+        assert response.data.workflow_run_id == "run-id"
+        assert response.data.reasons[0]["form_id"] == "form-1"
+        assert response.data.reasons[0]["expiration_time"] == 123
+
+    def test_workflow_blocking_pipeline_pause_payload_contract(self) -> None:
+        from core.app.apps.workflow.generate_task_pipeline import WorkflowAppGenerateTaskPipeline
+
+        app_config = WorkflowUIBasedAppConfig(
+            tenant_id="tenant",
+            app_id="app",
+            app_mode=AppMode.WORKFLOW,
+            additional_features=AppAdditionalFeatures(),
+            variables=[],
+            workflow_id="workflow-id",
+        )
+        application_generate_entity = WorkflowAppGenerateEntity.model_construct(
+            task_id="task",
+            app_config=app_config,
+            inputs={},
+            files=[],
+            user_id="user",
+            stream=False,
+            invoke_from=InvokeFrom.WEB_APP,
+            trace_manager=None,
+            workflow_execution_id="run-id",
+            extras={},
+            call_depth=0,
+        )
+        pipeline = WorkflowAppGenerateTaskPipeline(
+            application_generate_entity=application_generate_entity,
+            workflow=SimpleNamespace(id="workflow-id", tenant_id="tenant", features_dict={}),
+            queue_manager=SimpleNamespace(invoke_from=InvokeFrom.WEB_APP, graph_runtime_state=None),
+            user=SimpleNamespace(id="user", session_id="session"),
+            stream=False,
+            draft_var_saver_factory=lambda **kwargs: None,
+        )
+
+        def _gen():
+            yield HumanInputRequiredResponse(
+                task_id="task",
+                workflow_run_id="run",
+                data=HumanInputRequiredResponse.Data(
+                    form_id="form-1",
+                    node_id="node-1",
+                    node_title="Human Input",
+                    form_content="content",
+                    expiration_time=1,
+                ),
+            )
+            yield WorkflowPauseStreamResponse(
+                task_id="task",
+                workflow_run_id="run",
+                data=WorkflowPauseStreamResponse.Data(
+                    workflow_run_id="run",
+                    status=WorkflowExecutionStatus.PAUSED,
+                    outputs={},
+                    paused_nodes=["node-1"],
+                    reasons=[{"type": "human_input_required", "form_id": "form-1", "expiration_time": 1}],
+                    created_at=1,
+                    elapsed_time=0.1,
+                    total_tokens=0,
+                    total_steps=0,
+                ),
+            )
+
+        response = pipeline._to_blocking_response(_gen())
+
+        assert isinstance(response, WorkflowAppPausedBlockingResponse)
+        assert response.data.status == WorkflowExecutionStatus.PAUSED
+        assert response.data.paused_nodes == ["node-1"]
+        assert response.data.reasons == [
+            {"type": "human_input_required", "form_id": "form-1", "expiration_time": 1}
+        ]
+
+    def test_service_api_pause_event_serializes_hitl_reason(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        converter = _build_service_api_pause_converter()
+        converter.workflow_start_to_stream_response(
+            task_id="task",
+            workflow_run_id="run-id",
+            workflow_id="workflow-id",
+            reason=WorkflowStartReason.INITIAL,
+        )
+
+        expiration_time = datetime(2024, 1, 1, tzinfo=UTC)
+
+        class _FakeSession:
+            def execute(self, _stmt):
+                return [("form-1", expiration_time, '{"display_in_ui": true}')]
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+        monkeypatch.setattr(workflow_response_converter, "Session", lambda **_: _FakeSession())
+        monkeypatch.setattr(workflow_response_converter, "db", SimpleNamespace(engine=object()))
+        monkeypatch.setattr(
+            workflow_response_converter,
+            "load_form_tokens_by_form_id",
+            lambda form_ids, session=None: {"form-1": "token"},
+        )
+
+        reason = HumanInputRequired(
+            form_id="form-1",
+            form_content="Rendered",
+            inputs=[
+                FormInput(type=FormInputType.TEXT_INPUT, output_variable_name="field", default=None),
+            ],
+            actions=[UserAction(id="approve", title="Approve")],
+            display_in_ui=True,
+            node_id="node-id",
+            node_title="Human Step",
+            form_token="token",
+        )
+        queue_event = QueueWorkflowPausedEvent(
+            reasons=[reason],
+            outputs={"answer": "value"},
+            paused_nodes=["node-id"],
+        )
+
+        runtime_state = SimpleNamespace(total_tokens=0, node_run_steps=0)
+        responses = converter.workflow_pause_to_stream_response(
+            event=queue_event,
+            task_id="task",
+            graph_runtime_state=runtime_state,
+        )
+
+        assert isinstance(responses[-1], WorkflowPauseStreamResponse)
+        pause_resp = responses[-1]
+        assert pause_resp.workflow_run_id == "run-id"
+        assert pause_resp.data.paused_nodes == ["node-id"]
+        assert pause_resp.data.outputs == {}
+        assert pause_resp.data.reasons[0]["type"] == "human_input_required"
+        assert pause_resp.data.reasons[0]["form_id"] == "form-1"
+        assert pause_resp.data.reasons[0]["form_token"] == "token"
+        assert pause_resp.data.reasons[0]["expiration_time"] == int(expiration_time.timestamp())
+
+        assert isinstance(responses[0], HumanInputRequiredResponse)
+        hi_resp = responses[0]
+        assert hi_resp.data.form_id == "form-1"
+        assert hi_resp.data.node_id == "node-id"
+        assert hi_resp.data.node_title == "Human Step"
+        assert hi_resp.data.inputs[0].output_variable_name == "field"
+        assert hi_resp.data.actions[0].id == "approve"
+        assert hi_resp.data.display_in_ui is True
+        assert hi_resp.data.form_token == "token"
+        assert hi_resp.data.expiration_time == int(expiration_time.timestamp())
+
+    # Snapshot payload contract
+    def test_snapshot_events_include_pause_payload_contract(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = _build_workflow_run(WorkflowExecutionStatus.PAUSED)
+        snapshot = _build_snapshot(WorkflowNodeExecutionStatus.PAUSED)
+        resumption_context = _build_resumption_context("task-ctx")
+        monkeypatch.setattr("services.workflow_event_snapshot_service.load_form_tokens_by_form_id", lambda form_ids, session=None: {"form-1": "wtok"})
+
+        class _SessionContext:
+            def __init__(self, session):
+                self._session = session
+
+            def __enter__(self):
+                return self._session
+
+            def __exit__(self, exc_type, exc, tb):
+                return False
+
+        session_maker = lambda: _SessionContext(
+            SimpleNamespace(
+                execute=lambda _stmt: [("form-1", datetime(2024, 1, 1, tzinfo=UTC), '{"display_in_ui": true}')],
+            )
+        )
+        pause_entity = _FakePauseEntity(
+            pause_id="pause-1",
+            workflow_run_id="run-1",
+            paused_at_value=datetime(2024, 1, 1, tzinfo=UTC),
+            pause_reasons=[
+                HumanInputRequired(
+                    form_id="form-1",
+                    form_content="content",
+                    node_id="node-1",
+                    node_title="Human Input",
+                    form_token="wtok",
+                )
+            ],
+        )
+
+        events = _build_snapshot_events(
+            workflow_run=workflow_run,
+            node_snapshots=[snapshot],
+            task_id="task-ctx",
+            message_context=None,
+            pause_entity=pause_entity,
+            resumption_context=resumption_context,
+            session_maker=session_maker,
+        )
+
+        assert [event["event"] for event in events] == [
+            "workflow_started",
+            "node_started",
+            "node_finished",
+            "human_input_required",
+            "workflow_paused",
+        ]
+        assert events[2]["data"]["status"] == WorkflowNodeExecutionStatus.PAUSED.value
+        assert events[3]["data"]["form_token"] == "wtok"
+        pause_data = events[-1]["data"]
+        assert pause_data["paused_nodes"] == ["node-1"]
+        assert pause_data["outputs"] == {"result": "value"}
+        assert pause_data["reasons"][0]["type"] == "human_input_required"
+        assert pause_data["reasons"][0]["form_token"] == "wtok"
+        assert pause_data["status"] == WorkflowExecutionStatus.PAUSED.value
+        assert pause_data["created_at"] == int(workflow_run.created_at.timestamp())
+        assert pause_data["elapsed_time"] == workflow_run.elapsed_time
+        assert pause_data["total_tokens"] == workflow_run.total_tokens
+        assert pause_data["total_steps"] == workflow_run.total_steps

api/tests/unit_tests/controllers/service_api/app/test_human_input_form.py

@@ -0,0 +1,111 @@
+"""Unit tests for Service API human input form endpoints."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+from werkzeug.exceptions import NotFound
+
+from controllers.service_api.app.human_input_form import WorkflowHumanInputFormApi
+from models.human_input import RecipientType
+from tests.unit_tests.controllers.service_api.conftest import _unwrap
+
+
+class TestWorkflowHumanInputFormApi:
+    def test_get_success(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        definition = SimpleNamespace(
+            model_dump=lambda: {
+                "rendered_content": "Rendered form content",
+                "inputs": [{"output_variable_name": "name"}],
+                "default_values": {"name": "Alice", "age": 30, "meta": {"k": "v"}},
+                "user_actions": [{"id": "approve", "title": "Approve"}],
+            }
+        )
+        form = SimpleNamespace(
+            app_id="app-1",
+            tenant_id="tenant-1",
+            expiration_time=datetime(2099, 1, 1, tzinfo=UTC),
+            get_definition=lambda: definition,
+        )
+        service_mock = Mock()
+        service_mock.get_form_by_token.return_value = form
+        workflow_module = sys.modules["controllers.service_api.app.human_input_form"]
+        monkeypatch.setattr(workflow_module, "HumanInputService", lambda _engine: service_mock)
+        monkeypatch.setattr(workflow_module, "db", SimpleNamespace(engine=object()))
+
+        api = WorkflowHumanInputFormApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1")
+
+        with app.test_request_context("/form/human_input/token-1", method="GET"):
+            response = handler(api, app_model=app_model, form_token="token-1")
+
+        payload = json.loads(response.get_data(as_text=True))
+        assert payload == {
+            "form_content": "Rendered form content",
+            "inputs": [{"output_variable_name": "name"}],
+            "resolved_default_values": {"name": "Alice", "age": "30", "meta": '{"k": "v"}'},
+            "user_actions": [{"id": "approve", "title": "Approve"}],
+            "expiration_time": int(form.expiration_time.timestamp()),
+        }
+        service_mock.get_form_by_token.assert_called_once_with("token-1")
+        service_mock.ensure_form_active.assert_called_once_with(form)
+
+    def test_get_form_not_in_app(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        form = SimpleNamespace(
+            app_id="another-app",
+            tenant_id="tenant-1",
+            expiration_time=datetime(2099, 1, 1, tzinfo=UTC),
+        )
+        service_mock = Mock()
+        service_mock.get_form_by_token.return_value = form
+        workflow_module = sys.modules["controllers.service_api.app.human_input_form"]
+        monkeypatch.setattr(workflow_module, "HumanInputService", lambda _engine: service_mock)
+        monkeypatch.setattr(workflow_module, "db", SimpleNamespace(engine=object()))
+
+        api = WorkflowHumanInputFormApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1")
+
+        with app.test_request_context("/form/human_input/token-1", method="GET"):
+            with pytest.raises(NotFound):
+                handler(api, app_model=app_model, form_token="token-1")
+
+    def test_post_success(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        form = SimpleNamespace(
+            app_id="app-1",
+            tenant_id="tenant-1",
+            recipient_type=RecipientType.BACKSTAGE,
+        )
+        service_mock = Mock()
+        service_mock.get_form_by_token.return_value = form
+        workflow_module = sys.modules["controllers.service_api.app.human_input_form"]
+        monkeypatch.setattr(workflow_module, "HumanInputService", lambda _engine: service_mock)
+        monkeypatch.setattr(workflow_module, "db", SimpleNamespace(engine=object()))
+
+        api = WorkflowHumanInputFormApi()
+        handler = _unwrap(api.post)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1")
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context(
+            "/form/human_input/token-1",
+            method="POST",
+            json={"inputs": {"name": "Alice"}, "action": "approve", "user": "external-1"},
+        ):
+            response, status = handler(api, app_model=app_model, end_user=end_user, form_token="token-1")
+
+        assert response == {}
+        assert status == 200
+        service_mock.submit_form_by_token.assert_called_once_with(
+            recipient_type=RecipientType.BACKSTAGE,
+            form_token="token-1",
+            selected_action_id="approve",
+            form_data={"name": "Alice"},
+            submission_end_user_id="end-user-1",
+        )

api/tests/unit_tests/controllers/service_api/app/test_workflow_events.py

@@ -0,0 +1,166 @@
+"""Unit tests for Service API workflow event stream endpoints."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import ANY, Mock
+
+import pytest
+from werkzeug.exceptions import NotFound
+
+from controllers.service_api.app.error import NotWorkflowAppError
+from controllers.service_api.app.workflow_events import WorkflowEventsApi
+from models.enums import CreatorUserRole
+from models.model import AppMode
+from tests.unit_tests.controllers.service_api.conftest import _unwrap
+
+
+def _mock_repo_for_run(monkeypatch: pytest.MonkeyPatch, workflow_run):
+    workflow_events_module = sys.modules["controllers.service_api.app.workflow_events"]
+    repo = SimpleNamespace(get_workflow_run_by_id_and_tenant_id=lambda **_kwargs: workflow_run)
+    monkeypatch.setattr(
+        workflow_events_module.DifyAPIRepositoryFactory,
+        "create_api_workflow_run_repository",
+        lambda *_args, **_kwargs: repo,
+    )
+    monkeypatch.setattr(workflow_events_module, "db", SimpleNamespace(engine=object()))
+    return workflow_events_module
+
+
+class TestWorkflowEventsApi:
+    def test_wrong_app_mode(self, app) -> None:
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(mode=AppMode.CHAT.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1", method="GET"):
+            with pytest.raises(NotWorkflowAppError):
+                handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+    def test_workflow_run_not_found(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        _mock_repo_for_run(monkeypatch, workflow_run=None)
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1", method="GET"):
+            with pytest.raises(NotFound):
+                handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+    def test_workflow_run_permission_denied(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.ACCOUNT,
+            created_by="another-user",
+            finished_at=None,
+        )
+        _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1", method="GET"):
+            with pytest.raises(NotFound):
+                handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+    def test_finished_run_returns_sse(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="end-user-1",
+            finished_at=datetime(2099, 1, 1, tzinfo=UTC),
+        )
+        workflow_events_module = _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        monkeypatch.setattr(
+            workflow_events_module.WorkflowResponseConverter,
+            "workflow_run_result_to_finish_response",
+            lambda **_kwargs: SimpleNamespace(
+                model_dump=lambda mode="json": {"task_id": "run-1", "status": "succeeded"},
+                event=SimpleNamespace(value="workflow_finished"),
+            ),
+        )
+
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1", method="GET"):
+            response = handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+        assert response.mimetype == "text/event-stream"
+        body = response.get_data(as_text=True).strip()
+        assert body.startswith("data: ")
+        payload = json.loads(body[len("data: ") :])
+        assert payload["task_id"] == "run-1"
+        assert payload["event"] == "workflow_finished"
+
+    def test_running_run_streams_events(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="end-user-1",
+            finished_at=None,
+        )
+        workflow_events_module = _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        msg_generator = Mock()
+        msg_generator.retrieve_events.return_value = ["raw-event"]
+        workflow_generator = Mock()
+        workflow_generator.convert_to_event_stream.return_value = iter(["data: streamed\n\n"])
+        monkeypatch.setattr(workflow_events_module, "MessageGenerator", lambda: msg_generator)
+        monkeypatch.setattr(workflow_events_module, "WorkflowAppGenerator", lambda: workflow_generator)
+
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1", method="GET"):
+            response = handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+        assert response.get_data(as_text=True) == "data: streamed\n\n"
+        msg_generator.retrieve_events.assert_called_once_with(
+            AppMode.WORKFLOW,
+            "run-1",
+            terminal_events=None,
+        )
+        workflow_generator.convert_to_event_stream.assert_called_once_with(["raw-event"])
+
+    def test_running_run_with_snapshot(self, app, monkeypatch: pytest.MonkeyPatch) -> None:
+        workflow_run = SimpleNamespace(
+            id="run-1",
+            app_id="app-1",
+            created_by_role=CreatorUserRole.END_USER,
+            created_by="end-user-1",
+            finished_at=None,
+        )
+        workflow_events_module = _mock_repo_for_run(monkeypatch, workflow_run=workflow_run)
+        msg_generator = Mock()
+        workflow_generator = Mock()
+        workflow_generator.convert_to_event_stream.return_value = iter(["data: snapshot\n\n"])
+        snapshot_builder = Mock(return_value=["snapshot-events"])
+        monkeypatch.setattr(workflow_events_module, "MessageGenerator", lambda: msg_generator)
+        monkeypatch.setattr(workflow_events_module, "WorkflowAppGenerator", lambda: workflow_generator)
+        monkeypatch.setattr(workflow_events_module, "build_workflow_event_stream", snapshot_builder)
+
+        api = WorkflowEventsApi()
+        handler = _unwrap(api.get)
+        app_model = SimpleNamespace(id="app-1", tenant_id="tenant-1", mode=AppMode.WORKFLOW.value)
+        end_user = SimpleNamespace(id="end-user-1")
+
+        with app.test_request_context("/workflow/run-1/events?user=u1&include_state_snapshot=true", method="GET"):
+            response = handler(api, app_model=app_model, end_user=end_user, task_id="run-1")
+
+        assert response.get_data(as_text=True) == "data: snapshot\n\n"
+        msg_generator.retrieve_events.assert_not_called()
+        snapshot_builder.assert_called_once()
+        workflow_generator.convert_to_event_stream.assert_called_once_with(["snapshot-events"])

api/tests/unit_tests/core/app/apps/advanced_chat/test_generate_response_converter.py

@@ -1,10 +1,10 @@
 from collections.abc import Generator
 
-from graphon.enums import WorkflowNodeExecutionStatus
-
+import pytest
 from core.app.apps.advanced_chat.generate_response_converter import AdvancedChatAppGenerateResponseConverter
 from core.app.entities.task_entities import (
     ChatbotAppBlockingResponse,
+    ChatbotAppPausedBlockingResponse,
     ChatbotAppStreamResponse,
     ErrorStreamResponse,
     MessageEndStreamResponse,
@@ -12,6 +12,8 @@ from core.app.entities.task_entities import (
     NodeStartStreamResponse,
     PingStreamResponse,
 )
+from graphon.entities.pause_reason import PauseReasonType
+from graphon.enums import WorkflowExecutionStatus, WorkflowNodeExecutionStatus
 
 
 class TestAdvancedChatGenerateResponseConverter:
@@ -29,6 +31,37 @@ class TestAdvancedChatGenerateResponseConverter:
         response = AdvancedChatAppGenerateResponseConverter.convert_blocking_simple_response(blocking)
         assert "usage" not in response["metadata"]
 
+    def test_blocking_full_response_derives_pause_data_from_model_dump(self, monkeypatch: pytest.MonkeyPatch):
+        data = ChatbotAppPausedBlockingResponse.Data(
+            id="msg-1",
+            mode="chat",
+            conversation_id="c1",
+            message_id="m1",
+            workflow_run_id="run-1",
+            answer="partial",
+            metadata={"usage": {"total_tokens": 1}},
+            created_at=1,
+            paused_nodes=["node-1"],
+            reasons=[{"type": PauseReasonType.HUMAN_INPUT_REQUIRED, "form_id": "form-1"}],
+            status=WorkflowExecutionStatus.PAUSED,
+            elapsed_time=0.1,
+            total_tokens=0,
+            total_steps=0,
+        )
+        original_model_dump = type(data).model_dump
+
+        def _model_dump_with_future_field(self, *args, **kwargs):
+            payload = original_model_dump(self, *args, **kwargs)
+            payload["future_field"] = "future-value"
+            return payload
+
+        monkeypatch.setattr(type(data), "model_dump", _model_dump_with_future_field)
+        blocking = ChatbotAppPausedBlockingResponse(task_id="t1", data=data)
+
+        response = AdvancedChatAppGenerateResponseConverter.convert_blocking_full_response(blocking)
+
+        assert response["data"]["future_field"] == "future-value"
+
     def test_stream_simple_response_includes_node_events(self):
         node_start = NodeStartStreamResponse(
             task_id="t1",

api/tests/unit_tests/core/app/apps/advanced_chat/test_generate_task_pipeline_core.py

@@ -41,15 +41,20 @@ from core.app.entities.queue_entities import (
     QueueWorkflowSucceededEvent,
 )
 from core.app.entities.task_entities import (
+    ChatbotAppPausedBlockingResponse,
+    HumanInputRequiredResponse,
     AnnotationReply,
     AnnotationReplyAccount,
     MessageAudioStreamResponse,
     MessageEndStreamResponse,
     PingStreamResponse,
+    WorkflowPauseStreamResponse,
 )
 from core.base.tts.app_generator_tts_publisher import AudioTrunk
 from core.workflow.system_variables import build_system_variables
 from libs.datetime_utils import naive_utc_now
+from graphon.entities.pause_reason import PauseReasonType
+from graphon.nodes.human_input.entities import UserAction
 from models.enums import MessageStatus
 from models.model import AppMode, EndUser
 from tests.workflow_test_utils import build_test_variable_pool
@@ -123,6 +128,57 @@ class TestAdvancedChatGenerateTaskPipeline:
         assert response.data.answer == "done"
         assert response.data.metadata == {"k": "v"}
 
+    def test_to_blocking_response_falls_back_to_human_input_required_when_pause_event_missing(self):
+        pipeline = _make_pipeline()
+        pipeline._task_state.answer = "partial answer"
+        pipeline._workflow_run_id = "run-id"
+        pipeline._graph_runtime_state = GraphRuntimeState(
+            variable_pool=VariablePool(system_variables=build_system_variables(workflow_execution_id="run-id")),
+            start_at=0.0,
+            total_tokens=7,
+            node_run_steps=3,
+        )
+
+        def _gen():
+            yield HumanInputRequiredResponse(
+                task_id="task",
+                workflow_run_id="run-id",
+                data=HumanInputRequiredResponse.Data(
+                    form_id="form-1",
+                    node_id="node-1",
+                    node_title="Approval",
+                    form_content="Need approval",
+                    inputs=[],
+                    actions=[UserAction(id="approve", title="Approve")],
+                    display_in_ui=True,
+                    form_token="token-1",
+                    resolved_default_values={},
+                    expiration_time=123,
+                ),
+            )
+
+        response = pipeline._to_blocking_response(_gen())
+
+        assert isinstance(response, ChatbotAppPausedBlockingResponse)
+        assert response.data.workflow_run_id == "run-id"
+        assert response.data.status == "paused"
+        assert response.data.paused_nodes == ["node-1"]
+        assert response.data.reasons == [
+            {
+                "type": PauseReasonType.HUMAN_INPUT_REQUIRED,
+                "form_id": "form-1",
+                "node_id": "node-1",
+                "node_title": "Approval",
+                "form_content": "Need approval",
+                "inputs": [],
+                "actions": [{"id": "approve", "title": "Approve", "button_style": "default"}],
+                "display_in_ui": True,
+                "form_token": "token-1",
+                "resolved_default_values": {},
+                "expiration_time": 123,
+            }
+        ]
+
     def test_handle_text_chunk_event_updates_state(self):
         pipeline = _make_pipeline()
         pipeline._message_cycle_manager = SimpleNamespace(

api/tests/unit_tests/core/app/apps/test_base_app_generate_response_converter.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverter
+from core.app.entities.app_invoke_entities import InvokeFrom
+from core.app.entities.task_entities import (
+    AppStreamResponse,
+    PingStreamResponse,
+    WorkflowAppBlockingResponse,
+    WorkflowAppStreamResponse,
+)
+from graphon.enums import WorkflowExecutionStatus
+
+
+class _DummyConverter(AppGenerateResponseConverter[WorkflowAppBlockingResponse]):
+    blocking_full_calls: list[WorkflowAppBlockingResponse] = []
+    blocking_simple_calls: list[WorkflowAppBlockingResponse] = []
+    stream_full_calls: list[Generator[AppStreamResponse, None, None]] = []
+    stream_simple_calls: list[Generator[AppStreamResponse, None, None]] = []
+
+    @classmethod
+    def reset(cls) -> None:
+        cls.blocking_full_calls = []
+        cls.blocking_simple_calls = []
+        cls.stream_full_calls = []
+        cls.stream_simple_calls = []
+
+    @classmethod
+    def convert_blocking_full_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
+        cls.blocking_full_calls.append(blocking_response)
+        return {"kind": "blocking-full", "task_id": blocking_response.task_id}
+
+    @classmethod
+    def convert_blocking_simple_response(cls, blocking_response: WorkflowAppBlockingResponse) -> dict[str, object]:
+        cls.blocking_simple_calls.append(blocking_response)
+        return {"kind": "blocking-simple", "task_id": blocking_response.task_id}
+
+    @classmethod
+    def convert_stream_full_response(
+        cls, stream_response: Generator[AppStreamResponse, None, None]
+    ) -> Generator[dict | str, None, None]:
+        cls.stream_full_calls.append(stream_response)
+        yield {"kind": "stream-full"}
+
+    @classmethod
+    def convert_stream_simple_response(
+        cls, stream_response: Generator[AppStreamResponse, None, None]
+    ) -> Generator[dict | str, None, None]:
+        cls.stream_simple_calls.append(stream_response)
+        yield {"kind": "stream-simple"}
+
+
+def _build_blocking_response() -> WorkflowAppBlockingResponse:
+    return WorkflowAppBlockingResponse(
+        task_id="task-1",
+        workflow_run_id="run-1",
+        data=WorkflowAppBlockingResponse.Data(
+            id="run-1",
+            workflow_id="workflow-1",
+            status=WorkflowExecutionStatus.SUCCEEDED,
+            outputs={"ok": True},
+            error=None,
+            elapsed_time=0.1,
+            total_tokens=0,
+            total_steps=1,
+            created_at=1,
+            finished_at=2,
+        ),
+    )
+
+
+def _build_stream_response() -> Generator[AppStreamResponse, None, None]:
+    yield WorkflowAppStreamResponse(
+        workflow_run_id="run-1",
+        stream_response=PingStreamResponse(task_id="task-1"),
+    )
+
+
+def test_convert_routes_blocking_response_by_invoke_from() -> None:
+    _DummyConverter.reset()
+    blocking_response = _build_blocking_response()
+
+    full_result = _DummyConverter.convert(blocking_response, InvokeFrom.SERVICE_API)
+    simple_result = _DummyConverter.convert(blocking_response, InvokeFrom.WEB_APP)
+
+    assert full_result == {"kind": "blocking-full", "task_id": "task-1"}
+    assert simple_result == {"kind": "blocking-simple", "task_id": "task-1"}
+    assert _DummyConverter.blocking_full_calls == [blocking_response]
+    assert _DummyConverter.blocking_simple_calls == [blocking_response]
+
+
+def test_convert_routes_stream_response_by_invoke_from() -> None:
+    _DummyConverter.reset()
+
+    full_result = list(_DummyConverter.convert(_build_stream_response(), InvokeFrom.SERVICE_API))
+    simple_result = list(_DummyConverter.convert(_build_stream_response(), InvokeFrom.WEB_APP))
+
+    assert full_result == [{"kind": "stream-full"}]
+    assert simple_result == [{"kind": "stream-simple"}]
+    assert len(_DummyConverter.stream_full_calls) == 1
+    assert len(_DummyConverter.stream_simple_calls) == 1

api/tests/unit_tests/core/app/apps/test_message_generator.py

@@ -1,5 +1,6 @@
 from unittest.mock import Mock, patch
 
+from core.app.entities.task_entities import StreamEvent
 from core.app.apps.message_generator import MessageGenerator
 from models.model import AppMode
 
@@ -23,7 +24,21 @@ class TestMessageGenerator:
                 "core.app.apps.message_generator.stream_topic_events", return_value=iter([{"event": "ping"}])
             ) as mock_stream,
         ):
-            events = list(MessageGenerator.retrieve_events(AppMode.WORKFLOW, "run-1", idle_timeout=1, ping_interval=2))
+            events = list(
+                MessageGenerator.retrieve_events(
+                    AppMode.WORKFLOW,
+                    "run-1",
+                    idle_timeout=1,
+                    ping_interval=2,
+                    terminal_events=[StreamEvent.WORKFLOW_FINISHED.value],
+                )
+            )
 
         assert events == [{"event": "ping"}]
-        mock_stream.assert_called_once()
+        mock_stream.assert_called_once_with(
+            topic="topic",
+            idle_timeout=1,
+            ping_interval=2,
+            on_subscribe=None,
+            terminal_events=[StreamEvent.WORKFLOW_FINISHED.value],
+        )

api/tests/unit_tests/core/app/apps/test_streaming_utils.py

@@ -106,3 +106,21 @@ def test_stream_topic_events_emits_ping_and_idle_timeout(monkeypatch):
     assert next(generator) == StreamEvent.PING.value
     # next receive yields None -> ping interval triggers
     assert next(generator) == StreamEvent.PING.value
+
+
+def test_stream_topic_events_can_continue_past_pause():
+    topic = FakeTopic()
+    topic.publish(json.dumps({"event": StreamEvent.WORKFLOW_PAUSED.value}).encode())
+    topic.publish(json.dumps({"event": StreamEvent.WORKFLOW_FINISHED.value}).encode())
+
+    generator = stream_topic_events(
+        topic=topic,
+        idle_timeout=1.0,
+        terminal_events=[StreamEvent.WORKFLOW_FINISHED.value],
+    )
+
+    assert next(generator) == StreamEvent.PING.value
+    assert next(generator)["event"] == StreamEvent.WORKFLOW_PAUSED.value
+    assert next(generator)["event"] == StreamEvent.WORKFLOW_FINISHED.value
+    with pytest.raises(StopIteration):
+        next(generator)

api/tests/unit_tests/core/app/apps/test_workflow_pause_events.py

@@ -90,7 +90,6 @@ def test_graph_run_paused_event_emits_queue_pause_event():
     assert queue_event.outputs == {"foo": "bar"}
     assert queue_event.paused_nodes == ["node-pause-1"]
 
-
 def _build_converter():
     application_generate_entity = SimpleNamespace(
         inputs={},

api/tests/unit_tests/core/app/apps/workflow/test_generate_response_converter.py

@@ -9,6 +9,7 @@ from core.app.entities.task_entities import (
     NodeStartStreamResponse,
     PingStreamResponse,
     WorkflowAppBlockingResponse,
+    WorkflowAppPausedBlockingResponse,
     WorkflowAppStreamResponse,
 )
 

api/tests/unit_tests/core/app/apps/workflow/test_generate_task_pipeline_core.py

@@ -38,10 +38,12 @@ from core.app.entities.queue_entities import (
 )
 from core.app.entities.task_entities import (
     ErrorStreamResponse,
+    HumanInputRequiredResponse,
     MessageAudioEndStreamResponse,
     MessageAudioStreamResponse,
     PingStreamResponse,
     WorkflowFinishStreamResponse,
+    WorkflowAppPausedBlockingResponse,
     WorkflowPauseStreamResponse,
     WorkflowStartStreamResponse,
 )
@@ -91,27 +93,49 @@ def _make_pipeline():
 
 
 class TestWorkflowGenerateTaskPipeline:
-    def test_to_blocking_response_handles_pause(self):
+    def test_to_blocking_response_falls_back_to_human_input_required_when_pause_event_missing(self):
         pipeline = _make_pipeline()
+        pipeline._graph_runtime_state = GraphRuntimeState(
+            variable_pool=VariablePool(system_variables=build_system_variables(workflow_execution_id="run-id")),
+            start_at=0.0,
+            total_tokens=5,
+            node_run_steps=2,
+        )
 
         def _gen():
-            yield WorkflowPauseStreamResponse(
+            yield HumanInputRequiredResponse(
                 task_id="task",
-                workflow_run_id="run",
-                data=WorkflowPauseStreamResponse.Data(
-                    workflow_run_id="run",
-                    status=WorkflowExecutionStatus.PAUSED,
-                    outputs={},
-                    created_at=1,
-                    elapsed_time=0.1,
-                    total_tokens=0,
-                    total_steps=0,
+                workflow_run_id="run-id",
+                data=HumanInputRequiredResponse.Data(
+                    form_id="form-1",
+                    node_id="node-1",
+                    node_title="Human Input",
+                    form_content="content",
+                    expiration_time=1,
                 ),
             )
 
         response = pipeline._to_blocking_response(_gen())
 
+        assert isinstance(response, WorkflowAppPausedBlockingResponse)
+        assert response.workflow_run_id == "run-id"
         assert response.data.status == WorkflowExecutionStatus.PAUSED
+        assert response.data.paused_nodes == ["node-1"]
+        assert response.data.reasons == [
+            {
+                "type": "human_input_required",
+                "form_id": "form-1",
+                "node_id": "node-1",
+                "node_title": "Human Input",
+                "form_content": "content",
+                "inputs": [],
+                "actions": [],
+                "display_in_ui": False,
+                "form_token": None,
+                "resolved_default_values": {},
+                "expiration_time": 1,
+            }
+        ]
 
     def test_to_blocking_response_handles_finish(self):
         pipeline = _make_pipeline()

api/tests/unit_tests/libs/test_email_i18n.py

@@ -503,6 +503,7 @@ class TestEmailI18nIntegration:
             EmailType.ACCOUNT_DELETION_VERIFICATION,
             EmailType.QUEUE_MONITOR_ALERT,
             EmailType.DOCUMENT_CLEAN_NOTIFY,
+            EmailType.WORKFLOW_COMMENT_MENTION,
         ]
 
         for email_type in expected_types:

api/tests/unit_tests/models/test_comment_models.py

@@ -0,0 +1,100 @@
+from unittest.mock import Mock, patch
+
+from models.comment import WorkflowComment, WorkflowCommentMention, WorkflowCommentReply
+
+
+def test_workflow_comment_account_properties_and_cache() -> None:
+    comment = WorkflowComment(created_by="user-1", resolved_by="user-2", content="hello", position_x=1, position_y=2)
+    created_account = Mock(id="user-1")
+    resolved_account = Mock(id="user-2")
+
+    with patch("models.comment.db.session.get", side_effect=[created_account, resolved_account]) as get_mock:
+        assert comment.created_by_account is created_account
+        assert comment.resolved_by_account is resolved_account
+        assert get_mock.call_count == 2
+
+    comment.cache_created_by_account(created_account)
+    comment.cache_resolved_by_account(resolved_account)
+    with patch("models.comment.db.session.get") as get_mock:
+        assert comment.created_by_account is created_account
+        assert comment.resolved_by_account is resolved_account
+        get_mock.assert_not_called()
+
+    comment_without_resolver = WorkflowComment(
+        created_by="user-1",
+        resolved_by=None,
+        content="hello",
+        position_x=1,
+        position_y=2,
+    )
+    with patch("models.comment.db.session.get") as get_mock:
+        assert comment_without_resolver.resolved_by_account is None
+        get_mock.assert_not_called()
+
+
+def test_workflow_comment_counts_and_participants() -> None:
+    reply_1 = WorkflowCommentReply(comment_id="comment-1", content="reply-1", created_by="user-2")
+    reply_2 = WorkflowCommentReply(comment_id="comment-1", content="reply-2", created_by="user-2")
+    mention_1 = WorkflowCommentMention(comment_id="comment-1", mentioned_user_id="user-3")
+    mention_2 = WorkflowCommentMention(comment_id="comment-1", mentioned_user_id="user-4")
+    comment = WorkflowComment(created_by="user-1", resolved_by=None, content="hello", position_x=1, position_y=2)
+    comment.replies = [reply_1, reply_2]
+    comment.mentions = [mention_1, mention_2]
+
+    account_1 = Mock(id="user-1")
+    account_2 = Mock(id="user-2")
+    account_3 = Mock(id="user-3")
+    account_map = {
+        "user-1": account_1,
+        "user-2": account_2,
+        "user-3": account_3,
+        "user-4": None,
+    }
+
+    with patch("models.comment.db.session.get", side_effect=lambda _model, user_id: account_map[user_id]) as get_mock:
+        participants = comment.participants
+
+    assert comment.reply_count == 2
+    assert comment.mention_count == 2
+    assert set(participants) == {account_1, account_2, account_3}
+    assert get_mock.call_count == 4
+
+
+def test_workflow_comment_participants_use_cached_accounts() -> None:
+    reply = WorkflowCommentReply(comment_id="comment-1", content="reply-1", created_by="user-2")
+    mention = WorkflowCommentMention(comment_id="comment-1", mentioned_user_id="user-3")
+    comment = WorkflowComment(created_by="user-1", resolved_by=None, content="hello", position_x=1, position_y=2)
+    comment.replies = [reply]
+    comment.mentions = [mention]
+
+    account_1 = Mock(id="user-1")
+    account_2 = Mock(id="user-2")
+    account_3 = Mock(id="user-3")
+    comment.cache_created_by_account(account_1)
+    reply.cache_created_by_account(account_2)
+    mention.cache_mentioned_user_account(account_3)
+
+    with patch("models.comment.db.session.get") as get_mock:
+        participants = comment.participants
+
+    assert set(participants) == {account_1, account_2, account_3}
+    get_mock.assert_not_called()
+
+
+def test_reply_and_mention_account_properties_and_cache() -> None:
+    reply = WorkflowCommentReply(comment_id="comment-1", content="reply", created_by="user-1")
+    mention = WorkflowCommentMention(comment_id="comment-1", mentioned_user_id="user-2")
+    reply_account = Mock(id="user-1")
+    mention_account = Mock(id="user-2")
+
+    with patch("models.comment.db.session.get", side_effect=[reply_account, mention_account]) as get_mock:
+        assert reply.created_by_account is reply_account
+        assert mention.mentioned_user_account is mention_account
+        assert get_mock.call_count == 2
+
+    reply.cache_created_by_account(reply_account)
+    mention.cache_mentioned_user_account(mention_account)
+    with patch("models.comment.db.session.get") as get_mock:
+        assert reply.created_by_account is reply_account
+        assert mention.mentioned_user_account is mention_account
+        get_mock.assert_not_called()

api/tests/unit_tests/repositories/test_sqlalchemy_api_workflow_run_repository.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+from graphon.nodes.human_input.entities import FormDefinition, FormInput, UserAction
+from graphon.nodes.human_input.enums import FormInputType
+from models.human_input import RecipientType
+from repositories.sqlalchemy_api_workflow_run_repository import _build_human_input_required_reason
+
+
+def _build_form_model() -> SimpleNamespace:
+    expiration_time = datetime(2024, 1, 1, tzinfo=UTC)
+    definition = FormDefinition(
+        form_content="content",
+        inputs=[FormInput(type=FormInputType.TEXT_INPUT, output_variable_name="name")],
+        user_actions=[UserAction(id="approve", title="Approve")],
+        rendered_content="rendered",
+        expiration_time=expiration_time,
+        default_values={"name": "Alice"},
+        node_title="Ask Name",
+        display_in_ui=True,
+    )
+    return SimpleNamespace(
+        id="form-1",
+        node_id="node-1",
+        form_definition=definition.model_dump_json(),
+        expiration_time=expiration_time,
+    )
+
+
+def _build_reason_model() -> SimpleNamespace:
+    return SimpleNamespace(form_id="form-1", node_id="node-1")
+
+
+def test_build_human_input_required_reason_prefers_standalone_web_app_token() -> None:
+    reason = _build_human_input_required_reason(
+        _build_reason_model(),
+        _build_form_model(),
+        [
+            SimpleNamespace(recipient_type=RecipientType.BACKSTAGE, access_token="btok"),
+            SimpleNamespace(recipient_type=RecipientType.CONSOLE, access_token="ctok"),
+            SimpleNamespace(recipient_type=RecipientType.STANDALONE_WEB_APP, access_token="wtok"),
+        ],
+    )
+
+    assert reason.node_title == "Ask Name"
+    assert reason.resolved_default_values == {"name": "Alice"}
+
+
+def test_build_human_input_required_reason_falls_back_to_console_token() -> None:
+    reason = _build_human_input_required_reason(
+        _build_reason_model(),
+        _build_form_model(),
+        [
+            SimpleNamespace(recipient_type=RecipientType.BACKSTAGE, access_token="btok"),
+            SimpleNamespace(recipient_type=RecipientType.CONSOLE, access_token="ctok"),
+        ],
+    )
+
+    assert reason.node_id == "node-1"
+    assert reason.actions[0].id == "approve"

api/tests/unit_tests/repositories/test_workflow_collaboration_repository.py

@@ -0,0 +1,121 @@
+import json
+from unittest.mock import Mock
+
+import pytest
+
+from repositories import workflow_collaboration_repository as repo_module
+from repositories.workflow_collaboration_repository import WorkflowCollaborationRepository
+
+
+class TestWorkflowCollaborationRepository:
+    @pytest.fixture
+    def mock_redis(self, monkeypatch: pytest.MonkeyPatch) -> Mock:
+        mock_redis = Mock()
+        monkeypatch.setattr(repo_module, "redis_client", mock_redis)
+        return mock_redis
+
+    def test_get_sid_mapping_returns_mapping(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.get.return_value = b'{"workflow_id":"wf-1","user_id":"u-1"}'
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        result = repository.get_sid_mapping("sid-1")
+
+        # Assert
+        assert result == {"workflow_id": "wf-1", "user_id": "u-1"}
+
+    def test_list_sessions_filters_invalid_entries(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.hgetall.return_value = {
+            b"sid-1": b'{"user_id":"u-1","username":"Jane","sid":"sid-1","connected_at":2}',
+            b"sid-2": b'{"username":"Missing","sid":"sid-2"}',
+            b"sid-3": b"not-json",
+        }
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        result = repository.list_sessions("wf-1")
+
+        # Assert
+        assert result == [
+            {
+                "user_id": "u-1",
+                "username": "Jane",
+                "avatar": None,
+                "sid": "sid-1",
+                "connected_at": 2,
+            }
+        ]
+
+    def test_set_session_info_persists_payload(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.exists.return_value = True
+        repository = WorkflowCollaborationRepository()
+        payload = {
+            "user_id": "u-1",
+            "username": "Jane",
+            "avatar": None,
+            "sid": "sid-1",
+            "connected_at": 1,
+        }
+
+        # Act
+        repository.set_session_info("wf-1", payload)
+
+        # Assert
+        assert mock_redis.hset.called
+        workflow_key, sid, session_json = mock_redis.hset.call_args.args
+        assert workflow_key == "workflow_online_users:wf-1"
+        assert sid == "sid-1"
+        assert json.loads(session_json)["user_id"] == "u-1"
+        assert mock_redis.set.called
+
+    def test_refresh_session_state_expires_keys(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.exists.return_value = True
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        repository.refresh_session_state("wf-1", "sid-1")
+
+        # Assert
+        assert mock_redis.expire.call_count == 2
+
+    def test_get_current_leader_decodes_bytes(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.get.return_value = b"sid-1"
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        result = repository.get_current_leader("wf-1")
+
+        # Assert
+        assert result == "sid-1"
+
+    def test_set_leader_if_absent_uses_nx(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.set.return_value = True
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        result = repository.set_leader_if_absent("wf-1", "sid-1")
+
+        # Assert
+        assert result is True
+        _key, _value = mock_redis.set.call_args.args
+        assert _key == "workflow_leader:wf-1"
+        assert _value == "sid-1"
+        assert mock_redis.set.call_args.kwargs["nx"] is True
+        assert "ex" in mock_redis.set.call_args.kwargs
+
+    def test_get_session_sids_decodes(self, mock_redis: Mock) -> None:
+        # Arrange
+        mock_redis.hkeys.return_value = [b"sid-1", "sid-2"]
+        repository = WorkflowCollaborationRepository()
+
+        # Act
+        result = repository.get_session_sids("wf-1")
+
+        # Assert
+        assert result == ["sid-1", "sid-2"]

api/tests/unit_tests/services/test_app_generate_service.py

@@ -327,7 +327,8 @@ class TestGenerate:
             streaming=False,
         )
         assert result == {"result": "advanced-blocking"}
-        assert gen_spy.call_args.kwargs.get("streaming") is False
+        call_kwargs = gen_spy.call_args.kwargs
+        assert call_kwargs.get("streaming") is False
         retrieve_spy.assert_not_called()
 
     # -- ADVANCED_CHAT streaming --------------------------------------------

api/tests/unit_tests/services/test_workflow_collaboration_service.py

@@ -0,0 +1,608 @@
+from unittest.mock import Mock, patch
+
+import pytest
+
+from repositories.workflow_collaboration_repository import WorkflowCollaborationRepository
+from services.workflow_collaboration_service import WorkflowCollaborationService
+
+
+class TestWorkflowCollaborationService:
+    @pytest.fixture
+    def service(self) -> tuple[WorkflowCollaborationService, Mock, Mock]:
+        repository = Mock(spec=WorkflowCollaborationRepository)
+        socketio = Mock()
+        return WorkflowCollaborationService(repository, socketio), repository, socketio
+
+    def test_authorize_and_join_workflow_room_returns_leader_status(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, socketio = service
+        socketio.get_session.return_value = {
+            "user_id": "u-1",
+            "username": "Jane",
+            "avatar": None,
+            "tenant_id": "t-1",
+        }
+
+        with (
+            patch.object(collaboration_service, "_can_access_workflow", return_value=True),
+            patch.object(collaboration_service, "get_or_set_leader", return_value="sid-1"),
+            patch.object(collaboration_service, "broadcast_online_users"),
+        ):
+            # Act
+            result = collaboration_service.authorize_and_join_workflow_room("wf-1", "sid-1")
+
+        # Assert
+        assert result == ("u-1", True)
+        repository.set_session_info.assert_called_once()
+        socketio.enter_room.assert_called_once_with("sid-1", "wf-1")
+        socketio.emit.assert_called_once_with("status", {"isLeader": True}, room="sid-1")
+
+    def test_authorize_and_join_workflow_room_returns_none_when_missing_user(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, _repository, socketio = service
+        socketio.get_session.return_value = {}
+
+        # Act
+        result = collaboration_service.authorize_and_join_workflow_room("wf-1", "sid-1")
+
+        # Assert
+        assert result is None
+
+    def test_authorize_and_join_workflow_room_returns_none_when_missing_tenant(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        socketio.get_session.return_value = {"user_id": "u-1", "username": "Jane", "avatar": None}
+
+        result = collaboration_service.authorize_and_join_workflow_room("wf-1", "sid-1")
+
+        assert result is None
+        repository.set_session_info.assert_not_called()
+        socketio.enter_room.assert_not_called()
+        socketio.emit.assert_not_called()
+
+    def test_authorize_and_join_workflow_room_returns_none_when_workflow_is_not_accessible(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        socketio.get_session.return_value = {
+            "user_id": "u-1",
+            "username": "Jane",
+            "avatar": None,
+            "tenant_id": "t-1",
+        }
+
+        with patch.object(collaboration_service, "_can_access_workflow", return_value=False):
+            result = collaboration_service.authorize_and_join_workflow_room("wf-1", "sid-1")
+
+        assert result is None
+        repository.set_session_info.assert_not_called()
+        socketio.enter_room.assert_not_called()
+        socketio.emit.assert_not_called()
+
+    def test_repr_and_save_socket_identity(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        collaboration_service, _repository, socketio = service
+        user = Mock()
+        user.id = "u-1"
+        user.name = "Jane"
+        user.avatar = "avatar.png"
+        user.current_tenant_id = "t-1"
+
+        assert "WorkflowCollaborationService" in repr(collaboration_service)
+
+        collaboration_service.save_socket_identity("sid-1", user)
+
+        socketio.save_session.assert_called_once_with(
+            "sid-1",
+            {"user_id": "u-1", "username": "Jane", "avatar": "avatar.png", "tenant_id": "t-1"},
+        )
+
+    def test_can_access_workflow_uses_session_factory(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, _repository, _socketio = service
+        session = Mock()
+        session.scalar.return_value = "wf-1"
+        session_context = Mock()
+        session_context.__enter__ = Mock(return_value=session)
+        session_context.__exit__ = Mock(return_value=False)
+
+        with patch(
+            "services.workflow_collaboration_service.session_factory.create_session",
+            return_value=session_context,
+        ):
+            result = collaboration_service._can_access_workflow("wf-1", "tenant-1")
+
+        assert result is True
+        session.scalar.assert_called_once()
+
+    def test_relay_collaboration_event_unauthorized(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_sid_mapping.return_value = None
+
+        # Act
+        result = collaboration_service.relay_collaboration_event("sid-1", {})
+
+        # Assert
+        assert result == ({"msg": "unauthorized"}, 401)
+
+    def test_relay_collaboration_event_emits_update(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+        payload = {"type": "mouse_move", "data": {"x": 1}, "timestamp": 123}
+
+        # Act
+        result = collaboration_service.relay_collaboration_event("sid-1", payload)
+
+        # Assert
+        assert result == ({"msg": "event_broadcasted"}, 200)
+        socketio.emit.assert_called_once_with(
+            "collaboration_update",
+            {"type": "mouse_move", "userId": "u-1", "data": {"x": 1}, "timestamp": 123},
+            room="wf-1",
+            skip_sid="sid-1",
+        )
+
+    def test_relay_collaboration_event_requires_event_type(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, _socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+
+        result = collaboration_service.relay_collaboration_event("sid-1", {"data": {"x": 1}})
+
+        assert result == ({"msg": "invalid event type"}, 400)
+
+    def test_relay_collaboration_event_sync_request_forwards_to_active_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+        repository.get_current_leader.return_value = "sid-leader"
+        payload = {"type": "sync_request", "data": {"reason": "join"}, "timestamp": 123}
+
+        with (
+            patch.object(collaboration_service, "refresh_session_state"),
+            patch.object(collaboration_service, "is_session_active", return_value=True),
+        ):
+            result = collaboration_service.relay_collaboration_event("sid-1", payload)
+
+        assert result == ({"msg": "sync_request_forwarded"}, 200)
+        socketio.emit.assert_called_once_with(
+            "collaboration_update",
+            {"type": "sync_request", "userId": "u-1", "data": {"reason": "join"}, "timestamp": 123},
+            room="sid-leader",
+        )
+        repository.set_leader.assert_not_called()
+
+    def test_relay_collaboration_event_sync_request_reelects_active_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+        repository.get_current_leader.return_value = "sid-old"
+        repository.list_sessions.return_value = [
+            {
+                "user_id": "u-2",
+                "username": "B",
+                "avatar": None,
+                "sid": "sid-2",
+                "connected_at": 1,
+                "graph_active": True,
+            },
+            {
+                "user_id": "u-3",
+                "username": "C",
+                "avatar": None,
+                "sid": "sid-3",
+                "connected_at": 2,
+                "graph_active": True,
+            },
+        ]
+        payload = {"type": "sync_request", "data": {"reason": "join"}, "timestamp": 123}
+
+        def _is_session_active(_workflow_id: str, session_sid: str) -> bool:
+            return session_sid != "sid-old"
+
+        with (
+            patch.object(collaboration_service, "refresh_session_state"),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+            patch.object(collaboration_service, "is_session_active", side_effect=_is_session_active),
+        ):
+            result = collaboration_service.relay_collaboration_event("sid-2", payload)
+
+        assert result == ({"msg": "sync_request_forwarded"}, 200)
+        repository.delete_leader.assert_called_once_with("wf-1")
+        repository.set_leader.assert_called_once_with("wf-1", "sid-2")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-2")
+        socketio.emit.assert_called_once_with(
+            "collaboration_update",
+            {"type": "sync_request", "userId": "u-1", "data": {"reason": "join"}, "timestamp": 123},
+            room="sid-2",
+        )
+
+    def test_relay_collaboration_event_sync_request_returns_when_no_active_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+        repository.get_current_leader.return_value = "sid-old"
+        repository.list_sessions.return_value = []
+        payload = {"type": "sync_request", "data": {"reason": "join"}, "timestamp": 123}
+
+        with (
+            patch.object(collaboration_service, "refresh_session_state"),
+            patch.object(collaboration_service, "is_session_active", return_value=False),
+        ):
+            result = collaboration_service.relay_collaboration_event("sid-2", payload)
+
+        assert result == ({"msg": "no_active_leader"}, 200)
+        repository.delete_leader.assert_called_once_with("wf-1")
+        socketio.emit.assert_not_called()
+
+    def test_relay_graph_event_unauthorized(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_sid_mapping.return_value = None
+
+        # Act
+        result = collaboration_service.relay_graph_event("sid-1", {"nodes": []})
+
+        # Assert
+        assert result == ({"msg": "unauthorized"}, 401)
+
+    def test_disconnect_session_no_mapping(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_sid_mapping.return_value = None
+
+        # Act
+        collaboration_service.disconnect_session("sid-1")
+
+        # Assert
+        repository.delete_session.assert_not_called()
+
+    def test_disconnect_session_cleans_up(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+
+        with (
+            patch.object(collaboration_service, "handle_leader_disconnect") as handle_leader_disconnect,
+            patch.object(collaboration_service, "broadcast_online_users") as broadcast_online_users,
+        ):
+            # Act
+            collaboration_service.disconnect_session("sid-1")
+
+        # Assert
+        repository.delete_session.assert_called_once_with("wf-1", "sid-1")
+        handle_leader_disconnect.assert_called_once_with("wf-1", "sid-1")
+        broadcast_online_users.assert_called_once_with("wf-1")
+
+    def test_get_or_set_leader_returns_active_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-1"
+
+        with patch.object(collaboration_service, "is_session_active", return_value=True):
+            # Act
+            result = collaboration_service.get_or_set_leader("wf-1", "sid-2")
+
+        # Assert
+        assert result == "sid-1"
+        repository.set_leader_if_absent.assert_not_called()
+
+    def test_get_or_set_leader_replaces_dead_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-1"
+        repository.set_leader_if_absent.return_value = True
+        repository.list_sessions.return_value = [
+            {
+                "user_id": "u-2",
+                "username": "B",
+                "avatar": None,
+                "sid": "sid-2",
+                "connected_at": 1,
+                "graph_active": True,
+            }
+        ]
+
+        with (
+            patch.object(collaboration_service, "is_session_active", side_effect=lambda _wf, sid: sid != "sid-1"),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+        ):
+            # Act
+            result = collaboration_service.get_or_set_leader("wf-1", "sid-2")
+
+        # Assert
+        assert result == "sid-2"
+        repository.delete_session.assert_called_once_with("wf-1", "sid-1")
+        repository.delete_leader.assert_called_once_with("wf-1")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-2")
+
+    def test_get_or_set_leader_falls_back_to_existing(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.side_effect = [None, "sid-3"]
+        repository.set_leader_if_absent.return_value = False
+        repository.list_sessions.return_value = [
+            {
+                "user_id": "u-2",
+                "username": "B",
+                "avatar": None,
+                "sid": "sid-2",
+                "connected_at": 1,
+                "graph_active": True,
+            }
+        ]
+
+        # Act
+        result = collaboration_service.get_or_set_leader("wf-1", "sid-2")
+
+        # Assert
+        assert result == "sid-3"
+
+    def test_get_or_set_leader_returns_sid_when_leader_still_missing(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.side_effect = [None, None]
+        repository.set_leader_if_absent.return_value = False
+
+        result = collaboration_service.get_or_set_leader("wf-1", "sid-2")
+
+        assert result == "sid-2"
+
+    def test_handle_leader_disconnect_elects_new(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-1"
+        repository.list_sessions.return_value = [
+            {
+                "user_id": "u-2",
+                "username": "B",
+                "avatar": None,
+                "sid": "sid-2",
+                "connected_at": 1,
+                "graph_active": True,
+            }
+        ]
+
+        with (
+            patch.object(collaboration_service, "is_session_active", return_value=True),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+        ):
+            # Act
+            collaboration_service.handle_leader_disconnect("wf-1", "sid-1")
+
+        # Assert
+        repository.set_leader.assert_called_once_with("wf-1", "sid-2")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-2")
+
+    def test_handle_leader_disconnect_clears_when_empty(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-1"
+        repository.list_sessions.return_value = []
+
+        # Act
+        collaboration_service.handle_leader_disconnect("wf-1", "sid-1")
+
+        # Assert
+        repository.delete_leader.assert_called_once_with("wf-1")
+
+    def test_handle_leader_disconnect_ignores_non_leader_or_missing_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, _socketio = service
+
+        repository.get_current_leader.return_value = None
+        collaboration_service.handle_leader_disconnect("wf-1", "sid-1")
+
+        repository.get_current_leader.return_value = "sid-leader"
+        collaboration_service.handle_leader_disconnect("wf-1", "sid-other")
+
+        repository.set_leader.assert_not_called()
+        repository.delete_leader.assert_not_called()
+
+    def test_broadcast_leader_change_logs_emit_errors(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        repository.get_session_sids.return_value = ["sid-1", "sid-2"]
+        socketio.emit.side_effect = [RuntimeError("boom"), None]
+
+        with patch("services.workflow_collaboration_service.logging.exception") as exception_mock:
+            collaboration_service.broadcast_leader_change("wf-1", "sid-2")
+
+        assert exception_mock.call_count == 1
+
+    def test_broadcast_online_users_sorts_and_emits(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, socketio = service
+        repository.list_sessions.return_value = [
+            {"user_id": "u-1", "username": "A", "avatar": None, "sid": "sid-1", "connected_at": 3},
+            {"user_id": "u-2", "username": "B", "avatar": None, "sid": "sid-2", "connected_at": 1},
+        ]
+        repository.get_current_leader.return_value = "sid-1"
+
+        with patch.object(collaboration_service, "is_session_active", return_value=True):
+            # Act
+            collaboration_service.broadcast_online_users("wf-1")
+
+        # Assert
+        socketio.emit.assert_called_once_with(
+            "online_users",
+            {
+                "workflow_id": "wf-1",
+                "users": [
+                    {"user_id": "u-2", "username": "B", "avatar": None, "sid": "sid-2", "connected_at": 1},
+                    {"user_id": "u-1", "username": "A", "avatar": None, "sid": "sid-1", "connected_at": 3},
+                ],
+                "leader": "sid-1",
+            },
+            room="wf-1",
+        )
+
+    def test_broadcast_online_users_reassigns_missing_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, socketio = service
+        users = [{"user_id": "u-2", "username": "B", "avatar": None, "sid": "sid-2", "connected_at": 1}]
+        repository.get_current_leader.return_value = "sid-old"
+
+        with (
+            patch.object(collaboration_service, "_prune_inactive_sessions", return_value=users),
+            patch.object(collaboration_service, "_select_graph_leader", return_value="sid-2"),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+        ):
+            collaboration_service.broadcast_online_users("wf-1")
+
+        repository.delete_leader.assert_called_once_with("wf-1")
+        repository.set_leader.assert_called_once_with("wf-1", "sid-2")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-2")
+        socketio.emit.assert_called_once_with(
+            "online_users",
+            {"workflow_id": "wf-1", "users": users, "leader": "sid-2"},
+            room="wf-1",
+        )
+
+    def test_refresh_session_state_expires_active_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-1"
+
+        with patch.object(collaboration_service, "is_session_active", return_value=True):
+            # Act
+            collaboration_service.refresh_session_state("wf-1", "sid-1")
+
+        # Assert
+        repository.refresh_session_state.assert_called_once_with("wf-1", "sid-1")
+        repository.expire_leader.assert_called_once_with("wf-1")
+        repository.set_leader.assert_not_called()
+
+    def test_refresh_session_state_sets_leader_when_missing(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        # Arrange
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = None
+        repository.list_sessions.return_value = [
+            {
+                "user_id": "u-2",
+                "username": "B",
+                "avatar": None,
+                "sid": "sid-2",
+                "connected_at": 1,
+                "graph_active": True,
+            }
+        ]
+
+        with (
+            patch.object(collaboration_service, "is_session_active", return_value=True),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+        ):
+            # Act
+            collaboration_service.refresh_session_state("wf-1", "sid-2")
+
+        # Assert
+        repository.set_leader.assert_called_once_with("wf-1", "sid-2")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-2")
+
+    def test_refresh_session_state_replaces_inactive_existing_leader(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, _socketio = service
+        repository.get_current_leader.return_value = "sid-old"
+
+        with (
+            patch.object(collaboration_service, "is_session_active", return_value=False),
+            patch.object(collaboration_service, "broadcast_leader_change") as broadcast_leader_change,
+        ):
+            collaboration_service.refresh_session_state("wf-1", "sid-new")
+
+        repository.delete_leader.assert_called_once_with("wf-1")
+        repository.set_leader.assert_called_once_with("wf-1", "sid-new")
+        broadcast_leader_change.assert_called_once_with("wf-1", "sid-new")
+
+    def test_relay_graph_event_emits_update(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        # Arrange
+        collaboration_service, repository, socketio = service
+        repository.get_sid_mapping.return_value = {"workflow_id": "wf-1", "user_id": "u-1"}
+
+        # Act
+        result = collaboration_service.relay_graph_event("sid-1", {"nodes": []})
+
+        # Assert
+        assert result == ({"msg": "graph_update_broadcasted"}, 200)
+        repository.refresh_session_state.assert_called_once_with("wf-1", "sid-1")
+        socketio.emit.assert_called_once_with("graph_update", {"nodes": []}, room="wf-1", skip_sid="sid-1")
+
+    def test_prune_inactive_sessions_handles_empty_and_removes_stale(
+        self, service: tuple[WorkflowCollaborationService, Mock, Mock]
+    ) -> None:
+        collaboration_service, repository, _socketio = service
+        repository.list_sessions.return_value = []
+        assert collaboration_service._prune_inactive_sessions("wf-1") == []
+
+        active = {"sid": "sid-1", "user_id": "u-1", "connected_at": 1}
+        stale = {"sid": "sid-2", "user_id": "u-2", "connected_at": 2}
+        repository.list_sessions.return_value = [active, stale]
+
+        with patch.object(
+            collaboration_service,
+            "is_session_active",
+            side_effect=lambda _workflow_id, sid: sid == "sid-1",
+        ):
+            users = collaboration_service._prune_inactive_sessions("wf-1")
+
+        assert users == [active]
+        repository.delete_session.assert_called_with("wf-1", "sid-2")
+
+    def test_is_session_active_guard_branches(self, service: tuple[WorkflowCollaborationService, Mock, Mock]) -> None:
+        collaboration_service, repository, socketio = service
+        socketio.manager.is_connected.return_value = True
+        repository.session_exists.return_value = True
+        repository.sid_mapping_exists.return_value = True
+
+        assert collaboration_service.is_session_active("wf-1", "") is False
+
+        socketio.manager.is_connected.return_value = False
+        assert collaboration_service.is_session_active("wf-1", "sid-1") is False
+
+        socketio.manager.is_connected.side_effect = AttributeError("missing manager")
+        assert collaboration_service.is_session_active("wf-1", "sid-1") is False
+        socketio.manager.is_connected.side_effect = None
+
+        socketio.manager.is_connected.return_value = True
+        repository.session_exists.return_value = False
+        assert collaboration_service.is_session_active("wf-1", "sid-1") is False
+
+        repository.session_exists.return_value = True
+        repository.sid_mapping_exists.return_value = False
+        assert collaboration_service.is_session_active("wf-1", "sid-1") is False

api/tests/unit_tests/services/test_workflow_comment_service.py

@@ -0,0 +1,578 @@
+from unittest.mock import MagicMock, Mock, patch
+
+import pytest
+from werkzeug.exceptions import Forbidden, NotFound
+
+from services import workflow_comment_service as service_module
+from services.workflow_comment_service import WorkflowCommentService
+
+
+@pytest.fixture
+def mock_session(monkeypatch: pytest.MonkeyPatch) -> Mock:
+    session = Mock()
+    context_manager = MagicMock()
+    context_manager.__enter__.return_value = session
+    context_manager.__exit__.return_value = False
+    mock_db = MagicMock()
+    mock_db.engine = Mock()
+    empty_scalars = Mock()
+    empty_scalars.all.return_value = []
+    session.scalars.return_value = empty_scalars
+    monkeypatch.setattr(service_module, "Session", Mock(return_value=context_manager))
+    monkeypatch.setattr(service_module, "db", mock_db)
+    monkeypatch.setattr(service_module.send_workflow_comment_mention_email_task, "delay", Mock())
+    return session
+
+
+def _mock_scalars(result_list: list[object]) -> Mock:
+    scalars = Mock()
+    scalars.all.return_value = result_list
+    return scalars
+
+
+class TestWorkflowCommentService:
+    def test_validate_content_rejects_empty(self) -> None:
+        with pytest.raises(ValueError):
+            WorkflowCommentService._validate_content("   ")
+
+    def test_validate_content_rejects_too_long(self) -> None:
+        with pytest.raises(ValueError):
+            WorkflowCommentService._validate_content("a" * 1001)
+
+    def test_filter_valid_mentioned_user_ids_filters_by_tenant_and_preserves_order(self, mock_session: Mock) -> None:
+        tenant_member_1 = "123e4567-e89b-12d3-a456-426614174000"
+        tenant_member_2 = "123e4567-e89b-12d3-a456-426614174002"
+        non_tenant_member = "123e4567-e89b-12d3-a456-426614174001"
+        mock_session.scalars.return_value = _mock_scalars([tenant_member_1, tenant_member_2])
+
+        result = WorkflowCommentService._filter_valid_mentioned_user_ids(
+            [
+                tenant_member_1,
+                "",
+                123,  # type: ignore[list-item]
+                tenant_member_1,
+                non_tenant_member,
+                tenant_member_2,
+            ],
+            session=mock_session,
+            tenant_id="tenant-1",
+        )
+
+        assert result == [
+            tenant_member_1,
+            tenant_member_2,
+        ]
+
+    def test_format_comment_excerpt_handles_short_and_long_limits(self) -> None:
+        assert WorkflowCommentService._format_comment_excerpt("  hello  ", max_length=10) == "hello"
+        assert WorkflowCommentService._format_comment_excerpt("abcdefghijk", max_length=3) == "abc"
+        assert WorkflowCommentService._format_comment_excerpt("  abcdefghijk  ", max_length=8) == "abcde..."
+
+    def test_build_mention_email_payloads_returns_empty_for_no_candidates(self, mock_session: Mock) -> None:
+        assert (
+            WorkflowCommentService._build_mention_email_payloads(
+                session=mock_session,
+                tenant_id="tenant-1",
+                app_id="app-1",
+                mentioner_id="user-1",
+                mentioned_user_ids=[],
+                content="hello",
+            )
+            == []
+        )
+        assert (
+            WorkflowCommentService._build_mention_email_payloads(
+                session=mock_session,
+                tenant_id="tenant-1",
+                app_id="app-1",
+                mentioner_id="user-1",
+                mentioned_user_ids=["user-1"],
+                content="hello",
+            )
+            == []
+        )
+
+    def test_dispatch_mention_emails_enqueues_each_payload(self) -> None:
+        delay_mock = Mock()
+        with patch.object(service_module.send_workflow_comment_mention_email_task, "delay", delay_mock):
+            WorkflowCommentService._dispatch_mention_emails(
+                [
+                    {"to": "a@example.com"},
+                    {"to": "b@example.com"},
+                ]
+            )
+
+        assert delay_mock.call_count == 2
+
+    def test_build_mention_email_payloads_skips_accounts_without_email(self, mock_session: Mock) -> None:
+        account_without_email = Mock()
+        account_without_email.email = None
+        account_without_email.name = "No Email"
+        account_without_email.interface_language = "en-US"
+
+        account_with_email = Mock()
+        account_with_email.email = "user@example.com"
+        account_with_email.name = ""
+        account_with_email.interface_language = None
+
+        mock_session.scalar.side_effect = ["My App", "Commenter"]
+        mock_session.scalars.return_value = _mock_scalars([account_without_email, account_with_email])
+
+        payloads = WorkflowCommentService._build_mention_email_payloads(
+            session=mock_session,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            mentioner_id="user-1",
+            mentioned_user_ids=["user-2"],
+            content="hello",
+        )
+        expected_app_url = f"{service_module.dify_config.CONSOLE_WEB_URL.rstrip('/')}/app/app-1/workflow"
+
+        assert payloads == [
+            {
+                "language": "en-US",
+                "to": "user@example.com",
+                "mentioned_name": "user@example.com",
+                "commenter_name": "Commenter",
+                "app_name": "My App",
+                "comment_content": "hello",
+                "app_url": expected_app_url,
+            }
+        ]
+
+    def test_create_comment_creates_mentions(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_at = "ts"
+
+        with (
+            patch.object(service_module, "WorkflowComment", return_value=comment),
+            patch.object(service_module, "WorkflowCommentMention", return_value=Mock()),
+            patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids", return_value=["user-2"]),
+        ):
+            result = WorkflowCommentService.create_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                created_by="user-1",
+                content="hello",
+                position_x=1.0,
+                position_y=2.0,
+                mentioned_user_ids=["user-2", "bad-id"],
+            )
+
+        assert result == {"id": "comment-1", "created_at": "ts"}
+        assert mock_session.add.call_args_list[0].args[0] is comment
+        assert mock_session.add.call_count == 2
+        mock_session.commit.assert_called_once()
+
+    def test_update_comment_raises_not_found(self, mock_session: Mock) -> None:
+        mock_session.scalar.return_value = None
+
+        with pytest.raises(NotFound):
+            WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="user-1",
+                content="hello",
+            )
+
+    def test_update_comment_raises_forbidden(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.created_by = "owner"
+        mock_session.scalar.return_value = comment
+
+        with pytest.raises(Forbidden):
+            WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="intruder",
+                content="hello",
+            )
+
+    def test_update_comment_replaces_mentions(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_by = "owner"
+        mock_session.scalar.return_value = comment
+
+        existing_mentions = [Mock(), Mock()]
+        mock_session.scalars.return_value = _mock_scalars(existing_mentions)
+
+        with patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids", return_value=["user-2"]):
+            result = WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="owner",
+                content="updated",
+                mentioned_user_ids=["user-2", "bad-id"],
+            )
+
+        assert result == {"id": "comment-1", "updated_at": comment.updated_at}
+        assert mock_session.delete.call_count == 2
+        assert mock_session.add.call_count == 1
+        mock_session.commit.assert_called_once()
+
+    def test_update_comment_preserves_mentions_when_mentioned_user_ids_omitted(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_by = "owner"
+        mock_session.scalar.return_value = comment
+
+        with (
+            patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids") as filter_mentions_mock,
+            patch.object(WorkflowCommentService, "_build_mention_email_payloads") as build_payloads_mock,
+            patch.object(WorkflowCommentService, "_dispatch_mention_emails") as dispatch_mock,
+        ):
+            result = WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="owner",
+                content="updated",
+            )
+
+        assert result == {"id": "comment-1", "updated_at": comment.updated_at}
+        mock_session.delete.assert_not_called()
+        mock_session.add.assert_not_called()
+        filter_mentions_mock.assert_not_called()
+        build_payloads_mock.assert_not_called()
+        dispatch_mock.assert_called_once_with([])
+        mock_session.commit.assert_called_once()
+
+    def test_update_comment_clears_mentions_when_empty_list_provided(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_by = "owner"
+        mock_session.scalar.return_value = comment
+
+        existing_mentions = [Mock(), Mock()]
+        mock_session.scalars.return_value = _mock_scalars(existing_mentions)
+
+        with patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids", return_value=[]):
+            result = WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="owner",
+                content="updated",
+                mentioned_user_ids=[],
+            )
+
+        assert result == {"id": "comment-1", "updated_at": comment.updated_at}
+        assert mock_session.delete.call_count == 2
+        mock_session.add.assert_not_called()
+        mock_session.commit.assert_called_once()
+
+    def test_update_comment_notifies_only_new_mentions(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_by = "owner"
+        mock_session.scalar.return_value = comment
+
+        existing_mention = Mock()
+        existing_mention.mentioned_user_id = "user-2"
+        mock_session.scalars.return_value = _mock_scalars([existing_mention])
+
+        with (
+            patch.object(
+                WorkflowCommentService,
+                "_filter_valid_mentioned_user_ids",
+                return_value=["user-2", "user-3"],
+            ),
+            patch.object(
+                WorkflowCommentService,
+                "_build_mention_email_payloads",
+                return_value=[],
+            ) as build_payloads_mock,
+            patch.object(WorkflowCommentService, "_dispatch_mention_emails") as dispatch_mock,
+        ):
+            WorkflowCommentService.update_comment(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                user_id="owner",
+                content="updated",
+                mentioned_user_ids=["user-2", "user-3"],
+            )
+
+        assert build_payloads_mock.call_args.kwargs["mentioned_user_ids"] == ["user-3"]
+        dispatch_mock.assert_called_once_with([])
+
+    def test_get_comments_preloads_related_accounts(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.created_by = "user-1"
+        comment.resolved_by = "user-2"
+        reply = Mock()
+        reply.created_by = "user-3"
+        mention = Mock()
+        mention.mentioned_user_id = "user-4"
+        comment.replies = [reply]
+        comment.mentions = [mention]
+        comment.cache_created_by_account = Mock()
+        comment.cache_resolved_by_account = Mock()
+        reply.cache_created_by_account = Mock()
+        mention.cache_mentioned_user_account = Mock()
+
+        account_1 = Mock()
+        account_1.id = "user-1"
+        account_2 = Mock()
+        account_2.id = "user-2"
+        account_3 = Mock()
+        account_3.id = "user-3"
+        account_4 = Mock()
+        account_4.id = "user-4"
+
+        mock_session.scalars.side_effect = [
+            _mock_scalars([comment]),
+            _mock_scalars([account_1, account_2, account_3, account_4]),
+        ]
+
+        result = WorkflowCommentService.get_comments("tenant-1", "app-1")
+
+        assert result == [comment]
+        comment.cache_created_by_account.assert_called_once_with(account_1)
+        comment.cache_resolved_by_account.assert_called_once_with(account_2)
+        reply.cache_created_by_account.assert_called_once_with(account_3)
+        mention.cache_mentioned_user_account.assert_called_once_with(account_4)
+
+    def test_preload_accounts_returns_early_for_empty_comments(self, mock_session: Mock) -> None:
+        WorkflowCommentService._preload_accounts(mock_session, [])
+
+        mock_session.scalars.assert_not_called()
+
+    def test_get_comment_raises_not_found_with_provided_session(self) -> None:
+        session = Mock()
+        session.scalar.return_value = None
+
+        with pytest.raises(NotFound):
+            WorkflowCommentService.get_comment("tenant-1", "app-1", "comment-1", session=session)
+
+    def test_get_comment_uses_context_manager_when_session_not_provided(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.created_by = "user-1"
+        comment.resolved_by = None
+        comment.replies = []
+        comment.mentions = []
+        comment.cache_created_by_account = Mock()
+        comment.cache_resolved_by_account = Mock()
+        mock_session.scalar.return_value = comment
+        mock_session.scalars.return_value = _mock_scalars([])
+
+        result = WorkflowCommentService.get_comment("tenant-1", "app-1", "comment-1")
+
+        assert result is comment
+        comment.cache_created_by_account.assert_called_once()
+        comment.cache_resolved_by_account.assert_called_once_with(None)
+
+    def test_delete_comment_raises_forbidden(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.created_by = "owner"
+
+        with patch.object(WorkflowCommentService, "get_comment", return_value=comment):
+            with pytest.raises(Forbidden):
+                WorkflowCommentService.delete_comment("tenant-1", "app-1", "comment-1", "intruder")
+
+    def test_delete_comment_removes_related_entities(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.created_by = "owner"
+
+        mentions = [Mock(), Mock()]
+        replies = [Mock()]
+        mock_session.scalars.side_effect = [_mock_scalars(mentions), _mock_scalars(replies)]
+
+        with patch.object(WorkflowCommentService, "get_comment", return_value=comment):
+            WorkflowCommentService.delete_comment("tenant-1", "app-1", "comment-1", "owner")
+
+        assert mock_session.delete.call_count == 4
+        mock_session.commit.assert_called_once()
+
+    def test_resolve_comment_sets_fields(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.resolved = False
+        comment.resolved_at = None
+        comment.resolved_by = None
+
+        with (
+            patch.object(WorkflowCommentService, "get_comment", return_value=comment),
+            patch.object(service_module, "naive_utc_now", return_value="now"),
+        ):
+            result = WorkflowCommentService.resolve_comment("tenant-1", "app-1", "comment-1", "user-1")
+
+        assert result is comment
+        assert comment.resolved is True
+        assert comment.resolved_at == "now"
+        assert comment.resolved_by == "user-1"
+        mock_session.commit.assert_called_once()
+
+    def test_resolve_comment_noop_when_already_resolved(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.resolved = True
+
+        with patch.object(WorkflowCommentService, "get_comment", return_value=comment):
+            result = WorkflowCommentService.resolve_comment("tenant-1", "app-1", "comment-1", "user-1")
+
+        assert result is comment
+        mock_session.commit.assert_not_called()
+
+    def test_create_reply_requires_comment(self, mock_session: Mock) -> None:
+        mock_session.get.return_value = None
+
+        with pytest.raises(NotFound):
+            WorkflowCommentService.create_reply("comment-1", "hello", "user-1")
+
+    def test_create_reply_creates_mentions(self, mock_session: Mock) -> None:
+        mock_session.get.return_value = Mock()
+        reply = Mock()
+        reply.id = "reply-1"
+        reply.created_at = "ts"
+
+        with (
+            patch.object(service_module, "WorkflowCommentReply", return_value=reply),
+            patch.object(service_module, "WorkflowCommentMention", return_value=Mock()),
+            patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids", return_value=["user-2"]),
+        ):
+            result = WorkflowCommentService.create_reply(
+                comment_id="comment-1",
+                content="hello",
+                created_by="user-1",
+                mentioned_user_ids=["user-2", "bad-id"],
+            )
+
+        assert result == {"id": "reply-1", "created_at": "ts"}
+        assert mock_session.add.call_count == 2
+        mock_session.commit.assert_called_once()
+
+    def test_update_reply_raises_not_found(self, mock_session: Mock) -> None:
+        mock_session.scalar.return_value = None
+
+        with pytest.raises(NotFound):
+            WorkflowCommentService.update_reply(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                reply_id="reply-1",
+                user_id="user-1",
+                content="hello",
+            )
+
+    def test_update_reply_raises_forbidden(self, mock_session: Mock) -> None:
+        reply = Mock()
+        reply.created_by = "owner"
+        mock_session.scalar.return_value = reply
+
+        with pytest.raises(Forbidden):
+            WorkflowCommentService.update_reply(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                reply_id="reply-1",
+                user_id="intruder",
+                content="hello",
+            )
+
+    def test_update_reply_replaces_mentions(self, mock_session: Mock) -> None:
+        reply = Mock()
+        reply.id = "reply-1"
+        reply.comment_id = "comment-1"
+        reply.created_by = "owner"
+        reply.updated_at = "updated"
+        mock_session.scalar.return_value = reply
+        mock_session.scalars.return_value = _mock_scalars([Mock()])
+        comment = Mock()
+        comment.tenant_id = "tenant-1"
+        comment.app_id = "app-1"
+        mock_session.get.return_value = comment
+
+        with patch.object(WorkflowCommentService, "_filter_valid_mentioned_user_ids", return_value=["user-2"]):
+            result = WorkflowCommentService.update_reply(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                reply_id="reply-1",
+                user_id="owner",
+                content="new",
+                mentioned_user_ids=["user-2", "bad-id"],
+            )
+
+        assert result == {"id": "reply-1", "updated_at": "updated"}
+        assert mock_session.delete.call_count == 1
+        assert mock_session.add.call_count == 1
+        mock_session.commit.assert_called_once()
+        mock_session.refresh.assert_called_once_with(reply)
+
+    def test_update_comment_updates_position_coordinates_when_provided(self, mock_session: Mock) -> None:
+        comment = Mock()
+        comment.id = "comment-1"
+        comment.created_by = "owner"
+        comment.position_x = 1.0
+        comment.position_y = 2.0
+        mock_session.scalar.return_value = comment
+        mock_session.scalars.return_value = _mock_scalars([])
+
+        WorkflowCommentService.update_comment(
+            tenant_id="tenant-1",
+            app_id="app-1",
+            comment_id="comment-1",
+            user_id="owner",
+            content="updated",
+            position_x=10.5,
+            position_y=20.5,
+            mentioned_user_ids=[],
+        )
+
+        assert comment.position_x == 10.5
+        assert comment.position_y == 20.5
+
+    def test_delete_reply_raises_forbidden(self, mock_session: Mock) -> None:
+        reply = Mock()
+        reply.created_by = "owner"
+        mock_session.scalar.return_value = reply
+
+        with pytest.raises(Forbidden):
+            WorkflowCommentService.delete_reply(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                reply_id="reply-1",
+                user_id="intruder",
+            )
+
+    def test_delete_reply_raises_not_found(self, mock_session: Mock) -> None:
+        mock_session.scalar.return_value = None
+
+        with pytest.raises(NotFound):
+            WorkflowCommentService.delete_reply(
+                tenant_id="tenant-1",
+                app_id="app-1",
+                comment_id="comment-1",
+                reply_id="reply-1",
+                user_id="owner",
+            )
+
+    def test_delete_reply_removes_mentions(self, mock_session: Mock) -> None:
+        reply = Mock()
+        reply.created_by = "owner"
+        mock_session.scalar.return_value = reply
+        mock_session.scalars.return_value = _mock_scalars([Mock(), Mock()])
+
+        WorkflowCommentService.delete_reply(
+            tenant_id="tenant-1",
+            app_id="app-1",
+            comment_id="comment-1",
+            reply_id="reply-1",
+            user_id="owner",
+        )
+
+        assert mock_session.delete.call_count == 3
+        mock_session.commit.assert_called_once()
+
+    def test_validate_comment_access_delegates_to_get_comment(self) -> None:
+        comment = Mock()
+        with patch.object(WorkflowCommentService, "get_comment", return_value=comment) as get_comment_mock:
+            result = WorkflowCommentService.validate_comment_access("comment-1", "tenant-1", "app-1")
+
+        assert result is comment
+        get_comment_mock.assert_called_once_with("tenant-1", "app-1", "comment-1")

api/tests/unit_tests/services/test_workflow_service.py

@@ -12,7 +12,7 @@ This test suite covers:
 import json
 import uuid
 from typing import Any, cast
-from unittest.mock import ANY, MagicMock, patch
+from unittest.mock import ANY, MagicMock, Mock, patch
 
 import pytest
 from graphon.entities import WorkflowNodeExecution
@@ -713,6 +713,79 @@ class TestWorkflowService:
         with pytest.raises(ValueError, match="Invalid app mode"):
             workflow_service.validate_features_structure(app, features)
 
+    # ==================== Draft Workflow Variable Update Tests ====================
+    # These tests verify updating draft workflow environment/conversation variables
+
+    def test_update_draft_workflow_environment_variables_updates_workflow(self, workflow_service, mock_db_session):
+        """Test update_draft_workflow_environment_variables updates draft fields."""
+        app = TestWorkflowAssociatedDataFactory.create_app_mock()
+        account = TestWorkflowAssociatedDataFactory.create_account_mock()
+        workflow = TestWorkflowAssociatedDataFactory.create_workflow_mock()
+        variables = [Mock()]
+
+        with (
+            patch.object(workflow_service, "get_draft_workflow", return_value=workflow),
+            patch("services.workflow_service.naive_utc_now", return_value="now"),
+        ):
+            workflow_service.update_draft_workflow_environment_variables(
+                app_model=app,
+                environment_variables=variables,
+                account=account,
+            )
+
+        assert workflow.environment_variables == variables
+        assert workflow.updated_by == account.id
+        assert workflow.updated_at == "now"
+        mock_db_session.session.commit.assert_called_once()
+
+    def test_update_draft_workflow_environment_variables_raises_when_missing(self, workflow_service):
+        """Test update_draft_workflow_environment_variables raises when draft missing."""
+        app = TestWorkflowAssociatedDataFactory.create_app_mock()
+        account = TestWorkflowAssociatedDataFactory.create_account_mock()
+
+        with patch.object(workflow_service, "get_draft_workflow", return_value=None):
+            with pytest.raises(ValueError, match="No draft workflow found."):
+                workflow_service.update_draft_workflow_environment_variables(
+                    app_model=app,
+                    environment_variables=[],
+                    account=account,
+                )
+
+    def test_update_draft_workflow_conversation_variables_updates_workflow(self, workflow_service, mock_db_session):
+        """Test update_draft_workflow_conversation_variables updates draft fields."""
+        app = TestWorkflowAssociatedDataFactory.create_app_mock()
+        account = TestWorkflowAssociatedDataFactory.create_account_mock()
+        workflow = TestWorkflowAssociatedDataFactory.create_workflow_mock()
+        variables = [Mock()]
+
+        with (
+            patch.object(workflow_service, "get_draft_workflow", return_value=workflow),
+            patch("services.workflow_service.naive_utc_now", return_value="now"),
+        ):
+            workflow_service.update_draft_workflow_conversation_variables(
+                app_model=app,
+                conversation_variables=variables,
+                account=account,
+            )
+
+        assert workflow.conversation_variables == variables
+        assert workflow.updated_by == account.id
+        assert workflow.updated_at == "now"
+        mock_db_session.session.commit.assert_called_once()
+
+    def test_update_draft_workflow_conversation_variables_raises_when_missing(self, workflow_service):
+        """Test update_draft_workflow_conversation_variables raises when draft missing."""
+        app = TestWorkflowAssociatedDataFactory.create_app_mock()
+        account = TestWorkflowAssociatedDataFactory.create_account_mock()
+
+        with patch.object(workflow_service, "get_draft_workflow", return_value=None):
+            with pytest.raises(ValueError, match="No draft workflow found."):
+                workflow_service.update_draft_workflow_conversation_variables(
+                    app_model=app,
+                    conversation_variables=[],
+                    account=account,
+                )
+
     # ==================== Publish Workflow Tests ====================
     # These tests verify creating published versions from draft workflows
 

api/tests/unit_tests/services/workflow/test_workflow_event_snapshot_service.py

@@ -1,28 +1,36 @@
 import json
 import queue
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from threading import Event
+from types import SimpleNamespace
+from typing import Any, cast
+from unittest.mock import MagicMock
 
 import pytest
 from graphon.entities.pause_reason import HumanInputRequired
 from graphon.enums import WorkflowExecutionStatus, WorkflowNodeExecutionStatus
 from graphon.runtime import GraphRuntimeState, VariablePool
+from sqlalchemy.orm import Session, sessionmaker
 
 from core.app.app_config.entities import WorkflowUIBasedAppConfig
 from core.app.entities.app_invoke_entities import InvokeFrom, WorkflowAppGenerateEntity
+from core.app.entities.task_entities import StreamEvent
 from core.app.layers.pause_state_persist_layer import WorkflowResumptionContext, _WorkflowGenerateEntityWrapper
 from models.enums import CreatorUserRole
 from models.model import AppMode
 from models.workflow import WorkflowRun
 from repositories.api_workflow_node_execution_repository import WorkflowNodeExecutionSnapshot
 from repositories.entities.workflow_pause import WorkflowPauseEntity
+from services import workflow_event_snapshot_service as service_module
 from services.workflow_event_snapshot_service import (
     BufferState,
     MessageContext,
     _build_snapshot_events,
+    _is_terminal_event,
     _resolve_task_id,
+    build_workflow_event_stream,
 )
 
 
@@ -125,49 +133,6 @@ def _build_resumption_context(task_id: str) -> WorkflowResumptionContext:
     )
 
 
-def test_build_snapshot_events_includes_pause_event() -> None:
-    workflow_run = _build_workflow_run(WorkflowExecutionStatus.PAUSED)
-    snapshot = _build_snapshot(WorkflowNodeExecutionStatus.PAUSED)
-    resumption_context = _build_resumption_context("task-ctx")
-    pause_entity = _FakePauseEntity(
-        pause_id="pause-1",
-        workflow_run_id="run-1",
-        paused_at_value=datetime(2024, 1, 1, tzinfo=UTC),
-        pause_reasons=[
-            HumanInputRequired(
-                form_id="form-1",
-                form_content="content",
-                node_id="node-1",
-                node_title="Human Input",
-            )
-        ],
-    )
-
-    events = _build_snapshot_events(
-        workflow_run=workflow_run,
-        node_snapshots=[snapshot],
-        task_id="task-ctx",
-        message_context=None,
-        pause_entity=pause_entity,
-        resumption_context=resumption_context,
-    )
-
-    assert [event["event"] for event in events] == [
-        "workflow_started",
-        "node_started",
-        "node_finished",
-        "workflow_paused",
-    ]
-    assert events[2]["data"]["status"] == WorkflowNodeExecutionStatus.PAUSED.value
-    pause_data = events[-1]["data"]
-    assert pause_data["paused_nodes"] == ["node-1"]
-    assert pause_data["outputs"] == {"result": "value"}
-    assert pause_data["status"] == WorkflowExecutionStatus.PAUSED.value
-    assert pause_data["created_at"] == int(workflow_run.created_at.timestamp())
-    assert pause_data["elapsed_time"] == workflow_run.elapsed_time
-    assert pause_data["total_tokens"] == workflow_run.total_tokens
-    assert pause_data["total_steps"] == workflow_run.total_steps
-
 
 def test_build_snapshot_events_applies_message_context() -> None:
     workflow_run = _build_workflow_run(WorkflowExecutionStatus.RUNNING)
@@ -222,3 +187,647 @@ def test_resolve_task_id_priority(context_task_id, buffered_task_id, expected) -
         buffer_state.task_id_ready.set()
     task_id = _resolve_task_id(resumption_context, buffer_state, "run-1", wait_timeout=0.0)
     assert task_id == expected
+
+
+def _build_workflow_run_additional(status: WorkflowExecutionStatus = WorkflowExecutionStatus.RUNNING) -> WorkflowRun:
+    return WorkflowRun(
+        id="run-1",
+        tenant_id="tenant-1",
+        app_id="app-1",
+        workflow_id="workflow-1",
+        type="workflow",
+        triggered_from="app-run",
+        version="v1",
+        graph=None,
+        inputs=json.dumps({"query": "hello"}),
+        status=status,
+        outputs=json.dumps({}),
+        error=None,
+        elapsed_time=1.2,
+        total_tokens=5,
+        total_steps=2,
+        created_by_role=CreatorUserRole.END_USER,
+        created_by="user-1",
+        created_at=datetime(2024, 1, 1, tzinfo=UTC),
+    )
+
+
+def _build_resumption_context_additional(task_id: str) -> WorkflowResumptionContext:
+    app_config = WorkflowUIBasedAppConfig(
+        tenant_id="tenant-1",
+        app_id="app-1",
+        app_mode=AppMode.WORKFLOW,
+        workflow_id="workflow-1",
+    )
+    generate_entity = WorkflowAppGenerateEntity(
+        task_id=task_id,
+        app_config=app_config,
+        inputs={},
+        files=[],
+        user_id="user-1",
+        stream=True,
+        invoke_from=InvokeFrom.EXPLORE,
+        call_depth=0,
+        workflow_execution_id="run-1",
+    )
+    runtime_state = GraphRuntimeState(variable_pool=VariablePool(), start_at=0.0)
+    runtime_state.outputs = {"answer": "ok"}
+    wrapper = _WorkflowGenerateEntityWrapper(entity=generate_entity)
+    return WorkflowResumptionContext(
+        generate_entity=wrapper,
+        serialized_graph_runtime_state=runtime_state.dumps(),
+    )
+
+
+class _SessionContext:
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    def __enter__(self) -> Any:
+        return self._session
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        return False
+
+
+class _SessionMaker:
+    def __init__(self, session: Any) -> None:
+        self._session = session
+
+    def __call__(self) -> _SessionContext:
+        return _SessionContext(self._session)
+
+
+class _SubscriptionContext:
+    def __init__(self, subscription: Any) -> None:
+        self._subscription = subscription
+
+    def __enter__(self) -> Any:
+        return self._subscription
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        return False
+
+
+class _Topic:
+    def __init__(self, subscription: Any) -> None:
+        self._subscription = subscription
+
+    def subscribe(self) -> _SubscriptionContext:
+        return _SubscriptionContext(self._subscription)
+
+
+class _StaticSubscription:
+    def receive(self, timeout: int = 1) -> None:
+        return None
+
+
+@dataclass(frozen=True)
+class _PauseEntity(WorkflowPauseEntity):
+    state: bytes
+
+    @property
+    def id(self) -> str:
+        return "pause-1"
+
+    @property
+    def workflow_execution_id(self) -> str:
+        return "run-1"
+
+    @property
+    def resumed_at(self) -> datetime | None:
+        return None
+
+    @property
+    def paused_at(self) -> datetime:
+        return datetime(2024, 1, 1, tzinfo=UTC)
+
+    def get_state(self) -> bytes:
+        return self.state
+
+    def get_pause_reasons(self) -> list[Any]:
+        return []
+
+
+def test_get_message_context_should_return_none_when_no_message() -> None:
+    # Arrange
+    session = SimpleNamespace(scalar=MagicMock(return_value=None))
+    session_maker = _SessionMaker(session)
+
+    # Act
+    result = service_module._get_message_context(cast(sessionmaker[Session], session_maker), "run-1")
+
+    # Assert
+    assert result is None
+
+
+def test_get_message_context_should_default_created_at_to_zero_when_message_has_no_timestamp() -> None:
+    # Arrange
+    message = SimpleNamespace(
+        id="msg-1",
+        conversation_id="conv-1",
+        created_at=None,
+        answer="answer",
+    )
+    session = SimpleNamespace(scalar=MagicMock(return_value=message))
+    session_maker = _SessionMaker(session)
+
+    # Act
+    result = service_module._get_message_context(cast(sessionmaker[Session], session_maker), "run-1")
+
+    # Assert
+    assert result is not None
+    assert result.created_at == 0
+    assert result.message_id == "msg-1"
+    assert result.conversation_id == "conv-1"
+    assert result.answer == "answer"
+
+
+def test_load_resumption_context_should_return_none_when_pause_entity_missing() -> None:
+    # Arrange
+
+    # Act
+    result = service_module._load_resumption_context(None)
+
+    # Assert
+    assert result is None
+
+
+def test_load_resumption_context_should_return_none_when_pause_entity_state_is_invalid() -> None:
+    # Arrange
+    pause_entity = _PauseEntity(state=b"not-a-valid-state")
+
+    # Act
+    result = service_module._load_resumption_context(pause_entity)
+
+    # Assert
+    assert result is None
+
+
+def test_load_resumption_context_should_parse_valid_state_into_context() -> None:
+    # Arrange
+    context = _build_resumption_context_additional(task_id="task-ctx")
+    pause_entity = _PauseEntity(state=context.dumps().encode())
+
+    # Act
+    result = service_module._load_resumption_context(pause_entity)
+
+    # Assert
+    assert result is not None
+    assert result.get_generate_entity().task_id == "task-ctx"
+
+
+def test_resolve_task_id_should_return_workflow_run_id_when_buffer_state_is_missing() -> None:
+    # Arrange
+
+    # Act
+    result = service_module._resolve_task_id(
+        resumption_context=None,
+        buffer_state=None,
+        workflow_run_id="run-1",
+    )
+
+    # Assert
+    assert result == "run-1"
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected"),
+    [
+        (b'{"event":"node_started"}', {"event": "node_started"}),
+        (b"invalid-json", None),
+        (b"[]", None),
+    ],
+)
+def test_parse_event_message_should_parse_only_json_object(
+    payload: bytes,
+    expected: dict[str, Any] | None,
+) -> None:
+    # Arrange
+
+    # Act
+    result = service_module._parse_event_message(payload)
+
+    # Assert
+    assert result == expected
+
+
+def test_is_terminal_event_should_recognize_finished_and_optional_paused_events() -> None:
+    # Arrange
+    finished_event = {"event": StreamEvent.WORKFLOW_FINISHED.value}
+    paused_event = {"event": StreamEvent.WORKFLOW_PAUSED.value}
+
+    # Act
+    is_finished = service_module._is_terminal_event(finished_event, close_on_pause=False)
+    paused_without_flag = service_module._is_terminal_event(paused_event, close_on_pause=False)
+    paused_with_flag = service_module._is_terminal_event(paused_event, close_on_pause=True)
+
+    # Assert
+    assert is_finished is True
+    assert paused_without_flag is False
+    assert paused_with_flag is True
+    assert service_module._is_terminal_event(StreamEvent.PING.value, close_on_pause=True) is False
+
+
+def test_apply_message_context_should_update_payload_when_context_exists() -> None:
+    # Arrange
+    payload: dict[str, Any] = {"event": "workflow_started"}
+    context = MessageContext(conversation_id="conv-1", message_id="msg-1", created_at=1700000000)
+
+    # Act
+    service_module._apply_message_context(payload, context)
+
+    # Assert
+    assert payload["conversation_id"] == "conv-1"
+    assert payload["message_id"] == "msg-1"
+    assert payload["created_at"] == 1700000000
+
+
+def test_start_buffering_should_capture_task_id_and_enqueue_event() -> None:
+    # Arrange
+    class Subscription:
+        def __init__(self) -> None:
+            self._calls = 0
+
+        def receive(self, timeout: int = 1) -> bytes | None:
+            self._calls += 1
+            if self._calls == 1:
+                return b'{"event":"node_started","task_id":"task-1"}'
+            return None
+
+    subscription = Subscription()
+
+    # Act
+    buffer_state = service_module._start_buffering(subscription)
+    ready = buffer_state.task_id_ready.wait(timeout=1)
+    event = buffer_state.queue.get(timeout=1)
+    buffer_state.stop_event.set()
+    finished = buffer_state.done_event.wait(timeout=1)
+
+    # Assert
+    assert ready is True
+    assert finished is True
+    assert buffer_state.task_id_hint == "task-1"
+    assert event["event"] == "node_started"
+
+
+def test_start_buffering_should_drop_old_event_when_queue_is_full(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    class QueueWithSingleFull:
+        def __init__(self) -> None:
+            self._first_put = True
+            self.items: list[dict[str, Any]] = [{"event": "old"}]
+
+        def put_nowait(self, item: dict[str, Any]) -> None:
+            if self._first_put:
+                self._first_put = False
+                raise queue.Full
+            self.items.append(item)
+
+        def get_nowait(self) -> dict[str, Any]:
+            if not self.items:
+                raise queue.Empty
+            return self.items.pop(0)
+
+        def empty(self) -> bool:
+            return len(self.items) == 0
+
+    fake_queue = QueueWithSingleFull()
+    monkeypatch.setattr(service_module.queue, "Queue", lambda maxsize=2048: fake_queue)
+
+    class Subscription:
+        def __init__(self) -> None:
+            self._calls = 0
+
+        def receive(self, timeout: int = 1) -> bytes | None:
+            self._calls += 1
+            if self._calls == 1:
+                return b'{"event":"node_started","task_id":"task-2"}'
+            return None
+
+    subscription = Subscription()
+
+    # Act
+    buffer_state = service_module._start_buffering(subscription)
+    ready = buffer_state.task_id_ready.wait(timeout=1)
+    buffer_state.stop_event.set()
+    finished = buffer_state.done_event.wait(timeout=1)
+
+    # Assert
+    assert ready is True
+    assert finished is True
+    assert fake_queue.items[-1]["task_id"] == "task-2"
+
+
+def test_start_buffering_should_set_done_event_when_subscription_raises() -> None:
+    # Arrange
+    class Subscription:
+        def receive(self, timeout: int = 1) -> bytes | None:
+            raise RuntimeError("subscription failure")
+
+    subscription = Subscription()
+
+    # Act
+    buffer_state = service_module._start_buffering(subscription)
+    finished = buffer_state.done_event.wait(timeout=1)
+
+    # Assert
+    assert finished is True
+
+
+def test_build_workflow_event_stream_should_emit_ping_and_terminal_snapshot_event(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    workflow_run = _build_workflow_run_additional(status=WorkflowExecutionStatus.RUNNING)
+    topic = _Topic(_StaticSubscription())
+    workflow_run_repo = SimpleNamespace(get_workflow_pause=MagicMock())
+    node_repo = SimpleNamespace(get_execution_snapshots_by_workflow_run=MagicMock(return_value=[]))
+    factory = SimpleNamespace(
+        create_api_workflow_run_repository=MagicMock(return_value=workflow_run_repo),
+        create_api_workflow_node_execution_repository=MagicMock(return_value=node_repo),
+    )
+    monkeypatch.setattr(service_module, "DifyAPIRepositoryFactory", factory)
+    monkeypatch.setattr(service_module.MessageGenerator, "get_response_topic", MagicMock(return_value=topic))
+    monkeypatch.setattr(
+        service_module,
+        "_get_message_context",
+        MagicMock(return_value=MessageContext("conv-1", "msg-1", 1700000000)),
+    )
+    monkeypatch.setattr(service_module, "_load_resumption_context", MagicMock(return_value=None))
+    buffer_state = BufferState(
+        queue=queue.Queue(),
+        stop_event=Event(),
+        done_event=Event(),
+        task_id_ready=Event(),
+        task_id_hint="task-1",
+    )
+    monkeypatch.setattr(service_module, "_start_buffering", MagicMock(return_value=buffer_state))
+    monkeypatch.setattr(service_module, "_resolve_task_id", MagicMock(return_value="task-1"))
+    monkeypatch.setattr(
+        service_module,
+        "_build_snapshot_events",
+        MagicMock(return_value=[{"event": StreamEvent.WORKFLOW_FINISHED.value, "task_id": "task-1"}]),
+    )
+
+    # Act
+    events = list(
+        build_workflow_event_stream(
+            app_mode=AppMode.ADVANCED_CHAT,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=MagicMock(),
+        )
+    )
+
+    # Assert
+    assert events[0] == StreamEvent.PING.value
+    finished_event = cast(Mapping[str, Any], events[1])
+    assert finished_event["event"] == StreamEvent.WORKFLOW_FINISHED.value
+    assert buffer_state.stop_event.is_set() is True
+    node_repo.get_execution_snapshots_by_workflow_run.assert_called_once()
+    called_kwargs = node_repo.get_execution_snapshots_by_workflow_run.call_args.kwargs
+    assert called_kwargs["workflow_run_id"] == "run-1"
+
+
+def test_build_workflow_event_stream_should_emit_periodic_ping_and_stop_after_idle_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    workflow_run = _build_workflow_run_additional(status=WorkflowExecutionStatus.RUNNING)
+    topic = _Topic(_StaticSubscription())
+    workflow_run_repo = SimpleNamespace(get_workflow_pause=MagicMock())
+    node_repo = SimpleNamespace(get_execution_snapshots_by_workflow_run=MagicMock(return_value=[]))
+    factory = SimpleNamespace(
+        create_api_workflow_run_repository=MagicMock(return_value=workflow_run_repo),
+        create_api_workflow_node_execution_repository=MagicMock(return_value=node_repo),
+    )
+    monkeypatch.setattr(service_module, "DifyAPIRepositoryFactory", factory)
+    monkeypatch.setattr(service_module.MessageGenerator, "get_response_topic", MagicMock(return_value=topic))
+    monkeypatch.setattr(service_module, "_load_resumption_context", MagicMock(return_value=None))
+    monkeypatch.setattr(service_module, "_build_snapshot_events", MagicMock(return_value=[]))
+    monkeypatch.setattr(service_module, "_resolve_task_id", MagicMock(return_value="task-1"))
+
+    class AlwaysEmptyQueue:
+        def empty(self) -> bool:
+            return False
+
+        def get(self, timeout: int = 1) -> None:
+            raise queue.Empty
+
+    buffer_state = BufferState(
+        queue=AlwaysEmptyQueue(),  # type: ignore[arg-type]
+        stop_event=Event(),
+        done_event=Event(),
+        task_id_ready=Event(),
+        task_id_hint="task-1",
+    )
+    monkeypatch.setattr(service_module, "_start_buffering", MagicMock(return_value=buffer_state))
+    time_values = cycle([0.0, 6.0, 21.0, 26.0])
+    monkeypatch.setattr(service_module.time, "time", lambda: next(time_values))
+
+    # Act
+    events = list(
+        build_workflow_event_stream(
+            app_mode=AppMode.WORKFLOW,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=MagicMock(),
+            idle_timeout=20.0,
+            ping_interval=5.0,
+        )
+    )
+
+    # Assert
+    assert events == [StreamEvent.PING.value, StreamEvent.PING.value]
+    assert buffer_state.stop_event.is_set() is True
+
+
+def test_build_workflow_event_stream_should_exit_when_buffer_done_and_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    workflow_run = _build_workflow_run_additional(status=WorkflowExecutionStatus.RUNNING)
+    topic = _Topic(_StaticSubscription())
+    workflow_run_repo = SimpleNamespace(get_workflow_pause=MagicMock())
+    node_repo = SimpleNamespace(get_execution_snapshots_by_workflow_run=MagicMock(return_value=[]))
+    factory = SimpleNamespace(
+        create_api_workflow_run_repository=MagicMock(return_value=workflow_run_repo),
+        create_api_workflow_node_execution_repository=MagicMock(return_value=node_repo),
+    )
+    monkeypatch.setattr(service_module, "DifyAPIRepositoryFactory", factory)
+    monkeypatch.setattr(service_module.MessageGenerator, "get_response_topic", MagicMock(return_value=topic))
+    monkeypatch.setattr(service_module, "_load_resumption_context", MagicMock(return_value=None))
+    monkeypatch.setattr(service_module, "_build_snapshot_events", MagicMock(return_value=[]))
+    monkeypatch.setattr(service_module, "_resolve_task_id", MagicMock(return_value="task-1"))
+    buffer_state = BufferState(
+        queue=queue.Queue(),
+        stop_event=Event(),
+        done_event=Event(),
+        task_id_ready=Event(),
+        task_id_hint="task-1",
+    )
+    buffer_state.done_event.set()
+    monkeypatch.setattr(service_module, "_start_buffering", MagicMock(return_value=buffer_state))
+
+    # Act
+    events = list(
+        build_workflow_event_stream(
+            app_mode=AppMode.WORKFLOW,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=MagicMock(),
+        )
+    )
+
+    # Assert
+    assert events == [StreamEvent.PING.value]
+    assert buffer_state.stop_event.is_set() is True
+
+
+def test_build_workflow_event_stream_should_continue_when_pause_loading_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Arrange
+    workflow_run = _build_workflow_run_additional(status=WorkflowExecutionStatus.PAUSED)
+    topic = _Topic(_StaticSubscription())
+    workflow_run_repo = SimpleNamespace(get_workflow_pause=MagicMock(side_effect=RuntimeError("boom")))
+    node_repo = SimpleNamespace(get_execution_snapshots_by_workflow_run=MagicMock(return_value=[]))
+    factory = SimpleNamespace(
+        create_api_workflow_run_repository=MagicMock(return_value=workflow_run_repo),
+        create_api_workflow_node_execution_repository=MagicMock(return_value=node_repo),
+    )
+    monkeypatch.setattr(service_module, "DifyAPIRepositoryFactory", factory)
+    monkeypatch.setattr(service_module.MessageGenerator, "get_response_topic", MagicMock(return_value=topic))
+    monkeypatch.setattr(service_module, "_load_resumption_context", MagicMock(return_value=None))
+    monkeypatch.setattr(service_module, "_resolve_task_id", MagicMock(return_value="task-1"))
+    snapshot_builder = MagicMock(return_value=[{"event": StreamEvent.WORKFLOW_FINISHED.value}])
+    monkeypatch.setattr(service_module, "_build_snapshot_events", snapshot_builder)
+    buffer_state = BufferState(
+        queue=queue.Queue(),
+        stop_event=Event(),
+        done_event=Event(),
+        task_id_ready=Event(),
+        task_id_hint="task-1",
+    )
+    monkeypatch.setattr(service_module, "_start_buffering", MagicMock(return_value=buffer_state))
+
+    # Act
+    events = list(
+        build_workflow_event_stream(
+            app_mode=AppMode.WORKFLOW,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=MagicMock(),
+        )
+    )
+
+    # Assert
+    assert events[0] == StreamEvent.PING.value
+    assert snapshot_builder.call_args.kwargs["pause_entity"] is None
+
+
+def test_is_terminal_event_respects_close_on_pause_flag() -> None:
+    pause_event = {"event": "workflow_paused"}
+    finish_event = {"event": "workflow_finished"}
+
+    assert _is_terminal_event(pause_event, close_on_pause=True) is True
+    assert _is_terminal_event(pause_event, close_on_pause=False) is False
+    assert _is_terminal_event(finish_event, close_on_pause=False) is True
+
+
+def test_build_snapshot_events_preserves_public_form_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    workflow_run = _build_workflow_run(WorkflowExecutionStatus.PAUSED)
+    snapshot = _build_snapshot(WorkflowNodeExecutionStatus.PAUSED)
+    resumption_context = _build_resumption_context("task-ctx")
+    monkeypatch.setattr(service_module, "load_form_tokens_by_form_id", lambda form_ids, session=None: {"form-1": "wtok"})
+    session_maker = _SessionMaker(
+        SimpleNamespace(
+            execute=lambda _stmt: [("form-1", datetime(2024, 1, 1, tzinfo=UTC), '{"display_in_ui": true}')],
+        )
+    )
+    pause_entity = _FakePauseEntity(
+        pause_id="pause-1",
+        workflow_run_id="run-1",
+        paused_at_value=datetime(2024, 1, 1, tzinfo=UTC),
+        pause_reasons=[
+            HumanInputRequired(
+                form_id="form-1",
+                form_content="content",
+                node_id="node-1",
+                node_title="Human Input",
+                form_token="wtok",
+            )
+        ],
+    )
+
+    events = _build_snapshot_events(
+        workflow_run=workflow_run,
+        node_snapshots=[snapshot],
+        task_id="task-ctx",
+        message_context=None,
+        pause_entity=pause_entity,
+        resumption_context=resumption_context,
+        session_maker=cast(sessionmaker[Session], session_maker),
+    )
+
+    assert events[-2]["event"] == StreamEvent.HUMAN_INPUT_REQUIRED.value
+    assert events[-2]["data"]["form_token"] == "wtok"
+    pause_data = events[-1]["data"]
+    assert pause_data["reasons"][0]["form_token"] == "wtok"
+
+
+def test_build_workflow_event_stream_loads_pause_tokens_without_flask_app_context(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    workflow_run = _build_workflow_run_additional(status=WorkflowExecutionStatus.PAUSED)
+    topic = _Topic(_StaticSubscription())
+    pause_entity = _FakePauseEntity(
+        pause_id="pause-1",
+        workflow_run_id="run-1",
+        paused_at_value=datetime(2024, 1, 1, tzinfo=UTC),
+        pause_reasons=[
+            HumanInputRequired(
+                form_id="form-1",
+                form_content="content",
+                node_id="node-1",
+                node_title="Human Input",
+            )
+        ],
+    )
+    workflow_run_repo = SimpleNamespace(get_workflow_pause=MagicMock(return_value=pause_entity))
+    node_repo = SimpleNamespace(get_execution_snapshots_by_workflow_run=MagicMock(return_value=[]))
+    factory = SimpleNamespace(
+        create_api_workflow_run_repository=MagicMock(return_value=workflow_run_repo),
+        create_api_workflow_node_execution_repository=MagicMock(return_value=node_repo),
+    )
+    monkeypatch.setattr(service_module, "DifyAPIRepositoryFactory", factory)
+    monkeypatch.setattr(service_module.MessageGenerator, "get_response_topic", MagicMock(return_value=topic))
+    monkeypatch.setattr(service_module, "_load_resumption_context", MagicMock(return_value=_build_resumption_context("task-1")))
+    monkeypatch.setattr(service_module, "load_form_tokens_by_form_id", lambda form_ids, session=None: {"form-1": "wtok"})
+
+    session = SimpleNamespace(
+        scalar=MagicMock(return_value=None),
+        execute=lambda _stmt: [("form-1", datetime(2024, 1, 1, tzinfo=UTC), '{"display_in_ui": true}')],
+    )
+    session_maker = _SessionMaker(session)
+
+    events = list(
+        build_workflow_event_stream(
+            app_mode=AppMode.WORKFLOW,
+            workflow_run=workflow_run,
+            tenant_id="tenant-1",
+            app_id="app-1",
+            session_maker=cast(sessionmaker[Session], session_maker),
+        )
+    )
+
+    pause_event = cast(Mapping[str, Any], events[-1])
+    assert pause_event["event"] == StreamEvent.WORKFLOW_PAUSED.value
+    assert pause_event["data"]["reasons"][0]["form_token"] == "wtok"

api/tests/unit_tests/tasks/test_workflow_execute_task.py

@@ -7,11 +7,16 @@ from unittest.mock import MagicMock
 
 import pytest
 
-from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity, InvokeFrom
+from core.app.entities.app_invoke_entities import AdvancedChatAppGenerateEntity, InvokeFrom, WorkflowAppGenerateEntity
 from models.enums import CreatorUserRole
 from models.model import App, AppMode, Conversation
 from models.workflow import Workflow, WorkflowRun
-from tasks.app_generate.workflow_execute_task import _publish_streaming_response, _resume_app_execution
+from tasks.app_generate.workflow_execute_task import (
+    _publish_streaming_response,
+    _resume_advanced_chat,
+    _resume_app_execution,
+    _resume_workflow,
+)
 
 
 class _FakeSessionContext:
@@ -38,12 +43,28 @@ def _build_advanced_chat_generate_entity(conversation_id: str | None) -> Advance
     )
 
 
+def _build_workflow_generate_entity(stream: bool) -> WorkflowAppGenerateEntity:
+    return WorkflowAppGenerateEntity(
+        task_id="task-id",
+        inputs={},
+        files=[],
+        user_id="user-id",
+        stream=stream,
+        invoke_from=InvokeFrom.WEB_APP,
+        workflow_execution_id="workflow-run-id",
+    )
+
+
+def _single_event_generator(payload):
+    yield payload
+
+
 @pytest.fixture
-def mock_topic(mocker) -> MagicMock:
+def mock_topic(monkeypatch: pytest.MonkeyPatch) -> MagicMock:
     topic = MagicMock()
-    mocker.patch(
+    monkeypatch.setattr(
         "tasks.app_generate.workflow_execute_task.MessageBasedAppGenerator.get_response_topic",
-        return_value=topic,
+        lambda *_args, **_kwargs: topic,
     )
     return topic
 
@@ -67,31 +88,35 @@ def test_publish_streaming_response_coerces_string_uuid(mock_topic: MagicMock):
     mock_topic.publish.assert_called_once_with(json.dumps({"event": "bar"}).encode())
 
 
-def test_resume_app_execution_queries_message_by_conversation_and_workflow_run(mocker):
+def test_resume_app_execution_queries_message_by_conversation_and_workflow_run(monkeypatch: pytest.MonkeyPatch):
     workflow_run_id = "run-id"
     conversation_id = "conversation-id"
     message = MagicMock()
 
-    mocker.patch("tasks.app_generate.workflow_execute_task.db", SimpleNamespace(engine=object()))
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task.db", SimpleNamespace(engine=object()))
 
     pause_entity = MagicMock()
     pause_entity.get_state.return_value = b"state"
 
     workflow_run_repo = MagicMock()
     workflow_run_repo.get_workflow_pause.return_value = pause_entity
-    mocker.patch(
+    monkeypatch.setattr(
         "tasks.app_generate.workflow_execute_task.DifyAPIRepositoryFactory.create_api_workflow_run_repository",
-        return_value=workflow_run_repo,
+        lambda *_args, **_kwargs: workflow_run_repo,
     )
 
     generate_entity = _build_advanced_chat_generate_entity(conversation_id)
     resumption_context = MagicMock()
     resumption_context.serialized_graph_runtime_state = "{}"
     resumption_context.get_generate_entity.return_value = generate_entity
-    mocker.patch(
-        "tasks.app_generate.workflow_execute_task.WorkflowResumptionContext.loads", return_value=resumption_context
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.WorkflowResumptionContext.loads",
+        lambda *_args, **_kwargs: resumption_context,
+    )
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.GraphRuntimeState.from_snapshot",
+        lambda *_args, **_kwargs: MagicMock(),
     )
-    mocker.patch("tasks.app_generate.workflow_execute_task.GraphRuntimeState.from_snapshot", return_value=MagicMock())
 
     workflow_run = SimpleNamespace(
         workflow_id="wf-id",
@@ -120,10 +145,11 @@ def test_resume_app_execution_queries_message_by_conversation_and_workflow_run(m
     session.get.side_effect = _session_get
     session.scalar.return_value = message
 
-    mocker.patch("tasks.app_generate.workflow_execute_task.Session", return_value=_FakeSessionContext(session))
-    mocker.patch("tasks.app_generate.workflow_execute_task._resolve_user_for_run", return_value=MagicMock())
-    resume_advanced_chat = mocker.patch("tasks.app_generate.workflow_execute_task._resume_advanced_chat")
-    mocker.patch("tasks.app_generate.workflow_execute_task._resume_workflow")
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task.Session", lambda *_args, **_kwargs: _FakeSessionContext(session))
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._resolve_user_for_run", lambda *_args, **_kwargs: MagicMock())
+    resume_advanced_chat = MagicMock()
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._resume_advanced_chat", resume_advanced_chat)
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._resume_workflow", MagicMock())
 
     _resume_app_execution({"workflow_run_id": workflow_run_id})
 
@@ -144,29 +170,35 @@ def test_resume_app_execution_queries_message_by_conversation_and_workflow_run(m
     assert resume_advanced_chat.call_args.kwargs["message"] is message
 
 
-def test_resume_app_execution_returns_early_when_advanced_chat_missing_conversation_id(mocker):
+def test_resume_app_execution_returns_early_when_advanced_chat_missing_conversation_id(
+    monkeypatch: pytest.MonkeyPatch,
+):
     workflow_run_id = "run-id"
 
-    mocker.patch("tasks.app_generate.workflow_execute_task.db", SimpleNamespace(engine=object()))
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task.db", SimpleNamespace(engine=object()))
 
     pause_entity = MagicMock()
     pause_entity.get_state.return_value = b"state"
 
     workflow_run_repo = MagicMock()
     workflow_run_repo.get_workflow_pause.return_value = pause_entity
-    mocker.patch(
+    monkeypatch.setattr(
         "tasks.app_generate.workflow_execute_task.DifyAPIRepositoryFactory.create_api_workflow_run_repository",
-        return_value=workflow_run_repo,
+        lambda *_args, **_kwargs: workflow_run_repo,
     )
 
     generate_entity = _build_advanced_chat_generate_entity(conversation_id=None)
     resumption_context = MagicMock()
     resumption_context.serialized_graph_runtime_state = "{}"
     resumption_context.get_generate_entity.return_value = generate_entity
-    mocker.patch(
-        "tasks.app_generate.workflow_execute_task.WorkflowResumptionContext.loads", return_value=resumption_context
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.WorkflowResumptionContext.loads",
+        lambda *_args, **_kwargs: resumption_context,
+    )
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.GraphRuntimeState.from_snapshot",
+        lambda *_args, **_kwargs: MagicMock(),
     )
-    mocker.patch("tasks.app_generate.workflow_execute_task.GraphRuntimeState.from_snapshot", return_value=MagicMock())
 
     workflow_run = SimpleNamespace(
         workflow_id="wf-id",
@@ -191,12 +223,99 @@ def test_resume_app_execution_returns_early_when_advanced_chat_missing_conversat
 
     session.get.side_effect = _session_get
 
-    mocker.patch("tasks.app_generate.workflow_execute_task.Session", return_value=_FakeSessionContext(session))
-    mocker.patch("tasks.app_generate.workflow_execute_task._resolve_user_for_run", return_value=MagicMock())
-    resume_advanced_chat = mocker.patch("tasks.app_generate.workflow_execute_task._resume_advanced_chat")
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task.Session", lambda *_args, **_kwargs: _FakeSessionContext(session))
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._resolve_user_for_run", lambda *_args, **_kwargs: MagicMock())
+    resume_advanced_chat = MagicMock()
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._resume_advanced_chat", resume_advanced_chat)
 
     _resume_app_execution({"workflow_run_id": workflow_run_id})
 
     session.scalar.assert_not_called()
     workflow_run_repo.resume_workflow_pause.assert_not_called()
     resume_advanced_chat.assert_not_called()
+
+
+def test_resume_advanced_chat_publishes_events_for_originally_blocking_runs(monkeypatch: pytest.MonkeyPatch):
+    generate_entity = _build_advanced_chat_generate_entity(conversation_id="conversation-id")
+    generate_entity.stream = False
+
+    generator_instance = MagicMock()
+    response_stream = _single_event_generator({"event": "message"})
+    generator_instance.resume.return_value = response_stream
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.AdvancedChatAppGenerator",
+        lambda: generator_instance,
+    )
+
+    publish_streaming_response = MagicMock()
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._publish_streaming_response", publish_streaming_response)
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.DifyCoreRepositoryFactory.create_workflow_execution_repository",
+        lambda **kwargs: MagicMock(),
+    )
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.DifyCoreRepositoryFactory.create_workflow_node_execution_repository",
+        lambda **kwargs: MagicMock(),
+    )
+
+    _resume_advanced_chat(
+        app_model=SimpleNamespace(id="app-id"),
+        workflow=SimpleNamespace(created_by="workflow-owner"),
+        user=MagicMock(),
+        conversation=SimpleNamespace(id="conversation-id"),
+        message=MagicMock(),
+        generate_entity=generate_entity,
+        graph_runtime_state=MagicMock(),
+        session_factory=MagicMock(),
+        pause_state_config=MagicMock(),
+        workflow_run_id="workflow-run-id",
+        workflow_run=SimpleNamespace(triggered_from="app_run"),
+    )
+
+    resumed_entity = generator_instance.resume.call_args.kwargs["application_generate_entity"]
+    assert resumed_entity.stream is True
+    publish_streaming_response.assert_called_once_with(response_stream, "workflow-run-id", AppMode.ADVANCED_CHAT)
+
+
+def test_resume_workflow_publishes_events_for_originally_blocking_runs(monkeypatch: pytest.MonkeyPatch):
+    generate_entity = _build_workflow_generate_entity(stream=False)
+
+    generator_instance = MagicMock()
+    response_stream = _single_event_generator({"event": "workflow_finished"})
+    generator_instance.resume.return_value = response_stream
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.WorkflowAppGenerator",
+        lambda: generator_instance,
+    )
+
+    publish_streaming_response = MagicMock()
+    monkeypatch.setattr("tasks.app_generate.workflow_execute_task._publish_streaming_response", publish_streaming_response)
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.DifyCoreRepositoryFactory.create_workflow_execution_repository",
+        lambda **kwargs: MagicMock(),
+    )
+    monkeypatch.setattr(
+        "tasks.app_generate.workflow_execute_task.DifyCoreRepositoryFactory.create_workflow_node_execution_repository",
+        lambda **kwargs: MagicMock(),
+    )
+    workflow_run_repo = MagicMock()
+    pause_entity = MagicMock()
+
+    _resume_workflow(
+        app_model=SimpleNamespace(id="app-id"),
+        workflow=SimpleNamespace(created_by="workflow-owner"),
+        user=MagicMock(),
+        generate_entity=generate_entity,
+        graph_runtime_state=MagicMock(),
+        session_factory=MagicMock(),
+        pause_state_config=MagicMock(),
+        workflow_run_id="workflow-run-id",
+        workflow_run=SimpleNamespace(triggered_from="app_run"),
+        workflow_run_repo=workflow_run_repo,
+        pause_entity=pause_entity,
+    )
+
+    resumed_entity = generator_instance.resume.call_args.kwargs["application_generate_entity"]
+    assert resumed_entity.stream is True
+    publish_streaming_response.assert_called_once_with(response_stream, "workflow-run-id", AppMode.WORKFLOW)
+    workflow_run_repo.delete_workflow_pause.assert_called_once_with(pause_entity)

api/uv.lock

@@ -537,6 +537,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1a/39/47f9197bdd44df24d67ac8893641e16f386c984a0619ef2ee4c51fbbc019/beautifulsoup4-4.14.3-py3-none-any.whl", hash = "sha256:0918bfe44902e6ad8d57732ba310582e98da931428d231a5ecb9e7c703a735bb", size = 107721, upload-time = "2025-11-30T15:08:24.087Z" },
 ]
 
+[[package]]
+name = "bidict"
+version = "0.23.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/6e/026678aa5a830e07cd9498a05d3e7e650a4f56a42f267a53d22bcda1bdc9/bidict-0.23.1.tar.gz", hash = "sha256:03069d763bc387bbd20e7d49914e75fc4132a41937fa3405417e1a5a2d006d71", size = 29093, upload-time = "2024-02-18T19:09:05.748Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/99/37/e8730c3587a65eb5645d4aba2d27aae48e8003614d6aaf15dda67f702f1f/bidict-0.23.1-py3-none-any.whl", hash = "sha256:5dae8d4d79b552a71cbabc7deb25dfe8ce710b17ff41711e13010ead2abfc3e5", size = 32764, upload-time = "2024-02-18T19:09:04.156Z" },
+]
+
 [[package]]
 name = "billiard"
 version = "4.2.3"
@@ -1290,6 +1299,7 @@ dependencies = [
     { name = "flask-orjson" },
     { name = "flask-restx" },
     { name = "gevent" },
+    { name = "gevent-websocket" },
     { name = "gmpy2" },
     { name = "google-api-python-client" },
     { name = "google-cloud-aiplatform" },
@@ -1311,10 +1321,12 @@ dependencies = [
     { name = "opik" },
     { name = "psycogreen" },
     { name = "psycopg2-binary" },
+    { name = "python-socketio" },
     { name = "readabilipy" },
     { name = "redis", extra = ["hiredis"] },
     { name = "resend" },
     { name = "sendgrid" },
+    { name = "sseclient-py" },
     { name = "weave" },
 ]
 
@@ -1341,7 +1353,6 @@ dev = [
     { name = "pytest-xdist" },
     { name = "ruff" },
     { name = "scipy-stubs" },
-    { name = "sseclient-py" },
     { name = "testcontainers" },
     { name = "types-aiofiles" },
     { name = "types-beautifulsoup4" },
@@ -1542,6 +1553,7 @@ requires-dist = [
     { name = "flask-orjson", specifier = ">=2.0.0,<3.0.0" },
     { name = "flask-restx", specifier = ">=1.3.2,<2.0.0" },
     { name = "gevent", specifier = ">=26.4.0" },
+    { name = "gevent-websocket", specifier = ">=0.10.1" },
     { name = "gmpy2", specifier = ">=2.3.0" },
     { name = "google-api-python-client", specifier = ">=2.194.0" },
     { name = "google-cloud-aiplatform", specifier = ">=1.147.0,<2.0.0" },
@@ -1563,10 +1575,12 @@ requires-dist = [
     { name = "opik", specifier = "~=1.11.2" },
     { name = "psycogreen", specifier = ">=1.0.2" },
     { name = "psycopg2-binary", specifier = ">=2.9.11" },
+    { name = "python-socketio", specifier = ">=5.13.0" },
     { name = "readabilipy", specifier = ">=0.3.0,<1.0.0" },
     { name = "redis", extras = ["hiredis"], specifier = ">=7.4.0" },
     { name = "resend", specifier = ">=2.27.0,<3.0.0" },
     { name = "sendgrid", specifier = ">=6.12.5" },
+    { name = "sseclient-py", specifier = ">=1.8.0" },
     { name = "weave", specifier = ">=0.52.36,<1.0.0" },
 ]
 
@@ -1593,7 +1607,6 @@ dev = [
     { name = "pytest-xdist", specifier = ">=3.8.0" },
     { name = "ruff", specifier = ">=0.15.10" },
     { name = "scipy-stubs", specifier = ">=1.15.3.0" },
-    { name = "sseclient-py", specifier = ">=1.8.0" },
     { name = "testcontainers", specifier = ">=4.14.2" },
     { name = "types-aiofiles", specifier = ">=25.1.0" },
     { name = "types-beautifulsoup4", specifier = ">=4.12.0" },
@@ -2464,6 +2477,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f6/df/7875e08b06a95f4577b71708ec470d029fadf873a66eb813a2861d79dfb5/gevent-26.4.0-cp312-cp312-win_amd64.whl", hash = "sha256:1c737e6ac6ce1398df0e3f41c58d982e397c993cbe73ac05b7edbe39e128c9cb", size = 1680530, upload-time = "2026-04-08T23:15:38.714Z" },
 ]
 
+[[package]]
+name = "gevent-websocket"
+version = "0.10.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "gevent" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/98/d2/6fa19239ff1ab072af40ebf339acd91fb97f34617c2ee625b8e34bf42393/gevent-websocket-0.10.1.tar.gz", hash = "sha256:7eaef32968290c9121f7c35b973e2cc302ffb076d018c9068d2f5ca8b2d85fb0", size = 18366, upload-time = "2017-03-12T22:46:05.68Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/84/2dc373eb6493e00c884cc11e6c059ec97abae2678d42f06bf780570b0193/gevent_websocket-0.10.1-py3-none-any.whl", hash = "sha256:17b67d91282f8f4c973eba0551183fc84f56f1c90c8f6b6b30256f31f66f5242", size = 22987, upload-time = "2017-03-12T22:46:03.611Z" },
+]
+
 [[package]]
 name = "gitdb"
 version = "4.0.12"
@@ -5313,6 +5338,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
 ]
 
+[[package]]
+name = "python-engineio"
+version = "4.13.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "simple-websocket" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/34/12/bdef9dbeedbe2cdeba2a2056ad27b1fb081557d34b69a97f574843462cae/python_engineio-4.13.1.tar.gz", hash = "sha256:0a853fcef52f5b345425d8c2b921ac85023a04dfcf75d7b74696c61e940fd066", size = 92348, upload-time = "2026-02-06T23:38:06.12Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/aa/54/0cce26da03a981f949bb8449c9778537f75f5917c172e1d2992ff25cb57d/python_engineio-4.13.1-py3-none-any.whl", hash = "sha256:f32ad10589859c11053ad7d9bb3c9695cdf862113bfb0d20bc4d890198287399", size = 59847, upload-time = "2026-02-06T23:38:04.861Z" },
+]
+
 [[package]]
 name = "python-http-client"
 version = "3.3.7"
@@ -5369,6 +5406,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d9/4f/00be2196329ebbff56ce564aa94efb0fbc828d00de250b1980de1a34ab49/python_pptx-1.0.2-py3-none-any.whl", hash = "sha256:160838e0b8565a8b1f67947675886e9fea18aa5e795db7ae531606d68e785cba", size = 472788, upload-time = "2024-08-07T17:33:28.192Z" },
 ]
 
+[[package]]
+name = "python-socketio"
+version = "5.16.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "bidict" },
+    { name = "python-engineio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/59/81/cf8284f45e32efa18d3848ed82cdd4dcc1b657b082458fbe01ad3e1f2f8d/python_socketio-5.16.1.tar.gz", hash = "sha256:f863f98eacce81ceea2e742f6388e10ca3cdd0764be21d30d5196470edf5ea89", size = 128508, upload-time = "2026-02-06T23:42:07Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/07/c7/deb8c5e604404dbf10a3808a858946ca3547692ff6316b698945bb72177e/python_socketio-5.16.1-py3-none-any.whl", hash = "sha256:a3eb1702e92aa2f2b5d3ba00261b61f062cce51f1cfb6900bf3ab4d1934d2d35", size = 82054, upload-time = "2026-02-06T23:42:05.772Z" },
+]
+
 [[package]]
 name = "pytz"
 version = "2025.2"
@@ -5749,6 +5799,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
 ]
 
+[[package]]
+name = "simple-websocket"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wsproto" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b0/d4/bfa032f961103eba93de583b161f0e6a5b63cebb8f2c7d0c6e6efe1e3d2e/simple_websocket-1.1.0.tar.gz", hash = "sha256:7939234e7aa067c534abdab3a9ed933ec9ce4691b0713c78acb195560aa52ae4", size = 17300, upload-time = "2024-10-10T22:39:31.412Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/52/59/0782e51887ac6b07ffd1570e0364cf901ebc36345fea669969d2084baebb/simple_websocket-1.1.0-py3-none-any.whl", hash = "sha256:4af6069630a38ed6c561010f0e11a5bc0d4ca569b36306eb257cd9a192497c8c", size = 13842, upload-time = "2024-10-10T22:39:29.645Z" },
+]
+
 [[package]]
 name = "six"
 version = "1.17.0"
@@ -7185,6 +7247,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ff/21/abdedb4cdf6ff41ebf01a74087740a709e2edb146490e4d9beea054b0b7a/wrapt-1.16.0-py3-none-any.whl", hash = "sha256:6906c4100a8fcbf2fa735f6059214bb13b97f75b1a61777fcf6432121ef12ef1", size = 23362, upload-time = "2023-11-09T06:33:28.271Z" },
 ]
 
+[[package]]
+name = "wsproto"
+version = "1.3.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c7/79/12135bdf8b9c9367b8701c2c19a14c913c120b882d50b014ca0d38083c2c/wsproto-1.3.2.tar.gz", hash = "sha256:b86885dcf294e15204919950f666e06ffc6c7c114ca900b060d6e16293528294", size = 50116, upload-time = "2025-11-20T18:18:01.871Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/f5/10b68b7b1544245097b2a1b8238f66f2fc6dcaeb24ba5d917f52bd2eed4f/wsproto-1.3.2-py3-none-any.whl", hash = "sha256:61eea322cdf56e8cc904bd3ad7573359a242ba65688716b0710a5eb12beab584", size = 24405, upload-time = "2025-11-20T18:18:00.454Z" },
+]
+
 [[package]]
 name = "xinference-client"
 version = "2.4.0"

docker/.env.example

@@ -132,6 +132,10 @@ MIGRATION_ENABLED=true
 # The default value is 300 seconds.
 FILES_ACCESS_TIMEOUT=300
 
+# Collaboration mode toggle
+# To open collaboration features, you also need to set SERVER_WORKER_CLASS=geventwebsocket.gunicorn.workers.GeventWebSocketWorker
+ENABLE_COLLABORATION_MODE=false
+
 # Access token expiration time in minutes
 ACCESS_TOKEN_EXPIRE_MINUTES=60
 
@@ -167,6 +171,7 @@ SERVER_WORKER_AMOUNT=1
 # Modifying it may also decrease throughput.
 #
 # It is strongly discouraged to change this parameter.
+# If enable collaboration mode, it must be set to geventwebsocket.gunicorn.workers.GeventWebSocketWorker
 SERVER_WORKER_CLASS=gevent
 
 # Default number of worker connections, the default is 10.
@@ -428,6 +433,8 @@ CONSOLE_CORS_ALLOW_ORIGINS=*
 COOKIE_DOMAIN=
 # When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1.
 NEXT_PUBLIC_COOKIE_DOMAIN=
+# WebSocket server URL. 
+NEXT_PUBLIC_SOCKET_URL=ws://localhost
 NEXT_PUBLIC_BATCH_CONCURRENCY=5
 
 # ------------------------------

docker/docker-compose-template.yaml

@@ -159,6 +159,7 @@ services:
       APP_API_URL: ${APP_API_URL:-}
       AMPLITUDE_API_KEY: ${AMPLITUDE_API_KEY:-}
       NEXT_PUBLIC_COOKIE_DOMAIN: ${NEXT_PUBLIC_COOKIE_DOMAIN:-}
+      NEXT_PUBLIC_SOCKET_URL: ${NEXT_PUBLIC_SOCKET_URL:-ws://localhost}
       SENTRY_DSN: ${WEB_SENTRY_DSN:-}
       NEXT_TELEMETRY_DISABLED: ${NEXT_TELEMETRY_DISABLED:-0}
       EXPERIMENTAL_ENABLE_VINEXT: ${EXPERIMENTAL_ENABLE_VINEXT:-false}

docker/docker-compose.yaml

@@ -34,6 +34,7 @@ x-shared-env: &shared-api-worker-env
   OPENAI_API_BASE: ${OPENAI_API_BASE:-https://api.openai.com/v1}
   MIGRATION_ENABLED: ${MIGRATION_ENABLED:-true}
   FILES_ACCESS_TIMEOUT: ${FILES_ACCESS_TIMEOUT:-300}
+  ENABLE_COLLABORATION_MODE: ${ENABLE_COLLABORATION_MODE:-false}
   ACCESS_TOKEN_EXPIRE_MINUTES: ${ACCESS_TOKEN_EXPIRE_MINUTES:-60}
   REFRESH_TOKEN_EXPIRE_DAYS: ${REFRESH_TOKEN_EXPIRE_DAYS:-30}
   APP_DEFAULT_ACTIVE_REQUESTS: ${APP_DEFAULT_ACTIVE_REQUESTS:-0}
@@ -119,6 +120,7 @@ x-shared-env: &shared-api-worker-env
   CONSOLE_CORS_ALLOW_ORIGINS: ${CONSOLE_CORS_ALLOW_ORIGINS:-*}
   COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
   NEXT_PUBLIC_COOKIE_DOMAIN: ${NEXT_PUBLIC_COOKIE_DOMAIN:-}
+  NEXT_PUBLIC_SOCKET_URL: ${NEXT_PUBLIC_SOCKET_URL:-ws://localhost}
   NEXT_PUBLIC_BATCH_CONCURRENCY: ${NEXT_PUBLIC_BATCH_CONCURRENCY:-5}
   STORAGE_TYPE: ${STORAGE_TYPE:-opendal}
   OPENDAL_SCHEME: ${OPENDAL_SCHEME:-fs}
@@ -878,6 +880,7 @@ services:
       APP_API_URL: ${APP_API_URL:-}
       AMPLITUDE_API_KEY: ${AMPLITUDE_API_KEY:-}
       NEXT_PUBLIC_COOKIE_DOMAIN: ${NEXT_PUBLIC_COOKIE_DOMAIN:-}
+      NEXT_PUBLIC_SOCKET_URL: ${NEXT_PUBLIC_SOCKET_URL:-ws://localhost}
       SENTRY_DSN: ${WEB_SENTRY_DSN:-}
       NEXT_TELEMETRY_DISABLED: ${NEXT_TELEMETRY_DISABLED:-0}
       EXPERIMENTAL_ENABLE_VINEXT: ${EXPERIMENTAL_ENABLE_VINEXT:-false}

docker/nginx/conf.d/default.conf.template

@@ -14,6 +14,14 @@ server {
       include proxy.conf;
     }
 
+    location /socket.io/ {
+      proxy_pass http://api:5001;
+      include proxy.conf;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection "upgrade";
+      proxy_cache_bypass $http_upgrade;
+    }
+
     location /v1 {
       proxy_pass http://api:5001;
       include proxy.conf;

packages/iconify-collections/assets/public/common/enter-key.svg

@@ -0,0 +1,4 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 4C0 1.79086 1.79086 0 4 0H12C14.2091 0 16 1.79086 16 4V12C16 14.2091 14.2091 16 12 16H4C1.79086 16 0 14.2091 0 12V4Z" fill="white" fill-opacity="0.12"/>
+<path d="M3.42756 8.7358V7.62784H10.8764C11.2003 7.62784 11.4957 7.5483 11.7628 7.3892C12.0298 7.23011 12.2415 7.01705 12.3977 6.75C12.5568 6.48295 12.6364 6.1875 12.6364 5.86364C12.6364 5.53977 12.5568 5.24574 12.3977 4.98153C12.2386 4.71449 12.0256 4.50142 11.7585 4.34233C11.4943 4.18324 11.2003 4.10369 10.8764 4.10369H10.3991V3H10.8764C11.4048 3 11.8849 3.12926 12.3168 3.38778C12.7486 3.64631 13.0938 3.99148 13.3523 4.4233C13.6108 4.85511 13.7401 5.33523 13.7401 5.86364C13.7401 6.25852 13.6648 6.62926 13.5142 6.97585C13.3665 7.32244 13.1619 7.62784 12.9006 7.89205C12.6392 8.15625 12.3352 8.36364 11.9886 8.5142C11.642 8.66193 11.2713 8.7358 10.8764 8.7358H3.42756ZM6.16761 12.0554L2.29403 8.18182L6.16761 4.30824L6.9304 5.07102L3.81534 8.18182L6.9304 11.2926L6.16761 12.0554Z" fill="white"/>
+</svg>

packages/iconify-collections/assets/public/other/comment.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="14" height="12" viewBox="0 0 14 12" fill="none">
+<path d="M12.3334 4C12.3334 2.52725 11.1395 1.33333 9.66671 1.33333H4.33337C2.86062 1.33333 1.66671 2.52724 1.66671 4V10.6667H9.66671C11.1395 10.6667 12.3334 9.47274 12.3334 8V4ZM7.66671 6.66667V8H4.33337V6.66667H7.66671ZM9.66671 4V5.33333H4.33337V4H9.66671ZM13.6667 8C13.6667 10.2091 11.8758 12 9.66671 12H0.333374V4C0.333374 1.79086 2.12424 0 4.33337 0H9.66671C11.8758 0 13.6667 1.79086 13.6667 4V8Z" fill="currentColor"/>
+</svg>

pnpm-lock.yaml

@@ -384,6 +384,9 @@ catalogs:
     lexical:
       specifier: 0.43.0
       version: 0.43.0
+    loro-crdt:
+      specifier: 1.10.8
+      version: 1.10.8
     mermaid:
       specifier: 11.14.0
       version: 11.14.0
@@ -471,6 +474,9 @@ catalogs:
     shiki:
       specifier: 4.0.2
       version: 4.0.2
+    socket.io-client:
+      specifier: 4.8.3
+      version: 4.8.3
     sortablejs:
       specifier: 1.15.7
       version: 1.15.7
@@ -839,6 +845,9 @@ importers:
       lexical:
         specifier: 'catalog:'
         version: 0.43.0
+      loro-crdt:
+        specifier: 'catalog:'
+        version: 1.10.8
       mermaid:
         specifier: 'catalog:'
         version: 11.14.0
@@ -920,6 +929,9 @@ importers:
       shiki:
         specifier: 'catalog:'
         version: 4.0.2
+      socket.io-client:
+        specifier: 'catalog:'
+        version: 4.8.3
       sortablejs:
         specifier: 'catalog:'
         version: 1.15.7
@@ -3544,6 +3556,9 @@ packages:
     resolution: {integrity: sha512-TeheYy0ILzBEI/CO55CP6zJCSdSWeRtGnHy8U8dWSUH4I68iqTsy7HkMktR4xakThc9jotkPQUXT4ITdbV7cHA==}
     engines: {node: '>=18'}
 
+  '@socket.io/component-emitter@3.1.2':
+    resolution: {integrity: sha512-9BCxFwvbGg/RsZK9tjXd8s4UcwR0MWeFQ1XEKIQVVvAGJyINdrqKMcTRyLoK8Rse1GjzLV9cwjWV1olXRWEXVA==}
+
   '@solid-primitives/event-listener@2.4.5':
     resolution: {integrity: sha512-nwRV558mIabl4yVAhZKY8cb6G+O1F0M6Z75ttTu5hk+SxdOnKSGj+eetDIu7Oax1P138ZdUU01qnBPR8rnxaEA==}
     peerDependencies:
@@ -5500,6 +5515,13 @@ packages:
   end-of-stream@1.4.5:
     resolution: {integrity: sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==}
 
+  engine.io-client@6.6.4:
+    resolution: {integrity: sha512-+kjUJnZGwzewFDw951CDWcwj35vMNf2fcj7xQWOctq1F2i1jkDdVvdFG9kM/BEChymCH36KgjnW0NsL58JYRxw==}
+
+  engine.io-parser@5.2.3:
+    resolution: {integrity: sha512-HqD3yTBfnBxIrbnM1DoD6Pcq8NECnh8d4As1Qgh0z5Gg3jRRIqijury0CL3ghu/edArpUYiYqQiDUQBIs4np3Q==}
+    engines: {node: '>=10.0.0'}
+
   enhanced-resolve@5.20.1:
     resolution: {integrity: sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==}
     engines: {node: '>=10.13.0'}
@@ -6624,6 +6646,9 @@ packages:
     resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
     hasBin: true
 
+  loro-crdt@1.10.8:
+    resolution: {integrity: sha512-GvH8fSJST1VDHRGzlQml80pBYoFbIP4ULeV1S8fD4ffmA8m+icoPORyVUW2AkJBY3dxKIcMMn0WqaJmpCmnbkQ==}
+
   loupe@3.2.1:
     resolution: {integrity: sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==}
 
@@ -7763,6 +7788,14 @@ packages:
     resolution: {integrity: sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==}
     engines: {node: '>= 18'}
 
+  socket.io-client@4.8.3:
+    resolution: {integrity: sha512-uP0bpjWrjQmUt5DTHq9RuoCBdFJF10cdX9X+a368j/Ft0wmaVgxlrjvK3kjvgCODOMMOz9lcaRzxmso0bTWZ/g==}
+    engines: {node: '>=10.0.0'}
+
+  socket.io-parser@4.2.6:
+    resolution: {integrity: sha512-asJqbVBDsBCJx0pTqw3WfesSY0iRX+2xzWEWzrpcH7L6fLzrhyF8WPI8UaeM4YCuDfpwA/cgsdugMsmtz8EJeg==}
+    engines: {node: '>=10.0.0'}
+
   solid-js@1.9.11:
     resolution: {integrity: sha512-WEJtcc5mkh/BnHA6Yrg4whlF8g6QwpmXXRg4P2ztPmcKeHHlH4+djYecBLhSpecZY2RRECXYUwIc/C2r3yzQ4Q==}
 
@@ -8490,6 +8523,18 @@ packages:
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
+  ws@8.18.3:
+    resolution: {integrity: sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
   ws@8.20.0:
     resolution: {integrity: sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==}
     engines: {node: '>=10.0.0'}
@@ -8518,6 +8563,10 @@ packages:
     resolution: {integrity: sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==}
     engines: {node: '>=8.0'}
 
+  xmlhttprequest-ssl@2.1.2:
+    resolution: {integrity: sha512-TEU+nJVUUnA4CYJFLvK5X9AOeH4KvDvhIfm0vV1GaQRtchnG0hgK5p8hw/xjv8cunWYCsiPCSDzObPyhEwq3KQ==}
+    engines: {node: '>=0.4.0'}
+
   yallist@3.1.1:
     resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
 
@@ -10902,6 +10951,8 @@ snapshots:
 
   '@sindresorhus/base62@1.0.0': {}
 
+  '@socket.io/component-emitter@3.1.2': {}
+
   '@solid-primitives/event-listener@2.4.5(solid-js@1.9.11)':
     dependencies:
       '@solid-primitives/utils': 6.4.0(solid-js@1.9.11)
@@ -12966,6 +13017,20 @@ snapshots:
     dependencies:
       once: 1.4.0
 
+  engine.io-client@6.6.4:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3(supports-color@8.1.1)
+      engine.io-parser: 5.2.3
+      ws: 8.18.3
+      xmlhttprequest-ssl: 2.1.2
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
+  engine.io-parser@5.2.3: {}
+
   enhanced-resolve@5.20.1:
     dependencies:
       graceful-fs: 4.2.11
@@ -14310,6 +14375,8 @@ snapshots:
     dependencies:
       js-tokens: 4.0.0
 
+  loro-crdt@1.10.8: {}
+
   loupe@3.2.1: {}
 
   lower-case@2.0.2:
@@ -16002,6 +16069,24 @@ snapshots:
 
   smol-toml@1.6.1: {}
 
+  socket.io-client@4.8.3:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3(supports-color@8.1.1)
+      engine.io-client: 6.6.4
+      socket.io-parser: 4.2.6
+    transitivePeerDependencies:
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
+  socket.io-parser@4.2.6:
+    dependencies:
+      '@socket.io/component-emitter': 3.1.2
+      debug: 4.4.3(supports-color@8.1.1)
+    transitivePeerDependencies:
+      - supports-color
+
   solid-js@1.9.11:
     dependencies:
       csstype: 3.2.3
@@ -16776,6 +16861,8 @@ snapshots:
 
   wrappy@1.0.2: {}
 
+  ws@8.18.3: {}
+
   ws@8.20.0: {}
 
   wsl-utils@0.1.0:
@@ -16791,6 +16878,8 @@ snapshots:
 
   xmlbuilder@15.1.1: {}
 
+  xmlhttprequest-ssl@2.1.2: {}
+
   yallist@3.1.1: {}
 
   yallist@5.0.0: {}

pnpm-workspace.yaml

@@ -142,6 +142,7 @@ catalog:
   ky: 2.0.0
   lamejs: 1.2.1
   lexical: 0.43.0
+  loro-crdt: 1.10.8
   mermaid: 11.14.0
   mime: 4.1.0
   mitt: 3.0.1
@@ -172,6 +173,7 @@ catalog:
   scheduler: 0.27.0
   sharp: 0.34.5
   shiki: 4.0.2
+  socket.io-client: 4.8.3
   sortablejs: 1.15.7
   std-semver: 1.0.8
   storybook: 10.3.5

web/.env.example

@@ -14,6 +14,8 @@ NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
 NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
 # When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1.
 NEXT_PUBLIC_COOKIE_DOMAIN=
+# WebSocket server URL.
+NEXT_PUBLIC_SOCKET_URL=ws://localhost:5001
 
 # Dev-only Hono proxy targets.
 # The frontend keeps requesting http://localhost:5001 directly,

web/__tests__/app/app-access-control-flow.test.tsx

@@ -1,3 +1,4 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import AppPublisher from '@/app/components/app/app-publisher'
@@ -23,6 +24,27 @@ let mockAppDetail: {
   }
 } | null = null
 
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  })
+
+const renderWithQueryClient = (ui: React.ReactElement) => {
+  const queryClient = createTestQueryClient()
+  return render(
+    <QueryClientProvider client={queryClient}>
+      {ui}
+    </QueryClientProvider>,
+  )
+}
+
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({
     t: (key: string, options?: { ns?: string }) => options?.ns ? `${options.ns}.${key}` : key,
@@ -76,6 +98,18 @@ vi.mock('@/app/components/app/overview/embedded', () => ({
   default: () => null,
 }))
 
+vi.mock('@/app/components/workflow/collaboration/core/websocket-manager', () => ({
+  webSocketClient: {
+    getSocket: vi.fn(() => null),
+  },
+}))
+
+vi.mock('@/app/components/workflow/collaboration/core/collaboration-manager', () => ({
+  collaborationManager: {
+    onAppPublishUpdate: vi.fn(() => vi.fn()),
+  },
+}))
+
 vi.mock('@/app/components/app/app-access-control', () => ({
   default: ({
     onConfirm,
@@ -115,7 +149,7 @@ describe('App Access Control Flow', () => {
   })
 
   it('refreshes app detail after confirming access control updates', async () => {
-    render(<AppPublisher publishedAt={1700000000} />)
+    renderWithQueryClient(<AppPublisher publishedAt={1700000000} />)
 
     fireEvent.click(screen.getByRole('button', { name: 'workflow.common.publish' }))
     fireEvent.click(screen.getByText('app.accessControlDialog.accessItems.specific'))

web/__tests__/app/app-publisher-flow.test.tsx

@@ -1,3 +1,4 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import AppPublisher from '@/app/components/app/app-publisher'
@@ -27,6 +28,27 @@ let mockAppDetail: {
   }
 } | null = null
 
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  })
+
+const renderWithQueryClient = (ui: React.ReactElement) => {
+  const queryClient = createTestQueryClient()
+  return render(
+    <QueryClientProvider client={queryClient}>
+      {ui}
+    </QueryClientProvider>,
+  )
+}
+
 vi.mock('react-i18next', () => ({
   useTranslation: () => ({
     t: (key: string) => key,
@@ -106,6 +128,18 @@ vi.mock('@/app/components/app/overview/embedded', () => ({
   ),
 }))
 
+vi.mock('@/app/components/workflow/collaboration/core/websocket-manager', () => ({
+  webSocketClient: {
+    getSocket: vi.fn(() => null),
+  },
+}))
+
+vi.mock('@/app/components/workflow/collaboration/core/collaboration-manager', () => ({
+  collaborationManager: {
+    onAppPublishUpdate: vi.fn(() => vi.fn()),
+  },
+}))
+
 vi.mock('@/app/components/app/app-access-control', () => ({
   default: () => <div data-testid="app-access-control" />,
 }))
@@ -183,7 +217,7 @@ describe('App Publisher Flow', () => {
   it('publishes from the summary panel and tracks the publish event', async () => {
     const onPublish = vi.fn().mockResolvedValue(undefined)
 
-    render(
+    renderWithQueryClient(
       <AppPublisher
         publishedAt={1700000000}
         onPublish={onPublish}
@@ -210,7 +244,7 @@ describe('App Publisher Flow', () => {
   })
 
   it('opens embedded modal and resolves the installed explore target', async () => {
-    render(<AppPublisher publishedAt={1700000000} />)
+    renderWithQueryClient(<AppPublisher publishedAt={1700000000} />)
 
     fireEvent.click(screen.getByText('common.publish'))
     fireEvent.click(screen.getByText('common.embedIntoSite'))
@@ -231,7 +265,7 @@ describe('App Publisher Flow', () => {
       installed_apps: [],
     })
 
-    render(<AppPublisher publishedAt={1700000000} />)
+    renderWithQueryClient(<AppPublisher publishedAt={1700000000} />)
 
     fireEvent.click(screen.getByText('common.publish'))
     fireEvent.click(screen.getByText('common.openInExplore'))

web/__tests__/apps/app-list-browsing-flow.test.tsx

@@ -93,6 +93,10 @@ vi.mock('@/service/tag', () => ({
   fetchTagList: vi.fn().mockResolvedValue([]),
 }))
 
+vi.mock('@/service/apps', () => ({
+  fetchWorkflowOnlineUsers: vi.fn().mockResolvedValue({}),
+}))
+
 vi.mock('@/service/use-apps', () => ({
   useInfiniteAppList: () => ({
     data: { pages: mockPages },

web/__tests__/apps/create-app-flow.test.tsx

@@ -80,6 +80,10 @@ vi.mock('@/service/tag', () => ({
   fetchTagList: vi.fn().mockResolvedValue([]),
 }))
 
+vi.mock('@/service/apps', () => ({
+  fetchWorkflowOnlineUsers: vi.fn().mockResolvedValue({}),
+}))
+
 vi.mock('@/service/use-apps', () => ({
   useInfiniteAppList: () => ({
     data: { pages: mockPages },

web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/card-view.tsx

@@ -5,7 +5,8 @@ import type { BlockEnum } from '@/app/components/workflow/types'
 import type { UpdateAppSiteCodeResponse } from '@/models/app'
 import type { App } from '@/types/app'
 import type { I18nKeysByPrefix } from '@/types/i18n'
-import { useCallback, useMemo } from 'react'
+import * as React from 'react'
+import { useCallback, useEffect, useMemo } from 'react'
 import { useTranslation } from 'react-i18next'
 import AppCard from '@/app/components/app/overview/app-card'
 import TriggerCard from '@/app/components/app/overview/trigger-card'
@@ -13,6 +14,8 @@ import { useStore as useAppStore } from '@/app/components/app/store'
 import Loading from '@/app/components/base/loading'
 import { toast } from '@/app/components/base/ui/toast'
 import MCPServiceCard from '@/app/components/tools/mcp/mcp-service-card'
+import { collaborationManager } from '@/app/components/workflow/collaboration/core/collaboration-manager'
+import { webSocketClient } from '@/app/components/workflow/collaboration/core/websocket-manager'
 import { isTriggerNode } from '@/app/components/workflow/types'
 import { NEED_REFRESH_APP_LIST_KEY } from '@/config'
 import {
@@ -72,25 +75,56 @@ const CardView: FC<ICardViewProps> = ({ appId, isInPanel, className }) => {
     ? buildTriggerModeMessage(t('mcp.server.title', { ns: 'tools' }))
     : null
 
-  const updateAppDetail = async () => {
+  const updateAppDetail = useCallback(async () => {
     try {
       const res = await fetchAppDetail({ url: '/apps', id: appId })
       setAppDetail({ ...res })
     }
-    catch (error) { console.error(error) }
-  }
+    catch (error) {
+      console.error(error)
+    }
+  }, [appId, setAppDetail])
 
   const handleCallbackResult = (err: Error | null, message?: I18nKeysByPrefix<'common', 'actionMsg.'>) => {
     const type = err ? 'error' : 'success'
 
     message ||= (type === 'success' ? 'modifiedSuccessfully' : 'modifiedUnsuccessfully')
 
-    if (type === 'success')
+    if (type === 'success') {
       updateAppDetail()
 
+      // Emit collaboration event to notify other clients of app state changes
+      const socket = webSocketClient.getSocket(appId)
+      if (socket) {
+        socket.emit('collaboration_event', {
+          type: 'app_state_update',
+          data: { timestamp: Date.now() },
+          timestamp: Date.now(),
+        })
+      }
+    }
+
     toast(t(`actionMsg.${message}`, { ns: 'common' }) as string, { type })
   }
 
+  // Listen for collaborative app state updates from other clients
+  useEffect(() => {
+    if (!appId)
+      return
+
+    const unsubscribe = collaborationManager.onAppStateUpdate(async () => {
+      try {
+        // Update app detail when other clients modify app state
+        await updateAppDetail()
+      }
+      catch (error) {
+        console.error('app state update failed:', error)
+      }
+    })
+
+    return unsubscribe
+  }, [appId, updateAppDetail])
+
   const onChangeSiteStatus = async (value: boolean) => {
     const [err] = await asyncRunSafe<App>(
       updateAppSiteStatus({

web/app/(commonLayout)/app/(appDetailLayout)/[appId]/overview/tracing/provider-config-modal.tsx

@@ -12,7 +12,6 @@ import {
   PortalToFollowElem,
   PortalToFollowElemContent,
 } from '@/app/components/base/portal-to-follow-elem'
-import { Button } from '@/app/components/base/ui/button'
 import {
   AlertDialog,
   AlertDialogActions,
@@ -22,6 +21,7 @@ import {
   AlertDialogDescription,
   AlertDialogTitle,
 } from '@/app/components/base/ui/alert-dialog'
+import { Button } from '@/app/components/base/ui/button'
 import { toast } from '@/app/components/base/ui/toast'
 import { addTracingConfig, removeTracingConfig, updateTracingConfig } from '@/service/apps'
 import { docURL } from './config'

web/app/components/app-sidebar/app-info/__tests__/use-app-info-actions.spec.ts

@@ -20,8 +20,11 @@ const mockUpdateAppInfo = vi.fn()
 const mockCopyApp = vi.fn()
 const mockExportAppConfig = vi.fn()
 const mockDeleteApp = vi.fn()
+const mockFetchAppDetail = vi.fn()
 const mockFetchWorkflowDraft = vi.fn()
 const mockDownloadBlob = vi.fn()
+const mockGetSocket = vi.fn()
+const mockOnAppMetaUpdate = vi.fn()
 
 let mockAppDetail: Record<string, unknown> | undefined = {
   id: 'app-1',
@@ -68,6 +71,7 @@ vi.mock('@/service/apps', () => ({
   copyApp: (...args: unknown[]) => mockCopyApp(...args),
   exportAppConfig: (...args: unknown[]) => mockExportAppConfig(...args),
   deleteApp: (...args: unknown[]) => mockDeleteApp(...args),
+  fetchAppDetail: (...args: unknown[]) => mockFetchAppDetail(...args),
 }))
 
 vi.mock('@/service/workflow', () => ({
@@ -82,6 +86,18 @@ vi.mock('@/utils/app-redirection', () => ({
   getRedirection: vi.fn(),
 }))
 
+vi.mock('@/app/components/workflow/collaboration/core/websocket-manager', () => ({
+  webSocketClient: {
+    getSocket: (...args: unknown[]) => mockGetSocket(...args),
+  },
+}))
+
+vi.mock('@/app/components/workflow/collaboration/core/collaboration-manager', () => ({
+  collaborationManager: {
+    onAppMetaUpdate: (...args: unknown[]) => mockOnAppMetaUpdate(...args),
+  },
+}))
+
 vi.mock('@/config', () => ({
   NEED_REFRESH_APP_LIST_KEY: 'test-refresh-key',
 }))
@@ -89,6 +105,8 @@ vi.mock('@/config', () => ({
 describe('useAppInfoActions', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    mockOnAppMetaUpdate.mockReturnValue(() => {})
+    mockGetSocket.mockReturnValue(null)
     mockAppDetail = {
       id: 'app-1',
       name: 'Test App',
@@ -191,6 +209,35 @@ describe('useAppInfoActions', () => {
       expect(toastMocks.call).toHaveBeenCalledWith({ type: 'success', message: 'app.editDone' })
     })
 
+    it('should emit app_meta_update after successful edit when collaboration socket exists', async () => {
+      const updatedApp = { ...mockAppDetail, name: 'Updated' }
+      const socket = { emit: vi.fn() }
+      mockUpdateAppInfo.mockResolvedValue(updatedApp)
+      mockGetSocket.mockReturnValue(socket)
+
+      const { result } = renderHook(() => useAppInfoActions({}))
+
+      await act(async () => {
+        await result.current.onEdit({
+          name: 'Updated',
+          icon_type: 'emoji',
+          icon: '🤖',
+          icon_background: '#fff',
+          description: '',
+          use_icon_as_answer_icon: false,
+        })
+      })
+      await new Promise(resolve => setTimeout(resolve, 0))
+
+      expect(mockGetSocket).toHaveBeenCalledWith('app-1')
+      expect(socket.emit).toHaveBeenCalledWith(
+        'collaboration_event',
+        expect.objectContaining({
+          type: 'app_meta_update',
+        }),
+      )
+    })
+
     it('should notify error on edit failure', async () => {
       mockUpdateAppInfo.mockRejectedValue(new Error('fail'))
 
@@ -502,4 +549,31 @@ describe('useAppInfoActions', () => {
       })
     })
   })
+
+  describe('collaboration app meta updates', () => {
+    it('should refresh app detail when receiving app_meta_update', async () => {
+      const updated = { ...mockAppDetail, name: 'Remote Updated' }
+      const unsubscribe = vi.fn()
+      let onUpdate: (() => Promise<void>) | undefined
+
+      mockOnAppMetaUpdate.mockImplementation((callback: () => Promise<void>) => {
+        onUpdate = callback
+        return unsubscribe
+      })
+      mockFetchAppDetail.mockResolvedValue(updated)
+
+      const { unmount } = renderHook(() => useAppInfoActions({}))
+      await new Promise(resolve => setTimeout(resolve, 0))
+
+      await act(async () => {
+        await onUpdate?.()
+      })
+
+      expect(mockFetchAppDetail).toHaveBeenCalledWith({ url: '/apps', id: 'app-1' })
+      expect(mockSetAppDetail).toHaveBeenCalledWith(updated)
+
+      unmount()
+      expect(unsubscribe).toHaveBeenCalled()
+    })
+  })
 })