@canonmsg/agent-sdk 0.4.0 → 0.6.0

package/dist/canon-agent.d.ts

@@ -12,6 +12,7 @@ export declare class CanonAgent {
     private agentContext;
     private cachedConversationIds;
     private running;
+    private runtimeHeartbeatTimer;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
     start(): Promise<void>;
@@ -28,6 +29,10 @@ export declare class CanonAgent {
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     stop(): Promise<void>;
+    private publishAgentRuntime;
+    private startRuntimeHeartbeat;
+    private stopRuntimeHeartbeat;
+    private clearAgentRuntime;
     private handleMessages;
     private executeHandler;
     static register(options: {

package/dist/canon-agent.js

@@ -1,10 +1,11 @@
-import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
+import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, mergeWorkSessionContexts, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
 import { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
 const AUTO_MODE_THRESHOLD = 500;
+const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsQueue: true,
@@ -28,6 +29,7 @@ export class CanonAgent {
     agentContext = null;
     cachedConversationIds = [];
     running = false;
+    runtimeHeartbeatTimer = null;
     constructor(options) {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
@@ -109,12 +111,16 @@ export class CanonAgent {
             rtm.setOnAgentContext((ctx) => {
                 this.agentContext = ctx;
             });
+            rtm.setConnectionHandlers({
+                onConnected: () => this.startRuntimeHeartbeat(),
+                onDisconnected: () => this.stopRuntimeHeartbeat(),
+            });
             this.realtimeManager = rtm;
             await rtm.start();
             console.log('[canon-sdk] SSE stream started');
         }
         else {
-            this.pollingManager = new PollingManager(this.apiClient, this.debouncer, agentId, this.options.pollingIntervalMs);
+            this.pollingManager = new PollingManager(this.apiClient, this.debouncer, agentId, this.options.pollingIntervalMs, () => this.startRuntimeHeartbeat(), () => this.stopRuntimeHeartbeat());
             await this.pollingManager.start();
             console.log(`[canon-sdk] Polling started (interval: ${this.options.pollingIntervalMs}ms)`);
         }
@@ -155,6 +161,7 @@ export class CanonAgent {
                 clearTurnState(id, this.agentId).catch(() => { });
             }
         }
+        await this.clearAgentRuntime();
         this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
@@ -162,6 +169,36 @@ export class CanonAgent {
         this.debouncer.destroy();
         console.log('[canon-sdk] Stopped');
     }
+    async publishAgentRuntime() {
+        if (!this.agentId)
+            return;
+        await rtdbWrite(`/agent-runtime/${this.agentId}`, {
+            clientType: this.options.clientType ?? 'generic',
+            hostMode: false,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    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() {
+        if (!this.agentId)
+            return;
+        await rtdbWrite(`/agent-runtime/${this.agentId}`, null).catch(() => { });
+    }
     async handleMessages(conversationId, messages) {
         if (!this.handler) {
             console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);
@@ -237,8 +274,9 @@ export class CanonAgent {
             }
         }, 3500);
         try {
-            // Fetch history from API
-            const history = await this.apiClient.getMessages(conversationId, this.options.historyLimit);
+            // Fetch hydrated history/context from API
+            const page = await this.apiClient.getMessagesPage(conversationId, this.options.historyLimit);
+            const history = page.messages;
             // If sessions enabled, seed the session with fetched history
             if (this.sessionManager && session) {
                 this.sessionManager.seedHistory(conversationId, history);
@@ -294,6 +332,11 @@ export class CanonAgent {
                     m.isOwner = m.senderId === ownerId;
                 }
             }
+            const explicitWorkSession = messages.find((message) => message.workSession)?.workSession
+                ?? history.find((message) => message.workSession)?.workSession
+                ?? null;
+            const activeWorkSessions = mergeWorkSessionContexts(explicitWorkSession, page.workSessions ?? []);
+            const workSession = explicitWorkSession;
             // Build agent context (fallback to minimal if not yet received)
             const agent = this.agentContext ?? {
                 agentId: this.agentId,
@@ -308,6 +351,23 @@ export class CanonAgent {
             const react = (messageId, emoji) => this.apiClient.react(conversationId, messageId, emoji);
             const addMember = (userId) => this.apiClient.addMember(conversationId, userId);
             const removeMember = (userId) => this.apiClient.removeMember(conversationId, userId);
+            const createWorkSession = (options) => this.apiClient.createWorkSession({
+                conversationId,
+                ...(options ?? {}),
+            });
+            const getWorkSession = (workSessionId, targetConversationId = conversationId) => this.apiClient.getWorkSession(workSessionId, targetConversationId);
+            const updateWorkSessionContext = (workSessionId, options) => this.apiClient.upsertWorkSessionConversation(workSessionId, conversationId, options);
+            const sendLinkedMessage = (targetConversationId, text, options) => {
+                if (!options?.workSessionId && !options?.createWorkSession) {
+                    throw new Error('sendLinkedMessage requires workSessionId or createWorkSession');
+                }
+                return this.apiClient.sendLinkedMessage({
+                    sourceConversationId: conversationId,
+                    targetConversationId,
+                    text,
+                    ...options,
+                });
+            };
             // Invoke handler
             await this.handler({
                 messages,
@@ -323,7 +383,13 @@ export class CanonAgent {
                 react,
                 addMember,
                 removeMember,
+                createWorkSession,
+                getWorkSession,
+                updateWorkSessionContext,
+                sendLinkedMessage,
                 agent,
+                workSession,
+                activeWorkSessions,
                 session: session
                     ? {
                         id: session.id,

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { CanonAgent } from './canon-agent.js';
 export { CanonApiError } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonMessage, CanonConversation, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
 export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/polling.d.ts

@@ -5,10 +5,12 @@ export declare class PollingManager {
     private debouncer;
     private agentId;
     private pollingIntervalMs;
+    private onHealthy;
+    private onUnhealthy;
     private lastSeenTimestamps;
     private pollTimer;
     private running;
-    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number);
+    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number, onHealthy?: () => void, onUnhealthy?: () => void);
     start(): Promise<void>;
     private poll;
     private findActiveConversations;

package/dist/polling.js

@@ -5,14 +5,18 @@ export class PollingManager {
     debouncer;
     agentId;
     pollingIntervalMs;
+    onHealthy;
+    onUnhealthy;
     lastSeenTimestamps = new Map();
     pollTimer = null;
     running = false;
-    constructor(apiClient, debouncer, agentId, pollingIntervalMs) {
+    constructor(apiClient, debouncer, agentId, pollingIntervalMs, onHealthy, onUnhealthy) {
         this.apiClient = apiClient;
         this.debouncer = debouncer;
         this.agentId = agentId;
         this.pollingIntervalMs = pollingIntervalMs;
+        this.onHealthy = onHealthy ?? null;
+        this.onUnhealthy = onUnhealthy ?? null;
     }
     async start() {
         this.running = true;
@@ -22,6 +26,7 @@ export class PollingManager {
         for (const convo of conversations) {
             this.lastSeenTimestamps.set(convo.id, now);
         }
+        this.onHealthy?.();
         // Start polling
         this.pollTimer = setInterval(() => this.poll(), this.pollingIntervalMs);
     }
@@ -30,6 +35,7 @@ export class PollingManager {
             return;
         try {
             const conversations = await this.apiClient.getConversations();
+            this.onHealthy?.();
             const activeConvos = this.findActiveConversations(conversations);
             await Promise.all(activeConvos.map(async (convo) => {
                 try {
@@ -67,6 +73,7 @@ export class PollingManager {
             }));
         }
         catch (err) {
+            this.onUnhealthy?.();
             console.error('[canon-sdk] Polling error:', err);
         }
     }

package/dist/realtime.d.ts

@@ -15,8 +15,14 @@ export declare class RealtimeManager {
     private knownConversationIds;
     private discoveryTimer;
     private onAgentContext;
+    private onConnected;
+    private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
+    setConnectionHandlers(handlers: {
+        onConnected?: () => void;
+        onDisconnected?: () => void;
+    }): void;
     start(): Promise<void>;
     stop(): void;
     private discoverNewConversations;

package/dist/realtime.js

@@ -17,6 +17,8 @@ export class RealtimeManager {
     knownConversationIds = new Set();
     discoveryTimer = null;
     onAgentContext = null;
+    onConnected = null;
+    onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
         this.debouncer = debouncer;
         this.agentId = agentId;
@@ -54,6 +56,10 @@ export class RealtimeManager {
                 },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
+                    this.onConnected?.();
+                },
+                onDisconnected: () => {
+                    this.onDisconnected?.();
                 },
                 onError: (err) => {
                     console.error('[canon-sdk] SSE error:', err.message);
@@ -64,6 +70,10 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
+    setConnectionHandlers(handlers) {
+        this.onConnected = handlers.onConnected ?? null;
+        this.onDisconnected = handlers.onDisconnected ?? null;
+    }
     async start() {
         this.running = true;
         // Snapshot current conversations
@@ -89,6 +99,7 @@ export class RealtimeManager {
             this.discoveryTimer = null;
         }
         this.stream.stop();
+        this.onDisconnected?.();
     }
     // ── Conversation discovery ─────────────────────────────────────────
     async discoverNewConversations() {

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
-import type { CanonMessage, CanonConversation, SendMessageOptions } from '@canonmsg/core';
+export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+import type { CanonMessage, CanonConversation, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 export type SDKMessage = CanonMessage;
 export type SDKConversation = CanonConversation;
 export interface ProgressMessageOptions extends SendMessageOptions {
@@ -59,8 +59,20 @@ export interface MessageHandlerContext {
     addMember: (userId: string) => Promise<void>;
     /** Remove a member from this conversation (requires owner/admin role) */
     removeMember: (userId: string) => Promise<void>;
+    /** Create a Canon work session rooted in this conversation. */
+    createWorkSession: (options?: Omit<CreateWorkSessionOptions, 'conversationId'>) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
+    /** Load this conversation's scoped view of a Canon work session. */
+    getWorkSession: (workSessionId: string, conversationId?: string) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
+    /** Update or attach this conversation's scoped work-session context. */
+    updateWorkSessionContext: (workSessionId: string, options?: UpdateWorkSessionConversationOptions) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
+    /** Send into another conversation under an existing or lazily created Canon work session. */
+    sendLinkedMessage: (targetConversationId: string, text: string, options?: Omit<import('@canonmsg/core').SendLinkedMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'text'>) => Promise<import('@canonmsg/core').SendLinkedMessageResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
+    /** Canon-provided shared task context for this turn, when attached to inbound messages. */
+    workSession?: import('@canonmsg/core').CanonWorkSessionContext | null;
+    /** All active Canon work sessions currently linked to this conversation. */
+    activeWorkSessions?: import('@canonmsg/core').CanonWorkSessionContext[];
     /** Per-conversation session state. Present when sessions are enabled. */
     session?: SessionInfo;
     /** Turn lifecycle helpers for live-work rendering and progress reporting. */

package/package.json

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