@yahaha-studio/kichi-forwarder 0.1.2-beta.2 → 0.1.2-beta.5

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.2-beta.2",
+  "version": "0.1.2-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",
+  "main": "./dist/index.js",
   "files": [
     "README.md",
     "assets/",
     "config/",
+    "dist/",
     "index.ts",
     "openclaw.plugin.json",
     "skills/",
@@ -17,6 +18,9 @@
     "extensions": [
       "./index.ts"
     ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
     "compat": {
       "pluginApi": ">=2026.3.24",
       "minGatewayVersion": "2026.3.24"
@@ -26,6 +30,10 @@
       "pluginSdkVersion": "2026.3.24"
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "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.3.24",
+    "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

@@ -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,8 @@ 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. Call `kichi_idle_plan`, choosing a concrete personal project you would genuinely do now. Use the previous `idlePlan` only as optional reference.
+6. 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.
+7. 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.
+8. 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. An empty or blank `HEARTBEAT.md` means the snippet is missing — treat it the same as "snippet not found", not as a read failure.
-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,10 @@ export class KichiForwarderService {
       timeout: NodeJS.Timeout;
     }
   >();
+  onBotMessageReceived: BotMessageReceivedHandler | null = null;
 
   constructor(
-    private logger: Logger,
+    private logger: PluginLogger,
     private options: KichiForwarderServiceOptions,
   ) {}
 
@@ -316,6 +322,32 @@ 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; }
 
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
@@ -537,6 +569,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

@@ -275,3 +275,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[];
+};