workflow-exec-engine 0.0.2__py3-none-any.whl

workflow_engine/control/control_points.py

@@ -0,0 +1,223 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Control point interfaces -- user implements the decision layer.
+
+ControlPoint (workflow control -- drives the workflow forward):
+- on_task: send a task to an agent (user decides when/how)      [required]
+- on_self_task: handle a self-loop task locally                 [default]
+- on_route: choose a branch (user decides which path)           [required]
+- on_negotiation: supply clarification during Negotiation-T     [default]
+
+Authorization-T and Notification-T are pre-positioning concerns handled
+once before the workflow starts via ExtensionSender, not in-workflow
+callbacks. EventCallback is optional; instantiate directly as a no-op
+sink or subclass.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional, TYPE_CHECKING
+from loguru import logger
+
+if TYPE_CHECKING:
+    from workflow_engine.client.engine_client import WorkflowEngineClient
+from workflow_engine.core.models import (
+    TaskRequest, TaskResponse, RouteDecision, JumpCondition,
+)
+
+
+class EventType:
+    """Execution event types emitted by the SDK.
+
+    Values are stable strings, so direct string comparison
+    (``event_type == "step_start"``) also works.
+
+    These constants cover every event emitted across the three layers:
+    lifecycle (``START``/``COMPLETE``/``ERROR``/``CLOSE`` from the runner),
+    step/task execution (``STEP_*``/``TASK_*`` from the executor), agent
+    traffic (``AGENT_*`` from the engine client), and the A2A-T extension
+    handlers (``NEGOTIATION_*``/``AUTHORIZATION_*``/``NOTIFICATION``).
+    The executor also emits ``WORKFLOW_COMPLETE`` just before the runner
+    emits ``COMPLETE`` (or ``ERROR``); see the Developer Guide for the full
+    event ordering.
+    """
+    # Runner lifecycle (execute_psop)
+    START = "start"
+    COMPLETE = "complete"
+    CLOSE = "close"
+    # Step / task execution (WorkflowExecutor)
+    STEP_START = "step_start"
+    STEP_COMPLETE = "step_complete"
+    TASK_REQUEST = "task_request"
+    TASK_RESPONSE = "task_response"
+    TASK_STATUS_CHANGED = "task_status_changed"
+    ROUTE_DECISION = "route_decision"
+    WORKFLOW_COMPLETE = "workflow_complete"
+    # Agent traffic (WorkflowEngineClient)
+    AGENT_REQUEST = "agent_request"
+    AGENT_RESPONSE = "agent_response"
+    AGENT_STATUS_UPDATE = "agent_status_update"
+    AGENT_ARTIFACT_UPDATE = "agent_artifact_update"
+    AGENT_MESSAGE_EVENT = "agent_message_event"
+    # A2A-T extensions (negotiation / authorization / notification)
+    NEGOTIATION_REQUEST = "negotiation_request"
+    NEGOTIATION_RESOLVED = "negotiation_resolved"
+    NEGOTIATION_FAILED = "negotiation_failed"
+    AUTHORIZATION_REQUEST = "authorization_request"
+    AUTHORIZATION_RESOLVED = "authorization_resolved"
+    NOTIFICATION = "notification"
+    # Emitted by both the executor (step failure) and the runner (final
+    # failure). On failure you may see two "error" events with different
+    # data shapes -- see the Developer Guide.
+    ERROR = "error"
+
+
+class ControlPoint(ABC):
+    """Workflow-control decision interface.
+
+    Each method drives the workflow forward and is called by the
+    WorkflowExecutor (``on_task`` / ``on_self_task`` / ``on_route``) or the
+    client auto-negotiate loop (``on_negotiation``).
+    """
+
+    @abstractmethod
+    async def on_task(self, request: TaskRequest, engine_client: "WorkflowEngineClient") -> TaskResponse:
+        """Called when a step needs to send a task. User decides how to send.
+
+        ``request.message`` holds the full assembled message (upstream context
+        + task + language hint); ``request.context`` holds just the upstream
+        context. Call ``engine_client.send_message(request.agent_name,
+        request.message)`` to dispatch, or skip / transform as you see fit.
+        """
+        ...
+
+    async def on_self_task(self, request: TaskRequest) -> TaskResponse:
+        """Handle a self-loop task locally, WITHOUT sending an A2A-T message.
+
+        Called when a workflow step is marked ``SELF_LOOP``: the agent
+        executing the workflow processes the task itself. No
+        ``engine_client`` is passed on purpose: self-loop tasks must not
+        send A2A-T messages. Override to handle local aggregation, merge,
+        or any business logic the workflow-executing agent owns.
+
+        Default: echoes the task message back as the output.
+        """
+        return TaskResponse(success=True, output=request.message)
+
+    @abstractmethod
+    async def on_route(self, step_name: str, results: Dict[str, Any],
+                       conditions: List[JumpCondition]) -> RouteDecision:
+        """Called at a branch. User decides which branch to take.
+
+        ``conditions`` is the list of ``JumpCondition(step, condition)``
+        declared on the current step. Return a ``RouteDecision`` whose
+        ``next_step`` matches one of the conditions' step names. An invalid
+        ``next_step`` logs a warning and ends the workflow.
+        """
+        ...
+
+    async def on_negotiation(self, agent_name: str, negotiation_text: str,
+                             receive_result: Dict[str, Any]) -> str:
+        """Provide supplementary data when an agent returns INPUT_REQUIRED.
+
+        Return the clarification text -- the SDK internally resends the
+        follow-up message. Do NOT send messages here. The engine's
+        ``send_message`` auto-negotiation loop calls this method when an
+        agent returns INPUT_REQUIRED.
+
+        Default: returns a generic clarification.
+        """
+        return "Please proceed with the original task using available information."
+
+
+class NegotiationStrategy(ABC):
+    """Strategy for generating negotiation clarifications.
+
+    Single responsibility: when an agent returns INPUT_REQUIRED
+    (Negotiation-T), produce the clarification text to send back. This is a
+    separate concern from workflow orchestration (task dispatch, routing).
+    Users who need custom negotiation logic (LLM-based clarification, DAG-
+    predecessor forwarding, etc.) implement this interface and inject it
+    into DefaultControlPoint rather than mixing negotiation policy into
+    their ControlPoint class.
+    """
+
+    @abstractmethod
+    async def resolve(self, agent_name: str, negotiation_text: str,
+                      receive_result: Dict[str, Any]) -> str:
+        """Generate a clarification for the given negotiation request."""
+        ...
+
+
+class DefaultControlPoint(ControlPoint):
+    """Default ControlPoint with single-responsibility methods.
+
+    Negotiation-T auto-loop delegates to an injected NegotiationStrategy
+    (or returns a generic clarification if none is provided). Override
+    on_negotiation directly when a full strategy object is overkill.
+    """
+
+    def __init__(self, negotiation_strategy: Optional["NegotiationStrategy"] = None):
+        self._negotiation_strategy = negotiation_strategy
+
+    async def on_task(self, request: TaskRequest, engine_client: "WorkflowEngineClient") -> TaskResponse:
+        logger.info(f"[DefaultCP] onTask: agent={request.agent_name}, step={request.step_name}")
+        try:
+            result = await engine_client.send_message(request.agent_name, request.message)
+            success = bool(result.text)
+            logger.info(
+                f"[DefaultCP] Response from {request.agent_name}: "
+                f"{len(result.text or '')} chars, success={success}"
+            )
+            return TaskResponse(success=success, output=result.text or "")
+        except Exception as e:
+            logger.error(f"[DefaultCP] Task failed for {request.agent_name}: {e}")
+            return TaskResponse(success=False, error=f"Agent call failed: {e}")
+
+    async def on_self_task(self, request: TaskRequest) -> TaskResponse:
+        logger.info(f"[DefaultCP] onSelfTask: step={request.step_name}, agent={request.agent_name} (local, no A2A-T)")
+        return TaskResponse(success=True, output=request.message)
+
+    async def on_route(self, step_name: str, results: Dict[str, Any],
+                       conditions: List[JumpCondition]) -> RouteDecision:
+        next_step = conditions[0].step
+        for jc in conditions:
+            if jc.step not in ("end", "retry", "endNode"):
+                next_step = jc.step
+                break
+        logger.info(f"[DefaultCP] onRoute: {step_name} -> {next_step}")
+        return RouteDecision(next_step=next_step, reason="default: first non-terminal branch")
+
+    async def on_negotiation(self, agent_name: str, negotiation_text: str,
+                             receive_result: Dict[str, Any]) -> str:
+        if self._negotiation_strategy is not None:
+            return await self._negotiation_strategy.resolve(
+                agent_name, negotiation_text, receive_result)
+        logger.info(f"[DefaultCP] onNegotiation: agent={agent_name}, concern={negotiation_text}")
+        return "Please proceed with the original task using available information."
+
+
+class EventCallback:
+    """Optional callback for execution progress events.
+
+    Subclass and override ``on_event`` to receive events, or instantiate
+    directly as a no-op sink. Event types are listed in :class:`EventType`.
+    """
+
+    def on_event(self, event_type: str, data: Dict[str, Any]):
+        """Called for each execution event. Default: no-op."""
+        return None

