Skip to content

Self-improving AI Employees for everyone

feat(agent): env-sourced agent defaults + in-run canvas reload + docs refresh

trohitgc14c54bea9f2
diff --git a/.env.template b/.env.template
index 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=false
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 window
compaction_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:**
```python
api_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:**
```python
openai_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_service
svc = 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 threshold
anthropic_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 Tracking
diff --git a/client/src/components/ui/SettingsPanel.tsx b/client/src/components/ui/SettingsPanel.tsx
index 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.ts
index 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): Work
maxProcesses: 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.md
index 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 in
services/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; broadcast
node_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 messages
with 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.md
index 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 functi
3. `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, da
registry['claude_code_agent'] = partial(handle_claude_code_agent, ...)
```
-### Temporal dispatch routing (post-F4)
+### Temporal dispatch routing
Two 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.md
index 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 Override
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index 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 sites
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index 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`) calls
diff --git a/docs-internal/workflow_ops_protocol.md b/docs-internal/workflow_ops_protocol.md
index 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 modes
diff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.json
index 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.py
index 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.py
index 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 columns
result = 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 settings
existing = 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.py
index 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 imported
onboarding_completed: bool = Field(default=False) # Track if user completed or skipped onboarding
onboarding_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__.py
index 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:
continue
if 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.py
index 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] = None
try:
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_limit
except 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] = None
try:
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_limit
except 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.py
index 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 block
def _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.py
index 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 annotations
import logging
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
from 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] = None
try:
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_limit
except 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 = 200
return {
"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.py
index 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 = 0
compaction_threshold = payload.get("compaction_threshold")
thinking_accumulated = ""
diff --git a/server/tests/nodes/test_agent_builder.py b/server/tests/nodes/test_agent_builder.py
index 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