@canonmsg/core 0.22.0 → 0.24.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type CanonMessage, type CanonConversation, type CanonContact, type CanonContactRequest, type CanonMessagesPage, type CanonResolveAdmissionResult, type AgentContext, type AddMemberResult, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import { type CanonMessage, type CanonConversation, type CanonContact, type CanonContactRequest, type CanonMessagesPage, type CanonResolveAdmissionResult, type AgentContext, type AddMemberResult, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetRuntimeTurnOptions, type SetStreamingOptions } from './types.js';
 import type { RuntimeInputKind } from './runtime-cards.js';
 import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
 import type { RuntimeInputChoice, RuntimeInputNativeMetadata } from './runtime-cards.js';
@@ -55,6 +55,7 @@ export declare class CanonClient {
     removeMember(conversationId: string, userId: string): Promise<void>;
     setStreaming(options: SetStreamingOptions): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;
+    setRuntimeTurn(options: SetRuntimeTurnOptions): Promise<void>;
     setTyping(conversationId: string, typing: boolean, status?: 'thinking' | 'typing'): Promise<void>;
     createRuntimeInputRequest(options: {
         conversationId: string;

package/dist/client.js

@@ -310,6 +310,15 @@ export class CanonClient {
         if (!res.ok)
             throw new CanonApiError(res.status, await res.text());
     }
+    async setRuntimeTurn(options) {
+        const res = await fetch(`${this.baseUrl}/runtime/turn`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
     async setTyping(conversationId, typing, status) {
         const res = await fetch(`${this.baseUrl}/typing`, {
             method: 'POST',

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonRuntimeProvenance, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonRuntimeProvenance, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, SetRuntimeTurnOptions, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export { DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, RUNTIME_PRESENTATION_FIELDS, buildRuntimePresentationPolicy, getRuntimePresentationHint, isRuntimePresentationField, isRuntimePresentationFieldHidden, redactAgentRuntimeForConversation, redactAgentSessionSnapshotForConversation, redactExecutionMetadataForConversation, redactRuntimeActivityItemForConversation, redactRuntimeDescriptorForConversation, redactRuntimeInfoForConversation, redactSessionStateForConversation, } from './runtime-presentation.js';
 export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';
@@ -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

@@ -1,6 +1,6 @@
 import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 import type { ResolvedAgentBehaviorPolicy } from './policy.js';
-import type { TurnLifecycleState } from './turn-protocol.js';
+import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
 import type { CanonSelfContext } from './self-context.js';
 export type { ExecutionEnvironmentMode };
 export type MediaAttachmentKind = 'image' | 'audio' | 'file';
@@ -613,6 +613,23 @@ export interface SetStreamingOptions {
     text: string;
     status: StreamingStatus;
     messageId: string;
+    turnId?: string | null;
+}
+export interface SetRuntimeTurnOptions {
+    conversationId: string;
+    state: TurnLifecycleState;
+    turnId?: string | null;
+    queueDepth?: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: Partial<RuntimeCapabilities>;
+    openedAt?: number | null;
+    /**
+     * Set when this publish represents real turn progress. Omit for heartbeat or
+     * status-only refreshes so Canon can preserve stale-turn recovery semantics.
+     */
+    turnUpdatedAt?: number | null;
 }
 /** Written by Canon app to /control/{convoId}/{agentId}/session in RTDB */
 export interface SessionControl {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.22.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",
@@ -47,7 +47,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "~5.7.0"
+    "typescript": "~5.7.0",
+    "vitest": "^3.0.0"
   },
   "license": "MIT"
 }