@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/input/keybindings.js

@@ -0,0 +1,202 @@
+/**
+ * KeybindingsManager — loads and merges keyboard shortcut configuration.
+ *
+ * Default bindings are hardcoded here. Users can override any binding by
+ * creating ~/.goodvibes/goodvibes/keybindings.json.
+ *
+ * Config file format example:
+ * {
+ *   "search": { "key": "g", "ctrl": true },
+ *   "block-copy": { "key": "c", "ctrl": true, "alt": true }
+ * }
+ *
+ * Each value is a KeyCombo or an array of KeyCombos for multi-binding support.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+/** Human-readable description for each action (used in /keybindings display). */
+export const ACTION_DESCRIPTIONS = {
+    'copy-selection': 'Copy selected text to clipboard',
+    'clear-cancel': 'Clear input / cancel generation / exit (double)',
+    'screen-clear': 'Repaint the screen',
+    'panel-picker': 'Open, focus, or hide the panel workspace',
+    'panel-close': 'Close the currently active panel',
+    'panel-close-all': 'Close all open panels',
+    'panel-tab-next': 'Next workspace panel tab',
+    'panel-tab-prev': 'Previous workspace panel tab',
+    'history-search': 'Reverse input history search',
+    'search': 'Toggle conversation search',
+    'block-copy': 'Copy nearest block to clipboard',
+    'bookmark': 'Bookmark / unbookmark nearest block',
+    'block-save': 'Save nearest block to file',
+    'delete-word': 'Delete word backward',
+    'apply-diff-line-start': 'Apply nearest diff / move to line start',
+    'next-error-line-end': 'Navigate to next error / move to line end',
+    'kill-line': 'Kill to end of line',
+    'clear-prompt': 'Clear the prompt',
+    'undo': 'Undo last prompt edit',
+    'redo': 'Redo last undone edit',
+    'paste': 'Paste from clipboard (image priority)',
+    'replay-panel': 'Open / close the Replay panel',
+};
+/** Default key bindings for all actions. */
+export const DEFAULT_KEYBINDINGS = {
+    'copy-selection': [{ key: 'c', ctrl: true, shift: true }],
+    'clear-cancel': [{ key: 'c', ctrl: true }],
+    'screen-clear': [{ key: 'l', ctrl: true }],
+    'panel-picker': [{ key: 'p', ctrl: true }],
+    'panel-close': [{ key: 'x', ctrl: true }],
+    'panel-close-all': [{ key: 'x', ctrl: true, shift: true }],
+    'panel-tab-next': [{ key: ']', ctrl: true }],
+    'panel-tab-prev': [{ key: '[', ctrl: true }],
+    'history-search': [{ key: 'r', ctrl: true }],
+    'search': [{ key: 'f', ctrl: true }],
+    'block-copy': [{ key: 'y', ctrl: true }],
+    'bookmark': [{ key: 'b', ctrl: true }],
+    'block-save': [{ key: 's', ctrl: true }],
+    'delete-word': [{ key: 'w', ctrl: true }],
+    'apply-diff-line-start': [{ key: 'a', ctrl: true }],
+    'next-error-line-end': [{ key: 'e', ctrl: true }],
+    'kill-line': [{ key: 'k', ctrl: true }],
+    'clear-prompt': [{ key: 'u', ctrl: true }],
+    'undo': [{ key: 'z', ctrl: true }],
+    'redo': [{ key: 'z', ctrl: true, shift: true }],
+    'paste': [{ key: 'v', ctrl: true }],
+    'replay-panel': [{ key: 'r', ctrl: true, shift: true }],
+};
+function resolveKeybindingsPath(options) {
+    if (options?.configPath) {
+        return options.configPath;
+    }
+    const userRoot = options?.userRoot ?? options?.homeDirectory;
+    if (!userRoot) {
+        throw new Error('KeybindingsManager requires configPath or an explicit userRoot/homeDirectory.');
+    }
+    return join(userRoot, '.goodvibes', 'goodvibes', 'keybindings.json');
+}
+/**
+ * KeybindingsManager — owns the resolved keybinding table.
+ *
+ * Call loadFromDisk() once at startup (in main.ts) to merge user config.
+ * Then use matches() anywhere a key token is being evaluated.
+ */
+export class KeybindingsManager {
+    bindings;
+    configPath;
+    constructor(options) {
+        this.configPath = resolveKeybindingsPath(options);
+        // Start with deep copy of defaults
+        this.bindings = this.cloneDefaults();
+    }
+    cloneDefaults() {
+        const result = {};
+        for (const [action, combos] of Object.entries(DEFAULT_KEYBINDINGS)) {
+            result[action] = combos.map(c => ({ ...c }));
+        }
+        return result;
+    }
+    /**
+     * Load user overrides from disk and merge into the binding table.
+     * Unknown actions are ignored with a debug log. Malformed entries are skipped.
+     * Safe to call multiple times (reloads on each call).
+     */
+    loadFromDisk() {
+        if (!existsSync(this.configPath))
+            return;
+        try {
+            const raw = readFileSync(this.configPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            const validActions = new Set(Object.keys(DEFAULT_KEYBINDINGS));
+            // Reset to defaults before applying overrides
+            this.bindings = this.cloneDefaults();
+            for (const [action, combo] of Object.entries(parsed)) {
+                if (!validActions.has(action)) {
+                    logger.debug('keybindings: unknown action, skipping', { action });
+                    continue;
+                }
+                const normalized = Array.isArray(combo) ? combo : [combo];
+                if (!this.validateCombos(normalized)) {
+                    logger.debug('keybindings: invalid combo for action, skipping', { action, combo });
+                    continue;
+                }
+                this.bindings[action] = normalized;
+            }
+            logger.debug('keybindings: loaded overrides from disk', { path: this.configPath });
+        }
+        catch (err) {
+            logger.debug('keybindings: failed to load config file', { path: this.configPath, err: summarizeError(err) });
+        }
+    }
+    validateCombos(combos) {
+        return combos.every((c) => {
+            if (typeof c !== 'object' || c === null)
+                return false;
+            const combo = c;
+            return typeof combo['key'] === 'string' && combo['key'].length > 0;
+        });
+    }
+    /**
+     * matches — Check whether a keyboard token matches the given action.
+     *
+     * @param action  The action to test.
+     * @param token   The parsed keyboard token from InputTokenizer.
+     *                Expects: { logicalName: string; ctrl?: boolean; shift?: boolean; alt?: boolean }
+     */
+    matches(action, token) {
+        const combos = this.bindings[action];
+        if (!combos)
+            return false;
+        return combos.some((combo) => this.comboMatches(combo, token));
+    }
+    comboMatches(combo, token) {
+        if (token.logicalName !== combo.key)
+            return false;
+        if (!!combo.ctrl !== !!token.ctrl)
+            return false;
+        if (!!combo.shift !== !!token.shift)
+            return false;
+        if (!!combo.alt !== !!token.alt)
+            return false;
+        return true;
+    }
+    /**
+     * getAll — Return the full resolved binding table for display purposes.
+     */
+    getAll() {
+        return Object.keys(this.bindings).map((action) => ({
+            action,
+            combos: this.bindings[action],
+            description: ACTION_DESCRIPTIONS[action],
+        }));
+    }
+    /**
+     * getComboLabel — Return a human-readable label for the first combo of an action.
+     * Example: { key: 'f', ctrl: true } → "Ctrl+F"
+     */
+    getComboLabel(action) {
+        const combos = this.bindings[action];
+        if (!combos?.length)
+            return '(unbound)';
+        return this.formatCombo(combos[0]);
+    }
+    /**
+     * formatCombo — Format a KeyCombo as a human-readable string.
+     */
+    formatCombo(combo) {
+        const parts = [];
+        if (combo.ctrl)
+            parts.push('Ctrl');
+        if (combo.alt)
+            parts.push('Alt');
+        if (combo.shift)
+            parts.push('Shift');
+        parts.push(combo.key.length === 1 ? combo.key.toUpperCase() : combo.key);
+        return parts.join('+');
+    }
+    /** Return the config file path. */
+    getConfigPath() {
+        return this.configPath;
+    }
+}

package/dist/_internal/platform/integrations/index.d.ts

@@ -0,0 +1,13 @@
+export { SlackIntegration, SlackSocketModeClient } from '@pellux/goodvibes-sdk/platform/integrations/slack';
+export type { SlackAuthTestResult, SlackConversationRecord, SlackCursorPage, SlackEvent, SlackEventCallback, SlackInteraction, SlackOAuthAuthorizeOptions, SlackOAuthExchangeOptions, SlackOAuthExchangeResult, SlackSlashCommand, SlackSocketModeConnection, SlackSocketModeEnvelope, SlackSocketModeClientOptions, SlackUserRecord, } from '@pellux/goodvibes-sdk/platform/integrations/slack';
+export { DiscordGatewayClient, DiscordGatewayIntent, DiscordGatewayOpcode, DiscordIntegration } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+export type { DiscordApplicationCommand, DiscordApplicationCommandOption, DiscordGatewayBotResponse, DiscordGatewayClientOptions, DiscordGatewayDispatch, DiscordInteraction, DiscordOAuthAuthorizeOptions, } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+export { DiscordInteractionType, DiscordInteractionResponseType } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+export { Notifier } from './notifier.js';
+export { GitHubIntegration } from '@pellux/goodvibes-sdk/platform/integrations/github';
+export type { GitHubWebhookEvent } from '@pellux/goodvibes-sdk/platform/integrations/github';
+export { DeliveryQueue, DeliveryError, classifyDeliveryError, snapshotQueueStatus } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+export { NtfyIntegration } from '@pellux/goodvibes-sdk/platform/integrations/ntfy';
+export type { DeliveryOutcome, DeliveryFailureClass, DeadLetterEntry, DeliveryMetrics, DeliveryQueueConfig, IntegrationQueueStatus, } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+export type { NtfyMessage, NtfyPublishOptions, NtfySubscribeOptions, NtfyWebSocketOptions } from '@pellux/goodvibes-sdk/platform/integrations/ntfy';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/integrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/integrations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAC;AAC5G,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,eAAe,GAChB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AAC3J,YAAY,EACV,yBAAyB,EACzB,+BAA+B,EAC/B,yBAAyB,EACzB,2BAA2B,EAC3B,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,8BAA8B,EAAE,MAAM,qDAAqD,CAAC;AAC7H,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oDAAoD,CAAC;AACvF,YAAY,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,sDAAsD,CAAC;AAChJ,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sDAAsD,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAC"}

package/dist/_internal/platform/integrations/index.js

@@ -0,0 +1,7 @@
+export { SlackIntegration, SlackSocketModeClient } from '@pellux/goodvibes-sdk/platform/integrations/slack';
+export { DiscordGatewayClient, DiscordGatewayIntent, DiscordGatewayOpcode, DiscordIntegration } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+export { DiscordInteractionType, DiscordInteractionResponseType } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+export { Notifier } from './notifier.js';
+export { GitHubIntegration } from '@pellux/goodvibes-sdk/platform/integrations/github';
+export { DeliveryQueue, DeliveryError, classifyDeliveryError, snapshotQueueStatus } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+export { NtfyIntegration } from '@pellux/goodvibes-sdk/platform/integrations/ntfy';

package/dist/_internal/platform/integrations/notifier.d.ts

@@ -0,0 +1,56 @@
+import type { RuntimeEventBus } from '../runtime/events/index.js';
+import { SlackIntegration } from '@pellux/goodvibes-sdk/platform/integrations/slack';
+import { DiscordIntegration } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+import type { DeliveryQueueConfig, IntegrationQueueStatus } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+import { ServiceRegistry } from '../config/service-registry.js';
+/**
+ * Notifier — unified notification dispatcher.
+ *
+ * Reads configuration from environment variables:
+ *   SLACK_WEBHOOK_URL, SLACK_BOT_TOKEN
+ *   DISCORD_WEBHOOK_URL, DISCORD_BOT_TOKEN
+ *
+ * Attach to the RuntimeEventBus to automatically post notifications for key events.
+ */
+export declare class Notifier {
+    private slack?;
+    private discord?;
+    private unsubscribers;
+    private readonly _queue;
+    constructor(options?: {
+        slack?: SlackIntegration;
+        discord?: DiscordIntegration;
+        delivery?: Partial<DeliveryQueueConfig>;
+    });
+    /**
+     * Create a Notifier pre-wired from configured services and environment variables.
+     */
+    static fromConfig(serviceRegistry: Pick<ServiceRegistry, 'resolveSecret'>): Promise<Notifier>;
+    /**
+     * Send a notification to all configured channels.
+     *
+     * @param event  - Human-readable event name (used as message text)
+     * @param data   - Arbitrary key/value payload for formatting
+     */
+    notify(event: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get delivery queue status snapshots for all active channels.
+     * Used by integration diagnostics to surface queue and DLQ state.
+     */
+    getQueueStatus(): IntegrationQueueStatus[];
+    /**
+     * Replay all dead-letter entries to their respective channels.
+     * Re-attempts delivery for each DLQ entry; results are returned per-entry.
+     */
+    replayDeadLetters(): Promise<Array<{
+        id: string;
+        outcome: import('@pellux/goodvibes-sdk/platform/integrations/delivery').DeliveryOutcome;
+    }>>;
+    /** Dispose the delivery queue (cancel pending timers). Call on shutdown. */
+    dispose(): void;
+    attachToRuntimeBus(bus: RuntimeEventBus): void;
+    /** Remove all notification subscriptions. */
+    detach(): void;
+    private formatText;
+}
+//# sourceMappingURL=notifier.d.ts.map

package/dist/_internal/platform/integrations/notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifier.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/integrations/notifier.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,4BAA4B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qDAAqD,CAAC;AAEzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAExH,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAMhE;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAC,CAAmB;IACjC,OAAO,CAAC,OAAO,CAAC,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,OAAO,CAAC,EAAE;QACpB,KAAK,CAAC,EAAE,gBAAgB,CAAC;QACzB,OAAO,CAAC,EAAE,kBAAkB,CAAC;QAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;KACzC;IAMD;;OAEG;WACU,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmCnG;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;;OAGG;IACH,cAAc,IAAI,sBAAsB,EAAE;IAY1C;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,sDAAsD,EAAE,eAAe,CAAA;KAAE,CAAC,CAAC;IAalJ,4EAA4E;IAC5E,OAAO,IAAI,IAAI;IAIf,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAoC9C,6CAA6C;IAC7C,MAAM,IAAI,IAAI;IAWd,OAAO,CAAC,UAAU;CAuBnB"}

package/dist/_internal/platform/integrations/notifier.js

@@ -0,0 +1,166 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { SlackIntegration } from '@pellux/goodvibes-sdk/platform/integrations/slack';
+import { DiscordIntegration } from '@pellux/goodvibes-sdk/platform/integrations/discord';
+import { DeliveryQueue } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+import { snapshotQueueStatus } from '@pellux/goodvibes-sdk/platform/integrations/delivery';
+import { ServiceRegistry } from '../config/service-registry.js';
+// ---------------------------------------------------------------------------
+// Notifier
+// ---------------------------------------------------------------------------
+/**
+ * Notifier — unified notification dispatcher.
+ *
+ * Reads configuration from environment variables:
+ *   SLACK_WEBHOOK_URL, SLACK_BOT_TOKEN
+ *   DISCORD_WEBHOOK_URL, DISCORD_BOT_TOKEN
+ *
+ * Attach to the RuntimeEventBus to automatically post notifications for key events.
+ */
+export class Notifier {
+    slack;
+    discord;
+    unsubscribers = [];
+    _queue;
+    constructor(options) {
+        this.slack = options?.slack;
+        this.discord = options?.discord;
+        this._queue = new DeliveryQueue(options?.delivery ?? {});
+    }
+    /**
+     * Create a Notifier pre-wired from configured services and environment variables.
+     */
+    static async fromConfig(serviceRegistry) {
+        const [slackWebhookFromService, slackTokenFromService, discordWebhookFromService, discordTokenFromService,] = await Promise.all([
+            serviceRegistry.resolveSecret('slack', 'webhookUrl'),
+            serviceRegistry.resolveSecret('slack', 'primary'),
+            serviceRegistry.resolveSecret('discord', 'webhookUrl'),
+            serviceRegistry.resolveSecret('discord', 'primary'),
+        ]);
+        const slackWebhook = slackWebhookFromService ?? process.env.SLACK_WEBHOOK_URL;
+        const slackToken = slackTokenFromService ?? process.env.SLACK_BOT_TOKEN;
+        const discordWebhook = discordWebhookFromService ?? process.env.DISCORD_WEBHOOK_URL;
+        const discordToken = discordTokenFromService ?? process.env.DISCORD_BOT_TOKEN;
+        const slack = slackWebhook || slackToken
+            ? new SlackIntegration(slackWebhook, slackToken)
+            : undefined;
+        const discord = discordWebhook || discordToken
+            ? new DiscordIntegration(discordWebhook, discordToken)
+            : undefined;
+        return new Notifier({ slack, discord });
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Send a notification to all configured channels.
+     *
+     * @param event  - Human-readable event name (used as message text)
+     * @param data   - Arbitrary key/value payload for formatting
+     */
+    async notify(event, data) {
+        const text = this.formatText(event, data);
+        if (this.slack) {
+            const slack = this.slack;
+            await this._queue.enqueue('slack', event, text, () => slack.postWebhook(text));
+        }
+        if (this.discord) {
+            const discord = this.discord;
+            await this._queue.enqueue('discord', event, text, () => discord.postWebhook(text));
+        }
+    }
+    /**
+     * Get delivery queue status snapshots for all active channels.
+     * Used by integration diagnostics to surface queue and DLQ state.
+     */
+    getQueueStatus() {
+        const sloEnforced = this._queue.sloEnforced;
+        const statuses = [];
+        if (this.slack) {
+            statuses.push(snapshotQueueStatus('slack', this._queue, sloEnforced));
+        }
+        if (this.discord) {
+            statuses.push(snapshotQueueStatus('discord', this._queue, sloEnforced));
+        }
+        return statuses;
+    }
+    /**
+     * Replay all dead-letter entries to their respective channels.
+     * Re-attempts delivery for each DLQ entry; results are returned per-entry.
+     */
+    async replayDeadLetters() {
+        return this._queue.replay(async (dlqEntry) => {
+            const text = dlqEntry.payload;
+            if (dlqEntry.channel === 'slack' && this.slack) {
+                await this.slack.postWebhook(text);
+            }
+            else if (dlqEntry.channel === 'discord' && this.discord) {
+                await this.discord.postWebhook(text);
+            }
+            else {
+                throw new Error(`No active integration for channel: ${dlqEntry.channel}`);
+            }
+        });
+    }
+    /** Dispose the delivery queue (cancel pending timers). Call on shutdown. */
+    dispose() {
+        this._queue.dispose();
+    }
+    attachToRuntimeBus(bus) {
+        this.detach();
+        this.unsubscribers.push(bus.on('AGENT_COMPLETED', ({ payload }) => {
+            void this.notify('AGENT_COMPLETED', {
+                event: 'AGENT_COMPLETED',
+                agentId: payload.agentId,
+                task: payload.output?.slice(0, 100) ?? payload.agentId,
+                result: payload.output,
+            });
+        }));
+        this.unsubscribers.push(bus.on('WORKFLOW_CHAIN_PASSED', ({ payload }) => {
+            void this.notify('WORKFLOW_CHAIN_PASSED', {
+                event: 'WORKFLOW_CHAIN_PASSED',
+                chainId: payload.chainId,
+            });
+        }));
+        this.unsubscribers.push(bus.on('WORKFLOW_CHAIN_FAILED', ({ payload }) => {
+            void this.notify('WORKFLOW_CHAIN_FAILED', {
+                event: 'WORKFLOW_CHAIN_FAILED',
+                chainId: payload.chainId,
+                reason: payload.reason,
+            });
+        }));
+        logger.info('Notifier: attached to RuntimeEventBus');
+    }
+    /** Remove all notification subscriptions. */
+    detach() {
+        for (const unsub of this.unsubscribers) {
+            unsub();
+        }
+        this.unsubscribers = [];
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    formatText(event, data) {
+        switch (event) {
+            case 'AGENT_COMPLETED': {
+                const task = typeof data.task === 'string' ? data.task : String(data.agentId ?? '');
+                return `Agent completed: ${task}`;
+            }
+            case 'WORKFLOW_CHAIN_PASSED': {
+                const score = typeof data.score === 'number' ? `${data.score}/10` : 'passed';
+                return `Review passed: ${score}`;
+            }
+            case 'WORKFLOW_CHAIN_FAILED': {
+                const reason = typeof data.reason === 'string' ? data.reason : 'unknown reason';
+                return `Review chain failed: ${reason}`;
+            }
+            default: {
+                const extras = Object.entries(data)
+                    .filter(([k]) => k !== 'event')
+                    .map(([k, v]) => `${k}=${String(v)}`)
+                    .join(', ');
+                return extras ? `${event}: ${extras}` : event;
+            }
+        }
+    }
+}

package/dist/_internal/platform/integrations/webhooks.d.ts

@@ -0,0 +1,52 @@
+import type { RuntimeEventBus } from '../runtime/events/index.js';
+/**
+ * WebhookNotifier — sends HTTP POST notifications to configured webhook URLs.
+ *
+ * Defaults to ntfy.sh-compatible format: plain text body, no auth required.
+ * Works with any service that accepts a plain POST with a text/plain body,
+ * including ntfy.sh, generic webhooks, and custom endpoints.
+ *
+ * Usage:
+ *   const notifier = new WebhookNotifier(['https://ntfy.sh/my-topic']);
+ *   notifier.attachToRuntimeBus(runtimeBus);
+ */
+export declare class WebhookNotifier {
+    private urls;
+    private unsubscribers;
+    constructor(urls?: string[]);
+    /**
+     * Create a WebhookNotifier from a list of URLs (e.g. from persisted config).
+     */
+    static fromConfig(urls: string[]): WebhookNotifier;
+    /** Add a webhook URL. Ignores duplicates. Throws on invalid URL. */
+    addUrl(url: string): void;
+    /** Remove a webhook URL. */
+    removeUrl(url: string): boolean;
+    /** Replace all webhook URLs. */
+    setUrls(urls: string[]): void;
+    /** Get a copy of all configured webhook URLs. */
+    getUrls(): string[];
+    /** Returns true if at least one URL is configured. */
+    isConfigured(): boolean;
+    /**
+     * Send a plain-text notification to all configured webhooks.
+     *
+     * Uses ntfy.sh format by default: POST with text/plain body.
+     * All URLs are fired in parallel; individual failures are logged but do not
+     * throw — remaining URLs still receive the notification.
+     */
+    send(text: string): Promise<void>;
+    /**
+     * Send a test notification to all configured webhooks.
+     */
+    test(): Promise<{
+        url: string;
+        ok: boolean;
+        error?: string;
+    }[]>;
+    attachToRuntimeBus(bus: RuntimeEventBus): void;
+    /** Remove all webhook subscriptions. */
+    detach(): void;
+    private postOne;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/_internal/platform/integrations/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/integrations/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,4BAA4B,CAAC;AAM7F;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,aAAa,CAAyB;gBAElC,IAAI,GAAE,MAAM,EAAO;IAI/B;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe;IAQlD,oEAAoE;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQzB,4BAA4B;IAC5B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQ/B,gCAAgC;IAChC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAI7B,iDAAiD;IACjD,OAAO,IAAI,MAAM,EAAE;IAInB,sDAAsD;IACtD,YAAY,IAAI,OAAO;IAQvB;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAsBrE,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IA8B9C,wCAAwC;IACxC,MAAM,IAAI,IAAI;YAWA,OAAO;CAYtB"}

package/dist/_internal/platform/integrations/webhooks.js

@@ -0,0 +1,141 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+// ---------------------------------------------------------------------------
+// WebhookNotifier
+// ---------------------------------------------------------------------------
+/**
+ * WebhookNotifier — sends HTTP POST notifications to configured webhook URLs.
+ *
+ * Defaults to ntfy.sh-compatible format: plain text body, no auth required.
+ * Works with any service that accepts a plain POST with a text/plain body,
+ * including ntfy.sh, generic webhooks, and custom endpoints.
+ *
+ * Usage:
+ *   const notifier = new WebhookNotifier(['https://ntfy.sh/my-topic']);
+ *   notifier.attachToRuntimeBus(runtimeBus);
+ */
+export class WebhookNotifier {
+    urls;
+    unsubscribers = [];
+    constructor(urls = []) {
+        this.urls = [...urls];
+    }
+    /**
+     * Create a WebhookNotifier from a list of URLs (e.g. from persisted config).
+     */
+    static fromConfig(urls) {
+        return new WebhookNotifier(urls);
+    }
+    // -------------------------------------------------------------------------
+    // URL management
+    // -------------------------------------------------------------------------
+    /** Add a webhook URL. Ignores duplicates. Throws on invalid URL. */
+    addUrl(url) {
+        new URL(url); // throws TypeError if url is invalid
+        if (!this.urls.includes(url)) {
+            this.urls.push(url);
+            logger.info('WebhookNotifier: added URL', { url });
+        }
+    }
+    /** Remove a webhook URL. */
+    removeUrl(url) {
+        const before = this.urls.length;
+        this.urls = this.urls.filter((u) => u !== url);
+        const removed = this.urls.length < before;
+        if (removed)
+            logger.info('WebhookNotifier: removed URL', { url });
+        return removed;
+    }
+    /** Replace all webhook URLs. */
+    setUrls(urls) {
+        this.urls = [...urls];
+    }
+    /** Get a copy of all configured webhook URLs. */
+    getUrls() {
+        return [...this.urls];
+    }
+    /** Returns true if at least one URL is configured. */
+    isConfigured() {
+        return this.urls.length > 0;
+    }
+    // -------------------------------------------------------------------------
+    // Sending
+    // -------------------------------------------------------------------------
+    /**
+     * Send a plain-text notification to all configured webhooks.
+     *
+     * Uses ntfy.sh format by default: POST with text/plain body.
+     * All URLs are fired in parallel; individual failures are logged but do not
+     * throw — remaining URLs still receive the notification.
+     */
+    async send(text) {
+        if (this.urls.length === 0)
+            return;
+        const results = await Promise.allSettled(this.urls.map((url) => this.postOne(url, text)));
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            if (result.status === 'rejected') {
+                const msg = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                logger.warn('WebhookNotifier: delivery failed', { url: this.urls[i], error: msg });
+            }
+        }
+    }
+    /**
+     * Send a test notification to all configured webhooks.
+     */
+    async test() {
+        if (this.urls.length === 0)
+            return [];
+        const results = await Promise.allSettled(this.urls.map((url) => this.postOne(url, 'goodvibes-sdk: webhook test')));
+        return this.urls.map((url, i) => {
+            const result = results[i];
+            if (result.status === 'fulfilled') {
+                return { url, ok: true };
+            }
+            else {
+                const error = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                return { url, ok: false, error };
+            }
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Runtime event integration
+    // -------------------------------------------------------------------------
+    attachToRuntimeBus(bus) {
+        this.detach();
+        this.unsubscribers.push(bus.on('AGENT_COMPLETED', ({ payload }) => {
+            void this.send(`Agent completed: ${payload.agentId}`);
+        }));
+        this.unsubscribers.push(bus.on('AGENT_FAILED', ({ payload }) => {
+            void this.send(`Agent failed: ${payload.agentId} — ${payload.error}`);
+        }));
+        this.unsubscribers.push(bus.on('WORKFLOW_CHAIN_PASSED', ({ payload }) => {
+            void this.send(`WRFC passed: chain ${payload.chainId}`);
+        }));
+        this.unsubscribers.push(bus.on('WORKFLOW_CHAIN_FAILED', ({ payload }) => {
+            void this.send(`WRFC failed: ${payload.reason}`);
+        }));
+        logger.info('WebhookNotifier: attached to RuntimeEventBus', { urlCount: this.urls.length });
+    }
+    /** Remove all webhook subscriptions. */
+    detach() {
+        for (const unsub of this.unsubscribers) {
+            unsub();
+        }
+        this.unsubscribers = [];
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    async postOne(url, text) {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'text/plain' },
+            body: text,
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`HTTP ${res.status}: ${body}`);
+        }
+    }
+}