@ixo/oracle-runtime 0.0.1

package/dist/modules/messages/request-preparer.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { SessionManagerService } from '@ixo/common';
+import { BadRequestException, Injectable, NotFoundException, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import * as crypto from 'node:crypto';
+import { UserMatrixSqliteSyncService } from '../../matrix/checkpointer/user-matrix-sqlite-sync-service.service.js';
+import { HomeServerCache } from './homeserver-cache.js';
+/**
+ * Resolves everything the agent build needs from the incoming request:
+ *
+ *   - session lookup (parallel with the Matrix → SQLite sync triggered the
+ *     first time we see this user this process)
+ *   - room id resolution (uses the cached value when present, otherwise asks
+ *     Matrix)
+ *   - per-DID home-server cache
+ *   - timezone / current-time extraction
+ *   - the `runnableConfig` LangGraph needs for checkpointing
+ *
+ * Construction is hot-path code — every chat request runs this once.
+ */
+let RequestPreparer = class RequestPreparer {
+    sessions;
+    checkpointSync;
+    homeServerCache;
+    config;
+    constructor(sessions, checkpointSync, homeServerCache, config) {
+        this.sessions = sessions;
+        this.checkpointSync = checkpointSync;
+        this.homeServerCache = homeServerCache;
+        this.config = config;
+    }
+    async prepare(payload) {
+        const did = payload.did;
+        const sessionId = payload.sessionId;
+        const requestId = payload.stream && 'requestId' in payload
+            ? payload.requestId
+            : crypto.randomUUID();
+        const homeServerName = payload.homeServer ?? (await this.homeServerCache.get(did));
+        // Per-process sync-once is owned by `UserMatrixSqliteSyncService` — the
+        // first request per user warms the SQLite, subsequent requests reuse it.
+        // We still kick the warm-up in parallel with the session lookup so the
+        // first-time path stays as fast as possible.
+        const [, targetSession] = await Promise.all([
+            this.checkpointSync.getUserDatabase(did),
+            this.sessions.getSession(sessionId, did, false),
+        ]);
+        if (!targetSession) {
+            throw new NotFoundException('Session not found');
+        }
+        let roomId = targetSession.roomId;
+        if (!roomId) {
+            const oracleEntityDid = this.config.getOrThrow('ORACLE_ENTITY_DID');
+            const roomResult = await this.sessions.matrixManger.getOracleRoomIdWithHomeServer({
+                userDid: did,
+                oracleEntityDid,
+                userHomeServer: homeServerName,
+            });
+            roomId = roomResult.roomId;
+            if (!roomId) {
+                throw new NotFoundException('Room not found or Invalid Session Id');
+            }
+        }
+        const timezone = this.resolveTimezone(payload, payload.req);
+        const currentTime = timezone
+            ? this.formatTimeInTimezone(timezone)
+            : undefined;
+        const threadId = payload.overrideLangchainThreadId ?? sessionId;
+        const runnableConfig = {
+            configurable: {
+                thread_id: threadId,
+                requestId,
+                sessionId: threadId,
+            },
+        };
+        return {
+            sessionId,
+            langchainThreadId: threadId,
+            roomId,
+            homeServerName,
+            requestId,
+            runnableConfig,
+            targetSession,
+            timezone,
+            currentTime,
+        };
+    }
+    validateSessionId(sessionId, did) {
+        if (!sessionId || !did) {
+            throw new BadRequestException('Invalid parameters');
+        }
+    }
+    resolveTimezone(payload, req) {
+        if (payload?.timezone) {
+            return payload.timezone.trim() || undefined;
+        }
+        const header = req?.headers['x-timezone'];
+        if (!header)
+            return undefined;
+        const tz = typeof header === 'string' ? header : header[0];
+        return tz?.trim() || undefined;
+    }
+    formatTimeInTimezone(timezone) {
+        try {
+            return new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                year: 'numeric',
+                month: 'long',
+                day: 'numeric',
+                hour: 'numeric',
+                minute: '2-digit',
+                second: '2-digit',
+                hour12: true,
+                timeZoneName: 'short',
+            }).format(new Date());
+        }
+        catch {
+            return new Date().toLocaleString('en-US', {
+                timeZone: 'UTC',
+                timeZoneName: 'short',
+            });
+        }
+    }
+};
+RequestPreparer = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [SessionManagerService,
+        UserMatrixSqliteSyncService,
+        HomeServerCache,
+        ConfigService])
+], RequestPreparer);
+export { RequestPreparer };

