Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: align references with native LLM runtime
trohitgc8bfb6fb02fc
diff --git a/CLAUDE.md b/CLAUDE.mdindex 84a28447..f0a261a9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -19,10 +19,10 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern). 25 `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use). `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live count via `glob server/nodes/**/__init__.py`); handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `triggers.py` generic trigger-node handler, `todo.py` writeTodos shim — `google_auth.py` was retired into `nodes/google/_auth_helper.py`). **Wave 11.H added "self-contained plugin folders"** — up to six generic registries (`ws_handler_registry`, `register_router`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`) so rich plugins like telegram own their entire surface area without core-services edits. || **[Nodes Cookbook](./server/nodes/README.md)** | 5-minute recipe + folder map + shared helpers (`_base.py` / `_inline.py` per domain) + shared credentials + **canonical folder-per-plugin shape (telegram is the reference implementation)** + contract invariants + common pitfalls. Lives next to the plugin files. || **[Node Creation Guide](./docs-internal/node_creation.md)** | Canonical plugin recipe — one self-contained folder per plugin under `server/nodes/<group>/<plugin>/`, rooted at `__init__.py`. Multi-file split (`_service.py` / `_handlers.py` / etc.) when the plugin owns long-lived state. Zero frontend edits, zero core-services edits. Auto-registers via `BaseNode.__init_subclass__` + the six `register_*` hooks. Covers tool nodes, dual-purpose nodes (workflow + AI tool), and specialized agents as variations of the same recipe. |-| **[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 Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute through the provider-neutral `run_native_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). Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context_length; per-user UserSettings override exposed in Settings tab. |+| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Native usage aggregation plus shared client-side summarization through `ChatUnifier` for memory-connected agents. Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context length; see the document for the per-session override limitation on Temporal runs. || **[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 |@@ -46,7 +46,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Onboarding Service](./docs-internal/onboarding.md)** | First-launch welcome wizard with 5 steps, database persistence, and replay from Settings || **[CLI Services Integration](./docs-internal/cli_services_integration.md)** | Guide for integrating CLI-based services (Temporal, etc.) with proper lifecycle management || **[Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md)** | Distributed workflow execution: activities, FIRST_COMPLETED scheduling, horizontal scaling |-| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in services/llm/: Protocol-based providers, config-driven base URLs, 12 providers (xai native-chat-only; ollama/lmstudio local servers), native vs LangChain path routing |+| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in `services/llm/`: protocol-based providers, config-driven base URLs, and 12 providers (10 cloud plus Ollama / LM Studio; xAI is agent-selectable without a standalone chat-model node). LangChain is isolated to replay compatibility for legacy Temporal histories. || **[Event Waiter System](./docs-internal/event_waiter_system.md)** | In-memory asyncio.Future waiter for push-based trigger nodes on the canvas-Run path (WhatsApp, Telegram, Webhook, Chat, Task completion). Deployed triggers ride the Temporal canary path; the Redis-Streams backend was retired in Wave 15.3 || **[Credentials Encryption](./docs-internal/credentials_encryption.md)** | Fernet + PBKDF2 encryption pipeline, separate credentials.db, two credential systems (OAuth vs API keys), multi-backend abstraction || **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`, broadcast message types, Android two-state model |@@ -125,8 +125,8 @@ server/services/├── himalaya_service.py # HimalayaService CLI wrapper for IMAP/SMTP (any email provider)├── email_service.py # EmailService orchestrator (credential resolution, provider presets)├── todo_service.py # TodoService singleton for writeTodos tool (JSON per-session state)-├── memory.py # Markdown-based conversation memory helpers-├── memory_store.py # In-memory conversation store (LangChain 0.3+ compatible)+├── memory/ # Native Markdown/JSONL/runtime/vector-store helpers+├── memory_store.py # In-memory conversation sessions using native Message values├── skill_prompt.py # Skill system prompt builder (injects SKILL.md for personality skills)├── text.py # TextService (text generation nodes)├── chat_client.py # JSON-RPC 2.0 WebSocket client for chat backend@@ -139,7 +139,7 @@ server/services/│ ├── triggers.py # Generic event-trigger handler│ ├── todo.py # writeTodos execution shim (used by every agent)│ └── __init__.py # Docstring only (google_auth.py retired into nodes/google/_auth_helper.py)-├── llm/ # Native LLM provider SDKs (chat path; the agent loop in ai.py is still LangChain)+├── llm/ # Native LLM provider SDKs for chat and every new agent execution│ ├── __init__.py # Public API exports│ ├── protocol.py # ThinkingConfig, Message, LLMResponse, LLMProvider Protocol│ ├── config.py # ProviderConfig, resolve_max_tokens, resolve_temperature@@ -572,14 +572,13 @@ authoring model.### UI Components- `src/components/ParameterRenderer.tsx` - Universal parameter renderer (also handles AI-specific control rendering; the former `AIParameterRenderer.tsx` was absorbed here)- `src/components/parameterPanel/MiddleSection.tsx` - Parameter panel middle section with conditional display logic-- `src/components/OutputPanel.tsx` - Connected node output display with drag mapping+- `src/components/output/OutputPanel.tsx` - Connected node output display with drag mapping- `src/components/LocationParameterPanel.tsx` - Location-specific parameter handling- `src/components/AIAgentNode.tsx` - Spec-driven agent canvas component. Reads `useNodeSpec(type)` for handles / icon / colour / displayName / uiHints; renders any plugin whose backend `component_kind` is `"agent"` or `"chat"`. No `AGENT_CONFIGS` map.- `src/ParameterPanel.tsx` - Main parameter configuration modal### AI Chat Model Components-AI model nodes route through `SquareNode` via `Dashboard.tsx`'s `COMPONENT_BY_KIND['model']` lookup. Per-provider visual data (icon, color, displayName) comes from the backend `NodeSpec` declared in `server/nodes/model/<provider>_chat_model.py`. The pre-Wave-11 per-provider wrappers (`BaseChatModelNode`, `OpenAIChatModelNode`, `ClaudeChatModelNode`, `GeminiChatModelNode`, `ModelNode`) were deleted -- nothing imported them after the migration.-- `src/services/apiKeyManager.ts` - Secure API key storage and validation with LangChain+AI model nodes route through `SquareNode` via `Dashboard.tsx`'s `COMPONENT_BY_KIND['model']` lookup. Per-provider visual data (icon, color, displayName) comes from the backend `NodeSpec` declared in `server/nodes/model/<provider>_chat_model/__init__.py`. The pre-Wave-11 per-provider wrappers (`BaseChatModelNode`, `OpenAIChatModelNode`, `ClaudeChatModelNode`, `GeminiChatModelNode`, `ModelNode`) were deleted -- nothing imported them after the migration.### Specialized UI- `src/components/ui/MapSelector.tsx` - Interactive location picker@@ -687,7 +686,7 @@ Node groups (palette categories): agent, model, skill, tool, trigger, workflow,### Temporal Distributed Execution-Workflows execute via Temporal for durability and horizontal scaling, gated by `TEMPORAL_ENABLED`. Three dispatch paths exist — legacy single `execute_node_activity` (fallback), per-type `node.{type}.v{version}` activities (F4.A, `TEMPORAL_PER_TYPE_DISPATCH=true`), and Agent-as-child-workflow (F4.B, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`) — with `rlm_agent`/`claude_code_agent` always bypassing AgentWorkflow. **Per-queue activity routing is production-default (Wave 16)**: a `TemporalWorkerPool` runs one activity-only worker per plugin-declared `cls.task_queue` (ai-heavy / browser / code-exec / rest-api / messaging / ...) with per-queue concurrency + rate limits + resource-based tuning for ai-heavy/browser; rollback via `TEMPORAL_WORKER_POOL_ENABLED=false`. Resilience knobs (Waves 17-18): `DEPLOYMENT_MODE` (local halves concurrency; sizes the sticky cache), one-shot retry on `agent.execute_llm_step.v1` (LLM calls are not idempotent), observability interceptors (`activity_retry` WARN on re-dispatch), 30s periodic heartbeat during long activity bodies, cron `catchup_window=24h`, poller autoscaling. Execution routing falls back Temporal → sequential; the Temporal dev server + embedded worker are managed in-process under `server/services/temporal/` (pooch-downloaded CLI, single `temporal server start-dev` process, gRPC 7233 + Web UI 8080, SQLite at `~/.opencompany/temporal.db`). Full architecture, dispatch matrix, per-node + agent-loop lifecycle, the 7 F4.B `agent.*.v1` activities, heartbeat semantics, delegation input contract, resumption toggle (`TEMPORAL_TERMINATE_RUNNING_ON_STARTUP`), the worker tuning recipe, and all `.env` tunables live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).+Workflows execute via Temporal for durability and horizontal scaling, gated by `TEMPORAL_ENABLED`. Three dispatch paths exist — legacy single `execute_node_activity` (fallback), per-type `node.{type}.v{version}` activities (F4.A, `TEMPORAL_PER_TYPE_DISPATCH=true`), and Agent-as-child-workflow (F4.B, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`) — with `rlm_agent`/`claude_code_agent` always bypassing AgentWorkflow. **Per-queue activity routing is production-default (Wave 16)**: a `TemporalWorkerPool` runs one activity-only worker per plugin-declared `cls.task_queue` (ai-heavy / browser / code-exec / rest-api / messaging / ...) with per-queue concurrency + rate limits + resource-based tuning for ai-heavy/browser; rollback via `TEMPORAL_WORKER_POOL_ENABLED=false`. Resilience knobs (Waves 17-18): `DEPLOYMENT_MODE` (local halves concurrency; sizes the sticky cache), one-shot retry on `agent.execute_llm_step.v1` (LLM calls are not idempotent), observability interceptors (`activity_retry` WARN on re-dispatch), 30s periodic heartbeat during long activity bodies, cron `catchup_window=24h`, poller autoscaling. Execution routing falls back Temporal → sequential; the Temporal dev server + embedded worker are managed in-process under `server/services/temporal/` (pooch-downloaded CLI, single `temporal server start-dev` process, gRPC 7233 + Web UI 8080, SQLite at `~/.opencompany/temporal.db`). Full architecture, dispatch matrix, per-node + agent-loop lifecycle, all 16 F4.B `agent.*.v1` activities, heartbeat semantics, delegation input contract, resumption toggle (`TEMPORAL_TERMINATE_RUNNING_ON_STARTUP`), the worker tuning recipe, and all `.env` tunables live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).**Temporal tracing ownership is strict.** Register the SDK `TracingInterceptor` exactly once on the shared `Client.connect(...)`; the Python SDK automatically prepends compatible client interceptors to every worker. Never repeat `TracingInterceptor` in `Worker(..., interceptors=...)`. Worker lists contain the distinct `ObservabilityWorkerInterceptor` and plugin-specific worker interceptors only. Exact paired `StartActivity` / `RunActivity` / `CompleteWorkflow` console spans with identical Temporal identities indicate duplicate instrumentation, not duplicate execution; use Temporal Event History and the `node.<type>.execute` application span to verify actual attempts. See the tracing and debugging sections in [TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md) and [errors.md](./docs-internal/errors.md).@@ -985,7 +984,7 @@ Console logs are persisted to SQLite database and loaded on page refresh.| `server/routers/websocket.py` | WebSocket handlers for chat and console operations |### Per-Workflow Workspace Directory-Each workflow execution gets a persistent workspace directory where nodes save output files and AI agents (especially Deep Agent) access them via filesystem tools.+Each workflow execution gets a persistent workspace directory where nodes save output files and agents such as Coding Agent access them through connected filesystem tools.**Directory**: `~/.opencompany/workspaces/<workflow_slug>/` (Wave 14 — keyed by the human-readable slug, not the UUID; see "Workflow naming" below).@@ -998,8 +997,8 @@ workspace_base_dir: str = Field(default="workspaces", env="WORKSPACE_BASE_DIR")- `workflow.py` creates the workspace dir and injects `workspace_dir` into the execution context. The dir name is the `workflow_slug` resolved from the DB (falls back to `"default"` for one-off Runs without a saved row).- `fileDownloader` saves to `{workspace_dir}/downloads/` by default- Code executors (Python/JS/TS) receive `workspace_dir` in their execution namespace-- Deep Agent uses `FilesystemBackend(root_dir=workspace_dir, virtual_mode=True)` -- its filesystem tools (`read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`) operate within the workspace-- `virtual_mode=True` sandboxes paths to prevent traversal outside workspace+- The `fileRead`, `fileModify`, `fsSearch`, and `shell` nodes use the native `WorkspaceBackend` rooted at `workspace_dir`; Coding Agent can invoke those nodes when they are connected as tools+- `WorkspaceBackend` resolves and validates paths beneath that root, rejects traversal and symlink escapes, and uses per-path locks plus atomic replacement for writes- Rename follows the workflow: when the user renames a workflow, `save_workflow` recomputes the slug and `os.rename`s the workspace dir to match (existing files preserved).**Key Files:**@@ -1009,7 +1008,7 @@ workspace_base_dir: str = Field(default="workspaces", env="WORKSPACE_BASE_DIR")| `server/services/workflow.py` | `_get_workspace_dir()`, injects into context || `server/nodes/document/file_downloader/` | `fileDownloader` saves to the workspace || `server/nodes/code/` | `workspace_dir` available in Python/JS/TS executors |-| `server/nodes/filesystem/_backend.py` | `NushellBackend(root_dir=workspace_dir, virtual_mode=True)` for the file/shell plugins |+| `server/nodes/filesystem/_backend.py` | Native contained workspace filesystem implementation |### Workflow Naming (Wave 14)The workflow record carries three identity fields with strict separation:@@ -1087,11 +1086,11 @@ deploy_workflow() -> Sets up triggers, returns immediately### AI Chat Model System (5-Layer Architecture)-Chat-model nodes (`openaiChatModel`, `anthropicChatModel`, ...) render through `SquareNode` from the backend NodeSpec. Dual-path execution: native SDK (`ChatUnifier` in `services/llm/`) for chat, LangChain (`_run_agent_loop`) for agents. 11 providers are wired for agents (see the provider list above); model params (max output, context length, thinking type, temperature range) come from `ModelRegistryService`. The 5-layer architecture, the native-vs-LangChain split, proxy/local-LLM (Ollama, LM Studio) routing, the per-provider model + thinking/reasoning matrix (budget / effort / format), and `extract_thinking_from_response` all live in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**. The runtime output schema (`thinking` field for downstream nodes) is backend-served per [Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md).+Chat-model nodes (`openaiChatModel`, `anthropicChatModel`, ...) render through `SquareNode` from the backend NodeSpec. Direct chat and every new agent execution route through the native SDK facade (`ChatUnifier` in `services/llm/`); the 12-provider surface is 10 cloud providers plus Ollama and LM Studio. Eleven providers have standalone chat-model nodes, while xAI is selected directly from agent parameters. Model params (max output, context length, thinking type, temperature range) come from `ModelRegistryService`. The provider architecture, proxy/local-LLM routing, per-provider model + thinking/reasoning matrix (budget / effort / format), and the replay-only LangChain boundary for legacy Temporal histories all live in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**. The runtime output schema (`thinking` field for downstream nodes) is backend-served per [Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md).## AI Agent Node Architecture-AI Agent (`aiAgent`) and Chat Agent / Zeenie (`chatAgent`) run the same plain-async `_run_agent_loop` (`server/services/ai.py`) and support memory / skills / tools / task input; differences are the backend method (`execute_agent()` vs `execute_chat_agent()`) and error-handling softness. The loop routes purely on `response.tool_calls`, hot-rebinds the tool surface mid-run after canvas mutations, and treats compaction (token-based, post-turn) as the real termination signal. Connection collection is `collect_agent_connections` in `server/services/plugin/edge_walker.py` (5-tuple: memory, skill, tool, input, task); the pre-Wave-11 `handle_ai_agent`/`handle_chat_agent` handlers are gone (dispatch is per-plugin `execute_op` under `server/nodes/agent/<plugin>/__init__.py`).+AI Agent (`aiAgent`) and Chat Agent / Zeenie (`chatAgent`) both use the plain-async `run_native_agent_loop` in `server/services/agent_runtime.py` and support memory / skills / tools / task input. `AIService.execute_agent()` and `execute_chat_agent()` prepare the same canonical native messages and `AgentToolSpec` values, then the loop appends each lossless assistant message before executing its tool calls, hot-rebinds the tool surface after canvas mutations, and stops when the model returns no tool calls (with `max_iterations` as a safety cap). Connection collection is `collect_agent_connections` in `server/services/plugin/edge_walker.py` (5-tuple: memory, skill, tool, input, task); the pre-Wave-11 `handle_ai_agent`/`handle_chat_agent` handlers are gone (dispatch is per-plugin `execute_op` under `server/nodes/agent/<plugin>/__init__.py`). `_run_agent_loop` remains only for replaying pre-cutover or explicitly legacy-pinned Temporal histories.**`max_iterations` precedence (highest->lowest): per-node `parameters.max_iterations` > `UserSettings.agent_recursion_limit` > env `AGENT_RECURSION_LIMIT` (default 200) > `llm_defaults.json:agent.recursion_limit`.**@@ -1305,19 +1304,28 @@ Multi-step welcome wizard shown on first launch — database-backed (`UserSettin## AI Chat Model Development Guide-A new chat-model provider is one self-contained folder under `server/nodes/model/<provider>_chat_model/` with `__init__.py` declaring a `ChatModelBase` subclass (auto-registers via `BaseNode.__init_subclass__`; the frontend renders it through `SquareNode` from the NodeSpec with zero TS changes). Credentials live in `server/nodes/model/_credentials.py`. The full recipe — native chat path (`services/llm/providers/`), LangChain agent path, `llm_defaults.json` config, the dual-path routing, and the per-provider implementation-file map — is in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**.+A new chat-model provider is one self-contained folder under `server/nodes/model/<provider>_chat_model/` with `__init__.py` declaring a `ChatModelBase` subclass (auto-registers via `BaseNode.__init_subclass__`; the frontend renders it through `SquareNode` from the NodeSpec with zero TS changes). Credentials live in `server/nodes/model/_credentials.py`. The full recipe — native provider registration under `services/llm/providers/`, `llm_defaults.json` configuration, the `_COMPAT_PROVIDERS` entry required for OpenAI-compatible endpoints, and the per-provider implementation-file map — is in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**.## Simple Memory System-The Simple Memory node (`simpleMemory`, plugin `server/nodes/skill/simple_memory.py`) provides markdown-based conversation history on the agent's `input-memory` handle: window-based trimming, an editable markdown view, and optional long-term vector retrieval. Memory is loaded/parsed/appended/trimmed via the helpers in `server/services/memory/`. The full lifecycle (two storage formats, the markdown helper API, vector store, the `claude_code_agent` native-session bridge, clearing/resume) is the canonical **[Memory Lifecycle](./docs-internal/memory_lifecycle.md)**; token tracking + compaction thresholds are in **[Memory Compaction](./docs-internal/memory_compaction.md)**.+The Simple Memory node (`simpleMemory`, plugin `server/nodes/skill/simple_memory/`) provides markdown-based conversation history on the agent's `input-memory` handle: window-based trimming, an editable markdown view, and optional long-term vector retrieval. Memory is loaded/parsed/appended/trimmed via the helpers in `server/services/memory/`. The full lifecycle (two storage formats, the markdown helper API, vector store, the `claude_code_agent` native-session bridge, clearing/resume) is the canonical **[Memory Lifecycle](./docs-internal/memory_lifecycle.md)**; token tracking + compaction thresholds are in **[Memory Compaction](./docs-internal/memory_compaction.md)**.## Memory Compaction, Token Tracking, and Cost Calculation-Automatic memory compaction, token tracking, and cost calculation for all LLM providers. After each agent turn, `CompactionService.track()` records token metrics + cost (via `PricingService`) and, when cumulative tokens cross the threshold, summarises the transcript (native Anthropic/OpenAI context-management APIs where available, client-side summarisation otherwise). Effective threshold = `compaction_ratio` x the model's context window.+Memory-connected standard agents aggregate native `Usage` across every model+turn. The in-process path calls `CompactionService.track()` after execution to+persist session metrics and can trigger `compact_context()`, which performs a+shared client-side summarization call through `ChatUnifier`. The Temporal+`AgentWorkflow` also aggregates and returns loop usage and can invoke the same+summarizer, but it does not currently persist that loop aggregate through+`CompactionService.track()`. Provider-native Anthropic/OpenAI context-management+compaction is not used by the agent runtime. Executions without connected+memory still aggregate usage inside the loop but do not create session+compaction records.-**Compaction-ratio precedence (highest->lowest): per-session `SessionTokenState.custom_threshold` > per-user `UserSettings.compaction_ratio` > env `COMPACTION_RATIO` (default 0.8) > `llm_defaults.json:agent.compaction.ratio`.**+**Threshold precedence inside `CompactionService.track()` (highest-to-lowest): per-session `SessionTokenState.custom_threshold` > per-user `UserSettings.compaction_ratio` > env `COMPACTION_RATIO` (default 0.8) > `llm_defaults.json:agent.compaction.ratio`.** The Temporal agent workflow currently prepares its threshold from the model/user/env ratio without reading the per-session custom threshold, so do not promise that override on every execution path.-Full reference — the `CompactionService` API, native vs client-side compaction, the 5-section summary format, DB models (`TokenUsageMetric` / `SessionTokenState` / `CompactionEvent`), WS handlers, and the broadcast events — in **[Memory Compaction](./docs-internal/memory_compaction.md)**; per-service API cost tracking is in **[Pricing Service](./docs-internal/pricing_service.md)**.+Full reference — the `CompactionService` API, shared client-side compaction, the 5-section summary format, DB models (`TokenUsageMetric` / `SessionTokenState` / `CompactionEvent`), WS handlers, and the broadcast events — in **[Memory Compaction](./docs-internal/memory_compaction.md)**; per-service API cost tracking is in **[Pricing Service](./docs-internal/pricing_service.md)**.## API Cost Tracking@@ -1369,29 +1377,32 @@ Tool nodes provide capabilities that AI Agents can invoke during reasoning. Each```Tool Node (calculatorTool) → (tool output) → AI Agent (input-tools handle)↓- _run_agent_loop builds tools from schemas+ AIService builds AgentToolSpec values↓- LLM decides when to call tools+ run_native_agent_loop sends ToolDef schemas↓- Tool executor runs handler+ LLM selects zero or more tool calls↓- Result returned to LLM+ Tool executor runs handlers+ ↓+ Native tool results return to LLM```### Tool Execution Flow1. **Tool Discovery**: AI Agent scans edges for nodes connected to `input-tools` handle-2. **Schema Building**: `_get_tool_schema()` in `ai.py` creates Pydantic schema for each tool type-3. **Tool Binding**: `_run_agent_loop` binds tools via `chat_model.bind_tools(tools)`+2. **Schema Building**: `_build_tool_from_node()` in `ai.py` combines the Pydantic validation model with an inlined JSON schema in an `AgentToolSpec` / `ToolDef`+3. **Provider Compilation**: `run_native_agent_loop` passes provider-neutral `ToolDef` values through `ChatUnifier`; each native provider compiles the schema it supports4. **LLM Decision**: LLM decides when to call tools based on user query5. **Status Broadcast**: `executing_tool` status broadcast with tool_name for UI animation6. **Tool Execution**: `execute_tool()` in `tools.py` dispatches to appropriate handler-7. **Result Return**: Tool result returned to LLM for continued reasoning+7. **Result Return**: Native tool-result messages are appended for continued reasoning### Key Files| File | Description ||------|-------------|| `server/services/handlers/tools.py` | Tool execution handlers |-| `server/services/ai.py` | `_get_tool_schema()` - Pydantic schemas for tools |+| `server/services/ai.py` | `_build_tool_from_node()` / `_get_tool_schema()` - provider-neutral tool specs and Pydantic validation |+| `server/services/agent_runtime.py` | `AgentToolSpec` and the shared native agent loop || `server/services/plugin/edge_walker.py` | `collect_agent_connections` — tool/skill/memory discovery from edges |### Adding a new tool or specialized agent (Wave 11)@@ -2683,9 +2694,9 @@ This function:- **`outputMode: "terminal"` uiHint — spec-driven CLI output rendering**: the output panel (`components/output/OutputPanel.tsx`, the active renderer — `ui/OutputDisplayPanel.tsx` is legacy/unimported) renders string responses through ReactMarkdown by default, which whitespace-collapses CLI text. CLI-wrapper plugins (`githubAction`, `vercelAction`, `shell`) declare `ui_hints = {"outputMode": "terminal"}`; the panel resolves the spec via `useNodeSpec(selectedNode?.type)` and renders their text in a `<pre>` on the per-theme `--code-*` surface, routes wholly-JSON strings to the JSON tree via the shared `tryParseJson` (`utils/formatters.ts`), and surfaces object/array `result` payloads (server-side-parsed CLI JSON; arrays survive `unwrap` un-peeled) in the Response section. Pair with the `_shape` convention: parsed JSON in `result` OR text in `stdout` — never both — empty keys omitted. Locked by `client/src/components/__tests__/OutputPanel.test.tsx` (render tests: real `\n`/`\t` preserved) + the uiHints known-set in `test_node_spec.py`. Cache note: nodeSpecs are session-sticky (`staleTime: FOREVER`, revision-busted at page load) — after a backend restart a hard browser reload is needed before new uiHints reach an open canvas.- **`--action-X-hover` triplet + ActionButton zero-arithmetic**: each of the 6 action roles (`run`/`stop`/`save`/`config`/`secret`/`tools`) now exposes a `-hover` variant (0.25 alpha) alongside the existing `-soft` (0.15) and `-border` (0.6). ActionButton's CVA reads `hover:bg-action-X-hover` directly; disabled state is the shadcn-idiomatic `disabled:opacity-50` on the base class. No per-token `/25`, `/40`, `/10` opacity arithmetic at any call site. Credential-modal panels (`OAuthConnect`, `EmailPanel`, `QrPairingPanel`) and the skill / tool-schema editors (`SkillEditorModal`, `ToolSchemaEditor`) consume `<ActionButton intent="...">` directly. `ActionDef` carries an `intent` key; the catalogue adapter maps server-sent `theme_color` palette strings to intents via `SERVER_COLOR_TO_INTENT`.- **Credentials: DB as single source of truth + symmetric broadcasts + cache dedup**: `CredentialsDatabase` (encrypted SQLite) is canonical; every other layer is a derived cache with explicit invalidation. Backend `AuthService._memory_cache + _models_cache` collapsed into one `_api_key_cache: Dict[str, ApiKeyCacheEntry]` dataclass — single write/evict site. Per RFC 9700 (OAuth 2.0 BCP, 2024) the `_oauth_cache` no longer carries `refresh_token`; new `get_oauth_refresh_token(provider, customer)` reads from the encrypted DB on every call. `validate_api_key`, `save_api_key`, `delete_api_key`, `twitter_logout`, `google_logout` now broadcast symmetrically: `update_api_key_status` (in-memory map) + `broadcast_credential_event(...)` (refetch signal) wrapping `WorkflowEvent` (CloudEvents v1.0 from `services/events/envelope.py`, the same envelope the Wave 12 EventSource framework uses). The dead-letter `credential_catalogue_updated` event is finally emitted by the backend. Frontend retired the 200-LOC `client/src/components/credentials/providers.tsx` static fallback — `useCatalogueQuery` is the only source; cold-boot renders `<Skeleton>`, server-unreachable shows an explicit error state. `ApiKeyStatus.hasKey` mirror dropped (duplicated catalogue's `provider.stored`); two new selector hooks (`useProviderStored`, `useStoredProviderCount`) read the catalogue. Pytest invariant `test_credential_broadcasts.py` (14 tests) locks the broadcast contract via `inspect.getsource` introspection + the CloudEvents v1.0 envelope shape + AuthService DB-write-then-cache-update ordering + the no-refresh-token-in-cache rule.-- **Local-LLM provider routing + per-model context**: Ollama and LM Studio are first-class providers (9 in total for agents now: cloud 7 + 2 local). Provider detection is driven by `detect_ai_provider` in `server/constants.py` plus the `provider` Literal in `nodes/agent/{ai_agent,chat_agent,_specialized}.py` — both MUST list `ollama` / `lmstudio` or chat-model nodes / agent dropdowns silently fall through to `'openai'` and `execute_chat` calls api.openai.com with the placeholder key. The validator at `nodes/model/_local_validator.py` probes via the official SDKs (`ollama.AsyncClient.ps()` for typed `ProcessResponse.Model`, `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo`) — reads only typed fields (`context_length`, `max_context_length`, `vision`, `trained_for_tool_use`, `architecture`, `params_string`, `format`, plus Ollama's `details.{family,parameter_size,quantization_level}`). No regex, no Modelfile-parameters parsing, no `/api/show` modelinfo dict-key hunting. Per-model params persist in `EncryptedAPIKey.models["model_params"]` (via `save_api_key(model_params=...)`) AND in `model_registry.json` via `register_local_model()` — sync `get_context_length()` / `get_max_output_tokens()` find real values without async DB lookups, and entries survive process restart. `is_model_valid_for_provider` returns `True` for open-world providers (`openrouter` / `ollama` / `lmstudio`) so local model names like `qwen/qwen3.6-27b` aren't rejected by the cloud-style pattern check. Runtime path uses `OpenAIProvider(base_url={user_proxy_url}, api_key="ollama")` — traffic stays on `localhost`.-- **Typed openai exception → NodeUserError**: `execute_chat` / `execute_agent` / `execute_chat_agent` in `services/ai.py` each have **one** `except openai.OpenAIError as e` block that re-raises `NodeUserError(str(e)) from e`. The openai SDK's typed exception hierarchy — `BadRequestError` (400, e.g. `n_keep > n_ctx` overflow), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `RateLimitError` (429), `APIConnectionError` (server unreachable), `APITimeoutError` — IS the user-correctable contract. `BaseNode.execute()` catches `NodeUserError` and logs at WARN with one line, no stacktrace. The plain `except Exception` block keeps the full-traceback path for real bugs. Zero string matching, zero flag plumbing, zero classification helpers. The `frontend toast` reads `response.message ?? response.error` so both clean envelopes (validator-style) and uncaught-error envelopes (handler-wrapper-style) surface a useful message.-- **Plugin extraction (Wave 11.I)**: every plugin's WS handlers, OAuth client, FastAPI router, and lifecycle service live entirely under `nodes/<plugin>/`. Eight plugin domains migrated this round (whatsapp / twitter / google-workspace / android / browser / email / code / credential-validation-scaffold for maps+apify+ollama+lmstudio) follow the telegram pattern. `routers/websocket.py` shrunk from ~3,785 to ~2,977 LOC (-808). Three plugin routers (`routers/twitter.py`, `routers/google.py`, `routers/android.py`) moved into `nodes/<plugin>/_router.py` and mount via the plugin-router loop in `main.py`; the explicit `app.include_router(<plugin>.router)` calls and `from routers import <plugin>` imports in `main.py` are gone. **`register_router(router, name=...)` is the new sibling helper to `register_ws_handlers` (same file: `services/ws_handler_registry.py`)** — six generic registries total now (ws_handlers, router, filter_builder, trigger_precheck, service_refresh, output_schema). **`Credential.validate(data) -> dict` + `Credential._probe(api_key) -> ProbeResult` is the new shared validator scaffold** in `services/plugin/credential.py` — replaces the per-router `_SPECIAL_PROVIDER_VALIDATORS` dict; one `_LLMApiKey._probe` method serves all 9 cloud LLM providers, dedicated `_probe` overrides handle Maps + Apify, `_LocalLLM.validate` overrides for Ollama / LM Studio's 2-storage edge case. **`tests/test_plugin_self_containment.py` locks the contract** with 7 invariant classes (forbidden-imports / no-router-outside-nodes / per-plugin self-registration / registry-API sanity / stale-paths-absent / main.py-does-not-mount / WS_HANDLERS-non-empty); same `inspect.getsource` introspection style as `test_credential_broadcasts.py`. Wire format unchanged — frontend WS message-type strings (`whatsapp_status`, `twitter_oauth_login`, `google_oauth_status`, `android_relay_connect`, etc.) and HTTP route paths (`/api/twitter/callback`, `/api/google/callback`, `/api/android/*`) are byte-identical post-migration.+- **Local-LLM provider routing + per-model context**: Ollama and LM Studio are first-class providers (12 total for agents: 10 cloud + 2 local). Provider detection is driven by `detect_ai_provider` in `server/constants.py` plus the `provider` Literal in `nodes/agent/{ai_agent,chat_agent,_specialized}.py` — both MUST list `ollama` / `lmstudio` or chat-model nodes / agent dropdowns silently fall through to `'openai'` and `execute_chat` calls api.openai.com with the placeholder key. The validator at `nodes/model/_local_validator.py` probes via the official SDKs (`ollama.AsyncClient.ps()` for typed `ProcessResponse.Model`, `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo`) — reads only typed fields (`context_length`, `max_context_length`, `vision`, `trained_for_tool_use`, `architecture`, `params_string`, `format`, plus Ollama's `details.{family,parameter_size,quantization_level}`). No regex, no Modelfile-parameters parsing, no `/api/show` modelinfo dict-key hunting. Per-model params persist in `EncryptedAPIKey.models["model_params"]` (via `save_api_key(model_params=...)`) AND in `model_registry.json` via `register_local_model()` — sync `get_context_length()` / `get_max_output_tokens()` find real values without async DB lookups, and entries survive process restart. `is_model_valid_for_provider` returns `True` for open-world providers (`openrouter` / `ollama` / `lmstudio`) so local model names like `qwen/qwen3.6-27b` aren't rejected by the cloud-style pattern check. Runtime path uses `OpenAIProvider(base_url={user_proxy_url}, api_key="ollama")` — traffic stays on `localhost`.+- **Typed SDK error → `LLMError` → `NodeUserError`**: Native providers normalize SDK failures into structured `LLMError` values carrying category, retryability, HTTP status, provider code, request ID, and retry-after metadata. `ChatUnifier` translates them at the execution boundary into a user-safe `NodeUserError`; `BaseNode.execute()` logs that at WARN with one line and no stack trace. Unexpected exceptions retain the full-traceback path. In-process agent turns retry only errors marked retryable, while Temporal owns activity retries and disables the inner retry loop.+- **Plugin extraction (Wave 11.I)**: every plugin's WS handlers, OAuth client, FastAPI router, and lifecycle service live entirely under `nodes/<plugin>/`. Eight plugin domains migrated this round (whatsapp / twitter / google-workspace / android / browser / email / code / credential-validation-scaffold for maps+apify+ollama+lmstudio) follow the telegram pattern. `routers/websocket.py` shrunk from ~3,785 to ~2,977 LOC (-808). Three plugin routers (`routers/twitter.py`, `routers/google.py`, `routers/android.py`) moved into `nodes/<plugin>/_router.py` and mount via the plugin-router loop in `main.py`; the explicit `app.include_router(<plugin>.router)` calls and `from routers import <plugin>` imports in `main.py` are gone. **`register_router(router, name=...)` is the new sibling helper to `register_ws_handlers` (same file: `services/ws_handler_registry.py`)** — six generic registries total now (ws_handlers, router, filter_builder, trigger_precheck, service_refresh, output_schema). **`Credential.validate(data) -> dict` + `Credential._probe(api_key) -> ProbeResult` is the new shared validator scaffold** in `services/plugin/credential.py` — replaces the per-router `_SPECIAL_PROVIDER_VALIDATORS` dict; one `_LLMApiKey._probe` method serves all 10 cloud LLM providers, dedicated `_probe` overrides handle Maps + Apify, `_LocalLLM.validate` overrides for Ollama / LM Studio's 2-storage edge case. **`tests/test_plugin_self_containment.py` locks the contract** with 7 invariant classes (forbidden-imports / no-router-outside-nodes / per-plugin self-registration / registry-API sanity / stale-paths-absent / main.py-does-not-mount / WS_HANDLERS-non-empty); same `inspect.getsource` introspection style as `test_credential_broadcasts.py`. Wire format unchanged — frontend WS message-type strings (`whatsapp_status`, `twitter_oauth_login`, `google_oauth_status`, `android_relay_connect`, etc.) and HTTP route paths (`/api/twitter/callback`, `/api/google/callback`, `/api/android/*`) are byte-identical post-migration.- **Typed CloudEvents factory pattern for new broadcasts** (b6aecd3): every new server→FE lifecycle broadcast follows the recipe locked by `broadcast_credential_event`, `broadcast_agent_progress`, and `broadcast_agent_capability`. (1) Add a typed factory — convention: `source = "opencompany://services/<area>"`, reverse-DNS `type = "com.opencompany.<area>.<event>"`, and `subject = <exact primary entity id>`. Put snake_case workflow/execution scope inside `data`; CloudEvents extension attribute names MUST be lowercase-alphanumeric, so the historical top-level `workflow_id`/`trigger_node_id`/`correlation_id` fields are compatibility debt and are forbidden on new contracts. (2) Add a broadcaster wrapper that emits `broadcast({type: "<wire_key>", data: event.model_dump(mode="json", exclude_none=True)})`. (3) FE validates `specversion`, ID/source/type, subject ownership, and event-specific payload invariants, deduplicates by `(source,id)`, then writes only the exact scoped entity. (4) Add contract tests in `test_events.py` and keep `tests/test_status_broadcasts.py`'s raw-callsite allowlist empty. Raw `node_status` remains allowed only as the established high-frequency latest-state/reconnect projection paired with a typed lifecycle occurrence; it is not the event of record.- **Plugin-folder location for plugin-specific CloudEvents factories** (RFC §6.4): when a typed event is owned by one plugin (telegram, whatsapp, android, email, google, master_skill, agent_builder, webhook_trigger, chat_trigger, agent), the factory + `broadcast_<event>` wrapper live in [`server/nodes/<plugin>/_events.py`](./server/nodes), NOT on `WorkflowEvent` / `StatusBroadcaster` directly. Telegram's [`_events.py`](./server/nodes/telegram/_events.py) is the canonical template — `broadcast_telegram_status` constructs the envelope via a plain factory function and calls `get_status_broadcaster().broadcast(...)` itself. Latest example: [`server/nodes/skill/master_skill/_events.py`](./server/nodes/skill/master_skill/_events.py) (`broadcast_skill_lifecycle("created" \| "updated" \| "deleted" \| "content_saved", name=..., **data_extra)`) — replaces four raw-dict broadcasts in `handle_create_user_skill` / `handle_update_user_skill` / `handle_delete_user_skill` / `handle_save_skill_content` (the last one was previously silent). FE routes wire key `skill_lifecycle` to invalidate `userSkills` + `folderSkills` queries and drop the `skillContent` cache on delete + content_saved so the Master Skill panel refreshes live across every connected client. Cross-cutting events (credential, workflow_lifecycle, agent_progress, agent_capability, node_parameters_updated) keep their `WorkflowEvent` classmethods + `StatusBroadcaster` wrappers — only plugin-scoped events move to the plugin folder.- **Operator-metadata fields in credential panels** (f746ddf): when a credential panel needs a non-credential follow-up field (e.g. Telegram bot token + owner chat id), declare it as a second entry in the provider's `fields` array in `server/config/credential_providers.json`. The first field stays the validate/connect target; subsequent fields render below as plain text inputs via `SecondaryFieldRow` in `ApiKeyPanel.tsx` (shadcn `Input` + `Label` + `<ActionButton intent="save">`). Each field carries an optional `help` slot (`FieldDef.help` / `ServerFieldDef.help`) for always-visible explanatory text under the input. Save writes via `panel.actions.save(field.key, value)` → `auth_service.store_api_key` (which is permissive about provider string). The credential class must declare the new key in `extra_fields` (`Credential` subclass attribute) so the storage layer accepts it. Reference: `telegram_owner_chat_id` field.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex c85ac9a4..702c777a 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -18,7 +18,7 @@ See [SETUP.md](docs-internal/SETUP.md) for environment setup and [SCRIPTS.md](doAt a glance:- **115+ workflow nodes** across ~30 palette groups (live count: glob `server/nodes/**/__init__.py`; group list: `server/nodes/groups.py`; one self-contained plugin folder per node under `server/nodes/<group>/`)-- **12 LLM providers** via a hybrid native SDK + LangChain architecture (11 chat-model nodes; xAI native-chat-only)+- **12 native LLM providers** (10 cloud providers plus Ollama and LM Studio; 11 standalone chat-model nodes because xAI is selected directly by agent nodes)- **Specialized AI agents** with the Agent Teams delegation pattern — SSOT is the `AI_AGENT_TYPES` frozenset in `server/constants.py`, which spans the base/specialized/team-lead agents plus the CLI-backed (`claude_code_agent`, `rlm_agent`) and Vertex-hosted (`vertex_managed_agent`) variants; `codex_agent` is a sibling CLI-agent plugin- **WebSocket-first API** replacing most REST endpoints (live handler count = `MESSAGE_HANDLERS` + plugin registries)- **65+ built-in skills**, editable in-UI with SKILL.md defaults on disk (live count: glob `server/skills/**/SKILL.md`)@@ -36,7 +36,7 @@ Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](do[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/ai-agent-routing.svg)-AI execution splits into two paths. `execute_chat()` for direct chat completions delegates every provider to the native SDK layer in [services/llm/](server/services/llm/) via `ChatUnifier` (12 providers, lazy imports, normalized `LLMResponse`; Groq, Cerebras, and the local servers ride the OpenAI-compatible client with a custom `base_url` — the old chat-path LangChain fallback is retired). `execute_agent()` and `execute_chat_agent()` build a LangChain chat model (`ChatOpenAI` / `ChatAnthropic` / etc.) and drive it through `_run_agent_loop`. Team leads (`orchestrator_agent`, `ai_employee`) receive an intrinsic Task Manager and may assign only agents connected to their `input-teammates` handle. Delegate descriptors stay internal. `task_manager(assign_task)` persists and returns `queued`; Temporal hands work to a detached `DelegatedTaskWorkflow`, while legacy execution reuses the same durable task record. Completion emits `taskTrigger` with owning execution context for a separate lead review. The RLM Agent uses a REPL-based recursive language model pattern. Long-running activities remain alive through activity heartbeats.+Direct chat completions and every new agent execution use the native SDK layer in [services/llm/](server/services/llm/) through `ChatUnifier`. The shared `run_native_agent_loop` consumes lossless native messages and provider-neutral `AgentToolSpec` definitions; Groq, Cerebras, xAI, DeepSeek, Kimi, Mistral, and the local servers ride the OpenAI-compatible client with provider-specific `base_url` values. LangChain remains only in the frozen compatibility branch for pre-cutover or explicitly legacy-pinned Temporal histories. Team leads (`orchestrator_agent`, `ai_employee`) receive an intrinsic Task Manager and may assign only agents connected to their `input-teammates` handle. Delegate descriptors stay internal. `task_manager(assign_task)` persists and returns `queued`; Temporal hands work to a detached `DelegatedTaskWorkflow`, while legacy execution reuses the same durable task record. Completion emits `taskTrigger` with owning execution context for a separate lead review. The RLM Agent uses a REPL-based recursive language model pattern. Long-running activities remain alive through activity heartbeats.Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md) - [cli_agent_framework.md](docs-internal/cli_agent_framework.md)@@ -73,7 +73,7 @@ The diagram above shows the full lifecycle of a workflow node: one self-containe**Add an LLM provider**- Guide: [native_llm_sdk.md](docs-internal/native_llm_sdk.md) → "Adding a New Provider"-- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): config-only in `server/config/llm_defaults.json` + the compat list in `services/llm/providers/_compat.py`+- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): add the provider configuration to `server/config/llm_defaults.json` and its name to `services/llm/providers/_compat.py::_COMPAT_PROVIDERS`- Custom-SDK provider: new file in `server/services/llm/providers/` that calls `register_provider(ProviderSpec(...))` at module bottom (lazy factory + `sdk_exception_refs`; the legacy `factory.py` was removed — `register_provider` is the only entry point)- Chat-model node plugin: `server/nodes/model/<provider>_chat_model/__init__.py`; for agent-dropdown exposure also extend the `provider` Literal in `nodes/agent/{ai_agent,chat_agent,_specialized}` and `detect_ai_provider` in `server/constants.py`diff --git a/README.md b/README.mdindex 75c411d4..0c882e2f 100644--- a/README.md+++ b/README.md@@ -126,15 +126,15 @@ Skills are short markdown files that teach an agent how to do something well —### Memory that scales with your context window-Agents track token usage and automatically compact long conversations as you approach your model's context limit (80% by default, configurable). Compaction summarizes in five sections — Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve — so the agent picks up exactly where it left off. Anthropic and OpenAI use native API compaction; everywhere else, the agent summarizes itself.+Agents connected to a memory node can track normalized token usage and compact long conversations as they approach the model's context limit (80% by default). Compaction is a context-pressure control, not an agent termination rule: the shared native LLM layer asks the selected model for a five-section summary — Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve — and continues from that summary. Provider-reported usage is aggregated across an agent loop; session token and cost metrics are persisted on the memory-connected in-process path, while durable Temporal runs return their aggregate usage in the execution result.### Cost tracking, built in-Every LLM call and API request is tracked with USD cost. See per-provider spend in the API Credentials panel. Configure your own pricing in `pricing.json` if you switch providers mid-flight.+Memory-connected agent runs calculate USD cost from provider-reported usage when that usage is available. See tracked spend in the API Credentials panel, and configure pricing in `pricing.json` for custom model pricing. This is not a universal audit log of every LLM or third-party API request.## Built Like Production Infrastructure-- **Durable execution via Temporal.** Every node runs as an independent Temporal activity with automatic retries; cron schedules have a 24-hour catch-up window so missed ticks backfill; per-queue worker pools scale horizontally. Falls back to a local executor when disabled.+- **Durable execution via Temporal.** Ordinary node and agent-support activities retry transient failures with bounded backoff; billed `AgentWorkflow` LLM-step activities run once to avoid automatic double billing after ambiguous failures. Cron schedules have a 24-hour catch-up window so missed ticks backfill, and per-queue worker pools scale horizontally. Falls back to a local executor when disabled.- **Credentials encrypted at rest.** API keys and OAuth tokens live in a separate `credentials.db`, encrypted with Fernet (AES-128-CBC + HMAC-SHA256) and a PBKDF2-SHA256 key at 600,000 iterations. Nothing leaves your machine.- **Login-gated by choice.** Runs open on localhost by default; flip on single-owner JWT auth (or multi-user mode) for shared and cloud deployments — `company deploy` enables it automatically.diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.mdindex 5135e4c2..c2284176 100644--- a/docs-internal/DESIGN.md+++ b/docs-internal/DESIGN.md@@ -64,7 +64,10 @@ No shipped configuration sets `REDIS_ENABLED=true`, so this branch is unreachabl## RLM Agent Execution-`rlm_agent` is the only agent node type that does not go through `handle_chat_agent`. It has a dedicated handler `handle_rlm_agent` that routes to `RLMService` in `services/rlm_service.py`.+`rlm_agent` is the agent type that does not use the shared native tool-calling+loop. Its `RLMAgentNode.execute_op` plugin collects the usual connections and+routes to `RLMService` in `services/rlm/`, which owns the recursive REPL+runtime.The Recursive Language Model pattern replaces the standard tool-calling loop with a Python REPL (`exec()`) where the agent writes code that can call:diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.mdindex eb760337..c95fc13b 100644--- a/docs-internal/SETUP.md+++ b/docs-internal/SETUP.md@@ -38,6 +38,15 @@ npm run buildnpm run start```+The default server install stays lightweight and does not install the+`sentence-transformers` stack. OpenAI and Ollama embeddings work through their+native SDKs in the default install. To enable local Hugging Face embeddings for+the embedding node and long-term memory, install the optional extra:++```bash+cd server && uv sync --extra local-embeddings+```+### Docker```bash@@ -62,7 +71,7 @@ Services will be available at:### Backend (Python FastAPI - Port 3010)- FastAPI with async support- SQLAlchemy + SQLite database-- LangChain for AI integrations+- Native Anthropic and Google Gen AI providers plus the OpenAI SDK for OpenAI-compatible chat through `ChatUnifier`; Ollama's SDK is used for local model discovery and embeddings- WebSocket for real-time updates**Key Endpoints:**diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex 9553dcbd..e7d4923b 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -414,8 +414,11 @@ native provider SDKs for every turn. Histories whose recorded prepare resulthas no engine marker are pre-cutover histories and follow the frozen LangChainpath with their historical payload, activity commands, and message shape. Thetemporary `AGENT_LLM_ENGINE=langchain` emergency switch can also pin a newly-prepared execution to that compatibility path without changing an execution-after it starts. A native run never falls back after a provider request starts.+prepared execution to that compatibility path. Those emergency executions are+marker-bearing histories whose recorded `llm_engine` is `langchain`; they+continue replaying the compatibility branch just like markerless pre-cutover+histories. Changing the environment cannot change an execution after it starts,+and a native run never falls back after a provider request starts.`emit_phase(phase, status?)` is a thin helper that schedules `agent.broadcast_progress.v1`. The activity emits `WorkflowEvent.agent_progress` (CloudEvents v1.0, `type="com.opencompany.agent.progress"`) for FE consumers; when `status` is supplied it also drives a raw-dict `update_node_status` for the canvas-glow color (executing / success / error). Same dual-channel pattern F4.A's `_node_activity` uses. When this workflow is itself a delegated child (`context["parent_node_id"]` set), every `emit_phase` call ALSO schedules a second broadcast against the parent's `node_id` with `phase="delegating"` — the parent's canvas badge then advances in real time while the child loops, instead of freezing at "executing" glow until the child completes.@@ -427,7 +430,8 @@ Durable event listeners retain their deployment graph as a fallback, but each fi**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:+`collect_agent_activities()` registers **16 agent activities**. Seven are the+core loop activities:| Activity | Purpose ||---|---|@@ -435,10 +439,29 @@ Durable event listeners retain their deployment graph as a fallback, but each fi| `agent.execute_llm_step.v1` | One LLM turn. The native branch decodes Message Wire V2, rebuilds `ToolDef` values, calls `run_native_llm_step(ChatUnifier, ...)` with SDK retries disabled, heartbeats while awaiting the provider, and returns the exact assistant message + tool calls + normalized usage. Guards against un-invokable payloads: post-filter system-only message lists raise `ApplicationError(type="EmptyAgentPrompt", non_retryable=True)`. || `agent.refresh_tools.v1` | Translates `workflow_ops` add_node ops (`component_kind="tool"` OR `usable_as_tool=True`) into fresh `AgentToolSpec`-derived `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.compact_memory.v1` | Context-pressure compaction when cumulative active-context tokens hit the threshold. Best-effort: continues with un-compacted history on failure; it is not an agent termination control. || `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. |+The other nine support skills and durable delegation:++| Activity | Purpose |+|---|---|+| `agent.skill.invoke.v1` | Executes one progressive skill action with a history-recorded, retry-safe result. |+| `agent.skill.clear.v1` | Clears the agent's turn-scoped skill state. |+| `agent.begin_delegation.v1` | Idempotently persists and claims a direct delegation before child startup. |+| `agent.queue_delegation.v1` | Persists a team task before it waits for a root-wide concurrency permit. |+| `agent.acquire_subagent_permit.v1` | Heartbeats while polling the durable root coordinator for a subagent permit. |+| `agent.release_subagent_permit.v1` | Idempotently releases a root-wide subagent permit. |+| `agent.register_task_execution.v1` | Persists the runner and child Temporal identities for trace inspection. |+| `agent.finish_delegation.v1` | Idempotently records a delegated child's terminal result and usage. |+| `agent.finalize_team.v1` | Finalizes a team after its required tasks reach accepted or terminal states. |++The F4.B compaction threshold is prepared from the model context length and+the ratio configuration. It currently does not read+`SessionTokenState.custom_threshold` or `compaction_enabled`; those stored+per-session controls are therefore not authoritative for this path.+**Broadcasts inside the loop** wrap `WorkflowEvent` (CloudEvents v1.0) per RFC §6.4: `agent_progress` events (`com.opencompany.agent.progress`) and `node_parameters_updated` events (`com.opencompany.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.@@ -481,9 +504,10 @@ Trigger nodes that aren't the firing trigger are:| Scenario | Behavior ||----------|----------|-| Node WebSocket call fails | Temporal retries (up to 3 attempts with backoff) |+| Ordinary node or agent-support activity fails transiently | Temporal retries up to 3 attempts with backoff unless the error type is non-retryable. |+| `AgentWorkflow` LLM-step activity fails | `LLM_STEP_RETRY` allows one attempt. Provider SDK retries are also disabled so an ambiguous failure is not silently billed again. || Worker crashes mid-execution | Temporal reschedules on another worker |-| Node times out (10 min) | Temporal retries with backoff |+| Ordinary node times out | Temporal applies that activity's retry policy; plugin timeouts vary by node type. || All retries exhausted | Workflow receives failure, stops execution |## File Structure@@ -496,7 +520,7 @@ server/services/temporal/│ └── _execute_via_websocket() # WebSocket execution├── plugin_activities.py # collect_plugin_activities() -> per-type node.{type}.v{ver} activities (F4.A)├── agent_workflow.py # AgentWorkflow loop + detached DelegatedTaskWorkflow-├── agent_activities.py # collect_agent_activities() -> the 7 agent.*.v1 activities (F4.B)+├── agent_activities.py # collect_agent_activities() -> 16 agent.*.v1 activities (F4.B)├── workflow.py # MachinaWorkflow class│ ├── run() # Main orchestrator│ ├── _filter_executable_graph() # Config node filtering@@ -591,6 +615,13 @@ One supervisor-build-time env var (read inside `_temporal_specs.py`, not in `Set|---|---|---|| `TEMPORAL_SERVER_READY_TIMEOUT_SECONDS` | `120` | How long the supervisor waits for Temporal's gRPC port to come up. Covers the first-run binary download (~114 MB) if `company build` didn't pre-cache. |+One temporary agent-engine cutover variable is also read directly rather than+through `Settings`:++| Env var | `.env.template` default | Purpose |+|---|---|---|+| `AGENT_LLM_ENGINE` | `native` | `agent.prepare_payload.v1` reads this with `os.getenv` and records `native` or `langchain` in each new execution's prepare result. It affects only executions prepared after the environment changes; recorded histories keep their selected engine. `langchain` is the emergency compatibility setting and is removed with the legacy replay branch in Stage 2. |+## DebuggingThe Web UI is at http://localhost:8080; the UI's HTTP API is served at http://localhost:8233.diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.mdindex 80e93428..9f7abd86 100644--- a/docs-internal/agent_architecture.md+++ b/docs-internal/agent_architecture.md@@ -170,7 +170,11 @@ Resolved per-execution by `execute_agent` / `execute_chat_agent` (and `prepare_a3. **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).+The iteration limit is the termination backstop. Compaction is a post-turn+context-pressure control for agents with connected memory; it summarizes active+history so a loop can continue within the model's context window, but it does+not decide when the loop terminates. See+[memory_compaction.md](memory_compaction.md).### Hot rebind after canvas mutation@@ -507,10 +511,14 @@ Two settings flags route agent execution through different Temporal paths (see [Both flags default to `true` in `.env.template`.New `AgentWorkflow` executions record `llm_engine="native"` and-`message_wire_version=2` in the `agent.prepare_payload.v1` result. Only-recorded histories whose prepare result predates those markers replay the-frozen LangChain / `StructuredTool` branch; marker-bearing native executions-never fall back after a provider request starts.+`message_wire_version=2` in the `agent.prepare_payload.v1` result by default.+Recorded histories whose prepare result predates those markers replay the+frozen LangChain / `StructuredTool` branch. The temporary+`AGENT_LLM_ENGINE=langchain` emergency setting can also create a marker-bearing+prepare result explicitly pinned to that compatibility branch. Marker-bearing+native executions never fall back after a provider request starts, and changing+the environment does not alter an execution whose prepare result is already in+history.**Team leads** (`orchestrator_agent`, `ai_employee`) run the same`execute_chat_agent` path as the other specialized agents but add andiff --git a/docs-internal/claude_code_agent_architecture.md b/docs-internal/claude_code_agent_architecture.mdindex ff996ed6..98f23ebc 100644--- a/docs-internal/claude_code_agent_architecture.md+++ b/docs-internal/claude_code_agent_architecture.md@@ -1,5 +1,12 @@# Claude Code Agent Architecture+> **Current implementation note:** The production `claude_code_agent` is an+> interactive Claude Code CLI/PTY integration implemented under+> `server/nodes/agent/claude_code_agent/`. It does not use LangGraph or+> LangChain. The LangGraph diagrams and dependency snapshot below are retained+> only as historical design material and must not be used as implementation+> guidance.+## Table of Contents1. [Memory & Context Compaction Architecture](#1-memory--context-compaction-architecture)2. [Sub-Agent Creation & Handling](#2-sub-agent-creation--handling)@@ -352,7 +359,11 @@# 2. Sub-Agent Creation & Handling-## 2.1 LangGraph Sub-Agent Architecture Overview+## 2.1 Historical LangGraph Sub-Agent Architecture (non-production)++> Historical design snapshot only. Production sub-agent execution uses the+> CLI-backed agent framework and Temporal delegation workflows; no production+> import or dependency on LangGraph is implied by this section.```┌─────────────────────────────────────────────────────────────────────────────┐@@ -1212,7 +1223,10 @@----## Version Information+## Historical Dependency Snapshot (non-production)++These were the versions considered by the superseded LangGraph design. They+are not dependencies of the current server runtime.| Package | Version ||---------|---------|diff --git a/docs-internal/claude_code_cli_reference.md b/docs-internal/claude_code_cli_reference.mdindex 20063877..2e64a318 100644--- a/docs-internal/claude_code_cli_reference.md+++ b/docs-internal/claude_code_cli_reference.md@@ -178,31 +178,33 @@ live on separate doc pages:If a separate snapshot of any of these pages would help, fetch andadd an analogous `claude_code_*_reference.md` file.-## Flags we use in `services/cli_agent/`+## Flags used by the current Claude Code agentQuick cross-reference for the OpenCompany `claude_code_agent` integration:| Flag | Used in | Purpose ||---|---|---|-| `--output-format stream-json` | always | NDJSON event stream parsed by `session.py:_consume_stdout` |-| `--verbose` | always | required when `--output-format stream-json` is set with `--print` |-| `--include-partial-messages` | always | surface streaming deltas to the Terminal panel |-| `--include-hook-events` | always | surface `SessionStart` / hook events into the stream |-| `--print`, `-p` | always | one-shot non-interactive query |+| `--output-format stream-json` | always | NDJSON event stream consumed by `_pool.py` |+| `--input-format stream-json` | always | prompts are written to the long-lived subprocess over stdin |+| `--verbose` | always | include complete stream-json event detail |+| `--ide` | always | discover the per-process IDE lockfile used for MCP connectivity || `--model <id>` | always | from `ClaudeTaskSpec.model` / config default |-| `--max-turns <N>` | always | from `ClaudeTaskSpec.max_turns` |-| `--permission-mode <mode>` | always | default `acceptEdits` |-| `--allowedTools <csv>` | always | `Read,Edit,Bash,Glob,Grep,Write,Skill,WebSearch,WebFetch,mcp__opencompany__*` (see canonical patterns RFC §5 R3) |+| `--permission-mode <mode>` | normally | defaults to `dontAsk` so the explicit allowlist remains authoritative without interactive prompts |+| `--allowedTools <csv>` | always | connected workflow tools plus OpenCompany MCP infrastructure tools; Claude built-ins are opt-in, except `Skill` when a skill is connected || `--mcp-config <json>` | when MCP wired | inline JSON with `{mcpServers: {opencompany: {type: http, url, headers, alwaysLoad: true}}}` || `--strict-mcp-config` | when MCP wired | blocks user-level `~/.claude.json` MCP entries |-| `--append-system-prompt <text>` | when system_prompt or connected tools wired | per-task system prompt + connected-tools steering directive |-| `--session-id <UUID>` | memory bridge first run | deterministic `uuid5(memory_node_id, session_id)` |-| `--resume <UUID>` | memory bridge subsequent runs | `simpleMemory.last_session_id` saved by `_persist_memory` |-| `--max-budget-usd <USD>` | when `ClaudeTaskSpec.max_budget_usd > 0` | cost cap per task |+| `--append-system-prompt <text>` | when `system_prompt` is set | append the task prompt to Claude Code's built-in system prompt |+| `--continue` | first spawn for a memory-bound run | let Claude select the latest conversation for the stable working directory |+| `--resume <UUID>` | pooled-process crash or reap recovery | resume the session UUID captured from Claude's stream events || `--effort <level>` | optional per-task override | reasoning effort |-| `--fallback-model <id>` | optional per-task override | fallback when default model is overloaded || `--add-dir <path>*` | optional per-task override | grant extra working dirs || `--disallowedTools <csv>` | optional per-task override | remove tools from context || `--agent <name>` | optional per-task override | use a specific subagent |+The interactive subprocess path intentionally does not emit `--print`,+`--include-partial-messages`, `--include-hook-events`, or `--session-id`.+It also retains `max_turns`, `max_budget_usd`, and `fallback_model` on the+task specification only for compatibility; their corresponding flags are+print-mode-only and are not emitted by this path.+See [`server/nodes/agent/claude_code_agent/_provider.py`](../server/nodes/agent/claude_code_agent/_provider.py) for the argv-construction code.diff --git a/docs-internal/design-system/components/canvas/ComponentItem.prompt.md b/docs-internal/design-system/components/canvas/ComponentItem.prompt.mdindex 88b82822..cedc335f 100644--- a/docs-internal/design-system/components/canvas/ComponentItem.prompt.md+++ b/docs-internal/design-system/components/canvas/ComponentItem.prompt.md@@ -1,7 +1,7 @@Component-palette row: what users drag onto the canvas.```jsx-<ComponentItem icon="🤖" name="AI Agent" description="LangGraph agent with memory and tools" />+<ComponentItem icon="🤖" name="AI Agent" description="Native agent with memory and tools" /><ComponentItem icon="📱" name="WhatsApp Send" description="Send a WhatsApp message" />```diff --git a/docs-internal/design-system/readme.md b/docs-internal/design-system/readme.mdindex f61fb882..a5a831ce 100644--- a/docs-internal/design-system/readme.md+++ b/docs-internal/design-system/readme.md@@ -23,7 +23,7 @@ The app ships 12 visual themes (light, dark, Renaissance, Cyber, Edo, Steampunk- **Short declarative fragments for value props.** "No code required. No subscription. No usage limits."- **Sentence case everywhere** — headings ("What You Can Build" is Title Case in README headers, but UI copy is sentence case: "No workflows yet", "Create your first workflow to get started"). Buttons are single words or short verb phrases: **Start**, **Stop**, **Save**, **New Workflow**, **Apply All**.- **UI microcopy is terse and systemy.** Status bar reads like a shell prompt: `ONLINE | WF: Test | NODES: 12 | THEME: DARK | 14:02:33`. States: "Saved" / "Modified". Tooltips are full sentences: "Override all agent nodes in this workflow to use the selected model".-- **Numbers as proof.** "50+ other services", "11 LLM providers", "17 specialized agent types", "16 device services". Counts are surfaced in the UI too (badge with component count, "3 saved").+- **Numbers as proof.** "50+ other services", "12 LLM providers", "17 specialized agent types", "16 device services". Counts are surfaced in the UI too (badge with component count, "3 saved").- **Emoji: not part of the brand voice.** Marketing copy uses none. In-product the only emoji are *functional glyphs* (⚙️ gear button, 📦 fallback icon) — never decorative, never in sentences.- **Bold for product nouns** mid-sentence: "**AI Employee**", "**Stripe**", "**WhatsApp**".- Example headline pairs: "Personal AI assistants that remember" / "Task automations that run themselves" — lowercase-after-first-word, noun phrase + verb clause.diff --git a/docs-internal/errors.md b/docs-internal/errors.mdindex c47d22c3..4518d557 100644--- a/docs-internal/errors.md+++ b/docs-internal/errors.md@@ -139,7 +139,7 @@ construction paths.## 3. Temporal Activity `CancelledError` on Long-Running Nodes-**Symptom**: Nodes that run for more than ~2 minutes (Deep Agent, browser automation, AI multi-tool loops) fail with:+**Symptom**: Nodes that run for more than ~2 minutes (Coding Agent, browser automation, AI multi-tool loops) fail with:```asyncio.exceptions.CancelledError```diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 209f3c90..796462ae 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -173,8 +173,8 @@ client/src/│├── services/│ ├── executionService.ts # ExecutionResult shape + node-execution plumbing-│ ├── apiKeyManager.ts # LangChain API key utilities-│ └── dynamicParameterService.ts # Remote options loaders for ParameterRenderer+│ ├── dynamicParameterService.ts # Remote options loaders for ParameterRenderer+│ └── workflowApi.ts # Workflow REST helpers│├── adapters/│ └── nodeSpecToDescription.ts # Backend NodeSpec -> legacy INodeTypeDescription shapediff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.mdindex 60ccb992..d2507bc5 100644--- a/docs-internal/memory_compaction.md+++ b/docs-internal/memory_compaction.md@@ -1,121 +1,79 @@-# Memory Compaction, Token Tracking, and Cost Calculation Service+# Memory Compaction, Session Token Tracking, and Cost Calculation-> **Related docs:** [memory_lifecycle.md](./memory_lifecycle.md) for the markdown / vector-store / state-clear surface. This doc is the SSOT for the **service** (CompactionService API, thresholds, native-API integration, pricing). memory_lifecycle.md is the SSOT for the **flow** (how the markdown moves through an agent turn).+> **Related docs:** [memory_lifecycle.md](./memory_lifecycle.md) for the markdown / vector-store / state-clear surface. This doc is the SSOT for the **service** (`CompactionService`, thresholds, shared native summarization, and pricing). `memory_lifecycle.md` is the SSOT for the **flow** (how the markdown moves through an agent turn).## Overview-The compaction service enables automatic memory compaction, token tracking, and **cost calculation** for OpenCompany specialized agents. It uses a hybrid approach leveraging native provider APIs (Anthropic, OpenAI) when available, with comprehensive token and cost tracking for all providers.+`CompactionService` provides session token tracking, cost calculation, and+automatic memory compaction for agent executions that have a connected memory+session. Every provider normalizes reported usage into `services.llm.protocol.Usage`,+but only execution paths that call `CompactionService.track()` persist that+usage to the session metric tables. Standalone chat-model calls and arbitrary+third-party API requests are not part of this accounting surface.-**Inspired by:** Claude Code's compaction pattern from the Anthropic SDK-**Threshold Strategy:** per-session `custom_threshold` > per-user `UserSettings.compaction_ratio` > env `Settings.compaction_ratio` (default **0.8** = 80% of context window) > JSON `llm_defaults.json:agent.compaction.ratio` fallback-**Cost Calculation:** Official pricing from each provider (per 1M tokens)+All providers use the same client-side summarization path:+`CompactionService.compact_context()` calls+`run_native_llm_step(ChatUnifier, ...)`, then replaces the active memory+history with a structured five-section summary. The current agent runtime does+not enable Anthropic or OpenAI provider-managed compaction. Compaction reduces+active context pressure; it does not terminate an agent loop.-## Architecture--```-┌─────────────────────────────────────────────────────────────────┐-│ AI Agent Execution │-└─────────────────────────────────────────────────────────────────┘- │- ▼-┌─────────────────────────────────────────────────────────────────┐-│ CompactionService.track() │-│ ┌────────────────────────────────────────────────────────────┐ │-│ │ 1. Save TokenUsageMetric to database │ │-│ │ 2. Update SessionTokenState cumulative counters │ │-│ │ 3. Check if cumulative_total >= threshold │ │-│ │ 4. Return {total, threshold, needs_compaction} │ │-│ └────────────────────────────────────────────────────────────┘ │-└─────────────────────────────────────────────────────────────────┘- │- ▼ (if needs_compaction)-┌─────────────────────────────────────────────────────────────────┐-│ Native Provider Compaction │-│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │-│ │ Anthropic │ │ OpenAI │ │ Others │ │-│ │ context_ │ │ compact_ │ │ Client-side │ │-│ │ management │ │ threshold │ │ summarization │ │-│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │-└─────────────────────────────────────────────────────────────────┘- │- ▼-┌─────────────────────────────────────────────────────────────────┐-│ CompactionService.record() │-│ ┌────────────────────────────────────────────────────────────┐ │-│ │ 1. Save CompactionEvent to database │ │-│ │ 2. Reset SessionTokenState cumulative counters │ │-│ │ 3. Increment compaction_count │ │-│ └────────────────────────────────────────────────────────────┘ │-└─────────────────────────────────────────────────────────────────┘-```--## Native Provider APIs--### Anthropic SDK (tool_runner)--When using Anthropic's SDK with `tool_runner`, pass the compaction control config:+**Inspired by:** Claude Code's structured compaction pattern-```python-from services.compaction import get_compaction_service--svc = get_compaction_service()+**Default threshold:** per-user `UserSettings.compaction_ratio` > env+`Settings.compaction_ratio` (default **0.8** of the context window) > JSON+`llm_defaults.json:agent.compaction.ratio` fallback-# Model-aware threshold (80% of context window by default)-compaction_config = svc.anthropic_config(model="claude-opus-4.6", provider="anthropic")-# Returns: {"enabled": True, "context_token_threshold": 800000} (80% of 1M context)+**Cost calculation:** configured per-model pricing applied to usage the provider+reports; missing usage cannot be inferred-# Or override with explicit threshold-compaction_config = svc.anthropic_config(threshold=100000)-# Returns: {"enabled": True, "context_token_threshold": 100000}+## Architecture-# Use with tool_runner-result = await tool_runner(- model="claude-opus-4.6",- messages=messages,- tools=tools,- compaction_control=compaction_config-)```--### Anthropic Messages API--For direct Messages API usage with the compaction beta:--```python-# Model-aware threshold-api_config = svc.anthropic_api_config(model="claude-sonnet-4.5", provider="anthropic")-# Threshold auto-computed from model's context window (80% of 1M = 800000)--# Or override with explicit threshold-api_config = svc.anthropic_api_config(threshold=100000)--# Use with Messages API-response = await client.messages.create(- model="claude-sonnet-4.5",- messages=messages,- **api_config-)+native agent loop+ └─ aggregates Usage across all LLM iterations+ ├─ in-process + connected memory+ │ └─ CompactionService.track()+ │ ├─ persist TokenUsageMetric + calculated cost+ │ ├─ update SessionTokenState+ │ └─ if threshold reached and memory/key available:+ │ compact_context()+ └─ Temporal AgentWorkflow+ ├─ returns aggregate usage in the workflow result+ └─ when its context counter reaches the prepared threshold:+ agent.compact_memory.v1 → compact_context()++compact_context()+ └─ run_native_llm_step(ChatUnifier, selected provider/model)+ └─ five-section summary → CompactionService.record()+ ├─ persist CompactionEvent+ ├─ reset the active-context counter+ └─ increment compaction_count```-### OpenAI+## Runtime Compaction Path-For OpenAI models (including GPT-4 and o-series):+`compact_context()` uses the same native provider boundary as ordinary agent+turns. It sends one user message containing the current memory markdown through+`run_native_llm_step`, with SDK-internal retries disabled. The in-process path+allows the native step helper's bounded explicit retry policy; the Temporal+activity passes `explicit_max_retries=0` because Temporal owns activity+delivery and a repeated summarizer request can be billed twice.-```python-# Model-aware threshold-openai_config = svc.openai_config(model="gpt-5.2", provider="openai")-# Returns: {"context_management": {"compact_threshold": 320000}} (80% of 400K)--# Or override with explicit threshold-openai_config = svc.openai_config(threshold=100000)-# Returns: {"context_management": {"compact_threshold": 100000}}-```+`anthropic_config()`, `anthropic_api_config()`, and `openai_config()` remain+configuration helpers on `CompactionService`. The current chat and agent+execution paths do not pass those provider-managed compaction controls to the+SDK. `AgentWorkflow` currently calls `anthropic_config()` only as a+provider-agnostic way to calculate its numeric threshold.## Database Schema### TokenUsageMetric-Tracks token usage per agent execution:+Stores one metric whenever `CompactionService.track()` or the compaction+summarizer's internal metric writer is invoked. A memory-connected in-process+agent normally writes its loop aggregate as one row; the summarizer uses+`iteration=0`. This table is not populated by every LLM request in the system.```pythonclass TokenUsageMetric(SQLModel, table=True):@@ -165,8 +123,8 @@ class SessionTokenState(SQLModel, table=True):last_compaction_at: Optional[datetime]compaction_count: int = 0- # Per-session configuration- custom_threshold: Optional[int] # Overrides global setting+ # Stored per-session configuration (see the runtime caveat below)+ custom_threshold: Optional[int]compaction_enabled: bool = Trueupdated_at: Optional[datetime]@@ -219,7 +177,8 @@ svc = get_compaction_service()### Track Token Usage-Call after each AI agent execution:+The in-process agent path calls this after a memory-connected native agent loop+returns aggregate usage:```pythonresult = await svc.track(@@ -245,12 +204,14 @@ result = await svc.track(# "needs_compaction": False# }#-# Threshold priority: custom_threshold > per-user UserSettings.compaction_ratio > env Settings.compaction_ratio (80%) > JSON fallback+# In-process threshold priority:+# custom_threshold > per-user UserSettings.compaction_ratio+# > env Settings.compaction_ratio (80%) > JSON fallback```### Record Compaction Event-Call after native provider handles compaction:+`compact_context()` calls this after the shared client-side summarizer succeeds:```pythonawait svc.record(@@ -294,6 +255,21 @@ await svc.configure("user-session-123", enabled=False)await svc.configure("user-session-123", threshold=75000, enabled=True)```+These calls persist the fields, but their runtime effect is currently+path-dependent:++- `custom_threshold` is honored by `track()` and `stats()` on the in-process+ path.+- `AgentWorkflow` (F4.B) calculates a ratio-based threshold during+ `agent.prepare_payload.v1`; it does not read `custom_threshold`.+- `compaction_enabled` is stored but is not consulted by `track()` or F4.B.+ Only the global `COMPACTION_ENABLED` value controls `track()` today, and F4.B+ does not currently honor that global enabled flag when it extracts the+ numeric threshold.++Treat the WebSocket settings as persistence/UI controls until those execution+paths are unified; do not promise that they disable or override every run.+## WebSocket Handlers### get_compaction_stats@@ -320,7 +296,9 @@ ws.send(JSON.stringify({### configure_compaction-Update compaction settings for a session:+Persist compaction settings for a session. See the path-dependent runtime+caveat under `Configure Per-Session Settings`; a successful response confirms+storage, not that every execution path consumed the setting.```javascript// Client request@@ -350,18 +328,22 @@ COMPACTION_RATIO=0.8 # Fraction of context window that triggers compact# Read by core.config.Settings.compaction_ratio.```-**Threshold priority chain** (highest → lowest):+**In-process `track()` 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.+The ratio-based threshold is computed from+`model_registry.get_agent_defaults()["compaction"]["ratio"]` and the model+context length — for example, a 1M-token model at 0.8 gets an 800K trigger.+F4.B uses this ratio-based calculation and does not apply the first+per-session step.-### Per-Session Override+### Stored Per-Session Override-Sessions can override the global threshold:+Sessions can store a custom threshold:```python# Via service API@@ -375,6 +357,9 @@ ws.send(JSON.stringify({}));```+The custom threshold currently overrides the in-process `track()` and `stats()`+paths only; it is not read by F4.B `AgentWorkflow`.+## Integration with AI Service### Token Extraction from Native Agent Responses@@ -382,7 +367,8 @@ ws.send(JSON.stringify({Every provider normalizes token accounting into`services.llm.protocol.Usage`. The shared native agent loop adds usage fromevery iteration, including cache and reasoning tokens, and returns the-aggregate in `final_state["usage"]`:+aggregate in `final_state["usage"]`. Aggregation does not itself imply database+persistence:```pythonfinal_state = await run_native_agent_loop(...)@@ -398,9 +384,10 @@ usage = final_state["usage"]# )```-### Integration Point+### In-Process Persistence Point-In `server/services/ai.py`, after agent execution:+In `server/services/ai.py`, the in-process path calls the service only when a+memory session is connected:```python# After native agent-loop execution, before memory save@@ -422,7 +409,7 @@ if memory_data and memory_data.get('session_id'):| File | Description ||------|-------------|-| `server/services/compaction.py` | CompactionService class with model-aware thresholds and provider configs |+| `server/services/compaction.py` | `CompactionService` with session metrics, model-aware thresholds, and shared client-side summarization || `server/services/model_registry.py` | ModelRegistryService providing context_length for threshold computation || `server/models/database.py` | SQLModel tables for token tracking || `server/core/database.py` | CRUD methods for metrics and events |@@ -433,21 +420,32 @@ if memory_data and memory_data.get('session_id'):## Design Decisions-1. **Hybrid Approach**: Leverage native provider APIs (Anthropic, OpenAI) for compaction instead of reimplementing. Track tokens for all providers.+1. **One Native Summarization Path**: Every provider compacts through+ `run_native_llm_step(ChatUnifier, ...)`; the runtime does not enable+ provider-managed compaction.2. **Pydantic BaseModel**: Use Pydantic for configuration validation to reduce boilerplate code.-3. **Per-Session State**: Each memory session has independent token tracking and thresholds. This allows different agents to have different compaction settings.+3. **Per-Session State**: Each tracked memory session has independent+ counters. Stored per-session controls are not yet honored uniformly; see+ `Configure Per-Session Settings`.-4. **Model-Aware Threshold**: Threshold is `compaction_ratio` x the model's context window (default ratio **0.8** = 80%). For example, Claude Opus 4.8 (1M context) gets an 800K threshold, GPT-5.2 (400K) gets 320K, Groq models (131K) get ~105K. Ratio precedence: per-session `custom_threshold` > per-user `UserSettings.compaction_ratio` > env `Settings.compaction_ratio` (`COMPACTION_RATIO`, default 0.8) > JSON `llm_defaults.json:agent.compaction.ratio` fallback.+4. **Model-Aware Threshold**: The ratio-based threshold is+ `compaction_ratio × context_window` (default **0.8**). The in-process+ `track()` path additionally lets `custom_threshold` override that value;+ F4.B currently does not.5. **Singleton Pattern**: Service accessible via `get_compaction_service()` for easy integration anywhere in the codebase.6. **Lazy Initialization**: Service is lazily initialized via container on first access, not blocking app startup.-## Client-Side Compaction+## Shared Client-Side Compaction-For all providers (not just Anthropic/OpenAI), the service performs automatic client-side compaction when the model-aware threshold is exceeded. This uses the AI service to generate a structured summary following Claude Code's 5-section pattern. The summary max_tokens is capped at `min(4096, model's max output tokens)`.+For every provider, the service can perform client-side compaction when a+memory-connected execution reaches its applicable threshold. It uses+`ChatUnifier` through `run_native_llm_step` to generate a structured summary+following the five-section pattern. Summary `max_tokens` is capped at+`min(4096, model's max output tokens)`.### compact_context() Method@@ -496,7 +494,8 @@ Details that must be retained for continuity.### Automatic Triggering-Compaction is automatically triggered in `_track_token_usage()` when:+On the in-process path, compaction is automatically triggered in+`_track_token_usage()` when:1. `needs_compaction` returns true (cumulative tokens >= threshold)2. Memory content is available (connected memory node)3. API key is available for summarization@@ -518,6 +517,11 @@ if tracking.get('needs_compaction') and memory_content and api_key:memory_data['memory_content'] = result['summary']```+F4.B performs a parallel check inside `AgentWorkflow` using the workflow's+active-context usage counter and the ratio-based threshold recorded by+`agent.prepare_payload.v1`. It invokes the same `compact_context()` method+through `agent.compact_memory.v1`.+### AI Service WiringThe compaction service requires the AI service to generate summaries. This is wired during app startup:@@ -532,11 +536,12 @@ compaction_svc.set_ai_service(container.ai_service())## WebSocket Broadcasts-The service broadcasts real-time updates to the frontend:+The in-process integration can broadcast real-time updates to the frontend:### token_usage_update-Broadcast after each AI execution with token tracking:+Broadcast after a memory-connected in-process execution successfully tracks+usage:```json{diff --git a/docs-internal/memory_lifecycle.md b/docs-internal/memory_lifecycle.mdindex d84aa0da..72e39edb 100644--- a/docs-internal/memory_lifecycle.md+++ b/docs-internal/memory_lifecycle.md@@ -13,7 +13,7 @@ Canonical home for how conversation memory is loaded, appended, trimmed, archive| Format | File | Used by | Wire shape ||---|---|---|---|| **Markdown transcript** | [`services/memory/markdown.py`](../server/services/memory/markdown.py) | aiAgent, chatAgent, rlm_agent, claude_code_agent (mirror) | `### **Human/Assistant** (timestamp)` blocks under a top-level `# Conversation History` heading |-| **Anthropic-Messages JSONL** | [`services/memory/jsonl.py`](../server/services/memory/jsonl.py) | Standalone primitive — not used by any agent today | One JSON object per line: `{"role": "user"|"assistant", "content": str \| [ContentBlock], ...metadata}` |+| **Anthropic-Messages JSONL** | [`services/memory/jsonl.py`](../server/services/memory/jsonl.py) | Standalone primitive — not used by any agent today | One JSON object per line: `{"role": "user"|"assistant", "content": str \| [ContentBlock], ...metadata}`; parsing normalizes to `Message` and discards metadata |The markdown format is the visible UI surface — `simpleMemory.memory_content`is rendered as a markdown editor in the parameter panel. The normalized JSONL@@ -21,7 +21,9 @@ helpers remain a standalone primitive; the live `claude_code_agent` bridgeuses claude's own native session JSONL on disk (see §6) and mirrors thetranscript into `memory_content` via the **markdown** helpers for visibility.-## 2. Markdown helper API+## 2. Normalized helper APIs++### Markdown transcriptThree pure functions, no I/O, locked by `tests/services/memory/`:@@ -47,12 +49,57 @@ from services.memory import (This is also the value `clear_agent_session_state` resets `memory_content` to (see §5). Defined as `DEFAULT_MEMORY_CONTENT` in [`services/memory/state.py`](../server/services/memory/state.py).+### Standalone JSONL++The JSONL module is a tested, re-exported primitive, but no production agent+currently calls it:++```python+from services.memory import (+ parse_jsonl, # str -> List[services.llm.protocol.Message]+ append_message, # (text, role, content, **metadata) -> str+ trim_window, # (text, window_size_pairs) -> (trimmed, removed_lines)+)+```++- **`parse_jsonl`** accepts only `user` and `assistant` rows. String content+ passes through; list content is reduced to its text blocks, joined with+ spaces. Tool blocks, unknown roles, invalid JSON, non-string content, and+ extra metadata are omitted from the returned native `Message` values.+- **`append_message`** writes `role`, `content`, and supplied metadata to one+ JSON object and always ends the result with a newline. Metadata remains on+ that serialized line, but `parse_jsonl` does not copy it into `Message`;+ this is wire preservation, not a metadata round trip through the parser.+- **`trim_window`** counts non-empty rows and keeps the last+ `window_size * 2`. When trimming is required, it rebuilds the result without+ blank lines and returns older serialized rows verbatim; under capacity it+ returns the original input unchanged.++Claude Code's CLI owns and reads its native session JSONL independently. The+helpers above do not parse or rewrite those live CLI files.++### Direct process-local message log++[`services/memory_store.py`](../server/services/memory_store.py) is a separate+process-local log. `add_message` normalizes legacy roles (`human` → `user`,+`ai` → `assistant`); `get_messages` returns timestamped dictionaries for the+`simpleMemory.read` operation; and `get_native_messages` returns the stored+native `Message` values directly, filtered to `user`/`assistant`. Its optional+window is a count of individual messages, not user/assistant pairs.++This log is currently written directly by `rlm_agent`. It is not the+DB-backed `memory_content` transcript used passively by aiAgent/chatAgent and+the Claude UI mirror, and it does not survive a process restart.+## 3. Canonical implementation and call sites-`services.memory` is the single implementation. `services.ai` keeps only a-thin `_parse_memory_markdown` compatibility wrapper and aliases the canonical+`services.memory` is the canonical implementation for DB-backed markdown,+the standalone JSONL helpers, vector memory, and reset orchestration. The+direct process-local `services.memory_store` log described above remains a+separate surface. `services.ai` keeps only a thin+`_parse_memory_markdown` compatibility wrapper and aliases the canonicalvector-store cache so older internal imports continue to resolve without-creating duplicate state. Runtime appends use+creating duplicate vector state. Runtime appends use`services.memory.runtime.append_memory_turns_atomic`, which performs theappend/trim mutation transactionally and idempotently.@@ -62,6 +109,7 @@ append/trim mutation transactionally and idempotently.| `services/temporal/agent_activities.py` — `agent.persist_turn.v1` | `append_memory_turns_atomic` || `services/cli_agent/service.py` — claude_code_agent mirror | markdown/runtime helpers and canonical vector store || `services/memory/state.py` — reset orchestration | canonical vector-store cache + atomic parameter mutation |+| `services/memory_store.py` — direct process-local log | `add_message`, `get_messages`, `get_native_messages`, `clear_session` |## 4. Long-term vector store@@ -69,9 +117,11 @@ append/trim mutation transactionally and idempotently.provides a shared async embedder factory for direct `openai.AsyncOpenAI`,`ollama.AsyncClient`, and optional `sentence-transformers` adapters, thenranks entries locally by cosine similarity. Hugging Face model load and-encoding run in a worker thread. When its `local-embeddings` extra is absent,-the factory returns `None` with a warning, so long-term archival remains-best-effort.+encoding run in a worker thread. `create_embedder` is the strict constructor:+it raises `EmbedderUnavailableError` for a missing SDK/optional extra or a+missing OpenAI credential. The higher-level `get_memory_vector_store` factory+catches availability failures, logs a warning, and returns `None`, so+long-term archival remains best-effort.```pythonfrom services.memory import get_memory_vector_store@@ -110,7 +160,7 @@ Three stores are cleared in one call:1. **Vector store** (when `clear_long_term=True`) — delete and close every provider/model cache entry for the session (the `services.ai` alias observes the same deletion).2. **TodoService** — every candidate key (`workflow_id`, `session_id`, `"default"`) is cleared because [`server/nodes/tool/write_todos/__init__.py`](../server/nodes/tool/write_todos/__init__.py) uses `ctx.workflow_id or ctx.node_id or "default"` as the storage key and we want to clear whichever fallback the write path actually used.-3. **simpleMemory node fields** (when `memory_node_id` provided) — `memory_content` → `DEFAULT_MEMORY_CONTENT`; `last_session_id` → `None` (so claude_code_agent starts fresh next run instead of `--resume`-ing into a wiped transcript); orphan `memory_jsonl` field popped if present.+3. **simpleMemory node fields** (when `memory_node_id` provided) — `memory_content` → `DEFAULT_MEMORY_CONTENT`; diagnostic/back-compat `last_session_id` → `None`; orphan `memory_jsonl` field popped if present. Normal Claude continuity uses stable `cwd` plus `--continue`, so clearing this field alone neither deletes Claude's native JSONL nor guarantees a fresh Claude conversation.Frontend `clear_memory` WS handler ([`routers/websocket.py:2167`](../server/routers/websocket.py)) calls this; UI presents a Reset Memory button on the simpleMemory parameter panel.@@ -130,24 +180,40 @@ the authoritative Simple Memory parameters into the archived generation's`runtime_data.simple_memory` map. It then resets the live memory-node fields,connected agent sessions, vector caches, direct memory-store sessions,conversation rows, and token counters. The next Temporal generation therefore-starts with the empty conversation placeholder.+starts with the empty DB-backed conversation placeholder. Claude's own+on-disk session history is a separate lifecycle; `--continue` can still find+it until that native session data is cleared.The archived copy is immutable history; the live `node_parameters` row remainsthe source of truth and is reset to the empty-state value for the next Start.## 6. claude_code_agent native session resume bridge-`claude_code_agent` does **not** inject `memory_content` as a system prompt. It calls claude's CLI with `--resume <UUID>` so claude reads its own native JSONL transcript on disk (`<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`). The bridge has three coupled mechanisms; full plumbing in [cli_agent_framework.md → Memory bridge](./cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent).+`claude_code_agent` does **not** inject `memory_content` as a system prompt.+When memory is connected, normal spawns use Claude's `--continue` flag from a+stable working directory. Claude then selects its latest native JSONL+transcript under+`<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. Full plumbing+is in [cli_agent_framework.md → Memory bridge](./cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent).| Mechanism | Where | Why ||---|---|---|-| **Stable `cwd=repo_root`** | `AICliSession.cwd()` when `memory_bound=True` | Keeps claude's `project_key = re.sub(r"[^a-zA-Z0-9.-]", "-", str(cwd))` constant so `--resume <UUID>` finds the prior JSONL |-| **UUID5 first-run / `--resume` thereafter** | `claude_code_agent.execute()` | First run: `uuid5(NAMESPACE_OID, f"{memory_node_id}:{session_id}")` → `--session-id <UUID5>`. Subsequent runs: `simpleMemory.last_session_id` → `--resume <UUID>` |-| **Auto-clear stale `last_session_id`** | `_persist_memory` in `services/cli_agent/service.py` | When claude returns `No conversation found with session ID: <UUID>`, wipe `last_session_id` (preserve `memory_content`); next run self-heals |--`memory_content` is the UI mirror, not the resume channel. `_persist_memory` ([`services/cli_agent/service.py:446-513`](../server/services/cli_agent/service.py)) appends every successful run's user prompt + assistant response to it via the **same markdown helpers** aiAgent uses, and saves the most recent run's `r.session_id` to `simpleMemory.last_session_id` in one DB write. Always broadcasts `node_parameters_updated` (CloudEvents v1.0 envelope, `source_hint="cli"`) so the simpleMemory parameter panel auto-refetches mid-run.--**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`, `claude_code_agent` raises `NodeUserError` — concurrent `--resume <UUID>` spawns against one JSONL would race.+| **Stable `cwd=repo_root`** | `AICliSession.cwd()` when `memory_bound=True` | Keeps Claude's cwd-derived project key constant so `--continue` searches the same project history |+| **`--continue` for normal continuity** | `claude_code_agent.execute()` | Every memory-bound task opts into `continue_session`; with no prior session Claude starts fresh, otherwise it loads the latest session for that cwd |+| **Returned session ID** | `_persist_memory` in `services/cli_agent/service.py` | Saves the latest returned UUID to `simpleMemory.last_session_id` for diagnostics and backward compatibility; normal node execution does not read it to select the next session |++`memory_content` is the UI mirror, not the continuation channel.+`_persist_memory` appends every successful run's user prompt + assistant+response to it via the **same markdown helpers** aiAgent uses, and records the+most recent `r.session_id` in the same DB write. It broadcasts+`node_parameters_updated` (CloudEvents v1.0 envelope, `source_hint="cli"`) so+the simpleMemory parameter panel auto-refetches mid-run. Explicit+`--resume <UUID>` remains an internal compatibility/crash-recovery mechanism,+but it is not driven by `last_session_id` during the normal node path.++**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`,+`claude_code_agent` raises `NodeUserError` because concurrent memory-bound CLI+turns under one cwd could race over the same session state.## 7. The lifecycle in motion (aiAgent example)@@ -155,7 +221,7 @@ the source of truth and is reset to the empty-state value for the next Start.Turn N starts│▼-1. handle_ai_agent / handle_chat_agent reads simpleMemory.memory_content from DB+1. The agent plugin/prepare step reads simpleMemory.memory_content from DB│▼2. _parse_memory_markdown(content) → List[native Message]@@ -180,7 +246,8 @@ Turn N starts7. (Optional) await store.add_texts(removed_texts) — long-term archival```-F4.B `AgentWorkflow` runs steps 4-9 as separate Temporal activities.+F4.B `AgentWorkflow` runs the work represented by steps 4-7 as separate+Temporal activities.`prepare_payload.v1` records `llm_engine` and the message wire version;new executions use native Message Wire V2, preserving Gemini thoughtsignatures, Anthropic signed/redacted thinking, and OpenAI continuation@@ -194,8 +261,8 @@ progress.| Engine | Memory shape on input | Memory shape on output | Notes ||---|---|---|---|| `aiAgent` / `chatAgent` | Native `Message` list parsed from markdown | Atomic appended pair + trim | Native SDK path; see §7 |-| `rlm_agent` | Markdown injected as REPL pre-context | Last `FINAL(...)` call's payload | RLM internal recursion uses its own state machine; only entry/exit cross the memory boundary |-| `claude_code_agent` | `--resume <UUID>` reads native JSONL; `memory_content` ignored on input | Bridge writes markdown mirror + saves `last_session_id` | See §6 |+| `rlm_agent` | DB-backed Markdown injected as REPL pre-context | Prompt/response appended to the direct process-local `services.memory_store` log; DB Markdown is not updated | RLM internal recursion uses its own state machine; only entry/exit cross the memory boundary |+| `claude_code_agent` | Stable cwd + `--continue` lets Claude select its native JSONL; `memory_content` ignored on input | Bridge writes markdown mirror + saves diagnostic/back-compat `last_session_id` | See §6 |## 9. Compaction trigger@@ -221,5 +288,8 @@ The CloudEvents `node_parameters_updated` envelope emitted on every memory write- Don't write to `simpleMemory.memory_content` without broadcasting `node_parameters_updated` — the parameter panel won't refetch and users will see stale content.- Don't add new local copies of the markdown helpers. Import from `services.memory` (or from `services.memory.markdown` / `.jsonl` directly).- Don't bypass `clear_agent_session_state` to "just delete the markdown" — TodoService and the vector store will leak across sessions.-- Don't inject `memory_content` as a system prompt for `claude_code_agent` — `--resume <UUID>` is the resume channel; `memory_content` is for the human reader.-- Don't run claude_code_agent with `memory_bound=True` in parallel batches — the `--resume` guard raises `NodeUserError` and you'll burn a credit.+- Don't inject `memory_content` as a system prompt for `claude_code_agent` —+ stable-cwd `--continue` is the normal continuation channel;+ `memory_content` is for the human reader.+- Don't run claude_code_agent with `memory_bound=True` in parallel batches —+ the continuity guard raises `NodeUserError` and you'll burn a credit.diff --git a/docs-internal/native_llm_sdk.md b/docs-internal/native_llm_sdk.mdindex 54523a73..8d18c820 100644--- a/docs-internal/native_llm_sdk.md+++ b/docs-internal/native_llm_sdk.md@@ -13,7 +13,10 @@ LangChain added a useful abstraction early on, but it introduced three recurring1. **Windows/Python 3.13 hangs**: `langchain_google_genai` deadlocks on gRPC init. The native Gemini path bypasses LangChain entirely and uses `google.genai.Client` directly.2. **Parameter translation loss**: LangChain's `max_completion_tokens` rewrite breaks OpenAI-compatible providers (DeepSeek, Kimi, Mistral) that expect `max_tokens`.-3. **Hard-coded URLs**: Each provider class in LangChain hard-codes its base URL. The native layer reads `base_url` from `server/config/llm_defaults.json`, so adding an OpenAI-compatible provider is a config change.+3. **Endpoint control**: OpenAI-compatible endpoint URLs are declared in+ `server/config/llm_defaults.json` and registered through `_compat.py`.+ Adding one requires the JSON entry plus one `_COMPAT_PROVIDERS` entry, not a+ provider-specific adapter class.The native layer also gives a single normalized response shape (`LLMResponse`) across providers, which simplifies downstream code for token tracking, cost calculation, and thinking extraction.@@ -42,8 +45,9 @@ server/services/llm/```Each provider module calls `register_provider(ProviderSpec(...))` at module-bottom — that side-effect IS the registration contract; there is no central-provider list to edit.+bottom. Shipped provider modules are imported from `providers/__init__.py` so+their registration side effects run at service import. OpenAI-compatible+providers share `_compat.py` and its explicit `_COMPAT_PROVIDERS` tuple.## Supported Providers@@ -80,21 +84,20 @@ Source of truth for this list: `server/config/llm_defaults.json` (the `providers| Provider | Key Models | Context | Max Output | Thinking | Temp Range ||----------|-----------|---------|-----------|----------|------------|-| **OpenAI** | GPT-5.5/5.4/5.2 | 400K–1.05M | 128K | effort (hybrid) | 0-2 |-| **OpenAI** | GPT-4.1/4.1-mini/4.1-nano | 1M | 32K | none | 0-2 |-| **OpenAI** | o3, o4-mini | 200K | 100K | effort (reasoning) | fixed 1.0 |-| **OpenAI** | GPT-4o/4o-mini | 128K | 16K | none | 0-2 |+| **OpenAI** | GPT-5.6 Sol/Terra/Luna, GPT-5.5/5.4 | 1.05M | 128K | effort | omitted for reasoning models |+| **OpenAI** | GPT-4.1 | ~1.05M | 32K | none | 0-2 || **Anthropic** | Claude Fable 5 | 1M | 128K | budget | 0-1 || **Anthropic** | Claude Opus 4.8/4.7 | 1M | 128K | budget | 0-1 || **Anthropic** | Claude Sonnet 4.6 | 1M | 64K | budget | 0-1 || **Anthropic** | Claude Haiku 4.5 | 200K | 64K | budget | 0-1 || **Google** | Gemini 3.5-flash, 3.1-pro/flash-lite, 3-flash, 2.5-pro/flash/flash-lite | 1M | 64K | budget | 0-2 |+| **xAI** | Grok 4.20/4.20-multi-agent, 4.5, 4.3, 3 | 131K-2M | 131K | model/provider dependent | 0-2 || **DeepSeek** | deepseek-v4-flash, deepseek-v4-pro (deepseek-chat/reasoner legacy) | 1M | 64K | thinking modes | 0-2 |-| **Kimi** | kimi-k2.6, kimi-k2.5, kimi-k2.7-code | 256K | 96K | on by default (disabled for agents) | fixed 0.6 |+| **Kimi** | kimi-k3 (default), kimi-k2.6, kimi-k2.5, kimi-k2.7-code | 1M (K3); 256K (K2) | 131K (K3); 32K/96K (K2) | K2 provider default explicitly disabled unless requested | K2 fixed 0.6; K3 0-1 || **Mistral** | mistral-large/medium/small-latest, codestral-latest | 256K | 131K | none | 0-1.5 |-| **Groq** | Llama 3.3-70b, Llama 3.1-8b, GPT-OSS-120b/20b, Qwen3-32b | 131K | 8-131K | format (Qwen3) | 0-2 |+| **Groq** | GPT-OSS-120b/20b, Qwen3-32b, legacy Llama 3.x tiers | 131K | 32K-131K | effort (GPT-OSS), format (Qwen3) | 0-2 || **OpenRouter** | 200+ models from multiple providers | varies | varies | varies | 0-2 |-| **Cerebras** | GPT-OSS-120b, Qwen-3-235b, GLM-4.7 | 131K | 65K | budget (Qwen) | 0-1.5 |+| **Cerebras** | GPT-OSS-120b, Z.ai GLM 4.7, Gemma 4 31B | 131K | 40K | budget (GLM preview) | 0-1.5 || **Ollama** | Whatever the user has pulled (qwen2.5, llama3.x, phi-3, deepseek-r1, ...) | per-loaded-model (typed via `ps()`) | ctx ÷ 4 (capped 4096) | none (per-model) | 0-2 || **LM Studio** | Whatever the user has loaded in the LM Studio UI | per-loaded-model (typed via `LlmInstanceInfo.context_length`) | ctx ÷ 4 (capped 4096) | none (per-model) | 0-2 |@@ -168,17 +171,20 @@ class LLMResponse:`thinking`, and `tool_calls` fields remain convenience views; `raw` is neverwritten to memory or Temporal history.-## Registry, Unifier, and Lazy Imports+## Registry, Unifier, and Lazy SDK Clients-Providers self-register and are imported only when first used, so no SDK-loads at startup (locked by `tests/llm/test_lazy_sdk_imports.py`):+The lightweight provider modules are imported eagerly so the registry is+complete at service startup. Heavy SDK imports, exception-class resolution,+and client construction are deferred until first use; `ChatUnifier` then keeps+clients in its bounded cache. This boundary is locked by+`tests/llm/test_lazy_sdk_imports.py`:```python# server/services/llm/providers/anthropic.py — bottom of the moduleregister_provider(ProviderSpec(name="anthropic",- factory=lambda api_key, **kw: AnthropicProvider(api_key, **kw), # lazy: class imported here only+ factory=lambda api_key, **kw: AnthropicProvider(api_key, **kw), # invoked when a client is first neededsdk_exception_refs=("anthropic:APIError",), # "module:Class" string, resolved at except time))@@ -212,7 +218,7 @@ class ProviderConfig:base_url: str = "" # OpenAI-compatible base URL```-Adding a new OpenAI-compatible provider is a pure config change:+Adding a new OpenAI-compatible provider requires a config entry:```json"deepseek": {@@ -226,7 +232,16 @@ Adding a new OpenAI-compatible provider is a pure config change:}```-No new provider class, no new import. `providers/_compat.py` registers a spec whose factory reuses `OpenAIProvider` with the config's `base_url`.+Then add the same provider name to `_COMPAT_PROVIDERS` in+`providers/_compat.py`. No new provider class or module import is needed: the+compat loop reuses `OpenAIProvider` and pins the JSON `base_url` in+`ProviderSpec.client_kwargs`.++At client creation, a stored `{provider}_proxy` URL takes precedence over that+configured compat URL. Plain OpenAI uses the SDK default endpoint unless+`openai_proxy` is set. OpenRouter uses its adapter's built-in endpoint unless+`openrouter_proxy` is set. Ollama and LM Studio rely on their stored proxy URL+at runtime so requests go to the selected local server.## Unified Native Execution Path@@ -244,9 +259,11 @@ ChatUnifier.chat(provider=..., Message[], ToolDef[])`run_native_agent_loop` appends the provider's exact assistant envelope beforeexecuting tools. This preserves Gemini thought signatures, Anthropic signed andredacted thinking blocks, and OpenAI reasoning continuation state across-in-process and Temporal turns. Temporal executions created before the migration-remain pinned to the legacy engine by their recorded prepare-activity result;-new executions record `llm_engine=native` and wire version 2.+in-process and Temporal turns. A markerless prepare result identifies a+pre-cutover history and selects the legacy branch. New executions normally+record `llm_engine=native` and wire version 2; the temporary emergency setting+can instead record `llm_engine=langchain`. Either recorded choice remains+deterministic on replay.## Thinking and Reasoning@@ -359,7 +376,8 @@ AI providers support optional proxy-based authentication — requests route throFor every new chat and agent run, `proxy_url` flows through `ChatUnifier` intothe cached native provider factory. The old `create_model()` proxy path exists-only for histories already pinned to `llm_engine=langchain`.+only for markerless pre-cutover histories or emergency executions whose+prepare result is explicitly pinned to `llm_engine=langchain`.**Use cases:** Claude Code CLI proxy for Anthropic models; native Ollama / LM Studio support; custom auth proxies; dev/testing with mock servers.@@ -426,7 +444,8 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":2. **Custom-SDK provider** (Anthropic, Gemini pattern):- Create `services/llm/providers/<name>.py` implementing the `LLMProvider` protocol.- - At module bottom call `register_provider(ProviderSpec(name=..., factory=..., sdk_exception_refs=("sdk_module:ErrorClass",)))` — the lazy factory + string exception refs keep the SDK unimported until first use (never import the SDK at registration; locked by `tests/llm/test_lazy_sdk_imports.py`).+ - At module bottom call `register_provider(ProviderSpec(name=..., factory=..., sdk_exception_refs=("sdk_module:ErrorClass",)))` and add the module to the side-effect imports in `services/llm/providers/__init__.py`.+ - Keep the SDK import inside provider construction or call methods. The eager provider-module import registers the spec; the factory and string exception refs keep SDK loading and client construction lazy (locked by `tests/llm/test_lazy_sdk_imports.py`).- Add a config entry in `llm_defaults.json` (no `base_url` needed if the SDK handles URLs itself).- There is no `factory.py` to touch — the legacy factory module was removed; registration via `register_provider` is the only entry point.@@ -440,7 +459,7 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":|---|---|| `server/nodes/model/<provider>_chat_model/__init__.py` | Plugin entry — metadata + Params + auto-registers || `server/nodes/model/_credentials.py` | `Credential` subclass per provider |-| `server/config/llm_defaults.json` | base_url + supported_params + temperature constraints (no hardcoded URLs in Python) |+| `server/config/llm_defaults.json` | OpenAI-compatible `base_url` values plus supported parameters and model constraints; dedicated SDK providers may use SDK defaults, and OpenRouter owns its gateway fallback in Python || `server/services/llm/providers/<provider>.py` | Native SDK provider (Protocol-based) + `register_provider(ProviderSpec)` at module bottom || `server/services/llm/registry.py` | `ProviderSpec` / `register_provider` — the provider registration contract || `server/services/llm/unifier.py` | `ChatUnifier` — chat dispatch facade + typed-error translation |diff --git a/docs-internal/node-logic-flows/ai_agents/chatAgent.md b/docs-internal/node-logic-flows/ai_agents/chatAgent.mdindex 8eb5e70b..f68e05f4 100644--- a/docs-internal/node-logic-flows/ai_agents/chatAgent.md+++ b/docs-internal/node-logic-flows/ai_agents/chatAgent.md@@ -31,7 +31,7 @@ own plugin folder; there is no `functools.partial` wiring anymore.| `input-main` | main | no | Upstream data. Auto-prompt fallback when `prompt` is empty. || `input-skill` | main | no | Skill nodes (including `masterSkill` aggregation). || `input-memory` | main | no | `simpleMemory` node for conversation history. |-| `input-tools` | main | no | Tool nodes bound to the LLM via `chat_model.bind_tools`. |+| `input-tools` | main | no | Tool nodes compiled into provider-neutral `AgentToolSpec` / `ToolDef` values for each native LLM step. || `input-task` | main | no | `taskTrigger` output - formatted and prepended to the prompt. || `input-teammates` | main | no | **Team-lead only** (`orchestrator_agent`, `ai_employee`). Agents on this handle become authorized Task Manager assignees. |@@ -80,6 +80,10 @@ flowchart TD`edge_walker.collect_agent_connections`; same rules as `aiAgent` (see that docfor memory session derivation, `masterSkill` expansion, Android toolkit,child-agent tool discovery).+- **Native agent loop**: current executions call the shared+ `run_native_agent_loop` / `run_native_llm_step` service through+ `ChatUnifier`. The LangChain tool-binding loop is retained only for+ replaying eligible pre-cutover or emergency-pinned Temporal histories.- **Task context injection** mirrors `aiAgent`: `format_task_context` wrapsthe task result as a plain-English instruction that the LLM must "reportnaturally", then all tools are stripped if the task has already completed@@ -95,9 +99,11 @@ flowchart TD## Side Effects-- **Database writes**: none directly. `execute_chat_agent` writes- `token_usage_metrics` and updates the connected `simpleMemory` node's- `memoryContent` via `database.save_node_parameters`.+- **Database writes**: none directly. In-process execution can update a+ connected `simpleMemory` node and record compaction usage for that memory+ session; the Temporal workflow accumulates normalized usage in its result+ envelope. Standalone executions without connected memory do not persist a+ token metric here.- **Broadcasts**: `StatusBroadcaster` is fetched and passed down, enabling`update_node_status` events (`thinking`, `executing_tool`, `success`), plus`token_usage_update` from the compaction tracker.diff --git a/docs-internal/node-logic-flows/ai_chat_models/anthropicChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/anthropicChatModel.mdindex f6eab0ba..ca7dc533 100644--- a/docs-internal/node-logic-flows/ai_chat_models/anthropicChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/anthropicChatModel.md@@ -11,7 +11,7 @@## Purpose-Single-turn chat completion against the Anthropic Messages API (Claude family). The `ChatModelBase.chat` operation (in `_base.py`) calls `AIService.execute_chat` for every chat-model node; provider-specific branching lives inside `execute_chat` and the native `services/llm/providers/anthropic.py`. Also wired as an AI-agent advisor tool (`usable_as_tool = True`) so an agent can consult a stronger model mid-task.+Single-turn chat completion against the Anthropic Messages API (Claude family). The `ChatModelBase.chat` operation (in `_base.py`) calls the provider-neutral `AIService.execute_chat`; Anthropic-specific request and response behavior lives in `services/llm/providers/anthropic.py` behind `ChatUnifier`. Also wired as an AI-agent advisor tool (`usable_as_tool = True`) so an agent can consult a stronger model mid-task.## Inputs (handles)@@ -73,7 +73,7 @@ flowchart TDG --> H[Lookup anthropic_proxy credential]H --> I[ChatUnifier.chat -> registry.get_provider anthropic<br/>await provider.chat with thinking]I --> J[Return success envelope with response + thinking]- I -- Exception --> X+ I -- typed SDK error --> X[NodeUserError -> BaseNode error envelope]```## Decision Logic@@ -81,7 +81,7 @@ flowchart TD- **Validation**: missing api_key or empty prompt -> error envelope.- **Provider routing**: `detect_ai_provider` matches `'anthropic'` on `'anthropic' in node_type.lower()` branch.- **Native provider**: `ChatUnifier` resolves the self-registered `anthropic` spec - uses the `anthropic` Python SDK.-- **Model ID scrubbing**: strips `[FREE] ` prefix; strips `owner/` prefix for non-OpenRouter providers.+- **Model ID handling**: strips only the UI-only `[FREE] ` decoration. Provider model IDs are otherwise treated as opaque and preserved.- **Temperature override**: when `thinkingEnabled=true`, temperature is auto-forced to 1 by `native_resolve_temperature`.- **Thinking config**: `NativeThinkingConfig(enabled=True, budget=int(thinkingBudget))` forwarded to the SDK, which maps to Anthropic's `thinking={type: "enabled", budget_tokens: N}`.@@ -89,7 +89,7 @@ flowchart TD- **Database writes**: none on the bare chat path.- **Broadcasts**: none.-- **External API calls**: `POST https://api.anthropic.com/v1/messages` via `anthropic` SDK; base URL configurable in `llm_defaults.json`, overridable via `anthropic_proxy` credential.+- **External API calls**: Anthropic Messages API via the `anthropic` SDK's default endpoint; an `anthropic_proxy` credential can override the SDK base URL.- **File I/O**: none.- **Subprocess**: none.@@ -103,10 +103,10 @@ flowchart TD## Edge cases & known limits- **Model ID format**: Anthropic API uses hyphens (`claude-sonnet-4-6`), NOT dots. Dotted IDs (as used by OpenRouter or Gemini) will 404. The frontend model list already uses the correct form, but template-substituted or hand-entered IDs with dots will fail.-- **`maxTokens > thinkingBudget` required**: if thinking is enabled and `maxTokens <= thinkingBudget`, the Anthropic API rejects the request. The handler does not pre-validate this; the resulting error becomes the envelope's `error` field.+- **Thinking budget versus output**: when thinking is enabled and the requested `maxTokens` does not exceed `thinkingBudget`, the native provider raises `max_tokens` to `thinkingBudget + 1024` before calling Anthropic.- **Temperature forced to 1 when thinking enabled**: regardless of user input.- **1M context**: current Claude models (Fable 5, Opus 4.x, Sonnet 4.6) support a 1M context window; configured in `llm_defaults.json` rather than the node.-- **Errors swallowed into envelope**: handler never raises; all failures surface as `success=false`.+- **Error boundary**: typed Anthropic SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.- **No streaming** / **no pricing tracking** on standalone chat nodes.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.mdindex fe88667e..a8b20edf 100644--- a/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.md@@ -11,8 +11,9 @@## Purpose-Ultra-fast inference on Cerebras' custom AI hardware. Models include Llama-3.1, GPT-OSS-120b, Qwen-3-235b. The `ChatModelBase.chat` operation calls+Ultra-fast inference on Cerebras' custom AI hardware. The current curated+models are GPT-OSS-120b plus preview Z.ai GLM 4.7 and Gemma 4 tiers. The+`ChatModelBase.chat` operation calls`AIService.execute_chat`, which routes through `ChatUnifier`. Like Groq,Cerebras is one of the eight OpenAI-compatible providers registered in`providers/_compat.py`; bare chat and current agent executions share this@@ -71,7 +72,7 @@ flowchart TDC --> D{valid key + prompt?}D -- no --> X[error envelope]D -- yes --> E[detect_ai_provider -> 'cerebras']- E --> F[Strip 'owner/' prefix]+ E --> F[Preserve opaque provider model ID]F --> G[ChatUnifier.chat provider='cerebras']G --> H[registry.get_provider cerebras<br/>_compat.py spec: OpenAIProvider + base_url=api.cerebras.ai/v1]H --> I[await provider.chat -> LLMResponse]@@ -86,7 +87,7 @@ flowchart TD- **Native OpenAI-compatible path**: `ChatUnifier` resolves the `cerebras`spec registered in `providers/_compat.py` (reuses `OpenAIProvider` with theCerebras `base_url`) for both chat and agent requests.-- **Reasoning**: same parsed/hidden mechanism as Groq Qwen - only the Qwen-3-235b variant honors it.+- **Reasoning**: the curated reasoning-capable model is `zai-glm-4.7`; other current Cerebras models ignore the shared thinking controls.- **Temperature range**: narrower (0-1.5 clamp) than OpenAI/Groq. `_resolve_temperature` applies the clamp.## Side Effects@@ -107,9 +108,9 @@ flowchart TD## Edge cases & known limits- **Temperature capped at 1.5**, not 2.-- **Reasoning only on Qwen-3-235b**.-- **Small max output**: 8K for most models; exceeding this surfaces as a provider-side error in the envelope.-- **Errors swallowed into envelope**.+- **Reasoning only on the configured GLM preview tier**.+- **Output ceiling**: current curated Cerebras models allow up to 40,960 output tokens; unknown models use the configured 8K fallback.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.mdindex 67c44fc3..432cdd45 100644--- a/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.md@@ -65,7 +65,7 @@ flowchart TDC --> D{valid key + prompt?}D -- no --> X[error envelope]D -- yes --> E[detect_ai_provider -> 'deepseek']- E --> F[Strip 'owner/' prefix]+ E --> F[Preserve opaque provider model ID]F --> G[ChatUnifier.chat -> registry.get_provider deepseek<br/>OpenAI SDK w/ DeepSeek base_url]G --> H[provider.chat]H --> I[success envelope]@@ -76,7 +76,8 @@ flowchart TD- **Validation**: missing api_key / empty prompt -> error envelope.- **Provider routing**: `detect_ai_provider` matches `'deepseek' in node_type.lower()` **first** (before kimi/mistral/cerebras/groq/openrouter/anthropic/gemini), so routing is unambiguous.-- **Native path**: uses the OpenAI SDK with DeepSeek's base URL from `llm_defaults.json`. OpenAI-compatible `max_tokens` is passed via `extra_body` to bypass LangChain's `max_completion_tokens` translation (not relevant on the native path but documented for the LangChain-agent path).+- **Native path**: uses the OpenAI SDK with DeepSeek's base URL from `llm_defaults.json`. The compatible provider sends `max_tokens` directly in the Chat Completions request; there is no LangChain parameter translation on current chat or agent executions.+- **Model ID handling**: only the UI-only `[FREE] ` decoration is stripped. The remaining model ID is preserved.- **`deepseek-reasoner` always-on CoT**: reasoning_content is ALWAYS produced, regardless of `thinkingEnabled`. The native provider extracts it into `LLMResponse.thinking`.## Side Effects@@ -98,9 +99,9 @@ flowchart TD- **`deepseek-reasoner` always thinks**: `thinkingEnabled=false` does NOT disable the reasoning trace; it just means the UI won't highlight it. The response still contains `reasoning_content`.- **`thinkingBudget` has no effect**: DeepSeek reasoning is not budget-configurable; the field is silently ignored.-- **128K context, up to 64K output**.+- **Context and output**: the curated V4 models use a 1,048,576-token context window and a 65,536-token output ceiling; legacy `deepseek-chat` and `deepseek-reasoner` remain 131,072-context aliases.- **OpenAI-compatible but not OpenAI**: features like `response_format: json_object` have subtly different behavior.-- **Errors swallowed into envelope**.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.mdindex 677d5946..cb32aaaf 100644--- a/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.md@@ -71,7 +71,7 @@ flowchart TDF --> G[ChatUnifier.chat -> registry.get_provider gemini<br/>google.genai.Client]G --> H[provider.chat -> LLMResponse]H --> I[success envelope]- G -- Exception --> X+ G -- typed SDK error --> X[NodeUserError -> BaseNode error envelope]```## Decision Logic@@ -81,13 +81,13 @@ flowchart TD- **Native SDK**: `ChatUnifier` uses `google.genai.Client` for both chat andcurrent agent requests.- **Thinking budget**: `thinkingBudget` -> `NativeThinkingConfig.budget` -> Gemini `thinking_budget` API parameter.-- **Model string scrubbing**: `[FREE] ` prefix stripped; `owner/model` prefix stripped (non-OpenRouter).+- **Model ID handling**: only the UI-only `[FREE] ` decoration is stripped; the remaining provider model ID is preserved.## Side Effects- **Database writes**: none on bare chat path.- **Broadcasts**: none.-- **External API calls**: `POST https://generativelanguage.googleapis.com/v1beta/...` via `google-genai` SDK; base URL from `llm_defaults.json`.+- **External API calls**: the endpoint selected by the native `google-genai` SDK. A proxy credential can override the Developer API base URL; Vertex Express mode uses the Vertex endpoint and ignores that proxy.- **File I/O**: none.- **Subprocess**: none.@@ -104,9 +104,9 @@ flowchart TDformer adapter's gRPC import deadlock. Both current chat and agentexecutions use the native path.- **Thinking budget units**: expressed as token count, not low/medium/high effort levels. Defaults to 2048.-- **Safety settings**: forwarded via the SDK; malformed values surface as `success=false` in the envelope.+- **Safety settings**: forwarded via the SDK; typed API failures are translated into a user-safe node error at the execution boundary.- **`maxTokens` clamp**: capped at the model's ceiling (65K for 2.5/3.x).-- **Errors swallowed into envelope** - handler never raises.+- **Error boundary**: typed Google SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.mdindex 83b6d920..36e5768c 100644--- a/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.md@@ -69,7 +69,7 @@ flowchart TDC --> D{valid key + prompt?}D -- no --> X[error envelope]D -- yes --> E[detect_ai_provider -> 'groq']- E --> F[Strip 'owner/' prefix from model<br/>non-OpenRouter]+ E --> F[Preserve opaque provider model ID]F --> G[ChatUnifier.chat provider='groq']G --> H[registry.get_provider groq<br/>_compat.py spec: OpenAIProvider + Groq base_url]H --> I[await provider.chat -> LLMResponse]@@ -85,7 +85,7 @@ flowchart TDregistered in `providers/_compat.py` (reuses `OpenAIProvider` with the`base_url` from `llm_defaults.json`) for both chat and agent requests.- **Reasoning**: only Qwen3-32b actually honors `reasoningFormat`. Non-Qwen models ignore the flag.-- **Model string scrubbing**: `[FREE] ` prefix stripped; `owner/` prefix stripped (non-OpenRouter).+- **Model ID handling**: only the UI-only `[FREE] ` decoration is stripped. Owner-qualified IDs such as `openai/gpt-oss-120b` and `qwen/qwen3-32b` are preserved because Groq requires them.## Side Effects@@ -107,7 +107,7 @@ flowchart TD- **Reasoning only on Qwen3-32b**: QwQ has been removed from Groq. Other models ignore `reasoningFormat`.- **`reasoningFormat=hidden` suppresses `thinking`**: response contains only the final answer.- **Finish reason**: passed through from the API response (`"stop"` fallback when absent).-- **Errors swallowed into envelope**.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.mdindex f19fa91c..fd46a388 100644--- a/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.md@@ -11,7 +11,11 @@## Purpose-Kimi models by Moonshot AI (`kimi-k2.6`, `kimi-k2.5`, `kimi-k2.7-code`). 256K context, 96K output. Uses OpenAI-compatible Moonshot endpoint via the native path. `KimiChatModelNode` uses the shared `ChatModelParams` unchanged (no provider override). The `ChatModelBase.chat` operation calls `AIService.execute_chat`.+Kimi models by Moonshot AI. `kimi-k3` is the current default with a+1,048,576-token context window and a 131,072-token output ceiling;+`kimi-k2.6`, `kimi-k2.5`, and `kimi-k2.7-code` remain available as 262K+tiers. The node uses Moonshot's OpenAI-compatible endpoint through the native+provider layer and the shared `ChatModelParams`.## Inputs (handles)@@ -25,11 +29,11 @@ Kimi models by Moonshot AI (`kimi-k2.6`, `kimi-k2.5`, `kimi-k2.7-code`). 256K co|------|------|---------|----------|---------------------|-------------|| `prompt` | string | `""` | yes | - | User message || `system_prompt` | string | `""` | no | - | System prompt |-| `model` | string | `""` (injected) | no | - | `kimi-k2.6`, `kimi-k2.5`, or `kimi-k2.7-code` |-| `temperature` | number\|null | `null` (**ignored**) | no | - | Provider forces 0.6 (instant) or 1.0 (thinking); user input ignored |-| `max_tokens` | number\|null | `null` (up to 96K) | no | - | 1-200000 |+| `model` | string | `""` (injected) | no | - | `kimi-k3` default; `kimi-k2.6`, `kimi-k2.5`, and `kimi-k2.7-code` also supported |+| `temperature` | number\|null | `null` | no | - | K2.5/K2.6/K2.7 Code force 0.6; K3 uses the supplied/default value clamped to 0-1 |+| `max_tokens` | number\|null | `null` (model ceiling) | no | - | Up to 131,072 for K3; lower model-specific ceilings for K2 tiers || `top_p` | number\|null | `1.0` | no | - | |-| `thinking_enabled` | boolean | `false` (Params default) | no | - | Base default is `false`; the provider treats k2.5 as thinking-on unless explicitly disabled |+| `thinking_enabled` | boolean | `false` (Params default) | no | - | When false/unset, the native provider explicitly disables K2.5/K2.6/K2.7 thinking defaults || `api_key` | string\|null | `null` (injected) | no | - | `auth_service.get_api_key('kimi', 'default')` |(Kimi uses the shared `ChatModelParams` unchanged; field names are snake_case, unknown keys ignored.)@@ -64,8 +68,8 @@ flowchart TDC --> D{valid key + prompt?}D -- no --> X[error envelope]D -- yes --> E[detect_ai_provider -> 'kimi']- E --> F[Strip 'owner/' prefix]- F --> G[native_resolve_temperature<br/>forces 0.6 or 1.0 based on model + thinking]+ E --> F[Preserve opaque provider model ID]+ F --> G[native_resolve_temperature<br/>applies configured per-model policy]G --> H[ChatUnifier.chat -> registry.get_provider kimi<br/>OpenAI SDK w/ Moonshot base_url]H --> I[provider.chat]I --> J[success envelope]@@ -76,9 +80,10 @@ flowchart TD- **Validation**: missing api_key / empty prompt -> error envelope.- **Provider routing**: `detect_ai_provider` matches `'kimi' in node_type.lower()`. Ordering guarantees it lands in the kimi lane before groq / openrouter / anthropic / gemini.-- **Fixed temperature**: `native_resolve_temperature` ignores user input for Kimi and forces 0.6 (instant) or 1.0 (thinking).-- **Thinking default-on for k2.5**: if user leaves `thinkingEnabled` unset, k2.5 still thinks. To disable, must pass `thinkingEnabled=false`. This is done explicitly for the tool-calling agent integration (where thinking streams break tool-call parsing).+- **Temperature policy**: K2.5, K2.6, and K2.7 Code are fixed at 0.6 by configuration. K3 uses the supplied/default value clamped to Kimi's 0-1 range.+- **Thinking defaults**: Moonshot's K2.5/K2.6/K2.7 models can default to thinking, so the native provider explicitly sends `thinking={"type":"disabled"}` unless the request enables thinking. This keeps ordinary chat and tool-call parsing deterministic.- **Native path**: uses the OpenAI SDK with Moonshot base_url from `llm_defaults.json`.+- **Model ID handling**: only the UI-only `[FREE] ` decoration is stripped. The remaining model ID is preserved.## Side Effects@@ -97,11 +102,10 @@ flowchart TD## Edge cases & known limits-- **Temperature is non-configurable**: any user-supplied `temperature` is overridden. Documented in the prompt help text but easy to miss.-- **Thinking default is ON** for k2.5: contrast with every other chat model, which defaults thinking OFF.-- **Agent compatibility quirk**: when Kimi is used as a tool-calling agent model, `thinkingEnabled` is explicitly forced False because streamed thinking tokens corrupt tool-call JSON. This is handled in the agent path, not here.-- **256K context / 96K output**: largest of the native providers.-- **Errors swallowed into envelope**.+- **K2 temperature is non-configurable**: any user-supplied value is overridden to 0.6 for the configured K2 tiers; this does not apply to K3.+- **Default application behavior is thinking off** for K2.5/K2.6/K2.7 unless the request explicitly enables it.+- **K3 capacity**: 1,048,576-token context and 131,072-token output. K2 tiers use 262,144-token context with model-specific 32K or 96K output ceilings.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.mdindex ce4ea720..3faa0af8 100644--- a/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.md@@ -99,7 +99,7 @@ flowchart TD- **Server must be running with a model loaded**: LM Studio reports loaded models via `list_loaded()`; if nothing is loaded the probe returns no models.- **Provider routing dependency**: `lmstudio` must be present in `detect_ai_provider` AND in each agent's `provider` Literal, or the node silently falls back to OpenAI cloud.- **Max output default**: ctx ÷ 4, capped at 4096, unless the user overrides `max_tokens`. Typed `LlmInstanceInfo.context_length` drives this.-- **Errors swallowed into envelope** on the chat path.+- **Error boundary**: typed OpenAI SDK connection/API failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.mdindex 1a380dd8..17b7ea6f 100644--- a/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.md@@ -63,7 +63,7 @@ flowchart TDC --> D{valid key + prompt?}D -- no --> X[error envelope]D -- yes --> E[detect_ai_provider -> 'mistral']- E --> F[Strip 'owner/' prefix]+ E --> F[Preserve opaque provider model ID]F --> G[ChatUnifier.chat -> registry.get_provider mistral<br/>OpenAI SDK w/ Mistral base_url]G --> H[provider.chat - thinking ignored]H --> I[success envelope, thinking=null]@@ -77,6 +77,7 @@ flowchart TD- **Temperature clamp**: 0-1.5 (narrower than OpenAI).- **No thinking**: `thinkingEnabled` is silently ignored (Mistral API has no equivalent parameter). `thinking` always returns null.- **Native path**: uses OpenAI SDK with Mistral base_url from `llm_defaults.json`.+- **Model ID handling**: only the UI-only `[FREE] ` decoration is stripped. The remaining model ID is preserved.## Side Effects@@ -98,7 +99,7 @@ flowchart TD- **No reasoning support**: `thinkingEnabled` / `thinkingBudget` / `reasoningEffort` / `reasoningFormat` are all silently ignored. The UI may still surface these fields because the parameter factory is shared.- **Temperature capped at 1.5** (not 2).- **Codestral is code-specialized**: prompts that assume chat behavior may produce different output patterns.-- **Errors swallowed into envelope**.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.mdindex 436ee2a0..34bd066f 100644--- a/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.md@@ -101,7 +101,7 @@ flowchart TD- **Provider routing dependency**: `ollama` must be present in `detect_ai_provider` AND in each agent's `provider` Literal, or the node silently falls back to OpenAI cloud.- **Max output default**: ctx ÷ 4, capped at 4096, unless the user overrides `max_tokens`.- **Per-model params survive restart**: written through to `model_registry.json` so context length is known without re-clicking Fetch.-- **Errors swallowed into envelope** on the chat path.+- **Error boundary**: typed OpenAI SDK connection/API failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.mdindex 1290578d..509ee8f3 100644--- a/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.md@@ -11,7 +11,7 @@## Purpose-Single-turn chat completion against the OpenAI REST API. Used either as a standalone workflow node (user enters a prompt, the node produces a response), wired into an AI Agent via the `input-model` handle, or connected as an advisor tool (`usable_as_tool = True`). Every chat-model node runs through the shared `ChatModelBase.chat` operation (in `_base.py`), which calls `AIService.execute_chat`; per-provider differences live inside `execute_chat` (native SDK for OpenAI) and in the clamp / temperature helpers.+Single-turn chat completion against the OpenAI API. Used either as a standalone workflow node (user enters a prompt, the node produces a response), wired into an AI Agent via the `input-model` handle, or connected as an advisor tool (`usable_as_tool = True`). Every chat-model node runs through the shared `ChatModelBase.chat` operation (in `_base.py`), which calls provider-neutral `AIService.execute_chat`; OpenAI-specific request policy lives in the native provider and shared model-policy helpers.## Inputs (handles)@@ -87,17 +87,17 @@ flowchart TD- **Validation**: missing `api_key` -> ValueError; empty/whitespace `prompt` (via `is_valid_message_content`) -> ValueError. Both produce a `success=false` envelope.- **Provider routing**: `detect_ai_provider(node_type)` returns `'openai'` for this node; falls through the else branch in `constants.detect_ai_provider`.-- **Native path**: `ChatUnifier` resolves the self-registered `openai` spec, so the native `openai` SDK is used via `spec.factory(api_key, proxy_url=...)`. (LangChain is agent-path only.)-- **Model string scrubbing**: strips `[FREE] ` prefix if present. For non-OpenRouter providers (like this one), any `provider/model` slash prefix is stripped so the OpenAI API sees a flat ID.+- **Native path**: `ChatUnifier` resolves the self-registered `openai` spec, so the native `openai` SDK serves both current chat and agent executions. LangChain remains isolated to eligible Temporal-history replay.+- **Model ID handling**: strips only the UI-only `[FREE] ` decoration. Provider model IDs are otherwise opaque and preserved.- **Thinking config**: only built when `thinkingEnabled` is truthy; passed through to the provider's `chat()` method.-- **System prompt**: accepts `system_prompt`, `systemMessage`, or `systemPrompt`. Only prepended as a `SystemMessage` when non-empty (`is_valid_message_content`).-- **Error path**: any exception in the chat flow is caught, logged, and returned as `success=false` with `error: <str>`.+- **System prompt**: reads the schema-canonical `system_prompt` field and prepends a native `Message(role="system")` when it is non-empty.+- **Error path**: typed SDK failures are translated by `ChatUnifier` into `NodeUserError` and re-raised to `BaseNode.execute()`; unexpected exceptions are logged and returned as `success=false`.## Side Effects- **Database writes**: none directly in the happy path. `_track_token_usage` (invoked elsewhere in the AI service when memory is attached) writes `TokenUsageMetric` rows; for a bare chat model node with no memory this path is typically not exercised from `execute_chat`.- **Broadcasts**: none from `execute_chat` itself.-- **External API calls**: one HTTPS call to `https://api.openai.com/v1/chat/completions` via the `openai` Python SDK (base URL configured in `server/config/llm_defaults.json`; overridable via `{provider}_proxy` credential for Ollama-style routing).+- **External API calls**: the standalone chat node uses OpenAI Chat Completions through the native SDK. Native agent turns that need reasoning continuation state use the Responses API; ordinary agent turns use Chat Completions. An `openai_proxy` credential can override the SDK endpoint.- **File I/O**: none.- **Subprocess**: none.@@ -110,11 +110,11 @@ flowchart TD## Edge cases & known limits-- **O-series fixed temperature**: `o1`, `o3`, `o3-mini`, `o4-mini` accept only `temperature=1`; `_resolve_temperature` (and its native counterpart) clamps regardless of input.+- **Reasoning-model temperature**: the native provider omits `temperature` for configured OpenAI reasoning models instead of forwarding an unsupported value.- **GPT-5 hybrid reasoning**: `reasoningEffort` (`minimal` / `low` / `medium` / `high`) is consumed via `NativeThinkingConfig.effort` and forwarded to the provider SDK. Without `thinkingEnabled=true` the effort value is ignored.- **Reasoning summary availability**: the content of `thinking` for o-series models is gated on OpenAI org verification - unverified orgs get `thinking=null` even with `reasoningEffort` set.- **`maxTokens` clamp**: clamped to the model's actual output ceiling by `native_resolve_max_tokens`. Exceeding the limit silently caps without error.-- **All errors are swallowed into the envelope**: any exception (HTTP, timeout, auth, JSON parse) becomes `success=false, error=str(e)`. The handler never raises.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.- **No streaming**: `execute_chat` is single-shot; the full response is awaited before returning.- **Pricing / token tracking**: standalone chat model nodes do NOT trigger `_track_token_usage` - that lives on the agent code paths. Cost attribution for bare chat-model executions is therefore not recorded.diff --git a/docs-internal/node-logic-flows/ai_chat_models/openrouterChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/openrouterChatModel.mdindex 6c9504c6..e22c72ec 100644--- a/docs-internal/node-logic-flows/ai_chat_models/openrouterChatModel.md+++ b/docs-internal/node-logic-flows/ai_chat_models/openrouterChatModel.md@@ -69,7 +69,7 @@ flowchart TDD --> E{valid key + prompt?}E -- no --> X[error envelope]E -- yes --> F[detect_ai_provider -> 'openrouter']- F --> G[DO NOT strip 'owner/' prefix<br/>provider == openrouter]+ F --> G[Preserve opaque owner/model ID]G --> H[ChatUnifier.chat -> registry.get_provider openrouter<br/>OpenAI SDK w/ base_url=openrouter.ai/api/v1]H --> I[provider.chat -> response]I --> J[success envelope]@@ -80,7 +80,7 @@ flowchart TD- **Validation**: missing api_key / empty prompt -> error envelope.- **Provider routing**: matches `'openrouter' in node_type.lower()` in `detect_ai_provider` BEFORE the `anthropic`/`gemini` branches, so model IDs like `anthropic/claude-3.5-sonnet` stay in the OpenRouter lane.-- **Model string rule (important)**: for OpenRouter, the `owner/model` slash-prefix is **kept** (the API expects it). For every other provider the prefix is stripped. See `execute_chat` line: `if provider != 'openrouter' and '/' in model: model = model.split('/', 1)[-1]`.+- **Model string rule (important)**: the `owner/model` identifier is preserved because OpenRouter requires it. The native provider layer treats model IDs as opaque for every provider; it strips only the UI-only `[FREE] ` decoration.- **[FREE] prefix**: stripped unconditionally before the API call; exists only for the frontend dropdown grouping.- **Native provider**: OpenAI SDK reused with `base_url` set to the OpenRouter gateway; `OpenRouterProvider` inherits from `OpenAIProvider`.@@ -103,8 +103,8 @@ flowchart TD- **200+ models, varying capabilities**: thinking support, context windows, temperature ranges, and pricing all vary per routed model. The handler applies generic clamps; mismatches surface as envelope errors from the downstream provider (e.g. "This model does not support the reasoning parameter").- **`[FREE] ` models are OpenRouter-free but may still cost latency**: routing can queue against capacity.-- **`owner/model` prefix is load-bearing**: removing it breaks routing. Unique among the 11 chat-model nodes.-- **Errors swallowed into envelope**.+- **`owner/model` prefix is load-bearing**: removing it breaks OpenRouter routing. Other compatible providers, notably Groq, may also require owner-qualified identifiers.+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`, which produces the standard failure envelope. Unexpected failures are logged and returned by `execute_chat`.## Relateddiff --git a/docs-internal/node-logic-flows/ai_tools/agentBuilder.md b/docs-internal/node-logic-flows/ai_tools/agentBuilder.mdindex c7006b98..92f3b0d1 100644--- a/docs-internal/node-logic-flows/ai_tools/agentBuilder.md+++ b/docs-internal/node-logic-flows/ai_tools/agentBuilder.md@@ -100,7 +100,7 @@ flowchart TD- **Idempotency**: `add_tool` / `add_subagent` / `add_skill` are no-ops (empty `operations`) when the target is already wired/enabled, surfacing the existing node id in the summary.- **add_subagent gate**: only team leads (`orchestrator_agent`, `ai_employee`) may spawn delegates; cannot spawn another team lead.- **create_workflow disabled**: `_CREATE_WORKFLOW_ENABLED = False` short-circuits with a "temporarily disabled" summary; the implementation body is intact for one-line re-enable.-- **Summary suffix**: depends on `ctx.raw["auto_rebind_tools"]` (UserSettings) — "Available immediately" when auto-rebind is on, else "Available on your next turn" (the agent loop binds tools at turn start, so a mid-run mutation is callable next turn unless auto-rebind rebinds it in place).+- **Summary suffix**: depends on `ctx.raw["auto_rebind_tools"]` (UserSettings) — "Available immediately" when auto-rebind is on, else "Available on your next turn" (the native agent loop compiles its tool list at turn start, so a mid-run mutation is callable next turn unless auto-rebind refreshes that list in place).## Side Effectsdiff --git a/docs-internal/node-logic-flows/code_fs_process/fileModify.md b/docs-internal/node-logic-flows/code_fs_process/fileModify.mdindex 4d45f707..e84fedae 100644--- a/docs-internal/node-logic-flows/code_fs_process/fileModify.md+++ b/docs-internal/node-logic-flows/code_fs_process/fileModify.md@@ -16,7 +16,10 @@ Two operations: `write` (create/overwrite) and `edit` (exact stringfind-and-replace). Paths are normalized and resolved through`WorkspaceBackend`, then guarded by a per-path lock. Both operations use asame-directory temporary file plus `os.replace` so concurrent writes cannot-expose partial content; existing file modes and newline bytes are preserved.+expose partial content. Existing file modes are preserved. `write` preserves+the caller's newline characters, while `edit` reads with universal-newline+translation and normalizes the source text plus `old_string`/`new_string` to+LF before replacing and writing.## Inputs (handles)@@ -71,13 +74,12 @@ flowchart TDC --> D{operation?}D -- write --> W[path lock + worker thread:<br/>raise IsADir if dir,<br/>atomic_write_text]W -- OSError/ValueError --> Eenv[raise NodeUserError str e]- W -- result.error --> Eenv- W -- ok --> Wok[Return dict<br/>operation=write, file_path=result.path]+ W -- ok --> Wok[Return dict<br/>operation=write,<br/>normalized file_path]D -- edit --> Ei{old_string empty?}Ei -- yes --> Ereq[raise NodeUserError:<br/>old_string is required for edit]- Ei -- no --> Ed[path lock + worker thread:<br/>exact replacement + atomic_write_text]- Ed -- result.error --> Eenv- Ed -- ok --> Edok[Return dict<br/>occurrences=result.occurrences]+ Ei -- no --> Ed[path lock + worker thread:<br/>read UTF-8 + normalize LF,<br/>exact replacement + atomic_write_text]+ Ed -- replacement error --> Eenv+ Ed -- ok --> Edok[Return dict<br/>operation=edit, normalized file_path,<br/>occurrences count]D -- other --> Unk[raise NodeUserError:<br/>Unknown operation: <op>]```@@ -92,15 +94,17 @@ flowchart TD- **`write` overwrite handling**: `_do_write` resolves the contained path,rejects directories, and atomically replaces or creates the file. `OSError`/ `ValueError` are caught and re-raised as `NodeUserError`.-- **Backend-level errors**: a non-empty `result.error` from `write`/`edit`- short-circuits with `raise NodeUserError(result.error)`. Common: non-unique- `old_string` when `replace_all=False`, path escape with `virtual_mode=True`.+- **Replacement errors**: `perform_string_replacement` returns an error string+ for zero or ambiguous matches; the operation raises it as `NodeUserError`.+ Containment and filesystem exceptions are also translated to+ `NodeUserError`.- **`edit` uniqueness constraint**: when `replace_all=False`, the backendREQUIRES `old_string` to appear exactly once. Zero or multiple matchestrigger a backend-level error.-- **`file_path` echoed from `result.path`**: on success the returned- `file_path` comes from the backend's normalised path, falling back to the- normalised `file_path` only if `result.path` is empty.+- **Result shape**: `write` returns only `operation` and normalized+ `file_path`; `edit` returns those fields plus the integer `occurrences`.+ Neither branch returns a backend result object or `written` /+ `replacements`.## Side Effects@@ -111,6 +115,8 @@ flowchart TD- `get_backend` ensures the workspace root exists.- `write` and `edit` write a same-directory temporary file, flush it, retainan existing file's mode, and atomically replace the destination.+ - `write` emits the caller's text unchanged; `edit` normalizes CRLF and+ lone-CR input and replacement strings to LF.- **Subprocess**: none.## External Dependencies@@ -125,8 +131,9 @@ flowchart TD- **`edit` without a match**: raises `NodeUserError` (backend surfaces themessage). The handler never distinguishes "not found" from "multiplematches" - both are `NodeUserError` strings.-- **No encoding option**: writes are always UTF-8 and preserve caller newline- bytes (`newline=""`).+- **No encoding option**: writes are always UTF-8. Direct `write` preserves+ caller newline characters (`newline=""`), but `edit` uses universal-newline+ reads and rewrites the resulting LF-normalized text.- **`working_directory` not exposed**: `extra="ignore"` means the sandboxcannot be widened via a node param on this node.- **`replace_all=true` with empty `new_string`**: effectively deletes everydiff --git a/docs-internal/node-logic-flows/code_fs_process/shell.md b/docs-internal/node-logic-flows/code_fs_process/shell.mdindex 4cbae3df..73a68a4b 100644--- a/docs-internal/node-logic-flows/code_fs_process/shell.md+++ b/docs-internal/node-logic-flows/code_fs_process/shell.md@@ -16,18 +16,16 @@ Runs a short-lived shell command inside the per-workflow workspace. The nativelike `npm`, `node`, `python`, and `git` ARE reachable on PATH. It uses Nushellwhen `nu` is installed and otherwise uses the host shell (`sh` or `cmd.exe`).When Nushell is selected, `&&` / `||` / `$VAR` / backticks / `>` do not use-bash semantics; see `shell-skill/SKILL.md` for the Nu equivalents. For+bash semantics; see `shell-skill/SKILL.md` for conditional Nu guidance. When+Nushell is absent, all other syntax is interpreted by the host shell. Forlong-running processes (dev servers, watchers), users are directed to[`processManager`](./processManager.md); this node kills the command at-`timeout`.--NOTE: the node's `description` metadata still reads "sandboxed; no system PATH",-which no longer matches the `inherit_env=True` backend — a code-side copy-mismatch (out of scope for this card).+`timeout`. Node metadata describes this as short-lived execution from the+workflow workspace and marks the tool as open-world.A pre-flight regex (`_BASH_CHAIN_RE`) rejects bash chain operators (` && ` / ` || `)-up-front with a corrective message before Nushell's parser would emit a cryptic-`shell_andand` / `shell_oror` error.+up-front with a corrective message before runner selection. They are therefore+rejected even when the fallback host shell would otherwise support them.Runs synchronously under `asyncio.to_thread()` so the event loop keepsservicing other requests while the command executes.@@ -42,7 +40,7 @@ servicing other requests while the command executes.| Name | Type | Default | Required | displayOptions.show | Description ||------|------|---------|----------|---------------------|-------------|-| `command` | string | (required, `min_length=1`) | yes | - | Nushell command |+| `command` | string | (required, `min_length=1`) | yes | - | Nushell command when `nu` is installed; otherwise a host-shell command || `cwd` | string | `""` | no | - | Declared param, but `get_backend` resolves the working dir from `working_directory` (not exposed) / `ctx.workspace_dir`, so `cwd` does NOT change the backend root || `timeout` | number | `30` (ge=1, le=600) | no | - | Max seconds |@@ -88,8 +86,13 @@ flowchart TD## Decision Logic- **Validation**: empty `command` is rejected by Pydantic `min_length=1` (no- manual check). A ` && ` / ` || ` in the command -> `raise NodeUserError` with- a Nushell-equivalent hint (`;` or `try { … } catch { … }`).+ manual check). A ` && ` / ` || ` in the command -> `raise NodeUserError`+ before runner selection, with a Nushell-oriented hint (`;` or+ `try { … } catch { … }`).+- **Runner selection**: `_find_nu()` caches `shutil.which("nu")`. A match runs+ `[nu, "-n", "--no-history", "-c", command]`; otherwise+ `subprocess.run(command, shell=True, ...)` delegates syntax to the host+ shell.- **Inherited PATH**: `WorkspaceBackend(inherit_env=True)` — external tools(`npm`, `node`, `python`, `git`, …) ARE reachable. The previous "scrubbedPATH" framing no longer holds. AI agents are still steered toward@@ -101,8 +104,10 @@ flowchart TDreflects whether the handler itself finished, not whether the commandsucceeded. Users must inspect `exit_code` in the payload.- **Truncation**: the native backend caps output at 100,000 characters by- default; when capped, `truncated=true` and a trailing marker surface to the- caller.+ default; when capped, `truncated=true` and the returned `stdout` contains+ `... Output truncated at 100000 bytes.` after the retained prefix. For a+ non-zero process exit, the subsequently appended `Exit code: N` line follows+ that marker.- **ANSI stripping**: `result.output` is run through `core.ansi.strip_ansi`(a wrapper over **`click.unstyle`**) before being returned as `stdout` (andbefore the operator-log line), so colour/cursor codes from tools like@@ -128,21 +133,28 @@ flowchart TD- **Python packages**: standard library plus `core.ansi`.- **Environment variables**: `WORKSPACE_BASE_DIR`.-- **OS utilities**: `nu` (Nushell) on PATH for the primary path; whatever the- command references is reachable because PATH is inherited.+- **OS utilities**: optional `nu` (Nushell) on PATH; otherwise the platform+ host shell. Whatever the command references is reachable because PATH is+ inherited.## Edge cases & known limits-- **Nushell grammar, not bash**: `&&` / `||` are pre-flight-rejected; `$VAR`,- backticks, and `>` redirection differ from bash. See `shell-skill/SKILL.md`.+- **Conditional shell grammar**: space-delimited `&&` / `||` are+ pre-flight-rejected.+ Other variables, substitutions, redirection, pipelines, and builtins follow+ Nushell grammar only when `nu` is installed; otherwise they follow the host+ shell. See `shell-skill/SKILL.md`.- **Truncation corrupts JSON output**: if a command prints JSON and the- backend truncates, the `stdout` string becomes invalid JSON with no- trailing marker beyond `truncated=true`.+ backend truncates, the `stdout` string becomes invalid JSON because the+ backend appends its human-readable truncation marker; `truncated=true`+ provides the machine-readable signal.- **`exit_code=124` is exit-code polysemy**: real programs can legitimately- exit 124; the handler does not distinguish those from a backend-side- SIGTERM-on-timeout.-- **`timeout` is best-effort**: the backend uses `subprocess.run(..., timeout=)`.- A child process that ignores SIGTERM may keep running until SIGKILL.+ exit 124; the handler does not distinguish those from the backend's timeout+ result.+- **`timeout` covers the direct subprocess**: the backend uses+ `subprocess.run(..., timeout=)` and kills the direct child on expiry.+ Descendant processes started by that shell may not be terminated as a+ process group.- **Stdin is empty**: the node exposes no way to pipe data into thecommand - `input_data` from upstream nodes does not reach it.- **No environment variable override**: users cannot inject env vars viadiff --git a/docs-internal/node-logic-flows/document/fileDownloader.md b/docs-internal/node-logic-flows/document/fileDownloader.mdindex 6a07282c..3d6150b3 100644--- a/docs-internal/node-logic-flows/document/fileDownloader.md+++ b/docs-internal/node-logic-flows/document/fileDownloader.md@@ -14,7 +14,7 @@ Download a batch of URLs in parallel to a local directory using a bounded`asyncio.Semaphore`. Typically consumes the `items` array produced by`httpScraper`. Output directory defaults to `<workspace_dir>/downloads/` sodownloaded files land in the per-workflow workspace and can be picked up by-`documentParser` or the Deep Agent filesystem tools.+`documentParser` or the Coding Agent filesystem tools.## Inputs (handles)diff --git a/docs-internal/node-logic-flows/document/textChunker.md b/docs-internal/node-logic-flows/document/textChunker.mdindex fac92ef3..74baeb6a 100644--- a/docs-internal/node-logic-flows/document/textChunker.md+++ b/docs-internal/node-logic-flows/document/textChunker.md@@ -11,9 +11,13 @@## PurposeSplit documents into overlapping text chunks suitable for embedding. The-dependency-free local splitter preserves the former recursive-character and-Markdown separator/overlap semantics. Typically sits between-`documentParser` and `embeddingGenerator` in a RAG pipeline.+dependency-free local splitter preserves the tested recursive-character+chunk-size and overlap behavior. Its Markdown mode reuses the historical+separator list, but the local implementation escapes every separator before+matching it. Regex-shaped entries such as `\n#{1,6} ` are therefore literal,+not regular expressions; this is not full regex parity with the former+LangChain Markdown splitter. Typically sits between `documentParser` and+`embeddingGenerator` in a RAG pipeline.## Inputs (handles)@@ -99,6 +103,9 @@ flowchart TD## Edge cases & known limits- `token` strategy is mentioned in the frontend options/description but there is no branch for it; it currently falls through to recursive. Documented gotcha.+- Markdown separators are matched literally. Paragraph/newline separators+ still split ordinary Markdown, but regex-style heading and horizontal-rule+ patterns do not receive special regex treatment.- `chunkSize`/`chunkOverlap` are cast via `int(...)`; the local splitter raisesif `overlap > chunkSize`.- Pure function, no randomness - deterministic given the same inputs.diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.mdindex 6710aaad..962e3297 100644--- a/docs-internal/node_panels.md+++ b/docs-internal/node_panels.md@@ -23,7 +23,7 @@ Files:- [client/src/components/parameterPanel/InputSection.tsx](../client/src/components/parameterPanel/InputSection.tsx)- [client/src/components/parameterPanel/MiddleSection.tsx](../client/src/components/parameterPanel/MiddleSection.tsx)- [client/src/components/parameterPanel/OutputSection.tsx](../client/src/components/parameterPanel/OutputSection.tsx)-- [client/src/components/OutputPanel.tsx](../client/src/components/OutputPanel.tsx) — drag source for connected outputs+- [client/src/components/output/OutputPanel.tsx](../client/src/components/output/OutputPanel.tsx) — drag source for connected outputs- [client/src/components/ParameterRenderer.tsx](../client/src/components/ParameterRenderer.tsx) — universal widget- [client/src/hooks/useParameterPanel.ts](../client/src/hooks/useParameterPanel.ts)- [client/src/hooks/useDragVariable.ts](../client/src/hooks/useDragVariable.ts)diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex eb71f2a7..348a1a9f 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -360,7 +360,7 @@ on a plugin resolves to a registered class.| `nodes/twitter/_credentials.py` | `TwitterCredential` | oauth2 | twitterSend / twitterSearch / twitterUser / twitterReceive || `nodes/telegram/_credentials.py` | `TelegramCredential` | api_key | telegramSend / telegramReceive || `nodes/scraper/_credentials.py` | `ApifyCredential` | api_key (bearer) | apifyActor |-| `nodes/model/_credentials.py` | `OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Ollama / LMStudio` | api_key | 11 chat-model nodes (Ollama / LM Studio store a local server URL; the Xai credential is native-chat-only — no node) |+| `nodes/model/_credentials.py` | `OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Ollama / LMStudio` | api_key | 12 native providers and 11 standalone chat-model nodes. Ollama / LM Studio store a local server URL; xAI is agent-selectable but has no standalone node. || `nodes/search/*.py` (inline) | `BraveSearch / Serper / Perplexity` | api_key | single-use search nodes |`GoogleCredential` exposes a `build_credentials()` classmethod that@@ -400,7 +400,7 @@ Every `BaseNode` subclass exposes `cls.as_activity()`, a Temporal`@activity.defn`-decorated callable with name`node.{type}.v{version}`. As of F4.A (commit `8261b05`) theseactivities are **wired into the orchestrator** behind-`TEMPORAL_PER_TYPE_DISPATCH` (default off):+`TEMPORAL_PER_TYPE_DISPATCH` (default on; set it to `false` for rollback):- Flag OFF: orchestrator schedules legacy `execute_node_activity`(status quo since Wave 11; WS round-trip back to FastAPI).@@ -411,10 +411,12 @@ activities are **wired into the orchestrator** behindbecause the worker shares the FastAPI process.`TemporalWorkerManager._worker` registers BOTH the legacy activity AND-every per-type activity (~1.6s startup cost). Per-queue routing-(`task_queue=cls.task_queue`) waits for `TemporalWorkerPool` to be-wired in `main.py`; the orchestrator currently passes `task_queue=None`-so per-type activities still poll the single default queue.+every per-type activity. With the default-on+`TEMPORAL_WORKER_POOL_ENABLED`, `main.py` also starts a+`TemporalWorkerPool`, and `MachinaWorkflow._resolve_activity()` routes each+per-type activity to its plugin-declared `cls.task_queue`. Setting+`TEMPORAL_WORKER_POOL_ENABLED=false` stops the pool and routes activities back+to the manager's single default queue.```python# Worker collection patterns (both supported).@@ -423,11 +425,11 @@ so per-type activities still poll the single default queue.from services.temporal.plugin_activities import collect_plugin_activitiesactivities = collect_plugin_activities()-# Filter by declared queue (for future TemporalWorkerPool):+# Filter by declared queue (what each TemporalWorkerPool worker uses):ai_heavy = collect_plugin_activities(task_queue="ai-heavy")worker = Worker(client, task_queue="ai-heavy", activities=ai_heavy, ...)-# Multi-queue pool (future enhancement — class exists, not started yet):+# Multi-queue pool (started by main.py when TEMPORAL_WORKER_POOL_ENABLED=true):from services.temporal.worker import TemporalWorkerPoolpool = TemporalWorkerPool(client) # defaults to all declared queuesawait pool.start()@@ -435,7 +437,7 @@ await pool.start()### Temporal agent workflows (F4.B)-`TEMPORAL_AGENT_WORKFLOW_ENABLED` (default off, commit `a4d009e`)+`TEMPORAL_AGENT_WORKFLOW_ENABLED` (default on; set it to `false` for rollback)flips agent dispatch from activity to **child workflow**. The`AgentWorkflow` class in `services/temporal/agent_workflow.py` orchestrates the agent loop:@@ -449,9 +451,10 @@ AgentWorkflow.run(payload):4. if compaction threshold: execute_activity("agent.compact_memory.v1")```-Three new activities (`agent.execute_llm_step.v1`,-`agent.persist_turn.v1`, `agent.compact_memory.v1`) registered-alongside the per-type activities.+The worker registers 16 `agent.*.v1` activities alongside the per-type+activities. The three shown above are the core model/persistence/compaction+steps; the remainder cover payload preparation, progress and output+persistence, tool/skill refresh, delegation lifecycle, and team finalization.**Agents that migrate** (15): `aiAgent`, `chatAgent`, 11 specializedagents (`android_agent`, `coding_agent`, `web_agent`, `task_agent`,diff --git a/docs-internal/rlm_service.md b/docs-internal/rlm_service.mdindex 2c064e1c..5adfc1ec 100644--- a/docs-internal/rlm_service.md+++ b/docs-internal/rlm_service.md@@ -4,7 +4,7 @@## Overview-The RLM (Recursive Language Models) service integrates the `rlms` library into OpenCompany as a specialized agent node (`rlm_agent`). Unlike other specialized agents that route to `handle_chat_agent` and use the standard agent loop, the RLM agent uses its own REPL-based code execution loop where the LM writes Python code blocks that are `exec()`-ed in a sandboxed environment.+The RLM (Recursive Language Models) service integrates the `rlms` library into OpenCompany as a specialized agent node (`rlm_agent`). Unlike other specialized agents that dispatch through `SpecializedAgentBase` and the standard native agent loop, the RLM agent uses its own REPL-based code execution loop where the LM writes Python code blocks that are `exec()`-ed in a sandboxed environment.**Library**: [rlms](https://pypi.org/project/rlms/) (pip install rlms)**Paper**: https://arxiv.org/abs/2512.24601@@ -15,8 +15,8 @@ The RLM (Recursive Language Models) service integrates the `rlms` library into O| Aspect | Standard Agents (aiAgent, chatAgent, etc.) | RLM Agent (rlm_agent) ||--------|---------------------------------------------|----------------------|| Execution model | LLM -> tool call -> LLM -> tool call | LLM -> `\`\`\`repl` code block -> exec() -> stdout -> LLM |-| Tool interface | LangChain StructuredTool with Pydantic schemas | Python functions injected into REPL namespace |-| State management | Message accumulation in `_run_agent_loop` | Python variables in REPL namespace + `context` variable |+| Tool interface | Provider-neutral `AgentToolSpec` / `ToolDef` values with Pydantic validation | Python functions injected into REPL namespace |+| State management | Native message accumulation in `run_native_agent_loop` | Python variables in REPL namespace + `context` variable || Completion signal | LLM stops making tool calls | LLM calls `FINAL(answer)` or `FINAL_VAR(variable_name)` || Recursion | Agent delegation (fire-and-forget) | `rlm_query()` spawns child RLM with own REPL || Strengths | Structured tool calling, provider-agnostic | Complex reasoning, code-driven decomposition, recursive sub-problems |@@ -49,11 +49,11 @@ Execution Flow================================NodeExecutor._dispatch()- -> RLMAgentNode.execute_op() [server/nodes/agent/rlm_agent.py]+ -> RLMAgentNode.execute_op() [server/nodes/agent/rlm_agent/__init__.py]| (post-Wave-11 replacement for the| retired server/services/handlers/rlm.py)+-- collect_agent_connections() [services/plugin/edge_walker.py]- +-- _format_task_context() [nodes/agent/_inline.py — prepare_agent_call]+ +-- format_task_context() [services/plugin/edge_walker.py]+-- tool stripping on completion [REUSE pattern]+-- auto-prompt fallback [REUSE pattern]|@@ -87,8 +87,9 @@ server/services/rlm/adapters.py # BackendAdapter, ChatModelExtractor, ToolBridgeAdapterservice.py # RLMService class with execute() method-server/services/handlers/- rlm.py # Thin handler (~70 lines, mirrors handle_chat_agent)+server/nodes/agent/rlm_agent/+ __init__.py # RLMAgentNode plugin + execute_op orchestration+ meta.json # Plugin metadata```---@@ -196,30 +197,29 @@ These are extracted from the node's `options` object:----## Handler Pattern+## Plugin Execution Pattern-The handler (`handle_rlm_agent`) follows `handle_chat_agent` exactly:+`RLMAgentNode.execute_op` shares the standard edge-collection and task/input+preparation helpers, then delegates to the independent RLM service:```python-# 1. Collect connections (same as handle_chat_agent)-memory_data, skill_data, tool_data, input_data, task_data = await _collect_agent_connections(- node_id, context, database, log_prefix="[RLM Agent]"+# 1. Collect connected memory, skills, tools, input, and task data+memory_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(+ node_id, ctx.raw, database, log_prefix="[RLM Agent]")-# 2. Task context injection (same pattern)+# 2. Inject task context and strip tools for terminal task notificationsif task_data:- task_context = _format_task_context(task_data)+ task_context = format_task_context(task_data)parameters = {**parameters, 'prompt': f"{task_context}\n\n{parameters.get('prompt', '')}"}-- # 3. Tool stripping on task completion (same pattern)if task_status in ('completed', 'error') and tool_data:tool_data = []-# 4. Auto-prompt fallback (same pattern)+# 3. Apply the same text-shaped auto-prompt fallback as standard agentsif not parameters.get('prompt') and input_data:prompt = input_data.get('message') or input_data.get('text') or ...-# 5. Delegate to RLM service (differs from handle_chat_agent)+# 4. Invoke the RLM-specific REPL runtimereturn await ai_service.rlm_service.execute(node_id, parameters, ...)```@@ -230,11 +230,9 @@ return await ai_service.rlm_service.execute(node_id, parameters, ...)| File | Change ||------|--------|| `server/constants.py` | `'rlm_agent'` in `AI_AGENT_TYPES` frozenset |-| `server/services/node_executor.py` | `'rlm_agent': partial(handle_rlm_agent, ...)` in `_build_handler_registry()` |-| `server/services/handlers/__init__.py` | `from .rlm import handle_rlm_agent` |+| `server/nodes/agent/rlm_agent/__init__.py` | `RLMAgentNode` auto-registers through the plugin base and owns `execute_op` || `server/services/ai.py` | `self.rlm_service = RLMService(auth=self.auth)` in `AIService.__init__()` |-| `server/requirements.txt` | `rlms>=0.1.1` |-| `server/pyproject.toml` | `"rlms>=0.1.1"` in `[project] dependencies` |+| `server/pyproject.toml` / generated requirements | `rlms` runtime dependency |---diff --git a/package.json b/package.jsonindex a2bbe1ca..334ba2c2 100644--- a/package.json+++ b/package.json@@ -8,7 +8,7 @@"automation","react-flow","ai-agent",- "langchain",+ "native-llm","n8n","whatsapp","android",diff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.jsonindex 130b1edb..eee56698 100644--- a/server/config/llm_defaults.json+++ b/server/config/llm_defaults.json@@ -1,7 +1,7 @@{"version": "2026.07.23","last_updated": "2026-07-23",- "_description": "LLM provider defaults. popular_models drives the ordered global selector and offline fallback independently of token constraints. POLICY (2026-07-23): popular_models lists only models with >= 1M-token context windows — providers whose models are all below 1M carry an empty list and contribute nothing to the global selector (their models stay reachable via the live per-provider fetch_models dropdown). Connection config drives native SDK and LangChain paths; model specs are enriched by model_registry.json (OpenRouter cache).",+ "_description": "LLM provider defaults. popular_models drives the ordered global selector and offline fallback independently of token constraints. POLICY (2026-07-23): popular_models lists only models with >= 1M-token context windows — providers whose models are all below 1M carry an empty list and contribute nothing to the global selector (their models stay reachable via the live per-provider fetch_models dropdown). base_url directly configures the eight OpenAI-compatible native providers; dedicated OpenAI, Anthropic, and Gemini providers use SDK defaults, while OpenRouter has its own gateway default. Runtime proxy credentials can override supported endpoints. Model specs are enriched by model_registry.json (OpenRouter cache).","agent": {"_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.",diff --git a/server/nodes/README.md b/server/nodes/README.mdindex 697e2a8e..30ec7917 100644--- a/server/nodes/README.md+++ b/server/nodes/README.md@@ -173,7 +173,7 @@ the sibling file via relative path:from ._credentials import GoogleCredential # shared with 6 siblings# inside server/nodes/model/openai_chat_model.py-from ._credentials import OpenAICredential # one of 10 LLM creds+from ._credentials import OpenAICredential # one of 10 cloud LLM creds# inside server/nodes/twitter/twitter_send.pyfrom ._credentials import TwitterCredential # shared with 3 siblings@@ -186,7 +186,7 @@ from ._credentials import TwitterCredential # shared with 3 sibling| `nodes/twitter/` | `TwitterCredential` (OAuth2 + PKCE) | twitter_send / _search / _user / _receive || `nodes/telegram/` | `TelegramCredential` (bot token + owner chat id) | telegram_send / _receive || `nodes/scraper/` | `ApifyCredential` (Bearer) | apify_actor |-| `nodes/model/` | 12 LLM classes (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Ollama / LMStudio`) | 11 chat models |+| `nodes/model/` | 12 LLM credential classes: 10 cloud (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / xAI`) plus Ollama / LM Studio | 11 chat models (xAI has no standalone chat-model node) || `nodes/search/` | `BraveSearch / Serper / Perplexity` inlined in each plugin file | single-use per plugin |Declare inline only when genuinely single-use (see@@ -296,7 +296,7 @@ The credential-validator dispatch is a sibling concern, handled by theexisting `services/plugin/credential.py:Credential` base class. Your`Credential` subclass overrides `_probe(api_key) -> ProbeResult` (or,in rare cases like local-LLM 2-storage, the whole `validate(data)--> dict` classmethod). Maps, Apify, all 9 cloud LLM providers, and+-> dict` classmethod). Maps, Apify, all 10 cloud LLM providers, andboth local-LLM providers (Ollama / LM Studio) all dispatch through thesame scaffold — no `_SPECIAL_PROVIDER_VALIDATORS` dict in`routers/websocket.py`.diff --git a/server/nodes/skill/simple_memory/__init__.py b/server/nodes/skill/simple_memory/__init__.pyindex c029ade8..2a77fcf7 100644--- a/server/nodes/skill/simple_memory/__init__.py+++ b/server/nodes/skill/simple_memory/__init__.py@@ -1,10 +1,15 @@"""Simple Memory — Wave 11.E.3 inlined.-Markdown-based conversation memory, optionally backed by a vector-store for semantic recall. Connects upward to an agent's input-memory-handle. The plugin queries the in-memory ``MessageStore`` directly;-agents read the ``memory_content`` parameter (the editable markdown)-plus the live message log returned here.+The node exposes two distinct memory surfaces. ``memory_content`` is the+passive, DB-backed markdown transcript connected agents read and update+through :mod:`services.memory.runtime`; executing this node does not populate+that transcript. The ``read`` operation separately queries the process-local+``services.memory_store`` log and returns timestamped message dictionaries.+That direct log is currently written by the RLM service and does not survive+a process restart.++Long-term embedding settings are passive configuration consumed by agent+paths; they do not make the ``read`` operation query the vector store.Field shape mirrors the pre-Wave-11 nodeDefinitions (camelCase on main)but with snake_case names, since plugin Pydantic params are the sourcediff --git a/server/services/ai.py b/server/services/ai.pyindex 8e0d5f2e..5214db06 100644--- a/server/services/ai.py+++ b/server/services/ai.py@@ -1251,7 +1251,7 @@ class AIService:options = parameters.get("options", {})flattened = {**parameters, **options}- # Extract parameters with camelCase/snake_case support for LangChain+ # Extract the schema-canonical chat-model parameters.api_key = flattened.get("api_key")model = flattened.get("model", "gpt-3.5-turbo")# Strip [FREE] prefix if present (added by OpenRouter model list for display)diff --git a/server/services/llm/providers/_compat.py b/server/services/llm/providers/_compat.pyindex a573fe5b..231158e5 100644--- a/server/services/llm/providers/_compat.py+++ b/server/services/llm/providers/_compat.py@@ -25,8 +25,8 @@ logger = get_logger(__name__)# Names match the ``providers.<name>`` keys in ``llm_defaults.json``.# The compat providers' ``base_url`` is pulled lazily from the JSON-# config so adding a new compat endpoint costs zero code — just append-# the name here after the JSON entry lands.+# config. Adding a new compat endpoint requires its JSON entry plus one+# explicit name in this tuple; no provider subclass is required.## Groq + Cerebras moved here in Phase D (May 2026). Both expose# OpenAI-compatible `/v1` endpoints (``api.groq.com/openai/v1`` /diff --git a/server/services/memory/jsonl.py b/server/services/memory/jsonl.pyindex 3cd004a6..2af4a360 100644--- a/server/services/memory/jsonl.py+++ b/server/services/memory/jsonl.py@@ -1,13 +1,14 @@-"""Standard-JSONL conversation-memory helpers.+"""Standalone standard-JSONL conversation normalization helpers.Lines are Anthropic Messages API objects: ``{"role": "user"|"assistant",-"content": str | List[ContentBlock], ...}``. Extra metadata-(``timestamp``, ``session_id``, ``model``, ...) rides alongside-``role`` / ``content`` and is preserved on round-trip; standard parsers-(Anthropic SDK, LangChain converters) ignore unknown keys.+"content": str | List[ContentBlock], ...}``. :func:`append_message` can+serialize extra metadata (``timestamp``, ``session_id``, ``model``, ...),+but :func:`parse_jsonl` intentionally drops it when normalizing rows to+native :class:`services.llm.protocol.Message` values.-Used by :mod:`nodes.agent.claude_code_agent` (session memory) via-:func:`services.cli_agent.service.AICliService.run_batch`.+No production agent currently calls these helpers. Claude Code owns and+reads its native session JSONL independently; this module remains a tested+primitive for normalized import/export."""import json@@ -19,8 +20,9 @@ from services.llm.protocol import Messagedef parse_jsonl(text: str) -> List[Message]:"""Standard JSONL -> native :class:`Message` list.- Tool-call content blocks collapse to text; rows with unknown roles- or unparseable JSON are skipped (forward compatibility).+ Text content blocks are joined with spaces; tool-call blocks and extra+ metadata are discarded. Rows with unknown roles, non-text content, or+ unparseable JSON are skipped for forward compatibility."""if not text:return []@@ -58,8 +60,10 @@ def append_message() -> str:"""Append one Anthropic Messages-format line to a JSONL string.- Metadata fields ride alongside ``role`` / ``content``. Always emits- a trailing newline so successive appends concatenate cleanly.+ Metadata fields ride alongside ``role`` / ``content`` on the serialized+ line, but :func:`parse_jsonl` does not surface them on ``Message``.+ Always emits a trailing newline so successive appends concatenate+ cleanly."""line = json.dumps({"role": role, "content": content, **metadata},diff --git a/server/skills/coding_agent/file-read-skill/SKILL.md b/server/skills/coding_agent/file-read-skill/SKILL.mdindex 8baed503..7ef033dd 100644--- a/server/skills/coding_agent/file-read-skill/SKILL.md+++ b/server/skills/coding_agent/file-read-skill/SKILL.md@@ -1,6 +1,6 @@---name: file-read-skill-description: Read file contents with line numbers and pagination support.+description: Read raw file contents with line-based pagination support.allowed-tools: file_readmetadata:author: opencompany@@ -11,7 +11,8 @@ metadata:# File Read Tool-Read file contents with line-numbered output and pagination. Uses the workspace-contained native filesystem backend.+Read raw file contents with line-based pagination. Uses the+workspace-contained native filesystem backend.**Path sandbox:** all paths resolve inside the per-workflow workspace root. Use workspace-relative paths (e.g. `reports/data.csv`); `..` and `~` segments are rejected, and absolute paths are remapped into the workspace. Use `fs_search` with `mode: "ls"` to discover what exists.@@ -23,7 +24,7 @@ Read file contents with line-numbered output and pagination. Uses the workspace-|-------|------|----------|-------------|| file_path | string | Yes | Path to the file to read || offset | int | No | Line number to start from, 0-indexed (default: 0) |-| limit | int | No | Maximum lines to read (default: 100, max: 10000) |+| limit | int | No | Maximum lines to read (default: 2000, max: 10000) |### Examples@@ -41,14 +42,19 @@ Read file contents with line-numbered output and pagination. Uses the workspace-```json{- "content": "1\tline one\n2\tline two\n...",- "file_path": "/path/to/file.py",- "encoding": "utf-8"+ "content": "line one\nline two\n...",+ "line_count": 2,+ "file_path": "/path/to/file.py"}```### Guidelines1. Use offset/limit for large files instead of reading everything-2. File content is returned with line numbers (tab-separated)-3. Binary files return base64-encoded content+2. `content` is the selected text slice, without added line numbers; text line+ endings are normalized to LF+3. `line_count` counts the lines in the returned slice, not the whole file+4. `file_path` is the normalized virtual path inside the workflow workspace+5. Non-UTF-8 files are returned as base64 text in `content`; the tool result+ does not include a separate `encoding` field, and line pagination is not+ applied to that base64 representationdiff --git a/server/skills/coding_agent/fs-search-skill/SKILL.md b/server/skills/coding_agent/fs-search-skill/SKILL.mdindex f5fb3e1f..a6c814cf 100644--- a/server/skills/coding_agent/fs-search-skill/SKILL.md+++ b/server/skills/coding_agent/fs-search-skill/SKILL.md@@ -24,7 +24,6 @@ Search the filesystem: list directories, glob pattern match files, or grep file| mode | string | No | `ls` (list directory), `glob` (pattern match), `grep` (search contents). Default: `ls` || path | string | No | Directory path to search in (default: `.`) || pattern | string | If glob/grep | Glob pattern (e.g., `**/*.py`) or grep search text |-| file_filter | string | No | Glob to filter files for grep mode (e.g., `*.py`) |### Examples@@ -40,7 +39,7 @@ Search the filesystem: list directories, glob pattern match files, or grep file**Search for a function:**```json-{"mode": "grep", "path": ".", "pattern": "def my_function", "file_filter": "*.py"}+{"mode": "grep", "path": ".", "pattern": "def my_function"}```**Find all config files:**@@ -53,10 +52,20 @@ Search the filesystem: list directories, glob pattern match files, or grep file**ls mode:**```json{- "path": ".",+ "path": "/","entries": [- {"name": "src", "type": "dir", "size": null},- {"name": "README.md", "type": "file", "size": 1234}+ {+ "path": "/src/",+ "is_dir": true,+ "size": 0,+ "modified_at": "2026-07-24T10:30:00"+ },+ {+ "path": "/README.md",+ "is_dir": false,+ "size": 1234,+ "modified_at": "2026-07-24T10:31:00"+ }],"count": 2}@@ -65,9 +74,22 @@ Search the filesystem: list directories, glob pattern match files, or grep file**glob mode:**```json{- "path": ".",+ "path": "/","pattern": "**/*.py",- "matches": [{"path": "src/main.py"}, {"path": "tests/test_main.py"}],+ "matches": [+ {+ "path": "/src/main.py",+ "is_dir": false,+ "size": 1200,+ "modified_at": "2026-07-24T10:31:00"+ },+ {+ "path": "/tests/test_main.py",+ "is_dir": false,+ "size": 850,+ "modified_at": "2026-07-24T10:32:00"+ }+ ],"count": 2}```@@ -75,19 +97,25 @@ Search the filesystem: list directories, glob pattern match files, or grep file**grep mode:**```json{- "path": ".",+ "path": "/","pattern": "def main","matches": [- {"path": "src/main.py", "line": 42, "text": "def main():"}+ {"path": "/src/main.py", "line": 42, "text": "def main():"}],"count": 1}```+`path` values in entries and matches are normalized virtual paths rooted at+the workflow workspace. `size` and `modified_at` are best-effort metadata and+may be absent if the backend cannot stat an entry.+### Guidelines1. Use `ls` to explore directory structure2. Use `glob` to find files by name pattern (supports `**` recursive, `*` wildcard, `?` single char)3. Use `grep` to search file contents (literal text, not regex)-4. Combine `grep` with `file_filter` to limit search scope-5. Results are capped at 500 matches for grep mode+4. Narrow a grep by choosing a more specific `path`; there is no+ `file_filter` parameter+5. The native backend does not impose a match-count cap; scope broad searches+ carefully because every matching result is returneddiff --git a/server/skills/terminal/shell-skill/SKILL.md b/server/skills/terminal/shell-skill/SKILL.mdindex c3b1961f..f76ef077 100644--- a/server/skills/terminal/shell-skill/SKILL.md+++ b/server/skills/terminal/shell-skill/SKILL.md@@ -1,6 +1,6 @@---name: shell-skill-description: Execute short-lived shell commands inside the per-workflow workspace. The shell is Nushell (cross-platform, same syntax on Windows/macOS/Linux). External tools on PATH (npm, node, python, git, ...) are available.+description: Execute short-lived shell commands inside the per-workflow workspace. Uses Nushell when installed and otherwise the host shell. External tools on PATH (npm, node, python, git, ...) are available.allowed-tools: "shell"metadata:author: opencompany@@ -9,29 +9,37 @@ metadata:----# Shell Tool (Nushell)+# Shell Tool-Execute short-lived shell commands in the workflow workspace. **The shell is [Nushell](https://www.nushell.sh/) — the same grammar runs on Windows, macOS, and Linux.** Do not write `cmd.exe`, PowerShell, or Bash idioms; they will fail or behave wrong.+Execute short-lived shell commands in the workflow workspace. The backend uses+[Nushell](https://www.nushell.sh/) when `nu` is installed. Otherwise it passes+the command to the host shell (`cmd.exe` on Windows or the platform+`/bin/sh`-style shell on POSIX). Shell-specific syntax is therefore+conditional on the installed runner.-External binaries on `PATH` (`npm`, `node`, `python`, `git`, `pwd`, etc.) are available — Nu invokes them as external commands automatically.+External binaries on `PATH` (`npm`, `node`, `python`, `git`, etc.) are+available to whichever runner is selected.-**GNU coreutils (`sed`, `awk`, `head`, `tail`, `grep`, `cut`, `sort`, `uniq`, `wc`, `tr`, `xargs`, `find`) are NOT in PATH on Windows** and will fail with `Command not found`. Use Nushell builtins or switch tools — see the table below.+For portable calls, prefer one external command with ordinary arguments, such+as `git status` or `python -V`. Use `file_read`, `file_modify`, or `fs_search`+for filesystem work; they avoid runner-specific parsing.-## Check the host before reaching for external tools+## Runner-dependent syntax-Don't burn turns on trial-and-error (`sed not found` → retry with `awk` → `awk not found` → ...). Detect the host **once** at the start of a task that needs platform-sensitive binaries, then branch:+The node rejects space-delimited `&&` and `||` before selecting a runner, so+those operators are unsupported even when the host shell would normally+accept them. Prefer separate tool calls. If the environment is known to have+Nushell, its equivalents include:```nu-# `$nu.os-info.name` is "windows" | "linux" | "macos" | "android" | ...-let os = $nu.os-info.name+try { npm install } catch { print 'install failed'; exit 1 }+open README.md --raw | lines | first 20```-Then either:-1. **Skip the shell entirely.** For reading / editing / searching files, the right answer almost always is `file_read` / `file_modify` / `fs_search` — they are path-sandboxed and platform-agnostic by construction.-2. **Use Nu builtins.** `open`, `lines`, `first`, `last`, `find`, `glob`, `length`, `save`, `cp`, `mv`, `rm`, `mkdir` exist on every host.-3. **Probe before invoking external CLIs.** `if (which sed | is-empty) { ... } else { sed ... }` — but at that point, `file_read` / `file_modify` is shorter and works everywhere.--**Rule of thumb**: if your command starts with `sed` / `awk` / `head` / `tail` / `grep`, stop and reach for `file_read` or `fs_search` instead. You almost never need a host check — you need the dedicated tool.+Do not send Nushell pipelines, Bash substitutions, PowerShell cmdlets, or+`cmd.exe` builtins unless the selected environment is known to support that+syntax. GNU utilities such as `sed`, `awk`, and `grep` are not generally+available on Windows.## shell_execute Tool@@ -39,8 +47,8 @@ Then either:| Field | Type | Required | Description ||-------|------|----------|-------------|-| command | string | Yes | Nushell command (single or `;`-chained) |-| timeout | int | No | Seconds (default 30, max 300) |+| command | string | Yes | Command interpreted by Nushell when installed, otherwise by the host shell |+| timeout | int | No | Seconds (default 30, max 600) |### Response@@ -59,9 +67,9 @@ Then either:| 124 | Timed out || non-zero | Failure |-## Critical: Nushell ≠ Bash+## Nushell reference (only when `nu` is installed)-| Bash / cmd.exe (do NOT use) | Nushell (correct) |+| Bash / cmd.exe form | Nushell form ||---|---|| `cmd1 && cmd2` (and-then) | `cmd1; cmd2` *(unconditional sequential — see below for short-circuit)* || `cmd1 || cmd2` (or-else) | `try { cmd1 } catch { cmd2 }` |@@ -84,26 +92,22 @@ Then either:| `find . -name '*.py'` | `glob '**/*.py'` || `xargs cmd` | `each { \|x\| cmd $x }` |-### Short-circuit "and-then" (the `&&` replacement)+### Short-circuit "and-then" when Nushell is active-The user log showed `pwd && ls -la` failing — the parser explicitly rejects `&&`. Use one of:+The node explicitly rejects the usual space-delimited `&&` form. With+Nushell available, use:```nu-# A: just sequential, doesn't short-circuit on failure-pwd; ls -la--# B: short-circuit using exit code via try/catch+# Short-circuit using try/catchtry { npm install } catch { print 'install failed'; exit 1 }ls -la-# C: explicit conditional on the previous command's success+# Or inspect an external command's exit codelet r = (do { npm install } | complete)if $r.exit_code == 0 { ls -la } else { print $r.stderr }```-Use **A** for "run these in order regardless of outcome", **B/C** when you must stop on failure.--## Common tasks (cross-platform, Nushell)+## Common tasks when Nushell is active| Task | Command ||---|---|@@ -137,11 +141,11 @@ Use **A** for "run these in order regardless of outcome", **B/C** when you must## Guidelines-1. **Never use `&&`, `||`, backticks, `$VAR`, or `>` redirection.** Use the Nushell equivalent on the right side of the table above.-2. **Never invoke GNU coreutils** (`sed`, `awk`, `head`, `tail`, `grep`, `find`, `wc`, `cut`, `sort`, `uniq`, `xargs`, `tr`). They are not on Windows. For peeking at a file, use **`file_read`** (line-numbered, `offset`/`limit` aware); for searching, use **`fs_search`** (grep mode).-3. **Check the host first** when an external CLI is unavoidable. `let os = $nu.os-info.name` once, then gate by `windows` / `linux` / `macos`. Don't loop "try → fail → retry".-4. **One command (or `;`-chain) per call.** No multi-line scripts; if you need control flow, use `if` / `try` / `each` inline.+1. **Never use `&&` or `||`.** The node pre-flight rejects their common+ space-delimited forms before invoking either runner, and their behavior is+ not portable even without surrounding spaces.+2. **Prefer one simple command per call.** Chaining, variables, redirection, pipelines, and builtins depend on whether Nushell or the host shell was selected.+3. **Use dedicated filesystem tools.** `file_read`, `file_modify`, and `fs_search` are workspace-contained and avoid shell parsing differences.+4. **Treat Nushell syntax as conditional.** The reference above applies only when `nu` is installed.5. **Short-lived only.** `shell_execute` *always* awaits completion — a small `timeout` does **not** make it run in the background, it just kills the command after N seconds. If the command runs longer than ~30s, opens a port, watches files, or is described as "dev server / watcher / daemon" (`npm run dev`, `vite`, `tsx watch`, `python -m http.server`, ...), use **`process_manager`** instead. Trying to "fire and forget" with `timeout=2` will kill the process the moment the port comes up.-6. **Nu syntax is host-agnostic.** Builtins (`ls`, `open`, `glob`, `lines`, `save`, `cp`, ...) work the same everywhere. You only need the host check for *external* tools.-7. **Quote glob patterns** (`'*.py'`) so Nu's `glob` builtin expands them, not the caller.-8. **Capture command exit code** with `do { … } | complete` if you need to branch on success/failure.+6. **The timeout range is 1–600 seconds.** Use `process_manager` instead of raising it for persistent processes.