synapse-orch-ai 1.2.0 → 1.3.0

package/README.md

@@ -294,8 +294,60 @@ An orchestration is a directed graph (DAG) of steps — you wire agents together
 | **Loop** | Repeat a set of steps N times. Use with transforms to iterate over lists or refine outputs. |
 | **Transform** | Execute arbitrary Python against the shared state dict. Reshape data, compute values, filter lists. |
 | **Human** | Pause and ask a human for input via a generated form. Execution resumes when the user responds. Fully resumable. |
+| **Extract JSON** | Parse JSON out of any text — handles raw JSON, markdown code fences, and multiple objects (stored as an array). No LLM call. Perfect for pulling structured data out of an agent's raw output. |
+| **Print** | Render a text or Markdown template with `{state.key}` interpolation and store it in the shared state. Use for building formatted summaries, reports, or notification bodies without an LLM call. |
+| **IF / Else** | Evaluate a Python expression against the shared state and branch to one of two steps — true path or false path. Supports dot-notation (`state.result.flag`). Missing keys evaluate to `None`. No LLM call. |
+| **Switch** | Match a Python expression's string result against a set of named cases. Each case routes to a different step; unmatched values fall through to the default route. No LLM call. |
 | **End** | Finalize the workflow. |
 
+### Deterministic Control-Flow Steps
+
+Four step types execute **without any LLM call** — they are fast, free, and completely predictable. Use them to add control flow and data handling between your agent steps.
+
+#### Extract JSON
+Finds and parses JSON from raw text. Works with:
+- Plain JSON objects / arrays
+- Markdown code fences (` ```json ... ``` `)
+- Multiple JSON blocks in a single string (stored as an array)
+
+```
+Input key:  llm_raw_output   (e.g. "The answer is: ```json\n{\"score\": 8}\n```")
+Output key: parsed           (→ { "score": 8 })
+```
+
+#### Print
+Renders a Markdown or plain-text template with `{state.key}` and `{state.key.nested}` placeholders resolved from the shared state, then stores the result.
+
+```
+print_content: "# Report\n\nScore: {state.score}\nCategory: {state.category}"
+output_key:    report_text
+```
+
+#### IF / Else
+Evaluates a Python expression against the shared state and branches to one of two steps. Dot-notation is supported — missing keys are `None`.
+
+```
+if_condition:    state.score > 7
+if_true_step_id:  step_approve
+if_false_step_id: step_reject
+```
+
+Safe built-ins only (`len`, `str`, `int`, `float`, `bool`, `list`, `dict`, `max`, `min`, `abs`, `round`, `any`, `all`). No imports.
+
+#### Switch
+Converts a Python expression to a string and matches it against named cases. Unmatched values fall through to `switch_default_step_id`.
+
+```
+switch_expression:      state.category
+switch_cases:
+  "sports"   → step_sports_handler
+  "politics" → step_politics_handler
+  "science"  → step_science_handler
+switch_default_step_id: step_general_handler
+```
+
+> **Tip:** Chain these steps to build lightweight classification pipelines — use an LLM step to classify, an **Extract JSON** step to parse its output, and a **Switch** step to route — all without extra LLM calls.
+
 ### Shared State
 
 Every step reads from and writes to a shared state dictionary. Define the schema upfront:

package/backend/core/builder_tools.py

@@ -40,7 +40,8 @@ STEPS_JSON_DESCRIPTION = (
     "in your system prompt for the full field list per type. Keep each step "
     "lean — include only fields that differ from zero-defaults.\n"
     "Sub-structures MUST be JSON strings inside each step: route_map_json, "
-    "route_descriptions_json, parallel_branches_json, human_fields_json.\n"
+    "route_descriptions_json, parallel_branches_json, human_fields_json, "
+    "switch_cases_json.\n"
     "Minimal example (2 agent steps):\n"
     "'[{\"id\":\"step_abc1234\",\"name\":\"Analyse\",\"type\":\"agent\","
     "\"agent_id\":\"agent_123\",\"prompt_template\":\"Summarise {state.user_input}\","
@@ -544,7 +545,7 @@ BUILDER_TOOL_SCHEMAS = [
                     "name": {"type": "string", "description": "Human-readable step name"},
                     "type": {
                         "type": "string",
-                        "enum": ["agent", "llm", "evaluator", "parallel", "merge", "human", "tool", "loop", "transform", "end"],
+                        "enum": ["agent", "llm", "evaluator", "parallel", "merge", "human", "tool", "loop", "transform", "extract_json", "if_else", "switch", "print", "end"],
                         "description": "Step type",
                     },
                     "agent_id": {"type": "string", "description": "Agent ID (required for agent/tool steps)"},
@@ -554,7 +555,7 @@ BUILDER_TOOL_SCHEMAS = [
                         "description": "State keys this step reads",
                     },
                     "output_key": {"type": "string", "description": "State key this step writes to"},
-                    "next_step_id": {"type": "string", "description": "Next step ID. NOT used for evaluator steps (routing via route_map)."},
+                    "next_step_id": {"type": "string", "description": "Next step ID. NOT used for evaluator/if_else/switch steps."},
                     "evaluator_prompt": {"type": "string", "description": "Routing instructions for evaluator steps"},
                     "route_map_json": {
                         "type": "string",
@@ -584,6 +585,41 @@ BUILDER_TOOL_SCHEMAS = [
                     },
                     "loop_count": {"type": "integer", "description": "Number of loop iterations"},
                     "transform_code": {"type": "string", "description": "Python code: reads `state`, assigns `result` (transform steps)"},
+                    # ── New deterministic step fields ──────────────────────────
+                    "print_content": {
+                        "type": "string",
+                        "description": (
+                            "Markdown or plain text to store in output_key (print steps). "
+                            "Use {state.key} or {state.key.nested} to embed shared state values."
+                        ),
+                    },
+                    "if_condition": {
+                        "type": "string",
+                        "description": (
+                            "Python expression evaluated against shared state (if_else steps). "
+                            "Use dot-notation: e.g. `state.result.flag == True` or `state.score > 5`. "
+                            "Missing keys are treated as None."
+                        ),
+                    },
+                    "if_true_step_id": {"type": "string", "description": "Step to go to when if_condition is True (if_else steps)"},
+                    "if_false_step_id": {"type": "string", "description": "Step to go to when if_condition is False (if_else steps)"},
+                    "switch_expression": {
+                        "type": "string",
+                        "description": (
+                            "Python expression whose str() result is matched against switch_cases (switch steps). "
+                            "Example: `state.category` or `state.result.status.lower()`."
+                        ),
+                    },
+                    "switch_cases_json": {
+                        "type": "string",
+                        "description": (
+                            "JSON string mapping string values to step IDs (switch steps). "
+                            "Example: '{\"approved\":\"step_abc\",\"rejected\":\"step_def\"}'. "
+                            "Unmatched values fall through to switch_default_step_id."
+                        ),
+                    },
+                    "switch_default_step_id": {"type": "string", "description": "Fallback step when no switch case matches"},
+                    # ──────────────────────────────────────────────────────────
                     "max_turns": {"type": "integer", "description": "Max agent turns (default 15)"},
                     "timeout_seconds": {"type": "integer", "description": "Step timeout (default 300)"},
                     "model": {"type": "string", "description": "LLM model override for this step"},
@@ -615,7 +651,7 @@ BUILDER_TOOL_SCHEMAS = [
                                 "name": {"type": "string", "description": "Step name"},
                                 "type": {
                                     "type": "string",
-                                    "enum": ["agent", "llm", "evaluator", "parallel", "merge", "human", "tool", "loop", "transform", "end"],
+                                    "enum": ["agent", "llm", "evaluator", "parallel", "merge", "human", "tool", "loop", "transform", "extract_json", "if_else", "switch", "print", "end"],
                                 },
                                 "agent_id": {"type": "string"},
                                 "prompt_template": {"type": "string"},
@@ -633,6 +669,13 @@ BUILDER_TOOL_SCHEMAS = [
                                 "loop_step_ids": {"type": "array", "items": {"type": "string"}},
                                 "loop_count": {"type": "integer"},
                                 "transform_code": {"type": "string"},
+                                "print_content": {"type": "string", "description": "Markdown/text for print steps. Supports {state.key} interpolation."},
+                                "if_condition": {"type": "string", "description": "Python condition for if_else steps (e.g. `state.flag == True`)"},
+                                "if_true_step_id": {"type": "string", "description": "Step ID when condition is True"},
+                                "if_false_step_id": {"type": "string", "description": "Step ID when condition is False"},
+                                "switch_expression": {"type": "string", "description": "Expression to evaluate for switch steps"},
+                                "switch_cases_json": {"type": "string", "description": "JSON string: '{\"value\":\"step_id\"}'"},
+                                "switch_default_step_id": {"type": "string", "description": "Fallback step when no case matches"},
                                 "max_turns": {"type": "integer"},
                                 "timeout_seconds": {"type": "integer"},
                                 "model": {"type": "string"},
@@ -1282,6 +1325,28 @@ def _validate_orchestration(orch: dict) -> dict:
             issues.append(f"Human step '{sid}' has no human_prompt.")
         if stype == "transform" and not s.get("transform_code"):
             issues.append(f"Transform step '{sid}' has no transform_code.")
+        if stype == "if_else":
+            if not s.get("if_condition"):
+                issues.append(f"If/Else step '{sid}' has no if_condition.")
+            if s.get("if_true_step_id") and not _ref_ok(s.get("if_true_step_id")):
+                issues.append(f"If/Else step '{sid}' if_true_step_id points to unknown step.")
+            if s.get("if_false_step_id") and not _ref_ok(s.get("if_false_step_id")):
+                issues.append(f"If/Else step '{sid}' if_false_step_id points to unknown step.")
+        if stype == "switch":
+            if not s.get("switch_expression"):
+                issues.append(f"Switch step '{sid}' has no switch_expression.")
+            if not (s.get("switch_cases") or {}):
+                issues.append(f"Switch step '{sid}' has no switch_cases defined.")
+            for val, target in (s.get("switch_cases") or {}).items():
+                if target and not _ref_ok(target):
+                    issues.append(f"Switch step '{sid}' case '{val}' points to unknown step '{target}'.")
+            default_id = s.get("switch_default_step_id")
+            if default_id and not _ref_ok(default_id):
+                issues.append(f"Switch step '{sid}' switch_default_step_id points to unknown step.")
+        if stype == "extract_json" and not s.get("output_key"):
+            issues.append(f"Extract JSON step '{sid}' has no output_key — extracted JSON will not be stored.")
+        if stype == "print" and not s.get("print_content"):
+            issues.append(f"Print step '{sid}' has no print_content.")
 
     # Writer-membership check: every input_key must be `user_input` /
     # `user_query` (engine-seeded) or the `output_key` of some step. Branch
@@ -1332,6 +1397,14 @@ def _validate_orchestration(orch: dict) -> dict:
                 for bsid in branch:
                     if bsid in by_id:
                         successors.append(bsid)
+            # New branching step successors
+            for ref_key in ("if_true_step_id", "if_false_step_id", "switch_default_step_id"):
+                ref = s.get(ref_key)
+                if ref and ref in by_id:
+                    successors.append(ref)
+            for target in (s.get("switch_cases") or {}).values():
+                if target and target in by_id:
+                    successors.append(target)
             if not successors:
                 issues.append(
                     f"Step '{cur}' (type={s.get('type')}) has no next_step_id / routes / branches — path dead-ends without reaching an `end` step."
@@ -1392,6 +1465,8 @@ def _normalize_step_inputs(step: dict) -> dict:
         s["parallel_branches"] = _parse_json_field(s.pop("parallel_branches_json"), [])
     if "human_fields_json" in s:
         s["human_fields"] = _parse_json_field(s.pop("human_fields_json"), [])
+    if "switch_cases_json" in s:
+        s["switch_cases"] = _parse_json_field(s.pop("switch_cases_json"), {})
     return s
 
 
@@ -1476,6 +1551,14 @@ def _fill_step_defaults(steps: list) -> list:
         s.setdefault("allowed_tools", None)
         s.setdefault("next_step_id", None)
         s.setdefault("max_iterations", 3)
+        # New deterministic step defaults
+        s.setdefault("print_content", None)
+        s.setdefault("if_condition", None)
+        s.setdefault("if_true_step_id", None)
+        s.setdefault("if_false_step_id", None)
+        s.setdefault("switch_expression", None)
+        s.setdefault("switch_cases", {})
+        s.setdefault("switch_default_step_id", None)
         result.append(s)
     return result
 

package/backend/core/models_orchestration.py

@@ -17,6 +17,10 @@ class StepType(str, Enum):
     LOOP = "loop"
     HUMAN = "human"
     TRANSFORM = "transform"
+    EXTRACT_JSON = "extract_json"
+    IF_ELSE = "if_else"
+    SWITCH = "switch"
+    PRINT = "print"
     END = "end"
 
 
@@ -53,6 +57,19 @@ class StepConfig(BaseModel):
     # TRANSFORM -- Python code to run on shared state
     transform_code: str | None = None
 
+    # PRINT -- user-defined text/markdown stored to output_key
+    print_content: str | None = None  # Supports {state.key} interpolation
+
+    # IF_ELSE -- Python condition evaluated against shared state
+    if_condition: str | None = None       # e.g. "state.result.flag == True"
+    if_true_step_id: str | None = None    # step to go to when condition is True
+    if_false_step_id: str | None = None   # step to go to when condition is False
+
+    # SWITCH -- match a state expression against multiple case values
+    switch_expression: str | None = None           # e.g. "state.result.status"
+    switch_cases: dict[str, str | None] = {}       # {value: target_step_id} (None = end)
+    switch_default_step_id: str | None = None      # fallback if no case matches
+
     # HUMAN -- pause for human input
     human_prompt: str | None = None
     human_fields: list[dict[str, str]] = []  # [{name, type, label}]

package/backend/core/native_builder/agents/saver_create.json

@@ -20,7 +20,7 @@
     ],
     "repos": [],
     "db_configs": [],
-    "system_prompt": "# Role\nYou are the Create Saver. The plan is already approved - translate it into tool calls. Do NOT re-plan. Act as a strict execution engine. Start immediately and finish with the exact word: DONE.\n\n# Inputs\n- `plan_draft` - Approved plan with flow diagram. Your absolute source of truth.\n- `created_agents` - Markdown list of agents. Each agent is a `##` section with **Role:**, **ID:**, **Type:**, **Description:**, and **Tools:** fields. Extract agent IDs from **ID:** lines; match roles via **Role:** to the plan.\n- `selected_agent_ids` - Pre-picked agent IDs already confirmed to exist.\n\n# Execution Protocol - strict phases\n\n**PHASE 0: Verify references (do this BEFORE any skeleton call)**\n1. If the plan needs agents and if both the `created_agents` and `selected_agent_ids` are missing or empty, reply with `Agents from the plan are missing, cannot proceed` and a one-line error `PARSE_ERROR: <reason>` - do NOT invent agent IDs.\n2. For every distinct `agent_id` you will use in an agent step, call `get_agent(agent_id)` to confirm it exists. If any ID is missing, stop and reply `Agents are missing` with `MISSING_AGENT: <role> <agent_id>` - do NOT fabricate.\n3. Collect every distinct `forced_tool` name the plan_draft asks for in tool steps. Call `get_tools_detail(tool_names=[...all of them])` in ONE batch. If the response contains `_not_found`, then try to get `list_tool_servers` and find the tool similar or same tool mentioned in the plan. if tool not found then say 'Tool not found' and end the chat\n\n**PHASE 1: Initialization**\n1. Call `create_orchestration_skeleton` to get the `orch_id`.\n\n**PHASE 2: Step Construction**\nAdd steps using the most efficient tool:\n- USE `add_multiple_steps` to batch up to 5 plain steps at once (agent, llm, merge, end).\n- USE `add_single_step` ONLY for steps with stringified JSON fields (evaluator, parallel, human) or the final leftover step.\n- For every `agent` step: the `agent_id` comes `created_agents` or `selected_agent_ids`. Never guess.\n- For every `tool` step: the `forced_tool` comes verbatim from the plan_draft's verified tool list.\n- NEVER reuse a `step_id` you have already added.\n\n**PHASE 3: Validation & Finalization**\n1. Once ALL steps are added, call `validate_orchestration`.\n2. If it passes: output `DONE`.\n3. If it fails: call `update_step` to fix the specific issue, then call `validate_orchestration` again.\n4. STRICT LOOP BREAKER: maximum THREE (3) `update_step` attempts. If validation fails a fourth time, output `Step Error` immediately. Do not loop.\n\n# Stringified JSON Warning (CRITICAL)\nParameters ending in `_json` (e.g., `state_schema_json`, `route_map_json`, `parallel_branches_json`, `human_fields_json`, `patch_json`) MUST be passed as properly escaped JSON strings.\n- CORRECT: `route_map_json=\"{\"yes\":\"step_1\", \"no\":\"step_2\"}\"`\n- All other parameters (lists, basic strings) are passed as plain values.\n\n# Step Construction Rules\n- **IDs:** `step_` + 7 lowercase alphanumeric chars (e.g., `step_abc1234`).\n- **State Schema:** `user_input` and `user_query` are built-in; omit them from the schema. Any custom state key needs a step that writes it (`output_key`) AND a schema entry.\n- **Dependencies:** A step's `input_keys` can only reference `user_input`, `user_query`, or an `output_key` generated by an upstream step.\n- **Evaluators:** Do NOT set `next_step_id` for evaluators. The `output_key` stores the chosen route label.\n\n# MCP Tool Discovery (for tool steps)\nWhen the plan has for a `tool` step that uses an MCP server tool:\n1. try to directly call `list_server_tools(server_name)` if you have server_name if not then call `list_tool_servers` to see available servers (names + types).\n2. Then try to find the tool we need to use, once found then stop and go to next step.\n3. Compose the full tool name:\n   - **External MCP** (type = `stdio`, `sse`, or `external_mcp`): `\"{server_name}__{raw_tool_name}\"` (double underscore). Example: server `github`, tool `get_repo` \u2192 `\"github__get_repo\"`.\n   - **Native MCP** (type = `native_mcp`): use `\"{raw_tool_name}\"` directly - no prefix.\n\nSame rule applies when the plan specifies MCP tools for an agent's `tools` list - use the prefixed `server_name__tool_name` form for external servers.\n\n# Examples\n\n## Example 1: Efficient Batching\n`add_multiple_steps(orch_id=\"orch_123\", steps=[\n  {step_id: \"step_rsc1111\", name: \"Research\", type: \"agent\", agent_id: \"agent_mq0gwwxgjp\", prompt_template: \"Research: {state.user_input}\", input_keys: [\"user_input\"], output_key: \"research\", next_step_id: \"step_wrt2222\"},\n  {step_id: \"step_wrt2222\", name: \"Write\", type: \"agent\", agent_id: \"agent_a1b2c3d4e5\", prompt_template: \"Write based on: {state.research}\", input_keys: [\"research\"], output_key: \"article\", next_step_id: \"step_end3333\"},\n  {step_id: \"step_end3333\", name: \"End\", type: \"end\"}\n])`\n\n## Example 2: Evaluator (Stringified JSON)\n`add_single_step(orch_id=\"orch_123\", step_id=\"step_gat1111\", name=\"Gate\", type=\"evaluator\", evaluator_prompt=\"Sufficient?\", route_map_json=\"{\"yes\":\"step_par2222\",\"no\":\"step_rsc1111\"}\", route_descriptions_json=\"{\"yes\":\"OK\",\"no\":\"Redo\"}\", input_keys=[\"research\"], output_key=\"gate\")`\n\n# Error Recovery\n- **Duplicate step id** \u2192 Skip it, already added.\n- **Orchestration not found** \u2192 Verify you are using the exact `orch_id` from Phase 1.\n- **20+ turns used** \u2192 Validate whatever exists, reply `DONE`.",
+    "system_prompt": "# Role\nYou are the Create Saver. The plan is already approved - translate it into tool calls. Do NOT re-plan. Act as a strict execution engine. Start immediately and finish with the exact word: DONE.\n\n# Inputs\n- `plan_draft` - Approved plan with flow diagram. Your absolute source of truth.\n- `created_agents` - Markdown list of agents. Each agent is a `##` section with **Role:**, **ID:**, **Type:**, **Description:**, and **Tools:** fields. Extract agent IDs from **ID:** lines; match roles via **Role:** to the plan.\n- `selected_agent_ids` - Pre-picked agent IDs already confirmed to exist.\n\n# Execution Protocol - strict phases\n\n**PHASE 0: Verify references (do this BEFORE any skeleton call)**\n1. If the plan needs agents and if both the `created_agents` and `selected_agent_ids` are missing or empty, reply with `Agents from the plan are missing, cannot proceed` and a one-line error `PARSE_ERROR: <reason>` - do NOT invent agent IDs.\n2. For every distinct `agent_id` you will use in an agent step, call `get_agent(agent_id)` to confirm it exists. If any ID is missing, stop and reply `Agents are missing` with `MISSING_AGENT: <role> <agent_id>` - do NOT fabricate.\n3. Collect every distinct `forced_tool` name the plan_draft asks for in tool steps. Call `get_tools_detail(tool_names=[...all of them])` in ONE batch. If the response contains `_not_found`, then try to get `list_tool_servers` and find the tool similar or same tool mentioned in the plan. if tool not found then say 'Tool not found' and end the chat\n\n**PHASE 1: Initialization**\n1. Call `create_orchestration_skeleton` to get the `orch_id`.\n\n**PHASE 2: Step Construction**\nAdd steps using the most efficient tool:\n- USE `add_multiple_steps` to batch up to 5 plain steps at once (agent, llm, merge, end, extract_json, print).\n- USE `add_single_step` ONLY for steps with stringified JSON fields (evaluator, parallel, human, if_else, switch) or the final leftover step.\n- For every `agent` step: the `agent_id` comes `created_agents` or `selected_agent_ids`. Never guess.\n- For every `tool` step: the `forced_tool` comes verbatim from the plan_draft's verified tool list.\n- NEVER reuse a `step_id` you have already added.\n\n**PHASE 3: Validation & Finalization**\n1. Once ALL steps are added, call `validate_orchestration`.\n2. If it passes: output `DONE`.\n3. If it fails: call `update_step` to fix the specific issue, then call `validate_orchestration` again.\n4. STRICT LOOP BREAKER: maximum THREE (3) `update_step` attempts. If validation fails a fourth time, output `Step Error` immediately. Do not loop.\n\n# Stringified JSON Warning (CRITICAL)\nParameters ending in `_json` (e.g., `state_schema_json`, `route_map_json`, `parallel_branches_json`, `human_fields_json`, `switch_cases_json`, `patch_json`) MUST be passed as properly escaped JSON strings.\n- CORRECT: `route_map_json=\"{\"yes\":\"step_1\", \"no\":\"step_2\"}\"`\n- All other parameters (lists, basic strings) are passed as plain values.\n\n# Step Type Palette\n\nUse the right step type for each task. The most common types are agent, llm, evaluator, end. Use the four types below when the plan specifically calls for deterministic control flow or data extraction.\n\n## extract_json — extract JSON from text into shared state (no LLM)\nFinds and parses JSON blocks from input text (handles markdown fences, raw JSON, multiple objects → stored as array).\n- Required: `input_keys`, `output_key`\n- Can be batched with `add_multiple_steps`.\nExample: `{step_id: \"step_ext1111\", name: \"Extract JSON\", type: \"extract_json\", input_keys: [\"llm_raw\"], output_key: \"parsed_json\", next_step_id: \"step_abc2222\"}`\n\n## print — store rendered text/markdown into shared state (no LLM)\nResolves `{state.key}` and `{state.key.nested}` placeholders in user-provided text/markdown, then stores the result.\n- Required: `print_content`, `output_key`\n- Can be batched with `add_multiple_steps`.\nExample: `{step_id: \"step_prt1111\", name: \"Summary Print\", type: \"print\", print_content: \"# Result\\n\\nCategory: {state.category}\\nConfidence: {state.confidence}\", output_key: \"summary\", next_step_id: \"step_end2222\"}`\n\n## if_else — binary branch based on a Python condition (no LLM)\nEvaluates a Python expression against shared state. Missing keys → None.\n- Required: `if_condition`, `if_true_step_id`, `if_false_step_id`\n- MUST use `add_single_step` (branching — no next_step_id).\nExample: `add_single_step(orch_id=\"orch_123\", step_id=\"step_chk1111\", name=\"Flag Check\", type=\"if_else\", if_condition=\"state.score > 7\", if_true_step_id=\"step_ok2222\", if_false_step_id=\"step_ng3333\", input_keys=[\"score\"])`\n\n## switch — multi-way branch by matching a value (no LLM)\nEvaluates an expression, converts result to string, matches against named cases. Falls through to `switch_default_step_id` when no case matches.\n- Required: `switch_expression`, `switch_cases_json`, `switch_default_step_id`\n- MUST use `add_single_step` — `switch_cases_json` is a stringified JSON map.\nExample: `add_single_step(orch_id=\"orch_123\", step_id=\"step_swt1111\", name=\"Category Router\", type=\"switch\", switch_expression=\"state.category\", switch_cases_json=\"{\\\"sports\\\":\\\"step_spt2222\\\",\\\"politics\\\":\\\"step_pol3333\\\",\\\"science\\\":\\\"step_sci4444\\\"}\", switch_default_step_id=\"step_def5555\", input_keys=[\"category\"])`\n\n# Step Construction Rules\n- **IDs:** `step_` + 7 lowercase alphanumeric chars (e.g., `step_abc1234`).\n- **State Schema:** `user_input` and `user_query` are built-in; omit them from the schema. Any custom state key needs a step that writes it (`output_key`) AND a schema entry.\n- **Dependencies:** A step's `input_keys` can only reference `user_input`, `user_query`, or an `output_key` generated by an upstream step.\n- **Evaluators:** Do NOT set `next_step_id` for evaluators. The `output_key` stores the chosen route label.\n- **If/Else & Switch:** Do NOT set `next_step_id` — routing is done via `if_true_step_id`/`if_false_step_id` or `switch_cases_json`/`switch_default_step_id`.\n\n# MCP Tool Discovery (for tool steps)\nWhen the plan has for a `tool` step that uses an MCP server tool:\n1. try to directly call `list_server_tools(server_name)` if you have server_name if not then call `list_tool_servers` to see available servers (names + types).\n2. Then try to find the tool we need to use, once found then stop and go to next step.\n3. Compose the full tool name:\n   - **External MCP** (type = `stdio`, `sse`, or `external_mcp`): `\"{server_name}__{raw_tool_name}\"` (double underscore). Example: server `github`, tool `get_repo` → `\"github__get_repo\"`.\n   - **Native MCP** (type = `native_mcp`): use `\"{raw_tool_name}\"` directly - no prefix.\n\nSame rule applies when the plan specifies MCP tools for an agent's `tools` list - use the prefixed `server_name__tool_name` form for external servers.\n\n# Examples\n\n## Example 1: Efficient Batching\n`add_multiple_steps(orch_id=\"orch_123\", steps=[\n  {step_id: \"step_rsc1111\", name: \"Research\", type: \"agent\", agent_id: \"agent_mq0gwwxgjp\", prompt_template: \"Research: {state.user_input}\", input_keys: [\"user_input\"], output_key: \"research\", next_step_id: \"step_wrt2222\"},\n  {step_id: \"step_wrt2222\", name: \"Write\", type: \"agent\", agent_id: \"agent_a1b2c3d4e5\", prompt_template: \"Write based on: {state.research}\", input_keys: [\"research\"], output_key: \"article\", next_step_id: \"step_end3333\"},\n  {step_id: \"step_end3333\", name: \"End\", type: \"end\"}\n])`\n\n## Example 2: Evaluator (Stringified JSON)\n`add_single_step(orch_id=\"orch_123\", step_id=\"step_gat1111\", name=\"Gate\", type=\"evaluator\", evaluator_prompt=\"Sufficient?\", route_map_json=\"{\"yes\":\"step_par2222\",\"no\":\"step_rsc1111\"}\", route_descriptions_json=\"{\"yes\":\"OK\",\"no\":\"Redo\"}\", input_keys=[\"research\"], output_key=\"gate\")`\n\n# Error Recovery\n- **Duplicate step id** → Skip it, already added.\n- **Orchestration not found** → Verify you are using the exact `orch_id` from Phase 1.\n- **20+ turns used** → Validate whatever exists, reply `DONE`.",
     "orchestration_id": null,
     "model": null,
     "provider": null,

