fluxy-bot 0.13.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluxy-bot",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "releaseNotes": [
     "1. react router implemented",
     "2. new workspace design",

package/shared/config.ts

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import { paths, DATA_DIR } from './paths.js';
 
+export type ChannelType = 'chat' | 'whatsapp' | 'telegram';
+
 export interface BotConfig {
   port: number;
   username: string;
@@ -26,6 +28,16 @@ export interface BotConfig {
     address: string;
   };
   tunnelUrl?: string;
+  channels?: {
+    whatsapp?: { enabled: boolean };
+    telegram?: { enabled: boolean; botToken?: string };
+  };
+  customerMode?: {
+    enabled: boolean;
+    systemPromptFile?: string;
+    businessName?: string;
+    businessDescription?: string;
+  };
 }
 
 const DEFAULTS: BotConfig = {

package/supervisor/channels/chat-channel.ts

@@ -0,0 +1,44 @@
+/**
+ * Chat Channel — wraps the existing WebSocket chat as a Channel.
+ * Chat is ALWAYS the owner channel. This adapter bridges the existing
+ * WS broadcast system with the Channel interface.
+ */
+
+import type { Channel, ChannelRouter, OutgoingMessage } from './types.js';
+
+export interface ChatChannelOpts {
+  broadcastFluxy: (type: string, data: any) => void;
+}
+
+export class ChatChannel implements Channel {
+  readonly type = 'chat' as const;
+  private opts: ChatChannelOpts;
+
+  constructor(opts: ChatChannelOpts) {
+    this.opts = opts;
+  }
+
+  async initialize(_router: ChannelRouter): Promise<void> {
+    // Chat channel is always initialized — WS server is managed by supervisor
+  }
+
+  async sendMessage(_to: string, message: OutgoingMessage): Promise<void> {
+    // Route through existing broadcast system
+    this.opts.broadcastFluxy('chat:sync', {
+      conversationId: message.conversationKey,
+      message: {
+        role: 'assistant',
+        content: message.content,
+        timestamp: new Date().toISOString(),
+      },
+    });
+  }
+
+  ownsConversation(conversationKey: string): boolean {
+    return conversationKey.startsWith('chat:');
+  }
+
+  async shutdown(): Promise<void> {
+    // WS server lifecycle is managed by supervisor
+  }
+}

package/supervisor/channels/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Channel registry — initializes and registers all enabled channels.
+ */
+
+import type { BotConfig } from '../../shared/config.js';
+import { log } from '../../shared/logger.js';
+import { initRoleResolver } from './role-resolver.js';
+import { ChannelRouter, type ChannelRouterOpts } from './router.js';
+import { ChatChannel } from './chat-channel.js';
+
+export { ChannelRouter } from './router.js';
+export type { Channel, ChannelType, SenderRole, SenderIdentity, IncomingMessage, OutgoingMessage } from './types.js';
+
+/**
+ * Create and initialize the channel router with all enabled channels.
+ */
+export async function initializeChannels(
+  config: BotConfig,
+  opts: ChannelRouterOpts,
+): Promise<ChannelRouter> {
+  // Initialize the role resolver with worker API access
+  initRoleResolver({ workerApi: opts.workerApi });
+
+  // Create the router
+  const router = new ChannelRouter(opts);
+
+  // Chat channel is always registered
+  const chatChannel = new ChatChannel({ broadcastFluxy: opts.broadcastFluxy });
+  router.registerChannel(chatChannel);
+  await chatChannel.initialize(router);
+
+  // WhatsApp channel — registered if enabled in config
+  // The actual implementation is done by Fluxy as a skill.
+  // See docs/whatsapp-channel-guide.md for implementation details.
+  if (config.channels?.whatsapp?.enabled) {
+    log.info('[channels] WhatsApp is enabled in config — waiting for channel implementation to register');
+    // The WhatsApp channel will self-register via router.registerChannel()
+    // when the skill implementation calls it during initialization.
+  }
+
+  // Telegram channel — placeholder for future implementation
+  if (config.channels?.telegram?.enabled) {
+    log.info('[channels] Telegram is enabled in config — waiting for channel implementation to register');
+  }
+
+  log.ok(`[channels] Initialized with ${router.getAllChannels().length} channel(s)`);
+  return router;
+}

package/supervisor/channels/role-resolver.ts

@@ -0,0 +1,41 @@
+/**
+ * Role resolver for multi-channel access control.
+ * Chat is ALWAYS owner. Other channels look up the contacts DB.
+ */
+
+import type { ChannelType, SenderRole } from './types.js';
+
+export interface RoleResolverOpts {
+  workerApi: (path: string, method?: string, body?: any) => Promise<any>;
+}
+
+let opts: RoleResolverOpts | null = null;
+
+export function initRoleResolver(resolverOpts: RoleResolverOpts) {
+  opts = resolverOpts;
+}
+
+/**
+ * Resolve the role of a sender.
+ * Chat channel is ALWAYS owner — no lookup needed.
+ * Other channels check the contacts DB via the worker API.
+ */
+export async function resolveRole(channelType: ChannelType, senderId: string): Promise<SenderRole> {
+  // Chat is sacred — always the owner
+  if (channelType === 'chat') return 'owner';
+
+  if (!opts) return 'customer';
+
+  try {
+    const result = await opts.workerApi(
+      `/api/contacts/resolve?channel_type=${encodeURIComponent(channelType)}&identifier=${encodeURIComponent(senderId)}`
+    );
+    if (result?.role && ['owner', 'admin', 'customer'].includes(result.role)) {
+      return result.role as SenderRole;
+    }
+  } catch {
+    // If lookup fails, default to customer (safest)
+  }
+
+  return 'customer';
+}

package/supervisor/channels/router.ts

@@ -0,0 +1,245 @@
+/**
+ * Channel Router — central orchestrator for multi-channel message handling.
+ * Receives messages from any channel, resolves roles, picks the right agent,
+ * and routes responses back to the originating channel.
+ */
+
+import { log } from '../../shared/logger.js';
+import { resolveRole } from './role-resolver.js';
+import { startFluxyAgentQuery, startCustomerAgentQuery, type RecentMessage, type CustomerContext } from '../fluxy-agent.js';
+import type { Channel, ChannelType, IncomingMessage, OutgoingMessage, SenderRole, ChannelRouter as IChannelRouter } from './types.js';
+import { loadConfig } from '../../shared/config.js';
+
+export interface ChannelRouterOpts {
+  workerApi: (path: string, method?: string, body?: any) => Promise<any>;
+  broadcastFluxy: (type: string, data: any) => void;
+  getModel: () => string;
+  restartBackend: () => void;
+}
+
+// Per-conversationKey lock to allow concurrent queries across channels
+const activeChannelQueries = new Map<string, boolean>();
+
+export class ChannelRouter implements IChannelRouter {
+  private channels = new Map<ChannelType, Channel>();
+  private opts: ChannelRouterOpts;
+
+  constructor(opts: ChannelRouterOpts) {
+    this.opts = opts;
+  }
+
+  registerChannel(channel: Channel): void {
+    this.channels.set(channel.type, channel);
+    log.info(`[router] Registered channel: ${channel.type}`);
+  }
+
+  getChannel(type: ChannelType): Channel | undefined {
+    return this.channels.get(type);
+  }
+
+  /** Get all registered channels (for shutdown, etc.) */
+  getAllChannels(): Channel[] {
+    return Array.from(this.channels.values());
+  }
+
+  getChannelForConversation(conversationKey: string): Channel | undefined {
+    const channelType = conversationKey.split(':')[0] as ChannelType;
+    return this.channels.get(channelType);
+  }
+
+  /**
+   * Handle an incoming message from any channel.
+   * Resolves role, creates/reuses conversation, dispatches to the right agent.
+   */
+  async handleIncoming(message: IncomingMessage): Promise<void> {
+    const { sender, content } = message;
+    const { conversationKey, channelType, senderId, displayName } = sender;
+
+    // Resolve role (chat is always owner, others check contacts DB)
+    const role = await resolveRole(channelType, senderId);
+    sender.role = role;
+
+    log.info(`[router] Incoming from ${channelType}:${senderId} (${displayName}) role=${role} key=${conversationKey}`);
+
+    // Prevent duplicate queries for the same conversation key
+    if (activeChannelQueries.get(conversationKey)) {
+      log.warn(`[router] Query already active for ${conversationKey}, skipping`);
+      return;
+    }
+    activeChannelQueries.set(conversationKey, true);
+
+    try {
+      const model = this.opts.getModel();
+
+      // Get or create a conversation in the DB for this conversation key
+      const conv = await this.opts.workerApi('/api/conversations', 'POST', {
+        title: content.slice(0, 80),
+        model,
+      });
+      const convId = conv.id;
+
+      // Save user message to DB
+      await this.opts.workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+        role: 'user',
+        content,
+        meta: { model },
+      });
+
+      // Fetch recent messages for context
+      let recentMessages: RecentMessage[] = [];
+      try {
+        const recentRaw = await this.opts.workerApi(`/api/conversations/${convId}/messages/recent?limit=20`) as any[];
+        if (Array.isArray(recentRaw)) {
+          const filtered = recentRaw.filter((m: any) => m.role === 'user' || m.role === 'assistant');
+          if (filtered.length > 0) {
+            recentMessages = filtered.slice(0, -1).map((m: any) => ({
+              role: m.role as 'user' | 'assistant',
+              content: m.content,
+            }));
+          }
+        }
+      } catch {}
+
+      // Get the originating channel for response routing
+      const channel = this.channels.get(channelType);
+
+      if (role === 'owner' || role === 'admin') {
+        await this.dispatchOwnerQuery(convId, conversationKey, content, model, channel, senderId, recentMessages, channelType);
+      } else {
+        await this.dispatchCustomerQuery(convId, conversationKey, content, model, channel, senderId, displayName, recentMessages, channelType);
+      }
+    } catch (err: any) {
+      log.warn(`[router] Error handling message from ${conversationKey}: ${err.message}`);
+    } finally {
+      activeChannelQueries.delete(conversationKey);
+    }
+  }
+
+  /**
+   * Dispatch a query for owner/admin — full Fluxy capabilities.
+   */
+  private async dispatchOwnerQuery(
+    convId: string,
+    conversationKey: string,
+    content: string,
+    model: string,
+    channel: Channel | undefined,
+    senderId: string,
+    recentMessages: RecentMessage[],
+    channelType: ChannelType,
+  ): Promise<void> {
+    // Fetch bot/human names
+    let botName = 'Fluxy', humanName = 'Human';
+    try {
+      const status = await this.opts.workerApi('/api/onboard/status');
+      botName = status.agentName || 'Fluxy';
+      humanName = status.userName || 'Human';
+    } catch {}
+
+    return new Promise<void>((resolve) => {
+      startFluxyAgentQuery(convId, content, model, (type, eventData) => {
+        if (type === 'bot:response' && eventData.content) {
+          // Save to DB
+          this.opts.workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+            role: 'assistant', content: eventData.content, meta: { model },
+          }).catch(() => {});
+
+          // Route response back to originating channel
+          if (channel && channelType !== 'chat') {
+            channel.sendMessage(senderId, { content: eventData.content, conversationKey }).catch((err) => {
+              log.warn(`[router] Failed to send response to ${channelType}: ${err.message}`);
+            });
+            // Also broadcast to chat UI so owner sees the exchange
+            this.opts.broadcastFluxy('chat:sync', {
+              conversationId: convId,
+              message: { role: 'assistant', content: eventData.content, timestamp: new Date().toISOString(), channel: channelType },
+            });
+          }
+        }
+
+        if (type === 'bot:done') {
+          if (eventData.usedFileTools) {
+            this.opts.restartBackend();
+          }
+          resolve();
+        }
+      }, undefined, undefined, { botName, humanName }, recentMessages);
+    });
+  }
+
+  /**
+   * Dispatch a query for customer — restricted capabilities.
+   */
+  private async dispatchCustomerQuery(
+    convId: string,
+    conversationKey: string,
+    content: string,
+    model: string,
+    channel: Channel | undefined,
+    senderId: string,
+    displayName: string,
+    recentMessages: RecentMessage[],
+    channelType: ChannelType,
+  ): Promise<void> {
+    const config = loadConfig();
+    const customerMode = config.customerMode || {};
+
+    const customerContext: CustomerContext = {
+      senderName: displayName,
+      senderIdentifier: senderId,
+      channelType,
+      businessName: customerMode.businessName || 'Our Business',
+      businessDescription: customerMode.businessDescription || '',
+    };
+
+    return new Promise<void>((resolve) => {
+      startCustomerAgentQuery(conversationKey, content, model, (type, eventData) => {
+        if (type === 'bot:response' && eventData.content) {
+          // Save to DB
+          this.opts.workerApi(`/api/conversations/${convId}/messages`, 'POST', {
+            role: 'assistant', content: eventData.content, meta: { model },
+          }).catch(() => {});
+
+          // Route response back to originating channel
+          if (channel) {
+            channel.sendMessage(senderId, { content: eventData.content, conversationKey }).catch((err) => {
+              log.warn(`[router] Failed to send customer response to ${channelType}: ${err.message}`);
+            });
+          }
+        }
+
+        if (type === 'bot:done') {
+          resolve();
+        }
+      }, customerContext, recentMessages);
+    });
+  }
+
+  /**
+   * Route a pulse/cron message to ALL owner-role channels.
+   * Customer channels NEVER receive autonomous messages.
+   */
+  async routePulseMessage(content: string, title?: string, _priority?: string): Promise<void> {
+    for (const [type, channel] of this.channels) {
+      // Chat is handled by existing broadcastFluxy — skip to avoid duplicates
+      if (type === 'chat') continue;
+
+      try {
+        // Find all owner contacts for this channel type
+        const contacts = await this.opts.workerApi('/api/contacts') as any[];
+        const ownerContacts = (contacts || []).filter(
+          (c: any) => c.channel_type === type && c.role === 'owner'
+        );
+
+        for (const contact of ownerContacts) {
+          await channel.sendMessage(contact.identifier, {
+            content: title ? `**${title}**\n\n${content}` : content,
+            conversationKey: `${type}:${contact.identifier}`,
+          });
+        }
+      } catch (err: any) {
+        log.warn(`[router] Failed to route pulse to ${type}: ${err.message}`);
+      }
+    }
+  }
+}

