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

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
@@ -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.
 

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