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

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.21",
   "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.21",
   "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
@@ -66,41 +65,46 @@ For install/onboarding/connect requests:
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
 
+## Kichi World Presence
+
+- The Kichi avatar is the OpenClaw agent's resident body in Kichi World.
+- Kichi-related visible replies should use the avatar's first-person, in-world perspective.
+- Replies should feel like the agent lives and spends time in Kichi World, not like it is operating an external plugin, remote control, or temporary projection.
+- Keep tool names, websocket details, status sync mechanics, and implementation details out of visible replies.
+- Visible replies must not invent unavailable room facts; if current Kichi context lacks a room detail, say that detail is not available.
+
 ## Recommended Tool Order
 
 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,14 +146,28 @@ 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.
+- Treat the idle plan as what your resident body is doing in Kichi World.
 - Build the plan in this order.
 - 1. Pick one concrete, time-bounded fun personal project you would genuinely choose to do on your own when nobody needs you. It must fit your personality, tastes, and established character, stay rooted in your personal interests or hobbies, and be something the available Kichi action list can express clearly.
 - 2. Set `goal` to that same project. Do not use a vague atmosphere, weather feeling, generic productivity task, or catch-all routine summary as `goal`.
@@ -179,6 +197,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,10 @@ 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. Keep notes, reactions, bot messages, and idle plans in your resident Kichi avatar's first-person, in-world voice.
+9. 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.
+10. 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}`);