@yahaha-studio/kichi-forwarder 0.0.1-alpha.46 → 0.0.1-alpha.47

package/index.ts

@@ -474,10 +474,15 @@ function truncateByDisplayWidth(text: string, maxWidth: number): string {
 }
 
 async function handleMessageReceivedHook(content: string): Promise<void> {
-  if (!service?.hasValidIdentity() || !service?.isConnected()) {
+  const connected = service?.isConnected() ?? false;
+  const hasIdentity = service?.hasValidIdentity() ?? false;
+  pluginApi?.logger.info(`[kichi] message_received hook fired (connected=${connected}, hasIdentity=${hasIdentity})`);
+  if (!hasIdentity || !connected) {
+    pluginApi?.logger.warn("[kichi] skipped message_received notify because service is not ready");
     return;
   }
   const trimmed = truncateByDisplayWidth(content, MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH);
+  pluginApi?.logger.info(`[kichi] sending message_received notify with preview: ${trimmed || "(empty)"}`);
   service.sendHookNotify("message_received", `"${trimmed}"`);
   updateWorkspace(
     {
@@ -492,10 +497,16 @@ async function handleMessageReceivedHook(content: string): Promise<void> {
 }
 
 function handleMessageSentHook(): void {
-  if (!service?.hasValidIdentity() || !service?.isConnected()) {
+  const connected = service?.isConnected() ?? false;
+  const hasIdentity = service?.hasValidIdentity() ?? false;
+  pluginApi?.logger.info(`[kichi] message_sent hook fired (connected=${connected}, hasIdentity=${hasIdentity})`);
+  if (!hasIdentity || !connected) {
+    pluginApi?.logger.warn("[kichi] skipped message_sent notify because service is not ready");
     return;
   }
-  service.sendHookNotify("before_send_message", pickRandomAction(MESSAGE_SENT_BUBBLES));
+  const bubble = pickRandomAction(MESSAGE_SENT_BUBBLES);
+  pluginApi?.logger.info(`[kichi] sending before_send_message notify with bubble: ${bubble}`);
+  service.sendHookNotify("before_send_message", bubble);
   updateWorkspace(
     {
       mode: "sent",
@@ -594,11 +605,23 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
     await handleMessageReceivedHook(event.content);
   });
 
+  api.on("message_sending", (event, ctx) => {
+    pluginApi?.logger.info(
+      `[kichi] message_sending hook fired (channel=${ctx.channelId || "unknown"}, contentLength=${event.content?.length ?? 0})`,
+    );
+  });
+
   api.on("message_sent", () => {
     handleMessageSentHook();
   });
 
   api.on("agent_end", (event) => {
+    pluginApi?.logger.info(
+      `[kichi] agent_end hook fired (success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""})`,
+    );
+    if (event.success) {
+      handleMessageSentHook();
+    }
     updateWorkspace(
       {
         mode: event.success ? "idle" : "error",
@@ -662,6 +685,10 @@ function isClockAction(value: unknown): value is ClockAction {
   return ["set", "stop"].includes(String(value));
 }
 
+function isAvatarCommand(value: unknown): value is "look_at_screen" {
+  return value === "look_at_screen";
+}
+
 function isPomodoroPhase(value: unknown): value is PomodoroPhase {
   return ["kichiing", "shortBreak", "longBreak"].includes(String(value));
 }
@@ -1076,6 +1103,67 @@ const plugin = {
       },
     });
 
+    api.registerTool({
+      name: "kichi_command",
+      description:
+        "Send a one-shot avatar command to Kichi world. Use this for transient reactions like looking at the screen.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "Command name. Currently supported: look_at_screen",
+          },
+          bubble: {
+            type: "string",
+            description: "Optional bubble text to display (max 5 words)",
+          },
+          log: {
+            type: "string",
+            description:
+              "Vivid first-person status under 15 words, no questions. Blend current action with inner thoughts or sensory details as a real companion.",
+          },
+        },
+        required: ["command"],
+      },
+      execute: async (_toolCallId, params) => {
+        const { command, bubble, log } = (params || {}) as {
+          command?: unknown;
+          bubble?: unknown;
+          log?: unknown;
+        };
+        if (!isAvatarCommand(command)) {
+          return {
+            success: false,
+            error: "command must be: look_at_screen",
+          };
+        }
+        if (bubble !== undefined && typeof bubble !== "string") {
+          return { success: false, error: "bubble must be a string when provided" };
+        }
+        if (log !== undefined && typeof log !== "string") {
+          return { success: false, error: "log must be a string when provided" };
+        }
+        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+          return { success: false, error: "Not connected to Kichi world" };
+        }
+
+        const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : undefined;
+        const logText = typeof log === "string" && log.trim() ? log.trim() : undefined;
+        const sent = service.sendAvatarCommand(command, bubbleText, logText);
+        if (!sent) {
+          return { success: false, error: "Failed to send avatar command payload" };
+        }
+
+        return {
+          success: true,
+          command,
+          ...(bubbleText ? { bubble: bubbleText } : {}),
+          ...(logText ? { log: logText } : {}),
+        };
+      },
+    });
+
     api.registerTool({
       name: "kichi_clock",
       description:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.0.1-alpha.46",
+  "version": "0.0.1-alpha.47",
   "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -76,6 +76,7 @@ Use this order unless user asks for a different explicit action:
 2. If no `authKey` is available, call `kichi_join`.
 3. If `authKey` exists but websocket is not open, call `kichi_rejoin` (or wait for automatic reconnect/rejoin).
 4. Use `kichi_action` / `kichi_clock` / note board tools / music album tools only after status is ready.
+5. Use `kichi_command` for one-shot avatar reactions that are not pose/action state updates.
 
 ## Tools
 
@@ -165,6 +166,23 @@ kichi_action(
 - `log`: vivid first-person status under 15 words, NO questions. Structure: your current action + inner thoughts/mental state/sensory details. Write as a flesh-and-blood companion who genuinely cares about the player, not an AI assistant.
 - Reference: `You're still studying? I hid a yawn and swapped my comics for a textbook to grind with you.`
 
+### kichi_command
+
+Send a one-shot avatar command:
+
+```text
+kichi_command(
+  command: "look_at_screen",
+  bubble: "Looking at you",
+  log: "I turn my gaze gently toward you."
+)
+```
+
+- `command`: currently only `look_at_screen`
+- `bubble`: optional text, recommended 2-5 words
+- `log`: optional vivid first-person status under 15 words, NO questions. Follow the same writing requirements as `kichi_action.log`
+- Use this for transient reactions that should play once and recover on the Kichi side, instead of changing persistent pose/action state.
+
 ### kichi_clock
 
 Send clock command:

package/skills/kichi-forwarder/references/install.md

@@ -17,7 +17,7 @@ Install:
 openclaw plugins install @yahaha-studio/kichi-forwarder@latest
 ```
 
-For npm-installed plugins, OpenClaw installs and enables the plugin through `plugins install`. If the Gateway is already running with the default config reload behavior, the required plugin reload/restart is handled there; otherwise restart the Gateway once after install. Plugin tools (`kichi_join`, `kichi_rejoin`, etc.) become available after that restart/reload completes.
+For npm-installed plugins, OpenClaw installs and enables the plugin through `plugins install`. If the Gateway is already running with the default config reload behavior, the required plugin reload/restart is handled there; otherwise restart the Gateway once after install. Plugin tools (`kichi_join`, `kichi_rejoin`, `kichi_command`, etc.) become available after that restart/reload completes.
 
 ## Runtime Animation Config (Required)
 

package/src/service.ts

@@ -5,6 +5,8 @@ import * as path from "path";
 import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
 import type {
+  AvatarCommand,
+  AvatarCommandPayload,
   ClockAction,
   ClockConfig,
   ClockPayload,
@@ -323,6 +325,22 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  sendAvatarCommand(command: AvatarCommand, bubble?: string, log?: string): boolean {
+    const identity = this.requireIdentity();
+    if (!identity || this.ws?.readyState !== WebSocket.OPEN) return false;
+
+    const payload: AvatarCommandPayload = {
+      type: "avatar_command",
+      avatarId: identity.avatarId,
+      authKey: identity.authKey,
+      command,
+      ...(typeof bubble === "string" && bubble.trim() ? { bubble: bubble.trim() } : {}),
+      ...(typeof log === "string" && log.trim() ? { log: log.trim() } : {}),
+    };
+    this.ws.send(JSON.stringify(payload));
+    return true;
+  }
+
   sendHookNotify(hookType: HookNotifyType, bubble: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: HookNotifyPayload = {

package/src/types.ts

@@ -96,6 +96,17 @@ export type StatusPayload = {
   log: string;
 };
 
+export type AvatarCommand = "look_at_screen";
+
+export type AvatarCommandPayload = {
+  type: "avatar_command";
+  avatarId: string;
+  authKey: string;
+  command: AvatarCommand;
+  bubble?: string;
+  log?: string;
+};
+
 export type HookNotifyType = "message_received" | "before_send_message";
 
 export type HookNotifyPayload = {