crewly 1.12.1 → 1.13.1

package/dist/cli/backend/src/utils/native-binding.utils.js

@@ -0,0 +1,206 @@
+/**
+ * Native-binding fail-fast helpers.
+ *
+ * When a native Node addon (e.g. `better-sqlite3`, `node-pty`,
+ * `sqlite-vec-darwin-*`) is built for the wrong CPU/ABI and Node tries
+ * to `dlopen` it, the loader emits a recognisable error pattern:
+ *
+ * ```
+ * dlopen .../foo.node, 0x0001
+ * mach-o file, but is an incompatible architecture
+ * (have 'x86_64', need 'arm64e' or 'arm64')
+ * ```
+ *
+ * This module exists for one reason: those errors must NEVER be
+ * silently swallowed by a try/catch wrapper at the gateway layer
+ * (which used to downgrade chat-v2 to a JSON-file fallback while
+ * `chat.db` quietly went stale — F-CYCLE7-1, audit 2026-05-07 §2.1).
+ *
+ * The contract:
+ *
+ *   1. {@link loadNativeAddonOrFatal} wraps `require(name)`.
+ *   2. If the require throws and the error matches a known native-arch
+ *      / dlopen pattern, we rethrow as {@link NativeBindingFatalError},
+ *      which carries `fatal: true`.
+ *   3. The boot-time wiring (`backend/src/index.ts`, the chat-v2 init
+ *      try/catch) inspects caught errors with {@link isNativeBindingFatalError}
+ *      and **rethrows fatal errors** rather than logging them as
+ *      "non-critical". This crashes the process at boot — which is the
+ *      desired behaviour: an arch-mismatched binary can be fixed by
+ *      `npm rebuild <pkg> --build-from-source`, but only if the operator
+ *      sees the failure.
+ *
+ * @module utils/native-binding.utils
+ */
+/**
+ * Marker class for native-binding failures that MUST crash the
+ * process at boot rather than be downgraded to a runtime fallback.
+ *
+ * Holds the original underlying error in `cause` so logs surface
+ * the full dlopen trace.
+ */
+export class NativeBindingFatalError extends Error {
+    /** Discriminator readable by `instanceof` and structural callers. */
+    fatal = true;
+    /**
+     * The npm package name that failed to load (`'better-sqlite3'`,
+     * `'node-pty'`, etc.). Used in the boot-failure log line and the
+     * remediation hint that follows it.
+     */
+    moduleName;
+    /**
+     * The original error thrown by `require(name)`. Preserved for log
+     * fidelity — the dlopen line itself is the most useful piece of
+     * context for whoever has to run the rebuild.
+     */
+    cause;
+    /**
+     * Build a fatal-error wrapper.
+     *
+     * @param moduleName - The npm package that failed to load
+     * @param cause - The underlying error from the failed require
+     * @param remediation - One-line remediation hint shown in the message
+     *   (default: `npm rebuild <moduleName> --build-from-source`)
+     */
+    constructor(moduleName, cause, remediation) {
+        const fix = remediation ??
+            `Run \`npm rebuild ${moduleName} --build-from-source\` (or delete node_modules/${moduleName}/build and reinstall) to recompile for this host's arch.`;
+        const causeMessage = cause instanceof Error ? cause.message : String(cause);
+        super(`FATAL: native binding "${moduleName}" failed to load. ${fix} Original error: ${causeMessage}`);
+        this.name = 'NativeBindingFatalError';
+        this.moduleName = moduleName;
+        this.cause = cause;
+        // Preserve the original stack chain when available so debuggers
+        // can walk back to the dlopen frame.
+        if (cause instanceof Error && cause.stack) {
+            this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+        }
+    }
+}
+/**
+ * Type guard for {@link NativeBindingFatalError}. Survives realm
+ * boundaries (unlike a bare `instanceof`) by also checking the
+ * structural `fatal === true` + `name === 'NativeBindingFatalError'`
+ * shape — useful when the same module is loaded via two different
+ * resolver paths (ts-jest vs. native ESM) and `instanceof` would
+ * unexpectedly miss.
+ *
+ * @param err - Any thrown value
+ * @returns True iff the error is a fatal native-binding load failure
+ */
+export function isNativeBindingFatalError(err) {
+    if (err instanceof NativeBindingFatalError)
+        return true;
+    if (err !== null &&
+        typeof err === 'object' &&
+        err.name === 'NativeBindingFatalError' &&
+        err.fatal === true) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Patterns that identify a dlopen / arch-mismatch / ABI-version
+ * failure. Match any one and we treat the require failure as a fatal
+ * native-binding error.
+ *
+ * Sourced from real Node.js loader output across:
+ *   - macOS Mach-O (`mach-o file, but is an incompatible architecture`,
+ *     `have 'x86_64', need 'arm64'`, `dlopen` prefix)
+ *   - glibc Linux (`wrong ELF class`, `cannot open shared object file`)
+ *   - Node ABI mismatch (`NODE_MODULE_VERSION` mismatch after Node
+ *     upgrade, `was compiled against a different Node.js version`)
+ *   - Windows (`is not a valid Win32 application`)
+ *   - Generic native-addon loader (`Module did not self-register`,
+ *     which happens when a `.node` file is loaded by a Node ABI it
+ *     does not match)
+ *
+ * Each pattern is anchored case-insensitively against the error
+ * message string. Tested in `native-binding.utils.test.ts`.
+ */
+const FATAL_NATIVE_PATTERNS = [
+    // macOS Mach-O dlopen + arch mismatch ----------------------------
+    /dlopen[\s\S]*incompatible architecture/i,
+    /mach-o file, but is an incompatible architecture/i,
+    /have '[^']+', need '[^']+'/i,
+    // glibc Linux ELF mismatch ---------------------------------------
+    /wrong ELF class/i,
+    /cannot open shared object file/i,
+    // Node ABI mismatch ----------------------------------------------
+    /NODE_MODULE_VERSION/i,
+    /was compiled against a different Node\.js version/i,
+    /Module did not self-register/i,
+    // Windows --------------------------------------------------------
+    /is not a valid Win32 application/i,
+];
+/**
+ * Decide whether the given error indicates a native-addon arch / ABI
+ * mismatch (vs. a benign "package not installed" error or a runtime
+ * SQL bug from inside the addon).
+ *
+ * Stable, narrow behaviour — only matches the patterns in
+ * {@link FATAL_NATIVE_PATTERNS}. Callers can refine further by
+ * inspecting `err.code === 'ERR_DLOPEN_FAILED'` (Node ≥ 16 emits this
+ * for any failed `dlopen`, including arch mismatches) before calling
+ * this helper if they want a broader net.
+ *
+ * @param err - Any thrown value
+ * @returns True iff the error message matches a known native-mismatch pattern
+ */
+export function isNativeArchMismatchError(err) {
+    if (err === null || err === undefined)
+        return false;
+    const message = err instanceof Error ? err.message : String(err);
+    if (typeof message !== 'string' || message.length === 0)
+        return false;
+    // `code` is a stronger signal than message-pattern when present.
+    const code = err.code;
+    if (code === 'ERR_DLOPEN_FAILED')
+        return true;
+    return FATAL_NATIVE_PATTERNS.some((re) => re.test(message));
+}
+/**
+ * Load a native Node addon by name, escalating arch / ABI mismatches
+ * to {@link NativeBindingFatalError}.
+ *
+ * Behaviour:
+ *   - On success: returns the require'd module unchanged.
+ *   - On failure that matches {@link isNativeArchMismatchError}:
+ *     throws {@link NativeBindingFatalError}.
+ *   - On any other failure (e.g. `Cannot find module 'foo'` because
+ *     the package isn't installed at all): rethrows the original
+ *     error unchanged, so callers can keep their existing
+ *     "package missing → soft error" semantics.
+ *
+ * @param moduleName - Package name (`'better-sqlite3'`, `'node-pty'`)
+ * @param requireFn - The CJS-style require to use (typically the result
+ *   of `createBareModuleRequire(...)` from `node-require.utils.ts`)
+ * @param remediation - Optional override for the remediation hint shown
+ *   in the wrapped error message
+ * @returns The loaded module
+ *
+ * @throws {NativeBindingFatalError} when the require fails with a
+ *   recognised native-arch / ABI / dlopen pattern.
+ *
+ * @example
+ * ```ts
+ * import { loadNativeAddonOrFatal } from '../../utils/native-binding.utils.js';
+ *
+ * const Database = loadNativeAddonOrFatal<typeof import('better-sqlite3')>(
+ *   'better-sqlite3',
+ *   nodeRequire,
+ * );
+ * ```
+ */
+export function loadNativeAddonOrFatal(moduleName, requireFn, remediation) {
+    try {
+        return requireFn(moduleName);
+    }
+    catch (err) {
+        if (isNativeArchMismatchError(err)) {
+            throw new NativeBindingFatalError(moduleName, err, remediation);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=native-binding.utils.js.map

package/dist/cli/backend/src/utils/native-binding.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-binding.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/native-binding.utils.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/websocket/chat.gateway.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Chat Gateway Module
+ *
+ * Integrates chat functionality with the WebSocket infrastructure.
+ * Forwards chat events from ChatService to connected clients.
+ *
+ * @module websocket/chat.gateway
+ */
+import { Server as SocketIOServer } from 'socket.io';
+import type { ChatMessage, ChatSender } from '../types/chat.types.js';
+/**
+ * Chat Gateway class for WebSocket-based chat messaging.
+ *
+ * Provides:
+ * - Real-time chat message broadcasting
+ * - Typing indicator support
+ * - Conversation update notifications
+ * - Terminal output to chat message processing
+ */
+export declare class ChatGateway {
+    private io;
+    private logger;
+    private chatV2;
+    private initialized;
+    /**
+     * Create a new ChatGateway.
+     *
+     * @param io - Socket.IO server instance
+     */
+    constructor(io: SocketIOServer);
+    /**
+     * Initialize the chat gateway.
+     *
+     * Subscribes to chat-v2 message events and wires the
+     * client-facing WebSocket handlers.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Subscribe to ChatV2Service events and broadcast to WebSocket clients.
+     * Phase 6c of the unified-chat-message-store spec — replaces the
+     * legacy ChatService EventEmitter wiring.
+     */
+    private setupChatV2Listeners;
+    /**
+     * Set up WebSocket event handlers for chat-specific events.
+     */
+    private setupWebSocketHandlers;
+    /**
+     * Broadcast a message to all clients in the chat room.
+     *
+     * @param event - Event name
+     * @param message - Message to broadcast
+     */
+    private broadcast;
+    /**
+     * Broadcast a message to a specific conversation room.
+     *
+     * @param conversationId - Conversation ID
+     * @param event - Event name
+     * @param message - Message to broadcast
+     */
+    private broadcastToConversation;
+    /**
+     * Process terminal output and convert to chat message if applicable.
+     *
+     * Checks for response markers in terminal output and creates
+     * chat messages from extracted content.
+     *
+     * @param sessionId - The session/agent ID that produced the output
+     * @param output - Raw terminal output
+     * @param conversationId - Target conversation ID
+     * @returns The created chat message, or null if no response marker found
+     */
+    processTerminalOutput(sessionId: string, output: string, conversationId?: string): Promise<ChatMessage | null>;
+    /**
+     * Process a unified [NOTIFY] message and add it directly to a conversation.
+     *
+     * Unlike `processTerminalOutput`, this method takes pre-extracted content
+     * from a [NOTIFY] payload — no regex extraction needed. Optional metadata
+     * (e.g. Slack delivery tracking fields) is merged into the message metadata.
+     *
+     * @param sessionId - The session/agent ID that produced the output
+     * @param content - Pre-extracted markdown content from NotifyPayload.message
+     * @param conversationId - Target conversation ID
+     * @param metadata - Optional additional metadata to attach to the message
+     * @returns The created chat message, or null on failure
+     */
+    processNotifyMessage(sessionId: string, content: string, conversationId: string, metadata?: Record<string, unknown>): Promise<ChatMessage | null>;
+    /**
+     * Emit a typing indicator for the orchestrator.
+     *
+     * Call this when the orchestrator starts/stops processing a message.
+     *
+     * @param conversationId - Conversation ID
+     * @param isTyping - Whether the orchestrator is typing
+     */
+    emitOrchestratorTyping(conversationId: string, isTyping: boolean): void;
+    /**
+     * Emit a typing indicator for an agent.
+     *
+     * @param conversationId - Conversation ID
+     * @param sender - Agent sender information
+     * @param isTyping - Whether the agent is typing
+     */
+    emitAgentTyping(conversationId: string, sender: ChatSender, isTyping: boolean): void;
+    /**
+     * Emit a typing indicator via the WebSocket broadcast channel.
+     * Phase 6c: typing indicators were previously emitted on the
+     * legacy ChatService EventEmitter; with that retired, the gateway
+     * sources them directly. Typing is transient and never persisted,
+     * so no chat-v2 write is involved.
+     *
+     * @param conversationId - Conversation ID
+     * @param sender - Sender descriptor
+     * @param isTyping - Whether the sender is typing
+     */
+    private broadcastTyping;
+    /**
+     * Check if the gateway is initialized.
+     *
+     * @returns True if initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Initialize the ChatGateway with a Socket.IO server.
+ *
+ * @param io - Socket.IO server instance
+ * @returns The ChatGateway instance
+ */
+export declare function initializeChatGateway(io: SocketIOServer): Promise<ChatGateway>;
+/**
+ * Get the ChatGateway instance.
+ *
+ * @returns The ChatGateway instance or null if not initialized
+ */
+export declare function getChatGateway(): ChatGateway | null;
+/**
+ * Reset the ChatGateway instance (for testing).
+ */
+export declare function resetChatGateway(): void;
+//# sourceMappingURL=chat.gateway.d.ts.map

package/dist/cli/backend/src/websocket/chat.gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.gateway.d.ts","sourceRoot":"","sources":["../../../../../backend/src/websocket/chat.gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,IAAI,cAAc,EAAU,MAAM,WAAW,CAAC;AAW7D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEtE;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;OAIG;gBACS,EAAE,EAAE,cAAc;IAM9B;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUjC;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA+D9B;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAQ/B;;;;;;;;;;OAUG;IACG,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAyC9B;;;;;;;;;;;;OAYG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAyC9B;;;;;;;OAOG;IACH,sBAAsB,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIvE;;;;;;OAMG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIpF;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAevB;;;;OAIG;IACH,aAAa,IAAI,OAAO;CAGzB;AAQD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAMpF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/cli/backend/src/websocket/chat.gateway.js

@@ -0,0 +1,327 @@
+/**
+ * Chat Gateway Module
+ *
+ * Integrates chat functionality with the WebSocket infrastructure.
+ * Forwards chat events from ChatService to connected clients.
+ *
+ * @module websocket/chat.gateway
+ */
+import { getChatV2Service } from '../services/chat-v2/chat-v2.singleton.js';
+import { SYSTEM_PRINCIPAL, v2MessageToLegacy, v2ChannelToLegacy, senderToV2, } from '../services/chat-v2/legacy-dto.utils.js';
+import { LoggerService } from '../services/core/logger.service.js';
+/**
+ * Chat Gateway class for WebSocket-based chat messaging.
+ *
+ * Provides:
+ * - Real-time chat message broadcasting
+ * - Typing indicator support
+ * - Conversation update notifications
+ * - Terminal output to chat message processing
+ */
+export class ChatGateway {
+    io;
+    logger;
+    chatV2;
+    initialized = false;
+    /**
+     * Create a new ChatGateway.
+     *
+     * @param io - Socket.IO server instance
+     */
+    constructor(io) {
+        this.io = io;
+        this.logger = LoggerService.getInstance().createComponentLogger('ChatGateway');
+        this.chatV2 = getChatV2Service();
+    }
+    /**
+     * Initialize the chat gateway.
+     *
+     * Subscribes to chat-v2 message events and wires the
+     * client-facing WebSocket handlers.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.setupChatV2Listeners();
+        this.setupWebSocketHandlers();
+        this.initialized = true;
+        this.logger.info('ChatGateway initialized');
+    }
+    /**
+     * Subscribe to ChatV2Service events and broadcast to WebSocket clients.
+     * Phase 6c of the unified-chat-message-store spec — replaces the
+     * legacy ChatService EventEmitter wiring.
+     */
+    setupChatV2Listeners() {
+        this.chatV2.on('chat_message', (dto) => {
+            const legacy = v2MessageToLegacy(dto);
+            this.logger.debug('Broadcasting chat_message', { messageId: legacy.id });
+            this.broadcast('chat_message', {
+                type: 'chat_message',
+                data: legacy,
+                timestamp: new Date().toISOString(),
+            });
+        });
+    }
+    /**
+     * Set up WebSocket event handlers for chat-specific events.
+     */
+    setupWebSocketHandlers() {
+        this.io.on('connection', (socket) => {
+            // Handle chat conversation subscription
+            socket.on('subscribe_to_chat', async (conversationId) => {
+                this.logger.debug('Client subscribing to chat', {
+                    socketId: socket.id,
+                    conversationId,
+                });
+                // Join chat room
+                socket.join('chat');
+                if (conversationId) {
+                    socket.join(`chat_${conversationId}`);
+                }
+                // Send current conversation if requested
+                if (conversationId) {
+                    try {
+                        const channel = this.chatV2.getChannel(conversationId, SYSTEM_PRINCIPAL);
+                        const messageCount = this.chatV2.countChannelMessages(conversationId, SYSTEM_PRINCIPAL);
+                        socket.emit('chat_conversation', {
+                            type: 'chat_conversation',
+                            data: v2ChannelToLegacy(channel, messageCount),
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                    catch {
+                        // Channel not found / unauthorized — silently skip; the
+                        // client will see no chat_conversation event.
+                    }
+                }
+                socket.emit('chat_subscribed', {
+                    type: 'chat_subscribed',
+                    data: { conversationId },
+                    timestamp: new Date().toISOString(),
+                });
+            });
+            // Handle unsubscription from chat
+            socket.on('unsubscribe_from_chat', (conversationId) => {
+                socket.leave('chat');
+                if (conversationId) {
+                    socket.leave(`chat_${conversationId}`);
+                }
+            });
+            // Handle typing indicator from client
+            socket.on('chat_typing', (data) => {
+                // User typing indicators are just echoed to other clients
+                socket.to(`chat_${data.conversationId}`).emit('chat_typing', {
+                    type: 'chat_typing',
+                    data: {
+                        conversationId: data.conversationId,
+                        sender: { type: 'user' },
+                        isTyping: data.isTyping,
+                    },
+                    timestamp: new Date().toISOString(),
+                });
+            });
+        });
+    }
+    /**
+     * Broadcast a message to all clients in the chat room.
+     *
+     * @param event - Event name
+     * @param message - Message to broadcast
+     */
+    broadcast(event, message) {
+        this.io.to('chat').emit(event, message);
+    }
+    /**
+     * Broadcast a message to a specific conversation room.
+     *
+     * @param conversationId - Conversation ID
+     * @param event - Event name
+     * @param message - Message to broadcast
+     */
+    broadcastToConversation(conversationId, event, message) {
+        this.io.to(`chat_${conversationId}`).emit(event, message);
+    }
+    /**
+     * Process terminal output and convert to chat message if applicable.
+     *
+     * Checks for response markers in terminal output and creates
+     * chat messages from extracted content.
+     *
+     * @param sessionId - The session/agent ID that produced the output
+     * @param output - Raw terminal output
+     * @param conversationId - Target conversation ID
+     * @returns The created chat message, or null if no response marker found
+     */
+    async processTerminalOutput(sessionId, output, conversationId) {
+        // Only process if there's an active conversation
+        if (!conversationId)
+            return null;
+        // Check if output contains response markers
+        const hasResponseMarker = output.includes('[RESPONSE]') ||
+            output.includes('[CHAT_RESPONSE]') ||
+            output.includes('```response');
+        if (!hasResponseMarker)
+            return null;
+        try {
+            const channel = this.chatV2.ensureChannelForLegacyConversation({
+                conversationId,
+                agentSession: 'crewly-orc',
+            });
+            const { message } = this.chatV2.recordTurn({
+                channelId: channel.id,
+                senderType: 'agent',
+                senderId: sessionId,
+                content: output,
+                metadata: { source: 'pty-runtime', sessionId },
+            });
+            const legacyMessage = v2MessageToLegacy(message);
+            this.logger.debug('Added agent message to chat', {
+                messageId: legacyMessage.id,
+                conversationId,
+            });
+            return legacyMessage;
+        }
+        catch (error) {
+            this.logger.error('Failed to process terminal output for chat', {
+                sessionId,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            return null;
+        }
+    }
+    /**
+     * Process a unified [NOTIFY] message and add it directly to a conversation.
+     *
+     * Unlike `processTerminalOutput`, this method takes pre-extracted content
+     * from a [NOTIFY] payload — no regex extraction needed. Optional metadata
+     * (e.g. Slack delivery tracking fields) is merged into the message metadata.
+     *
+     * @param sessionId - The session/agent ID that produced the output
+     * @param content - Pre-extracted markdown content from NotifyPayload.message
+     * @param conversationId - Target conversation ID
+     * @param metadata - Optional additional metadata to attach to the message
+     * @returns The created chat message, or null on failure
+     */
+    async processNotifyMessage(sessionId, content, conversationId, metadata) {
+        try {
+            const channel = this.chatV2.ensureChannelForLegacyConversation({
+                conversationId,
+                agentSession: 'crewly-orc',
+            });
+            const { message } = this.chatV2.recordTurn({
+                channelId: channel.id,
+                senderType: 'agent',
+                senderId: sessionId,
+                content,
+                metadata: {
+                    sessionId,
+                    ...(metadata ?? {}),
+                    // `source` is set LAST so a caller cannot clobber the audit
+                    // discriminator. It is a closed enum (RECORD_TURN_SOURCES) owned by
+                    // this path; when a caller spread an out-of-enum value over it, the
+                    // write failed validation and the agent's reply was dropped after the
+                    // work was already done. Callers may add metadata, not redefine
+                    // where the turn came from.
+                    source: 'in-process-runtime',
+                },
+            });
+            const legacyMessage = v2MessageToLegacy(message);
+            this.logger.debug('Added notify message to chat', {
+                messageId: legacyMessage.id,
+                conversationId,
+            });
+            return legacyMessage;
+        }
+        catch (error) {
+            this.logger.error('Failed to process notify message for chat', {
+                sessionId,
+                conversationId,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            return null;
+        }
+    }
+    /**
+     * Emit a typing indicator for the orchestrator.
+     *
+     * Call this when the orchestrator starts/stops processing a message.
+     *
+     * @param conversationId - Conversation ID
+     * @param isTyping - Whether the orchestrator is typing
+     */
+    emitOrchestratorTyping(conversationId, isTyping) {
+        this.broadcastTyping(conversationId, { type: 'orchestrator', name: 'Orchestrator' }, isTyping);
+    }
+    /**
+     * Emit a typing indicator for an agent.
+     *
+     * @param conversationId - Conversation ID
+     * @param sender - Agent sender information
+     * @param isTyping - Whether the agent is typing
+     */
+    emitAgentTyping(conversationId, sender, isTyping) {
+        this.broadcastTyping(conversationId, sender, isTyping);
+    }
+    /**
+     * Emit a typing indicator via the WebSocket broadcast channel.
+     * Phase 6c: typing indicators were previously emitted on the
+     * legacy ChatService EventEmitter; with that retired, the gateway
+     * sources them directly. Typing is transient and never persisted,
+     * so no chat-v2 write is involved.
+     *
+     * @param conversationId - Conversation ID
+     * @param sender - Sender descriptor
+     * @param isTyping - Whether the sender is typing
+     */
+    broadcastTyping(conversationId, sender, isTyping) {
+        // Resolve sender type via the shared mapper so the wire shape
+        // matches what existing subscribers expect.
+        senderToV2(sender);
+        this.broadcast('chat_typing', {
+            type: 'chat_typing',
+            data: { conversationId, sender, isTyping },
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Check if the gateway is initialized.
+     *
+     * @returns True if initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+}
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+let chatGatewayInstance = null;
+/**
+ * Initialize the ChatGateway with a Socket.IO server.
+ *
+ * @param io - Socket.IO server instance
+ * @returns The ChatGateway instance
+ */
+export async function initializeChatGateway(io) {
+    if (!chatGatewayInstance) {
+        chatGatewayInstance = new ChatGateway(io);
+        await chatGatewayInstance.initialize();
+    }
+    return chatGatewayInstance;
+}
+/**
+ * Get the ChatGateway instance.
+ *
+ * @returns The ChatGateway instance or null if not initialized
+ */
+export function getChatGateway() {
+    return chatGatewayInstance;
+}
+/**
+ * Reset the ChatGateway instance (for testing).
+ */
+export function resetChatGateway() {
+    chatGatewayInstance = null;
+}
+//# sourceMappingURL=chat.gateway.js.map