package/dist/modules/messages/sse-stream-runner.d.ts

@@ -0,0 +1,73 @@
+import type { Response } from 'express';
+import { type BaseMessage } from 'langchain';
+import { AgentBuilder } from './agent-builder.js';
+import { type SendMessagePayload } from './dto/send-message.dto.js';
+import { type PreparedRequest } from './request-preparer.js';
+export interface StreamRunInput {
+    payload: SendMessagePayload & {
+        msgFromMatrixRoom?: boolean;
+        clientType?: 'matrix' | 'slack' | 'portal';
+    };
+    prepared: PreparedRequest;
+    inputMessages: BaseMessage[];
+    res: Response;
+    abortControllers: Map<string, AbortController>;
+    /**
+     * Called once the agent stream completes with the assembled assistant
+     * content, so the orchestrator can fire-and-forget Matrix replay and
+     * post-message sync without coupling SseStreamRunner to either.
+     */
+    onComplete?: (assistantText: string) => void;
+}
+/**
+ * Owns the SSE side of the chat request: headers, heartbeat, abort
+ * controller registration, and the for-await loop translating
+ * `streamEvents` output into the wire format the frontend consumes.
+ *
+ * Event types preserved verbatim from the legacy implementation:
+ *
+ *   - `ReasoningEvent` (thinking + chunked reasoning + completion marker)
+ *   - `ToolCallEvent`  (server-executed tools — fired on `tool_calls`)
+ *   - `ActionCallEvent` (AG-UI actions — same `tool_calls` channel but
+ *      named in `payload.agActions`; the runner branches on the name)
+ *   - `message` chunk (plain assistant text)
+ *   - `error` + `done`
+ *
+ * The SSE headers and the first `Thinking...` event are emitted by
+ * `MessagesController` BEFORE the orchestrator hands off — this class
+ * picks up after the connection is open, so we don't pay the pre-flight
+ * latency before the client knows the request was accepted.
+ */
+export declare class SseStreamRunner {
+    private readonly agentBuilder;
+    private readonly logger;
+    constructor(agentBuilder: AgentBuilder);
+    run(input: StreamRunInput): Promise<void>;
+    /**
+     * Fires when an agent invokes a tool. `data.input` carries the fully
+     * parsed args — the right place to emit the `isRunning` event with
+     * complete args. We key the map by `run_id` from the event envelope so
+     * the matching `on_tool_end` (which shares the same `run_id`) can pair
+     * with it regardless of how the model formatted the original
+     * `tool_call_id`.
+     */
+    private handleToolStart;
+    private handleToolEnd;
+    /**
+     * Emit a terminal `error` event for any tool/action call that started but
+     * never received a matching `on_tool_end`. Keeps the frontend from
+     * showing a perpetually-spinning tool when the agent ends a turn with
+     * unresolved tool runs in flight.
+     */
+    private flushOrphanedToolCalls;
+    /**
+     * Emits reasoning + text chunks. Tool-call emission has moved to
+     * `handleToolStart` (which fires on `on_tool_start` with full,
+     * finalized args) — the chunk's partial `tool_calls` deltas are
+     * intentionally ignored here to avoid emitting an `isRunning` event
+     * with empty args before the model finishes producing the call.
+     */
+    private handleChatStream;
+    private writeSse;
+}
+//# sourceMappingURL=sse-stream-runner.d.ts.map

