synapse-orch-ai 0.1.0

package/backend/core/messaging/store.py

@@ -0,0 +1,95 @@
+"""
+JSON-backed persistent store for messaging channel configurations.
+Saved to DATA_DIR/messaging_channels.json.
+"""
+import json
+import os
+import time
+import uuid
+from typing import Optional
+
+from core.config import DATA_DIR
+
+CHANNELS_FILE = os.path.join(DATA_DIR, "messaging_channels.json")
+
+
+def _load_raw() -> list[dict]:
+    if not os.path.exists(CHANNELS_FILE):
+        return []
+    try:
+        with open(CHANNELS_FILE, "r") as f:
+            data = json.load(f)
+        return data if isinstance(data, list) else []
+    except Exception:
+        return []
+
+
+def _save_raw(data: list[dict]) -> None:
+    os.makedirs(DATA_DIR, exist_ok=True)
+    with open(CHANNELS_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+
+def list_channels() -> list[dict]:
+    """Return all channel configs."""
+    return _load_raw()
+
+
+def get_channel(channel_id: str) -> Optional[dict]:
+    """Return one channel by id, or None."""
+    return next((c for c in _load_raw() if c["id"] == channel_id), None)
+
+
+def get_channels_for_agent(agent_id: str) -> list[dict]:
+    """Return all channels bound to a specific agent."""
+    return [c for c in _load_raw() if c.get("agent_id") == agent_id]
+
+
+def save_channel(channel: dict) -> dict:
+    """Create or update a channel. Auto-assigns id and timestamps."""
+    data = _load_raw()
+    now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    if not channel.get("id"):
+        channel["id"] = f"chn_{uuid.uuid4().hex[:8]}"
+        channel["created_at"] = now
+
+    channel["updated_at"] = now
+    # Set defaults
+    channel.setdefault("status", "stopped")
+    channel.setdefault("last_error", None)
+    channel.setdefault("enabled", True)
+    channel.setdefault("multi_agent_mode", False)
+
+    idx = next((i for i, c in enumerate(data) if c["id"] == channel["id"]), None)
+    if idx is not None:
+        # Preserve runtime-only fields from existing record
+        existing = data[idx]
+        channel["created_at"] = existing.get("created_at", now)
+        data[idx] = channel
+    else:
+        data.append(channel)
+
+    _save_raw(data)
+    return channel
+
+
+def update_channel_status(channel_id: str, status: str, last_error: Optional[str] = None) -> None:
+    """Update only the runtime status fields (called by manager)."""
+    data = _load_raw()
+    for c in data:
+        if c["id"] == channel_id:
+            c["status"] = status
+            c["last_error"] = last_error
+            break
+    _save_raw(data)
+
+
+def delete_channel(channel_id: str) -> bool:
+    """Delete a channel by id. Returns True if found and removed."""
+    data = _load_raw()
+    new_data = [c for c in data if c["id"] != channel_id]
+    if len(new_data) == len(data):
+        return False
+    _save_raw(new_data)
+    return True

package/backend/core/models.py

@@ -0,0 +1,154 @@
+"""
+Pydantic models and data classes used across the backend.
+Extracted from server.py for better readability.
+"""
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel
+
+
+class ChatRequest(BaseModel):
+    message: str
+    # Client-generated ID for scoping short-term context. Frontend should generate a new
+    # one on each reload so each tab/reload is a fresh session.
+    session_id: str | None = None
+    # The active agent ID — sent by the frontend on every request so the backend
+    # doesn't rely on the global variable (which resets on uvicorn reload).
+    agent_id: str | None = None
+    # Optional ephemeral client-side state we want the server/agent to reuse.
+    client_state: dict[str, Any] | None = None
+    # Base64 data-URI images (e.g. "data:image/png;base64,..."). Max 5 per request.
+    images: list[str] = []
+
+class ChatResponse(BaseModel):
+    response: str
+    intent: str = "chat"
+    data: Any | None = None
+    tool_name: str | None = None
+
+
+class DBConfig(BaseModel):
+    id: str
+    name: str
+    db_type: str  # postgres, mysql, sqlite, mssql
+    connection_string: str
+    description: str = ""
+    schema_info: str = ""  # Cached schema summary (populated via refresh)
+    last_tested: str | None = None
+    status: str = "untested"  # untested | connected | error
+    error_message: str | None = None
+
+
+class Agent(BaseModel):
+    id: str
+    name: str
+    description: str
+    avatar: str = "default"
+    type: str = "conversational"  # conversational | analysis | code | orchestrator
+    tools: list[str] # ["all"] or ["search_codebase", "get_weather"]
+    repos: list[str] = [] # list of repo IDs for code agents
+    db_configs: list[str] = [] # list of db config IDs for code agents
+    system_prompt: str
+    orchestration_id: str | None = None  # for orchestrator type agents
+    model: str | None = None  # per-agent model override (None = use default)
+    provider: str | None = None  # auto-detected from model name
+    max_turns: int | None = None  # per-agent turn limit override (None = use global default of 30)
+
+class Repo(BaseModel):
+    id: str
+    name: str
+    path: str
+    description: str = ""
+    included_patterns: list[str] = ["*.py", "*.ts", "*.tsx", "*.js", "*.jsx", "*.rs", "*.go", "*.java", "*.md", "*.html", "*.vue", "*.css", "*.scss", "*.cpp", "*.c"]
+    excluded_patterns: list[str] = [".*", "node_modules", "__pycache__", "venv", ".git", "*.pyc"]
+    last_indexed: str | None = None
+    status: str = "pending" # pending | indexing | indexed | error
+    file_count: int = 0
+    embedding_model_provider: str = "gemini"
+    error_message: str | None = None
+
+class AgentActiveRequest(BaseModel):
+    agent_id: str
+
+
+class Settings(BaseModel):
+    agent_name: str
+    model: str = "mistral" # Default model (Ollama or Cloud)
+    mode: str = "local" # "local" | "cloud" | "bedrock"
+    openai_key: str = ""
+    anthropic_key: str = ""
+    gemini_key: str = ""
+    grok_key: str = ""  # xAI Grok API key (starts with 'xai-')
+    deepseek_key: str = ""  # DeepSeek API key
+    openai_compatible_key: str = ""  # API key for OpenAI-compatible cloud (OpenRouter, Together, etc.)
+    openai_compatible_base_url: str = ""  # Base URL for OpenAI-compatible cloud (e.g. https://openrouter.ai/api)
+    openai_compatible_models: str = ""  # Comma-separated model names for OpenAI-compatible cloud
+    local_compatible_base_url: str = ""  # Base URL for local v1-compatible (vLLM, LM Studio, etc.)
+    local_compatible_key: str = ""  # Optional API key for local v1-compatible
+    local_compatible_models: str = ""  # Comma-separated model names for local v1-compatible
+    openai_compatible_embed_models: str = ""  # Comma-separated embedding model names for OpenAI-compatible cloud
+    local_compatible_embed_models: str = ""  # Comma-separated embedding model names for local v1-compatible
+    bedrock_api_key: str = ""  # e.g. ABSK... (Amazon Bedrock API key)
+    # Optional: required for some Bedrock models that don't support on-demand throughput.
+    # Can be an inference profile ID or full ARN.
+    bedrock_inference_profile: str = ""
+    # Optional: embedding model used for long-term memory when mode == bedrock
+    embedding_model: str = ""
+    aws_access_key_id: str = ""
+    aws_secret_access_key: str = ""
+    aws_session_token: str = ""
+    aws_region: str = "us-east-1"
+    sql_connection_string: str = ""
+    n8n_url: str = "http://localhost:5678"
+    n8n_api_key: str = ""
+    n8n_table_id: str = ""
+    global_config: dict[str, str] = {}
+    vault_enabled: bool = True
+    vault_threshold: int = 100000
+    auto_compact_enabled: bool = False
+    auto_compact_threshold: int = 100000
+    allow_db_write: bool = False  # If False, only SELECT/SHOW/DESCRIBE queries allowed
+    embed_code: bool = False  # If False, search_codebase is disabled and postgres not required
+    bash_allowed_dirs: list[str] = []  # Extra dirs the bash tool can run commands in (repos + vault always included)
+    report_agent_enabled: bool = True
+    coding_agent_enabled: bool = True
+    messaging_enabled: bool = True
+
+
+class PersonalAddress(BaseModel):
+    address1: str = ""
+    address2: str = ""
+    city: str = ""
+    state: str = ""
+    zipcode: str = ""
+
+
+class PersonalDetails(BaseModel):
+    first_name: str = ""
+    last_name: str = ""
+    email: str = ""
+    phone_number: str = ""
+    address: PersonalAddress = PersonalAddress()
+
+
+class AddMCPServerRequest(BaseModel):
+    name: str
+    label: str = ""                # human-friendly display name (falls back to name if empty)
+    server_type: str = "stdio"     # "stdio" | "remote"
+    # stdio fields
+    command: str = ""
+    args: List[str] = []
+    env: Dict[str, str] = {}
+    # remote fields
+    url: str = ""
+    token: str = ""                # pre-auth bearer token (PAT); empty = start OAuth
+
+
+class GeneratePromptRequest(BaseModel):
+    description: str
+    agent_type: str = "conversational"
+    tools: list[str] = []
+    existing_prompt: str = ""
+
+
+class GoogleCredsRequest(BaseModel):
+    content: str # Raw JSON string or dict

package/backend/core/models_orchestration.py

@@ -0,0 +1,123 @@
+"""
+Pydantic models for the multi-agent orchestration system.
+Defines orchestrations (workflow graphs), steps (nodes), and run state.
+"""
+from typing import Any
+from enum import Enum
+from pydantic import BaseModel
+
+
+class StepType(str, Enum):
+    AGENT = "agent"
+    LLM = "llm"
+    TOOL = "tool"
+    EVALUATOR = "evaluator"
+    PARALLEL = "parallel"
+    MERGE = "merge"
+    LOOP = "loop"
+    HUMAN = "human"
+    TRANSFORM = "transform"
+    END = "end"
+
+
+class StepConfig(BaseModel):
+    """A single step (node) in an orchestration workflow graph."""
+    id: str
+    name: str
+    type: StepType
+
+    # AGENT / EVALUATOR -- which agent to invoke
+    agent_id: str | None = None
+    prompt_template: str | None = None  # Supports {state.key} references
+
+    # EVALUATOR -- outgoing routes as tools for the agent to call
+    # Maps decision label → target step_id (None = end orchestration)
+    route_map: dict[str, str | None] = {}
+    # Optional description per route — helps LLM understand when to pick each route
+    route_descriptions: dict[str, str] = {}
+    # Evaluator-specific prompt for the routing decision (separate from agent's prompt_template)
+    evaluator_prompt: str | None = None
+    # Per-step model override (especially useful for evaluators)
+    model: str | None = None
+
+    # PARALLEL -- each inner list is a sequential chain of step IDs
+    parallel_branches: list[list[str]] = []
+
+    # MERGE -- how to combine parallel outputs
+    merge_strategy: str = "list"  # "list" | "concat" | "dict"
+
+    # LOOP -- run body steps N times, then follow next_step_id (done path)
+    loop_count: int = 3
+    loop_step_ids: list[str] = []  # ordered steps in loop body
+
+    # TRANSFORM -- Python code to run on shared state
+    transform_code: str | None = None
+
+    # HUMAN -- pause for human input
+    human_prompt: str | None = None
+    human_fields: list[dict[str, str]] = []  # [{name, type, label}]
+    human_channel_id: str | None = None      # messaging channel to notify (optional)
+    human_timeout_seconds: int = 3600        # how long to wait for messaging response
+
+    # I/O mapping
+    input_keys: list[str] = []    # Keys to pull from shared state as context
+    output_key: str | None = None  # Key to write result into shared state
+
+    # TOOL — forced single tool call with ReAct retry
+    forced_tool: str | None = None  # Tool name for TOOL type steps
+
+    # Per-step guardrails
+    max_turns: int = 15
+    timeout_seconds: int = 300
+    allowed_tools: list[str] | None = None  # Override agent's tools (narrows only)
+
+    # Graph routing
+    next_step_id: str | None = None  # Linear next step / loop "done" path
+    max_iterations: int = 3  # Max times this step can execute in one run (loop guard)
+
+    # Visual canvas position (for @xyflow/react)
+    position_x: float = 0
+    position_y: float = 0
+
+
+class Orchestration(BaseModel):
+    """Top-level orchestration definition -- a workflow graph of steps."""
+    id: str
+    name: str
+    description: str = ""
+    avatar: str = "default"
+    steps: list[StepConfig] = []
+    entry_step_id: str = ""
+    state_schema: dict[str, Any] = {}  # {key: {type, default, description}}
+
+    # Global guardrails
+    max_total_turns: int = 100
+    max_total_cost_usd: float | None = None
+    timeout_minutes: int = 30
+
+    trigger: str = "manual"  # "manual" | "scheduled"
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class OrchestrationRun(BaseModel):
+    """A single execution instance of an orchestration."""
+    run_id: str
+    orchestration_id: str
+    session_id: str | None = None
+    status: str = "running"  # running | paused | completed | failed | cancelled
+    shared_state: dict[str, Any] = {}
+    step_history: list[dict[str, Any]] = []
+    current_step_id: str | None = None
+
+    # Human-in-the-loop
+    waiting_for_human: bool = False
+    human_prompt: str | None = None
+    human_fields: list[dict[str, str]] = []
+
+    # Cost tracking
+    total_tokens_used: int = 0
+    total_cost_usd: float = 0.0
+
+    started_at: str | None = None
+    ended_at: str | None = None

package/backend/core/models_schedule.py

@@ -0,0 +1,56 @@
+"""
+Pydantic models for the Schedules feature.
+"""
+from typing import Literal
+from pydantic import BaseModel
+
+
+class Schedule(BaseModel):
+    id: str
+    name: str
+    description: str = ""
+    enabled: bool = True
+    created_at: str
+    target_type: Literal["agent", "orchestration"]
+    target_id: str
+    prompt: str
+    schedule_type: Literal["interval", "cron"]
+    # Interval fields
+    interval_value: int | None = None
+    interval_unit: Literal["minutes", "hours", "days"] | None = None
+    # Cron fields
+    cron_expression: str | None = None
+    missed_run_policy: Literal["run_immediately", "skip"] = "skip"
+    # Server-computed state -- never trust client-provided values
+    last_run_at: str | None = None
+    next_run_at: str | None = None
+
+
+class ScheduleCreate(BaseModel):
+    name: str
+    description: str = ""
+    enabled: bool = True
+    target_type: Literal["agent", "orchestration"]
+    target_id: str
+    prompt: str
+    schedule_type: Literal["interval", "cron"]
+    # Interval fields
+    interval_value: int | None = None
+    interval_unit: Literal["minutes", "hours", "days"] | None = None
+    # Cron fields
+    cron_expression: str | None = None
+    missed_run_policy: Literal["run_immediately", "skip"] = "skip"
+
+
+class ScheduleUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+    enabled: bool | None = None
+    target_type: Literal["agent", "orchestration"] | None = None
+    target_id: str | None = None
+    prompt: str | None = None
+    schedule_type: Literal["interval", "cron"] | None = None
+    interval_value: int | None = None
+    interval_unit: Literal["minutes", "hours", "days"] | None = None
+    cron_expression: str | None = None
+    missed_run_policy: Literal["run_immediately", "skip"] | None = None

package/backend/core/native_builder/__init__.py

@@ -0,0 +1,60 @@
+"""
+Native Builder — Synapse's AI Builder implemented as a real orchestration.
+
+This package holds the seed JSON definitions (orchestration + sub-agents) and
+the idempotent seeding function used at startup. See seed.py.
+"""
+from .seed import seed_native_builder, NATIVE_BUILDER_ORCH_ID, NATIVE_BUILDER_AGENT_ID
+
+__all__ = [
+    "seed_native_builder",
+    "NATIVE_BUILDER_ORCH_ID",
+    "NATIVE_BUILDER_AGENT_ID",
+    "STEP_TYPE_CHEATSHEET",
+]
+
+
+# Shared step-type reference used by the plan drafter prompt AND the saver
+# agents' system prompts so the drafter's plan and the saver's materialised
+# JSON agree on the step palette.
+#
+# Fields listed per type are the ones that MUST be populated for that type
+# (beyond the common id/name/type/input_keys/output_key/next_step_id/
+# max_turns/timeout_seconds/max_iterations). Unlisted fields may be left at
+# their zero-defaults (`route_map: {}`, `parallel_branches: []`, etc.) so the
+# engine deserialises cleanly.
+STEP_TYPE_CHEATSHEET = """\
+- **agent**: runs a configured sub-agent with a prompt + its tool set. Required: `agent_id`, `prompt_template`. Use for any step that needs multi-turn reasoning or tool use.
+- **llm**: single one-shot LLM call, no tools. Required: `prompt_template` (optional `model`). Use for lightweight summarisation, rewriting, or deterministic prose generation.
+- **tool**: forces a single tool call with no LLM reasoning. Required: `forced_tool` (+ `agent_id` for tool-resolution). Use when the arguments are already in state and just need forwarding.
+- **evaluator**: pure routing node. Required: `route_map_json` (JSON-encoded `{label: target_step_id}`), `route_descriptions_json` (JSON), `evaluator_prompt`. Output_key stores the bare route label. Use to fork on a classifier decision.
+- **parallel**: runs multiple branches concurrently. Required: `parallel_branches_json` (JSON-encoded list of step-id lists), `next_step_id` (where they converge). Use when independent work can overlap.
+- **merge**: combines parallel-branch outputs. Required: `merge_strategy` (`concat` | `list` | `dict`). Place immediately after a parallel's convergence.
+- **loop**: runs a body N times. Required: `loop_step_ids` (ordered body), `loop_count`. Use for fixed repetition; for conditional loops use an evaluator that routes back.
+- **human**: pauses for user input. Required: `human_prompt`, `human_fields_json` (JSON-encoded list of `{name, type, label}`). Output_key stores the response dict.
+- **transform**: runs a snippet of Python against state. Required: `transform_code` — reads `state`, assigns to `result`. Use for pure-data reshapes; avoid heavy logic.
+- **end**: terminates the orchestration. No type-specific fields. Every flow must reach an `end` step.
+
+JSON-string fields (the saver's tool schemas accept these as JSON-encoded strings — Gemini hangs on open objects, so these are passed as strings and parsed server-side):
+- `route_map_json` → object mapping decision label → target step_id. Empty string ends that branch. Example: `'{"approved":"step_abc1234","denied":""}'`
+- `route_descriptions_json` → object mapping label → short classifier hint. Example: `'{"approved":"User accepts the draft"}'`
+- `parallel_branches_json` → array of arrays of step ids. Example: `'[["step_a","step_b"],["step_c"]]'`
+- `human_fields_json` → array of `{name, type, label}` objects. Example: `'[{"name":"approved","type":"boolean","label":"Approve?"}]'`
+- `state_schema_json` (orchestration-level) → object mapping key → `{type, default, description}`. Allowed types: str, int, float, bool, list, dict. Example: `'{"user_input":{"type":"str","default":"","description":"Initial message"}}'`
+
+Wiring rules that apply to every step:
+- `id` format: `step_` + 7 lowercase-alphanumeric chars, unique within the orchestration.
+- `output_key` of an upstream step must appear in the `input_keys` of any downstream step that reads it.
+- `entry_step_id` at the orchestration level must match the first step actually executed.
+- Agents are referenced by their real `agent_xxxxxxx` ID — never invent one.
+- For tool steps, confirm the tool exists via `get_tools_detail` before naming it in `forced_tool`.
+
+State lifecycle rules (CRITICAL — think of state keys as step outputs):
+- `user_input` and `user_query` are ALWAYS pre-populated with the user's initial message before any step runs. Use either freely in `input_keys` or `{state.user_input}` / `{state.user_query}` in `prompt_template`.
+- Every other state key enters state via exactly one mechanism: some step's `output_key` writes it. Keys that no step writes are meaningless — they can only ever be their schema default.
+- HARD RULE: a key may appear in a step's `input_keys` (or be referenced as `{state.X}` in a prompt) only if ONE of these holds:
+  (a) X is `user_input` or `user_query`, OR
+  (b) Some step in the orchestration has `output_key: X`.
+- Branch conditioning is NOT the validator's concern. If a key's producer sits on one branch and a downstream step on another branch still reads it, that's fine — the engine falls back to the schema default on unset reads. Iterative refinement loops (first pass reads the default, subsequent passes read real data) are first-class patterns.
+- When designing `state_schema`, for each declared key you must be able to name the single step whose `output_key` writes it. If you cannot name the writer, delete the key — don't declare or read phantom keys.
+"""

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

@@ -0,0 +1,20 @@
+{
+    "id": "agent_native_builder_agent_creator",
+    "name": "Builder — Agent Creator",
+    "description": "Creates the sub-agents referenced by an approved plan draft.",
+    "avatar": "default",
+    "type": "conversational",
+    "tools": [
+        "list_agents",
+        "get_agent",
+        "create_agent",
+        "create_agents",
+        "get_tools_detail",
+        "list_tool_servers",
+        "list_server_tools",
+        "list_repos"
+    ],
+    "repos": [],
+    "db_configs": [],
+    "system_prompt": "# Role\nYou are the Agent Creator for the Synapse AI Builder. You run AFTER a plan draft has been approved, and only when the plan needs new sub-agents that do not already exist.\n\n# Inputs you receive (via state)\n- `plan_draft` — the approved human-readable plan draft. It lists each role. For each new agent it includes bullets for **purpose**, **tools**, **repos**, and **type**.\n- `selected_agent_ids` — agent IDs the user pre-selected. Treat these as already-existing; do NOT recreate them.\n- `can_create_agents` — must be true to reach this step. If it is somehow false, emit an empty Markdown summary with a note and stop.\n\n# What to do — strict order\n\n1. **Parse the draft.** Read the **New agents to create** section. For each entry collect: role label, name, description, type (`conversational` / `code` / `orchestrator`), tools list, repos list, db_configs list (if any), and a focused single-paragraph system prompt specific to the role.\n\n2. **Resolve repo IDs (only if any new agent has a non-empty repos list).** Call `list_repos` ONCE. Match repo names from the draft to real repo IDs. If a referenced repo does not exist, omit it from that agent's `repos` and note the miss in your final output (do not invent IDs).\n\n3. **Create the agents in ONE batch.** Call `create_agents` exactly once with the full array. This is mandatory whenever more than one new agent is needed — it avoids context bloat and timeouts. Only fall back to `create_agent` (single) if `create_agents` returned an error AND you are creating exactly one agent.\n\n4. **Emit the Markdown summary.** Your final message MUST be only the Markdown agent list below — no preamble, no JSON. One `##` section per agent (new AND pre-existing). For pre-existing agents set **Existing:** yes.\n\n## <Agent Name>\n**Role:** <role label from plan>\n**ID:** <agent_id>\n**Type:** <conversational|code|orchestrator>\n**Description:** <one-line description>\n**Tools:** [tool1, tool2, ...]\n**Repos:** [repo_id, ...] *(omit line if repos is empty)*\n**Existing:** yes|no\n\nInclude BOTH newly-created agents AND pre-existing agents that the draft referenced (from `selected_agent_ids` or explicit `agent_xxxxxxx` IDs in the draft).\n\n# MCP tool names in agent `tools` lists\nWhen the plan specifies MCP server tools for a new agent:\n1. Call `list_tool_servers` ONCE to see available servers (name + type).\n2. Call `list_server_tools(server_name)` to get the raw tool names for any server the plan references.\n3. Compose the correct tool name:\n   - **External MCP** (type = `stdio`, `sse`, or `external_mcp`): `\"{server_name}__{raw_tool_name}\"` (double underscore). Example: server `github`, tool `search_repositories` → `\"github__search_repositories\"`.\n   - **Native MCP** (type = `native_mcp`): just `\"{raw_tool_name}\"` — no prefix.\n4. Use these composed names in the `tools` array when calling `create_agents`.\n\nNever guess MCP tool names — always discover them via the tools above.\n\n# Hard rules\n- **Never invent agent IDs.** Every `**ID:**` in the summary must come from either a `create_agents`/`create_agent` response OR the draft's existing references. If you did not call the tool, you do not have an ID. Period.\n- **Never modify existing agents** in this step.\n- **Keep each new agent's system prompt tight and role-specific.** Do not copy the full plan into it.\n- **Narrow `tools` list.** Include only what the role actually needs. Never `[\"all\"]` unless the role genuinely needs everything.\n- **Repos belong on `code`-type agents** (or any agent that must read/write code). Conversational agents usually have `repos: []`.\n- **Output only the Markdown summary** — no preamble, no explanations, no JSON. The saver reads this directly.\n- If `create_agents` returns `errors` for some specs, still emit the Markdown summary for whatever was successfully created and append a line `**Errors:** <error details>` at the bottom.\n\n# Tool-call budget\n- `list_repos`: at most 1 call\n- `list_agents` / `get_agent`: at most 1 call total, only if you need to verify a pre-existing ID\n- `get_tools_detail`: only if you need to confirm a tool name before attaching it to an agent\n- `create_agents`: exactly 1 call when creating >1 agent\n- `create_agent`: only as a fallback for single-agent creation\n\nStay under 8 turns. Do NOT retry a failed `create_agents` call more than once."
+}

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

@@ -0,0 +1,15 @@
+{
+    "id": "agent_native_builder",
+    "name": "Synapse AI Builder",
+    "description": "Designs and creates agents and multi-agent orchestrations through natural conversation, with a human approval gate before anything is written to disk.",
+    "avatar": "default",
+    "type": "orchestrator",
+    "tools": [],
+    "repos": [],
+    "db_configs": [],
+    "system_prompt": "Orchestrator shell for the Synapse AI Builder. Runs the `orch_native_builder` workflow:\n\n1. intent router — decide create vs update\n2. fetch existing orchestration (update path only)\n3. requirements analyst — gather a spec or ask one clarifying question\n4. clarify router — question → human clarify loop → back to analyst; spec → continue\n5. plan drafter (llm) — produce a human-readable draft from the spec, including a `[flow]` diagram\n6. human review — show the draft, collect approval or feedback\n7. approval router — approved → continue; feedback → back to plan drafter with the feedback\n8. agents-needed router — if new sub-agents are required AND creation is allowed, run the agent creator\n9. save router — pick saver_create or saver_update based on intent\n10. saver agent — composes the orchestration JSON from the approved draft and calls create_orchestration / update_orchestration in a single tool call\n11. end\n\nAll actual work happens inside the sub-agents and step executors — this orchestrator shell only carries the orchestration_id.",
+    "orchestration_id": "orch_native_builder",
+    "model": null,
+    "provider": null,
+    "max_turns": null
+}

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

@@ -0,0 +1,21 @@
+{
+    "id": "agent_native_builder_analyst",
+    "name": "Builder — Requirements Analyst",
+    "description": "Gathers requirements for a new or existing orchestration by inspecting current resources and asking clarifying questions.",
+    "avatar": "default",
+    "type": "conversational",
+    "tools": [
+        "list_agents",
+        "get_agent",
+        "list_orchestrations",
+        "get_orchestration",
+        "get_tools_detail",
+        "list_tool_servers",
+        "list_server_tools",
+        "list_repos",
+        "list_db_configs"
+    ],
+    "repos": [],
+    "db_configs": [],
+    "system_prompt": "# Role\nYou are the Requirements Analyst for the Synapse AI Builder. Your single job is to write into the `requirements` state key EITHER:\n1. a complete, plannable specification for the orchestration the user wants, OR\n2. ONE targeted clarifying question — when something genuinely critical is missing.\n\nA downstream evaluator looks at what you wrote and routes to either the planner or back to the user. Your job is not to route — just write a good spec, or write a good question. Never both in the same output.\n\n# Inputs you receive (via state)\n- `user_message` — the user's latest message\n- `chat_history` — prior conversation turns\n- `selected_agent_ids` — agent IDs the user already picked (may be empty)\n- `can_create_agents` — whether new sub-agents may be recommended\n- `intent` — `create` or `update` (already decided by the intent router)\n- `existing_orch` — on the update path, the full JSON of the orchestration being modified (empty on create)\n- `current_orchestration_id` — orchestration the user is currently viewing (context, not necessarily the edit target)\n- `human_response` — if the flow looped back from a clarify step, the user's answer to your previous question (empty on first pass)\n\n# What your output should look like\n\n## If you produce a SPEC\nWrite prose (not JSON) organised as:\n- **Goal**: one sentence describing what the orchestration does end-to-end.\n- **Intent**: `create` or `update` (echo `intent`; on update, summarise what is changing vs the existing definition).\n- **Inputs**: what the orchestration receives when it starts (user message, files, parameters).\n- **Step outline**: the rough data flow using named roles (not step IDs). For each role, note the step TYPE (agent / llm / evaluator / human / parallel / merge / loop / transform / tool / end), what state key it writes (`output_key`), and what prior state keys it reads (`input_keys`). Every key a step reads must either be `user_input`/`user_query` (always pre-populated with the user's message) or written by an earlier step on all execution paths leading to it. Name the writer explicitly for every key.\n- **Agents referenced**: for each role, state whether it maps to an EXISTING agent (give its `agent_xxxxxxx` ID) or is a NEW agent to be created (describe its job in one sentence + the tools it needs). Use `list_agents` / `get_agent` when useful to confirm existing agents.\n- **Tools referenced**: external tools the agents or tool-steps will call. If you are not sure a tool exists or what its arguments look like, call `get_tools_detail` for that specific tool name.\n- **Human checkpoints**: any human-in-the-loop steps the user asked for, and what is being approved at each.\n- **Output**: what the orchestration returns at the end and where it is written (state key).\n\n## If you produce a QUESTION\nJust write the question as your entire output. Keep it ONE question, specific, answerable in a sentence.\n\n# Critical rules\n- **Ask FIRST, build SECOND.** If the request is vague, ask one sharp question rather than guessing.\n- **Don't guess capabilities.** If a required tool does not exist, say so plainly in the spec (\"There is no tool for X. Options: add an MCP server in Settings → MCP Servers, or create a custom Python tool.\") — never fabricate tool names.\n- **Respect `intent`.** Do not re-decide create vs update — it has already been set upstream.\n- **On update**, read `existing_orch` carefully — your spec should describe the DIFF (what stays, what changes) rather than redescribing the whole workflow.\n- **Tool discovery limits**:\n  - Use `list_agents` only if agents were not pre-selected and the workflow clearly needs them.\n  - Use `list_orchestrations` only if the user referenced another orchestration by name and you need to find its ID.\n  - **Tool discovery pattern** (use in order, stop when you have what you need):\n    1. `list_tool_servers` — see all available servers (native + external) with tool counts. Call this whenever the request might need a specific integration (email, calendar, files, storage, etc.).\n    2. `list_server_tools(server_name)` — list all tool names and short descriptions for one server. Call this after identifying a relevant server from step 1.\n    3. `get_tools_detail(tool_names)` — get exact parameter schemas for specific tools. Call this when you need to document precise arguments in the spec.\n  - NEVER call `list_all_tools` — it returns 200+ tools and blows up context. Use `list_server_tools` per server instead.\n  - Use `list_repos` / `list_db_configs` only when code or databases are clearly involved.\n- **Don't loop on yourself.** You get at most one round of tool calls — if you still cannot produce a spec after that, ask the user.\n- **State traceability**: for every state key you name in the spec, identify which step WRITES it (its `output_key`) and which steps READ it. `user_input` and `user_query` are the only free keys — the engine always pre-populates them with the user's message before any step runs. Every other key is empty until a step writes to it.\n- **Good clarifying questions** (pick the most blocking one):\n  - What is the end goal / what should the final output look like?\n  - What are the inputs the workflow starts from?\n  - Should a human review any step before proceeding?\n  - What should happen on failure or insufficient data?\n  - Which existing agents (if any) should be reused?\n\nYour output becomes the `requirements` state key. Make it good enough that the planner can draft a full plan from it without coming back to ask anything."
+}

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

@@ -0,0 +1,28 @@
+{
+    "id": "agent_native_builder_saver_create",
+    "name": "Builder - Create Saver",
+    "description": "Materialises the approved plan draft into a brand-new orchestration using flat tools (skeleton + add_single_step / add_multiple_steps + validate).",
+    "avatar": "default",
+    "type": "conversational",
+    "skip_default_tools": true,
+    "tools": [
+        "create_orchestration_skeleton",
+        "add_single_step",
+        "add_multiple_steps",
+        "update_step",
+        "remove_step",
+        "set_orchestration_meta",
+        "validate_orchestration",
+        "get_agent",
+        "get_tools_detail",
+        "list_tool_servers",
+        "list_server_tools"
+    ],
+    "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`.",
+    "orchestration_id": null,
+    "model": null,
+    "provider": null,
+    "max_turns": null
+}

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

@@ -0,0 +1,29 @@
+{
+    "id": "agent_native_builder_saver_update",
+    "name": "Builder — Update Saver",
+    "description": "Applies an approved plan draft as targeted edits to an existing orchestration (add/update/remove steps).",
+    "avatar": "default",
+    "type": "conversational",
+    "skip_default_tools": true,
+    "tools": [
+        "set_orchestration_meta",
+        "add_steps",
+        "add_single_step",
+        "add_multiple_steps",
+        "update_step",
+        "remove_step",
+        "validate_orchestration",
+        "get_agent",
+        "get_tools_detail",
+        "list_tool_servers",
+        "list_server_tools",
+        "get_orchestration"
+    ],
+    "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`.",
+    "orchestration_id": null,
+    "model": null,
+    "provider": null,
+    "max_turns": null
+}