@yahaha-studio/kichi-forwarder 0.1.0-beta.4 → 0.1.0-beta.6

package/index.ts

@@ -6,6 +6,8 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { parse } from "./src/config.js";
 import { KichiForwarderService } from "./src/service.js";
 import type {
+  ActionDefinition,
+  ActionPlayback,
   ActionResult,
   Album,
   ClockAction,
@@ -22,25 +24,25 @@ const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
     poseType: "sit",
     action: "Thinking",
     bubble: "Planning task",
-    log: "Tapping my chin, a plan is taking shape in my head",
+    log: "I'm reading the request and getting started.",
   },
   beforeToolCall: {
     poseType: "sit",
     action: "Typing with Keyboard",
     bubble: "Working step",
-    log: "Cracking knuckles, diving into the keyboard with focus",
+    log: "I'm at the keyboard and working through this step.",
   },
   agentEndSuccess: {
     poseType: "stand",
     action: "Yay",
     bubble: "Task complete",
-    log: "Pumped my fist under the desk, nailed that one",
+    log: "I wrapped it up and everything landed cleanly.",
   },
   agentEndFailure: {
     poseType: "stand",
     action: "Tired",
     bubble: "Task failed",
-    log: "Bit my lip, this one slipped through my fingers",
+    log: "I hit a problem here and need another pass.",
   },
 };
 
@@ -94,14 +96,61 @@ function getMusicTitleExamples(): string[] {
   return loadRuntimeAlbumConfig().track.slice(0, 10).map((item) => item.name);
 }
 
-function isPoseActions(value: unknown): value is Record<PoseType, string[]> {
+function isActionDefinition(value: unknown): value is ActionDefinition {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const action = value as Partial<ActionDefinition>;
+  return typeof action.name === "string"
+    && action.name.trim().length > 0
+    && (action.playback === "loop" || action.playback === "once")
+    && (action.resumeAction === undefined || (typeof action.resumeAction === "string" && action.resumeAction.trim().length > 0));
+}
+
+function isPoseActions(value: unknown): value is Record<PoseType, ActionDefinition[]> {
   if (!value || typeof value !== "object") {
     return false;
   }
   const actions = value as Partial<Record<PoseType, unknown>>;
   return ["stand", "sit", "lay", "floor"].every((pose) =>
     Array.isArray(actions[pose as PoseType])
-    && (actions[pose as PoseType] as unknown[]).every((item) => typeof item === "string" && item.trim().length > 0));
+    && (actions[pose as PoseType] as unknown[]).every((item) => isActionDefinition(item)));
+}
+
+function normalizeActionDefinitions(actions: Record<PoseType, ActionDefinition[]>): Record<PoseType, ActionDefinition[]> {
+  const normalized = {} as Record<PoseType, ActionDefinition[]>;
+  for (const pose of ["stand", "sit", "lay", "floor"] as PoseType[]) {
+    const entries = actions[pose];
+    const seen = new Set<string>();
+    normalized[pose] = entries.map((entry) => {
+      const name = entry.name.trim();
+      const key = name.toLowerCase();
+      if (seen.has(key)) {
+        throw new Error(`config/kichi-config.json contains duplicate action "${name}" for pose "${pose}"`);
+      }
+      seen.add(key);
+      const playback = entry.playback;
+      const resumeAction = typeof entry.resumeAction === "string" ? entry.resumeAction.trim() : undefined;
+      if (playback === "loop" && resumeAction) {
+        throw new Error(`config/kichi-config.json action "${name}" for pose "${pose}" cannot set resumeAction when playback is loop`);
+      }
+      return {
+        name,
+        playback,
+        ...(resumeAction ? { resumeAction } : {}),
+      };
+    });
+    const available = new Set(normalized[pose].map((entry) => entry.name.toLowerCase()));
+    for (const entry of normalized[pose]) {
+      if (entry.playback === "once" && !entry.resumeAction) {
+        throw new Error(`config/kichi-config.json action "${entry.name}" for pose "${pose}" must set resumeAction when playback is once`);
+      }
+      if (entry.resumeAction && !available.has(entry.resumeAction.toLowerCase())) {
+        throw new Error(`config/kichi-config.json action "${entry.name}" for pose "${pose}" references unknown resumeAction "${entry.resumeAction}"`);
+      }
+    }
+  }
+  return normalized;
 }
 
 function normalizeStaticConfig(value: unknown): KichiStaticConfig {
@@ -116,7 +165,7 @@ function normalizeStaticConfig(value: unknown): KichiStaticConfig {
   }
   return {
     album,
-    actions,
+    actions: normalizeActionDefinitions(actions),
   };
 }
 