package/dist/modules/messages/sse-stream-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream-runner.d.ts","sourceRoot":"","sources":["../../../src/modules/messages/sse-stream-runner.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAkB,KAAK,WAAW,EAAe,MAAM,WAAW,CAAC;AAE1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAyG7D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,kBAAkB,GAAG;QAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,UAAU,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;KAC5C,CAAC;IACF,QAAQ,EAAE,eAAe,CAAC;IAC1B,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,GAAG,EAAE,QAAQ,CAAC;IACd,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,YAAY;IAFzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE9B,YAAY,EAAE,YAAY;IAEjD,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAsK/C;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAoDvB,OAAO,CAAC,aAAa;IAgDrB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IA2B9B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAmDxB,OAAO,CAAC,QAAQ;CASjB"}

package/dist/modules/messages/sse-stream-runner.js

@@ -0,0 +1,352 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var SseStreamRunner_1;
+import { ActionCallEvent, ReasoningEvent, ToolCallEvent, } from '@ixo/oracles-events';
+import { Injectable, Logger } from '@nestjs/common';
+import { emojify } from '../../utils/emoji.js';
+import { AgentBuilder } from './agent-builder.js';
+import { emitSSEEvent, formatSSE, runWithSSEContext, sendSSEDone, sendSSEError, setSSEHeaders, startSSEHeartbeat, } from './sse.utils.js';
+const THINKING_PHRASES = [
+    'Thinking...',
+    'Working...',
+    'Analyzing...',
+    'Processing...',
+    'Computing...',
+    'Crunching...',
+    'Deliberating...',
+    'Reasoning...',
+    'Calculating...',
+    'Evaluating...',
+    'Pondering...',
+    'Reading...',
+    'Synthesizing...',
+    'Formulating...',
+    'Considering...',
+    'Exploring ideas...',
+    'Investigating...',
+    'Brainstorming...',
+    'Solving...',
+    'Reviewing...',
+    'Reflecting...',
+];
+function pickThinkingPhrase() {
+    return THINKING_PHRASES[Math.floor(Math.random() * THINKING_PHRASES.length)];
+}
+/**
+ * Parse a `ToolMessage.content` payload into a JSON object when possible.
+ * Returns `null` if the content is a non-JSON string, an array of content
+ * blocks (LangChain multi-modal output), or anything else we can't reason
+ * about. Used by the action-call status decoder to detect failures.
+ */
+function safeParseToolContent(content) {
+    if (typeof content === 'string') {
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Non-JSON text — fall through.
+        }
+        return null;
+    }
+    if (content && typeof content === 'object' && !Array.isArray(content)) {
+        return content;
+    }
+    return null;
+}
+/**
+ * Unwrap the args object emitted on `on_tool_start.data.input`. MCP tools
+ * surface their args as `{ input: "<json-string>" }` because their schema
+ * accepts a single stringified payload — parse the inner JSON so the
+ * frontend sees the real fields. For native tools, `input` is already
+ * the parsed args object and is returned as-is.
+ */
+function extractToolArgs(input) {
+    if (input == null || typeof input !== 'object' || Array.isArray(input)) {
+        return undefined;
+    }
+    const obj = input;
+    const keys = Object.keys(obj);
+    if (keys.length === 1 &&
+        keys[0] === 'input' &&
+        typeof obj.input === 'string') {
+        try {
+            const parsed = JSON.parse(obj.input);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not JSON — fall through and return the wrapper as-is.
+        }
+    }
+    return obj;
+}
+/**
+ * Owns the SSE side of the chat request: headers, heartbeat, abort
+ * controller registration, and the for-await loop translating
+ * `streamEvents` output into the wire format the frontend consumes.
+ *
+ * Event types preserved verbatim from the legacy implementation:
+ *
+ *   - `ReasoningEvent` (thinking + chunked reasoning + completion marker)
+ *   - `ToolCallEvent`  (server-executed tools — fired on `tool_calls`)
+ *   - `ActionCallEvent` (AG-UI actions — same `tool_calls` channel but
+ *      named in `payload.agActions`; the runner branches on the name)
+ *   - `message` chunk (plain assistant text)
+ *   - `error` + `done`
+ *
+ * The SSE headers and the first `Thinking...` event are emitted by
+ * `MessagesController` BEFORE the orchestrator hands off — this class
+ * picks up after the connection is open, so we don't pay the pre-flight
+ * latency before the client knows the request was accepted.
+ */
+let SseStreamRunner = SseStreamRunner_1 = class SseStreamRunner {
+    agentBuilder;
+    logger = new Logger(SseStreamRunner_1.name);
+    constructor(agentBuilder) {
+        this.agentBuilder = agentBuilder;
+    }
+    async run(input) {
+        const { payload, prepared, inputMessages, res, abortControllers } = input;
+        const { sessionId, requestId } = prepared;
+        // SSE headers + heartbeat may already be set by the controller (early
+        // flush). Set them defensively here in case run() is called directly.
+        if (!res.headersSent) {
+            setSSEHeaders(res, requestId);
+            res.flushHeaders();
+        }
+        const heartbeat = startSSEHeartbeat(res);
+        const abortController = new AbortController();
+        const existingController = abortControllers.get(sessionId);
+        if (existingController) {
+            existingController.abort();
+        }
+        abortControllers.set(sessionId, abortController);
+        const onClose = () => abortController.abort();
+        res.on('close', onClose);
+        try {
+            await runWithSSEContext(res, async () => {
+                const thinkingText = pickThinkingPhrase();
+                const thinkingEvent = ReasoningEvent.createChunk(sessionId, requestId, thinkingText, [{ type: 'thinking', text: thinkingText }], false);
+                emitSSEEvent(thinkingEvent);
+                thinkingEvent.emit();
+                const { agent, stateInput, langGraphConfig } = await this.agentBuilder.build({ payload, prepared, inputMessages }, abortController);
+                // ReactAgent.streamEvents returns the same `{event, data, tags}`
+                // shape as LangChain's `streamEvents v2` — the v2 envelope is the
+                // default for ReactAgent in langchain@1.4, no extra option needed.
+                const stream = agent.streamEvents(stateInput, langGraphConfig);
+                let fullContent = '';
+                const toolCallMap = new Map();
+                const actionCallMap = new Map();
+                const agActionNames = new Set((payload.agActions ?? []).map((a) => a.name));
+                for await (const evt of stream) {
+                    if (abortController.signal.aborted)
+                        break;
+                    const { data, event, run_id, name } = evt;
+                    if (event === 'on_tool_start') {
+                        this.handleToolStart(run_id, name ?? 'tool', data, sessionId, requestId, agActionNames, toolCallMap, actionCallMap, res, abortController);
+                        continue;
+                    }
+                    if (event === 'on_tool_end') {
+                        this.handleToolEnd(run_id, data, toolCallMap, actionCallMap, res, abortController);
+                        continue;
+                    }
+                    if (event === 'on_chat_model_stream') {
+                        const chunkContent = this.handleChatStream(data, sessionId, requestId, res, abortController);
+                        if (chunkContent)
+                            fullContent += chunkContent;
+                    }
+                }
+                if (!abortController.signal.aborted) {
+                    // Flush any tool/action calls that started but never received a
+                    // matching `on_tool_end`. Without this, the frontend keeps the
+                    // tool stuck in `isRunning` forever — the run completed cleanly
+                    // but the UI has no signal to clear it.
+                    this.flushOrphanedToolCalls(toolCallMap, actionCallMap, res, abortController);
+                    const completeEvent = ReasoningEvent.createChunk(sessionId, requestId, '', undefined, true);
+                    if (!res.writableEnded) {
+                        res.write(formatSSE(completeEvent.eventName, completeEvent.payload));
+                    }
+                    sendSSEDone(res);
+                    input.onComplete?.(fullContent);
+                }
+            }, abortController);
+        }
+        catch (error) {
+            const aborted = error instanceof Error &&
+                (error.name === 'AbortError' ||
+                    error.message.includes('aborted') ||
+                    error.message.includes('Stream aborted by client'));
+            if (aborted) {
+                if (!res.writableEnded)
+                    sendSSEDone(res);
+                return;
+            }
+            this.logger.error('Stream failed', error);
+            if (!res.writableEnded && !abortController.signal.aborted) {
+                sendSSEError(res, error instanceof Error ? error : 'Something went wrong');
+                sendSSEDone(res);
+            }
+        }
+        finally {
+            clearInterval(heartbeat);
+            res.off('close', onClose);
+            // Only clear the map entry if it still points at *our* controller. A
+            // newer same-session request replaces the entry at the top of `run()`
+            // (aborting us first); deleting unconditionally here would drop that
+            // newer request's controller and make it un-abortable.
+            if (abortControllers.get(sessionId) === abortController) {
+                abortControllers.delete(sessionId);
+            }
+            if (!res.writableEnded)
+                res.end();
+        }
+    }
+    /**
+     * Fires when an agent invokes a tool. `data.input` carries the fully
+     * parsed args — the right place to emit the `isRunning` event with
+     * complete args. We key the map by `run_id` from the event envelope so
+     * the matching `on_tool_end` (which shares the same `run_id`) can pair
+     * with it regardless of how the model formatted the original
+     * `tool_call_id`.
+     */
+    handleToolStart(runId, toolName, data, sessionId, requestId, agActionNames, toolCallMap, actionCallMap, res, abortController) {
+        const args = extractToolArgs(data.input);
+        const isAction = agActionNames.has(toolName);
+        if (isAction) {
+            const actionCallEvent = new ActionCallEvent({
+                requestId,
+                sessionId,
+                toolCallId: runId,
+                toolName,
+                args,
+                status: 'isRunning',
+            });
+            this.writeSse(res, abortController, actionCallEvent.eventName, actionCallEvent.payload);
+            actionCallMap.set(runId, actionCallEvent);
+            return;
+        }
+        const toolCallEvent = new ToolCallEvent({
+            requestId,
+            sessionId,
+            toolName,
+            args: args ?? {},
+            status: 'isRunning',
+        });
+        toolCallEvent.payload.args.toolName = toolName;
+        toolCallEvent.payload.eventId = runId;
+        this.writeSse(res, abortController, toolCallEvent.eventName, toolCallEvent.payload);
+        toolCallMap.set(runId, toolCallEvent);
+    }
+    handleToolEnd(runId, data, toolCallMap, actionCallMap, res, abortController) {
+        const toolMessage = data.output;
+        const actionCallEvent = actionCallMap.get(runId);
+        if (actionCallEvent) {
+            actionCallEvent.payload.output = emojify(toolMessage.content.toString());
+            actionCallEvent.payload.toolCallId = runId;
+            const parsed = safeParseToolContent(toolMessage.content);
+            if (parsed?.success === false || parsed?.error) {
+                actionCallEvent.payload.status = 'error';
+                actionCallEvent.payload.error =
+                    parsed.error || 'Action failed';
+            }
+            else {
+                actionCallEvent.payload.status = 'done';
+            }
+            this.writeSse(res, abortController, actionCallEvent.eventName, actionCallEvent.payload);
+            actionCallMap.delete(runId);
+            return;
+        }
+        const toolCallEvent = toolCallMap.get(runId);
+        if (!toolCallEvent)
+            return;
+        toolCallEvent.payload.output = emojify(toolMessage.content);
+        toolCallEvent.payload.status = 'done';
+        toolCallEvent.payload.args.toolName =
+            toolMessage.name;
+        toolCallEvent.payload.eventId = runId;
+        this.writeSse(res, abortController, toolCallEvent.eventName, toolCallEvent.payload);
+        toolCallMap.delete(runId);
+    }
+    /**
+     * Emit a terminal `error` event for any tool/action call that started but
+     * never received a matching `on_tool_end`. Keeps the frontend from
+     * showing a perpetually-spinning tool when the agent ends a turn with
+     * unresolved tool runs in flight.
+     */
+    flushOrphanedToolCalls(toolCallMap, actionCallMap, res, abortController) {
+        for (const [runId, evt] of actionCallMap) {
+            evt.payload.status = 'error';
+            evt.payload.error = 'Action did not complete';
+            evt.payload.toolCallId = runId;
+            this.writeSse(res, abortController, evt.eventName, evt.payload);
+        }
+        actionCallMap.clear();
+        for (const [runId, evt] of toolCallMap) {
+            // `IToolCallEvent.status` only allows 'isRunning' | 'done' — there's
+            // no error variant on tool calls (unlike actions). Mark as 'done'
+            // with a sentinel output so the FE clears its spinner but the user
+            // sees the call didn't actually produce a result.
+            evt.payload.status = 'done';
+            evt.payload.output = '⏱️ Tool did not complete';
+            evt.payload.eventId = runId;
+            this.writeSse(res, abortController, evt.eventName, evt.payload);
+        }
+        toolCallMap.clear();
+    }
+    /**
+     * Emits reasoning + text chunks. Tool-call emission has moved to
+     * `handleToolStart` (which fires on `on_tool_start` with full,
+     * finalized args) — the chunk's partial `tool_calls` deltas are
+     * intentionally ignored here to avoid emitting an `isRunning` event
+     * with empty args before the model finishes producing the call.
+     */
+    handleChatStream(data, sessionId, requestId, res, abortController) {
+        const chunk = data.chunk;
+        const rawResponse = chunk.additional_kwargs?.__raw_response;
+        const delta = rawResponse?.choices?.[0]?.delta;
+        const reasoning = delta?.reasoning ?? delta?.reasoning_content;
+        if (reasoning && reasoning.trim()) {
+            const reasoningDetails = Array.isArray(delta?.reasoning_details)
+                ? delta.reasoning_details
+                    .filter((d) => d != null &&
+                    typeof d === 'object' &&
+                    typeof d.type === 'string' &&
+                    typeof d.text === 'string' &&
+                    d.text.trim().length > 0)
+                    .map((d) => ({ type: d.type, text: d.text }))
+                : undefined;
+            const reasoningEvent = ReasoningEvent.createChunk(sessionId, requestId, reasoning, reasoningDetails, false);
+            this.writeSse(res, abortController, reasoningEvent.eventName, reasoningEvent.payload);
+        }
+        const content = chunk.content;
+        if (!content)
+            return undefined;
+        const parsed = emojify(String(content));
+        this.writeSse(res, abortController, 'message', {
+            content: parsed,
+            timestamp: new Date().toISOString(),
+        });
+        return parsed;
+    }
+    writeSse(res, abortController, eventName, payload) {
+        if (res.writableEnded || abortController.signal.aborted)
+            return;
+        res.write(formatSSE(eventName, payload));
+    }
+};
+SseStreamRunner = SseStreamRunner_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [AgentBuilder])
+], SseStreamRunner);
+export { SseStreamRunner };

