synapse-orch-ai 0.1.0

package/backend/core/native_builder/orchestration.json

@@ -0,0 +1,515 @@
+{
+    "id": "orch_native_builder",
+    "name": "Synapse AI Builder",
+    "description": "Designs and creates agents and orchestrations through conversation, with a human approval gate before anything is written to disk.",
+    "avatar": "default",
+    "entry_step_id": "step_intent",
+    "state_schema": {
+        "user_message": {"type": "str", "default": "", "description": "The user's latest message"},
+        "chat_history": {"type": "str", "default": "", "description": "Prior conversation turns"},
+        "selected_agent_ids": {"type": "list", "default": [], "description": "Agent IDs the user pre-selected"},
+        "can_create_agents": {"type": "bool", "default": false, "description": "Whether the builder may create new agents"},
+        "current_orchestration_id": {"type": "str", "default": "", "description": "Orchestration currently being viewed or targeted for edit"},
+        "intent": {"type": "str", "default": "", "description": "Decision from the intent router: create or update"},
+        "existing_orch": {"type": "str", "default": "", "description": "Full JSON of the orchestration being updated (empty on create)"},
+        "requirements": {"type": "str", "default": "", "description": "Requirements spec OR one clarifying question from the analyst"},
+        "human_response": {"type": "str", "default": "", "description": "User's answer on a clarify loop-back"},
+        "plan_draft": {"type": "str", "default": "", "description": "Human-readable draft of the plan shown to the user for review"},
+        "review_feedback": {"type": "str", "default": "", "description": "User's approval text or revision feedback on the draft"},
+        "approval_decision": {"type": "str", "default": "", "description": "Router result: approved or revise"},
+        "agents_needed": {"type": "str", "default": "", "description": "Router result: yes if new sub-agents must be created, no otherwise"},
+        "created_agents": {"type": "str", "default": "", "description": "Role-to-agent-id mapping of agents created or reused for the plan"},
+        "save_decision": {"type": "str", "default": "", "description": "Router result: create or update — picks which saver agent runs"},
+        "final_orch": {"type": "dict", "default": {}, "description": "Result of the save tool call (create_orchestration or update_orchestration)"},
+        "summary": {"type": "str", "default": "", "description": "Friendly completion message generated after the orchestration is saved"}
+    },
+    "max_total_turns": 150,
+    "timeout_minutes": 45,
+    "trigger": "manual",
+    "steps": [
+        {
+            "id": "step_intent",
+            "name": "Route: Create vs Update",
+            "type": "evaluator",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {
+                "create": "step_understand",
+                "update": "step_fetch_existing"
+            },
+            "route_descriptions": {
+                "create": "Default path. Pick this for any NEW orchestration request, even when current_orchestration_id is set (viewing an orchestration is not editing it).",
+                "update": "Pick this ONLY when BOTH conditions hold: (a) current_orchestration_id is a non-empty string, AND (b) the user's latest message explicitly uses words like 'edit', 'update', 'modify', 'change', 'add to', 'remove from', or otherwise clearly refers to mutating that existing orchestration."
+            },
+            "evaluator_prompt": "Decide whether the user wants to CREATE a new orchestration or UPDATE the one they are currently viewing.\n\nLook at:\n- `current_orchestration_id`: if empty, always pick `create`.\n- `user_message`: explicit edit verbs ('edit', 'update', 'modify', 'change', 'rename', 'add a step', 'remove the X step', 'make it also do Y') with a reference to the current orchestration → `update`. Everything else → `create`.\n\nReturn exactly one of: create, update.",
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["user_message", "current_orchestration_id"],
+            "output_key": "intent",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 120,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 3,
+            "position_x": 0,
+            "position_y": 0
+        },
+        {
+            "id": "step_fetch_existing",
+            "name": "Fetch Existing Orchestration",
+            "type": "tool",
+            "agent_id": null,
+            "prompt_template": "Call `get_orchestration` with orch_id = \"{state.current_orchestration_id}\" so the downstream planner can see the current definition before drafting changes.",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["current_orchestration_id"],
+            "output_key": "existing_orch",
+            "forced_tool": "get_orchestration",
+            "max_turns": 3,
+            "timeout_seconds": 120,
+            "allowed_tools": null,
+            "next_step_id": "step_understand",
+            "max_iterations": 2,
+            "position_x": 300,
+            "position_y": 200
+        },
+        {
+            "id": "step_understand",
+            "name": "Understand Requirements",
+            "type": "agent",
+            "agent_id": "agent_native_builder_analyst",
+            "prompt_template": "Intent (already decided upstream): {state.intent}\n\nUser message: {state.user_message}\n\nChat history:\n{state.chat_history}\n\nPre-selected agent IDs: {state.selected_agent_ids}\nCan create new agents: {state.can_create_agents}\nCurrent orchestration ID (may be empty): {state.current_orchestration_id}\n\nExisting orchestration JSON (only populated on update):\n{state.existing_orch}\n\nLatest user clarification (empty on first pass):\n{state.human_response}\n\nProduce EITHER a complete requirements spec (prose, structured per your system prompt) OR one sharp clarifying question. Write it as your final response — it will be stored in the `requirements` state key, and a downstream evaluator decides whether to route to the planner or back to the user.",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["user_message", "chat_history", "selected_agent_ids", "can_create_agents", "current_orchestration_id", "intent", "existing_orch", "human_response"],
+            "output_key": "requirements",
+            "forced_tool": null,
+            "max_turns": 15,
+            "timeout_seconds": 600,
+            "allowed_tools": null,
+            "next_step_id": "step_clarify_route",
+            "max_iterations": 3,
+            "position_x": 600,
+            "position_y": 0
+        },
+        {
+            "id": "step_clarify_route",
+            "name": "Route: Clarify or Draft",
+            "type": "evaluator",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {
+                "clarify": "step_human_clarify",
+                "draft": "step_draft_plan"
+            },
+            "route_descriptions": {
+                "clarify": "The analyst asked a question instead of producing a spec — the `requirements` text reads like a question (interrogative phrasing, ends with '?', starts with 'What/Which/Should/How/Do you…').",
+                "draft": "The analyst produced a complete specification — the `requirements` text describes goal, inputs, step outline, agents, and output (not a question)."
+            },
+            "evaluator_prompt": "Read the `requirements` text. If it is a QUESTION directed at the user, pick `clarify`. If it is a structured SPECIFICATION (goal, inputs, steps, agents, output), pick `draft`. Return exactly one of: clarify, draft.",
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["requirements"],
+            "output_key": "clarify_decision",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 120,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 3,
+            "position_x": 900,
+            "position_y": 0
+        },
+        {
+            "id": "step_human_clarify",
+            "name": "Ask User for Clarification",
+            "type": "human",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": "{state.requirements}",
+            "human_fields": [
+                {"name": "answer", "type": "textarea", "label": "Your answer"}
+            ],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["requirements"],
+            "output_key": "human_response",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 3600,
+            "allowed_tools": null,
+            "next_step_id": "step_understand",
+            "max_iterations": 5,
+            "position_x": 900,
+            "position_y": 250
+        },
+        {
+            "id": "step_draft_plan",
+            "name": "Draft Plan",
+            "type": "llm",
+            "agent_id": null,
+            "prompt_template": "You are the Plan Drafter for the Synapse AI Builder. Produce a HUMAN-READABLE markdown draft of the orchestration plan. The user will read this next and either approve it or send revision feedback. After approval, a saver agent reads this draft to materialise the real orchestration JSON, so the draft must be precise enough to act on.\n\n# Inputs\nIntent: {state.intent}\n\nRequirements spec:\n{state.requirements}\n\nExisting orchestration (only on update; empty otherwise):\n{state.existing_orch}\n\nPre-selected agent IDs: {state.selected_agent_ids}\nCan create new agents: {state.can_create_agents}\n\nPrevious draft (empty on first pass):\n{state.plan_draft}\n\nUser's revision feedback on the previous draft (empty on first pass):\n{state.review_feedback}\n\n# Step-type palette (use these — never invent a type)\n{{STEP_TYPE_CHEATSHEET}}\n\n# What to write\nMarkdown with these sections, in this order:\n\n## Overview\nOne paragraph: what the orchestration does end-to-end. On update, call out what is changing vs the existing definition.\n\n## State schema\nBullet list of state keys with type and one-line purpose.\n\n## Steps\nNumbered list. For each step:\n- **Name** (step type: one of agent / llm / evaluator / human / parallel / merge / loop / transform / tool / end)\n- What it does, its input keys, its output key, and its next step (or route map for evaluators).\n- For agent steps: role name AND whether it maps to an existing agent (`agent_xxxxxxx`) or a NEW agent to create (describe its job + tools).\n- For tool steps: the forced tool name. If you are uncertain a tool exists, flag it under Open questions rather than guessing.\n- For human steps: the prompt the user will see and the fields collected.\n\n## Agents summary\nTwo short lists:\n- **Existing agents reused**: one line each — `role → agent_id (name)`.\n- **New agents to create**: one block per new agent. Each block uses this exact shape so the downstream Agent Creator can parse it deterministically:\n  - `role: <role_label>` — short identifier used elsewhere in the plan (e.g. `question_generator`).\n  - `name: <Display Name>` — what the agent will be called.\n  - `type: conversational | code | orchestrator` — pick `code` ONLY if the agent reads/writes a repo; pick `orchestrator` only if it runs a sub-orchestration; everything else is `conversational`.\n  - `purpose: <one sentence>` — what this agent does end-to-end.\n  - `tools: [tool_name, tool_name]` — narrow list, only what the role needs. Use real tool names (confirmed by the analyst via `get_tools_detail`). Never `[\"all\"]`.\n  - `repos: [repo_id, repo_id]` — real repo IDs from `list_repos`. Use `[]` for conversational agents that do not touch code.\n  - `db_configs: [db_id]` — real DB IDs from `list_db_configs`. Use `[]` if none.\n\n  (If `can_create_agents` is false, still list the blocks and add a `status: CANNOT CREATE — creation disabled` line so the user can enable it or pre-select an existing agent.)\n\n## Flow\nClose with a fenced code block tagged `flow` showing the wiring as ASCII. Use the role/step name (not a fabricated step_id) and label the type. Example shape:\n\n```flow\nintake (agent: analyst)\n    ↓\nroute (evaluator)\n    ├─ a → process (llm)\n    └─ b → fallback (human)\n         ↓\n       end (end)\n```\n\nKeep it scannable — one node per line, one arrow per edge, evaluator branches with `├─`/`└─`, convergence shown by sharing the next line. The user uses this diagram to sanity-check wiring before approval.\n\n## Open questions\nOnly include this section if something is genuinely ambiguous. One bullet per question.\n\n# Rules\n- Write plain markdown, no code fences around the whole thing (the `flow` block is the only fenced block).\n- If `review_feedback` is non-empty, treat the previous draft as a starting point and revise per the feedback — do not start from scratch unless the user asked you to.\n- Do NOT produce raw orchestration JSON here. This is the human-facing draft. The JSON is produced by the saver agent later.\n- Keep it concise — the user will read this.",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["intent", "requirements", "existing_orch", "selected_agent_ids", "can_create_agents", "plan_draft", "review_feedback"],
+            "output_key": "plan_draft",
+            "forced_tool": null,
+            "max_turns": 5,
+            "timeout_seconds": 600,
+            "allowed_tools": null,
+            "next_step_id": "step_human_review",
+            "max_iterations": 5,
+            "position_x": 1200,
+            "position_y": 0
+        },
+        {
+            "id": "step_human_review",
+            "name": "Review Plan",
+            "type": "human",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": "Here is the proposed plan. Reply **approve** (or 'ok' / 'looks good' / 'yes') to build it as-is, or describe the changes you want and it will be redrafted.\n\n---\n\n{state.plan_draft}",
+            "human_fields": [
+                {"name": "feedback", "type": "textarea", "label": "Approve or describe changes"}
+            ],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["plan_draft"],
+            "output_key": "review_feedback",
+            "forced_tool": null,
+            "max_turns": 1,
+            "timeout_seconds": 3600,
+            "allowed_tools": null,
+            "next_step_id": "step_approval_route",
+            "max_iterations": 5,
+            "position_x": 1500,
+            "position_y": 0
+        },
+        {
+            "id": "step_approval_route",
+            "name": "Route: Approved or Revise",
+            "type": "evaluator",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {
+                "approved": "step_agents_needed",
+                "revise": "step_draft_plan"
+            },
+            "route_descriptions": {
+                "approved": "The user accepted the draft. Short affirmative replies like 'approve', 'approved', 'ok', 'okay', 'yes', 'looks good', 'lgtm', 'go ahead', 'build it', 'proceed', 'sounds good', a thumbs-up, or any reply that does not request changes.",
+                "revise": "The user asked for changes — the reply contains concrete feedback, edits, or a different direction. If the reply mixes approval with a small tweak ('looks good, but also add X'), treat the tweak as revision and pick `revise`."
+            },
+            "evaluator_prompt": "Classify `review_feedback`. If it is clearly an approval with NO change requests, return `approved`. If it contains any change request, correction, or new requirement — even a minor one mixed with positive words — return `revise`. Return exactly one of: approved, revise.",
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["review_feedback"],
+            "output_key": "approval_decision",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 120,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 3,
+            "position_x": 1800,
+            "position_y": 0
+        },
+        {
+            "id": "step_agents_needed",
+            "name": "Route: Need New Agents?",
+            "type": "evaluator",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {
+                "yes": "step_create_agents",
+                "no": "step_save_route"
+            },
+            "route_descriptions": {
+                "yes": "The approved plan draft has a non-empty 'New agents to create' section AND `can_create_agents` is true — run the agent creator before saving.",
+                "no": "Either the plan reuses only existing agents, OR `can_create_agents` is false (in which case the saver will materialise the plan with whatever agents are available and surface a TODO for missing roles)."
+            },
+            "evaluator_prompt": "Inspect `plan_draft` for a 'New agents to create' section listing one or more new agents. If that section exists with at least one new agent AND `can_create_agents` is true, return `yes`. Otherwise return `no`. Return exactly one of: yes, no.",
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["plan_draft", "can_create_agents"],
+            "output_key": "agents_needed",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 120,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 3,
+            "position_x": 2100,
+            "position_y": 0
+        },
+        {
+            "id": "step_create_agents",
+            "name": "Create New Sub-Agents",
+            "type": "agent",
+            "agent_id": "agent_native_builder_agent_creator",
+            "prompt_template": "The approved plan draft below lists one or more NEW agents to create. Create each of them by calling `create_agent`, then write the full role → agent_id mapping (including pre-existing agents the draft references) into your final response. Follow your system prompt exactly.\n\nApproved plan draft:\n{state.plan_draft}\n\nPre-selected agent IDs (already exist — do not recreate): {state.selected_agent_ids}\nCan create new agents: {state.can_create_agents}",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["plan_draft", "selected_agent_ids", "can_create_agents"],
+            "output_key": "created_agents",
+            "forced_tool": null,
+            "max_turns": 20,
+            "timeout_seconds": 900,
+            "allowed_tools": null,
+            "next_step_id": "step_save_route",
+            "max_iterations": 2,
+            "position_x": 2400,
+            "position_y": 150
+        },
+        {
+            "id": "step_save_route",
+            "name": "Route: Create or Update Saver",
+            "type": "evaluator",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {
+                "create": "step_save_create",
+                "update": "step_save_update"
+            },
+            "route_descriptions": {
+                "create": "Intent is `create` — route to the create_orchestration saver.",
+                "update": "Intent is `update` — route to the update_orchestration saver."
+            },
+            "evaluator_prompt": "Return `state.intent` verbatim. Must be exactly one of: create, update.",
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["intent"],
+            "output_key": "save_decision",
+            "forced_tool": null,
+            "max_turns": 3,
+            "timeout_seconds": 60,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 3,
+            "position_x": 3000,
+            "position_y": 0
+        },
+        {
+            "id": "step_save_create",
+            "name": "Materialise & Save (create)",
+            "type": "agent",
+            "agent_id": "agent_native_builder_saver_create",
+            "prompt_template": "Approved plan draft (your source of truth — includes a `[flow]` diagram):\n{state.plan_draft}\n\nRole → agent_id mapping (empty if no new agents were created this run):\n{state.created_agents}\n\nPre-selected agent IDs (already exist — reuse where appropriate): {state.selected_agent_ids}",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["plan_draft", "created_agents", "selected_agent_ids"],
+            "output_key": "final_orch",
+            "forced_tool": null,
+            "max_turns": 30,
+            "timeout_seconds": 900,
+            "allowed_tools": null,
+            "next_step_id": "step_summarize",
+            "max_iterations": 3,
+            "position_x": 3300,
+            "position_y": -150
+        },
+        {
+            "id": "step_save_update",
+            "name": "Materialise & Save (update)",
+            "type": "agent",
+            "agent_id": "agent_native_builder_saver_update",
+            "prompt_template": "Target orchestration ID: {state.current_orchestration_id}\n\nExisting orchestration JSON (preserve untouched step IDs from here):\n{state.existing_orch}\n\nApproved plan draft describing the change (includes a `[flow]` diagram):\n{state.plan_draft}\n\nRole → agent_id mapping (empty if no new agents were created this run):\n{state.created_agents}",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["current_orchestration_id", "existing_orch", "plan_draft", "created_agents"],
+            "output_key": "final_orch",
+            "forced_tool": null,
+            "max_turns": 20,
+            "timeout_seconds": 600,
+            "allowed_tools": null,
+            "next_step_id": "step_summarize",
+            "max_iterations": 3,
+            "position_x": 3300,
+            "position_y": 150
+        },
+        {
+            "id": "step_summarize",
+            "name": "Summarise Result",
+            "type": "llm",
+            "agent_id": null,
+            "prompt_template": "The Synapse AI Builder has just finished. Here is the result:\n\n{state.final_orch}\n\nWrite a short, friendly 2–3 sentence confirmation for the user. Mention the orchestration name and ID. Say it is ready to use.",
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": ["final_orch"],
+            "output_key": "summary",
+            "forced_tool": null,
+            "max_turns": 1,
+            "timeout_seconds": 60,
+            "allowed_tools": null,
+            "next_step_id": "step_end",
+            "max_iterations": 1,
+            "position_x": 3600,
+            "position_y": 0
+        },
+        {
+            "id": "step_end",
+            "name": "End",
+            "type": "end",
+            "agent_id": null,
+            "prompt_template": null,
+            "route_map": {},
+            "route_descriptions": {},
+            "evaluator_prompt": null,
+            "model": null,
+            "parallel_branches": [],
+            "merge_strategy": "list",
+            "loop_count": 3,
+            "loop_step_ids": [],
+            "transform_code": null,
+            "human_prompt": null,
+            "human_fields": [],
+            "human_channel_id": null,
+            "human_timeout_seconds": 3600,
+            "input_keys": [],
+            "output_key": null,
+            "forced_tool": null,
+            "max_turns": 1,
+            "timeout_seconds": 60,
+            "allowed_tools": null,
+            "next_step_id": null,
+            "max_iterations": 1,
+            "position_x": 3600,
+            "position_y": 0
+        }
+    ]
+}

