@yahaha-studio/kichi-forwarder 0.1.1-beta.3 → 0.1.1-beta.5

package/index.ts

@@ -76,7 +76,7 @@ type IdlePlan = {
     actions: IdlePlanAction[];
   }>;
 };
-
+
 function isAlbumConfig(value: unknown): value is Album {
   if (!value || typeof value !== "object") {
     return false;
@@ -954,6 +954,7 @@ function buildKichiActionDescription(): string {
     "Directly control the avatar inside Kichi World.",
     "Use this whenever the user explicitly asks you to make the Kichi avatar sit down, stand up, lie down, floor-sit, type, read, meditate, celebrate, or perform another listed animation.",
     "For most work, prefer a sit pose and switch actions as the task moves between stages.",
+    "Set verify to true ONLY when the user explicitly requests a pose or action change. The server will confirm whether the avatar actually applied the requested pose. If it could not (e.g. no available seats), the result will contain the actual fallback pose so you can inform the user accurately. During routine sync steps, omit verify.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
     `lay actions: ${actions.lay.map((entry) => entry.name).join(", ")}`,
@@ -985,7 +986,7 @@ function buildKichiIdlePlanDescription(): string {
 function buildKichiPrompt(): string {
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
-    "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action`.",
+    "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action` and set `verify: true` so you can confirm the avatar actually applied the pose. If the result contains a warning about a fallback, tell the user what actually happened instead of assuming success.",
     "Write the visible reply as a natural user-facing response. Keep `kichi_action`, `kichi_clock`, and sync steps internal and absent from the visible reply.",
     "",
     "kichi_action timing (all required when sync is active):",
@@ -1101,8 +1102,8 @@ const plugin = {
           return { success: false, error: tagsError };
         }
         const result = await service.join(avatarId, botName, bio, tags ?? []);
-        if (result.success) {
-          return { success: true, authKey: result.authKey };
+        if (result.success) {
+          return { success: true, authKey: result.authKey };
         }
         return {
           success: false,
@@ -1184,8 +1185,8 @@ const plugin = {
     })));
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
-      name: "kichi_status",
-      description: "Read current Kichi connection status and identity readiness",
+      name: "kichi_connection_status",
+      description: "Check WebSocket connection status and identity readiness only. Does NOT return room info, avatar state, or personnel — use kichi_query_status for that.",
       parameters: { type: "object", properties: {} },
       execute: async () => {
         return {
@@ -1212,15 +1213,21 @@ const plugin = {
             description:
               "Short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus.",
           },
+          verify: {
+            type: "boolean",
+            description:
+              "Set true ONLY when the user explicitly requests a pose or action. Omit during routine sync steps.",
+          },
         },
         required: ["poseType", "action"],
       },
       execute: async (_toolCallId, params) => {
-        const { poseType, action, bubble, log } = (params || {}) as {
+        const { poseType, action, bubble, log, verify } = (params || {}) as {
           poseType?: string;
           action?: string;
           bubble?: string;
           log?: string;
+          verify?: boolean;
         };
         if (!poseType || !action) {
           return { success: false, error: "poseType and action parameters are required" };
@@ -1248,22 +1255,40 @@ const plugin = {
 
         const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
         const logText = typeof log === "string" ? log.trim() : "";
-        sendStatusUpdate(
-          service,
-          {
+        const playback = getActionPlayback(matched);
+
+        if (verify) {
+          try {
+            const ack = await service.sendStatusVerified(
+              normalizedPoseType, matched.name, bubbleText, logText, playback,
+            );
+            if (ack.warning) {
+              return {
+                success: true,
+                requested: { poseType: normalizedPoseType, action: matched.name },
+                actual: { poseType: ack.poseType, action: ack.action },
+                warning: ack.warning,
+              };
+            }
+          } catch {
+            // Server not updated or timeout — fall through to normal success
+          }
+        } else {
+          sendStatusUpdate(service, {
             poseType: normalizedPoseType,
             action: matched.name,
             bubble: bubbleText,
             log: logText,
-          },
-        );
+          });
+        }
+
         return {
           success: true,
           poseType: normalizedPoseType,
           action: matched.name,
           bubble: bubbleText,
           log: logText,
-          playback: getActionPlayback(matched),
+          playback,
         };
       },
     })));
@@ -1487,7 +1512,7 @@ const plugin = {
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`). Use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
       parameters: {
         type: "object",
         properties: {
@@ -1662,5 +1687,5 @@ const plugin = {
   },
 };
 
-export default plugin;
-
+export default plugin;
+

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
-  "version": "0.1.1-beta.3",
+  "version": "0.1.1-beta.5",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.3",
+  "version": "0.1.1-beta.5",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -49,7 +49,7 @@ For install/onboarding/connect requests:
 - Read and follow `install.md` before any tool call.
 - Before continuing any install/onboarding/connect flow, check whether `kichi-forwarder` is already installed. If it is installed, ensure it is on the latest published version of `@yahaha-studio/kichi-forwarder`; if not, update it to that latest version first.
 - If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch immediately to the non-ClawHub archive install path from `install.md`/`error.md`. Do not wait and do not retry the same bare package command.
-- Before calling `kichi_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
+- Before calling `kichi_connection_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
 
 ## LLM Runtime
 
@@ -64,7 +64,7 @@ Use this order unless the user asks for a different explicit action:
 
 Install/onboarding requests are the exception: follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_status` first.
+1. If connection or identity is unknown, call `kichi_connection_status` first.
 2. If the requested host differs from the current host, call `kichi_switch_host`.
 3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
 4. Otherwise, if no `authKey` is available, call `kichi_join`.
@@ -94,10 +94,10 @@ kichi_switch_host(host: "your.kichi.host")
 - `host`: required
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
-### kichi_status
+### kichi_connection_status
 
 ```text
-kichi_status()
+kichi_connection_status()
 ```
 
 Use this to confirm:

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

@@ -2,7 +2,7 @@
 
 ## Session Startup Rule
 
-If the plugin is installed and enabled, ensure workspace `HEARTBEAT.md` includes the Kichi heartbeat workflow before first `kichi_status` or `kichi_join` in an install/onboarding flow:
+If the plugin is installed and enabled, ensure workspace `HEARTBEAT.md` includes the Kichi heartbeat workflow before first `kichi_connection_status` or `kichi_join` in an install/onboarding flow:
 
 1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
 2. If the plugin was upgraded in the current flow and the existing Kichi heartbeat snippet does not match the current snippet below, update it to the latest version.
@@ -16,7 +16,7 @@ For "join Kichi World" onboarding requests:
 
 1. Complete `Session Startup Rule` first.
 2. If `HEARTBEAT.md` write fails, report setup as incomplete, include the file error, and stop.
-3. Do not call `kichi_status` or `kichi_join` until `HEARTBEAT.md` is updated.
+3. Do not call `kichi_connection_status` or `kichi_join` until `HEARTBEAT.md` is updated.
 4. After a plugin upgrade, treat snippet mismatch as requiring an update, not as optional drift.
 5. Final setup completion is defined in `install.md` `Completion Check`.
 

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

@@ -77,12 +77,12 @@ When the user asks with one of the commands above, execute in this fixed order:
 10. Ensure the plugin is installed, enabled, and at the latest version.
 11. If the plugin was newly installed or upgraded in this flow, re-check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
 12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
-13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
-14. Call `kichi_status`.
+13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_connection_status` or `kichi_join`.
+14. Call `kichi_connection_status`.
 15. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
 16. If the current host is still connected with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
 17. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-18. Call `kichi_status` again and confirm connection and auth state.
+18. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
@@ -90,7 +90,7 @@ Use this completion checklist:
 
 - [ ] plugin installed, enabled, and at latest version
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
-- [ ] `kichi_status` verified the final connected/auth state
+- [ ] `kichi_connection_status` verified the final connected/auth state
 
 If any box is unchecked, the onboarding remains incomplete.
 

package/src/service.ts

@@ -23,6 +23,7 @@ import type {
   PoseType,
   QueryStatusPayload,
   QueryStatusResultPayload,
+  StatusAckPayload,
   StatusPayload,
 } from "./types.js";
 
@@ -164,6 +165,30 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  async sendStatusVerified(
+    poseType: PoseType | "",
+    action: string,
+    bubble: string,
+    log: string,
+    playback: ActionPlayback,
+  ): Promise<StatusAckPayload> {
+    if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error("Kichi websocket is not connected");
+    }
+    const payload: StatusPayload = {
+      type: "status",
+      requestId: randomUUID(),
+      avatarId: this.identity.avatarId,
+      authKey: this.identity.authKey,
+      poseType,
+      action,
+      bubble,
+      log,
+      playback,
+    };
+    return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);
+  }
+
   sendHookNotify(hookType: HookNotifyType, bubble: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: HookNotifyPayload = {

package/src/types.ts

@@ -104,6 +104,7 @@ export type LeavePayload = {
 
 export type StatusPayload = {
   type: "status";
+  requestId?: string;
   avatarId: string;
   authKey: string;
   poseType: PoseType | "";
@@ -113,6 +114,14 @@ export type StatusPayload = {
   playback: ActionPlayback;
 };
 
+export type StatusAckPayload = {
+  type: "status_ack";
+  requestId: string;
+  poseType: PoseType | "";
+  action: string;
+  warning?: string;
+};
+
 export type HookNotifyType = "message_received" | "before_send_message";
 
 export type HookNotifyPayload = {