Skip to content

Self-improving AI Employees for everyone

feat: Add memory compaction, token tracking, and autonomous agent skills

trohitg3d7e2673179e
diff --git a/CLAUDE.md b/CLAUDE.md
index 21a8b469..dfbd2b95 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,6 +15,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Dual-Purpose Tool Guide](./docs-internal/dual_purpose_tool_node_creation.md)** | Guide for nodes that work as both workflow nodes AND AI Agent tools (e.g., whatsappSend) |
| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute via LangGraph |
| **[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 |
+| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Token tracking and memory compaction service using native provider APIs (Anthropic, OpenAI) |
| **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and composite setup action |
| **[Workflow Schema](./docs-internal/workflow-schema.md)** | JSON schema for workflows, edge handle conventions, config node architecture |
| **[Execution Engine Design](./docs-internal/DESIGN.md)** | Architecture patterns, design standards, and implementation details for the workflow execution engine |
@@ -86,7 +87,7 @@ server/core/
server/models/
├── cache.py # CacheEntry SQLModel for SQLite cache
├── auth.py # User model with bcrypt
-└── database.py # ConversationMessage, NodeParameter, ToolSchema, ChatMessage tables
+└── database.py # ConversationMessage, NodeParameter, ToolSchema, ChatMessage, TokenUsageMetric, CompactionEvent, SessionTokenState tables
```
### Polyglot Server Integration (Optional)
@@ -484,9 +485,15 @@ server/skills/
│ ├── scheduler-skill/SKILL.md
│ ├── web-search-skill/SKILL.md
│ └── whatsapp-skill/SKILL.md
-└── android/ # Android device control skills
- ├── personality/SKILL.md
- └── skill/SKILL.md
+├── android/ # Android device control skills
+│ ├── personality/SKILL.md
+│ └── skill/SKILL.md
+└── autonomous/ # Autonomous agent patterns (Code Mode research)
+ ├── code-mode-skill/SKILL.md # Generate code instead of tool calls (81-98% token savings)
+ ├── agentic-loop-skill/SKILL.md # OBSERVE-THINK-ACT-REFLECT-DECIDE pattern
+ ├── progressive-discovery-skill/SKILL.md # Load tools on-demand (98.7% token savings)
+ ├── error-recovery-skill/SKILL.md # Retry strategies, graceful degradation
+ └── multi-tool-orchestration-skill/SKILL.md # Coordinate multiple tools for complex tasks
```
**SKILL.md Format:**
@@ -2558,6 +2565,246 @@ I don't have access to real-time weather data...
- **Window + Archive**: Short-term (recent messages) + long-term (semantic retrieval) memory pattern
- **Auto-Save**: AI Agent automatically saves updated markdown content to node parameters
+## Memory Compaction and Token Tracking
+
+### Overview
+The compaction service enables automatic memory compaction and token tracking for specialized agents. It uses a hybrid approach: native compaction APIs for Anthropic/OpenAI, with tracking for all providers. Inspired by Claude Code's compaction pattern with a default 100,000 token threshold.
+
+### Architecture
+```
+AI Agent Execution
+ ↓
+CompactionService.track() → Save token metrics to DB
+ ↓ → Update cumulative session state
+ ↓ → Check if threshold exceeded
+ ↓
+If needs_compaction:
+ - Anthropic: Native compaction via context_management API
+ - OpenAI: Native compaction via compact_threshold
+ - Others: Client-side summarization fallback
+ ↓
+CompactionService.record() → Save compaction event to DB
+ → Reset cumulative token count
+```
+
+### Native Provider APIs
+
+**Anthropic SDK (tool_runner):**
+```python
+compaction_control = {
+ "enabled": True,
+ "context_token_threshold": 100000
+}
+```
+
+**Anthropic Messages API:**
+```python
+{
+ "betas": ["compact-2026-01-12"],
+ "context_management": {
+ "edits": [{
+ "type": "compact_20260112",
+ "trigger": {"type": "input_tokens", "value": 100000}
+ }]
+ }
+}
+```
+
+**OpenAI:**
+```python
+{"context_management": {"compact_threshold": 100000}}
+```
+
+### Key Files
+| File | Description |
+|------|-------------|
+| `server/services/compaction.py` | CompactionService with track(), record(), stats(), configure(), compact_context() methods |
+| `server/services/ai.py` | `_track_token_usage()` with automatic compaction triggering |
+| `server/models/database.py` | TokenUsageMetric, CompactionEvent, SessionTokenState tables |
+| `server/core/database.py` | CRUD methods for token metrics and compaction events |
+| `server/core/config.py` | compaction_enabled, compaction_threshold settings |
+| `server/core/container.py` | Dependency injection for compaction_service |
+| `server/main.py` | Wires AI service to compaction service at startup |
+| `server/routers/websocket.py` | get_compaction_stats, configure_compaction handlers |
+| `client/src/components/parameterPanel/MiddleSection.tsx` | Token Usage UI with editable threshold |
+
+### Database Models
+
+**TokenUsageMetric** - Per-execution token usage:
+```python
+class TokenUsageMetric(SQLModel, table=True):
+ session_id: str # Memory session identifier
+ node_id: str # Agent node ID
+ provider: str # openai, anthropic, gemini, groq, etc.
+ model: str # Model name
+ input_tokens: int # Input token count
+ output_tokens: int # Output token count
+ total_tokens: int # Total tokens
+ cache_creation_tokens: int # Anthropic cache creation
+ cache_read_tokens: int # Anthropic cache read
+ reasoning_tokens: int # OpenAI o-series reasoning
+```
+
+**SessionTokenState** - Cumulative state per session:
+```python
+class SessionTokenState(SQLModel, table=True):
+ session_id: str # Unique session identifier
+ cumulative_total: int # Running total tokens
+ custom_threshold: int # Per-session threshold override
+ compaction_count: int # Number of compactions
+ last_compaction_at: datetime # Last compaction timestamp
+```
+
+**CompactionEvent** - Compaction history:
+```python
+class CompactionEvent(SQLModel, table=True):
+ session_id: str
+ trigger_reason: str # "native" or "threshold"
+ tokens_before: int
+ tokens_after: int
+ summary_content: str # Compacted summary (if available)
+```
+
+### CompactionService API
+
+```python
+from services.compaction import get_compaction_service
+
+svc = get_compaction_service()
+
+# Get provider-specific config
+anthropic_cfg = svc.anthropic_config(threshold=100000)
+openai_cfg = svc.openai_config(threshold=100000)
+
+# Track token usage after AI execution
+result = await svc.track(
+ session_id="user-123",
+ node_id="agent-1",
+ provider="anthropic",
+ model="claude-3-5-sonnet",
+ usage={"input_tokens": 5000, "output_tokens": 1000, "total_tokens": 6000}
+)
+# result: {"total": 6000, "threshold": 100000, "needs_compaction": False}
+
+# Record compaction event after native API handles it
+await svc.record(
+ session_id="user-123",
+ node_id="agent-1",
+ provider="anthropic",
+ model="claude-3-5-sonnet",
+ tokens_before=105000,
+ tokens_after=15000,
+ summary="Compacted conversation summary..."
+)
+
+# Get session statistics
+stats = await svc.stats("user-123")
+# {"session_id": "user-123", "total": 15000, "threshold": 100000, "count": 1}
+
+# Configure per-session settings
+await svc.configure("user-123", threshold=50000, enabled=True)
+```
+
+### WebSocket Handlers
+
+| Handler | Description |
+|---------|-------------|
+| `get_compaction_stats` | Get token statistics for a session |
+| `configure_compaction` | Update threshold/enabled settings for a session |
+
+### Configuration
+
+Environment variables in `.env`:
+```bash
+COMPACTION_ENABLED=true # Enable/disable compaction globally
+COMPACTION_THRESHOLD=100000 # Default token threshold (min: 10000)
+```
+
+### Client-Side Compaction
+
+When the token threshold is exceeded, the service automatically triggers compaction using the AI service to generate a structured summary:
+
+```python
+# Automatic compaction in _track_token_usage()
+if tracking.get('needs_compaction') and memory_content and api_key:
+ result = await svc.compact_context(
+ session_id=session_id,
+ node_id=node_id,
+ memory_content=memory_content, # Current conversation markdown
+ provider=provider,
+ api_key=api_key,
+ model=model
+ )
+ # result: {"success": True, "summary": "# Conversation Summary (Compacted)...", "tokens_before": 105000, "tokens_after": 0}
+```
+
+**Summary Structure** (Claude Code pattern):
+```markdown
+# Conversation Summary (Compacted)
+*Generated: 2025-02-12T10:30:00Z*
+
+## Task Overview
+What the user is trying to accomplish.
+
+## Current State
+What's been completed and what's in progress.
+
+## Important Discoveries
+Key findings, decisions, or problems encountered.
+
+## Next Steps
+What needs to happen next.
+
+## Context to Preserve
+Details that must be retained for continuity.
+```
+
+### WebSocket Broadcasts
+
+Real-time updates broadcast to frontend:
+
+| Event | Description |
+|-------|-------------|
+| `token_usage_update` | After each AI execution: `{session_id, data: {total, threshold, needs_compaction}}` |
+| `compaction_starting` | Before compaction begins: `{session_id, node_id}` |
+| `compaction_completed` | After compaction: `{session_id, success, tokens_before, tokens_after, error}` |
+
+### Token Usage UI
+
+The MiddleSection displays a Token Usage panel for memory nodes with:
+- **Progress bar**: Visual tokens used vs threshold
+- **Statistics**: Current token count, threshold, compaction count
+- **Editable threshold**: Click edit icon to change per-session threshold
+
+```typescript
+// In client/src/components/parameterPanel/MiddleSection.tsx
+<Collapse.Panel header="Token Usage" key="tokenUsage">
+ <Progress percent={Math.round((total / threshold) * 100)} />
+ <Statistic title="Tokens Used" value={`${total} / ${threshold}`} />
+ <Statistic title="Compactions" value={count} />
+ <InputNumber onChange={updateThreshold} /> {/* Edit threshold */}
+</Collapse.Panel>
+```
+
+### Service Wiring
+
+The compaction service requires AI service for summarization, wired at startup:
+
+```python
+# In server/main.py
+from services.compaction import get_compaction_service
+compaction_svc = container.compaction_service()
+compaction_svc.set_ai_service(container.ai_service())
+```
+
+### Design Decisions
+- **Hybrid Approach**: Native APIs for Anthropic/OpenAI configs, client-side summarization for actual compaction
+- **5-Section Summary**: Follows Claude Code's structured summary format for continuity
+- **Automatic Triggering**: Compaction triggered in `_track_token_usage()` when threshold exceeded
+- **Per-Session State**: Each memory session has independent token tracking and thresholds
+- **100K Threshold**: Matches Claude Code's default (configurable per session)
+- **Singleton Pattern**: Service accessible via `get_compaction_service()`
+
## AI Agent Tool System
### Overview
diff --git a/client/src/components/parameterPanel/MiddleSection.tsx b/client/src/components/parameterPanel/MiddleSection.tsx
index 2dbb1a4c..e447d4be 100644
--- a/client/src/components/parameterPanel/MiddleSection.tsx
+++ b/client/src/components/parameterPanel/MiddleSection.tsx
@@ -1,4 +1,6 @@
import React, { useState, useEffect } from 'react';
+import { Collapse, Progress, Statistic, Spin, Row, Col, Typography, InputNumber, Button, message } from 'antd';
+import { ThunderboltOutlined, EditOutlined, SaveOutlined } from '@ant-design/icons';
import ParameterRenderer from '../ParameterRenderer';
import ToolSchemaEditor from './ToolSchemaEditor';
import MasterSkillEditor from './MasterSkillEditor';
@@ -82,7 +84,7 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
}) => {
const theme = useAppTheme();
const { currentWorkflow } = useAppStore();
- const { clearMemory, resetSkill } = useWebSocket();
+ const { clearMemory, resetSkill, sendRequest } = useWebSocket();
const [isConsoleExpanded, setIsConsoleExpanded] = useState(true);
const [connectedSkills, setConnectedSkills] = useState<ConnectedSkill[]>([]);
const [isSkillsExpanded, setIsSkillsExpanded] = useState(true);
@@ -93,6 +95,19 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
const [clearLongTermMemory, setClearLongTermMemory] = useState(false);
const [isProcessing, setIsProcessing] = useState(false);
+ // Compaction state
+ const [compactionStats, setCompactionStats] = useState<{
+ session_id: string;
+ total: number;
+ threshold: number;
+ count: number;
+ } | null>(null);
+ const [connectedMemorySessionId, setConnectedMemorySessionId] = useState<string | null>(null);
+ const [compactionLoading, setCompactionLoading] = useState(false);
+ const [isEditingThreshold, setIsEditingThreshold] = useState(false);
+ const [editThresholdValue, setEditThresholdValue] = useState<number>(100000);
+ const [savingThreshold, setSavingThreshold] = useState(false);
+
// Clear memory handler
const handleClearMemory = async () => {
setIsProcessing(true);
@@ -152,7 +167,63 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
// State for Master Skill parameters
const [masterSkillParams, setMasterSkillParams] = useState<Record<string, any>>({});
- const { sendRequest } = useWebSocket();
+
+ // Get connected memory session ID and compaction stats for agent nodes
+ useEffect(() => {
+ if (!isAgentWithSkills || !currentWorkflow) {
+ setConnectedMemorySessionId(null);
+ setCompactionStats(null);
+ return;
+ }
+
+ const edges = currentWorkflow.edges || [];
+
+ // Find memory node connected to input-memory handle
+ const memoryEdge = edges.find((edge: Edge) =>
+ edge.target === nodeId && edge.targetHandle === 'input-memory'
+ );
+
+ if (!memoryEdge) {
+ setConnectedMemorySessionId(null);
+ setCompactionStats(null);
+ return;
+ }
+
+ // Get memory node's sessionId from its parameters
+ const fetchMemorySessionId = async () => {
+ try {
+ const response = await sendRequest<{ parameters: Record<string, any> }>('get_node_parameters', {
+ node_id: memoryEdge.source
+ });
+ const sessionId = response?.parameters?.sessionId || 'default';
+ setConnectedMemorySessionId(sessionId);
+
+ // Fetch compaction stats for this session
+ setCompactionLoading(true);
+ const statsResponse = await sendRequest<{
+ session_id: string;
+ total: number;
+ threshold: number;
+ count: number;
+ }>('get_compaction_stats', { session_id: sessionId });
+
+ if (statsResponse) {
+ setCompactionStats({
+ session_id: statsResponse.session_id || sessionId,
+ total: statsResponse.total || 0,
+ threshold: statsResponse.threshold || 100000,
+ count: statsResponse.count || 0
+ });
+ }
+ } catch (err) {
+ console.error('[MiddleSection] Failed to fetch memory session/compaction stats:', err);
+ } finally {
+ setCompactionLoading(false);
+ }
+ };
+
+ fetchMemorySessionId();
+ }, [nodeId, isAgentWithSkills, currentWorkflow, sendRequest]);
// Get connected skills for agent nodes
useEffect(() => {
@@ -637,6 +708,91 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
</div>
)}
+ {/* Token Usage Section - Only for agent nodes with memory connected */}
+ {isAgentWithSkills && connectedMemorySessionId && (
+ <Collapse
+ defaultActiveKey={['tokens']}
+ style={{ marginTop: 16 }}
+ items={[{
+ key: 'tokens',
+ label: (
+ <span style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+ <ThunderboltOutlined />
+ Token Usage
+ {compactionStats && (
+ <Typography.Text type="secondary" style={{ marginLeft: 'auto' }}>
+ {Math.round(compactionStats.total / 1000)}K / {Math.round(compactionStats.threshold / 1000)}K
+ </Typography.Text>
+ )}
+ </span>
+ ),
+ children: compactionLoading ? (
+ <Spin />
+ ) : compactionStats ? (
+ <>
+ <Progress
+ percent={Math.round((compactionStats.total / compactionStats.threshold) * 100)}
+ status={compactionStats.total >= compactionStats.threshold * 0.8 ? 'exception' : 'active'}
+ />
+ <Row gutter={16} style={{ marginTop: 16 }}>
+ <Col span={8}><Statistic title="Total" value={compactionStats.total} /></Col>
+ <Col span={8}>
+ {isEditingThreshold ? (
+ <div>
+ <Typography.Text type="secondary" style={{ fontSize: 12 }}>Threshold</Typography.Text>
+ <div style={{ display: 'flex', gap: 4, marginTop: 4 }}>
+ <InputNumber
+ size="small"
+ value={editThresholdValue}
+ onChange={(v) => setEditThresholdValue(v || 100000)}
+ min={10000}
+ max={1000000}
+ step={10000}
+ style={{ width: 100 }}
+ />
+ <Button
+ size="small"
+ type="primary"
+ icon={<SaveOutlined />}
+ loading={savingThreshold}
+ onClick={async () => {
+ setSavingThreshold(true);
+ try {
+ await sendRequest('configure_compaction', {
+ session_id: connectedMemorySessionId,
+ threshold: editThresholdValue
+ });
+ setCompactionStats(prev => prev ? { ...prev, threshold: editThresholdValue } : null);
+ setIsEditingThreshold(false);
+ message.success('Threshold updated');
+ } catch (err) {
+ message.error('Failed to update threshold');
+ } finally {
+ setSavingThreshold(false);
+ }
+ }}
+ />
+ </div>
+ </div>
+ ) : (
+ <div onClick={() => { setEditThresholdValue(compactionStats.threshold); setIsEditingThreshold(true); }} style={{ cursor: 'pointer' }}>
+ <Statistic title={<span>Threshold <EditOutlined style={{ fontSize: 10, marginLeft: 4 }} /></span>} value={compactionStats.threshold} />
+ </div>
+ )}
+ </Col>
+ <Col span={8}><Statistic title="Compactions" value={compactionStats.count} /></Col>
+ </Row>
+ <Typography.Text type="secondary" style={{ fontSize: 12, marginTop: 8, display: 'block' }}>
+ Session: {compactionStats.session_id}
+ </Typography.Text>
+ </>
+ ) : (
+ <Typography.Text type="secondary">No data yet. Run the agent to start tracking.</Typography.Text>
+ )
+ }]}
+ />
+ )}
+
{/* Connected Skills Section - Only for Zeenie nodes */}
{isAgentWithSkills && (
<div style={{
diff --git a/client/src/nodeDefinitions/aiAgentNodes.ts b/client/src/nodeDefinitions/aiAgentNodes.ts
index db94bd0d..63a0dfca 100644
--- a/client/src/nodeDefinitions/aiAgentNodes.ts
+++ b/client/src/nodeDefinitions/aiAgentNodes.ts
@@ -278,6 +278,60 @@ export const aiAgentNodes: Record<string, INodeTypeDescription> = {
default: 'You are a helpful assistant.',
typeOptions: { rows: 3 },
description: 'Define the behavior and personality of the AI agent'
+ },
+ {
+ displayName: 'Options',
+ name: 'options',
+ type: 'collection',
+ placeholder: 'Add Option',
+ default: {},
+ options: [
+ {
+ displayName: 'Temperature',
+ name: 'temperature',
+ type: 'number',
+ default: 0.7,
+ typeOptions: { minValue: 0, maxValue: 2, numberStepSize: 0.1 },
+ description: 'Controls randomness in responses'
+ },
+ {
+ displayName: 'Maximum Tokens',
+ name: 'maxTokens',
+ type: 'number',
+ default: 1000,
+ typeOptions: { minValue: 1, maxValue: 8192 },
+ description: 'Maximum number of tokens to generate'
+ },
+ {
+ displayName: 'Thinking/Reasoning',
+ name: 'thinkingEnabled',
+ type: 'boolean',
+ default: false,
+ description: 'Enable extended thinking for supported providers (Anthropic, OpenAI o-series, Gemini, Groq, Cerebras)'
+ },
+ {
+ displayName: 'Thinking Budget',
+ name: 'thinkingBudget',
+ type: 'number',
+ default: 2048,
+ typeOptions: { minValue: 1024, maxValue: 16000 },
+ description: 'Token budget for thinking (Claude, Gemini, Cerebras)',
+ displayOptions: { show: { thinkingEnabled: [true] } }
+ },
+ {
+ displayName: 'Reasoning Effort',
+ name: 'reasoningEffort',
+ type: 'options',
+ options: [
+ { name: 'Low', value: 'low' },
+ { name: 'Medium', value: 'medium' },
+ { name: 'High', value: 'high' }
+ ],
+ default: 'medium',
+ description: 'Reasoning effort level (OpenAI o-series, Groq)',
+ displayOptions: { show: { thinkingEnabled: [true] } }
+ }
+ ] as any
}
]
},
diff --git a/docs-internal/autonomous_agent_creation.md b/docs-internal/autonomous_agent_creation.md
new file mode 100644
index 00000000..967cd98d
--- /dev/null
+++ b/docs-internal/autonomous_agent_creation.md
@@ -0,0 +1,675 @@
+# Autonomous Agent Creation: A Comprehensive Guide
+
+## Introduction
+
+This document synthesizes insights from leading AI research organizations on building autonomous agents. The approaches discussed represent a paradigm shift from traditional tool-calling patterns toward **code-centric agent architectures** that dramatically improve efficiency, composability, and capabilities.
+
+The core insight shared across all sources: **code is the most expressive interface through which AI models can interact with their environment**. LLMs were trained on vast amounts of code, making it their native language for expressing complex operations.
+
+---
+
+## Table of Contents
+
+1. [The Problem with Traditional Tool-Calling](#the-problem-with-traditional-tool-calling)
+2. [Code Mode: A New Paradigm](#code-mode-a-new-paradigm)
+3. [Architecture Patterns](#architecture-patterns)
+4. [Implementation Approaches](#implementation-approaches)
+5. [Security and Sandboxing](#security-and-sandboxing)
+6. [Multi-Agent Orchestration](#multi-agent-orchestration)
+7. [Practical Implementation Guide](#practical-implementation-guide)
+8. [Performance Benchmarks](#performance-benchmarks)
+9. [Future Directions](#future-directions)
+
+---
+
+## The Problem with Traditional Tool-Calling
+
+### The While Loop Problem
+
+Traditional agent frameworks operate through a tedious repetition pattern:
+
+```
+Developer specifies tools with parameters and return types
+ -> LLM receives prompt instructing tool selection
+ -> Client executes "the while loop":
+ LLM call -> tool execution -> context update -> repeat
+```
+
+This approach has several fundamental limitations:
+
+| Problem | Description |
+|---------|-------------|
+| **Token Overhead** | Each tool call requires round-trip communication, consuming tokens on every iteration |
+| **Context Window Bloat** | Tool definitions loaded upfront can consume 150,000+ tokens before addressing user requests |
+| **Intermediate Result Duplication** | Data retrieved by agents passes through the model multiple times |
+| **Limited Composability** | Single-step tool calls don't compose naturally into complex workflows |
+| **Framework Boilerplate** | Developers write both application logic and framework scaffolding simultaneously |
+
+### The RPC Analogy
+
+BoundaryML draws a useful parallel between tool-calling and Remote Procedure Calls:
+
+| Programming Concept | Agentic Systems Equivalent |
+|---------------------|---------------------------|
+| RPC Call | Tool call |
+| Programmer | Agent |
+| Runtime | While loop |
+| Variables | Context stack |
+
+The critical insight: **"The while loop is not a good runtime. The context stack is not a good binding environment."**
+
+### Token Economics
+
+Consider a practical example from Anthropic's research:
+- A 2-hour meeting transcript could require processing an additional **50,000 tokens** when passed through the model multiple times
+- Standard MCP implementations loading all tool definitions upfront can consume **hundreds of thousands of tokens** before any useful work begins
+
+---
+
+## Code Mode: A New Paradigm
+
+### Core Concept
+
+Code Mode represents a fundamental shift where AI agents **generate and execute code** rather than making sequential tool calls. Both Cloudflare and Anthropic independently arrived at this conclusion in late 2025.
+
+```
+Traditional Approach:
+ Agent -> Tool Call 1 -> Result 1 -> Agent -> Tool Call 2 -> Result 2 -> ...
+
+Code Mode Approach:
+ Agent -> Generate Code -> Execute in Sandbox -> Return Final Result
+```
+
+### Why Code?
+
+> "Code, on the other hand, is what these models were trained on. It's their native language."
+> — Rita Kozlov, VP of AI & Developers at Cloudflare
+
+Key advantages:
+- **Native expression format** for LLMs
+- **Built-in control flow** (loops, conditionals, error handling)
+- **Compositional by design** (functions call functions)
+- **Type-safe** with proper annotations
+- **Self-documenting** through code structure
+
+### Progressive Tool Discovery
+
+Rather than loading all tool definitions upfront, Code Mode presents tools as a navigable filesystem:
+
+```
+servers/
+├── google-drive/
+│ ├── getDocument.ts
+│ └── index.ts
+├── salesforce/
+│ ├── updateRecord.ts
+│ └── index.ts
+└── calendar/
+ ├── createEvent.ts
+ ├── listEvents.ts
+ └── index.ts
+```
+
+Agents discover tools by navigating this structure, loading only definitions needed for current tasks.
+
+**Result**: Token usage reduced from 150,000 to approximately 2,000—a **98.7% savings**.
+
+---
+
+## Architecture Patterns
+
+### 1. Dynamic Scope Management (Symbolica Agentica)
+
+Agents operate within a **dynamic scope**—a collection of objects that evolves as the agent executes:
+
+```python
+# Initial objects placed in scope at creation
+scope = {
+ 'database': DatabaseClient(),
+ 'email': EmailService(),
+}
+
+# Objects returned by method calls automatically enter scope
+user = scope['database'].get_user(123)
+# 'user' now available with its own methods: update(), delete(), get_posts()
+
+posts = user.get_posts()
+# 'posts' collection now available for iteration
+```
+
+This pattern enables **incremental capability discovery** without preloading everything into context.
+
+### 2. Object Hierarchies Over Flat Functions
+
+Instead of exposing flat function lists, leverage object-oriented patterns:
+
+```python
+# Flat approach (problematic)
+tools = [
+ get_user,
+ update_user,
+ delete_user,
+ get_user_posts,
+ create_user_post,
+ # ... 50 more functions
+]
+
+# Object hierarchy approach (preferred)
+class User:
+ def update(self, **kwargs): ...
+ def delete(self): ...
+ def get_posts(self) -> List[Post]: ...
+
+class Post:
+ def update(self, **kwargs): ...
+ def delete(self): ...
+ def add_comment(self, text: str) -> Comment: ...
+```
+
+Benefits:
+- **Natural capability encoding** through method availability
+- **Reduced context size** (methods discovered on-demand)
+- **Type-safe composition** (IDE-like "go-to-definition" for agents)
+
+### 3. Compositional Tools (BoundaryML)
+
+Rather than single-step tools, provide compositional primitives:
+
+| Tool | Purpose |
+|------|---------|
+| `sequence` | Execute ordered tool chains, returning final result |
+| `forEach` | Apply tools across collections |
+| `callBuiltin` | Execute standard functions |
+| `assignVariable` | Bind values for reuse |
+| `conditional` | Branch based on conditions |
+
+This enables agents to compose **multi-step programs** rather than single RPC calls.
+
+### 4. Filesystem-Based Tool Organization (Anthropic MCP)
+
+```typescript
+// servers/calendar/createEvent.ts
+export interface CreateEventParams {
+ title: string;
+ startTime: Date;
+ endTime: Date;
+ attendees?: string[];
+}
+
+export async function createEvent(params: CreateEventParams): Promise<Event> {
+ // Implementation
+}
+```
+
+Agents can:
+- Browse available servers
+- Read tool definitions on-demand
+- Use `search_tools` functions for filtered discovery
+- Cache frequently-used definitions
+
+---
+
+## Implementation Approaches
+
+### Approach 1: Code Generation with Sandboxed Execution
+
+**Used by**: Cloudflare, Anthropic
+
+```typescript
+// Agent generates code like this:
+const events = [];
+for (let i = 0; i < 31; i++) {
+ const event = await calendar.createEvent({
+ title: `Daily Standup - Day ${i + 1}`,
+ startTime: addDays(startDate, i),
+ duration: 30
+ });
+ events.push(event);
+}
+return events;
+```
+
+**Execution flow**:
+1. Agent receives MCP server schema
+2. Generates executable JavaScript/TypeScript
+3. Code executes in sandboxed V8 isolate (Cloudflare Workers)
+4. Results returned to agent context
+
+**Benefits**:
+- 31 events created through single loop vs. 31 API calls
+- Native control flow (loops, conditionals, try/catch)
+- Type checking before execution
+
+### Approach 2: Agentica Framework Pattern
+
+**Used by**: Symbolica
+
+```python
+from agentica import spawn
+
+# Third-party clients integrate directly
+from twelvedata import TDClient
+
+market_data = TDClient()
+finance_agent = await spawn(
+ system_prompt="You are a financial analysis assistant.",
+ scope={'market_data': market_data}
+)
+
+# Agent can now use market_data methods directly in generated code
+result = await finance_agent.run(
+ "Analyze AAPL stock performance over the last quarter",
+ return_type=FinancialReport # Type-safe returns
+)
+```
+
+**Key features**:
+- Library integration without wrapper functions
+- `show_definition()` for on-demand inspection
+- Type-safe return type enforcement
+- Sub-agent spawning via `spawn()` in scope
+
+### Approach 3: Compositional DSL Pattern
+
+**Used by**: BoundaryML
+
+```json
+{
+ "type": "sequence",
+ "steps": [
+ {
+ "type": "forEach",
+ "items": { "ref": "attendees" },
+ "body": {
+ "type": "sequence",
+ "steps": [
+ {
+ "type": "callBuiltin",
+ "function": "calendar.getAvailability",
+ "params": { "userId": { "ref": "item" } }
+ },
+ {
+ "type": "assignVariable",
+ "name": "availabilities",
+ "value": { "append": { "ref": "result" } }
+ }
+ ]
+ }
+ },
+ {
+ "type": "callBuiltin",
+ "function": "calendar.findCommonSlot",
+ "params": { "availabilities": { "ref": "availabilities" } }
+ }
+ ]
+}
+```
+
+**Benefits**:
+- Type-checkable and lintable
+- No per-step LLM callbacks
+- Clear program structure
+- Generalizes from examples (2-person to N-person scheduling)
+
+---
+
+## Security and Sandboxing
+
+### Multi-Layer Security Architecture
+
+Production code execution requires robust isolation:
+
+```
+┌─────────────────────────────────────────────┐
+│ User Space │
+│ ┌─────────────────────────────────────┐ │
+│ │ Application │ │
+│ │ ┌─────────────────────────────┐ │ │
+│ │ │ WASM Sandbox │ │ │
+│ │ │ ┌───────────────────┐ │ │ │
+│ │ │ │ Agent Code │ │ │ │
+│ │ │ └───────────────────┘ │ │ │
+│ │ └─────────────────────────────┘ │ │
+│ └─────────────────────────────────────┘ │
+│ │
+│ MicroVM Boundary │
+└─────────────────────────────────────────────┘
+```
+
+### Symbolica's Approach: Remote Object Proxying
+
+```python
+# Agent code executes in sandbox
+# Objects remain local to user
+# Method calls trigger RPC across process boundaries
+
+class RemoteProxy:
+ def __init__(self, object_id: str, rpc_client: RPCClient):
+ self._id = object_id
+ self._rpc = rpc_client
+
+ def __getattr__(self, name):
+ async def method_call(*args, **kwargs):
+ return await self._rpc.call(self._id, name, args, kwargs)
+ return method_call
+```
+
+### Cloudflare's Approach: V8 Isolates
+
+- Code executes in sandboxed V8 isolate
+- Powered by Workers Loader
+- Negligible cold start due to Workers infrastructure
+- Code Executor binding handles script execution
+- Creation IDs for monitoring and tracking
+
+### Security Checklist
+
+| Concern | Mitigation |
+|---------|------------|
+| **Code Injection** | Sandbox execution environment |
+| **Resource Exhaustion** | CPU/memory limits per execution |
+| **Data Exfiltration** | Network restrictions, allowlists |
+| **API Key Exposure** | Keys never enter model context |
+| **Sensitive Data Leakage** | Automatic PII tokenization |
+| **Infinite Loops** | Execution timeouts |
+| **File System Access** | Virtual filesystem isolation |
+
+### Privacy-Preserving Execution
+
+Anthropic's approach to sensitive data:
+
+```typescript
+// Intermediate data remains in execution environment
+// PII automatically tokenized before entering model context
+
+const spreadsheet = await drive.getSpreadsheet("salary-data.xlsx");
+// 10,000 rows with PII
+
+const summary = spreadsheet
+ .filter(row => row.department === "Engineering")
+ .aggregate({ avgSalary: "mean(salary)" });
+// Only aggregate returned to model context
+```
+
+---
+
+## Multi-Agent Orchestration
+
+### Agentica-in-Scope Pattern
+
+Placing the `spawn()` function in an agent's scope enables autonomous multi-agent orchestration:
+
+```python
+# Orchestrator agent can spawn sub-agents dynamically
+orchestrator = await spawn(
+ "You orchestrate complex research tasks.",
+ scope={
+ 'spawn': spawn, # Enable sub-agent creation
+ 'search': SearchClient(),
+ 'summarize': SummarizationService(),
+ }
+)
+
+# Orchestrator can now create specialized sub-agents
+# Sub-agents inherit capabilities and objects from orchestrator
+```
+
+### Type-Safe Agent Composition
+
+```python
+# Agents specify return types when invoked
+# Execution environment enforces type compliance
+
+research_result = await research_agent.run(
+ "Research quantum computing trends",
+ return_type=ResearchReport
+)
+
+# Subsequent agents can reliably depend on returned objects
+analysis = await analysis_agent.run(
+ f"Analyze this report: {research_result}",
+ return_type=AnalysisSummary,
+ scope={'report': research_result} # Type-safe injection
+)
+```
+
+### Agent Communication Patterns
+
+| Pattern | Description | Use Case |
+|---------|-------------|----------|
+| **Sequential Pipeline** | Output of agent N feeds input of agent N+1 | Document processing workflows |
+| **Parallel Fan-Out** | Multiple agents process simultaneously | Research aggregation |
+| **Hierarchical Delegation** | Parent spawns child agents for subtasks | Complex problem decomposition |
+| **Shared State** | Agents share objects through scope | Collaborative editing |
+
+---
+
+## Practical Implementation Guide
+
+### Step 1: Define Your Tool Schema
+
+```typescript
+// servers/crm/index.ts
+export interface CRMServer {
+ contacts: {
+ list(filters?: ContactFilters): Promise<Contact[]>;
+ get(id: string): Promise<Contact>;
+ create(data: CreateContactData): Promise<Contact>;
+ update(id: string, data: UpdateContactData): Promise<Contact>;
+ };
+ deals: {
+ list(filters?: DealFilters): Promise<Deal[]>;
+ create(data: CreateDealData): Promise<Deal>;
+ updateStage(id: string, stage: DealStage): Promise<Deal>;
+ };
+}
+```
+
+### Step 2: Implement Object Hierarchies
+
+```python
+class Contact:
+ """CRM Contact with related operations."""
+
+ def __init__(self, data: dict, client: CRMClient):
+ self.id = data['id']
+ self.name = data['name']
+ self.email = data['email']
+ self._client = client
+
+ async def get_deals(self) -> List['Deal']:
+ """Get all deals associated with this contact."""
+ return await self._client.deals.list(contact_id=self.id)
+
+ async def create_deal(self, data: CreateDealData) -> 'Deal':
+ """Create a new deal for this contact."""
+ data['contact_id'] = self.id
+ return await self._client.deals.create(data)
+
+ async def send_email(self, subject: str, body: str) -> EmailResult:
+ """Send email to this contact."""
+ return await self._client.email.send(
+ to=self.email,
+ subject=subject,
+ body=body
+ )
+```
+
+### Step 3: Configure Sandbox Environment
+
+```typescript
+// Cloudflare Workers approach
+export default {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const agent = new Agent({
+ model: "claude-4",
+ servers: {
+ crm: new CRMServer(env.CRM_API_KEY),
+ email: new EmailServer(env.EMAIL_API_KEY),
+ },
+ sandbox: {
+ maxExecutionTime: 30000, // 30 seconds
+ maxMemory: 128 * 1024 * 1024, // 128MB
+ allowedNetworkHosts: ['api.crm.com', 'api.email.com'],
+ }
+ });
+
+ return agent.handle(request);
+ }
+};
+```
+
+### Step 4: Enable Progressive Discovery
+
+```python
+class AgentScope:
+ """Dynamic scope with progressive discovery."""
+
+ def __init__(self, initial_objects: dict):
+ self._objects = initial_objects
+ self._definitions_cache = {}
+
+ def show_definition(self, object_name: str) -> str:
+ """IDE-like go-to-definition for agents."""
+ if object_name not in self._definitions_cache:
+ obj = self._objects.get(object_name)
+ if obj:
+ self._definitions_cache[object_name] = self._extract_definition(obj)
+ return self._definitions_cache.get(object_name, "Object not found")
+
+ def _extract_definition(self, obj) -> str:
+ """Extract type hints, docstrings, and method signatures."""
+ import inspect
+ lines = []
+ for name, method in inspect.getmembers(obj, predicate=inspect.ismethod):
+ if not name.startswith('_'):
+ sig = inspect.signature(method)
+ doc = method.__doc__ or "No description"
+ lines.append(f"{name}{sig}: {doc}")
+ return "\n".join(lines)
+```
+
+### Step 5: Implement Type-Safe Returns
+
+```python
+from pydantic import BaseModel
+from typing import TypeVar, Generic
+
+T = TypeVar('T', bound=BaseModel)
+
+class TypedAgentResult(Generic[T]):
+ def __init__(self, value: T, execution_trace: List[str]):
+ self.value = value
+ self.trace = execution_trace
+
+async def run_agent(
+ prompt: str,
+ return_type: Type[T],
+ scope: dict
+) -> TypedAgentResult[T]:
+ """Execute agent with type-safe return enforcement."""
+
+ # Generate and execute code
+ result = await execute_in_sandbox(prompt, scope)
+
+ # Validate return type
+ if not isinstance(result.value, return_type):
+ try:
+ result.value = return_type.model_validate(result.value)
+ except ValidationError as e:
+ raise AgentTypeError(f"Return type mismatch: {e}")
+
+ return result
+```
+
+---
+
+## Performance Benchmarks
+
+### Token Efficiency Comparison
+
+| Scenario | Traditional MCP | Code Mode | Savings |
+|----------|-----------------|-----------|---------|
+| Simple single-event task | 1,000 tokens | 680 tokens | 32% |
+| 31-event creation | 15,500 tokens | 2,945 tokens | **81%** |
+| Tool definition loading | 150,000 tokens | 2,000 tokens | **98.7%** |
+| Complex workflow (10 steps) | 25,000 tokens | 4,500 tokens | 82% |
+
+### Benchmark Results
+
+**Symbolica Agentica on BrowseComp-Plus**:
+- GPT-5 with Agentica: **77.11%**
+- GPT-5 without Agentica: 73.25%
+- Improvement: **3.86 percentage points**
+
+### Latency Improvements
+
+| Operation | Sequential Tool Calls | Code Mode |
+|-----------|----------------------|-----------|
+| 31 calendar events | ~31 round trips | 1 round trip |
+| Data filtering (10K rows) | N/A (context overflow) | Single execution |
+| Multi-step workflow | N * LLM latency | 1 * LLM latency |
+
+---
+
+## Future Directions
+
+### Research Areas
+
+1. **Better DSLs for Agent Programs**
+ - Moving beyond single RPC calls toward coherent program structures
+ - Type-checking and linting for agent-generated plans
+ - Formal verification of agent behavior
+
+2. **Context Degradation Mitigation**
+ - Research shows context degradation in extended conversations
+ - LLMs perform better with complete program specifications
+ - Single-shot program generation vs. multi-turn accumulation
+
+3. **Skill Learning and Persistence**
+ - Agents save reusable code functions as recoverable skills
+ - State persistence across operations through filesystem access
+ - Learning from successful execution traces
+
+4. **Cross-Language Agent Interoperability**
+ - Language-agnostic object models
+ - Runtime type checking across language boundaries
+ - Unified execution environments (Python, TypeScript, more)
+
+### Emerging Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| **Agent Skills** | Persistent, reusable code snippets agents can invoke |
+| **Typed Agent Protocols** | Formal interface definitions for agent communication |
+| **Execution Traces** | Debuggable records of agent decisions and code |
+| **Rollback Capabilities** | Transaction-like semantics for agent operations |
+
+---
+
+## Conclusion
+
+The shift from traditional tool-calling to code-centric agent architectures represents a fundamental advancement in AI agent design. Key takeaways:
+
+1. **Code is the natural interface** for LLMs to express complex operations
+2. **Progressive discovery** dramatically reduces token consumption
+3. **Object hierarchies** enable natural capability encoding
+4. **Sandboxed execution** provides necessary security guarantees
+5. **Type-safe composition** enables reliable multi-agent systems
+
+The convergence of Cloudflare, Anthropic, Symbolica, and BoundaryML on these patterns suggests a maturing consensus on how to build production-ready autonomous agents.
+
+---
+
+## References
+
+- [Agentica: Beyond Code Mode for Autonomous Agents](https://www.symbolica.ai/blog/beyond-code-mode-agentica) - Symbolica
+- [Code Mode: The Better Way to Use MCP](https://blog.cloudflare.com/code-mode/) - Cloudflare
+- [Code Execution with MCP: Building More Efficient AI Agents](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic
+- [Lambda the Ultimate AI Agent](https://boundaryml.com/blog/lambda-the-ultimate-ai-agent) - BoundaryML
+- [Cloudflare Code Mode Cuts Token Usage by 81%](https://workos.com/blog/cloudflare-code-mode-cuts-token-usage-by-81) - WorkOS
+
+---
+
+*Document created: 2026-02-12*
+*Based on research from Symbolica, Cloudflare, Anthropic, and BoundaryML*
diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.md
new file mode 100644
index 00000000..c44eb22e
--- /dev/null
+++ b/docs-internal/memory_compaction.md
@@ -0,0 +1,608 @@
+# Memory Compaction and Token Tracking Service
+
+## Overview
+
+The compaction service enables automatic memory compaction and token tracking for MachinaOs specialized agents. It uses a hybrid approach leveraging native provider APIs (Anthropic, OpenAI) when available, with comprehensive token tracking for all providers.
+
+**Inspired by:** Claude Code's compaction pattern from the Anthropic SDK
+**Default Threshold:** 100,000 tokens (configurable per session)
+
+## 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:
+
+```python
+from services.compaction import get_compaction_service
+
+svc = get_compaction_service()
+compaction_config = svc.anthropic_config(threshold=100000)
+# Returns: {"enabled": True, "context_token_threshold": 100000}
+
+# Use with tool_runner
+result = await tool_runner(
+ model="claude-3-5-sonnet-20241022",
+ messages=messages,
+ tools=tools,
+ compaction_control=compaction_config
+)
+```
+
+### Anthropic Messages API
+
+For direct Messages API usage with the compaction beta:
+
+```python
+api_config = svc.anthropic_api_config(threshold=100000)
+# Returns:
+# {
+# "betas": ["compact-2026-01-12"],
+# "context_management": {
+# "edits": [{
+# "type": "compact_20260112",
+# "trigger": {"type": "input_tokens", "value": 100000}
+# }]
+# }
+# }
+
+# Use with Messages API
+response = await client.messages.create(
+ model="claude-3-5-sonnet-20241022",
+ messages=messages,
+ **api_config
+)
+```
+
+### OpenAI
+
+For OpenAI models (including GPT-4 and o-series):
+
+```python
+openai_config = svc.openai_config(threshold=100000)
+# Returns: {"context_management": {"compact_threshold": 100000}}
+```
+
+## Database Schema
+
+### TokenUsageMetric
+
+Tracks token usage per agent execution:
+
+```python
+class TokenUsageMetric(SQLModel, table=True):
+ __tablename__ = "token_usage_metrics"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True) # Memory session ID
+ node_id: str = Field(index=True) # Agent node ID
+ workflow_id: Optional[str] = None # Workflow context
+ provider: str # openai, anthropic, gemini, groq
+ model: str # Model identifier
+
+ # Core token counts (LangChain UsageMetadata compatible)
+ input_tokens: int = 0
+ output_tokens: int = 0
+ total_tokens: int = 0
+
+ # Provider-specific token details
+ cache_creation_tokens: int = 0 # Anthropic cache miss
+ cache_read_tokens: int = 0 # Anthropic cache hit
+ reasoning_tokens: int = 0 # OpenAI o-series reasoning
+
+ iteration: int = 1 # LangGraph iteration number
+ execution_id: Optional[str] # Workflow execution ID
+ created_at: Optional[datetime]
+```
+
+### SessionTokenState
+
+Cumulative token state per memory session:
+
+```python
+class SessionTokenState(SQLModel, table=True):
+ __tablename__ = "session_token_states"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(unique=True, index=True)
+
+ # Cumulative counters (reset after compaction)
+ cumulative_input_tokens: int = 0
+ cumulative_output_tokens: int = 0
+ cumulative_cache_tokens: int = 0
+ cumulative_reasoning_tokens: int = 0
+ cumulative_total: int = 0
+
+ # Compaction tracking
+ last_compaction_at: Optional[datetime]
+ compaction_count: int = 0
+
+ # Per-session configuration
+ custom_threshold: Optional[int] # Overrides global setting
+ compaction_enabled: bool = True
+
+ updated_at: Optional[datetime]
+```
+
+### CompactionEvent
+
+Historical record of compaction events:
+
+```python
+class CompactionEvent(SQLModel, table=True):
+ __tablename__ = "compaction_events"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True)
+ node_id: str
+ workflow_id: Optional[str]
+
+ trigger_reason: str # "native", "threshold", "manual"
+ tokens_before: int
+ tokens_after: int
+ messages_before: int = 0
+ messages_after: int = 0
+
+ summary_model: str
+ summary_provider: str
+ summary_tokens_used: int = 0
+ success: bool = True
+ error_message: Optional[str]
+ summary_content: Optional[str] # The compacted summary
+
+ created_at: Optional[datetime]
+```
+
+## Service API
+
+### Initialization
+
+The service is initialized via dependency injection in `container.py`:
+
+```python
+from services.compaction import get_compaction_service, init_compaction_service
+
+# During app startup (handled by container)
+compaction_service = init_compaction_service(database, settings)
+
+# Get the singleton instance anywhere
+svc = get_compaction_service()
+```
+
+### Track Token Usage
+
+Call after each AI agent execution:
+
+```python
+result = await svc.track(
+ session_id="user-session-123",
+ node_id="agent-node-1",
+ provider="anthropic",
+ model="claude-3-5-sonnet-20241022",
+ usage={
+ "input_tokens": 5000,
+ "output_tokens": 1000,
+ "total_tokens": 6000,
+ "cache_creation_tokens": 2000, # Optional
+ "cache_read_tokens": 1500, # Optional
+ "reasoning_tokens": 0 # Optional
+ }
+)
+
+# result:
+# {
+# "total": 6000, # New cumulative total
+# "threshold": 100000, # Active threshold
+# "needs_compaction": False
+# }
+```
+
+### Record Compaction Event
+
+Call after native provider handles compaction:
+
+```python
+await svc.record(
+ session_id="user-session-123",
+ node_id="agent-node-1",
+ provider="anthropic",
+ model="claude-3-5-sonnet-20241022",
+ tokens_before=105000,
+ tokens_after=15000,
+ summary="## Summary\nConversation about project planning..." # Optional
+)
+```
+
+### Get Session Statistics
+
+```python
+stats = await svc.stats("user-session-123")
+# {
+# "session_id": "user-session-123",
+# "total": 15000,
+# "threshold": 100000,
+# "count": 1 # Number of compactions
+# }
+```
+
+### Configure Per-Session Settings
+
+```python
+# Set custom threshold for a session
+await svc.configure("user-session-123", threshold=50000)
+
+# Disable compaction for a session
+await svc.configure("user-session-123", enabled=False)
+
+# Both
+await svc.configure("user-session-123", threshold=75000, enabled=True)
+```
+
+## WebSocket Handlers
+
+### get_compaction_stats
+
+Get token usage statistics for a session:
+
+```javascript
+// Client request
+ws.send(JSON.stringify({
+ type: "get_compaction_stats",
+ session_id: "user-session-123"
+}));
+
+// Server response
+{
+ "type": "get_compaction_stats",
+ "success": true,
+ "session_id": "user-session-123",
+ "total": 45000,
+ "threshold": 100000,
+ "count": 0
+}
+```
+
+### configure_compaction
+
+Update compaction settings for a session:
+
+```javascript
+// Client request
+ws.send(JSON.stringify({
+ type: "configure_compaction",
+ session_id: "user-session-123",
+ threshold: 50000,
+ enabled: true
+}));
+
+// Server response
+{
+ "type": "configure_compaction",
+ "success": true
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# In server/.env
+COMPACTION_ENABLED=true # Enable/disable compaction globally (default: true)
+COMPACTION_THRESHOLD=100000 # Default token threshold (default: 100000, min: 10000)
+```
+
+### Per-Session Override
+
+Sessions can override the global threshold:
+
+```python
+# Via service API
+await svc.configure("session-id", threshold=50000)
+
+# Via WebSocket
+ws.send(JSON.stringify({
+ type: "configure_compaction",
+ session_id: "session-id",
+ threshold: 50000
+}));
+```
+
+## Integration with AI Service
+
+### Token Extraction from LangChain
+
+LangChain normalizes token usage across all providers via `UsageMetadata`:
+
+```python
+from langchain_core.messages.ai import UsageMetadata, add_usage
+
+# After AI execution
+response = await model.ainvoke(messages)
+usage = response.usage_metadata
+
+# Example usage_metadata:
+# {
+# 'input_tokens': 8,
+# 'output_tokens': 304,
+# 'total_tokens': 312,
+# 'input_token_details': {'cache_read': 0, 'cache_creation': 0},
+# 'output_token_details': {'reasoning': 256}
+# }
+
+# Aggregate across LangGraph iterations
+total_usage = None
+for msg in final_state["messages"]:
+ if hasattr(msg, 'usage_metadata') and msg.usage_metadata:
+ total_usage = add_usage(total_usage, msg.usage_metadata)
+```
+
+### Integration Point
+
+In `server/services/ai.py`, after agent execution:
+
+```python
+# After LangGraph execution, before memory save
+if memory_data and memory_data.get('session_id'):
+ from services.compaction import get_compaction_service
+ svc = get_compaction_service()
+
+ if svc and ai_response and ai_response.usage_metadata:
+ usage = ai_response.usage_metadata
+ tracking = await svc.track(
+ session_id=memory_data['session_id'],
+ node_id=node_id,
+ provider=provider,
+ model=model,
+ usage={
+ "input_tokens": usage.get('input_tokens', 0),
+ "output_tokens": usage.get('output_tokens', 0),
+ "total_tokens": usage.get('total_tokens', 0),
+ "cache_creation_tokens": usage.get('input_token_details', {}).get('cache_creation', 0),
+ "cache_read_tokens": usage.get('input_token_details', {}).get('cache_read', 0),
+ "reasoning_tokens": usage.get('output_token_details', {}).get('reasoning', 0),
+ }
+ )
+
+ if tracking.get('needs_compaction'):
+ # Trigger native compaction or client-side summarization
+ ...
+```
+
+## File Reference
+
+| File | Description |
+|------|-------------|
+| `server/services/compaction.py` | CompactionService class with provider configs |
+| `server/models/database.py` | SQLModel tables for token tracking |
+| `server/core/database.py` | CRUD methods for metrics and events |
+| `server/core/config.py` | Environment variable configuration |
+| `server/core/container.py` | Dependency injection setup |
+| `server/routers/websocket.py` | WebSocket handlers |
+| `server/main.py` | Service initialization on startup |
+
+## Design Decisions
+
+1. **Hybrid Approach**: Leverage native provider APIs (Anthropic, OpenAI) for compaction instead of reimplementing. Track tokens for all providers.
+
+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.
+
+4. **100K Token Threshold**: Matches Claude Code's default. This provides a good balance between context retention and performance.
+
+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
+
+For all providers (not just Anthropic/OpenAI), the service performs automatic client-side compaction when the threshold is exceeded. This uses the AI service to generate a structured summary following Claude Code's 5-section pattern.
+
+### compact_context() Method
+
+```python
+result = await svc.compact_context(
+ session_id="user-session-123",
+ node_id="agent-node-1",
+ memory_content="# Conversation History\n...", # Current memory markdown
+ provider="anthropic",
+ api_key="sk-...",
+ model="claude-3-5-sonnet-20241022"
+)
+
+# result:
+# {
+# "success": True,
+# "summary": "# Conversation Summary (Compacted)\n...",
+# "tokens_before": 105000,
+# "tokens_after": 0
+# }
+```
+
+### Summary Structure
+
+The compacted summary follows Claude Code's 5-section pattern:
+
+```markdown
+# Conversation Summary (Compacted)
+*Generated: 2025-02-12T10:30:00Z*
+
+## Task Overview
+What the user is trying to accomplish.
+
+## Current State
+What's been completed and what's in progress.
+
+## Important Discoveries
+Key findings, decisions, or problems encountered.
+
+## Next Steps
+What needs to happen next.
+
+## Context to Preserve
+Details that must be retained for continuity.
+```
+
+### Automatic Triggering
+
+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
+
+```python
+# In server/services/ai.py _track_token_usage()
+if tracking.get('needs_compaction') and memory_content and api_key:
+ result = await svc.compact_context(
+ session_id=session_id,
+ node_id=node_id,
+ memory_content=memory_content,
+ provider=provider,
+ api_key=api_key,
+ model=model
+ )
+
+ if result.get("success"):
+ # Update memory with compacted summary
+ memory_data['memory_content'] = result['summary']
+```
+
+### AI Service Wiring
+
+The compaction service requires the AI service to generate summaries. This is wired during app startup:
+
+```python
+# In server/main.py
+from services.compaction import get_compaction_service
+
+compaction_svc = container.compaction_service()
+compaction_svc.set_ai_service(container.ai_service())
+```
+
+## WebSocket Broadcasts
+
+The service broadcasts real-time updates to the frontend:
+
+### token_usage_update
+
+Broadcast after each AI execution with token tracking:
+
+```json
+{
+ "type": "token_usage_update",
+ "session_id": "user-session-123",
+ "data": {
+ "total": 45000,
+ "threshold": 100000,
+ "needs_compaction": false
+ }
+}
+```
+
+### compaction_starting
+
+Broadcast when compaction is about to begin:
+
+```json
+{
+ "type": "compaction_starting",
+ "session_id": "user-session-123",
+ "node_id": "agent-node-1"
+}
+```
+
+### compaction_completed
+
+Broadcast when compaction finishes:
+
+```json
+{
+ "type": "compaction_completed",
+ "session_id": "user-session-123",
+ "success": true,
+ "tokens_before": 105000,
+ "tokens_after": 0,
+ "error": null
+}
+```
+
+## Frontend UI
+
+### Token Usage Panel
+
+The Token Usage panel is displayed in the MiddleSection of the parameter panel for memory nodes (simpleMemory). It shows:
+
+- **Progress bar**: Visual representation of tokens used vs threshold
+- **Statistics**: Current token count, threshold, compaction count
+- **Editable threshold**: Click edit icon to change threshold per session
+
+```typescript
+// In client/src/components/parameterPanel/MiddleSection.tsx
+<Collapse.Panel header="Token Usage" key="tokenUsage">
+ <Progress
+ percent={Math.min(100, Math.round((tokenStats.total / tokenStats.threshold) * 100))}
+ status={tokenStats.total >= tokenStats.threshold ? 'exception' : 'normal'}
+ />
+ <Statistic title="Tokens Used" value={`${tokenStats.total.toLocaleString()} / ${tokenStats.threshold.toLocaleString()}`} />
+ <Statistic title="Compactions" value={tokenStats.count} />
+
+ {/* Editable threshold */}
+ {isEditingThreshold ? (
+ <InputNumber
+ value={editThresholdValue}
+ onChange={setEditThresholdValue}
+ min={10000}
+ max={1000000}
+ step={10000}
+ />
+ ) : (
+ <Button icon={<EditOutlined />} onClick={() => setIsEditingThreshold(true)} />
+ )}
+</Collapse.Panel>
+```
+
+## Future Enhancements
+
+1. **Cost Tracking**: Extend token metrics to include cost calculations per provider/model
+2. **Compaction History UI**: View past compaction events and summaries in the frontend
+3. **Multiple Summary Strategies**: Allow users to choose different summarization approaches
diff --git a/package-lock.json b/package-lock.json
index 78b66be3..5b81a8ae 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "machinaos",
- "version": "0.0.12",
+ "version": "0.0.14",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "machinaos",
- "version": "0.0.12",
+ "version": "0.0.14",
"hasInstallScript": true,
"license": "MIT",
"workspaces": [
diff --git a/package.json b/package.json
index 9ef7e640..8a59c3db 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "machinaos",
- "version": "0.0.13",
+ "version": "0.0.14",
"description": "Open source workflow automation platform with AI agents, React Flow, and n8n-inspired architecture",
"type": "module",
"keywords": [
diff --git a/server/core/config.py b/server/core/config.py
index aa1f809a..a8501442 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -109,6 +109,10 @@ class Settings(BaseSettings):
# Feature Toggles
ws_logging_enabled: bool = Field(default=True, env="WS_LOGGING_ENABLED")
+ # Compaction Configuration
+ compaction_enabled: bool = Field(default=True, env="COMPACTION_ENABLED")
+ compaction_threshold: int = Field(default=100000, env="COMPACTION_THRESHOLD", ge=10000)
+
# Gunicorn Configuration (for production deployment)
gunicorn_timeout: int = Field(default=120, env="GUNICORN_TIMEOUT", ge=30)
gunicorn_graceful_timeout: int = Field(default=30, env="GUNICORN_GRACEFUL_TIMEOUT", ge=10)
diff --git a/server/core/container.py b/server/core/container.py
index c995037b..84d2ddc2 100644
--- a/server/core/container.py
+++ b/server/core/container.py
@@ -14,6 +14,7 @@ from services.text import TextService
from services.android_service import AndroidService
from services.user_auth import UserAuthService
from services.temporal import TemporalClientWrapper
+from services.compaction import init_compaction_service
class Container(containers.DeclarativeContainer):
@@ -83,6 +84,12 @@ class Container(containers.DeclarativeContainer):
AndroidService
)
+ compaction_service = providers.Singleton(
+ init_compaction_service,
+ database=database,
+ settings=settings
+ )
+
workflow_service = providers.Singleton(
WorkflowService,
database=database,
diff --git a/server/core/database.py b/server/core/database.py
index 17b9bed7..e7b4949a 100644
--- a/server/core/database.py
+++ b/server/core/database.py
@@ -9,7 +9,11 @@ from sqlalchemy import text, func
from contextlib import asynccontextmanager
from core.config import Settings
-from models.database import NodeParameter, Workflow, Execution, APIKey, APIKeyValidation, NodeOutput, ConversationMessage, ToolSchema, UserSkill, ChatMessage, UserSettings
+from models.database import (
+ NodeParameter, Workflow, Execution, APIKey, APIKeyValidation, NodeOutput,
+ ConversationMessage, ToolSchema, UserSkill, ChatMessage, UserSettings,
+ TokenUsageMetric, CompactionEvent, SessionTokenState
+)
from models.cache import CacheEntry # SQLite-backed cache for Redis alternative
from models.auth import User # Import User model to ensure table creation
from core.logging import get_logger
@@ -1476,4 +1480,222 @@ class Database:
except Exception as e:
logger.error("Failed to save user settings", user_id=user_id, error=str(e))
- return False
\ No newline at end of file
+ return False
+
+ # ============================================================================
+ # Token Usage Metrics
+ # ============================================================================
+
+ async def save_token_metric(self, metric: Dict[str, Any]) -> bool:
+ """Save a token usage metric record."""
+ try:
+ async with self.get_session() as session:
+ entry = TokenUsageMetric(
+ session_id=metric.get("session_id", "default"),
+ node_id=metric.get("node_id", ""),
+ workflow_id=metric.get("workflow_id"),
+ provider=metric.get("provider", ""),
+ model=metric.get("model", ""),
+ input_tokens=metric.get("input_tokens", 0),
+ output_tokens=metric.get("output_tokens", 0),
+ total_tokens=metric.get("total_tokens", 0),
+ cache_creation_tokens=metric.get("cache_creation_tokens", 0),
+ cache_read_tokens=metric.get("cache_read_tokens", 0),
+ reasoning_tokens=metric.get("reasoning_tokens", 0),
+ iteration=metric.get("iteration", 1),
+ execution_id=metric.get("execution_id"),
+ created_at=datetime.now(timezone.utc)
+ )
+ session.add(entry)
+ await session.commit()
+ return True
+ except Exception as e:
+ logger.error("Failed to save token metric", error=str(e))
+ return False
+
+ async def get_session_token_metrics(
+ self, session_id: str, limit: int = 100
+ ) -> List[Dict[str, Any]]:
+ """Get token metrics for a session."""
+ try:
+ async with self.get_session() as session:
+ stmt = (
+ select(TokenUsageMetric)
+ .where(TokenUsageMetric.session_id == session_id)
+ .order_by(TokenUsageMetric.created_at.desc())
+ .limit(limit)
+ )
+ result = await session.execute(stmt)
+ metrics = result.scalars().all()
+
+ return [
+ {
+ "id": m.id,
+ "session_id": m.session_id,
+ "node_id": m.node_id,
+ "provider": m.provider,
+ "model": m.model,
+ "input_tokens": m.input_tokens,
+ "output_tokens": m.output_tokens,
+ "total_tokens": m.total_tokens,
+ "cache_creation_tokens": m.cache_creation_tokens,
+ "cache_read_tokens": m.cache_read_tokens,
+ "reasoning_tokens": m.reasoning_tokens,
+ "iteration": m.iteration,
+ "created_at": m.created_at.isoformat() if m.created_at else None
+ }
+ for m in metrics
+ ]
+ except Exception as e:
+ logger.error("Failed to get token metrics", session_id=session_id, error=str(e))
+ return []
+
+ # ============================================================================
+ # Session Token State
+ # ============================================================================
+
+ async def get_or_create_session_token_state(
+ self, session_id: str
+ ) -> Dict[str, Any]:
+ """Get or create token state for a session."""
+ try:
+ async with self.get_session() as session:
+ stmt = select(SessionTokenState).where(
+ SessionTokenState.session_id == session_id
+ )
+ result = await session.execute(stmt)
+ state = result.scalar_one_or_none()
+
+ if not state:
+ state = SessionTokenState(
+ session_id=session_id,
+ updated_at=datetime.now(timezone.utc)
+ )
+ session.add(state)
+ await session.commit()
+ await session.refresh(state)
+
+ return {
+ "session_id": state.session_id,
+ "cumulative_input_tokens": state.cumulative_input_tokens,
+ "cumulative_output_tokens": state.cumulative_output_tokens,
+ "cumulative_cache_tokens": state.cumulative_cache_tokens,
+ "cumulative_reasoning_tokens": state.cumulative_reasoning_tokens,
+ "cumulative_total": state.cumulative_total,
+ "last_compaction_at": state.last_compaction_at.isoformat() if state.last_compaction_at else None,
+ "compaction_count": state.compaction_count,
+ "custom_threshold": state.custom_threshold,
+ "compaction_enabled": state.compaction_enabled
+ }
+ except Exception as e:
+ logger.error("Failed to get session token state", error=str(e))
+ return {
+ "session_id": session_id,
+ "cumulative_total": 0,
+ "compaction_enabled": True
+ }
+
+ async def update_session_token_state(
+ self, session_id: str, updates: Dict[str, Any]
+ ) -> bool:
+ """Update session token state."""
+ try:
+ async with self.get_session() as session:
+ stmt = select(SessionTokenState).where(
+ SessionTokenState.session_id == session_id
+ )
+ result = await session.execute(stmt)
+ state = result.scalar_one_or_none()
+
+ if not state:
+ state = SessionTokenState(session_id=session_id)
+ session.add(state)
+
+ for key, value in updates.items():
+ if hasattr(state, key):
+ setattr(state, key, value)
+
+ state.updated_at = datetime.now(timezone.utc)
+ await session.commit()
+ return True
+ except Exception as e:
+ logger.error("Failed to update session token state", error=str(e))
+ return False
+
+ async def reset_session_token_state(self, session_id: str) -> bool:
+ """Reset token state after compaction."""
+ return await self.update_session_token_state(session_id, {
+ "cumulative_input_tokens": 0,
+ "cumulative_output_tokens": 0,
+ "cumulative_cache_tokens": 0,
+ "cumulative_reasoning_tokens": 0,
+ "cumulative_total": 0,
+ "last_compaction_at": datetime.now(timezone.utc)
+ })
+
+ # ============================================================================
+ # Compaction Events
+ # ============================================================================
+
+ async def save_compaction_event(self, event: Dict[str, Any]) -> bool:
+ """Save a compaction event record."""
+ try:
+ async with self.get_session() as session:
+ entry = CompactionEvent(
+ session_id=event.get("session_id", "default"),
+ node_id=event.get("node_id", ""),
+ workflow_id=event.get("workflow_id"),
+ trigger_reason=event.get("trigger_reason", "threshold"),
+ tokens_before=event.get("tokens_before", 0),
+ tokens_after=event.get("tokens_after", 0),
+ messages_before=event.get("messages_before", 0),
+ messages_after=event.get("messages_after", 0),
+ summary_model=event.get("summary_model", ""),
+ summary_provider=event.get("summary_provider", ""),
+ summary_tokens_used=event.get("summary_tokens_used", 0),
+ success=event.get("success", True),
+ error_message=event.get("error_message"),
+ summary_content=event.get("summary_content"),
+ created_at=datetime.now(timezone.utc)
+ )
+ session.add(entry)
+ await session.commit()
+ return True
+ except Exception as e:
+ logger.error("Failed to save compaction event", error=str(e))
+ return False
+
+ async def get_compaction_history(
+ self, session_id: str, limit: int = 50
+ ) -> List[Dict[str, Any]]:
+ """Get compaction history for a session."""
+ try:
+ async with self.get_session() as session:
+ stmt = (
+ select(CompactionEvent)
+ .where(CompactionEvent.session_id == session_id)
+ .order_by(CompactionEvent.created_at.desc())
+ .limit(limit)
+ )
+ result = await session.execute(stmt)
+ events = result.scalars().all()
+
+ return [
+ {
+ "id": e.id,
+ "session_id": e.session_id,
+ "node_id": e.node_id,
+ "trigger_reason": e.trigger_reason,
+ "tokens_before": e.tokens_before,
+ "tokens_after": e.tokens_after,
+ "messages_before": e.messages_before,
+ "messages_after": e.messages_after,
+ "success": e.success,
+ "error_message": e.error_message,
+ "created_at": e.created_at.isoformat() if e.created_at else None
+ }
+ for e in events
+ ]
+ except Exception as e:
+ logger.error("Failed to get compaction history", session_id=session_id, error=str(e))
+ return []
\ No newline at end of file
diff --git a/server/main.py b/server/main.py
index 3231acde..11d012af 100644
--- a/server/main.py
+++ b/server/main.py
@@ -116,6 +116,12 @@ async def lifespan(app: FastAPI):
)
await cleanup_service.start()
+ # Initialize compaction service and wire AI service
+ from services.compaction import get_compaction_service
+ compaction_svc = container.compaction_service() # Trigger singleton initialization
+ compaction_svc.set_ai_service(container.ai_service())
+ logger.info("Compaction service initialized")
+
# Record startup time for health reporting
set_startup_time()
diff --git a/server/models/database.py b/server/models/database.py
index 4f7fad6b..57029658 100644
--- a/server/models/database.py
+++ b/server/models/database.py
@@ -260,4 +260,73 @@ class UserSettings(SQLModel, table=True):
updated_at: datetime = Field(
default_factory=lambda: datetime.now(timezone.utc),
sa_column=Column(DateTime(timezone=True), onupdate=func.now())
- )
\ No newline at end of file
+ )
+
+
+# =============================================================================
+# Token Tracking and Memory Compaction
+# =============================================================================
+
+
+class TokenUsageMetric(SQLModel, table=True):
+ """Token usage per agent execution."""
+
+ __tablename__ = "token_usage_metrics"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True, max_length=255)
+ node_id: str = Field(index=True, max_length=255)
+ workflow_id: Optional[str] = Field(default=None, max_length=255)
+ provider: str = Field(max_length=50)
+ model: str = Field(max_length=100)
+ input_tokens: int = Field(default=0)
+ output_tokens: int = Field(default=0)
+ total_tokens: int = Field(default=0)
+ cache_creation_tokens: int = Field(default=0)
+ cache_read_tokens: int = Field(default=0)
+ reasoning_tokens: int = Field(default=0)
+ iteration: int = Field(default=1)
+ execution_id: Optional[str] = Field(default=None, max_length=255)
+ created_at: Optional[datetime] = Field(default=None)
+
+
+class CompactionEvent(SQLModel, table=True):
+ """Compaction event history."""
+
+ __tablename__ = "compaction_events"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True, max_length=255)
+ node_id: str = Field(max_length=255)
+ workflow_id: Optional[str] = Field(default=None, max_length=255)
+ trigger_reason: str = Field(max_length=50)
+ tokens_before: int = Field(default=0)
+ tokens_after: int = Field(default=0)
+ messages_before: int = Field(default=0)
+ messages_after: int = Field(default=0)
+ summary_model: str = Field(max_length=100)
+ summary_provider: str = Field(max_length=50)
+ summary_tokens_used: int = Field(default=0)
+ success: bool = Field(default=True)
+ error_message: Optional[str] = Field(default=None, max_length=2000)
+ summary_content: Optional[str] = Field(default=None, max_length=50000)
+ created_at: Optional[datetime] = Field(default=None)
+
+
+class SessionTokenState(SQLModel, table=True):
+ """Cumulative token state per memory session."""
+
+ __tablename__ = "session_token_states"
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(unique=True, index=True, max_length=255)
+ cumulative_input_tokens: int = Field(default=0)
+ cumulative_output_tokens: int = Field(default=0)
+ cumulative_cache_tokens: int = Field(default=0)
+ cumulative_reasoning_tokens: int = Field(default=0)
+ cumulative_total: int = Field(default=0)
+ last_compaction_at: Optional[datetime] = Field(default=None)
+ compaction_count: int = Field(default=0)
+ custom_threshold: Optional[int] = Field(default=None)
+ compaction_enabled: bool = Field(default=True)
+ updated_at: Optional[datetime] = Field(default=None)
\ No newline at end of file
diff --git a/server/routers/websocket.py b/server/routers/websocket.py
index 868006b5..4fbade3b 100644
--- a/server/routers/websocket.py
+++ b/server/routers/websocket.py
@@ -1770,6 +1770,7 @@ async def handle_scan_skill_folder(data: Dict[str, Any], websocket: WebSocket) -
Returns list of discovered skills with their metadata.
Used by MasterSkillEditor when skillFolder is set.
+ Also registers discovered skills in the global registry for get_skill_content.
"""
from pathlib import Path
from services.skill_loader import get_skill_loader
@@ -1786,6 +1787,10 @@ async def handle_scan_skill_folder(data: Dict[str, Any], websocket: WebSocket) -
for skill_md in target_dir.rglob("SKILL.md"):
metadata = skill_loader._parse_skill_metadata(skill_md)
if metadata:
+ # Register the skill in the global registry so get_skill_content can find it
+ metadata.path = skill_md.parent
+ skill_loader._registry[metadata.name] = metadata
+
skills.append({
"name": metadata.name,
"description": metadata.description,
@@ -2006,6 +2011,31 @@ async def handle_save_user_settings(data: Dict[str, Any], websocket: WebSocket)
return {"success": False, "error": "Failed to save settings"}
+# ============================================================================
+# Compaction Handlers
+# ============================================================================
+
+@ws_handler("session_id")
+async def handle_get_compaction_stats(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Get compaction statistics for a session."""
+ from services.compaction import get_compaction_service
+ svc = get_compaction_service()
+ if not svc:
+ return {"success": False, "error": "Compaction service not initialized"}
+ return await svc.stats(data["session_id"])
+
+
+@ws_handler("session_id")
+async def handle_configure_compaction(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Configure compaction settings for a session."""
+ from services.compaction import get_compaction_service
+ svc = get_compaction_service()
+ if not svc:
+ return {"success": False, "error": "Compaction service not initialized"}
+ success = await svc.configure(data["session_id"], data.get("threshold"), data.get("enabled"))
+ return {"success": success}
+
+
# ============================================================================
# Message Router
# ============================================================================
@@ -2134,6 +2164,10 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {
# User Settings
"get_user_settings": handle_get_user_settings,
"save_user_settings": handle_save_user_settings,
+
+ # Compaction
+ "get_compaction_stats": handle_get_compaction_stats,
+ "configure_compaction": handle_configure_compaction,
}
diff --git a/server/services/ai.py b/server/services/ai.py
index b9775ea3..36ffc455 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -761,6 +761,16 @@ class AIService:
if isinstance(content, str) and content.strip():
return content
+ # LangChain standard: use content_blocks property for typed content extraction
+ if ai_response and hasattr(ai_response, 'content_blocks') and ai_response.content_blocks:
+ text_parts = []
+ for block in ai_response.content_blocks:
+ if isinstance(block, dict) and block.get('type') == 'text':
+ text_parts.append(block.get('text', ''))
+ extracted = '\n'.join(filter(None, text_parts))
+ if extracted.strip():
+ return extracted
+
# Content is empty - try to get error details from metadata
error_details = []
if ai_response and hasattr(ai_response, 'response_metadata'):
@@ -775,13 +785,21 @@ class AIService:
if blocked:
error_details.append(f"Blocked categories: {', '.join(blocked)}")
- elif finish_reason == 'MAX_TOKENS':
- # Check if reasoning consumed all tokens
- token_details = meta.get('output_token_details', {})
- reasoning_tokens = token_details.get('reasoning', 0)
- output_tokens = meta.get('usage_metadata', {}).get('candidates_token_count', 0)
- if reasoning_tokens > 0 and output_tokens == 0:
- error_details.append(f"Model used all tokens for reasoning ({reasoning_tokens} tokens). Try increasing max_tokens or simplifying the prompt.")
+ elif finish_reason in ('MAX_TOKENS', 'length'):
+ # Check if reasoning consumed all tokens (OpenAI o-series models)
+ # OpenAI path: token_usage.completion_tokens_details.reasoning_tokens
+ token_usage = meta.get('token_usage', {})
+ completion_details = token_usage.get('completion_tokens_details', {})
+ reasoning_tokens = completion_details.get('reasoning_tokens', 0)
+ completion_tokens = token_usage.get('completion_tokens', 0)
+
+ # Also check Gemini path: output_token_details
+ if not reasoning_tokens:
+ token_details = meta.get('output_token_details', {})
+ reasoning_tokens = token_details.get('reasoning', 0)
+
+ if reasoning_tokens > 0 and reasoning_tokens >= completion_tokens:
+ error_details.append(f"Model used all {reasoning_tokens} tokens for reasoning, none left for response. Increase max_tokens (current response used {completion_tokens} total).")
else:
error_details.append("Response truncated due to max_tokens limit")
@@ -794,8 +812,15 @@ class AIService:
if error_details:
raise ValueError(f"AI returned empty response. {'; '.join(error_details)}")
- # Generic empty response
- logger.warning(f"[LangGraph] Empty response with no error details. Content type: {type(content)}, value: {content}")
+ # Generic empty response - log full response details for debugging
+ if ai_response:
+ logger.warning(f"[LangGraph] Empty response debug - content_blocks: {getattr(ai_response, 'content_blocks', None)}")
+ logger.warning(f"[LangGraph] Empty response debug - additional_kwargs: {getattr(ai_response, 'additional_kwargs', {})}")
+ if hasattr(ai_response, 'response_metadata'):
+ meta = ai_response.response_metadata
+ logger.warning(f"[LangGraph] Empty response debug - finish_reason: {meta.get('finish_reason')}")
+ logger.warning(f"[LangGraph] Empty response debug - token_usage: {meta.get('token_usage')}")
+ logger.warning(f"[LangGraph] Empty response with no error details. Content type: {type(content)}, value: {repr(content)}")
raise ValueError("AI generated empty response. Try rephrasing your prompt or using a different model.")
def _is_reasoning_model(self, model: str) -> bool:
@@ -809,6 +834,141 @@ class AIService:
# e.g., o1, o1-mini, o3, o3-mini, o4-mini
return bool(re.match(r'^o[134](-|$)', model_lower))
+ async def _track_token_usage(
+ self,
+ session_id: str,
+ node_id: str,
+ provider: str,
+ model: str,
+ ai_response,
+ all_messages: list,
+ broadcaster=None,
+ workflow_id: Optional[str] = None,
+ memory_content: Optional[str] = None,
+ api_key: Optional[str] = None,
+ memory_node_id: Optional[str] = None,
+ ) -> Optional[Dict[str, Any]]:
+ """Track token usage and trigger compaction if threshold exceeded.
+
+ Extracts usage_metadata from LangChain AIMessage and tracks it
+ in the compaction service for session token monitoring.
+
+ Args:
+ session_id: Memory session ID
+ node_id: Agent node ID
+ provider: AI provider name
+ model: Model name
+ ai_response: The AIMessage response
+ all_messages: All messages in conversation (for aggregation)
+ broadcaster: Optional status broadcaster
+ workflow_id: Optional workflow ID for scoped broadcasts
+ memory_content: Current memory content (for compaction)
+ api_key: API key (for compaction summarization)
+ memory_node_id: Memory node ID (for parameter updates)
+
+ Returns:
+ Compaction result if triggered, None otherwise
+ """
+ from services.compaction import get_compaction_service
+
+ svc = get_compaction_service()
+ if not svc:
+ return
+
+ # Extract usage_metadata from AIMessage (LangChain standardizes this)
+ usage = None
+ if hasattr(ai_response, 'usage_metadata') and ai_response.usage_metadata:
+ usage = ai_response.usage_metadata
+ elif hasattr(ai_response, 'response_metadata'):
+ # Fallback: check response_metadata for usage info
+ meta = ai_response.response_metadata
+ if 'usage' in meta:
+ usage = meta['usage']
+ elif 'token_usage' in meta:
+ usage = meta['token_usage']
+
+ if not usage:
+ # Aggregate usage from all AI messages if single message has no usage
+ total_input = 0
+ total_output = 0
+ for msg in all_messages:
+ if hasattr(msg, 'usage_metadata') and msg.usage_metadata:
+ total_input += msg.usage_metadata.get('input_tokens', 0)
+ total_output += msg.usage_metadata.get('output_tokens', 0)
+ if total_input > 0 or total_output > 0:
+ usage = {
+ 'input_tokens': total_input,
+ 'output_tokens': total_output,
+ 'total_tokens': total_input + total_output
+ }
+
+ if not usage:
+ logger.debug(f"[TokenTracking] No usage_metadata available for {provider}/{model}")
+ return
+
+ # Normalize usage dict (handle both dict and TypedDict formats)
+ usage_dict = {
+ 'input_tokens': usage.get('input_tokens', 0) if isinstance(usage, dict) else getattr(usage, 'input_tokens', 0),
+ 'output_tokens': usage.get('output_tokens', 0) if isinstance(usage, dict) else getattr(usage, 'output_tokens', 0),
+ 'total_tokens': usage.get('total_tokens', 0) if isinstance(usage, dict) else getattr(usage, 'total_tokens', 0)
+ }
+
+ try:
+ tracking = await svc.track(
+ session_id=session_id,
+ node_id=node_id,
+ provider=provider,
+ model=model,
+ usage=usage_dict
+ )
+ logger.debug(f"[TokenTracking] Tracked {usage_dict['total_tokens']} tokens for session {session_id}, total={tracking['total']}")
+
+ # Broadcast token update
+ if broadcaster:
+ await broadcaster.broadcast({
+ "type": "token_usage_update",
+ "session_id": session_id,
+ "workflow_id": workflow_id,
+ "data": tracking
+ })
+
+ # Trigger compaction if threshold exceeded
+ if tracking.get('needs_compaction') and memory_content and api_key:
+ logger.info(f"[Compaction] Threshold exceeded for session {session_id}, triggering compaction")
+
+ if broadcaster:
+ await broadcaster.broadcast({
+ "type": "compaction_starting",
+ "session_id": session_id,
+ "node_id": node_id
+ })
+
+ result = await svc.compact_context(
+ session_id=session_id,
+ node_id=node_id,
+ memory_content=memory_content,
+ provider=provider,
+ api_key=api_key,
+ model=model
+ )
+
+ if broadcaster:
+ await broadcaster.broadcast({
+ "type": "compaction_completed",
+ "session_id": session_id,
+ "success": result.get("success", False),
+ "tokens_before": result.get("tokens_before", 0),
+ "tokens_after": result.get("tokens_after", 0),
+ "error": result.get("error")
+ })
+
+ return result
+
+ except Exception as e:
+ logger.warning(f"[TokenTracking] Failed to track tokens: {e}")
+
+ return None
+
def create_model(self, provider: str, api_key: str, model: str,
temperature: float, max_tokens: int,
thinking: Optional[ThinkingConfig] = None,
@@ -1553,6 +1713,24 @@ class AIService:
logger.info(f"[LangGraph] Agent completed in {iterations} iteration(s), thinking={'yes' if thinking_content else 'no'}")
+ # Track token usage if memory connected (for compaction service)
+ # Also triggers compaction if threshold exceeded
+ compaction_result = None
+ if session_id and ai_response:
+ compaction_result = await self._track_token_usage(
+ session_id=session_id,
+ node_id=node_id,
+ provider=provider,
+ model=model,
+ ai_response=ai_response,
+ all_messages=all_messages,
+ broadcaster=broadcaster,
+ workflow_id=workflow_id,
+ memory_content=memory_data.get('memory_content', '') if memory_data else None,
+ api_key=api_key,
+ memory_node_id=memory_data.get('node_id') if memory_data else None
+ )
+
# Save to memory if connected (markdown-based with optional vector DB)
# Only save non-empty messages using standardized validation
if memory_data and memory_data.get('node_id') and is_valid_message_content(prompt) and is_valid_message_content(response_content):
@@ -1564,10 +1742,18 @@ class AIService:
"history_count": history_count
})
- # Update markdown content
- updated_content = memory_data.get('memory_content', '# Conversation History\n\n*No messages yet.*\n')
- updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
- updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
+ # If compaction happened, use compacted summary as base
+ if compaction_result and compaction_result.get('success') and compaction_result.get('summary'):
+ # Start fresh with compacted summary, then add current exchange
+ updated_content = compaction_result['summary']
+ updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
+ updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
+ logger.info(f"[LangGraph Memory] Using compacted summary as new base")
+ else:
+ # Normal flow: append to existing memory
+ updated_content = memory_data.get('memory_content', '# Conversation History\n\n*No messages yet.*\n')
+ updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
+ updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
# Trim to window size, archive removed to vector DB
window_size = memory_data.get('window_size', 10)
@@ -1967,6 +2153,26 @@ class AIService:
logger.info(f"[ChatAgent] Response generated, thinking={'yes' if thinking_content else 'no'}, iterations={iterations}")
+ # Track token usage if memory connected (for compaction service)
+ # Use ai_response for tools path, response for simple invoke
+ # Also triggers compaction if threshold exceeded
+ response_msg = ai_response if all_tools else response
+ compaction_result = None
+ if session_id and response_msg:
+ compaction_result = await self._track_token_usage(
+ session_id=session_id,
+ node_id=node_id,
+ provider=provider,
+ model=model,
+ ai_response=response_msg,
+ all_messages=all_messages if all_tools else messages + [response_msg],
+ broadcaster=broadcaster,
+ workflow_id=workflow_id,
+ memory_content=memory_content,
+ api_key=api_key,
+ memory_node_id=memory_data.get('node_id') if memory_data else None
+ )
+
# Save to memory if connected (markdown-based like AI Agent)
if memory_data and memory_data.get('node_id') and is_valid_message_content(prompt) and is_valid_message_content(response_content):
await broadcast_status("saving_memory", {
@@ -1975,10 +2181,17 @@ class AIService:
"has_memory": True
})
- # Update markdown content
- updated_content = memory_content or '# Conversation History\n\n*No messages yet.*\n'
- updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
- updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
+ # If compaction happened, use compacted summary as base
+ if compaction_result and compaction_result.get('success') and compaction_result.get('summary'):
+ updated_content = compaction_result['summary']
+ updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
+ updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
+ logger.info(f"[ChatAgent Memory] Using compacted summary as new base")
+ else:
+ # Normal flow: append to existing memory
+ updated_content = memory_content or '# Conversation History\n\n*No messages yet.*\n'
+ updated_content = _append_to_memory_markdown(updated_content, 'human', prompt)
+ updated_content = _append_to_memory_markdown(updated_content, 'ai', response_content)
# Trim to window size, archive removed to vector DB
window_size = memory_data.get('window_size', 10)
diff --git a/server/services/compaction.py b/server/services/compaction.py
new file mode 100644
index 00000000..3ec09ea1
--- /dev/null
+++ b/server/services/compaction.py
@@ -0,0 +1,187 @@
+"""Memory compaction service using native provider APIs.
+
+Anthropic: tool_runner with compaction_control parameter
+OpenAI: context_management with compact_threshold
+Others: Client-side summarization fallback
+"""
+
+from pydantic import BaseModel
+from datetime import datetime, timezone
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+from core.logging import get_logger
+
+if TYPE_CHECKING:
+ from core.database import Database
+ from core.config import Settings
+
+logger = get_logger(__name__)
+
+
+class CompactionConfig(BaseModel):
+ """Provider-agnostic compaction configuration."""
+ enabled: bool = True
+ threshold: int = 100000
+
+
+class CompactionService:
+ """Minimal compaction service using native provider APIs."""
+
+ def __init__(self, database: "Database", settings: "Settings"):
+ self._db = database
+ self._config = CompactionConfig(
+ enabled=settings.compaction_enabled,
+ threshold=settings.compaction_threshold
+ )
+ self._ai_service = None
+
+ def set_ai_service(self, ai_service) -> None:
+ """Wire AI service for generating compaction summaries."""
+ self._ai_service = ai_service
+
+ def anthropic_config(self, threshold: Optional[int] = None) -> Dict[str, Any]:
+ """Anthropic SDK compaction_control for tool_runner."""
+ return {
+ "enabled": self._config.enabled,
+ "context_token_threshold": threshold or self._config.threshold
+ }
+
+ def anthropic_api_config(self, threshold: Optional[int] = None) -> Dict[str, Any]:
+ """Anthropic Messages API context_management config."""
+ return {
+ "betas": ["compact-2026-01-12"],
+ "context_management": {
+ "edits": [{
+ "type": "compact_20260112",
+ "trigger": {"type": "input_tokens", "value": threshold or self._config.threshold}
+ }]
+ }
+ }
+
+ def openai_config(self, threshold: Optional[int] = None) -> Dict[str, Any]:
+ """OpenAI context_management config."""
+ return {"context_management": {"compact_threshold": threshold or self._config.threshold}}
+
+ async def track(self, session_id: str, node_id: str, provider: str, model: str, usage: Dict[str, int]) -> Dict[str, Any]:
+ """Track token usage and return compaction status."""
+ await self._db.save_token_metric({"session_id": session_id, "node_id": node_id, "provider": provider, "model": model, **usage})
+
+ state = await self._db.get_or_create_session_token_state(session_id)
+ new_total = state["cumulative_total"] + usage.get("total_tokens", 0)
+
+ await self._db.update_session_token_state(session_id, {
+ "cumulative_input_tokens": state["cumulative_input_tokens"] + usage.get("input_tokens", 0),
+ "cumulative_output_tokens": state["cumulative_output_tokens"] + usage.get("output_tokens", 0),
+ "cumulative_total": new_total
+ })
+
+ threshold = state.get("custom_threshold") or self._config.threshold
+ return {"total": new_total, "threshold": threshold, "needs_compaction": self._config.enabled and new_total >= threshold}
+
+ async def record(self, session_id: str, node_id: str, provider: str, model: str, tokens_before: int, tokens_after: int, summary: Optional[str] = None) -> None:
+ """Record compaction event after native API handles it."""
+ state = await self._db.get_or_create_session_token_state(session_id)
+ await self._db.save_compaction_event({
+ "session_id": session_id, "node_id": node_id, "trigger_reason": "native",
+ "tokens_before": tokens_before, "tokens_after": tokens_after,
+ "summary_model": model, "summary_provider": provider, "success": True, "summary_content": summary
+ })
+ await self._db.update_session_token_state(session_id, {
+ "cumulative_total": tokens_after,
+ "last_compaction_at": datetime.now(timezone.utc),
+ "compaction_count": state["compaction_count"] + 1
+ })
+
+ async def stats(self, session_id: str) -> Dict[str, Any]:
+ """Get session statistics."""
+ state = await self._db.get_or_create_session_token_state(session_id)
+ return {"session_id": session_id, "total": state["cumulative_total"], "threshold": state.get("custom_threshold") or self._config.threshold, "count": state.get("compaction_count", 0)}
+
+ async def configure(self, session_id: str, threshold: Optional[int] = None, enabled: Optional[bool] = None) -> bool:
+ """Configure session settings."""
+ updates = {}
+ if threshold is not None:
+ updates["custom_threshold"] = threshold
+ if enabled is not None:
+ updates["compaction_enabled"] = enabled
+ return await self._db.update_session_token_state(session_id, updates) if updates else True
+
+ async def compact_context(
+ self,
+ session_id: str,
+ node_id: str,
+ memory_content: str,
+ provider: str,
+ api_key: str,
+ model: str,
+ ) -> Dict[str, Any]:
+ """Perform compaction by summarizing conversation history.
+
+ Uses the AI service to generate a structured summary following Claude Code pattern.
+ """
+ if not self._ai_service:
+ logger.warning("[Compaction] AI service not wired")
+ return {"success": False, "error": "AI service not available"}
+
+ if not memory_content or len(memory_content.strip()) < 100:
+ return {"success": False, "error": "Memory content too short"}
+
+ state = await self._db.get_or_create_session_token_state(session_id)
+ tokens_before = state["cumulative_total"]
+
+ try:
+ prompt = f"""Summarize this conversation into a structured format:
+
+## Task Overview
+What the user is trying to accomplish.
+
+## Current State
+What's been completed and what's in progress.
+
+## Important Discoveries
+Key findings, decisions, or problems encountered.
+
+## Next Steps
+What needs to happen next.
+
+## Context to Preserve
+Details that must be retained for continuity.
+
+---
+CONVERSATION:
+{memory_content}
+---
+
+Provide a concise but complete summary."""
+
+ llm = self._ai_service.create_model(
+ provider=provider, api_key=api_key, model=model,
+ temperature=0.3, max_tokens=2000
+ )
+
+ from langchain_core.messages import HumanMessage
+ response = await llm.ainvoke([HumanMessage(content=prompt)])
+ summary = response.content if hasattr(response, 'content') else str(response)
+
+ new_memory = f"# Conversation Summary (Compacted)\n*Generated: {datetime.now(timezone.utc).isoformat()}*\n\n{summary}"
+
+ await self.record(session_id, node_id, provider, model, tokens_before, 0, new_memory)
+ logger.info(f"[Compaction] Session {session_id}: {tokens_before} -> 0 tokens")
+
+ return {"success": True, "summary": new_memory, "tokens_before": tokens_before, "tokens_after": 0}
+
+ except Exception as e:
+ logger.error(f"[Compaction] Failed: {e}")
+ return {"success": False, "error": str(e)}
+
+
+_service: Optional[CompactionService] = None
+
+def get_compaction_service() -> Optional[CompactionService]:
+ return _service
+
+def init_compaction_service(database: "Database", settings: "Settings") -> CompactionService:
+ global _service
+ _service = CompactionService(database, settings)
+ logger.info("[Compaction] Initialized")
+ return _service
diff --git a/server/skills/autonomous/agentic-loop-skill/SKILL.md b/server/skills/autonomous/agentic-loop-skill/SKILL.md
new file mode 100644
index 00000000..4b2ee182
--- /dev/null
+++ b/server/skills/autonomous/agentic-loop-skill/SKILL.md
@@ -0,0 +1,228 @@
+---
+name: agentic-loop-skill
+description: Autonomous decision loop with reflection and iteration
+allowed-tools: delegate_to_ai_agent python_code check_delegated_tasks
+metadata:
+ author: machina
+ version: "1.0"
+ category: autonomous
+ icon: "🔄"
+ color: "#8B5CF6"
+---
+# Agentic Loop Pattern
+
+You are an autonomous agent capable of iterative problem-solving through self-delegation and reflection.
+
+## Core Loop Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ AGENTIC LOOP │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ OBSERVE ──▶ THINK ──▶ ACT ──▶ REFLECT ──▶ DECIDE │
+│ ▲ │ │
+│ │ │ │
+│ └──────────── (if not done) ◀──────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Step Details
+
+1. **OBSERVE**: What is the current state?
+ - What data do I have?
+ - What has been accomplished?
+ - What constraints exist?
+
+2. **THINK**: What should I do next?
+ - What is the immediate goal?
+ - What's the best action to take?
+ - What could go wrong?
+
+3. **ACT**: Execute ONE focused action
+ - Generate code for computation
+ - Call a specific tool
+ - Delegate to a specialized agent
+
+4. **REFLECT**: Did it work?
+ - Was the action successful?
+ - What did I learn?
+ - How does this change the state?
+
+5. **DECIDE**: Continue or complete?
+ - Is the goal achieved? -> Complete and return
+ - More work needed? -> Continue loop
+ - Error occurred? -> Handle or escalate
+
+## Self-Delegation Pattern
+
+To iterate on complex tasks, delegate to yourself with updated context:
+
+```json
+{
+ "task": "Continue: [specific next step description]",
+ "context": "Iteration: 2/5\nPrevious result: [summary]\nCurrent state: [state]\nRemaining: [what's left to do]"
+}
+```
+
+### Context String Template
+
+```
+Iteration: {current}/{max}
+Goal: {original goal}
+Progress: {what has been accomplished}
+State: {current data/results}
+Errors: {any errors encountered}
+Next: {specific next action}
+```
+
+## Example: Multi-Step Research Task
+
+**Task**: "Research the top 3 programming languages of 2024, compare their use cases"
+
+### Iteration 1: Gather Data
+```json
+{
+ "task": "Continue: Search for programming language rankings",
+ "context": "Iteration: 1/4\nGoal: Compare top 3 programming languages\nProgress: Starting research\nNext: Use web_search to find current rankings"
+}
+```
+Action: Use web_search tool
+Result: Found TIOBE index - Python, C, C++
+
+### Iteration 2: Deep Dive on First Language
+```json
+{
+ "task": "Continue: Research Python use cases",
+ "context": "Iteration: 2/4\nGoal: Compare top 3 programming languages\nProgress: Identified top 3 (Python, C, C++)\nState: Rankings found\nNext: Research Python use cases"
+}
+```
+Action: Use web_search for Python applications
+Result: AI/ML, web development, automation, data science
+
+### Iteration 3: Research Remaining Languages
+```json
+{
+ "task": "Continue: Research C and C++ use cases",
+ "context": "Iteration: 3/4\nGoal: Compare top 3 programming languages\nProgress: Python use cases complete\nState: Python = AI/ML, web, automation\nNext: Research C and C++ use cases"
+}
+```
+Action: Use web_search for C/C++ applications
+Result: Systems programming, embedded, games, performance-critical
+
+### Iteration 4: Synthesize and Report
+```json
+{
+ "task": "Continue: Create comparison summary",
+ "context": "Iteration: 4/4\nGoal: Compare top 3 programming languages\nProgress: All research complete\nState: Python=AI/ML/Web, C=Systems/Embedded, C++=Games/Performance\nNext: Generate final comparison"
+}
+```
+Action: Generate comprehensive comparison
+Result: Complete comparison delivered to user
+
+## Stop Conditions
+
+**STOP and return when:**
+- Goal is achieved
+- Max iterations reached (default: 5)
+- Unrecoverable error encountered
+- User cancellation received
+- Diminishing returns (same result twice)
+
+**CONTINUE when:**
+- Progress is being made
+- More steps clearly needed
+- Recoverable error (can retry differently)
+
+## State Management Best Practices
+
+### DO:
+- Include iteration count in every delegation
+- Summarize previous results (not full data)
+- Be specific about the next action
+- Track accumulated state across iterations
+
+### DON'T:
+- Include massive data blobs in context
+- Forget to update iteration count
+- Lose track of the original goal
+- Continue indefinitely without progress
+
+## Example: Iterative Calculation
+
+**Task**: "Calculate fibonacci(50) and factorize it"
+
+### Iteration 1: Calculate Fibonacci
+```python
+# Use code mode for computation
+def fib(n):
+ a, b = 0, 1
+ for _ in range(n):
+ a, b = b, a + b
+ return a
+
+result = fib(50)
+print(f"Fibonacci(50) = {result}")
+# Result: 12586269025
+```
+
+### Iteration 2: Factorize
+```json
+{
+ "task": "Continue: Factorize the fibonacci result",
+ "context": "Iteration: 2/3\nGoal: Calculate and factorize fib(50)\nProgress: fib(50) = 12586269025\nNext: Find prime factors"
+}
+```
+
+```python
+def factorize(n):
+ factors = []
+ d = 2
+ while d * d <= n:
+ while n % d == 0:
+ factors.append(d)
+ n //= d
+ d += 1
+ if n > 1:
+ factors.append(n)
+ return factors
+
+n = 12586269025
+factors = factorize(n)
+print(f"Prime factors: {factors}")
+print(f"Verification: {eval('*'.join(map(str, factors)))}")
+```
+
+### Iteration 3: Summarize
+Final response to user with both results
+
+## Integration with Task Trigger
+
+When using self-delegation:
+1. Your delegation creates a background task
+2. Task completes and fires `task_completed` event
+3. Task Trigger node catches the event
+4. Result is injected into your next prompt
+5. You continue with the result
+
+This enables visual tracking of the loop in the workflow canvas.
+
+## Error Recovery in Loops
+
+If an iteration fails:
+```json
+{
+ "task": "Retry: [same task with different approach]",
+ "context": "Iteration: 2/5 (retry 1)\nGoal: [original goal]\nProgress: [what worked]\nError: [what failed and why]\nNew approach: [different strategy]"
+}
+```
+
+## Anti-Patterns to Avoid
+
+1. **Infinite loops** - Always track iteration count
+2. **Lost context** - Always include previous results
+3. **Redundant work** - Check if step already done
+4. **Unclear goals** - State what "done" means clearly
+5. **Giant context** - Summarize, don't copy everything
+6. **No progress check** - Verify each step advanced the goal
diff --git a/server/skills/autonomous/code-mode-skill/SKILL.md b/server/skills/autonomous/code-mode-skill/SKILL.md
new file mode 100644
index 00000000..2f2caf50
--- /dev/null
+++ b/server/skills/autonomous/code-mode-skill/SKILL.md
@@ -0,0 +1,226 @@
+---
+name: code-mode-skill
+description: Generate Python code instead of sequential tool calls (81-98% token savings)
+allowed-tools: python_code javascript_code
+metadata:
+ author: machina
+ version: "1.0"
+ category: autonomous
+ icon: "💻"
+ color: "#10B981"
+---
+# Code Mode Pattern
+
+You are a Code Mode agent. Instead of calling tools sequentially, generate Python code that accomplishes the entire task in a single execution.
+
+## Why Code Mode?
+
+Research from Cloudflare and Anthropic shows Code Mode provides:
+- **81-98% token savings** vs sequential tool call sequences
+- **Explicit control flow** - loops, conditionals, error handling in code
+- **Reusable patterns** - functions and variables persist across iterations
+- **Better debugging** - executable code is easier to trace and verify
+
+## Available Libraries
+
+When generating Python code, you have access to:
+```python
+import math # Mathematical functions (factorial, sqrt, sin, cos, etc.)
+import json # JSON parsing and serialization
+import datetime # Date and time operations
+from datetime import timedelta
+import re # Regular expressions for text processing
+import random # Random number generation
+from collections import Counter, defaultdict # Data structures
+```
+
+## Core Pattern
+
+1. **Analyze** - Understand the complete task requirements
+2. **Generate** - Write complete Python code that solves the entire task
+3. **Execute** - Use the `python_code` tool to run the code
+4. **Return** - The code output becomes your response
+
+## Simple Example
+
+**Task**: "Calculate factorial of 10 and check if it's divisible by 7"
+
+**Wrong approach** (multiple tool calls - wasteful):
+```
+1. Call calculator: factorial(10)
+2. Get result: 3628800
+3. Call calculator: 3628800 % 7
+4. Get result: 0
+5. Return answer
+(4 LLM round-trips, ~4000 tokens)
+```
+
+**Code Mode approach** (single execution):
+```python
+import math
+import json
+
+# Calculate factorial
+result = math.factorial(10)
+
+# Check divisibility
+divisible = result % 7 == 0
+
+# Output structured result
+output = {
+ "factorial_of_10": result,
+ "divisible_by_7": divisible,
+ "remainder": result % 7
+}
+print(json.dumps(output, indent=2))
+```
+(2 LLM round-trips, ~800 tokens - 80% savings)
+
+## Complex Example with Loop
+
+**Task**: "Find all prime numbers between 1 and 100, show which are twin primes"
+
+```python
+import json
+
+def is_prime(n):
+ """Check if a number is prime."""
+ if n < 2:
+ return False
+ for i in range(2, int(n**0.5) + 1):
+ if n % i == 0:
+ return False
+ return True
+
+# Find all primes
+primes = [n for n in range(1, 101) if is_prime(n)]
+
+# Find twin primes (primes that differ by 2)
+twin_primes = []
+for i in range(len(primes) - 1):
+ if primes[i + 1] - primes[i] == 2:
+ twin_primes.append((primes[i], primes[i + 1]))
+
+output = {
+ "primes": primes,
+ "count": len(primes),
+ "sum": sum(primes),
+ "twin_primes": twin_primes,
+ "twin_count": len(twin_primes)
+}
+print(json.dumps(output, indent=2))
+```
+
+## Data Processing Example
+
+**Task**: "Analyze this list of numbers: find mean, median, mode, and standard deviation"
+
+```python
+import json
+from collections import Counter
+import math
+
+# Input data (would come from user or previous step)
+numbers = [23, 45, 67, 23, 89, 45, 23, 67, 90, 12, 45, 78]
+
+# Calculate statistics
+n = len(numbers)
+mean = sum(numbers) / n
+
+# Median
+sorted_nums = sorted(numbers)
+if n % 2 == 0:
+ median = (sorted_nums[n//2 - 1] + sorted_nums[n//2]) / 2
+else:
+ median = sorted_nums[n//2]
+
+# Mode
+counter = Counter(numbers)
+mode = counter.most_common(1)[0][0]
+
+# Standard deviation
+variance = sum((x - mean) ** 2 for x in numbers) / n
+std_dev = math.sqrt(variance)
+
+output = {
+ "data": numbers,
+ "count": n,
+ "mean": round(mean, 2),
+ "median": median,
+ "mode": mode,
+ "std_deviation": round(std_dev, 2),
+ "min": min(numbers),
+ "max": max(numbers)
+}
+print(json.dumps(output, indent=2))
+```
+
+## Error Handling in Code
+
+Always include error handling for robustness:
+
+```python
+import json
+
+def safe_divide(a, b):
+ """Safely divide two numbers."""
+ try:
+ return {"result": a / b, "success": True}
+ except ZeroDivisionError:
+ return {"error": "Division by zero", "success": False}
+ except Exception as e:
+ return {"error": str(e), "success": False}
+
+# Example usage
+results = []
+test_cases = [(10, 2), (15, 3), (7, 0), (100, 4)]
+
+for a, b in test_cases:
+ result = safe_divide(a, b)
+ result["operation"] = f"{a} / {b}"
+ results.append(result)
+
+print(json.dumps({"calculations": results}, indent=2))
+```
+
+## When NOT to Use Code Mode
+
+Use specific tools instead for:
+- **External API calls** - Use `http_request` tool for network requests
+- **Database operations** - Use data-specific tools
+- **File operations** - Use file-specific tools
+- **User interaction** - Respond directly without code
+- **Real-time data** - Use `web_search` or specific data tools
+- **Device control** - Use Android/device-specific tools
+
+## Integration with Multiple Tools
+
+When you need both code AND external tools, use this pattern:
+1. Gather data using appropriate tools (http_request, web_search, etc.)
+2. Process the gathered data using Code Mode
+3. Return the combined result
+
+Example flow:
+```
+User: "Search for Python release dates and calculate days since each release"
+
+1. Use web_search tool: "Python version release dates"
+2. Use python_code to process:
+ - Parse the dates from search results
+ - Calculate days since each release
+ - Format output nicely
+```
+
+## Output Format
+
+Always output results as JSON for downstream processing:
+```python
+import json
+# ... your calculations ...
+print(json.dumps(output, indent=2))
+```
+
+This enables:
+- Easy parsing by downstream nodes
+- Structured data for further processing
+- Clear, readable output for users
diff --git a/server/skills/autonomous/error-recovery-skill/SKILL.md b/server/skills/autonomous/error-recovery-skill/SKILL.md
new file mode 100644
index 00000000..b7241744
--- /dev/null
+++ b/server/skills/autonomous/error-recovery-skill/SKILL.md
@@ -0,0 +1,394 @@
+---
+name: error-recovery-skill
+description: Handle errors gracefully with retry strategies and fallback patterns
+allowed-tools: delegate_to_ai_agent python_code check_delegated_tasks
+metadata:
+ author: machina
+ version: "1.0"
+ category: autonomous
+ icon: "🛡️"
+ color: "#EF4444"
+---
+# Error Recovery Pattern
+
+You are an agent that handles errors gracefully through retry strategies, alternative approaches, and graceful degradation.
+
+## Error Classification
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ERROR CATEGORIES │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ TRANSIENT (Retry) RECOVERABLE (Alternative) │
+│ ───────────────── ──────────────────────── │
+│ • Network timeout • Missing data → try another │
+│ • Rate limit (429) • Format error → parse differ │
+│ • Service busy (503) • Partial failure → use partial │
+│ • Connection reset • Auth expired → re-auth │
+│ │
+│ PERMANENT (Report) CRITICAL (Escalate) │
+│ ────────────────── ─────────────────── │
+│ • Not found (404) • Security violation │
+│ • Permission denied (403) • Data corruption │
+│ • Invalid input (400) • System failure │
+│ • Resource deleted (410) • Unrecoverable state │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Retry Strategy
+
+For transient errors, use exponential backoff:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ EXPONENTIAL BACKOFF │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Attempt 1 ──▶ FAIL ──▶ Wait 1 second │
+│ │ │
+│ ▼ │
+│ Attempt 2 ──▶ FAIL ──▶ Wait 2 seconds │
+│ │ │
+│ ▼ │
+│ Attempt 3 ──▶ FAIL ──▶ Wait 4 seconds │
+│ │ │
+│ ▼ │
+│ Attempt 4 ──▶ FAIL ──▶ Report failure │
+│ │
+│ Formula: wait_time = 2^(attempt - 1) seconds │
+│ Max attempts: 4 (configurable) │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Code Mode Retry Implementation
+
+```python
+import json
+import time
+
+def with_retry(operation, max_attempts=4):
+ """Execute operation with exponential backoff retry."""
+ last_error = None
+
+ for attempt in range(1, max_attempts + 1):
+ try:
+ result = operation()
+ return {"success": True, "result": result, "attempts": attempt}
+ except Exception as e:
+ last_error = str(e)
+
+ # Check if error is retryable
+ if is_permanent_error(e):
+ return {
+ "success": False,
+ "error": last_error,
+ "error_type": "permanent",
+ "attempts": attempt
+ }
+
+ # Wait before retry (exponential backoff)
+ if attempt < max_attempts:
+ wait_time = 2 ** (attempt - 1)
+ time.sleep(wait_time)
+
+ return {
+ "success": False,
+ "error": last_error,
+ "error_type": "transient_exhausted",
+ "attempts": max_attempts
+ }
+
+def is_permanent_error(e):
+ """Check if error is permanent (should not retry)."""
+ error_msg = str(e).lower()
+ permanent_indicators = [
+ "not found", "404",
+ "permission denied", "403", "forbidden",
+ "invalid", "400", "bad request",
+ "unauthorized", "401"
+ ]
+ return any(indicator in error_msg for indicator in permanent_indicators)
+
+# Usage
+result = with_retry(lambda: risky_operation())
+print(json.dumps(result, indent=2))
+```
+
+## Alternative Approach Pattern
+
+When the primary approach fails, try alternatives:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ALTERNATIVE APPROACHES │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Primary: API call to service A │
+│ │ │
+│ ▼ │
+│ FAILED (service down) │
+│ │ │
+│ ▼ │
+│ Alternative 1: Try service B (backup API) │
+│ │ │
+│ ▼ │
+│ FAILED (rate limited) │
+│ │ │
+│ ▼ │
+│ Alternative 2: Use cached data │
+│ │ │
+│ ▼ │
+│ SUCCESS (stale but available) │
+│ │ │
+│ ▼ │
+│ Return with warning: "Data may be outdated" │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Self-Delegation for Retry
+
+Use delegation to retry with a different approach:
+
+```json
+{
+ "task": "Retry: Get weather data using alternative source",
+ "context": "Attempt: 2/3
+Error: Primary weather API timeout
+Previous approach: OpenWeatherMap API
+New approach: Try WeatherAPI.com or use cached forecast
+Original request: Weather for New York"
+}
+```
+
+## Graceful Degradation
+
+When full success isn't possible, return partial results:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ GRACEFUL DEGRADATION │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Request: "Get user profile with posts and followers" │
+│ │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
+│ │ Profile │ │ Posts │ │ Followers │ │
+│ │ SUCCESS │ │ FAILED │ │ SUCCESS │ │
+│ └─────────────┘ └─────────────┘ └─────────────┘ │
+│ │
+│ Response: │
+│ { │
+│ "profile": { ... }, // Full data │
+│ "posts": null, // Unavailable │
+│ "posts_error": "Service temporarily unavailable", │
+│ "followers": [ ... ], // Full data │
+│ "partial": true, // Indicates degraded response │
+│ "degraded_fields": ["posts"] │
+│ } │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Code Mode Graceful Degradation
+
+```python
+import json
+
+def fetch_user_data(user_id):
+ """Fetch user data with graceful degradation."""
+ result = {
+ "user_id": user_id,
+ "partial": False,
+ "errors": []
+ }
+
+ # Try to get profile (required)
+ try:
+ result["profile"] = get_profile(user_id)
+ except Exception as e:
+ # Profile is required - cannot degrade
+ return {
+ "success": False,
+ "error": f"Cannot fetch required profile: {e}"
+ }
+
+ # Try to get posts (optional, can degrade)
+ try:
+ result["posts"] = get_posts(user_id)
+ except Exception as e:
+ result["posts"] = None
+ result["errors"].append(f"posts: {e}")
+ result["partial"] = True
+
+ # Try to get followers (optional, can degrade)
+ try:
+ result["followers"] = get_followers(user_id)
+ except Exception as e:
+ result["followers"] = None
+ result["errors"].append(f"followers: {e}")
+ result["partial"] = True
+
+ return {"success": True, "data": result}
+
+# Simulated functions
+def get_profile(uid): return {"name": "John", "email": "[email protected]"}
+def get_posts(uid): raise Exception("Service unavailable")
+def get_followers(uid): return [{"id": 1, "name": "Jane"}]
+
+output = fetch_user_data("user_123")
+print(json.dumps(output, indent=2))
+```
+
+## Error Recovery in Agentic Loops
+
+When an iteration fails in an agentic loop:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ LOOP ERROR RECOVERY │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Iteration 2: FAILED │
+│ │ │
+│ ▼ │
+│ Classify Error │
+│ │ │
+│ ├──▶ Transient? ──▶ Retry same iteration │
+│ │ │
+│ ├──▶ Recoverable? ──▶ Try alternative approach │
+│ │ │
+│ └──▶ Permanent? ──▶ Skip or report │
+│ │
+│ Continue to Iteration 3 with updated context: │
+│ "Iteration 2 failed: [reason]. Proceeding with │
+│ partial results from Iteration 1." │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Delegation with Error Context
+
+```json
+{
+ "task": "Continue: Process remaining items (skip failed)",
+ "context": "Iteration: 3/5
+Progress: Processed items 1-5, item 3 failed (invalid format)
+State: Results for items [1,2,4,5] available
+Error handling: Skipping item 3, continuing with remaining
+Next: Process items 6-10"
+}
+```
+
+## Error Reporting Best Practices
+
+### What to Include
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ERROR REPORT STRUCTURE │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ 1. WHAT failed │
+│ "Failed to send WhatsApp message" │
+│ │
+│ 2. WHY it failed │
+│ "Recipient phone number not registered on WhatsApp" │
+│ │
+│ 3. WHAT was tried │
+│ "Attempted 3 times with exponential backoff" │
+│ │
+│ 4. WHAT can be done │
+│ "Try a different contact method (SMS, email) or │
+│ verify the phone number is correct" │
+│ │
+│ 5. PARTIAL results (if any) │
+│ "Message was prepared but not delivered" │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Example Error Response
+
+```json
+{
+ "success": false,
+ "error": {
+ "type": "delivery_failed",
+ "message": "Failed to send WhatsApp message",
+ "reason": "Recipient not on WhatsApp",
+ "attempts": 3,
+ "recovery_attempted": true,
+ "partial_result": {
+ "message_prepared": true,
+ "recipient_validated": false
+ }
+ },
+ "suggestions": [
+ "Verify the phone number format (+1234567890)",
+ "Try sending via SMS instead",
+ "Check if recipient has WhatsApp installed"
+ ]
+}
+```
+
+## Anti-Patterns to Avoid
+
+### 1. Silent Failures
+```
+// Never do this
+try:
+ result = risky_operation()
+except:
+ pass // Error swallowed silently
+
+// Always report
+try:
+ result = risky_operation()
+except Exception as e:
+ return {"success": False, "error": str(e)}
+```
+
+### 2. Infinite Retry
+```
+// Never do this
+while True:
+ try:
+ result = operation()
+ break
+ except:
+ continue // Infinite loop
+
+// Always limit attempts
+for attempt in range(MAX_ATTEMPTS):
+ ...
+```
+
+### 3. Retry Permanent Errors
+```
+// Never retry these
+- 404 Not Found
+- 403 Forbidden
+- 401 Unauthorized
+- 400 Bad Request
+
+// Only retry these
+- 429 Too Many Requests
+- 503 Service Unavailable
+- 504 Gateway Timeout
+- Connection errors
+```
+
+### 4. Lose Context on Error
+```
+// Never do this
+except Exception:
+ return "An error occurred"
+
+// Preserve context
+except Exception as e:
+ return f"Failed at step {step}: {e}. Progress: {progress}"
+```
diff --git a/server/skills/autonomous/multi-tool-orchestration-skill/SKILL.md b/server/skills/autonomous/multi-tool-orchestration-skill/SKILL.md
new file mode 100644
index 00000000..647c611a
--- /dev/null
+++ b/server/skills/autonomous/multi-tool-orchestration-skill/SKILL.md
@@ -0,0 +1,457 @@
+---
+name: multi-tool-orchestration-skill
+description: Coordinate multiple tools together for complex multi-step tasks
+allowed-tools: delegate_to_ai_agent python_code javascript_code web_search http_request calculator current_time
+metadata:
+ author: machina
+ version: "1.0"
+ category: autonomous
+ icon: "🔀"
+ color: "#6366F1"
+---
+# Multi-Tool Orchestration Pattern
+
+You are an agent skilled at coordinating multiple tools together to accomplish complex tasks that require combining different capabilities.
+
+## Why Multi-Tool Orchestration?
+
+Complex real-world tasks often require multiple tools working together:
+- **Data gathering** (web_search, http_request) + **Processing** (python_code) + **Delivery** (whatsapp_send)
+- **Time awareness** (current_time) + **Calculation** (calculator) + **Scheduling** (scheduler)
+- **Location** (gmaps) + **Communication** (social_send) + **Memory** (memory)
+
+## Orchestration Patterns
+
+### Pattern 1: Sequential Pipeline
+
+Tools execute in order, each passing results to the next:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ SEQUENTIAL PIPELINE │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ [web_search] ──▶ [python_code] ──▶ [whatsapp_send] │
+│ │ │ │ │
+│ │ │ │ │
+│ "Find stock "Calculate "Send summary │
+│ prices" average" to user" │
+│ │ │ │ │
+│ ▼ ▼ ▼ │
+│ Raw data ──────▶ Processed ──────▶ Delivered │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Example: Stock Price Alert
+
+**Task**: "Get the current prices of AAPL, GOOGL, and MSFT, calculate the average, and send me a WhatsApp message with the results"
+
+**Orchestration Steps:**
+
+1. **Gather Data** (web_search):
+```json
+{"tool": "web_search", "query": "AAPL GOOGL MSFT stock price today"}
+```
+
+2. **Process Data** (python_code):
+```python
+import json
+
+# Data from previous step
+prices = {"AAPL": 185.50, "GOOGL": 141.25, "MSFT": 378.90}
+
+# Calculate statistics
+average = sum(prices.values()) / len(prices)
+highest = max(prices.items(), key=lambda x: x[1])
+lowest = min(prices.items(), key=lambda x: x[1])
+
+output = {
+ "prices": prices,
+ "average": round(average, 2),
+ "highest": {"symbol": highest[0], "price": highest[1]},
+ "lowest": {"symbol": lowest[0], "price": lowest[1]},
+ "summary": f"Average: ${average:.2f} | High: {highest[0]} | Low: {lowest[0]}"
+}
+print(json.dumps(output, indent=2))
+```
+
+3. **Deliver Result** (whatsapp_send):
+```json
+{
+ "tool": "whatsapp_send",
+ "recipient": "user",
+ "message": "Stock Update:\n- AAPL: $185.50\n- GOOGL: $141.25\n- MSFT: $378.90\n\nAverage: $235.22"
+}
+```
+
+### Pattern 2: Parallel Gather, Sequential Process
+
+Gather data from multiple sources simultaneously, then process together:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ PARALLEL GATHER + SEQUENTIAL PROCESS │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ [web_search: weather] ──────┐ │
+│ │ │
+│ [web_search: news] ─────────┼──▶ [python_code] ──▶ Output │
+│ │ "Combine & │
+│ [current_time] ─────────────┘ Format" │
+│ │
+│ All three run independently, results combined │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Example: Daily Briefing
+
+**Task**: "Create a morning briefing with weather, top news, and today's schedule"
+
+**Orchestration:**
+
+```python
+import json
+from datetime import datetime
+
+# Results from parallel tool calls (simulated)
+weather_data = {"temp": 72, "condition": "Sunny", "high": 78, "low": 65}
+news_data = [
+ {"title": "Tech stocks rally", "source": "Reuters"},
+ {"title": "New AI breakthrough", "source": "TechCrunch"}
+]
+current_time = datetime.now()
+
+# Combine into briefing
+briefing = {
+ "date": current_time.strftime("%A, %B %d, %Y"),
+ "time": current_time.strftime("%I:%M %p"),
+ "weather": {
+ "summary": f"{weather_data['condition']}, {weather_data['temp']}F",
+ "range": f"High: {weather_data['high']}F, Low: {weather_data['low']}F"
+ },
+ "news": [f"- {n['title']} ({n['source']})" for n in news_data],
+ "formatted": None
+}
+
+# Create formatted output
+briefing["formatted"] = f"""
+Good Morning! {briefing['date']}
+
+WEATHER
+{briefing['weather']['summary']}
+{briefing['weather']['range']}
+
+TOP NEWS
+{chr(10).join(briefing['news'])}
+"""
+
+print(json.dumps(briefing, indent=2))
+```
+
+### Pattern 3: Conditional Branching
+
+Choose different tools based on intermediate results:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ CONDITIONAL BRANCHING │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ [initial_check] │
+│ │ │
+│ ┌───────────┼───────────┐ │
+│ ▼ ▼ ▼ │
+│ Condition A Condition B Condition C │
+│ │ │ │ │
+│ ▼ ▼ ▼ │
+│ [tool_A] [tool_B] [tool_C] │
+│ │ │ │ │
+│ └───────────┼───────────┘ │
+│ ▼ │
+│ [final_tool] │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Example: Smart Communication
+
+**Task**: "Contact John with the meeting update - use the best available channel"
+
+**Orchestration Logic:**
+```
+1. CHECK availability:
+ - Is John online on WhatsApp? → Use whatsapp_send
+ - Is John's email available? → Use email (via http_request)
+ - Neither? → Schedule reminder for later
+
+2. EXECUTE chosen channel
+
+3. CONFIRM delivery status
+```
+
+### Pattern 4: Iterative Refinement
+
+Use tool results to improve subsequent tool calls:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ITERATIVE REFINEMENT │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ [web_search v1] ──▶ [python_code: analyze] │
+│ │ │ │
+│ │ "Results incomplete" │
+│ │ │ │
+│ │ ▼ │
+│ │ [web_search v2] │
+│ │ (refined query) │
+│ │ │ │
+│ │ "Results better" │
+│ │ │ │
+│ └──────────────────────┼──▶ [python_code: combine] │
+│ │ │
+│ ▼ │
+│ Final Result │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Example: Research Task
+
+**Task**: "Find comprehensive information about quantum computing applications in finance"
+
+**Iteration 1:**
+```json
+{"tool": "web_search", "query": "quantum computing finance applications"}
+```
+Result: General overview, but missing specific use cases
+
+**Iteration 2 (refined):**
+```json
+{"tool": "web_search", "query": "quantum computing portfolio optimization risk analysis"}
+```
+Result: Specific applications found
+
+**Combine with Code:**
+```python
+import json
+
+# Results from both searches
+search_1 = ["Overview of quantum finance", "Major players"]
+search_2 = ["Portfolio optimization algorithms", "Risk modeling with qubits"]
+
+combined = {
+ "topic": "Quantum Computing in Finance",
+ "general": search_1,
+ "specific_applications": search_2,
+ "summary": "Quantum computing in finance focuses on portfolio optimization and risk analysis..."
+}
+print(json.dumps(combined, indent=2))
+```
+
+## Complex Multi-Tool Examples
+
+### Example 1: Travel Planning Assistant
+
+**Task**: "Plan a trip from New York to San Francisco next week, find hotels, and send me an itinerary"
+
+**Tools Used**: `current_time`, `web_search`, `python_code`, `whatsapp_send`
+
+**Orchestration:**
+
+```
+Step 1: Get current date (current_time)
+ ↓
+Step 2: Calculate "next week" dates (python_code)
+ ↓
+Step 3: Search for flights (web_search: "NYC to SFO flights [dates]")
+ ↓
+Step 4: Search for hotels (web_search: "San Francisco hotels [dates]")
+ ↓
+Step 5: Combine and format itinerary (python_code)
+ ↓
+Step 6: Send to user (whatsapp_send)
+```
+
+**Code for Step 5:**
+```python
+import json
+from datetime import datetime, timedelta
+
+# Inputs from previous steps
+today = datetime.now()
+trip_start = today + timedelta(days=7)
+trip_end = trip_start + timedelta(days=3)
+
+flights = [
+ {"airline": "United", "departure": "8:00 AM", "price": "$350"},
+ {"airline": "Delta", "departure": "11:30 AM", "price": "$380"}
+]
+
+hotels = [
+ {"name": "Marriott Union Square", "price": "$250/night", "rating": 4.5},
+ {"name": "Hilton Financial District", "price": "$280/night", "rating": 4.3}
+]
+
+itinerary = {
+ "trip": {
+ "from": "New York (JFK)",
+ "to": "San Francisco (SFO)",
+ "dates": f"{trip_start.strftime('%b %d')} - {trip_end.strftime('%b %d, %Y')}"
+ },
+ "recommended_flight": flights[0],
+ "recommended_hotel": hotels[0],
+ "estimated_total": "$1,100",
+ "formatted_message": f"""
+Travel Itinerary: NYC → SFO
+
+DATES
+{trip_start.strftime('%b %d')} - {trip_end.strftime('%b %d, %Y')}
+
+FLIGHT (Recommended)
+{flights[0]['airline']} - {flights[0]['departure']} - {flights[0]['price']}
+
+HOTEL (Recommended)
+{hotels[0]['name']}
+{hotels[0]['price']} | Rating: {hotels[0]['rating']}/5
+
+ESTIMATED TOTAL: $1,100
+"""
+}
+
+print(json.dumps(itinerary, indent=2))
+```
+
+### Example 2: Automated Report Generation
+
+**Task**: "Generate a weekly sales report with charts and email it to the team"
+
+**Tools Used**: `http_request` (API), `python_code`, `http_request` (email)
+
+**Orchestration:**
+
+```
+Step 1: Fetch sales data from API (http_request)
+ ↓
+Step 2: Process and analyze data (python_code)
+ ↓
+Step 3: Generate text summary (python_code)
+ ↓
+Step 4: Format as HTML report (python_code)
+ ↓
+Step 5: Send via email API (http_request)
+```
+
+### Example 3: Smart Home Automation
+
+**Task**: "When I get home, turn on the lights, set temperature to 72F, and play my evening playlist"
+
+**Tools Used**: `location`, `http_request` (smart home API), `python_code`
+
+**Orchestration:**
+
+```
+Step 1: Check current location (location tool)
+ ↓
+Step 2: Calculate distance to home (python_code)
+ ↓
+Step 3: If within 1 mile:
+ ├── Turn on lights (http_request to smart home API)
+ ├── Set thermostat (http_request to smart home API)
+ └── Start playlist (http_request to music API)
+ ↓
+Step 4: Confirm all actions (python_code)
+```
+
+## Orchestration with Delegation
+
+For complex multi-tool tasks, delegate sub-tasks to yourself:
+
+```json
+{
+ "task": "Continue: Execute delivery phase of travel planning",
+ "context": "Iteration: 3/4
+Previous: Gathered flight and hotel data
+Current state: Itinerary formatted and ready
+Data: {flight: United $350, hotel: Marriott $250/night}
+Next: Send itinerary via WhatsApp and confirm delivery"
+}
+```
+
+## Tool Combination Matrix
+
+| Task Type | Primary Tools | Supporting Tools |
+|-----------|--------------|------------------|
+| **Research** | web_search, http_request | python_code (analysis) |
+| **Calculation** | calculator, python_code | current_time |
+| **Communication** | whatsapp_send, http_request | python_code (formatting) |
+| **Scheduling** | current_time, calculator | python_code (date math) |
+| **Data Processing** | python_code, javascript_code | http_request (APIs) |
+| **Location-based** | gmaps, location | python_code, whatsapp_send |
+
+## Best Practices
+
+### 1. Plan Before Executing
+```
+Before calling tools, outline:
+1. What data do I need?
+2. What tools provide that data?
+3. What order should they run?
+4. How will results combine?
+```
+
+### 2. Minimize Tool Calls
+```
+BAD: web_search("AAPL price") → web_search("GOOGL price") → web_search("MSFT price")
+GOOD: web_search("AAPL GOOGL MSFT stock prices today")
+```
+
+### 3. Use Code for Complex Logic
+```
+Instead of multiple calculator calls:
+calculator(10 * 5) → calculator(50 + 20) → calculator(70 / 2)
+
+Use python_code:
+result = ((10 * 5) + 20) / 2 # Single execution
+```
+
+### 4. Pass Context Between Tools
+```
+Tool 1 output: {"temperature": 72, "unit": "F"}
+Tool 2 input: Use the temperature (72F) in the message
+```
+
+### 5. Handle Partial Failures
+```
+If tool 2 of 4 fails:
+- Continue with remaining tools if possible
+- Use partial data from successful tools
+- Report what succeeded and what failed
+```
+
+## Anti-Patterns
+
+### 1. Serial When Parallel is Possible
+```
+// Unnecessary waiting
+await web_search("weather")
+await web_search("news") // Could run in parallel
+await web_search("stocks") // Could run in parallel
+```
+
+### 2. Over-Orchestration
+```
+// Don't use 5 tools when 1 suffices
+Task: "What's 2 + 2?"
+BAD: current_time → python_code → calculator → format → return
+GOOD: calculator(2 + 2) or just respond "4"
+```
+
+### 3. Ignoring Tool Results
+```
+// Always use the actual results
+BAD: Call web_search, ignore result, make up answer
+GOOD: Call web_search, process result, return based on actual data
+```
diff --git a/server/skills/autonomous/progressive-discovery-skill/SKILL.md b/server/skills/autonomous/progressive-discovery-skill/SKILL.md
new file mode 100644
index 00000000..c622aa35
--- /dev/null
+++ b/server/skills/autonomous/progressive-discovery-skill/SKILL.md
@@ -0,0 +1,223 @@
+---
+name: progressive-discovery-skill
+description: Discover and load tools progressively as needed (reduces token overhead)
+allowed-tools: delegate_to_ai_agent check_delegated_tasks
+metadata:
+ author: machina
+ version: "1.0"
+ category: autonomous
+ icon: "🔍"
+ color: "#F59E0B"
+---
+# Progressive Tool Discovery
+
+You are an agent that discovers and uses capabilities progressively as needed, rather than loading everything upfront.
+
+## Why Progressive Discovery?
+
+Loading all tools at start creates:
+- **Token overhead**: 150,000+ tokens for tool definitions
+- **Context pollution**: Irrelevant tools confuse the LLM
+- **Slower responses**: More tokens = more processing time
+
+Progressive discovery provides:
+- **98.7% token savings** (Anthropic MCP research)
+- **Focused context**: Only relevant tools loaded
+- **Better decisions**: Less noise, clearer choices
+
+## Discovery Pattern
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ PROGRESSIVE DISCOVERY │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ 1. START with minimal context │
+│ │ │
+│ ▼ │
+│ 2. IDENTIFY what capability is needed │
+│ │ │
+│ ▼ │
+│ 3. CHECK what tools/agents are connected │
+│ │ │
+│ ├──▶ Tool exists? ──▶ USE it directly │
+│ │ │
+│ └──▶ Specialized agent exists? ──▶ DELEGATE to it │
+│ │
+│ 4. EXECUTE with focused context │
+│ │ │
+│ ▼ │
+│ 5. RETURN result (don't load more than needed) │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Available Specialized Agents
+
+Check your connected tools - you may have access to these specialized agents:
+
+| Agent | Capabilities | When to Delegate |
+|-------|--------------|------------------|
+| `android_agent` | Device control, apps, sensors | Android device tasks |
+| `coding_agent` | Python/JavaScript execution | Code computation |
+| `web_agent` | Web scraping, HTTP requests | Internet data |
+| `task_agent` | Scheduling, timers, cron | Time-based tasks |
+| `social_agent` | WhatsApp, messaging | Communication |
+| `travel_agent` | Maps, locations, directions | Travel planning |
+
+## Discovery Examples
+
+### Example 1: User asks "What's the battery level?"
+
+**Without Progressive Discovery** (wasteful):
+```
+Load ALL tools (calculator, web_search, whatsapp, android, maps, code, ...)
+Parse user request
+Find that android tool is needed
+Execute battery check
+```
+
+**With Progressive Discovery** (efficient):
+```
+1. IDENTIFY: This needs Android device access
+2. CHECK: Is android_agent or battery tool connected?
+3. YES → Delegate: "Check battery level"
+4. RETURN: Battery at 75%, charging
+```
+
+### Example 2: User asks "Calculate compound interest for $10,000 at 5% for 10 years"
+
+**Discovery Process:**
+```
+1. IDENTIFY: This is a mathematical calculation
+2. CHECK: Do I have python_code or calculator tool?
+
+ IF python_code connected:
+ Use Code Mode for complex calculation
+
+ ELIF calculator connected:
+ Use calculator for simple operations
+
+ ELSE:
+ Report: "I need a code executor or calculator to compute this"
+```
+
+### Example 3: User asks "Send my location to John on WhatsApp"
+
+**Discovery Process:**
+```
+1. IDENTIFY: Needs location + messaging
+2. CHECK: What's connected?
+
+ Step A - Get location:
+ IF location tool connected → Use directly
+ ELIF android_agent connected → Delegate location request
+ ELSE → Ask user for location
+
+ Step B - Send message:
+ IF whatsapp_send connected → Use directly
+ ELIF social_agent connected → Delegate message
+ ELSE → Report: "WhatsApp not available"
+```
+
+## Delegation Pattern
+
+When delegating to a specialized agent:
+
+```json
+{
+ "task": "Specific task description",
+ "context": "Relevant context only (not everything)"
+}
+```
+
+**Good Context** (focused):
+```json
+{
+ "task": "Get current GPS coordinates",
+ "context": "User needs their location for a WhatsApp message"
+}
+```
+
+**Bad Context** (bloated):
+```json
+{
+ "task": "Get current GPS coordinates",
+ "context": "Full conversation history... user preferences... all previous results... system info..."
+}
+```
+
+## Capability Check Pattern
+
+Before attempting an action, verify the capability exists:
+
+```
+IF task requires capability X:
+
+ IF direct_tool_for_X is connected:
+ → Use tool directly (fastest)
+
+ ELIF specialized_agent_for_X is connected:
+ → Delegate to agent (handles complexity)
+
+ ELSE:
+ → Report: "This capability is not available"
+ → Suggest: "Connect [tool/agent name] to enable this"
+```
+
+## Anti-Patterns to Avoid
+
+### 1. Loading Everything Upfront
+```
+❌ "Let me check all my tools: calculator, web_search, whatsapp,
+ android, maps, code, http, scheduler, memory..."
+
+✓ "To answer this, I need [specific capability]"
+```
+
+### 2. Delegating Without Checking
+```
+❌ Immediately delegate to android_agent without checking if connected
+
+✓ Check connected tools first, then delegate if available
+```
+
+### 3. Over-Explaining Capabilities
+```
+❌ "I have access to many tools including... [lists everything]"
+
+✓ "I can help with that. Let me [specific action]."
+```
+
+### 4. Redundant Delegation
+```
+❌ Delegate "calculate 2+2" to coding_agent
+
+✓ Simple math can be done directly or with calculator tool
+```
+
+## Integration with Agentic Loop
+
+Progressive Discovery works with the Agentic Loop pattern:
+
+```
+OBSERVE: What does the user need?
+ ↓
+THINK: What capability is required?
+ ↓
+DISCOVER: Is that capability connected?
+ ↓
+ACT: Use tool directly OR delegate to agent
+ ↓
+REFLECT: Did it work?
+ ↓
+DECIDE: Complete or discover next capability
+```
+
+## Best Practices
+
+1. **Start minimal** - Don't enumerate all tools at the start
+2. **Discover on demand** - Only check for capabilities when needed
+3. **Prefer direct tools** - Use connected tools before delegating
+4. **Focused delegation** - Pass only relevant context to agents
+5. **Report gaps clearly** - If capability missing, say what's needed