package/backend/core/native_builder/seed.py

@@ -0,0 +1,135 @@
+"""Idempotent seeding of the native builder orchestration and its sub-agents.
+
+Reads bundled JSON definitions from this package and merges any missing entries
+(by id) into data/user_agents.json and data/orchestrations.json.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_AGENTS_DIR = os.path.join(_HERE, "agents")
+_ORCH_FILE = os.path.join(_HERE, "orchestration.json")
+
+NATIVE_BUILDER_ORCH_ID = "orch_native_builder"
+NATIVE_BUILDER_AGENT_ID = "agent_native_builder"
+
+# Agent IDs that were shipped by earlier versions of the native builder and
+# should be purged on startup. Kept here so stale entries get cleaned up from
+# data/user_agents.json when users upgrade.
+LEGACY_BUILDER_AGENT_IDS: set[str] = {
+    "agent_native_builder_planner_create",
+    "agent_native_builder_planner_update",
+}
+
+
+def _load_json(path: str) -> Any:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _expand_cheatsheet(text: str) -> str:
+    # Imported lazily to avoid a circular import (this module is imported from __init__.py).
+    from . import STEP_TYPE_CHEATSHEET
+    if not isinstance(text, str):
+        return text
+    return text.replace("{{STEP_TYPE_CHEATSHEET}}", STEP_TYPE_CHEATSHEET)
+
+
+def _apply_cheatsheet_to_agent(agent: dict) -> dict:
+    sp = agent.get("system_prompt")
+    if isinstance(sp, str):
+        agent["system_prompt"] = _expand_cheatsheet(sp)
+    return agent
+
+
+def _apply_cheatsheet_to_orch(orch: dict) -> dict:
+    for step in orch.get("steps", []) or []:
+        pt = step.get("prompt_template")
+        if isinstance(pt, str):
+            step["prompt_template"] = _expand_cheatsheet(pt)
+    return orch
+
+
+def _load_bundled_agents() -> list[dict]:
+    if not os.path.isdir(_AGENTS_DIR):
+        return []
+    out: list[dict] = []
+    for name in sorted(os.listdir(_AGENTS_DIR)):
+        if name.endswith(".json"):
+            out.append(_apply_cheatsheet_to_agent(_load_json(os.path.join(_AGENTS_DIR, name))))
+    return out
+
+
+def _load_bundled_orchestration() -> dict:
+    return _apply_cheatsheet_to_orch(_load_json(_ORCH_FILE))
+
+
+def seed_native_builder() -> dict:
+    """Sync the builder orchestration and sub-agents from the bundled definitions.
+
+    Native-builder entries (ids starting with `agent_native_builder` / equal to
+    `orch_native_builder`) are always replaced with the bundled version so tool
+    list / prompt fixes propagate on restart. Other entries are left alone.
+
+    Returns: {"agents_added": [...], "agents_updated": [...], "agents_removed": [...], "orchestration": "added"|"updated"|"unchanged"}.
+    """
+    from core.routes.agents import load_user_agents, save_user_agents
+    from core.routes.orchestrations import load_orchestrations, save_orchestrations
+
+    bundled_agents = _load_bundled_agents()
+    bundled_orch = _load_bundled_orchestration()
+    bundled_agent_map = {a["id"]: a for a in bundled_agents}
+
+    existing_agents = load_user_agents()
+    agents_added: list[str] = []
+    agents_updated: list[str] = []
+    agents_removed: list[str] = []
+    seen_bundled_ids: set[str] = set()
+    new_agents: list[dict] = []
+    for a in existing_agents:
+        aid = a.get("id")
+        if aid in LEGACY_BUILDER_AGENT_IDS:
+            agents_removed.append(aid)
+            continue
+        if aid in bundled_agent_map:
+            bundled = bundled_agent_map[aid]
+            if a != bundled:
+                agents_updated.append(aid)
+            new_agents.append(bundled)
+            seen_bundled_ids.add(aid)
+        else:
+            new_agents.append(a)
+    for aid, bundled in bundled_agent_map.items():
+        if aid not in seen_bundled_ids:
+            new_agents.append(bundled)
+            agents_added.append(aid)
+    if agents_added or agents_updated or agents_removed:
+        save_user_agents(new_agents)
+
+    existing_orchs = load_orchestrations()
+    orch_status = "unchanged"
+    new_orchs: list[dict] = []
+    seen_orch = False
+    for o in existing_orchs:
+        if o.get("id") == bundled_orch["id"]:
+            seen_orch = True
+            if o != bundled_orch:
+                orch_status = "updated"
+            new_orchs.append(bundled_orch)
+        else:
+            new_orchs.append(o)
+    if not seen_orch:
+        new_orchs.append(bundled_orch)
+        orch_status = "added"
+    if orch_status != "unchanged":
+        save_orchestrations(new_orchs)
+
+    return {
+        "agents_added": agents_added,
+        "agents_updated": agents_updated,
+        "agents_removed": agents_removed,
+        "orchestration": orch_status,
+    }

package/backend/core/orchestration/__init__.py

@@ -0,0 +1,5 @@
+"""Multi-agent orchestration engine."""
+from .engine import OrchestrationEngine
+from .state import SharedState
+
+__all__ = ["OrchestrationEngine", "SharedState"]