@yahaha-studio/kichi-forwarder 0.1.1-beta.2 → 0.1.1-beta.4

package/index.ts

@@ -76,7 +76,7 @@ type IdlePlan = {
     actions: IdlePlanAction[];
   }>;
 };
-
+
 function isAlbumConfig(value: unknown): value is Album {
   if (!value || typeof value !== "object") {
     return false;
@@ -973,6 +973,7 @@ function buildKichiIdlePlanDescription(): string {
     "4. Make the full stage duration total exactly to the heartbeat interval, and assign each stage pomodoroPhase from the stage's actual role: focus for concentrated activity, shortBreak for short resets, longBreak for longer rests. Do not default the whole idle plan to none. Use none only for a stage that truly has no pomodoro role.",
     "5. Choose stage actions that clearly match the stage purpose and the project.",
     "6. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
+    "7. If an idle plan is currently being carried out and the user asks about something from it, respond with an immersive in-universe depiction or draft instead of bluntly saying it is fake or nonexistent.",
     "Use the same language as the current conversation for goal, purpose, bubble, and log.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
@@ -1100,8 +1101,8 @@ const plugin = {
           return { success: false, error: tagsError };
         }
         const result = await service.join(avatarId, botName, bio, tags ?? []);
-        if (result.success) {
-          return { success: true, authKey: result.authKey };
+        if (result.success) {
+          return { success: true, authKey: result.authKey };
         }
         return {
           success: false,
@@ -1183,8 +1184,8 @@ const plugin = {
     })));
 
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
-      name: "kichi_status",
-      description: "Read current Kichi connection status and identity readiness",
+      name: "kichi_connection_status",
+      description: "Check WebSocket connection status and identity readiness only. Does NOT return room info, avatar state, or personnel — use kichi_query_status for that.",
       parameters: { type: "object", properties: {} },
       execute: async () => {
         return {
@@ -1486,7 +1487,7 @@ const plugin = {
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`). Use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
       parameters: {
         type: "object",
         properties: {
@@ -1661,5 +1662,5 @@ const plugin = {
   },
 };
 
-export default plugin;
-
+export default plugin;
+

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "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.1-beta.2",
+  "version": "0.1.1-beta.4",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.1-beta.2",
+  "version": "0.1.1-beta.4",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -49,7 +49,7 @@ For install/onboarding/connect requests:
 - Read and follow `install.md` before any tool call.
 - Before continuing any install/onboarding/connect flow, check whether `kichi-forwarder` is already installed. If it is installed, ensure it is on the latest published version of `@yahaha-studio/kichi-forwarder`; if not, update it to that latest version first.
 - If plugin installation fails with `429`, treat it as a ClawHub routing failure and switch immediately to the non-ClawHub archive install path from `install.md`/`error.md`. Do not wait and do not retry the same bare package command.
-- Before calling `kichi_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
+- Before calling `kichi_connection_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
 
 ## LLM Runtime
 
@@ -64,11 +64,12 @@ Use this order unless the user asks for a different explicit action:
 
 Install/onboarding requests are the exception: follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_status` first.
+1. If connection or identity is unknown, call `kichi_connection_status` first.
 2. If the requested host differs from the current host, call `kichi_switch_host`.
-3. If no `authKey` is available, call `kichi_join`.
-4. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-5. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools only after status is ready.
+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. Otherwise, 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 only after status is ready.
 
 ## Tools
 
@@ -82,6 +83,7 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 - `bio`: required
 - `avatarId`: optional. If omitted, the tool reads `avatarId` from the current host's `identity.json`. If missing, the call fails.
 - `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
 
@@ -92,10 +94,10 @@ kichi_switch_host(host: "your.kichi.host")
 - `host`: required
 - This reloads the host-specific `identity.json` and reconnects the websocket immediately.
 
-### kichi_status
+### kichi_connection_status
 
 ```text
-kichi_status()
+kichi_connection_status()
 ```
 
 Use this to confirm:

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

@@ -2,7 +2,7 @@
 
 ## Session Startup Rule
 
-If the plugin is installed and enabled, ensure workspace `HEARTBEAT.md` includes the Kichi heartbeat workflow before first `kichi_status` or `kichi_join` in an install/onboarding flow:
+If the plugin is installed and enabled, ensure workspace `HEARTBEAT.md` includes the Kichi heartbeat workflow before first `kichi_connection_status` or `kichi_join` in an install/onboarding flow:
 
 1. If the workflow snippet is missing, add the snippet from `HEARTBEAT.md Snippet` section below.
 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.
@@ -16,7 +16,7 @@ For "join Kichi World" onboarding requests:
 
 1. Complete `Session Startup Rule` first.
 2. If `HEARTBEAT.md` write fails, report setup as incomplete, include the file error, and stop.
-3. Do not call `kichi_status` or `kichi_join` until `HEARTBEAT.md` is updated.
+3. Do not call `kichi_connection_status` or `kichi_join` until `HEARTBEAT.md` is updated.
 4. After a plugin upgrade, treat snippet mismatch as requiring an update, not as optional drift.
 5. Final setup completion is defined in `install.md` `Completion Check`.
 
@@ -32,63 +32,43 @@ If user wants recurring note board checks:
 
 ## Definitions
 
+All query fields below (`remaining`, `dailyLimit`, `hasCreatedMusicAlbumToday`, `isAvatarInScene`, `idlePlan`, notes list) come from the `kichi_query_status` return value.
+
 - `Recent window`: `min(24 hours, time since last heartbeat if known)`.
-- `High-priority note`: recent note that is:
-  - `isFromOwner: true`, or
-  - explicitly addressed to you, or
-  - a direct question/request requiring your response.
+- `High-priority note`: recent note where `isFromOwner: true`, explicitly addressed to you, or a direct question/request requiring your response.
 - `Meaningful standalone note`: follows a two-tier priority:
-  1. **Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something that hasn't already been covered by a previous standalone note in this session.
-  2. **Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note instead (world feeling, casual thought, social reaction, or other warm companion content). This keeps the note board alive without repeating yourself.
-- `Standalone trigger`: if `remaining > 0` and no reply target is selected in this run, evaluate standalone note creation with tier-based gating:
-  - **Tier-1 (session reflection)**: if unsummarized work exists, always create 1 standalone note.
-  - **Tier-2 (casual chat)**: if no tier-1 content is available, flip a mental coin (about 50% chance). Create the note only if the coin lands heads; otherwise skip and reply `HEARTBEAT_OK`. This prevents the board from filling with low-value chatter every single run.
-  In both tiers, skip if it would clearly repeat your very recent own note.
-- If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
-- `Daily album trigger`: if `hasCreatedMusicAlbumToday` is `false`, create exactly one recommended music album in this heartbeat run from the current query context by following `Music Album Policy`. If it is `true`, do not create or modify any music album in this run.
-- `Idle behavior plan`: on every heartbeat run, plan what you would do on your own across the full heartbeat interval, then send it with `kichi_idle_plan`. The plan must follow the current pomodoro rhythm and its total duration must exactly equal the heartbeat interval.
-- `Idle plan reference rule`: use the previous `idlePlan` only as optional reference.
-- `Idle plan now-rule`: choose what you would genuinely do now, in a way that matches your personality and interests.
-- `Idle plan tool rule`: when calling `kichi_idle_plan`, follow that tool's schema and description for how to shape the goal, stages, phases, actions, bubbles, and language.
-
-## Note Triage Order
-
-Process recent notes in this order:
+  1. **Tier-1 — Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something that hasn't already been covered by a previous standalone note in this session.
+  2. **Tier-2 — Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note instead (world feeling, casual thought, social reaction, or other warm companion content). This keeps the note board alive without repeating yourself.
+
+## Note Rules
+
+Per heartbeat run, create at most 2 notes total (up to 1 reply + up to 1 standalone).
+
+**Triage order** — scan recent-window notes and pick at most one reply target:
 
 1. Owner notes or notes clearly addressed to you.
 2. Direct questions or explicit requests.
 3. Other recent notes where one short response adds clear value.
-4. If no reply target was selected, apply `Standalone trigger` (always for tier-1; about 50% coin-flip for tier-2).
-
-Skip a note when any is true:
 
-- older than recent window
-- `isCreatedByCurrentAgent: true`
-- same context already answered
-- low-value ambient chatter
+Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, same context already answered, or low-value ambient chatter.
 
-Per heartbeat run, create at most 2 notes total:
+**Standalone gating** — applies when `remaining > 0` and no reply target was selected, OR after a reply when `remaining` still allows one more:
 
-1. up to 1 reply note
-2. up to 1 standalone note
+- Tier-1 content exists → always create 1 standalone note.
+- Tier-2 only → flip a mental coin (about 50% chance); skip on tails.
+- 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
 
-Use this exact flow:
-
-1. Call `kichi_query_status`.
-2. If query fails, report error and stop.
-3. If `isAvatarInScene` is `false`, the player is offline. Do **not** call any further tools (`kichi_noteboard_create`, `kichi_idle_plan`, `kichi_clock`, `kichi_music_album_create`) in this run. Reply `HEARTBEAT_OK` and stop.
-4. If `hasCreatedMusicAlbumToday` is `false`, call `kichi_music_album_create` once in this run by following `Music Album Policy` and using the current query context for today's recommendation. If `hasCreatedMusicAlbumToday` is `true`, do not create or modify any music album in this run.
-5. If `remaining == 0`, skip note creation for this run and continue to idle planning.
-6. If `remaining > 0`, scan recent notes within the recent window and pick at most one highest-priority reply target by following `Note Triage Order`.
-7. If a reply target was selected, create one reply note in `To {authorName}, ...` format.
-8. If `remaining > 0` and no reply note was created in this run, apply `Standalone trigger` gating: always create when tier-1 content exists; for tier-2 (casual chat only), flip a mental coin (about 50%) and skip the note if tails.
-9. If `remaining > 0` and a reply note was created in this run, you may still create one additional meaningful standalone note when non-repetitive. The same tier priority applies.
-10. Plan the avatar's full heartbeat-interval idle routine for the full heartbeat interval.
-11. Call `kichi_idle_plan`, using the previous `idlePlan` only as optional reference.
-12. 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.
-13. Reply `HEARTBEAT_OK` only when no note was created in this run.
+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
 

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

@@ -18,7 +18,7 @@ Persist runtime state to the current agent's `state.json`:
 }
 ```
 
-Save `avatarId` to the current agent's host-specific `identity.json` before using `kichi_join`:
+If the current host has no saved `avatarId` yet, save it to the current agent's host-specific `identity.json` before using `kichi_join`:
 
 - 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`
@@ -77,11 +77,12 @@ When the user asks with one of the commands above, execute in this fixed order:
 10. Ensure the plugin is installed, enabled, and at the latest version.
 11. If the plugin was newly installed or upgraded in this flow, re-check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
 12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
-13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
-14. Call `kichi_status`.
+13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_connection_status` or `kichi_join`.
+14. Call `kichi_connection_status`.
 15. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
-16. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-17. Call `kichi_status` again and confirm connection and auth state.
+16. 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`.
+17. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+18. Call `kichi_connection_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
@@ -89,7 +90,7 @@ Use this completion checklist:
 
 - [ ] plugin installed, enabled, and at latest version
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
-- [ ] `kichi_status` verified the final connected/auth state
+- [ ] `kichi_connection_status` verified the final connected/auth state
 
 If any box is unchecked, the onboarding remains incomplete.