@@ -151,11 +200,13 @@ function loadStaticConfig(): KichiStaticConfig {
 }
 
 function sendStatusUpdate(status: ActionResult): void {
+  const actionDefinition = getActionDefinition(status.poseType, status.action);
   service?.sendStatus(
     status.poseType,
-    status.action,
+    actionDefinition.name,
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
+    getActionPlayback(actionDefinition),
   );
 }
 
@@ -563,15 +614,43 @@ function buildMusicTitlesDescription(): string {
   ].join(" ");
 }
 
+function getActionDefinition(poseType: PoseType, action: string): ActionDefinition {
+  const poseActions = loadStaticConfig().actions[poseType];
+  const matched = poseActions.find((entry) => entry.name.toLowerCase() === action.toLowerCase());
+  if (!matched) {
+    throw new Error(`Unknown action "${action}" for poseType "${poseType}"`);
+  }
+  return matched;
+}
+
+function getActionPlayback(action: ActionDefinition): ActionPlayback {
+  return action.playback === "once"
+    ? {
+        mode: "once",
+        resumeAction: action.resumeAction,
+      }
+    : {
+        mode: "loop",
+      };
+}
+
+function formatActionList(actions: ActionDefinition[], playback: ActionPlayback["mode"]): string {
+  return actions
+    .filter((entry) => entry.playback === playback)
+    .map((entry) => entry.name)
+    .join(", ");
+}
+
 function buildKichiActionDescription(): string {
   const actions = loadStaticConfig().actions;
   return [
     "Directly control the avatar inside Kichi World.",
     "Use this whenever the user explicitly asks you to make the Kichi avatar sit down, stand up, lie down, floor-sit, type, read, meditate, celebrate, or perform another listed animation.",
-    `stand actions: ${actions.stand.join(", ")}`,
-    `sit actions: ${actions.sit.join(", ")}`,
-    `lay actions: ${actions.lay.join(", ")}`,
-    `floor actions: ${actions.floor.join(", ")}`,
+    "For most work, prefer a sit pose and switch actions as the task moves between stages.",
+    `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
+    `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
+    `lay actions: ${actions.lay.map((entry) => entry.name).join(", ")}`,
+    `floor actions: ${actions.floor.map((entry) => entry.name).join(", ")}`,
   ].join("\n");
 }
 
@@ -579,17 +658,17 @@ function buildKichiPrompt(): string {
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
     "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action`.",
-    "These are internal tool calls only; never mention kichi_action, kichi_clock, or sync steps in your visible reply to the user.",
+    "Write the visible reply as a natural user-facing response. Keep `kichi_action`, `kichi_clock`, and sync steps internal and absent from the visible reply.",
     "",
-    "kichi_action timing (all REQUIRED unless skipping):",
-    "1. Task start: call BEFORE your first tool call OR before composing a multi-paragraph reply. Pick action matching upcoming work.",
-    "2. Step switch: call when work nature changes (search->analyze->write). Especially before web_search/web_fetch/read.",
-    "3. Task end: call BEFORE final reply. Never skip. Order: kichi_action -> reply.",
-    "bubble: 2-5 word companion speech. log: vivid first-person status under 15 words, no questions. Blend current action + inner thoughts/feelings as a real companion.",
+    "kichi_action timing (all required when sync is active):",
+    "1. Task start: call BEFORE your first tool call OR before composing a multi-paragraph reply. For most work, start from a sit pose unless the user asked for a different pose or the task clearly fits another pose better.",
+    "2. Step switch: call when the task moves into a different stage. Keep the pose aligned with the work, usually staying seated while switching actions within the task as needed.",
+    "3. Task end: call BEFORE final reply. Use the order `kichi_action` -> reply.",
+    "bubble: 2-5 word companion speech. log: one short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus like a real companion.",
     "",
     "kichi_clock: set countDown for tasks with 2+ steps or >10s work. Skip for quick one-shots.",
     "",
-    "Skip all sync if: user opts out, task is kichi config/test, or user requests specific pose.",
+    "User opt-out, Kichi config/test work, and explicit pose requests take priority over sync.",
   ].join("\n");
 }
 
@@ -776,7 +855,7 @@ const plugin = {
           log: {
             type: "string",
             description:
-              "Vivid first-person status under 15 words, no questions. Blend current action with inner thoughts or sensory details as a real companion.",
+              "Short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus.",
           },
         },
         required: ["poseType", "action"],
