Skip to content

Self-improving AI Employees for everyone

docs(agents): correct stale statements in agent, delegation and skill docs

trohitgc7125880995e
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index 356878c6..f5e330ac 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -90,7 +90,7 @@ Result broadcast via WebSocket
| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (the renamed `_collect_agent_connections`), `format_task_context()` |
| `server/nodes/agent/_inline.py` | `prepare_agent_call()` — task-context injection + auto-prompt fallback + teammate collection; calls `collect_agent_connections` then `ai_service.execute_[chat_]agent` |
| `server/nodes/agent/<plugin>/__init__.py` | Per-plugin `execute_op()` (Wave 11 replaced `handle_ai_agent` / `handle_chat_agent`) |
-| `server/services/ai.py` | `AIService` facade -- skill injection (`_build_skill_system_prompt`, line 273), tool building, context/memory and execution-boundary handling |
+| `server/services/ai.py` | `AIService` facade -- skill injection (`_build_skill_system_prompt`), tool building, context/memory and execution-boundary handling |
| `server/services/skill_prompt.py` | `build_skill_system_prompt` -- the only skill-to-system-message path (personality bodies only) |
| `server/services/agent_runtime.py` | `AgentToolSpec`, `run_native_llm_step`, and `run_native_agent_loop` |
| `server/services/llm/` | `ChatUnifier`, provider-neutral messages/tool definitions, and native provider SDK adapters |
@@ -123,6 +123,8 @@ is involved — each iteration:
dispatch it through `tool_executor`, and append a native
`Message(role="tool", tool_call_id=...)`. Malformed arguments become a
deterministic tool error containing `raw_arguments` rather than crashing.
+ An external tool's result text is cut to `tool_output_limit` characters
+ before it is appended (see Signature below).
Results containing workflow `operations` are passed to
`rebind_from_operations`; returned `AgentToolSpec` values extend
`current_tools` for the next request.
@@ -155,16 +157,24 @@ async def run_native_agent_loop(
Callable[[int, LLMResponse, List[Message]], Awaitable[Optional[List[Message]]]]
] = None,
conversation_saver: Optional[Callable[[List[Message]], Awaitable[None]]] = None,
+ tool_output_limit: Optional[int] = None,
) -> Dict[str, Any]:
"""Returns messages, iteration, thinking, truncation, usage, and response."""
```
-(`services/agent_runtime.py:190-216`.) The three trailing keywords are the
-RFC-0002 hooks: `context_management` is forwarded to the provider step (the
-Anthropic compaction edit), `compaction_pause_callback` lets the caller swap
-the message list after a provider-side compaction pause, and
-`conversation_saver` persists the full transcript after every turn through
-the plain conversation store (see [agent_context_flow.md](agent_context_flow.md)).
+(`run_native_agent_loop` in `services/agent_runtime.py`.) `context_management`,
+`compaction_pause_callback` and `conversation_saver` are the RFC-0002 hooks:
+`context_management` is forwarded to the provider step (the Anthropic
+compaction edit), `compaction_pause_callback` lets the caller swap the
+message list after a provider-side compaction pause, and `conversation_saver`
+persists the full transcript after every turn through the plain conversation
+store (see [agent_context_flow.md](agent_context_flow.md)).
+`tool_output_limit` caps, in characters, what one external tool result adds
+to `messages` (`bound_tool_output` in `services/tool_output.py`; `None` or `0`
+keeps results whole). Delegated-agent answers, skill loads and Task Manager
+results are exempt (`tool_output_is_capped`). `execute_agent` /
+`execute_chat_agent` pass the resolved Tool Result Limit; see
+[agent_context_flow.md → Transcript size](agent_context_flow.md).
There is no mutable model binding step. Each native LLM request derives its
provider-facing declarations from the current `AgentToolSpec.definition`
@@ -177,6 +187,7 @@ next iteration.
| Trigger | What happens |
|---|---|
| LLM emits no `tool_calls` | Return with `truncated: False`. This is the normal exit. |
+| `finish_reason == "compaction"` with no `tool_calls` | **Not** an exit. Anthropic's durability pause returns only a compaction block; it has already been saved, so the loop calls `compaction_pause_callback` (when given, its non-`None` return replaces `messages`) and continues to the next iteration. |
| `tool_executor` is `None` but LLM emits tool calls | WARN + return (treat as final). |
| `iteration` reaches `max_iterations` | Append a synthetic native assistant `Message` + return with `truncated: True`. |
@@ -378,14 +389,14 @@ metadata:
### 5. System Message Injection
The only path from `skill_data` to the system message is
-`_build_skill_system_prompt` (`server/services/ai.py:273`), a thin wrapper
-that imports and calls `services/skill_prompt.py::build_skill_system_prompt`.
-It is called from `execute_agent` (`ai.py:917`), `execute_chat_agent`
-(`ai.py:1633`), the RLM service (`services/rlm/service.py:74-77`) and the
-Temporal `agent.prepare_payload` activity (`agent_activities.py:971-973`):
+`_build_skill_system_prompt` (module-level in `server/services/ai.py`), a thin
+wrapper that imports and calls `services/skill_prompt.py::build_skill_system_prompt`.
+It is called from `execute_agent`, `execute_chat_agent`, the RLM service
+(`services/rlm/service.py`) and the Temporal `agent.prepare_payload` activity
+(`services/temporal/agent_activities.py`):
```python
-# server/services/ai.py:273
+# server/services/ai.py
def _build_skill_system_prompt(skill_data, log_prefix="[Agent]") -> tuple:
from services.skill_prompt import build_skill_system_prompt
return build_skill_system_prompt(skill_data, log_prefix)
@@ -463,15 +474,18 @@ full transcript, and nothing else about the request changes because a Context
node is attached.
`simpleMemory` ("Memory") is **not** conversation history: it is a `ToolNode`
-on `input-tools` that the agent calls explicitly (`remember` / `recall` /
-`update` / `forget`). The `input-memory` handle is retired — no agent declares
+on `input-tools` that the agent calls explicitly (its `operation` argument
+takes the `MemoryOperation` values in `server/nodes/tool/simple_memory/`:
+`remember` / `recall` / `list` / `get` / `update` / `forget`). The
+`input-memory` handle is retired — no agent declares
it; `normalize_workflow_graph` rewrites legacy `simpleMemory -> input-memory`
edges into a Context node plus an ordinary tool edge. The legacy markdown
memory path (`memory_data`, `parse_memory_markdown`,
`append_to_memory_markdown`, `trim_markdown_window`, the vector store) is
reached only for `input-memory` graphs: `execute_agent` passes the tuple's
first element as `context_data` to `_prepare_context` and sets `memory_data =
-None` whenever a Context runtime resolves (`ai.py:969-980`). Token tracking
+None` whenever a Context runtime resolves (the `context_runtime is not None`
+branch right after the `_prepare_context` call). Token tracking
and compaction thresholds are in [memory_compaction.md](memory_compaction.md).
---
diff --git a/docs-internal/agent_delegation.md b/docs-internal/agent_delegation.md
index 4c97d59e..e102f9f6 100644
--- a/docs-internal/agent_delegation.md
+++ b/docs-internal/agent_delegation.md
@@ -66,7 +66,7 @@ Parent continues reasoning Child runs independently
| Finds child's own memory/skills/tools/task
|
AIService.execute_agent() / execute_chat_agent()
- | Uses child's provider/model/system_message
+ | Uses child's provider/model
| Uses child's memory (isolated session)
| Uses child's skills + tools
| system_message = delegated task,
@@ -93,7 +93,7 @@ for tool_info in tool_data:
For agent node types, the method:
-1. Resolves the tool name via `_resolve_default_tool_name_description(node_type)` — a closure inside `_build_tool_from_node()` that reads the plugin class's `tool_name` ClassVar (each agent plugin declares `tool_name = "delegate_to_<x>"`). There is no central `DEFAULT_TOOL_NAMES` dict; the name comes from the plugin class via `services.node_registry.get_node_class`. The delegation branch is gated by `_get_tool_schema()`'s `_AGENT_DELEGATION_TYPES` tuple (`services/ai.py:2509-2528`) — **18 agents**: the 15 standard delegatable agents (`aiAgent`, `chatAgent`, `android_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`, `consumer_agent`, `autonomous_agent`, `orchestrator_agent`, `ai_employee`), the two bypass-loop agents `rlm_agent` and `claude_code_agent`, and the bridged cloud agent `vertex_managed_agent`. (`AI_AGENT_TYPES` in `server/constants.py:32-53` mirrors this same 18-entry set; `codex_agent` is not currently in it. The `tool_name = f"delegate_to_{cls.type}"` default is stamped by `BaseNode.__init_subclass__`, `services/plugin/base.py:257`, so only `aiAgent`, `chatAgent` and `vertex_managed_agent` declare it explicitly.)
+1. Resolves the tool name via `_resolve_default_tool_name_description(node_type)` — a closure inside `_build_tool_from_node()` that reads the plugin class's `tool_name` ClassVar (each agent plugin declares `tool_name = "delegate_to_<x>"`). There is no central `DEFAULT_TOOL_NAMES` dict; the name comes from the plugin class via `services.node_registry.get_node_class`. The delegation branch is gated by `_get_tool_schema()`'s `_AGENT_DELEGATION_TYPES` tuple (local to that method in `services/ai.py`) — **18 agents**: the 15 standard delegatable agents (`aiAgent`, `chatAgent`, `android_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`, `consumer_agent`, `autonomous_agent`, `orchestrator_agent`, `ai_employee`), the two bypass-loop agents `rlm_agent` and `claude_code_agent`, and the bridged cloud agent `vertex_managed_agent`. (the `AI_AGENT_TYPES` frozenset in `server/constants.py` mirrors this same 18-entry set; `codex_agent` is not currently in it. The `tool_name = f"delegate_to_{cls.type}"` default is stamped by `BaseNode.__init_subclass__` in `services/plugin/base.py`, so only `aiAgent`, `chatAgent` and `vertex_managed_agent` declare it explicitly.)
2. Creates a `DelegateToAgentSchema` Pydantic model in `_get_tool_schema()` with two fields (`task` -> the child's mission directive / system message, `context` -> the child's input data / prompt):
```python
@@ -198,7 +198,7 @@ A `(parent_node_id, node_id, task_hash)` duplicate guard (`_active_delegations`)
child_params = await database.get_node_parameters(node_id) or {}
```
-The child's stored parameters (provider, model, system message, etc.) come from the database -- whatever the user configured in the child node's parameter panel. They are NOT inherited from the parent.
+The child's stored parameters (provider, model, temperature, etc.) come from the database -- whatever the user configured in the child node's parameter panel. They are NOT inherited from the parent. The stored `system_message` and `prompt` are loaded here too, but step 4e overwrites both with the delegated `task` / `context`.
**4c. Inject API key if missing:**
```python
@@ -327,8 +327,8 @@ The child now executes with:
| Resource | Source |
|----------|--------|
-| Prompt | Delegated task from parent's LLM |
-| System message | Child's own (from its DB params) |
+| Prompt | Delegated `context` from parent's LLM (falls back to `task`) |
+| System message | Delegated `task` from parent's LLM (replaces the child's stored system message) |
| Provider / model | Child's own (from its DB params) |
| API key | Injected from credential store based on child's provider |
| Temperature / max tokens | Child's own (from its DB params) |
@@ -368,8 +368,8 @@ If the child has **no memory node connected**, it has no conversation history an
| Parameter | How it arrives |
|-----------|---------------|
-| `task` (string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call |
-| `context` (optional string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call |
+| `task` (string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call; becomes the child's `system_message` |
+| `context` (optional string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call; becomes the child's `prompt` (falls back to `task`) |
| `workflow_id` | Injected by tool_executor callback from parent's execution context |
| `nodes` / `edges` | Injected by tool_executor callback -- ALL workflow nodes and edges |
| `ai_service` / `database` | Injected by tool_executor callback -- shared instances (by reference) |
@@ -380,7 +380,6 @@ If the child has **no memory node connected**, it has no conversation history an
|-----------|--------|
| `provider` | Child's DB params (e.g., `'openai'`, `'anthropic'`) |
| `model` | Child's DB params (e.g., `'gpt-4o'`), or first stored model as fallback |
-| `systemMessage` | Child's DB params |
| `temperature` | Child's DB params |
| `max_tokens` / `maxTokens` | Child's DB params |
| `thinkingEnabled` / `thinkingBudget` | Child's DB params |
@@ -391,7 +390,8 @@ If the child has **no memory node connected**, it has no conversation history an
### What the parent does NOT pass
-- Provider, model, temperature, max tokens, system message
+- Provider, model, temperature, max tokens
+- The parent's own system message (the child's stored one is replaced by the delegated `task` instead)
- Memory or conversation history
- Skills or skill instructions
- Tool configurations
@@ -529,7 +529,7 @@ Every delegated agent broadcasts status at key phases via WebSocket:
|-------|------|-------------|
| `delegated_task` | Child starts executing | Child's node ID |
| `initializing` | Creating LLM model | Child's node ID |
-| `loading_memory` | Parsing markdown history | Child's node ID |
+| `loading_memory` | Parsing markdown history (legacy `input-memory` graphs only; not emitted when a Context node resolves) | Child's node ID |
| `building_tools` | Converting tool nodes to `AgentToolSpec` values | Child's node ID |
| `invoking_llm` | Calling model | Child's node ID |
| `executing_tool` | Running a tool called by child's LLM | Tool node ID |
diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.md
index a0b934d5..0fee58a0 100644
--- a/docs-internal/memory_compaction.md
+++ b/docs-internal/memory_compaction.md
@@ -408,13 +408,13 @@ usage = final_state["usage"]
### In-Process Persistence Point
In `server/services/ai.py`, the in-process path calls the service only when a
-legacy memory session id was resolved earlier in the run (`session_id` is set
-from `memory_data["session_id"]` at `ai.py:1006`; it stays `None` once a
-Context runtime resolves, because `execute_agent` nulls `memory_data` in that
-case):
+legacy memory session id was resolved earlier in the run (`execute_agent`
+sets `session_id` from `memory_data["session_id"]` while building the initial
+messages; it stays `None` once a Context runtime resolves, because
+`execute_agent` nulls `memory_data` in that case):
```python
-# ai.py:1430-1446 — after native agent-loop execution, before memory save
+# execute_agent in ai.py — after native agent-loop execution, before memory save
if session_id and ai_response:
compaction_result = await self._track_token_usage(
session_id=session_id,
@@ -442,7 +442,7 @@ if session_id and ai_response:
| `server/core/database.py` | CRUD methods for metrics and events |
| `server/core/config.py` | Environment variable configuration |
| `server/core/container.py` | Dependency injection setup |
-| `server/services/settings/handlers.py` | WebSocket handlers `get_compaction_stats` (line 215) and `configure_compaction` (line 233); registered into `MESSAGE_HANDLERS` by `routers/websocket.py` |
+| `server/services/settings/handlers.py` | WebSocket handlers `get_compaction_stats` (`handle_get_compaction_stats`) and `configure_compaction` (`handle_configure_compaction`); registered into `MESSAGE_HANDLERS` by `routers/websocket.py` |
| `server/main.py` | Service initialization on startup |
## Design Decisions
diff --git a/server/services/agent_runtime.py b/server/services/agent_runtime.py
index 561a8866..db8a56d8 100644
--- a/server/services/agent_runtime.py
+++ b/server/services/agent_runtime.py
@@ -432,7 +432,8 @@ async def run_native_agent_loop(
role="assistant",
content=(
f"[Recursion limit reached: {max_iterations} iterations. "
- "Adjust agent.recursion_limit in llm_defaults.json or simplify the task.]"
+ "Raise AI Agent Max Steps in Settings (env AGENT_RECURSION_LIMIT "
+ "is used only when no settings are saved) or simplify the task.]"
),
)
messages.append(terminal)
diff --git a/server/services/llm/providers/__init__.py b/server/services/llm/providers/__init__.py
index ab2b39f8..f92e029e 100644
--- a/server/services/llm/providers/__init__.py
+++ b/server/services/llm/providers/__init__.py
@@ -23,4 +23,4 @@ from services.llm.providers import anthropic # noqa: F401
from services.llm.providers import openai # noqa: F401
from services.llm.providers import gemini # noqa: F401
from services.llm.providers import openrouter # noqa: F401
-from services.llm.providers import _compat # noqa: F401 (registers 9 OpenAI-compat providers)
+from services.llm.providers import _compat # noqa: F401 (registers every name in _COMPAT_PROVIDERS, plus openai_compatible)
diff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.md
index cce50c83..7919af39 100644
--- a/server/skills/GUIDE.md
+++ b/server/skills/GUIDE.md
@@ -24,6 +24,7 @@ server/skills/
├── coding_agent/ # Code execution skills
│ python-skill, javascript-skill, monty-skill, file-read-skill,
│ file-modify-skill, fs-search-skill
+├── employee/ # Home Settings > Skills catalogue (see "The `employee` folder" below)
├── gcloud/ # gcloud-skill (Google Cloud CLI)
├── github/ # github-skill (gh CLI)
├── language_agent/ # speech-skill, translation-skill
@@ -128,7 +129,7 @@ The skill resolver (`SkillLoader._parse_skill_metadata`) takes each `allowed-too
## Optional Supporting Files
-Skills can include additional files that are loaded alongside the main instructions:
+Skills can include additional files that the model reads on demand after loading the skill:
```
server/skills/assistant/my-new-skill/
@@ -142,8 +143,13 @@ server/skills/assistant/my-new-skill/
└── examples.txt
```
-- **scripts/**: All files loaded as text, available to the AI as code context
-- **references/**: Only `.md`, `.txt`, `.json` files loaded as reference material
+- **scripts/**: Every top-level file is read as text and declared as a resource
+- **references/**: Only top-level `.md`, `.txt`, `.json` files are read and declared as resources
+
+Nothing here is executed or put into the prompt up front. `Skill.load` returns
+the instructions plus a manifest of these resources (`references/<file>`,
+`scripts/<file>`); the model then pulls their text through the same tool's
+`read_resource` / `search_resource` actions (`server/services/skill_runtime.py`).
## Creating a New Folder Group
@@ -186,9 +192,9 @@ Discover.
1. **Master Skill Node**: Select a folder from the dropdown. Enable/disable individual skills with checkboxes. Edit instructions inline.
-2. **Individual Skill Nodes**: Each built-in skill also has a dedicated node in the Component Palette (e.g. WhatsApp Skill, Memory Skill). These connect directly to an AI Agent's skill handle.
+2. **No per-skill nodes**: Master Skill is the only skill node (`SKILL_NODE_TYPES` in `server/constants.py`); it connects to an agent's `input-skill` handle. There are no dedicated palette nodes per built-in skill.
-3. **At Execution Time**: When the AI Agent runs, enabled skills' instructions are injected into the system prompt, giving the AI context about its available capabilities.
+3. **At Execution Time**: Only personality skills (names ending in `-personality`) are injected eagerly: their full instructions are appended to the system prompt (`server/services/skill_prompt.py`). Every other enabled skill uses progressive disclosure through the bound `Skill` tool (`server/services/skill_runtime.py`): the tool description carries a bounded name/description catalogue, `load` returns a skill's instructions and resource manifest, and `read_resource` / `search_resource` read its declared files. The system prompt is not changed for these skills.
## Skill Content Lifecycle