@whimmy-ai/whimmy 0.4.0 → 0.5.0

package/package.json

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

package/src/channel.ts

@@ -12,6 +12,7 @@ import type {
   HookApprovalRequest,
   HookReactRequest,
   HookReadRequest,
+  HookAskUserAnswerRequest,
   ChatChunkPayload,
   ChatMediaPayload,
   ChatPresencePayload,
@@ -20,6 +21,8 @@ import type {
   ChatDeletePayload,
   ToolLifecyclePayload,
   ExecApprovalRequestedPayload,
+  AskUserQuestionPayload,
+  AskUserQuestion,
   WebhookEvent,
   ResolvedAccount,
   GatewayStartContext,
@@ -90,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 {
@@ -348,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) {
@@ -461,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);
@@ -832,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,
@@ -847,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

@@ -6,21 +6,23 @@ import type { OpenClawConfig } from 'openclaw/plugin-sdk';
 import { getWhimmyRuntime } from './runtime';
 import type { AgentConfig, Logger } from './types';
 
-/** In-memory cache: agentId → hash of { model, systemPrompt }. */
+/** 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 and system prompt.  Uses an in-memory hash cache to skip redundant
- * disk writes when nothing changed.
+ * 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,
@@ -58,6 +60,32 @@ export async function ensureWhimmyAgent(
   // 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');

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

@@ -65,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',
@@ -143,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)}`;
 }
 
 /**
@@ -188,7 +188,7 @@ export async function uploadFile(
   conn: ConnectionInfo,
 ): Promise<{ url: string; fileName: string; mimeType: string }> {
   const protocol = conn.tls ? 'https' : 'http';
-  const url = `${protocol}://${conn.host}/files/upload`;
+  const url = `${protocol}://${conn.host}/api/v1/files/upload`;
 
   const fileBuffer = readFileSync(filePath);
   const fileName = basename(filePath);