Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(agent): env-sourced agent defaults + in-run canvas reload + docs refresh
trohitgc14c54bea9f2
diff --git a/.env.template b/.env.templateindex ebfd5047..a62a43f4 100644--- a/.env.template+++ b/.env.template@@ -98,6 +98,16 @@ EVENT_FRAMEWORK_ENABLED=true# context-window threshold. Per-session overrides via the UI.COMPACTION_ENABLED=true+# Compaction trigger threshold as a fraction of the model's context+# window (0.05 - 0.99). 0.8 = compact when cumulative tokens hit 80%.+# Per-user overrides via the UserSettings row (Settings tab).+COMPACTION_RATIO=0.8++# Agent loop hard step cap. AI Agent + Chat Agent stop the LLM/tool+# iteration loop after this many rounds and return a truncation note.+# Per-user overrides via the UserSettings row (Settings tab).+AGENT_RECURSION_LIMIT=200+# Dead-letter queue for failed workflow executions. Off by default.DLQ_ENABLED=falsediff --git a/CLAUDE.md b/CLAUDE.mdindex cf4fe12a..beed6528 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,7 +20,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute via the plain-async `_run_agent_loop` || **[Agent Delegation](./docs-internal/agent_delegation.md)** | How memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool || **[Agent Teams](./docs-internal/agent_teams.md)** | Claude SDK Agent Teams pattern - AI Employee and Orchestrator nodes with input-teammates handle for multi-agent coordination |-| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Token tracking and model-aware memory compaction using native provider APIs (Anthropic, OpenAI) with threshold = 50% of context window |+| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Token tracking and model-aware memory compaction using native provider APIs (Anthropic, OpenAI). Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context_length; per-user UserSettings override exposed in Settings tab. || **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks || **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection || **[Email Service](./docs-internal/email_service.md)** | IMAP/SMTP integration via Himalaya CLI with EmailService orchestrator, provider presets, custom credential fallback, and polling triggers |@@ -2360,12 +2360,23 @@ Adding a new node type's output shape: define one Pydantic model, register it in## AI Agent Node Architecture### Agent Loop Termination-The standard agent path (`_run_agent_loop` in `services/ai.py`) routes purely on `response.tool_calls` — no custom iteration counter beyond `max_iterations`. The cap is sourced from `agent.recursion_limit` in `llm_defaults.json` (currently 500 — generous backstop, not the load-bearing termination signal).+The standard agent path (`_run_agent_loop` in `services/ai.py`) routes purely on `response.tool_calls` — no custom iteration counter beyond `max_iterations`. Resolution precedence (highest → lowest):-The token-based compaction threshold (`agent.compaction.ratio` × context_length, ≈100K for claude-sonnet-4-6) is the real termination signal: `_track_token_usage` runs after each agent turn, and when cumulative tokens cross the threshold it invokes `CompactionService.compact_context` to summarise the transcript before the next turn.+1. Per-agent-node `parameters.max_iterations` (set on the agent node itself).+2. Per-user `UserSettings.agent_recursion_limit` (Settings tab, DB-backed).+3. Env `Settings.agent_recursion_limit` from `AGENT_RECURSION_LIMIT` (default **200**).+4. JSON fallback `llm_defaults.json:agent.recursion_limit` (legacy SSOT, kept as last-resort).++The token-based compaction threshold (`compaction_ratio` × model context_length, default 80% × ~200K for claude-sonnet-4-6 ≈ 160K) is the real termination signal: `_track_token_usage` runs after each agent turn, and when cumulative tokens cross the threshold it invokes `CompactionService.compact_context` to summarise the transcript before the next turn. Ratio precedence mirrors the recursion limit chain — per-session `custom_threshold` > `UserSettings.compaction_ratio` > `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) > JSON fallback.If the iteration cap is ever hit anyway, `_run_agent_loop` appends a terminal `AIMessage` carrying a truncation note and returns `truncated=True` so `_extract_text_content` returns a usable partial response and the workflow continues — `_track_token_usage` and any post-loop persistence still run.+### Hot rebind after canvas mutation++`_run_agent_loop` accepts a `rebind_from_operations: Callable[[List[Dict]], Awaitable[List[StructuredTool]]]` callback. After each iteration's tool calls return, the loop inspects every result for an `operations` field (workflow_ops batch, today only `agentBuilder` emits this), invokes the callback, extends the local `current_tools` list, and re-calls `chat_model.bind_tools(current_tools)` so the LLM sees the new tools in the NEXT iteration — no Run-stop-Run cycle. The callback is wired by `execute_agent` / `execute_chat_agent` as a closure that calls `_build_tool_from_node` for each `add_node` op with `component_kind == "tool"` OR `usable_as_tool=True` (excluding chat models). Gated by `UserSettings.auto_rebind_tools_after_canvas_change` (default True); when off the closure is `None` and the LLM is told "Available on your next turn" in the operation summary.++For the F4.B Temporal path, the same rebind happens via the `agent.refresh_tools.v1` activity called from `AgentWorkflow.run` between iterations. See [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).+### Spec-driven component design (Wave 10.D)`AIAgentNode.tsx` knows nothing about specific agent types. It calls `useNodeSpec(type)` once and reads `handles`, `color`, `displayName`, `subtitle`, and `uiHints` from the cached `NodeSpec` ([`AIAgentNode.tsx:55-68`](./client/src/components/AIAgentNode.tsx#L55-L68)). The earlier 60-line `AGENT_CONFIGS` map (one entry per agent type, each with hardcoded `themeColorKey` + handle topology) was retired in Wave 10.D.@@ -3575,26 +3586,26 @@ CompactionService.record() → Save compaction event to DB### Native Provider APIs-**Threshold strategy:** per-session `custom_threshold` > model-aware threshold (50% of context window) > global default.+**Threshold strategy:** per-session `custom_threshold` > per-user `UserSettings.compaction_ratio` × context_length > env `Settings.compaction_ratio` (`COMPACTION_RATIO`, default 0.8) × context_length > JSON `llm_defaults.json` ratio × context_length.**Anthropic SDK (tool_runner):**```python-# Model-aware: threshold computed from model's context window+# Model-aware: threshold = compaction_ratio × model's context windowcompaction_control = svc.anthropic_config(model="claude-opus-4.6", provider="anthropic")-# Returns: {"enabled": True, "context_token_threshold": 500000} (50% of 1M)+# Returns: {"enabled": True, "context_token_threshold": 800000} (0.8 × 1M with default ratio)```**Anthropic Messages API:**```pythonapi_config = svc.anthropic_api_config(model="claude-sonnet-4.5", provider="anthropic")# Returns: {"betas": ["compact-2026-01-12"], "context_management": {"edits": [...]}}-# Threshold auto-computed from model's context window+# Threshold auto-computed from model's context window × compaction_ratio.```**OpenAI:**```pythonopenai_config = svc.openai_config(model="gpt-5.2", provider="openai")-# Returns: {"context_management": {"compact_threshold": 200000}} (50% of 400K)+# Returns: {"context_management": {"compact_threshold": 320000}} (0.8 × 400K with default ratio)```### Key Files@@ -3666,11 +3677,11 @@ from services.compaction import get_compaction_servicesvc = get_compaction_service()-# Get model-aware provider config (threshold = 50% of context window)+# Get model-aware provider config (threshold = compaction_ratio × context window)anthropic_cfg = svc.anthropic_config(model="claude-opus-4.6", provider="anthropic")-# threshold: 500000 (50% of 1M context)+# threshold: 800000 (0.8 × 1M context with default ratio)openai_cfg = svc.openai_config(model="gpt-5.2", provider="openai")-# threshold: 200000 (50% of 400K context)+# threshold: 320000 (0.8 × 400K context with default ratio)# Or override with explicit thresholdanthropic_cfg = svc.anthropic_config(threshold=100000)@@ -3748,24 +3759,33 @@ pricing_info = pricing.get_pricing("anthropic", "claude-3-5-sonnet-20241022")### Configuration-The compaction threshold is fully JSON-driven via `server/config/llm_defaults.json`:+The compaction threshold + agent recursion limit are env-driven via `.env` (read by `core.config.Settings`); `server/config/llm_defaults.json` is the legacy SSOT and acts as last-resort fallback when Settings can't load:++```bash+# .env (mirrors .env.template)+COMPACTION_ENABLED=true # Enable/disable compaction globally+COMPACTION_RATIO=0.8 # Fraction of context window that triggers compaction (0.05-0.99)+AGENT_RECURSION_LIMIT=200 # Agent loop hard step cap (>=1)+``````json+// server/config/llm_defaults.json — last-resort fallback only"agent": {- "recursion_limit": 500,+ "recursion_limit": 200,"default_temperature": 0.7,- "compaction": { "ratio": 0.5 }+ "compaction": { "ratio": 0.8 }}```-Effective threshold = `providers.<provider>.context_length.<model>` × `agent.compaction.ratio` (e.g. claude-sonnet-4-6 → 200K × 0.5 = 100K input tokens). When model/provider are unknown, `model_registry.get_context_length` falls through to the provider's `_default` entry in the same JSON — never a Python constant.+Effective threshold = `providers.<provider>.context_length.<model>` × `compaction_ratio` (e.g. claude-sonnet-4-6 → 200K × 0.8 = 160K input tokens). When model/provider are unknown, `model_registry.get_context_length` falls through to the provider's `_default` entry in the same JSON.-Only the global on/off toggle stays in `.env`:-```bash-COMPACTION_ENABLED=true # Enable/disable compaction globally-```+**Threshold priority** (highest → lowest):+1. Per-session `SessionTokenState.custom_threshold` (WebSocket override).+2. Per-user `UserSettings.compaction_ratio` × context_length (Settings tab override).+3. Env `Settings.compaction_ratio` × context_length.+4. JSON `llm_defaults.json:agent.compaction.ratio` × context_length.-**Threshold priority:** per-session `custom_threshold` > model-aware (`context_length × ratio`).+Same precedence chain applies to `recursion_limit`: per-node `parameters.max_iterations` > `UserSettings.agent_recursion_limit` > `Settings.agent_recursion_limit` > JSON.### Client-Side Compaction@@ -3849,7 +3869,7 @@ compaction_svc.set_ai_service(container.ai_service())- **5-Section Summary**: Follows Claude Code's structured summary format for continuity- **Automatic Triggering**: Compaction triggered in `_track_token_usage()` when threshold exceeded- **Per-Session State**: Each memory session has independent token tracking and thresholds-- **Model-Aware Threshold**: 50% of model's context window (e.g., 500K for Claude Opus 4.6 with 1M context, 200K for GPT-5.2 with 400K context). Falls back to global `COMPACTION_THRESHOLD` when model info unavailable. Per-session `custom_threshold` always takes priority.+- **Model-Aware Threshold**: `compaction_ratio` × model's context window. Default ratio 0.8 (env `COMPACTION_RATIO`, was 0.5 pre-2026.06). E.g. 800K for Claude Opus 4.6 with 1M context, 320K for GPT-5.2 with 400K context. Falls back to JSON `llm_defaults.json:agent.compaction.ratio` when Settings can't load. Per-session `custom_threshold` > per-user `UserSettings.compaction_ratio` > env Settings.- **Singleton Pattern**: Service accessible via `get_compaction_service()`## API Cost Trackingdiff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsxindex 01510f09..97e7749a 100644--- a/client/src/components/ui/SettingsPanel.tsx+++ b/client/src/components/ui/SettingsPanel.tsx@@ -332,23 +332,41 @@ const SettingsPanel: React.FC<SettingsPanelProps> = ({</span></div><Slider- min={10}- max={90}+ min={5}+ max={95}step={5}value={[Math.round(settings.compactionRatio * 100)]}- onValueChange={(value) => handleChange('compactionRatio', (value[0] ?? 50) / 100)}+ onValueChange={(value) => handleChange('compactionRatio', (value[0] ?? 80) / 100)}disabled={isSaving}className="my-3"/><div className="flex justify-between text-[10px] text-fg-muted">- <span>10%</span>+ <span>5%</span><span>50%</span>- <span>90%</span>+ <span>95%</span></div><div className="mt-1 text-xs leading-snug text-fg-muted">Lower = compact sooner (saves tokens, loses detail). Higher = compact later (preserves context, uses more tokens).</div></div>++ <div className="my-1 border-b border-border-default" />++ <Row+ label="AI Agent Max Steps"+ description="Hard cap on the agent loop's LLM-iteration count per run. The token-based compaction threshold is usually the real termination signal; this is the safety backstop."+ >+ <Input+ type="number"+ min={1}+ max={5000}+ step={10}+ value={settings.agentRecursionLimit}+ onChange={(e) => handleChange('agentRecursionLimit', Number(e.target.value) || 200)}+ disabled={isSaving}+ className="w-24"+ />+ </Row></Section>{/* Process Manager */}diff --git a/client/src/components/ui/settingsPanel/schema.ts b/client/src/components/ui/settingsPanel/schema.tsindex 5fb70782..6eb2801a 100644--- a/client/src/components/ui/settingsPanel/schema.ts+++ b/client/src/components/ui/settingsPanel/schema.ts@@ -17,7 +17,8 @@ export const workflowSettingsSchema = z.object({componentPaletteDefaultOpen: z.boolean().default(true),consolePanelDefaultOpen: z.boolean().default(false),memoryWindowSize: z.number().int().min(1).max(100).default(100),- compactionRatio: z.number().min(0.1).max(0.9).default(0.5),+ compactionRatio: z.number().min(0.05).max(0.99).default(0.8),+ agentRecursionLimit: z.number().int().min(1).max(5000).default(200),maxProcesses: z.number().int().min(1).max(50).default(10),autoAddSkillForTools: z.boolean().default(true),autoRebindToolsAfterCanvasChange: z.boolean().default(true),@@ -44,6 +45,7 @@ export function fromServerRow(row: Record<string, any> | null | undefined): WorkmaxProcesses: row.max_processes,autoAddSkillForTools: row.auto_add_skill_for_tools,autoRebindToolsAfterCanvasChange: row.auto_rebind_tools_after_canvas_change,+ agentRecursionLimit: row.agent_recursion_limit,});}@@ -63,5 +65,6 @@ export function toServerRow(s: WorkflowSettings): Record<string, any> {max_processes: s.maxProcesses,auto_add_skill_for_tools: s.autoAddSkillForTools,auto_rebind_tools_after_canvas_change: s.autoRebindToolsAfterCanvasChange,+ agent_recursion_limit: s.agentRecursionLimit,};}diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex a6803ba0..dfdc8190 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -312,11 +312,22 @@ AgentWorkflow.run(context):envelope so the LLM sees only the handler's return value(matches the in-process tool-call serialisation inservices/ai.py:_run_agent_loop).- 4. execute_activity("agent.persist_turn.v1")+ 4. for each tool result with an ``operations`` field+ (canvas-mutating tools — today only ``agentBuilder``):+ if payload["auto_rebind_tools"] is True:+ execute_activity("agent.refresh_tools.v1", {operations: …})+ translates add_node ops with component_kind=="tool" OR+ usable_as_tool=True (minus chat-model plugins) into the+ same tool_payload shape prepare_agent_payload emits.+ Reuses ai_service._build_tool_from_node + get_node_class.+ tools.extend(refresh_result["tools"])+ tool_index.update(...)+ # next execute_llm_step.v1 sees the new tools.+ 5. execute_activity("agent.persist_turn.v1")append_to_memory_markdown(content, "human", prompt) +(content, "ai", response); trim window; broadcastnode_parameters_updated CloudEvents (source_hint="agent").- 5. if token_total >= compaction_threshold:+ 6. if token_total >= compaction_threshold:execute_activity("agent.compact_memory.v1")null-guarded against worker-bootstrap race; replaces messageswith summary only when result.success is True.@@ -332,6 +343,20 @@ AgentWorkflow.run(context):Each LLM step is one activity, each tool call is one per-type activity (the same activities F4.A registered). **Delegation tool calls** (`delegate_to_<x>`) where the child type is in `AGENT_WORKFLOW_TYPES` are the exception: they spawn a child `AgentWorkflow` via `workflow.execute_child_workflow` instead of a per-type activity, with `parent_node_id` injected into `child_context` to enable the parent-mirror broadcast above. Deterministic child workflow id is `f"{parent_workflow_id}-delegate-{child_node_id}-{iteration}"` so Temporal retries don't spawn duplicates. Non-agent tools and excluded types (`rlm_agent`, `claude_code_agent`) still go through `execute_activity` as before. Failures of tool activities surface as error messages back to the LLM (matching the in-process agent loop behaviour); the agent loop continues.+**Canvas-aware tools** opt into receiving the parent workflow's `nodes`/`edges` by declaring `needs_canvas: ClassVar[bool] = True` on their `BaseNode` subclass. The F4.B tool dispatch reads this via `services.node_registry.get_node_class(node_type).needs_canvas` and forwards `context.get("nodes")` / `context.get("edges")` into `tool_payload`; default plugins keep the empty-canvas optimisation. Today only `agentBuilder` opts in (it walks edges to resolve its calling agent and mutates the canvas). Operations inside agentBuilder reload via `database.get_workflow(workflow_id)` so in-run duplicate detection sees mutations from earlier calls in the same workflow run — see [agent_builder section in CLAUDE.md](../CLAUDE.md).++**Seven agent activities** are registered by `collect_agent_activities()` for `AgentWorkflow` to schedule by name:++| Activity | Purpose |+|---|---|+| `agent.prepare_payload.v1` | Resolves the DB-backed payload (provider / model / api_key / system_message / user_prompt / tools / memory_node_id / memory_content / memory_window_size / max_iterations / thinking_config / compaction_threshold / auto_rebind_tools). Reads `UserSettings.agent_recursion_limit` + `UserSettings.auto_rebind_tools_after_canvas_change`. |+| `agent.execute_llm_step.v1` | One LLM turn — rebuilds StructuredTools from the workflow's current `tools` list and returns the assistant message + tool_calls. |+| `agent.refresh_tools.v1` | Translates `workflow_ops` add_node ops (component_kind="tool" OR usable_as_tool=True) into fresh `tool_payload` entries via `_build_tool_from_node`. Workflow extends `tools` + `tool_index` from the result. |+| `agent.persist_turn.v1` | Appends the latest human/assistant exchange to memory markdown, trims the window, broadcasts `node.parameters.updated`. |+| `agent.compact_memory.v1` | Token-budget compaction when cumulative tokens hit the threshold. Best-effort: continues with un-compacted history on failure. |+| `agent.store_output.v1` | Writes `output_main` / `output_top` / `output_0` so downstream nodes resolve `{{aiAgent.response}}` via `ParameterResolver`. |+| `agent.broadcast_progress.v1` | Emits `WorkflowEvent.agent_progress` (CloudEvents v1.0) + optional raw-dict `update_node_status` for canvas-glow color. Single helper drives every phase emit. |+**Broadcasts inside the loop** wrap `WorkflowEvent` (CloudEvents v1.0) per RFC §6.4: `agent_progress` events (`com.machinaos.agent.progress`) and `node_parameters_updated` events (`com.machinaos.node.parameters.updated`) flow through the `StatusBroadcaster.broadcast_agent_progress` and `StatusBroadcaster.broadcast_node_parameters_updated` wrappers respectively. The latter is reused by the legacy `routers/websocket.py:handle_save_node_parameters` (user-source) and `services/cli_agent/service.py:_persist_memory` (cli-source) — all three emission sites share the same envelope, distinguished by `source_hint` (`"user"` / `"cli"` / `"agent"`).`rlm_agent`, `claude_code_agent` are NOT migrated — their internal session state (RLM REPL / Claude CLI `--resume` with stable `cwd`) requires single-process continuity and would break across activity boundaries.diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.mdindex 16ff1eae..9682c93b 100644--- a/docs-internal/agent_architecture.md+++ b/docs-internal/agent_architecture.md@@ -92,7 +92,7 @@ The agent loop is a plain `for iteration in range(max_iterations):` async functi3. `response = await chat_model.ainvoke(filtered)` — single LLM call. The full assistant message is appended to `messages` verbatim so provider-specific metadata survives (Gemini `thought_signature`, Anthropic cache markers, OpenAI `reasoning_content`).4. `extract_thinking_from_response(response)` — accumulates thinking across iterations with the `--- Iteration N ---` separator (multi-step reasoning).5. If `response.tool_calls` is empty → return `{messages, iteration, thinking_content, truncated: False}`.-6. Otherwise dispatch each `tool_call` via the supplied `tool_executor`, wrap each result as a `ToolMessage`, append, and loop.+6. Otherwise dispatch each `tool_call` via the supplied `tool_executor`, wrap each result as a `ToolMessage`, append. After all calls in this iteration return, inspect each result for a `operations` field (workflow_ops batch from canvas-mutating tools); call `rebind_from_operations(ops)` if wired, extend the local `current_tools` list, and `chat_model.bind_tools(current_tools)` again so the LLM sees the new tools in the NEXT iteration. Loop.On hitting `max_iterations`, append a terminal `AIMessage` with a truncation note and return `truncated: True`.@@ -107,11 +107,12 @@ async def _run_agent_loop(tool_executor: Optional[Callable] = None,max_iterations: int = 500,progress_callback: Optional[Callable[[int], Any]] = None,+ rebind_from_operations: Optional[Callable[[List[Dict[str, Any]]], Awaitable[List[Any]]]] = None,) -> Dict[str, Any]:"""Returns {messages, iteration, thinking_content, truncated}."""```-Tools bind once at the top via `chat_model.bind_tools(tools)`; the same provider-unified LangChain method every chat model honours.+Tools bind at loop start via `chat_model.bind_tools(tools)` and **rebind** mid-loop whenever a tool returns workflow_ops (today only `agentBuilder`). The rebound model is the SAME LangChain `chat_model.bind_tools` method every provider honours — no per-provider plumbing.### Termination@@ -121,7 +122,27 @@ Tools bind once at the top via `chat_model.bind_tools(tools)`; the same provider| `tool_executor` is `None` but LLM emits tool calls | WARN + return (treat as final). || `iteration` reaches `max_iterations` | Append synthetic terminal `AIMessage` + return with `truncated: True`. |-`max_iterations` defaults to 500 (sourced from `llm_defaults.json:agent.recursion_limit`). It's a backstop, not the load-bearing signal — compaction (token-based, post-turn) is the actual termination control.+### `max_iterations` precedence++Resolved per-execution by `execute_agent` / `execute_chat_agent` (and `prepare_agent_payload` for F4.B), highest to lowest:++1. **Per-agent-node** `parameters.max_iterations` — set by the user on the agent node itself.+2. **Per-user** `UserSettings.agent_recursion_limit` — Settings tab override (DB-backed).+3. **Env** `Settings.agent_recursion_limit` from `AGENT_RECURSION_LIMIT` (default 200).+4. **JSON** `llm_defaults.json:agent.recursion_limit` — last-resort fallback when Settings can't load.++This is a backstop, not the load-bearing signal — compaction (token-based, post-turn) is the actual termination control. See [memory_compaction.md](memory_compaction.md).++### Hot rebind after canvas mutation++When `agentBuilder` (the only canvas-mutating tool today) spawns a new node mid-run via `add_tool` / `add_skill` / `add_subagent`, the operation returns a `workflow_ops` batch in its result's `operations` field. The loop detects the field, calls `rebind_from_operations(ops)`, and extends the bound tool surface so the LLM can invoke the new tool in the very next iteration — no Run-stop-Run cycle.++Closure responsibilities:++- **`_rebind_from_operations(ops) -> List[StructuredTool]`** (in `execute_agent` / `execute_chat_agent`): filter ops for `add_node` with the plugin class's `component_kind == "tool"` OR `usable_as_tool=True` (excluding `component_kind == "model"`), synthesize a `tool_info` dict, call `self._build_tool_from_node(tool_info)`, return the new StructuredTools. Tool configs get folded into the captured `tool_configs` dict so the `tool_executor` can dispatch the new call.+- The closure is gated on the user toggle: `UserSettings.auto_rebind_tools_after_canvas_change` (default `True`). When off, the LLM is told "Available on your next turn" in the operation summary and the closure isn't wired.++For the F4.B Temporal path, the in-process closure is replaced by the `agent.refresh_tools.v1` activity; see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md).### Where it's called@@ -348,16 +369,16 @@ registry['rlm_agent'] = partial(handle_rlm_agent, ai_service=self.ai_service, daregistry['claude_code_agent'] = partial(handle_claude_code_agent, ...)```-### Temporal dispatch routing (post-F4)+### Temporal dispatch routingTwo settings flags route agent execution through different Temporal paths (see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md) for the full matrix):-| Flag | Off (default) | On |+| Flag | Off | On (default) ||---|---|---|| `TEMPORAL_PER_TYPE_DISPATCH` | Every node routes through the legacy `execute_node_activity` single dispatcher (WS round-trip to the FastAPI handler). | Each node routes through its per-type activity `node.{type}.v{version}` registered via `BaseNode.as_activity()`. Per-plugin retry / timeout / heartbeat configs apply. |-| `TEMPORAL_AGENT_WORKFLOW_ENABLED` | All 11 specialized + 2 team leads + 2 base agents (`aiAgent` / `chatAgent`) run inside `execute_node_activity` (`_run_agent_loop` in-activity). | The 14 migrating agent types become Temporal **child workflows** (`AgentWorkflow`). LLM steps + tool calls become activities; `agent.prepare_payload.v1` resolves the DB-backed payload as the workflow's first step. `rlm_agent` / `claude_code_agent` stay on the F4.A per-type activity path (externalised session state). |+| `TEMPORAL_AGENT_WORKFLOW_ENABLED` | All specialized + team leads + base agents (`aiAgent` / `chatAgent`) run inside `execute_node_activity` (`_run_agent_loop` in-activity). | The migrating agent types become Temporal **child workflows** (`AgentWorkflow`). LLM steps + tool calls become activities; `agent.prepare_payload.v1` resolves the DB-backed payload as the workflow's first step; `agent.refresh_tools.v1` rebinds the tool surface after canvas mutations. `rlm_agent` / `claude_code_agent` stay on the F4.A per-type activity path (externalised session state). |-Today both flags default to `false`; the wiring is shipped (F4.A at `8261b05`, F4.B infrastructure at `a4d009e`, per-agent dispatch at `0459131`) but production rollout awaits canary verification on a Temporal dev cluster.+Both flags default to `true` in `.env.template`.**Team leads** (`orchestrator_agent`, `ai_employee`) use the same `handle_chat_agent` routing but add an `input-teammates` handle. Connected agents become `delegate_to_<type>` tools automatically via `_collect_teammate_connections()`. See [agent_teams.md](agent_teams.md).diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.mdindex 357e038d..82a4577f 100644--- a/docs-internal/memory_compaction.md+++ b/docs-internal/memory_compaction.md@@ -343,16 +343,21 @@ ws.send(JSON.stringify({### Environment Variables```bash-# In server/.env+# In server/.env (mirrors .env.template)COMPACTION_ENABLED=true # Enable/disable compaction globally (default: true)-COMPACTION_THRESHOLD=100000 # Global fallback threshold (default: 100000, min: 10000)- # Used when model context window is unknown+COMPACTION_RATIO=0.8 # Fraction of context window that triggers compaction+ # (default: 0.8 — was 0.5 pre-2026.06). Range 0.05-0.99.+ # Read by core.config.Settings.compaction_ratio.```-**Threshold priority chain:**-1. Per-session `custom_threshold` (set via `configure()` or WebSocket)-2. Model-aware threshold: 50% of model's context window (e.g., 500K for 1M model)-3. Global `COMPACTION_THRESHOLD` from `.env` (fallback when model info unavailable)+**Threshold priority chain** (highest → lowest):++1. **Per-session** `SessionTokenState.custom_threshold` (set via `configure()` or WebSocket).+2. **Per-user** `UserSettings.compaction_ratio` × model's context_length — DB-backed override exposed in the Settings tab.+3. **Env** `Settings.compaction_ratio` × model's context_length — `COMPACTION_RATIO` × `model_registry.get_context_length(provider, model)`.+4. **JSON fallback** `llm_defaults.json:agent.compaction.ratio` × context_length — when Settings can't load (one-off CLI scripts).++Effective threshold computed by `model_registry.get_agent_defaults()["compaction"]["ratio"]` (which now reads from `Settings` first) — e.g. claude-sonnet-4-6 with 1M context × 0.8 = 800K trigger.### Per-Session Overridediff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.mdindex f2da3ec7..0f671dd9 100644--- a/docs-internal/node_allowlist.md+++ b/docs-internal/node_allowlist.md@@ -64,6 +64,19 @@ Re-enable: drop the entries. The hook + filters are forward-compatible with empt|---|---|---|| `android` group + `android_agent` / `androidTool` + `android` credential category + `android_agent` skill folder | Hardware-tied (ADB / Android relay) — high friction to set up, low value for most users | Palette + credentials + skill folders || `email` group + `email` credential category | Himalaya CLI dependency — complex install path, IMAP/SMTP config burden | Palette + credentials |+| `taskManager` (single node) | Functionality folded into `writeTodos`; redundant duplicate | Palette + LLM-spawnable set via agentBuilder |++## agentBuilder integration++`agentBuilder` honors the same allowlist when surfacing its spawnable catalogue (`inspect_canvas.available_tools` / `available_agents` / `available_skills`) and rejecting `add_tool` / `add_subagent` / `add_skill` calls:++| Allowlist field | agentBuilder filter |+|---|---|+| `disabled_nodes` | Excluded from `_allowed_tool_types()` + `_allowed_subagent_types()` — the LLM can't spawn or list the type. |+| `disabled_groups` | Excluded from both sets via plugin `group` tuple intersection (any matching entry hides every plugin in the group). |+| `disabled_skill_folders` | Excluded from `_catalogue_skills()` — the LLM doesn't see folders the operator marked. Match is on the SkillMetadata path ancestor (e.g. `disabled_skill_folders: ["android_agent"]` blocks every skill under `server/skills/android_agent/`). |++Read via `services.node_allowlist.get_node_allowlist_service().get_config()` — same singleton the UI hook hits. Adding a node to `disabled_nodes` once propagates to BOTH the UI palette AND the LLM's spawnable surface.## Filter call sitesdiff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex b6c64775..37aeec21 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -128,11 +128,23 @@ class SpecializedAgentBase(ActionNode, abstract=True):| `credentials` | Tuple of `Credential` subclasses the node uses. || `Params` | Pydantic `BaseModel` — user-facing parameters. Used for both UI rendering and AI tool schemas. || `Output` | Pydantic `BaseModel` — runtime output shape. |-| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. |+| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). |+| `needs_canvas` | `ClassVar[bool]` — when `True`, the F4.B `AgentWorkflow` tool-dispatch forwards the parent workflow's `nodes`/`edges` into the per-tool activity payload. Today only `AgentBuilderNode` opts in (walks edges to resolve its calling agent). || `task_queue` | Temporal worker pool. See `TaskQueue` constants. || `retry_policy` | `RetryPolicy` dataclass (mirrors `temporalio.common.RetryPolicy`). || `start_to_close_timeout` / `heartbeat_timeout` | Per-node Temporal knobs. |+### Polymorphic result envelope (`interpret_result`)++`BaseNode.interpret_result(result) -> (success: bool, payload: Any, error: Optional[str])` is the classmethod the F4.A activity wrapper at [`BaseNode.as_activity`](../server/services/plugin/base.py) calls to normalise broadcast inputs across node kinds:++| Node kind | Contract | Default semantics |+|---|---|---|+| `ActionNode` / `TriggerNode` | `{success: bool, result: Any, error?: str, ...}` envelope (produced by `_wrap_success` / `_wrap_error`). | Inherits `BaseNode.interpret_result` — reads `success` + `result` + `error` keys. |+| `ToolNode` | Flat dict IS the success payload (the LLM-feedable shape). Error paths still produce the standard envelope via `_wrap_error`. | Overridden on `ToolNode`: if no `success` key, treat the dict as success payload; otherwise delegate to base. |++This is the contract that makes `writeTodos` / `calculatorTool` etc. broadcast successfully through F4.A — without the polymorphic override, the wrapper's `if result.get("success")` check would treat every ToolNode result as failure and never call `update_node_output`.+### Auto-derived uiHints`BaseNode._metadata_dict` (`server/services/plugin/base.py`) callsdiff --git a/docs-internal/workflow_ops_protocol.md b/docs-internal/workflow_ops_protocol.mdindex 7aef415a..888e4388 100644--- a/docs-internal/workflow_ops_protocol.md+++ b/docs-internal/workflow_ops_protocol.md@@ -30,7 +30,7 @@ ids that later ops reference via `client_ref` placeholders.| Type | Required | Optional | Purpose ||---|---|---|---|-| `add_node` | `client_ref`, `node_type`, `parameters` | `label`, `position` | Create a new node + persist its initial params. `client_ref` is a batch-local id later ops can target. |+| `add_node` | `client_ref`, `node_type`, `parameters` | `label`, `position`, `minted_id` | Create a new node + persist its initial params. `client_ref` is a batch-local id later ops can target. When `minted_id` is set (BE hot-spawn path — `agentBuilder` mints upfront so status broadcasts route to the same React Flow id), the FE applier adopts the supplied id verbatim instead of calling `newId()`. || `add_edge` | `source`, `target` | `source_handle`, `target_handle` | Wire two nodes. `source` / `target` are either existing node ids (string) or `{client_ref}` references. || `set_node_parameters` | `node_id`, `parameters` | -- | Shallow-merge `parameters` into the node's existing params via `saveNodeParameters`. || `delete_node` | `node_id` | -- | Remove node; edges to/from it cascade-delete. |@@ -122,7 +122,7 @@ failures (toast, log, retry, etc.).| Service | Trigger | Module ||---|---|---|| Auto-add Skill on tool connect | WS request `evaluate_auto_skill` (frontend on edge connect/disconnect) | `server/services/auto_skill.py` |-| Agent Builder runtime tools | WS broadcast `workflow_ops_apply` (backend, mid-execution) | `server/nodes/tool/agent_builder.py` |+| Agent Builder runtime tools | WS broadcast `workflow_ops_apply` (backend, mid-execution) + DB persist via `database.save_workflow` so subsequent runs and in-run reload see the mutation | `server/nodes/tool/agent_builder/__init__.py` |## Two delivery modesdiff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.jsonindex f5c5affb..cfc7b8f9 100644--- a/server/config/llm_defaults.json+++ b/server/config/llm_defaults.json@@ -4,11 +4,11 @@"_description": "LLM provider defaults. Connection config (base_url, models_endpoint) drives both native SDK and LangChain paths. Model specs auto-enriched by model_registry.json (OpenRouter cache).","agent": {- "_description": "Agent execution defaults shared across the agent loop + compaction layers. recursion_limit is intentionally generous so the token-based compaction.ratio is the load-bearing termination signal, not the step cap.",- "recursion_limit": 500,+ "_description": "Agent execution defaults. recursion_limit and compaction.ratio are sourced from the environment (AGENT_RECURSION_LIMIT, COMPACTION_RATIO via core.config.Settings) — these JSON values are last-resort fallbacks when the env vars aren't loaded (e.g. one-off CLI scripts that bypass Settings). default_temperature stays JSON-resident since it has no env override yet.",+ "recursion_limit": 200,"default_temperature": 0.7,"compaction": {- "ratio": 0.5+ "ratio": 0.8}},diff --git a/server/core/config.py b/server/core/config.pyindex 5728e321..58755cde 100644--- a/server/core/config.py+++ b/server/core/config.py@@ -241,10 +241,15 @@ class Settings(BaseSettings):# silently allows. Override to "0.0.0.0" for container deployments.whatsapp_bind_host: str = Field(default="localhost", env="WHATSAPP_BIND_HOST")- # Compaction Configuration. The threshold is fully model-aware and- # sourced from server/config/llm_defaults.json (context_length ×- # agent.compaction.ratio). Only the global on/off toggle remains here.+ # Compaction Configuration. Threshold = model context_length ×+ # compaction_ratio. Per-user UserSettings row overrides at runtime.compaction_enabled: bool = Field(default=True, env="COMPACTION_ENABLED")+ compaction_ratio: float = Field(default=0.8, env="COMPACTION_RATIO", ge=0.05, le=0.99)++ # Agent loop hard step cap. Per-user UserSettings row overrides+ # at runtime; per-agent-node ``parameters.max_iterations`` is the+ # innermost override.+ agent_recursion_limit: int = Field(default=200, env="AGENT_RECURSION_LIMIT", ge=1)# Gunicorn Configuration (for production deployment)gunicorn_timeout: int = Field(default=120, env="GUNICORN_TIMEOUT", ge=30)diff --git a/server/core/database.py b/server/core/database.pyindex 8ad63139..3eaad65f 100644--- a/server/core/database.py+++ b/server/core/database.py@@ -133,6 +133,10 @@ class Database:await conn.execute(text("ALTER TABLE user_settings ADD COLUMN auto_rebind_tools_after_canvas_change BOOLEAN DEFAULT 1"))logger.info("Added auto_rebind_tools_after_canvas_change column to user_settings")+ if "agent_recursion_limit" not in columns:+ await conn.execute(text("ALTER TABLE user_settings ADD COLUMN agent_recursion_limit INTEGER DEFAULT 200"))+ logger.info("Added agent_recursion_limit column to user_settings")+# Migrate token_usage_metrics table - add cost columnsresult = await conn.execute(text("PRAGMA table_info(token_usage_metrics)"))columns = {row[1] for row in result.fetchall()}@@ -1572,6 +1576,7 @@ class Database:"default_llm_model": settings.default_llm_model,"auto_add_skill_for_tools": settings.auto_add_skill_for_tools,"auto_rebind_tools_after_canvas_change": settings.auto_rebind_tools_after_canvas_change,+ "agent_recursion_limit": settings.agent_recursion_limit,"created_at": settings.created_at.isoformat() if settings.created_at else None,"updated_at": settings.updated_at.isoformat() if settings.updated_at else None,}@@ -1619,6 +1624,8 @@ class Database:existing.auto_add_skill_for_tools = settings_data["auto_add_skill_for_tools"]if "auto_rebind_tools_after_canvas_change" in settings_data:existing.auto_rebind_tools_after_canvas_change = settings_data["auto_rebind_tools_after_canvas_change"]+ if "agent_recursion_limit" in settings_data:+ existing.agent_recursion_limit = settings_data["agent_recursion_limit"]else:# Create new settingsexisting = UserSettings(@@ -1637,6 +1644,7 @@ class Database:default_llm_model=settings_data.get("default_llm_model"),auto_add_skill_for_tools=settings_data.get("auto_add_skill_for_tools", True),auto_rebind_tools_after_canvas_change=settings_data.get("auto_rebind_tools_after_canvas_change", True),+ agent_recursion_limit=settings_data.get("agent_recursion_limit", 200),)session.add(existing)diff --git a/server/models/database.py b/server/models/database.pyindex 4cb09bb1..25801053 100644--- a/server/models/database.py+++ b/server/models/database.py@@ -248,7 +248,8 @@ class UserSettings(SQLModel, table=True):component_palette_default_open: bool = Field(default=True)console_panel_default_open: bool = Field(default=False)memory_window_size: int = Field(default=100) # Message pairs in short-term memory (1-100)- compaction_ratio: float = Field(default=0.5) # Fraction of context window triggering compaction (0.1-0.9)+ compaction_ratio: float = Field(default=0.8) # Fraction of context window triggering compaction (0.05-0.99). Mirrors COMPACTION_RATIO env default.+ agent_recursion_limit: int = Field(default=200) # Hard step cap for the agent loop. Mirrors AGENT_RECURSION_LIMIT env default.examples_loaded: bool = Field(default=False) # Track if example workflows were importedonboarding_completed: bool = Field(default=False) # Track if user completed or skipped onboardingonboarding_step: int = Field(default=0) # Last completed onboarding step (for resuming)diff --git a/server/nodes/tool/agent_builder/__init__.py b/server/nodes/tool/agent_builder/__init__.pyindex 71d70935..8cab5c38 100644--- a/server/nodes/tool/agent_builder/__init__.py+++ b/server/nodes/tool/agent_builder/__init__.py@@ -364,22 +364,88 @@ def _skill_folder_exists(skill_folder: str) -> bool:# -----------------------------------------------------------------------------def _find_wired_types(+async def _load_live_canvas(ctx: NodeContext,+) -> tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:+ """Reload the canvas snapshot from the persisted ``workflow.data``+ so successive agentBuilder operations in the SAME run see each+ other's mutations.++ The per-tool activity's ``ctx.nodes`` / ``ctx.edges`` is frozen at+ MachinaWorkflow start — without this reload, every add_tool /+ add_skill / add_subagent call inside a single AgentWorkflow run+ would see the same stale snapshot, ``_find_wired_types`` would+ never detect the just-spawned tool, and duplicates would pile up.++ Falls back to ``ctx.nodes`` / ``ctx.edges`` when ``ctx.workflow_id``+ is missing (standalone Run) or the DB lookup fails. Read-only —+ callers still pass the returned tuple into ``_find_wired_types``+ explicitly so the caller controls precedence.+ """+ if ctx.workflow_id:+ try:+ from services.plugin.deps import get_database++ database = get_database()+ workflow = await database.get_workflow(ctx.workflow_id)+ if workflow is not None and workflow.data:+ nodes = list(workflow.data.get("nodes") or [])+ edges = list(workflow.data.get("edges") or [])+ return nodes, edges+ except Exception as exc: # noqa: BLE001 — defensive: fall back to ctx+ logger.debug(+ "[agentBuilder] live canvas reload failed for %s: %s",+ ctx.workflow_id,+ exc,+ )+ return list(ctx.nodes or []), list(ctx.edges or [])+++def _resolve_caller_from(+ self_id: str,+ edges: List[Dict[str, Any]],+) -> str:+ """``_resolve_caller`` variant that takes an explicit edges list so+ callers can resolve against the freshly-reloaded canvas instead of+ ``ctx.edges`` (frozen at workflow start)."""+ for edge in edges or []:+ if edge.get("source") == self_id and edge.get("targetHandle") == _TOOL_HANDLE:+ target = edge.get("target")+ if target:+ logger.info(+ "[agentBuilder] caller resolved (live canvas): self=%s -> agent=%s",+ self_id,+ target,+ )+ return target+ logger.info(+ "[agentBuilder] no input-tools edge found from %s; falling back to self as caller (canvas: %d nodes? edges=%d)",+ self_id,+ 0,+ len(edges or []),+ )+ return self_id+++def _find_wired_types(+ nodes: List[Dict[str, Any]],+ edges: List[Dict[str, Any]],target_node_id: str,target_handle: str,) -> Dict[str, str]:- """Walk ``ctx.edges`` for edges arriving at ``target_node_id`` on+ """Walk ``edges`` for entries arriving at ``target_node_id`` on``target_handle`` and return ``{source_node_type: source_node_id}``for every match.- Used by ``add_tool`` / ``add_subagent`` to detect already-wired- nodes before spawning duplicates. Sync + ctx-only (no DB) — same- lightweight pattern as :func:`_resolve_caller`.+ Accepts explicit ``nodes`` / ``edges`` lists so callers can hand in+ a freshly-reloaded canvas (via :func:`_load_live_canvas`) instead+ of the per-tool activity's stale ``ctx`` snapshot. Without this the+ same agentBuilder run can't detect tools it added moments ago in+ the same iteration."""- nodes_by_id = {n.get("id"): n for n in (ctx.nodes or []) if n.get("id")}+ nodes_by_id = {n.get("id"): n for n in (nodes or []) if n.get("id")}wired: Dict[str, str] = {}- for edge in ctx.edges or []:+ for edge in edges or []:if edge.get("target") != target_node_id:continueif edge.get("targetHandle") != target_handle:@@ -693,9 +759,11 @@ class AgentBuilderNode(ToolNode):params: AgentBuilderParams,) -> AgentBuilderOutput:_log_op_entry("inspect_canvas", ctx)- nodes = list(ctx.nodes or [])- edges = list(ctx.edges or [])- caller_id = _resolve_caller(ctx)+ # Reload from DB so the snapshot reflects any in-run mutations+ # (per-tool ctx is frozen at MachinaWorkflow start, so without+ # this the LLM never sees nodes it added moments ago).+ nodes, edges = await _load_live_canvas(ctx)+ caller_id = _resolve_caller_from(ctx.node_id, edges)type_by_id = {n.get("id"): n.get("type") for n in nodes}node_summaries = [@@ -794,12 +862,16 @@ class AgentBuilderNode(ToolNode):operations=[],)- caller_id = _resolve_caller(ctx)+ # Reload the canvas from DB so duplicate detection sees any+ # tool the LLM just spawned earlier in THIS run. The ctx+ # snapshot is frozen at MachinaWorkflow start.+ live_nodes, live_edges = await _load_live_canvas(ctx)+ caller_id = _resolve_caller_from(ctx.node_id, live_edges)# Idempotent duplicate check — if this tool type is already wired# to the caller's input-tools handle, reuse the existing instance# rather than spawning another. Surfaces the existing node id in# the summary so the LLM knows it CAN call the tool.- existing_tools = _find_wired_types(ctx, caller_id, _TOOL_HANDLE)+ existing_tools = _find_wired_types(live_nodes, live_edges, caller_id, _TOOL_HANDLE)if node_type in existing_tools:return AgentBuilderOutput(operation="add_tool",@@ -858,9 +930,10 @@ class AgentBuilderNode(ToolNode):operations=[],)- nodes = list(ctx.nodes or [])- edges = list(ctx.edges or [])- caller_id = _resolve_caller(ctx)+ # Reload from DB so we see any masterSkill spawned earlier in+ # the same run (or skill already toggled on in this run).+ nodes, edges = await _load_live_canvas(ctx)+ caller_id = _resolve_caller_from(ctx.node_id, edges)skill_edge = next((e for e in edges if e.get("target") == caller_id and e.get("targetHandle") == _SKILL_HANDLE),@@ -946,8 +1019,10 @@ class AgentBuilderNode(ToolNode):operations=[],)- nodes = list(ctx.nodes or [])- caller_id = _resolve_caller(ctx)+ # Reload from DB so duplicate detection sees teammates spawned+ # earlier in the same run.+ nodes, edges = await _load_live_canvas(ctx)+ caller_id = _resolve_caller_from(ctx.node_id, edges)caller = next((n for n in nodes if n.get("id") == caller_id), None)caller_type = (caller or {}).get("type") or ""@@ -978,7 +1053,7 @@ class AgentBuilderNode(ToolNode):)# Idempotent duplicate check — see add_tool above for rationale.- existing_teammates = _find_wired_types(ctx, caller_id, _TEAMMATES_HANDLE)+ existing_teammates = _find_wired_types(nodes, edges, caller_id, _TEAMMATES_HANDLE)if agent_type in existing_teammates:return AgentBuilderOutput(operation="add_subagent",diff --git a/server/services/ai.py b/server/services/ai.pyindex 37ad52da..87454ca6 100644--- a/server/services/ai.py+++ b/server/services/ai.py@@ -1827,14 +1827,18 @@ class AIService:# default is True; lookup failures fall back to True so the# feature doesn't silently disable itself on a transient DB hiccup.auto_rebind_enabled = True+ user_recursion_limit: Optional[int] = Nonetry:user_settings = await self.database.get_user_settings()if user_settings is not None:auto_rebind_enabled = bool(user_settings.get("auto_rebind_tools_after_canvas_change", True))+ _raw_limit = user_settings.get("agent_recursion_limit")+ if isinstance(_raw_limit, int) and _raw_limit > 0:+ user_recursion_limit = _raw_limitexcept Exception as exc: # noqa: BLE001 — defensive read- logger.debug("[Agent] auto_rebind settings read failed: %s", exc)+ logger.debug("[Agent] user_settings read failed: %s", exc)async def _rebind_from_operations(operations: List[Dict[str, Any]]) -> List[Any]:"""Translate workflow_ops add_node ops (component_kind='tool')@@ -1916,16 +1920,20 @@ class AIService:},)- # Run the agent loop. ``recursion_limit`` (read from- # llm_defaults.json:agent.recursion_limit) is the hard cap on- # how many LLM turns the loop will run. The real termination- # signal is the LLM returning a final response without tool- # calls; this cap is the safety backstop. On hit, the loop- # appends a synthetic terminal AIMessage so downstream- # extraction returns a usable partial response.+ # Run the agent loop. ``recursion_limit`` precedence:+ # 1. ``UserSettings.agent_recursion_limit`` (per-user)+ # 2. ``Settings.agent_recursion_limit`` env var (global default)+ # 3. ``llm_defaults.json:agent.recursion_limit`` (legacy fallback)+ # The real termination signal is the LLM returning a final+ # response without tool_calls; this cap is the safety backstop.+ # On hit, the loop appends a synthetic terminal AIMessage so+ # downstream extraction returns a usable partial response.from services.model_registry import get_model_registry- recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])+ if user_recursion_limit is not None:+ recursion_limit = user_recursion_limit+ else:+ recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])async def _emit_progress(iter_count: int) -> None:if broadcaster:@@ -2349,16 +2357,21 @@ class AIService:logger.error(f"[ChatAgent] Tool execution failed: {tool_name}", error=str(e))return {"error": str(e)}- # Auto-rebind toggle: same machinery as ``execute_agent``.+ # Auto-rebind toggle + recursion_limit override: same+ # machinery as ``execute_agent``.auto_rebind_enabled = True+ user_recursion_limit: Optional[int] = Nonetry:user_settings = await self.database.get_user_settings()if user_settings is not None:auto_rebind_enabled = bool(user_settings.get("auto_rebind_tools_after_canvas_change", True))+ _raw_limit = user_settings.get("agent_recursion_limit")+ if isinstance(_raw_limit, int) and _raw_limit > 0:+ user_recursion_limit = _raw_limitexcept Exception as exc: # noqa: BLE001 — defensive read- logger.debug("[ChatAgent] auto_rebind settings read failed: %s", exc)+ logger.debug("[ChatAgent] user_settings read failed: %s", exc)async def _rebind_from_operations(operations: List[Dict[str, Any]]) -> List[Any]:"""Mirror of execute_agent._rebind_from_operations — see that@@ -2409,10 +2422,13 @@ class AIService:# Run the agent loop. See ``execute_agent`` for the# rationale on ``recursion_limit`` + the truncation- # behaviour on hit.+ # behaviour on hit. Precedence: UserSettings > env.from services.model_registry import get_model_registry- recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])+ if user_recursion_limit is not None:+ recursion_limit = user_recursion_limit+ else:+ recursion_limit = int(get_model_registry().get_agent_defaults()["recursion_limit"])async def _emit_progress(iter_count: int) -> None:if broadcaster:diff --git a/server/services/model_registry.py b/server/services/model_registry.pyindex 6b841f88..1fb96f13 100644--- a/server/services/model_registry.py+++ b/server/services/model_registry.py@@ -562,14 +562,32 @@ class ModelRegistryService:self._llm_defaults = {"providers": {}}def get_agent_defaults(self) -> Dict[str, Any]:- """Return the ``agent`` block from ``llm_defaults.json``.-- Holds runtime defaults shared across the agent executor and- compaction layer (e.g. ``recursion_limit``, ``compaction.ratio``).- Callers should ``.get(...)`` with their own fallback so the system- still boots if the JSON is missing or partial.+ """Return the ``agent`` block defaults (recursion_limit,+ compaction.ratio, default_temperature).++ Source-of-truth order:+ 1. Environment via ``core.config.Settings``+ (``AGENT_RECURSION_LIMIT`` / ``COMPACTION_RATIO``) — wins.+ 2. ``server/config/llm_defaults.json:agent`` block — fallback+ when Settings can't be instantiated (e.g. one-off CLI+ scripts that bypass it).++ Per-user ``UserSettings.agent_recursion_limit`` /+ ``compaction_ratio`` overrides are applied by the caller at+ request time — this helper returns the GLOBAL defaults only."""- return self._llm_defaults.get("agent", {})+ block = dict(self._llm_defaults.get("agent", {}))+ try:+ from core.config import Settings++ settings = Settings()+ block["recursion_limit"] = int(settings.agent_recursion_limit)+ compaction = dict(block.get("compaction") or {})+ compaction["ratio"] = float(settings.compaction_ratio)+ block["compaction"] = compaction+ except Exception: # noqa: BLE001 — defensive: keep JSON fallback usable+ pass+ return blockdef _get_default_max_output_tokens(self, provider: str, model: str) -> int:"""Fallback: get max output tokens from llm_defaults.json."""diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.pyindex 38ba9803..c00cf306 100644--- a/server/services/temporal/agent_activities.py+++ b/server/services/temporal/agent_activities.py@@ -35,7 +35,7 @@ References:from __future__ import annotationsimport logging-from typing import Any, Dict, List+from typing import Any, Dict, List, Optionalfrom temporalio import activity@@ -642,19 +642,39 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:prompt = str(out[field])break- # Read the user toggle for mid-loop tool rebinding once at prep- # time. ``AgentWorkflow.run`` reads it from the returned payload and- # forwards into per-tool activity payloads so agentBuilder + the- # workflow's own rebind branch see the same value.+ # Read user-overridable globals once at prep time.+ # - auto_rebind_tools: forwarded into every per-tool activity so+ # agentBuilder's summary + the workflow rebind branch read the+ # same value.+ # - agent_recursion_limit: applied to the agent loop's hard step+ # cap. Per-user override beats env Settings.auto_rebind_tools = True+ settings_recursion_limit: Optional[int] = Nonetry:user_settings = await database.get_user_settings()if user_settings is not None:auto_rebind_tools = bool(user_settings.get("auto_rebind_tools_after_canvas_change", True))+ raw_limit = user_settings.get("agent_recursion_limit")+ if isinstance(raw_limit, int) and raw_limit > 0:+ settings_recursion_limit = raw_limitexcept Exception as exc: # noqa: BLE001 — defensive read- activity.logger.debug(f"auto_rebind settings read failed: {exc}")+ activity.logger.debug(f"user_settings read failed: {exc}")++ # Precedence: per-node parameter > per-user UserSettings > env Settings.+ node_param_limit = parameters.get("max_iterations")+ if isinstance(node_param_limit, int) and node_param_limit > 0:+ effective_recursion_limit = node_param_limit+ elif settings_recursion_limit is not None:+ effective_recursion_limit = settings_recursion_limit+ else:+ from core.config import Settings as _Settings++ try:+ effective_recursion_limit = int(_Settings().agent_recursion_limit)+ except Exception: # noqa: BLE001 — last-resort fallback+ effective_recursion_limit = 200return {"node_id": node_id,@@ -672,7 +692,7 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:"memory_node_id": memory_node_id,"memory_content": memory_content,"memory_window_size": memory_window_size,- "max_iterations": int(parameters.get("max_iterations") or 50),+ "max_iterations": effective_recursion_limit,"thinking_config": thinking_config_dict,"compaction_threshold": compaction_threshold,"auto_rebind_tools": auto_rebind_tools,diff --git a/server/services/temporal/agent_workflow.py b/server/services/temporal/agent_workflow.pyindex f4c451c7..95981341 100644--- a/server/services/temporal/agent_workflow.py+++ b/server/services/temporal/agent_workflow.py@@ -73,8 +73,25 @@ TOOL_STEP_TIMEOUT = timedelta(minutes=10)TOOL_HEARTBEAT_TIMEOUT = timedelta(minutes=2)# Bounded loop count to defend against a runaway LLM. Plugin classes-# can override via ``payload["max_iterations"]``; this is the hard cap.-DEFAULT_MAX_ITERATIONS = 50+# override via ``payload["max_iterations"]`` (set by+# ``prepare_agent_payload`` from Settings.agent_recursion_limit). This+# module-level fallback fires only if the payload omits the key, which+# should never happen — kept as a defensive backstop.+def _default_max_iterations() -> int:+ """Read the env-backed default once, fall back to JSON via+ ``model_registry.get_agent_defaults`` so this still works in+ one-off CLI scripts that bypass Settings."""+ try:+ from core.config import Settings++ return int(Settings().agent_recursion_limit)+ except Exception: # noqa: BLE001+ try:+ from services.model_registry import get_model_registry++ return int(get_model_registry().get_agent_defaults().get("recursion_limit") or 200)+ except Exception: # noqa: BLE001+ return 200# Retry policy for the agent's own activities (LLM step, persist,# compact). Tool activities use their plugin's policy. Wave 12 D1:@@ -200,7 +217,7 @@ class AgentWorkflow:tools = payload.get("tools") or []tool_index: Dict[str, Dict[str, Any]] = {t["name"]: t for t in tools}- max_iterations = int(payload.get("max_iterations") or DEFAULT_MAX_ITERATIONS)+ max_iterations = int(payload.get("max_iterations") or _default_max_iterations())token_total = 0compaction_threshold = payload.get("compaction_threshold")thinking_accumulated = ""diff --git a/server/tests/nodes/test_agent_builder.py b/server/tests/nodes/test_agent_builder.pyindex 3d6556b6..c55cfc92 100644--- a/server/tests/nodes/test_agent_builder.py+++ b/server/tests/nodes/test_agent_builder.py@@ -845,6 +845,74 @@ class TestDbPersistence:assert add_node_op["minted_id"] in persisted_ids+class TestInRunCanvasReload:+ """Within a single AgentWorkflow run, ``ctx.nodes`` / ``ctx.edges``+ is frozen at MachinaWorkflow start — so the SECOND agentBuilder+ call inside the run wouldn't see the FIRST call's mutation just+ by reading ``ctx``. Each operation now reloads ``workflow.data``+ from the DB via ``_load_live_canvas`` so duplicate detection+ catches in-run repeats, not just cross-run repeats."""++ async def test_add_tool_uses_db_reload_for_duplicate_check(self):+ """ctx has empty edges (simulating frozen-at-run-start+ snapshot) but the DB has the httpRequest already wired+ (simulating an earlier-in-run add_tool that persisted). The+ reload must see the DB state and return idempotent success+ instead of spawning a duplicate."""+ node = ab.AgentBuilderNode()+ # ctx looks like a fresh workflow — no tools wired anywhere.+ # Only the agentBuilder->agent input-tools edge that+ # _resolve_caller needs.+ ctx = _make_ctx(+ nodes=[+ _agent_node("agent-1"),+ {"id": "ab-1", "type": "agentBuilder", "data": {"label": "AB"}},+ ],+ edges=[_edge("ab-1", "agent-1", "input-tools")],+ workflow_id="wf-test",+ )+ params = ab.AgentBuilderParams(operation="add_tool", node_type="httpRequest")++ # DB reflects the prior in-run add_tool mutation: httpRequest+ # node spawned + edge to agent-1.+ live_workflow = SimpleNamespace(+ name="Test",+ slug="Test_1",+ description="",+ data={+ "nodes": [+ {"id": "agent-1", "type": "aiAgent"},+ {"id": "ab-1", "type": "agentBuilder"},+ {"id": "http-existing", "type": "httpRequest"},+ ],+ "edges": [+ {"source": "ab-1", "target": "agent-1", "targetHandle": "input-tools"},+ {"source": "http-existing", "target": "agent-1", "targetHandle": "input-tools"},+ ],+ },+ )+ mock_db = MagicMock()+ mock_db.get_workflow = AsyncMock(return_value=live_workflow)+ mock_db.save_workflow = AsyncMock(return_value=True)+ mock_container = MagicMock()+ mock_container.database.return_value = mock_db++ with (+ patch.object(ab, "registered_node_classes", return_value=_registry(httpRequest="tool")),+ patch("core.container.container", mock_container),+ ):+ result = await node.add_tool(ctx, params)++ # Duplicate detected via DB reload — not via ctx.edges (which+ # didn't have httpRequest).+ assert result.operations == []+ assert "already wired" in result.summary+ assert "http-existing" in result.summary+ # save_workflow must NOT be called on the idempotent path —+ # no mutation to persist.+ mock_db.save_workflow.assert_not_called()++class TestDuplicateDetection:async def test_add_tool_is_idempotent_when_already_wired(self):"""If the caller already has a node of the requested type wired