agentic-loop-upgrade

Enhanced agentic loop with planning, parallel execution, confidence gates, semantic error recovery, and observable state machine. Includes Mode dashboard UI for easy configuration.

# Enhanced Agentic Loop Skill

A comprehensive upgrade to OpenClaw's agentic capabilities with persistent state, automatic planning, approval gates, retry logic, context management, checkpointing, knowledge graph auto-injection, and channel-aware plan rendering.

> 📋 **Security review?** See [SECURITY.md](./SECURITY.md) for a complete trust and capability audit document including network activity, file write scope, credential handling, and rollback instructions.

## Security & Trust Summary

| Property | Value |
|---|---|
| Outbound network | LLM provider only (inherited from host) |
| Telemetry / phone-home | ❌ None |
| System prompt modification | ✅ Additive-only (appends plan status; never replaces core prompt) |
| Runner wrapping | ✅ Transparent (original runner always called; interceptions logged) |
| Credential storage | ❌ None (inherits host agent auth, stores nothing new) |
| Persistence | Local `~/.openclaw/` only |
| Enabled by default | ❌ No — explicit opt-in required |
| Approval gates default | ✅ On for high/critical risk operations |

## Status: ✅ Active (v2.3.0)

All components are integrated and working.

| Component | Status |
|-----------|--------|
| Mode Dashboard UI | ✅ Working |
| Configuration System | ✅ Working |
| Hook/Wrapper Integration | ✅ Working |
| State Machine | ✅ Working |
| Planning Layer | ✅ Working |
| Parallel Execution | ✅ Working |
| Confidence Gates | ✅ Working |
| Error Recovery | ✅ Working |
| Checkpointing | ✅ Working |
| Memory Auto-Inject | ✅ Working (v2) |
| Discord Plan Rendering | ✅ Working (v2) |

## Features

### 1. Persistent Plan State
Plans survive across conversation turns. The agent knows where it left off.

```typescript
import { getStateManager } from "@openclaw/enhanced-loop";

const state = getStateManager();
await state.init(sessionId);

// Plan persists in ~/.openclaw/agent-state/{sessionId}.json
state.setPlan(plan);
state.completeStep("step_1", "Files created");
const progress = state.getProgress(); // { completed: 1, total: 5, percent: 20 }
```

### 2. Automatic Step Completion Detection
Analyzes tool results to determine if plan steps are complete.

```typescript
import { createStepTracker } from "@openclaw/enhanced-loop";

const tracker = createStepTracker(stateManager);

// After each tool execution
const analysis = await tracker.analyzeToolResult(tool, result);
if (analysis.isComplete) {
  console.log(`Step done: ${analysis.suggestedResult}`);
}
```

### 3. Tool Approval Gates with Timeout
Risky operations pause for human approval, but auto-proceed after N seconds.

```typescript
import { getApprovalGate } from "@openclaw/enhanced-loop";

const gate = getApprovalGate({
  enabled: true,
  timeoutMs: 15000, // 15 seconds to respond
  requireApprovalFor: ["high", "critical"],
  onApprovalNeeded: (request) => {
    // Notify user: "⚠️ Approve rm -rf? Auto-proceeding in 15s..."
  },
});

// Before risky tool execution
if (gate.requiresApproval(tool)) {
  const result = await gate.requestApproval(tool);
  if (!result.proceed) {
    return { blocked: true, reason: result.request.riskReason };
  }
}

// User can respond with:
gate.approve(requestId);  // Allow it
gate.deny(requestId);     // Block it
// Or wait for timeout → auto-proceeds
```

**Risk Levels:**
- `low`: Read operations (auto-approved)
- `medium`: Write/Edit, safe exec
- `high`: Messages, browser actions, git push
- `critical`: rm -rf, database drops, format commands

### 4. Automatic Retry with Alternatives
Failed tools get diagnosed and retried with modified approaches.

```typescript
import { createRetryEngine } from "@openclaw/enhanced-loop";

const retry = createRetryEngine({
  enabled: true,
  maxAttempts: 3,
  retryDelayMs: 1000,
});

const result = await retry.executeWithRetry(tool, executor);
// Automatically:
// - Diagnoses errors (permission, network, not_found, etc.)
// - Applies fixes (add sudo, increase timeout, etc.)
// - Retries with exponential backoff
```

