Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
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.mdindex 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 adeterministic 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 itsprovider-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 InjectionThe 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.pydef _build_skill_system_prompt(skill_data, log_prefix="[Agent]") -> tuple:from services.skill_prompt import build_skill_system_promptreturn build_skill_system_prompt(skill_data, log_prefix)@@ -463,15 +474,18 @@ full transcript, and nothing else about the request changes because a Contextnode 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 declaresit; `normalize_workflow_graph` rewrites legacy `simpleMemory -> input-memory`edges into a Context node plus an ordinary tool edge. The legacy markdownmemory path (`memory_data`, `parse_memory_markdown`,`append_to_memory_markdown`, `trim_markdown_window`, the vector store) isreached only for `input-memory` graphs: `execute_agent` passes the tuple'sfirst 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 trackingand compaction thresholds are in [memory_compaction.md](memory_compaction.md).---diff --git a/docs-internal/agent_delegation.md b/docs-internal/agent_delegation.mdindex 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.mdindex 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 PointIn `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 saveif 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 Decisionsdiff --git a/server/services/agent_runtime.py b/server/services/agent_runtime.pyindex 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__.pyindex 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: F401from services.llm.providers import openai # noqa: F401from services.llm.providers import gemini # noqa: F401from 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.mdindex 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