@shepai/cli 1.181.0 → 1.182.0-pr512.369be8e

package/dist/packages/core/src/infrastructure/services/messaging/messaging-tunnel.adapter.js

@@ -0,0 +1,262 @@
+/**
+ * Messaging Tunnel Adapter
+ *
+ * Manages the WebSocket tunnel connection to the Commands.com Gateway and
+ * translates its binary/text frames into a presentation-agnostic callback
+ * for the consuming messaging service.
+ *
+ * Protocol reference:
+ *   https://github.com/Commands-com/gateway/blob/main/internal/gateway/integrations_tunnel.go
+ *
+ * Responsibilities:
+ *   - Open an authenticated WebSocket (Bearer token on the upgrade headers)
+ *   - Handle tunnel.connected → auto-activate the configured routes
+ *   - Decode incoming tunnel.request frames and dispatch to `onRequest`
+ *   - Send tunnel.response frames back with the handler's reply
+ *   - Reconnect on disconnect with a small delay
+ */
+import WebSocket from 'ws';
+const RECONNECT_DELAY_MS = 5_000;
+const PING_INTERVAL_MS = 25_000;
+const defaultFactory = (url, options) => new WebSocket(url, options);
+function headersArrayToRecord(pairs) {
+    if (!pairs)
+        return {};
+    const out = {};
+    for (const [k, v] of pairs) {
+        out[k.toLowerCase()] = v;
+    }
+    return out;
+}
+function headersRecordToArray(record) {
+    if (!record)
+        return undefined;
+    return Object.entries(record);
+}
+function base64Encode(s) {
+    return Buffer.from(s, 'utf8').toString('base64');
+}
+function base64Decode(b64) {
+    return Buffer.from(b64, 'base64').toString('utf8');
+}
+export class MessagingTunnelAdapter {
+    deps;
+    ws = null;
+    requestHandler = null;
+    pingTimer = null;
+    reconnectTimer = null;
+    connected = false;
+    stopping = false;
+    activatedRoutes = new Set();
+    factory;
+    constructor(deps) {
+        this.deps = deps;
+        this.factory = deps.webSocketFactory ?? defaultFactory;
+    }
+    /** Register a handler for inbound tunnel.request frames. */
+    onRequest(handler) {
+        this.requestHandler = handler;
+    }
+    /** Whether the WebSocket tunnel is currently open. */
+    isConnected() {
+        return this.connected;
+    }
+    /** Whether the given route has been activated on the tunnel. */
+    isRouteActivated(routeId) {
+        return this.activatedRoutes.has(routeId);
+    }
+    /**
+     * Open the tunnel and resolve once the server has emitted tunnel.connected.
+     * Reconnects are silent (fire-and-forget).
+     */
+    async connect() {
+        if (this.connected || this.stopping)
+            return;
+        const base = this.deps.gatewayUrl.replace(/^http/, 'ws').replace(/\/$/, '');
+        const url = `${base}/gateway/v1/integrations/tunnel/connect?device_id=${encodeURIComponent(this.deps.deviceId)}`;
+        const ws = this.factory(url, {
+            headers: { authorization: `Bearer ${this.deps.accessToken}` },
+        });
+        this.ws = ws;
+        await new Promise((resolve, reject) => {
+            const onceOpen = () => {
+                ws.off('error', onceError);
+                resolve();
+            };
+            const onceError = (err) => {
+                ws.off('open', onceOpen);
+                reject(err);
+            };
+            ws.once('open', onceOpen);
+            ws.once('error', onceError);
+        });
+        ws.on('message', (data) => {
+            this.handleRawFrame(data).catch(() => {
+                // Malformed frames are non-fatal.
+            });
+        });
+        ws.on('close', () => this.handleClose());
+        ws.on('error', () => {
+            // Errors also trigger close; avoid duplicate handling.
+        });
+        this.connected = true;
+        this.startPing();
+    }
+    /** Close the tunnel permanently (no auto-reconnect). */
+    async disconnect() {
+        this.stopping = true;
+        this.stopPing();
+        this.clearReconnect();
+        this.activatedRoutes.clear();
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch {
+                // ignore
+            }
+            this.ws = null;
+        }
+        this.connected = false;
+    }
+    async handleRawFrame(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        switch (frame.type) {
+            case 'tunnel.connected':
+                this.handleConnected(frame);
+                return;
+            case 'tunnel.activate.result':
+                this.handleActivateResult(frame);
+                return;
+            case 'tunnel.request':
+                await this.handleRequest(frame);
+                return;
+            case 'tunnel.route_deactivated':
+                this.handleRouteDeactivated(frame);
+                return;
+            case 'tunnel.error':
+                this.handleProtocolError(frame);
+                return;
+            default:
+                // Unknown frame — silently drop per gateway forward-compat policy.
+                return;
+        }
+    }
+    handleConnected(_frame) {
+        // Auto-activate every configured route. The gateway expects a single
+        // batched frame with a `routes` array — sending one-at-a-time with
+        // `route_id` is silently ignored.
+        if (this.deps.routeIds.length === 0)
+            return;
+        this.sendFrame({
+            type: 'tunnel.activate',
+            routes: [...this.deps.routeIds],
+        });
+    }
+    handleActivateResult(frame) {
+        // Gateway returns "active" for newly-activated routes. Treat any
+        // non-rejected status as success to be forward-compatible.
+        for (const entry of frame.results ?? []) {
+            if (entry.status && entry.status !== 'rejected') {
+                this.activatedRoutes.add(entry.route_id);
+            }
+        }
+    }
+    handleRouteDeactivated(frame) {
+        this.activatedRoutes.delete(frame.route_id);
+    }
+    handleProtocolError(_frame) {
+        // No-op — recoverable errors are surfaced through reconnection.
+    }
+    async handleRequest(frame) {
+        if (!this.requestHandler) {
+            this.sendFrame({
+                type: 'tunnel.response',
+                request_id: frame.request_id,
+                status: 503,
+            });
+            return;
+        }
+        const decoded = {
+            requestId: frame.request_id,
+            routeId: frame.route_id,
+            method: frame.method,
+            path: frame.path,
+            headers: headersArrayToRecord(frame.headers),
+            body: frame.body_base64 ? base64Decode(frame.body_base64) : '',
+        };
+        let response;
+        try {
+            response = await this.requestHandler(decoded);
+        }
+        catch {
+            response = { status: 500 };
+        }
+        this.sendFrame({
+            type: 'tunnel.response',
+            request_id: frame.request_id,
+            status: response.status,
+            headers: headersRecordToArray(response.headers),
+            body_base64: response.body ? base64Encode(response.body) : undefined,
+        });
+    }
+    sendFrame(frame) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            this.ws.send(JSON.stringify(frame));
+        }
+        catch {
+            // ignore — close handler will reconnect
+        }
+    }
+    handleClose() {
+        this.connected = false;
+        this.activatedRoutes.clear();
+        this.stopPing();
+        if (!this.stopping) {
+            this.scheduleReconnect();
+        }
+    }
+    startPing() {
+        this.pingTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                try {
+                    this.ws.ping();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }, PING_INTERVAL_MS);
+        this.pingTimer.unref?.();
+    }
+    stopPing() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        this.clearReconnect();
+        this.reconnectTimer = setTimeout(() => {
+            this.connect().catch(() => {
+                // Will retry on the next close event.
+            });
+        }, RECONNECT_DELAY_MS);
+        this.reconnectTimer.unref?.();
+    }
+    clearReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}

