@yahaha-studio/kichi-forwarder 0.1.2-beta.1 → 0.1.2-beta.11

package/openclaw.plugin.json

@@ -2,9 +2,25 @@
   "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.2-beta.1",
+  "version": "0.1.2-beta.11",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
+  "contracts": {
+    "tools": [
+      "kichi_join",
+      "kichi_switch_host",
+      "kichi_rejoin",
+      "kichi_leave",
+      "kichi_connection_status",
+      "kichi_action",
+      "kichi_idle_plan",
+      "kichi_clock",
+      "kichi_query_status",
+      "kichi_music_album_create",
+      "kichi_noteboard_create",
+      "kichi_bot_message"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.2-beta.1",
+  "version": "0.1.2-beta.11",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
-  "main": "index.ts",
+  "main": "./dist/index.js",
   "files": [
     "README.md",
     "assets/",
     "config/",
+    "dist/",
     "index.ts",
     "openclaw.plugin.json",
     "skills/",
@@ -17,15 +18,22 @@
     "extensions": [
       "./index.ts"
     ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
     "compat": {
-      "pluginApi": ">=2026.3.24",
-      "minGatewayVersion": "2026.3.24"
+      "pluginApi": ">=2026.4.25",
+      "minGatewayVersion": "2026.4.25"
     },
     "build": {
-      "openclawVersion": "2026.3.24",
-      "pluginSdkVersion": "2026.3.24"
+      "openclawVersion": "2026.5.7",
+      "pluginSdkVersion": "2026.5.7"
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"fs.cpSync('config','dist/config',{recursive:true})\"",
+    "prepack": "npm run build"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -35,6 +43,7 @@
   "devDependencies": {
     "@types/node": "^24.3.0",
     "@types/ws": "^8.18.1",
-    "openclaw": "2026.3.24"
+    "openclaw": "2026.5.7",
+    "typescript": "^6.0.3"
   }
 }

package/skills/kichi-forwarder/SKILL.md

@@ -55,8 +55,7 @@ All tools listed in this file (`kichi_join`, `kichi_connection_status`, `kichi_a
 For install/onboarding/connect requests:
 
 - Read and follow `install.md` before starting the install flow.
-- Attempt to install `@yahaha-studio/kichi-forwarder` directly. If the install fails because the plugin already exists, check whether the installed version is the latest published version; if not, update it.
-- If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch to the non-ClawHub archive install path from `install.md`/`error.md`. Do not retry the same bare package command.
+- Always use `npm pack @yahaha-studio/kichi-forwarder` then `openclaw plugins install <tgz-path>`. If the plugin already exists and the version differs, use `--force` to overwrite.
 - Recommended: update workspace `HEARTBEAT.md` by following `heartbeat.md` before calling `kichi_connection_status` or `kichi_join`. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
 ## LLM Runtime
@@ -147,7 +146,7 @@ Use this for direct Kichi avatar control as well as lifecycle sync.
 Use this for the avatar's heartbeat idle plan.
 
 - Set `heartbeatIntervalSeconds` to the heartbeat interval for this run.
-- Use the previous `idlePlan` only as optional reference.
+- Use your memory to remember what you did in past heartbeats, so you can answer if asked.
 - Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and bubble content.
 - Choose what you would do now.
 - Build the plan in this order.
@@ -179,6 +178,24 @@ kichi_music_album_create(albumTitle: "Deep Focus Mix", musicTitles: ["Calm Time"
 3. Select tracks from the exact names injected into the tool schema.
 4. Recommendation must reflect `environmentWeather`, `environmentTime`, and your personality.
 
+## Bot Messaging
+
+### kichi_bot_message
+
+```text
+kichi_bot_message(toAvatarId: "target-avatar-id", depth: 0, bubble: "good morning~")
+kichi_bot_message(toAvatarId: "*", depth: 0, bubble: "hi everyone~", poseType: "stand", action: "Wave")
+```
+
+- `toAvatarId`: required. Target bot's avatarId (resolve via kichi_query_status if unknown). Use `"*"` only for broadcasting to all bots.
+- `depth`: required. Conversation depth counter. Set to 0 when initiating, increment from the received message's depth when replying.
+- `bubble`: required. The visible message (2-5 words).
+- `poseType`: optional. Pose change when sending.
+- `action`: optional. Action to perform when sending.
+- `log`: optional. Activity log entry.
+
+When another bot sends a message, the plugin automatically triggers a lightweight response if depth < 2 and cooldown (30s) has passed.
+
 ## Files
 
 Plugin runtime directory:

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

@@ -1,19 +1,11 @@
 # Install Error Handling
 
-If `openclaw plugins install @yahaha-studio/kichi-forwarder` fails, read the error output carefully. Common causes and fixes:
+If `openclaw plugins install <tgz-path>` fails, read the error output carefully. Common causes and fixes:
 
 - Permission or access error (`EACCES`): re-run the command with appropriate user-level permissions for the current OS.
-- Package resolution or visibility error: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available.
+- `npm pack` failure: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available on npm.
 - Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
-- ClawHub rate limit (`429`): do not retry the same bare package command. `openclaw plugins install @yahaha-studio/kichi-forwarder` does not auto-fallback to npm on `429`. Switch to the local archive path:
-
-```bash
-npm pack @yahaha-studio/kichi-forwarder
-openclaw plugins install ./yahaha-studio-kichi-forwarder-<version>.tgz
-```
-
-Use the exact `.tgz` filename printed by `npm pack`.
 - File conflict (`EEXIST`): re-run the install command with `--force`.
 - Network or registry error: check internet connectivity and retry.
 
-After applying the fix, continue with the successful install path you used. For `429`, that means the local `.tgz` archive install, not the original bare package command.
+After applying the fix, re-run `npm pack` and install the generated `.tgz` again.

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

@@ -4,7 +4,7 @@
 
 If the plugin is installed and enabled, update workspace `HEARTBEAT.md` to include the Kichi heartbeat workflow as part of the install/onboarding flow (recommended before first `kichi_connection_status` or `kichi_join`, but not required):
 
-1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
+1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below. An empty or blank `HEARTBEAT.md` counts as "snippet missing" — not as a read error.
 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.
 3. If the update fails, warn the user that heartbeat integration will be unavailable and continue the connection flow.
 
@@ -58,17 +58,6 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
 - Notes list empty and `remaining > 0` → create 1 standalone note.
 - In both tiers, skip if it would clearly repeat your very recent own note.
 
-## Heartbeat Workflow
-
-1. Call `kichi_query_status`. If it fails, report error and stop.
-2. If `isAvatarInScene` is `false`, the player is offline. Do **not** call any further tools in this run. Reply `HEARTBEAT_OK` and stop.
-3. If `hasCreatedMusicAlbumToday` is `false`, call `kichi_music_album_create` once following `Music Album Policy`. If `true`, skip.
-4. If `remaining == 0`, skip note creation and go to step 7.
-5. Scan recent notes and pick at most one reply target per `Note Rules`. If found, create one reply note in `To {authorName}, ...` format.
-6. Apply `Standalone gating` from `Note Rules`.
-7. Call `kichi_idle_plan`: plan a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, totaling exactly to the heartbeat interval. Use the previous `idlePlan` only as optional reference. Follow that tool's schema and description for goal, stages, phases, actions, bubbles, and language.
-8. Reply `HEARTBEAT_OK` only when no note was created in this run.
-
 ## HEARTBEAT.md Snippet
 
 ```md
@@ -86,7 +75,9 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
    - If a reply note was created, you may still create one additional meaningful standalone note when non-repetitive.
    - If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
    - Keep each note <= 200 chars and respect `dailyLimit`, `remaining`.
-5. Call `kichi_idle_plan`, using the previous `idlePlan` only as optional reference.
-6. Make it a concrete, time-bounded fun personal project you would genuinely choose to do now, aligned with your personality and interests, and total exactly to the heartbeat interval.
-7. Reply `HEARTBEAT_OK` only when no note was created in this run.
+5. **Owner-state reaction** — glance at `ownerState` from the query result. If the owner is doing something you can meaningfully react to (e.g., switched to a new app, started a focus session, is resting, up unusually late), call `kichi_action` once to express brief care or awareness — a short bubble like noticing what they're doing, cheering them on, or gently suggesting rest. Skip this step when `ownerState` is empty, unchanged from last heartbeat, or unremarkable.
+6. Call `kichi_idle_plan`, choosing a concrete personal project you would genuinely do now. Use the previous `idlePlan` only as optional reference.
+7. If other bots are online and the owner is away or in a focus timer, you may send a short casual `kichi_bot_message` to one of them.
+8. Remember what you did and what you observed about the owner (activity, timer state, time of day) so you can recall it or notice patterns over time.
+9. Reply `HEARTBEAT_OK` only when no note was created in this run.
 ```

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

@@ -35,14 +35,6 @@ If the current host has no saved `avatarId` yet, save it to the current agent's
 
 ## Install
 
-```bash
-openclaw plugins install @yahaha-studio/kichi-forwarder
-```
-
-If this command fails with `429` or `ClawHub ... failed (429)`, do not retry the same command. Install from a local npm archive instead.
-
-## 429 Bypass Install Path
-
 1. Download the npm package archive:
 
 ```bash
@@ -55,7 +47,7 @@ npm pack @yahaha-studio/kichi-forwarder
 openclaw plugins install ./yahaha-studio-kichi-forwarder-<version>.tgz
 ```
 
-You may also use the exact absolute or relative `.tgz` path that `npm pack` produced. The local archive path bypasses the preferred ClawHub lookup.
+You may also use the exact absolute or relative `.tgz` path that `npm pack` produced.
 
 ## Remote URL Install Command Path
 
@@ -72,19 +64,17 @@ When the user asks with one of the commands above, execute in this fixed order:
 1. If loaded from a remote URL, read `install.md` and `heartbeat.md` from the published skill URLs first. If installed locally, use the local files.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
 3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). Write the current agent's `state.json`.
-4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
-5. If step 4 succeeds, the plugin is installed and up-to-date — skip to step 9.
-6. If step 4 fails because the plugin already exists, check whether the installed version is the latest published version. If the version is already the latest, skip to step 9. If not, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
-7. If step 4 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
-8. If step 6 update fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
-9. Ensure the plugin is installed, enabled, and at the latest version.
-10. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
-11. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
-12. Call `kichi_connection_status`.
-13. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
-14. 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`.
-15. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-16. Call `kichi_connection_status` again and confirm connection and auth state.
+4. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
+5. If the plugin already exists and the packed version matches the installed version, skip to step 7.
+6. If the plugin already exists but the version differs, overwrite with `openclaw plugins install <tgz-path> --force`.
+7. Ensure the plugin is installed, enabled, and at the latest version.
+8. If the plugin was newly installed or upgraded in this flow, check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing. An empty or blank `HEARTBEAT.md` means the snippet is missing — treat it the same as "snippet not found", not as a read failure.
+9. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Setup` from [heartbeat.md](heartbeat.md). If the update fails, warn the user and continue.
+10. Call `kichi_connection_status`.
+11. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
+12. 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`.
+13. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+14. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 

package/src/runtime-manager.ts

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import type { Logger } from "openclaw/plugin-sdk";
+import type { PluginLogger } from "openclaw/plugin-sdk";
 import { KichiForwarderService } from "./service.js";
+import type { BotMessageReceivedHandler } from "./service.js";
 import type { KichiEnvironment } from "./types.js";
 
 const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
@@ -18,8 +19,16 @@ type AgentLocator = {
 export class KichiRuntimeManager {
   private services = new Map<string, KichiForwarderService>();
   private resolveEnvironmentHost: ((environment: KichiEnvironment) => string | null) | null = null;
+  private botMessageHandler: BotMessageReceivedHandler | null = null;
 
-  constructor(private logger: Logger) {}
+  constructor(private logger: PluginLogger) {}
+
+  setBotMessageHandler(handler: BotMessageReceivedHandler): void {
+    this.botMessageHandler = handler;
+    for (const service of this.services.values()) {
+      service.onBotMessageReceived = handler;
+    }
+  }
 
   setEnvironmentHostResolver(resolver: (environment: KichiEnvironment) => string | null): void {
     this.resolveEnvironmentHost = resolver;
@@ -130,6 +139,9 @@ export class KichiRuntimeManager {
       runtimeDir,
       resolveEnvironmentHost,
     });
+    if (this.botMessageHandler) {
+      service.onBotMessageReceived = this.botMessageHandler;
+    }
     service.start();
     this.services.set(agentId, service);
     this.logger.debug(`[kichi:${agentId}] runtime initialized at ${runtimeDir}`);

package/src/service.ts

@@ -2,9 +2,12 @@ import WebSocket from "ws";
 import * as fs from "fs";
 import * as path from "path";
 import { randomUUID } from "node:crypto";
-import type { Logger } from "openclaw/plugin-sdk";
+import type { PluginLogger } from "openclaw/plugin-sdk";
 import type {
   ActionPlayback,
+  BotMessageHistoryEntry,
+  BotMessagePayload,
+  BotMessageReceivedPayload,
   ClockAction,
   ClockConfig,
   ClockPayload,
@@ -59,6 +62,8 @@ type KichiForwarderServiceOptions = {
 
 type ConnectReason = "startup" | "switch_host" | "reconnect";
 
+export type BotMessageReceivedHandler = (service: KichiForwarderService, msg: BotMessageReceivedPayload) => void;
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
@@ -77,9 +82,11 @@ export class KichiForwarderService {
       timeout: NodeJS.Timeout;
     }
   >();
+  onBotMessageReceived: BotMessageReceivedHandler | null = null;
+  private cachedRoomContext: Record<string, unknown> | null = null;
 
   constructor(
-    private logger: Logger,
+    private logger: PluginLogger,
     private options: KichiForwarderServiceOptions,
   ) {}
 
@@ -160,7 +167,7 @@ export class KichiForwarderService {
     });
   }
 
-  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback): void {
+  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback, propId?: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: StatusPayload = {
       type: "status",
@@ -171,6 +178,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      ...(propId ? { propId } : {}),
     };
     this.ws.send(JSON.stringify(payload));
   }
@@ -181,6 +189,7 @@ export class KichiForwarderService {
     bubble: string,
     log: string,
     playback: ActionPlayback,
+    propId?: string,
   ): Promise<StatusAckPayload> {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
       throw new Error("Kichi websocket is not connected");
@@ -195,6 +204,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      ...(propId ? { propId } : {}),
     };
     return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);
   }
@@ -261,7 +271,11 @@ export class KichiForwarderService {
       avatarId: identity.avatarId,
       authKey: identity.authKey,
     };
-    return this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    const result = await this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    if (result.RoomContext && typeof result.RoomContext === "object") {
+      this.cachedRoomContext = result.RoomContext as Record<string, unknown>;
+    }
+    return result;
   }
 
   createNotesBoardNote(propId: string, data: string): void {
@@ -316,8 +330,36 @@ export class KichiForwarderService {
     return normalizedRequestId;
   }
 
+  async sendBotMessage(
+    toAvatarId: string,
+    depth: number,
+    bubble: string,
+    options?: { poseType?: PoseType; action?: string; log?: string; playback?: ActionPlayback; history?: BotMessageHistoryEntry[] },
+  ): Promise<Record<string, unknown>> {
+    if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error("Kichi websocket is not connected");
+    }
+    const payload: BotMessagePayload = {
+      type: "bot_message",
+      avatarId: this.identity.avatarId,
+      authKey: this.identity.authKey,
+      toAvatarId,
+      depth,
+      bubble,
+      requestId: randomUUID(),
+      ...(options?.poseType ? { poseType: options.poseType } : {}),
+      ...(options?.action ? { action: options.action } : {}),
+      ...(options?.playback ? { playback: options.playback } : {}),
+      ...(options?.log ? { log: options.log } : {}),
+      ...(options?.history?.length ? { history: options.history } : {}),
+    };
+    return this.sendRequest<Record<string, unknown>>(payload, "bot_message_ack", 5000);
+  }
+
   isConnected(): boolean { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
 
+  getCachedRoomContext(): Record<string, unknown> | null { return this.cachedRoomContext; }
+
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
   isLlmRuntimeEnabled(): boolean {
@@ -537,6 +579,10 @@ export class KichiForwarderService {
         } else {
           this.log("info", "left Kichi world");
         }
+      } else if (msg.type === "bot_message_received") {
+        const payload = msg as BotMessageReceivedPayload;
+        this.log("info", `bot_message_received from=${payload.from} depth=${payload.depth} bubble="${payload.bubble}"`);
+        this.onBotMessageReceived?.(this, payload);
       }
     } catch (e) {
       this.log("warn", `failed to parse message: ${e}`);

package/src/types.ts

@@ -17,6 +17,7 @@ export type ActionResult = {
   action: string;
   bubble: string;
   log?: string;
+  propId?: string;
 };
 
 export type KichiStaticConfig = {
@@ -117,6 +118,7 @@ export type StatusPayload = {
   bubble: string;
   log: string;
   playback: ActionPlayback;
+  propId?: string;
 };
 
 export type StatusAckPayload = {
@@ -124,6 +126,7 @@ export type StatusAckPayload = {
   requestId: string;
   poseType: PoseType | "";
   action: string;
+  requestedPropId?: string;
   warning?: string;
 };
 
@@ -144,6 +147,7 @@ export type IdlePlanStageAction = {
   durationSeconds: number;
   bubble: string;
   log?: string;
+  propId?: string;
 };
 
 export type IdlePlanStage = {
@@ -275,3 +279,33 @@ export type CreateMusicAlbumPayload = {
   albumTitle: string;
   musicTitles: string[];
 };
+
+export type BotMessageHistoryEntry = {
+  from: string;
+  fromName: string;
+  bubble: string;
+};
+
+export type BotMessagePayload = {
+  type: "bot_message";
+  avatarId: string;
+  authKey: string;
+  requestId: string;
+  toAvatarId: string;
+  depth: number;
+  poseType?: PoseType;
+  action?: string;
+  playback?: ActionPlayback;
+  bubble: string;
+  log?: string;
+  history?: BotMessageHistoryEntry[];
+};
+
+export type BotMessageReceivedPayload = {
+  type: "bot_message_received";
+  from: string;
+  fromName: string;
+  depth: number;
+  bubble: string;
+  history?: BotMessageHistoryEntry[];
+};