@canonmsg/agent-sdk 1.5.3 → 1.5.5

package/dist/canon-agent.d.ts

@@ -140,6 +140,7 @@ export declare class CanonAgent {
     private publishAcceptedRuntimeSignal;
     private abortActiveTurns;
     private resolveBatchDeliveryIntent;
+    private markQueuedMessagesAccepted;
     private notifyMessageInterrupt;
     private createRuntimeStatePublisher;
     private requireRuntimeStatePublisher;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
+import { ApprovalManager, CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeInputOutcome, buildRuntimeInputRequest, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -7,6 +7,9 @@ import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
 const RUNTIME_PRIMITIVE_DEDUPE_MAX = 1_000;
+const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
+const RUNTIME_INPUT_POLL_MS = 1_000;
+const RUNTIME_INPUT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsInputInterrupt: false,
@@ -125,6 +128,24 @@ const STANDARD_PRIMITIVE_COMMANDS = {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function sleepWithAbort(ms, signal) {
+    if (signal.aborted)
+        return Promise.reject(createTurnAbortError());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(createTurnAbortError());
+        }, { once: true });
+    });
+}
+function safeRuntimeInputId(value, kind) {
+    const raw = value?.trim() || `${kind}_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 160);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `${kind}_${randomUUID()}`;
+}
 function isRuntimePrimitiveId(value) {
     return value === 'runtime.status'
         || value === 'runtime.reasoning.set'
@@ -227,6 +248,7 @@ export class CanonAgent {
             debounceMs: 2000,
             historyLimit: 50,
             autoMarkRead: true,
+            runtimeControlSurface: 'agent',
             ...options,
         };
         this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
@@ -983,6 +1005,14 @@ export class CanonAgent {
             ? 'interrupt'
             : 'queue';
     }
+    async markQueuedMessagesAccepted(conversationId, messages) {
+        await Promise.all(messages.map((message) => {
+            if (!message.id || normalizeTurnMetadata(message.metadata)?.inboundDisposition !== 'queued') {
+                return Promise.resolve();
+            }
+            return this.apiClient.updateMessageDisposition(conversationId, message.id, 'accepted_now').catch(() => { });
+        }));
+    }
     async notifyMessageInterrupt(conversationId, abortSignal) {
         if (!abortSignal || !this.interruptHandler)
             return;
@@ -1001,7 +1031,7 @@ export class CanonAgent {
         return createRuntimeStatePublisher({
             agentId: this.agentId,
             clientType: this.options.clientType ?? 'generic',
-            hostMode: false,
+            hostMode: this.options.runtimeControlSurface === 'host',
         });
     }
     requireRuntimeStatePublisher() {
@@ -1037,6 +1067,7 @@ export class CanonAgent {
     async executeHandler(conversationId, messages, session, provenanceByMessageId) {
         if (!this.handler)
             return;
+        await this.markQueuedMessagesAccepted(conversationId, messages);
         const turnId = randomUUID();
         const turnOpenedAt = Date.now();
         let turnState = 'thinking';
@@ -1337,6 +1368,139 @@ export class CanonAgent {
                     return { decision: 'deny' };
                 }
             };
+            const requestRuntimeInput = async (request) => {
+                throwIfAborted();
+                const inputId = safeRuntimeInputId(request.inputId, request.kind);
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = Date.now() + timeoutMs;
+                const expiresAt = new Date(expiresAtMs).toISOString();
+                let result = { status: 'timeout', inputId };
+                let requestCreated = false;
+                let requestResolved = false;
+                const cancelPendingRequest = async () => {
+                    if (!requestCreated || requestResolved)
+                        return;
+                    try {
+                        await this.apiClient.consumeRuntimeInputResponse({
+                            conversationId,
+                            inputId,
+                            cancel: true,
+                        });
+                        requestResolved = true;
+                    }
+                    catch { }
+                };
+                shouldPersistTurnState = true;
+                try {
+                    await this.apiClient.createRuntimeInputRequest({
+                        conversationId,
+                        inputId,
+                        kind: request.kind,
+                        expiresAt: expiresAtMs,
+                    });
+                    requestCreated = true;
+                    try {
+                        await this.apiClient.clearStreaming(conversationId);
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.apiClient.setTyping(conversationId, false);
+                    }
+                    catch { }
+                    const card = buildRuntimeInputRequest(inputId, {
+                        kind: request.kind,
+                        responseUserId: agent.ownerId,
+                        title: request.title,
+                        prompt: request.prompt,
+                        ...(request.choices ? { choices: request.choices } : {}),
+                        ...(request.secretName ? { secretName: request.secretName } : {}),
+                        ...(request.native ? { native: request.native } : {}),
+                        expiresAt,
+                        ...(request.sensitive !== undefined ? { sensitive: request.sensitive } : {}),
+                    });
+                    await this.apiClient.sendMessage(conversationId, card.text, {
+                        metadata: {
+                            ...card.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    });
+                    while (Date.now() < expiresAtMs) {
+                        throwIfAborted();
+                        try {
+                            const response = await this.apiClient.consumeRuntimeInputResponse({
+                                conversationId,
+                                inputId,
+                            });
+                            if (response.status === 'submitted') {
+                                requestResolved = true;
+                                result = {
+                                    status: 'submitted',
+                                    value: response.value,
+                                    inputId,
+                                };
+                                break;
+                            }
+                            if (response.status === 'cancelled' || response.status === 'timeout') {
+                                requestResolved = true;
+                                result = { status: response.status, inputId };
+                                break;
+                            }
+                        }
+                        catch {
+                            // Transient consume failures should not leak sensitive input or
+                            // break the runtime; keep waiting until the explicit timeout.
+                        }
+                        await sleepWithAbort(Math.min(RUNTIME_INPUT_POLL_MS, Math.max(1, expiresAtMs - Date.now())), abortController.signal);
+                    }
+                    if (!requestResolved) {
+                        try {
+                            const response = await this.apiClient.consumeRuntimeInputResponse({
+                                conversationId,
+                                inputId,
+                            });
+                            if (response.status === 'submitted') {
+                                result = { status: 'submitted', value: response.value, inputId };
+                            }
+                            else if (response.status === 'cancelled' || response.status === 'timeout') {
+                                result = { status: response.status, inputId };
+                            }
+                        }
+                        catch { }
+                        requestResolved = true;
+                    }
+                    const outcome = buildRuntimeInputOutcome(inputId, result.status, {
+                        kind: request.kind,
+                        reason: result.status,
+                    });
+                    await this.apiClient.sendMessage(conversationId, outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await this.apiClient.setTyping(conversationId, true, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    await cancelPendingRequest();
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return result;
+                }
+            };
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
             const replyWithFile = async (filePath, text = '', options) => {
                 throwIfAborted();
@@ -1399,6 +1563,7 @@ export class CanonAgent {
                 selfContexts,
                 provenance,
                 requestApproval,
+                requestRuntimeInput,
                 abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, parseTextApprovalReply, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, SessionRule, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -56,6 +56,24 @@ export interface RuntimeApprovalRequest {
     /** Whether an approval reply may set an in-memory session rule. */
     allowSessionRule?: boolean;
 }
+export interface RuntimeInputRequest {
+    kind: RuntimeInputKind;
+    title: string;
+    prompt: string;
+    choices?: RuntimeInputChoice[];
+    secretName?: string;
+    sensitive?: boolean;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeInputNativeMetadata;
+    inputId?: string;
+    timeoutMs?: number;
+}
+export interface RuntimeInputResult {
+    status: 'submitted' | 'cancelled' | 'timeout';
+    value?: string;
+    inputId: string;
+}
 export interface MessageHandlerContext {
     messages: CanonMessage[];
     history: CanonMessage[];
@@ -109,6 +127,12 @@ export interface MessageHandlerContext {
      * and enforce the returned decision in their own approval hook.
      */
     requestApproval: (request: RuntimeApprovalRequest) => Promise<ApprovalResult>;
+    /**
+     * Ask the agent owner for runtime input such as clarification, sudo, or a
+     * secret. Sensitive values are returned only to the calling runtime and are
+     * never persisted in Canon message metadata.
+     */
+    requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
@@ -155,6 +179,7 @@ export interface RuntimeControlHandlers {
     onStopAndDrop?: RuntimeSignalHandler;
     onNewSession?: RuntimeSignalHandler;
 }
+export type RuntimeControlSurface = 'agent' | 'host';
 export interface RuntimePrimitiveContext {
     conversationId: string;
     primitive: CanonRuntimePrimitiveId;
@@ -186,6 +211,8 @@ export interface CanonAgentOptions {
     runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
     /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
     runtimeControls?: RuntimeControlHandlers;
+    /** Runtime publishing surface. Use `host` when this agent owns live runtime controls. */
+    runtimeControlSurface?: RuntimeControlSurface;
     /** Optional typed runtime primitive handlers. Enables descriptor-backed command controls when provided. */
     runtimePrimitives?: RuntimePrimitiveHandlers;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^0.20.0"
+    "@canonmsg/core": "^0.21.0"
   },
   "publishConfig": {
     "access": "public"