# Agent Sdk

> Agent SDK with checkpoint manager, session forking for parallel execution, and real-time query control

- Skill: `jrennie99-glitch/agent-sdk` (Agent Skill)
- Install (CLI): `npx skillmds add jrennie99-glitch/agent-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/agent-sdk/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

### Checkpoint Diff

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

### Delete Checkpoint

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

### Persistence

```typescript
// 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.

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

const executor = new ParallelSwarmExecutor();
```

### Spawn Parallel Agents

```typescript
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:

```typescript
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.

```typescript
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

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

### Pause a Query

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

### Resume a Query

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

### Terminate a Query

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

### Controlled Query State

```typescript
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