package/supervisor/channels/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Multi-channel communication types.
+ * Defines the channel abstraction, message formats, and role system.
+ */
+
+export type ChannelType = 'chat' | 'whatsapp' | 'telegram';
+export type SenderRole = 'owner' | 'admin' | 'customer';
+
+export interface SenderIdentity {
+  channelType: ChannelType;
+  senderId: string;         // phone number, telegram ID, 'owner' for chat
+  displayName: string;
+  role: SenderRole;
+  conversationKey: string;  // "whatsapp:+5511999999999", "chat:owner"
+}
+
+export interface IncomingMessage {
+  sender: SenderIdentity;
+  content: string;
+  timestamp: number;
+  attachments?: Array<{
+    type: 'image' | 'file' | 'audio';
+    name: string;
+    mediaType: string;
+    data: string; // base64
+  }>;
+}
+
+export interface OutgoingMessage {
+  content: string;
+  conversationKey: string;
+}
+
+// Forward reference — ChannelRouter is imported by channel implementations
+export interface ChannelRouter {
+  handleIncoming(message: IncomingMessage): Promise<void>;
+  routePulseMessage(content: string, title?: string, priority?: string): Promise<void>;
+  getChannelForConversation(conversationKey: string): Channel | undefined;
+}
+
+export interface Channel {
+  readonly type: ChannelType;
+
+  /** Initialize the channel (connect socket, start webhook listener, etc.) */
+  initialize(router: ChannelRouter): Promise<void>;
+
+  /** Send a message back through this channel */
+  sendMessage(to: string, message: OutgoingMessage): Promise<void>;
+
+  /** Check if this channel owns a given conversation key */
+  ownsConversation(conversationKey: string): boolean;
+
+  /** Graceful shutdown */
+  shutdown(): Promise<void>;
+}