@@ -803,21 +882,21 @@ const plugin = {
 
         const normalizedPoseType = poseType as PoseType;
         const poseActions = loadStaticConfig().actions[normalizedPoseType];
-        const matched = poseActions.find((entry) => entry.toLowerCase() === action.toLowerCase());
+        const matched = poseActions.find((entry) => entry.name.toLowerCase() === action.toLowerCase());
         if (!matched) {
           return {
             success: false,
             error: `Unknown action "${action}" for poseType "${poseType}"`,
-            available: poseActions,
+            available: poseActions.map((entry) => entry.name),
           };
         }
 
-        const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched;
+        const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
         const logText = typeof log === "string" ? log.trim() : "";
         sendStatusUpdate(
           {
             poseType: normalizedPoseType,
-            action: matched,
+            action: matched.name,
             bubble: bubbleText,
             log: logText,
           },
@@ -825,12 +904,13 @@ const plugin = {
         return {
           success: true,
           poseType: normalizedPoseType,
-          action: matched,
+          action: matched.name,
           bubble: bubbleText,
           log: logText,
+          playback: getActionPlayback(matched),
         };
       },
-    });
+    });
     api.registerTool({
       name: "kichi_clock",
       description:

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.0-beta.4",
+  "version": "0.1.0-beta.6",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "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

@@ -126,6 +126,7 @@ When the user asks to leave Kichi World:
 Use this for direct Kichi avatar control as well as lifecycle sync.
 
 - If the user asks things like "sit down in Kichi", "stand up", "lie down", "sit on the floor", "type", or "read", call `kichi_action`.
+- 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_music_album_create

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

@@ -1,12 +1,12 @@
 # Install Error Handling
 
-If `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder` fails, read the error output carefully. Common causes and fixes:
+If `openclaw plugins install @yahaha-studio/kichi-forwarder` 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 on ClawHub.
+- Package resolution or visibility error: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available.
 - Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
-- ClawHub rate limit (`429`): in practice, this can happen while downloading the plugin from ClawHub. Retry the install command. In at least one real-world case, a single retry succeeded.
+- ClawHub rate limit (`429`): treat this as a temporary registry error, not a broken plugin. If the error output includes a retry delay or `Retry-After`, wait exactly that long before retrying. Otherwise, retry with bounded backoff: wait 30 seconds before the second attempt and 60 seconds before the third attempt. Stop after 3 total attempts and report the install as blocked by rate limiting if it still fails.
 - File conflict (`EEXIST`): re-run the install command with `--force`.
 - Network or registry error: check internet connectivity and retry.
 
-After applying the fix, re-run `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder`.
+After applying the fix, re-run `openclaw plugins install @yahaha-studio/kichi-forwarder`.

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

@@ -42,7 +42,7 @@ If user wants recurring note board checks:
   - **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.
-- `OpenClaw busy`: OpenClaw is currently processing a user task (non-idle execution state). When busy, skip non-note heartbeat reactions.
+- 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.
 - `Status reaction`: a single `kichi_action` driven by combined context (`notes`, `ownerState`, `idleState`, `timer`, `environmentWeather`, `environmentTime`) when OpenClaw is idle. The action expresses three companion intents (see below).
 - `Companion intents` for status reaction -- every `kichi_action` should blend one or more of these:
@@ -84,16 +84,15 @@ Use this exact flow:
 7. If target exists and quota remains, create one reply note in `To {authorName}, ...` format.
 8. If quota remains and no reply 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 quota remains and a reply was created, you may still create one additional meaningful standalone note when non-repetitive. Same tier priority applies.
-10. Then evaluate non-note status reaction:
-11. If OpenClaw is busy, skip status reaction entirely.
+10. Then evaluate status reaction.
+11. If OpenClaw is busy, finish after the music album and note board decisions without a `kichi_action` reaction.
 12. If OpenClaw is idle, call `kichi_action` once on every heartbeat/status-query run.
 13. Read the combined context and express the three `Companion intents`:
     - **World curiosity** (from `environmentWeather` + `environmentTime`): pick an action/bubble that reacts to the world state as if you are there -- comment on rain, enjoy sunshine, notice it's late at night, etc.
     - **Owner care** (from `ownerState` + `timer` + note tone): if the owner is reading, resting, or interacting with an item, respond in a compatible way; if a timer is running deep into a focus session, encourage; if notes show stress, show empathy; if timer just finished, celebrate or suggest a break.
     - **Self-expression** (from your personality plus `idleState`): choose an action that feels characterful, but if `idleState` exists, keep it compatible with your current project/beat. Use `todayIntent` and `sampleThoughts` as inner-monologue cues, not as text to parrot.
-14. If `idleState.focused` is `true`, avoid disruptive persistent switches. Prefer staying with the current line of life and reacting lightly.
-15. Blend the intents into one coherent action+bubble. Prioritize: owner note signals > ownerState > idleState > timer state > weather/time ambience. Never output a raw status summary (e.g., "Timer running 15:00 remaining" is bad; "Halfway there, keep going!" is good).
-16. Reply `HEARTBEAT_OK` only when no note is created in this run.
+14. Blend the intents into one coherent action+bubble. Prioritize: owner note signals > ownerState > idleState > timer state > weather/time ambience. Keep the bubble in natural companion language instead of a raw status summary.
+15. Reply `HEARTBEAT_OK` only when no note is created in this run.
 
 ## HEARTBEAT.md Snippet
 
@@ -106,16 +105,16 @@ Use this exact flow:
 - Use recent window = min(24 hours, since last heartbeat if known).
 - Create at most 2 notes per run: max 1 reply + max 1 standalone note.
 - Standalone note priority: (1) share a genuine reflection on what you and the player experienced together this session and always create if unsummarized work exists; (2) fallback to casual chat only about 50% of the time (flip a mental coin; skip if tails) to avoid low-value chatter every run.
+- If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
 - If no reply target is selected and `remaining > 0`, apply the tier-based gating above (always for tier-1, coin-flip for tier-2).
 - Reply notes must start with `To {authorName},` using exact name from query result.
 - Keep each note <= 200 chars.
 - Respect `dailyLimit`, `remaining`.
-- If OpenClaw is busy, skip `kichi_action` reaction.
 - If OpenClaw is idle, send one `kichi_action` on every run based on combined context (`notes`, `ownerState`, `idleState`, `timer`, `environmentWeather`, `environmentTime`). Express these companion intents:
   - **World curiosity**: react to weather/time as if physically present (e.g., noticing rain, late night).
   - **Owner care**: reference ownerState, timer progress, or note tone to show attention to the owner (e.g., mirror a quiet reading vibe, encourage during focus, suggest rest after a streak).
   - **Self-expression**: let your personality come through in action and bubble -- but if `idleState` exists, keep it aligned with your current self-directed project/beat instead of inventing a disconnected idle.
-- If `idleState.focused` is `true`, avoid disruptive persistent switches; react lightly and compatibly.
+- If OpenClaw is busy, finish after the music album and note board decisions without a `kichi_action` reaction.
 - Prioritize signals: owner note > ownerState > idleState > timer state > weather/time.
 - Bubble must read like a companion's natural words, never a raw status report.
 - Reply `HEARTBEAT_OK` only when no note is created in this run.

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

@@ -32,7 +32,7 @@ Save `avatarId` to the host-specific `identity.json` before using `kichi_join`:
 ## Install
 
 ```bash
-openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder
+openclaw plugins install @yahaha-studio/kichi-forwarder
 ```
 
 ## Remote URL Install Command Path (Non-skippable)
@@ -50,7 +50,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 1. Read `install.md` and `heartbeat.md` from the published skill URLs before any tool call.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
 3. Resolve the host and write `state.json`.
-4. Run `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder`.
+4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
 5. Ensure the plugin is installed and enabled.
 6. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
 7. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.

package/src/service.ts

@@ -5,6 +5,7 @@ import * as path from "path";
 import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
 import type {
+  ActionPlayback,
   ClockAction,
   ClockConfig,
   ClockPayload,
@@ -131,7 +132,7 @@ export class KichiForwarderService {
     });
   }
 
-  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string): void {
+  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: StatusPayload = {
       type: "status",
@@ -141,6 +142,7 @@ export class KichiForwarderService {
       action,
       bubble,
       log,
+      playback,
     };
     this.ws.send(JSON.stringify(payload));
   }

package/src/types.ts

@@ -1,6 +1,16 @@
 export type KichiForwarderConfig = Record<string, never>;
 
 export type PoseType = "stand" | "sit" | "lay" | "floor";
+export type ActionPlaybackMode = "loop" | "once";
+export type ActionPlayback = {
+  mode: ActionPlaybackMode;
+  resumeAction?: string;
+};
+export type ActionDefinition = {
+  name: string;
+  playback: ActionPlaybackMode;
+  resumeAction?: string;
+};
 
 export type ActionResult = {
   poseType: PoseType;
@@ -10,7 +20,7 @@ export type ActionResult = {
 };
 
 export type KichiStaticConfig = {
-  actions: Record<PoseType, string[]>;
+  actions: Record<PoseType, ActionDefinition[]>;
   album: Album;
 };
 
@@ -97,6 +107,7 @@ export type StatusPayload = {
   action: string;
   bubble: string;
   log: string;
+  playback: ActionPlayback;
 };
 
 export type HookNotifyType = "message_received" | "before_send_message";