@canonmsg/core 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequ
 export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 export { createStreamingHelper } from './streaming.js';
 export type { RTDBHandle, RTDBRef, ServerTimestamp, StreamingHelperOptions, StreamingNode } from './streaming.js';
+export { createTurnOutputController } from './turn-output-controller.js';
+export type { TurnOutputController, TurnOutputControllerOptions, TurnOutputMode, TurnOutputSnapshot, } from './turn-output-controller.js';
 export { clearPendingRegistration, getOrCreatePendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, updatePendingRegistration, upsertAgentProfile, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 export type { AgentProfile, PendingRegistration, ProfileLockHandle } from './agent-profiles.js';
 export { resolveCanonAgent, resolveCanonProfile, getActiveProfile, getActiveProfileLock } from './agent-resolver.js';

package/dist/index.js

@@ -22,6 +22,7 @@ export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalRep
 export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
 // Streaming (RTDB helpers)
 export { createStreamingHelper } from './streaming.js';
+export { createTurnOutputController } from './turn-output-controller.js';
 // Agent profiles (loading, locking, resolution)
 export { clearPendingRegistration, getOrCreatePendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, updatePendingRegistration, upsertAgentProfile, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 // Agent resolver

package/dist/runtime-state-publisher.d.ts

@@ -10,6 +10,7 @@ export interface RuntimeStreamingPayload {
     text: string;
     status: 'thinking' | 'streaming' | 'tool';
     messageId?: string;
+    turnId?: string | null;
     updatedAt?: number | {
         '.sv': 'timestamp';
     };

package/dist/streaming.d.ts

@@ -23,6 +23,7 @@ export interface StreamingNode {
     startedAt: unknown;
     updatedAt: unknown;
     messageId: string;
+    turnId?: string | null;
 }
 /**
  * Creates helpers that read/write the RTDB streaming node for a single
@@ -41,7 +42,7 @@ export interface StreamingNode {
 export declare function createStreamingHelper(opts: StreamingHelperOptions): {
     forConversation: (conversationId: string, agentId: string) => {
         /** Write the initial streaming node (status: "thinking", empty text). */
-        start(messageId: string): Promise<void>;
+        start(messageId: string, turnId?: string | null): Promise<void>;
         /** Update the accumulated text and optionally change status. */
         update(text: string, status?: StreamingStatus): Promise<void>;
         /** Set status without changing text (e.g. switching to "tool"). */

package/dist/streaming.js

@@ -20,13 +20,14 @@ export function createStreamingHelper(opts) {
         const nodeRef = db.ref(nodePath);
         return {
             /** Write the initial streaming node (status: "thinking", empty text). */
-            async start(messageId) {
+            async start(messageId, turnId) {
                 const node = {
                     text: '',
                     status: 'thinking',
                     startedAt: serverTimestamp,
                     updatedAt: serverTimestamp,
                     messageId,
+                    ...(turnId ? { turnId } : {}),
                 };
                 await nodeRef.set(node);
             },

package/dist/turn-output-controller.d.ts

@@ -0,0 +1,35 @@
+import type { StreamingStatus } from './types.js';
+export type TurnOutputMode = 'delta' | 'block' | 'snapshot' | 'status';
+export interface TurnOutputSnapshot {
+    turnId: string;
+    messageId: string;
+    text: string;
+    status: StreamingStatus;
+}
+export interface TurnOutputControllerOptions {
+    turnId: string;
+    mode?: TurnOutputMode;
+    throttleMs?: number;
+    blockSeparator?: string;
+    writeSnapshot: (snapshot: TurnOutputSnapshot) => void | Promise<void>;
+    clearSnapshot: () => void | Promise<void>;
+    schedule?: typeof setTimeout;
+    cancel?: typeof clearTimeout;
+}
+export interface TurnOutputController {
+    readonly turnId: string;
+    readonly mode: TurnOutputMode;
+    getText(): string;
+    getStatus(): StreamingStatus;
+    startThinking(text?: string): Promise<void>;
+    startStreaming(text?: string): Promise<void>;
+    appendDelta(delta: string): void;
+    appendBlock(block: string): void;
+    replaceSnapshot(text: string, status?: StreamingStatus): Promise<void>;
+    setStatus(status: StreamingStatus, text?: string): Promise<void>;
+    flush(status?: StreamingStatus): Promise<void>;
+    waitingInput(): Promise<void>;
+    interrupt(): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function createTurnOutputController(options: TurnOutputControllerOptions): TurnOutputController;

package/dist/turn-output-controller.js

@@ -0,0 +1,125 @@
+const DEFAULT_THROTTLE_MS = 120;
+const DEFAULT_BLOCK_SEPARATOR = '\n\n';
+function normalizeStatus(status) {
+    return status === 'thinking' || status === 'tool' || status === 'streaming'
+        ? status
+        : 'streaming';
+}
+function appendBlockText(currentText, block, separator) {
+    if (!block)
+        return currentText;
+    const prefix = currentText ? separator : '';
+    const combined = `${currentText}${prefix}${block}`;
+    return separator === '\n\n' ? combined.replace(/\n{3,}/g, '\n\n') : combined;
+}
+export function createTurnOutputController(options) {
+    const schedule = options.schedule ?? setTimeout;
+    const cancel = options.cancel ?? clearTimeout;
+    const throttleMs = Math.max(0, options.throttleMs ?? DEFAULT_THROTTLE_MS);
+    const mode = options.mode ?? 'snapshot';
+    const blockSeparator = options.blockSeparator ?? DEFAULT_BLOCK_SEPARATOR;
+    let text = '';
+    let status = 'thinking';
+    let timer = null;
+    let pendingPromise = Promise.resolve();
+    const write = (nextStatus = status) => {
+        if (mode === 'status')
+            return;
+        const snapshot = {
+            turnId: options.turnId,
+            messageId: options.turnId,
+            text,
+            status: normalizeStatus(nextStatus),
+        };
+        pendingPromise = pendingPromise
+            .catch(() => { })
+            .then(() => Promise.resolve(options.writeSnapshot(snapshot)).catch(() => { }));
+    };
+    const cancelTimer = () => {
+        if (!timer)
+            return;
+        cancel(timer);
+        timer = null;
+    };
+    const scheduleWrite = () => {
+        if (mode === 'status')
+            return;
+        if (throttleMs <= 0) {
+            write();
+            return;
+        }
+        if (timer)
+            return;
+        timer = schedule(() => {
+            timer = null;
+            write();
+        }, throttleMs);
+    };
+    const flush = async (nextStatus = status) => {
+        cancelTimer();
+        write(nextStatus);
+        await pendingPromise;
+    };
+    const clear = async () => {
+        cancelTimer();
+        text = '';
+        status = 'thinking';
+        pendingPromise = pendingPromise
+            .catch(() => { })
+            .then(() => Promise.resolve(options.clearSnapshot()).catch(() => { }));
+        await pendingPromise;
+    };
+    return {
+        turnId: options.turnId,
+        mode,
+        getText() {
+            return text;
+        },
+        getStatus() {
+            return status;
+        },
+        async startThinking(nextText = '') {
+            text = nextText;
+            status = 'thinking';
+            await flush('thinking');
+        },
+        async startStreaming(nextText = text) {
+            text = nextText;
+            status = 'streaming';
+            await flush('streaming');
+        },
+        appendDelta(delta) {
+            if (!delta)
+                return;
+            if (status !== 'streaming')
+                text = '';
+            text += delta;
+            status = 'streaming';
+            scheduleWrite();
+        },
+        appendBlock(block) {
+            if (!block)
+                return;
+            if (status !== 'streaming')
+                text = '';
+            text = appendBlockText(text, block, blockSeparator);
+            status = 'streaming';
+            scheduleWrite();
+        },
+        async replaceSnapshot(nextText, nextStatus = 'streaming') {
+            text = nextText;
+            status = normalizeStatus(nextStatus);
+            await flush(status);
+        },
+        async setStatus(nextStatus, nextText) {
+            if (nextText !== undefined)
+                text = nextText;
+            status = normalizeStatus(nextStatus);
+            await flush(status);
+        },
+        flush,
+        waitingInput: clear,
+        interrupt: clear,
+        clear,
+    };
+}

package/dist/types.d.ts

@@ -613,6 +613,7 @@ export interface SetStreamingOptions {
     text: string;
     status: StreamingStatus;
     messageId: string;
+    turnId?: string | null;
 }
 export interface SetRuntimeTurnOptions {
     conversationId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",