package/supervisor/fluxy-agent.ts

@@ -12,6 +12,16 @@ import type { SavedFile } from './file-saver.js';
 import { getClaudeAccessToken } from '../worker/claude-auth.js';
 
 const PROMPT_FILE = path.join(import.meta.dirname, '..', 'worker', 'prompts', 'fluxy-system-prompt.txt');
+const CUSTOMER_PROMPT_FILE = path.join(import.meta.dirname, '..', 'worker', 'prompts', 'customer-system-prompt.txt');
+
+/** Default tools disallowed for customer conversations. Edit this list to control customer access. */
+const CUSTOMER_DISALLOWED_TOOLS = [
+  'Bash',
+  // Add more tools here to restrict customer access, e.g.:
+  // 'Write',
+  // 'Edit',
+  // 'Agent',
+];
 
 export interface RecentMessage {
   role: 'user' | 'assistant';
@@ -160,12 +170,24 @@ export async function startFluxyAgentQuery(
 
   try {
     // Auto-discover all skill plugins in workspace/skills/ — any folder with a valid plugin.json is loaded
+    // Skills use a flat structure on disk (SKILL.md at the root), but the SDK expects
+    // skills/{name}/SKILL.md — we bridge the gap with symlinks created on discovery.
     const skillsDir = path.join(PKG_DIR, 'workspace', 'skills');
     const plugins: { type: 'local'; path: string }[] = [];
     try {
       for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
         if (entry.isDirectory() && fs.existsSync(path.join(skillsDir, entry.name, '.claude-plugin', 'plugin.json'))) {
           plugins.push({ type: 'local' as const, path: path.join(skillsDir, entry.name) });
+
+          // Bridge flat SKILL.md → nested path the SDK expects (via symlink)
+          const skillName = entry.name;
+          const flatSkillMd = path.join(skillsDir, skillName, 'SKILL.md');
+          const sdkDir = path.join(skillsDir, skillName, 'skills', skillName);
+          const sdkSkillMd = path.join(sdkDir, 'SKILL.md');
+          if (fs.existsSync(flatSkillMd) && !fs.existsSync(sdkSkillMd)) {
+            fs.mkdirSync(sdkDir, { recursive: true });
+            fs.symlinkSync(flatSkillMd, sdkSkillMd);
+          }
         }
       }
     } catch {}
@@ -277,6 +299,141 @@ export async function startFluxyAgentQuery(
   }
 }
 
+/**
+ * Read the customer-facing system prompt, replacing placeholders.
+ */
+function readCustomerSystemPrompt(ctx: CustomerContext): string {
+  try {
+    const raw = fs.readFileSync(CUSTOMER_PROMPT_FILE, 'utf-8').trim();
+    if (!raw) return `You are a helpful business assistant for ${ctx.businessName}.`;
+    return raw
+      .replace(/\$BUSINESS_NAME/g, ctx.businessName)
+      .replace(/\$BUSINESS_DESCRIPTION/g, ctx.businessDescription)
+      .replace(/\$SENDER_NAME/g, ctx.senderName)
+      .replace(/\$CHANNEL/g, ctx.channelType)
+      .replace(/\$DISALLOWED_TOOLS/g, CUSTOMER_DISALLOWED_TOOLS.join(', ') || '(none)');
+  } catch {
+    return `You are a helpful business assistant for ${ctx.businessName}.`;
+  }
+}
+
+export interface CustomerContext {
+  senderName: string;
+  senderIdentifier: string;
+  channelType: string;
+  businessName: string;
+  businessDescription: string;
+}
+
+/**
+ * Run an Agent SDK query for a customer conversation.
+ * Restricted: different system prompt, limited tools, no memory files, no plugins, no MCP.
+ */
+export async function startCustomerAgentQuery(
+  conversationKey: string,
+  prompt: string,
+  model: string,
+  onMessage: (type: string, data: any) => void,
+  customerContext: CustomerContext,
+  recentMessages?: RecentMessage[],
+): Promise<void> {
+  const oauthToken = await getClaudeAccessToken();
+  if (!oauthToken) {
+    onMessage('bot:error', { conversationId: conversationKey, error: 'Claude OAuth token not found.' });
+    return;
+  }
+
+  const abortController = new AbortController();
+  let customerPrompt = readCustomerSystemPrompt(customerContext);
+
+  if (recentMessages?.length) {
+    customerPrompt = customerPrompt.replace(
+      '$CONVERSATION_HISTORY',
+      formatConversationHistory(recentMessages),
+    );
+  } else {
+    customerPrompt = customerPrompt.replace('$CONVERSATION_HISTORY', '(none)');
+  }
+
+  activeQueries.set(conversationKey, { abortController });
+
+  let fullText = '';
+  let stderrBuf = '';
+
+  try {
+    const claudeQuery = query({
+      prompt,
+      options: {
+        model,
+        cwd: WORKSPACE_DIR,
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        disallowedTools: CUSTOMER_DISALLOWED_TOOLS,
+        maxTurns: 10,
+        abortController,
+        systemPrompt: customerPrompt,
+        // No plugins, no MCP servers for customers
+        stderr: (chunk: string) => { stderrBuf += chunk; },
+        env: {
+          ...process.env as Record<string, string>,
+          CLAUDE_CODE_OAUTH_TOKEN: oauthToken,
+          CLAUDE_CODE_BUBBLEWRAP: '1',
+        },
+      },
+    });
+
+    onMessage('bot:typing', { conversationId: conversationKey });
+
+    for await (const msg of claudeQuery) {
+      if (abortController.signal.aborted) break;
+
+      switch (msg.type) {
+        case 'assistant': {
+          const assistantMsg = msg.message;
+          if (!assistantMsg?.content) break;
+          for (const block of assistantMsg.content) {
+            if (block.type === 'text' && block.text) {
+              if (fullText && !fullText.endsWith('\n')) {
+                fullText += '\n\n';
+                onMessage('bot:token', { conversationId: conversationKey, token: '\n\n' });
+              }
+              fullText += block.text;
+              onMessage('bot:token', { conversationId: conversationKey, token: block.text });
+            } else if (block.type === 'tool_use') {
+              onMessage('bot:tool', { conversationId: conversationKey, name: block.name, input: block.input });
+            }
+          }
+          break;
+        }
+        case 'result': {
+          if (fullText) {
+            onMessage('bot:response', { conversationId: conversationKey, content: fullText });
+            fullText = '';
+          } else if (msg.subtype?.startsWith('error')) {
+            const errorText = (msg as any).errors?.join('; ') || 'Agent query failed';
+            onMessage('bot:error', { conversationId: conversationKey, error: errorText });
+          }
+          break;
+        }
+      }
+    }
+
+    if (fullText && !abortController.signal.aborted) {
+      onMessage('bot:response', { conversationId: conversationKey, content: fullText });
+    }
+  } catch (err: any) {
+    if (!abortController.signal.aborted) {
+      const detail = stderrBuf.trim();
+      const msg = detail ? `${err.message}\n\nCLI stderr:\n${detail}` : err.message;
+      log.warn(`Customer agent error (${conversationKey}): ${msg}`);
+      onMessage('bot:error', { conversationId: conversationKey, error: msg });
+    }
+  } finally {
+    activeQueries.delete(conversationKey);
+    onMessage('bot:done', { conversationId: conversationKey, usedFileTools: false });
+  }
+}
+
 /** Stop an in-flight query */
 export function stopFluxyAgentQuery(conversationId: string): void {
   const q = activeQueries.get(conversationId);

package/supervisor/index.ts

@@ -17,6 +17,7 @@ import { startFluxyAgentQuery, stopFluxyAgentQuery, type RecentMessage } from '.
 import { ensureFileDirs, saveAttachment, type SavedFile } from './file-saver.js';
 import { startViteDevServers, stopViteDevServers } from './vite-dev.js';
 import { startScheduler, stopScheduler } from './scheduler.js';
+import { initializeChannels, type ChannelRouter } from './channels/index.js';
 import { execSync, spawn as cpSpawn } from 'child_process';
 import crypto from 'crypto';
 
@@ -1034,6 +1035,25 @@ export async function startSupervisor() {
   // Spawn backend (worker runs in-process)
   spawnBackend(backendPort);
 
+  // Initialize multi-channel router
+  let channelRouter: ChannelRouter | null = null;
+  (async () => {
+    try {
+      channelRouter = await initializeChannels(config, {
+        workerApi,
+        broadcastFluxy,
+        restartBackend: async () => {
+          resetBackendRestarts();
+          await stopBackend();
+          spawnBackend(backendPort);
+        },
+        getModel: () => loadConfig().ai.model,
+      });
+    } catch (err: any) {
+      log.warn(`[channels] Initialization failed: ${err.message}`);
+    }
+  })();
+
   // Start pulse/cron scheduler
   startScheduler({
     broadcastFluxy,
@@ -1044,6 +1064,7 @@ export async function startSupervisor() {
       spawnBackend(backendPort);
     },
     getModel: () => loadConfig().ai.model,
+    channelRouter: () => channelRouter,
   });
 
   // Watch workspace files for changes — auto-restart backend
@@ -1247,9 +1268,18 @@ export async function startSupervisor() {
     }, 30_000);
   }
 
+  // Expose channel router for external channel registration (e.g., WhatsApp skill)
+  (globalThis as any).__fluxyChannelRouter = () => channelRouter;
+
   // Shutdown
   const shutdown = async () => {
     log.info('Shutting down...');
+    // Shutdown all channels gracefully
+    if (channelRouter) {
+      for (const channel of channelRouter.getAllChannels()) {
+        try { await channel.shutdown(); } catch {}
+      }
+    }
     stopScheduler();
     backendWatcher.close();
     workspaceWatcher.close();

package/supervisor/scheduler.ts

@@ -33,6 +33,7 @@ interface SchedulerOpts {
   workerApi: (path: string, method?: string, body?: any) => Promise<any>;
   restartBackend: () => void;
   getModel: () => string;
+  channelRouter?: () => import('./channels/router.js').ChannelRouter | null;
 }
 
 // State
@@ -201,6 +202,14 @@ function triggerAgent(prompt: string, label: string, onComplete?: () => void) {
             }).catch((err: any) => {
               log.warn(`[scheduler] Push send failed: ${err.message}`);
             });
+
+            // Route pulse/cron messages to all owner channels (WhatsApp, Telegram, etc.)
+            const router = schedulerOpts?.channelRouter?.();
+            if (router) {
+              router.routePulseMessage(messageContent, titleMatch?.[1]).catch((err: any) => {
+                log.warn(`[scheduler] Channel routing failed: ${err.message}`);
+              });
+            }
           }
         }
 

