@canonmsg/agent-sdk 0.2.0

package/dist/canon-agent.js

@@ -0,0 +1,274 @@
+import { CanonClient, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
+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;
+export class CanonAgent {
+    options;
+    apiClient;
+    authManager;
+    debouncer;
+    pollingManager = null;
+    realtimeManager = null;
+    sessionManager = null;
+    handler = null;
+    agentId = null;
+    agentContext = null;
+    cachedConversationIds = [];
+    running = false;
+    constructor(options) {
+        this.options = {
+            baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
+            deliveryMode: 'auto',
+            pollingIntervalMs: 3000,
+            debounceMs: 2000,
+            historyLimit: 50,
+            autoMarkRead: true,
+            ...options,
+        };
+        this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
+        this.authManager = new AuthManager(this.apiClient);
+        this.debouncer = new Debouncer(this.options.debounceMs);
+        if (options.sessions?.enabled) {
+            this.sessionManager = new SessionManager({
+                contextLimit: options.sessions.contextLimit,
+                concurrency: options.sessions.concurrency,
+                idleTimeoutMs: options.sessions.idleTimeoutMs,
+            });
+        }
+    }
+    on(event, handler) {
+        if (event === 'message') {
+            this.handler = handler;
+        }
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // 1. Authenticate
+        const { agentId } = await this.authManager.authenticate();
+        this.agentId = agentId;
+        console.log(`[canon-sdk] Authenticated as ${agentId}`);
+        // 2. Wire debouncer to handler
+        this.debouncer.setCallback(async (conversationId, messages) => {
+            await this.handleMessages(conversationId, messages);
+        });
+        // 3. Fetch conversations (used for delivery mode + session state)
+        let conversations = [];
+        try {
+            conversations = await this.apiClient.getConversations();
+            this.cachedConversationIds = conversations.map((c) => c.id);
+        }
+        catch {
+            // Non-fatal — delivery mode will fall back to default
+        }
+        // 3a. Determine delivery mode
+        let mode = this.options.deliveryMode;
+        if (mode === 'auto') {
+            mode = conversations.length < AUTO_MODE_THRESHOLD ? 'sse' : 'polling';
+            console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
+        }
+        // 3b. Fetch agent context (identity, owner, access level)
+        try {
+            this.agentContext = await this.apiClient.getAgentMe();
+        }
+        catch {
+            console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
+        }
+        // 3c. Initialize RTDB session state reporting (opt-in)
+        if (this.options.sessionState) {
+            initRTDBAuth(this.apiClient);
+            for (const id of this.cachedConversationIds) {
+                writeSessionState(id, agentId, {
+                    cwd: process.cwd(),
+                    isActive: true,
+                    ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
+                }).catch(() => { });
+            }
+            if (this.cachedConversationIds.length > 0) {
+                console.log(`[canon-sdk] Session state reported for ${this.cachedConversationIds.length} conversations`);
+            }
+        }
+        // 4. Start delivery
+        if (mode === 'sse' || mode === 'realtime') {
+            const { RealtimeManager } = await import('./realtime.js');
+            const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
+            rtm.setOnAgentContext((ctx) => {
+                this.agentContext = ctx;
+            });
+            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);
+            await this.pollingManager.start();
+            console.log(`[canon-sdk] Polling started (interval: ${this.options.pollingIntervalMs}ms)`);
+        }
+    }
+    async createConversation(options) {
+        return this.apiClient.createConversation(options);
+    }
+    async updateTopic(conversationId, topic) {
+        return this.apiClient.updateTopic(conversationId, topic);
+    }
+    async leaveConversation(conversationId) {
+        return this.apiClient.leaveConversation(conversationId);
+    }
+    async updateConversationName(conversationId, name) {
+        return this.apiClient.updateConversationName(conversationId, name);
+    }
+    async addMember(conversationId, userId) {
+        return this.apiClient.addMember(conversationId, userId);
+    }
+    async removeMember(conversationId, userId) {
+        return this.apiClient.removeMember(conversationId, userId);
+    }
+    async uploadMedia(conversationId, data, mimeType) {
+        return this.apiClient.uploadMedia(conversationId, data, mimeType);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        // Clear session state if enabled (uses cached IDs — no network call during shutdown)
+        if (this.options.sessionState && this.agentId) {
+            for (const id of this.cachedConversationIds) {
+                clearSessionState(id, this.agentId).catch(() => { });
+            }
+        }
+        this.pollingManager?.stop();
+        this.realtimeManager?.stop();
+        this.sessionManager?.destroy();
+        this.authManager.destroy();
+        this.debouncer.destroy();
+        console.log('[canon-sdk] Stopped');
+    }
+    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.`);
+            return;
+        }
+        if (this.sessionManager) {
+            await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages) => {
+                await this.executeHandler(conversationId, newMessages, session);
+            });
+        }
+        else {
+            await this.executeHandler(conversationId, messages);
+        }
+    }
+    async executeHandler(conversationId, messages, session) {
+        if (!this.handler)
+            return;
+        // Show thinking indicator and keep it alive (5s client-side expiry)
+        try {
+            await this.apiClient.setTyping(conversationId, true, 'thinking');
+        }
+        catch {
+            // Non-critical
+        }
+        const thinkingKeepalive = setInterval(() => {
+            this.apiClient.setTyping(conversationId, true, 'thinking').catch(() => { });
+        }, 3500);
+        try {
+            // Fetch history from API
+            const history = await this.apiClient.getMessages(conversationId, this.options.historyLimit);
+            // If sessions enabled, seed the session with fetched history
+            if (this.sessionManager && session) {
+                this.sessionManager.seedHistory(conversationId, history);
+            }
+            // Get conversation info
+            const conversations = await this.apiClient.getConversations();
+            const conversation = conversations.find((c) => c.id === conversationId);
+            if (!conversation)
+                return;
+            // Build reply function — switch to typing, send, then clear
+            const reply = async (text) => {
+                try {
+                    await this.apiClient.setTyping(conversationId, true, 'typing');
+                }
+                catch { }
+                const result = await this.apiClient.sendMessage(conversationId, text);
+                try {
+                    await this.apiClient.setTyping(conversationId, false);
+                }
+                catch { }
+                return result;
+            };
+            // Enrich history messages with isOwner
+            if (this.agentContext?.ownerId) {
+                const ownerId = this.agentContext.ownerId;
+                for (const m of history) {
+                    m.isOwner = m.senderId === ownerId;
+                }
+            }
+            // Build agent context (fallback to minimal if not yet received)
+            const agent = this.agentContext ?? {
+                agentId: this.agentId,
+                ownerId: '',
+                ownerName: '',
+                accessLevel: 'open',
+            };
+            // Build context methods bound to this conversation
+            const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
+            const markAsRead = () => this.apiClient.markAsRead(conversationId);
+            const leave = () => this.apiClient.leaveConversation(conversationId);
+            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);
+            // Invoke handler
+            await this.handler({
+                messages,
+                history,
+                conversationId,
+                conversation,
+                reply,
+                deleteMessage,
+                markAsRead,
+                leave,
+                react,
+                addMember,
+                removeMember,
+                agent,
+                session: session
+                    ? {
+                        id: session.id,
+                        messages: session.messages,
+                        metadata: session.metadata,
+                    }
+                    : undefined,
+            });
+            // Auto-mark conversation as read after successful processing
+            if (this.options.autoMarkRead) {
+                try {
+                    await this.apiClient.markAsRead(conversationId);
+                }
+                catch {
+                    // Non-critical
+                }
+            }
+        }
+        catch (err) {
+            console.error(`[canon-sdk] Handler error for ${conversationId}:`, err);
+        }
+        finally {
+            clearInterval(thinkingKeepalive);
+            // Always clear typing when done
+            try {
+                await this.apiClient.setTyping(conversationId, false);
+            }
+            catch { }
+        }
+    }
+    // Static registration helpers (unauthenticated)
+    static async register(options) {
+        const { baseUrl, ...body } = options;
+        return CanonClient.register(baseUrl, body);
+    }
+    static async checkStatus(requestId, baseUrl) {
+        return CanonClient.checkStatus(baseUrl, requestId);
+    }
+}

package/dist/debouncer.d.ts

@@ -0,0 +1,13 @@
+import type { CanonMessage } from '@canonmsg/core';
+export declare class Debouncer {
+    private debounceMs;
+    private pending;
+    private timers;
+    private orderedFlags;
+    private callback;
+    constructor(debounceMs: number);
+    setCallback(cb: (conversationId: string, messages: CanonMessage[]) => void): void;
+    add(conversationId: string, message: CanonMessage): void;
+    private flush;
+    destroy(): void;
+}

package/dist/debouncer.js

@@ -0,0 +1,64 @@
+export class Debouncer {
+    debounceMs;
+    pending = new Map();
+    timers = new Map();
+    // Track whether each conversation's pending messages are already in sorted
+    // order so we can skip the sort on flush when possible (#10)
+    orderedFlags = new Map();
+    callback = null;
+    constructor(debounceMs) {
+        this.debounceMs = debounceMs;
+    }
+    setCallback(cb) {
+        this.callback = cb;
+    }
+    add(conversationId, message) {
+        const existing = this.pending.get(conversationId) || [];
+        // Deduplicate by message ID
+        if (!existing.some((m) => m.id === message.id)) {
+            if (existing.length === 0) {
+                // First message for this conversation — trivially ordered
+                this.orderedFlags.set(conversationId, true);
+            }
+            else if (this.orderedFlags.get(conversationId) !== false) {
+                // Still potentially ordered — check if new message maintains sort order
+                const lastTime = new Date(existing[existing.length - 1].createdAt).getTime();
+                const newTime = new Date(message.createdAt).getTime();
+                if (newTime < lastTime) {
+                    this.orderedFlags.set(conversationId, false);
+                }
+            }
+            existing.push(message);
+            this.pending.set(conversationId, existing);
+        }
+        // Reset timer for this conversation
+        const existingTimer = this.timers.get(conversationId);
+        if (existingTimer)
+            clearTimeout(existingTimer);
+        this.timers.set(conversationId, setTimeout(() => {
+            this.flush(conversationId);
+        }, this.debounceMs));
+    }
+    flush(conversationId) {
+        const messages = this.pending.get(conversationId);
+        const isOrdered = this.orderedFlags.get(conversationId) ?? false;
+        this.pending.delete(conversationId);
+        this.timers.delete(conversationId);
+        this.orderedFlags.delete(conversationId);
+        if (messages && messages.length > 0 && this.callback) {
+            // Only sort if insertions arrived out of order (#10)
+            if (!isOrdered) {
+                messages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+            }
+            this.callback(conversationId, messages);
+        }
+    }
+    destroy() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.pending.clear();
+        this.orderedFlags.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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 { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CanonAgent } from './canon-agent.js';
+export { CanonApiError } from '@canonmsg/core';
+export { SessionManager } from './session-manager.js';

package/dist/polling.d.ts

@@ -0,0 +1,16 @@
+import { CanonClient } from '@canonmsg/core';
+import { Debouncer } from './debouncer.js';
+export declare class PollingManager {
+    private apiClient;
+    private debouncer;
+    private agentId;
+    private pollingIntervalMs;
+    private lastSeenTimestamps;
+    private pollTimer;
+    private running;
+    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number);
+    start(): Promise<void>;
+    private poll;
+    private findActiveConversations;
+    stop(): void;
+}

package/dist/polling.js

@@ -0,0 +1,78 @@
+export class PollingManager {
+    apiClient;
+    debouncer;
+    agentId;
+    pollingIntervalMs;
+    lastSeenTimestamps = new Map();
+    pollTimer = null;
+    running = false;
+    constructor(apiClient, debouncer, agentId, pollingIntervalMs) {
+        this.apiClient = apiClient;
+        this.debouncer = debouncer;
+        this.agentId = agentId;
+        this.pollingIntervalMs = pollingIntervalMs;
+    }
+    async start() {
+        this.running = true;
+        // Initialize: mark current time as baseline (only respond to messages after start)
+        const now = Date.now();
+        const conversations = await this.apiClient.getConversations();
+        for (const convo of conversations) {
+            this.lastSeenTimestamps.set(convo.id, now);
+        }
+        // Start polling
+        this.pollTimer = setInterval(() => this.poll(), this.pollingIntervalMs);
+    }
+    async poll() {
+        if (!this.running)
+            return;
+        try {
+            const conversations = await this.apiClient.getConversations();
+            const activeConvos = this.findActiveConversations(conversations);
+            await Promise.all(activeConvos.map(async (convo) => {
+                try {
+                    const messages = await this.apiClient.getMessages(convo.id, 50);
+                    // Filter to only new messages (after lastSeen, not from self)
+                    const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
+                    const newMessages = messages.filter((m) => {
+                        const msgTime = new Date(m.createdAt).getTime();
+                        return msgTime > lastSeen && m.senderId !== this.agentId;
+                    });
+                    for (const msg of newMessages) {
+                        this.debouncer.add(convo.id, msg);
+                    }
+                    // Update lastSeen to latest message timestamp
+                    if (messages.length > 0) {
+                        const latestTime = Math.max(...messages.map((m) => new Date(m.createdAt).getTime()));
+                        this.lastSeenTimestamps.set(convo.id, latestTime);
+                    }
+                }
+                catch (err) {
+                    console.error(`[canon-sdk] Failed to fetch messages for ${convo.id}:`, err);
+                }
+            }));
+        }
+        catch (err) {
+            console.error('[canon-sdk] Polling error:', err);
+        }
+    }
+    findActiveConversations(conversations) {
+        return conversations.filter((convo) => {
+            if (!convo.lastMessage)
+                return false;
+            // Skip if agent was last sender
+            if (convo.lastMessage.senderId === this.agentId)
+                return false;
+            const lastMsgTime = new Date(convo.lastMessage.timestamp).getTime();
+            const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
+            return lastMsgTime > lastSeen;
+        });
+    }
+    stop() {
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+}

package/dist/realtime.d.ts

@@ -0,0 +1,23 @@
+import { CanonClient, type AgentContext } from '@canonmsg/core';
+import { Debouncer } from './debouncer.js';
+/**
+ * Wraps @canonmsg/core's CanonStream with SDK-specific features:
+ * - Debouncer integration (message batching)
+ * - Conversation discovery polling (detect new conversations)
+ * - Agent context callback
+ */
+export declare class RealtimeManager {
+    private apiClient;
+    private debouncer;
+    private agentId;
+    private stream;
+    private running;
+    private knownConversationIds;
+    private discoveryTimer;
+    private onAgentContext;
+    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
+    setOnAgentContext(cb: (ctx: AgentContext) => void): void;
+    start(): Promise<void>;
+    stop(): void;
+    private discoverNewConversations;
+}

package/dist/realtime.js

@@ -0,0 +1,124 @@
+import { CanonClient, CanonStream } from '@canonmsg/core';
+const DISCOVERY_INTERVAL_MS = 5_000;
+/**
+ * Wraps @canonmsg/core's CanonStream with SDK-specific features:
+ * - Debouncer integration (message batching)
+ * - Conversation discovery polling (detect new conversations)
+ * - Agent context callback
+ */
+export class RealtimeManager {
+    apiClient;
+    debouncer;
+    agentId;
+    stream;
+    running = false;
+    knownConversationIds = new Set();
+    discoveryTimer = null;
+    onAgentContext = null;
+    constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
+        this.debouncer = debouncer;
+        this.agentId = agentId;
+        this.apiClient = apiClient || new CanonClient(apiKey);
+        this.stream = new CanonStream({
+            apiKey,
+            agentId,
+            streamUrl,
+            handler: {
+                onMessage: (payload) => {
+                    const m = payload.message;
+                    const message = {
+                        id: m.id,
+                        senderId: m.senderId,
+                        senderType: m.senderType ?? 'human',
+                        isOwner: m.isOwner ?? false,
+                        contentType: m.contentType ?? 'text',
+                        text: m.text ?? null,
+                        imageUrl: m.imageUrl ?? null,
+                        audioUrl: m.audioUrl ?? null,
+                        audioDurationMs: m.audioDurationMs ?? null,
+                        mentions: m.mentions ?? [],
+                        replyTo: m.replyTo ?? null,
+                        replyToPosition: m.replyToPosition ?? null,
+                        status: 'sent',
+                        deleted: false,
+                        createdAt: m.createdAt ?? new Date().toISOString(),
+                        ...(m.metadata ? { metadata: m.metadata } : {}),
+                    };
+                    this.debouncer.add(payload.conversationId, message);
+                },
+                onAgentContext: (ctx) => {
+                    this.onAgentContext?.(ctx);
+                },
+                onConnected: () => {
+                    // Reset backoff is handled internally by CanonStream
+                },
+                onError: (err) => {
+                    console.error('[canon-sdk] SSE error:', err.message);
+                },
+            },
+        });
+    }
+    setOnAgentContext(cb) {
+        this.onAgentContext = cb;
+    }
+    async start() {
+        this.running = true;
+        // Snapshot current conversations
+        try {
+            const convos = await this.apiClient.getConversations();
+            for (const c of convos)
+                this.knownConversationIds.add(c.id);
+        }
+        catch {
+            // Non-fatal
+        }
+        // Start SSE stream
+        await this.stream.start();
+        // Start conversation discovery poll
+        this.discoveryTimer = setInterval(() => this.discoverNewConversations(), DISCOVERY_INTERVAL_MS);
+        if (this.discoveryTimer.unref)
+            this.discoveryTimer.unref();
+    }
+    stop() {
+        this.running = false;
+        if (this.discoveryTimer) {
+            clearInterval(this.discoveryTimer);
+            this.discoveryTimer = null;
+        }
+        this.stream.stop();
+    }
+    // ── Conversation discovery ─────────────────────────────────────────
+    async discoverNewConversations() {
+        if (!this.running)
+            return;
+        try {
+            const convos = await this.apiClient.getConversations();
+            const newConvoIds = [];
+            for (const c of convos) {
+                if (!this.knownConversationIds.has(c.id)) {
+                    this.knownConversationIds.add(c.id);
+                    newConvoIds.push(c.id);
+                }
+            }
+            if (newConvoIds.length === 0)
+                return;
+            console.log(`[canon-sdk] Discovered ${newConvoIds.length} new conversation(s) — fetching messages`);
+            // Fetch and deliver pending messages from new conversations
+            for (const convoId of newConvoIds) {
+                try {
+                    const messages = await this.apiClient.getMessages(convoId, 50);
+                    const newMessages = messages.filter((m) => m.senderId !== this.agentId);
+                    for (const msg of newMessages) {
+                        this.debouncer.add(convoId, msg);
+                    }
+                }
+                catch {
+                    // Will be picked up after reconnect
+                }
+            }
+        }
+        catch {
+            // Non-fatal — will retry next interval
+        }
+    }
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,61 @@
+import type { CanonMessage } from '@canonmsg/core';
+export interface SessionConfig {
+    /** Max messages to retain per session (default: 50) */
+    contextLimit?: number;
+    /** Max sessions processing concurrently (default: 10) */
+    concurrency?: number;
+    /** Evict idle sessions after this many ms (default: 1h) */
+    idleTimeoutMs?: number;
+}
+export interface Session {
+    /** Session ID (= conversationId) */
+    id: string;
+    /** Accumulated messages for this conversation, oldest first */
+    messages: CanonMessage[];
+    /** Arbitrary per-session state managed by the agent */
+    metadata: Record<string, unknown>;
+    /** When this session last processed a message */
+    lastActiveAt: number;
+}
+type SessionHandler = (session: Session, newMessages: CanonMessage[]) => Promise<void>;
+/**
+ * Manages per-conversation sessions with:
+ * - In-memory message buffer per session
+ * - Serialized processing within a session (queue)
+ * - Parallel processing across sessions (bounded concurrency)
+ * - Idle session eviction
+ */
+export declare class SessionManager {
+    private sessions;
+    private queues;
+    private activeCount;
+    private pending;
+    private processing;
+    private seenMessages;
+    private seededSessions;
+    private sweepTimer;
+    private contextLimit;
+    private concurrency;
+    private idleTimeoutMs;
+    constructor(config?: SessionConfig);
+    /** Get or create a session for a conversation */
+    getSession(conversationId: string): Session;
+    /**
+     * Enqueue messages for processing in a specific session.
+     * Returns a promise that resolves when the handler completes for these messages.
+     *
+     * - Messages within the same session are serialized (queued).
+     * - Messages across different sessions run concurrently up to the concurrency limit.
+     */
+    enqueue(conversationId: string, messages: CanonMessage[], handler: SessionHandler): Promise<void>;
+    private drainSession;
+    /** Seed a session with historical messages (e.g. fetched from API) */
+    seedHistory(conversationId: string, history: CanonMessage[]): void;
+    /** Remove idle sessions */
+    private sweep;
+    /** Number of active sessions */
+    get sessionCount(): number;
+    /** Clean up all state */
+    destroy(): void;
+}
+export {};