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

package/openclaw.plugin.json

@@ -2,9 +2,26 @@
   "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.2",
+  "version": "0.1.2-beta.20",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
+  "contracts": {
+    "tools": [
+      "kichi_join",
+      "kichi_switch_host",
+      "kichi_rejoin",
+      "kichi_leave",
+      "kichi_connection_status",
+      "kichi_action",
+      "kichi_glance",
+      "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.2",
+  "version": "0.1.2-beta.20",
   "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

@@ -23,7 +23,7 @@ Install and connect requests use `on <environment>` syntax. Supported environmen
 
 - `steam`: connects to `focus-wss.yahaha.com`
 - `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
-- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then call `kichi_switch_host`
+- `test`: no fixed host — use the test host from the user request when provided; otherwise ask the user for the test host before calling `kichi_join`
 
 ## Runtime State
 
@@ -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
@@ -70,37 +69,34 @@ For install/onboarding/connect requests:
 
 Use this order unless the user asks for a different explicit action. For install/onboarding requests, follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_connection_status` first.
-2. If the requested environment differs from the current environment, call `kichi_switch_host` with the target environment.
-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. If no `authKey` is available, call `kichi_join`.
-5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools after status is ready.
+1. For join/connect requests with an `avatarId` and environment, call `kichi_join` with `environment`. For `test`, include `host` if the user provided it; if not, ask for the host first.
 
 ## Tools
 
 ### kichi_join
 
 ```text
-kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
+kichi_join(environment: "steam-playtest", avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
+kichi_join(environment: "test", host: "192.168.1.100", avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<from SOUL.md>", tags: ["calm", "focused", "curious"])
 ```
 
+- `environment`: required. One of `steam`, `steam-playtest`, `test`. `kichi_join` switches to the target environment before joining.
+- `host`: required for `test` environment, ignored otherwise. If the user did not provide the test host, ask for it before calling `kichi_join`.
+- `avatarId`: required
 - `botName`: required
-- `bio`: required
-- `avatarId`: optional. If omitted, the tool reads `avatarId` from the current host's `identity.json`. If missing, the call fails.
+- `bio`: required. Extract from `SOUL.md`, covering persona and idle plan goals if present.
 - `tags`: optional string list. Empty strings are ignored and duplicates are removed. If omitted, the join payload sends `[]`.
-- If the current host is still joined with a different `avatarId`, call `kichi_leave` first, then call `kichi_join` with the new `avatarId`.
 
 ### kichi_switch_host
 
 ```text
 kichi_switch_host(environment: "steam")
-kichi_switch_host(environment: "test")
+kichi_switch_host(environment: "test", host: "192.168.1.100")
 ```
 
 - `environment`: required. One of `steam`, `steam-playtest`, `test`.
-- Host is resolved from `config/environments.json`. If the environment has no configured host (null), the call fails.
-- For `test` environment: ask the user for the test node host, write it to the plugin's `config/environments.json`, then call this tool.
+- `host`: required for `test` environment, ignored otherwise.
+- For `steam` and `steam-playtest`, the host is resolved automatically from the bundled config.
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
 ### kichi_connection_status
@@ -142,12 +138,25 @@ Use this for direct Kichi avatar control as well as lifecycle sync.
 - For most work, prefer a sit pose and switch actions inside the same task as the work moves between stages.
 - The current action lists are injected into prompt context before the model chooses `kichi_action`.
 
+### kichi_glance
+
+```text
+kichi_glance(target: "camera", duration: 1.8)
+```
+
+Use this only when the player directly asks from chat for attention such as "look at me" or "look at the camera".
+
+- `target`: optional. Only `camera` is supported.
+- `duration`: optional seconds, defaults to `1.8`.
+- `requestId`: optional tracing ID; the websocket ack returns it.
+- Do not use this for heartbeat, idle plans, bot messages, lifecycle hooks, or routine work/status sync.
+
 ### kichi_idle_plan
 
 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 +188,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,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

@@ -6,7 +6,7 @@ Install and connect requests use `on <environment>` syntax. Supported environmen
 
 - `steam`: connects to `focus-wss.yahaha.com`
 - `steam-playtest`: connects to `focus-steam-playtest-wss-int.yahaha.com`
-- `test`: no fixed host — ask the user for the current test node host, write it to the plugin's `config/environments.json`, then connect
+- `test`: no fixed host — use the test host from the user request when provided; otherwise ask the user for the test host before calling `kichi_join`
 
 ## Runtime Files
 
@@ -18,31 +18,13 @@ Persist runtime state to the current agent's `state.json`:
 ```json
 {
   "currentEnvironment": "steam",
-  "llmRuntimeEnabled": true
-}
-```
-
-If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` (this helps `kichi_join` resolve the avatar automatically when `avatarId` is omitted):
-
-- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\hosts\<encoded-host>\identity.json`
-
-```json
-{
-  "avatarId": "your-avatar-id"
+  "llmRuntimeEnabled": true,
+  "testHost": "192.168.1.100"
 }
 ```
 
 ## 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 +37,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
 
@@ -71,28 +53,24 @@ 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.
+3. Parse environment from the `on <environment>` part of the command (e.g. `on steam-playtest`). For `test`, parse the host from the request or ask the user for it before continuing.
+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. Run `openclaw --version`. If the version is **5.7 or later**, ensure `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess` set to `true`. If missing, add it. On older versions, skip this step.
+9. 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.
+10. 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.
+11. Call `kichi_join` with parsed `environment`, `host` for test, `avatarId`, `botName`, `bio`, and `tags`.
 
 ## Required Post-install Integration
 
 Use this completion checklist:
 
 - [ ] plugin installed, enabled, and at latest version
+- [ ] `openclaw.json` has `plugins.entries.kichi-forwarder.hooks.allowConversationAccess: true` (OpenClaw >= 5.7 only)
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
-- [ ] `kichi_connection_status` verified the final connected/auth state
+- [ ] `kichi_join` completed successfully
 
 If any box is unchecked, the onboarding remains incomplete.
 

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}`);