Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat: Add memory compaction, token tracking, and autonomous agent skills
trohitg3d7e2673179e
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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### Overviewdiff --git a/client/src/components/parameterPanel/MiddleSection.tsx b/client/src/components/parameterPanel/MiddleSection.tsxindex 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 handlerconst handleClearMemory = async () => {setIsProcessing(true);@@ -152,7 +167,63 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({// State for Master Skill parametersconst [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 nodesuseEffect(() => {@@ -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.tsindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 approachesdiff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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.pyindex aa1f809a..a8501442 100644--- a/server/core/config.py+++ b/server/core/config.py@@ -109,6 +109,10 @@ class Settings(BaseSettings):# Feature Togglesws_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.pyindex c995037b..84d2ddc2 100644--- a/server/core/container.py+++ b/server/core/container.py@@ -14,6 +14,7 @@ from services.text import TextServicefrom services.android_service import AndroidServicefrom services.user_auth import UserAuthServicefrom services.temporal import TemporalClientWrapper+from services.compaction import init_compaction_serviceclass 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.pyindex 17b9bed7..e7b4949a 100644--- a/server/core/database.py+++ b/server/core/database.py@@ -9,7 +9,11 @@ from sqlalchemy import text, funcfrom contextlib import asynccontextmanagerfrom 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 alternativefrom models.auth import User # Import User model to ensure table creationfrom 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 filediff --git a/server/main.py b/server/main.pyindex 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 reportingset_startup_time()diff --git a/server/models/database.py b/server/models/database.pyindex 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 filediff --git a/server/routers/websocket.py b/server/routers/websocket.pyindex 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 Pathfrom 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.pyindex 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 metadataerror_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-minireturn 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 validationif 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 DBwindow_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 DBwindow_size = memory_data.get('window_size', 10)diff --git a/server/services/compaction.py b/server/services/compaction.pynew file mode 100644index 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 _servicediff --git a/server/skills/autonomous/agentic-loop-skill/SKILL.md b/server/skills/autonomous/agentic-loop-skill/SKILL.mdnew file mode 100644index 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 goaldiff --git a/server/skills/autonomous/code-mode-skill/SKILL.md b/server/skills/autonomous/code-mode-skill/SKILL.mdnew file mode 100644index 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 usersdiff --git a/server/skills/autonomous/error-recovery-skill/SKILL.md b/server/skills/autonomous/error-recovery-skill/SKILL.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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