@canonmsg/agent-sdk 7.1.3 → 8.0.0

package/dist/auth.d.ts

@@ -1,11 +1,8 @@
 import { CanonClient } from '@canonmsg/core';
 export declare class AuthManager {
     private apiClient;
-    private token;
-    private agentId;
     private expiresAt;
     private refreshTimer;
-    private onRefreshCallback;
     private refreshRetryCount;
     constructor(apiClient: CanonClient);
     authenticate(): Promise<{
@@ -15,8 +12,5 @@ export declare class AuthManager {
     private scheduleRefresh;
     /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
     private scheduleRetry;
-    setOnRefresh(cb: (token: string) => void): void;
-    getToken(): string | null;
-    getAgentId(): string | null;
     destroy(): void;
 }

package/dist/auth.js

@@ -3,19 +3,14 @@ const BASE_RETRY_MS = 30_000;
 const MAX_RETRY_BACKOFF_MS = 240_000;
 export class AuthManager {
     apiClient;
-    token = null;
-    agentId = null;
     expiresAt = 0;
     refreshTimer = null;
-    onRefreshCallback = null;
     refreshRetryCount = 0;
     constructor(apiClient) {
         this.apiClient = apiClient;
     }
     async authenticate() {
         const result = await this.apiClient.getAuthToken();
-        this.token = result.token;
-        this.agentId = result.agentId;
         this.expiresAt = new Date(result.expiresAt).getTime();
         this.refreshRetryCount = 0;
         this.scheduleRefresh();
@@ -29,12 +24,9 @@ export class AuthManager {
         this.refreshTimer = setTimeout(async () => {
             try {
                 const result = await this.apiClient.getAuthToken();
-                this.token = result.token;
                 this.expiresAt = new Date(result.expiresAt).getTime();
                 this.refreshRetryCount = 0;
                 this.scheduleRefresh();
-                if (this.onRefreshCallback)
-                    this.onRefreshCallback(result.token);
             }
             catch (err) {
                 console.error('[canon-sdk] Token refresh failed:', err);
@@ -53,21 +45,10 @@ export class AuthManager {
         console.warn(`[canon-sdk] Retrying token refresh in ${backoff / 1000}s (attempt ${this.refreshRetryCount}/${MAX_REFRESH_RETRIES})`);
         this.refreshTimer = setTimeout(() => this.scheduleRefresh(), backoff);
     }
-    setOnRefresh(cb) {
-        this.onRefreshCallback = cb;
-    }
-    getToken() {
-        return this.token;
-    }
-    getAgentId() {
-        return this.agentId;
-    }
     destroy() {
         if (this.refreshTimer) {
             clearTimeout(this.refreshTimer);
             this.refreshTimer = null;
         }
-        this.token = null;
-        this.agentId = null;
     }
 }

package/dist/canon-agent.d.ts

@@ -103,7 +103,7 @@ export declare class CanonAgent {
     on(event: 'callStarted', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
     on(event: 'callEnded', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
     onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
-    describeCommands(_provider?: string): ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    describeCommands(): ReadonlyArray<CanonRuntimeCommandDescriptor>;
     publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
     publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
     clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;

package/dist/canon-agent.js

@@ -2,15 +2,13 @@ import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtime
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
-import { buildRuntimeCardCreateArgs } from './runtime-card.js';
+import { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } from './runtime-card.js';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 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_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
 const SDK_MESSAGE_ID_READABLE_MAX = 120;
 /** Canon's message id ceiling, matching core's chunked sender. */
 const CANON_MESSAGE_ID_MAX = 160;
@@ -163,16 +161,6 @@ function safeRuntimeInputId(value, kind) {
         ? normalized
         : `${kind}_${randomUUID()}`;
 }
-function safeRuntimeCardId(value) {
-    const raw = value?.trim() || `card_${randomUUID()}`;
-    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 80);
-    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
-        ? normalized
-        : `card_${randomUUID()}`;
-}
-function normalizeResponseUserId(value) {
-    return value?.trim() || undefined;
-}
 /**
  * Part id for text this sdk split itself, mirroring the `-part-N` rule (and the
  * 160-character id cap) that core's chunked sender applies to a split final, so
@@ -523,7 +511,7 @@ export class CanonAgent {
         }
         void this.publishAgentRuntime().catch(() => { });
     }
-    describeCommands(_provider) {
+    describeCommands() {
         return this.buildRuntimeDescriptor().commands ?? [];
     }
     async publishRuntimeFacts(conversationId, facts) {
@@ -690,7 +678,7 @@ export class CanonAgent {
         // 4. Start delivery
         const { RealtimeManager } = await import('./realtime.js');
         this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
-        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient, { enableVoiceEvents: this.voiceEventsEnabled });
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled });
         if (this.voiceEventsEnabled) {
             rtm.setCallHandlers({
                 onCallStarted: (payload) => {
@@ -1208,11 +1196,15 @@ export class CanonAgent {
     createRuntimeStatePublisher() {
         if (!this.agentId)
             return null;
+        // start() assigns rtdbHandle before agentId, so this can only be null
+        // when the agent has not started — same condition as the guard above.
+        if (!this.rtdbHandle)
+            return null;
         return createRuntimeStatePublisher({
             agentId: this.agentId,
             clientType: this.options.clientType ?? 'generic',
             hostMode: this.options.runtimeControlSurface === 'host',
-            ...(this.rtdbHandle ? { rtdb: this.rtdbHandle } : {}),
+            rtdb: this.rtdbHandle,
         });
     }
     requireRuntimeStatePublisher() {
@@ -1566,7 +1558,7 @@ export class CanonAgent {
                 agent,
                 membershipChange,
             });
-            const participationHistory = buildParticipationHistorySnapshot(history, agent.agentId);
+            const participationHistory = buildParticipationHistorySnapshot(history);
             const turnContext = buildCanonTurnContextV2({
                 content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
                 conversationId,
@@ -1694,7 +1686,6 @@ export class CanonAgent {
                 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;
                 const ownerOnly = request.kind === 'secret'
@@ -1799,23 +1790,10 @@ export class CanonAgent {
             };
             const sendCard = async (request) => {
                 throwIfAborted();
-                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
-                const explicitExpiresAt = request.expiresAt instanceof Date
-                    ? request.expiresAt.getTime()
-                    : typeof request.expiresAt === 'number'
-                        ? request.expiresAt
-                        : typeof request.expiresAt === 'string'
-                            ? Date.parse(request.expiresAt)
-                            : null;
-                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
-                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
-                    ? explicitExpiresAt
-                    : Date.now() + timeoutMs;
-                const responseUserId = normalizeResponseUserId(request.responseUserId)
-                    ?? triggeringHumanId;
-                const routedRequest = responseUserId
-                    ? { ...request, responseUserId }
-                    : request;
+                const { cardId, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
+                    request,
+                    triggeringHumanId,
+                });
                 // 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({
@@ -1844,23 +1822,10 @@ export class CanonAgent {
                     && request.card.blocks.some((block) => block.kind === 'actions');
                 if (!hasActions)
                     return sendCard(request);
-                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
-                const explicitExpiresAt = request.expiresAt instanceof Date
-                    ? request.expiresAt.getTime()
-                    : typeof request.expiresAt === 'number'
-                        ? request.expiresAt
-                        : typeof request.expiresAt === 'string'
-                            ? Date.parse(request.expiresAt)
-                            : null;
-                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
-                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
-                    ? explicitExpiresAt
-                    : Date.now() + timeoutMs;
-                const responseUserId = normalizeResponseUserId(request.responseUserId)
-                    ?? triggeringHumanId;
-                const routedRequest = responseUserId
-                    ? { ...request, responseUserId }
-                    : request;
+                const { cardId, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
+                    request,
+                    triggeringHumanId,
+                });
                 let result = { status: 'timeout', cardId };
                 let requestCreated = false;
                 let requestResolved = false;

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -8,9 +8,7 @@ import { Debouncer } from './debouncer.js';
  */
 export declare class RealtimeManager {
     private debouncer;
-    private agentId;
     private stream;
-    private running;
     /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
     private readonly recentInboundMessageIds;
     private lastSseErrorKey;
@@ -28,7 +26,7 @@ export declare class RealtimeManager {
     private onDisconnected;
     private onCallStarted;
     private onCallEnded;
-    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient, options?: {
+    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, options?: {
         enableVoiceEvents?: boolean;
     });
     private hasSeenInboundMessage;

package/dist/realtime.js

@@ -1,12 +1,6 @@
 import { CanonStream, } from '@canonmsg/core';
 const RECENT_INBOUND_TTL_MS = 30 * 60 * 1000;
 const MAX_RECENT_INBOUND_MESSAGE_IDS = 5000;
-function messageCreatedAtMs(createdAt) {
-    if (!createdAt)
-        return 0;
-    const parsed = new Date(createdAt).getTime();
-    return Number.isFinite(parsed) ? parsed : 0;
-}
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
@@ -15,9 +9,7 @@ function messageCreatedAtMs(createdAt) {
  */
 export class RealtimeManager {
     debouncer;
-    agentId;
     stream;
-    running = false;
     /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
     recentInboundMessageIds = new Map();
     lastSseErrorKey = null;
@@ -35,9 +27,8 @@ export class RealtimeManager {
     onDisconnected = null;
     onCallStarted = null;
     onCallEnded = null;
-    constructor(apiKey, debouncer, agentId, streamUrl, apiClient, options) {
+    constructor(apiKey, debouncer, agentId, streamUrl, options) {
         this.debouncer = debouncer;
-        this.agentId = agentId;
         this.stream = new CanonStream({
             apiKey,
             agentId,
@@ -64,7 +55,7 @@ export class RealtimeManager {
                     if (this.hasSeenInboundMessage(payload.conversationId, payload.message.id)) {
                         return;
                     }
-                    this.recordSeenInboundMessage(payload.conversationId, payload.message.id, messageCreatedAtMs(payload.message.createdAt));
+                    this.recordSeenInboundMessage(payload.conversationId, payload.message.id);
                     if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
                         console.error(`[canon-sdk] Ignoring server-dispatched observe-only message in ${payload.conversationId}: ${payload.turnDispatch.reason}`);
                         return;
@@ -140,10 +131,9 @@ export class RealtimeManager {
     hasSeenInboundMessage(conversationId, messageId) {
         return this.recentInboundMessageIds.has(`${conversationId}:${messageId}`);
     }
-    recordSeenInboundMessage(conversationId, messageId, createdAtMs) {
+    recordSeenInboundMessage(conversationId, messageId) {
         const now = Date.now();
         this.recentInboundMessageIds.set(`${conversationId}:${messageId}`, now);
-        void createdAtMs;
         this.pruneRecentInboundMessageIds(now);
     }
     pruneRecentInboundMessageIds(now = Date.now()) {
@@ -205,11 +195,9 @@ export class RealtimeManager {
         this.onCallEnded = handlers.onCallEnded ?? null;
     }
     async start() {
-        this.running = true;
         await this.stream.start();
     }
     stop() {
-        this.running = false;
         this.stream.stop();
     }
 }

package/dist/runtime-card.d.ts

@@ -1,5 +1,24 @@
 import type { RuntimeCardNativeMetadata, RuntimeCardV1 } from '@canonmsg/core';
 import type { RuntimeCardRequest } from './types';
+export declare const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS: number;
+export declare const RUNTIME_INPUT_ID_PATTERN: RegExp;
+export declare function normalizeResponseUserId(value: string | undefined): string | undefined;
+/**
+ * Resolve the routing prelude shared verbatim by `sendCard` (display) and
+ * `requestCard` (interactive): the sanitized card id, the effective expiry,
+ * and the request with an explicit responder folded in.
+ *
+ * `triggeringHumanId` must be passed in by the caller rather than re-derived
+ * here — it is captured from the enclosing message handler's scope.
+ */
+export declare function resolveRuntimeCardRouting(input: {
+    request: RuntimeCardRequest;
+    triggeringHumanId?: string;
+}): {
+    cardId: string;
+    expiresAtMs: number;
+    routedRequest: RuntimeCardRequest;
+};
 /** Arguments passed to `CanonClient.createRuntimeCardRequest`. */
 export interface RuntimeCardCreateArgs {
     conversationId: string;

package/dist/runtime-card.js

@@ -1,3 +1,45 @@
+import { randomUUID } from 'node:crypto';
+export const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
+export const RUNTIME_INPUT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
+function safeRuntimeCardId(value) {
+    const raw = value?.trim() || `card_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 80);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `card_${randomUUID()}`;
+}
+export function normalizeResponseUserId(value) {
+    return value?.trim() || undefined;
+}
+/**
+ * Resolve the routing prelude shared verbatim by `sendCard` (display) and
+ * `requestCard` (interactive): the sanitized card id, the effective expiry,
+ * and the request with an explicit responder folded in.
+ *
+ * `triggeringHumanId` must be passed in by the caller rather than re-derived
+ * here — it is captured from the enclosing message handler's scope.
+ */
+export function resolveRuntimeCardRouting(input) {
+    const { request, triggeringHumanId } = input;
+    const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+    const explicitExpiresAt = request.expiresAt instanceof Date
+        ? request.expiresAt.getTime()
+        : typeof request.expiresAt === 'number'
+            ? request.expiresAt
+            : typeof request.expiresAt === 'string'
+                ? Date.parse(request.expiresAt)
+                : null;
+    const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+    const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+        ? explicitExpiresAt
+        : Date.now() + timeoutMs;
+    const responseUserId = normalizeResponseUserId(request.responseUserId)
+        ?? triggeringHumanId;
+    const routedRequest = responseUserId
+        ? { ...request, responseUserId }
+        : request;
+    return { cardId, expiresAtMs, routedRequest };
+}
 /**
  * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
  * and `requestCard` (interactive).

package/dist/session-manager.d.ts

@@ -59,8 +59,6 @@ export declare class SessionManager {
     seedHistory(conversationId: string, history: CanonMessage[]): void;
     /** Remove idle sessions */
     private sweep;
-    /** Number of active sessions */
-    get sessionCount(): number;
     /** Number of queued batches waiting behind the active turn for this conversation. */
     getQueueDepth(conversationId: string): number;
     /** Drop one not-yet-running queued message for a conversation. */

package/dist/session-manager.js

@@ -191,10 +191,6 @@ export class SessionManager {
             }
         }
     }
-    /** Number of active sessions */
-    get sessionCount() {
-        return this.sessions.size;
-    }
     /** Number of queued batches waiting behind the active turn for this conversation. */
     getQueueDepth(conversationId) {
         return this.queues.get(conversationId)?.length ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "7.1.3",
+  "version": "8.0.0",
   "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": "^8.2.0"
+    "@canonmsg/core": "^9.0.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/policy-history.d.ts

@@ -1,10 +0,0 @@
-import { type CanonMessage, type ParticipationHistorySnapshot } from '@canonmsg/core';
-export type { ParticipationHistorySnapshot } from '@canonmsg/core';
-/**
- * Builds message-specific participation history snapshots for backlog delivery.
- *
- * `messages` must be ordered newest-first, matching Canon's `getMessages()`
- * API. Each snapshot is computed from older history only, never from the
- * target message itself or newer messages that had not occurred yet.
- */
-export declare function buildParticipationHistorySnapshots(messages: CanonMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy-history.js

@@ -1,11 +0,0 @@
-import { buildParticipationHistorySnapshots as buildSharedParticipationHistorySnapshots, } from '@canonmsg/core';
-/**
- * Builds message-specific participation history snapshots for backlog delivery.
- *
- * `messages` must be ordered newest-first, matching Canon's `getMessages()`
- * API. Each snapshot is computed from older history only, never from the
- * target message itself or newer messages that had not occurred yet.
- */
-export function buildParticipationHistorySnapshots(messages, agentId) {
-    return buildSharedParticipationHistorySnapshots(messages, agentId);
-}

package/dist/turn-filter.d.ts

@@ -1,9 +0,0 @@
-import { type ResolvedAgentBehaviorPolicy, type CanonMessage, type MessageCreatedPayload } from '@canonmsg/core';
-export declare function shouldDispatchInboundMessage(_conversationId: string, agentId: string, message: CanonMessage, options?: {
-    conversationType?: 'direct' | 'group' | 'unknown';
-    behavior?: ResolvedAgentBehaviorPolicy | null;
-    recentHumanCount?: number;
-    consecutiveAgentTurns?: number;
-    currentAgentStreakStartedByHuman?: boolean;
-    turnDispatch?: MessageCreatedPayload['turnDispatch'];
-}): Promise<boolean>;

package/dist/turn-filter.js

@@ -1,25 +0,0 @@
-import { evaluateParticipationPolicy, shouldTriggerAgentTurn, } from '@canonmsg/core';
-export async function shouldDispatchInboundMessage(_conversationId, agentId, message, options) {
-    if (message.senderId === agentId)
-        return false;
-    if (options?.turnDispatch) {
-        return options.turnDispatch.kind === 'run_turn';
-    }
-    const triggerDecision = shouldTriggerAgentTurn({
-        senderType: message.senderType,
-        metadata: message.metadata,
-    });
-    if (!triggerDecision.allow)
-        return false;
-    if (!options?.behavior)
-        return true;
-    return evaluateParticipationPolicy(options.behavior, {
-        conversationType: options.conversationType ?? 'unknown',
-        senderType: message.senderType,
-        isOwner: message.isOwner,
-        mentionedAgent: Array.isArray(message.mentions) && message.mentions.includes(agentId),
-        recentHumanCount: options.recentHumanCount,
-        consecutiveAgentTurns: options.consecutiveAgentTurns,
-        currentAgentStreakStartedByHuman: options.currentAgentStreakStartedByHuman,
-    }).allow;
-}