package/dist/packages/core/src/infrastructure/services/messaging/messaging.service.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Messaging Service
+ *
+ * Core orchestrator for the external messaging remote control feature.
+ * Wires together:
+ *   - Commands.com Gateway tunnel (inbound webhook delivery)
+ *   - Telegram Bot API client (outbound replies + notifications)
+ *   - Command executor (parses slash commands, runs use cases)
+ *   - Notification emitter (debounced forwarding from the local event bus)
+ *   - Chat relay (interactive agent ↔ messenger bridge)
+ *   - Pairing auto-confirm (matches /pair <code> against pending codes)
+ *
+ * Lifecycle:
+ *   1. `isConfigured()` checks settings for required fields.
+ *   2. `start()` opens the tunnel and subscribes to the notification bus.
+ *   3. Inbound `tunnel.request` frames are parsed as Telegram Update objects
+ *      and dispatched to either the pair confirm flow or the command executor.
+ *   4. `stop()` tears everything down.
+ */
+import type { IMessagingService } from '../../../application/ports/output/services/messaging-service.interface.js';
+import type { MessagingNotification, MessagingConfig } from '../../../domain/generated/output.js';
+import type { NotificationBus } from '../notifications/notification-bus.js';
+import type { IFeatureRepository } from '../../../application/ports/output/repositories/feature-repository.interface.js';
+import type { ListFeaturesUseCase } from '../../../application/use-cases/features/list-features.use-case.js';
+import type { ShowFeatureUseCase } from '../../../application/use-cases/features/show-feature.use-case.js';
+import type { CreateFeatureUseCase } from '../../../application/use-cases/features/create/create-feature.use-case.js';
+import type { ApproveAgentRunUseCase } from '../../../application/use-cases/agents/approve-agent-run.use-case.js';
+import type { RejectAgentRunUseCase } from '../../../application/use-cases/agents/reject-agent-run.use-case.js';
+import type { StopAgentRunUseCase } from '../../../application/use-cases/agents/stop-agent-run.use-case.js';
+import type { ResumeFeatureUseCase } from '../../../application/use-cases/features/resume-feature.use-case.js';
+import type { ListRepositoriesUseCase } from '../../../application/use-cases/repositories/list-repositories.use-case.js';
+import type { ConfirmMessagingPairingUseCase } from '../../../application/use-cases/messaging/confirm-pairing.use-case.js';
+import type { ITelegramClient } from '../../../application/ports/output/services/telegram-client.interface.js';
+import type { IInteractiveSessionService } from '../../../application/ports/output/services/interactive-session-service.interface.js';
+interface MessagingServiceDeps {
+    config: MessagingConfig;
+    accessToken: string;
+    telegramClient: ITelegramClient;
+    /** Bot token the sender will use to reply to Telegram users. */
+    telegramBotToken?: string;
+    notificationBus: NotificationBus;
+    featureRepo: IFeatureRepository;
+    createFeature: CreateFeatureUseCase;
+    approveAgentRun: ApproveAgentRunUseCase;
+    rejectAgentRun: RejectAgentRunUseCase;
+    stopAgentRun: StopAgentRunUseCase;
+    resumeFeature: ResumeFeatureUseCase;
+    listFeatures: ListFeaturesUseCase;
+    showFeature: ShowFeatureUseCase;
+    listRepositories: ListRepositoriesUseCase;
+    confirmPairing: ConfirmMessagingPairingUseCase;
+    interactiveSessionService: IInteractiveSessionService;
+}
+export declare class MessagingService implements IMessagingService {
+    private readonly deps;
+    private tunnelAdapter;
+    private commandExecutor;
+    private notificationEmitter;
+    private chatRelay;
+    private sender;
+    private started;
+    constructor(deps: MessagingServiceDeps);
+    isConfigured(): boolean;
+    isConnected(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    sendNotification(notification: MessagingNotification): Promise<void>;
+    private collectRouteIds;
+    private handleTunnelRequest;
+    private handleChatStart;
+    private handleChatEnd;
+    private handleChatMessage;
+    private platformForRoute;
+    private handlePairConfirm;
+    private sendReply;
+}
+export {};
+//# sourceMappingURL=messaging.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/messaging/messaging.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/messaging/messaging.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2EAA2E,CAAC;AACnH,OAAO,KAAK,EAEV,qBAAqB,EACrB,eAAe,EAChB,MAAM,qCAAqC,CAAC;AAa7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gFAAgF,CAAC;AACzH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mEAAmE,CAAC;AAC7G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kEAAkE,CAAC;AAC3G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2EAA2E,CAAC;AACtH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qEAAqE,CAAC;AAClH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oEAAoE,CAAC;AAChH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAC5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oEAAoE,CAAC;AAC/G,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2EAA2E,CAAC;AACzH,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,sEAAsE,CAAC;AAC3H,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yEAAyE,CAAC;AAC/G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qFAAqF,CAAC;AAGtI,UAAU,oBAAoB;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,eAAe,CAAC;IAChC,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,EAAE,kBAAkB,CAAC;IAChC,aAAa,EAAE,oBAAoB,CAAC;IACpC,eAAe,EAAE,sBAAsB,CAAC;IACxC,cAAc,EAAE,qBAAqB,CAAC;IACtC,YAAY,EAAE,mBAAmB,CAAC;IAClC,aAAa,EAAE,oBAAoB,CAAC;IACpC,YAAY,EAAE,mBAAmB,CAAC;IAClC,WAAW,EAAE,kBAAkB,CAAC;IAChC,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,cAAc,EAAE,8BAA8B,CAAC;IAC/C,yBAAyB,EAAE,0BAA0B,CAAC;CACvD;AAmCD,qBAAa,gBAAiB,YAAW,iBAAiB;IAQ5C,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,OAAO,CAAS;gBAEK,IAAI,EAAE,oBAAoB;IAEvD,YAAY,IAAI,OAAO;IAgBvB,WAAW,IAAI,OAAO;IAIhB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoDtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAerB,gBAAgB,CAAC,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1E,OAAO,CAAC,eAAe;YAQT,mBAAmB;YAiEnB,eAAe;YAgDf,aAAa;YAMb,iBAAiB;IAa/B,OAAO,CAAC,gBAAgB;YAOV,iBAAiB;YAyBjB,SAAS;CASxB"}

package/dist/packages/core/src/infrastructure/services/messaging/messaging.service.js

@@ -0,0 +1,279 @@
+/**
+ * Messaging Service
+ *
+ * Core orchestrator for the external messaging remote control feature.
+ * Wires together:
+ *   - Commands.com Gateway tunnel (inbound webhook delivery)
+ *   - Telegram Bot API client (outbound replies + notifications)
+ *   - Command executor (parses slash commands, runs use cases)
+ *   - Notification emitter (debounced forwarding from the local event bus)
+ *   - Chat relay (interactive agent ↔ messenger bridge)
+ *   - Pairing auto-confirm (matches /pair <code> against pending codes)
+ *
+ * Lifecycle:
+ *   1. `isConfigured()` checks settings for required fields.
+ *   2. `start()` opens the tunnel and subscribes to the notification bus.
+ *   3. Inbound `tunnel.request` frames are parsed as Telegram Update objects
+ *      and dispatched to either the pair confirm flow or the command executor.
+ *   4. `stop()` tears everything down.
+ */
+import { MessagingPlatform, MessagingFrameType, MessagingCommandType, } from '../../../domain/generated/output.js';
+import { MessagingTunnelAdapter } from './messaging-tunnel.adapter.js';
+import { MessagingCommandExecutor } from './command-executor.js';
+import { MessagingNotificationEmitter } from './notification-emitter.js';
+import { MessagingChatRelay } from './chat-relay.js';
+import { TelegramMessageSender } from './telegram-message-sender.js';
+import { parseTelegramUpdate, parsePairCommand } from './telegram-webhook.parser.js';
+import { parseWhatsAppUpdate } from './whatsapp-webhook.parser.js';
+const COMMAND_REGEX = /^\/(new|approve|reject|stop|resume|status|list|chat|end|mute|unmute|help)(?:@\w+)?(?:\s+(\S+))?(?:\s+(.+))?$/i;
+const COMMANDS_TAKING_FEATURE_ID = [
+    MessagingCommandType.Approve,
+    MessagingCommandType.Reject,
+    MessagingCommandType.Stop,
+    MessagingCommandType.Resume,
+    MessagingCommandType.Status,
+    MessagingCommandType.Chat,
+];
+function parseSlashCommand(text) {
+    const match = text.trim().match(COMMAND_REGEX);
+    if (!match)
+        return null;
+    const command = match[1].toLowerCase();
+    const second = match[2];
+    const rest = match[3];
+    if (COMMANDS_TAKING_FEATURE_ID.includes(command) && second) {
+        return { command, featureId: second, args: rest };
+    }
+    const args = [second, rest].filter(Boolean).join(' ');
+    return { command, args: args || undefined };
+}
+export class MessagingService {
+    deps;
+    tunnelAdapter = null;
+    commandExecutor = null;
+    notificationEmitter = null;
+    chatRelay = null;
+    sender = null;
+    started = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    isConfigured() {
+        const { config } = this.deps;
+        if (!config.enabled || !config.gatewayUrl || !config.deviceId)
+            return false;
+        // The tunnel must start as soon as a route exists — not only after the
+        // user is fully paired. The auto-confirm flow requires this: the daemon
+        // needs to be receiving tunnel.request frames in order to see the
+        // inbound `/pair <code>` message from the user's first DM and call
+        // ConfirmMessagingPairingUseCase. If we gated on `paired && chatId`
+        // the user could never complete pairing without a manual chatId entry
+        // in the UI.
+        const telegramReady = !!config.telegram?.routeId;
+        const whatsappReady = !!config.whatsapp?.routeId;
+        return telegramReady || whatsappReady;
+    }
+    isConnected() {
+        return this.tunnelAdapter?.isConnected() ?? false;
+    }
+    async start() {
+        if (this.started || !this.isConfigured())
+            return;
+        const { config, accessToken, telegramClient, notificationBus, featureRepo } = this.deps;
+        const routeIds = this.collectRouteIds();
+        this.tunnelAdapter = new MessagingTunnelAdapter({
+            gatewayUrl: config.gatewayUrl,
+            accessToken,
+            deviceId: config.deviceId,
+            routeIds,
+        });
+        this.sender = new TelegramMessageSender(telegramClient, () => {
+            const chatId = this.deps.config.telegram?.chatId;
+            const botToken = this.deps.telegramBotToken;
+            if (!chatId || !botToken)
+                return null;
+            return { chatId, botToken };
+        });
+        this.commandExecutor = new MessagingCommandExecutor(featureRepo, this.deps.createFeature, this.deps.approveAgentRun, this.deps.rejectAgentRun, this.deps.stopAgentRun, this.deps.resumeFeature, this.deps.listFeatures, this.deps.showFeature, this.deps.listRepositories);
+        this.notificationEmitter = new MessagingNotificationEmitter(this.sender, notificationBus, config.debounceMs ?? 5_000);
+        this.chatRelay = new MessagingChatRelay(this.sender, config.chatBufferMs ?? 3_000);
+        this.tunnelAdapter.onRequest((req) => this.handleTunnelRequest(req));
+        try {
+            await this.tunnelAdapter.connect();
+        }
+        catch {
+            // Connection failure is non-fatal — the adapter reconnects automatically.
+        }
+        this.notificationEmitter.start();
+        this.started = true;
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.notificationEmitter?.stop();
+        this.chatRelay?.stop();
+        await this.tunnelAdapter?.disconnect();
+        this.tunnelAdapter = null;
+        this.commandExecutor = null;
+        this.notificationEmitter = null;
+        this.chatRelay = null;
+        this.sender = null;
+        this.started = false;
+    }
+    async sendNotification(notification) {
+        await this.sender?.send(notification);
+    }
+    collectRouteIds() {
+        const out = [];
+        const { config } = this.deps;
+        if (config.telegram?.routeId)
+            out.push(config.telegram.routeId);
+        if (config.whatsapp?.routeId)
+            out.push(config.whatsapp.routeId);
+        return out;
+    }
+    async handleTunnelRequest(req) {
+        // Per-route → platform resolution.
+        const platform = this.platformForRoute(req.routeId);
+        if (!platform) {
+            return { status: 404 };
+        }
+        const parsed = platform === MessagingPlatform.Telegram
+            ? parseTelegramUpdate(req.body)
+            : parseWhatsAppUpdate(req.body);
+        if (!parsed) {
+            return { status: 200 };
+        }
+        // 1. Handle /pair <code> auto-confirmation before anything else.
+        const pair = parsePairCommand(parsed.text);
+        if (pair) {
+            await this.handlePairConfirm(platform, parsed.chatId, pair.code);
+            return { status: 200 };
+        }
+        // 2. Dispatch slash commands via the command executor. /chat and /end
+        //    are handled specially because they manipulate the chat relay.
+        const slash = parseSlashCommand(parsed.text);
+        if (slash) {
+            if (slash.command === MessagingCommandType.Chat) {
+                await this.handleChatStart(platform, parsed.chatId, slash.featureId);
+                return { status: 200 };
+            }
+            if (slash.command === MessagingCommandType.End) {
+                await this.handleChatEnd(parsed.chatId);
+                return { status: 200 };
+            }
+            if (this.commandExecutor) {
+                const cmd = {
+                    type: MessagingFrameType.Command,
+                    command: slash.command,
+                    featureId: slash.featureId,
+                    args: slash.args,
+                    chatId: parsed.chatId,
+                    platform,
+                };
+                try {
+                    const reply = await this.commandExecutor.execute(cmd);
+                    await this.sendReply(parsed.chatId, reply);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    await this.sendReply(parsed.chatId, `Command failed: ${msg}`);
+                }
+                return { status: 200 };
+            }
+        }
+        // 3. If there's an active chat relay, forward the message to the
+        //    interactive session.
+        if (this.chatRelay?.hasActiveRelay()) {
+            await this.handleChatMessage(parsed.chatId, parsed.text);
+            return { status: 200 };
+        }
+        // 4. Unknown message — ignore silently.
+        return { status: 200 };
+    }
+    async handleChatStart(platform, chatId, featureId) {
+        if (!featureId) {
+            await this.sendReply(chatId, 'Usage: /chat <feature_id>');
+            return;
+        }
+        if (!this.chatRelay)
+            return;
+        const feature = await this.deps.featureRepo.findById(featureId);
+        if (!feature) {
+            await this.sendReply(chatId, `Feature ${featureId} not found.`);
+            return;
+        }
+        if (!feature.worktreePath) {
+            await this.sendReply(chatId, `Feature ${featureId} has no worktree yet — it may not be checked out.`);
+            return;
+        }
+        // Subscribe to the interactive session's stream and forward deltas to
+        // the chat relay buffer. The unsubscribe handle is owned by the relay.
+        const unsubscribe = this.deps.interactiveSessionService.subscribeByFeature(feature.id, (chunk) => {
+            if (chunk.delta) {
+                this.chatRelay?.bufferAgentOutput(chunk.delta);
+            }
+            if (chunk.done) {
+                this.chatRelay?.flushBuffer();
+            }
+        });
+        const message = this.chatRelay.startRelay(feature.id, chatId, platform, feature.worktreePath, unsubscribe);
+        await this.sendReply(chatId, message);
+    }
+    async handleChatEnd(chatId) {
+        if (!this.chatRelay)
+            return;
+        const message = this.chatRelay.endRelay();
+        await this.sendReply(chatId, message);
+    }
+    async handleChatMessage(_chatId, text) {
+        if (!this.chatRelay?.hasActiveRelay())
+            return;
+        const featureId = this.chatRelay.getActiveFeatureId();
+        const worktreePath = this.chatRelay.getActiveWorktreePath();
+        if (!featureId || !worktreePath)
+            return;
+        try {
+            await this.deps.interactiveSessionService.sendUserMessage(featureId, text, worktreePath);
+        }
+        catch {
+            // Delivery failures surface as missing agent replies — no point
+            // spamming the user's chat with error toasts.
+        }
+    }
+    platformForRoute(routeId) {
+        const { config } = this.deps;
+        if (config.telegram?.routeId === routeId)
+            return MessagingPlatform.Telegram;
+        if (config.whatsapp?.routeId === routeId)
+            return MessagingPlatform.WhatsApp;
+        return null;
+    }
+    async handlePairConfirm(platform, chatId, code) {
+        const { config } = this.deps;
+        const platformCfg = platform === MessagingPlatform.Telegram ? config.telegram : config.whatsapp;
+        if (!platformCfg?.pendingPairingCode || platformCfg.pendingPairingCode !== code) {
+            await this.sendReply(chatId, 'Invalid or expired pairing code.');
+            return;
+        }
+        try {
+            await this.deps.confirmPairing.execute({ platform, chatId });
+            await this.sendReply(chatId, 'Paired with Shep. You can now send commands like /status, /list, or /help.');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            await this.sendReply(chatId, `Pairing failed: ${msg}`);
+        }
+    }
+    async sendReply(chatId, text) {
+        const botToken = this.deps.telegramBotToken;
+        if (!botToken || !text)
+            return;
+        try {
+            await this.deps.telegramClient.sendMessage({ botToken, chatId, text });
+        }
+        catch {
+            // Non-fatal — swallow so the tunnel response still completes.
+        }
+    }
+}

package/dist/packages/core/src/infrastructure/services/messaging/notification-emitter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Messaging Notification Emitter
+ *
+ * Subscribes to Shep's existing NotificationEventBus and pushes
+ * events through the Gateway tunnel for delivery to messaging apps.
+ *
+ * Features:
+ * - Debouncing: events for the same feature+type are collapsed within
+ *   a configurable window (default 5s) to avoid flooding
+ * - Content sanitization: all messages are scrubbed of paths, code, and secrets
+ * - Gate events are never debounced — delivered immediately
+ */
+import type { NotificationBus } from '../notifications/notification-bus.js';
+import type { IMessageSender } from '../../../application/ports/output/services/message-sender.interface.js';
+/**
+ * Subscribes to the notification event bus and forwards events
+ * to the messaging tunnel for delivery to the user's phone.
+ */
+export declare class MessagingNotificationEmitter {
+    private readonly sender;
+    private readonly notificationBus;
+    private readonly debounceMs;
+    private debounceTimers;
+    private listening;
+    private handler;
+    constructor(sender: IMessageSender, notificationBus: NotificationBus, debounceMs?: number);
+    /** Start listening for notification events */
+    start(): void;
+    /** Stop listening for notification events */
+    stop(): void;
+    private emitDebounced;
+}
+//# sourceMappingURL=notification-emitter.d.ts.map

package/dist/packages/core/src/infrastructure/services/messaging/notification-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-emitter.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/messaging/notification-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAE5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wEAAwE,CAAC;AAI7G;;;GAGG;AACH,qBAAa,4BAA4B;IAMrC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,cAAc,CAAoD;IAC1E,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAqD;gBAGjD,MAAM,EAAE,cAAc,EACtB,eAAe,EAAE,eAAe,EAChC,UAAU,GAAE,MAA4B;IAG3D,8CAA8C;IAC9C,KAAK,IAAI,IAAI;IAwBb,6CAA6C;IAC7C,IAAI,IAAI,IAAI;IAgBZ,OAAO,CAAC,aAAa;CAiBtB"}