Routine Execution

Task A → validate → clear conversation → Task B → validate → clear → Task C → done
           ↓                                ↓
    memory persists ──────────────→ memory persists

import {
  Connector, ConnectorTools, Services, tools, Vendor, executeRoutine,
  createRoutineDefinition,
} from 'oneringai';

// 1. Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

Connector.create({
  name: 'serper-main', serviceType: Services.Serper,
  auth: { type: 'api_key', apiKey: process.env.SERPER_API_KEY! },
  baseURL: 'https://google.serper.dev',
});
const searchTools = ConnectorTools.for('serper-main');

// 2. Define a routine
const routine = createRoutineDefinition({
  name: 'Research Report',
  description: 'Research a topic and write a report',
  instructions: 'You are a research assistant. Be thorough and cite sources.',
  tasks: [
    {
      name: 'Research',
      description: 'Search for information about quantum computing advances in 2026',
      expectedOutput: 'A summary of key findings stored in memory',
      suggestedTools: ['serper-main_web_search', 'web_fetch'],
      validation: {
        skipReflection: false, // Reflection is opt-in; not a host completion proof.
        completionCriteria: [
          'At least 3 distinct sources were found',
          'Key findings were stored in memory',
        ],
      },
    },
    {
      name: 'Write Report',
      description: 'Write a structured report based on the research findings',
      expectedOutput: 'A markdown report with introduction, findings, and conclusion',
      dependsOn: ['Research'],
      validation: {
        skipReflection: false, // Reflection is opt-in; not a host completion proof.
        completionCriteria: [
          'Report has an introduction, findings section, and conclusion',
          'Report cites specific sources from the research',
        ],
      },
    },
  ],
});

// 3. Execute
const execution = await executeRoutine({
  definition: routine,
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...searchTools, tools.webFetch],
  onTaskComplete: (task) => console.log(`Done: ${task.name}`),
  onTaskFailed: (task) => console.error(`Failed: ${task.name}`),
});

console.log(execution.status);   // 'completed' | 'failed'
console.log(execution.progress); // 100

interface RoutineDefinition {
  name: string;                    // Routine name
  description: string;             // Human-readable description (required)
  instructions?: string;           // System prompt for the agent
  requiredTools?: string[];        // Tool names that must be available
  requiredPlugins?: string[];      // Plugin names that must be registered

  tasks: TaskInput[];              // Array of task definitions (TaskDefinition does not exist)

  concurrency?: {
    maxParallelTasks: number;      // Required if concurrency is set; runner executes tasks sequentially regardless
    strategy: 'fifo' | 'priority' | 'shortest-first';
    failureMode?: 'fail-fast' | 'continue' | 'fail-all';  // Default: 'fail-fast'
  };
}

interface TaskInput {
  name: string;                    // Task name (used as ID)
  description: string;             // What the agent should do
  expectedOutput?: string;         // What success looks like
  suggestedTools?: string[];       // Hint to the agent about useful tools
  dependsOn?: string[];            // Task names this depends on
  maxAttempts?: number;            // Max retry attempts (default: 3)

  validation?: {
    completionCriteria?: string[]; // Criteria for LLM self-reflection
    minCompletionScore?: number;   // Minimum score 0-100 (default: 80)
    skipReflection?: boolean;      // Skip validation, auto-pass
  };
}

const mapTask = {
  name: 'Process Items',
  description: 'Process each item from the list',
  controlFlow: {
    type: 'map',
    source: '__items_list',
    resultKey: '__processed_items',
    maxIterations: 50,
    iterationTimeoutMs: 120000, // 2 min per iteration
    tasks: [
      { name: 'Process', description: 'Process the current item' },
    ],
  },
};

import { ROUTINE_KEYS } from 'oneringai';

// ROUTINE_KEYS.PLAN            → '__routine_plan'
// ROUTINE_KEYS.DEPS            → '__routine_deps'
// ROUTINE_KEYS.DEP_RESULT_PREFIX → '__dep_result_'
// ROUTINE_KEYS.MAP_ITEM        → '__map_item'
// ROUTINE_KEYS.MAP_INDEX       → '__map_index'
// ROUTINE_KEYS.MAP_TOTAL       → '__map_total'
// ROUTINE_KEYS.FOLD_ACCUMULATOR → '__fold_accumulator'

