@canonmsg/agent-sdk 0.2.0

package/dist/session-manager.js

@@ -0,0 +1,180 @@
+const DEFAULT_CONTEXT_LIMIT = 50;
+const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_IDLE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour
+const SWEEP_INTERVAL_MS = 60 * 1000; // 1 minute
+/**
+ * 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 class SessionManager {
+    sessions = new Map();
+    queues = new Map();
+    activeCount = 0;
+    // Use Set<string> instead of Array for O(1) dedup and correct pop semantics (#1, #2)
+    pending = new Set();
+    processing = new Set();
+    // Per-session seen message ID sets for O(1) dedup (#9)
+    seenMessages = new Map();
+    // Track seeded sessions so seedHistory is idempotent (#7)
+    seededSessions = new Set();
+    sweepTimer = null;
+    contextLimit;
+    concurrency;
+    idleTimeoutMs;
+    constructor(config = {}) {
+        this.contextLimit = config.contextLimit ?? DEFAULT_CONTEXT_LIMIT;
+        this.concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+        this.idleTimeoutMs = config.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+        this.sweepTimer = setInterval(() => this.sweep(), SWEEP_INTERVAL_MS);
+        // Don't hold the process open for the sweeper
+        if (this.sweepTimer.unref)
+            this.sweepTimer.unref();
+    }
+    /** Get or create a session for a conversation */
+    getSession(conversationId) {
+        let session = this.sessions.get(conversationId);
+        if (!session) {
+            session = {
+                id: conversationId,
+                messages: [],
+                metadata: {},
+                lastActiveAt: Date.now(),
+            };
+            this.sessions.set(conversationId, session);
+            this.seenMessages.set(conversationId, new Set());
+        }
+        // Refresh lastActiveAt on every access to prevent premature eviction (#8)
+        session.lastActiveAt = Date.now();
+        return 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.
+     */
+    async enqueue(conversationId, messages, handler) {
+        const session = this.getSession(conversationId);
+        const seen = this.seenMessages.get(conversationId);
+        // Append new messages using O(1) Set lookup for dedup (#9)
+        for (const msg of messages) {
+            if (!seen.has(msg.id)) {
+                seen.add(msg.id);
+                session.messages.push(msg);
+            }
+        }
+        // Trim to context limit (keep most recent)
+        if (session.messages.length > this.contextLimit) {
+            session.messages = session.messages.slice(-this.contextLimit);
+        }
+        session.lastActiveAt = Date.now();
+        return new Promise((resolve, reject) => {
+            // Add to this session's queue
+            let queue = this.queues.get(conversationId);
+            if (!queue) {
+                queue = [];
+                this.queues.set(conversationId, queue);
+            }
+            queue.push({ messages, resolve, reject });
+            // Try to drain
+            this.drainSession(conversationId, handler);
+        });
+    }
+    drainSession(conversationId, handler) {
+        // Already processing this session — the current run will pick up queued items
+        if (this.processing.has(conversationId))
+            return;
+        const queue = this.queues.get(conversationId);
+        if (!queue || queue.length === 0)
+            return;
+        // Check concurrency limit
+        if (this.activeCount >= this.concurrency) {
+            // Park this session — Set.add() is atomic and idempotent, eliminating
+            // the race between check and insert (#1)
+            this.pending.add(conversationId);
+            return;
+        }
+        // Take the next item
+        const item = queue.shift();
+        if (queue.length === 0)
+            this.queues.delete(conversationId);
+        this.activeCount++;
+        this.processing.add(conversationId);
+        const session = this.getSession(conversationId);
+        handler(session, item.messages)
+            .then(() => item.resolve())
+            .catch((err) => item.reject(err))
+            .finally(() => {
+            this.processing.delete(conversationId);
+            this.activeCount--;
+            // Continue draining this session if more items queued
+            const remaining = this.queues.get(conversationId);
+            if (remaining && remaining.length > 0) {
+                this.drainSession(conversationId, handler);
+            }
+            // Unpark the next pending session.
+            // Use Set iteration + explicit delete to get the correct conversation ID
+            // rather than shift() which could dequeue the wrong entry (#2)
+            if (this.pending.size > 0) {
+                const nextId = this.pending.values().next().value;
+                this.pending.delete(nextId);
+                this.drainSession(nextId, handler);
+            }
+        });
+    }
+    /** Seed a session with historical messages (e.g. fetched from API) */
+    seedHistory(conversationId, history) {
+        // Idempotent: only seed once per session, preventing races between
+        // concurrent batches that both observe an empty session (#7)
+        if (this.seededSessions.has(conversationId))
+            return;
+        const session = this.getSession(conversationId);
+        // Only seed if session is empty (first time)
+        if (session.messages.length > 0)
+            return;
+        this.seededSessions.add(conversationId);
+        const seen = this.seenMessages.get(conversationId);
+        const sliced = history.slice(-this.contextLimit);
+        session.messages = sliced;
+        for (const msg of sliced) {
+            seen.add(msg.id);
+        }
+    }
+    /** Remove idle sessions */
+    sweep() {
+        const now = Date.now();
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActiveAt > this.idleTimeoutMs &&
+                !this.processing.has(id) &&
+                !this.queues.has(id) &&
+                !this.pending.has(id) // also skip sessions waiting for a concurrency slot (#8)
+            ) {
+                this.sessions.delete(id);
+                this.seenMessages.delete(id);
+                this.seededSessions.delete(id);
+            }
+        }
+    }
+    /** Number of active sessions */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /** Clean up all state */
+    destroy() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+        this.sessions.clear();
+        this.queues.clear();
+        this.pending.clear();
+        this.processing.clear();
+        this.seenMessages.clear();
+        this.seededSessions.clear();
+        this.activeCount = 0;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,71 @@
+export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+import type { CanonMessage, CanonConversation } from '@canonmsg/core';
+export type SDKMessage = CanonMessage;
+export type SDKConversation = CanonConversation;
+export interface SessionInfo {
+    /** Session ID (= conversationId) */
+    id: string;
+    /** All accumulated messages for this conversation (within the context limit), oldest first */
+    messages: SDKMessage[];
+    /** Arbitrary per-session state the agent can read/write across handler calls */
+    metadata: Record<string, unknown>;
+}
+export interface MessageHandlerContext {
+    messages: SDKMessage[];
+    history: SDKMessage[];
+    conversationId: string;
+    conversation: SDKConversation;
+    reply: (text: string) => Promise<{
+        messageId: string;
+    }>;
+    /** Soft-delete a message (agent must be the sender) */
+    deleteMessage: (messageId: string) => Promise<void>;
+    /** Mark conversation as read */
+    markAsRead: () => Promise<void>;
+    /** Leave this conversation */
+    leave: () => Promise<void>;
+    /** Toggle emoji reaction on a message */
+    react: (messageId: string, emoji: string) => Promise<void>;
+    /** Add a member to this conversation (requires owner/admin role) */
+    addMember: (userId: string) => Promise<void>;
+    /** Remove a member from this conversation (requires owner/admin role) */
+    removeMember: (userId: string) => Promise<void>;
+    /** Trusted agent identity & access context */
+    agent: import('@canonmsg/core').AgentContext;
+    /** Per-conversation session state. Present when sessions are enabled. */
+    session?: SessionInfo;
+}
+export type MessageHandler = (ctx: MessageHandlerContext) => Promise<void>;
+export interface SessionOptions {
+    /** Enable per-conversation session management (default: false) */
+    enabled: boolean;
+    /** Max messages retained per session (default: 50) */
+    contextLimit?: number;
+    /** Max sessions processing concurrently (default: 10) */
+    concurrency?: number;
+    /** Evict idle sessions after this many ms (default: 3600000 = 1h) */
+    idleTimeoutMs?: number;
+}
+export type DeliveryMode = 'auto' | 'sse' | 'realtime' | 'polling';
+export interface CanonAgentOptions {
+    apiKey: string;
+    baseUrl?: string;
+    streamUrl?: string;
+    deliveryMode?: DeliveryMode;
+    pollingIntervalMs?: number;
+    debounceMs?: number;
+    historyLimit?: number;
+    /** Automatically mark conversations as read when handling messages (default: true) */
+    autoMarkRead?: boolean;
+    /** Per-conversation session management */
+    sessions?: SessionOptions;
+    /** Agent client type for capability detection. Defaults to 'generic'. */
+    clientType?: import('@canonmsg/core').AgentClientType;
+    /**
+     * Enable RTDB session state reporting. Off by default.
+     * When enabled, the SDK writes { cwd, isActive, ... } to
+     * /session-state/{convoId}/{agentId} so the Canon app can display
+     * the agent's active status and configuration.
+     */
+    sessionState?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@canonmsg/agent-sdk",
+  "version": "0.2.0",
+  "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@canonmsg/core": "^0.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "~5.7.0"
+  },
+  "license": "MIT"
+}