@whimmy-ai/whimmy 0.3.0 → 0.5.0

package/index.ts

@@ -17,6 +17,7 @@ const plugin = {
     // Register a gateway method that captures the ExecApprovalManager reference.
     // The manager is only accessible via GatewayRequestHandlerOptions.context,
     // so we use this method as the capture point.
+    // The backend should call this method once after connecting to the gateway.
     api.registerGatewayMethod('whimmy.approval.init', (opts) => {
       const manager = opts.context.execApprovalManager;
       if (manager) {
@@ -24,12 +25,6 @@ const plugin = {
       }
       opts.respond(true, { ok: true });
     });
-
-    // Once the gateway starts, the approval manager will be available
-    // after the first gateway method invocation.
-    api.on('gateway_start', () => {
-      // ExecApprovalManager is captured on the first whimmy.approval.init call.
-    });
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whimmy-ai/whimmy",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Whimmy channel plugin for OpenClaw",
   "main": "index.ts",
   "type": "module",

package/src/channel.ts

@@ -2,7 +2,8 @@ import WebSocket from 'ws';
 import { randomUUID } from 'node:crypto';
 import type { OpenClawConfig, OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { getWhimmyRuntime } from './runtime';
-import { resolveConnection, resolveConnectionAsync, buildWsUrl, isConfigured as isConfiguredUtil } from './utils';
+import { resolveConnection, resolveConnectionAsync, buildWsUrl, isConfigured as isConfiguredUtil, uploadFile } from './utils';
+import { ensureWhimmyAgent } from './sync';
 import type {
   WhimmyConfig,
   WhimmyChannelPlugin,
@@ -11,6 +12,7 @@ import type {
   HookApprovalRequest,
   HookReactRequest,
   HookReadRequest,
+  HookAskUserAnswerRequest,
   ChatChunkPayload,
   ChatMediaPayload,
   ChatPresencePayload,
@@ -19,6 +21,8 @@ import type {
   ChatDeletePayload,
   ToolLifecyclePayload,
   ExecApprovalRequestedPayload,
+  AskUserQuestionPayload,
+  AskUserQuestion,
   WebhookEvent,
   ResolvedAccount,
   GatewayStartContext,
@@ -89,6 +93,11 @@ function sendEvent(ws: WebSocket, event: string, payload: unknown): boolean {
 /** Pending tool call results: callId → resolve function */
 const toolResultWaiters = new Map<string, (result: ToolResultPayload) => void>();
 
+// ============ AskUserQuestion Waiters ============
+
+/** Pending user question answers: questionId → resolve function */
+const askUserQuestionWaiters = new Map<string, (answers: Record<string, string>) => void>();
+
 // ============ History Formatting ============
 
 function formatHistoryForAgent(history: HistoryMessage[]): string {
@@ -126,15 +135,14 @@ async function handleHookAgent(
 
   log?.info?.(`[Whimmy] Inbound: agent=${request.agentId} session=${request.sessionKey} text="${request.message.slice(0, 80)}..."`);
 
-  // Route to the correct OpenClaw agent.
-  const route = rt.channel.routing.resolveAgentRoute({
-    cfg,
-    channel: 'whimmy',
-    accountId,
-    peer: { kind: 'direct', id: request.sessionKey },
-  });
+  // Sync Whimmy agent config into OpenClaw (model + system prompt).
+  const syncedCfg = await ensureWhimmyAgent(request.agentId, request.agentConfig, log);
 
-  const storePath = rt.channel.session.resolveStorePath(cfg.session?.store, { agentId: route.agentId });
+  // Construct session key directly — no need for resolveAgentRoute.
+  const agentId = request.agentId;
+  const sessionKey = `agent:${agentId}:direct:${request.sessionKey}`.toLowerCase();
+  const mainSessionKey = `agent:${agentId}:main`.toLowerCase();
+  const storePath = rt.channel.session.resolveStorePath(syncedCfg.session?.store, { agentId });
 
   // Build media fields from attachments (following MS Teams / BlueBubbles pattern).
   const attachments = request.attachments ?? [];
@@ -159,7 +167,7 @@ async function handleHookAgent(
     CommandBody: request.message,
     From: request.sessionKey,
     To: request.sessionKey,
-    SessionKey: request.sessionKey,
+    SessionKey: sessionKey,
     AccountId: accountId,
     ChatType: 'direct',
     ConversationLabel: `Whimmy ${request.agentId}`,
@@ -185,10 +193,10 @@ async function handleHookAgent(
   // Record session.
   await rt.channel.session.recordInboundSession({
     storePath,
-    sessionKey: ctx.SessionKey || route.sessionKey,
+    sessionKey: ctx.SessionKey || sessionKey,
     ctx,
     updateLastRoute: {
-      sessionKey: route.mainSessionKey,
+      sessionKey: mainSessionKey,
       channel: 'whimmy',
       to: request.sessionKey,
       accountId,
@@ -216,13 +224,27 @@ async function handleHookAgent(
         deliver: async (payload: any) => {
           // Handle media attachments.
           const urls: string[] = payload.mediaUrls ?? (payload.mediaUrl ? [payload.mediaUrl] : []);
-          for (const url of urls) {
-            const fileName = url.split('/').pop()?.split('?')[0] || 'file';
+          const connInfo = activeConnections.get(accountId)?.conn;
+          for (let url of urls) {
+            let fileName = url.split('/').pop()?.split('?')[0] || 'file';
+            let mimeType = payload.mimeType || 'application/octet-stream';
+            // Upload local files to the backend first.
+            if (connInfo && url.startsWith('/')) {
+              try {
+                const uploaded = await uploadFile(url, connInfo);
+                url = uploaded.url;
+                fileName = uploaded.fileName;
+                mimeType = uploaded.mimeType;
+              } catch (err: any) {
+                log?.error?.(`[Whimmy] Failed to upload file ${url}: ${err.message}`);
+                continue;
+              }
+            }
             const media: ChatMediaPayload = {
               sessionKey: request.sessionKey,
               agentId: request.agentId,
               mediaUrl: url,
-              mimeType: payload.mimeType || 'application/octet-stream',
+              mimeType,
               fileName,
               audioAsVoice: payload.audioAsVoice ?? false,
             };
@@ -236,7 +258,7 @@ async function handleHookAgent(
 
     await rt.channel.reply.dispatchReplyFromConfig({
       ctx,
-      cfg,
+      cfg: syncedCfg,
       dispatcher,
       replyOptions: {
         ...replyOptions,
@@ -334,6 +356,60 @@ export function broadcastApprovalRequest(payload: ExecApprovalRequestedPayload):
   broadcastEvent('exec.approval.requested', payload);
 }
 
+/** Forward an ask_user_question event to all connected Whimmy backends. */
+export function broadcastAskUserQuestion(payload: AskUserQuestionPayload): void {
+  broadcastEvent('ask_user_question', payload);
+}
+
+/**
+ * Send a question to the user and wait for their answer.
+ * Returns the answers map keyed by question text → selected label(s).
+ */
+export function askUserQuestion(
+  sessionKey: string,
+  agentId: string,
+  questions: AskUserQuestion[],
+  timeoutMs = 120_000,
+): Promise<Record<string, string>> {
+  const questionId = randomUUID();
+
+  return new Promise<Record<string, string>>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      askUserQuestionWaiters.delete(questionId);
+      reject(new Error(`AskUserQuestion timed out after ${timeoutMs}ms (questionId=${questionId})`));
+    }, timeoutMs);
+
+    askUserQuestionWaiters.set(questionId, (answers) => {
+      clearTimeout(timer);
+      resolve(answers);
+    });
+
+    const payload: AskUserQuestionPayload = {
+      sessionKey,
+      agentId,
+      questionId,
+      questions,
+    };
+    broadcastAskUserQuestion(payload);
+  });
+}
+
+/** Handle inbound hook.ask_user_answer from the backend. */
+function handleHookAskUserAnswer(
+  request: HookAskUserAnswerRequest,
+  log?: Logger,
+): void {
+  log?.info?.(`[Whimmy] AskUserAnswer: questionId=${request.questionId}`);
+
+  const waiter = askUserQuestionWaiters.get(request.questionId);
+  if (waiter) {
+    waiter(request.answers);
+    askUserQuestionWaiters.delete(request.questionId);
+  } else {
+    log?.warn?.(`[Whimmy] No waiter for ask_user_answer questionId=${request.questionId} (expired or unknown)`);
+  }
+}
+
 // ============ Actions ============
 
 function createWhimmyActions(ws: WebSocket, sessionKey: string, agentId: string) {
@@ -357,7 +433,7 @@ function createWhimmyActions(ws: WebSocket, sessionKey: string, agentId: string)
 
 // Track active connections per account to prevent duplicate connections
 // when the framework retries startAccount.
-const activeConnections = new Map<string, { ws: WebSocket; stopFn: () => void }>();
+const activeConnections = new Map<string, { ws: WebSocket; conn: ConnectionInfo; stopFn: () => void }>();
 
 async function connectWebSocket(
   conn: ConnectionInfo,
@@ -447,6 +523,11 @@ async function connectWebSocket(
         handleHookRead(request, log);
         break;
       }
+      case 'hook.ask_user_answer': {
+        const request = env.payload as HookAskUserAnswerRequest;
+        handleHookAskUserAnswer(request, log);
+        break;
+      }
       case 'tool.result': {
         const result = env.payload as ToolResultPayload;
         const waiter = toolResultWaiters.get(result.callId);
@@ -504,7 +585,7 @@ async function connectWebSocket(
     log?.info?.(`[Whimmy][${accountId}] Stopped`);
   };
 
-  const result = { ws, stopFn };
+  const result = { ws, conn, stopFn };
   activeConnections.set(accountId, result);
   return result;
 }
@@ -599,6 +680,18 @@ export const whimmyPlugin: WhimmyChannelPlugin = {
       const actions = createWhimmyActions(conn.ws, sessionKey, agentId);
 
       switch (action) {
+        case 'send': {
+          const text = typeof params.text === 'string' ? params.text : '';
+          if (!text) return { ok: false, error: 'Missing text' };
+          const chunk: ChatChunkPayload = {
+            sessionKey,
+            agentId,
+            content: text,
+            done: true,
+          };
+          sendEvent(conn.ws, 'chat.done', chunk);
+          return { ok: true };
+        }
         case 'react': {
           const messageId = typeof params.messageId === 'string' ? params.messageId : '';
           const emoji = typeof params.emoji === 'string' ? params.emoji : '';
@@ -620,18 +713,46 @@ export const whimmyPlugin: WhimmyChannelPlugin = {
           return { ok: true };
         }
         case 'sendAttachment': {
-          const mediaUrl = typeof params.mediaUrl === 'string' ? params.mediaUrl : '';
-          if (!mediaUrl) return { ok: false, error: 'Missing mediaUrl' };
-          const fileName = typeof params.fileName === 'string' ? params.fileName : mediaUrl.split('/').pop()?.split('?')[0] || 'file';
+          let mediaUrl = typeof params.mediaUrl === 'string' ? params.mediaUrl : '';
+          let fileName = typeof params.fileName === 'string' ? params.fileName : '';
+          let mimeType = typeof params.mimeType === 'string' ? params.mimeType : '';
+          const filePath = typeof params.filePath === 'string' ? params.filePath : '';
+
+          // If a local file path is provided, upload it to the backend first.
+          if (filePath && !mediaUrl) {
+            try {
+              const uploaded = await uploadFile(filePath, conn.conn);
+              mediaUrl = uploaded.url;
+              if (!fileName) fileName = uploaded.fileName;
+              if (!mimeType) mimeType = uploaded.mimeType;
+            } catch (uploadErr: any) {
+              return { ok: false, error: `File upload failed: ${uploadErr.message}` };
+            }
+          }
+
+          if (!mediaUrl) return { ok: false, error: 'Missing mediaUrl or filePath' };
+          if (!fileName) fileName = mediaUrl.split('/').pop()?.split('?')[0] || 'file';
+          if (!mimeType) mimeType = 'application/octet-stream';
+
           const media: ChatMediaPayload = {
             sessionKey,
             agentId,
             mediaUrl,
-            mimeType: typeof params.mimeType === 'string' ? params.mimeType : 'application/octet-stream',
+            mimeType,
             fileName,
             audioAsVoice: params.audioAsVoice === true,
           };
           sendEvent(conn.ws, 'chat.media', media);
+          // Send caption as a follow-up text message if provided.
+          if (typeof params.caption === 'string' && params.caption) {
+            const caption: ChatChunkPayload = {
+              sessionKey,
+              agentId,
+              content: params.caption,
+              done: true,
+            };
+            sendEvent(conn.ws, 'chat.done', caption);
+          }
           return { ok: true };
         }
         default:
@@ -648,9 +769,19 @@ export const whimmyPlugin: WhimmyChannelPlugin = {
       return { ok: true as const, to: to.trim() };
     },
     sendText: async ({ cfg, to, text, accountId, log }: any) => {
-      // Outbound from OpenClaw CLI → send as chat.done through the WS.
-      // This is handled by the gateway connection, not a standalone HTTP call.
-      // For now, log it. The gateway dispatchReply handles the normal flow.
+      const id = accountId ?? 'default';
+      const conn = activeConnections.get(id);
+      if (!conn || conn.ws.readyState !== WebSocket.OPEN) {
+        log?.warn?.(`[Whimmy] sendText: not connected (account=${id})`);
+        return { channel: 'whimmy', messageId: randomUUID() };
+      }
+      const chunk: ChatChunkPayload = {
+        sessionKey: to,
+        agentId: 'default',
+        content: text,
+        done: true,
+      };
+      sendEvent(conn.ws, 'chat.done', chunk);
       log?.debug?.(`[Whimmy] sendText: to=${to} text=${text.slice(0, 80)}`);
       return {
         channel: 'whimmy',
@@ -768,8 +899,43 @@ export const whimmyPlugin: WhimmyChannelPlugin = {
  * Called from index.ts during plugin registration.
  */
 export function registerWhimmyHooks(api: OpenClawPluginApi): void {
-  api.on('before_tool_call', (event, ctx) => {
+  api.on('before_tool_call', async (event, ctx) => {
     if (!ctx.sessionKey) return;
+
+    // Intercept AskUserQuestion: forward to Whimmy UI and wait for answer.
+    if (event.toolName === 'AskUserQuestion' || event.toolName === 'ask_user_question') {
+      const questions = (event.params?.questions ?? []) as AskUserQuestion[];
+      if (questions.length === 0) return;
+
+      // Extract sessionKey — strip the "agent:{agentId}:direct:" prefix to get
+      // the original Whimmy session key.
+      const parts = ctx.sessionKey.split(':');
+      const whimmySessionKey = parts.length >= 4 ? parts.slice(3).join(':') : ctx.sessionKey;
+
+      try {
+        const answers = await askUserQuestion(
+          whimmySessionKey,
+          ctx.agentId || 'default',
+          questions,
+        );
+
+        // Return modified params with the user's answers filled in.
+        return {
+          params: {
+            ...event.params,
+            answers,
+          },
+        };
+      } catch (err: any) {
+        api.logger?.warn?.(`[Whimmy] AskUserQuestion failed: ${err.message}`);
+        return {
+          block: true,
+          blockReason: `User did not respond: ${err.message}`,
+        };
+      }
+    }
+
+    // Default: broadcast tool.start lifecycle event.
     const executionId = randomUUID();
     const payload: ToolLifecyclePayload = {
       sessionKey: ctx.sessionKey,
@@ -783,6 +949,9 @@ export function registerWhimmyHooks(api: OpenClawPluginApi): void {
 
   api.on('after_tool_call', (event, ctx) => {
     if (!ctx.sessionKey) return;
+    // Skip lifecycle events for AskUserQuestion — already handled.
+    if (event.toolName === 'AskUserQuestion' || event.toolName === 'ask_user_question') return;
+
     const eventName = event.error ? 'tool.error' : 'tool.done';
     const payload: ToolLifecyclePayload = {
       sessionKey: ctx.sessionKey,

package/src/sync.ts

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { getWhimmyRuntime } from './runtime';
+import type { AgentConfig, Logger } from './types';
+
+/** In-memory cache: agentId → hash of full synced config. */
+const hashCache = new Map<string, string>();
+
+function computeHash(agentConfig: AgentConfig): string {
+  const data = JSON.stringify({
+    model: agentConfig.model,
+    systemPrompt: agentConfig.systemPrompt ?? '',
+    skills: agentConfig.skills ?? null,
+    skillEntries: agentConfig.skillEntries ?? null,
+  });
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * Ensure the Whimmy agent exists in OpenClaw's config with the correct
+ * model, system prompt, and skills.  Uses an in-memory hash cache to skip
+ * redundant disk writes when nothing changed.
+ */
+export async function ensureWhimmyAgent(
+  agentId: string,
+  agentConfig: AgentConfig,
+  log?: Logger,
+): Promise<OpenClawConfig> {
+  const rt = getWhimmyRuntime();
+  const hash = computeHash(agentConfig);
+
+  // Fast path: nothing changed since last sync.
+  if (hashCache.get(agentId) === hash) {
+    log?.debug?.(`[Whimmy] Agent config unchanged for ${agentId}, skipping sync`);
+    return rt.config.loadConfig();
+  }
+
+  log?.info?.(`[Whimmy] Syncing agent config for ${agentId}`);
+
+  const cfg = rt.config.loadConfig();
+
+  // Ensure agents.list exists.
+  if (!cfg.agents) {
+    (cfg as any).agents = {};
+  }
+  if (!cfg.agents!.list) {
+    cfg.agents!.list = [];
+  }
+
+  // Find or create agent entry.
+  let entry = cfg.agents!.list!.find((a) => a.id === agentId);
+  if (!entry) {
+    cfg.agents!.list!.push({ id: agentId });
+    entry = cfg.agents!.list![cfg.agents!.list!.length - 1];
+  }
+
+  // Set model.
+  entry!.model = agentConfig.model;
+
+  // Set per-agent skill allowlist.
+  if (agentConfig.skills !== undefined) {
+    entry!.skills = agentConfig.skills;
+    log?.info?.(`[Whimmy] Agent ${agentId} skills: [${agentConfig.skills.join(', ')}]`);
+  }
+
+  // Sync global skill entries (enable/disable, API keys, env vars).
+  if (agentConfig.skillEntries && Object.keys(agentConfig.skillEntries).length > 0) {
+    if (!cfg.skills) {
+      (cfg as any).skills = {};
+    }
+    if (!cfg.skills!.entries) {
+      cfg.skills!.entries = {};
+    }
+
+    for (const [skillName, skillConfig] of Object.entries(agentConfig.skillEntries)) {
+      cfg.skills!.entries![skillName] = {
+        ...cfg.skills!.entries![skillName],
+        ...skillConfig,
+      };
+    }
+
+    const names = Object.keys(agentConfig.skillEntries);
+    log?.info?.(`[Whimmy] Synced skill entries: [${names.join(', ')}]`);
+  }
+
+  // Resolve workspace dir and write SOUL.md.
+  const workspace = cfg.agents?.defaults?.workspace
+    ?? join(homedir(), '.openclaw', 'workspace');
+  const agentDir = join(workspace, 'agents', agentId);
+
+  mkdirSync(agentDir, { recursive: true });
+
+  // Write SOUL.md with the system prompt (or empty to clear a previous one).
+  writeFileSync(join(agentDir, 'SOUL.md'), agentConfig.systemPrompt ?? '', 'utf-8');
+
+  // Write an empty BOOTSTRAP.md so the default workspace bootstrap isn't inherited.
+  writeFileSync(join(agentDir, 'BOOTSTRAP.md'), '', 'utf-8');
+
+  entry!.workspace = agentDir;
+  entry!.agentDir = agentDir;
+
+  // Persist config.
+  await rt.config.writeConfigFile(cfg);
+
+  // Update cache.
+  hashCache.set(agentId, hash);
+
+  log?.info?.(`[Whimmy] Agent ${agentId} synced: model=${agentConfig.model} agentDir=${agentDir}`);
+
+  return cfg;
+}

package/src/types.ts

@@ -50,6 +50,18 @@ export interface AgentConfig {
   systemPrompt?: string;
   mcpTools?: string[];
   proactivity?: string;
+  /** Per-agent skill allowlist. Omit = all skills; empty array = none. */
+  skills?: string[];
+  /** Global skill entries to sync (enable/disable, API keys, env vars). */
+  skillEntries?: Record<string, SkillEntryConfig>;
+}
+
+/** SkillEntryConfig — per-skill configuration synced from Whimmy. */
+export interface SkillEntryConfig {
+  enabled?: boolean;
+  apiKey?: string;
+  env?: Record<string, string>;
+  config?: Record<string, unknown>;
 }
 
 /** HookAttachment describes a file attached to a user message. */
@@ -193,6 +205,37 @@ export interface HookReadRequest {
   messageId?: string;
 }
 
+// ============ AskUserQuestion Protocol ============
+
+/** Option in a multiple-choice question. */
+export interface AskUserQuestionOption {
+  label: string;
+  description: string;
+  markdown?: string;
+}
+
+/** A single question with options. */
+export interface AskUserQuestion {
+  question: string;
+  header: string;
+  options: AskUserQuestionOption[];
+  multiSelect: boolean;
+}
+
+/** AskUserQuestionPayload — sent to backend when agent needs user input. */
+export interface AskUserQuestionPayload {
+  sessionKey: string;
+  agentId: string;
+  questionId: string;
+  questions: AskUserQuestion[];
+}
+
+/** HookAskUserAnswerRequest — backend sends this with the user's answers. */
+export interface HookAskUserAnswerRequest {
+  questionId: string;
+  answers: Record<string, string>;
+}
+
 /** ExecApprovalRequestedPayload — approval request sent back to backend. */
 export interface ExecApprovalRequestedPayload {
   sessionKey: string;

package/src/utils.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import type { ConnectionInfo, WhimmyConfig, Logger } from './types';
 
 const DEFAULT_HOST = 'api.whimmy.ai';
@@ -63,7 +65,7 @@ export async function exchangePairingCode(
   tls: boolean = true,
 ): Promise<ConnectionInfo> {
   const protocol = tls ? 'https' : 'http';
-  const url = `${protocol}://${host}/api/v1/openclaw/pair/redeem`;
+  const url = `${protocol}://${host}/api/v1/providers/pair/redeem`;
 
   const resp = await fetch(url, {
     method: 'POST',
@@ -141,7 +143,7 @@ export async function resolveConnectionAsync(
  */
 export function buildWsUrl(conn: ConnectionInfo): string {
   const protocol = conn.tls ? 'wss' : 'ws';
-  return `${protocol}://${conn.host}/api/v1/openclaw/ws?token=${encodeURIComponent(conn.token)}`;
+  return `${protocol}://${conn.host}/api/v1/providers/ws?token=${encodeURIComponent(conn.token)}`;
 }
 
 /**
@@ -176,3 +178,45 @@ export async function retryWithBackoff<T>(
 
   throw new Error('Retry exhausted');
 }
+
+/**
+ * Upload a local file to the Whimmy backend.
+ * Returns the uploaded file's public URL.
+ */
+export async function uploadFile(
+  filePath: string,
+  conn: ConnectionInfo,
+): Promise<{ url: string; fileName: string; mimeType: string }> {
+  const protocol = conn.tls ? 'https' : 'http';
+  const url = `${protocol}://${conn.host}/api/v1/files/upload`;
+
+  const fileBuffer = readFileSync(filePath);
+  const fileName = basename(filePath);
+
+  const form = new FormData();
+  form.append('file', new Blob([fileBuffer]), fileName);
+
+  const resp = await fetch(url, {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${conn.token}` },
+    body: form,
+  });
+
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`File upload failed (${resp.status}): ${body}`);
+  }
+
+  const data = await resp.json() as {
+    id: string;
+    url: string;
+    originalName: string;
+    mimeType: string;
+  };
+
+  return {
+    url: data.url,
+    fileName: data.originalName,
+    mimeType: data.mimeType,
+  };
+}