const routine = createRoutineDefinition({
  name: 'Data Pipeline',
  tasks: [
    { name: 'Fetch Data', description: '...' },
    { name: 'Clean Data', description: '...', dependsOn: ['Fetch Data'] },
    { name: 'Analyze', description: '...', dependsOn: ['Clean Data'] },
    { name: 'Visualize', description: '...', dependsOn: ['Analyze'] },
  ],
});

const validation = {
  validation: {
    skipReflection: false, // Reflection is opt-in; not a host completion proof.
    completionCriteria: [
      'All API endpoints were documented',
      'Error codes were listed for each endpoint',
      'Authentication requirements were specified',
    ],
    minCompletionScore: 85,  // Strict: require 85+ score
  },
};

const routine = createRoutineDefinition({
  name: 'Pipeline',
  concurrency: {
    maxParallelTasks: 1,
    strategy: 'fifo',
    failureMode: 'fail-fast',  // Default: stop on first failure
    // failureMode: 'continue', // Skip failed tasks, continue with independents
  },
  tasks: [],
});

const execution = await executeRoutine({
  definition: routine,
  connector: 'openai',
  model: 'gpt-4.1',
  prompts: {
    // Custom system prompt
    system: (definition) => `You are ${definition.name}. Follow these rules...`,

    // Custom task prompt
    task: (task) => `
      ## ${task.name}
      ${task.description}
      Remember to store results using store_set("whiteboard", key, { description, value }).
    `,

    // Custom validation prompt
    validation: (task, context) => `
      Did the agent complete "${task.name}"?
      Criteria: ${task.validation?.completionCriteria?.join(', ')}
      Response: ${context.responseText}
      Return JSON: { "isComplete": boolean, "completionScore": number, "explanation": string }
    `,
  },
});

const execution = await executeRoutine({
  definition: routine,
  connector: 'openai',
  model: 'gpt-4.1',

  onTaskComplete: (task, execution) => {
    console.log(`Task "${task.name}" completed`);
    console.log(`  Score: ${task.result?.validationScore}`);
    console.log(`  Progress: ${execution.progress}%`);
  },

  onTaskFailed: (task, execution) => {
    console.error(`Task "${task.name}" failed after ${task.attempts} attempts`);
    console.error(`  Error: ${task.result?.error}`);
  },
});

interface ExecuteRoutineOptions {
  /** Routine definition to execute */
  definition: RoutineDefinition;

  /** Pre-created Agent instance. When provided, connector/model/tools are ignored.
   *  The agent is NOT destroyed after execution — caller manages its lifecycle. */
  agent?: Agent;

  /** Connector name — required when `agent` is not provided */
  connector?: string;

  /** Model ID — required when `agent` is not provided */
  model?: string;

  /** Additional tools — only used when creating a new agent (no `agent` provided) */
  tools?: ToolFunction[];

  /** Input parameter values for parameterized routines */
  inputs?: Record<string, unknown>;

  /** Hooks — applied to agent for the duration of routine execution */
  hooks?: HookConfig;

  /** Called when a task starts executing */
  onTaskStarted?: (task: Task, execution: RoutineExecution) => void;

  /** Called when a task completes successfully */
  onTaskComplete?: (task: Task, execution: RoutineExecution) => void;

  /** Called when a task fails */
  onTaskFailed?: (task: Task, execution: RoutineExecution) => void;

  /** Called after each validation attempt (whether pass or fail) */
  onTaskValidation?: (task: Task, result: TaskValidationResult, execution: RoutineExecution) => void;

  /** Configurable prompts (all have sensible defaults) */
  prompts?: {
    system?: (definition: RoutineDefinition) => string;
    task?: (task: Task) => string;
    validation?: (task: Task, context: ValidationContext) => string;
  };
}

interface RoutineExecution {
  id: string;                      // Unique execution ID
  routineId: string;               // From definition
  status: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
  plan: Plan;                      // Tasks with statuses and results
  progress: number;                // 0-100 percentage
  startedAt?: number;              // Timestamp
  completedAt?: number;            // Timestamp
  lastUpdatedAt: number;           // Timestamp
  error?: string;                  // Error message if failed
}