package/dist/modules/messages/sse.utils.d.ts

@@ -0,0 +1,29 @@
+import { type AllEvents } from '@ixo/oracles-events';
+import { type Response } from 'express';
+/** SSE event format: `event: <name>\ndata: <jsonPayload>\n\n` */
+export declare function formatSSEEvent(event: AllEvents): string;
+/** Format a raw event/data pair without going through the event class system. */
+export declare function formatSSE(eventType: string, data: unknown): string;
+/** SSE heartbeat (comment line) — keeps proxies/load balancers from timing out. */
+export declare function sendSSEHeartbeat(res: Response): void;
+/** Start a 15s heartbeat interval. Caller clears the returned timer. */
+export declare function startSSEHeartbeat(res: Response): NodeJS.Timeout;
+/** Set SSE response headers, optionally including a request id. */
+export declare function setSSEHeaders(res: Response, requestId?: string): void;
+/** Signal stream completion. */
+export declare function sendSSEDone(res: Response): void;
+/** Send an error event. */
+export declare function sendSSEError(res: Response, error: Error | string): void;
+/**
+ * Run a callback with an SSE context bound to AsyncLocalStorage so deeply
+ * nested code can call `emitSSEEvent()` without threading the Response
+ * through every function signature.
+ */
+export declare function runWithSSEContext<T>(res: Response, callback: () => Promise<T>, abortController?: AbortController): Promise<T>;
+/** Emit an SSE event from anywhere within the active SSE context. */
+export declare function emitSSEEvent(event: AllEvents): void;
+export declare function getSSEContext(): Response | undefined;
+export declare function getSSEabortController(): AbortController | undefined;
+export declare function hasSSEContext(): boolean;
+export declare function isSSEAborted(): boolean;
+//# sourceMappingURL=sse.utils.d.ts.map