workflow_engine/core/__init__.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from workflow_engine.core.models import (
+    Workflow, WorkflowStep, Task, JumpCondition,
+    StepType, TaskStatus, ExecutionResult,
+    SendMessageResult, TaskRequest, TaskResponse, RouteDecision,
+    WorkflowSearchResult,
+)
+from workflow_engine.core.context_builder import ContextBuilder
+from workflow_engine.core.executor import WorkflowExecutor
+
+__all__ = [
+    "Workflow", "WorkflowStep", "Task", "JumpCondition",
+    "StepType", "TaskStatus", "ExecutionResult",
+    "SendMessageResult", "TaskRequest", "TaskResponse", "RouteDecision",
+    "WorkflowSearchResult",
+    "ContextBuilder", "WorkflowExecutor",
+]

workflow_engine/core/context_builder.py

@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""Context assembly for the Workflow Execution SDK."""
+
+from collections import deque
+from typing import Dict, Any, List, Optional
+from loguru import logger
+
+from workflow_engine.core.models import Workflow, WorkflowStep
+
+
+class ContextBuilder:
+    def __init__(self, workflow: Workflow, runtime_intent: str = ""):
+        self.workflow = workflow
+        self.runtime_intent = runtime_intent
+        self._step_index = {s.name: i for i, s in enumerate(workflow.steps)}
+
+    def get_step_predecessors(self, step_name: str) -> List[str]:
+        predecessors = []
+        for s in self.workflow.steps:
+            if s.next:
+                for jc in s.next:
+                    if jc.step == step_name and s.name != step_name:
+                        predecessors.append(s.name)
+                        break
+        return predecessors
+
+    def get_all_predecessors(self, step_name: str) -> List[str]:
+        ancestors = set()
+        queue = deque([step_name])
+        while queue:
+            current = queue.popleft()
+            for s in self.workflow.steps:
+                if s.next:
+                    for jc in s.next:
+                        if jc.step == current and s.name != current and s.name not in ancestors:
+                            ancestors.add(s.name)
+                            queue.append(s.name)
+                            break
+        return list(ancestors)
+
+    def build_context(self, step: WorkflowStep, step_outputs: Dict[str, Dict[str, Any]]) -> str:
+        if step.layer <= 0:
+            if self.runtime_intent:
+                logger.info(f"[Context] Step {step.name}: layer 0, using runtime intent only")
+                return f"## Runtime Context\n\n{self.runtime_intent}"
+            logger.info(f"[Context] Step {step.name}: layer 0, no context")
+            return ""
+        parts = []
+        if self.runtime_intent:
+            parts.append(f"## Runtime Context\n\n{self.runtime_intent}")
+        parts.append("## Previous Step Execution Results\n")
+        if step.context_from and "*" in step.context_from:
+            all_pred = self.get_all_predecessors(step.name)
+            ref_pairs = [(n, step_outputs[n]) for n in all_pred if n in step_outputs]
+            logger.info(f"[Context] Step {step.name}: using ALL predecessors ({len(ref_pairs)} available)")
+        elif step.context_from:
+            ref_pairs = [(n, step_outputs[n]) for n in step.context_from if n in step_outputs]
+            logger.info(f"[Context] Step {step.name}: using context_from={step.context_from} ({len(ref_pairs)} available)")
+        else:
+            pred_names = self.get_step_predecessors(step.name)
+            ref_pairs = [(n, step_outputs[n]) for n in pred_names if n in step_outputs]
+            logger.info(f"[Context] Step {step.name}: using direct predecessors={pred_names} ({len(ref_pairs)} available)")
+        for ref_step_name, ref_results in ref_pairs:
+            parts.append(f"### {ref_step_name} Results\n")
+            for task_desc, output in ref_results.items():
+                text = output if isinstance(output, str) else str(output)
+                parts.append(f"**Task**: {task_desc}\n**Output**: {text}\n\n")
+        result = "\n".join(parts).strip()
+        logger.info(f"[Context] Step {step.name}: built context ({len(result)} chars)")
+        if result:
+            logger.info(f"[Context] Content:\n{result[:2000]}")
+        return result
+
+    def build_task_message(self, task_description: str, context_message: str, lang: str = "zh") -> str:
+        lang_hint = ""
+        if lang == "en":
+            lang_hint = "\n\nPlease respond in English."
+        elif lang == "zh":
+            lang_hint = "\n\n请用中文回复。"
+        if context_message:
+            return f"{context_message}\n\n## Current Task\n{task_description}{lang_hint}"
+        return f"{task_description}{lang_hint}"
+
+    def find_step_index(self, step_name: str) -> Optional[int]:
+        return self._step_index.get(step_name)

workflow_engine/core/executor.py

@@ -0,0 +1,278 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# All Rights Reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""WorkflowExecutor - DAG traversal, delegates to ControlPoint."""
+
+import asyncio
+import time
+from collections import deque
+from typing import Dict, Any, List, Optional, TYPE_CHECKING
+from loguru import logger
+
+from workflow_engine.core.models import (
+    Workflow, WorkflowStep, Task, StepType, TaskStatus,
+    ExecutionResult, TaskRequest, TaskResponse, RouteDecision,
+)
+from workflow_engine.core.context_builder import ContextBuilder
+from workflow_engine.control.control_points import ControlPoint, EventCallback
+
+if TYPE_CHECKING:
+    from workflow_engine.client.engine_client import WorkflowEngineClient
+
+
+class WorkflowExecutor:
+    """Main entry point.  Traverses DAG, calls ControlPoint at decision points."""
+
+    def __init__(
+        self,
+        workflow: Workflow,
+        control_point: ControlPoint,
+        engine_client: "WorkflowEngineClient",
+        event_callback: Optional[EventCallback] = None,
+        runtime_intent: str = "",
+        lang: str = "zh",
+    ):
+        self.workflow = workflow
+        self.control_point = control_point
+        self.engine_client = engine_client
+        self.engine_client.set_control_point(control_point)
+        try:
+            self.engine_client.set_event_callback(event_callback)
+        except Exception:
+            pass
+        self.event_callback = event_callback
+        self.lang = lang
+        self.context_builder = ContextBuilder(workflow, runtime_intent)
+        self.step_outputs: Dict[str, Dict[str, Any]] = {}
+        self.execution_history: List[Dict[str, Any]] = []
+        logger.info(f"[Executor] Workflow: {workflow.name}, steps={len(workflow.steps)}, intent={runtime_intent[:80] if runtime_intent else None}, lang={lang}")
+
+    def _emit_event(self, event_type: str, data: Dict[str, Any]):
+        if self.event_callback:
+            try:
+                self.event_callback.on_event(event_type, data)
+            except Exception as e:
+                logger.warning(f"Event callback error: {e}")
+
+    async def run(self) -> ExecutionResult:
+        """Execute the workflow DAG with parallel step dispatch.
+
+        Mirrors Java's executeSteps: collects all ready steps (predecessors
+        satisfied), dispatches them concurrently via asyncio.gather, then
+        processes their next-step indices. Steps at the same layer run in
+        parallel; subtasks within a step also run in parallel.
+        """
+        logger.info(f"[Executor] Starting workflow: {self.workflow.name} ({len(self.workflow.steps)} steps)")
+        pending = deque([
+            i for i, s in enumerate(self.workflow.steps)
+            if s.layer == 0 and not self.context_builder.get_step_predecessors(s.name)
+        ])
+        executed: set = set()
+        defer_count: Dict[int, int] = {}
+        failed = False
+        try:
+            while pending and not failed:
+                ready, deferred = self._collect_ready(pending, executed, defer_count)
+                for idx in deferred:
+                    pending.append(idx)
+                if not ready:
+                    if deferred:
+                        await asyncio.sleep(0.05)
+                        continue
+                    break
+                executed.update(ready)
+                results = await asyncio.gather(
+                    *[self._execute_step(idx) for idx in ready],
+                    return_exceptions=True,
+                )
+                failed = self._process_results(ready, results, pending, executed)
+        except Exception as e:
+            logger.critical(f"DAG traversal error: {e}", exc_info=True)
+            return ExecutionResult(success=False, history=self.execution_history,
+                                   step_outputs=self.step_outputs, error=str(e))
+        self._emit_event("workflow_complete", {})
+        logger.info(f"[Executor] Workflow completed: {self.workflow.name}, {len(self.execution_history)} task(s) executed")
+        return ExecutionResult(success=not failed, history=self.execution_history,
+                               step_outputs=self.step_outputs,
+                               error=("Step execution failed" if failed else None))
+
+    def _collect_ready(self, pending: deque, executed: set,
+                       defer_count: Dict[int, int]) -> tuple:
+        """Drain pending into ready (predecessors satisfied) and deferred."""
+        ready: List[int] = []
+        deferred: List[int] = []
+        while pending:
+            idx = pending.popleft()
+            if idx >= len(self.workflow.steps) or idx in executed:
+                continue
+            step = self.workflow.steps[idx]
+            predecessors = self.context_builder.get_step_predecessors(step.name)
+            if all(p in self.step_outputs for p in predecessors):
+                ready.append(idx)
+            else:
+                dc = defer_count.get(idx, 0) + 1
+                if dc > len(self.workflow.steps):
+                    executed.add(idx)
+                    continue
+                defer_count[idx] = dc
+                deferred.append(idx)
+        return ready, deferred
+
+    async def _execute_step(self, idx: int) -> tuple:
+        """Execute one step: subtasks + next-step determination.
+
+        Returns (step_name, step_result, success, next_indices).
+        """
+        step = self.workflow.steps[idx]
+        t_step = time.time()
+        logger.info(f"--- Executing step: {step.name} ---")
+        self._emit_event("step_start", {"step": step.name})
+        step_result, success = await self._execute_subtasks(step)
+        self.step_outputs[step.name] = step_result
+        next_indices: List[int] = []
+        if success:
+            self._emit_event("step_complete", {"step": step.name, "results": step_result})
+            next_indices = await self._determine_next_steps(step, step_result)
+        else:
+            logger.error(f"Step {step.name} failed, stopping.")
+            self._emit_event("error", {"step": step.name, "results": step_result})
+        logger.info(f"[Timing] Step '{step.name}' total: {time.time()-t_step:.2f}s, success={success}")
+        return step.name, step_result, success, next_indices
+
+    def _process_results(self, ready: List[int], results: list,
+                         pending: deque, executed: set) -> bool:
+        """Process asyncio.gather results, enqueue next steps. Returns failed."""
+        for idx, result in zip(ready, results):
+            if isinstance(result, Exception):
+                step = self.workflow.steps[idx]
+                logger.error(f"Step {step.name} raised: {result}")
+                self._emit_event("error", {"step": step.name, "error": str(result)})
+                return True
+            _, _, success, next_indices = result
+            if not success:
+                return True
+            for nxt in reversed(next_indices):
+                if nxt not in executed and nxt not in pending:
+                    pending.appendleft(nxt)
+        return False
+
+    async def _execute_subtasks(self, step: WorkflowStep) -> tuple[Dict[str, Any], bool]:
+        context_message = self.context_builder.build_context(step, self.step_outputs)
+        results: Dict[str, Any] = {}
+        logger.info(f"[Executor] Step {step.name}: {len(step.subtasks)} subtask(s), type={step.step_type.value}")
+
+        async def execute_single(task: Task, subtask_index: int) -> tuple[str, Any, bool]:
+            task_message = self.context_builder.build_task_message(task.description, context_message, self.lang)
+            request = TaskRequest(agent_name=task.agent, skill=task.skill, message=task_message,
+                                    description=task.description,
+                                    context=context_message, step_name=step.name, subtask_index=subtask_index)
+            self._emit_event("task_request", {"step": step.name, "agent": task.agent, "task": task.description})
+            logger.info(f"[Executor] Dispatching task: step={step.name}, agent={task.agent}, subtask_index={subtask_index}, desc={task.description}")
+            logger.debug(f"[Executor] Task message to {task.agent}: [{task_message}]")
+            t_task = time.time()
+            try:
+                # SELF_LOOP steps are handled locally without sending an
+                # A2A-T message (mirrors Java dispatchTask SELF_LOOP branch).
+                if step.step_type == StepType.SELF_LOOP:
+                    logger.info(f"[Executor] Self-loop task: step={step.name}, agent={task.agent} (local, no A2A-T)")
+                    response = await self.control_point.on_self_task(request)
+                else:
+                    response = await self.control_point.on_task(request, self.engine_client)
+                logger.info(f"[Timing] Task '{task.description}' -> {task.agent}: {time.time()-t_task:.2f}s")
+                task.status = TaskStatus.SUCCESS if response.success else TaskStatus.FAILED
+                self._emit_event("task_status_changed", {"step": step.name, "subtask_index": subtask_index, "agent": task.agent, "status": task.status.value})
+                status = "success" if response.success else "failed"
+                logger.info(f"[Executor] Task {task.description[:60]} -> {task.agent}: {status}")
+                if response.success and response.output:
+                    logger.debug(f"[Executor] Task output from {task.agent}: [{response.output}]")
+                self.execution_history.append({"step": step.name, "task": task.description, "agent": task.agent,
+                    "status": status,
+                    "output": response.output if response.success else (response.error or "")})
+                self._emit_event("task_response", {"step": step.name, "agent": task.agent, "task": task.description,
+                    "output": response.output if response.success else (response.error or "")})
+                return task.description, response.output, response.success
+            except Exception as e:
+                logger.info(f"[Timing] Task '{task.description}' -> {task.agent}: {time.time()-t_task:.2f}s (failed)")
+                task.status = TaskStatus.FAILED
+                self._emit_event("task_status_changed", {"step": step.name, "subtask_index": subtask_index, "agent": task.agent, "status": task.status.value})
+                logger.error(f"[Executor] Task {task.description[:60]} -> {task.agent}: exception: {e}")
+                self.execution_history.append({"step": step.name, "task": task.description, "agent": task.agent,
+                    "status": "failed", "output": str(e)})
+                return task.description, {"error": str(e)}, False
+
+        if step.step_type == StepType.ANY_SUCCESS:
+            tasks = [asyncio.create_task(execute_single(t, i)) for i, t in enumerate(step.subtasks)]
+            for coro in asyncio.as_completed(tasks):
+                desc, output, success = await coro
+                results[desc] = output
+                if success:
+                    logger.info(f"[Executor] Step {step.name}: ANY_SUCCESS, first success for task: {desc}")
+                    for t in tasks:
+                        if not t.done(): t.cancel()
+                    await asyncio.gather(*tasks, return_exceptions=True)
+                    return results, True
+            return results, False
+        gathered = await asyncio.gather(*[execute_single(t, i) for i, t in enumerate(step.subtasks)])
+        failed = False
+        for desc, output, success in gathered:
+            results[desc] = output
+            if not success: failed = True
+        return results, not failed
+
+    async def _determine_next_steps(self, step: WorkflowStep, step_result: Dict[str, Any]) -> List[int]:
+        if not step.next:
+            return []
+        # All-unconditional next steps -> fan out (parallel execution),
+        # skipping terminal markers. Mirrors the original engine's semantics:
+        # empty conditions mean "go to all of them", not "pick one".
+        if all(not jc.condition for jc in step.next):
+            indices = []
+            for jc in step.next:
+                if jc.step in ("end", "retry", "endNode"):
+                    continue
+                idx = self.context_builder.find_step_index(jc.step)
+                if idx is not None:
+                    indices.append(idx)
+            return indices
+        # Has conditional branches -> user decides via on_route.
+        # Build route context: merge context_from upstream results + current
+        # step results (mirrors Java's determineNextSteps routeContext).
+        route_context: Dict[str, Any] = {}
+        if step.context_from:
+            for ref in step.context_from:
+                if ref in self.step_outputs:
+                    route_context[ref] = self.step_outputs[ref]
+        route_context[step.name] = step_result
+        decision = await self.control_point.on_route(step.name, route_context, step.next)
+        logger.info(f"Route for '{step.name}': {decision.next_step} ({decision.reason})")
+        self._emit_event("route_decision", {"step": step.name, "next": decision.next_step, "reason": decision.reason})
+        idx = self.context_builder.find_step_index(decision.next_step)
+        if idx is None:
+            allowed = [jc.step for jc in step.next]
+            logger.warning(
+                f"on_route returned '{decision.next_step}' for step '{step.name}', "
+                f"not in allowed next steps {allowed}; workflow will end."
+            )
+        return [idx] if idx is not None else []
+
+
+    @property
+    def current_step_outputs(self) -> Dict[str, Dict[str, Any]]:
+        return self.step_outputs
+    @property
+    def history(self) -> List[Dict[str, Any]]:
+        return self.execution_history