// Shape of Task.result (not a separately exported type)
interface TaskResult {
  success: boolean;
  output?: unknown;                // Agent's response text (or control-flow result)
  error?: string;                  // Error message if failed
  validationScore?: number;        // 0-100 from validation
  validationExplanation?: string;  // Why it passed/failed
}

import {
  Connector, Vendor, Agent,
  executeRoutine, createRoutineDefinition,
  ConnectorTools, Services, tools,
} from 'oneringai';

// Setup connectors
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

Connector.create({
  name: 'serper',
  serviceType: Services.Serper,
  auth: { type: 'api_key', apiKey: process.env.SERPER_API_KEY! },
  baseURL: 'https://google.serper.dev',
});

// Define the routine
const routine = createRoutineDefinition({
  name: 'Competitive Analysis',
  description: 'Analyze competitors and produce a report',
  instructions: 'You are a business analyst. Be thorough and data-driven.',
  requiredTools: ['web_search'],
  tasks: [
    {
      name: 'Identify Competitors',
      description: 'Search for the top 5 competitors of Acme Corp in the cloud storage market',
      expectedOutput: 'List of competitors stored in context',
      suggestedTools: ['web_search'],
      validation: {
        skipReflection: false, // Reflection is opt-in; not a host completion proof.
        completionCriteria: [
          'At least 5 competitors were identified',
          'Competitor names were stored using store_set("whiteboard", ...)',
        ],
      },
    },
    {
      name: 'Analyze Features',
      description: 'For each competitor found, research their key features and pricing',
      dependsOn: ['Identify Competitors'],
      expectedOutput: 'Feature comparison data stored in memory',
      suggestedTools: ['web_search', 'web_fetch'],
      maxAttempts: 2,
      validation: {
        skipReflection: false, // Reflection is opt-in; not a host completion proof.
        completionCriteria: [
          'Features were researched for all identified competitors',
          'Pricing information was found for at least 3 competitors',
          'Data was stored in working memory',
        ],
        minCompletionScore: 70,  // More lenient — pricing may not always be public
      },
    },
    {
      name: 'Write Report',
      description: 'Compile findings into a structured competitive analysis report',
      dependsOn: ['Analyze Features'],
      expectedOutput: 'A markdown report with executive summary, feature comparison table, and recommendations',
      validation: {
        skipReflection: false, // Reflection is opt-in; not a host completion proof.
        completionCriteria: [
          'Report has an executive summary',
          'Report includes a feature comparison table',
          'Report provides actionable recommendations',
        ],
      },
    },
  ],
});

// Execute with search tools
const searchTools = ConnectorTools.for('serper');

const execution = await executeRoutine({
  definition: routine,
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...searchTools, tools.webFetch],
  onTaskComplete: (task, exec) => {
    console.log(`[${exec.progress}%] ${task.name} completed (score: ${task.result?.validationScore})`);
  },
  onTaskFailed: (task) => {
    console.error(`FAILED: ${task.name} — ${task.result?.error}`);
  },
});

if (execution.status === 'completed') {
  // Get the final report from the last task's output
  const reportTask = execution.plan.tasks.find(t => t.name === 'Write Report');
  console.log(reportTask?.result?.output);
} else {
  console.error(`Routine failed: ${execution.error}`);
}

import {
  createFileRoutineDefinitionStorage,
  createRoutineDefinition,
} from 'oneringai';

const storage = createFileRoutineDefinitionStorage();

// Save a routine
const routine = createRoutineDefinition({
  name: 'Daily Report',
  description: 'Generate a daily status report',
  tags: ['daily', 'reports'],
  author: 'alice',
  tasks: [
    { name: 'Gather Data', description: 'Collect metrics from all sources' },
    { name: 'Write Report', description: 'Summarize findings', dependsOn: ['Gather Data'] },
  ],
});

await storage.save(undefined, routine);  // undefined = default user

// Load by ID
const loaded = await storage.load(undefined, routine.id);

// List with filtering
const dailyRoutines = await storage.list(undefined, { tags: ['daily'] });
const searchResults = await storage.list(undefined, { search: 'report', limit: 10 });

// Delete
await storage.delete(undefined, routine.id);

import { StorageRegistry } from 'oneringai';

StorageRegistry.configure({
  routineDefinitions: (ctx) => new MongoRoutineStorage(ctx?.userId),
});

import {
  createRoutineExecutionRecord,
  createTaskSnapshots,
  createExecutionRecorder,
} from 'oneringai';

