Agent Sdk

Agent SDK — Checkpoint Manager, Session Forking, and Query Control

Purpose

The Agent SDK provides three core capabilities for Claude Flow v2: a checkpoint manager for git-like session checkpointing using Claude Code SDK message UUIDs, a parallel swarm executor using session forking for 10-20x faster agent spawning, and a real-time query controller for pause/resume/terminate of running agents.

1. Checkpoint Manager

Git-like checkpointing using actual SDK message UUIDs as checkpoint identifiers.

Create a Checkpoint Manager

import { RealCheckpointManager, checkpointManager } from './sdk/checkpoint-manager';

const manager = new RealCheckpointManager({
  persistPath: '.claude-flow/checkpoints',   // Default
  autoCheckpointInterval: 10,                 // Every 10 messages
  maxCheckpoints: 50,                         // Per session limit
});

// Or use the singleton
import { checkpointManager } from './sdk/checkpoint-manager';

Track a Session

await manager.trackSession(sessionId, queryGenerator, autoCheckpoint);
// Monitors SDK messages from the query generator
// Emits 'message:tracked' for each message
// Auto-checkpoints every N messages if enabled

Create Checkpoint

const checkpointId = await manager.createCheckpoint(sessionId, 'Before refactoring');
// Checkpoint ID = last message UUID from the SDK
// Stores: messageCount, totalTokens, filesModified
// Persisted to: .claude-flow/checkpoints/{id}.json
// Enforces maxCheckpoints limit per session

Rollback to Checkpoint

const rolledBackQuery = await manager.rollbackToCheckpoint(checkpointId, 'Continue from here');
// Uses SDK's resumeSessionAt to rewind to exact message UUID
// Returns a new Query that resumes from that point
// Internally calls: query({ prompt, options: { resume: sessionId, resumeSessionAt: checkpointId } })

List Checkpoints

const checkpoints = manager.listCheckpoints(sessionId);
// Returns Checkpoint[] sorted by timestamp (newest first)
// Each: { id, sessionId, description, timestamp, messageCount, totalTokens, filesModified }

Checkpoint Diff

const diff = manager.getCheckpointDiff(fromId, toId);
// { messagesDiff, tokensDiff, filesAdded, filesRemoved }

Delete Checkpoint

await manager.deleteCheckpoint(checkpointId);
// Removes from memory and disk

Persistence

// Load all checkpoints from disk (after restart)
const loaded = await manager.loadAllCheckpoints();

// List persisted checkpoint IDs
const ids = await manager.listPersistedCheckpoints();

Checkpoint Events

• checkpoint:created — New checkpoint created
• checkpoint:rollback — Rolled back to checkpoint
• checkpoint:deleted — Checkpoint deleted
• checkpoint:limit_enforced — Old checkpoints pruned
• message:tracked — SDK message tracked
• persist:saved / persist:loaded / persist:deleted / persist:error

2. Session Forking (Parallel Swarm Executor)

Spawns multiple agents in parallel using SDK session forking for 10-20x performance gain.

import { ParallelSwarmExecutor } from './sdk/session-forking';

const executor = new ParallelSwarmExecutor();

Spawn Parallel Agents

const result = await executor.spawnParallelAgents(
  [
    { agentId: 'coder-1', agentType: 'implementation', task: 'Build auth module', priority: 'high' },
    { agentId: 'coder-2', agentType: 'implementation', task: 'Build API layer', priority: 'high' },
    { agentId: 'tester-1', agentType: 'testing', task: 'Write test suite', priority: 'medium' },
  ],
  {
    maxParallelAgents: 10,          // Concurrency limit
    baseSessionId: 'base-session',  // Fork from this session
    resumeFromMessage: 'msg-uuid',  // Resume from specific message
    sharedMemory: true,
    timeout: 300000,                // 5 minutes
    model: 'claude-sonnet-4',
  }
);

// result:
// {
//   success: boolean,
//   agentResults: Map<agentId, { output, messages, duration, status, error }>,
//   totalDuration: number,
//   failedAgents: string[],
//   successfulAgents: string[],
// }

Execution Protocol

1. Agents sorted by priority: critical > high > medium > low
2. Created in batches (respecting maxParallelAgents)
3. Each agent spawned with forkSession: true in SDK options
4. All agents in a batch execute concurrently via Promise.allSettled
5. Results collected and metrics updated

SDK Integration

Each forked agent session uses:

const sdkOptions: Options = {
  forkSession: true,               // KEY: Enable session forking
  resume: baseSessionId,           // Resume from base session
  resumeSessionAt: resumeMessage,  // Resume from specific message
  model: 'claude-sonnet-4',
  maxTurns: 50,
};

Events

• parallel:complete — All agents finished

3. Real-Time Query Controller

Control running agent queries dynamically: pause, resume, terminate, and change configuration mid-execution.

import { RealTimeQueryController } from './sdk/query-control';

const controller = new RealTimeQueryController({
  allowPause: true,
  allowModelChange: true,
  allowPermissionChange: true,
  monitoringInterval: 1000,        // Status check every 1 second
});

Register Query for Control

const controlled = controller.registerQuery(queryId, agentId, query);
// Starts monitoring, emits 'query:registered'

Pause a Query

await controller.pauseQuery(queryId, 'Manual pause for review');
// Calls query.interrupt() via SDK
// Sets status to 'paused', records pausedAt timestamp

Resume a Query

await controller.resumeQuery(queryId);
// Marks as running, records resumedAt timestamp

Terminate a Query

await controller.terminateQuery(queryId, 'Task completed');
// Calls query.interrupt() via SDK
// Sets status to 'terminated', stops monitoring

Controlled Query State

interface ControlledQuery {
  queryId: string;
  agentId: string;
  query: Query;
  status: 'running' | 'paused' | 'terminated' | 'completed' | 'failed';
  isPaused: boolean;
  canControl: boolean;
  startTime: number;
  pausedAt?: number;
  resumedAt?: number;
  terminatedAt?: number;
  currentModel?: string;
  permissionMode?: PermissionMode;
}

Events

• query:registered — Query registered for control
• query:paused — Query paused
• query:resumed — Query resumed
• query:terminated — Query terminated

Additional Modules

• sdk-config.ts — SDK configuration management
• compatibility-layer.ts — V2/V3 compatibility bridging
• in-process-mcp.ts — In-process MCP server implementation
• claude-flow-mcp-integration.ts — MCP integration utilities
• validation-demo.ts — Validation demonstration