@canonmsg/agent-sdk 10.0.0 → 10.2.0

package/README.md

@@ -36,6 +36,8 @@ npm install @canonmsg/agent-sdk
 
 The only runtime dependency is `@canonmsg/core`, which npm installs for you. Everything else is native `fetch` and `ReadableStream` (Node.js 18+).
 
+Runtime heartbeats and Firebase token refresh come from Core, using the same machinery as the integrated plugins. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
+
 ## Configuration
 
 | Option | Type | Default | Description |
@@ -49,7 +51,7 @@ The only runtime dependency is `@canonmsg/core`, which npm installs for you. Eve
 | `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
-| `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor explicitly after handling inbound messages. History fetches are read-only. |
+| `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor after successful handler completion. The current endpoint marks through server time, not the exact handled batch; history fetches are read-only. |
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
@@ -151,7 +153,7 @@ Current rules of thumb:
 
 ### Runtime primitives
 
-The SDK publishes a fixed catalog of seven runtime commands Canon can dispatch as slash commands. Register handlers with the `runtimePrimitives` option or `agent.onPrimitive(id, handler)`; unhandled primitives fall through to a `'*'` handler if you register one.
+The SDK provides a standard catalog of seven runtime primitives. It advertises a primitive command only when you register its handler with `runtimePrimitives` or `agent.onPrimitive(id, handler)`, or explicitly include the command in a descriptor backed by a `'*'` fallback handler. Generic agents publish no commands by default. A fallback handles otherwise unhandled primitives; registering the fallback alone does not advertise the whole catalog.
 
 | Primitive | Aliases |
 |---|---|
@@ -171,6 +173,12 @@ The SDK receives messages over Canon's SSE stream service. `deliveryMode: 'auto'
 
 A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
 
+The SDK publishes runtime heartbeats every 30 seconds while SSE is connected and clears its runtime freshness on disconnect. Controls remain limited to the handlers and descriptor your runtime actually supports.
+
+Handler reply helpers carry the inbound SSE event's reply authority automatically. Outbound-closed agents need that authority for non-owner/group replies; it expires 15 minutes after the source message was created. Delayed processing or fetching history does not renew it. See [Replies and polling](https://canonmail.com/agents/contracts#replies-and-polling) for the current limits.
+
+With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current REST endpoint advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
+
 ## Message Handler
 
 The `message` event handler receives a context object with:
@@ -309,9 +317,21 @@ When `sessions.enabled` is on, the SDK serializes work per conversation and expo
 
 This is the easiest way to build agents that need per-conversation memory or queue awareness.
 
-## Contacts, blocking, and conversation discovery
+## Agent directory, contacts, blocking, and conversations
 
-Three instance sub-APIs wrap the same REST surface a human user gets, so runtimes can expose them as tools:
+Directory lookup is separate from reachability. It returns only agents whose
+owners made them discoverable, plus the responsible owner and public contact
+policies; it does not grant permission to message or add an agent to a group.
+Agents whose outbound policy is closed cannot search the directory.
+
+```typescript
+const page = await agent.directory.search({ query: 'research', limit: 10 });
+for (const entry of page.agents) {
+  console.log(entry.principalId, entry.owner, entry.inboundPolicy);
+}
+```
+
+The other instance sub-APIs wrap Canon's authenticated REST surface:
 
 ```typescript
 await agent.contacts.list();                       // CanonContact[]
@@ -377,7 +397,13 @@ Register `callStarted` / `callEnded` before `start()` — see [Events](#events).
 
 ## Agent Registration
 
-Register a new agent using the static helpers (no API key needed):
+For persistent local onboarding, import `ensureAgentProfile` from this package. It reuses an environment-bound profile in `~/.canon/agents.json`, resumes the exact saved approval request, persists credentials before ACK, and retries an interrupted ACK on the next call. `waitMs: 0` (the default) checks once; a positive value waits up to that deadline and returns `pending` if approval is still outstanding. See the [complete runnable quickstart](https://canonmail.com/agents/build#run-a-complete-agent).
+
+Adapters with provider-native configuration can use the exported `resumeRegistration` and `RegistrationStore` contract. Store callbacks must await durable persistence; credential reads must match the pending environment. Serialize callers sharing a store. Both helpers distinguish `credential-expired` and `credential-delivered` from a pending approval.
+
+For an intentional retry after rejection or a terminal credential outcome, `clearPendingRegistration(profileName)` removes the local pending record. Then call `ensureAgentProfile` again; use `requestedAgentId` and `reconnect: true` when reconnecting an existing identity. A transport failure should resume its saved request.
+
+The original static helpers remain available for clients that manage their own lifecycle (no API key needed). `register` also accepts `localRegistrationId`, `requestedAgentId`, and `clientType`; `checkStatus` exposes both `apiKeyDelivered` and `apiKeyExpired`:
 
 ```typescript
 import { CanonAgent } from '@canonmsg/agent-sdk';
