Skip to content

Self-improving AI Employees for everyone

docs: align references with native LLM runtime

trohitgc8bfb6fb02fc
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 Flow
1. **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 supports
4. **LLM Decision**: LLM decides when to call tools based on user query
5. **Status Broadcast**: `executing_tool` status broadcast with tool_name for UI animation
6. **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.md
index 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](do
At 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
[![AI Agent Routing](docs/diagrams/ai-agent-routing.svg)](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.md
index 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.md
index 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.md
index eb760337..c95fc13b 100644
--- a/docs-internal/SETUP.md
+++ b/docs-internal/SETUP.md
@@ -38,6 +38,15 @@ npm run build
npm 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.md
index 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 result
has no engine marker are pre-cutover histories and follow the frozen LangChain
path with their historical payload, activity commands, and message shape. The
temporary `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. |
+
## Debugging
The 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.md
index 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_a
3. **Env** `Settings.agent_recursion_limit` from `AGENT_RECURSION_LIMIT` (default 200).
4. **JSON** `llm_defaults.json:agent.recursion_limit` — last-resort fallback when Settings can't load.
-This is a backstop, not the load-bearing signal — compaction (token-based, post-turn) is the actual termination control. See [memory_compaction.md](memory_compaction.md).
+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 an
diff --git a/docs-internal/claude_code_agent_architecture.md b/docs-internal/claude_code_agent_architecture.md
index 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 Contents
1. [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.md
index 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 and
add an analogous `claude_code_*_reference.md` file.
-## Flags we use in `services/cli_agent/`
+## Flags used by the current Claude Code agent
Quick 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.md
index 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.md
index 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.md
index 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.md
index 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 shape
diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.md
index 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.
```python
class 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 = True
updated_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:
```python
result = 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:
```python
await 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 from
every 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:
```python
final_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 Wiring
The 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.md
index 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` bridge
uses claude's own native session JSONL on disk (see §6) and mirrors the
transcript into `memory_content` via the **markdown** helpers for visibility.
-## 2. Markdown helper API
+## 2. Normalized helper APIs
+
+### Markdown transcript
Three 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 canonical
vector-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 the
append/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, then
ranks 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.
```python
from 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 remains
the 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 starts
7. (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 thought
signatures, 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.md
index 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 recurring
1. **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 never
written 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 module
register_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 needed
sdk_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 before
executing tools. This preserves Gemini thought signatures, Anthropic signed and
redacted 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 thro
For every new chat and agent run, `proxy_url` flows through `ChatUnifier` into
the 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.md
index 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 doc
for 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` wraps
the task result as a plain-English instruction that the LLM must "report
naturally", 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.md
index 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 TD
G --> 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.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/cerebrasChatModel.md
index 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 TD
C --> 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 the
Cerebras `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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/deepseekChatModel.md
index 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 TD
C --> 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/geminiChatModel.md
index 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 TD
F --> 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 and
current 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 TD
former adapter's gRPC import deadlock. Both current chat and agent
executions 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/groqChatModel.md
index 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 TD
C --> 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 TD
registered 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/kimiChatModel.md
index 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 TD
C --> 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/lmstudioChatModel.md
index 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/mistralChatModel.md
index 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 TD
C --> 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/ollamaChatModel.md
index 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/openaiChatModel.md
index 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.md
index 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 TD
D --> 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`.
## Related
diff --git a/docs-internal/node-logic-flows/ai_tools/agentBuilder.md b/docs-internal/node-logic-flows/ai_tools/agentBuilder.md
index 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 Effects
diff --git a/docs-internal/node-logic-flows/code_fs_process/fileModify.md b/docs-internal/node-logic-flows/code_fs_process/fileModify.md
index 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 string
find-and-replace). Paths are normalized and resolved through
`WorkspaceBackend`, then guarded by a per-path lock. Both operations use a
same-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 TD
C --> 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 backend
REQUIRES `old_string` to appear exactly once. Zero or multiple matches
trigger 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, retain
an 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 the
message). The handler never distinguishes "not found" from "multiple
matches" - 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 sandbox
cannot be widened via a node param on this node.
- **`replace_all=true` with empty `new_string`**: effectively deletes every
diff --git a/docs-internal/node-logic-flows/code_fs_process/shell.md b/docs-internal/node-logic-flows/code_fs_process/shell.md
index 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 native
like `npm`, `node`, `python`, and `git` ARE reachable on PATH. It uses Nushell
when `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. For
long-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 keeps
servicing 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 "scrubbed
PATH" framing no longer holds. AI agents are still steered toward
@@ -101,8 +104,10 @@ flowchart TD
reflects whether the handler itself finished, not whether the command
succeeded. 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` (and
before 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 the
command - `input_data` from upstream nodes does not reach it.
- **No environment variable override**: users cannot inject env vars via
diff --git a/docs-internal/node-logic-flows/document/fileDownloader.md b/docs-internal/node-logic-flows/document/fileDownloader.md
index 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/` so
downloaded 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.md
index 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 @@
## Purpose
Split 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 raises
if `overlap > chunkSize`.
- Pure function, no randomness - deterministic given the same inputs.
diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.md
index 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.md
index 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`) these
activities 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** behind
because 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_activities
activities = 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 TemporalWorkerPool
pool = TemporalWorkerPool(client) # defaults to all declared queues
await 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 specialized
agents (`android_agent`, `coding_agent`, `web_agent`, `task_agent`,
diff --git a/docs-internal/rlm_service.md b/docs-internal/rlm_service.md
index 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, ToolBridgeAdapter
service.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 notifications
if 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 agents
if 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 runtime
return 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.json
index 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.json
index 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.md
index 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.py
from ._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 the
existing `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, and
both local-LLM providers (Ollama / LM Studio) all dispatch through the
same 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__.py
index 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 source
diff --git a/server/services/ai.py b/server/services/ai.py
index 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.py
index 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.py
index 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 Message
def 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.md
index 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_read
metadata:
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"
}
```
### Guidelines
1. 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 representation
diff --git a/server/skills/coding_agent/fs-search-skill/SKILL.md b/server/skills/coding_agent/fs-search-skill/SKILL.md
index 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.
+
### Guidelines
1. Use `ls` to explore directory structure
2. 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 returned
diff --git a/server/skills/terminal/shell-skill/SKILL.md b/server/skills/terminal/shell-skill/SKILL.md
index 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/catch
try { 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 code
let 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.