@flowdot.ai/daemon 1.0.0

package/dist/loop/errors.d.ts

@@ -0,0 +1,115 @@
+import type { LoopId, LoopRunId, LoopStatus } from './types.js';
+export type LoopErrorCode = 'LOOP_NOT_FOUND' | 'LOOP_ALREADY_EXISTS' | 'LOOP_NAME_TAKEN' | 'LOOP_INVALID_STATUS' | 'LOOP_EXPIRED' | 'LOOP_LIMIT_EXCEEDED' | 'INVALID_INTERVAL' | 'INTERVAL_TOO_SHORT' | 'INTERVAL_PARSE_ERROR' | 'INVALID_CRON_EXPRESSION' | 'LOOP_EXECUTION_ERROR' | 'LOOP_EXECUTION_TIMEOUT' | 'LOOP_RUN_NOT_FOUND' | 'DAEMON_NOT_RUNNING' | 'DAEMON_ALREADY_RUNNING' | 'DAEMON_START_FAILED' | 'DAEMON_STOP_FAILED' | 'DAEMON_COMMUNICATION_ERROR' | 'DAEMON_CONNECTION_ERROR' | 'DAEMON_IPC_TIMEOUT' | 'SCHEDULER_ERROR' | 'INVALID_LOOP_STATE' | 'STORAGE_READ_ERROR' | 'STORAGE_WRITE_ERROR' | 'STORAGE_CORRUPT' | 'STORAGE_MIGRATION_ERROR' | 'VALIDATION_ERROR' | 'INVALID_PROMPT' | 'INVALID_NAME' | 'INVALID_OPTIONS' | 'NOTIFICATION_FAILED' | 'WEBHOOK_ERROR' | 'SLACK_ERROR' | 'CONFIG_ERROR' | 'INVALID_CONFIG' | 'MANAGER_NOT_INITIALIZED';
+export declare class LoopError extends Error {
+    readonly code: LoopErrorCode;
+    readonly context: Record<string, unknown>;
+    readonly timestamp: Date;
+    constructor(code: LoopErrorCode, message: string, context?: Record<string, unknown>);
+    toJSON(): Record<string, unknown>;
+    toLogString(): string;
+}
+export declare class LoopNotFoundError extends LoopError {
+    constructor(identifier: string, identifierType?: 'id' | 'name');
+}
+export declare class LoopAlreadyExistsError extends LoopError {
+    constructor(loopId: LoopId);
+}
+export declare class LoopNameTakenError extends LoopError {
+    constructor(name: string);
+}
+export declare class LoopInvalidStatusError extends LoopError {
+    constructor(loopId: LoopId, currentStatus: LoopStatus, operation: string, allowedStatuses: LoopStatus[]);
+}
+export declare class LoopExpiredError extends LoopError {
+    constructor(loopId: LoopId, expiredAt: Date);
+}
+export declare class LoopLimitExceededError extends LoopError {
+    constructor(currentCount: number, maxCount: number);
+}
+export declare class InvalidIntervalError extends LoopError {
+    constructor(interval: string, reason: string);
+}
+export declare class IntervalTooShortError extends LoopError {
+    constructor(interval: string, milliseconds: number, minimumMs: number);
+}
+export declare class InvalidCronExpressionError extends LoopError {
+    constructor(expression: string, parseError: string);
+}
+export declare class LoopExecutionError extends LoopError {
+    constructor(loopId: LoopId, runId: LoopRunId, cause: string, originalError?: Error);
+}
+export declare class LoopExecutionTimeoutError extends LoopError {
+    constructor(loopId: LoopId, runId: LoopRunId, timeoutMs: number);
+}
+export declare class LoopRunNotFoundError extends LoopError {
+    constructor(loopId: LoopId, runId: LoopRunId);
+}
+export declare class DaemonNotRunningError extends LoopError {
+    constructor();
+}
+export declare class DaemonAlreadyRunningError extends LoopError {
+    constructor(pid: number);
+}
+export declare class DaemonStartFailedError extends LoopError {
+    constructor(reason: string, originalError?: Error);
+}
+export declare class DaemonStopFailedError extends LoopError {
+    constructor(pid: number, reason: string);
+}
+export declare class DaemonCommunicationError extends LoopError {
+    constructor(operation: string, reason: string);
+}
+export declare class DaemonConnectionError extends LoopError {
+    constructor(host: string, port: number, reason: string);
+}
+export declare class DaemonIPCTimeoutError extends LoopError {
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class SchedulerError extends LoopError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+export declare class InvalidLoopStateError extends LoopError {
+    constructor(loopId: LoopId, currentStatus: LoopStatus, expectedState: string);
+}
+export declare class StorageReadError extends LoopError {
+    constructor(path: string, reason: string, originalError?: Error);
+}
+export declare class StorageWriteError extends LoopError {
+    constructor(path: string, reason: string, originalError?: Error);
+}
+export declare class StorageCorruptError extends LoopError {
+    constructor(path: string, reason: string);
+}
+export declare class StorageMigrationError extends LoopError {
+    constructor(fromVersion: number, toVersion: number, reason: string);
+}
+export declare class ValidationError extends LoopError {
+    constructor(field: string, value: unknown, reason: string);
+}
+export declare class InvalidPromptError extends LoopError {
+    constructor(reason: string);
+}
+export declare class InvalidNameError extends LoopError {
+    constructor(name: string, reason: string);
+}
+export declare class InvalidOptionsError extends LoopError {
+    constructor(option: string, value: unknown, reason: string);
+}
+export declare class NotificationFailedError extends LoopError {
+    constructor(method: string, reason: string, originalError?: Error);
+}
+export declare class WebhookError extends LoopError {
+    constructor(url: string, statusCode: number | null, reason: string);
+}
+export declare class SlackError extends LoopError {
+    constructor(reason: string, originalError?: Error);
+}
+export declare class ConfigError extends LoopError {
+    constructor(key: string, reason: string);
+}
+export declare class InvalidConfigError extends LoopError {
+    constructor(key: string, value: unknown, expectedType: string);
+}
+export declare function isLoopError(error: unknown): error is LoopError;
+export declare function hasErrorCode(error: unknown, code: LoopErrorCode): error is LoopError;
+export declare function wrapError(error: unknown, code: LoopErrorCode, message: string): LoopError;

package/dist/loop/errors.js

@@ -0,0 +1,312 @@
+export class LoopError extends Error {
+    code;
+    context;
+    timestamp;
+    constructor(code, message, context = {}) {
+        super(message);
+        this.name = 'LoopError';
+        this.code = code;
+        this.context = context;
+        this.timestamp = new Date();
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+        };
+    }
+    toLogString() {
+        const contextStr = Object.keys(this.context).length > 0
+            ? ` Context: ${JSON.stringify(this.context)}`
+            : '';
+        return `[${this.code}] ${this.message}${contextStr}`;
+    }
+}
+export class LoopNotFoundError extends LoopError {
+    constructor(identifier, identifierType = 'id') {
+        super('LOOP_NOT_FOUND', `Loop not found: ${identifier}`, { identifier, identifierType });
+        this.name = 'LoopNotFoundError';
+    }
+}
+export class LoopAlreadyExistsError extends LoopError {
+    constructor(loopId) {
+        super('LOOP_ALREADY_EXISTS', `Loop already exists with ID: ${loopId}`, { loopId });
+        this.name = 'LoopAlreadyExistsError';
+    }
+}
+export class LoopNameTakenError extends LoopError {
+    constructor(name) {
+        super('LOOP_NAME_TAKEN', `Loop name already in use: "${name}"`, { name });
+        this.name = 'LoopNameTakenError';
+    }
+}
+export class LoopInvalidStatusError extends LoopError {
+    constructor(loopId, currentStatus, operation, allowedStatuses) {
+        super('LOOP_INVALID_STATUS', `Cannot ${operation} loop in "${currentStatus}" status. Allowed: ${allowedStatuses.join(', ')}`, { loopId, currentStatus, operation, allowedStatuses });
+        this.name = 'LoopInvalidStatusError';
+    }
+}
+export class LoopExpiredError extends LoopError {
+    constructor(loopId, expiredAt) {
+        super('LOOP_EXPIRED', `Loop has expired at ${expiredAt.toISOString()}`, { loopId, expiredAt: expiredAt.toISOString() });
+        this.name = 'LoopExpiredError';
+    }
+}
+export class LoopLimitExceededError extends LoopError {
+    constructor(currentCount, maxCount) {
+        super('LOOP_LIMIT_EXCEEDED', `Maximum concurrent loops limit reached (${currentCount}/${maxCount})`, { currentCount, maxCount });
+        this.name = 'LoopLimitExceededError';
+    }
+}
+export class InvalidIntervalError extends LoopError {
+    constructor(interval, reason) {
+        super('INVALID_INTERVAL', `Invalid interval "${interval}": ${reason}`, { interval, reason });
+        this.name = 'InvalidIntervalError';
+    }
+}
+export class IntervalTooShortError extends LoopError {
+    constructor(interval, milliseconds, minimumMs) {
+        const minFormatted = formatDuration(minimumMs);
+        const actualFormatted = formatDuration(milliseconds);
+        super('INTERVAL_TOO_SHORT', `Interval "${interval}" (${actualFormatted}) is shorter than minimum allowed (${minFormatted})`, { interval, milliseconds, minimumMs });
+        this.name = 'IntervalTooShortError';
+    }
+}
+export class InvalidCronExpressionError extends LoopError {
+    constructor(expression, parseError) {
+        super('INVALID_CRON_EXPRESSION', `Invalid cron expression "${expression}": ${parseError}`, { expression, parseError });
+        this.name = 'InvalidCronExpressionError';
+    }
+}
+export class LoopExecutionError extends LoopError {
+    constructor(loopId, runId, cause, originalError) {
+        super('LOOP_EXECUTION_ERROR', `Loop execution failed: ${cause}`, {
+            loopId,
+            runId,
+            cause,
+            originalError: originalError?.message,
+            originalStack: originalError?.stack,
+        });
+        this.name = 'LoopExecutionError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class LoopExecutionTimeoutError extends LoopError {
+    constructor(loopId, runId, timeoutMs) {
+        super('LOOP_EXECUTION_TIMEOUT', `Loop execution timed out after ${formatDuration(timeoutMs)}`, { loopId, runId, timeoutMs });
+        this.name = 'LoopExecutionTimeoutError';
+    }
+}
+export class LoopRunNotFoundError extends LoopError {
+    constructor(loopId, runId) {
+        super('LOOP_RUN_NOT_FOUND', `Loop run not found: ${runId}`, { loopId, runId });
+        this.name = 'LoopRunNotFoundError';
+    }
+}
+export class DaemonNotRunningError extends LoopError {
+    constructor() {
+        super('DAEMON_NOT_RUNNING', 'Loop daemon is not running. Start it with "flowdot daemon start"', {});
+        this.name = 'DaemonNotRunningError';
+    }
+}
+export class DaemonAlreadyRunningError extends LoopError {
+    constructor(pid) {
+        super('DAEMON_ALREADY_RUNNING', `Loop daemon is already running (PID: ${pid})`, { pid });
+        this.name = 'DaemonAlreadyRunningError';
+    }
+}
+export class DaemonStartFailedError extends LoopError {
+    constructor(reason, originalError) {
+        super('DAEMON_START_FAILED', `Failed to start loop daemon: ${reason}`, {
+            reason,
+            originalError: originalError?.message,
+        });
+        this.name = 'DaemonStartFailedError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class DaemonStopFailedError extends LoopError {
+    constructor(pid, reason) {
+        super('DAEMON_STOP_FAILED', `Failed to stop loop daemon (PID: ${pid}): ${reason}`, { pid, reason });
+        this.name = 'DaemonStopFailedError';
+    }
+}
+export class DaemonCommunicationError extends LoopError {
+    constructor(operation, reason) {
+        super('DAEMON_COMMUNICATION_ERROR', `Daemon communication failed during ${operation}: ${reason}`, { operation, reason });
+        this.name = 'DaemonCommunicationError';
+    }
+}
+export class DaemonConnectionError extends LoopError {
+    constructor(host, port, reason) {
+        super('DAEMON_CONNECTION_ERROR', `Failed to connect to daemon at ${host}:${port}: ${reason}`, { host, port, reason });
+        this.name = 'DaemonConnectionError';
+    }
+}
+export class DaemonIPCTimeoutError extends LoopError {
+    constructor(operation, timeoutMs) {
+        super('DAEMON_IPC_TIMEOUT', `IPC request timed out after ${formatDuration(timeoutMs)}: ${operation}`, { operation, timeoutMs });
+        this.name = 'DaemonIPCTimeoutError';
+    }
+}
+export class SchedulerError extends LoopError {
+    constructor(message, context = {}) {
+        super('SCHEDULER_ERROR', message, context);
+        this.name = 'SchedulerError';
+    }
+}
+export class InvalidLoopStateError extends LoopError {
+    constructor(loopId, currentStatus, expectedState) {
+        super('INVALID_LOOP_STATE', `Loop ${loopId} is in "${currentStatus}" state, expected "${expectedState}"`, { loopId, currentStatus, expectedState });
+        this.name = 'InvalidLoopStateError';
+    }
+}
+export class StorageReadError extends LoopError {
+    constructor(path, reason, originalError) {
+        super('STORAGE_READ_ERROR', `Failed to read from storage: ${reason}`, {
+            path,
+            reason,
+            originalError: originalError?.message,
+        });
+        this.name = 'StorageReadError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class StorageWriteError extends LoopError {
+    constructor(path, reason, originalError) {
+        super('STORAGE_WRITE_ERROR', `Failed to write to storage: ${reason}`, {
+            path,
+            reason,
+            originalError: originalError?.message,
+        });
+        this.name = 'StorageWriteError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class StorageCorruptError extends LoopError {
+    constructor(path, reason) {
+        super('STORAGE_CORRUPT', `Storage data is corrupt at ${path}: ${reason}`, { path, reason });
+        this.name = 'StorageCorruptError';
+    }
+}
+export class StorageMigrationError extends LoopError {
+    constructor(fromVersion, toVersion, reason) {
+        super('STORAGE_MIGRATION_ERROR', `Failed to migrate storage from v${fromVersion} to v${toVersion}: ${reason}`, { fromVersion, toVersion, reason });
+        this.name = 'StorageMigrationError';
+    }
+}
+export class ValidationError extends LoopError {
+    constructor(field, value, reason) {
+        super('VALIDATION_ERROR', `Validation failed for "${field}": ${reason}`, { field, value, reason });
+        this.name = 'ValidationError';
+    }
+}
+export class InvalidPromptError extends LoopError {
+    constructor(reason) {
+        super('INVALID_PROMPT', `Invalid prompt: ${reason}`, { reason });
+        this.name = 'InvalidPromptError';
+    }
+}
+export class InvalidNameError extends LoopError {
+    constructor(name, reason) {
+        super('INVALID_NAME', `Invalid loop name "${name}": ${reason}`, { name, reason });
+        this.name = 'InvalidNameError';
+    }
+}
+export class InvalidOptionsError extends LoopError {
+    constructor(option, value, reason) {
+        super('INVALID_OPTIONS', `Invalid option "${option}": ${reason}`, { option, value, reason });
+        this.name = 'InvalidOptionsError';
+    }
+}
+export class NotificationFailedError extends LoopError {
+    constructor(method, reason, originalError) {
+        super('NOTIFICATION_FAILED', `Failed to send ${method} notification: ${reason}`, {
+            method,
+            reason,
+            originalError: originalError?.message,
+        });
+        this.name = 'NotificationFailedError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class WebhookError extends LoopError {
+    constructor(url, statusCode, reason) {
+        super('WEBHOOK_ERROR', `Webhook request failed: ${reason}`, { url, statusCode, reason });
+        this.name = 'WebhookError';
+    }
+}
+export class SlackError extends LoopError {
+    constructor(reason, originalError) {
+        super('SLACK_ERROR', `Slack notification failed: ${reason}`, {
+            reason,
+            originalError: originalError?.message,
+        });
+        this.name = 'SlackError';
+        if (originalError) {
+            this.cause = originalError;
+        }
+    }
+}
+export class ConfigError extends LoopError {
+    constructor(key, reason) {
+        super('CONFIG_ERROR', `Configuration error for "${key}": ${reason}`, { key, reason });
+        this.name = 'ConfigError';
+    }
+}
+export class InvalidConfigError extends LoopError {
+    constructor(key, value, expectedType) {
+        super('INVALID_CONFIG', `Invalid configuration value for "${key}": expected ${expectedType}`, { key, value, expectedType });
+        this.name = 'InvalidConfigError';
+    }
+}
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60000) {
+        return `${Math.round(ms / 1000)}s`;
+    }
+    if (ms < 3600000) {
+        return `${Math.round(ms / 60000)}m`;
+    }
+    if (ms < 86400000) {
+        return `${Math.round(ms / 3600000)}h`;
+    }
+    return `${Math.round(ms / 86400000)}d`;
+}
+export function isLoopError(error) {
+    return error instanceof LoopError;
+}
+export function hasErrorCode(error, code) {
+    return isLoopError(error) && error.code === code;
+}
+export function wrapError(error, code, message) {
+    if (isLoopError(error)) {
+        return error;
+    }
+    const originalError = error instanceof Error ? error : new Error(String(error));
+    const loopError = new LoopError(code, message, {
+        originalError: originalError.message,
+        originalStack: originalError.stack,
+    });
+    loopError.cause = originalError;
+    return loopError;
+}

package/dist/loop/index.d.ts

@@ -0,0 +1,11 @@
+export type { LoopId, LoopRunId, LoopStatus, LoopRunStatus, NotifyMethod, ModelTier, Loop, LoopRun, LoopConfig, LoopDaemonConfig, LoopWebhookConfig, CreateLoopInput, LoopCreateInput, DaemonStatus, NotificationPayload, Notifier, IPCMessage, IPCRequest, IPCResponse, IPCEvent, AgenticResponseFunction, AgenticResponseCallback, ExecuteActionFunction, Logger, } from './types.js';
+export { LoopError, LoopNotFoundError, LoopAlreadyExistsError, LoopNameTakenError, LoopInvalidStatusError, LoopExpiredError, LoopLimitExceededError, InvalidIntervalError, IntervalTooShortError, InvalidCronExpressionError, LoopExecutionError, LoopExecutionTimeoutError, LoopRunNotFoundError, DaemonNotRunningError, DaemonAlreadyRunningError, DaemonStartFailedError, DaemonStopFailedError, DaemonCommunicationError, DaemonConnectionError, DaemonIPCTimeoutError, SchedulerError, InvalidLoopStateError, StorageReadError, StorageWriteError, StorageCorruptError, StorageMigrationError, ValidationError, InvalidPromptError, InvalidNameError, InvalidOptionsError, NotificationFailedError, WebhookError, SlackError, ConfigError, InvalidConfigError, isLoopError, hasErrorCode, wrapError, } from './errors.js';
+export { IntervalParser, createIntervalParser, parseInterval, validateInterval, isValidInterval, calculateNextRun, type IntervalParserOptions, type ParseResult, } from './IntervalParser.js';
+export { LoopValidator, createLoopValidator, validateCreateInput, validateUpdateInput, validateLoopName, validatePrompt, DEFAULT_VALIDATION_CONSTRAINTS, type ValidationConstraints, type ValidationResult, type ValidationIssue, } from './LoopValidator.js';
+export { LoopStore, createLoopStore, initializeLoopStore, type LoopStoreOptions, } from './LoopStore.js';
+export { LoopScheduler, createLoopScheduler, createAndStartScheduler, type LoopSchedulerOptions, type SchedulerOptions, type SchedulerStats, type SchedulerEvents, } from './LoopScheduler.js';
+export { LoopExecutor, createLoopExecutor, createLoopExecutorWithConfig, createEmptyRun, createSuccessfulRun, createFailedRun, type LoopExecutorOptions, type ExecutorOptions, type ExecutionResult, type ExecutionContext, type ExecutorEvents, type AgentResponseFunction, type AgentResponse, type AgentAction, type ActionExecutorFunction, type ActionResult, } from './LoopExecutor.js';
+export { LoopManager, createLoopManager, type LoopManagerOptions, type ManagerStats, type ManagerEvents, } from './LoopManager.js';
+export { IPCServer, IPCClient, isDaemonRunning, waitForDaemon, daemonRequest, type IPCServerOptions, type IPCClientOptions, type RequestHandler, } from './DaemonIPC.js';
+export { LoopDaemon, startDaemon, stopDaemon, getDaemonStatus, isProcessRunning, createLoopDaemon, runDaemon, type LoopDaemonOptions, type DaemonControlOptions, type DaemonMethod, type DaemonEvents, } from './LoopDaemon.js';
+export { BaseNotifier, NullNotifier, TerminalNotifier, WebhookNotifier, SlackNotifier, createNotifier, createNotifierSync, createNotifiers, isValidNotifyMethod, getAvailableNotifyMethods, MAX_MESSAGE_LENGTH, MAX_TITLE_LENGTH, type NotifierConfig, type NotifierFactoryConfig, type TerminalNotifierOptions, type WebhookNotifierOptions, type SlackNotifierOptions, } from './notifications/index.js';

package/dist/loop/index.js

@@ -0,0 +1,10 @@
+export { LoopError, LoopNotFoundError, LoopAlreadyExistsError, LoopNameTakenError, LoopInvalidStatusError, LoopExpiredError, LoopLimitExceededError, InvalidIntervalError, IntervalTooShortError, InvalidCronExpressionError, LoopExecutionError, LoopExecutionTimeoutError, LoopRunNotFoundError, DaemonNotRunningError, DaemonAlreadyRunningError, DaemonStartFailedError, DaemonStopFailedError, DaemonCommunicationError, DaemonConnectionError, DaemonIPCTimeoutError, SchedulerError, InvalidLoopStateError, StorageReadError, StorageWriteError, StorageCorruptError, StorageMigrationError, ValidationError, InvalidPromptError, InvalidNameError, InvalidOptionsError, NotificationFailedError, WebhookError, SlackError, ConfigError, InvalidConfigError, isLoopError, hasErrorCode, wrapError, } from './errors.js';
+export { IntervalParser, createIntervalParser, parseInterval, validateInterval, isValidInterval, calculateNextRun, } from './IntervalParser.js';
+export { LoopValidator, createLoopValidator, validateCreateInput, validateUpdateInput, validateLoopName, validatePrompt, DEFAULT_VALIDATION_CONSTRAINTS, } from './LoopValidator.js';
+export { LoopStore, createLoopStore, initializeLoopStore, } from './LoopStore.js';
+export { LoopScheduler, createLoopScheduler, createAndStartScheduler, } from './LoopScheduler.js';
+export { LoopExecutor, createLoopExecutor, createLoopExecutorWithConfig, createEmptyRun, createSuccessfulRun, createFailedRun, } from './LoopExecutor.js';
+export { LoopManager, createLoopManager, } from './LoopManager.js';
+export { IPCServer, IPCClient, isDaemonRunning, waitForDaemon, daemonRequest, } from './DaemonIPC.js';
+export { LoopDaemon, startDaemon, stopDaemon, getDaemonStatus, isProcessRunning, createLoopDaemon, runDaemon, } from './LoopDaemon.js';
+export { BaseNotifier, NullNotifier, TerminalNotifier, WebhookNotifier, SlackNotifier, createNotifier, createNotifierSync, createNotifiers, isValidNotifyMethod, getAvailableNotifyMethods, MAX_MESSAGE_LENGTH, MAX_TITLE_LENGTH, } from './notifications/index.js';

package/dist/loop/notifications/Notifier.d.ts

@@ -0,0 +1,28 @@
+import type { NotifyMethod, NotificationPayload, Notifier, LoopWebhookConfig, Logger } from '../types.js';
+export declare const MAX_MESSAGE_LENGTH = 2000;
+export declare const MAX_TITLE_LENGTH = 100;
+export declare abstract class BaseNotifier implements Notifier {
+    abstract readonly type: NotifyMethod;
+    protected readonly enabled: boolean;
+    protected readonly logger: Logger;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    abstract send(payload: NotificationPayload): Promise<void>;
+    protected formatTitle(payload: NotificationPayload): string;
+    protected formatMessage(payload: NotificationPayload): string;
+    protected getStatusIcon(status?: string): string;
+    protected truncate(text: string, maxLength: number): string;
+    protected logNotification(payload: NotificationPayload, success: boolean): void;
+    protected handleError(error: unknown, payload: NotificationPayload): never;
+}
+export declare class NullNotifier extends BaseNotifier {
+    readonly type: NotifyMethod;
+    send(_payload: NotificationPayload): Promise<void>;
+}
+export interface NotifierConfig {
+    webhooks?: LoopWebhookConfig;
+    webhookUrl?: string | null;
+    slackWebhookUrl?: string | null;
+    logger?: Logger;
+}

package/dist/loop/notifications/Notifier.js

@@ -0,0 +1,78 @@
+import { NotificationFailedError } from '../errors.js';
+export const MAX_MESSAGE_LENGTH = 2000;
+export const MAX_TITLE_LENGTH = 100;
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+export class BaseNotifier {
+    enabled = true;
+    logger;
+    constructor(options = {}) {
+        this.logger = options.logger ?? noopLogger;
+    }
+    formatTitle(payload) {
+        const name = payload.loopName ?? payload.loopId.substring(0, 8);
+        const statusIcon = this.getStatusIcon(payload.status);
+        const title = payload.title || `Loop: ${name}`;
+        const formatted = statusIcon ? `${statusIcon} ${title}` : title;
+        return this.truncate(formatted, MAX_TITLE_LENGTH);
+    }
+    formatMessage(payload) {
+        const parts = [];
+        if (payload.message) {
+            parts.push(payload.message);
+        }
+        if (payload.error) {
+            parts.push(`\nError: ${payload.error}`);
+        }
+        parts.push(`\nTime: ${payload.timestamp.toLocaleString()}`);
+        return this.truncate(parts.join(''), MAX_MESSAGE_LENGTH);
+    }
+    getStatusIcon(status) {
+        switch (status) {
+            case 'success':
+                return '✓';
+            case 'error':
+                return '✗';
+            case 'running':
+                return '⟳';
+            default:
+                return '';
+        }
+    }
+    truncate(text, maxLength) {
+        if (text.length <= maxLength) {
+            return text;
+        }
+        return text.substring(0, maxLength - 3) + '...';
+    }
+    logNotification(payload, success) {
+        const level = success ? 'debug' : 'warn';
+        const message = success
+            ? `Notification sent via ${this.type}`
+            : `Notification failed via ${this.type}`;
+        this.logger[level]('LOOP', message, {
+            loopId: payload.loopId,
+            runId: payload.runId,
+            status: payload.status,
+        });
+    }
+    handleError(error, payload) {
+        const message = error instanceof Error ? error.message : String(error);
+        const originalError = error instanceof Error ? error : undefined;
+        this.logger.error('LOOP', `Notification failed: ${message}`, {
+            type: this.type,
+            loopId: payload.loopId,
+            runId: payload.runId,
+        });
+        throw new NotificationFailedError(this.type, message, originalError);
+    }
+}
+export class NullNotifier extends BaseNotifier {
+    type = 'none';
+    async send(_payload) {
+    }
+}

package/dist/loop/notifications/SlackNotifier.d.ts

@@ -0,0 +1,28 @@
+import type { NotifyMethod, NotificationPayload, Logger } from '../types.js';
+import { BaseNotifier } from './Notifier.js';
+export interface SlackNotifierOptions {
+    webhookUrl: string;
+    timeout?: number;
+    retries?: number;
+    channel?: string;
+    username?: string;
+    iconEmoji?: string;
+    logger?: Logger;
+}
+export declare class SlackNotifier extends BaseNotifier {
+    readonly type: NotifyMethod;
+    private readonly webhookUrl;
+    private readonly timeout;
+    private readonly retries;
+    private readonly channel?;
+    private readonly username;
+    private readonly iconEmoji;
+    constructor(options: SlackNotifierOptions);
+    send(payload: NotificationPayload): Promise<void>;
+    private buildPayload;
+    private sendRequest;
+    private getStatusColor;
+    private getStatusEmoji;
+    private truncateForSlack;
+    private delay;
+}