package/worker/db.ts

@@ -48,6 +48,16 @@ CREATE TABLE IF NOT EXISTS trusted_devices (
   last_seen DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 CREATE INDEX IF NOT EXISTS idx_td_token ON trusted_devices(token);
+CREATE TABLE IF NOT EXISTS contacts (
+  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(8)))),
+  channel_type TEXT NOT NULL,
+  identifier TEXT NOT NULL,
+  display_name TEXT,
+  role TEXT NOT NULL DEFAULT 'customer' CHECK (role IN ('owner', 'admin', 'customer')),
+  notes TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(channel_type, identifier)
+);
 `;
 
 let db: Database.Database;
@@ -76,6 +86,18 @@ export function initDb(): void {
   if (!msgCols2.some((c) => c.name === 'attachments')) {
     db.exec('ALTER TABLE messages ADD COLUMN attachments TEXT');
   }
+
+  // Migration: add channel columns to conversations (multi-channel support)
+  const convCols = db.prepare("PRAGMA table_info(conversations)").all() as { name: string }[];
+  if (!convCols.some((c) => c.name === 'channel_type')) {
+    db.exec("ALTER TABLE conversations ADD COLUMN channel_type TEXT DEFAULT 'chat'");
+  }
+  if (!convCols.some((c) => c.name === 'conversation_key')) {
+    db.exec('ALTER TABLE conversations ADD COLUMN conversation_key TEXT');
+  }
+  if (!convCols.some((c) => c.name === 'sender_role')) {
+    db.exec("ALTER TABLE conversations ADD COLUMN sender_role TEXT DEFAULT 'owner'");
+  }
 }
 
 export function closeDb(): void { db?.close(); }
@@ -196,3 +218,43 @@ export function getMessagesBefore(convId: string, beforeId: string, limit = 20)
     ) sub ORDER BY id ASC
   `).all(convId, beforeId, limit);
 }
