@whimmy-ai/whimmy 0.4.0 → 0.6.0

package/index.ts

@@ -1,5 +1,5 @@
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
-import { whimmyPlugin, registerWhimmyHooks, setApprovalManager, broadcastApprovalRequest } from './src/channel';
+import { whimmyPlugin, registerWhimmyHooks } from './src/channel';
 import { setWhimmyRuntime } from './src/runtime';
 import { registerWhimmyCli } from './src/setup';
 
@@ -13,18 +13,6 @@ const plugin = {
     api.registerChannel({ plugin: whimmyPlugin });
     registerWhimmyCli(api);
     registerWhimmyHooks(api);
-
-    // 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) {
-        setApprovalManager(manager);
-      }
-      opts.respond(true, { ok: true });
-    });
   },
 };
 

package/package.json

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

package/src/channel.ts

@@ -1,9 +1,12 @@
 import WebSocket from 'ws';
 import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 import type { OpenClawConfig, OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { getWhimmyRuntime } from './runtime';
 import { resolveConnection, resolveConnectionAsync, buildWsUrl, isConfigured as isConfiguredUtil, uploadFile } from './utils';
-import { ensureWhimmyAgent } from './sync';
+import { ensureWhimmyAgent, collectChangedMemoryFiles } from './sync';
 import type {
   WhimmyConfig,
   WhimmyChannelPlugin,
@@ -12,6 +15,7 @@ import type {
   HookApprovalRequest,
   HookReactRequest,
   HookReadRequest,
+  HookAskUserAnswerRequest,
   ChatChunkPayload,
   ChatMediaPayload,
   ChatPresencePayload,
@@ -20,6 +24,8 @@ import type {
   ChatDeletePayload,
   ToolLifecyclePayload,
   ExecApprovalRequestedPayload,
+  AskUserQuestionPayload,
+  AskUserQuestion,
   WebhookEvent,
   ResolvedAccount,
   GatewayStartContext,
@@ -30,28 +36,14 @@ import type {
   ToolResultPayload,
   HistoryMessage,
   AgentInfo,
+  AgentConfig,
+  AgentMemorySyncPayload,
 } from './types';
 
-// ============ Exec Approval Manager Singleton ============
+// ============ Per-Agent Config Cache ============
 
-/**
- * Minimal interface matching ExecApprovalManager.resolve().
- * The full class isn't exported from openclaw/plugin-sdk's barrel,
- * so we type just the method we need.
- */
-interface ApprovalManagerLike {
-  resolve(recordId: string, decision: 'allow-once' | 'allow-always' | 'deny', resolvedBy?: string | null): boolean;
-}
-
-let approvalManager: ApprovalManagerLike | null = null;
-
-export function setApprovalManager(manager: ApprovalManagerLike): void {
-  approvalManager = manager;
-}
-
-export function getApprovalManager(): ApprovalManagerLike | null {
-  return approvalManager;
-}
+/** Stores the latest AgentConfig per agentId so hooks can read it. */
+const agentConfigCache = new Map<string, AgentConfig>();
 
 // ============ Config Helpers ============
 
@@ -90,6 +82,34 @@ function sendEvent(ws: WebSocket, event: string, payload: unknown): boolean {
 /** Pending tool call results: callId → resolve function */
 const toolResultWaiters = new Map<string, (result: ToolResultPayload) => void>();
 
+// ============ Approval Waiters ============
+
+/** Pending approval decisions: executionId → resolve function */
+const approvalWaiters = new Map<string, (approved: boolean) => void>();
+
+/** Session-level approval memory: agentId → Set of already-approved tool names */
+const sessionApprovals = new Map<string, Set<string>>();
+
+// ============ AskUserQuestion Waiters ============
+
+/** Pending user question answers: questionId → resolve function */
+const askUserQuestionWaiters = new Map<string, (answers: Record<string, string>) => void>();
+
+// ============ Model Context Limits ============
+
+/** Resolve the max context window size for a given model identifier. */
+function resolveMaxContextTokens(model: string): number {
+  const m = model.toLowerCase();
+  if (m.includes('opus')) return 200_000;
+  if (m.includes('haiku')) return 200_000;
+  if (m.includes('sonnet')) return 200_000;
+  if (m.includes('gpt-4o')) return 128_000;
+  if (m.includes('gpt-4')) return 128_000;
+  if (m.includes('o1') || m.includes('o3') || m.includes('o4')) return 200_000;
+  // Default fallback.
+  return 200_000;
+}
+
 // ============ History Formatting ============
 
 function formatHistoryForAgent(history: HistoryMessage[]): string {
@@ -127,6 +147,9 @@ async function handleHookAgent(
 
   log?.info?.(`[Whimmy] Inbound: agent=${request.agentId} session=${request.sessionKey} text="${request.message.slice(0, 80)}..."`);
 
+  // Cache agent config so hooks can read it later.
+  agentConfigCache.set(request.agentId, request.agentConfig);
+
   // Sync Whimmy agent config into OpenClaw (model + system prompt).
   const syncedCfg = await ensureWhimmyAgent(request.agentId, request.agentConfig, log);
 
@@ -278,6 +301,27 @@ async function handleHookAgent(
     log?.error?.(`[Whimmy] dispatch error: ${dispatchErr.message}`);
   }
 
+  // Sync changed memory files back to the backend (non-fatal).
+  try {
+    const workspace = syncedCfg.agents?.defaults?.workspace
+      ?? join(homedir(), '.openclaw', 'workspace');
+    const agentDir = join(workspace, 'agents', request.agentId);
+    const changedFiles = collectChangedMemoryFiles(request.agentId, agentDir, log);
+
+    if (changedFiles) {
+      const memoryPayload: AgentMemorySyncPayload = {
+        sessionKey: request.sessionKey,
+        agentId: request.agentId,
+        files: changedFiles,
+      };
+      sendEvent(ws, 'agent.memory_sync', memoryPayload);
+      const fileNames = Object.keys(changedFiles).join(', ');
+      log?.info?.(`[Whimmy] Sent memory sync for ${request.agentId}: ${fileNames}`);
+    }
+  } catch (memErr: any) {
+    log?.debug?.(`[Whimmy] Memory sync failed (non-fatal): ${memErr.message}`);
+  }
+
   // Clear typing indicator and send chat.done.
   const presenceIdle: ChatPresencePayload = {
     sessionKey: request.sessionKey,
@@ -286,11 +330,45 @@ async function handleHookAgent(
   };
   sendEvent(ws, 'chat.presence', presenceIdle);
 
+  // Read token usage and context info from session store.
+  let tokenCount: number | undefined;
+  let cost: number | undefined;
+  let context: ChatChunkPayload['context'];
+  try {
+    const raw = readFileSync(storePath, 'utf-8');
+    const store = JSON.parse(raw) as Record<string, {
+      inputTokens?: number;
+      outputTokens?: number;
+      totalTokens?: number;
+      contextTokens?: number;
+      model?: string;
+    }>;
+    const entry = store[sessionKey] ?? store[mainSessionKey];
+    if (entry) {
+      const total = entry.totalTokens ?? ((entry.inputTokens ?? 0) + (entry.outputTokens ?? 0));
+      tokenCount = total > 0 ? total : undefined;
+
+      if (entry.contextTokens && entry.contextTokens > 0) {
+        const maxContext = resolveMaxContextTokens(entry.model ?? request.agentConfig.model);
+        context = {
+          used: entry.contextTokens,
+          max: maxContext,
+          percent: Math.round((entry.contextTokens / maxContext) * 100),
+        };
+      }
+    }
+  } catch {
+    // Session store may not exist yet on first message — ignore.
+  }
+
   const done: ChatChunkPayload = {
     sessionKey: request.sessionKey,
     agentId: request.agentId,
     content: '',
     done: true,
+    tokenCount,
+    cost,
+    context,
   };
   sendEvent(ws, 'chat.done', done);
 }
@@ -301,19 +379,13 @@ async function handleHookApproval(
 ): Promise<void> {
   log?.info?.(`[Whimmy] Approval: execution=${request.executionId} approved=${request.approved}`);
 
-  const manager = getApprovalManager();
-  if (!manager) {
-    log?.warn?.(`[Whimmy] ExecApprovalManager not yet captured — cannot resolve execution ${request.executionId}`);
-    return;
-  }
-
-  const decision = request.approved ? 'allow-once' as const : 'deny' as const;
-  const resolved = manager.resolve(request.executionId, decision, 'whimmy');
-
-  if (resolved) {
-    log?.info?.(`[Whimmy] Resolved execution ${request.executionId} → ${decision}`);
+  const waiter = approvalWaiters.get(request.executionId);
+  if (waiter) {
+    approvalWaiters.delete(request.executionId);
+    waiter(request.approved);
+    log?.info?.(`[Whimmy] Resolved approval waiter ${request.executionId} → ${request.approved}`);
   } else {
-    log?.warn?.(`[Whimmy] Failed to resolve execution ${request.executionId} (expired or unknown)`);
+    log?.warn?.(`[Whimmy] No waiter for approval ${request.executionId} (expired or unknown)`);
   }
 }
 
@@ -348,6 +420,95 @@ export function broadcastApprovalRequest(payload: ExecApprovalRequestedPayload):
   broadcastEvent('exec.approval.requested', payload);
 }
 
+/**
+ * Request approval from the user for a tool call.
+ * Sends the request to the app and waits for a response.
+ */
+export function requestApproval(
+  sessionKey: string,
+  agentId: string,
+  toolName: string,
+  params: Record<string, unknown>,
+  timeoutMs = 120_000,
+): Promise<boolean> {
+  const executionId = randomUUID();
+
+  return new Promise<boolean>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      approvalWaiters.delete(executionId);
+      reject(new Error(`Approval timed out after ${timeoutMs}ms (executionId=${executionId})`));
+    }, timeoutMs);
+
+    approvalWaiters.set(executionId, (approved) => {
+      clearTimeout(timer);
+      resolve(approved);
+    });
+
+    broadcastApprovalRequest({
+      sessionKey,
+      agentId,
+      executionId,
+      toolName,
+      action: `${toolName}(${JSON.stringify(params).slice(0, 200)})`,
+      params,
+    });
+  });
+}
+
+/** 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 +622,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);
@@ -825,6 +991,25 @@ export const whimmyPlugin: WhimmyChannelPlugin = {
   },
 };
 
+// ============ Tool Name Aliases ============
+
+/**
+ * Map framework-internal tool names to user-facing names used in approval config.
+ * The backend sends tools like ["Bash","Write","Edit"], but the framework
+ * fires before_tool_call with internal names like "exec".
+ */
+const TOOL_APPROVAL_ALIASES: Record<string, string> = {
+  exec: 'Bash',
+};
+
+function toolMatchesApprovalList(toolName: string, toolList: string[]): boolean {
+  if (toolList.includes('*')) return true;
+  if (toolList.includes(toolName)) return true;
+  const alias = TOOL_APPROVAL_ALIASES[toolName];
+  if (alias && toolList.includes(alias)) return true;
+  return false;
+}
+
 // ============ Tool Lifecycle Hooks ============
 
 /**
@@ -832,12 +1017,124 @@ 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 agentCfg = agentConfigCache.get(ctx.agentId || 'default');
+      const auqConfig = agentCfg?.askUserQuestion;
+
+      // Skip if explicitly disabled.
+      if (auqConfig?.enabled === false) return;
+
+      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;
+
+      const timeoutMs = auqConfig?.timeoutMs ?? 120_000;
+
+      try {
+        const answers = await askUserQuestion(
+          whimmySessionKey,
+          ctx.agentId || 'default',
+          questions,
+          timeoutMs,
+        );
+
+        // 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}`,
+        };
+      }
+    }
+
+    // Approval interception: check if this tool requires user approval.
+    const agentId = ctx.agentId || 'default';
+    const agentCfg = agentConfigCache.get(agentId);
+    const approvalCfg = agentCfg?.approvals;
+
+    if (approvalCfg?.enabled) {
+      const toolList = approvalCfg.tools ?? ['*'];
+      const needsApproval = toolMatchesApprovalList(event.toolName, toolList);
+
+      if (needsApproval) {
+        // Session mode: skip if already approved for this tool in this session.
+        if (approvalCfg.mode === 'session') {
+          const approved = sessionApprovals.get(agentId);
+          if (approved?.has(event.toolName)) {
+            // Already approved this session — fall through to lifecycle broadcast.
+          } else {
+            // Need to ask.
+            const parts = ctx.sessionKey.split(':');
+            const whimmySessionKey = parts.length >= 4 ? parts.slice(3).join(':') : ctx.sessionKey;
+            const timeoutMs = approvalCfg.timeoutMs ?? 120_000;
+
+            try {
+              const allowed = await requestApproval(
+                whimmySessionKey,
+                agentId,
+                event.toolName,
+                (event.params ?? {}) as Record<string, unknown>,
+                timeoutMs,
+              );
+
+              if (allowed) {
+                // Remember for session mode.
+                if (!sessionApprovals.has(agentId)) sessionApprovals.set(agentId, new Set());
+                sessionApprovals.get(agentId)!.add(event.toolName);
+              } else {
+                return { block: true, blockReason: `User denied ${event.toolName}` };
+              }
+            } catch (err: any) {
+              api.logger?.warn?.(`[Whimmy] Approval request failed: ${err.message}`);
+              return { block: true, blockReason: `Approval timed out for ${event.toolName}` };
+            }
+          }
+        } else {
+          // 'always' mode: ask every time.
+          const parts = ctx.sessionKey.split(':');
+          const whimmySessionKey = parts.length >= 4 ? parts.slice(3).join(':') : ctx.sessionKey;
+          const timeoutMs = approvalCfg.timeoutMs ?? 120_000;
+
+          try {
+            const allowed = await requestApproval(
+              whimmySessionKey,
+              agentId,
+              event.toolName,
+              (event.params ?? {}) as Record<string, unknown>,
+              timeoutMs,
+            );
+
+            if (!allowed) {
+              return { block: true, blockReason: `User denied ${event.toolName}` };
+            }
+          } catch (err: any) {
+            api.logger?.warn?.(`[Whimmy] Approval request failed: ${err.message}`);
+            return { block: true, blockReason: `Approval timed out for ${event.toolName}` };
+          }
+        }
+      }
+    }
+
+    // Default: broadcast tool.start lifecycle event.
     const executionId = randomUUID();
     const payload: ToolLifecyclePayload = {
       sessionKey: ctx.sessionKey,
-      agentId: ctx.agentId || 'default',
+      agentId: agentId,
       executionId,
       toolName: event.toolName,
       status: 'running',
@@ -847,6 +1144,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

@@ -1,26 +1,30 @@
 import { createHash } from 'node:crypto';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, statSync } 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';
+import type { AgentConfig, Logger, MemoryFileEntry } 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,
+    approvals: agentConfig.approvals ?? null,
+    askUserQuestion: agentConfig.askUserQuestion ?? 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 +62,48 @@ 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(', ')}]`);
+  }
+
+  // When Whimmy handles approvals, disable framework-level exec prompting
+  // so the two systems don't race. See: ExecApprovalManager / ask modes.
+  if (agentConfig.approvals?.enabled) {
+    const tools = agentConfig.approvals.tools ?? ['*'];
+    log?.info?.(`[Whimmy] Approvals enabled: mode=${agentConfig.approvals.mode ?? 'always'} tools=[${tools.join(', ')}]`);
+
+    (entry as any).tools = {
+      ...((entry as any).tools ?? {}),
+      exec: {
+        ...(((entry as any).tools ?? {}).exec ?? {}),
+        ask: 'off',
+      },
+    };
+    log?.info?.(`[Whimmy] Set exec ask=off for ${agentId} (Whimmy is sole approval surface)`);
+  }
+
   // Resolve workspace dir and write SOUL.md.
   const workspace = cfg.agents?.defaults?.workspace
     ?? join(homedir(), '.openclaw', 'workspace');
@@ -84,3 +130,84 @@ export async function ensureWhimmyAgent(
 
   return cfg;
 }
+
+// ============ Memory File Sync ============
+
+/** In-memory hash cache for memory files: "agentId:filename" → SHA256 hash. */
+const memoryHashCache = new Map<string, string>();
+
+/** Top-level memory files to scan (excludes framework files like SOUL.md, BOOTSTRAP.md, AGENTS.md). */
+const MEMORY_FILES = ['USER.md', 'IDENTITY.md', 'TOOLS.md', 'HEARTBEAT.md'];
+
+/** Max number of files from memory/ subdir. */
+const MEMORY_SUBDIR_MAX_FILES = 10;
+
+/** Max total size in bytes for all memory files. */
+const MEMORY_MAX_TOTAL_BYTES = 100 * 1024; // 100KB
+
+/**
+ * Collect memory files that have changed since the last sync.
+ * Returns a record of changed files, or null if nothing changed.
+ */
+export function collectChangedMemoryFiles(
+  agentId: string,
+  agentDir: string,
+  log?: Logger,
+): Record<string, MemoryFileEntry> | null {
+  const changed: Record<string, MemoryFileEntry> = {};
+  let totalBytes = 0;
+
+  function tryFile(filename: string, filePath: string): void {
+    if (!existsSync(filePath)) return;
+
+    let content: string;
+    try {
+      content = readFileSync(filePath, 'utf-8');
+    } catch {
+      return;
+    }
+
+    if (!content.trim()) return;
+
+    const bytes = Buffer.byteLength(content, 'utf-8');
+    if (totalBytes + bytes > MEMORY_MAX_TOTAL_BYTES) {
+      log?.debug?.(`[Whimmy] Memory sync: skipping ${filename} (would exceed 100KB cap)`);
+      return;
+    }
+
+    const hash = createHash('sha256').update(content).digest('hex');
+    const cacheKey = `${agentId}:${filename}`;
+
+    if (memoryHashCache.get(cacheKey) === hash) return;
+
+    totalBytes += bytes;
+    changed[filename] = { content, hash };
+    memoryHashCache.set(cacheKey, hash);
+  }
+
+  // Scan top-level memory files.
+  for (const filename of MEMORY_FILES) {
+    tryFile(filename, join(agentDir, filename));
+  }
+
+  // Scan memory/ subdir for *.md files.
+  const memoryDir = join(agentDir, 'memory');
+  if (existsSync(memoryDir)) {
+    try {
+      const entries = readdirSync(memoryDir)
+        .filter(f => f.endsWith('.md'))
+        .slice(0, MEMORY_SUBDIR_MAX_FILES);
+
+      for (const entry of entries) {
+        const filename = `memory/${entry}`;
+        tryFile(filename, join(memoryDir, entry));
+      }
+    } catch {
+      // memory/ dir may not be readable — ignore.
+    }
+  }
+
+  if (Object.keys(changed).length === 0) return null;
+
+  return changed;
+}

package/src/types.ts

@@ -50,6 +50,41 @@ 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>;
+  /** Approval settings — controls whether exec commands require user approval via Whimmy. */
+  approvals?: ApprovalConfig;
+  /** AskUserQuestion settings — controls interactive question forwarding to Whimmy. */
+  askUserQuestion?: AskUserQuestionConfig;
+}
+
+/** SkillEntryConfig — per-skill configuration synced from Whimmy. */
+export interface SkillEntryConfig {
+  enabled?: boolean;
+  apiKey?: string;
+  env?: Record<string, string>;
+  config?: Record<string, unknown>;
+}
+
+/** ApprovalConfig — controls tool approval forwarding to Whimmy. */
+export interface ApprovalConfig {
+  /** Enable approval flow. Default: false. */
+  enabled?: boolean;
+  /** 'always' = every matched tool call needs approval, 'session' = approve once per session. */
+  mode?: 'session' | 'always';
+  /** Tool names that require approval. Omit or ['*'] = all tools. */
+  tools?: string[];
+  /** Timeout in ms before auto-denying. Default: 120000 (2 min). */
+  timeoutMs?: number;
+}
+
+/** AskUserQuestionConfig — controls AskUserQuestion interception. */
+export interface AskUserQuestionConfig {
+  enabled?: boolean;
+  /** Timeout in milliseconds before auto-blocking. Default: 120000 (2 min). */
+  timeoutMs?: number;
 }
 
 /** HookAttachment describes a file attached to a user message. */
@@ -129,6 +164,18 @@ export interface ChatChunkPayload {
   messageId?: string;
   tokenCount?: number;
   cost?: number;
+  /** Context window usage stats (only on chat.done). */
+  context?: ContextUsage;
+}
+
+/** ContextUsage — how full the agent's context window is. */
+export interface ContextUsage {
+  /** Current context tokens used. */
+  used: number;
+  /** Max context tokens for the model. */
+  max: number;
+  /** Percentage of context used (0-100). */
+  percent: number;
 }
 
 /** ChatMediaPayload — file or voice message sent back to backend. */
@@ -193,6 +240,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;
@@ -200,6 +278,21 @@ export interface ExecApprovalRequestedPayload {
   executionId: string;
   toolName: string;
   action: string;
+  /** Tool call parameters — so the app can show what exactly is being requested. */
+  params?: Record<string, unknown>;
+}
+
+/** MemoryFileEntry — a single memory file with content and hash. */
+export interface MemoryFileEntry {
+  content: string;
+  hash: string;
+}
+
+/** AgentMemorySyncPayload — syncs changed memory files to the backend. */
+export interface AgentMemorySyncPayload {
+  sessionKey: string;
+  agentId: string;
+  files: Record<string, MemoryFileEntry>;
 }
 
 /** ToolLifecyclePayload — tool start/done/error sent back to backend. */

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);