@canonmsg/agent-sdk 5.0.0 → 5.1.1

package/dist/canon-agent.d.ts

@@ -53,6 +53,15 @@ export declare class CanonAgent {
     private approvalManager;
     private approvalManagerAgentId;
     private approvalManagerOwnerId;
+    /**
+     * Shared poll/timeout/abort engine for interactive runtime input + card
+     * requests. The server request is still created inline (host-specific
+     * `native`/`responseUserId`), so the descriptors register a no-op `create`
+     * but keep the built-in `cancel`: passing the turn's abort `signal` lets the
+     * manager fire `consume({ cancel: true })` on interrupt, so the hosts no
+     * longer hand-roll a `cancelPendingRequest`.
+     */
+    private runtimeRequestManager;
     private cachedConversationIds;
     private running;
     private runtimeHeartbeatTimer;
@@ -66,6 +75,16 @@ export declare class CanonAgent {
     private sseConnectedLogged;
     constructor(options: CanonAgentOptions);
     private ensureApprovalManager;
+    /**
+     * Shared engine for interactive runtime input + card polling. Unlike approval,
+     * these families do not need an owner (the request is created inline with the
+     * caller's own `responseUserId` policy), so the manager is always available.
+     * The registered descriptors keep the built-in poll/consume/timeout logic and
+     * the built-in `cancel` (best-effort `consume({ cancel: true })`), replacing
+     * only `create` with a no-op because the request is already created inline.
+     * On abort the manager runs that cancel via the passed `signal`.
+     */
+    private ensureRuntimeRequestManager;
     private filterApprovalReplyMessages;
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, sendMessageWithRetry, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, sendMessageWithRetry, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -10,7 +10,6 @@ const RUNTIME_CONTROL_POLL_INTERVAL_MS = 2_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_MESSAGE_ID_READABLE_MAX = 120;
 const SDK_RUNTIME_CAPABILITIES = {
@@ -168,6 +167,9 @@ function safeRuntimeCardId(value) {
         ? normalized
         : `card_${randomUUID()}`;
 }
+function normalizeResponseUserId(value) {
+    return value?.trim() || undefined;
+}
 function buildSdkMessageId(parts) {
     const raw = parts
         .map((part) => part == null ? '' : String(part))
@@ -268,6 +270,15 @@ export class CanonAgent {
     approvalManager = null;
     approvalManagerAgentId = null;
     approvalManagerOwnerId = null;
+    /**
+     * Shared poll/timeout/abort engine for interactive runtime input + card
+     * requests. The server request is still created inline (host-specific
+     * `native`/`responseUserId`), so the descriptors register a no-op `create`
+     * but keep the built-in `cancel`: passing the turn's abort `signal` lets the
+     * manager fire `consume({ cancel: true })` on interrupt, so the hosts no
+     * longer hand-roll a `cancelPendingRequest`.
+     */
+    runtimeRequestManager = null;
     cachedConversationIds = [];
     running = false;
     runtimeHeartbeatTimer = null;
@@ -354,6 +365,33 @@ export class CanonAgent {
         this.approvalManagerOwnerId = ownerId;
         return this.approvalManager;
     }
+    /**
+     * Shared engine for interactive runtime input + card polling. Unlike approval,
+     * these families do not need an owner (the request is created inline with the
+     * caller's own `responseUserId` policy), so the manager is always available.
+     * The registered descriptors keep the built-in poll/consume/timeout logic and
+     * the built-in `cancel` (best-effort `consume({ cancel: true })`), replacing
+     * only `create` with a no-op because the request is already created inline.
+     * On abort the manager runs that cancel via the passed `signal`.
+     */
+    ensureRuntimeRequestManager() {
+        if (!this.runtimeRequestManager) {
+            const manager = new RuntimeRequestManager(this.apiClient, {
+                agentId: this.agentId ?? '',
+                ownerId: '',
+            });
+            manager.register('input', {
+                ...runtimeInputDescriptor,
+                create: async ({ requestId }) => ({ requestId }),
+            });
+            manager.register('card', {
+                ...runtimeCardDescriptor,
+                create: async ({ requestId }) => ({ requestId }),
+            });
+            this.runtimeRequestManager = manager;
+        }
+        return this.runtimeRequestManager;
+    }
     filterApprovalReplyMessages(conversationId, messages) {
         const manager = this.ensureApprovalManager();
         if (!manager) {
@@ -1275,6 +1313,9 @@ export class CanonAgent {
                 }
             }
             const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
+            const triggeringHumanId = latestMessage?.senderType === 'human'
+                ? normalizeResponseUserId(latestMessage.senderId)
+                : undefined;
             let replyContext = latestMessage
                 ? resolveCanonReplyContext({ message: latestMessage, messages: history })
                 : null;
@@ -1438,6 +1479,11 @@ export class CanonAgent {
                         await this.typingSignals.clear(conversationId);
                     }
                     catch { }
+                    const responseUserId = normalizeResponseUserId(request.responseUserId)
+                        ?? triggeringHumanId;
+                    // Session-wide rules are owner-scoped. The effective responder, not
+                    // merely the member who triggered the turn, determines that scope.
+                    const mustIsolateSessionRules = Boolean(responseUserId && responseUserId !== agent.ownerId);
                     const result = await manager.requestApproval(conversationId, request.toolName, request.toolInput ?? {}, {
                         riskLevel: request.riskLevel,
                         risk: request.risk,
@@ -1447,8 +1493,9 @@ export class CanonAgent {
                         native: request.native,
                         toolSummary: request.toolSummary,
                         details: request.details,
-                        ignoreSessionRules: request.ignoreSessionRules,
-                        allowSessionRule: request.allowSessionRule,
+                        ...(responseUserId ? { responseUserId } : {}),
+                        ignoreSessionRules: mustIsolateSessionRules ? true : request.ignoreSessionRules,
+                        allowSessionRule: mustIsolateSessionRules ? false : request.allowSessionRule,
                     });
                     throwIfAborted();
                     shouldPersistTurnState = false;
@@ -1481,20 +1528,15 @@ export class CanonAgent {
                 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 { }
-                };
+                const ownerOnly = request.kind === 'secret'
+                    || request.kind === 'sudo'
+                    || request.sensitive === true
+                    || Boolean(request.questions?.some((question) => question.isSecret));
+                const responseUserId = ownerOnly
+                    ? normalizeResponseUserId(agent.ownerId)
+                    : normalizeResponseUserId(request.responseUserId)
+                        ?? triggeringHumanId
+                        ?? normalizeResponseUserId(agent.ownerId);
                 shouldPersistTurnState = true;
                 try {
                     await this.apiClient.createRuntimeInputRequest({
@@ -1502,7 +1544,7 @@ export class CanonAgent {
                         inputId,
                         kind: request.kind,
                         expiresAt: expiresAtMs,
-                        responseUserId: agent.ownerId,
+                        ...(responseUserId ? { responseUserId } : {}),
                         title: request.title,
                         prompt: request.prompt,
                         ...(request.choices ? { choices: request.choices } : {}),
@@ -1529,56 +1571,15 @@ export class CanonAgent {
                         await this.typingSignals.clear(conversationId);
                     }
                     catch { }
-                    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,
-                                    answers: response.answers,
-                                    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,
-                                    answers: response.answers,
-                                    inputId,
-                                };
-                            }
-                            else if (response.status === 'cancelled' || response.status === 'timeout') {
-                                result = { status: response.status, inputId };
-                            }
-                        }
-                        catch { }
-                        requestResolved = true;
-                    }
+                    // The shared engine owns the poll-with-abort loop + post-deadline
+                    // consume; the request was already created above, so the descriptor's
+                    // create is a no-op. On abort the manager fires the descriptor's
+                    // built-in cancel (consume({ cancel: true })) via the passed signal.
+                    result = await this.ensureRuntimeRequestManager().request('input', conversationId, { kind: request.kind }, {
+                        requestId: inputId,
+                        expiresAt: expiresAtMs,
+                        signal: abortController.signal,
+                    });
                     const outcome = buildRuntimeInputOutcome(inputId, result.status, {
                         kind: request.kind,
                         reason: result.status,
@@ -1607,8 +1608,16 @@ export class CanonAgent {
                     return result;
                 }
                 catch (error) {
-                    await cancelPendingRequest();
                     if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        if (requestCreated) {
+                            // Abort landing before the manager wired its cancel (e.g. during
+                            // the pre-request writeTurn/typing round-trips) leaves the
+                            // server-side request pending + responder-actionable; cancel it so
+                            // a late (possibly sensitive) answer can't resolve a dead request.
+                            await this.apiClient
+                                .consumeRuntimeInputResponse({ conversationId, inputId, cancel: true })
+                                .catch(() => { });
+                        }
                         throw error;
                     }
                     if (!requestCreated) {
@@ -1633,9 +1642,20 @@ export class CanonAgent {
                 const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
                     ? explicitExpiresAt
                     : Date.now() + timeoutMs;
+                const responseUserId = normalizeResponseUserId(request.responseUserId)
+                    ?? triggeringHumanId;
+                const routedRequest = responseUserId
+                    ? { ...request, responseUserId }
+                    : request;
                 // Fire-and-forget: post the durable card and return. The backend treats an
                 // action-less card as display (no pending state, no response expected).
-                await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({
+                    request: routedRequest,
+                    conversationId,
+                    cardId,
+                    fallbackTurnId: turnId,
+                    expiresAtMs,
+                }));
                 try {
                     await turnOutput.addBlock({
                         id: `card:${cardId}`,
@@ -1667,25 +1687,23 @@ export class CanonAgent {
                 const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
                     ? explicitExpiresAt
                     : Date.now() + timeoutMs;
+                const responseUserId = normalizeResponseUserId(request.responseUserId)
+                    ?? triggeringHumanId;
+                const routedRequest = responseUserId
+                    ? { ...request, responseUserId }
+                    : request;
                 let result = { status: 'timeout', cardId };
                 let requestCreated = false;
                 let requestResolved = false;
-                const cancelPendingRequest = async () => {
-                    if (!requestCreated || requestResolved)
-                        return;
-                    try {
-                        await this.apiClient.consumeRuntimeCardResponse({
-                            conversationId,
-                            cardId,
-                            cancel: true,
-                        });
-                        requestResolved = true;
-                    }
-                    catch { }
-                };
                 shouldPersistTurnState = true;
                 try {
-                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({
+                        request: routedRequest,
+                        conversationId,
+                        cardId,
+                        fallbackTurnId: turnId,
+                        expiresAtMs,
+                    }));
                     requestCreated = true;
                     try {
                         await turnOutput.addBlock({
@@ -1703,56 +1721,16 @@ export class CanonAgent {
                         await this.typingSignals.clear(conversationId);
                     }
                     catch { }
-                    while (Date.now() < expiresAtMs) {
-                        throwIfAborted();
-                        try {
-                            const response = await this.apiClient.consumeRuntimeCardResponse({
-                                conversationId,
-                                cardId,
-                            });
-                            if (response.status === 'submitted') {
-                                requestResolved = true;
-                                result = {
-                                    status: 'submitted',
-                                    cardId,
-                                    ...(response.actionId ? { actionId: response.actionId } : {}),
-                                    ...(response.values ? { values: response.values } : {}),
-                                };
-                                break;
-                            }
-                            if (response.status === 'cancelled' || response.status === 'timeout') {
-                                requestResolved = true;
-                                result = { status: response.status, cardId };
-                                break;
-                            }
-                        }
-                        catch {
-                            // Keep waiting; the control path is the authoritative source and
-                            // transient consume failures should not leak response values.
-                        }
-                        await sleepWithAbort(Math.min(RUNTIME_INPUT_POLL_MS, Math.max(1, expiresAtMs - Date.now())), abortController.signal);
-                    }
-                    if (!requestResolved) {
-                        try {
-                            const response = await this.apiClient.consumeRuntimeCardResponse({
-                                conversationId,
-                                cardId,
-                            });
-                            if (response.status === 'submitted') {
-                                result = {
-                                    status: 'submitted',
-                                    cardId,
-                                    ...(response.actionId ? { actionId: response.actionId } : {}),
-                                    ...(response.values ? { values: response.values } : {}),
-                                };
-                            }
-                            else if (response.status === 'cancelled' || response.status === 'timeout') {
-                                result = { status: response.status, cardId };
-                            }
-                        }
-                        catch { }
-                        requestResolved = true;
-                    }
+                    // The shared engine owns the poll-with-abort loop + post-deadline
+                    // consume; the request was already created above, so the descriptor's
+                    // create is a no-op. On abort the manager fires the descriptor's
+                    // built-in cancel (consume({ cancel: true })) via the passed signal.
+                    result = await this.ensureRuntimeRequestManager().request('card', conversationId, { card: request.card }, {
+                        requestId: cardId,
+                        expiresAt: expiresAtMs,
+                        signal: abortController.signal,
+                    });
+                    requestResolved = true;
                     // The interactive path never yields 'displayed' (that returns early via
                     // sendCard); narrow for buildRuntimeCardOutcome's resolution status.
                     const resolutionStatus = result.status === 'displayed' ? 'timeout' : result.status;
@@ -1784,9 +1762,14 @@ export class CanonAgent {
                 }
                 catch (error) {
                     const shouldSendInterruptedOutcome = requestCreated && !requestResolved;
-                    await cancelPendingRequest();
                     if (abortController.signal.aborted || isAbortLikeError(error)) {
                         if (shouldSendInterruptedOutcome) {
+                            // Cancel the server-side card if the abort landed before the
+                            // manager wired its cancel, so a late action can't resolve a dead
+                            // request (mirrors the runtime-input path).
+                            await this.apiClient
+                                .consumeRuntimeCardResponse({ conversationId, cardId, cancel: true })
+                                .catch(() => { });
                             const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
                             await sendDurableMessage(outcome.text, {
                                 metadata: {

package/dist/types.d.ts

@@ -59,6 +59,8 @@ export interface RuntimeApprovalRequest {
     turnId?: string;
     native?: ApprovalNativeRequestMetadata;
     details?: ApprovalRequestDetail[];
+    /** Human conversation member who should answer. Defaults to the triggering human. */
+    responseUserId?: string;
     /**
      * Ignore in-memory session rules for this approval request. Useful when the
      * action was triggered by someone other than the agent owner.
@@ -80,6 +82,8 @@ export interface RuntimeInputRequest {
     native?: RuntimeInputNativeMetadata;
     inputId?: string;
     timeoutMs?: number;
+    /** Human conversation member who should answer. Secret and sudo prompts remain owner-only. */
+    responseUserId?: string;
 }
 export interface RuntimeInputResult {
     status: 'submitted' | 'cancelled' | 'timeout';
@@ -91,6 +95,7 @@ export interface RuntimeCardRequest {
     card: RuntimeCardV1;
     cardId?: string;
     expiresAt?: string | number | Date;
+    /** Human conversation member who should answer. Defaults to the triggering human. */
     responseUserId?: string;
     timeoutMs?: number;
     runtimeId?: string;
@@ -155,21 +160,21 @@ export interface MessageHandlerContext {
     /** Runtime turn mode requested by the sender for this inbound turn, if any. */
     requestedTurnMode: string | null;
     /**
-     * Ask the conversation owner to approve a native runtime action. This only
+     * Ask the triggering human to approve a native runtime action. This only
      * renders Canon's inline approval card; runtimes must explicitly wait for
      * 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.
+     * Ask the triggering human for runtime input. Secret and sudo prompts remain
+     * owner-only. Sensitive values are returned only to the calling runtime and
+     * are never persisted in Canon message metadata.
      */
     requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
     /**
-     * Ask the agent owner to review/respond to a generic rich card. The visible
-     * card document is redacted for presentation; raw response values return
-     * only to the calling runtime through Canon's control path.
+     * Ask the triggering human to review/respond to a generic rich card. The
+     * visible card document is redacted for presentation; raw response values
+     * return only to the calling runtime through Canon's control path.
      */
     requestCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "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": "^4.0.0"
+    "@canonmsg/core": "^4.2.2"
   },
   "publishConfig": {
     "access": "public"