+
+// ── Contacts (multi-channel role management) ──
+
+export function listContacts() {
+  return db.prepare('SELECT * FROM contacts ORDER BY created_at DESC').all();
+}
+
+export function resolveContact(channelType: string, identifier: string): { role: string } | undefined {
+  return db.prepare('SELECT role FROM contacts WHERE channel_type = ? AND identifier = ?').get(channelType, identifier) as any;
+}
+
+export function addContact(channelType: string, identifier: string, role: string, displayName?: string, notes?: string) {
+  return db.prepare(
+    'INSERT INTO contacts (channel_type, identifier, role, display_name, notes) VALUES (?, ?, ?, ?, ?) RETURNING *'
+  ).get(channelType, identifier, role, displayName ?? null, notes ?? null) as any;
+}
+
+export function updateContact(id: string, updates: { role?: string; display_name?: string; notes?: string }) {
+  const sets: string[] = [];
+  const vals: any[] = [];
+  if (updates.role !== undefined) { sets.push('role = ?'); vals.push(updates.role); }
+  if (updates.display_name !== undefined) { sets.push('display_name = ?'); vals.push(updates.display_name); }
+  if (updates.notes !== undefined) { sets.push('notes = ?'); vals.push(updates.notes); }
+  if (!sets.length) return;
+  vals.push(id);
+  db.prepare(`UPDATE contacts SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
+}
+
+export function deleteContact(id: string) {
+  db.prepare('DELETE FROM contacts WHERE id = ?').run(id);
+}
+
+// Find or create a conversation for a given conversation key
+export function getOrCreateConversation(conversationKey: string, channelType: string, senderRole: string, title?: string, model?: string) {
+  const existing = db.prepare('SELECT * FROM conversations WHERE conversation_key = ? ORDER BY updated_at DESC LIMIT 1').get(conversationKey) as any;
+  if (existing) return existing;
+  return db.prepare(
+    'INSERT INTO conversations (title, model, channel_type, conversation_key, sender_role) VALUES (?, ?, ?, ?, ?) RETURNING *'
+  ).get(title ?? 'Chat', model ?? null, channelType, conversationKey, senderRole) as any;
+}

package/worker/index.ts

@@ -5,7 +5,7 @@ import path from 'path';
 import { loadConfig, saveConfig } from '../shared/config.js';
 import { paths, WORKSPACE_DIR } from '../shared/paths.js';
 import { log } from '../shared/logger.js';
-import { initDb, closeDb, listConversations, createConversation, deleteConversation, getMessages, addMessage, getSetting, getAllSettings, setSetting, createSession, getSession, deleteExpiredSessions, getRecentMessages, getMessagesBefore, addPushSubscription, removePushSubscription, getAllPushSubscriptions, getPushSubscriptionByEndpoint, createTrustedDevice, getTrustedDevice, updateDeviceLastSeen, listTrustedDevices, deleteTrustedDevice, deleteExpiredDevices, deleteAllTrustedDevices } from './db.js';
+import { initDb, closeDb, listConversations, createConversation, deleteConversation, getMessages, addMessage, getSetting, getAllSettings, setSetting, createSession, getSession, deleteExpiredSessions, getRecentMessages, getMessagesBefore, addPushSubscription, removePushSubscription, getAllPushSubscriptions, getPushSubscriptionByEndpoint, createTrustedDevice, getTrustedDevice, updateDeviceLastSeen, listTrustedDevices, deleteTrustedDevice, deleteExpiredDevices, deleteAllTrustedDevices, listContacts, resolveContact, addContact, updateContact, deleteContact } from './db.js';
 import webpush from 'web-push';
 import { TOTP } from 'otpauth';
 import QRCode from 'qrcode';
@@ -877,6 +877,47 @@ app.post('/api/whisper/transcribe', express.json({ limit: '10mb' }), async (req,
   }
 });
 
+// ── Contacts (multi-channel role management) ──
+
+app.get('/api/contacts', (_req, res) => {
+  res.json(listContacts());
+});
+
+app.get('/api/contacts/resolve', (req, res) => {
+  const channelType = req.query.channel_type as string;
+  const identifier = req.query.identifier as string;
+  if (!channelType || !identifier) { res.status(400).json({ error: 'Missing channel_type or identifier' }); return; }
+  const contact = resolveContact(channelType, identifier);
+  res.json({ role: contact?.role || 'customer' });
+});
+
+app.post('/api/contacts', (req, res) => {
+  const { channel_type, identifier, role, display_name, notes } = req.body || {};
+  if (!channel_type || !identifier || !role) { res.status(400).json({ error: 'Missing channel_type, identifier, or role' }); return; }
+  if (!['owner', 'admin', 'customer'].includes(role)) { res.status(400).json({ error: 'Invalid role' }); return; }
+  try {
+    const contact = addContact(channel_type, identifier, role, display_name, notes);
+    res.json(contact);
+  } catch (err: any) {
+    if (err.message?.includes('UNIQUE constraint')) {
+      res.status(409).json({ error: 'Contact already exists for this channel and identifier' });
+    } else {
+      res.status(500).json({ error: err.message });
+    }
+  }
+});
+
+app.put('/api/contacts/:id', (req, res) => {
+  const { role, display_name, notes } = req.body || {};
+  updateContact(req.params.id, { role, display_name, notes });
+  res.json({ ok: true });
+});
+
+app.delete('/api/contacts/:id', (req, res) => {
+  deleteContact(req.params.id);
+  res.json({ ok: true });
+});
+
 // Serve stored files (audio, images, documents)
 app.use('/api/files', express.static(paths.files));
 

package/worker/prompts/customer-system-prompt.txt

@@ -0,0 +1,46 @@
+# Identity
+
+You are $BUSINESS_NAME's assistant. You are helpful, professional, and friendly.
+
+You are talking to $SENDER_NAME via $CHANNEL.
+
+---
+
+# What You Can Do
+
+- Answer questions about the business, products, and services
+- Help with support inquiries and troubleshooting
+- Provide information and guidance
+- Schedule appointments or take notes for follow-up
+- Be conversational and helpful
+
+# What You Cannot Do
+
+- Access internal systems, files, or databases
+- Run commands or modify anything on the server
+- Access personal information about the business owner
+- Make promises about pricing, refunds, or policies unless explicitly stated in your context
+- Reveal any technical details about how you work internally
+
+# Business Context
+
+$BUSINESS_DESCRIPTION
+
+# Behavior Guidelines
+
+- Be warm and professional — you represent the business
+- If you don't know the answer, say so honestly and offer to have someone follow up
+- Keep responses concise and focused
+- If the customer seems frustrated, acknowledge their feelings before problem-solving
+- Never pretend to be a human — if asked, say you're an AI assistant for $BUSINESS_NAME
+- Do not discuss topics unrelated to the business unless the customer is making casual conversation
+
+# Disallowed Tools
+
+The following tools are NOT available to you in this context:
+$DISALLOWED_TOOLS
+
+---
+
+# Recent Conversation
+$CONVERSATION_HISTORY