### 5. Context Summarization
Automatically summarizes old messages when context grows long.

```typescript
import { createContextSummarizer } from "@openclaw/enhanced-loop";

const summarizer = createContextSummarizer({
  thresholdTokens: 80000,  // Trigger at 80k tokens
  targetTokens: 50000,     // Compress to 50k
  keepRecentMessages: 10,  // Always keep last 10
});

if (summarizer.needsSummarization(messages)) {
  const result = await summarizer.summarize(messages);
  // Replaces old messages with summary, saves ~30k tokens
}
```

### 6. Checkpoint/Restore
Save and resume long-running tasks across sessions.

```typescript
import { getCheckpointManager } from "@openclaw/enhanced-loop";

const checkpoints = getCheckpointManager();

// Create checkpoint
const ckpt = await checkpoints.createCheckpoint(state, {
  description: "After step 3",
  trigger: "manual",
});

// Later: check for incomplete work
const incomplete = await checkpoints.hasIncompleteWork(sessionId);
if (incomplete.hasWork) {
  console.log(incomplete.description);
  // "Incomplete task: Build website (3/6 steps, paused 2.5h ago)"
}

// Resume
const restored = await checkpoints.restore(sessionId);
// Injects context: "Resuming from checkpoint... [plan status]"
```

### 7. Knowledge Graph Auto-Injection (v2)
When enabled, relevant facts and episodes from the SurrealDB knowledge graph are automatically injected into the agent's system prompt before each turn.

```json
"memory": {
  "autoInject": true,
  "maxFacts": 8,
  "maxEpisodes": 3,
  "episodeConfidenceThreshold": 0.9,
  "includeRelations": true
}
```

Injected context appears as `## Semantic Memory` and `## Episodic Memory` blocks in the system prompt. Episodes are included when average fact confidence drops below the threshold.

### 8. Channel-Aware Plan Rendering (v2)
`:::plan` blocks are automatically transformed per channel:
- **Webchat**: Rendered as styled HTML cards with progress bars and checkmarks
- **Discord**: Stripped and replaced with emoji checklists (Discord doesn't support custom HTML)
- **Other channels**: Raw plan blocks passed through for channel-specific handling

Discord example output:
```
**Progress (2/5)**
✅ Gather requirements
🔄 Build the website
⬜ Deploy to hosting
⬜ Configure DNS
⬜ Final testing
```

## Unified Orchestrator

The recommended way to use all features together:

```typescript
import { createOrchestrator } from "@openclaw/enhanced-loop";

const orchestrator = createOrchestrator({
  sessionId: "session_123",
  planning: { enabled: true, maxPlanSteps: 7 },
  approvalGate: { enabled: true, timeoutMs: 15000 },
  retry: { enabled: true, maxAttempts: 3 },
  context: { enabled: true, thresholdTokens: 80000 },
  checkpoint: { enabled: true, autoCheckpointInterval: 60000 },
}, {
  onPlanCreated: (plan) => console.log("Plan:", plan.goal),
  onStepCompleted: (id, result) => console.log("✓", result),
  onApprovalNeeded: (req) => notifyUser(req),
  onCheckpointCreated: (id) => console.log("📍 Checkpoint:", id),
});

// Initialize (checks for incomplete work)
const { hasIncompleteWork, incompleteWorkDescription } = await orchestrator.init();

// Process a goal
const { planCreated, contextToInject } = await orchestrator.processGoal(
  "Build a REST API with authentication"
);

// Execute tools with all enhancements
const result = await orchestrator.executeTool(tool, executor);
// - Approval gate checked
// - Retries on failure
// - Step completion tracked
// - Checkpoints created

// Get status for display
const status = orchestrator.getStatus();
// { hasPlan: true, progress: { completed: 2, total: 5, percent: 40 }, ... }
```

## Mode Dashboard Integration

The skill includes a Mode tab for the OpenClaw Dashboard:

**Location:** Agent > Mode

**Features:**
- Toggle between Core Loop and Enhanced Loop
- Configure all settings visually
- Select orchestrator model from the OpenClaw model catalog (for cost control)
- Real-time configuration preview

## OpenClaw Integration

The skill integrates via the enhanced-loo