@dcyfr/ai 2.1.3 → 3.0.0

package/dist/ai/src/scheduler/agent-scheduler.d.ts

@@ -0,0 +1,365 @@
+/**
+ * DCYFR Agent Scheduler
+ * TLP:AMBER - Internal Use Only
+ *
+ * Provides time-based, webhook-based, and event-based task scheduling for
+ * autonomous agents. Features:
+ *   - Cron-style scheduling with built-in cron expression parser
+ *   - Webhook endpoints with secret-based authentication
+ *   - Event subscription with payload filtering
+ *   - Heartbeat health checks with quiet hours
+ *   - Telemetry integration (started/completed/failed events)
+ *   - All scheduled tasks default to readonly trust level
+ *
+ * @module scheduler/agent-scheduler
+ * @version 1.0.0
+ * @date 2026-03-01
+ */
+import { EventEmitter } from 'node:events';
+/** Trust levels for scheduled tasks */
+export type SchedulerTrustLevel = 'full' | 'sandboxed' | 'readonly';
+/**
+ * Configuration for a scheduled task
+ */
+export interface ScheduledTaskConfig {
+    /** Human-readable name for the task */
+    name: string;
+    /** Task description passed to AgentRuntime */
+    description: string;
+    /** Agent ID to execute the task */
+    agentId?: string;
+    /** Trust level — defaults to 'readonly' */
+    trustLevel?: SchedulerTrustLevel;
+    /** Custom metadata passed to task execution */
+    metadata?: Record<string, unknown>;
+    /** Maximum execution time in ms (0 = no limit) */
+    timeoutMs?: number;
+    /** Whether to retry on failure */
+    retryOnFailure?: boolean;
+    /** Maximum retry count */
+    maxRetries?: number;
+}
+/**
+ * A registered cron schedule
+ */
+export interface CronJob {
+    /** Unique job ID */
+    id: string;
+    /** Cron expression (5-field: min hour dom month dow) */
+    cronExpr: string;
+    /** Task configuration */
+    taskConfig: ScheduledTaskConfig;
+    /** Whether the job is active */
+    active: boolean;
+    /** Last run timestamp */
+    lastRunAt?: Date;
+    /** Next scheduled run */
+    nextRunAt?: Date;
+    /** Run count */
+    runCount: number;
+    /** Error count */
+    errorCount: number;
+}
+/**
+ * A registered webhook
+ */
+export interface WebhookEndpoint {
+    /** Unique webhook ID */
+    id: string;
+    /** Route path */
+    route: string;
+    /** Task template to execute on trigger */
+    taskTemplate: ScheduledTaskConfig;
+    /** Secret for validation */
+    secret: string;
+    /** Whether the webhook is active */
+    active: boolean;
+    /** Trigger count */
+    triggerCount: number;
+}
+/**
+ * A registered event subscription
+ */
+export interface EventSubscription {
+    /** Unique subscription ID */
+    id: string;
+    /** Event name to listen for */
+    eventName: string;
+    /** Filter function for event payload */
+    filter?: (payload: unknown) => boolean;
+    /** Task config to execute on matching event */
+    taskConfig: ScheduledTaskConfig;
+    /** Whether the subscription is active */
+    active: boolean;
+    /** Trigger count */
+    triggerCount: number;
+}
+/**
+ * Health check function
+ */
+export type HealthCheckFn = () => Promise<HealthCheckResult> | HealthCheckResult;
+/**
+ * Result of a single health check
+ */
+export interface HealthCheckResult {
+    /** Check name */
+    name: string;
+    /** Whether the check passed */
+    healthy: boolean;
+    /** Optional details */
+    details?: string;
+    /** Check duration in ms */
+    durationMs?: number;
+}
+/**
+ * Aggregated health report
+ */
+export interface HealthReport {
+    /** Overall health status */
+    healthy: boolean;
+    /** Timestamp of the report */
+    timestamp: Date;
+    /** Individual check results */
+    checks: HealthCheckResult[];
+    /** Total healthy checks */
+    healthyCount: number;
+    /** Total unhealthy checks */
+    unhealthyCount: number;
+}
+/**
+ * Quiet hours configuration
+ */
+export interface QuietHours {
+    /** Start hour (0-23) */
+    startHour: number;
+    /** End hour (0-23) */
+    endHour: number;
+    /** Timezone offset in hours (default: 0 / UTC) */
+    timezoneOffsetHours?: number;
+}
+/**
+ * Heartbeat configuration
+ */
+export interface HeartbeatConfig {
+    /** Check interval in ms */
+    intervalMs: number;
+    /** Health check functions */
+    checks: HealthCheckFn[];
+    /** Quiet hours — suppress during these hours */
+    quietHours?: QuietHours;
+}
+/**
+ * Task executor function — called when a scheduled task fires
+ */
+export type TaskExecutor = (taskConfig: ScheduledTaskConfig, context: TaskExecutionContext) => Promise<TaskExecutionResult>;
+/**
+ * Context passed to task executor
+ */
+export interface TaskExecutionContext {
+    /** Execution ID */
+    executionId: string;
+    /** Trigger source */
+    trigger: 'cron' | 'webhook' | 'event' | 'manual';
+    /** Trigger details */
+    triggerId: string;
+    /** Webhook payload (if triggered by webhook) */
+    webhookPayload?: unknown;
+    /** Event payload (if triggered by event) */
+    eventPayload?: unknown;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Result of a task execution
+ */
+export interface TaskExecutionResult {
+    /** Whether the task succeeded */
+    success: boolean;
+    /** Result data */
+    result?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in ms */
+    durationMs: number;
+}
+/**
+ * Telemetry event emitted by the scheduler
+ */
+export interface SchedulerTelemetryEvent {
+    /** Event type */
+    type: 'scheduler.task.started' | 'scheduler.task.completed' | 'scheduler.task.failed' | 'scheduler.heartbeat' | 'scheduler.webhook.received';
+    /** Event data */
+    data: Record<string, unknown>;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Webhook request shape
+ */
+export interface WebhookRequest {
+    /** Route path */
+    route: string;
+    /** Request body/payload */
+    body: unknown;
+    /** Headers including X-Webhook-Secret */
+    headers: Record<string, string>;
+}
+/**
+ * Check if a Date matches a 5-field cron expression
+ * Format: minute hour day-of-month month day-of-week
+ */
+export declare function matchesCron(cronExpr: string, date: Date): boolean;
+/**
+ * Calculate next matching time for a cron expression (within 48 hours)
+ */
+export declare function nextCronMatch(cronExpr: string, after?: Date): Date | null;
+/**
+ * Configuration for AgentScheduler
+ */
+export interface AgentSchedulerConfig {
+    /** Task executor function */
+    executor?: TaskExecutor;
+    /** Cron check interval in ms (default: 60000 = 1 minute) */
+    cronCheckIntervalMs?: number;
+    /** Default trust level for scheduled tasks */
+    defaultTrustLevel?: SchedulerTrustLevel;
+}
+/**
+ * Agent Scheduler
+ *
+ * Provides cron, webhook, and event-based task scheduling for autonomous agents.
+ *
+ * Emits:
+ *   - `scheduler.task.started` — Task execution started
+ *   - `scheduler.task.completed` — Task execution completed successfully
+ *   - `scheduler.task.failed` — Task execution failed
+ *   - `scheduler.heartbeat` — Heartbeat health report generated
+ *   - `scheduler.webhook.received` — Webhook request received
+ */
+export declare class AgentScheduler extends EventEmitter {
+    private readonly cronJobs;
+    private readonly webhooks;
+    private readonly subscriptions;
+    private readonly executor;
+    private readonly cronCheckIntervalMs;
+    private readonly defaultTrustLevel;
+    private cronTimer;
+    private heartbeatTimer;
+    private heartbeatConfig;
+    private running;
+    constructor(config?: AgentSchedulerConfig);
+    /**
+     * Schedule a recurring task using a cron expression.
+     *
+     * @param cronExpr - 5-field cron expression (minute hour dom month dow)
+     * @param taskConfig - Task configuration
+     * @returns Job ID
+     */
+    schedule(cronExpr: string, taskConfig: ScheduledTaskConfig): string;
+    /**
+     * Remove a cron job
+     */
+    unschedule(jobId: string): boolean;
+    /**
+     * Get all registered cron jobs
+     */
+    getJobs(): CronJob[];
+    /**
+     * Get a specific cron job
+     */
+    getJob(jobId: string): CronJob | undefined;
+    /**
+     * Register a webhook endpoint.
+     *
+     * @param route - Route path (e.g., '/webhook/deploy')
+     * @param taskTemplate - Task config template (payload merged at trigger time)
+     * @param secret - Secret for X-Webhook-Secret header validation
+     * @returns Webhook ID
+     */
+    webhook(route: string, taskTemplate: ScheduledTaskConfig, secret: string): string;
+    /**
+     * Handle an incoming webhook request.
+     * Validates X-Webhook-Secret header and triggers the associated task.
+     *
+     * @param request - Webhook request
+     * @returns Task execution result
+     * @throws Error if route not found or secret invalid
+     */
+    handleWebhook(request: WebhookRequest): Promise<TaskExecutionResult>;
+    /**
+     * Remove a webhook
+     */
+    removeWebhook(webhookId: string): boolean;
+    /**
+     * Get all registered webhooks
+     */
+    getWebhooks(): WebhookEndpoint[];
+    /**
+     * Subscribe to a runtime event. When the event fires and passes the filter,
+     * the associated task is executed.
+     *
+     * @param eventName - Event to listen for
+     * @param filter - Optional filter function on event payload
+     * @param taskConfig - Task configuration
+     * @returns Subscription ID
+     */
+    subscribe(eventName: string, filter: ((payload: unknown) => boolean) | null, taskConfig: ScheduledTaskConfig): string;
+    /**
+     * Emit an event to the scheduler. All matching subscriptions will be triggered.
+     *
+     * @param eventName - Event name
+     * @param payload - Event payload
+     * @returns Array of execution results
+     */
+    triggerEvent(eventName: string, payload: unknown): Promise<TaskExecutionResult[]>;
+    /**
+     * Remove an event subscription
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Get all event subscriptions
+     */
+    getSubscriptions(): EventSubscription[];
+    /**
+     * Start a heartbeat health check. Runs checks at the specified interval,
+     * respecting quiet hours. Emits 'scheduler.heartbeat' with HealthReport.
+     *
+     * @param config - Heartbeat configuration
+     */
+    heartbeat(config: HeartbeatConfig): void;
+    /**
+     * Run all health checks manually and return the report
+     */
+    runHealthChecks(): Promise<HealthReport>;
+    /**
+     * Start the scheduler — begins cron checking
+     */
+    start(): void;
+    /**
+     * Stop the scheduler — halts all timers
+     */
+    stop(): void;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): void;
+    /**
+     * Get scheduler status
+     */
+    getStatus(): {
+        running: boolean;
+        cronJobs: number;
+        webhooks: number;
+        subscriptions: number;
+        heartbeatActive: boolean;
+    };
+    private _startCronTimer;
+    private _stopCronTimer;
+    private _checkCronJobs;
+    private _executeTask;
+}
+/**
+ * Check if current time is within quiet hours
+ */
+export declare function isInQuietHours(quietHours: QuietHours): boolean;
+//# sourceMappingURL=agent-scheduler.d.ts.map

package/dist/ai/src/scheduler/agent-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-scheduler.d.ts","sourceRoot":"","sources":["../../../../packages/ai/src/scheduler/agent-scheduler.ts"],"names":[],"mappings":"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"}