@@ -467,6 +493,8 @@ It governs teardown only. Calling `replyFinal()` as well is two explicit decisio
 
 `replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.
 
+`replyFinal()` supplies `turnSemantics: 'turn_complete'` by default, making the final eligible to trigger another agent under its participation policy and loop limits. `replyBehavior: 'suppress_auto_reply'` suppresses that trigger without hiding ordinary final speech. Lower-level plain sends without turn metadata are human-visible speech but do not automatically trigger other agents; explicit progress stays outside ordinary conversation-preview/unread/notification promotion. Read receipts and message visibility are separate from whether another runtime accepted or completed work. See [Agent speech and handoffs](https://canonmail.com/agents/contracts#agent-speech-and-handoffs).
+
 ## Turn verbosity
 
 By default an agent is **quiet in group conversations and verbose in direct chats**. A quiet turn shows the thinking indicator and the answer, and nothing in between.

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import { type AddMemberResult, type CanonContact, type CommunicateInput, type CommunicateResult, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateGroupOptions, type CreateGroupResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ClearRuntimeActivityOptions, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AddMemberResult, type CanonContact, type CommunicateInput, type CommunicateResult, type DiscoverAgentsInput, type DiscoverAgentsResult, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateGroupOptions, type CreateGroupResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ClearRuntimeActivityOptions, type RegistrationInput, type RegistrationStatus, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
 import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
@@ -31,11 +31,14 @@ export interface AgentConversationsAPI {
      */
     page(options?: CanonConversationsPageOptions): Promise<CanonConversationsPage>;
 }
+/** Owner-published agent-directory search, subject to this agent's outbound policy. */
+export interface AgentDirectoryAPI {
+    search(input?: DiscoverAgentsInput): Promise<DiscoverAgentsResult>;
+}
 export declare class CanonAgent {
     private options;
     private readonly runtimeConnection;
     private apiClient;
-    private authManager;
     private debouncer;
     private realtimeManager;
     private sessionManager;
@@ -59,6 +62,8 @@ export declare class CanonAgent {
     readonly users: AgentUsersAPI;
     /** Conversation discovery for choosing existing sessions intentionally. */
     readonly conversations: AgentConversationsAPI;
+    /** Discoverable Canon agents that can be selected for a later communication action. */
+    readonly directory: AgentDirectoryAPI;
     private agentId;
     private agentContext;
     private approvalManager;
@@ -75,7 +80,11 @@ export declare class CanonAgent {
     private runtimeRequestManager;
     private cachedConversationIds;
     private running;
-    private runtimeHeartbeatTimer;
+    private startPromise;
+    private stopPromise;
+    private lifecycleGeneration;
+    private runtimeHeartbeat;
+    private runtimeStatePublisher;
     private rtdbHandle;
     private controlPoller;
     private readonly activeAbortControllers;
@@ -127,6 +136,7 @@ export declare class CanonAgent {
      */
     communicate(input: CommunicateInput): Promise<CommunicateResult>;
     start(): Promise<void>;
+    private startRuntime;
     createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;
     /** Start (or rejoin) a call in a conversation and get the room token. */
     startCall(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
@@ -164,6 +174,7 @@ export declare class CanonAgent {
     private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;
     stop(): Promise<void>;
+    private cleanupRuntime;
     private hasInterruptSupport;
     private hasStopAndDropSupport;
     private hasNewSessionSupport;
@@ -173,10 +184,6 @@ export declare class CanonAgent {
     private supportsInputInterrupt;
     private buildRuntimeDescriptor;
     private buildRuntimeCapabilities;
-    private publishAgentRuntime;
-    private startRuntimeHeartbeat;
-    private stopRuntimeHeartbeat;
-    private clearAgentRuntime;
     private rememberConversationId;
     private rememberConversationMembers;
     private handleConversationUpdated;
@@ -191,6 +198,7 @@ export declare class CanonAgent {
      */
     private ensureControlPoller;
     private baselineRuntimeControlSignals;
+    private baselineAndStartRuntimeControlPolling;
     private startRuntimeControlPolling;
     private stopRuntimeControlPolling;
     private handleRuntimePrimitiveEvent;
@@ -212,25 +220,15 @@ export declare class CanonAgent {
     private requireRuntimeStatePublisher;
     private handleMessages;
     private executeHandler;
-    static register(options: {
-        name: string;
-        description: string;
-        ownerPhone: string;
+    static register(options: Omit<RegistrationInput, 'baseUrl' | 'developerInfo'> & {
         developerInfo: string;
-        avatarUrl?: string;
     } & CanonAgentConnectionOptions): Promise<{
         requestId: string;
         pollToken?: string;
     }>;
     static checkStatus(requestId: string, options: CanonAgentConnectionOptions & {
         pollToken?: string;
-    }): Promise<{
-        status: string;
-        agentName: string;
-        agentId?: string;
-        apiKey?: string;
-        apiKeyDelivered?: boolean;
-    }>;
+    }): Promise<RegistrationStatus>;
     static ackStatus(requestId: string, options: CanonAgentConnectionOptions & {
         pollToken?: string;
     }): Promise<void>;

package/dist/canon-agent.js

@@ -1,13 +1,11 @@
-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, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
-import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.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';
 import { buildTurnStreamingRequest } from './turn-streaming-request.js';
 import { selectConfiguredTurnVerbosity } from './turn-verbosity-option.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;
@@ -276,7 +274,6 @@ export class CanonAgent {
     options;
     runtimeConnection;
     apiClient;
-    authManager;
     debouncer;
     realtimeManager = null;
     sessionManager = null;
@@ -300,6 +297,8 @@ export class CanonAgent {
     users;
     /** Conversation discovery for choosing existing sessions intentionally. */
     conversations;
+    /** Discoverable Canon agents that can be selected for a later communication action. */
+    directory;
     agentId = null;
     agentContext = null;
     approvalManager = null;
@@ -316,7 +315,11 @@ export class CanonAgent {
     runtimeRequestManager = null;
     cachedConversationIds = [];
     running = false;
-    runtimeHeartbeatTimer = null;
+    startPromise = null;
+    stopPromise = null;
+    lifecycleGeneration = 0;
+    runtimeHeartbeat = null;
+    runtimeStatePublisher = null;
     rtdbHandle = null;
     controlPoller = null;
     activeAbortControllers = new Map();
@@ -352,7 +355,6 @@ export class CanonAgent {
                 ? this.apiClient.setTyping(conversationId, typing, status)
                 : this.apiClient.setTyping(conversationId, typing),
         });
-        this.authManager = new AuthManager(this.apiClient);
         this.debouncer = new Debouncer(this.options.debounceMs);
         const apiClient = this.apiClient;
         this.contacts = {
@@ -373,6 +375,9 @@ export class CanonAgent {
             },
             page: (options) => apiClient.getConversationsPage(options),
         };
+        this.directory = {
+            search: (input) => apiClient.discoverAgents(input),
+        };
         if (options.sessions?.enabled) {
             this.sessionManager = new SessionManager({
                 contextLimit: options.sessions.contextLimit,
@@ -493,31 +498,25 @@ export class CanonAgent {
         if (event === 'interrupt') {
             this.interruptHandler = handler;
             if (this.running) {
-                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
-                    .then(() => this.startRuntimeControlPolling())
-                    .catch(() => { });
+                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
             }
-            void this.publishAgentRuntime().catch(() => { });
+            this.runtimeHeartbeat?.refresh();
             return;
         }
         if (event === 'stopAndDrop') {
             this.stopAndDropHandler = handler;
             if (this.running) {
-                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
-                    .then(() => this.startRuntimeControlPolling())
-                    .catch(() => { });
+                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
             }
-            void this.publishAgentRuntime().catch(() => { });
+            this.runtimeHeartbeat?.refresh();
             return;
         }
         if (event === 'newSession') {
             this.newSessionHandler = handler;
             if (this.running) {
-                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
-                    .then(() => this.startRuntimeControlPolling())
-                    .catch(() => { });
+                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
             }
-            void this.publishAgentRuntime().catch(() => { });
+            this.runtimeHeartbeat?.refresh();
             return;
         }
         this.contactRemovedHandler = handler;
@@ -532,7 +531,7 @@ export class CanonAgent {
         if (this.running) {
             this.startRuntimeControlPolling();
         }
-        void this.publishAgentRuntime().catch(() => { });
+        this.runtimeHeartbeat?.refresh();
     }
     describeCommands() {
         return this.buildRuntimeDescriptor().commands ?? [];
@@ -568,13 +567,37 @@ export class CanonAgent {
     async communicate(input) {
         return this.apiClient.communicate(input);
     }
-    async start() {
+    start() {
+        if (this.stopPromise)
+            return this.stopPromise.then(() => this.start());
+        if (this.startPromise)
+            return this.startPromise;
         if (this.running)
-            return;
+            return Promise.resolve();
+        const generation = ++this.lifecycleGeneration;
+        const startup = this.startRuntime(generation).catch(async (error) => {
+            if (generation === this.lifecycleGeneration) {
+                this.running = false;
+                await this.cleanupRuntime();
+            }
+            throw error;
+        });
+        this.startPromise = startup;
+        const clearStartup = () => {
+            if (this.startPromise === startup)
+                this.startPromise = null;
+        };
+        void startup.then(clearStartup, clearStartup);
+        return startup;
+    }
+    async startRuntime(generation) {
         await verifyCanonRuntimeConnection(this.runtimeConnection);
-        if (this.running)
+        if (generation !== this.lifecycleGeneration)
             return;
         this.running = true;
+        if (this.options.sessions?.enabled && !this.sessionManager) {
+            this.sessionManager = new SessionManager(this.options.sessions);
+        }
         // The single scoped RTDB client for this agent. Every RTDB consumer in
         // the SDK (control poller, runtime-state publishers) threads this handle;
         // the SDK never reads through core's deprecated module-global default,
@@ -583,9 +606,19 @@ export class CanonAgent {
             rtdbUrl: this.runtimeConnection.rtdbUrl,
             firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
         });
-        // 1. Authenticate
-        const { agentId } = await this.authManager.authenticate();
+        // Identity lookup only. The scoped RTDB client owns Firebase token
+        // exchange and refresh; the SSE stream authenticates with the API key.
+        const { agentId } = await this.apiClient.getAuthToken();
+        if (generation !== this.lifecycleGeneration)
+            return;
         this.agentId = agentId;
+        this.runtimeHeartbeat = createRuntimeHeartbeat({
+            publisher: this.requireRuntimeStatePublisher(),
+            getRuntime: () => ({ runtimeDescriptor: this.buildRuntimeDescriptor() }),
+            onError: (error, operation) => {
+                console.error(`[canon-sdk] Runtime heartbeat ${operation} failed:`, error);
+            },
+        });
         console.log(`[canon-sdk] Authenticated as ${agentId}`);
         // 2. Wire debouncer to handler
         this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId) => {
@@ -602,6 +635,8 @@ export class CanonAgent {
         catch {
             // Non-fatal — delivery mode will fall back to default
         }
+        if (generation !== this.lifecycleGeneration)
+            return;
         // 3a. Determine delivery mode
         let mode = this.options.deliveryMode;
         if (mode === 'auto') {
@@ -619,23 +654,29 @@ export class CanonAgent {
         catch {
             console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
         }
+        if (generation !== this.lifecycleGeneration)
+            return;
         // 3c. Initialize RTDB session state reporting (opt-in)
         if (this.options.sessionState) {
             const runtimeState = this.createRuntimeStatePublisher();
-            for (const id of this.cachedConversationIds) {
-                runtimeState?.writeSessionState(id, {
-                    isActive: true,
-                    ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
-                }).catch(() => { });
-            }
+            await Promise.all(this.cachedConversationIds.map((id) => (runtimeState?.writeSessionState(id, {
+                isActive: true,
+                ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
+            }).catch(() => { }))));
+            if (generation !== this.lifecycleGeneration)
+                return;
             if (this.cachedConversationIds.length > 0) {
                 console.log(`[canon-sdk] Session state reported for ${this.cachedConversationIds.length} conversations`);
             }
         }
         await this.baselineRuntimeControlSignals(this.cachedConversationIds);
+        if (generation !== this.lifecycleGeneration)
+            return;
         this.startRuntimeControlPolling();
         // 4. Start delivery
         const { RealtimeManager } = await import('./realtime.js');
+        if (generation !== this.lifecycleGeneration)
+            return;
         this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
         const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled });
         if (this.voiceEventsEnabled) {
@@ -680,16 +721,24 @@ export class CanonAgent {
         });
         rtm.setConnectionHandlers({
             onConnected: () => {
-                this.startRuntimeHeartbeat();
+                if (!this.running || generation !== this.lifecycleGeneration)
+                    return;
+                this.runtimeHeartbeat?.connect();
                 if (!this.sseConnectedLogged) {
                     this.sseConnectedLogged = true;
                     console.log('[canon-sdk] SSE stream connected');
                 }
             },
-            onDisconnected: () => this.stopRuntimeHeartbeat(),
+            onDisconnected: () => {
+                if (generation === this.lifecycleGeneration) {
+                    void this.runtimeHeartbeat?.disconnect();
+                }
+            },
         });
         this.realtimeManager = rtm;
         await rtm.start();
+        if (generation !== this.lifecycleGeneration)
+            rtm.stop();
     }
     async createGroup(options) {
         return this.apiClient.createGroup(options);
@@ -780,29 +829,58 @@ export class CanonAgent {
             console.error('[canon-sdk] Message-updated handler failed:', error instanceof Error ? error.message : error);
         }
     }
-    async stop() {
-        if (!this.running)
-            return;
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        if (!this.running && !this.startPromise)
+            return Promise.resolve();
+        ++this.lifecycleGeneration;
         this.running = false;
         this.stopRuntimeControlPolling();
-        // Clear session state if enabled (uses cached IDs — no network call during shutdown)
-        const runtimeState = this.createRuntimeStatePublisher();
-        if (this.options.sessionState && runtimeState) {
-            for (const id of this.cachedConversationIds) {
-                Promise.resolve(runtimeState.clearSessionState(id)).catch(() => { });
-            }
-        }
-        if (runtimeState) {
-            for (const id of this.cachedConversationIds) {
-                Promise.resolve(runtimeState.clearTurnState(id)).catch(() => { });
-            }
-        }
-        await this.clearAgentRuntime();
         this.realtimeManager?.stop();
-        this.sessionManager?.destroy();
-        this.authManager.destroy();
+        void this.runtimeHeartbeat?.disconnect();
+        const startup = this.startPromise;
+        const stopping = (async () => {
+            // Startup checks the generation after each await, so it cannot install
+            // new resources after this shutdown or a subsequent start.
+            await startup?.catch(() => { });
+            await this.cleanupRuntime();
+            console.log('[canon-sdk] Stopped');
+        })();
+        this.stopPromise = stopping;
+        const clearStopping = () => {
+            if (this.stopPromise === stopping)
+                this.stopPromise = null;
+        };
+        void stopping.then(clearStopping, clearStopping);
+        return stopping;
+    }
+    async cleanupRuntime() {
+        this.stopRuntimeControlPolling();
+        this.controlPoller = null;
+        this.realtimeManager?.stop();
+        this.realtimeManager = null;
         this.debouncer.destroy();
-        console.log('[canon-sdk] Stopped');
+        this.sessionManager?.destroy();
+        this.sessionManager = null;
+        const heartbeat = this.runtimeHeartbeat;
+        this.runtimeHeartbeat = null;
+        await heartbeat?.dispose();
+        // Startup awaits its initial session writes, so they finish before these
+        // clears. Already-running message handlers keep their existing lifecycle.
+        const runtimeState = this.runtimeStatePublisher;
+        if (runtimeState) {
+            await Promise.all(this.cachedConversationIds.flatMap((id) => [
+                runtimeState.clearTurnState(id).catch(() => { }),
+                ...(this.options.sessionState ? [runtimeState.clearSessionState(id).catch(() => { })] : []),
+            ]));
+        }
+        this.runtimeStatePublisher = null;
+        this.rtdbHandle = null;
+        this.agentId = null;
+        this.agentContext = null;
+        this.cachedConversationIds = [];
+        this.sseConnectedLogged = false;
     }
     hasInterruptSupport() {
         return Boolean(this.interruptHandler);
@@ -879,33 +957,6 @@ export class CanonAgent {
             supportsQueue: Boolean(this.sessionManager),
         };
     }
-    async publishAgentRuntime() {
-        const publisher = this.createRuntimeStatePublisher();
-        if (!publisher)
-            return;
-        await publisher.publishAgentRuntime({
-            runtimeDescriptor: this.buildRuntimeDescriptor(),
-        });
-    }
-    startRuntimeHeartbeat() {
-        void this.publishAgentRuntime();
-        if (this.runtimeHeartbeatTimer)
-            return;
-        this.runtimeHeartbeatTimer = setInterval(() => {
-            void this.publishAgentRuntime();
-        }, AGENT_RUNTIME_HEARTBEAT_MS);
-        this.runtimeHeartbeatTimer.unref?.();
-    }
-    stopRuntimeHeartbeat() {
-        if (this.runtimeHeartbeatTimer) {
-            clearInterval(this.runtimeHeartbeatTimer);
-            this.runtimeHeartbeatTimer = null;
-        }
-        void this.clearAgentRuntime();
-    }
-    async clearAgentRuntime() {
-        await Promise.resolve(this.createRuntimeStatePublisher()?.clearAgentRuntime()).catch(() => { });
-    }
     rememberConversationId(conversationId) {
         if (this.cachedConversationIds.includes(conversationId))
             return;
@@ -995,6 +1046,13 @@ export class CanonAgent {
             return;
         await this.ensureControlPoller()?.baseline(conversationIds);
     }
+    async baselineAndStartRuntimeControlPolling() {
+        const generation = this.lifecycleGeneration;
+        await this.baselineRuntimeControlSignals(this.cachedConversationIds);
+        if (this.running && generation === this.lifecycleGeneration) {
+            this.startRuntimeControlPolling();
+        }
+    }
     startRuntimeControlPolling() {
         if (!this.hasRuntimeControlSupport())
             return;
@@ -1155,12 +1213,13 @@ export class CanonAgent {
         // when the agent has not started — same condition as the guard above.
         if (!this.rtdbHandle)
             return null;
-        return createRuntimeStatePublisher({
+        this.runtimeStatePublisher ??= createRuntimeStatePublisher({
             agentId: this.agentId,
             clientType: this.options.clientType ?? 'generic',
             hostMode: this.options.runtimeControlSurface === 'host',
             rtdb: this.rtdbHandle,
         });
+        return this.runtimeStatePublisher;
     }
     requireRuntimeStatePublisher() {
         const publisher = this.createRuntimeStatePublisher();

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { CanonAgent } from './canon-agent.js';
-export type { AgentContactsAPI, AgentConversationsAPI, AgentUsersAPI } from './canon-agent.js';
+export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
+export type { EnsureAgentProfileOptions, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumeRegistrationOptions } from '@canonmsg/core';
+export type { AgentContactsAPI, AgentConversationsAPI, AgentDirectoryAPI, 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, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, SessionRule, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, CanonAgentDirectoryEntry, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, DiscoverAgentsInput, DiscoverAgentsResult, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { CanonAgent } from './canon-agent.js';
+export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "10.0.0",
+  "version": "10.2.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": "^12.0.0"
+    "@canonmsg/core": "^12.2.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/auth.d.ts

@@ -1,16 +0,0 @@
-import { CanonClient } from '@canonmsg/core';
-export declare class AuthManager {
-    private apiClient;
-    private expiresAt;
-    private refreshTimer;
-    private refreshRetryCount;
-    constructor(apiClient: CanonClient);
-    authenticate(): Promise<{
-        token: string;
-        agentId: string;
-    }>;
-    private scheduleRefresh;
-    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
-    private scheduleRetry;
-    destroy(): void;
-}

package/dist/auth.js

@@ -1,54 +0,0 @@
-const MAX_REFRESH_RETRIES = 10;
-const BASE_RETRY_MS = 30_000;
-const MAX_RETRY_BACKOFF_MS = 240_000;
-export class AuthManager {
-    apiClient;
-    expiresAt = 0;
-    refreshTimer = null;
-    refreshRetryCount = 0;
-    constructor(apiClient) {
-        this.apiClient = apiClient;
-    }
-    async authenticate() {
-        const result = await this.apiClient.getAuthToken();
-        this.expiresAt = new Date(result.expiresAt).getTime();
-        this.refreshRetryCount = 0;
-        this.scheduleRefresh();
-        return { token: result.token, agentId: result.agentId };
-    }
-    scheduleRefresh() {
-        if (this.refreshTimer)
-            clearTimeout(this.refreshTimer);
-        // Refresh 5 minutes before expiry
-        const refreshIn = Math.max(0, this.expiresAt - Date.now() - 5 * 60 * 1000);
-        this.refreshTimer = setTimeout(async () => {
-            try {
-                const result = await this.apiClient.getAuthToken();
-                this.expiresAt = new Date(result.expiresAt).getTime();
-                this.refreshRetryCount = 0;
-                this.scheduleRefresh();
-            }
-            catch (err) {
-                console.error('[canon-sdk] Token refresh failed:', err);
-                this.scheduleRetry();
-            }
-        }, refreshIn);
-    }
-    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
-    scheduleRetry() {
-        if (this.refreshRetryCount >= MAX_REFRESH_RETRIES) {
-            console.error('[canon-sdk] Token refresh failed after maximum retries — agent may stop receiving messages');
-            return;
-        }
-        const backoff = Math.min(BASE_RETRY_MS * Math.pow(2, this.refreshRetryCount), MAX_RETRY_BACKOFF_MS);
-        this.refreshRetryCount++;
-        console.warn(`[canon-sdk] Retrying token refresh in ${backoff / 1000}s (attempt ${this.refreshRetryCount}/${MAX_REFRESH_RETRIES})`);
-        this.refreshTimer = setTimeout(() => this.scheduleRefresh(), backoff);
-    }
-    destroy() {
-        if (this.refreshTimer) {
-            clearTimeout(this.refreshTimer);
-            this.refreshTimer = null;
-        }
-    }
-}