Breakpoints & Checkpoints

import { createAgentOrchestrator } from '@directive-run/ai';
import type { BreakpointConfig } from '@directive-run/ai';

const orchestrator = createAgentOrchestrator({
  runner,
  debug: true,

  breakpoints: [
    { type: 'pre_agent_run', label: 'Before agent runs' },
    {
      type: 'pre_output_guardrails',
      when: (context) => context.input.includes('sensitive'),
      label: 'Sensitive content check',
    },
  ],

  onBreakpoint: (request) => {
    console.log(`Breakpoint hit: ${request.type} for ${request.agentId}`);
    console.log(`Input: ${request.input}`);
  },

  breakpointTimeoutMs: 300000,  // 5 minutes (default)
});

// List pending breakpoints
const pending = orchestrator.getPendingBreakpoints();

for (const bp of pending) {
  console.log(`${bp.id}: ${bp.type} – ${bp.label}`);
}

// Resume with optional modifications
orchestrator.resumeBreakpoint(bp.id, {
  input: 'Modified input',  // Override the input
  skip: false,               // Set to true to skip the step entirely
});

// Cancel a breakpoint (aborts the operation)
orchestrator.cancelBreakpoint(bp.id, 'User cancelled');

interface BreakpointConfig<T extends BreakpointType = BreakpointType> {
  type: T;
  when?: (context: BreakpointContext) => boolean;  // Conditional – fires only when true
  label?: string;                                   // Human-readable label
}

interface BreakpointContext {
  agentId: string;
  agentName: string;
  input: string;
  state: Record<string, unknown>;
  breakpointType: BreakpointType;
  patternId?: string;     // Set during pattern execution
  handoff?: HandoffRequest;  // Set during handoffs
}

interface BreakpointRequest {
  id: string;
  type: BreakpointType;
  agentId: string;
  input: string;
  label?: string;
  requestedAt: number;
}

interface BreakpointModifications {
  input?: string;   // Override the agent input
  skip?: boolean;   // Skip this step entirely
}

import { createMultiAgentOrchestrator } from '@directive-run/ai';

const orchestrator = createMultiAgentOrchestrator({
  runner,
  agents: { researcher: { agent: researcher }, writer: { agent: writer } },
  breakpoints: [
    { type: 'pre_handoff', agentIds: ['researcher'] },
    { type: 'pre_pattern_step', patternIds: ['pipeline'] },
  ],
  onBreakpoint: (req) => console.log('Breakpoint:', req.type, req.id),
});

import { matchBreakpoint } from '@directive-run/ai';

const match = matchBreakpoint(breakpoints, 'pre_agent_run', context);
if (match) {
  console.log(`Matched: ${match.label}`);
}

const checkpoint = await orchestrator.checkpoint({ label: 'Before experiment' });

console.log(checkpoint.id);         // Unique ID
console.log(checkpoint.createdAt);  // Timestamp
console.log(checkpoint.label);      // 'Before experiment'

orchestrator.restore(checkpoint, {
  restoreTimeline: true,  // Also restore timeline events (default: true)
});

interface Checkpoint {
  version: 1;
  id: string;
  createdAt: number;
  label?: string;
  systemExport: string;        // Serialized Directive System state
  timelineExport: string;      // Serialized timeline events
  localState: CheckpointLocalState;
  memoryExport: string | null; // Serialized memory state
  orchestratorType: 'single' | 'multi';
}

interface MultiAgentCheckpointLocalState {
  type: 'multi';
  globalTokenCount: number;
  globalStatus: string;
  agentStates: Record<string, unknown>;
  handoffCounter: number;
  pendingHandoffs: HandoffRequest[];
  handoffResults: HandoffResult[];
  roundRobinCounters: Record<string, number>;
}

import { InMemoryCheckpointStore } from '@directive-run/ai';
import type { CheckpointStore } from '@directive-run/ai';

const store = new InMemoryCheckpointStore({ maxCheckpoints: 50 });

// Save
await store.save(checkpoint);

// Load
const loaded = await store.load(checkpoint.id);

// List all (returns { id, label, createdAt } summaries)
const all = await store.list();

// Delete
await store.delete(checkpoint.id);

// Clear all
await store.clear();

const store: CheckpointStore = {
  save: async (checkpoint) => {
    await db.insert('checkpoints', checkpoint);

    return checkpoint.id;
  },
  load: async (id) => {
    return await db.findOne('checkpoints', { id });
  },
  list: async () => {
    return await db.find('checkpoints', {}, { select: ['id', 'label', 'createdAt'] });
  },
  delete: async (id) => {
    const deleted = await db.delete('checkpoints', { id });

    return deleted > 0;
  },
  clear: async () => {
    await db.deleteAll('checkpoints');
  },
};

import { validateCheckpoint, createCheckpointId } from '@directive-run/ai';

// Type guard with prototype pollution protection
if (validateCheckpoint(data)) {
  orchestrator.restore(data);
}

// Generate a unique checkpoint ID
const id = createCheckpointId();

const breakpointEvents = timeline.getEventsByType('breakpoint_hit');
const resumeEvents = timeline.getEventsByType('breakpoint_resumed');