Cugaflo

CLAUDE.md

@@ -0,0 +1,7 @@
+# Git
+
+Always include `[skip ci]` in every git commit message.
+
+# Environment
+
+If `cuga start` is not recognized, remind the user to run `source .venv/bin/activate` first.

docs/diagrams/cuga-flo-high-level-sequence.md

@@ -0,0 +1,113 @@
+# CUGA FLO — High-Level Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant FA as FlowAgent
+    participant TA as TaskAgent
+    participant DA as DecisionAgent
+    participant Bridge as MCPFlowBridge
+    participant WE as WorkflowEngine
+
+    rect rgb(230, 245, 255)
+        Note over App,WE: INVOCATION — FlowAgent triggers WorkflowEngine via MCPFlowBridge
+        App->>FA: invoke(input_data, process_variables)
+        FA->>Bridge: run_process(process_key, initial_inputs)
+        Note over Bridge,WE: WorkflowEngine exposes run_process to CUGA FLO
+        Bridge->>WE: _run_via_mcp(process_key, initial_inputs)
+    end
+
+    rect rgb(230, 255, 235)
+        Note over App,WE: EXECUTION — WorkflowEngine calls back into MCPFlowBridge
+
+        alt Task Node
+            Note over Bridge,WE: MCPFlowBridge exposes execute_task to WorkflowEngine
+            WE->>Bridge: execute_task(task_id, process state)
+            Bridge->>FA: _handle_task(task_id, process state)
+            FA->>TA: execute(state, task_input)
+            TA-->>FA: {status, output}
+            FA-->>Bridge: {process_variables, task_results}
+            Bridge-->>WE: task execution result
+
+        else Gateway Node
+            Note over Bridge,WE: MCPFlowBridge exposes route_gateway to WorkflowEngine
+            WE->>Bridge: route_gateway(gateway_id, process state)
+            Bridge->>FA: _handle_gateway(gateway_id, process state)
+            FA->>DA: route(available_flows, state)
+            DA-->>FA: chosen flow_id
+            FA-->>Bridge: flow_id
+            Bridge-->>WE: routing decision (flow_id)
+
+        else Hook Node
+            Note over Bridge,WE: MCPFlowBridge exposes evaluate_hook to WorkflowEngine
+            WE->>Bridge: evaluate_hook(hook_id, process state)
+            Bridge->>FA: _handle_hook(hook, process state)
+            FA-->>Bridge: HookResult {action, intervention details}
+            Bridge-->>WE: hook intervention
+        end
+
+    end
+
+    rect rgb(255, 245, 225)
+        Note over App,WE: COMPLETION
+        WE-->>Bridge: (FlowState, ProcessModel)
+        Bridge-->>FA: FlowState
+        FA-->>App: FlowState
+    end
+```
+
+---
+
+## MCP Service Contracts
+
+### Services MCPFlowBridge Exposes to WorkflowEngine
+
+| MCP Tool | Called by | Routed to | Input |
+|---|---|---|---|
+| `execute_task` | WorkflowEngine | FlowAgent → TaskAgent | `task_id`, `process state` |
+| `route_gateway` | WorkflowEngine | FlowAgent → DecisionAgent | `gateway_id`, `process state` |
+| `evaluate_hook` | WorkflowEngine | FlowAgent | `hook_id`, `process state` |
+
+### Service WorkflowEngine Exposes to CUGA FLO
+
+| MCP Tool | Called by | Handled by | Input |
+|---|---|---|---|
+| `run_process` | FlowAgent (via MCPFlowBridge) | WorkflowEngine | `process_key`, `initial_inputs` |
+
+---
+
+## CUGA FLO Service Results
+
+### `execute_task` → Result to WorkflowEngine
+
+| Field | Type | Description |
+|---|---|---|
+| `process_variables` | `Dict[str, Any]` | Updated process variables after output mapping |
+| `task_results` | `Dict[str, Dict]` | `{task_id: {status: "completed"\|"error", output: "...", error: "..."}}` |
+
+---
+
+### `route_gateway` → Routing Result to WorkflowEngine
+
+| Field | Type | Description |
+|---|---|---|
+| `flow_id` | `str` | The single chosen outgoing sequence flow ID (e.g., `"flow_approved"`) |
+
+DecisionAgent resolves the routing via a two-step internal graph:
+1. **eval_condition** — deterministic safe-string evaluation of `${var} op value` conditions
+2. **decide** — LLM (CugaAgent) reads evaluation result + gateway policy + state and returns exactly one `flow_id`
+
+---
+
+### `evaluate_hook` → Interventions Suggested to WorkflowEngine
+
+| `action` | Effect on WorkflowEngine | Additional Fields |
+|---|---|---|
+| `CONTINUE` | Proceed normally along the current edge | — |
+| `SKIP_NODE` | Skip the immediately next node | `message` |
+| `SKIP_TO` | Jump execution to a named node | `skip_to_node: str` |
+| `REQUEST_USER_INPUT` | Pause process and surface prompt to user | `user_prompt: str` |
+| `TERMINATE` | Halt the process immediately | `message` |
+| `SWAP_NODES` | Exchange two nodes in the current graph | `swap_nodes: (node_a, node_b)` |
+| `REMOVE_NODE` | Remove a node and rewire surrounding flows | `remove_node: str` |
+| `ADD_NODE` | Insert a new node before target (triggers graph rebuild) | `add_node: {node_id, task_instruction}` |

docs/diagrams/cuga-flo-lifecycle.md

@@ -0,0 +1,147 @@
+# CUGA FLO Lifecycle — Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Sup as Supervisor (CugaAgent)
+    participant Deleg as delegation.py
+    participant App as Application
+    participant SC as supervisor_config.py
+    participant FC as FlowConfig
+    participant FA as FlowAgent
+    participant Bridge as MCPFlowBridge
+    participant Reg as ProcessRegistry
+    participant Eng as LangGraphWorkflowEngine
+    participant FS as FlowState
+    participant TA as TaskAgent
+    participant DA as DecisionAgent
+
+    rect rgb(230, 240, 255)
+        Note over App,Reg: STARTUP
+        App->>App: cuga start flow_agent_inline<br/>sets DYNACONF_SUPERVISOR__CONFIG_PATH
+        App->>SC: load supervisor YAML
+        SC->>SC: finds agent entry with type: flow_agent
+        SC->>FC: load_flow_from_yaml(flow_config_path)
+        FC->>Bridge: <<create>> MCPFlowBridge(name="cuga-flo-bridge")
+        FC->>Reg: <<create>> ProcessRegistry(bridge)
+        Note right of Reg: Services: register_flow(config_path)<br/>get_bpmn_process(key), get_flow_annotations(key)<br/>list_keys()
+        Reg->>Bridge: register_registry(self)
+        Note right of Bridge: Registers MCP tools: register_flow, get_bpmn_process, get_flow_annotations<br/>Bridge holds internal Reg reference
+        FC->>Bridge: load_flow(config_path)
+        Bridge->>Reg: register_flow(config_path)
+        Note right of Reg: Parses YAML (tasks, gateways,<br/>hooks, policies, action_permissions)<br/>+ BPMN file via BPMNParser<br/>Stores FlowConfig + BPMNProcess in cache
+        FC->>FA: <<create>> FlowAgent(process_key, bridge)
+        FA->>Bridge: get_flow_annotations(process_key)
+        Bridge->>Reg: get_flow_annotations(process_key)
+        Reg-->>Bridge: FlowConfig
+        Bridge-->>FA: FlowConfig
+        loop per agentic task (mode: task_agent)
+            FA->>TA: <<create>> TaskAgent(task_id, CugaAgent(tools, system_instruction))
+        end
+        loop per decision gateway (mode: decision_agent)
+            FA->>DA: <<create>> DecisionAgent(gateway_id, policy, flow_decisions)
+        end
+        Note right of FA: Also builds task_instructions, task_policies<br/>hooks, action_permissions from FlowConfig
+        FA->>Bridge: register_flow_agent(self)
+        Note right of Bridge: Registers MCP tools:<br/>execute_task, route_gateway, evaluate_hook
+        FC->>Eng: <<create>> LangGraphWorkflowEngine(bridge)
+        Eng->>Bridge: register_engine(self)
+        Note right of Bridge: Registers MCP tool: run_process<br/>All tools backed by FastMCPTransport (in-process)
+    end
+
+    rect rgb(220, 235, 255)
+        Note over Sup,FA: SUPERVISOR DELEGATION (optional path)
+        Sup->>Deleg: create_agent_delegation_func(adapter, agent_name, flow_agent)
+        Note right of Deleg: agent_or_config is FlowAgent instance<br/>Detected via isinstance(agent_or_config, FlowAgent)
+        Sup->>Deleg: delegate_to_agent(task, variables)
+        Deleg->>FA: invoke(input_data=task, process_variables=vars_to_pass)
+        FA-->>Deleg: FlowState
+        Deleg->>Deleg: extract last message from FlowState.messages
+        Deleg-->>Sup: answer string
+    end
+
+    rect rgb(230, 255, 230)
+        Note over App,Eng: INVOCATION
+        App->>FA: invoke(input_data, process_variables)
+        Note right of FA: str input_data → initial_inputs["_user_message"]<br/>dict input_data → merged into initial_inputs
+        FA->>Bridge: run_process(process_key, initial_inputs)
+        Bridge->>Eng: _run_via_mcp(process_key, initial_inputs, mcp_server)
+        Eng->>Bridge: call_tool("get_bpmn_process", {process_key})
+        Bridge->>Reg: get_bpmn_process(process_key)
+        Reg-->>Bridge: BPMNProcess
+        Bridge-->>Eng: BPMNProcess dict → from_dict()
+        Eng->>Bridge: call_tool("get_flow_annotations", {process_key})
+        Bridge->>Reg: get_flow_annotations(process_key)
+        Reg-->>Bridge: FlowConfig.to_engine_config()
+        Bridge-->>Eng: {agentic_task_ids, decision_gateway_ids, task_instructions, hooks,<br/>flow_conditions, tool_tasks, action_permissions}
+        Note right of Eng: Builds _ControlOverlay with<br/>MCP-backed handlers for each<br/>task / gateway / hook
+        Eng->>FS: FlowState(process_id, process_variables)
+        Note right of Eng: Engine owns FlowState<br/>Compiles + begins StateGraph execution
+    end
+
+    rect rgb(255, 245, 220)
+        Note over Eng,TA: ENGINE EXECUTION — Agentic Task Node
+        Eng->>Eng: _create_task_node(task_id)
+        Note right of Eng: Builds ControlPointContext:<br/>current_state — engine-held FS<br/>execution_history — engine-held path<br/>process_model_summary — inspect_model()<br/>task_instruction — static config[task_id]
+        Eng->>Bridge: call_tool("execute_task", {task_id, ctx.to_dict()})
+        Bridge->>FA: _handle_task(task_id, ctx)
+        Note right of FA: WHO: self.task_agents[task_id]<br/>HOW: self.task_policies[task_id]<br/>WHAT: ctx.task_instruction (engine disclosed)
+        FA->>FA: _build_task_input(task_id, ctx)
+        Note right of FA: combines task_instruction + policy +<br/>user_msg + process_variables + task_results
+        FA->>TA: execute(ctx.current_state, task_input)
+        Note right of TA: _process_output applies output_mapping:<br/>parses JSON from LLM output<br/>calls state.set_process_variable(var, val)<br/>for each output_key → process_var mapping
+        TA-->>FA: task result dict (process_variables already updated in-place)
+        FA-->>Bridge: partial dict {execution_path, task_results, process_variables}
+        Bridge-->>Eng: result dict
+        Eng->>FS: merge partial dict via reducers
+    end
+
+    rect rgb(255, 235, 235)
+        Note over Eng,DA: ENGINE EXECUTION — Gateway Node (two paths)
+        Eng->>Eng: _create_gateway_node(gateway_id)
+        Note right of Eng: Builds ControlPointContext:<br/>available_flows — outgoing BPMNFlows with<br/>flow_conditions overlaid from static config<br/>current_state — engine-held FS
+
+        alt mode: decision_agent (overlay.gateway_handlers present)
+            Eng->>Bridge: call_tool("route_gateway", {gateway_id, ctx.to_dict()})
+            Bridge->>FA: _handle_gateway(gateway_id, ctx)
+            FA->>DA: route(ctx.available_flows, ctx.current_state)
+            Note right of DA: eval_condition → decide StateGraph<br/>LLM reads condition result + policy<br/>returns chosen flow_id
+            DA-->>FA: chosen flow_id
+            FA-->>Bridge: flow_id string
+            Bridge-->>Eng: flow_id
+        else mode: tool (merge / pass-through, no gateway handler)
+            Eng->>Eng: _tool_route_gateway(gateway_id, flows, state, overlay)
+            Note right of Eng: eval_condition on each outgoing flow<br/>Returns first matched flow_id<br/>No MCP round-trip — pure engine logic
+        end
+
+        Eng->>FS: gateway_decisions[gw_id] = flow_id
+        Note right of Eng: Routes conditional edge
+    end
+
+    rect rgb(245, 230, 255)
+        Note over Eng,FA: ENGINE EXECUTION — Hook Node (PRE_EDGE)
+        Eng->>Eng: _create_hook_node(edge_id, hook, normal_target, process, overlay)
+        Note right of Eng: Builds ControlPointContext:<br/>edge_id — intercepted flow ID<br/>current_state — engine-held FS<br/>execution_history — engine-held path<br/>(no task_instruction)
+        Note right of Eng: If hook.condition set and not met → skip,<br/>Command(goto=normal_target)
+        Eng->>Bridge: call_tool("evaluate_hook", {hook_id, ctx.to_dict()})
+        Bridge->>FA: _handle_hook(hook, ctx)
+        Note right of FA: Checks hook.condition against state<br/>If policy: _llm_hook_decision(hook, ctx)<br/>  → LLM reads policy + process_variables<br/>  → returns {action, target_node, state_updates}<br/>If handler: hook.handler(state)<br/>Returns HookResult
+        FA-->>Bridge: HookResult dict {action, skip_to_node, state_updates, ...}
+        Bridge-->>Eng: HookResult dict
+        Note right of Eng: Enforces action_permissions<br/>Applies state_updates to process_variables<br/>SKIP_TO → Command(goto=skip_to_node)<br/>CONTINUE → Command(goto=normal_target)
+    end
+
+    rect rgb(240, 255, 240)
+        Note over Eng,App: COMPLETION
+        Eng-->>Bridge: (FlowState, BPMNProcess)
+        Bridge-->>FA: {state: FlowState.model_dump(), bpmn: bpmn.to_dict()}
+        FA->>FS: FlowState.model_validate(result["state"])
+        Note right of FA: FA does NOT store FlowState<br/>Ready for next invoke() call
+        alt not is_halted
+            FA->>FS: mark_complete()
+        end
+        FA->>FA: _build_completion_message(final_state, BPMNProcess.from_dict(result["bpmn"]))
+        FA->>FS: messages.append(summary)
+        FA-->>App: FlowState
+    end
+```