@krischoichoi/channel-harness 0.6.0

package/lib/reply-router.js

@@ -0,0 +1,674 @@
+import { joinAssistantStreamText } from '@deepseek-ai/dsh-llm';
+import { formatChannelTurnFailure } from './failure-display.js';
+export class ReplyRouter {
+    options;
+    active = new Map();
+    streamTurns = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Register the `session/event` listener; returns a disposer. */
+    attach(ctx) {
+        const stopSessionEvents = ctx.on('session/event', (session, event) => {
+            this.onSessionEvent(session, event);
+        });
+        const stopAssistantStream = ctx.on('agent/assistant-stream', ({ agent, frame }) => {
+            this.onAssistantStream(agent, frame);
+        });
+        return () => stopSessionEvents() && stopAssistantStream();
+    }
+    /** Consume transient V3 stream frames for native/edit previews. */
+    onAssistantStream(agent, frame) {
+        const key = `${agent.id}:${frame.attemptId}`;
+        if (frame.type === 'start') {
+            this.streamTurns.set(key, frame.turn);
+            return;
+        }
+        if (frame.type === 'end') {
+            this.streamTurns.delete(key);
+            return;
+        }
+        if (frame.chunk.type !== 'text-delta')
+            return;
+        const turn = this.streamTurns.get(key);
+        if (turn === undefined)
+            return;
+        const active = this.ensureActive(agent.session, turn);
+        if (active)
+            this.appendText(active, frame.chunk.text);
+    }
+    /** Testable entry point; the registered listener delegates here. */
+    onSessionEvent(session, event) {
+        switch (event.type) {
+            case 'turn/start':
+                // Turn existence only — no active reply is established here. Outbound
+                // delivery requires a Channel ReplyContext (message-id → claimed →
+                // turn), which is only authoritative once chunks flow. A non-channel
+                // turn on a channel-bound session must NOT auto-route (see header).
+                break;
+            case 'assistant/message': {
+                const streamedText = joinAssistantStreamText(event.data.stream);
+                const finalText = assistantText(event.data.message) || streamedText;
+                if (streamedText || finalText) {
+                    const active = this.ensureActive(session, event.data.turn);
+                    if (active) {
+                        const existingText = active.buffer;
+                        const remaining = streamedText.startsWith(existingText)
+                            ? streamedText.slice(existingText.length)
+                            : streamedText || finalText;
+                        if (remaining)
+                            this.appendText(active, remaining);
+                        active.finalText = finalText;
+                    }
+                }
+                break;
+            }
+            case 'turn/end':
+                void this.finishTurn(session, event.data.turn, event.data.reason);
+                break;
+        }
+    }
+    /** Session ids with an in-flight reply (used by the lifecycle drain). */
+    activeSessions() {
+        return [...this.active.keys()];
+    }
+    /**
+     * Finalize every reply still marked active, exactly like `turn/end` would.
+     * Turns still streaming at unload never deliver `turn/end`, so the lifecycle
+     * drain calls this after `whenIdle` to guarantee buffered/final text is
+     * delivered (or the reply handle fails) instead of being dropped.
+     */
+    async flushAll() {
+        for (const sessionId of [...this.active.keys()]) {
+            const active = this.active.get(sessionId);
+            if (active)
+                await this.finalize(active, active.turn);
+        }
+    }
+    /**
+     * Durable-log reconcile (doc §4.3 / §4.4): deliver the final assistant text
+     * for the last unfinished turn straight from the Session durable log, even
+     * when the `session/event` listener is no longer attached.
+     *
+     * Finds the last `turn/start` with no matching `turn/end`; if the
+     * ReplyRouter already holds an active reply for it, finalizes normally.
+     * Otherwise it rebuilds the assistant text from each V3
+     * `assistant/message.stream` (falling back to the message text) and delivers it via `adapter.send` (buffered
+     * strategy), then finishes/cleans up. The Session log is the ONLY source of
+     * transcript truth — reconcile never maintains a second copy.
+     */
+    async reconcileSession(session) {
+        const sessionId = String(session.id);
+        const unfinished = lastUnfinishedTurn(session.events);
+        if (!unfinished)
+            return; // no unfinished turn to reconcile
+        const { turn } = unfinished;
+        const rebuilt = rebuildAssistantText(session.events, turn);
+        // Same outbound gate as the live path: a durable-log turn with no active
+        // ReplyContext was not channel-inbound, so it must not be delivered back
+        // to the channel on unload — unless the binding opted into mirroring
+        // (issue #5), in which case the rebuilt final text is delivered buffered.
+        const context = this.options.replyContexts.getTurn(sessionId, turn);
+        if (!context) {
+            this.options.replyContexts.releaseTurn(sessionId, turn);
+            const mirrorBinding = rebuilt ? this.options.getBinding(sessionId) : undefined;
+            if (!mirrorBinding || mirrorBinding.mirror !== true || !rebuilt)
+                return;
+            const binding = mirrorBinding;
+            const adapter = this.options.getAdapter(binding.channelId);
+            if (!adapter || !adapter.capabilities.text)
+                return;
+            const mirrorContext = {
+                conversationType: binding.conversationType,
+                ...(binding.senderId === undefined ? {} : { senderId: binding.senderId }),
+            };
+            await this.deliver(adapter, targetFor(binding, mirrorContext), rebuilt);
+            return;
+        }
+        const active = this.active.get(sessionId);
+        if (active && !active.finished) {
+            // Already tracking this reply — finalize it normally with the durable
+            // text as the authoritative content.
+            active.buffer = rebuilt;
+            if (rebuilt)
+                active.finalText = rebuilt;
+            await this.finalize(active, turn);
+            return;
+        }
+        if (!rebuilt) {
+            this.options.replyContexts.releaseTurn(sessionId, turn);
+            return;
+        }
+        const binding = this.options.getBinding(sessionId);
+        if (!binding) {
+            this.options.logger.warn(`[channel-harness] reconcile: no session binding for '${sessionId}'`);
+            this.options.replyContexts.releaseTurn(sessionId, turn);
+            return;
+        }
+        const adapter = this.options.getAdapter(binding.channelId);
+        if (!adapter) {
+            this.options.logger.warn(`[channel-harness] reconcile: no adapter for channel '${binding.channelId}'`);
+            this.options.replyContexts.releaseTurn(sessionId, turn);
+            return;
+        }
+        if (active?.handle) {
+            // Deliver the missing remainder through the already-open reply handle.
+            await active.handle.finish(rebuilt ? { text: rebuilt } : undefined).catch(() => { });
+        }
+        else {
+            await this.deliver(adapter, targetFor(binding, context), rebuilt);
+        }
+        this.options.replyContexts.releaseTurn(sessionId, turn);
+    }
+    /** Clear all timers and drop active replies. */
+    dispose() {
+        for (const active of this.active.values()) {
+            if (active.timer)
+                clearTimeout(active.timer);
+            active.finished = true;
+        }
+        this.active.clear();
+        this.streamTurns.clear();
+    }
+    ensureActive(session, turn) {
+        const sessionId = String(session.id);
+        const context = this.options.replyContexts.getTurn(sessionId, turn);
+        if (!context) {
+            // ReplyContext is the outbound gate: a turn without an active context
+            // was not triggered by a channel inbound message, so it must never be
+            // routed back to the channel (even if the session is channel-bound) —
+            // unless the owner explicitly opted in via the binding's `mirror` flag
+            // (issue #5), in which case the turn is tracked as a buffered mirror.
+            return this.ensureMirrorActive(session, turn);
+        }
+        const existing = this.active.get(sessionId);
+        if (existing) {
+            // Defensive refresh: re-resolve target/strategy if the context changed.
+            // A session is single-flight (one turn at a time), so this is normally
+            // a no-op.
+            if (existing.context !== context) {
+                existing.context = context;
+                existing.target = targetFor(existing.binding, context);
+                existing.strategy = strategyFor(this.options.getAdapter(existing.binding.channelId), existing.target);
+            }
+            return existing;
+        }
+        const binding = this.options.getBinding(sessionId);
+        if (!binding) {
+            this.options.logger.warn(`[channel-harness] no session binding for '${sessionId}'`);
+            return null;
+        }
+        const adapter = this.options.getAdapter(binding.channelId);
+        if (!adapter) {
+            this.options.logger.warn(`[channel-harness] no adapter for channel '${binding.channelId}'`);
+            return null;
+        }
+        const target = targetFor(binding, context);
+        const active = {
+            binding,
+            strategy: strategyFor(adapter, target),
+            target,
+            context,
+            handle: null,
+            buffer: '',
+            finalText: '',
+            timer: null,
+            lastFlush: 0,
+            lastSentLength: 0,
+            turn,
+            finished: false,
+            flushing: null,
+        };
+        this.active.set(sessionId, active);
+        return active;
+    }
+    /**
+     * Mirror tracking for a non-channel turn (issue #5): only when the bound
+     * conversation opted in (`binding.mirror === true`) does the router attach
+     * a buffered-only reply that delivers the final assistant text to the bound
+     * conversation at `turn/end`. Everything else stays unrouted. The synthetic
+     * context carries NO platform state (no replyToMessageId / raw / runId) —
+     * the binding's stable identity is the sole delivery address.
+     */
+    ensureMirrorActive(session, turn) {
+        const sessionId = String(session.id);
+        const existing = this.active.get(sessionId);
+        if (existing)
+            return existing;
+        const binding = this.options.getBinding(sessionId);
+        if (!binding || binding.mirror !== true)
+            return null;
+        const adapter = this.options.getAdapter(binding.channelId);
+        if (!adapter || !adapter.capabilities.text)
+            return null;
+        const context = {
+            conversationType: binding.conversationType,
+            ...(binding.senderId === undefined ? {} : { senderId: binding.senderId }),
+        };
+        const active = {
+            binding,
+            // Mirror is always buffered: no edit streaming, no partial previews —
+            // only the final assistant text lands on the conversation.
+            strategy: 'buffered',
+            target: targetFor(binding, context),
+            context,
+            mirror: true,
+            handle: null,
+            buffer: '',
+            finalText: '',
+            timer: null,
+            lastFlush: 0,
+            lastSentLength: 0,
+            turn,
+            finished: false,
+            flushing: null,
+        };
+        this.active.set(sessionId, active);
+        return active;
+    }
+    appendText(active, delta) {
+        active.buffer += delta;
+        const interval = this.options.config.updateIntervalMs;
+        if (interval <= 0) {
+            // updateIntervalMs: 0 — flush on every delta (deterministic testing).
+            void this.flush(active);
+            return;
+        }
+        const now = Date.now();
+        if (now - active.lastFlush >= interval) {
+            void this.flush(active);
+            return;
+        }
+        if (!active.timer) {
+            active.timer = setTimeout(() => {
+                active.timer = null;
+                void this.flush(active);
+            }, interval - (now - active.lastFlush));
+        }
+    }
+    /**
+     * Enqueue a preview flush. Deltas are drained through a single in-flight
+     * chain so concurrent deltas can never double-`createReply` on the same
+     * reply; the chain reads the current buffer at execution time, so a flush
+     * that started before the newest delta still covers it.
+     */
+    flush(active) {
+        if (active.finished)
+            return;
+        if (!active.flushing) {
+            active.flushing = this.drain(active).finally(() => {
+                active.flushing = null;
+            });
+        }
+    }
+    /** Drain all pending deltas, flushing until the buffer is fully sent. */
+    async drain(active) {
+        while (!active.finished) {
+            if (active.strategy === 'buffered')
+                return; // send-once: deliver at turn/end
+            const sentBefore = active.lastSentLength;
+            await this.doFlush(active);
+            if (active.lastSentLength === sentBefore)
+                return; // no progress — stop
+        }
+    }
+    async doFlush(active) {
+        if (active.finished)
+            return;
+        active.lastFlush = Date.now();
+        if (active.buffer.length === active.lastSentLength)
+            return;
+        const adapter = this.options.getAdapter(active.binding.channelId);
+        if (!adapter?.createReply)
+            return;
+        try {
+            if (!active.handle) {
+                active.handle = await adapter.createReply(active.target, {
+                    markdown: true,
+                });
+                // The owning scope may have finished while the card was created.
+                if (active.finished)
+                    return;
+            }
+            if (active.strategy === 'edit') {
+                await active.handle.replace({ text: active.buffer });
+                active.lastSentLength = active.buffer.length;
+            }
+            else {
+                const delta = active.buffer.slice(active.lastSentLength);
+                active.lastSentLength = active.buffer.length;
+                await active.handle.append(delta);
+            }
+        }
+        catch (error) {
+            await active.handle?.fail(error).catch(() => { });
+            this.options.logger.error(`[channel-harness] reply flush failed for session '${active.binding.sessionId}'`, error);
+        }
+    }
+    resolveTurnTarget(sessionId, context) {
+        if (!context)
+            return undefined;
+        const binding = this.options.getBinding(sessionId);
+        if (!binding) {
+            this.options.logger.warn(`[channel-harness] no session binding for '${sessionId}'`);
+            return undefined;
+        }
+        const adapter = this.options.getAdapter(binding.channelId);
+        if (!adapter) {
+            this.options.logger.warn(`[channel-harness] no adapter for channel '${binding.channelId}'`);
+            return undefined;
+        }
+        return { binding, adapter, target: targetFor(binding, context) };
+    }
+    async finishTurn(session, turn, reason) {
+        const sessionId = String(session.id);
+        const active = this.active.get(sessionId);
+        // finalize() releases the reply context, so resolve it while it is still
+        // the outbound authority for this terminal event.
+        const context = this.options.replyContexts.getTurn(sessionId, turn);
+        const terminalTarget = active
+            ? (() => {
+                const adapter = this.options.getAdapter(active.binding.channelId);
+                return adapter
+                    ? { binding: active.binding, adapter, target: active.target }
+                    : undefined;
+            })()
+            : this.resolveTurnTarget(sessionId, context);
+        try {
+            // Existing assistant content retains its normal finalization path.
+            if (active)
+                await this.finalize(active, turn);
+            // A terminal failure is a separate system notice, never part of model
+            // output. The ReplyContext gate prevents Web/CLI turns from leaking to a
+            // channel-bound conversation.
+            if (reason.kind === 'error' && terminalTarget) {
+                this.options.logger.error(`[channel-harness] Harness turn failed for session '${sessionId}'`, {
+                    turn,
+                    code: reason.error.code,
+                    status: reason.error.status,
+                    requestId: reason.error.requestId,
+                    providerRetryAfterMs: reason.error.providerRetryAfterMs,
+                });
+                try {
+                    await this.deliver(terminalTarget.adapter, terminalTarget.target, formatChannelTurnFailure(reason.error));
+                }
+                catch (error) {
+                    this.options.logger.error(`[channel-harness] failed to deliver turn error for session '${sessionId}'`, error);
+                }
+            }
+        }
+        finally {
+            // Active replies clean up in finalize(). No-output terminal turns need
+            // the same release and typing cleanup even when delivery fails.
+            if (!active) {
+                this.options.replyContexts.releaseTurn(sessionId, turn);
+                if (terminalTarget) {
+                    this.stopTypingIfSupported(terminalTarget.binding.channelId, terminalTarget.target);
+                }
+            }
+        }
+    }
+    /**
+     * Finalize one active reply: clear its timer, drain any in-flight preview
+     * chain, deliver the accumulated text (or fail the handle), and release the
+     * active reply context for its turn (v1.1 §20). Shared by `turn/end`
+     * handling and the lifecycle `flushAll()` so an unloaded turn is finalized
+     * exactly like a completed one.
+     */
+    async finalize(active, turn) {
+        if (active.timer) {
+            clearTimeout(active.timer);
+            active.timer = null;
+        }
+        this.active.delete(active.binding.sessionId);
+        if (active.finished)
+            return;
+        // Let any in-flight preview chain drain first; otherwise the flush could
+        // land an update on a card that is about to be finalized (orphan card).
+        if (active.flushing) {
+            await active.flushing.catch(() => { });
+        }
+        active.finished = true;
+        const text = active.buffer.length > 0 ? active.buffer : active.finalText;
+        const adapter = this.options.getAdapter(active.binding.channelId);
+        if (!adapter) {
+            this.options.logger.warn(`[channel-harness] no adapter for channel '${active.binding.channelId}'`);
+            // Still release the active context for this turn (v1.1 §20).
+            this.options.replyContexts.releaseTurn(active.binding.sessionId, turn);
+            return;
+        }
+        const target = active.target;
+        try {
+            if (active.handle) {
+                // Pass the authoritative accumulated text: for `edit`, deltas pending
+                // in the throttle window may not have been flushed to the handle yet,
+                // so finalizing without them would drop content (M2 regression).
+                await active.handle.finish(text ? { text } : undefined);
+            }
+            else if (active.strategy !== 'buffered' && adapter.createReply && text) {
+                const handle = await adapter.createReply(target, { markdown: true });
+                await handle.finish({ text });
+            }
+            else if (text) {
+                await this.deliver(adapter, target, text);
+            }
+        }
+        catch (error) {
+            try {
+                await active.handle?.fail(error);
+            }
+            catch {
+                // Ignore secondary failure during fail.
+            }
+            this.options.logger.error(`[channel-harness] reply finish failed for session '${active.binding.sessionId}'`, error);
+        }
+        // Release the active reply context for this turn (v1.1 §20).
+        this.options.replyContexts.releaseTurn(active.binding.sessionId, turn);
+        // Best-effort typing stop: a typing API failure must never break delivery.
+        this.stopTypingIfSupported(active.binding.channelId, active.target);
+    }
+    stopTypingIfSupported(channelId, target) {
+        const adapter = this.options.getAdapter(channelId);
+        if (adapter?.stopTypingForTarget) {
+            void adapter.stopTypingForTarget(target).catch(() => { });
+        }
+        else if (adapter?.stopTyping) {
+            void adapter.stopTyping(target.conversationId).catch(() => { });
+        }
+    }
+    async deliver(adapter, target, text) {
+        if (!text)
+            return;
+        const max = this.options.config.maxTextLength;
+        if (!max || text.length <= max) {
+            await adapter.send(target, { text });
+            return;
+        }
+        const pieces = splitMessage(text, max, this.options.config);
+        for (const piece of pieces) {
+            await adapter.send(target, { text: piece });
+        }
+    }
+}
+function strategyFor(adapter, target) {
+    const mode = adapter.resolveStreamingMode?.(target) ?? adapter.capabilities.streaming;
+    if (adapter.createReply) {
+        if (mode === 'native')
+            return 'native';
+        if (mode === 'edit')
+            return 'edit';
+    }
+    return 'buffered';
+}
+function assistantText(message) {
+    let text = '';
+    for (const block of message.content) {
+        if (block.type === 'text')
+            text += block.text;
+    }
+    return text;
+}
+function targetFor(binding, context) {
+    const target = {
+        channelId: binding.channelId,
+        accountId: binding.accountId,
+        conversationId: binding.conversationId,
+    };
+    if (binding.threadId) {
+        target.threadId = binding.threadId;
+    }
+    if (context) {
+        target.conversationType = context.conversationType;
+        if (context.replyToMessageId) {
+            target.replyToMessageId = context.replyToMessageId;
+        }
+        if (context.raw !== undefined) {
+            target.raw = context.raw;
+        }
+        if (context.runId) {
+            target.runId = context.runId;
+        }
+    }
+    return target;
+}
+/**
+ * Find the last turn that started but never ended. Returns its turn number, or
+ * `undefined` when every opened turn was closed.
+ */
+function lastUnfinishedTurn(events) {
+    let lastOpen;
+    for (const event of events) {
+        if (event.type === 'turn/start') {
+            lastOpen = event.data.turn;
+        }
+        else if (event.type === 'turn/end' && event.data.turn === lastOpen) {
+            lastOpen = undefined;
+        }
+    }
+    return lastOpen === undefined ? undefined : { turn: lastOpen };
+}
+/**
+ * Rebuild the assistant text for one turn from its V3 compact assistant
+ * streams, falling back to `assistant/message` text when no delta flowed.
+ */
+function rebuildAssistantText(events, turn) {
+    let text = '';
+    for (const event of events) {
+        if ((event.type === 'assistant/message' || event.type === 'assistant/attempt') && event.data.turn === turn) {
+            text += joinAssistantStreamText(event.data.stream);
+        }
+    }
+    if (text.length > 0)
+        return text;
+    for (const event of events) {
+        if (event.type === 'assistant/message' && event.data.turn === turn) {
+            const fallback = assistantText(event.data.message);
+            if (fallback)
+                return fallback;
+        }
+    }
+    return '';
+}
+/**
+ * Split a long message into `maxLength`-bounded pieces, keeping fenced code
+ * blocks whole and preferring paragraph boundaries. `finalFlush: false`
+ * drops a trailing partial piece instead of delivering it.
+ */
+export function splitMessage(text, maxLength, config) {
+    if (text.length <= maxLength)
+        return [text];
+    const segments = config.splitCodeBlocks ? splitCodeSegments(text) : [text];
+    const pieces = [];
+    for (const segment of segments) {
+        if (segment.length === 0)
+            continue;
+        if (segment.length <= maxLength) {
+            pieces.push(segment);
+            continue;
+        }
+        if (config.splitParagraphs) {
+            pieces.push(...packSegments(segment, maxLength));
+        }
+        else {
+            pieces.push(...hardWrap(segment, maxLength));
+        }
+    }
+    if (!config.finalFlush && pieces.length > 1) {
+        const last = pieces[pieces.length - 1];
+        if (last && last.length < maxLength)
+            pieces.pop();
+    }
+    return pieces;
+}
+function splitCodeSegments(text) {
+    const segments = [];
+    const fence = /```[\s\S]*?```/g;
+    let cursor = 0;
+    let match;
+    while ((match = fence.exec(text))) {
+        const before = text.slice(cursor, match.index);
+        if (before)
+            segments.push(before);
+        segments.push(match[0]);
+        cursor = match.index + match[0].length;
+    }
+    const rest = text.slice(cursor);
+    if (rest)
+        segments.push(rest);
+    return segments.length > 0 ? segments : [text];
+}
+function packSegments(segment, maxLength) {
+    const paragraphs = segment.split(/\n\s*\n/);
+    const pieces = [];
+    let current = '';
+    for (const paragraph of paragraphs) {
+        if (paragraph.length <= maxLength) {
+            const candidate = current ? `${current}\n\n${paragraph}` : paragraph;
+            if (candidate.length <= maxLength) {
+                current = candidate;
+            }
+            else {
+                if (current)
+                    pieces.push(current);
+                current = paragraph;
+            }
+        }
+        else {
+            if (current)
+                pieces.push(current);
+            current = '';
+            pieces.push(...hardWrap(paragraph, maxLength));
+        }
+    }
+    if (current)
+        pieces.push(current);
+    return pieces;
+}
+function hardWrap(text, maxLength) {
+    const pieces = [];
+    let current = '';
+    for (const line of text.split('\n')) {
+        if (line.length > maxLength) {
+            if (current)
+                pieces.push(current);
+            current = '';
+            for (let i = 0; i < line.length; i += maxLength) {
+                pieces.push(line.slice(i, i + maxLength));
+            }
+        }
+        else {
+            const candidate = current ? `${current}\n${line}` : line;
+            if (candidate.length <= maxLength) {
+                current = candidate;
+            }
+            else {
+                pieces.push(current);
+                current = line;
+            }
+        }
+    }
+    if (current)
+        pieces.push(current);
+    return pieces;
+}
+//# sourceMappingURL=reply-router.js.map