// 1. Create the initial record from a definition
const record = createRoutineExecutionRecord(definition, 'openai', 'gpt-4.1', {
  type: 'schedule',
  source: 'daily-cron',
});

// 2. Insert into your storage backend
const execId = await storage.insert(userId, record);

// 3. Create recorder — returns ready-to-use hooks + callbacks
const recorder = createExecutionRecorder({
  storage,
  executionId: execId,
  logPrefix: '[MyRoutine]',
  maxTruncateLength: 500,  // truncate tool args/results in steps
});

// 4. Wire into executeRoutine()
executeRoutine({
  definition, agent, inputs,
  hooks: recorder.hooks,
  onTaskStarted: recorder.onTaskStarted,
  onTaskComplete: recorder.onTaskComplete,
  onTaskFailed: recorder.onTaskFailed,
  onTaskValidation: recorder.onTaskValidation,
})
  .then(exec => recorder.finalize(exec))
  .catch(err => recorder.finalize(null, err));

interface IRoutineExecutionStorage {
  insert(userId: string | undefined, record: RoutineExecutionRecord): Promise<string>;
  update(id: string, updates: Partial<Pick<RoutineExecutionRecord, 'status' | 'progress' | 'error' | 'completedAt' | 'lastActivityAt'>>): Promise<void>;
  pushStep(id: string, step: RoutineExecutionStep): Promise<void>;
  updateTask(id: string, taskName: string, updates: Partial<RoutineTaskSnapshot>): Promise<void>;
  load(id: string): Promise<RoutineExecutionRecord | null>;
  list(userId: string | undefined, options?: { routineId?: string; status?: RoutineExecutionStatus; limit?: number; offset?: number }): Promise<RoutineExecutionRecord[]>;
  hasRunning(userId: string | undefined, routineId: string): Promise<boolean>;
}

StorageRegistry.configure({
  routineExecutions: (ctx) => new MongoRoutineExecutionStorage(ctx?.userId),
});

import { SimpleScheduler } from 'oneringai';

const scheduler = new SimpleScheduler();

// Repeat every hour
scheduler.schedule('hourly-report', { intervalMs: 3600000 }, async () => {
  await executeRoutine({ definition: dailyRoutine, agent, inputs });
});

// Run once at a specific time
scheduler.schedule('end-of-day', { once: endOfDayTimestamp }, async () => {
  await executeRoutine({ definition: summaryRoutine, agent, inputs });
});

// Cancel a schedule
scheduler.cancel('hourly-report');

// Check if a schedule exists
scheduler.has('hourly-report'); // false

// Clean up all timers
scheduler.destroy();

import type { IScheduler, ScheduleHandle, ScheduleSpec } from 'oneringai';
import { Cron } from 'croner';

class CronScheduler implements IScheduler {
  private jobs = new Map<string, Cron>();
  private _isDestroyed = false;

  schedule(id: string, spec: ScheduleSpec, callback: () => void | Promise<void>): ScheduleHandle {
    if (spec.cron) {
      const job = new Cron(spec.cron, { timezone: spec.timezone }, callback);
      this.jobs.set(id, job);
      return { id, cancel: () => this.cancel(id) };
    }
    throw new Error('CronScheduler only handles cron specs');
  }
  cancel(id: string) { this.jobs.get(id)?.stop(); this.jobs.delete(id); }
  cancelAll() { for (const [id] of this.jobs) this.cancel(id); }
  has(id: string) { return this.jobs.has(id); }
  destroy() { this.cancelAll(); this._isDestroyed = true; }
  get isDestroyed() { return this._isDestroyed; }
}

import { EventEmitterTrigger } from 'oneringai';

const trigger = new EventEmitterTrigger();

// Register a handler
const unsubscribe = trigger.on('new-order', async (payload) => {
  const order = payload as { orderId: string; items: string[] };
  await executeRoutine({
    definition: orderProcessingRoutine,
    agent,
    inputs: { orderId: order.orderId, items: order.items },
  });
});

// Emit from your webhook handler, queue consumer, etc.
app.post('/webhooks/orders', (req, res) => {
  trigger.emit('new-order', req.body);
  res.sendStatus(200);
});

// Unsubscribe a specific handler
unsubscribe();

// Clean up all listeners
trigger.destroy();