@canonmsg/core 0.21.0 → 0.23.0

package/dist/approval-manager.js

@@ -50,7 +50,7 @@ export class ApprovalManager {
         }
         const approvalId = generateApprovalId();
         const expiresAt = new Date(Date.now() + this.config.timeoutSeconds * 1000).toISOString();
-        const { text, metadata } = buildApprovalRequest(approvalId, toolName, toolInput, {
+        const { metadata } = buildApprovalRequest(approvalId, toolName, toolInput, {
             riskLevel: opts?.riskLevel,
             risk: opts?.risk,
             category: opts?.category,
@@ -63,29 +63,47 @@ export class ApprovalManager {
             expiresAt,
             redactPatterns: this.config.redactPatterns,
         });
-        // Send the approval request message with metadata
-        // Spread to satisfy Record<string, unknown> without double cast
-        await this.client.sendMessage(conversationId, text, {
-            metadata: {
-                ...metadata,
-                turnSemantics: 'control',
-                replyBehavior: 'suppress_auto_reply',
-            },
+        await this.client.createRuntimeApprovalRequest({
+            conversationId,
+            approvalId,
+            toolName,
+            toolSummary: metadata.toolSummary,
+            expiresAt: Date.parse(expiresAt),
+            responseUserId: this.ownerId,
+            ...(opts?.riskLevel ? { riskLevel: opts.riskLevel } : {}),
+            ...(opts?.risk ? { risk: opts.risk } : {}),
+            ...(opts?.category ? { category: opts.category } : {}),
+            ...(opts?.runtimeId ? { runtimeId: opts.runtimeId } : {}),
+            ...(opts?.turnId ? { turnId: opts.turnId } : {}),
+            ...(metadata.native ? { native: metadata.native } : {}),
+            ...(metadata.details ? { details: metadata.details } : {}),
+            ...(opts?.allowSessionRule === false ? { allowSessionRule: false } : {}),
         });
         // Wait for reply or timeout
         return new Promise((resolve) => {
-            const timer = setTimeout(() => {
+            let settled = false;
+            let timer;
+            const finish = (result, reason) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
                 this.pending.delete(approvalId);
-                const msg = buildApprovalOutcome(approvalId, toolName, metadata.toolSummary, 'deny', 'timeout');
-                this.client.sendMessage(conversationId, msg, {
-                    metadata: {
-                        type: 'approval_outcome',
-                        approvalId,
-                        decision: 'deny',
-                        reason: 'timeout',
-                    },
-                }).catch(() => { });
-                resolve({ decision: 'deny' });
+                if (reason === 'timeout') {
+                    const msg = buildApprovalOutcome(approvalId, toolName, metadata.toolSummary, 'deny', 'timeout');
+                    this.client.sendMessage(conversationId, msg, {
+                        metadata: {
+                            type: 'approval_outcome',
+                            approvalId,
+                            decision: 'deny',
+                            reason: 'timeout',
+                        },
+                    }).catch(() => { });
+                }
+                resolve(result);
+            };
+            timer = setTimeout(() => {
+                finish({ decision: 'deny' }, 'timeout');
             }, this.config.timeoutSeconds * 1000);
             this.pending.set(approvalId, {
                 approvalId,
@@ -93,9 +111,32 @@ export class ApprovalManager {
                 toolName,
                 toolSummary: metadata.toolSummary,
                 allowSessionRule: opts?.allowSessionRule !== false,
-                resolve,
+                resolve: (result) => finish(result, 'replied'),
                 timer,
             });
+            const poll = async () => {
+                while (this.pending.has(approvalId)) {
+                    try {
+                        const response = await this.client.consumeRuntimeApprovalResponse({
+                            conversationId,
+                            approvalId,
+                        });
+                        if (response.status === 'allow' || response.status === 'deny') {
+                            this.resolveApproval(approvalId, response.status, response.sessionRule, conversationId);
+                            return;
+                        }
+                        if (response.status === 'timeout') {
+                            finish({ decision: 'deny' }, 'timeout');
+                            return;
+                        }
+                    }
+                    catch {
+                        // Keep polling through transient API errors until the local timeout.
+                    }
+                    await new Promise((resume) => setTimeout(resume, 1000));
+                }
+            };
+            void poll();
         });
     }
     /**

package/dist/client.d.ts

@@ -1,5 +1,7 @@
-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';
 import type { SendContextualMessageOptions, SendContextualMessageResult } from './self-context.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -53,16 +55,26 @@ 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;
         inputId: string;
         kind: RuntimeInputKind;
         expiresAt: number;
+        title?: string;
+        prompt?: string;
+        choices?: RuntimeInputChoice[];
+        secretName?: string;
+        native?: RuntimeInputNativeMetadata;
+        sensitive?: boolean;
+        responseUserId?: string;
+        turnId?: string;
     }): Promise<{
         success: true;
         inputId: string;
         expiresAt: number;
+        messageId?: string;
     }>;
     consumeRuntimeInputResponse(options: {
         conversationId: string;
@@ -86,6 +98,52 @@ export declare class CanonClient {
         inputId: string;
         kind: RuntimeInputKind;
     }>;
+    createRuntimeApprovalRequest(options: {
+        conversationId: string;
+        approvalId?: string;
+        toolName: string;
+        toolSummary: string;
+        expiresAt: number;
+        responseUserId?: string;
+        riskLevel?: 'normal' | 'destructive';
+        risk?: ApprovalRisk;
+        category?: ApprovalRequestCategory;
+        runtimeId?: string;
+        turnId?: string;
+        native?: ApprovalNativeRequestMetadata;
+        details?: ApprovalRequestDetail[];
+        allowSessionRule?: boolean;
+    }): Promise<{
+        success: true;
+        approvalId: string;
+        expiresAt: number;
+        messageId?: string;
+    }>;
+    consumeRuntimeApprovalResponse(options: {
+        conversationId: string;
+        approvalId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        approvalId: string;
+        expiresAt?: number;
+    } | {
+        status: 'allow';
+        approvalId: string;
+        sessionRule?: SessionRule;
+    } | {
+        status: 'deny';
+        approvalId: string;
+        sessionRule?: SessionRule;
+    } | {
+        status: 'timeout';
+        approvalId: string;
+    }>;
+    updateRuntimeStatus(options: {
+        runtime: string;
+        hostMode?: boolean;
+        runtimeDescriptor?: Record<string, unknown>;
+    }): Promise<void>;
     static register(baseUrl: string | undefined, body: {
         name: string;
         description: 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',
@@ -339,6 +348,35 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
+    async createRuntimeApprovalRequest(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-approval/request`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async consumeRuntimeApprovalResponse(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-approval/consume`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async updateRuntimeStatus(options) {
+        const res = await fetch(`${this.baseUrl}/runtime/status`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
     // ── Static unauthenticated registration endpoints ────────────────────
     static async register(baseUrl, body) {
         const url = baseUrl || DEFAULT_BASE_URL;

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';

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';
@@ -614,6 +614,22 @@ export interface SetStreamingOptions {
     status: StreamingStatus;
     messageId: string;
 }
+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 {
     model?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.21.0",
+  "version": "0.23.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"
 }