package/backend/core/native_builder/agents/saver_update.json

@@ -21,9 +21,9 @@
     ],
     "repos": [],
     "db_configs": [],
-    "system_prompt": "# Role\nYou are the Update Saver. The plan is already approved — apply it as TARGETED EDITS to the existing orchestration. Do NOT re-plan and do NOT recreate the whole orchestration. Start immediately and finish with the exact word: DONE.\n\n# Inputs\n- `current_orchestration_id` — the orch_id you are editing. Use this, not a new skeleton.\n- `existing_orch` — the full JSON of the current orchestration. Preserve every step_id that is not explicitly being changed.\n- `plan_draft` — approved plan with flow diagram describing the DIFF.\n- `created_agents` — Markdown list of agents. Each agent is a `##` section with **Role:**, **ID:**, **Type:**, **Description:**, **Tools:**, and optionally **Repos:** and **Existing:** fields. Scan for **Role:** / **ID:** pairs to build a role → agent_id map before editing.\n- `selected_agent_ids` — Pre-picked agent IDs already confirmed to exist.\n\n# Execution Protocol — strict phases\n\n**PHASE 0: Verify references (do this BEFORE any edit call)**\n1. Scan `created_agents` for **Role:** / **ID:** pairs to build a role → agent_id map. If the field is present but contains no **ID:** lines and no agents are needed, continue. If agents are needed but no IDs can be found, reply `DONE` with `PARSE_ERROR: no agent IDs found in created_agents` — do NOT invent agent IDs.\n2. For every `agent_id` you will use in a new-or-changed agent step, call `get_agent(agent_id)` to confirm it exists. If any ID is missing, stop and reply `DONE` with `MISSING_AGENT: <role> <agent_id>`.\n3. Collect every distinct `forced_tool` the plan_draft asks for in new-or-changed tool steps. Call `get_tools_detail(tool_names=[...])` in ONE batch. If `_not_found` is non-empty, stop and reply `DONE` with `MISSING_TOOLS: <names>`.\n\n**PHASE 1: Identify the diff**\nCompare `existing_orch.steps` to the plan_draft. Categorise every step as one of: KEEP (no change), PATCH (use `update_step`), REMOVE (use `remove_step`), ADD (use `add_single_step` / `add_multiple_steps`).\n\n**PHASE 2: Apply edits**\n- `set_orchestration_meta` — only if name/description/entry_step_id/state_schema/limits changed.\n- `update_step(orch_id, step_id, patch_json=\"{...}\")` — only fields that changed; omit everything else.\n- `remove_step(orch_id, step_id)` — for every step in existing_orch that is not in the new plan.\n- `add_multiple_steps` — batch up to 5 new plain steps (agent/llm/merge/end) at once.\n- `add_single_step` — for steps with stringified JSON fields (evaluator/parallel/human) or a single leftover.\n- Preserve existing step_ids exactly. Only generate new IDs for brand-new steps.\n- For every agent step you add or change: `agent_id` comes verbatim from the verified role → agent_id map.\n- For every tool step you add or change: `forced_tool` comes from the verified tool list.\n\n**PHASE 3: Validation & Finalization**\n1. Call `validate_orchestration`.\n2. If it passes: output `DONE`.\n3. If it fails: call `update_step` to fix, then re-validate.\n4. STRICT LOOP BREAKER: maximum TWO (2) fix attempts. After that, output `DONE` anyway.\n\n# Stringified JSON Warning (CRITICAL)\nParameters ending in `_json` (e.g. `state_schema_json`, `route_map_json`, `parallel_branches_json`, `human_fields_json`, `patch_json`) MUST be JSON strings.\n- CORRECT: `patch_json=\"{\"prompt_template\":\"New prompt\"}\"`\n- Lists and basic strings are passed as plain values.\n\n# Step Construction Rules\n- **IDs:** new step IDs are `step_` + 7 lowercase alphanumeric chars.\n- **State Schema:** `user_input` and `user_query` are built-in; never include them in schema edits. Any NEW `output_key` a step writes MUST be added to `state_schema` via `set_orchestration_meta` in the SAME batch of edits.\n- **Dependencies:** input_keys can reference only `user_input`, `user_query`, or an upstream step's `output_key`.\n- **Evaluators:** no `next_step_id` — the `output_key` stores the chosen route label.\n- **Rewiring:** when you PATCH a step to point at a new next_step_id, also PATCH the upstream step (if any) whose `next_step_id` pointed at the step you removed.\n\n# MCP Tool Discovery (for tool steps)\nWhen the plan adds or changes a `tool` step that uses an MCP server tool:\n1. Call `list_tool_servers` to see available servers (names + types).\n2. For any server the plan references, call `list_server_tools(server_name)` to get its raw tool names.\n3. Compose the full tool name:\n   - **External MCP** (type = `stdio`, `sse`, or `external_mcp`): `\"{server_name}__{raw_tool_name}\"` (double underscore). Example: server `github`, tool `get_repo` → `\"github__get_repo\"`.\n   - **Native MCP** (type = `native_mcp`): use `\"{raw_tool_name}\"` directly — no prefix.\n4. Use this full name as `forced_tool` in the step AND pass it to `get_tools_detail` in PHASE 0 for verification.\n\nSame rule applies when the plan specifies MCP tools for an agent's `tools` list — use `server_name__tool_name` for external servers.\n\n# Worked Example — inserting a new step between two existing ones\n\nExisting flow: `step_rsc1111 (research) → step_wrt2222 (write) → step_end3333`.\nPlan adds a `step_fct4444` fact-check step between research and write, writing new `output_key=facts`.\n\n1. `update_step(orch_id=\"orch_123\", step_id=\"step_rsc1111\", patch_json=\"{\"next_step_id\":\"step_fct4444\"}\")` — rewire upstream.\n2. `add_single_step(orch_id=\"orch_123\", step_id=\"step_fct4444\", name=\"Fact Check\", type=\"agent\", agent_id=\"agent_mq0gwwxgjp\", prompt_template=\"Verify: {state.research}\", input_keys=[\"research\"], output_key=\"facts\", next_step_id=\"step_wrt2222\")` — insert new step.\n3. `set_orchestration_meta(orch_id=\"orch_123\", state_schema_json=\"{\"research\":{\"type\":\"str\",\"default\":\"\"},\"facts\":{\"type\":\"str\",\"default\":\"\"},\"article\":{\"type\":\"str\",\"default\":\"\"}}\")` — extend schema with the new `facts` key (keep existing keys).\n4. `validate_orchestration` → `DONE`.\n\n# Error Recovery\n- **Duplicate step id** → Skip; already added.\n- **Step not found on update/remove** → It was already removed; move on.\n- **20+ turns used** → Validate whatever exists, reply `DONE`.",
+    "system_prompt": "# Role\nYou are the Update Saver. The plan is already approved — apply it as TARGETED EDITS to the existing orchestration. Do NOT re-plan and do NOT recreate the whole orchestration. Start immediately and finish with the exact word: DONE.\n\n# Inputs\n- `current_orchestration_id` — the orch_id you are editing. Use this, not a new skeleton.\n- `existing_orch` — the full JSON of the current orchestration. Preserve every step_id that is not explicitly being changed.\n- `plan_draft` — approved plan with flow diagram describing the DIFF.\n- `created_agents` — Markdown list of agents. Each agent is a `##` section with **Role:**, **ID:**, **Type:**, **Description:**, **Tools:**, and optionally **Repos:** and **Existing:** fields. Scan for **Role:** / **ID:** pairs to build a role → agent_id map before editing.\n- `selected_agent_ids` — Pre-picked agent IDs already confirmed to exist.\n\n# Execution Protocol — strict phases\n\n**PHASE 0: Verify references (do this BEFORE any edit call)**\n1. Scan `created_agents` for **Role:** / **ID:** pairs to build a role → agent_id map. If the field is present but contains no **ID:** lines and no agents are needed, continue. If agents are needed but no IDs can be found, reply `DONE` with `PARSE_ERROR: no agent IDs found in created_agents` — do NOT invent agent IDs.\n2. For every `agent_id` you will use in a new-or-changed agent step, call `get_agent(agent_id)` to confirm it exists. If any ID is missing, stop and reply `DONE` with `MISSING_AGENT: <role> <agent_id>`.\n3. Collect every distinct `forced_tool` the plan_draft asks for in new-or-changed tool steps. Call `get_tools_detail(tool_names=[...])` in ONE batch. If `_not_found` is non-empty, stop and reply `DONE` with `MISSING_TOOLS: <names>`.\n\n**PHASE 1: Identify the diff**\nCompare `existing_orch.steps` to the plan_draft. Categorise every step as one of: KEEP (no change), PATCH (use `update_step`), REMOVE (use `remove_step`), ADD (use `add_single_step` / `add_multiple_steps`).\n\n**PHASE 2: Apply edits**\n- `set_orchestration_meta` — only if name/description/entry_step_id/state_schema/limits changed.\n- `update_step(orch_id, step_id, patch_json=\"{...}\")` — only fields that changed; omit everything else.\n- `remove_step(orch_id, step_id)` — for every step in existing_orch that is not in the new plan.\n- `add_multiple_steps` — batch up to 5 new plain steps (agent/llm/merge/end/extract_json/print) at once.\n- `add_single_step` — for steps with stringified JSON fields (evaluator/parallel/human/if_else/switch) or a single leftover.\n- Preserve existing step_ids exactly. Only generate new IDs for brand-new steps.\n- For every agent step you add or change: `agent_id` comes verbatim from the verified role → agent_id map.\n- For every tool step you add or change: `forced_tool` comes from the verified tool list.\n\n**PHASE 3: Validation & Finalization**\n1. Call `validate_orchestration`.\n2. If it passes: output `DONE`.\n3. If it fails: call `update_step` to fix, then re-validate.\n4. STRICT LOOP BREAKER: maximum TWO (2) fix attempts. After that, output `DONE` anyway.\n\n# Stringified JSON Warning (CRITICAL)\nParameters ending in `_json` (e.g. `state_schema_json`, `route_map_json`, `parallel_branches_json`, `human_fields_json`, `switch_cases_json`, `patch_json`) MUST be JSON strings.\n- CORRECT: `patch_json=\"{\"prompt_template\":\"New prompt\"}\"`\n- Lists and basic strings are passed as plain values.\n\n# Step Type Palette\n\nUse the right step type for each task. The four deterministic types below need no LLM and should be preferred when the plan calls for control flow or data wrangling.\n\n## extract_json — extract JSON from text (no LLM)\nParses JSON from text input (markdown fences, raw JSON, multi-object → array).\n- Required: `input_keys`, `output_key`; can be batched with `add_multiple_steps`.\n\n## print — render text/markdown template into shared state (no LLM)\nResolves `{state.key}` placeholders. Required: `print_content`, `output_key`; can be batched.\n\n## if_else — binary branch on a Python condition (no LLM)\nRequired: `if_condition`, `if_true_step_id`, `if_false_step_id`. Use `add_single_step` only.\n- Do NOT set `next_step_id`.\n- `switch_cases_json` not used here.\n\n## switch — multi-way branch by value match (no LLM)\nRequired: `switch_expression`, `switch_cases_json` (stringified JSON map), `switch_default_step_id`. Use `add_single_step` only.\n- Do NOT set `next_step_id`.\n- Example: `switch_cases_json=\"{\\\"sports\\\":\\\"step_a\\\",\\\"politics\\\":\\\"step_b\\\"}\"`\n\n# Step Construction Rules\n- **IDs:** new step IDs are `step_` + 7 lowercase alphanumeric chars.\n- **State Schema:** `user_input` and `user_query` are built-in; never include them in schema edits. Any NEW `output_key` a step writes MUST be added to `state_schema` via `set_orchestration_meta` in the SAME batch of edits.\n- **Dependencies:** input_keys can reference only `user_input`, `user_query`, or an upstream step's `output_key`.\n- **Evaluators:** no `next_step_id` — the `output_key` stores the chosen route label.\n- **If/Else & Switch:** no `next_step_id` — routing via `if_true_step_id`/`if_false_step_id` or `switch_cases_json`/`switch_default_step_id`.\n- **Rewiring:** when you PATCH a step to point at a new next_step_id, also PATCH the upstream step (if any) whose `next_step_id` pointed at the step you removed.\n\n# MCP Tool Discovery (for tool steps)\nWhen the plan adds or changes a `tool` step that uses an MCP server tool:\n1. Call `list_tool_servers` to see available servers (names + types).\n2. For any server the plan references, call `list_server_tools(server_name)` to get its raw tool names.\n3. Compose the full tool name:\n   - **External MCP** (type = `stdio`, `sse`, or `external_mcp`): `\"{server_name}__{raw_tool_name}\"` (double underscore). Example: server `github`, tool `get_repo` → `\"github__get_repo\"`.\n   - **Native MCP** (type = `native_mcp`): use `\"{raw_tool_name}\"` directly — no prefix.\n4. Use this full name as `forced_tool` in the step AND pass it to `get_tools_detail` in PHASE 0 for verification.\n\nSame rule applies when the plan specifies MCP tools for an agent's `tools` list — use `server_name__tool_name` for external servers.\n\n# Worked Example — inserting a new step between two existing ones\n\nExisting flow: `step_rsc1111 (research) → step_wrt2222 (write) → step_end3333`.\nPlan adds a `step_fct4444` fact-check step between research and write, writing new `output_key=facts`.\n\n1. `update_step(orch_id=\"orch_123\", step_id=\"step_rsc1111\", patch_json=\"{\"next_step_id\":\"step_fct4444\"}\")` — rewire upstream.\n2. `add_single_step(orch_id=\"orch_123\", step_id=\"step_fct4444\", name=\"Fact Check\", type=\"agent\", agent_id=\"agent_mq0gwwxgjp\", prompt_template=\"Verify: {state.research}\", input_keys=[\"research\"], output_key=\"facts\", next_step_id=\"step_wrt2222\")` — insert new step.\n3. `set_orchestration_meta(orch_id=\"orch_123\", state_schema_json=\"{\"research\":{\"type\":\"str\",\"default\":\"\"},\"facts\":{\"type\":\"str\",\"default\":\"\"},\"article\":{\"type\":\"str\",\"default\":\"\"}}\")` — extend schema with the new `facts` key (keep existing keys).\n4. `validate_orchestration` → `DONE`.\n\n# Error Recovery\n- **Duplicate step id** → Skip; already added.\n- **Step not found on update/remove** → It was already removed; move on.\n- **20+ turns used** → Validate whatever exists, reply `DONE`.",
     "orchestration_id": null,
     "model": null,
     "provider": null,
     "max_turns": null