package/dist/modules/messages/sse.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.utils.d.ts","sourceRoot":"","sources":["../../../src/modules/messages/sse.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AASxC,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEvD;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAElE;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAIpD;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAAC,OAAO,CAE/D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAcrE;AAED,gCAAgC;AAChC,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAI/C;AAED,2BAA2B;AAC3B,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CASvE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,QAAQ,EACb,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,eAAe,CAAC,EAAE,eAAe,GAChC,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAKnD;AAED,wBAAgB,aAAa,IAAI,QAAQ,GAAG,SAAS,CAEpD;AAED,wBAAgB,qBAAqB,IAAI,eAAe,GAAG,SAAS,CAEnE;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAGtC"}

package/dist/modules/messages/sse.utils.js

@@ -0,0 +1,77 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const sseContextStorage = new AsyncLocalStorage();
+/** SSE event format: `event: <name>\ndata: <jsonPayload>\n\n` */
+export function formatSSEEvent(event) {
+    return `event: ${event.eventName}\ndata: ${JSON.stringify(event.payload)}\n\n`;
+}
+/** Format a raw event/data pair without going through the event class system. */
+export function formatSSE(eventType, data) {
+    return `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/** SSE heartbeat (comment line) — keeps proxies/load balancers from timing out. */
+export function sendSSEHeartbeat(res) {
+    if (!res.writableEnded) {
+        res.write(': heartbeat\n\n');
+    }
+}
+/** Start a 15s heartbeat interval. Caller clears the returned timer. */
+export function startSSEHeartbeat(res) {
+    return setInterval(() => sendSSEHeartbeat(res), 15000);
+}
+/** Set SSE response headers, optionally including a request id. */
+export function setSSEHeaders(res, requestId) {
+    const headers = {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    };
+    if (requestId) {
+        headers['X-Request-Id'] = requestId;
+        headers['Access-Control-Expose-Headers'] = 'X-Request-Id';
+    }
+    res.set(headers);
+}
+/** Signal stream completion. */
+export function sendSSEDone(res) {
+    if (!res.writableEnded) {
+        res.write(formatSSE('done', {}));
+    }
+}
+/** Send an error event. */
+export function sendSSEError(res, error) {
+    if (!res.writableEnded) {
+        res.write(formatSSE('error', {
+            error: error instanceof Error ? error.message : error,
+            timestamp: new Date().toISOString(),
+        }));
+    }
+}
+/**
+ * Run a callback with an SSE context bound to AsyncLocalStorage so deeply
+ * nested code can call `emitSSEEvent()` without threading the Response
+ * through every function signature.
+ */
+export function runWithSSEContext(res, callback, abortController) {
+    return sseContextStorage.run({ res, abortController }, callback);
+}
+/** Emit an SSE event from anywhere within the active SSE context. */
+export function emitSSEEvent(event) {
+    const context = sseContextStorage.getStore();
+    if (context?.res && !context.res.writableEnded) {
+        context.res.write(formatSSEEvent(event));
+    }
+}
+export function getSSEContext() {
+    return sseContextStorage.getStore()?.res;
+}
+export function getSSEabortController() {
+    return sseContextStorage.getStore()?.abortController;
+}
+export function hasSSEContext() {
+    return sseContextStorage.getStore() !== undefined;
+}
+export function isSSEAborted() {
+    const context = sseContextStorage.getStore();
+    return context?.abortController?.signal.aborted ?? false;
+}