@framers/agentos 0.1.6 → 0.1.8

package/dist/channels/ChannelRouter.js

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview Channel Router — routes messages between external platforms
+ * and agent seeds.
+ *
+ * The ChannelRouter sits between {@link IChannelAdapter} implementations
+ * and the agent runtime (e.g., Wunderland's StimulusRouter). It:
+ *
+ * 1. Manages adapter instances per platform.
+ * 2. Maintains binding lookups (platform+conversationId -> seedId).
+ * 3. Dispatches inbound messages to registered handlers.
+ * 4. Routes outbound agent messages to the correct adapter.
+ *
+ * @module @framers/agentos/channels/ChannelRouter
+ */
+// ============================================================================
+// ChannelRouter
+// ============================================================================
+/**
+ * Central routing hub for all external messaging channels.
+ *
+ * @example
+ * ```typescript
+ * const router = new ChannelRouter();
+ *
+ * // Register adapters
+ * router.registerAdapter(telegramAdapter);
+ * router.registerAdapter(discordAdapter);
+ *
+ * // Add bindings
+ * router.addBinding({
+ *   bindingId: 'b1',
+ *   seedId: 'cipher-001',
+ *   ownerUserId: 'user-1',
+ *   platform: 'telegram',
+ *   channelId: '123456789',
+ *   conversationType: 'direct',
+ *   isActive: true,
+ *   autoBroadcast: false,
+ * });
+ *
+ * // Handle inbound messages
+ * router.onMessage(async (message, binding, session) => {
+ *   // Route to StimulusRouter or agent runtime
+ *   await stimulusRouter.ingestChannelMessage(message, binding.seedId);
+ * });
+ *
+ * // Send outbound message
+ * await router.sendMessage('cipher-001', 'telegram', '123456789', {
+ *   blocks: [{ type: 'text', text: 'Hello from Cipher!' }],
+ * });
+ * ```
+ */
+export class ChannelRouter {
+    constructor() {
+        /** Registered adapters keyed by platform. */
+        this.adapters = new Map();
+        /** Active bindings keyed by bindingId. */
+        this.bindings = new Map();
+        /** Active sessions keyed by sessionId. */
+        this.sessions = new Map();
+        /** Inbound message handlers. */
+        this.messageHandlers = new Set();
+        /** Lookup index: `${platform}:${conversationId}` -> bindingId[]. */
+        this.bindingIndex = new Map();
+        /** Unsubscribe functions for adapter event listeners. */
+        this.adapterUnsubs = new Map();
+    }
+    // ── Adapter Management ──
+    /**
+     * Register a channel adapter. The router will subscribe to its events.
+     */
+    registerAdapter(adapter, options) {
+        const key = options?.platformKey ?? adapter.platform;
+        if (this.adapters.has(key)) {
+            // Tear down existing adapter for this platform
+            this.unregisterAdapter(key);
+        }
+        this.adapters.set(key, adapter);
+        // Subscribe to all events from this adapter
+        const unsub = adapter.on(async (event) => {
+            if (event.type === 'message') {
+                await this.handleInboundMessage(event.data);
+            }
+        });
+        this.adapterUnsubs.set(key, unsub);
+    }
+    /**
+     * Unregister and shut down an adapter.
+     */
+    async unregisterAdapter(platformKey) {
+        const unsub = this.adapterUnsubs.get(platformKey);
+        if (unsub) {
+            unsub();
+            this.adapterUnsubs.delete(platformKey);
+        }
+        const adapter = this.adapters.get(platformKey);
+        if (adapter) {
+            await adapter.shutdown();
+            this.adapters.delete(platformKey);
+        }
+    }
+    /**
+     * Get a registered adapter by platform.
+     */
+    getAdapter(platform) {
+        return this.adapters.get(platform);
+    }
+    /**
+     * List all registered adapters with their info.
+     */
+    listAdapters() {
+        const result = [];
+        for (const [key, adapter] of this.adapters) {
+            const conn = adapter.getConnectionInfo();
+            result.push({
+                platform: adapter.platform,
+                displayName: adapter.displayName,
+                description: `${adapter.displayName} channel adapter`,
+                capabilities: [...adapter.capabilities],
+                available: conn.status === 'connected',
+                requiredSecrets: [], // Populated by extension descriptor
+            });
+        }
+        return result;
+    }
+    // ── Binding Management ──
+    /**
+     * Add or update a channel binding.
+     */
+    addBinding(binding) {
+        this.bindings.set(binding.bindingId, binding);
+        this.rebuildBindingIndex();
+    }
+    /**
+     * Remove a channel binding.
+     */
+    removeBinding(bindingId) {
+        this.bindings.delete(bindingId);
+        this.rebuildBindingIndex();
+    }
+    /**
+     * Get all bindings for a seed.
+     */
+    getBindingsForSeed(seedId) {
+        return [...this.bindings.values()].filter((b) => b.seedId === seedId && b.isActive);
+    }
+    /**
+     * Get all bindings for a platform + conversation.
+     */
+    getBindingsForConversation(platform, conversationId) {
+        const key = `${platform}:${conversationId}`;
+        const bindingIds = this.bindingIndex.get(key) || [];
+        return bindingIds
+            .map((id) => this.bindings.get(id))
+            .filter((b) => b !== undefined && b.isActive);
+    }
+    /**
+     * Get all auto-broadcast bindings for a seed (used when agent publishes a post).
+     */
+    getBroadcastBindings(seedId) {
+        return [...this.bindings.values()].filter((b) => b.seedId === seedId && b.isActive && b.autoBroadcast);
+    }
+    // ── Message Handling ──
+    /**
+     * Register a handler for inbound messages. Returns unsubscribe function.
+     */
+    onMessage(handler) {
+        this.messageHandlers.add(handler);
+        return () => this.messageHandlers.delete(handler);
+    }
+    /**
+     * Send a message from an agent to a specific conversation.
+     */
+    async sendMessage(seedId, platform, conversationId, content) {
+        const adapter = this.adapters.get(platform);
+        if (!adapter) {
+            throw new Error(`No adapter registered for platform '${platform}'`);
+        }
+        const result = await adapter.sendMessage(conversationId, content);
+        // Update session metrics
+        this.touchSession(seedId, platform, conversationId);
+        return result;
+    }
+    /**
+     * Broadcast a message from an agent to all auto-broadcast bindings.
+     */
+    async broadcast(seedId, content) {
+        const bindings = this.getBroadcastBindings(seedId);
+        const results = [];
+        for (const binding of bindings) {
+            try {
+                const result = await this.sendMessage(seedId, binding.platform, binding.channelId, content);
+                results.push(result);
+            }
+            catch (err) {
+                console.error(`[ChannelRouter] Broadcast to ${binding.platform}:${binding.channelId} failed:`, err);
+            }
+        }
+        return results;
+    }
+    /**
+     * Send a typing indicator for an agent on a channel.
+     */
+    async sendTypingIndicator(platform, conversationId, isTyping) {
+        const adapter = this.adapters.get(platform);
+        if (adapter) {
+            await adapter.sendTypingIndicator(conversationId, isTyping);
+        }
+    }
+    // ── Session Management ──
+    /**
+     * Get or create a session for an agent + conversation.
+     */
+    getOrCreateSession(seedId, platform, conversationId) {
+        const sessionKey = `${seedId}:${platform}:${conversationId}`;
+        let session = this.sessions.get(sessionKey);
+        if (!session) {
+            session = {
+                sessionId: sessionKey,
+                seedId,
+                platform,
+                conversationId,
+                conversationType: 'direct',
+                lastMessageAt: new Date().toISOString(),
+                messageCount: 0,
+                isActive: true,
+            };
+            this.sessions.set(sessionKey, session);
+        }
+        return session;
+    }
+    /**
+     * Get active sessions for a seed.
+     */
+    getSessionsForSeed(seedId) {
+        return [...this.sessions.values()].filter((s) => s.seedId === seedId && s.isActive);
+    }
+    // ── Stats ──
+    getStats() {
+        let activeSessions = 0;
+        for (const s of this.sessions.values()) {
+            if (s.isActive)
+                activeSessions++;
+        }
+        return {
+            adapters: this.adapters.size,
+            bindings: this.bindings.size,
+            activeSessions,
+            totalSessions: this.sessions.size,
+        };
+    }
+    /**
+     * Shut down all adapters and clear state.
+     */
+    async shutdown() {
+        for (const key of [...this.adapters.keys()]) {
+            await this.unregisterAdapter(key);
+        }
+        this.bindings.clear();
+        this.sessions.clear();
+        this.bindingIndex.clear();
+        this.messageHandlers.clear();
+    }
+    // ── Private ──
+    async handleInboundMessage(message) {
+        const bindings = this.getBindingsForConversation(message.platform, message.conversationId);
+        if (bindings.length === 0) {
+            // No binding found — message is from an unbound conversation
+            return;
+        }
+        // Dispatch to all matching bindings (usually 1, but multi-agent groups are possible)
+        for (const binding of bindings) {
+            const session = this.getOrCreateSession(binding.seedId, message.platform, message.conversationId);
+            session.lastMessageAt = message.timestamp;
+            session.messageCount++;
+            session.conversationType = message.conversationType;
+            if (message.sender) {
+                session.remoteUser = message.sender;
+            }
+            // Dispatch to all registered handlers
+            const handlerPromises = [...this.messageHandlers].map(async (handler) => {
+                try {
+                    await Promise.resolve(handler(message, binding, session));
+                }
+                catch (err) {
+                    console.error(`[ChannelRouter] Handler error for ${message.platform}:${message.conversationId}:`, err);
+                }
+            });
+            await Promise.allSettled(handlerPromises);
+        }
+    }
+    touchSession(seedId, platform, conversationId) {
+        const session = this.getOrCreateSession(seedId, platform, conversationId);
+        session.lastMessageAt = new Date().toISOString();
+        session.messageCount++;
+    }
+    rebuildBindingIndex() {
+        this.bindingIndex.clear();
+        for (const [id, binding] of this.bindings) {
+            if (!binding.isActive)
+                continue;
+            const key = `${binding.platform}:${binding.channelId}`;
+            const existing = this.bindingIndex.get(key) || [];
+            existing.push(id);
+            this.bindingIndex.set(key, existing);
+        }
+    }
+}
+//# sourceMappingURL=ChannelRouter.js.map

package/dist/channels/ChannelRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChannelRouter.js","sourceRoot":"","sources":["../../src/channels/ChannelRouter.ts"],"names":[],"mappings":"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"}

package/dist/channels/IChannelAdapter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Interface for external messaging channel adapters.
+ *
+ * Each supported platform (Telegram, WhatsApp, Discord, etc.) implements
+ * this interface. Adapters handle:
+ * - Authentication and connection lifecycle
+ * - Inbound message reception (platform -> agent)
+ * - Outbound message delivery (agent -> platform)
+ * - Platform-specific features (typing, reactions, buttons, etc.)
+ *
+ * Adapters are registered as `messaging-channel` extension descriptors
+ * and managed by the {@link ChannelRouter}.
+ *
+ * @module @framers/agentos/channels/IChannelAdapter
+ */
+import type { ChannelAuthConfig, ChannelCapability, ChannelConnectionInfo, ChannelEventHandler, ChannelEventType, ChannelPlatform, ChannelSendResult, MessageContent } from './types.js';
+/**
+ * Core adapter interface for external messaging channels.
+ *
+ * Implementors wrap a platform SDK (e.g., grammY for Telegram, discord.js for
+ * Discord) and normalize all interactions to this common contract.
+ *
+ * @example
+ * ```typescript
+ * class TelegramAdapter implements IChannelAdapter {
+ *   readonly platform = 'telegram';
+ *   readonly displayName = 'Telegram';
+ *   readonly capabilities = ['text', 'images', 'inline_keyboard', 'typing_indicator'];
+ *
+ *   async initialize(auth: ChannelAuthConfig): Promise<void> {
+ *     this.bot = new Bot(auth.credential);
+ *     await this.bot.start();
+ *   }
+ *
+ *   async sendMessage(conversationId, content): Promise<ChannelSendResult> {
+ *     const textBlock = content.blocks.find(b => b.type === 'text');
+ *     const msg = await this.bot.api.sendMessage(conversationId, textBlock.text);
+ *     return { messageId: String(msg.message_id) };
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface IChannelAdapter {
+    /** Platform this adapter serves. */
+    readonly platform: ChannelPlatform;
+    /** Human-readable display name (e.g., "WhatsApp Business"). */
+    readonly displayName: string;
+    /** Declared capabilities of this adapter. */
+    readonly capabilities: readonly ChannelCapability[];
+    /**
+     * Initialize the adapter with authentication credentials.
+     * Called once when the extension is activated. Must be idempotent —
+     * calling initialize on an already-initialized adapter should reconnect.
+     */
+    initialize(auth: ChannelAuthConfig): Promise<void>;
+    /**
+     * Gracefully shut down the adapter, closing connections and releasing
+     * resources. Called during extension deactivation or application shutdown.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the current connection status and metadata.
+     */
+    getConnectionInfo(): ChannelConnectionInfo;
+    /**
+     * Send a message to a conversation on the external platform.
+     *
+     * @param conversationId - Platform-native conversation/chat ID.
+     * @param content - Message content to send.
+     * @returns The platform-assigned message ID.
+     */
+    sendMessage(conversationId: string, content: MessageContent): Promise<ChannelSendResult>;
+    /**
+     * Send a typing indicator to a conversation. Not all platforms support
+     * this — check `capabilities` for `'typing_indicator'`.
+     */
+    sendTypingIndicator(conversationId: string, isTyping: boolean): Promise<void>;
+    /**
+     * Register a handler for channel events. Multiple handlers can be
+     * registered. Use `eventTypes` to filter which events to receive.
+     *
+     * @param handler - Callback invoked when an event occurs.
+     * @param eventTypes - Optional filter. If omitted, handler receives all events.
+     * @returns Unsubscribe function.
+     */
+    on(handler: ChannelEventHandler, eventTypes?: ChannelEventType[]): () => void;
+    /**
+     * Edit a previously sent message. Only available if adapter declares
+     * the `'editing'` capability.
+     */
+    editMessage?(conversationId: string, messageId: string, content: MessageContent): Promise<void>;
+    /**
+     * Delete a previously sent message. Only available if adapter declares
+     * the `'deletion'` capability.
+     */
+    deleteMessage?(conversationId: string, messageId: string): Promise<void>;
+    /**
+     * Add a reaction to a message. Only available if adapter declares
+     * the `'reactions'` capability.
+     */
+    addReaction?(conversationId: string, messageId: string, emoji: string): Promise<void>;
+    /**
+     * Get conversation metadata (name, members, etc.). Useful for group chats.
+     */
+    getConversationInfo?(conversationId: string): Promise<{
+        name?: string;
+        memberCount?: number;
+        isGroup: boolean;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+//# sourceMappingURL=IChannelAdapter.d.ts.map

package/dist/channels/IChannelAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IChannelAdapter.d.ts","sourceRoot":"","sources":["../../src/channels/IChannelAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAEhB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,eAAe;IAG9B,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAIpD;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;OAEG;IACH,iBAAiB,IAAI,qBAAqB,CAAC;IAI3C;;;;;;OAMG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEzF;;;OAGG;IACH,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI9E;;;;;;;OAOG;IACH,EAAE,CAAC,OAAO,EAAE,mBAAmB,EAAE,UAAU,CAAC,EAAE,gBAAgB,EAAE,GAAG,MAAM,IAAI,CAAC;IAI9E;;;OAGG;IACH,WAAW,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhG;;;OAGG;IACH,aAAa,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;OAGG;IACH,WAAW,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtF;;OAEG;IACH,mBAAmB,CAAC,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QACpD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CAAC;CACJ"}

package/dist/channels/IChannelAdapter.js

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Interface for external messaging channel adapters.
+ *
+ * Each supported platform (Telegram, WhatsApp, Discord, etc.) implements
+ * this interface. Adapters handle:
+ * - Authentication and connection lifecycle
+ * - Inbound message reception (platform -> agent)
+ * - Outbound message delivery (agent -> platform)
+ * - Platform-specific features (typing, reactions, buttons, etc.)
+ *
+ * Adapters are registered as `messaging-channel` extension descriptors
+ * and managed by the {@link ChannelRouter}.
+ *
+ * @module @framers/agentos/channels/IChannelAdapter
+ */
+export {};
+//# sourceMappingURL=IChannelAdapter.js.map

package/dist/channels/IChannelAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IChannelAdapter.js","sourceRoot":"","sources":["../../src/channels/IChannelAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/channels/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel exports for the AgentOS Channel System.
+ * @module @framers/agentos/channels
+ */
+export * from './types.js';
+export type { IChannelAdapter } from './IChannelAdapter.js';
+export { ChannelRouter } from './ChannelRouter.js';
+export type { InboundMessageHandler, RegisterAdapterOptions } from './ChannelRouter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/channels/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel exports for the AgentOS Channel System.
+ * @module @framers/agentos/channels
+ */
+export * from './types.js';
+export { ChannelRouter } from './ChannelRouter.js';
+//# sourceMappingURL=index.js.map

package/dist/channels/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,YAAY,CAAC;AAE3B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}