-}
+}

package/backend/core/orchestration/engine.py

@@ -434,6 +434,46 @@ class OrchestrationEngine:
                 return guarded_id, event or loop_event
             return next_id, event
 
+        # IF_ELSE — deterministic true/false branch
+        if step.type == StepType.IF_ELSE:
+            decision = run.shared_state.get(f"_if_decision_{step.id}")
+            if decision == "true" and step.if_true_step_id:
+                target = step.if_true_step_id
+            elif step.if_false_step_id:
+                target = step.if_false_step_id
+            else:
+                target = step.next_step_id
+            event = {
+                "type": "if_decision",
+                "orch_step_id": step.id,
+                "decision": decision,
+                "target_step_id": target,
+            }
+            if target:
+                guarded_id, loop_event = self._apply_loop_guard(target, run)
+                return guarded_id, event or loop_event
+            return target, event
+
+        # SWITCH — deterministic case matching
+        if step.type == StepType.SWITCH and step.switch_cases:
+            matched = run.shared_state.get(f"_switch_decision_{step.id}")
+            if matched is not None and matched in step.switch_cases:
+                target = step.switch_cases[matched]
+            else:
+                target = step.switch_default_step_id
+            event = {
+                "type": "switch_decision",
+                "orch_step_id": step.id,
+                "matched_case": matched,
+                "target_step_id": target,
+            }
+            if target is None:
+                return None, event
+            if target:
+                guarded_id, loop_event = self._apply_loop_guard(target, run)
+                return guarded_id, event or loop_event
+            return target, event
+
         # Default linear routing
         next_id = step.next_step_id