Architecture

PORA Loop

The Plan-Observe-Reason-Act loop is the core execution cycle:

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  Plan   │───▶│ Observe │───▶│ Reason  │───▶│   Act   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     ▲                                              │
     └──────────────────────────────────────────────┘

1. Plan: LLM generates a TodoList based on task
2. Act: Executor walks TodoList, PORALoop executes each step
3. Observe: Tool result is observed
4. Reason: LLM decides retry or proceed

Key Files

• packages/core/src/runtime/pora-loop.ts — single-step execution with retry logic
• packages/core/src/runtime/executor.ts — walks TodoList, delegates to PORALoop
• packages/core/src/runtime/planner.ts — LLM-driven TODO generation
• packages/core/src/runtime/agent-runtime.ts — orchestrates plan/act modes, session lifecycle

Retry Logic

Max 2 retries for transient errors matching:

/(timeout|temporar|network|rate limit|econn|unavailable)/i

3-Phase Compaction

When conversation exceeds keepRecentMessages, compaction runs:

Phase 0: clearThinkingBlocks

Removes old assistant thinking blocks, keeps only the most recent N.

Phase 1: pruneToolResults

Truncates old large tool results (>8KB), protects recent turns.

Phase 2: LLM Summarize

Produces 5-section structured summary:

• Task Overview

• Current State

• Key Discoveries

• Next Steps

• Context to Preserve

VITAL Protection

Critical content survives truncation via markers:

• [VITAL] in content
• #vital or #critical tags
• ERROR: or WARNING: prefixes
• [!] alert markers

Branching System

Runtime modes for different execution contexts:

const branch = await runtime.createBranch({
  mode: 'container',
  target: { container: { image: 'node:20-alpine' } },
  description: 'Build in isolated environment'
});

Key Files

• packages/core/src/runtime/branching/branch-manager.ts — lifecycle management
• packages/core/src/runtime/branching/executors/ — mode-specific executors
• packages/core/src/runtime/tools/runtime-switch-tool.ts — LLM-callable tool