@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/hooks/types.d.ts

@@ -0,0 +1,94 @@
+/** The 5 lifecycle phases */
+export type HookPhase = 'Pre' | 'Post' | 'Fail' | 'Change' | 'Lifecycle';
+/** Hook event categories */
+export type HookCategory = 'tool' | 'file' | 'git' | 'agent' | 'compact' | 'llm' | 'mcp' | 'config' | 'budget' | 'session' | 'workflow' | 'permission' | 'transport' | 'orchestration' | 'communication';
+/** A fully qualified hook event path: Phase:Category:Specific */
+export type HookEventPath = `${HookPhase}:${HookCategory}:${string}`;
+/** Event payload passed to hooks */
+export interface HookEvent {
+    path: HookEventPath;
+    phase: HookPhase;
+    category: HookCategory;
+    specific: string;
+    sessionId: string;
+    timestamp: number;
+    payload: Record<string, unknown>;
+    /** For agent-scoped events */
+    agentId?: string;
+}
+/** Result returned by a hook handler */
+export interface HookResult {
+    /** For Pre hooks: allow, deny, or ask */
+    decision?: 'allow' | 'deny' | 'ask';
+    /** Reason for denial */
+    reason?: string;
+    /** Modified input (Pre hooks can modify tool input) */
+    updatedInput?: Record<string, unknown>;
+    /** Context to inject into the LLM conversation */
+    additionalContext?: string;
+    /** Whether the hook ran successfully */
+    ok: boolean;
+    /** Error message if hook failed */
+    error?: string;
+}
+/** The 5 hook types */
+export type HookType = 'command' | 'prompt' | 'agent' | 'http' | 'ts';
+/** Hook definition in hooks.json */
+export interface HookDefinition {
+    /** Which event path to match. Supports wildcards: Pre:tool:* */
+    match: string;
+    /** Further filter within the match (e.g., specific tool name) */
+    matcher?: string;
+    /** Hook type */
+    type: HookType;
+    /** For command hooks: shell command to execute */
+    command?: string;
+    /** For prompt/agent hooks: the prompt text. $ARGUMENTS replaced with event JSON. */
+    prompt?: string;
+    /** For http hooks: URL to POST to */
+    url?: string;
+    /** For ts hooks: path to TypeScript file */
+    path?: string;
+    /** For http hooks: custom headers */
+    headers?: Record<string, string>;
+    /** For prompt/agent hooks: LLM model to use */
+    model?: string;
+    /** Timeout in seconds (default: 30 for command/prompt/http, 60 for agent) */
+    timeout?: number;
+    /** Custom status message shown while hook runs */
+    statusMessage?: string;
+    /** Run in background without blocking */
+    async?: boolean;
+    /** Run once then auto-remove */
+    once?: boolean;
+    /** Description for documentation */
+    description?: string;
+    /** Optional name for programmatic enable/disable/remove */
+    name?: string;
+    /** Whether the hook is enabled (default: true) */
+    enabled?: boolean;
+}
+/** Hook chain step */
+export interface ChainStep {
+    match: string;
+    capture?: Record<string, string>;
+    within?: string;
+    condition?: string;
+    optional?: boolean;
+    debounce?: string;
+}
+/** Hook chain definition */
+export interface HookChain {
+    name: string;
+    description?: string;
+    steps: ChainStep[];
+    action: HookDefinition;
+}
+/** Full hooks.json schema */
+export interface HooksConfig {
+    /** Direct hooks keyed by event path pattern */
+    hooks?: Record<string, HookDefinition[]>;
+    /** Multi-event chains */
+    chains?: HookChain[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/hooks/types.d.ts.map

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

package/dist/platform/hooks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/integrations/delivery.d.ts

@@ -0,0 +1,186 @@
+/**
+ * The three possible outcomes for a single integration delivery attempt.
+ *
+ * - `delivered`   — message reached the destination successfully
+ * - `retrying`    — delivery failed with a retryable error; queued for retry
+ * - `dead_letter` — all retry attempts exhausted or terminal failure; moved to DLQ
+ */
+export type DeliveryOutcome = 'delivered' | 'retrying' | 'dead_letter';
+/**
+ * Classification of a delivery failure.
+ *
+ * - `retryable` — transient error; should be retried with backoff
+ *   (network timeout, HTTP 429, HTTP 5xx)
+ * - `terminal`  — permanent error; should not be retried
+ *   (HTTP 400/401/403/404, invalid URL, message too large)
+ */
+export type DeliveryFailureClass = 'retryable' | 'terminal';
+/**
+ * Classify a delivery error as retryable or terminal.
+ *
+ * Rules (in order):
+ * 1. Network errors with no HTTP status → retryable (timeout, ECONNREFUSED, etc.)
+ * 2. HTTP 4xx (except 408/429) → terminal (auth failure, bad request, not found)
+ * 3. HTTP 429 / 5xx → retryable
+ * 4. Unknown → retryable (prefer retry over silent drop)
+ */
+export declare function classifyDeliveryError(error: unknown): DeliveryFailureClass;
+/** Typed delivery error that carries an explicit failure classification. */
+export declare class DeliveryError extends Error {
+    readonly failureClass: DeliveryFailureClass;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, failureClass: DeliveryFailureClass, statusCode?: number | undefined);
+}
+/**
+ * A single entry in the dead-letter queue.
+ * Immutable snapshot of a delivery that exhausted all retry attempts.
+ */
+export interface DeadLetterEntry {
+    /** Unique entry identifier. */
+    readonly id: string;
+    /** Integration channel (e.g. "slack", "discord", "webhook"). */
+    readonly channel: string;
+    /** Event name that triggered the delivery. */
+    readonly event: string;
+    /** Message payload that failed to deliver. */
+    readonly payload: string;
+    /** Epoch ms when the entry was created (first attempt). */
+    readonly createdAt: number;
+    /** Epoch ms when the entry moved to the DLQ. */
+    readonly deadAt: number;
+    /** Number of delivery attempts made. */
+    readonly attempts: number;
+    /** Final error message. */
+    readonly finalError: string;
+    /** Failure class of the final error. */
+    readonly failureClass: DeliveryFailureClass;
+}
+/** Counters for delivery SLO tracking. */
+export interface DeliveryMetrics {
+    /** Total delivery attempts (all channels combined). */
+    readonly totalAttempts: number;
+    /** Successfully delivered messages. */
+    readonly delivered: number;
+    /** Messages currently queued for retry. */
+    readonly retrying: number;
+    /** Messages moved to the dead-letter queue. */
+    readonly deadLettered: number;
+    /** Total entries in the DLQ (including previously replayed). */
+    readonly dlqSize: number;
+}
+/** Configuration for the DeliveryQueue. */
+export interface DeliveryQueueConfig {
+    /**
+     * Maximum retry attempts after the initial delivery attempt.
+     * E.g., maxRetries: 3 means 4 total attempts (1 initial + 3 retries).
+     */
+    maxRetries: number;
+    /** Initial backoff delay in ms (default: 1000). */
+    initialDelayMs: number;
+    /** Maximum backoff delay in ms (default: 30_000). */
+    maxDelayMs: number;
+    /** Maximum dead-letter queue size; oldest entries evicted when exceeded (default: 500). */
+    maxDlqSize: number;
+    /**
+     * When true, SLO enforcement is active: dead-letter events are logged at
+     * error level and metrics are updated. When false, failures are logged at
+     * warn level only.
+     *
+     * Controlled by the `integration-delivery-slo` feature flag.
+     */
+    sloEnforced: boolean;
+}
+/**
+ * Delivery queue with retry/backoff and dead-letter storage.
+ *
+ * Wrap any integration send operation with `enqueue()`. The queue:
+ *  1. Attempts delivery immediately.
+ *  2. On retryable failure: schedules retry with exponential backoff + jitter.
+ *  3. On terminal failure or exhausted retries: moves entry to DLQ.
+ *  4. Emits `delivery:dead_letter` events to registered listeners.
+ *
+ * Dead-letter entries can be replayed via `replay()` or cleared with `clearDlq()`.
+ *
+ * Enable SLO enforcement via the `integration-delivery-slo` feature flag to
+ * surface dead-letter failures as error-level log entries and expose them in
+ * integration diagnostics.
+ */
+export declare class DeliveryQueue {
+    private readonly _config;
+    private readonly _dlq;
+    private readonly _pending;
+    private readonly _timers;
+    private readonly _listeners;
+    private _totalAttempts;
+    private _delivered;
+    private _retrying;
+    private _deadLettered;
+    constructor(config?: Partial<DeliveryQueueConfig>);
+    /**
+     * Enqueue a delivery attempt.
+     *
+     * @param channel - Integration channel identifier (e.g. "slack").
+     * @param event   - Event name for tracing.
+     * @param payload - Message text to deliver.
+     * @param deliver - Async function that performs the actual delivery.
+     * @returns The delivery outcome for the immediate attempt.
+     */
+    enqueue(channel: string, event: string, payload: string, deliver: () => Promise<void>): Promise<DeliveryOutcome>;
+    /**
+     * Replay all dead-letter entries.
+     *
+     * Each entry is re-enqueued with a fresh retry budget. The DLQ is cleared
+     * on a per-entry basis as each replayed entry resolves.
+     *
+     * @param deliver - Optional delivery function override. When omitted,
+     *   the original delivery function is not available (DLQ is persistent
+     *   storage), so a no-op is used and the caller must provide one.
+     *
+     * @returns Array of per-entry replay results.
+     */
+    replay(deliver: (entry: DeadLetterEntry) => Promise<void>): Promise<Array<{
+        id: string;
+        outcome: DeliveryOutcome;
+    }>>;
+    /**
+     * Register a listener invoked whenever an entry moves to the DLQ.
+     * Returns an unsubscribe function.
+     */
+    onDeadLetter(listener: (entry: DeadLetterEntry) => void): () => void;
+    /** Get current dead-letter queue contents (snapshot). */
+    getDlq(): readonly DeadLetterEntry[];
+    /** Clear all dead-letter entries. */
+    clearDlq(): number;
+    /** Whether SLO enforcement is active for this queue. */
+    get sloEnforced(): boolean;
+    /** Current delivery metrics snapshot. */
+    getMetrics(): DeliveryMetrics;
+    /**
+     * Cancel all pending retry timers and clear internal state.
+     * Call on shutdown to prevent timer leaks.
+     */
+    dispose(): void;
+    private _attempt;
+    private _moveToDlq;
+    private _computeDelay;
+}
+/**
+ * Snapshot of a DeliveryQueue for display in integration diagnostics.
+ */
+export interface IntegrationQueueStatus {
+    /** Integration channel identifier. */
+    readonly channel: string;
+    /** Current delivery metrics. */
+    readonly metrics: DeliveryMetrics;
+    /** Dead-letter entries (most recent first, capped at 50 for display). */
+    readonly dlqEntries: readonly DeadLetterEntry[];
+    /** Whether SLO enforcement is active. */
+    readonly sloEnforced: boolean;
+    /** Epoch ms of this snapshot. */
+    readonly capturedAt: number;
+}
+/**
+ * Produce a diagnostics snapshot for a channel's DeliveryQueue.
+ */
+export declare function snapshotQueueStatus(channel: string, queue: DeliveryQueue, sloEnforced: boolean): IntegrationQueueStatus;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/platform/integrations/delivery.d.ts.map

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

package/dist/platform/integrations/delivery.js

@@ -0,0 +1,311 @@
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+// ---------------------------------------------------------------------------
+// Failure classification
+// ---------------------------------------------------------------------------
+/** HTTP status codes that indicate a retryable transient failure. */
+const DELIVERY_RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Classify a delivery error as retryable or terminal.
+ *
+ * Rules (in order):
+ * 1. Network errors with no HTTP status → retryable (timeout, ECONNREFUSED, etc.)
+ * 2. HTTP 4xx (except 408/429) → terminal (auth failure, bad request, not found)
+ * 3. HTTP 429 / 5xx → retryable
+ * 4. Unknown → retryable (prefer retry over silent drop)
+ */
+export function classifyDeliveryError(error) {
+    if (error instanceof DeliveryError) {
+        return error.failureClass;
+    }
+    if (error instanceof Error) {
+        const msg = error.message.toLowerCase();
+        // HTTP status in message (e.g. "HTTP 400: bad request")
+        const match = /http\s+(\d{3})/.exec(msg);
+        if (match) {
+            const status = parseInt(match[1], 10);
+            return DELIVERY_RETRYABLE_STATUSES.has(status) ? 'retryable' : 'terminal';
+        }
+        // Network-level errors: timeout, connection refused, DNS failure
+        if (msg.includes('timeout') ||
+            msg.includes('aborted') ||
+            msg.includes('econnrefused') ||
+            msg.includes('enotfound') ||
+            msg.includes('network')) {
+            return 'retryable';
+        }
+        // TypeError for invalid URL or fetch misconfiguration
+        if (error instanceof TypeError) {
+            return 'terminal';
+        }
+    }
+    // Default: retryable (never silently drop)
+    return 'retryable';
+}
+// ---------------------------------------------------------------------------
+// DeliveryError — typed error with explicit classification
+// ---------------------------------------------------------------------------
+/** Typed delivery error that carries an explicit failure classification. */
+export class DeliveryError extends Error {
+    failureClass;
+    statusCode;
+    constructor(message, failureClass, statusCode) {
+        super(message);
+        this.failureClass = failureClass;
+        this.statusCode = statusCode;
+        this.name = 'DeliveryError';
+    }
+}
+const DEFAULT_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 1_000,
+    maxDelayMs: 30_000,
+    maxDlqSize: 500,
+    sloEnforced: false,
+};
+// ---------------------------------------------------------------------------
+// DeliveryQueue
+// ---------------------------------------------------------------------------
+/**
+ * Delivery queue with retry/backoff and dead-letter storage.
+ *
+ * Wrap any integration send operation with `enqueue()`. The queue:
+ *  1. Attempts delivery immediately.
+ *  2. On retryable failure: schedules retry with exponential backoff + jitter.
+ *  3. On terminal failure or exhausted retries: moves entry to DLQ.
+ *  4. Emits `delivery:dead_letter` events to registered listeners.
+ *
+ * Dead-letter entries can be replayed via `replay()` or cleared with `clearDlq()`.
+ *
+ * Enable SLO enforcement via the `integration-delivery-slo` feature flag to
+ * surface dead-letter failures as error-level log entries and expose them in
+ * integration diagnostics.
+ */
+export class DeliveryQueue {
+    _config;
+    _dlq = [];
+    _pending = new Map();
+    _timers = new Map();
+    _listeners = new Set();
+    // Metrics counters
+    _totalAttempts = 0;
+    _delivered = 0;
+    _retrying = 0;
+    _deadLettered = 0;
+    constructor(config = {}) {
+        this._config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Enqueue a delivery attempt.
+     *
+     * @param channel - Integration channel identifier (e.g. "slack").
+     * @param event   - Event name for tracing.
+     * @param payload - Message text to deliver.
+     * @param deliver - Async function that performs the actual delivery.
+     * @returns The delivery outcome for the immediate attempt.
+     */
+    async enqueue(channel, event, payload, deliver) {
+        const id = `${channel}:${event}:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
+        const entry = {
+            id,
+            channel,
+            event,
+            payload,
+            createdAt: Date.now(),
+            attempts: 0,
+            nextAttemptAt: 0,
+            deliver,
+        };
+        this._pending.set(id, entry);
+        return this._attempt(entry);
+    }
+    /**
+     * Replay all dead-letter entries.
+     *
+     * Each entry is re-enqueued with a fresh retry budget. The DLQ is cleared
+     * on a per-entry basis as each replayed entry resolves.
+     *
+     * @param deliver - Optional delivery function override. When omitted,
+     *   the original delivery function is not available (DLQ is persistent
+     *   storage), so a no-op is used and the caller must provide one.
+     *
+     * @returns Array of per-entry replay results.
+     */
+    async replay(deliver) {
+        const entries = [...this._dlq];
+        const results = [];
+        for (const dlqEntry of entries) {
+            // Remove from DLQ before replaying
+            const idx = this._dlq.findIndex((e) => e.id === dlqEntry.id);
+            if (idx !== -1)
+                this._dlq.splice(idx, 1);
+            this._deadLettered = Math.max(0, this._deadLettered - 1);
+            const outcome = await this.enqueue(dlqEntry.channel, dlqEntry.event, dlqEntry.payload, () => deliver(dlqEntry));
+            results.push({ id: dlqEntry.id, outcome });
+        }
+        return results;
+    }
+    /**
+     * Register a listener invoked whenever an entry moves to the DLQ.
+     * Returns an unsubscribe function.
+     */
+    onDeadLetter(listener) {
+        this._listeners.add(listener);
+        return () => this._listeners.delete(listener);
+    }
+    /** Get current dead-letter queue contents (snapshot). */
+    getDlq() {
+        return [...this._dlq];
+    }
+    /** Clear all dead-letter entries. */
+    clearDlq() {
+        const count = this._dlq.length;
+        this._dlq.length = 0;
+        return count;
+    }
+    /** Whether SLO enforcement is active for this queue. */
+    get sloEnforced() { return this._config.sloEnforced; }
+    /** Current delivery metrics snapshot. */
+    getMetrics() {
+        return {
+            totalAttempts: this._totalAttempts,
+            delivered: this._delivered,
+            retrying: this._retrying,
+            deadLettered: this._deadLettered,
+            dlqSize: this._dlq.length,
+        };
+    }
+    /**
+     * Cancel all pending retry timers and clear internal state.
+     * Call on shutdown to prevent timer leaks.
+     */
+    dispose() {
+        for (const timer of this._timers.values()) {
+            clearTimeout(timer);
+        }
+        this._timers.clear();
+        this._pending.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Internal retry logic
+    // -------------------------------------------------------------------------
+    async _attempt(entry) {
+        entry.attempts += 1;
+        this._totalAttempts += 1;
+        try {
+            await entry.deliver();
+            this._delivered += 1;
+            if (entry.attempts > 1)
+                this._retrying = Math.max(0, this._retrying - 1);
+            this._pending.delete(entry.id);
+            logger.debug('DeliveryQueue: delivered', {
+                channel: entry.channel,
+                event: entry.event,
+                attempts: entry.attempts,
+            });
+            return 'delivered';
+        }
+        catch (err) {
+            const errorMsg = summarizeError(err);
+            const failureClass = classifyDeliveryError(err);
+            if (failureClass === 'terminal' || entry.attempts > this._config.maxRetries) {
+                return this._moveToDlq(entry, errorMsg, failureClass);
+            }
+            // Schedule retry
+            const delayMs = this._computeDelay(entry.attempts);
+            entry.nextAttemptAt = Date.now() + delayMs;
+            this._retrying += 1;
+            logger.warn('DeliveryQueue: retrying', {
+                channel: entry.channel,
+                event: entry.event,
+                attempt: entry.attempts,
+                maxRetries: this._config.maxRetries,
+                delayMs,
+                error: errorMsg,
+                failureClass,
+            });
+            const timer = setTimeout(() => {
+                this._timers.delete(entry.id);
+                this._retrying = Math.max(0, this._retrying - 1);
+                // Fire-and-forget; outcome tracked via metrics
+                void this._attempt(entry);
+            }, delayMs);
+            this._timers.set(entry.id, timer);
+            return 'retrying';
+        }
+    }
+    _moveToDlq(entry, finalError, failureClass) {
+        const dlqEntry = {
+            id: entry.id,
+            channel: entry.channel,
+            event: entry.event,
+            payload: entry.payload,
+            createdAt: entry.createdAt,
+            deadAt: Date.now(),
+            attempts: entry.attempts,
+            finalError,
+            failureClass,
+        };
+        // Bounded DLQ: evict oldest entry when limit exceeded
+        if (this._dlq.length >= this._config.maxDlqSize) {
+            this._dlq.shift();
+            this._deadLettered = Math.max(0, this._deadLettered - 1);
+        }
+        this._dlq.push(dlqEntry);
+        this._deadLettered += 1;
+        this._pending.delete(entry.id);
+        if (this._config.sloEnforced) {
+            logger.error('DeliveryQueue: dead-lettered (SLO violated)', {
+                id: dlqEntry.id,
+                channel: dlqEntry.channel,
+                event: dlqEntry.event,
+                attempts: dlqEntry.attempts,
+                finalError: dlqEntry.finalError,
+                failureClass: dlqEntry.failureClass,
+            });
+        }
+        else {
+            logger.warn('DeliveryQueue: dead-lettered', {
+                id: dlqEntry.id,
+                channel: dlqEntry.channel,
+                event: dlqEntry.event,
+                attempts: dlqEntry.attempts,
+                finalError: dlqEntry.finalError,
+                failureClass: dlqEntry.failureClass,
+            });
+        }
+        for (const listener of this._listeners) {
+            try {
+                listener(dlqEntry);
+            }
+            catch (err) {
+                logger.debug('[delivery] listener error:', {
+                    error: summarizeError(err),
+                    entryId: dlqEntry.id,
+                });
+            }
+        }
+        return 'dead_letter';
+    }
+    _computeDelay(attempt) {
+        const exponential = this._config.initialDelayMs * Math.pow(2, attempt - 1);
+        const jitter = Math.random() * this._config.initialDelayMs * 0.5;
+        return Math.min(exponential + jitter, this._config.maxDelayMs);
+    }
+}
+/**
+ * Produce a diagnostics snapshot for a channel's DeliveryQueue.
+ */
+export function snapshotQueueStatus(channel, queue, sloEnforced) {
+    const dlq = queue.getDlq();
+    return {
+        channel,
+        metrics: queue.getMetrics(),
+        dlqEntries: [...dlq].reverse().slice(0, 50),
+        sloEnforced,
+        capturedAt: Date.now(),
+    };
+}